feat(domain): archive contracts — sheet snapshot (lean document, caps, integrity), envelope v1 layered reader, branding and label schemas, report rebase, sheet index moved from the app; bundle carries asset hashes

This commit is contained in:
bchanot committed 2026-10-11 12:30:57 +02:00
1 parent 8b86b926c8
commit cdc0943f35
25 files changed
+2253 -116

No files matched your search

+1
View File
@@ -57,6 +57,7 @@ function loadSheet(): SheetIndex {
document: json('document.json'),
migrationMap: json('report-migration-map.json'),
assets: {},
assetHashes: {},
}),
)
}
+7 -109
View File
@@ -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<LoadedSheet>
+8
View File
@@ -28,15 +28,21 @@ export interface BundledSheetData {
document: unknown
migrationMap: unknown
assets: Record<string, string>
/** sha256 by `svg_asset_id`, from the seed manifest. */
assetHashes: Record<string, string>
}
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<Record<string, string>>
/** sha256 by `svg_asset_id`; carried into a report archive as provenance. */
assetHashes: Readonly<Record<string, string>>
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,
}
}
+27 -3
View File
@@ -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', () => {
+8 -1
View File
@@ -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<string, string>
assetHashes: Record<string, string>
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<string, string> = {}
const assetHashes: Record<string, string> = {}
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`
},