beffroi-reporting/README.md

171 lines
5.9 KiB
Markdown

# Beffroi Reporting
Beffroi Reporting is the **integration workspace** for the Beffroi diagnostics and reporting toolchain.
It brings the complete environment together as Git submodules:
```text id="8efkt6"
beffroi-reporting
├── win-diagnostics/
├── beffroi-reports/
└── reportist/
```
The target layout uses `diagnostics/`, `reports/`, and `reporter/` respectively.
Renaming the current submodule paths is tracked in the migration roadmap.
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
↓
win-diagnostics
↓
diagnostic.json
↓
beffroi-reports
↓
report.yaml
↓
reportist
↓
PDF
```
## Getting started
Clone the complete workspace with its submodules:
```bash id="0mzx8u"
git clone --recursive <repository-url>
cd beffroi-reporting
```
For an existing checkout:
```bash id="ihk4op"
./bootstrap.sh
```
Bootstrap initializes the exact submodule revisions recorded by this repository,
checks Git, uv, and Typst, and prepares isolated Python 3.11 environments under
`.venv/component-checks/`. It may download submodules, Python, or pinned Python
packages, but it 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 | Workspace scripts, pinned submodules, and high-level commands |
| uv 0.12.13 | Creates Python 3.11 environments and installs locked dependencies |
| Python 3.11.14 | Tested component runtime, selected through uv |
| 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:
```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.
## Run the workflow
`make help` lists the high-level commands. Each delegates to the pinned component
CLI and requires explicit paths and report metadata. For example:
```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 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.
## Run component checks
On Linux/macOS with Bash, Git, Make, and `uv` available, run:
```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.
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.
## 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](win-diagnostics/docs/diagnostic-contract.md) and
[report validation](reportist/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.
## License
Root-level software and orchestration code is licensed under the **MIT License**.
Internal Beffroi data and content remain proprietary where applicable; see `LICENSE-DATA.md`.