beffroi-reporting/README.md

74 lines
2.9 KiB
Markdown

# Beffroi Reporting
Beffroi Reporting builds PDF reports from authored YAML/JSON and raw
WinDiagnostics captures. The Reportist plugins own their document
structure separately. Both import the visual elements and palettes in
[`reporter/visual`](reporter/visual).
The `reports` component contains only source content. Reportist provides the
standalone `reporter/build.sh` CLI for either document type; this macro checkout
owns edition, integration checks, encrypted packaging, and publication CI.
## Render one report
```bash
./beffroi.sh report reports/reports/2026-09-04-clevo-handoff.yaml report.pdf
```
Authored reports use `organization`, `theme`, `metadata`, `summary`, `sections`,
`findings`, `actions`, and any report-specific fields. Available named palettes
are `default`, `cic`, and `eridani`; a custom theme dictionary is also accepted.
The report plugin is in [`reporter/plugins/report`](reporter/plugins/report).
## Render one diagnostic
```bash
./beffroi.sh diagnostic-pdf reports/diagnostics/windows_system_report_DESKTOP-SAU019H_20260915_121057.json diagnostic.pdf
```
`diagnostic-pdf` and `capture-pdf` accept **raw WinDiagnostics JSON v1 or v2**.
Set `DIAGNOSTICS_THEME=default`, `cic`, or `eridani`, and optionally
`DIAGNOSTICS_AUTHOR`, before rendering. The diagnostic plugin is in
[`reporter/plugins/diagnostics`](reporter/plugins/diagnostics). Its PDF renderer
uses the raw capture directly; its separate analyzer can also emit normalized
diagnostic JSON v1 for evidence processing:
```bash
./beffroi.sh diagnostic CAPTURE.json EVIDENCE_ROOT NEW_OUTPUT_DIR REFERENCE_TIME [AUTHOR] [THEME]
```
That command writes `diagnostic.json` and `report.pdf`.
## Build the publication
```bash
./beffroi.sh all build/publication
./beffroi.sh all build/publication --replace --include-json
```
The build creates seven authored report PDFs and ten diagnostic PDFs from the
stored sources. `--include-json` exports authored report JSON and copies raw
diagnostic JSON alongside the PDFs. `--replace` stages a complete build before
replacing an existing output directory.
Run `./beffroi.sh test` to test the plugins and compare every published PDF with
the original Typst renderer. When `legacy/typst_reporter/build` is present, the
comparison checks extracted text, page counts, and rasterized pages. Without
that local reference, it checks recorded original text hashes and page counts.
## Commands
```text
./beffroi.sh report INPUT.yaml|json OUTPUT.pdf [--force]
./beffroi.sh diagnostic-pdf CAPTURE.json OUTPUT.pdf
./beffroi.sh capture-pdf CAPTURE.json OUTPUT.pdf
./beffroi.sh diagnostic CAPTURE EVIDENCE_ROOT OUTPUT_DIR REFERENCE_TIME [AUTHOR] [THEME]
./beffroi.sh all OUTPUT_DIR [--include-json] [--replace]
./beffroi.sh package BUILD_DIR ARTIFACT_DIR
./beffroi.sh test
./beffroi.sh bootstrap
./beffroi.sh doctor
```
See [`docs/development.md`](docs/development.md) for implementation details.