95 lines
10 KiB
Markdown
95 lines
10 KiB
Markdown
# 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.
|