2.4 KiB
Reportist
Reportist is a standalone Typst-based renderer for structured reports. It validates YAML or JSON input and produces sober, reproducible PDF documents.
report.yaml or report.json → validate → Typst → report.pdf
Reportist handles report structure, branding, presentation, and rendering. It does not collect evidence or interpret diagnostics, and it has no dependency on Beffroi-specific repositories.
Requirements
Runtime rendering requires Bash, Typst 0.15 or newer, standard POSIX utilities, and the fonts selected by the report. The examples use DejaVu Sans and DejaVu Sans Mono.
Render a report
bash tools/render.sh report.yaml --output report.pdf
Render every YAML and JSON report in a directory tree with:
bash tools/render-all.sh reports --output-dir output
The renderer validates input before invoking Typst. It stages the report and its
branding asset in an isolated temporary project, then publishes the completed
PDF after a successful render. Existing output is rejected unless --force is explicit.
Logo paths resolve relative to the input report. Absolute paths, parent traversal, and symlinked assets are rejected. Reports without branding use the neutral default theme.
Use --typst /path/to/typst when Typst is not available under the default
command name.
Validate a report
bash tools/validate.sh examples/example-report.yaml
Use bash tools/validate-all.sh DIRECTORY to validate a directory tree.
The version 1 format supports metadata, branding, summaries, timelines, findings, generic content sections, action plans, provenance, and appendices. See docs/report-contract.md and schema/report.schema.json for the complete public contract.
Exit codes
| Code | Meaning |
|---|---|
0 |
Validation or rendering succeeded |
1 |
Input, validation, asset, Typst, or I/O failure |
2 |
Invalid command-line usage |
Reproducibility
Record the Reportist revision, typst --version, and installed font files when
recreating a historical document. PDF bytes can vary across Typst or font
versions even when the report content and layout remain equivalent.
Contributing
See the contributor guide.
License
The software is licensed under the MIT License. Examples and bundled assets may carry their own terms where indicated.