Reproducible Beffroi diagnostics and reporting workspace, pinning the collector, report archive and renderer into one workflow.
Go to file
Dandaedre e8d67091da
refactor: align integration submodule paths
2026-09-15 23:58:12 +02:00
diagnostics@757866e637 refactor: align integration submodule paths 2026-09-15 23:58:12 +02:00
docs refactor: align integration submodule paths 2026-09-15 23:58:12 +02:00
references chore: establish reporting migration workspace 2026-09-15 15:00:26 +02:00
reporter@b4472e9055 refactor: align integration submodule paths 2026-09-15 23:58:12 +02:00
reports@d00f648f69 refactor: align integration submodule paths 2026-09-15 23:58:12 +02:00
scripts refactor: align integration submodule paths 2026-09-15 23:58:12 +02:00
.gitignore Adds all gitignores & READMEs 2026-09-15 15:15:36 +02:00
.gitmodules refactor: align integration submodule paths 2026-09-15 23:58:12 +02:00
AGENTS-TASKS.md refactor: align integration submodule paths 2026-09-15 23:58:12 +02:00
AGENTS.md Add AGENTS.md 2026-09-15 14:53:51 +02:00
Jenkinsfile test: run complete sanitized reporting pipeline 2026-09-15 22:41:11 +02:00
LICENSE.md New licences 2026-09-15 15:05:13 +02:00
Makefile feat: add bootstrap and workflow commands 2026-09-15 23:14:19 +02:00
README.md refactor: align integration submodule paths 2026-09-15 23:58:12 +02:00
bootstrap.sh refactor: align integration submodule paths 2026-09-15 23:58:12 +02:00

README.md

Beffroi Reporting

Beffroi Reporting is the integration workspace for the Beffroi diagnostics and reporting toolchain.

It brings the complete environment together as Git submodules:

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:

Windows
   ↓
diagnostics/ (win-diagnostics)
   ↓
diagnostic.json
   ↓
reports/ (beffroi-reports)
   ↓
report.yaml
   ↓
reporter/ (reportist)
   ↓
PDF

Getting started

Clone the complete workspace with its submodules:

git clone --recursive <repository-url>
cd beffroi-reporting

For an existing checkout:

./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:

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:

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:

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:

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:

git config push.recurseSubmodules on-demand

See the Git push documentation.

Migration status

🚧 Architecture migration in progress

AGENTS-TASKS.md tracks completed work, remaining migration passes, acceptance criteria, and the next-pass handoff. AGENTS.md defines repository ownership and rules for agents working across the workspace.

The first executable migration check is the synthetic legacy baseline. It records diagnostic behavior and renders example PDFs before extraction.

Version-1 diagnostic validation and report validation 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.