diff --git a/README.md b/README.md index ddbc47f..2d4eb52 100644 --- a/README.md +++ b/README.md @@ -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 -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 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). diff --git a/diagnostics b/diagnostics index f93c5d3..bc319ec 160000 --- a/diagnostics +++ b/diagnostics @@ -1 +1 @@ -Subproject commit f93c5d308319d3d74b71249880bbfa5a82c7b34f +Subproject commit bc319ece292fdfbcdc9ef475930f3878f6235771 diff --git a/reporter b/reporter index 76ef076..1d04ac9 160000 --- a/reporter +++ b/reporter @@ -1 +1 @@ -Subproject commit 76ef0760891c93c0e6821f5be24b0904091dbcbe +Subproject commit 1d04ac9b44074682438b596fdb686fdcba5a0655 diff --git a/reports b/reports index 03fc452..dbf2477 160000 --- a/reports +++ b/reports @@ -1 +1 @@ -Subproject commit 03fc452e2bf599e3a44a1528d95961ecf50ea206 +Subproject commit dbf247773c6e73197d4f5bab18f3c28381a7bb6a