diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md
index 5108efd..b799005 100644
--- a/AGENTS-TASKS.md
+++ b/AGENTS-TASKS.md
@@ -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.
diff --git a/Jenkinsfile b/Jenkinsfile
index 99e3356..ac93af4 100644
--- a/Jenkinsfile
+++ b/Jenkinsfile
@@ -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.
*
diff --git a/README.md b/README.md
index 614a11c..54afc1a 100644
--- a/README.md
+++ b/README.md
@@ -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
diff --git a/docs/report-contract.md b/docs/report-contract.md
index 410b18e..35d16e9 100644
--- a/docs/report-contract.md
+++ b/docs/report-contract.md
@@ -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
diff --git a/templates/report.typ b/templates/report.typ
new file mode 100644
index 0000000..eabeb36
--- /dev/null
+++ b/templates/report.typ
@@ -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) }
+}
diff --git a/tests/test_render.py b/tests/test_render.py
new file mode 100644
index 0000000..3a10f25
--- /dev/null
+++ b/tests/test_render.py
@@ -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(
+ '', 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('', 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()
diff --git a/tools/render.py b/tools/render.py
new file mode 100644
index 0000000..b732ccd
--- /dev/null
+++ b/tools/render.py
@@ -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())