ravenous-tools/requirements/data.md

7.8 KiB
Raw Permalink Blame History

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.