docs: publish user-focused README
Reportist CI Reportist failed CI.
Beffroi/reportist/pipeline/head There was a failure building this commit Details

This commit is contained in:
Dandaedre 2026-09-16 00:43:03 +02:00
parent 76ef076089
commit 1d04ac9b44
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
1 changed files with 62 additions and 55 deletions

117
README.md
View File

@ -1,79 +1,86 @@
# Reportist
Reportist is a generic **Typst-based report renderer**.
Reportist is a standalone Typst-based renderer for structured reports. It
validates YAML or JSON input and produces sober, reproducible PDF documents.
It turns structured YAML/JSON report definitions into sober, reproducible PDF documents.
```text id="38bc54"
report.yaml
↓
Reportist
↓
report.pdf
```text
report.yaml or report.json → validate → Typst → 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 handles report structure, branding, presentation, and rendering. It
does not collect evidence or interpret diagnostics, and it has no dependency on
Beffroi-specific repositories.
Reportist originates from the reporting tooling developed for the Beffroi diagnostics workflow, but is designed to be usable independently.
## Requirements
## 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.
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. Python and uv are used only for tests.
## Render a report
Runtime requirements are Bash, Typst 0.15 or newer, core POSIX utilities, and
the fonts selected by the report. The examples use DejaVu Sans and DejaVu Sans
Mono. Python and uv are test-only dependencies.
```bash
make render INPUT=examples/example-report.yaml OUTPUT=output/example-report.pdf
make render \
INPUT=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.
Or call the renderer directly:
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`.
```bash
bash tools/render.sh report.yaml --output report.pdf
```
For repeatable output, record the Reportist revision, `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.
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.
Run the standalone suite with:
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
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](docs/report-contract.md) and
[schema/report.schema.json](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.
## Testing
Run validation, rendering, branding, pagination, and standalone tests in a
uv-managed environment:
```bash
make test
```
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 validation errors, run `make validate INPUT=...`
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.
Poppler's `pdfinfo` and `pdftotext` enable additional pagination and extracted
text checks when installed.
## License
Software source code is licensed under the **MIT License**.
Examples and bundled assets may be subject to their own terms where indicated.
The software is licensed under the MIT License. Examples and bundled assets may
carry their own terms where indicated.