Generic Typst-based report renderer. Turns structured YAML/JSON reports into sober, reproducible PDF documents.
Go to file
Dandaedre a82bda2b4f
ci: remove standalone validation stage
2026-09-16 00:55:28 +02:00
docs docs: separate user and contributor guides 2026-09-16 00:47:13 +02:00
examples feat: define generic report v1 contract and YAML JSON validator 2026-09-15 16:32:36 +02:00
schema feat: define generic report v1 contract and YAML JSON validator 2026-09-15 16:32:36 +02:00
templates refactor: remove Python from Reportist runtime 2026-09-16 00:20:21 +02:00
tests fix: enforce report contract in production validator 2026-09-16 00:31:29 +02:00
tools ci: align renderer checks with portable runtime 2026-09-16 00:52:51 +02:00
.gitignore feat: define generic report v1 contract and YAML JSON validator 2026-09-15 16:32:36 +02:00
AGENT.md refactor: remove Python from Reportist runtime 2026-09-16 00:20:21 +02:00
AGENTS-TASKS.md docs: complete non-Python renderer migration 2026-09-16 00:29:37 +02:00
Jenkinsfile ci: remove standalone validation stage 2026-09-16 00:55:28 +02:00
LICENSE Initial commit 2026-09-15 14:49:58 +02:00
Makefile refactor: remove Python from Reportist runtime 2026-09-16 00:20:21 +02:00
README.md docs: separate user and contributor guides 2026-09-16 00:47:13 +02:00
requirements.in feat: define generic report v1 contract and YAML JSON validator 2026-09-15 16:32:36 +02:00
requirements.txt feat: define generic report v1 contract and YAML JSON validator 2026-09-15 16:32:36 +02:00

README.md

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, jq, 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

make render \
  INPUT=examples/example-report.yaml \
  OUTPUT=output/example-report.pdf

Or call the renderer directly:

bash tools/render.sh report.yaml --output report.pdf

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

make validate INPUT=examples/example-report.yaml

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.