79 lines
2.4 KiB
Markdown
79 lines
2.4 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
|
|
bash tools/render.sh report.yaml --output report.pdf
|
|
```
|
|
|
|
Render every YAML and JSON report in a directory tree with:
|
|
|
|
```bash
|
|
bash tools/render-all.sh reports --output-dir output
|
|
```
|
|
|
|
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
|
|
bash tools/validate.sh examples/example-report.yaml
|
|
```
|
|
|
|
Use `bash tools/validate-all.sh DIRECTORY` to validate a directory tree.
|
|
|
|
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.
|