83 lines
5.7 KiB
Markdown
83 lines
5.7 KiB
Markdown
# 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 and branding shape
|
|
checks are now implemented; see [report contract](report-contract.md). Rendering,
|
|
asset loading, and actual branding/layout behavior remain unimplemented.
|
|
|
|
## 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 macro migration runner renders these from pinned temporary legacy sources
|
|
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.
|