beffroi-reporting/docs/development.md

24 lines
1.3 KiB
Markdown

# Development and parity
`beffroi.sh` routes authored reports to `reporter/render.sh` and raw
WinDiagnostics captures to `reports/plugins/diagnostics/render.sh`. Each stages
its own Typst document model. The shared `reporter/visual/elements.typ` module
contains palette, badge, heading, panel, callout, code-block, and progress-bar
primitives. Report and diagnostic document assembly remain independent.
The original renderer is retained locally under `legacy/typst_reporter`. Run its
`render.sh --all` and `render-diagnostics.sh --all Beffroi` scripts to refresh
the reference PDFs. `./beffroi.sh test` builds the stored publication and runs
`scripts/check-legacy-parity.py` against all 17 PDFs. With the local reference
available, the check compares every page raster as well as extracted text and
pagination. Recorded original text hashes and page counts also guard CI builds
without the ignored legacy directory.
The diagnostic analyzer at `reports/plugins/diagnostics/analyse.sh` produces a
normalized evidence artifact. It is separate from the PDF renderer. The
`diagnostic` workflow creates that artifact and a PDF from the same raw capture.
`./beffroi.sh all OUTPUT_DIR --replace` stages a new publication next to the
output directory and replaces it only after all PDFs are ready. `--include-json`
adds JSON source exports.