beffroi-reporting/README.md

2.9 KiB

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.

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

./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.

Render one diagnostic

./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. Its PDF renderer uses the raw capture directly; its separate analyzer can also emit normalized diagnostic JSON v1 for evidence processing:

./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

./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

./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 for implementation details.