Architecture
How the code is organised
This page is for people who read or change the source of rqm. It says where things live and which rules keep them there.
The crates
The workspace has three crates:
rqmis the library and the command line.cargo install rqminstalls it.rqm-attrholds the#[rqm("...")]attribute. It is a pass-through: it returns the item unchanged, depends on nothing, and only checks that its arguments are string literals. A project adds it as a dev-dependency.xtaskholds the tools of this repository: the fixture harness (cargo xtask fixtures), the book tools (cargo xtask book) and the generator ofdocs/DIAGNOSTICS.md(cargo xtask diagnostics). It is never published.
The modules of rqm
main.rs parses the arguments, dispatches once, and maps the outcome to an exit code
cli/ one module for each command, and no business logic
config/ reading and validating rqm.yaml, finding it, the policy fingerprint, the template that init writes
yaml/ the strict YAML front door: the pinned options, typed scalars, and the writer
model/ requirements, kinds, references as distinct types, and inheritance
canon/ the canonical form that is hashed
hash/ the hashes, the algorithm id and the table of normative fields
scan/ the Rust source scan: targets, modules, test declarations, annotations, selectors
join/ the report adapters (nextest, pytest, generic), the XML reader and the attribution of cases to tests
verify/ the evaluation of a run, eligibility, presentation, the baseline evaluation and manual evidence
run/ starting suites, ending them, capturing output, run records and the run directory
promote/ the pure parts of promotion: relatedness, the plan and the baseline that is built
baseline/ the baseline model, the strict reader, and the staged atomic write
edit/ changing text at the spans that the readers report, which `rename` uses
fs/ opening files below the project root without following links, atomic writes, and write plans
output/ the human renderer and the JSON envelope
diag/ diagnostic codes, severities, spans and the registry
discover.rs finding the requirement files
snapshot.rs the immutable snapshot
The rule that matters most
verify/ and promote/ decide, and they touch nothing. They have no access to files, processes, the environment or the clock. The clock for a promotion is read once, in the command, and passed in as text. A guard test reads the code of both modules and fails on any use of std::fs, std::process, std::env or a clock. Because of that rule, the logic that matters most for correctness can be tested without a machine, and fuzzed.
All platform-specific code lives behind fs/ and run/. The only unsafe code is in the Windows modules of those two, and a guard test pins the number of unsafe blocks in each.
Where things are read once
- Requirement files are parsed in one place,
RequirementSet::load, and Rust sources in one place, the scan. Each file is opened safely, read once into a buffer, hashed, and parsed from that same buffer, so a hash never belongs to a different version of the file than the parse. Guard tests keep both places single. - The environment is read in three places only: the search for the configuration (
RQM_CONFIG), the lookup of the program of a suite (PATHandPATHEXT) and the lookup of the editor (VISUALandEDITOR). A guard test keeps it so. Everything else receives what it needs through theContextof the command, which is also how the tests run a command in process without touching the environment. - New uuids come from one function, and the generator is called in one file. It is the only part of rqm that is not deterministic.
- The label of a verification state is produced in
verify/presentation.rsand nowhere else.
The shape of a command
A command builds a snapshot, does its work on it, and returns an outcome that holds its data, its diagnostics and its exit category. One function renders the outcome in the human or the JSON form, and one function maps it to an exit code. A command writes only through the write plan of fs/, which checks everything first, writes in order, and undoes what it did when a step fails. init, create, rename and edit all work that way.
Every key of every command’s data is documented in docs/JSON.md, and a test fails when a key is missing from it. Every diagnostic code is registered in crates/rqm/src/diag/code.rs with its category, severity, exit code, message shape and remedy, and docs/DIAGNOSTICS.md is generated from that registry.
The book
The book is checked by cargo xtask book check, which cargo test also runs. It checks that every page is listed in SUMMARY.md, that links and includes point at something, that the pages are ASCII, that every document in docs/ is included by a page, that the --help pages are what the program prints now, that every command has a page, and that every example runs and prints what the page shows. book/AUTHORING.md is the guide for people who change it.