Reproducible Beffroi diagnostics and reporting workspace, pinning the collector, report archive and renderer into one workflow.
Go to file
Dandaedre 5967f3e843
Beffroi Reporting CI All component and integration checks passed.
Beffroi/beffroi-reporting/pipeline/head This commit looks good Details
refactor: adopt typst and rust runtime
2026-09-16 01:20:41 +02:00
diagnostics@e1ae8bb5df refactor: adopt typst and rust runtime 2026-09-16 01:20:41 +02:00
docs docs: separate user and contributor guides 2026-09-16 00:47:21 +02:00
references chore: establish reporting migration workspace 2026-09-15 15:00:26 +02:00
reporter@5902c6bc43 refactor: adopt typst and rust runtime 2026-09-16 01:20:41 +02:00
reports@419132b85f refactor: adopt typst and rust runtime 2026-09-16 01:20:41 +02:00
scripts refactor: adopt typst and rust runtime 2026-09-16 01:20:41 +02:00
tests refactor: remove Python from reporting runtime 2026-09-16 00:31:53 +02:00
.gitignore Adds all gitignores & READMEs 2026-09-15 15:15:36 +02:00
.gitmodules refactor: align integration submodule paths 2026-09-15 23:58:12 +02:00
AGENTS-TASKS.md refactor: adopt typst and rust runtime 2026-09-16 01:20:41 +02:00
AGENTS.md refactor: adopt typst and rust runtime 2026-09-16 01:20:41 +02:00
Jenkinsfile ci: remove workspace validation stages 2026-09-16 00:55:34 +02:00
LICENSE.md New licences 2026-09-15 15:05:13 +02:00
Makefile feat: add bootstrap and workflow commands 2026-09-15 23:14:19 +02:00
README.md refactor: adopt typst and rust runtime 2026-09-16 01:20:41 +02:00
bootstrap.sh refactor: adopt typst and rust runtime 2026-09-16 01:20:41 +02:00

README.md

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, Typst 0.15 or newer, and Rust/Cargo. Cargo installs 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.

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.

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.

Contributing

See the contributor guide.

License

Root-level orchestration software is licensed under the MIT License. Diagnostic evidence, report content, and branding may have separate terms; see LICENSE.md.