This repository has been archived on 2026-09-16. You can view files and clone it, but cannot push or open issues or pull requests.
typst_reporter/README.md

169 lines
5.6 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
```
Subfolders are preserved: `reports/customer/report.yaml` produces
`build/customer/report.pdf`, including in ZIP exports. `build/diagnostics/`
is reserved for diagnostic PDFs.
Remove old PDFs before regenerating all reports:
```bash
./render.sh --clean --all
./render-diagnostics.sh --clean --all "Your Name"
```
Each command cleans only its own report category. With a single input,
`--clean` removes only that input's PDF. Other files are retained.
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 WinDiagnostics schema 1 or 2 JSON capture 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
modules/ Shared Typst layouts and diagnostics normalization
render.sh Convenience build script
config/ Shared YAML themes, diagnostics rules, and watchlist
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 `modules/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, preserving subfolders.
- `/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
```