69 lines
3.3 KiB
Markdown
69 lines
3.3 KiB
Markdown
# Architecture
|
|
|
|
```mermaid
|
|
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/docs/build-cli.md).
|
|
`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 |
|
|
| PDF | 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.
|