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

121 lines
3.5 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.txt "Your Name" cic
```
The theme argument is optional and defaults to `default`. Render every `.txt`
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).