feat(domain): sheet document schema v2 — references registry, review_status, vertebral count_range; SQL gate + pgTAP 008

This commit is contained in:
bchanot committed 2026-10-09 16:30:58 +02:00
1 parent 6c5b2b7754
commit 3dbbfdf1df
19 files changed
+474 -71

No files matched your search

@@ -27,6 +27,7 @@ export function createEmptySheetDocument(
scope_disclaimer: {},
attribution: { authors: [], license: null, notes: null },
vertebral_config: { regions: [] },
references: [],
categories: [],
views: [
{
+51 -12
View File
@@ -1,16 +1,21 @@
import { z } from 'zod'
/**
* Canonical anatomical sheet document, schema_version 1.
* Canonical anatomical sheet document, schema_version 2.
*
* Shape contract of docs/development/ANATOMICAL_SHEET_MODEL.md §2. Every
* object is strict: a canonical document must not silently carry fields no
* version of the schema defines. Cross-references (view ids, zone ids…) are
* checked by validateSheetDocument, not here, so a draft with dangling
* references can still be saved.
* version of the schema defines. Cross-references (view ids, zone ids,
* reference ids…) are checked by validateSheetDocument, not here, so a
* draft with dangling references can still be saved.
*
* Version 2 (Step 4c): shared bibliographic `references` registry cited by
* `reference_ids`, `review_status` on findings and annotations, optional
* `count_range` on vertebral regions. No version 1 document was ever
* published, so version 1 is not read any more.
*/
export const SHEET_DOCUMENT_SCHEMA_VERSION = 1
export const SHEET_DOCUMENT_SCHEMA_VERSION = 2
/** Ids are never derived from labels, so translations never move them. */
export const STABLE_ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/
@@ -30,11 +35,29 @@ export const LocalizedOptionalTextSchema = z
.object({ fr: z.string().optional(), en: z.string().optional() })
.strict()
/**
* How far the sheet content was checked against references. `inherited` =
* taken over from a previous source without review; `reviewed` = checked
* and cited; `to_confirm` = changed or added on documented grounds, still
* awaiting a professional's confirmation.
*/
export const ReviewStatusSchema = z.enum(['inherited', 'reviewed', 'to_confirm'])
const CountRangeSchema = z
.object({ min: z.number().int().min(1), max: z.number().int().min(1) })
.strict()
/**
* `count` is the usual number of vertebrae (what the picker shows by
* default); `count_range` states the documented individual variation so a
* report may record a vertebra beyond the usual count. Null = no variation.
*/
export const VertebralRegionSchema = z
.object({
code: RegionCodeSchema,
name: LocalizedTextSchema,
count: z.number().int().min(1),
count_range: CountRangeSchema.nullable().default(null),
})
.strict()
@@ -125,6 +148,7 @@ const annotationCommon = {
category_id: StableIdSchema,
laterality: LateralitySchema,
geometry: GeometrySchema.nullable(),
review_status: ReviewStatusSchema.default('inherited'),
}
/** Observable annotations link to findings through one explicit field. */
@@ -165,15 +189,24 @@ const HttpUrlSchema = z
.url()
.refine((url) => /^https?:\/\//i.test(url), 'http(s) URL expected')
export const SourceRefSchema = z
/**
* One bibliographic reference, declared once in the document and cited by
* id from any number of findings (an anatomy atlas backs hundreds of
* entries). `citation` is the human-readable form (author, title, edition,
* year, publisher or journal, location in the work when known).
*/
export const ReferenceSchema = z
.object({
type: z.enum(['manual', 'journal', 'database', 'web']),
id: StableIdSchema,
type: z.enum(['book', 'journal', 'standard', 'legal', 'web', 'manual']),
citation: z.string().min(1),
url: HttpUrlSchema.optional(),
url: HttpUrlSchema.nullable().default(null),
doi: z.string().min(1).nullable().default(null),
})
.strict()
export type SourceRef = z.infer<typeof SourceRefSchema>
export type Reference = z.infer<typeof ReferenceSchema>
export type ReviewStatus = z.infer<typeof ReviewStatusSchema>
export type LocalizedText = z.infer<typeof LocalizedTextSchema>
export type LocalizedOptionalText = z.infer<typeof LocalizedOptionalTextSchema>
@@ -183,7 +216,8 @@ export interface FindingNode {
name: LocalizedText
description: LocalizedOptionalText
requires_vet_referral: boolean
sources: SourceRef[]
reference_ids: string[]
review_status: ReviewStatus
children: FindingNode[]
}
@@ -193,7 +227,8 @@ export interface FindingNodeInput {
name: LocalizedText
description?: LocalizedOptionalText
requires_vet_referral?: boolean
sources?: SourceRef[]
reference_ids?: string[]
review_status?: ReviewStatus
children?: FindingNodeInput[]
}
@@ -208,7 +243,8 @@ export const FindingNodeSchema: z.ZodType<
name: LocalizedTextSchema,
description: LocalizedOptionalTextSchema.default({}),
requires_vet_referral: z.boolean().default(false),
sources: z.array(SourceRefSchema).default([]),
reference_ids: z.array(StableIdSchema).default([]),
review_status: ReviewStatusSchema.default('inherited'),
children: z.array(FindingNodeSchema).default([]),
})
.strict(),
@@ -228,6 +264,8 @@ export const FindingCategorySchema = z
kind: FindingCategoryKindSchema,
name: LocalizedTextSchema,
description: LocalizedOptionalTextSchema.default({}),
reference_ids: z.array(StableIdSchema).default([]),
review_status: ReviewStatusSchema.default('inherited'),
children: z.array(FindingNodeSchema),
})
.strict()
@@ -261,6 +299,7 @@ export const AnatomicalSheetDocumentSchema = z
scope_disclaimer: LocalizedOptionalTextSchema,
attribution: AttributionSchema,
vertebral_config: VertebralConfigSchema,
references: z.array(ReferenceSchema),
categories: z.array(AnnotationCategorySchema),
views: z.array(SheetViewSchema),
annotations: z.array(AnnotationSchema),
@@ -3,6 +3,7 @@ import type {
Annotation,
FindingNode,
SheetView,
VertebralRegion,
} from './schema'
/**
@@ -32,6 +33,7 @@ type DetailView = Extract<SheetView, { kind: 'detail' }>
/** A sibling level of the finding tree: categories or node children. */
interface FindingLevelItem {
id: string
reference_ids: readonly string[]
children: readonly FindingNode[]
}
@@ -372,6 +374,69 @@ const checkFindingZonesReferenced: Rule = (doc) => {
)
}
const checkReferenceIdsUnique: Rule = (doc) =>
duplicateIssues(
doc.references.map((reference) => reference.id),
'reference.id.duplicate',
(index) => `references[${index}].id`,
)
/** A citation must point at a declared reference, at every depth. */
function citationIssues(
nodes: readonly FindingLevelItem[],
path: string,
known: ReadonlySet<string>,
): SheetIssue[] {
return nodes.flatMap((node, index) => {
const own = node.reference_ids.flatMap((id, refIndex) =>
known.has(id)
? []
: [
error(
'finding.reference.missing',
`${path}[${index}].reference_ids[${refIndex}]`,
`Reference "${id}" is not declared in references`,
),
],
)
const nested = citationIssues(
node.children,
`${path}[${index}].children`,
known,
)
return [...own, ...nested]
})
}
const checkFindingReferences: Rule = (doc) => {
const known = new Set(doc.references.map((reference) => reference.id))
return doc.finding_zones.flatMap((zone, index) =>
citationIssues(
zone.categories,
`finding_zones[${index}].categories`,
known,
),
)
}
/** The usual count must sit inside the documented variation. */
function countRangeIssue(region: VertebralRegion, index: number): SheetIssue[] {
const range = region.count_range
if (range === null) return []
if (range.min <= region.count && region.count <= range.max) return []
return [
error(
'region.count_range.invalid',
`vertebral_config.regions[${index}].count_range`,
`Region "${region.code}": count ${region.count} outside ` +
`${range.min}–${range.max}`,
),
]
}
const checkRegionCountRanges: Rule = (doc) =>
doc.vertebral_config.regions.flatMap(countRangeIssue)
const RULES: readonly Rule[] = [
checkMainViewCount,
checkViewIdsUnique,
@@ -391,6 +456,9 @@ const RULES: readonly Rule[] = [
checkFindingZoneIdsUnique,
checkFindingSiblings,
checkFindingZonesReferenced,
checkReferenceIdsUnique,
checkFindingReferences,
checkRegionCountRanges,
]
/** Lists every integrity issue of a shape-valid document. */