ravenous-tools/requirements/data.md

226 lines
7.8 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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.