108 lines
3.2 KiB
Markdown
108 lines
3.2 KiB
Markdown
# 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 |
|
|
|
|
```text
|
|
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.
|
|
|
|
## Installation
|
|
|
|
Clone the workspace with its pinned submodules and run bootstrap:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
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](docs/development.md).
|
|
|
|
## License
|
|
|
|
Root-level orchestration software is licensed under the MIT License. Diagnostic
|
|
evidence, report content, and branding may have separate terms; see
|
|
[LICENSE.md](LICENSE.md).
|