docs: publish user-focused README
Reportist CI Reportist failed CI.
Beffroi/reportist/pipeline/head There was a failure building this commit
Details
Reportist CI Reportist failed CI.
Beffroi/reportist/pipeline/head There was a failure building this commit
Details
This commit is contained in:
parent
76ef076089
commit
1d04ac9b44
117
README.md
117
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue