reportist/docs/migration-inventory.md

5.9 KiB

Historical migration inventory. The diagnostic template described here was retired in favor of the plugin contract in ../README.md.

Renderer inventory and draft contract

Source and ownership

Inspected legacy typst_reporter commit 1d381904fff3d378a7c0e04588e75310a9b7ed60 on 2026-09-15. Software carries an MIT notice, copyright 2026 Beffroi. Synthetic fixtures retain that notice; no Beffroi graphical assets are imported into Reportist.

Source Disposition
report.typ Generic entry point: retain author/date checks; replace fixed theme/logo lookup and add versioned YAML/JSON validation.
modules/model.typ: dict-get, as-content, theme-color, severity-color Generic helpers; report strings must remain inert content.
report-type-label, badge, metadata-line, section-title, subsection-title, callout, code-block Generic presentation; remove organisation-specific defaults.
render-block, render-findings, render-timeline, render-actions Generic structured content; preserve evidence/assessment separation.
confidence-bar, diagnostic-list, render-diagnostics Extract bars/lists/cards; supply domain labels and values as data. Never compute diagnostic confidence here.
report-header, report-footer, report-model Generic layout; remove default Beffroi identity and mandatory logo.
modules/diagnostics-model.typ Split widgets from fixed Windows sections and report assembly. Generic widgets go here, report shaping goes to beffroi-reports.
modules/diagnostics-normalize.typ Excluded: generic interpretation goes to win-diagnostics; display shaping goes to beffroi-reports.
diagnostics.typ, render-diagnostics.sh Excluded as renderer interfaces: replace raw-capture-to-PDF with diagnostic artifact → adapter → report input.
render.sh Reuse single-report CLI behavior; leave incident discovery and category cleaning to orchestration.
config/themes.yaml Generic palette/font defaults and external overrides; organisation choices belong in reports.
Diagnostic rules/watchlist Technical matchers go to diagnostics; report-ready recommendations go to reports.
Real reports, captures, assets beffroi-reports.
Packaging and publication Integration orchestration.
tools/check-diagnostics.typ Mixed synthetic/private analysis tests; do not copy wholesale.

Diagnostic-model helpers are color, get, ink, muted, accent, line-color, soft, severity-color, badge, heading, part-title, panel, metric, header, footer, short-text, finding-target, finding-card, evidence, and diagnostics-model. Extracting widgets does not justify moving the final domain-specific model unchanged.

Existing CLI and dependencies

The Bash wrapper accepts YAML/YML, one path or --all, and optional --clean. It resolves caller/repository paths, preserves subfolders under build/, reserves build/diagnostics/, and fails on missing input/tool or Typst errors. The entry point requires nonblank metadata.Author and metadata.Date, rejects unknown themes, and always supplies /assets/beffroi.png. There is no versioned schema. Defaults use A4, DejaVu Sans and DejaVu Sans Mono. No external Typst packages are imported. The new CLI must accept explicit input/output paths independently of legacy incident directory conventions.

Field mapping for version 1

Existing fields Proposed treatment
No schema version Require an explicit new schema_version; migration adds it deliberately.
title, subtitle, id, report_type Generic identity/purpose; require nonempty title, retain technical/briefing options.
metadata.Date, metadata.Author, extra labels Preserve capitalization and extra display labels; dates remain strings.
organization, theme, fixed logo Explicit branding/configuration with optional logo and neutral defaults; document external asset resolution.
status, severity Supplied display values, never inferred conclusions.
summary, closing Optional supplied prose.
timeline: time, event, notes Optional generic timeline.
findings: title, severity, status, evidence, assessment Preserve evidence and interpretation separately; define stable references.
sections, nested content Preserve text, bullets, steps, callout, code, subsection; reject unknown block types explicitly.
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 checks, rendering, safe asset loading, and replaceable branding are implemented; see report contract.

Baseline

The first two YAML examples from legacy docs/examples.md are copied unchanged to tests/fixtures/legacy/minimal.yaml and technical.yaml. All names, services, organisation, and timestamps are example data. No historical report was copied.

The migration comparison rendered these against the recorded source revision and checked missing author/date and unknown theme rejection. 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. 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.