3.3 KiB
Architecture
flowchart LR
S[Reports: YAML and raw JSON sources] --> M[Macro: beffroi.sh and publication build]
M --> C[Reportist: build.sh]
C --> R[Report plugin]
C --> D[Diagnostic plugin]
V[Shared visual elements and themes] --> R
V --> D
D --> A[Normalized evidence JSON, when requested]
R --> P[PDFs]
D --> P
P --> Z[Macro: encrypted archives and Jenkins publication]
Component contracts
Reports stores authored YAML reports in reports/reports/ and raw
WinDiagnostics JSON captures in reports/diagnostics/. The raw captures are
source evidence for the diagnostic renderer. It has a small syntax checker and
Jenkins job, but no plugin, analyzer, or visual asset. Source provenance is
documented in reports/docs/preserved-source.md.
Reportist is the rendering engine. Its public entry point is
reporter/build.sh; see its CLI contract.
reporter/plugins/report/ interprets authored reports.
reporter/plugins/diagnostics/ interprets raw captures and, separately,
produces normalized evidence JSON. These plugins have independent Typst
models. Both import reporter/visual/elements.typ and use the palettes in
reporter/visual/themes.yaml. reporter/tools/render-common.sh shares shell
option, path, and temporary staging rules. Each renderer stages its own Typst
model and resources so it can compile without the macro repository.
The macro repository pins both components as submodules. beffroi.sh
provides convenient commands for editing and checking one source.
scripts/build-publication.sh builds all stored sources into a new staged
publication and replaces an existing build only after rendering succeeds.
scripts/package-reports.sh creates AES-encrypted Reports.zip and
Diagnostics.zip. The root Jenkinsfile tests, builds, packages, archives,
and publishes those archives from main.
Data and output boundaries
| Input or output | Format | Owner |
|---|---|---|
| Authored report | YAML or JSON with fields defined by the report plugin | Reports content; Reportist interpretation |
| Raw capture | WinDiagnostics JSON v1/v2 | Reports content; diagnostic plugin interpretation |
| Normalized diagnostic | Diagnostic evidence JSON v1 | Diagnostic analyzer and validator |
| Plugin-specific layout | Reportist renderer | |
| Publication directory and encrypted ZIPs | Batch artifacts | Macro repository |
A normalized diagnostic is an evidence artifact. The diagnostic PDF is rendered
from the raw capture, not from a report-shaped intermediate representation.
Neither plugin is required to conform to the other's schema. New plugin kinds
are routed explicitly in reporter/build.sh; there is no automatic registry.
Verification
uv run --script reports/check_sources.py checks the YAML and JSON source
syntax. Reports CI runs this check on its own repository.
./beffroi.sh test runs the component suites, a diagnostic analysis workflow,
and a full publication build. The parity checker verifies the set of 17 PDFs,
recorded text hashes, and page counts. When original PDFs and Poppler are
available locally, it also compares rasterized pages. New plugins should add
focused input/render tests; an approved existing output needs a regression
oracle before its renderer is changed.