reportist/AGENTS-TASKS.md

10 KiB
Raw Blame History

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.json with 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.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 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: implementation revision 3356f3e passes 17 tests with Python 3.11.14 and Typst 0.15.1, including a long report of at least four pages. Consumers can use the documented tools/validate.py and tools/render.py commands; packaging, publication, and cross-repository workflows remain outside Reportist.

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.