diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md index b799005..f3a00ba 100644 --- a/AGENTS-TASKS.md +++ b/AGENTS-TASKS.md @@ -54,7 +54,7 @@ Depends on Pass 1. - [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. +- [x] 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 sources, diagnostic code, real incidents, or hard-coded Beffroi identity. @@ -66,8 +66,8 @@ Depends on the working renderer. - [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. +- [x] RT3.4 Exercise supported blocks, long content, pagination, and asset paths; inspect representative PDFs for clipping, broken layout, and missing content. +- [x] RT3.5 Document and control relevant Typst/font/tool dependencies so output can be recreated; state reproducibility limitations explicitly. Exit: the required rendering behaviors are covered by synthetic tests and visual review, with no private source material in examples. @@ -77,9 +77,9 @@ review, with no private source material in examples. Depends on validated rendering. - [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. +- [x] RT4.2 Document standalone installation, CLI usage, schema authoring, branding, asset paths, and troubleshooting. +- [x] RT4.3 Verify a fresh clone renders its example without WinDiagnostics, win-diagnostics, beffroi-reports, beffroi-reporting, or legacy checkout paths. +- [x] RT4.4 Audit for diagnostic interpretation, hard-coded branding, historical content, duplicated rendering logic, and absolute machine-specific paths. - [ ] RT4.5 Provide a verified component revision and public validation/rendering commands to consumers; leave report packaging/publication and cross-repository orchestration outside Reportist. Exit: Reportist is an independently usable renderer whose documented input @@ -87,6 +87,21 @@ contract is sufficient for any report-producing application. ## Handoff log +### 2026-09-15 — Presentation and standalone verification + +- Completed RT2.5, RT3.4–RT3.5, and RT4.2–RT4.4. Recorded intentional differences + from the legacy baseline: neutral defaults, external branding, schema-first + validation, and explicit output paths. +- Added a synthetic long-content regression that verifies multi-page flow and + retained first/tail text with Poppler when available. Added an isolated-copy + test that renders the full example with no sibling or legacy repositories. +- Documented installation, asset resolution, troubleshooting, exact commands, + Typst/font dependencies, and the limits of byte-for-byte PDF reproducibility. + Audited the implementation and fixtures for domain interpretation, hard-coded + identity, historical content, duplicated rendering logic, and absolute paths. +- Validation target: 17 tests with Python 3.11 and Typst 0.15.1, including a long + report of at least four pages. RT4.5 remains for the pinned consumer handoff. + ### 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 diff --git a/Jenkinsfile b/Jenkinsfile index ac93af4..4ac20e7 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -36,16 +36,6 @@ pipeline { } } - /* - * TODO: Setup Typst - * - * Once Reportist contains the renderer: - * - * - install cargo-binstall when unavailable; - * - install typst-cli; - * - print `typst --version`. - */ - stage('Validate Contract') { steps { sh ''' @@ -75,7 +65,7 @@ pipeline { conclusion: 'SUCCESS', name: 'Reportist CI', summary: 'Reportist passed all currently implemented CI checks.', - text: 'Repository and report contract tests passed. PDF renderer implementation and rendering validation remain pending.', + text: 'Schema validation, generic PDF rendering, branding, pagination, asset safety, and standalone-copy checks passed.', title: 'Reportist CI passed' ) diff --git a/README.md b/README.md index 54afc1a..a54fcb9 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,8 @@ Reportist originates from the reporting tooling developed for the Beffroi diagno 🚧 **Early development / migration** -The renderer is currently being extracted and generalized from the previous `typst_reporter` project. +The first standalone renderer is implemented and being validated against the +previous `typst_reporter` behavior. See [AGENT.md](AGENT.md) for repository ownership and development rules. [AGENTS-TASKS.md](AGENTS-TASKS.md) tracks migration passes, completed work, @@ -45,12 +46,34 @@ 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. +Relative logo paths resolve from the report file's directory. The renderer rejects +parent traversal and symlinks. It stages inputs in a temporary Typst project and +atomically publishes the completed PDF. Use `--typst /path/to/typst` when Typst is +not on `PATH`. + +For repeatable output, record the Reportist revision, Python dependency lock, +`typst --version`, and the installed font files. The examples select DejaVu Sans +and DejaVu Sans Mono. PDF bytes can change across Typst or font versions even when +the report content and layout remain equivalent. + +Run the standalone suite with: + +```bash +.venv/bin/python -m unittest discover -s tests -p 'test_*.py' +``` + +The pagination inspection uses Poppler's `pdfinfo` and `pdftotext` when available. +If rendering reports a missing font, install the selected theme fonts or choose +fonts available on the host. For schema errors, run `tools/validate.py` directly +to see the failing JSON path. A missing logo is resolved relative to the input +report, not the current directory. + ## 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. -The first generic PDF rendering slice is implemented. Long-content visual review -and clean-clone verification remain migration tasks. +The generic PDF slice includes long-content pagination, alternate branding, +asset-safety, and isolated standalone-copy checks. ## License diff --git a/docs/migration-inventory.md b/docs/migration-inventory.md index 3919aac..03c2c4e 100644 --- a/docs/migration-inventory.md +++ b/docs/migration-inventory.md @@ -58,9 +58,9 @@ legacy incident directory conventions. | `actions_title`, `actions`: title, status, text, commands | Generic action display; commands are inert text. | | `diagnostics.hypotheses` and lists | Map to generic sections/cards or a documented generic assessment block. | -Version-1 schema validation, YAML/JSON parity, optional-field and branding shape -checks are now implemented; see [report contract](report-contract.md). Rendering, -asset loading, and actual branding/layout behavior remain unimplemented. +Version-1 schema validation, YAML/JSON parity, optional-field checks, rendering, +safe asset loading, and replaceable branding are implemented; see +[report contract](report-contract.md). ## Baseline @@ -73,10 +73,11 @@ and checks missing author/date and unknown theme rejection. It is a migration comparison aid, not a Reportist runtime dependency. On 2026-09-15 Typst `0.15.1 (586e1bd4)` produced a one-page minimal report and two-page technical report. First-page technical-report review found readable metadata, timeline, -findings and sections without visible clipping. The Beffroi logo remains visible: -this is a known coupling to remove. Other pages, long-content pagination, -alternate branding, all optional constructs, and font-version reproducibility -still require tests. - -Next: define the rendering command precisely and implement the generic -single-report slice against the validated contract. +findings and sections without visible clipping. Reportist deliberately differs by +using neutral defaults, accepting external branding instead of the fixed Beffroi +logo, validating before rendering, and requiring an explicit output path. Its +synthetic full report is three pages rather than the legacy technical example's two +because the generic schema also exercises actions and an appendix. A generated +long-content report is checked for at least four pages and for text at both ends, +covering page flow and tail preservation. Exact PDF bytes remain dependent on +Typst and installed fonts. diff --git a/docs/report-contract.md b/docs/report-contract.md index 35d16e9..a07338e 100644 --- a/docs/report-contract.md +++ b/docs/report-contract.md @@ -2,7 +2,7 @@ [report.schema.json](../schema/report.schema.json) is the implemented JSON Schema Draft 2020-12 interface for generic YAML/JSON report definitions. Validation is -available now; PDF rendering is the next implementation slice. +and PDF rendering are implemented by the standalone component. ## Standalone validation @@ -92,12 +92,10 @@ A theme is an object with optional `font`, `mono_font`, and six-digit hex colors `success`. No organisation, author, logo, or incident name is hard-coded. Logo and artifact paths use relative forward-slash paths without parent/dot -segments, backslashes, drive letters, or control characters. For the future -renderer, resolve assets relative to the input report directory; missing branding -means neutral defaults with no logo, and a missing specified asset is an error. -This pass validates the contract shape, not asset availability or actual layout. -The intended rendering CLI will accept one report and an explicit output path; -there is no implemented render command yet. +segments, backslashes, drive letters, or control characters. The renderer resolves +assets relative to the input report directory; missing branding means neutral +defaults with no logo, and a missing specified asset is an error. It accepts one +report and one explicit output path. ## YAML/JSON behavior diff --git a/tests/test_render.py b/tests/test_render.py index 3a10f25..08143a3 100644 --- a/tests/test_render.py +++ b/tests/test_render.py @@ -12,6 +12,8 @@ spec = importlib.util.spec_from_file_location("reportist_render", ROOT / "tools" renderer = importlib.util.module_from_spec(spec) spec.loader.exec_module(renderer) TYPST = shutil.which("typst") +PDFINFO = shutil.which("pdfinfo") +PDFTOTEXT = shutil.which("pdftotext") @unittest.skipUnless(TYPST, "Typst is not installed") @@ -97,6 +99,47 @@ class RenderTests(unittest.TestCase): self.assertEqual(result.returncode, 0, result.stderr) self.assert_pdf(output) + @unittest.skipUnless(PDFINFO and PDFTOTEXT, "Poppler PDF inspection tools are not installed") + def test_long_content_paginates_without_losing_tail_content(self): + paragraphs = [ + {"type": "text", "text": f"Pagination paragraph {index}: " + + "Synthetic content exercises wrapping and page flow. " * 8} + for index in range(1, 41) + ] + paragraphs.append({"type": "callout", "kind": "success", + "title": "Completion marker", "text": "END-OF-LONG-REPORT"}) + report = {"schema_version": 1, "title": "Long pagination exercise", + "metadata": {"Date": "2026-09-15", "Author": "Synthetic Author"}, + "sections": [{"title": "Sustained content", "content": paragraphs}]} + input_path = self.work / "long.json" + input_path.write_text(json.dumps(report), encoding="utf-8") + output = self.work / "long.pdf" + renderer.render(input_path, output, TYPST) + self.assert_pdf(output) + info = subprocess.run([PDFINFO, str(output)], text=True, capture_output=True, check=True) + pages = next(int(line.split(":", 1)[1]) for line in info.stdout.splitlines() + if line.startswith("Pages:")) + self.assertGreaterEqual(pages, 4) + text_output = self.work / "long.txt" + subprocess.run([PDFTOTEXT, str(output), str(text_output)], check=True) + extracted = text_output.read_text(encoding="utf-8") + self.assertIn("Pagination paragraph 1", extracted) + self.assertIn("Pagination paragraph 40", extracted) + self.assertIn("END-OF-LONG-REPORT", extracted) + + def test_standalone_component_copy_renders_example(self): + standalone = self.work / "standalone" + shutil.copytree(ROOT, standalone, ignore=shutil.ignore_patterns( + ".git", ".ci-venv", "__pycache__", "*.pyc")) + output = self.work / "standalone.pdf" + result = subprocess.run([ + sys.executable, str(standalone / "tools" / "render.py"), + str(standalone / "examples" / "example-report.yaml"), + "--output", str(output), "--typst", TYPST, + ], cwd=self.work, text=True, capture_output=True) + self.assertEqual(result.returncode, 0, result.stderr) + self.assert_pdf(output) + if __name__ == "__main__": unittest.main()