83 lines
3.1 KiB
Markdown
83 lines
3.1 KiB
Markdown
# Reportist
|
|
|
|
Reportist is a generic **Typst-based report renderer**.
|
|
|
|
It turns structured YAML/JSON report definitions into sober, reproducible PDF documents.
|
|
|
|
```text id="38bc54"
|
|
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](AGENT.md) for repository ownership and development rules.
|
|
[AGENTS-TASKS.md](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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
.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](docs/report-contract.md) 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.
|