beffroi-reporting/README.md

77 lines
2.3 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
```bash
./beffroi.sh diagnostic-pdf capture.json diagnostic.pdf
```
This renders the capture directly with the established diagnostic layout. For
the evidence-backed analysis workflow, 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 output contains the normalized diagnostic, evidence-backed draft generation,
and rendered PDF.
## 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
./beffroi.sh diagnostic-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.