reportist/README.md

79 lines
2.3 KiB
Markdown

# Reportist
Reportist is a standalone Typst-based renderer for structured reports. It
validates YAML or JSON input and produces sober, reproducible PDF documents.
```text
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
make render \
INPUT=examples/example-report.yaml \
OUTPUT=output/example-report.pdf
```
Or call the renderer directly:
```bash
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
```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.
## Contributing
See the [contributor guide](docs/development.md).
## License
The software is licensed under the MIT License. Examples and bundled assets may
carry their own terms where indicated.