115 lines
3.4 KiB
Markdown
115 lines
3.4 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, 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:
|
|
|
|
```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
|
|
scripts/workflow.sh all \
|
|
/path/to/evidence/capture.json \
|
|
/path/to/evidence \
|
|
/path/to/new-run \
|
|
2026-09-15T12:00:00Z \
|
|
'Diagnostic review' \
|
|
'Reviewer Name' \
|
|
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
|
|
scripts/workflow.sh analyse CAPTURE EVIDENCE_ROOT OUTPUT REFERENCE_TIME
|
|
scripts/workflow.sh draft DIAGNOSTIC EVIDENCE_ROOT OUTPUT_DIR TITLE AUTHOR DATE
|
|
scripts/workflow.sh render REPORT OUTPUT
|
|
```
|
|
|
|
Process every JSON capture in a directory tree through all stages with:
|
|
|
|
```bash
|
|
scripts/workflow-all.sh CAPTURE_DIR EVIDENCE_ROOT OUTPUT_ROOT REFERENCE_TIME TITLE AUTHOR DATE
|
|
```
|
|
|
|
This creates parallel `diagnostics`, `generations`, and `pdfs` trees beneath a
|
|
new output root.
|
|
|
|
## 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).
|