74 lines
2.9 KiB
Markdown
74 lines
2.9 KiB
Markdown
# 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`](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
|
|
|
|
```bash
|
|
./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`](reporter/plugins/report).
|
|
|
|
## Render one diagnostic
|
|
|
|
```bash
|
|
./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`](reporter/plugins/diagnostics). Its PDF renderer
|
|
uses the raw capture directly; its separate analyzer can also emit normalized
|
|
diagnostic JSON v1 for evidence processing:
|
|
|
|
```bash
|
|
./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
|
|
|
|
```bash
|
|
./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
|
|
|
|
```text
|
|
./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`](docs/development.md) for implementation details.
|