92 lines
3.0 KiB
Markdown
92 lines
3.0 KiB
Markdown
# Beffroi Reporting
|
|
|
|
Beffroi Reporting turns structured reports and Windows diagnostic captures into
|
|
PDFs. The root `beffroi.sh` command is the main entry point.
|
|
|
|
## Generate one personal report
|
|
|
|
Write a Reportist YAML or JSON file, then run:
|
|
|
|
```bash
|
|
./beffroi.sh report my-report.yaml my-report.pdf
|
|
```
|
|
|
|
See [`reporter/examples`](reporter/examples) for complete inputs.
|
|
To select a built-in palette in YAML, set `branding.theme` to `default` or
|
|
`teal`; an explicit theme object is also supported.
|
|
|
|
## Generate one diagnostic report
|
|
|
|
Render a normalized diagnostic JSON v1 through the shared Reportist engine:
|
|
|
|
```bash
|
|
./beffroi.sh diagnostic-pdf diagnostic.json diagnostic.pdf
|
|
```
|
|
|
|
Set `DIAGNOSTICS_THEME=default`, `cic`, or `eridani` to choose a bundled palette.
|
|
Reportist can also emit its JSON intermediate directly:
|
|
|
|
```bash
|
|
./beffroi.sh report diagnostic.json diagnostic.pdf \
|
|
--plugin reports/plugins/diagnostics --plugin-input theme=cic \
|
|
--emit-ir diagnostic.report.json
|
|
```
|
|
|
|
For a raw WinDiagnostics capture, run `./beffroi.sh capture-pdf capture.json
|
|
diagnostic.pdf`. This analyzes the capture first, then renders the diagnostic.
|
|
For a persistent evidence-backed draft generation, run:
|
|
|
|
```bash
|
|
./beffroi.sh diagnostic \
|
|
capture.json /path/to/evidence /path/to/new-output \
|
|
2026-09-15T12:00:00Z 'Diagnostic review' 'Reviewer Name' 2026-09-15
|
|
```
|
|
|
|
The generation includes normalized diagnostic JSON, a Reportist JSON draft,
|
|
evidence snapshots, a hash manifest, and a PDF. Custom reports can use the same
|
|
tables, progress bars, finding lists, and section page breaks; see
|
|
[`reporter/examples/diagnostic-style.yaml`](reporter/examples/diagnostic-style.yaml).
|
|
|
|
## Generate every stored PDF
|
|
|
|
Add report YAML files under
|
|
[`reports/reports`](reports/reports)
|
|
or diagnostic JSON captures under
|
|
[`reports/diagnostics`](reports/diagnostics),
|
|
commit them with the reports submodule update, and run:
|
|
|
|
```bash
|
|
./beffroi.sh all build/publication
|
|
```
|
|
|
|
Stored report YAML is validated and rendered directly. Use `--include-json` to
|
|
export structured report JSON beside report PDFs and
|
|
the original diagnostic JSON beside diagnostic PDFs. Packaging includes these
|
|
JSON files, which is useful for downstream automation:
|
|
|
|
```bash
|
|
./beffroi.sh all build/publication --include-json
|
|
```
|
|
|
|
Jenkins runs the same build and publishes AES-encrypted `Reports.zip` and
|
|
`Diagnostics.zip` archives from `main` into the dedicated `work_reports`
|
|
destination.
|
|
|
|
## Commands
|
|
|
|
```text
|
|
./beffroi.sh report INPUT OUTPUT.pdf [Reportist options]
|
|
./beffroi.sh diagnostic-pdf DIAGNOSTIC.json OUTPUT.pdf
|
|
./beffroi.sh capture-pdf CAPTURE OUTPUT.pdf
|
|
./beffroi.sh diagnostic CAPTURE EVIDENCE_ROOT OUTPUT_DIR REFERENCE_TIME TITLE AUTHOR DATE
|
|
./beffroi.sh all NEW_OUTPUT_DIR [--include-json]
|
|
./beffroi.sh package BUILD_DIR ARTIFACT_DIR
|
|
./beffroi.sh test
|
|
./beffroi.sh bootstrap
|
|
./beffroi.sh doctor
|
|
```
|
|
|
|
The command reports missing tools for the requested operation. See
|
|
[`docs/development.md`](docs/development.md) for repository structure, testing,
|
|
publication details, and component development.
|