docs: focus readme on standalone report making

This commit is contained in:
Dandaedre 2026-09-16 02:03:08 +02:00
parent 7a7ba72524
commit 79179b2f68
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
1 changed files with 16 additions and 62 deletions

View File

@ -1,78 +1,32 @@
# Reportist
Reportist is a standalone Typst-based renderer for structured reports. It
validates YAML or JSON input and produces sober, reproducible PDF documents.
Reportist is a standalone structured-report maker. Give it a YAML or JSON report
definition and it produces a PDF with Typst. It has no dependency on the Beffroi
integration repository or diagnostic tools.
```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
## Render one report
```bash
bash tools/render.sh report.yaml --output report.pdf
bash tools/render.sh examples/example-report.yaml --output report.pdf
```
Render every YAML and JSON report in a directory tree with:
The renderer validates the input, loads an optional report-relative logo, and
writes the completed PDF. Existing output requires `--force`.
## Render every report in a directory
```bash
bash tools/render-all.sh reports --output-dir output
bash tools/render-all.sh /path/to/reports --output-dir /path/to/pdfs
```
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 after a successful render. 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
## Validate without rendering
```bash
bash tools/validate.sh examples/example-report.yaml
bash tools/validate-all.sh /path/to/reports
```
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.
Start with [`examples/example-report.yaml`](examples/example-report.yaml) or the
smaller [`examples/minimal-report.json`](examples/minimal-report.json). See
[`docs/report-contract.md`](docs/report-contract.md) for all fields and
[`docs/development.md`](docs/development.md) for tests and template development.