154 lines
5.0 KiB
Markdown
154 lines
5.0 KiB
Markdown
# Beffroi Reports
|
|
|
|
Create consistent technical PDF reports from readable, version-controlled YAML.
|
|
Typst handles the layout, while each report remains easy to edit, review, and
|
|
diff in Git.
|
|
|
|
## Quick overview
|
|
|
|
### Requirements
|
|
|
|
- [Typst](https://typst.app/) available as `typst`
|
|
- Bash and standard Unix command-line utilities
|
|
|
|
No additional Typst packages are required.
|
|
|
|
### Create and render a report
|
|
|
|
1. Copy an existing file in `reports/`, or start with the
|
|
[minimal boilerplate](docs/examples.md#minimal-report).
|
|
2. Edit the YAML content.
|
|
3. Render it:
|
|
|
|
```bash
|
|
./render.sh reports/my-report.yaml
|
|
```
|
|
|
|
The PDF is written to `build/my-report.pdf`. To render every report recursively:
|
|
|
|
```bash
|
|
./render.sh --all
|
|
```
|
|
|
|
Set the report's purpose explicitly:
|
|
|
|
```yaml
|
|
report_type: technical # Investigation, engineering review, or handoff
|
|
# report_type: briefing # Concise findings for stakeholders
|
|
```
|
|
|
|
See [Report types](docs/writing-reports.md#report-types) for the distinction.
|
|
|
|
Every report must include an author and date, and may select a theme:
|
|
|
|
```yaml
|
|
theme: default # Also available: cic, eridani
|
|
|
|
metadata:
|
|
Date: "2026-09-05"
|
|
Author: "Your Name"
|
|
```
|
|
|
|
Compilation stops with an actionable error if `metadata.Date` or
|
|
`metadata.Author` is absent or empty.
|
|
|
|
### Generate a Windows diagnostics assessment
|
|
|
|
Convert a Full WinDiagnostics text dump into a concise, exception-focused PDF:
|
|
|
|
```bash
|
|
./render-diagnostics.sh diagnostics/windows_system_report_PC.json "Your Name" cic
|
|
```
|
|
|
|
The theme argument is optional and defaults to `default`. Render every `.json`
|
|
dump under `diagnostics/` recursively with:
|
|
|
|
```bash
|
|
./render-diagnostics.sh --all "Your Name"
|
|
```
|
|
|
|
The result is written under `build/diagnostics/`. Its first page is a short
|
|
health summary; later pages deduplicate errors, retain useful evidence, and
|
|
record how every collected section was treated without reproducing large lists
|
|
of healthy inventory. See [Diagnostics reports](docs/diagnostics.md), including
|
|
the [safe finding-closure guide](docs/diagnostics.md#closing-findings-safely).
|
|
|
|
You can also invoke Typst directly:
|
|
|
|
```bash
|
|
typst compile \
|
|
--input report=reports/my-report.yaml \
|
|
report.typ \
|
|
build/my-report.pdf
|
|
```
|
|
|
|
### Project layout
|
|
|
|
```text
|
|
report.typ Typst entry point
|
|
model.typ Shared layout and YAML renderer
|
|
render.sh Convenience build script
|
|
assets/ Logos and other static assets
|
|
reports/ Authoritative YAML report sources
|
|
build/ Generated PDFs
|
|
docs/ Detailed documentation and examples
|
|
```
|
|
|
|
## Detailed guides
|
|
|
|
- [Writing reports](docs/writing-reports.md) — field reference, content blocks,
|
|
report types, status values, and authoring guidance.
|
|
- [Examples and boilerplate](docs/examples.md) — complete minimal and full
|
|
reports ready to copy and adapt.
|
|
- [Advanced setup](docs/advanced-setup.md) — nested archives, customization,
|
|
YAML themes, automation, and Git policy.
|
|
- [Diagnostics reports](docs/diagnostics.md) — WinDiagnostics synthesis,
|
|
filtering policy, usage, safe finding closure, and limitations.
|
|
|
|
## Core principle
|
|
|
|
YAML files are the authoritative report sources. Keep content and report state
|
|
in YAML, and keep visual presentation in `model.typ`. For example, prefer
|
|
`severity: high` over fields that specify colors or fonts.
|
|
|
|
Generated PDFs are reproducible artifacts suitable for email, handoff,
|
|
printing, tickets, and archival. Whether they are committed to Git is a project
|
|
policy; see [Generated PDF policy](docs/advanced-setup.md#generated-pdf-policy).
|
|
|
|
## License
|
|
|
|
See [LICENSE](LICENSE).
|
|
|
|
### Jenkins publication
|
|
|
|
Jenkins renders YAML reports and JSON diagnostics, validates the PDFs, and
|
|
publishes encrypted archives to the same `/mnt/books` mount used by the books:
|
|
|
|
- `/mnt/books/Reports/Reports.zip`: YAML report PDFs.
|
|
- `/mnt/books/Reports/Diagnostics.zip`: diagnostic PDFs, preserving subfolders.
|
|
|
|
Only the ZIPs are archived as Jenkins artifacts. The agent needs `uv` and Python 3, access to PyPI,
|
|
and write access to `/mnt/books/Reports`. `DIAGNOSTICS_AUTHOR` defaults to Beffroi.
|
|
Jenkins installs pinned [pyzipper](https://pypi.org/project/pyzipper/) into `.ci-venv`
|
|
and creates AES-256 ZIPs without a system `zip` executable. Extract with an
|
|
AES-capable ZIP reader, such as 7-Zip.
|
|
Jenkins binds the **Secret text** credential `typst-reporter-publish-password`
|
|
to `REPORT_ZIP_PASSWORD` only during the packaging stage. The credential must be
|
|
accessible to this job. The packaging script requires a nonempty password and
|
|
reads it from the environment with shell tracing disabled; there is no fallback
|
|
password. The next successful publication replaces both ZIPs using this secret.
|
|
|
|
To package an existing local build:
|
|
|
|
```bash
|
|
uv venv --allow-existing .ci-venv
|
|
uv pip install --python .ci-venv/bin/python -r tools/packaging-requirements.txt
|
|
# Prompt without echoing the password or storing it in shell history.
|
|
set +x
|
|
read -r -s -p 'Archive password: ' REPORT_ZIP_PASSWORD
|
|
printf '\n'
|
|
export REPORT_ZIP_PASSWORD
|
|
PACKAGING_PYTHON=.ci-venv/bin/python ./tools/package-reports.sh
|
|
unset REPORT_ZIP_PASSWORD
|
|
```
|