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