test: verify standalone report rendering

This commit is contained in:
Dandaedre 2026-09-15 23:02:51 +02:00
parent 091dfd7c5b
commit 3356f3ea0b
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
6 changed files with 107 additions and 37 deletions

View File

@ -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

12
Jenkinsfile vendored
View File

@ -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'
)

View File

@ -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

View File

@ -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.

View File

@ -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

View File

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