docs: publish user-focused project guides
Beffroi Reporting CI Beffroi Reporting integration CI failed.
Beffroi/beffroi-reporting/pipeline/head There was a failure building this commit Details

This commit is contained in:
Dandaedre 2026-09-16 00:43:09 +02:00
parent 94c82ff24c
commit a0bc786801
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
4 changed files with 78 additions and 127 deletions

199
README.md
View File

@ -1,87 +1,59 @@
# Beffroi Reporting
Beffroi Reporting is the **integration workspace** for the Beffroi diagnostics and reporting toolchain.
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:
It brings the complete environment together as Git submodules:
| 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 id="8efkt6"
beffroi-reporting
├── diagnostics/ → win-diagnostics
├── reports/ → beffroi-reports
└── reporter/ → reportist
```
During migration, the previous implementations are also available under `references/` so developers and agents can inspect the complete old and new workflows from one workspace.
The target pipeline is:
```text id="z3j03k"
Windows
↓
diagnostics/ (win-diagnostics)
↓
```text
Windows capture
↓
diagnostic.json
↓
reports/ (beffroi-reports)
↓
report.yaml
↓
reporter/ (reportist)
↓
PDF
↓
reviewable report draft
↓
report.pdf
```
## Getting started
Each component can be used separately. This repository supplies the pinned
versions and high-level commands for the complete workflow.
Clone the complete workspace with its submodules:
## Requirements
```bash id="0mzx8u"
git clone --recursive <repository-url>
cd beffroi-reporting
```
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.
For an existing checkout:
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.
```bash id="ihk4op"
./bootstrap.sh
```
## Installation
Bootstrap initializes the exact submodule revisions recorded by this repository,
checks Git, Make, jq, Typst, and a C compiler, and builds the small atomic
publication helper. It may download submodules but does not install system
packages. Use `./bootstrap.sh --check`
for a read-only dependency and pinned-revision check.
### External dependencies
| Tool | Supported/tested use |
| --- | --- |
| Bash, Git, Make, jq | Workspace scripts, structured transformations, and high-level commands |
| C compiler | Builds the native atomic no-replace directory publisher |
| uv 0.12.13 and Python 3.11.14 | Test harness only; uv creates and synchronizes every Python environment |
| Typst 0.15.1 | PDF compilation; Reportist supports Typst 0.15 or newer |
| DejaVu Sans / Sans Mono | Fonts selected by the bundled synthetic examples |
| Poppler `pdfinfo` / `pdftotext` | Optional pagination/text inspection in Reportist tests |
The first bootstrap may require network access for HTTPS submodules, Python, and
locked packages. Recreate and verify a pinned checkout with:
Clone the workspace with its pinned submodules and run bootstrap:
```bash
git clone --recursive <repository-url>
cd beffroi-reporting
./bootstrap.sh
make check
./bootstrap.sh --check
```
`git submodule status` prints the exact component revisions. A historical root
commit therefore selects its recorded compatible tool set rather than remote
branch heads. Exact PDF bytes can still vary with the Typst binary and font files.
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.
## Run the workflow
## Create a report
`make help` lists the high-level commands. Each delegates to the pinned component
CLI and requires explicit paths and report metadata. For example:
Run the complete workflow with an explicit capture, evidence root, and new work
directory:
```bash
make all \
@ -94,76 +66,55 @@ make all \
DATE=2026-09-15
```
The work directory must not exist. A successful run contains `diagnostic.json`,
an immutable `generation/`, and `report.pdf`. The individual `make analyse`,
`make draft`, and `make render` commands expose the same stages when review or
human editing is needed between them. Run `make help` for their variables.
The work directory must not already exist. A successful run creates:
## Run component checks
```text
new-run/
├── diagnostic.json
├── generation/
│ ├── diagnostic.json
│ ├── evidence/
│ ├── generation.json
│ └── report.draft.json
└── report.pdf
```
On Linux/macOS with Bash, Git, Make, and `uv` available, run:
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.
## Verification
Run all component suites and the sanitized capture-to-PDF integration test:
```bash
make check
```
The same runner is used by Jenkins (`bash scripts/check-components.sh`). It
creates separate Python 3.11 environments under `.venv/component-checks/` and
synchronizes each component's pinned requirements. On first use, uv may download
Python and dependencies, requiring network access. No system packages are changed.
The runner prints tool versions and component revisions and stops on any failure.
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.
Current coverage includes the diagnostic and report contract suites, Reportist
rendering tests, adapter preservation tests, and a branded synthetic
raw-capture-to-diagnostic-to-report-to-PDF path. The analyser covers all 53
reviewed event rules and seven advisory watchlist entries. Native Windows
collection and broader non-event health checks remain.
Submodules must already be initialized with the command above.
## Reproducibility
## Push component commits and the workspace together
After committing changes inside each component and committing their updated
submodule pins in this repository, run from the macro repository:
```bash
git push --recurse-submodules=on-demand
```
Git pushes the component commits needed by the macro commits before pushing the
macro repository. If a required component push fails, the macro push stops.
This uses each repository's configured remote/upstream; it does not commit files
or push unrelated component branches. All current component `main` branches have
an `origin/main` upstream. Unchanged reference submodules need no push.
To make that behavior the local default for this checkout:
```bash
git config push.recurseSubmodules on-demand
```
See the [Git push documentation](https://git-scm.com/docs/git-push#Documentation/git-push.txt---recurse-submodulescheckon-demandonlyno).
## Migration status
🚧 **Architecture migration in progress**
[AGENTS-TASKS.md](AGENTS-TASKS.md) tracks completed work, remaining migration passes,
acceptance criteria, and the next-pass handoff. [AGENTS.md](AGENTS.md) defines
repository ownership and rules for agents working across the workspace.
The first executable migration check is the [synthetic legacy baseline](docs/migration-baseline.md).
It records diagnostic behavior and renders example PDFs before extraction.
Version-1 [diagnostic validation](diagnostics/docs/diagnostic-contract.md) and
[report validation](reporter/docs/report-contract.md) are available independently
in their component repositories. The pinned components now run the sanitized
end-to-end pipeline through the root workflow; native collection and historical
incident migration remain in progress.
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 software and orchestration code is licensed under the **MIT License**.
Internal Beffroi data and content remain proprietary where applicable; see
[LICENSE.md](LICENSE.md). [Remaining external gates](docs/remaining-gates.md)
records the Windows, private-incident, and publication evidence still required.
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).

@ -1 +1 @@
Subproject commit f93c5d308319d3d74b71249880bbfa5a82c7b34f
Subproject commit bc319ece292fdfbcdc9ef475930f3878f6235771

@ -1 +1 @@
Subproject commit 76ef0760891c93c0e6821f5be24b0904091dbcbe
Subproject commit 1d04ac9b44074682438b596fdb686fdcba5a0655

@ -1 +1 @@
Subproject commit 03fc452e2bf599e3a44a1528d95961ecf50ea206
Subproject commit dbf247773c6e73197d4f5bab18f3c28381a7bb6a