feat: render generic reports to PDF

This commit is contained in:
Dandaedre 2026-09-15 22:32:57 +02:00
parent e2ada627d0
commit 091dfd7c5b
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
7 changed files with 368 additions and 27 deletions

View File

@ -41,7 +41,7 @@ Depends on Pass 0 for the selected slice.
- [x] RT1.2 Map existing report fields and diagnostics presentation needs to generic content structures; keep evidence interpretation outside the renderer.
- [x] RT1.3 Define external asset resolution, theme overrides, missing branding behavior, and neutral defaults without organisation-specific names, authors, logos, or incident terminology.
- [x] RT1.4 Specify YAML/JSON validation errors, unsupported schema handling, and schema evolution/migration policy.
- [ ] RT1.5 Define a simple CLI with explicit input and output paths, documented exit codes, and installation requirements; publish synthetic valid/invalid examples.
- [x] RT1.5 Define a simple CLI with explicit input and output paths, documented exit codes, and installation requirements; publish synthetic valid/invalid examples.
Exit: unrelated callers can author valid reports without knowing internal Typst
modules or using a diagnostic/reporting repository.
@ -50,10 +50,10 @@ modules or using a diagnostic/reporting repository.
Depends on Pass 1.
- [ ] RT2.1 Extract generic templates/components and styling, retaining the sober visual style while supplying identity and domain labels through input data.
- [ ] RT2.2 Implement schema validation before rendering with actionable errors.
- [ ] RT2.3 Implement the YAML/JSON-to-Typst-to-PDF CLI; document output behavior and support invocation outside the repository working directory.
- [ ] RT2.4 Add `examples/example-report.yaml` using synthetic content and generic assets; exercise the first supported content blocks.
- [x] RT2.1 Extract generic templates/components and styling, retaining the sober visual style while supplying identity and domain labels through input data.
- [x] RT2.2 Implement schema validation before rendering with actionable errors.
- [x] RT2.3 Implement the YAML/JSON-to-Typst-to-PDF CLI; document output behavior and support invocation outside the repository working directory.
- [x] RT2.4 Add `examples/example-report.yaml` using synthetic content and generic assets; exercise the first supported content blocks.
- [ ] RT2.5 Compare output with the baseline and record intentional visual or compatibility changes; add remaining reusable constructs in bounded slices.
Exit: a documented generic example renders through the public CLI without legacy
@ -63,9 +63,9 @@ sources, diagnostic code, real incidents, or hard-coded Beffroi identity.
Depends on the working renderer.
- [ ] RT3.1 Test successful rendering of valid YAML and JSON reports and rejection of malformed input or unsupported schema versions.
- [ ] RT3.2 Test that omitted optional fields render successfully and missing required fields produce clear errors.
- [ ] RT3.3 Test replaceable branding with unrelated synthetic identities and verify neutral defaults.
- [x] RT3.1 Test successful rendering of valid YAML and JSON reports and rejection of malformed input or unsupported schema versions.
- [x] RT3.2 Test that omitted optional fields render successfully and missing required fields produce clear errors.
- [x] RT3.3 Test replaceable branding with unrelated synthetic identities and verify neutral defaults.
- [ ] RT3.4 Exercise supported blocks, long content, pagination, and asset paths; inspect representative PDFs for clipping, broken layout, and missing content.
- [ ] RT3.5 Document and control relevant Typst/font/tool dependencies so output can be recreated; state reproducibility limitations explicitly.
@ -76,7 +76,7 @@ review, with no private source material in examples.
Depends on validated rendering.
- [ ] RT4.1 Enable schema, example rendering, and regression checks in Jenkins; report actual validation coverage and tool versions.
- [x] RT4.1 Enable schema, example rendering, and regression checks in Jenkins; report actual validation coverage and tool versions.
- [ ] RT4.2 Document standalone installation, CLI usage, schema authoring, branding, asset paths, and troubleshooting.
- [ ] RT4.3 Verify a fresh clone renders its example without WinDiagnostics, win-diagnostics, beffroi-reports, beffroi-reporting, or legacy checkout paths.
- [ ] RT4.4 Audit for diagnostic interpretation, hard-coded branding, historical content, duplicated rendering logic, and absolute machine-specific paths.
@ -87,6 +87,25 @@ contract is sufficient for any report-producing application.
## Handoff log
### 2026-09-15 — First standalone generic renderer
- Completed RT1.5, RT2.1–RT2.4 and RT3.1–RT3.3 with a schema-first Python CLI
and generic Typst template. YAML/JSON reports render from any working directory;
identity, logo and colors are supplied only through report data.
- Rendering stages the validated input and logo in a temporary Typst root, rejects
symlinks/traversal, and publishes a complete PDF atomically. Existing outputs
require `--force`; input files can never be output targets.
- Added seven rendering tests covering YAML/JSON, minimal input, invalid reports,
neutral defaults, unrelated branding/logo, output protection and asset safety.
- Validation: all eight contract and seven rendering tests pass with Python 3.11.14
and Typst 0.15.1. The full example produces a readable three-page A4 PDF and
the minimal example produces one page; extracted text contains expected content.
- Limits: RT2.5 visual baseline comparison, long-content/pagination review and
clean standalone clone verification remain open.
- Jenkins now requires Typst, prints its version and runs schema plus rendering
tests. Next: compare representative pages with the preserved baseline, then
extend pagination and asset coverage.
### 2026-09-15 — Planning pass
- Completed RT0.1–RT0.2; added roadmap and README navigation.

19
Jenkinsfile vendored
View File

@ -54,28 +54,13 @@ pipeline {
uv venv --python 3.11 --allow-existing .ci-venv
uv pip sync --python .ci-venv/bin/python requirements.txt
.ci-venv/bin/python --version
command -v typst >/dev/null 2>&1 || { echo "Typst is required for renderer tests" >&2; exit 1; }
typst --version
.ci-venv/bin/python -m unittest discover -s tests -p 'test_*.py'
'''
}
}
/*
* TODO: Render Example
*
* Once the renderer exists:
*
* reportist examples/example-report.yaml
*
* or the equivalent render.sh invocation.
*/
/*
* TODO: Regression Tests
*
* Render synthetic fixtures and verify that all supported
* report constructs compile successfully.
*/
/*
* No deployment stage is currently intended.
*

View File

@ -26,11 +26,31 @@ See [AGENT.md](AGENT.md) for repository ownership and development rules.
[AGENTS-TASKS.md](AGENTS-TASKS.md) tracks migration passes, completed work,
acceptance criteria, and the next-pass handoff.
## Render a report
Requirements: Python 3.11+, the pinned packages in `requirements.txt`, Typst
0.15 or newer, and the fonts selected by the report. The examples use DejaVu
Sans and DejaVu Sans Mono.
```bash
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python tools/render.py examples/example-report.yaml \
--output output/example-report.pdf
```
The CLI validates before rendering and works from outside the repository. It
refuses an existing output unless `--force` is explicit. Exit 0 means a PDF was
published, 1 means input, validation, asset, Typst, or I/O failure, and 2 means
invalid CLI usage. Branding and logo paths come from report data; reports without
branding use neutral colors and no logo.
## Contract validation
The version-1 schema, standalone validator, and synthetic examples are available.
See [contract documentation](docs/report-contract.md) for setup and validation commands.
Collection/analysis and PDF rendering are still separate migration tasks.
The first generic PDF rendering slice is implemented. Long-content visual review
and clean-clone verification remain migration tasks.
## License

View File

@ -23,6 +23,25 @@ from any working directory using explicit paths. It writes no files. Exit codes:
0 valid, 1 invalid/unreadable input or missing dependencies, 2 CLI usage error.
Errors identify the offending JSON path; unsupported file extensions are rejected.
## Rendering CLI
After installing Typst and the Python requirements:
```bash
python tools/render.py examples/example-report.yaml --output output/report.pdf
```
Validation always runs before Typst. Relative branding assets resolve from the
input report directory and are staged with the report; traversal and symlinks are
rejected. Rendering occurs in a temporary project and publishes the completed PDF
only after Typst succeeds. Existing output requires `--force`. The command is
independent of the caller's working directory.
Exit codes are 0 for a published PDF, 1 for data, validation, asset, rendering or
I/O failure, and 2 for invalid invocation. Typst 0.15+, Python 3.11+, PyYAML,
jsonschema, and selected fonts are external dependencies. PDF bytes can vary with
Typst and font versions; record them when historical reproduction matters.
## Required and optional content
Only `schema_version: 1`, nonblank `title`, and `metadata` containing nonblank

106
templates/report.typ Normal file
View File

@ -0,0 +1,106 @@
#let report-file = sys.inputs.at("report")
#let report-format = sys.inputs.at("format")
#let report = if report-format == "json" { json(report-file) } else { yaml(report-file) }
#let get(data, key, default: none) = data.at(key, default: default)
#let branding = get(report, "branding", default: (:))
#let theme = get(branding, "theme", default: (:))
#let color(key, fallback) = rgb(str(get(theme, key, default: fallback)))
#let ink = color("ink", "#22262b")
#let muted = color("muted", "#66707a")
#let line-color = color("line", "#d7dce1")
#let soft = color("paper_soft", "#f5f7f8")
#let accent = color("accent", "#34495e")
#let severity-color(value) = if value == "critical" { color("critical", "#7a3030")
} else if value in ("warning", "high", "medium") { color("warning", "#8a671c")
} else if value in ("ok", "success") { color("success", "#356344")
} else { color("info", "#385f7a") }
#let as-text(value) = str(value)
#let heading(title) = block(above: 12pt, below: 5pt)[
#text(size: 13pt, weight: "bold", fill: accent)[#as-text(title)]
#line(length: 100%, stroke: 0.6pt + line-color)
]
#let badge(value) = box(inset: (x: 5pt, y: 2pt), radius: 2pt,
fill: severity-color(str(value)).lighten(85%),
stroke: 0.5pt + severity-color(str(value)))[
#text(size: 7.5pt, weight: "bold", fill: severity-color(str(value)))[#as-text(value)]
]
#let callout(body, kind: "info", title: none) = block(width: 100%, inset: 8pt,
fill: severity-color(kind).lighten(92%), stroke: (left: 2pt + severity-color(kind)))[
#if title != none { text(weight: "bold", fill: severity-color(kind))[#as-text(title)]; parbreak() }
#body
]
#let render-block(item) = {
let kind = get(item, "type", default: "text")
if kind == "text" { [#as-text(get(item, "text", default: ""))] }
else if kind == "bullets" { list(..get(item, "items", default: ()).map(value => [#as-text(value)])) }
else if kind == "steps" { enum(..get(item, "items", default: ()).map(value => [#as-text(value)])) }
else if kind == "callout" { callout([#as-text(get(item, "text", default: ""))],
kind: get(item, "kind", default: "info"), title: get(item, "title", default: none)) }
else if kind == "code" { block(width: 100%, inset: 7pt, fill: soft,
stroke: 0.5pt + line-color)[#text(font: get(theme, "mono_font", default: "DejaVu Sans Mono"),
size: 8pt)[#as-text(get(item, "text", default: ""))]] }
else if kind == "subsection" {
block(above: 5pt, below: 3pt)[#text(weight: "bold", fill: ink)[#as-text(get(item, "title", default: ""))]]
for child in get(item, "content", default: ()) { render-block(child); v(3pt) }
}
}
#let logo = get(branding, "logo", default: none)
#let organization = get(branding, "organization", default: "Report")
#set page(paper: "a4", margin: (top: 20mm, bottom: 18mm, x: 20mm),
header: context {
grid(columns: (1fr, auto), align: (left, right + horizon),
text(size: 7.5pt, weight: "bold", fill: muted)[#as-text(organization)],
if logo != none { image(logo, height: 8mm, fit: "contain") })
v(3pt); line(length: 100%, stroke: 0.5pt + line-color)
},
footer: context grid(columns: (1fr, auto),
text(size: 7pt, fill: muted)[#if "id" in report { [Report #as-text(report.id)] }],
text(size: 7pt, fill: muted)[Page #counter(page).display()]))
#set text(font: get(theme, "font", default: "DejaVu Sans"), size: 9.5pt, fill: ink)
#set par(leading: 0.58em, spacing: 0.55em)
#text(size: 22pt, weight: "bold", fill: accent)[#as-text(report.title)]
#if "subtitle" in report { v(3pt); text(size: 11pt, fill: muted)[#as-text(report.subtitle)] }
#if "report_type" in report or "status" in report or "severity" in report {
v(7pt)
for value in (get(report, "report_type"), get(report, "status"), get(report, "severity")) {
if value != none { badge(value); h(4pt) }
}
}
#v(10pt)
#block(width: 100%, inset: 8pt, fill: soft, stroke: 0.5pt + line-color)[
#grid(columns: (1fr, 1fr), row-gutter: 5pt, column-gutter: 10pt,
..report.metadata.pairs().map(pair => [#text(size: 7.5pt, fill: muted)[#pair.at(0)]\
#as-text(pair.at(1))]))
]
#if "summary" in report { heading("Executive summary"); callout([#as-text(report.summary)]) }
#if "timeline" in report and report.timeline.len() > 0 {
heading("Timeline")
for entry in report.timeline { block(below: 5pt)[#text(weight: "bold", fill: accent)[#as-text(entry.time)]
#h(6pt)#as-text(entry.event)#if "notes" in entry { [ — #as-text(entry.notes)] }] }
}
#if "findings" in report and report.findings.len() > 0 {
heading("Findings")
for finding in report.findings { block(width: 100%, inset: 8pt, below: 6pt,
stroke: 0.5pt + line-color, radius: 2pt)[
#text(weight: "bold")[#as-text(finding.title)] #if "severity" in finding { h(5pt); badge(finding.severity) }
#if "evidence" in finding { parbreak(); text(size: 8pt, fill: muted)[Evidence]; parbreak(); as-text(finding.evidence) }
#if "assessment" in finding { parbreak(); text(size: 8pt, fill: muted)[Assessment]; parbreak(); as-text(finding.assessment) }
] }
}
#for section in get(report, "sections", default: ()) {
heading(section.title)
for item in section.content { render-block(item); v(4pt) }
}
#if "actions" in report and report.actions.len() > 0 {
heading(get(report, "actions_title", default: "Action plan"))
for action in report.actions { block(below: 5pt)[#text(weight: "bold")[#as-text(action.title)]
#if "status" in action { h(5pt); badge(action.status) }
#if "text" in action { parbreak(); as-text(action.text) }
#for command in get(action, "commands", default: ()) { parbreak(); render-block((type: "code", text: command)) }] }
}
#if "closing" in report { heading("Current state"); callout([#as-text(report.closing)], title: "Stopping point") }
#for section in get(report, "appendices", default: ()) {
pagebreak(weak: true); heading(section.title)
for item in section.content { render-block(item); v(4pt) }
}

102
tests/test_render.py Normal file
View File

@ -0,0 +1,102 @@
import importlib.util
import json
from pathlib import Path
import shutil
import subprocess
import sys
import tempfile
import unittest
ROOT = Path(__file__).resolve().parents[1]
spec = importlib.util.spec_from_file_location("reportist_render", ROOT / "tools" / "render.py")
renderer = importlib.util.module_from_spec(spec)
spec.loader.exec_module(renderer)
TYPST = shutil.which("typst")
@unittest.skipUnless(TYPST, "Typst is not installed")
class RenderTests(unittest.TestCase):
def setUp(self):
self.temporary = tempfile.TemporaryDirectory()
self.work = Path(self.temporary.name)
def tearDown(self):
self.temporary.cleanup()
def assert_pdf(self, path):
self.assertTrue(path.read_bytes().startswith(b"%PDF-"))
self.assertGreater(path.stat().st_size, 1000)
def test_yaml_and_json_examples_render(self):
for example in ("example-report.yaml", "example-report.json"):
with self.subTest(example=example):
output = self.work / f"{example}.pdf"
renderer.render(ROOT / "examples" / example, output, TYPST)
self.assert_pdf(output)
def test_minimal_report_renders_without_optional_fields(self):
output = self.work / "minimal.pdf"
renderer.render(ROOT / "examples" / "minimal-report.json", output, TYPST)
self.assert_pdf(output)
def test_invalid_input_leaves_no_pdf(self):
report = self.work / "invalid.json"
report.write_text(json.dumps({"schema_version": 2}), encoding="utf-8")
output = self.work / "invalid.pdf"
with self.assertRaisesRegex(ValueError, "invalid report"):
renderer.render(report, output, TYPST)
self.assertFalse(output.exists())
def test_replaceable_branding_logo_renders(self):
(self.work / "assets").mkdir()
(self.work / "assets" / "logo.svg").write_text(
'<svg xmlns="http://www.w3.org/2000/svg" width="80" height="24">'
'<rect width="80" height="24" fill="#663399"/></svg>', encoding="utf-8")
report = {"schema_version": 1, "title": "Alternate Brand", "metadata": {
"Date": "2026-09-15", "Author": "Synthetic Author"}, "branding": {
"organization": "Unrelated Example", "logo": "assets/logo.svg",
"theme": {"accent": "#663399"}}}
input_path = self.work / "brand.json"
input_path.write_text(json.dumps(report), encoding="utf-8")
output = self.work / "brand.pdf"
renderer.render(input_path, output, TYPST)
self.assert_pdf(output)
def test_existing_output_requires_force_and_input_is_never_output(self):
input_path = ROOT / "examples" / "minimal-report.json"
output = self.work / "report.pdf"
output.write_bytes(b"existing")
with self.assertRaisesRegex(ValueError, "output exists"):
renderer.render(input_path, output, TYPST)
self.assertEqual(output.read_bytes(), b"existing")
renderer.render(input_path, output, TYPST, force=True)
self.assert_pdf(output)
with self.assertRaisesRegex(ValueError, "must differ"):
renderer.render(input_path, input_path, TYPST, force=True)
def test_logo_symlink_is_rejected(self):
outside = self.work / "outside.svg"
outside.write_text('<svg xmlns="http://www.w3.org/2000/svg"/>', encoding="utf-8")
report_dir = self.work / "report"
report_dir.mkdir()
(report_dir / "logo.svg").symlink_to(outside)
report = {"schema_version": 1, "title": "Unsafe asset", "metadata": {
"Date": "2026-09-15", "Author": "Synthetic Author"},
"branding": {"logo": "logo.svg"}}
input_path = report_dir / "report.json"
input_path.write_text(json.dumps(report), encoding="utf-8")
with self.assertRaisesRegex(ValueError, "symlinks"):
renderer.render(input_path, self.work / "unsafe.pdf", TYPST)
def test_cli_runs_outside_repository(self):
output = self.work / "outside-cwd.pdf"
result = subprocess.run([
sys.executable, str(ROOT / "tools" / "render.py"),
str(ROOT / "examples" / "minimal-report.json"), "--output", str(output),
], cwd=self.work, text=True, capture_output=True)
self.assertEqual(result.returncode, 0, result.stderr)
self.assert_pdf(output)
if __name__ == "__main__":
unittest.main()

90
tools/render.py Normal file
View File

@ -0,0 +1,90 @@
#!/usr/bin/env python3
"""Validate a Reportist v1 YAML/JSON document and render it to PDF with Typst."""
import argparse
import importlib.util
import json
import os
from pathlib import Path
import shutil
import subprocess
import sys
import tempfile
ROOT = Path(__file__).resolve().parents[1]
spec = importlib.util.spec_from_file_location("reportist_validation", ROOT / "tools" / "validate.py")
validation = importlib.util.module_from_spec(spec)
spec.loader.exec_module(validation)
def stage_asset(report, input_path, staging):
logo = report.get("branding", {}).get("logo")
if not logo:
return
source = input_path.parent
for part in Path(logo).parts:
source = source / part
if source.is_symlink():
raise ValueError(f"/branding/logo: symlinks are not accepted: {logo}")
if not source.resolve().is_relative_to(input_path.parent.resolve()):
raise ValueError(f"/branding/logo: asset escapes the report directory or is a symlink: {logo}")
destination = staging / logo
destination.parent.mkdir(parents=True, exist_ok=True)
shutil.copyfile(source, destination)
def render(input_path, output_path, typst, force=False):
input_path = input_path.resolve()
output_path = output_path.resolve()
if input_path == output_path:
raise ValueError("input and output paths must differ")
if output_path.exists() and not force:
raise ValueError(f"{output_path}: output exists; use --force to replace it")
report = validation.load_report(input_path)
errors = validation.validate_document(report)
if errors:
raise ValueError("invalid report:\n" + "\n".join(errors))
output_path.parent.mkdir(parents=True, exist_ok=True)
with tempfile.TemporaryDirectory(prefix="reportist-") as directory:
staging = Path(directory)
staged_input = staging / ("report.json" if input_path.suffix.lower() == ".json" else "report.yaml")
shutil.copyfile(input_path, staged_input)
shutil.copyfile(ROOT / "templates" / "report.typ", staging / "report.typ")
stage_asset(report, input_path, staging)
staged_pdf = staging / "report.pdf"
command = [typst, "compile", "--root", str(staging), "--input",
f"report={staged_input.name}", "--input",
f"format={input_path.suffix.lower().lstrip('.')}",
str(staging / "report.typ"), str(staged_pdf)]
result = subprocess.run(command, text=True, capture_output=True)
if result.returncode:
raise ValueError("Typst rendering failed:\n" + (result.stderr.strip() or result.stdout.strip()))
if force:
os.replace(staged_pdf, output_path)
else:
os.link(staged_pdf, output_path)
def parser():
result = argparse.ArgumentParser(description=__doc__)
result.add_argument("input", type=Path)
result.add_argument("--output", type=Path, help="PDF path (default: input with .pdf suffix)")
result.add_argument("--typst", default="typst", help="Typst executable (default: typst on PATH)")
result.add_argument("--force", action="store_true", help="Replace an existing output after successful rendering")
return result
def main(argv=None):
args = parser().parse_args(argv)
output = args.output or args.input.with_suffix(".pdf")
try:
render(args.input, output, args.typst, args.force)
except (OSError, ValueError, subprocess.SubprocessError) as error:
print(f"error: {error}", file=sys.stderr)
return 1
print(f"Rendered PDF: {output}")
return 0
if __name__ == "__main__":
sys.exit(main())