docs: publish user-focused project guides
Beffroi Reporting CI Beffroi Reporting integration CI failed.
Beffroi/beffroi-reporting/pipeline/head There was a failure building this commit
Details
Beffroi Reporting CI Beffroi Reporting integration CI failed.
Beffroi/beffroi-reporting/pipeline/head There was a failure building this commit
Details
This commit is contained in:
parent
94c82ff24c
commit
a0bc786801
199
README.md
199
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 <repository-url>
|
||||
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 <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.
|
||||
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).
|
||||
|
|
|
|||
|
|
@ -1 +1 @@
|
|||
Subproject commit f93c5d308319d3d74b71249880bbfa5a82c7b34f
|
||||
Subproject commit bc319ece292fdfbcdc9ef475930f3878f6235771
|
||||
2
reporter
2
reporter
|
|
@ -1 +1 @@
|
|||
Subproject commit 76ef0760891c93c0e6821f5be24b0904091dbcbe
|
||||
Subproject commit 1d04ac9b44074682438b596fdb686fdcba5a0655
|
||||
2
reports
2
reports
|
|
@ -1 +1 @@
|
|||
Subproject commit 03fc452e2bf599e3a44a1528d95961ecf50ea206
|
||||
Subproject commit dbf247773c6e73197d4f5bab18f3c28381a7bb6a
|
||||
Loading…
Reference in New Issue