3.7 KiB
Beffroi Reporting
Beffroi Reporting is a reproducible workspace for turning Windows diagnostic captures into structured findings and PDF reports. It pins compatible revisions of three independent tools:
| Directory | Component | Responsibility |
|---|---|---|
diagnostics/ |
Win Diagnostics | Normalizes captures and produces traceable diagnostic findings |
reports/ |
Beffroi Reports | Creates immutable report drafts with evidence and provenance |
reporter/ |
Reportist | Validates YAML or JSON report definitions and renders PDFs with Typst |
Windows capture
↓
diagnostic.json
↓
reviewable report draft
↓
report.pdf
Each component can be used separately. This repository supplies the pinned versions and high-level commands for the complete workflow.
Requirements
The runtime uses Bash, Git, Make, jq, Typst 0.15 or newer, and a C compiler. The compiler builds a small helper used for atomic, no-replace publication. Selected report fonts must also be installed; the examples use DejaVu Sans and DejaVu Sans Mono.
Tests additionally require uv. Python is used only by the test suites, always in
uv-managed virtual environments. Poppler's pdfinfo and pdftotext enable
optional PDF inspection tests.
Installation
Clone the workspace with its pinned submodules and run bootstrap:
git clone --recursive <repository-url>
cd beffroi-reporting
./bootstrap.sh
Bootstrap checks runtime dependencies, initializes the recorded submodule
revisions, and builds the publication helper. It does not install system
packages. For an existing checkout, the same command initializes any missing
submodules. Use ./bootstrap.sh --check to verify dependencies and pins without
changing the checkout.
Create a report
Run the complete workflow with an explicit capture, evidence root, and new work directory:
make all \
CAPTURE=/path/to/evidence/capture.json \
EVIDENCE_ROOT=/path/to/evidence \
WORK_DIR=/path/to/new-run \
REFERENCE_TIME=2026-09-15T12:00:00Z \
TITLE='Diagnostic review' \
AUTHOR='Reviewer Name' \
DATE=2026-09-15
The work directory must not already exist. A successful run creates:
new-run/
├── diagnostic.json
├── generation/
│ ├── diagnostic.json
│ ├── evidence/
│ ├── generation.json
│ └── report.draft.json
└── report.pdf
The generation directory is immutable and records source hashes, tool versions, options, and evidence. Existing destinations are never overwritten.
Use the individual stages when a report needs review or editing between steps:
make analyse CAPTURE=... EVIDENCE_ROOT=... OUTPUT=... REFERENCE_TIME=...
make draft DIAGNOSTIC=... EVIDENCE_ROOT=... OUTPUT_DIR=... TITLE=... AUTHOR=... DATE=...
make render REPORT=... OUTPUT=...
Run make help for the complete command summary.
Verification
Run all component suites and the sanitized capture-to-PDF integration test:
make check
The tests create isolated uv environments inside each component. They cover the diagnostic contracts and rule catalog, immutable and racing publication, Reportist validation and rendering, replaceable branding, and the complete pipeline.
Reproducibility
Git submodules pin exact component commits instead of following branch heads.
git submodule status shows the selected revisions. Record the root commit,
Typst version, and installed font files when reproducing a historical report.
PDF bytes can vary across Typst and font versions even when content and layout
remain equivalent.
License
Root-level orchestration software is licensed under the MIT License. Diagnostic evidence, report content, and branding may have separate terms; see LICENSE.md.