7.8 KiB
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.