Generic Typst-based report renderer. Turns structured YAML/JSON reports into sober, reproducible PDF documents.
Go to file
Dandaedre d6286735e9
docs: record verified renderer handoff
2026-09-15 23:03:08 +02:00
docs test: verify standalone report rendering 2026-09-15 23:02:51 +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 feat: render generic reports to PDF 2026-09-15 22:32:57 +02:00
tests test: verify standalone report rendering 2026-09-15 23:02:51 +02:00
tools feat: render generic reports to PDF 2026-09-15 22:32:57 +02:00
.gitignore feat: define generic report v1 contract and YAML JSON validator 2026-09-15 16:32:36 +02:00
AGENT.md Add AGENT.md 2026-09-15 14:50:21 +02:00
AGENTS-TASKS.md docs: record verified renderer handoff 2026-09-15 23:03:08 +02:00
Jenkinsfile test: verify standalone report rendering 2026-09-15 23:02:51 +02:00
LICENSE Initial commit 2026-09-15 14:49:58 +02:00
README.md test: verify standalone report rendering 2026-09-15 23:02:51 +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 generic Typst-based report renderer.

It turns structured YAML/JSON report definitions into sober, reproducible PDF documents.

report.yaml
    ↓
 Reportist
    ↓
report.pdf

The project handles report structure, validation, presentation, themes and rendering. It is intentionally independent from the systems producing the information contained in a report.

Reportist originates from the reporting tooling developed for the Beffroi diagnostics workflow, but is designed to be usable independently.

Status

🚧 Early development / migration

The first standalone renderer is implemented and being validated against the previous typst_reporter behavior.

See AGENT.md for repository ownership and development rules. AGENTS-TASKS.md tracks migration passes, completed work, acceptance criteria, and the next-pass handoff.

Render a report

Requirements: Python 3.11+, the pinned packages in requirements.txt, Typst 0.15 or newer, and the fonts selected by the report. The examples use DejaVu Sans and DejaVu Sans Mono.

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python tools/render.py examples/example-report.yaml \
  --output output/example-report.pdf

The CLI validates before rendering and works from outside the repository. It refuses an existing output unless --force is explicit. Exit 0 means a PDF was published, 1 means input, validation, asset, Typst, or I/O failure, and 2 means invalid CLI usage. Branding and logo paths come from report data; reports without branding use neutral colors and no logo.

Relative logo paths resolve from the report file's directory. The renderer rejects parent traversal and symlinks. It stages inputs in a temporary Typst project and atomically publishes the completed PDF. Use --typst /path/to/typst when Typst is not on PATH.

For repeatable output, record the Reportist revision, Python dependency lock, typst --version, and the installed font files. The examples select DejaVu Sans and DejaVu Sans Mono. PDF bytes can change across Typst or font versions even when the report content and layout remain equivalent.

Run the standalone suite with:

.venv/bin/python -m unittest discover -s tests -p 'test_*.py'

The pagination inspection uses Poppler's pdfinfo and pdftotext when available. If rendering reports a missing font, install the selected theme fonts or choose fonts available on the host. For schema errors, run tools/validate.py directly to see the failing JSON path. A missing logo is resolved relative to the input report, not the current directory.

Contract validation

The version-1 schema, standalone validator, and synthetic examples are available. See contract documentation for setup and validation commands. The generic PDF slice includes long-content pagination, alternate branding, asset-safety, and isolated standalone-copy checks.

License

Software source code is licensed under the MIT License.

Examples and bundled assets may be subject to their own terms where indicated.