diff --git a/README.md b/README.md index 6b5057b..6cc345f 100644 --- a/README.md +++ b/README.md @@ -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.