test: verify standalone report rendering
This commit is contained in:
parent
091dfd7c5b
commit
3356f3ea0b
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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'
|
||||
)
|
||||
|
||||
|
|
|
|||
29
README.md
29
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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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()
|
||||
|
|
|
|||
Loading…
Reference in New Issue