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())