226 lines
7.8 KiB
Markdown
226 lines
7.8 KiB
Markdown
# Ravenous Tools - Spec-Schema
|
||
|
||
Each line defines a single requirement in a machine-readable format.
|
||
The token `r[category.subcategory.item]` identifies the requirement; the following paragraph gives a human-friendly description.
|
||
|
||
m Bulk Operations
|
||
r[bulk.export]
|
||
The `export` command must be able to generate classes, parts or objects as requested
|
||
|
||
## Dashboard
|
||
|
||
r[dashboard.metrics.display]
|
||
Dashboard must display aggregated statistics (total classes, average/SD for QOL, Damage, CC, Survivability, Mobility, Alterations, Support) in a terminal table.
|
||
|
||
r[dashboard.configuration]
|
||
Dashboard must be able to read a user configuration with generic thresholds for validation.
|
||
|
||
r[dashboard.warnings]
|
||
Dashboard must issue warnings for classes whose metrics exceed thresholds defined in the config (e.g., damage > 0.8).
|
||
|
||
r[dashboard.ascii-charts]
|
||
Dashboard must be able to render ASCII charts (e.g., bar chart of average damage) using a terminal rendering crate.
|
||
|
||
|
||
## TeX Export
|
||
|
||
r[tex.export]
|
||
The `tex` command must generate a LaTeX file for one or more classes, escaping special characters and including optional headers.
|
||
|
||
r[tex.template]
|
||
The `--template` flag must allow users to provide a custom LaTeX template that overrides the default.
|
||
|
||
r[tex.headers]
|
||
The `--no-headers` flag must omit LaTeX header/footer when appending to an existing document.
|
||
|
||
r[tex.output-format]
|
||
The `--out tex` option must write the output to the file system, respecting the target path and filename conventions.
|
||
|
||
## File Export
|
||
r[file.export.radar]
|
||
The tool must be able to display small inline graphs (radar) rendered to PNG/SVG for latex inclusion.
|
||
|
||
r[file.export]
|
||
All elements (classes, items) must be compairable and exportable as graph
|
||
|
||
r[file.export.html]
|
||
The tool must be able to export html graphs to compair elements
|
||
|
||
## Search / Filter
|
||
|
||
r[search.by-name]
|
||
The `search --name` flag must return class names matching a full or partial string.
|
||
|
||
r[search.by-tag]
|
||
The `search --tag` flag must filter classes containing a specified tag.
|
||
|
||
r[search.by-range]
|
||
The `search` command must support numeric range filters (e.g., `--max-damage 60`) and return classes, objects or parts within the bounds.
|
||
|
||
## Graph Generation
|
||
|
||
r[graph.damage-senarios]
|
||
The `graph` command must produce be able to produce several damage scenarios as graphs.
|
||
|
||
r[graph.comparison]
|
||
The `graph comparison` command must produce a chart comparing a user-supplied list of classes.
|
||
|
||
r[graph.embeddable]
|
||
Generated graph files must be referenceable from the TeX export via `\includegraphics`.
|
||
|
||
## Validation
|
||
|
||
r[validation.schema]
|
||
All JSON files used must be be validated befor being used.
|
||
|
||
r[validation.error-report]
|
||
Validation errors must identify the exact property and reason, formatted for readability.
|
||
|
||
r[validation.value-ranges]
|
||
The schema must enforce required fields, type constraints, and acceptable numeric ranges for each stat.
|
||
|
||
## Help & Auto-Completion
|
||
|
||
r[help.full]
|
||
`--help` for every sub-command must list all options, flags, and usage examples.
|
||
|
||
## Logging
|
||
|
||
r[logging.verbosity]
|
||
The CLI must accept `--verbose` and `--quiet` flags to control log level.
|
||
|
||
r[logging.levels]
|
||
Supported levels are `error`, `warn`, `info`, `debug`, and `trace`, matching the configuration defaults.
|
||
|
||
## Data Requirements
|
||
|
||
r[data.repo-path]
|
||
The repository root must be configurable via `config/ravenous_tools_data.toml` under `repo_path`.
|
||
|
||
r[data.file-format]
|
||
Each class must be stored as a single JSON file in `data/classes/`.
|
||
|
||
r[data.config]
|
||
Global settings are stored in `config/ravenous_tools_data.toml` with fields for thresholds, templates, etc.
|
||
|
||
## Non-Functional Requirements
|
||
|
||
r[nonfunctional.extensibility]
|
||
A plugin system exposing the `ravenous_tools_plugin` trait must allow third-party crates to add metrics or output formats.
|
||
|
||
r[nonfunctional.testing]
|
||
Unit and integration tests must cover ≥90 % of code paths, verified via CI.
|
||
|
||
r[nonfunctional.ci]
|
||
GitHub Actions workflow must run tests, linting, and build on each push/PR.
|
||
|
||
r[nonfunctional.documentation]
|
||
All public APIs must be documented, and a comprehensive README with examples must be provided.
|
||
|
||
r[nonfunctional.logging-structured]
|
||
All logs must be emitted in structured JSON-lines format for easy parsing.
|
||
|
||
## User-Story Requirements
|
||
|
||
r[userstory.balancer]
|
||
Balancers must view the aggregated damage-per-HP ratio across all classes in the dashboard.
|
||
|
||
r[userstory.writer]
|
||
Writers must export classes to LaTeX and embed graphs with minimal manual editing.
|
||
|
||
r[userstory.developer]
|
||
Developers must implement custom metric calculators via the plugin interface.
|
||
|
||
r[userstory.analyst]
|
||
Analysts must generate PNG graphs of damage curves directly from the terminal.
|
||
|
||
## Acceptance Criteria
|
||
|
||
r[acceptance.tex]
|
||
Generated `.tex` must compile without errors; templates and header flags must function.
|
||
|
||
r[acceptance.dashboard]
|
||
Dashboard must display at least five distinct metrics and render ASCII charts legibly.
|
||
|
||
r[acceptance.validation]
|
||
Invalid JSON files must be rejected with pinpointed error messages.
|
||
|
||
r[acceptance.help]
|
||
`--help` output must enumerate all sub-commands and examples; completion scripts install cleanly.
|
||
|
||
r[acceptance.graph]
|
||
PNG/SVG graph files must be created for each graph command and viewable in standard image viewers.
|
||
|
||
r[acceptance.logging]
|
||
Verbose/quiet modes and file logging must work as specified, with timestamps and levels.
|
||
|
||
r[acceptance.testing]
|
||
Code coverage must be ≥90 %; at least one end-to-end CLI test exercising create, export, and dashboard.
|
||
|
||
r[acceptance.documentation]
|
||
README, usage guide, and plugin development docs must be complete and up-to-date.
|
||
|
||
## Deliverables Checklist
|
||
|
||
r[deliverables.binary]
|
||
The CLI binary `ravenous-tools` must be distributable on crates.io and as a GitHub release.
|
||
|
||
r[deliverables.repo-skeleton]
|
||
The `data/` repository scaffold must be created empty with a README.
|
||
|
||
r[deliverables.config-sample]
|
||
`config/ravenous_tools_data.toml` (sample) must be provided with default values.
|
||
|
||
r[deliverables.latex-template]
|
||
`templates/default_template.toml` must be available and referenceable.
|
||
|
||
r[deliverables.tests]
|
||
Unit tests covering ≥90 % and integration tests for each sub-command must be included.
|
||
|
||
r[deliverables.ci-workflow]
|
||
A complete ci integration must be provided.
|
||
|
||
r[deliverables.documentation]
|
||
README, usage guide, API docs, and plugin interface docs must be comprehensive.
|
||
|
||
r[deliverables.plugin-interface]
|
||
`ravenous_tools_plugin` crate exposing the trait must be published.
|
||
|
||
r[deliverables.example-plugin]
|
||
An example plugin (e.g., custom metric calculator) must be distributed with the repo.
|
||
|
||
## Future Requirements
|
||
|
||
r[bulk.classes.export]
|
||
The `export` command must accept one or several class names and generate tex files containing all requested classes.
|
||
|
||
r[bulk.parts.export]
|
||
The `export` command must accept one or several parts types and generate tex files containing all requested parts.
|
||
|
||
r[bulk.objects.export]
|
||
The `export` command must accept one or several objects types and generate tex files containing all requested objects.
|
||
|
||
r[graph.supported-types]
|
||
Supported graph types include bar chart, line chart, heat-map, radar chart.
|
||
|
||
r[completion.bash]
|
||
Auto-completion scripts for Bash must be installable via `install-completion` sub-command.
|
||
|
||
r[completion.zsh]
|
||
Auto-completion scripts for Zsh must be installable via `install-completion` sub-command.
|
||
|
||
r[completion.fish]
|
||
Auto-completion scripts for Fish must be installable via `install-completion` sub-command.
|
||
|
||
r[completion.powershell]
|
||
Auto-completion scripts for PowerShell must be installable via `install-completion` sub-command.
|
||
|
||
r[logging.file]
|
||
The `--log <path>` option must write structured logs (JSON-lines) to the specified file.
|
||
|
||
r[userstory.designer]
|
||
Game designers must be able to add a new class with a single command and see it reflected immediately in exports.
|
||
|
||
r[acceptance.crud]
|
||
All CRUD commands must correctly manipulate JSON files, with clear errors when classes are missing.
|