beffroi-reporting/docs/development.md

26 lines
1.4 KiB
Markdown

# Development and parity
`beffroi.sh` routes authored reports and raw WinDiagnostics captures through
`reporter/build.sh`. Each plugin 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. The portable CI check uses pinned `pypdf` via `uv` for text and page
counts; Poppler adds its original text check and page raster comparison when
available. The recorded hashes guard CI builds without the ignored legacy
directory or Poppler tools.
The diagnostic analyzer at `reporter/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.