beffroi-reporting/docs/development.md

1.4 KiB

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.