From cdc0943f35803ed343e399455da4c2122297c664 Mon Sep 17 00:00:00 2001 From: bchanot Date: Sun, 11 Oct 2026 12:30:57 +0200 Subject: [PATCH] =?UTF-8?q?feat(domain):=20archive=20contracts=20=E2=80=94?= =?UTF-8?q?=20sheet=20snapshot=20(lean=20document,=20caps,=20integrity),?= =?UTF-8?q?=20envelope=20v1=20layered=20reader,=20branding=20and=20label?= =?UTF-8?q?=20schemas,=20report=20rebase,=20sheet=20index=20moved=20from?= =?UTF-8?q?=20the=20app;=20bundle=20carries=20asset=20hashes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../2026-10-11-step-06-phase-3-engine.md | 4 +- .../2026-10-11-step-06-phase-4-app.md | 24 + apps/app/scripts/compare-reports.ts | 1 + apps/app/src/services/sheetIndex.ts | 116 +---- apps/app/src/sheets/provider.ts | 8 + apps/app/tests/unit/sheets.provider.test.ts | 30 +- apps/app/vite/sheet-bundle.ts | 9 +- packages/domain/package.json | 3 +- packages/domain/src/anatomical-sheet/index.ts | 1 + .../src/anatomical-sheet/sheet-index.ts | 127 ++++++ packages/domain/src/archive/branding.ts | 51 +++ packages/domain/src/archive/envelope.ts | 172 +++++++ packages/domain/src/archive/index.ts | 4 + packages/domain/src/archive/labels.ts | 57 +++ packages/domain/src/archive/snapshot.ts | 425 ++++++++++++++++++ packages/domain/src/index.ts | 1 + packages/domain/src/report/index.ts | 5 + packages/domain/src/report/rebase.ts | 137 ++++++ .../tests/archive.branding-labels.test.ts | 137 ++++++ .../domain/tests/archive.envelope.test.ts | 211 +++++++++ .../domain/tests/archive.snapshot.test.ts | 366 +++++++++++++++ packages/domain/tests/helpers/draft-sheet.ts | 73 +++ .../domain/tests/helpers/legacy-leaves.ts | 95 ++++ packages/domain/tests/report.rebase.test.ts | 208 +++++++++ packages/domain/tests/sheet-index.test.ts | 104 +++++ 25 files changed, 2253 insertions(+), 116 deletions(-) create mode 100644 .claude/tasks/contracts/2026-10-11-step-06-phase-4-app.md create mode 100644 packages/domain/src/anatomical-sheet/sheet-index.ts create mode 100644 packages/domain/src/archive/branding.ts create mode 100644 packages/domain/src/archive/envelope.ts create mode 100644 packages/domain/src/archive/index.ts create mode 100644 packages/domain/src/archive/labels.ts create mode 100644 packages/domain/src/archive/snapshot.ts create mode 100644 packages/domain/src/report/rebase.ts create mode 100644 packages/domain/tests/archive.branding-labels.test.ts create mode 100644 packages/domain/tests/archive.envelope.test.ts create mode 100644 packages/domain/tests/archive.snapshot.test.ts create mode 100644 packages/domain/tests/helpers/draft-sheet.ts create mode 100644 packages/domain/tests/helpers/legacy-leaves.ts create mode 100644 packages/domain/tests/report.rebase.test.ts create mode 100644 packages/domain/tests/sheet-index.test.ts diff --git a/.claude/tasks/contracts/2026-10-11-step-06-phase-3-engine.md b/.claude/tasks/contracts/2026-10-11-step-06-phase-3-engine.md index 0bb4c082..6e68688e 100644 --- a/.claude/tasks/contracts/2026-10-11-step-06-phase-3-engine.md +++ b/.claude/tasks/contracts/2026-10-11-step-06-phase-3-engine.md @@ -1,6 +1,6 @@ # CONTRACT — step-06 phase 3 engine - date: 2026-10-11 | flow: ship-feature (executor) | branch: feature/step-06-pdf-archives -- status: draft (dispatched after phases 1 and 2 land) +- status: active (phases 1 and 2 landed) - spec: docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md Part II §13 (packages/pdf block), §14 (Export, Label policy, View SVG, Read), §15 (caps, sanitiser, text), §17 (goldens the engine must reproduce), §3.3 ## REQUEST (IMMUTABLE) @@ -12,7 +12,7 @@ Create `packages/pdf` (`@faunosteo/pdf`): the browser-free PDF engine that expor EXPECT: ok 2. Public API of `packages/pdf/src/index.ts` exactly spec §13: `exportReportArchive`, `exportFromEnvelope`, `readReportArchive`, `readAttachedDocument`, `ArchiveReadError` (kinds invalid_pdf | no_attachment | attachment_stripped | incompatible_version), `ArchiveExportError` (kinds snapshot_invalid | snapshot_too_large | sheet_mismatch | too_many_pages), `Rasterizer`, `ExportInput`, `ExportResult`, `ExportWarning`, `PdfLocale`, `defaultPdfLabels`, `PDF_KEYWORD`, `MAX_PDF_BYTES`, `MAX_ATTACHMENT_BYTES`, plus `composeHighlightedViewSvg(sheet: SheetSnapshot, viewId, observation): string` for tests and the app. 3. Export behaviour = spec §14 "Export" steps 1-10 and "Label policy"; branding images: `kind 'png'` → base64 decoded with `atob` → `embedPng`; `kind 'svg'` → sanitised + rasterised at width 1200 (height from its viewBox, same clamp) → `embedPng`; each slot fails alone (`logo_failed` warning); view raster failure → page without image + `view_raster_failed`; parallel rasterisation, sequential embedding in view order; `exportedAt` drives every date; `setKeywords([PDF_KEYWORD])`; envelope attached pretty-printed as `osteo-report.json`, description `Faunosteo report archive v1`. -4. Goldens (T3): `tests/goldens.test.ts` reproduces every Phase 0 golden under `apps/app/tests/fixtures/goldens/step6/` for the three reports (v2full migrated through the draft map, demo, v2unresolved rebuilt with the same recipe as Phase 0 — reuse the recipe by reading `apps/app/tests/helpers/legacyLeaves.ts` logic, copy what you need into `tests/helpers/`), two locales, two logo modes: text entries (page, text, x, y, size, font) identical; images identical; links identical; views facts identical except `titles` (hidden markers are absent in the engine; assert `titles` ≥ highlighted count instead). Logo modes: `nologos` = Branding with every logo null and credits with fallback texts, fake rasterizer returning the 1×1 PNG; `logos` = Branding built from the real `apps/app/public` files (PNG base64, Paws SVG), fake rasterizer returning the 2×1 PNG (same constants as Phase 0). Any mismatch is a visible change: do not "fix" the golden; report it. +4. Goldens (T3): `tests/goldens.test.ts` reproduces every Phase 0 golden under `apps/app/tests/fixtures/goldens/step6/` for the three reports (v2full migrated through the draft map, demo, v2unresolved rebuilt with the same recipe as Phase 0 — reuse the recipe by reading `apps/app/tests/helpers/legacyLeaves.ts` logic, copy what you need into `tests/helpers/`), two locales, two logo modes: text entries (page, text, x, y, size, font) identical; images identical; links identical (Phase 0 recorded images and links PER LOCALE: `images....json`, `links....json`, because the footer centres the powered-by block on the label width); views facts identical except `titles` and `dataAttributes` (hidden markers are absent in the engine and the layer `` loses its `data-layer`/`data-view-id`: assert `titles` ≥ highlighted count and `dataAttributes === 0` instead of the golden's 2). Logo modes: `nologos` = Branding with every logo null and credits with fallback texts, fake rasterizer returning the 1×1 PNG; `logos` = Branding built from the real `apps/app/public` files (PNG base64, Paws SVG), fake rasterizer returning the 2×1 PNG for views AND for the partner SVG (same constants and the same single stub as Phase 0, see `apps/app/tests/helpers/goldens.ts`). Compose through `composeViewSvg` from `@faunosteo/anatomy/render` (generic `root: ComposeElement`, xmldom `Element` satisfies it) with `highlight: { annotationIds, halo: view.kind === 'main' }`. Any mismatch is a visible change: do not "fix" the golden; report it. CHECK: cd packages/pdf && corepack pnpm vitest run tests/goldens.test.ts 2>&1 | tail -3 EXPECT: Tests .* passed 5. T1 no-sheet re-export (`tests/reexport.test.ts`): export demo from a snapshot built with `buildSheetSnapshot` on the draft loaded from `supabase/seed/anatomical-sheets/equine/draft/` → `readReportArchive` → `exportFromEnvelope` → identical text/images/views facts; envelope deep-equal minus `exportedAt`; the test file imports nothing that knows the draft after the first export (the second export receives only the envelope). diff --git a/.claude/tasks/contracts/2026-10-11-step-06-phase-4-app.md b/.claude/tasks/contracts/2026-10-11-step-06-phase-4-app.md new file mode 100644 index 00000000..cee19caf --- /dev/null +++ b/.claude/tasks/contracts/2026-10-11-step-06-phase-4-app.md @@ -0,0 +1,24 @@ +# CONTRACT — step-06 phase 4 app +- date: 2026-10-11 | flow: ship-feature (executor) | branch: feature/step-06-pdf-archives +- status: draft (dispatched after phase 3 lands) +- spec: docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md Part II §14 "App session", "Branding in the app", §16 messages, §17 (T12/T13 kept green), Part I §7 T2/T14/T15 + +## REQUEST (IMMUTABLE) +Wire the application onto `@faunosteo/pdf`: export through the engine with a snapshot, branding and the browser rasterizer; import through the engine with layered reading, kept archive and explicit rebase; new import messages; old PDF code removed; `report:compare` on the engine read API. No visual change to pages or app layout; alerts follow the existing `window.alert` pattern. + +## ACCEPTANCE CRITERIA +1. `apps/app/src/pdf/` contains only: `export.ts` (`exportReportToPdf(report, index, { locale }): Promise` kept as the route-facing signature, implemented as `exportReportArchive({ report, sheet: buildSheetSnapshot(index.sheet, report), branding: await loadBranding(), labels: defaultPdfLabels, locale, rasterizer: browserRasterizer, exportedAt: new Date() })`, warnings → `console.warn`), `import.ts` (`importReportFromPdf(bytes, map)` returning the engine's `ArchiveReadOutcome`; `ImportError` kinds `invalid_pdf | incompatible_version | no_attachment | attachment_stripped` mapped 1:1 from `ArchiveReadError`), `browserRasterizer.ts` (today's `svgToPng.ts` adapted to `(svg, { widthPx, heightPx }) => Promise`: the engine computes the size, the adapter sets width/height on the root and draws), `branding.ts` (`loadBranding(): Promise` per spec §14). `render/`, `attachment.ts`, `fonts.ts`, `src/anatomy/drawing.ts`'s highlight code are deleted; `drawing.ts` keeps `buildViewSvg`/`parseDrawing`/`sanitizeSvg` for the canvas (unchanged behaviour). + CHECK: ls apps/app/src/pdf + EXPECT: branding.ts browserRasterizer.ts export.ts import.ts +2. Store/persistence per spec §14 "App session": `archive: ReportArchiveEnvelope | null` in `ReportStore`, `hydrateImport({ report, archive })`, `initReport`/`reset`/`hydrateReport` clear it, `osteo:archive` key written only on those actions, `restoreDraft(index)` rebases a stale draft and restores the archive; `ArchivePersistence` beside `ReportPersistence`; tests in `state.reportStore.test.ts` extended (archive kept across a draft restore, cleared on new report, not rewritten on edits: spy on setItem). +3. `HomeRoute`: `importReportFromPdf` → `rebaseReportOnSheet(outcome.report, sheet.index, outcome.archive?.sheetSnapshot ?? null)` → `hydrateImport` → one alert composed per spec §16 (lines: migrated / archive_ok / snapshot_rejected with reason label / rebased with count) → `/editor`; error mapping adds `attachment_stripped`. `EditorRoute` export path unchanged for the user (download name, failure alert). The Phase 0 characterisation tests `routes.HomeRoute.import.test.tsx` and `routes.EditorRoute.export.test.tsx` stay green with at most these edits: the mocked outcome objects gain `origin`/`archive` fields, and the export call-shape assertion stays `(report, index, { locale })`. +4. i18n: keys of spec §16 added to fr.ts and en.ts with the given wording; `pdf.*` keys removed from both app dicts (the engine owns them; `severity.*`, `lateral.*`, `footer.*` stay, the UI uses them); `i18n.keys.test.ts` parity green. +5. `scripts/compare-reports.ts` + `scripts/compare/report.ts`: read through `readAttachedDocument` from `@faunosteo/pdf` and `readArchiveDocument` from `@faunosteo/domain/archive`; an envelope prints one extra header line `archive v1 (snapshot kept | snapshot rejected: )` under the same escaping rules; `scripts.compare.test.ts` green. +6. New tests: `pdf.export.app.test.ts` (T2: export the demo fixture through `exportReportToPdf` with the real bundled sheet, then mutate a cloned LoadedSheet's labels and one geometry, re-export the ENVELOPE through `exportFromEnvelope` and assert the engine output facts equal the first export, not the mutated sheet; T13 call shape covered by Phase 0), `pdf.goldens.test.ts` adapted so the app export path reproduces the Phase 0 goldens through the engine (same spies; the `rasterizeSvg` mock becomes a mock of `@/pdf/browserRasterizer`), `routes.HomeRoute.archive.test.tsx` (T15: envelope import with same sha → archive kept in store, archive_ok alert; envelope whose sha differs → rebased alert with count, unresolved flags, labels filled, `report.sheet` updated; snapshot rejected outcome → snapshot_rejected alert with the reason label; `attachment_stripped` → its error message), `migration.leaves.test.ts` kept green (612 leaves through the new path). +7. Bundle cost: `SHEET_BUNDLE=draft corepack pnpm build` in apps/app succeeds; report the gzip size of the main JS chunk before (from `git stash`-free method: build develop in a worktree is NOT allowed; instead read the size printed by vite for the chunk containing xmldom and report the total gz of dist/assets/*.js) and the size of the xmldom portion if vite's output isolates it; ceiling 50 KB gz for xmldom's share, else report. +8. Green: from the repo root `corepack pnpm typecheck && corepack pnpm lint && corepack pnpm test:run && corepack pnpm build`; `grep -rn "fetch(" apps/app/src/pdf` shows only `branding.ts`. + CHECK: cd /home/bchanot/Documents/faunosteo && corepack pnpm test:run 2>&1 | grep -E "Test Files|Tests " | tail -8 + EXPECT: all passed + +## FILE SCOPE +apps/app/src/pdf/**, apps/app/src/anatomy/drawing.ts (removal of highlight-only code if any), apps/app/src/app/routes/{HomeRoute,EditorRoute,NewReportRoute}.tsx (minimal), apps/app/src/state/{reportStore,persistence}.ts, apps/app/src/i18n/{fr,en}.ts, apps/app/scripts/**, apps/app/package.json (dependency `@faunosteo/pdf: workspace:*`, drop `pdf-lib` only if no app code imports it anymore), apps/app/tests/** (adaptations named above; goldens JSON files never edited), CLAUDE.md folder map lines for apps/app/src/pdf (keep docs minimal; Phase 5 owns the docs). Nothing under packages/**. diff --git a/apps/app/scripts/compare-reports.ts b/apps/app/scripts/compare-reports.ts index 87ca0b24..07bd6088 100644 --- a/apps/app/scripts/compare-reports.ts +++ b/apps/app/scripts/compare-reports.ts @@ -57,6 +57,7 @@ function loadSheet(): SheetIndex { document: json('document.json'), migrationMap: json('report-migration-map.json'), assets: {}, + assetHashes: {}, }), ) } diff --git a/apps/app/src/services/sheetIndex.ts b/apps/app/src/services/sheetIndex.ts index 2ba60a2a..b21b3751 100644 --- a/apps/app/src/services/sheetIndex.ts +++ b/apps/app/src/services/sheetIndex.ts @@ -1,113 +1,11 @@ -import type { - Annotation, - FindingCategory, - FindingNode, - FindingZone, - LocalizedText, - SheetView, - VertebralRegion, -} from '@faunosteo/domain' -import type { Locale } from '@/i18n/types' +import type { SheetIndex as DomainSheetIndex } from '@faunosteo/domain' import type { LoadedSheet } from '@/sheets/provider' /** - * Read-only lookups over a loaded sheet. Everything the editor used to derive - * from SVG attributes, label matching or the species manifest comes from the - * document here, by stable id: no label drives logic. + * The sheet index lives in @faunosteo/domain since Step 6 (shared with the + * PDF engine). This shim keeps the app's import path and binds the index to + * the sheet the app loads, so `index.sheet` still carries the migration map. */ - -export type ObservableAnnotation = Extract< - Annotation, - { kind: 'point' | 'zone' } -> - -export interface SheetIndex { - sheet: LoadedSheet - mainView: SheetView - view(id: string): SheetView | undefined - annotation(id: string): Annotation | undefined - annotationsOfView(viewId: string): Annotation[] - findingZone(id: string): FindingZone | undefined - /** The category or node at a path, undefined when absent from the sheet. */ - nodeAt( - zoneId: string, - path: readonly string[], - ): FindingCategory | FindingNode | undefined - regions(): VertebralRegion[] - region(code: string): VertebralRegion | undefined - /** The annotation that opens the vertebra picker for a region on a view. */ - spineAnnotation( - regionCode: string, - viewId: string, - ): ObservableAnnotation | undefined - /** Whether an annotation opens the vertebra picker. */ - isSpine(annotationId: string): boolean - name(annotation: Annotation): LocalizedText -} - -export function pickLabel( - text: LocalizedText | null | undefined, - locale: Locale, -): string { - if (!text) return '' - return locale === 'en' ? text.en || text.fr : text.fr || text.en -} - -export function isObservable( - a: Annotation | undefined, -): a is ObservableAnnotation { - return a !== undefined && a.kind !== 'detail_trigger' -} - -export function buildSheetIndex(sheet: LoadedSheet): SheetIndex { - const { document } = sheet - const views = new Map(document.views.map((v) => [v.id, v])) - const annotations = new Map(document.annotations.map((a) => [a.id, a])) - const zones = new Map(document.finding_zones.map((z) => [z.id, z])) - const regions = new Map( - document.vertebral_config.regions.map((r) => [r.code, r]), - ) - const mainView = document.views.find((v) => v.kind === 'main') - if (!mainView) throw new Error('sheet has no main view') - - const nodeAt: SheetIndex['nodeAt'] = (zoneId, path) => { - const zone = zones.get(zoneId) - if (!zone || path.length === 0) return undefined - let node: FindingCategory | FindingNode | undefined = zone.categories.find( - (c) => c.id === path[0], - ) - for (const segment of path.slice(1)) { - if (!node) return undefined - node = node.children.find((n) => n.id === segment) - } - return node - } - - return { - sheet, - mainView, - view: (id) => views.get(id), - annotation: (id) => annotations.get(id), - annotationsOfView: (viewId) => - document.annotations.filter((a) => a.view_id === viewId), - findingZone: (id) => zones.get(id), - nodeAt, - regions: () => document.vertebral_config.regions, - region: (code) => regions.get(code), - spineAnnotation: (code, viewId) => - document.annotations.find( - (a): a is ObservableAnnotation => - isObservable(a) && - a.view_id === viewId && - a.vertebral_region_code === code, - ), - isSpine: (id) => { - const a = annotations.get(id) - return isObservable(a) && a.vertebral_region_code !== null - }, - name: (a) => - a.kind === 'detail_trigger' - ? (a.name ?? views.get(a.opens_view_id)?.name ?? { fr: '', en: '' }) - : a.name, - } -} +export { buildSheetIndex, isObservable, pickLabel } from '@faunosteo/domain' +export type { ObservableAnnotation } from '@faunosteo/domain' +export type SheetIndex = DomainSheetIndex diff --git a/apps/app/src/sheets/provider.ts b/apps/app/src/sheets/provider.ts index a97a4d39..318c7bce 100644 --- a/apps/app/src/sheets/provider.ts +++ b/apps/app/src/sheets/provider.ts @@ -28,15 +28,21 @@ export interface BundledSheetData { document: unknown migrationMap: unknown assets: Record + /** sha256 by `svg_asset_id`, from the seed manifest. */ + assetHashes: Record } export interface LoadedSheet { status: SheetStatus ref: SheetRef speciesId: string + /** Document schema version of the sheet (`ref.schema_version`). */ + schemaVersion: number document: AnatomicalSheetDocument /** SVG text by `svg_asset_id`. */ assets: Readonly> + /** sha256 by `svg_asset_id`; carried into a report archive as provenance. */ + assetHashes: Readonly> migrationMap: ReportMigrationMap } @@ -56,8 +62,10 @@ export function parseBundledSheet(data: BundledSheetData): LoadedSheet { documentSha256: data.ref.document_sha256, }, speciesId: data.ref.species_id, + schemaVersion: data.ref.schema_version, document, assets: data.assets, + assetHashes: data.assetHashes, migrationMap, } } diff --git a/apps/app/tests/unit/sheets.provider.test.ts b/apps/app/tests/unit/sheets.provider.test.ts index ca7cee2a..d2e02ce4 100644 --- a/apps/app/tests/unit/sheets.provider.test.ts +++ b/apps/app/tests/unit/sheets.provider.test.ts @@ -2,6 +2,8 @@ * Replaces anatomy.horse / char.svgCatalogLink: the bundled reference sheet * loads, validates, and indexes as the canonical document says. */ +import { readFileSync } from 'node:fs' +import { resolve } from 'node:path' import { beforeAll, describe, expect, it } from 'vitest' import { bundledSheetProvider } from '@/sheets/provider' import { @@ -12,6 +14,12 @@ import { } from '@/services/sheetIndex' import { loadTestSheet } from '../helpers/sheet' +/** The seed manifest the bundle reads its asset hashes from. */ +const ASSET_MANIFEST = resolve( + __dirname, + '../../../../supabase/seed/anatomical-sheets/equine/draft/assets.json', +) + let sheet: SheetIndex beforeAll(async () => { sheet = await loadTestSheet() @@ -32,6 +40,19 @@ describe('bundled sheet provider', () => { ) expect(await bundledSheetProvider.getReferenceSheet('canine')).toBeNull() }) + + it('carries the schema version and the manifest hash of the horse asset', async () => { + const loaded = await bundledSheetProvider.getReferenceSheet('equine') + const manifest = JSON.parse(readFileSync(ASSET_MANIFEST, 'utf8')) as { + sha256: string + svg_asset_id: string + }[] + const horse = manifest[0]! + expect(loaded!.schemaVersion).toBe(2) + expect(Object.keys(loaded!.assetHashes)).toEqual([horse.svg_asset_id]) + expect(loaded!.assetHashes[horse.svg_asset_id]).toBe(horse.sha256) + expect(horse.sha256).toMatch(/^[0-9a-f]{64}$/) + }) }) describe('sheet index', () => { @@ -93,9 +114,12 @@ describe('sheet index', () => { .filter(isObservable) .map((a) => a.vertebral_region_code) .filter((c) => c !== null) - expect(sheet.regions().map((r) => r.code).sort()).toEqual( - [...carried].sort(), - ) + expect( + sheet + .regions() + .map((r) => r.code) + .sort(), + ).toEqual([...carried].sort()) }) it('resolves finding paths and reports absent ones', () => { diff --git a/apps/app/vite/sheet-bundle.ts b/apps/app/vite/sheet-bundle.ts index b9485e2e..70276067 100644 --- a/apps/app/vite/sheet-bundle.ts +++ b/apps/app/vite/sheet-bundle.ts @@ -7,7 +7,8 @@ import type { Plugin } from 'vite' * application as the virtual module `virtual:faunosteo-sheet`. * * Mode `draft` embeds `document.json`, `sheet-ref.json`, - * `report-migration-map.json` and the SVG assets of the seed folder; mode + * `report-migration-map.json`, the SVG assets of the seed folder and their + * manifest hashes (`assets.json`, carried into report archives); mode * `none` exports null and the app shows "no sheet configured". The default is * `draft` for the dev server and `none` for a build: a production bundle never * carries the medically unvalidated draft unless `SHEET_BUNDLE=draft` is set @@ -36,6 +37,7 @@ interface SeedFiles { document: unknown migrationMap: unknown assets: Record + assetHashes: Record watched: string[] } @@ -44,20 +46,24 @@ function readSeed(seedDir: string): SeedFiles { JSON.parse(readFileSync(join(seedDir, name), 'utf8')) as unknown const manifest = json('assets.json') as { file: string + sha256: string svg_asset_id: string }[] const assets: Record = {} + const assetHashes: Record = {} for (const asset of manifest) { assets[asset.svg_asset_id] = readFileSync( join(seedDir, 'assets', asset.file), 'utf8', ) + assetHashes[asset.svg_asset_id] = asset.sha256 } return { ref: json('sheet-ref.json'), document: json('document.json'), migrationMap: json('report-migration-map.json'), assets, + assetHashes, watched: [ 'sheet-ref.json', 'document.json', @@ -88,6 +94,7 @@ export function faunosteoSheetBundle(options: { document: seed.document, migrationMap: seed.migrationMap, assets: seed.assets, + assetHashes: seed.assetHashes, } return `export const bundledSheet = ${JSON.stringify(payload)}\n` }, diff --git a/packages/domain/package.json b/packages/domain/package.json index 187daae2..0fda4db0 100644 --- a/packages/domain/package.json +++ b/packages/domain/package.json @@ -10,7 +10,8 @@ "exports": { ".": "./src/index.ts", "./anatomical-sheet": "./src/anatomical-sheet/index.ts", - "./report": "./src/report/index.ts" + "./report": "./src/report/index.ts", + "./archive": "./src/archive/index.ts" }, "scripts": { "typecheck": "tsc -p tsconfig.json --noEmit", diff --git a/packages/domain/src/anatomical-sheet/index.ts b/packages/domain/src/anatomical-sheet/index.ts index 0e850af9..c0c1d0e6 100644 --- a/packages/domain/src/anatomical-sheet/index.ts +++ b/packages/domain/src/anatomical-sheet/index.ts @@ -1,3 +1,4 @@ export * from './schema' export * from './validate' export * from './create' +export * from './sheet-index' diff --git a/packages/domain/src/anatomical-sheet/sheet-index.ts b/packages/domain/src/anatomical-sheet/sheet-index.ts new file mode 100644 index 00000000..5fa2fdd0 --- /dev/null +++ b/packages/domain/src/anatomical-sheet/sheet-index.ts @@ -0,0 +1,127 @@ +import type { + AnatomicalSheetDocument, + Annotation, + FindingCategory, + FindingNode, + FindingZone, + LocalizedText, + SheetView, + VertebralRegion, +} from './schema' + +/** + * Read-only lookups over a sheet document. Everything the editor and the + * PDF engine derive from the sheet (zone names, finding paths, spine + * regions, trigger targets) comes from the document here, by stable id: + * no label drives logic. The index keeps the source it was built from so a + * caller gets back exactly what it passed (a loaded sheet with its migration + * map, or an archived snapshot). + */ + +/** The minimum a sheet source carries: provenance, document, SVG text by asset id. */ +export interface SheetIndexSource { + ref: { documentSha256: string } + document: AnatomicalSheetDocument + assets: Readonly> +} + +export type ObservableAnnotation = Extract< + Annotation, + { kind: 'point' | 'zone' } +> + +export interface SheetIndex { + sheet: S + mainView: SheetView + view(id: string): SheetView | undefined + annotation(id: string): Annotation | undefined + annotationsOfView(viewId: string): Annotation[] + findingZone(id: string): FindingZone | undefined + /** The category or node at a path, undefined when absent from the sheet. */ + nodeAt( + zoneId: string, + path: readonly string[], + ): FindingCategory | FindingNode | undefined + regions(): VertebralRegion[] + region(code: string): VertebralRegion | undefined + /** The annotation that opens the vertebra picker for a region on a view. */ + spineAnnotation( + regionCode: string, + viewId: string, + ): ObservableAnnotation | undefined + /** Whether an annotation opens the vertebra picker. */ + isSpine(annotationId: string): boolean + name(annotation: Annotation): LocalizedText +} + +/** The label in a locale, the other locale as fallback, '' when none. */ +export function pickLabel( + text: LocalizedText | null | undefined, + locale: 'fr' | 'en', +): string { + if (!text) return '' + return locale === 'en' ? text.en || text.fr : text.fr || text.en +} + +export function isObservable( + a: Annotation | undefined, +): a is ObservableAnnotation { + return a !== undefined && a.kind !== 'detail_trigger' +} + +function nodeAtPath( + zone: FindingZone | undefined, + path: readonly string[], +): FindingCategory | FindingNode | undefined { + if (!zone || path.length === 0) return undefined + let node: FindingCategory | FindingNode | undefined = zone.categories.find( + (c) => c.id === path[0], + ) + for (const segment of path.slice(1)) { + if (!node) return undefined + node = node.children.find((n) => n.id === segment) + } + return node +} + +export function buildSheetIndex( + sheet: S, +): SheetIndex { + const { document } = sheet + const views = new Map(document.views.map((v) => [v.id, v])) + const annotations = new Map(document.annotations.map((a) => [a.id, a])) + const zones = new Map(document.finding_zones.map((z) => [z.id, z])) + const regions = new Map( + document.vertebral_config.regions.map((r) => [r.code, r]), + ) + const mainView = document.views.find((v) => v.kind === 'main') + if (!mainView) throw new Error('sheet has no main view') + + return { + sheet, + mainView, + view: (id) => views.get(id), + annotation: (id) => annotations.get(id), + annotationsOfView: (viewId) => + document.annotations.filter((a) => a.view_id === viewId), + findingZone: (id) => zones.get(id), + nodeAt: (zoneId, path) => nodeAtPath(zones.get(zoneId), path), + regions: () => document.vertebral_config.regions, + region: (code) => regions.get(code), + spineAnnotation: (code, viewId) => + document.annotations.find( + (a): a is ObservableAnnotation => + isObservable(a) && + a.view_id === viewId && + a.vertebral_region_code === code, + ), + isSpine: (id) => { + const a = annotations.get(id) + return isObservable(a) && a.vertebral_region_code !== null + }, + name: (a) => + a.kind === 'detail_trigger' + ? (a.name ?? views.get(a.opens_view_id)?.name ?? { fr: '', en: '' }) + : a.name, + } +} diff --git a/packages/domain/src/archive/branding.ts b/packages/domain/src/archive/branding.ts new file mode 100644 index 00000000..d6e92c4e --- /dev/null +++ b/packages/domain/src/archive/branding.ts @@ -0,0 +1,51 @@ +import { z } from 'zod' + +/** + * The visual identity a PDF archive embeds so a re-export needs no network + * and no `public/` folder (STEP6 §3.4): logos as PNG base64 or SVG text, + * credits with the URL and the text printed when the logo fails. Caps are + * STEP6 §15 (branding row). + */ + +const KIB = 1024 +const BASE64_PATTERN = /^[A-Za-z0-9+/]*={0,2}$/ + +const HttpUrlSchema = z + .string() + .max(2048) + .url() + .refine((url) => /^https?:\/\//i.test(url), 'http(s) URL expected') + +export const ImageAssetSchema = z.discriminatedUnion('kind', [ + z + .object({ + kind: z.literal('png'), + base64: z + .string() + .max(512 * KIB) + .regex(BASE64_PATTERN), + }) + .strict(), + z.object({ kind: z.literal('svg'), svg: z.string().max(256 * KIB) }).strict(), +]) +export type ImageAsset = z.infer + +export const CreditSchema = z + .object({ + logo: ImageAssetSchema.nullable(), + url: HttpUrlSchema, + fallbackText: z.string().max(128), + }) + .strict() +export type Credit = z.infer + +export const BrandingSchema = z + .object({ + siteUrl: HttpUrlSchema, + headerLogo: ImageAssetSchema.nullable(), + footerLogo: ImageAssetSchema.nullable(), + poweredBy: CreditSchema.nullable(), + partner: CreditSchema.nullable(), + }) + .strict() +export type Branding = z.infer diff --git a/packages/domain/src/archive/envelope.ts b/packages/domain/src/archive/envelope.ts new file mode 100644 index 00000000..d2265ddd --- /dev/null +++ b/packages/domain/src/archive/envelope.ts @@ -0,0 +1,172 @@ +import { z } from 'zod' +import { readReportDocument } from '../report/migrate' +import type { ReportMigrationMap } from '../report/migration-map' +import { REPORT_VERSION, ReportSchema, type Report } from '../report/v3' +import { BrandingSchema, type Branding } from './branding' +import { PdfLabelSetSchema, type PdfLabelSet } from './labels' +import { + SheetSnapshotSchema, + SnapshotError, + assertSnapshot, + type SheetSnapshot, + type SnapshotRejection, +} from './snapshot' + +/** + * Attachment of a Step 6 PDF: the report (v3, unchanged) wrapped with the + * sheet snapshot, the branding and the PDF labels it was printed with + * (STEP6 §2.3). Reading is layered (§4, §14 "Read"): the report is located + * and parsed first so it is never lost because of its wrapper; the wrapper + * is then validated or dropped with a reason. + */ + +export const ENVELOPE_FORMAT = 'faunosteo-report-archive' +export const ENVELOPE_VERSION = 1 + +export interface ReportArchiveEnvelope { + format: typeof ENVELOPE_FORMAT + envelopeVersion: typeof ENVELOPE_VERSION + /** ISO timestamp of the export. */ + exportedAt: string + locale: 'fr' | 'en' + /** As exported, never rebased. */ + report: Report + sheetSnapshot: SheetSnapshot + branding: Branding + labels: PdfLabelSet +} + +/** Metadata is not strict: an additive v1 field never breaks an older reader. */ +const EnvelopeMetadataSchema = z.object({ + format: z.literal(ENVELOPE_FORMAT), + envelopeVersion: z.literal(ENVELOPE_VERSION), + exportedAt: z.string(), + locale: z.enum(['fr', 'en']), +}) + +/** Everything but the report and the snapshot, which the reader checks itself. */ +const EnvelopeWrapperSchema = EnvelopeMetadataSchema.extend({ + branding: BrandingSchema, + labels: PdfLabelSetSchema, +}) + +export const ReportArchiveEnvelopeSchema: z.ZodType< + ReportArchiveEnvelope, + z.ZodTypeDef, + unknown +> = EnvelopeWrapperSchema.extend({ + report: ReportSchema, + sheetSnapshot: SheetSnapshotSchema, +}) + +export type ArchiveOrigin = 'envelope_v1' | 'bare_v3' | 'v2' + +export interface ArchiveReadOutcome { + report: Report + origin: ArchiveOrigin + migrated: boolean + /** From the v2 migration; 0 for a v3 report. */ + unresolvedZones: number + unresolvedFindings: number + /** The validated envelope, when accepted. */ + archive: ReportArchiveEnvelope | null + /** Envelope present but its snapshot dropped. */ + snapshotRejected?: SnapshotRejection +} + +type Wrapped = + | { archive: ReportArchiveEnvelope } + | { snapshotRejected: SnapshotRejection } + +function isRecord(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value) +} + +/** An envelope of any version is recognised by a numeric envelopeVersion. */ +function envelopeVersionOf(data: unknown): number | null { + if (!isRecord(data)) return null + const version = data.envelopeVersion + return typeof version === 'number' ? version : null +} + +function reportVersionOf(data: unknown): number | null { + if (!isRecord(data)) return null + return typeof data.version === 'number' ? data.version : null +} + +function snapshotMatches(snapshot: SheetSnapshot, report: Report): boolean { + return ( + snapshot.ref.sheetId === report.sheet.sheetId && + snapshot.ref.documentSha256 === report.sheet.documentSha256 + ) +} + +/** Step 3 for a v1 envelope: wrapper schema → snapshot gate → sheet invariant. */ +function readEnvelopeV1( + data: Record, + report: Report, +): Wrapped { + const wrapper = EnvelopeWrapperSchema.safeParse(data) + if (!wrapper.success) return { snapshotRejected: 'schema' } + let snapshot: SheetSnapshot + try { + snapshot = assertSnapshot(data.sheetSnapshot) + } catch (error) { + if (error instanceof SnapshotError) { + return { snapshotRejected: error.reason } + } + throw error + } + if (!snapshotMatches(snapshot, report)) { + return { snapshotRejected: 'sheet_mismatch' } + } + return { + archive: { + format: wrapper.data.format, + envelopeVersion: wrapper.data.envelopeVersion, + exportedAt: wrapper.data.exportedAt, + locale: wrapper.data.locale, + report, + sheetSnapshot: snapshot, + branding: wrapper.data.branding, + labels: wrapper.data.labels, + }, + } +} + +/** + * Reads the JSON of a PDF attachment of any supported shape: bare Report v2 + * or v3, or an archive envelope. The report is parsed first and always + * returned (`readReportDocument` throws UnsupportedReportVersionError for an + * unknown report version); the envelope is accepted whole or dropped with + * `snapshotRejected`. + */ +export function readArchiveDocument( + data: unknown, + map: ReportMigrationMap, +): ArchiveReadOutcome { + const envelopeVersion = envelopeVersionOf(data) + const reportData = + envelopeVersion !== null ? (data as Record).report : data + const outcome = readReportDocument(reportData, map) + const migrated = reportVersionOf(reportData) !== REPORT_VERSION + const base: ArchiveReadOutcome = { + report: outcome.report, + origin: migrated ? 'v2' : 'bare_v3', + migrated, + unresolvedZones: outcome.unresolvedZones, + unresolvedFindings: outcome.unresolvedFindings, + archive: null, + } + if (envelopeVersion === null) return base + if (envelopeVersion !== ENVELOPE_VERSION) { + return { ...base, snapshotRejected: 'unsupported_envelope' } + } + const wrapped = readEnvelopeV1( + data as Record, + outcome.report, + ) + return 'archive' in wrapped + ? { ...base, origin: 'envelope_v1', archive: wrapped.archive } + : { ...base, origin: 'envelope_v1', ...wrapped } +} diff --git a/packages/domain/src/archive/index.ts b/packages/domain/src/archive/index.ts new file mode 100644 index 00000000..6b2bd63b --- /dev/null +++ b/packages/domain/src/archive/index.ts @@ -0,0 +1,4 @@ +export * from './snapshot' +export * from './branding' +export * from './labels' +export * from './envelope' diff --git a/packages/domain/src/archive/labels.ts b/packages/domain/src/archive/labels.ts new file mode 100644 index 00000000..217b856f --- /dev/null +++ b/packages/domain/src/archive/labels.ts @@ -0,0 +1,57 @@ +import { z } from 'zod' + +/** + * The static strings the PDF engine prints (section headings, metadata, + * severities, sides, footer credits), in both locales, frozen into the + * archive so a re-export renders the wording of the day. Exactly the dict + * keys apps/app/src/pdf read when Step 6 started. + */ + +export const PDF_LABEL_KEYS = [ + 'pdf.empty', + 'pdf.eyebrow.observation', + 'pdf.eyebrow.synthesis', + 'pdf.owner_prefix', + 'pdf.section.comment', + 'pdf.section.conclusion', + 'pdf.section.findings_prefix', + 'pdf.section.free_findings', + 'pdf.section.next_appointment', + 'pdf.section.recommendations', + 'pdf.section.severity', + 'pdf.section.zones', + 'pdf.siret_prefix', + 'pdf.subject', + 'pdf.title.conclusion', + 'pdf.title.suffix.bilan', + 'pdf.view.detail_prefix', + 'pdf.view.general', + 'severity.mild', + 'severity.moderate', + 'severity.severe', + 'lateral.left', + 'lateral.right', + 'footer.powered_by', + 'footer.in_partnership', +] as const + +export type PdfLabelKey = (typeof PDF_LABEL_KEYS)[number] +export type PdfLabels = Record + +export interface PdfLabelSet { + fr: PdfLabels + en: PdfLabels +} + +const labelShape = Object.fromEntries( + PDF_LABEL_KEYS.map((key) => [key, z.string().max(256)]), +) as Record + +export const PdfLabelsSchema: z.ZodType = z + .object(labelShape) + .strict() + +/** Strict: every key present in both locales, no extra key. */ +export const PdfLabelSetSchema: z.ZodType = z + .object({ fr: PdfLabelsSchema, en: PdfLabelsSchema }) + .strict() diff --git a/packages/domain/src/archive/snapshot.ts b/packages/domain/src/archive/snapshot.ts new file mode 100644 index 00000000..11402a26 --- /dev/null +++ b/packages/domain/src/archive/snapshot.ts @@ -0,0 +1,425 @@ +import { z } from 'zod' +import { + AnatomicalSheetDocumentSchema, + type AnatomicalSheetDocument, + type FindingCategory, + type FindingNode, + type FindingZone, + type SheetView, +} from '../anatomical-sheet/schema' +import { validateSheetDocument } from '../anatomical-sheet/validate' +import type { SheetIndexSource } from '../anatomical-sheet/sheet-index' +import { SheetRefSchema, type Report, type SheetRef } from '../report/v3' + +/** + * The sheet a report archive carries so an old bilan re-renders without the + * current catalog (STEP6 §2.2). The snapshot keeps the shape the renderer and + * the sheet index consume: a valid, lean `AnatomicalSheetDocument` (every + * view, annotation, category and region; finding trees pruned to the paths + * the report uses; bibliography emptied) plus the SVG text of every asset a + * view reaches. `assertSnapshot` is the single gate an imported snapshot + * passes (STEP6 §15 caps, integrity, reachable assets). + */ + +const SHA256_PATTERN = /^[0-9a-f]{64}$/ +const MIB = 1024 * 1024 + +/** Hard limits on an imported snapshot; every excess is a `caps` rejection. */ +export const SNAPSHOT_CAPS = { + views: 64, + annotations: 1024, + findingNodes: 8192, + findingDepth: 8, + labelChars: 512, + assets: 4, + assetBytes: 2 * MIB, + assetsTotalBytes: 6 * MIB, +} as const + +export type SheetSnapshotRef = SheetRef & { + schemaVersion: number + speciesId: string +} + +export interface SheetSnapshotAsset { + svgAssetId: string + /** Content address from the seed manifest; a provenance pointer, not a tamper check. */ + sha256: string | null + svg: string +} + +export interface SheetSnapshot { + status: 'draft' | 'published' + ref: SheetSnapshotRef + /** Lean, valid document (schema v2, strict). */ + document: AnatomicalSheetDocument + assets: SheetSnapshotAsset[] +} + +export const SheetSnapshotRefSchema: z.ZodType = + SheetRefSchema.extend({ + schemaVersion: z.number().int().positive(), + speciesId: z.string().min(1), + }).strict() + +const SheetSnapshotAssetSchema = z + .object({ + svgAssetId: z.string().uuid(), + sha256: z.string().regex(SHA256_PATTERN).nullable(), + svg: z.string().max(SNAPSHOT_CAPS.assetBytes), + }) + .strict() + +/** Shape tier only: caps beyond the schema and integrity live in assertSnapshot. */ +export const SheetSnapshotSchema: z.ZodType< + SheetSnapshot, + z.ZodTypeDef, + unknown +> = z + .object({ + status: z.enum(['draft', 'published']), + ref: SheetSnapshotRefSchema, + document: AnatomicalSheetDocumentSchema, + assets: z.array(SheetSnapshotAssetSchema).max(SNAPSHOT_CAPS.assets), + }) + .strict() + +/** What a loaded sheet provides to build a snapshot from. */ +export interface SnapshotSource { + status: 'draft' | 'published' + ref: SheetRef + speciesId: string + schemaVersion: number + document: AnatomicalSheetDocument + /** SVG text by `svg_asset_id`. */ + assets: Readonly> + /** sha256 by `svg_asset_id` (seed manifest); absent → null in the snapshot. */ + assetHashes?: Readonly> +} + +export type SnapshotRejection = + | 'unsupported_envelope' + | 'schema' + | 'caps' + | 'integrity' + | 'sheet_mismatch' + +/** Thrown by assertSnapshot; `reason` is what the import reports. */ +export class SnapshotError extends Error { + constructor( + public readonly reason: SnapshotRejection, + detail: string, + ) { + super(`snapshot rejected (${reason}): ${detail}`) + this.name = 'SnapshotError' + } +} + +/** Own-key lookup: ids come from documents (`__proto__` is not an entry). */ +function own( + record: Readonly>, + key: string, +): T | undefined { + return Object.hasOwn(record, key) ? record[key] : undefined +} + +/** The asset a view draws: its own, else the first one up its parent chain. */ +function assetOfView( + view: SheetView, + views: ReadonlyMap, +): string | null { + const visited = new Set() + let current: SheetView | undefined = view + while (current && !visited.has(current.id)) { + if (current.svg_asset_id !== null) return current.svg_asset_id + visited.add(current.id) + current = + current.kind === 'detail' ? views.get(current.parent_view_id) : undefined + } + return null +} + +/** Asset ids reachable from the views, in view order, each once. */ +function reachableAssetIds(document: AnatomicalSheetDocument): string[] { + const views = new Map(document.views.map((v) => [v.id, v])) + const ids: string[] = [] + for (const view of document.views) { + const id = assetOfView(view, views) + if (id !== null && !ids.includes(id)) ids.push(id) + } + return ids +} + +// --------------------------------------------------------------------------- +// Build + +/** Finding paths of the report grouped by zone, resolved and unresolved alike. */ +function pathsByZone(report: Report): Map { + const byZone = new Map() + for (const observation of report.observations) { + for (const finding of observation.findings) { + const paths = byZone.get(finding.findingZoneId) ?? [] + paths.push(finding.path) + byZone.set(finding.findingZoneId, paths) + } + } + return byZone +} + +/** Keeps, in document order, the nodes at `depth` of some path and their used descendants. */ +function pruneNodes( + nodes: readonly FindingNode[], + paths: readonly string[][], + depth: number, +): FindingNode[] { + return nodes + .filter((node) => paths.some((path) => path[depth] === node.id)) + .map((node) => ({ + id: node.id, + name: { ...node.name }, + description: {}, + requires_vet_referral: node.requires_vet_referral, + reference_ids: [], + review_status: node.review_status, + children: pruneNodes( + node.children, + paths.filter((path) => path[depth] === node.id), + depth + 1, + ), + })) +} + +function pruneCategories( + categories: readonly FindingCategory[], + paths: readonly string[][], +): FindingCategory[] { + return categories + .filter((category) => paths.some((path) => path[0] === category.id)) + .map((category) => ({ + id: category.id, + kind: category.kind, + name: { ...category.name }, + description: {}, + reference_ids: [], + review_status: category.review_status, + children: pruneNodes( + category.children, + paths.filter((path) => path[0] === category.id), + 1, + ), + })) +} + +function pruneZone(zone: FindingZone, paths: readonly string[][]): FindingZone { + return { + id: zone.id, + name: { ...zone.name }, + categories: pruneCategories(zone.categories, paths), + } +} + +function leanDocument( + document: AnatomicalSheetDocument, + report: Report, +): AnatomicalSheetDocument { + const used = pathsByZone(report) + return { + schema_version: document.schema_version, + species_id: document.species_id, + name: structuredClone(document.name), + description: structuredClone(document.description), + scope_disclaimer: structuredClone(document.scope_disclaimer), + attribution: structuredClone(document.attribution), + vertebral_config: structuredClone(document.vertebral_config), + references: [], + categories: structuredClone(document.categories), + views: structuredClone(document.views), + annotations: structuredClone(document.annotations), + finding_zones: document.finding_zones.map((zone) => + pruneZone(zone, used.get(zone.id) ?? []), + ), + } +} + +function snapshotAssets(sheet: SnapshotSource): SheetSnapshotAsset[] { + const assets: SheetSnapshotAsset[] = [] + for (const svgAssetId of reachableAssetIds(sheet.document)) { + const svg = own(sheet.assets, svgAssetId) + if (svg === undefined) continue + const sha256 = sheet.assetHashes + ? (own(sheet.assetHashes, svgAssetId) ?? null) + : null + assets.push({ svgAssetId, sha256, svg }) + } + return assets +} + +/** + * The snapshot of `sheet` a given report needs: pure, deterministic + * (document order everywhere), inputs untouched. Finding trees keep only the + * categories and nodes on a path some finding of the report names, as far as + * those nodes exist; a missing asset is left out and caught by assertSnapshot. + */ +export function buildSheetSnapshot( + sheet: SnapshotSource, + report: Report, +): SheetSnapshot { + return { + status: sheet.status, + ref: { + sheetId: sheet.ref.sheetId, + versionId: sheet.ref.versionId, + documentSha256: sheet.ref.documentSha256, + schemaVersion: sheet.schemaVersion, + speciesId: sheet.speciesId, + }, + document: leanDocument(sheet.document, report), + assets: snapshotAssets(sheet), + } +} + +// --------------------------------------------------------------------------- +// Assert + +function isRecord(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value) +} + +function childrenOf(node: unknown): unknown[] { + if (!isRecord(node)) return [] + const children = node.children + return Array.isArray(children) ? children : [] +} + +/** + * Depth of the finding trees, checked on the raw input before Zod recurses + * into it (an attacker-sized tree must not drive the parser). Iterative: + * an explicit stack of (node, depth) pairs, categories at depth 1. + */ +function assertFindingDepth(input: unknown): void { + if (!isRecord(input) || !isRecord(input.document)) return + const zones = input.document.finding_zones + if (!Array.isArray(zones)) return + const stack: Array<[unknown, number]> = [] + for (const zone of zones) { + if (!isRecord(zone) || !Array.isArray(zone.categories)) continue + for (const category of zone.categories) stack.push([category, 1]) + } + while (stack.length > 0) { + const [node, depth] = stack.pop()! + if (depth > SNAPSHOT_CAPS.findingDepth) { + throw new SnapshotError( + 'caps', + `finding depth over ${SNAPSHOT_CAPS.findingDepth}`, + ) + } + for (const child of childrenOf(node)) stack.push([child, depth + 1]) + } +} + +function countFindingNodes(document: AnatomicalSheetDocument): number { + let count = 0 + const stack: Array = + document.finding_zones.flatMap((zone) => zone.categories) + while (stack.length > 0) { + count += 1 + stack.push(...stack.pop()!.children) + } + return count +} + +/** + * Longest `name` label (`fr` or `en`) anywhere in the document: sheet, views, + * annotations, categories, regions, finding zones and nodes. Free texts + * (`description`, `scope_disclaimer`) are not labels and carry no cap here. + */ +function longestName(document: AnatomicalSheetDocument): number { + let longest = 0 + const stack: unknown[] = [document] + while (stack.length > 0) { + const value = stack.pop() + if (Array.isArray(value)) stack.push(...value) + if (!isRecord(value)) continue + const name = value.name + if (isRecord(name)) { + for (const key of ['fr', 'en']) { + const text = name[key] + if (typeof text === 'string') longest = Math.max(longest, text.length) + } + } + stack.push(...Object.values(value)) + } + return longest +} + +function utf8Length(text: string): number { + return new TextEncoder().encode(text).byteLength +} + +function assertCaps(snapshot: SheetSnapshot): void { + const over = (what: string) => new SnapshotError('caps', `${what} over cap`) + const { document, assets } = snapshot + if (document.views.length > SNAPSHOT_CAPS.views) throw over('views') + if (document.annotations.length > SNAPSHOT_CAPS.annotations) { + throw over('annotations') + } + if (countFindingNodes(document) > SNAPSHOT_CAPS.findingNodes) { + throw over('finding nodes') + } + if (longestName(document) > SNAPSHOT_CAPS.labelChars) throw over('label') + if (assets.length > SNAPSHOT_CAPS.assets) throw over('assets') + const sizes = assets.map((asset) => utf8Length(asset.svg)) + if (sizes.some((size) => size > SNAPSHOT_CAPS.assetBytes)) throw over('asset') + const total = sizes.reduce((sum, size) => sum + size, 0) + if (total > SNAPSHOT_CAPS.assetsTotalBytes) throw over('assets total') +} + +function assertIntegrity(snapshot: SheetSnapshot): void { + const errors = validateSheetDocument(snapshot.document).filter( + (issue) => issue.severity === 'error', + ) + if (errors.length > 0) { + throw new SnapshotError('integrity', errors[0]!.code) + } + const present = new Set(snapshot.assets.map((asset) => asset.svgAssetId)) + const views = new Map(snapshot.document.views.map((v) => [v.id, v])) + for (const view of snapshot.document.views) { + const assetId = assetOfView(view, views) + if (assetId === null || !present.has(assetId)) { + throw new SnapshotError('integrity', `view "${view.id}" reaches no asset`) + } + } +} + +/** + * The single gate of an imported snapshot, in this order: finding depth on + * the raw input → shape (`schema`) → caps (§15) → sheet integrity rules and + * every view reaching an asset carried by the snapshot (`integrity`). + * Returns the parsed snapshot; throws SnapshotError with the reason. + */ +export function assertSnapshot(snapshot: unknown): SheetSnapshot { + assertFindingDepth(snapshot) + const parsed = SheetSnapshotSchema.safeParse(snapshot) + if (!parsed.success) { + throw new SnapshotError( + 'schema', + parsed.error.issues[0]?.message ?? 'invalid', + ) + } + assertCaps(parsed.data) + assertIntegrity(parsed.data) + return parsed.data +} + +/** Adapter: a snapshot as the sheet index reads it (assets array → record). */ +export function snapshotIndexSource( + snapshot: SheetSnapshot, +): SheetIndexSource & { ref: SheetSnapshotRef } { + return { + ref: snapshot.ref, + document: snapshot.document, + assets: Object.fromEntries( + snapshot.assets.map((asset) => [asset.svgAssetId, asset.svg]), + ), + } +} diff --git a/packages/domain/src/index.ts b/packages/domain/src/index.ts index 9fb87034..a0985a5c 100644 --- a/packages/domain/src/index.ts +++ b/packages/domain/src/index.ts @@ -1,2 +1,3 @@ export * from './anatomical-sheet' export * from './report' +export * from './archive' diff --git a/packages/domain/src/report/index.ts b/packages/domain/src/report/index.ts index 2fae55c0..f54991a1 100644 --- a/packages/domain/src/report/index.ts +++ b/packages/domain/src/report/index.ts @@ -25,3 +25,8 @@ export { UnsupportedReportVersionError, type MigrationOutcome, } from './migrate' +export { + rebaseReportOnSheet, + type RebaseIndex, + type RebaseOutcome, +} from './rebase' diff --git a/packages/domain/src/report/rebase.ts b/packages/domain/src/report/rebase.ts new file mode 100644 index 00000000..626c2b65 --- /dev/null +++ b/packages/domain/src/report/rebase.ts @@ -0,0 +1,137 @@ +import type { + SheetIndex, + SheetIndexSource, +} from '../anatomical-sheet/sheet-index' +import type { Annotation, LocalizedText } from '../anatomical-sheet/schema' +import type { SheetSnapshot } from '../archive/snapshot' +import { + ReportSchema, + type Finding, + type Observation, + type Report, + type ReportZone, + type SheetRef, +} from './v3' + +/** + * Moves an imported report onto the sheet the application has loaded + * (STEP6 §3.5). A report written on another revision of the sheet keeps + * every datum: a zone or finding the loaded sheet no longer holds is flagged + * `unresolved`, its labels taken from the archived snapshot when the report + * carries none, and the report now references the loaded sheet. Nothing + * happens when the report already sits on the loaded sheet. + */ + +/** An index whose source names its sheet (a loaded sheet or a snapshot). */ +export type RebaseIndex = SheetIndex + +export interface RebaseOutcome { + report: Report + /** Zones and findings newly flagged by this rebase. */ + unresolvedZones: number + unresolvedFindings: number + rebased: boolean +} + +interface Counters { + zones: number + findings: number +} + +/** The name the archived snapshot gives an annotation (a trigger: its view's). */ +function archivedName( + archived: SheetSnapshot | null, + annotationId: string, +): LocalizedText | undefined { + if (!archived) return undefined + const annotation: Annotation | undefined = archived.document.annotations.find( + (a) => a.id === annotationId, + ) + if (!annotation) return undefined + if (annotation.kind !== 'detail_trigger') return annotation.name + const view = archived.document.views.find( + (v) => v.id === annotation.opens_view_id, + ) + return annotation.name ?? view?.name +} + +function flagZone( + zone: ReportZone, + archived: SheetSnapshot | null, +): ReportZone { + const out: ReportZone = { ...zone, unresolved: true } + const name = archivedName(archived, zone.annotationId) + if (name) { + out.labelFrSnapshot ??= name.fr + out.labelEnSnapshot ??= name.en + } + return out +} + +function rebaseZone( + zone: ReportZone, + index: RebaseIndex, + archived: SheetSnapshot | null, + counters: Counters, +): ReportZone { + if (zone.unresolved) return { ...zone } + const known = + index.annotation(zone.annotationId) !== undefined && + index.view(zone.viewId) !== undefined + if (known) return { ...zone } + counters.zones += 1 + return flagZone(zone, archived) +} + +function rebaseFinding( + finding: Finding, + index: RebaseIndex, + counters: Counters, +): Finding { + if (finding.unresolved) return { ...finding } + if (index.nodeAt(finding.findingZoneId, finding.path)) return { ...finding } + counters.findings += 1 + return { ...finding, unresolved: true } +} + +function rebaseObservation( + observation: Observation, + index: RebaseIndex, + archived: SheetSnapshot | null, + counters: Counters, +): Observation { + return { + ...observation, + zones: observation.zones.map((z) => + rebaseZone(z, index, archived, counters), + ), + findings: observation.findings.map((f) => + rebaseFinding(f, index, counters), + ), + } +} + +export function rebaseReportOnSheet( + report: Report, + index: RebaseIndex, + archived: SheetSnapshot | null, +): RebaseOutcome { + if (report.sheet.documentSha256 === index.sheet.ref.documentSha256) { + return { report, unresolvedZones: 0, unresolvedFindings: 0, rebased: false } + } + const counters: Counters = { zones: 0, findings: 0 } + const { sheetId, versionId, documentSha256 } = index.sheet.ref + const rebased: Report = { + ...report, + sheet: { sheetId, versionId, documentSha256 }, + observations: report.observations.map((o) => + rebaseObservation(o, index, archived, counters), + ), + } + return { + report: ReportSchema.parse(rebased), + unresolvedZones: counters.zones, + unresolvedFindings: counters.findings, + rebased: true, + } +} diff --git a/packages/domain/tests/archive.branding-labels.test.ts b/packages/domain/tests/archive.branding-labels.test.ts new file mode 100644 index 00000000..8ab12fb5 --- /dev/null +++ b/packages/domain/tests/archive.branding-labels.test.ts @@ -0,0 +1,137 @@ +import { describe, expect, it } from 'vitest' +import { + BrandingSchema, + PDF_LABEL_KEYS, + PdfLabelSetSchema, + type Branding, + type PdfLabels, +} from '../src' + +export function sampleBranding(): Branding { + return { + siteUrl: 'https://faunosteo.com', + headerLogo: { kind: 'png', base64: 'iVBORw0KGgo=' }, + footerLogo: null, + poweredBy: { + logo: null, + url: 'https://zenquality.fr', + fallbackText: 'zenquality.fr', + }, + partner: { + logo: { kind: 'svg', svg: '' }, + url: 'https://www.instagram.com/paws.iin.harmony', + fallbackText: '@paws.iin.harmony', + }, + } +} + +export function sampleLabels(): PdfLabels { + return Object.fromEntries( + PDF_LABEL_KEYS.map((key) => [key, key]), + ) as PdfLabels +} + +describe('BrandingSchema', () => { + it('accepts the current identity and both image kinds', () => { + expect(BrandingSchema.parse(sampleBranding())).toEqual(sampleBranding()) + const bare = { + siteUrl: 'http://localhost:5173', + headerLogo: null, + footerLogo: null, + poweredBy: null, + partner: null, + } + expect(BrandingSchema.parse(bare)).toEqual(bare) + }) + + it.each([ + ['unknown key', (b: Branding) => ({ ...b, extra: 1 })], + [ + 'non-http URL', + (b: Branding) => ({ ...b, siteUrl: 'javascript:alert(1)' }), + ], + ['ftp URL', (b: Branding) => ({ ...b, siteUrl: 'ftp://x.test/a' })], + [ + 'URL over 2048 chars', + (b: Branding) => ({ + ...b, + siteUrl: `https://x.test/${'a'.repeat(2048)}`, + }), + ], + [ + 'PNG base64 over 512 KiB', + (b: Branding) => ({ + ...b, + headerLogo: { kind: 'png', base64: 'A'.repeat(512 * 1024 + 4) }, + }), + ], + [ + 'PNG base64 with foreign characters', + (b: Branding) => ({ + ...b, + headerLogo: { kind: 'png', base64: '' }, + }), + ], + [ + 'SVG over 256 KiB', + (b: Branding) => ({ + ...b, + footerLogo: { kind: 'svg', svg: 'x'.repeat(256 * 1024 + 1) }, + }), + ], + [ + 'fallback text over 128 chars', + (b: Branding) => ({ + ...b, + poweredBy: { ...b.poweredBy!, fallbackText: 'x'.repeat(129) }, + }), + ], + [ + 'credit with unknown key', + (b: Branding) => ({ ...b, partner: { ...b.partner!, extra: true } }), + ], + ])('rejects %s', (_name, mutate) => { + expect(BrandingSchema.safeParse(mutate(sampleBranding())).success).toBe( + false, + ) + }) +}) + +describe('PdfLabelSetSchema', () => { + it('lists 25 distinct keys and accepts a complete set in both locales', () => { + expect(PDF_LABEL_KEYS).toHaveLength(25) + expect(new Set(PDF_LABEL_KEYS).size).toBe(25) + const set = { fr: sampleLabels(), en: sampleLabels() } + expect(PdfLabelSetSchema.parse(set)).toEqual(set) + }) + + it('rejects a missing key, an extra key, a long value, a missing locale', () => { + const missing: Partial = sampleLabels() + delete missing['pdf.empty'] + expect( + PdfLabelSetSchema.safeParse({ fr: missing, en: sampleLabels() }).success, + ).toBe(false) + expect( + PdfLabelSetSchema.safeParse({ + fr: { ...sampleLabels(), 'pdf.extra': 'x' }, + en: sampleLabels(), + }).success, + ).toBe(false) + expect( + PdfLabelSetSchema.safeParse({ + fr: { ...sampleLabels(), 'pdf.subject': 'x'.repeat(257) }, + en: sampleLabels(), + }).success, + ).toBe(false) + expect(PdfLabelSetSchema.safeParse({ fr: sampleLabels() }).success).toBe( + false, + ) + expect( + PdfLabelSetSchema.safeParse({ + fr: sampleLabels(), + en: sampleLabels(), + de: sampleLabels(), + }).success, + ).toBe(false) + }) +}) diff --git a/packages/domain/tests/archive.envelope.test.ts b/packages/domain/tests/archive.envelope.test.ts new file mode 100644 index 00000000..a8474a2a --- /dev/null +++ b/packages/domain/tests/archive.envelope.test.ts @@ -0,0 +1,211 @@ +import { describe, expect, it } from 'vitest' +import { + ENVELOPE_FORMAT, + ENVELOPE_VERSION, + ReportArchiveEnvelopeSchema, + UnsupportedReportVersionError, + buildSheetSnapshot, + migrateReportV2ToV3, + readArchiveDocument, + readReportDocument, + type ReportArchiveEnvelope, +} from '../src' +import fullV2 from './fixtures/report-v2.full.json' +import { sampleBranding, sampleLabels } from './archive.branding-labels.test' +import { loadDraftSheet } from './helpers/draft-sheet' +import { + leavesAsV2Report, + legacyLeaves, + loadLegacyBaseline, +} from './helpers/legacy-leaves' + +const draft = loadDraftSheet() +const map = draft.migrationMap +const { report } = readReportDocument(fullV2, map) + +/** A fresh envelope as JSON.parse of an attachment would give it. */ +function envelope(): ReportArchiveEnvelope { + const env: ReportArchiveEnvelope = { + format: ENVELOPE_FORMAT, + envelopeVersion: ENVELOPE_VERSION, + exportedAt: '2026-10-11T10:00:00.000Z', + locale: 'fr', + report, + sheetSnapshot: buildSheetSnapshot(draft, report), + branding: sampleBranding(), + labels: { fr: sampleLabels(), en: sampleLabels() }, + } + return JSON.parse(JSON.stringify(env)) as ReportArchiveEnvelope +} + +type Raw = Record +const raw = (env: ReportArchiveEnvelope): Raw => env as unknown as Raw + +describe('readArchiveDocument: bare reports', () => { + it('reads a bare v3 as is', () => { + const outcome = readArchiveDocument(JSON.parse(JSON.stringify(report)), map) + expect(outcome).toEqual({ + report, + origin: 'bare_v3', + migrated: false, + unresolvedZones: 0, + unresolvedFindings: 0, + archive: null, + }) + }) + + it('migrates a bare v2 with the counts of the migration', () => { + const outcome = readArchiveDocument(fullV2, map) + expect(outcome.origin).toBe('v2') + expect(outcome.migrated).toBe(true) + expect(outcome.archive).toBeNull() + expect(outcome.report).toEqual(report) + expect(outcome.snapshotRejected).toBeUndefined() + + const leaves = leavesAsV2Report(legacyLeaves(loadLegacyBaseline())) + const expected = migrateReportV2ToV3(leaves, map) + const migrated = readArchiveDocument(leaves, map) + expect(expected.unresolvedFindings).toBeGreaterThan(0) + expect(migrated.unresolvedFindings).toBe(expected.unresolvedFindings) + expect(migrated.unresolvedZones).toBe(expected.unresolvedZones) + expect(migrated.report).toEqual(expected.report) + }) + + it('throws for a report version it cannot read, or a non-object', () => { + expect(() => readArchiveDocument({ ...report, version: 1 }, map)).toThrow( + UnsupportedReportVersionError, + ) + for (const data of [null, undefined, 'report', 42, [report]]) { + expect(() => readArchiveDocument(data, map)).toThrow( + UnsupportedReportVersionError, + ) + } + }) +}) + +describe('readArchiveDocument: envelopes', () => { + it('accepts a valid v1 envelope whole', () => { + const env = envelope() + const outcome = readArchiveDocument(env, map) + expect(outcome.origin).toBe('envelope_v1') + expect(outcome.migrated).toBe(false) + expect(outcome.unresolvedZones).toBe(0) + expect(outcome.snapshotRejected).toBeUndefined() + expect(outcome.report).toEqual(report) + expect(outcome.archive).toEqual(env) + expect(ReportArchiveEnvelopeSchema.parse(env)).toEqual(env) + }) + + it('keeps the report of an envelope version it does not know', () => { + const outcome = readArchiveDocument( + { ...envelope(), envelopeVersion: 2 }, + map, + ) + expect(outcome.report).toEqual(report) + expect(outcome.origin).toBe('bare_v3') + expect(outcome.archive).toBeNull() + expect(outcome.snapshotRejected).toBe('unsupported_envelope') + }) + + it('names the report version when the wrapped report is unknown', () => { + const env = raw(envelope()) + env.report = { ...report, version: 4 } + let thrown: unknown + try { + readArchiveDocument(env, map) + } catch (error) { + thrown = error + } + expect(thrown).toBeInstanceOf(UnsupportedReportVersionError) + expect((thrown as UnsupportedReportVersionError).foundVersion).toBe(4) + }) + + it('ignores unknown metadata keys, __proto__ included, within v1', () => { + const env = raw(envelope()) + env.futureField = { anything: true } + const outcome = readArchiveDocument(env, map) + expect(outcome.archive).not.toBeNull() + expect('futureField' in outcome.archive!).toBe(false) + + const text = JSON.stringify(envelope()).replace( + '"format"', + '"__proto__":{"polluted":true},"format"', + ) + const polluted = readArchiveDocument(JSON.parse(text), map) + expect(polluted.archive).not.toBeNull() + expect(({} as { polluted?: boolean }).polluted).toBeUndefined() + expect(Object.hasOwn(polluted.archive!, '__proto__')).toBe(false) + }) + + it('drops the envelope on a wrapper fault (schema): branding, labels, metadata', () => { + const branding = raw(envelope()) + branding.branding = { ...sampleBranding(), siteUrl: 'javascript:alert(1)' } + expect(readArchiveDocument(branding, map)).toMatchObject({ + report, + origin: 'envelope_v1', + archive: null, + snapshotRejected: 'schema', + }) + + const labels = raw(envelope()) + labels.labels = { fr: sampleLabels() } + expect(readArchiveDocument(labels, map).snapshotRejected).toBe('schema') + + const locale = raw(envelope()) + locale.locale = 'de' + expect(readArchiveDocument(locale, map).snapshotRejected).toBe('schema') + + const format = raw(envelope()) + format.format = 'other' + expect(readArchiveDocument(format, map).snapshotRejected).toBe('schema') + }) + + it('drops a snapshot over the caps or failing its own schema', () => { + const caps = envelope() + caps.sheetSnapshot.document.name.fr = 'x'.repeat(513) + expect(readArchiveDocument(caps, map)).toMatchObject({ + report, + archive: null, + snapshotRejected: 'caps', + }) + + const schema = raw(envelope()) + schema.sheetSnapshot = { ...envelope().sheetSnapshot, extra: 1 } + expect(readArchiveDocument(schema, map).snapshotRejected).toBe('schema') + + const missing = raw(envelope()) + delete missing.sheetSnapshot + expect(readArchiveDocument(missing, map).snapshotRejected).toBe('schema') + + const integrity = envelope() + integrity.sheetSnapshot.assets = [] + expect(readArchiveDocument(integrity, map).snapshotRejected).toBe( + 'integrity', + ) + }) + + it('drops a snapshot of another sheet than the report (sheet_mismatch)', () => { + const sha = envelope() + sha.sheetSnapshot.ref.documentSha256 = 'f'.repeat(64) + expect(readArchiveDocument(sha, map)).toMatchObject({ + report, + origin: 'envelope_v1', + archive: null, + snapshotRejected: 'sheet_mismatch', + }) + + const id = envelope() + id.sheetSnapshot.ref.sheetId = 'another-sheet' + expect(readArchiveDocument(id, map).snapshotRejected).toBe('sheet_mismatch') + }) + + it('migrates a v2 report found inside an envelope and still checks the snapshot', () => { + const env = raw(envelope()) + env.report = fullV2 + const outcome = readArchiveDocument(env, map) + expect(outcome.origin).toBe('envelope_v1') + expect(outcome.migrated).toBe(true) + expect(outcome.report).toEqual(report) + expect(outcome.archive?.report).toEqual(report) + }) +}) diff --git a/packages/domain/tests/archive.snapshot.test.ts b/packages/domain/tests/archive.snapshot.test.ts new file mode 100644 index 00000000..14f59a4c --- /dev/null +++ b/packages/domain/tests/archive.snapshot.test.ts @@ -0,0 +1,366 @@ +import { describe, expect, it } from 'vitest' +import { + AnatomicalSheetDocumentSchema, + REPORT_VERSION, + SNAPSHOT_CAPS, + SnapshotError, + assertSnapshot, + buildSheetIndex, + buildSheetSnapshot, + readReportDocument, + snapshotIndexSource, + validateSheetDocument, + type Report, + type SheetSnapshot, + type SnapshotRejection, + type SnapshotSource, +} from '../src' +import { HORSE_MAIN_ASSET_ID, horseSlice } from './fixtures/horse-slice' +import fullV2 from './fixtures/report-v2.full.json' +import { loadDraftSheet } from './helpers/draft-sheet' +import { + leavesAsV2Report, + legacyLeaves, + loadLegacyBaseline, +} from './helpers/legacy-leaves' + +const SHA = 'b'.repeat(64) +const HASH = 'c'.repeat(64) +const SVG = '' + +function sliceSource(): SnapshotSource { + return { + status: 'draft', + ref: { sheetId: 'sheet-1', versionId: null, documentSha256: SHA }, + speciesId: 'equine', + schemaVersion: 2, + document: horseSlice(), + assets: { [HORSE_MAIN_ASSET_ID]: SVG }, + assetHashes: { [HORSE_MAIN_ASSET_ID]: HASH }, + } +} + +function sliceReport(): Report { + return { + version: REPORT_VERSION, + id: 'r1', + createdAt: '2026-10-10T10:00:00Z', + date: '2026-10-10', + practitioner: { name: 'Dr. Dupont' }, + animal: { speciesId: 'equine', name: 'Mistral' }, + owner: { name: 'Jean Martin' }, + sheet: { sheetId: 'sheet-1', versionId: null, documentSha256: SHA }, + observations: [ + { + id: 'obs-1', + zones: [{ annotationId: 'hip', viewId: 'view-main' }], + findings: [ + { + findingZoneId: 'hip', + path: ['hip-dysfunctions', 'articular', 'restriction-flexion'], + labelFrSnapshot: 'Restriction en flexion', + labelEnSnapshot: 'Flexion restriction', + }, + { + findingZoneId: 'hip', + path: ['hip-dysfunctions', 'articular', 'ghost-leaf'], + labelFrSnapshot: 'Disparu', + labelEnSnapshot: 'Gone', + unresolved: true, + }, + { + findingZoneId: 'sphenoid', + path: ['ssb-dysfunctions', 'physiological', 'torsion-right'], + labelFrSnapshot: 'Torsion droite', + labelEnSnapshot: 'Right torsion', + }, + ], + freeTextFindings: [], + comment: '', + }, + ], + conclusion: '', + recommendations: '', + localAnnotations: [], + } +} + +function sliceSnapshot(): SheetSnapshot { + return buildSheetSnapshot(sliceSource(), sliceReport()) +} + +function rejection(input: unknown): SnapshotRejection | 'accepted' { + try { + assertSnapshot(input) + return 'accepted' + } catch (error) { + if (error instanceof SnapshotError) return error.reason + throw error + } +} + +describe('buildSheetSnapshot on the equine draft', () => { + const draft = loadDraftSheet() + const { report } = readReportDocument(fullV2, draft.migrationMap) + const snapshot = buildSheetSnapshot(draft, report) + + it('keeps every view, annotation, category and region, empties the bibliography', () => { + expect(snapshot.document.views).toEqual(draft.document.views) + expect(snapshot.document.annotations).toEqual(draft.document.annotations) + expect(snapshot.document.categories).toEqual(draft.document.categories) + expect(snapshot.document.vertebral_config).toEqual( + draft.document.vertebral_config, + ) + expect(snapshot.document.references).toEqual([]) + expect(snapshot.document.name).toEqual(draft.document.name) + expect(snapshot.document.scope_disclaimer).toEqual( + draft.document.scope_disclaimer, + ) + expect(snapshot.document.attribution).toEqual(draft.document.attribution) + expect(snapshot.document.species_id).toBe('equine') + expect(snapshot.document.schema_version).toBe(2) + }) + + it('prunes finding trees to the paths the report uses, every zone kept', () => { + expect(snapshot.document.finding_zones.map((z) => z.id)).toEqual( + draft.document.finding_zones.map((z) => z.id), + ) + const c7 = snapshot.document.finding_zones.find((z) => z.id === 'c7-t1')! + expect(c7.categories).toHaveLength(1) + expect(c7.categories[0]).toMatchObject({ + id: 'c7-t1-dysfunctions', + kind: 'dysfunction', + description: {}, + reference_ids: [], + }) + expect(c7.categories[0]!.children.map((n) => n.id)).toEqual(['segmental']) + expect(c7.categories[0]!.children[0]!.children).toMatchObject([ + { id: 'fixation', description: {}, reference_ids: [], children: [] }, + ]) + const used = new Set( + report.observations.flatMap((o) => + o.findings.map((f) => f.findingZoneId), + ), + ) + for (const zone of snapshot.document.finding_zones) { + if (!used.has(zone.id)) expect(zone.categories, zone.id).toEqual([]) + else expect(zone.categories.length, zone.id).toBeGreaterThan(0) + } + }) + + it('carries the reachable asset with its manifest hash and the full ref', () => { + const [assetId] = Object.keys(draft.assets) + expect(snapshot.assets).toEqual([ + { + svgAssetId: assetId, + sha256: draft.assetHashes[assetId!], + svg: draft.assets[assetId!], + }, + ]) + expect(snapshot.ref).toEqual({ + ...draft.ref, + schemaVersion: 2, + speciesId: 'equine', + }) + expect(snapshot.status).toBe('draft') + }) + + it('is a valid document with no integrity error, under 250,000 bytes pretty-printed', () => { + expect(() => + AnatomicalSheetDocumentSchema.parse(snapshot.document), + ).not.toThrow() + const errors = validateSheetDocument(snapshot.document).filter( + (i) => i.severity === 'error', + ) + expect(errors).toEqual([]) + const bytes = Buffer.byteLength(JSON.stringify(snapshot, null, 2), 'utf8') + console.log( + `snapshot (report-v2.full on the draft, pretty JSON): ${bytes} bytes`, + ) + expect(bytes).toBeLessThan(250_000) + expect(assertSnapshot(snapshot)).toEqual(snapshot) + }) + + it('is pure and deterministic', () => { + const before = JSON.stringify(draft.document) + const again = buildSheetSnapshot(draft, report) + expect(JSON.stringify(draft.document)).toBe(before) + expect(again).toEqual(snapshot) + expect(again.document.views).not.toBe(draft.document.views) + }) + + it('keeps what exists of an unresolved path and nothing else (legacy leaves)', () => { + const v2 = leavesAsV2Report(legacyLeaves(loadLegacyBaseline())) + const migrated = readReportDocument(v2, draft.migrationMap) + expect(migrated.unresolvedFindings).toBeGreaterThan(0) + const snap = buildSheetSnapshot(draft, migrated.report) + expect(assertSnapshot(snap)).toEqual(snap) + const index = buildSheetIndex(snapshotIndexSource(snap)) + const findings = migrated.report.observations.flatMap((o) => o.findings) + for (const finding of findings) { + const node = index.nodeAt(finding.findingZoneId, finding.path) + if (finding.unresolved) + expect(node, finding.path.join('/')).toBeUndefined() + else expect(node, finding.path.join('/')).toBeDefined() + } + expect(index.sheet.ref.sheetId).toBe(draft.ref.sheetId) + expect(index.sheet.assets[snap.assets[0]!.svgAssetId]).toBe( + snap.assets[0]!.svg, + ) + }) +}) + +describe('buildSheetSnapshot on the slice', () => { + it('copies review_status and requires_vet_referral, skips an asset it has no text for', () => { + const snapshot = sliceSnapshot() + const hip = snapshot.document.finding_zones.find((z) => z.id === 'hip')! + expect(hip.categories.map((c) => c.id)).toEqual(['hip-dysfunctions']) + expect(hip.categories[0]!.review_status).toBe('inherited') + expect(hip.categories[0]!.children[0]!.children.map((n) => n.id)).toEqual([ + 'restriction-flexion', + ]) + const sphenoid = snapshot.document.finding_zones.find( + (z) => z.id === 'sphenoid', + )! + expect(sphenoid.categories[0]!.children[0]!.children[0]).toMatchObject({ + id: 'torsion-right', + requires_vet_referral: false, + }) + expect(snapshot.assets).toEqual([ + { svgAssetId: HORSE_MAIN_ASSET_ID, sha256: HASH, svg: SVG }, + ]) + const noHash = { ...sliceSource(), assetHashes: undefined } + expect( + buildSheetSnapshot(noHash, sliceReport()).assets[0]!.sha256, + ).toBeNull() + const noSvg = { ...sliceSource(), assets: {} } + expect(buildSheetSnapshot(noSvg, sliceReport()).assets).toEqual([]) + }) +}) + +describe('assertSnapshot', () => { + it('accepts the slice snapshot and returns the parsed copy', () => { + const snapshot = sliceSnapshot() + const parsed = assertSnapshot(JSON.parse(JSON.stringify(snapshot))) + expect(parsed).toEqual(snapshot) + }) + + it('rejects a finding tree deeper than the cap before parsing anything (caps)', () => { + let node: unknown = { id: 'leaf' } + for (let depth = 0; depth < SNAPSHOT_CAPS.findingDepth; depth += 1) { + node = { id: `n${depth}`, children: [node] } + } + const raw = { + garbage: true, + document: { finding_zones: [{ categories: [node] }] }, + } + expect(rejection(raw)).toBe('caps') + const shallow = { + document: { finding_zones: [{ categories: [{ id: 'c' }] }] }, + } + expect(rejection(shallow)).toBe('schema') + expect(rejection({ document: { finding_zones: 'x' } })).toBe('schema') + }) + + it('rejects shape faults (schema): unknown key, missing field, too many assets, non-object', () => { + expect(rejection({ ...sliceSnapshot(), extra: 1 })).toBe('schema') + const noStatus: Partial = sliceSnapshot() + delete noStatus.status + expect(rejection(noStatus)).toBe('schema') + const many = sliceSnapshot() + many.assets = Array.from({ length: 5 }, (_, i) => ({ + svgAssetId: `00000000-0000-4000-8000-00000000000${i}`, + sha256: null, + svg: SVG, + })) + expect(rejection(many)).toBe('schema') + expect(rejection(null)).toBe('schema') + expect(rejection('snapshot')).toBe('schema') + expect(rejection([sliceSnapshot()])).toBe('schema') + }) + + it('rejects a __proto__ key without polluting anything', () => { + const raw = JSON.parse( + JSON.stringify(sliceSnapshot()).replace( + '"status"', + '"__proto__":{"polluted":1},"status"', + ), + ) + expect(rejection(raw)).toBe('schema') + expect(({} as { polluted?: number }).polluted).toBeUndefined() + }) + + it('rejects counts over the caps (caps)', () => { + const views = sliceSnapshot() + views.document.views.push( + ...Array.from({ length: SNAPSHOT_CAPS.views }, (_, i) => ({ + ...views.document.views[1]!, + id: `extra-${i}`, + })), + ) + expect(rejection(views)).toBe('caps') + + const annotations = sliceSnapshot() + annotations.document.annotations.push( + ...Array.from({ length: SNAPSHOT_CAPS.annotations }, (_, i) => ({ + ...annotations.document.annotations[0]!, + id: `extra-${i}`, + })), + ) + expect(rejection(annotations)).toBe('caps') + + const nodes = sliceSnapshot() + const category = nodes.document.finding_zones[0]!.categories[0]! + category.children = Array.from( + { length: SNAPSHOT_CAPS.findingNodes }, + (_, i) => ({ + id: `leaf-${i}`, + name: { fr: 'x', en: 'x' }, + description: {}, + requires_vet_referral: false, + reference_ids: [], + review_status: 'inherited', + children: [], + }), + ) + expect(rejection(nodes)).toBe('caps') + + const label = sliceSnapshot() + label.document.name.fr = 'x'.repeat(SNAPSHOT_CAPS.labelChars + 1) + expect(rejection(label)).toBe('caps') + }) + + it('rejects oversize assets in bytes, single and total (caps)', () => { + const big = sliceSnapshot() + // 1.1M two-byte code points: under the schema's char cap, over 2 MiB. + big.assets[0]!.svg = 'é'.repeat(1_100_000) + expect(rejection(big)).toBe('caps') + + const total = sliceSnapshot() + total.assets = Array.from({ length: 4 }, (_, i) => ({ + svgAssetId: + i === 0 + ? HORSE_MAIN_ASSET_ID + : `00000000-0000-4000-8000-00000000000${i}`, + sha256: null, + svg: 'a'.repeat(1_600_000), + })) + expect(rejection(total)).toBe('caps') + }) + + it('rejects integrity faults: a sheet rule error, a view reaching no carried asset', () => { + const rule = sliceSnapshot() + rule.document.finding_zones = rule.document.finding_zones.filter( + (z) => z.id !== 'atm', + ) + expect(rejection(rule)).toBe('integrity') + + const noAsset = sliceSnapshot() + noAsset.assets = [] + expect(rejection(noAsset)).toBe('integrity') + + const otherAsset = sliceSnapshot() + otherAsset.assets[0]!.svgAssetId = '00000000-0000-4000-8000-000000000009' + expect(rejection(otherAsset)).toBe('integrity') + }) +}) diff --git a/packages/domain/tests/helpers/draft-sheet.ts b/packages/domain/tests/helpers/draft-sheet.ts new file mode 100644 index 00000000..98b7eed3 --- /dev/null +++ b/packages/domain/tests/helpers/draft-sheet.ts @@ -0,0 +1,73 @@ +import { readFileSync } from 'node:fs' +import { fileURLToPath } from 'node:url' +import { join, resolve } from 'node:path' +import { + AnatomicalSheetDocumentSchema, + ReportMigrationMapSchema, + type ReportMigrationMap, + type SnapshotSource, +} from '../../src' + +/** + * The committed equine draft (`pnpm import:equine`) as the application + * bundles it: document, reference, SVG assets and their manifest hashes, + * plus the v2 → v3 migration map. Read from the seed, never copied. + */ + +export const DRAFT_DIR = resolve( + fileURLToPath(import.meta.url), + '../../../../../supabase/seed/anatomical-sheets/equine/draft', +) + +interface SeedRef { + sheet_id: string + version_id: string | null + document_sha256: string + schema_version: number + species_id: string +} + +interface SeedAsset { + file: string + sha256: string + svg_asset_id: string +} + +function json(name: string): T { + return JSON.parse(readFileSync(join(DRAFT_DIR, name), 'utf8')) as T +} + +export interface DraftSheet extends SnapshotSource { + assetHashes: Readonly> + migrationMap: ReportMigrationMap +} + +export function loadDraftSheet(): DraftSheet { + const ref = json('sheet-ref.json') + const manifest = json('assets.json') + const assets: Record = {} + const assetHashes: Record = {} + for (const asset of manifest) { + assets[asset.svg_asset_id] = readFileSync( + join(DRAFT_DIR, 'assets', asset.file), + 'utf8', + ) + assetHashes[asset.svg_asset_id] = asset.sha256 + } + return { + status: 'draft', + ref: { + sheetId: ref.sheet_id, + versionId: ref.version_id, + documentSha256: ref.document_sha256, + }, + speciesId: ref.species_id, + schemaVersion: ref.schema_version, + document: AnatomicalSheetDocumentSchema.parse(json('document.json')), + assets, + assetHashes, + migrationMap: ReportMigrationMapSchema.parse( + json('report-migration-map.json'), + ), + } +} diff --git a/packages/domain/tests/helpers/legacy-leaves.ts b/packages/domain/tests/helpers/legacy-leaves.ts new file mode 100644 index 00000000..27608dce --- /dev/null +++ b/packages/domain/tests/helpers/legacy-leaves.ts @@ -0,0 +1,95 @@ +import { readFileSync } from 'node:fs' +import { fileURLToPath } from 'node:url' +import { resolve } from 'node:path' +import { + AnatomicalSheetDocumentSchema, + ReportV2Schema, + type AnatomicalSheetDocument, + type FindingCategory, + type FindingNode, + type ObservationV2, + type ReportV2, +} from '../../src' + +/** + * The legacy catalog as the application's archive knew it: every leaf of the + * generated baseline (`legacy-import/document.json`) becomes a Report v2 + * finding, grouped in one observation per zone. Same recipe as the app and + * anatomy helpers; migrated through the draft map it yields the unresolved + * items (sphenoid / ssb leaves) a Phase 0 golden was frozen with. + */ + +const BASELINE = resolve( + fileURLToPath(import.meta.url), + '../../../../../supabase/seed/anatomical-sheets/equine/legacy-import/document.json', +) + +export interface LegacyLeaf { + zoneId: string + path: string[] + name: { fr: string; en: string } + vet: boolean +} + +export function loadLegacyBaseline(): AnatomicalSheetDocument { + return AnatomicalSheetDocumentSchema.parse( + JSON.parse(readFileSync(BASELINE, 'utf8')), + ) +} + +export function legacyLeaves(doc: AnatomicalSheetDocument): LegacyLeaf[] { + const out: LegacyLeaf[] = [] + const walk = ( + zoneId: string, + nodes: readonly (FindingCategory | FindingNode)[], + prefix: string[], + ) => { + for (const node of nodes) { + const path = [...prefix, node.id] + if (node.children.length > 0) walk(zoneId, node.children, path) + else { + const vet = + 'requires_vet_referral' in node && node.requires_vet_referral + out.push({ zoneId, path, name: node.name, vet }) + } + } + } + for (const zone of doc.finding_zones) walk(zone.id, zone.categories, []) + return out +} + +export function leavesAsV2Report(leaves: LegacyLeaf[]): ReportV2 { + const byZone = new Map() + for (const leaf of leaves) { + let obs = byZone.get(leaf.zoneId) + if (!obs) { + obs = { + id: `obs-${leaf.zoneId}`, + zones: [], + findings: [], + freeTextFindings: [], + comment: '', + } + byZone.set(leaf.zoneId, obs) + } + obs.findings.push({ + zoneId: leaf.zoneId, + path: leaf.path, + labelFrSnapshot: leaf.name.fr, + labelEnSnapshot: leaf.name.en || leaf.name.fr, + ...(leaf.vet ? { requiresVetReferral: true } : {}), + }) + } + return ReportV2Schema.parse({ + version: 2, + id: 'all-leaves', + createdAt: '2026-10-10T00:00:00Z', + date: '2026-10-10', + practitioner: { name: 'Synthetic' }, + animal: { speciesId: 'equine', name: 'Synthetic' }, + owner: { name: 'Synthetic' }, + observations: [...byZone.values()], + conclusion: '', + recommendations: '', + }) +} diff --git a/packages/domain/tests/report.rebase.test.ts b/packages/domain/tests/report.rebase.test.ts new file mode 100644 index 00000000..1d7860fd --- /dev/null +++ b/packages/domain/tests/report.rebase.test.ts @@ -0,0 +1,208 @@ +import { describe, expect, it } from 'vitest' +import { + REPORT_VERSION, + ReportSchema, + buildSheetIndex, + buildSheetSnapshot, + rebaseReportOnSheet, + type AnatomicalSheetDocument, + type Report, + type SheetRef, + type SnapshotSource, +} from '../src' +import { HORSE_MAIN_ASSET_ID, horseSlice } from './fixtures/horse-slice' + +const SHA_A = 'a'.repeat(64) +const SHA_B = 'b'.repeat(64) +const REF_A: SheetRef = { + sheetId: 'sheet-1', + versionId: null, + documentSha256: SHA_A, +} +const REF_B: SheetRef = { + sheetId: 'sheet-1', + versionId: 'v2', + documentSha256: SHA_B, +} + +function source( + ref: SheetRef, + document: AnatomicalSheetDocument, +): SnapshotSource { + return { + status: 'draft', + ref, + speciesId: 'equine', + schemaVersion: 2, + document, + assets: { [HORSE_MAIN_ASSET_ID]: '' }, + } +} + +/** Revision B: the TMJ marker and the head trigger are gone, hip lost its articular node. */ +function revisionB(): AnatomicalSheetDocument { + const doc = horseSlice() + doc.annotations = doc.annotations.filter( + (a) => a.id !== 'atm' && a.id !== 'head-trigger', + ) + const hip = doc.finding_zones.find((z) => z.id === 'hip')! + hip.categories[0]!.children = hip.categories[0]!.children.filter( + (n) => n.id !== 'articular', + ) + return doc +} + +function reportOnA(): Report { + return { + version: REPORT_VERSION, + id: 'r1', + createdAt: '2026-10-10T10:00:00Z', + date: '2026-10-10', + practitioner: { name: 'Dr. Dupont' }, + animal: { speciesId: 'equine', name: 'Mistral' }, + owner: { name: 'Jean Martin' }, + sheet: REF_A, + observations: [ + { + id: 'obs-1', + zones: [ + { + annotationId: 'hip', + viewId: 'view-main', + side: 'left', + labelFrSnapshot: 'Hanche (coxo-fémorale)', + labelEnSnapshot: 'Hip joint', + }, + { annotationId: 'atm', viewId: 'view-head' }, + { annotationId: 'head-trigger', viewId: 'view-main' }, + { + annotationId: 'hip', + viewId: 'ghost-view', + labelFrSnapshot: 'Gardé', + }, + { + annotationId: 'gone-long-ago', + viewId: 'view-main', + labelFrSnapshot: 'Ancien', + unresolved: true, + }, + ], + findings: [ + { + findingZoneId: 'hip', + path: ['hip-dysfunctions', 'articular', 'restriction-flexion'], + labelFrSnapshot: 'Restriction en flexion', + labelEnSnapshot: 'Flexion restriction', + }, + { + findingZoneId: 'cervical', + path: ['cervical-observations', 'stumbling-proprioceptive'], + labelFrSnapshot: 'Trébuchements', + labelEnSnapshot: 'Stumbling', + requiresVetReferral: true, + }, + { + findingZoneId: 'atm', + path: ['atm-observations', 'headshaking'], + labelFrSnapshot: 'Headshaking', + labelEnSnapshot: 'Headshaking', + unresolved: true, + }, + ], + freeTextFindings: ['note'], + severity: 'moderate', + comment: '', + }, + ], + conclusion: 'c', + recommendations: 'r', + localAnnotations: [], + } +} + +const indexA = buildSheetIndex(source(REF_A, horseSlice())) +const indexB = buildSheetIndex(source(REF_B, revisionB())) + +describe('rebaseReportOnSheet', () => { + it('returns the report untouched when it already sits on the loaded sheet', () => { + const report = reportOnA() + const outcome = rebaseReportOnSheet(report, indexA, null) + expect(outcome).toEqual({ + report, + unresolvedZones: 0, + unresolvedFindings: 0, + rebased: false, + }) + expect(outcome.report).toBe(report) + }) + + it('flags what the new sheet lost, labels it from the archive, keeps the rest', () => { + const report = reportOnA() + const archived = buildSheetSnapshot(source(REF_A, horseSlice()), report) + const outcome = rebaseReportOnSheet(report, indexB, archived) + expect(outcome.rebased).toBe(true) + expect(outcome.unresolvedZones).toBe(3) + expect(outcome.unresolvedFindings).toBe(1) + expect(outcome.report.sheet).toEqual(REF_B) + expect(() => ReportSchema.parse(outcome.report)).not.toThrow() + + const [hip, atm, trigger, ghostView, old] = + outcome.report.observations[0]!.zones + expect(hip).toEqual(report.observations[0]!.zones[0]) + expect(atm).toEqual({ + annotationId: 'atm', + viewId: 'view-head', + unresolved: true, + labelFrSnapshot: 'Articulation Temporo-Mandibulaire (ATM)', + labelEnSnapshot: 'Temporomandibular Joint (TMJ)', + }) + expect(trigger).toEqual({ + annotationId: 'head-trigger', + viewId: 'view-main', + unresolved: true, + labelFrSnapshot: 'Tête', + labelEnSnapshot: 'Head', + }) + expect(ghostView).toEqual({ + annotationId: 'hip', + viewId: 'ghost-view', + unresolved: true, + labelFrSnapshot: 'Gardé', + labelEnSnapshot: 'Hip joint', + }) + expect(old).toEqual(report.observations[0]!.zones[4]) + + const [flexion, stumbling, headshaking] = + outcome.report.observations[0]!.findings + expect(flexion).toEqual({ + ...report.observations[0]!.findings[0], + unresolved: true, + }) + expect(stumbling).toEqual(report.observations[0]!.findings[1]) + expect(headshaking).toEqual(report.observations[0]!.findings[2]) + expect(outcome.report.observations[0]!.freeTextFindings).toEqual(['note']) + expect(report).toEqual(reportOnA()) + }) + + it('fills no label without an archived snapshot', () => { + const outcome = rebaseReportOnSheet(reportOnA(), indexB, null) + expect(outcome.report.observations[0]!.zones[1]).toEqual({ + annotationId: 'atm', + viewId: 'view-head', + unresolved: true, + }) + expect(outcome.unresolvedZones).toBe(3) + }) + + it('counts nothing twice: a rebased report rebased again onto the same sheet is stable', () => { + const first = rebaseReportOnSheet(reportOnA(), indexB, null) + const second = rebaseReportOnSheet( + { ...first.report, sheet: REF_A }, + indexB, + null, + ) + expect(second.unresolvedZones).toBe(0) + expect(second.unresolvedFindings).toBe(0) + expect(second.report).toEqual(first.report) + }) +}) diff --git a/packages/domain/tests/sheet-index.test.ts b/packages/domain/tests/sheet-index.test.ts new file mode 100644 index 00000000..13203d21 --- /dev/null +++ b/packages/domain/tests/sheet-index.test.ts @@ -0,0 +1,104 @@ +import { describe, expect, it } from 'vitest' +import { + buildSheetIndex, + isObservable, + pickLabel, + type SheetIndexSource, +} from '../src' +import { HORSE_MAIN_ASSET_ID, horseSlice } from './fixtures/horse-slice' + +const SHA = 'a'.repeat(64) + +function source() { + return { + ref: { documentSha256: SHA }, + document: horseSlice(), + assets: { [HORSE_MAIN_ASSET_ID]: '' }, + extra: 'kept by the index', + } satisfies SheetIndexSource & { extra: string } +} + +describe('buildSheetIndex', () => { + it('keeps the source as given, typed as the caller passed it', () => { + const index = buildSheetIndex(source()) + expect(index.sheet.extra).toBe('kept by the index') + expect(index.sheet.ref.documentSha256).toBe(SHA) + expect(index.mainView.id).toBe('view-main') + expect(index.view('view-head')?.kind).toBe('detail') + expect(index.view('nowhere')).toBeUndefined() + }) + + it('looks up annotations, zones, regions and spine markers by id', () => { + const index = buildSheetIndex(source()) + expect(index.annotation('hip')?.kind).toBe('point') + expect(index.annotationsOfView('view-head').map((a) => a.id)).toContain( + 'atm', + ) + expect(index.findingZone('cervical')?.name.en).toBe('Cervical Vertebrae') + expect(index.regions().map((r) => r.code)).toEqual([ + 'C', + 'T', + 'L', + 'S', + 'Cd', + ]) + expect(index.region('Cd')?.count_range).toEqual({ min: 15, max: 21 }) + expect(index.spineAnnotation('C', 'view-main')?.id).toBe( + 'cervical-vertebrae', + ) + expect(index.spineAnnotation('C', 'view-head')).toBeUndefined() + expect(index.isSpine('cervical-vertebrae')).toBe(true) + expect(index.isSpine('hip')).toBe(false) + expect(index.isSpine('head-trigger')).toBe(false) + }) + + it('resolves finding paths and reports absent ones', () => { + const index = buildSheetIndex(source()) + expect( + index.nodeAt('hip', [ + 'hip-dysfunctions', + 'articular', + 'restriction-flexion', + ])?.name.fr, + ).toBe('Restriction en flexion') + expect(index.nodeAt('hip', ['hip-dysfunctions'])?.name.fr).toBe( + 'Dysfonctions ostéopathiques', + ) + expect(index.nodeAt('hip', ['hip-dysfunctions', 'ghost'])).toBeUndefined() + expect(index.nodeAt('nowhere', ['x'])).toBeUndefined() + expect(index.nodeAt('hip', [])).toBeUndefined() + }) + + it('names a nameless trigger after the view it opens', () => { + const index = buildSheetIndex(source()) + expect(index.name(index.annotation('head-trigger')!)).toEqual({ + fr: 'Tête', + en: 'Head', + }) + expect(index.name(index.annotation('hip')!).en).toBe('Hip joint') + }) + + it('refuses a document without a main view', () => { + const src = source() + src.document.views = src.document.views.filter((v) => v.kind !== 'main') + expect(() => buildSheetIndex(src)).toThrow('no main view') + }) +}) + +describe('pickLabel / isObservable', () => { + it('falls back to the other locale and to the empty string', () => { + expect(pickLabel({ fr: 'Hanche', en: 'Hip' }, 'fr')).toBe('Hanche') + expect(pickLabel({ fr: 'Hanche', en: 'Hip' }, 'en')).toBe('Hip') + expect(pickLabel({ fr: 'Hanche', en: '' }, 'en')).toBe('Hanche') + expect(pickLabel({ fr: '', en: 'Hip' }, 'fr')).toBe('Hip') + expect(pickLabel(null, 'fr')).toBe('') + expect(pickLabel(undefined, 'en')).toBe('') + }) + + it('tells observable annotations from triggers', () => { + const index = buildSheetIndex(source()) + expect(isObservable(index.annotation('hip'))).toBe(true) + expect(isObservable(index.annotation('head-trigger'))).toBe(false) + expect(isObservable(undefined)).toBe(false) + }) +})