Corporate reporting with typist
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.
Go to file
Dandaedre 1d381904ff
Beffroi/typst_reporter/pipeline/head This commit looks good Details
Report CI typst_reporter passed all CI checks.
Vky/typst_reporter/pipeline/head This commit looks good Details
New model
2026-09-15 14:11:13 +02:00
assets New model 2026-09-15 14:11:13 +02:00
config Organize configs and modules and support nested report exports 2026-09-15 14:10:26 +02:00
diagnostics New diagnostics & analysis 2026-09-15 12:20:13 +02:00
docs Organize configs and modules and support nested report exports 2026-09-15 14:10:26 +02:00
modules New model 2026-09-15 14:11:13 +02:00
reports Step done 2026-09-15 11:10:38 +02:00
tools Organize configs and modules and support nested report exports 2026-09-15 14:10:26 +02:00
.gitignore Fix Jenkins ZIP packaging with uv-managed AES dependencies 2026-09-14 19:07:27 +02:00
Jenkinsfile Organize configs and modules and support nested report exports 2026-09-15 14:10:26 +02:00
LICENSE Initial commit 2026-09-05 18:21:45 +02:00
README.md Organize configs and modules and support nested report exports 2026-09-15 14:10:26 +02:00
diagnostics.typ Organize configs and modules and support nested report exports 2026-09-15 14:10:26 +02:00
render-diagnostics.sh Organize configs and modules and support nested report exports 2026-09-15 14:10:26 +02:00
render.sh Organize configs and modules and support nested report exports 2026-09-15 14:10:26 +02:00
report.typ Organize configs and modules and support nested report exports 2026-09-15 14:10:26 +02:00

README.md

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 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.
  2. Edit the YAML content.
  3. Render it:
./render.sh reports/my-report.yaml

The PDF is written to build/my-report.pdf. To render every report recursively:

./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:

./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:

report_type: technical # Investigation, engineering review, or handoff
# report_type: briefing  # Concise findings for stakeholders

See Report types for the distinction.

Every report must include an author and date, and may select a theme:

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:

./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:

./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, including the safe finding-closure guide.

You can also invoke Typst directly:

typst compile \
  --input report=reports/my-report.yaml \
  report.typ \
  build/my-report.pdf

Project layout

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 — field reference, content blocks, report types, status values, and authoring guidance.
  • Examples and boilerplate — complete minimal and full reports ready to copy and adapt.
  • Advanced setup — nested archives, customization, YAML themes, automation, and Git policy.
  • Diagnostics reports — 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.

License

See 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 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:

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