reportist/AGENTS-TASKS.md

7.8 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 — 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.