145 lines
4.9 KiB
Markdown
145 lines
4.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.
|
|
|
|
## 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`.
|