10 KiB
Reportist migration tracker
Follow AGENT.md. Reportist owns generic structured report validation and Typst/PDF rendering. Diagnostic interpretation, incident history, report conclusions, and Beffroi identity belong outside this repository.
Tracking rules
[x] means completed and verified; [ ] means work remains. Keep task IDs
stable. After each pass, update this checklist and append a handoff recording
changes, validation commands/results, limitations, and the next task. Check off
implementation only after its acceptance criteria pass.
This roadmap must remain usable from a standalone checkout. Legacy repositories are migration sources, not runtime dependencies. Coordinate public contracts with consumers; keep implementation and tests in their owning repository.
Initial planning baseline — 2026-09-15
Only instructions, README, license, ignore rules, and Jenkins scaffolding are
tracked. No renderer, report schema, synthetic examples, or rendering tests have
been migrated. Legacy typst_reporter mixes reusable layout with diagnostics
and organisation-specific content, so files must be classified before extraction.
Pass 0 — Inventory and visual baselines
- RT0.1 Read repository instructions and inspect tracked files, README, and Jenkins scaffold.
- RT0.2 Create this phased tracker and link it and the instructions from the README.
- RT0.3 Inventory legacy
report.typ, rendering wrappers, models, themes, validation, and content blocks; record source revisions, licenses, fonts, Typst requirements, and CLI behavior. - RT0.4 Classify reusable layout separately from diagnostics normalization/rules, hard-coded identity/assets, and real report content. Record destinations before copying anything.
- RT0.5 Create synthetic representative reports and capture legacy visual/behavior baselines, including headings, tables, findings, actions, appendices, and page breaks where supported.
Exit: the first extraction slice has a reusable feature inventory and observable visual baseline without importing private reports into generic fixtures.
Pass 1 — Public report contract
Depends on Pass 0 for the selected slice.
- RT1.1 Define
schema/report.schema.jsonwith explicit schema version, required/optional fields, metadata, branding, and generic report content; preserve useful legacy compatibility deliberately. - RT1.2 Map existing report fields and diagnostics presentation needs to generic content structures; keep evidence interpretation outside the renderer.
- RT1.3 Define external asset resolution, theme overrides, missing branding behavior, and neutral defaults without organisation-specific names, authors, logos, or incident terminology.
- 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.
Exit: unrelated callers can author valid reports without knowing internal Typst modules or using a diagnostic/reporting repository.
Pass 2 — Generic rendering slice
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.yamlusing 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 sources, diagnostic code, real incidents, or hard-coded Beffroi identity.
Pass 3 — Validation and presentation coverage
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.
- 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.
Exit: the required rendering behaviors are covered by synthetic tests and visual review, with no private source material in examples.
Pass 4 — Standalone delivery and integration handoff
Depends on validated rendering.
- 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.
- 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 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 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.
- Validation: documentation links, task IDs, and whitespace checked; renderer tests were not run because no implementation exists yet.
- Open: detailed source classification, synthetic examples, and baseline PDFs.
- Next: RT0.3–RT0.5, then define the first RT1 schema/CLI slice.
2026-09-15 — Inventory and executable baseline pass
- Completed RT0.3–RT0.5 for the initial rendering slice: source/function inventory, draft field mapping, and two synthetic legacy report examples with retained MIT notice.
- Evidence: migration inventory,
tests/fixtures/legacy/. - Validation: macro baseline command rendered both report PDFs and rejected missing author/date and unknown theme. Reviewed the technical report first page; later-page/long-content/alternate-branding coverage remains open.
- Existing Beffroi logo coupling remains visible in legacy output. No generic renderer implementation or public schema is claimed yet.
- Next: RT1 schema/validation fixtures, then RT2 generic rendering extraction.
2026-09-15 — Versioned contract pass
- Completed RT1.1–RT1.4: generic report v1 schema, YAML/JSON validator and paired synthetic examples, optional branding/path contract, generic blocks, and version/legacy mapping documentation.
- Evidence: report contract,
schema/report.schema.json,tools/validate.py,examples/,tests/test_contract.py. - Validation: eight unittest cases with many invalid-input subcases passed on Python 3.11 and 3.14, including an isolated standalone copy. Covers YAML/JSON parity, minimal reports, invalid dates/versions, duplicate keys, generic branding shape, nested blocks and parser errors.
- Jenkins now runs the contract tests. Rendering, actual asset loading and visual branding are not implemented or validated by these schema tests.
- Next: finish RT1.5 exact rendering command/output behavior, then RT2 extraction. No render command is claimed yet.