Files
faunosteo/docs/development/CHARACTERIZATION_REPORT.md

95 lines
10 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Characterisation report (plan Step 1)
Status: done 2026-10-08, branch `feature/step-01-characterisation-tests`.
Note 2026-10-10 (Step 5): the legacy suites this report lists were replaced one-to-one
by suites on the canonical sheet (`services.zoneInteraction`, `sheets.provider`,
`state.reportStore`, `pdf.roundtrip`, `components.*`, `routes.EditorRoute`); the
frozen v2 fixtures (`report-v2.*.json`, `report-v2.*.pdf`) remain the oracle of the
v2 → v3 migration.
Scope: a tested photograph of the current application before any SaaS
transformation. No file under `src/`, `public/`, `scripts/`, `docker/` was
changed. Commands run on this host: Node 24.21.0, pnpm 10.13.1 (corepack),
dependencies installed from the lockfile.
## 1. Results
| Command | Result |
|---|---|
| `pnpm test:run` | 39 files, 271 tests green (180 pre-existing + 91 new) |
| `pnpm typecheck` | 0 errors |
| `pnpm lint` | 0 errors, 0 warnings |
| `pnpm build` | OK (chunk-size warning pre-existing) |
## 2. Files added
| File | Cases | Characterises |
|---|---|---|
| `tests/fixtures/report-v2.full.json` | fixture | Golden Report v2 with every zone kind (plain hinge, bilateral both sides, spine with vertebrae, detail-popup), catalog findings with vet flag and side, free text, severity, comment, conclusion, recommendations, dated next appointment. Real `data-anno-id` and catalog paths. |
| `tests/fixtures/report-v2.minimal.json` | fixture | Smallest valid v2 report. |
| `tests/fixtures/README.md` | doc | Fixture contract: never edited to make a test pass. |
| `tests/unit/char.catalog.test.ts` | 13 | `pathologies.json`: byte parity of the two copies, Zod acceptance, schema_version, species, the 26 zone keys in order, `zone.id === key`, 3 categories per zone, root-category id convention with the **known** `sphenoid → ssb-dysfunctions` anomaly, 792 nodes / 612 leaves / depth 3 / 228+384, 41 vet flags all on leaves, 62 `description_fr`, 0 `description_en`, 0 `sources`, sibling-only id uniqueness (26× `anamnesis`, 11× `amplitude-asymmetry`), three `anamnesis` content variants (8/9/9 zones). |
| `tests/unit/char.svgCatalogLink.test.ts` | 18 | Raw attribute census of both SVGs (48/48/18/47/47/18/5/1), five category slugs, 27 distinct ids, `Horse_head.svg` = same drawing + different viewBox, the full 26-row mapping table annotation → catalog zone with score 0 in EN and FR, trigger unmatched, no orphan zone, substring rule unreachable, the two FR pairs inside the fuzzy tolerance (distances 5 and 3), opens-detail ↔ manifest coherence, spine helpers on the real file (region → polygon id, spawn, collect order, detail-sourced exclusion). |
| `tests/unit/char.pathologyEditor.test.ts` | 8 | The inline matcher of `public/pathology-editor.html` evaluated from the file and compared to `zoneMatch.ts` on all 27 annotations + edge labels (LRN-026 parity test), `generateId` slug rules, 76/76 inline translation keys disjoint from the app dictionary, shared `osteo:locale` key, hard-coded `SPECIES_CONFIG` pointing at existing files, zero `src/` imports, noindex, no Zod. |
| `tests/unit/char.clickChain.test.tsx` | 12 | `EditorRoute` through the DOM on the real SVGs: disclaimer once per session (`osteo:disclaimer-shown`), plain toggle add/remove and `data-state="current"`, collapsed-card fallback (click re-activates the last observation and is lost), detail trigger opens the modal and is never a zone, zones clicked in the modal carry `detailSourceId: 'head'`, spine click adds + opens the picker on the right tab and never toggles off, cancel leaves a zone without vertebrae, picker spawns another region and prunes to zero, bilateral left / right / both and "both present → clear both", ✕ removal keeps orphan findings (**known**, BDR-019), one picker per (catalog zone, side) and raw-id badge for the unnamed trigger. |
| `tests/unit/char.pdfFull.test.ts` | 15 | Export of the full fixture: page count, title/author metadata, re-fetch of SVGs and logos at export time, ZONES as bullet rows with `(C3, C4)` / `(Gauche)` suffixes, one `CONSTATS — <ZONE>` section per (zone, side) with snapshot labels and the `(!)` marker, free findings / severity / comment / view captions, conclusion page and header identity on every page, EN variant with identical attachment, deep-equal roundtrip, attachment dictionaries (`/F (osteo-report.json)`, `/AFRelationship /Data`, `/Desc` UTF-16 "Faunosteo state v2", `/Subtype /application#2Fjson`, Flate), pdf-lib 1.17.1 has no `getAttachments` so the traversal is the production path, `incompatible_version` with `foundVersion 3`, foreign attachment and Zod-invalid attachment both reported as `no_attachment` (**known**), orphan finding printed under its zone, unknown ids printed raw. |
| `tests/unit/char.schemaPersistence.test.ts` | 13 | Zod: fixtures accepted unchanged, unknown keys stripped, version literal 2, unbounded vertebra index (C99), French severity enum, orphan findings accepted, unknown species accepted, duplicate boneId with sides / detail. Persistence: full fixture mirrored to and restored from `osteo:draft`, `hydrateReport` does not revalidate, `initReport` shape, `osteo:lastPractitioner`, `osteo:locale`. |
| `tests/unit/char.i18nSpecies.test.tsx` | 12 | Dynamic keys (`severity.*`, `vertebra.region.*`, `home.import.error_*` with `{version}`, `pdf.section.*`/`pdf.view.*`), 71 `svg_editor.*` keys, label fallbacks, registry = equine only with the committed formula, catalog loader species id, `NewReportRoute` select defaults to equine with one option, scaffold script quirks (`schema_version '1.1'`, T13 default). |
Pre-existing tests reused as-is: all 32 files (180 cases). They already
cover: SVG parser rules and counts (`anatomy.*`), zoneMatch on a synthetic
catalog, spineZones on synthetic bones, VertebraPicker, FindingsTreePicker,
schemas, store actions and draft mirror, practitioner cache, locale,
dictionary parity, minimal PDF roundtrip, attachment extraction and the 16 MiB
inflate cap, `buildZoneLabels`, `rasterizeSvg`, UI primitives.
## 3. Behaviours characterised (summary)
- Report: schema acceptance boundary, store init/hydrate, persistence keys, draft restore.
- Anatomy: real SVG attributes and categories, id spaces, parser output, spine region inference and sync on real data.
- Findings: catalog structure, counts, conventions, anomalies, SVG ↔ catalog link table, matcher behaviour and fragile pairs.
- Pathology editor: matcher parity, id generation, translations, config, isolation.
- Click chain: every branch of `onZoneClick` and the three pickers' effect on the store.
- PDF: full export text, pages, attachment format, import error kinds, degradation on missing assets.
- i18n: dynamic keys, fallbacks, dictionary surface tied to legacy tools.
- Special cases: detail trigger, orphan findings, disclaimer flag, unbounded vertebra index, unknown species, foreign attachments.
## 4. Behaviours NOT characterised, and why
| Area | Reason | Where it will be covered |
|---|---|---|
| SVG editor (`SvgEditorRoute.tsx`, 1858 lines) | Vanilla DOM inside a `useEffect`, state in the DOM, drag/mouse geometry depends on `getScreenCTM` which happy-dom does not implement. Testing it would require rewriting it (forbidden in this step). | Replaced by the merged editor (plan Step 17); its operations are listed in audit 03 §2 and become reference tests of the new model. |
| Pathology editor DOM behaviour (tree add/edit/delete, dirty flag, download) | 1700 lines of imperative DOM in an IIFE with no export; only the pure functions were extracted by text. | Merged editor findings panel (Step 17). |
| Real rasterisation (`rasterizeSvg` on the real SVG) | No canvas in happy-dom; a 1×1 PNG stub is used. The existing `pdf.svgToPng` test covers the function with mocks. | Playwright raster hash at the PDF step (Step 6) or later e2e. |
| Visual PDF layout (positions, wrapping, pagination) | Only drawn strings are captured, not coordinates. | PDF golden comparison by extracted text stays; layout is a visual QA item. |
| Vertex-level SVG geometry | `cx/cy/points` are never read by the app; no behaviour to pin. | Importer tests (Step 4) when geometry becomes data. |
| `window.alert` on export failure, download anchor click | Side effects of the route; no value in pinning. | e2e. |
| Browser e2e (real routing, file input import, download) | No Playwright in the repo; adding it is tooling work outside this step. | See §6. |
## 5. Problems discovered (none fixed, by rule)
1. **Host tooling**: this machine had no `pnpm` and no `node_modules`; CLAUDE.md says pnpm is at `~/.local/bin/pnpm`, which does not exist. Node is 24.21.0, not 20. Used `corepack prepare pnpm@10.13.1` (the Dockerfile pin). CLAUDE.md note is stale.
2. **Import error cause lost**: a Zod-invalid attachment and a foreign JSON attachment both surface as `no_attachment` (audit 08 B.2, pinned as known).
3. **ZONES rendering**: the ' · ' joined value is split back into bullet rows by the renderer; harmless, but the dictionary-level `pdf.empty` fallback is printed when an observation has findings but no zone.
4. **Fuzzy tolerance**: the FR pairs fetlock ant./post. and sacral/caudal are inside the Levenshtein threshold (5 ≤ 7, 3 ≤ 4); unreachable today only because EN labels are exact.
5. **Scaffold script** writes `schema_version '1.1'` and a mixed formula (known, script slated for removal).
6. **README** still says 174 tests (actual before this step: 180). Not edited in this step to keep the diff to tests and docs; corrected at Step 2 with the workspace move.
## 6. To cover in a future e2e suite
- Full flow: `/` → `/new` → `/editor` → zones of each kind → findings → export → download → re-import from `/`.
- Session persistence across a real reload (sessionStorage) and language switch mid-edit.
- Detail modal interactions with real pointer events (tooltip hidden on the trigger).
- PDF opened in a viewer: attachment visible, pages readable, raster images present.
- Mobile viewport layout of the editor.
## 7. Known obsolescence
Tests in `char.clickChain.test.tsx` and `char.pdfFull.test.ts` are written
against the current route and export signatures. Plan Step 5 (zone service,
document v3) and Step 6 (PDF v3) will replace them one-to-one; each deleted
test must name its replacement in the commit message (TEST_STRATEGY.md §6).
`char.pathologyEditor.test.ts` and the `svg_editor.*` key count die with the
legacy editors (Step 17). `char.catalog.test.ts` and
`char.svgCatalogLink.test.ts` become the oracle of the legacy importer
(Step 4) and survive as long as the seed files exist.