170 lines
6.0 KiB
Markdown
170 lines
6.0 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
|
|
├── 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)
|
|
↓
|
|
diagnostic.json
|
|
↓
|
|
reports/ (beffroi-reports)
|
|
↓
|
|
report.yaml
|
|
↓
|
|
reporter/ (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, 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:
|
|
|
|
```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](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.
|
|
|
|
## 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.
|