feat(anatomy): curation pipeline — changeset schema, applier with before/after records, cleaned single asset, draft seed, changelog + review report generators; seed layout legacy-import/curation/draft

This commit is contained in:
bchanot committed 2026-10-09 16:50:08 +02:00
1 parent 3dbbfdf1df
commit 6870d87910
58 files changed
+18167 -267

No files matched your search

+88 -27
View File
@@ -1,55 +1,116 @@
/**
* Generates supabase/seed/anatomical-sheets/equine/v1/ from the legacy
* equine sources: canonical draft document, legacy id map, import report,
* byte-identical SVG assets with their manifest, and the SQL seed.
* Generates the two GENERATED folders of the official equine sheet from
* the legacy sources and the AUTHORED curation files:
*
* supabase/seed/anatomical-sheets/equine/legacy-import/ baseline
* supabase/seed/anatomical-sheets/equine/draft/ working revision
*
* pnpm import:equine (from the repository root)
*
* Output is byte-identical across runs; commit it and review the report.
* Output is byte-identical across runs; files a run no longer produces are
* removed from those two folders. Commit the result and review the reports.
*/
import { copyFile, mkdir, writeFile } from 'node:fs/promises'
import { join } from 'node:path'
import { copyFile, mkdir, readdir, rm, writeFile } from 'node:fs/promises'
import { dirname, join } from 'node:path'
import { fileURLToPath } from 'node:url'
import {
EQUINE_SEED_DIR,
buildEquineDraft,
EQUINE_DRAFT_DIR,
EQUINE_LEGACY_IMPORT_DIR,
EQUINE_SOURCE_PATHS,
HEAD_VIEW_ID,
importEquineLegacy,
parseViewBox,
readEquineCuration,
readEquineSources,
renderArtifacts,
} from '../legacy'
renderDraftArtifacts,
type DraftResult,
type ImportResult,
} from '../index'
const REPO_ROOT = fileURLToPath(new URL('../../../../', import.meta.url))
async function writeTextArtifacts(dir: string, files: Record<string, string>) {
for (const [name, text] of Object.entries(files)) {
await writeFile(join(dir, name), text, 'utf8')
/** File contents by path relative to a generated folder. */
type FolderFiles = Record<string, string | { copyFrom: string }>
async function writeFolder(dir: string, files: FolderFiles): Promise<void> {
for (const [name, content] of Object.entries(files)) {
const path = join(dir, name)
await mkdir(dirname(path), { recursive: true })
if (typeof content === 'string') await writeFile(path, content, 'utf8')
else await copyFile(join(REPO_ROOT, content.copyFrom), path)
}
}
async function copyAssets(dir: string): Promise<void> {
const assetsDir = join(dir, 'assets')
await mkdir(assetsDir, { recursive: true })
/** Removes what this run did not produce, inside the folder only. */
async function removeStale(dir: string, files: FolderFiles): Promise<void> {
const entries = await readdir(dir, { recursive: true, withFileTypes: true })
for (const entry of entries) {
if (!entry.isFile()) continue
const path = join(entry.parentPath, entry.name)
const name = path.slice(dir.length + 1)
if (!(name in files)) await rm(path)
}
}
async function generate(folder: string, files: FolderFiles): Promise<void> {
const dir = join(REPO_ROOT, folder)
await writeFolder(dir, files)
await removeStale(dir, files)
}
function legacyAssets(): FolderFiles {
const files: FolderFiles = {}
for (const source of [
EQUINE_SOURCE_PATHS.mainSvg,
EQUINE_SOURCE_PATHS.headSvg,
]) {
const name = source.slice(source.lastIndexOf('/') + 1)
await copyFile(join(REPO_ROOT, source), join(assetsDir, name))
files[`assets/${source.slice(source.lastIndexOf('/') + 1)}`] = {
copyFrom: source,
}
}
return files
}
function legacySummary(result: ImportResult): string {
const errors = result.issues.filter((i) => i.severity === 'error').length
return (
`${EQUINE_LEGACY_IMPORT_DIR}: ${result.stats.annotations} annotations, ` +
`${result.stats.nodes} nodes, ${result.anomalies.length} anomalies, ` +
`${errors} integrity errors, ${result.issues.length - errors} warnings`
)
}
function draftSummary(draft: DraftResult): string {
const changes = draft.changes.length
return (
`${EQUINE_DRAFT_DIR}: ${changes} changes (CHG-000 included), ` +
`${draft.records.length} records, ${draft.statsAfter.nodes} nodes, ` +
`${draft.assets.length} asset, 0 integrity errors, ${draft.issues.length} warnings`
)
}
async function main(): Promise<void> {
const result = importEquineLegacy(await readEquineSources(REPO_ROOT))
const dir = join(REPO_ROOT, EQUINE_SEED_DIR)
await mkdir(dir, { recursive: true })
await writeTextArtifacts(dir, await renderArtifacts(result))
await copyAssets(dir)
const errors = result.issues.filter((i) => i.severity === 'error').length
console.log(
`${EQUINE_SEED_DIR}: ${result.stats.annotations} annotations, ` +
`${result.stats.nodes} nodes, ${result.anomalies.length} anomalies, ` +
`${errors} integrity errors, ${result.issues.length - errors} warnings`,
)
const input = await readEquineSources(REPO_ROOT)
const result = importEquineLegacy(input)
const curation = await readEquineCuration(REPO_ROOT)
const draft = buildEquineDraft({
importResult: result,
legacyMainSvgBytes: input.mainSvg.bytes,
headViewBox: parseViewBox(result.viewBoxes[HEAD_VIEW_ID] ?? null),
...curation,
})
await generate(EQUINE_LEGACY_IMPORT_DIR, {
...(await renderArtifacts(result)),
...legacyAssets(),
})
await generate(EQUINE_DRAFT_DIR, {
...(await renderDraftArtifacts(draft, result.anomalies)),
[`assets/${draft.assets[0]!.file}`]: draft.cleanedSvg,
})
console.log(legacySummary(result))
console.log(draftSummary(draft))
}
main().catch((error: unknown) => {
+76
View File
@@ -0,0 +1,76 @@
import {
AnatomicalSheetDocumentSchema,
validateSheetDocument,
type AnatomicalSheetDocumentInput,
type Reference,
type SheetIssue,
} from '@faunosteo/domain'
import { applyOp, assertDeclared } from './ops'
import { changeSummary, type Change, type Changeset } from './schema'
import type { Item } from './targets'
import type { ChangeRecord, CurationResult } from './types'
/**
* Applies a changeset on a baseline document, deterministically and with a
* record per elementary edit. The references file replaces the document
* registry first (it is the source of truth). Any op that cannot apply
* exactly as written, and any integrity error left at the end, throws:
* a curated document is never produced from a partially applied changeset.
*/
function applyChange(doc: Item, change: Change, records: ChangeRecord[]) {
const summarised = changeSummary(change)
try {
assertDeclared(doc, change.reference_ids)
} catch (error) {
throw new Error(`${change.id}: ${(error as Error).message}`)
}
change.ops.forEach((op, index) => {
try {
applyOp({ doc, change: summarised, op, records })
} catch (error) {
throw new Error(`${change.id} op ${index}: ${(error as Error).message}`)
}
})
}
function describe(issues: readonly { path: string; message: string }[]) {
return issues.map((issue) => `${issue.path}: ${issue.message}`).join('; ')
}
/**
* Shape (Zod) then integrity check of a curated document. Throws on any
* shape issue or integrity error; returns the warnings, which are allowed.
*/
export function curatedIssues(doc: AnatomicalSheetDocumentInput): SheetIssue[] {
const parsed = AnatomicalSheetDocumentSchema.safeParse(doc)
if (!parsed.success) {
const issues = parsed.error.issues.map((issue) => ({
path: issue.path.join('.'),
message: issue.message,
}))
throw new Error(`curated document is not shape-valid: ${describe(issues)}`)
}
const issues = validateSheetDocument(parsed.data)
const errors = issues.filter((issue) => issue.severity === 'error')
if (errors.length > 0) {
throw new Error(
`curated document has integrity errors: ${describe(errors)}`,
)
}
return issues
}
export function applyChangeset(
baseline: AnatomicalSheetDocumentInput,
references: readonly Reference[],
changeset: Changeset,
): CurationResult {
const doc = structuredClone(baseline) as unknown as Item
doc.references = structuredClone(references)
const records: ChangeRecord[] = []
for (const change of changeset.changes) applyChange(doc, change, records)
const document = doc as unknown as AnatomicalSheetDocumentInput
curatedIssues(document)
return { document, records }
}
+59
View File
@@ -0,0 +1,59 @@
import { DOMParser, XMLSerializer, type Element } from '@xmldom/xmldom'
import type { ViewBox } from '@faunosteo/domain'
import { assetIdFromSha256, sha256Hex } from '../legacy/ids'
import type { AssetRecord } from '../legacy/types'
/**
* The curated sheet draws one clean anatomy: the legacy annotation layer
* (hitboxes, visual markers, the head detail-zone) now lives in the
* document as data, so every element carrying data-anno-id leaves the
* drawing. Everything else is serialised back untouched (xmldom keeps the
* declaration, attribute order and whitespace).
*/
export const CLEANED_ASSET_FILE = 'horse.svg'
/** Sizing the legacy app inlined on the root; the app sizes the drawing now. */
const LEGACY_ROOT_STYLE = 'width: 100%; height: auto; max-width: 100%;'
function annotatedElements(root: Element): Element[] {
const all = Array.from(root.getElementsByTagName('*'))
return all.filter((element) => element.hasAttribute('data-anno-id'))
}
export function stripLegacyAnnotations(svgText: string): string {
const doc = new DOMParser().parseFromString(svgText, 'image/svg+xml')
const root = doc.documentElement
if (!root || root.tagName !== 'svg') throw new Error('not an SVG document')
for (const element of annotatedElements(root)) {
element.parentNode?.removeChild(element)
}
if (root.getAttribute('style') === LEGACY_ROOT_STYLE) {
root.removeAttribute('style')
}
return new XMLSerializer().serializeToString(doc)
}
/** Manifest entry of the cleaned drawing; id derived from its sha256. */
export function cleanedAsset(bytes: Uint8Array): AssetRecord {
const sha256 = sha256Hex(bytes)
return {
file: CLEANED_ASSET_FILE,
sha256,
byte_size: bytes.byteLength,
svg_asset_id: assetIdFromSha256(sha256),
}
}
/** SVG viewBox attribute ("minX minY width height") → document view_box. */
export function parseViewBox(raw: string | null): ViewBox {
const numbers = (raw ?? '')
.trim()
.split(/[\s,]+/)
.map(Number)
const [min_x, min_y, width, height] = numbers
if (numbers.length !== 4 || numbers.some((n) => !Number.isFinite(n))) {
throw new Error(`invalid viewBox "${raw}"`)
}
return { min_x: min_x!, min_y: min_y!, width: width!, height: height! }
}
+108
View File
@@ -0,0 +1,108 @@
import { code, table } from '../markdown'
import { KIND_LABELS, LEVEL_LABELS, LEVELS } from './labels'
import { needsConfirmation, type ChangeLevel } from './schema'
import { statRows, type DocumentStats } from './stats'
import { isItem } from './targets'
import type { ChangeRecord } from './types'
/**
* French CHANGELOG of the working revision: volumes before / after, then
* one table per change level with every elementary edit. Pure formatting
* of the records, deterministic (no dates).
*/
const MAX_VALUE_LENGTH = 120
function isLabel(value: unknown): value is Record<string, string> {
if (!isItem(value)) return false
const entries = Object.entries(value)
return (
entries.length > 0 &&
entries.every(
([k, v]) => (k === 'fr' || k === 'en') && typeof v === 'string',
)
)
}
/** Compact text of a recorded value: labels as text, objects as JSON. */
export function compactValue(value: unknown): string {
let text: string
if (typeof value === 'string') text = value
else if (isLabel(value)) text = Object.values(value).join(' / ')
else text = JSON.stringify(value)
if (text.length <= MAX_VALUE_LENGTH) return text
return `${text.slice(0, MAX_VALUE_LENGTH - 1)}…`
}
export function recordSubject(record: ChangeRecord): string {
return record.field === null
? record.target
: `${record.target}.${record.field}`
}
function recordRow(record: ChangeRecord): string[] {
const { change } = record
return [
`${code(change.id)} ${change.title.fr}`,
code(recordSubject(record)),
compactValue(record.before),
compactValue(record.after),
KIND_LABELS[change.kind],
change.rationale,
change.reference_ids.map(code).join(', ') || '-',
needsConfirmation(change.level) ? 'oui' : 'non',
]
}
function levelSection(level: ChangeLevel, records: readonly ChangeRecord[]) {
const rows = records.filter((r) => r.change.level === level).map(recordRow)
const head = [
'Changement',
'Objet',
'Avant',
'Après',
'Nature',
'Justification',
'Références',
'Confirmation requise',
]
const body =
rows.length === 0 ? 'Aucun changement de ce niveau.' : table(head, rows)
return `## ${LEVEL_LABELS[level]}\n\n${body}`
}
function comparison(before: DocumentStats, after: DocumentStats): string {
const afterRows = new Map(statRows(after))
const rows = statRows(before).map(([label, value]) => [
label,
value,
afterRows.get(label) ?? 0,
])
return `## Comparaison quantitative\n\n${table(['Indicateur', 'Avant', 'Après'], rows)}`
}
function intro(): string {
return [
'# Journal des changements : révision de travail',
'',
'Généré par `pnpm import:equine` : import historique (`legacy-import/`) ' +
'puis changements rédigés (`curation/changes.json`). Ne pas modifier ' +
'à la main : relancer la commande.',
'',
'Niveaux : A = erreur démontrée, B = amélioration étayée, C = point ' +
'incertain. Les niveaux B et C demandent une confirmation professionnelle.',
].join('\n')
}
export function renderChangelog(
result: { records: readonly ChangeRecord[] },
before: DocumentStats,
after: DocumentStats,
): string {
const sections = [
intro(),
comparison(before, after),
...LEVELS.map((level) => levelSection(level, result.records)),
]
return `${sections.join('\n\n')}\n`
}
+79
View File
@@ -0,0 +1,79 @@
import { isItem, type Item, type ParsedTarget } from './targets'
/**
* Fields a `set` may write, per kind of item. Ids are left out on purpose:
* an id changes through `rename`, which also rewrites every reference to
* it. Unlisted field → the op fails instead of writing a stray key.
*/
const SETTABLE: Record<string, readonly string[]> = {
document: ['name', 'description', 'scope_disclaimer', 'attribution'],
region: ['name', 'count', 'count_range'],
reference: ['type', 'citation', 'url', 'doi'],
category: ['name', 'color'],
view: ['name', 'svg_asset_id', 'view_box', 'parent_view_id'],
annotation: [
'name',
'kind',
'view_id',
'category_id',
'laterality',
'geometry',
'review_status',
'finding_zone_id',
'vertebral_region_code',
'opens_view_id',
],
zone: ['name'],
finding_category: [
'kind',
'name',
'description',
'reference_ids',
'review_status',
],
finding_node: [
'name',
'description',
'requires_vet_referral',
'reference_ids',
'review_status',
],
}
export function splitField(field: string): string[] {
const path = field.split('.')
if (path.includes('')) throw new Error(`malformed field "${field}"`)
return path
}
/** Item kind of the settable table; a finding is a category or a node. */
export function fieldKind(target: ParsedTarget, isCategory?: boolean): string {
if (target.kind !== 'finding') return target.kind
const category = isCategory ?? target.ids.length === 2
return category ? 'finding_category' : 'finding_node'
}
export function isSettable(kind: string, field: string): boolean {
return SETTABLE[kind]?.includes(splitField(field)[0]!) ?? false
}
export function readField(item: Item, field: string): unknown {
let value: unknown = item
for (const key of splitField(field)) {
if (!isItem(value)) return undefined
value = value[key]
}
return value
}
/** Writes a deep copy of value; missing intermediate objects are created. */
export function writeField(item: Item, field: string, value: unknown): void {
const path = splitField(field)
let holder = item
for (const key of path.slice(0, -1)) {
if (!isItem(holder[key])) holder[key] = {}
holder = holder[key] as Item
}
holder[path[path.length - 1]!] = structuredClone(value)
}
+39
View File
@@ -0,0 +1,39 @@
export { applyChangeset, curatedIssues } from './apply'
export {
CLEANED_ASSET_FILE,
cleanedAsset,
parseViewBox,
stripLegacyAnnotations,
} from './assets'
export { compactValue, renderChangelog } from './changelog'
export {
buildEquineDraft,
DRAFT_SEED_SQL_FILE,
renderDraftArtifacts,
type DraftInput,
type DraftResult,
} from './pipeline'
export { renderReviewReport, type ReviewReportInput } from './review-report'
export {
ASSET_CHANGE_ID,
ChangeSchema,
ChangesetSchema,
OpSchema,
ReferencesFileSchema,
needsConfirmation,
} from './schema'
export type * from './schema'
export {
DOCUMENT_DOLLAR_TAG,
DRAFT_CHANGE_NOTE,
renderDraftSeedSql,
type DraftSeedParams,
} from './seed'
export {
CURATION_FILES,
readEquineCuration,
type CurationInput,
} from './sources'
export { documentStats, statRows, type DocumentStats } from './stats'
export { parseTarget, formatTarget } from './targets'
export type { ChangeRecord, CurationResult } from './types'
+29
View File
@@ -0,0 +1,29 @@
import type { ChangeKind, ChangeLevel, ChangePriority } from './schema'
/** French labels shared by the CHANGELOG and the review report. */
export const KIND_LABELS: Record<ChangeKind, string> = {
correction: 'Correction',
terminology: 'Terminologie',
translation: 'Traduction',
restructure: 'Réorganisation',
enrichment: 'Ajout',
reference: 'Référence',
geometry: 'Géométrie',
removal: 'Suppression',
technical: 'Technique',
}
export const LEVEL_LABELS: Record<ChangeLevel, string> = {
A: 'Niveau A : erreurs démontrées',
B: 'Niveau B : améliorations étayées (confirmation requise)',
C: 'Niveau C : points incertains (question au professionnel)',
}
export const PRIORITY_LABELS: Record<ChangePriority, string> = {
high: 'haute',
medium: 'moyenne',
low: 'basse',
}
export const LEVELS: readonly ChangeLevel[] = ['A', 'B', 'C']
+200
View File
@@ -0,0 +1,200 @@
import { isDeepStrictEqual } from 'node:util'
import { fieldKind, isSettable, readField, writeField } from './fields'
import { propagateRename } from './rename'
import type { Op, Position } from './schema'
import {
childList,
childPrefix,
findingScope,
isItem,
keyField,
locate,
topCollection,
type Item,
type Located,
type TargetKind,
} from './targets'
import { record, type OpContext } from './types'
/**
* The six op kinds of a change. Each one resolves its target, edits the
* working document in place and records what it changed; anything it
* cannot do exactly as written throws (the caller adds change id and op
* index to the message).
*/
type OpOf<K extends Op['op']> = Extract<Op, { op: K }>
const COLLECTION_KIND: Record<string, TargetKind> = {
references: 'reference',
categories: 'category',
views: 'view',
annotations: 'annotation',
finding_zones: 'zone',
regions: 'region',
}
function assertFree(list: Item[], key: string, id: string, self?: Item) {
if (list.some((entry) => entry !== self && entry[key] === id)) {
throw new Error(`"${id}" already exists among its siblings`)
}
}
function insertionIndex(list: Item[], key: string, position?: Position) {
if (position === undefined) return list.length
if (typeof position === 'number') {
if (position > list.length)
throw new Error(`position ${position} out of range`)
return position
}
const anchor = 'after' in position ? position.after : position.before
const index = list.findIndex((entry) => entry[key] === anchor)
if (index < 0) throw new Error(`unknown sibling "${anchor}"`)
return 'after' in position ? index + 1 : index
}
function unknownField(op: OpOf<'set'>): Error {
return new Error(`unknown field "${op.field}" on "${op.target}"`)
}
function setSelf(ctx: OpContext, located: Located, op: OpOf<'set'>) {
if (!isSettable(fieldKind(located.target), op.field)) throw unknownField(op)
const before = readField(located.item, op.field)
writeField(located.item, op.field, op.value)
record(ctx, op.target, op.field, { before, after: op.value })
}
/** Target and descendants that carry the field; unchanged items are skipped. */
function setSubtree(ctx: OpContext, located: Located, op: OpOf<'set'>) {
if (located.target.kind !== 'finding') {
throw new Error(`scope subtree needs a finding target, got "${op.target}"`)
}
const entries = findingScope(located, 'subtree').filter((entry) =>
isSettable(fieldKind(located.target, entry.isCategory), op.field),
)
if (entries.length === 0) throw unknownField(op)
for (const { target, item } of entries) {
const before = readField(item, op.field)
if (isDeepStrictEqual(before, op.value)) continue
writeField(item, op.field, op.value)
record(ctx, target, op.field, { before, after: op.value })
}
}
function applySet(ctx: OpContext, op: OpOf<'set'>): void {
const located = locate(ctx.doc, op.target)
if ((op.scope ?? 'self') === 'self') setSelf(ctx, located, op)
else setSubtree(ctx, located, op)
}
function applyRename(ctx: OpContext, op: OpOf<'rename'>): void {
const { target, siblings, item } = locate(ctx.doc, op.target)
if (siblings === null) throw new Error('the document has no id to rename')
const key = keyField(target.kind)
assertFree(siblings, key, op.id, item)
const before = structuredClone(item)
const from = String(item[key])
item[key] = op.id
record(ctx, op.target, null, { before, after: item })
propagateRename(ctx, { kind: target.kind, from, to: op.id })
}
interface Destination {
list: Item[]
key: 'id' | 'code'
prefix: string
}
function addDestination(ctx: OpContext, op: OpOf<'add'>): Destination {
const parent = locate(ctx.doc, op.target)
if (parent.target.kind !== 'document') {
if (op.field)
throw new Error(`field "${op.field}" is only valid on document`)
return { list: childList(parent), key: 'id', prefix: childPrefix(parent) }
}
if (!op.field) throw new Error('add on document needs a field')
const kind = COLLECTION_KIND[op.field]!
const list = topCollection(ctx.doc, kind)
return { list, key: keyField(kind), prefix: `${kind}:` }
}
function applyAdd(ctx: OpContext, op: OpOf<'add'>): void {
if (!isItem(op.value)) throw new Error('add needs an object value')
const dest = addDestination(ctx, op)
const id = op.value[dest.key]
if (typeof id !== 'string') {
throw new Error(`the added item needs a string "${dest.key}"`)
}
assertFree(dest.list, dest.key, id)
const index = insertionIndex(dest.list, dest.key, op.position)
dest.list.splice(index, 0, structuredClone(op.value))
record(ctx, dest.prefix + id, null, { before: null, after: op.value })
}
function applyRemove(ctx: OpContext, op: OpOf<'remove'>): void {
const { siblings, item } = locate(ctx.doc, op.target)
if (siblings === null) throw new Error('the document cannot be removed')
siblings.splice(siblings.indexOf(item), 1)
record(ctx, op.target, null, { before: item, after: null })
}
/** `after` of a move record is the new target path of the item. */
function applyMove(ctx: OpContext, op: OpOf<'move'>): void {
const source = locate(ctx.doc, op.target)
if (source.target.kind !== 'finding') {
throw new Error(`only findings move, got "${op.target}"`)
}
if (op.to === op.target || op.to.startsWith(`${op.target}/`)) {
throw new Error(`cannot move "${op.target}" into itself`)
}
const parent = locate(ctx.doc, op.to)
const list = childList(parent)
const id = String(source.item.id)
assertFree(list, 'id', id, source.item)
source.siblings!.splice(source.siblings!.indexOf(source.item), 1)
list.splice(insertionIndex(list, 'id', op.position), 0, source.item)
const after = childPrefix(parent) + id
record(ctx, op.target, null, { before: source.item, after })
}
/** Every cited id must be declared in the document references. */
export function assertDeclared(doc: Item, ids: readonly string[]): void {
const declared = new Set(topCollection(doc, 'reference').map((r) => r.id))
const missing = ids.filter((id) => !declared.has(id))
if (missing.length > 0) {
throw new Error(`undeclared reference(s): ${missing.join(', ')}`)
}
}
/** Appends citations in order, never twice on the same item. */
function applyCite(ctx: OpContext, op: OpOf<'cite'>): void {
assertDeclared(ctx.doc, op.reference_ids)
const located = locate(ctx.doc, op.target)
for (const { target, item } of findingScope(located, op.scope ?? 'self')) {
const before = Array.isArray(item.reference_ids) ? item.reference_ids : []
const added = [...new Set(op.reference_ids)].filter(
(id) => !before.includes(id),
)
if (added.length === 0) continue
item.reference_ids = [...before, ...added]
record(ctx, target, 'reference_ids', { before, after: item.reference_ids })
}
}
export function applyOp(ctx: OpContext): void {
const op = ctx.op
switch (op.op) {
case 'set':
return applySet(ctx, op)
case 'rename':
return applyRename(ctx, op)
case 'add':
return applyAdd(ctx, op)
case 'remove':
return applyRemove(ctx, op)
case 'move':
return applyMove(ctx, op)
case 'cite':
return applyCite(ctx, op)
}
}
+146
View File
@@ -0,0 +1,146 @@
import type {
AnatomicalSheetDocumentInput,
Reference,
SheetIssue,
ViewBox,
} from '@faunosteo/domain'
import { formatJson, formatMarkdown } from '../format'
import { HEAD_VIEW_ID, MAIN_VIEW_ID } from '../legacy/importer'
import type { Anomaly, AssetRecord, ImportResult } from '../legacy/types'
import { applyChangeset, curatedIssues } from './apply'
import { cleanedAsset, stripLegacyAnnotations } from './assets'
import { renderChangelog } from './changelog'
import { renderReviewReport } from './review-report'
import {
ASSET_CHANGE_ID,
changeSummary,
type Change,
type ChangeSummary,
type Changeset,
} from './schema'
import { DRAFT_CHANGE_NOTE, renderDraftSeedSql } from './seed'
import { documentStats, type DocumentStats } from './stats'
import type { ChangeRecord } from './types'
/**
* Legacy import → curated working draft. The asset step runs first as the
* reserved change CHG-000 (one cleaned drawing, head view = crop), then
* the authored changeset; both land in the same records, so the CHANGELOG
* lists them alike. Deterministic: same inputs, same bytes.
*/
export const DRAFT_SEED_SQL_FILE = 'equine_draft.sql'
export interface DraftInput {
importResult: ImportResult
legacyMainSvgBytes: Uint8Array
headViewBox: ViewBox
references: readonly Reference[]
changeset: Changeset
}
export interface DraftResult {
document: AnatomicalSheetDocumentInput
records: ChangeRecord[]
changes: ChangeSummary[]
assets: AssetRecord[]
/** Cleaned drawing, written as draft/assets/<assets[0].file>. */
cleanedSvg: string
statsBefore: DocumentStats
statsAfter: DocumentStats
/** Integrity warnings of the curated document (errors throw). */
issues: SheetIssue[]
sheetId: string
}
function assetChange(asset: AssetRecord, headViewBox: ViewBox): Change {
return {
id: ASSET_CHANGE_ID,
level: 'A',
kind: 'technical',
title: {
fr: 'Un seul dessin, vue tête = recadrage',
en: 'Single drawing, head view = crop',
},
rationale:
'Les deux fichiers historiques portent le même dessin (tracés ' +
'identiques) et les marqueurs sont désormais des données de la ' +
'fiche : un seul dessin nettoyé, la vue tête en est un recadrage.',
reference_ids: [],
priority: 'medium',
ops: [
{
op: 'set',
target: `view:${MAIN_VIEW_ID}`,
field: 'svg_asset_id',
value: asset.svg_asset_id,
},
{
op: 'set',
target: `view:${HEAD_VIEW_ID}`,
field: 'svg_asset_id',
value: null,
},
{
op: 'set',
target: `view:${HEAD_VIEW_ID}`,
field: 'view_box',
value: headViewBox,
},
],
}
}
function assertNotReserved(changeset: Changeset): void {
if (changeset.changes.some((change) => change.id === ASSET_CHANGE_ID)) {
throw new Error(`${ASSET_CHANGE_ID} is reserved for the asset step`)
}
}
export function buildEquineDraft(input: DraftInput): DraftResult {
assertNotReserved(input.changeset)
const legacyText = new TextDecoder('utf-8', { fatal: true }).decode(
input.legacyMainSvgBytes,
)
const cleanedSvg = stripLegacyAnnotations(legacyText)
const asset = cleanedAsset(new TextEncoder().encode(cleanedSvg))
const changes = [
assetChange(asset, input.headViewBox),
...input.changeset.changes,
]
const baseline = input.importResult.document
const result = applyChangeset(baseline, input.references, { changes })
return {
document: result.document,
records: result.records,
changes: changes.map(changeSummary),
assets: [asset],
cleanedSvg,
statsBefore: documentStats(baseline),
statsAfter: documentStats(result.document),
issues: curatedIssues(result.document),
sheetId: input.importResult.sheetId,
}
}
/** Text artifacts of the draft folder, keyed by file name. */
export async function renderDraftArtifacts(
draft: DraftResult,
legacyAnomalies: readonly Anomaly[],
): Promise<Record<string, string>> {
const documentJson = await formatJson(draft.document)
const changelog = renderChangelog(draft, draft.statsBefore, draft.statsAfter)
const review = renderReviewReport({ ...draft, legacyAnomalies })
return {
'document.json': documentJson,
'assets.json': await formatJson(draft.assets),
'CHANGELOG.md': await formatMarkdown(changelog),
'REVIEW-REPORT.md': await formatMarkdown(review),
[DRAFT_SEED_SQL_FILE]: renderDraftSeedSql({
sheetId: draft.sheetId,
assets: draft.assets,
documentJson,
changeNote: DRAFT_CHANGE_NOTE,
}),
}
}
+57
View File
@@ -0,0 +1,57 @@
import { allFindings, topCollection, type TargetKind } from './targets'
import { record, type OpContext } from './types'
/**
* Rename propagation: every field pointing at the renamed id follows, and
* each rewrite is a record of its own so the CHANGELOG shows the cascade.
*/
interface Link {
kind: 'annotation' | 'view'
field: string
}
const LINKS: Partial<Record<TargetKind, readonly Link[]>> = {
zone: [{ kind: 'annotation', field: 'finding_zone_id' }],
region: [{ kind: 'annotation', field: 'vertebral_region_code' }],
view: [
{ kind: 'view', field: 'parent_view_id' },
{ kind: 'annotation', field: 'view_id' },
{ kind: 'annotation', field: 'opens_view_id' },
],
category: [{ kind: 'annotation', field: 'category_id' }],
}
interface Rename {
kind: TargetKind
from: string
to: string
}
function followLink(ctx: OpContext, link: Link, rename: Rename): void {
for (const item of topCollection(ctx.doc, link.kind)) {
if (item[link.field] !== rename.from) continue
item[link.field] = rename.to
record(ctx, `${link.kind}:${String(item.id)}`, link.field, {
before: rename.from,
after: rename.to,
})
}
}
function followCitations(ctx: OpContext, rename: Rename): void {
for (const { target, item } of allFindings(ctx.doc)) {
const ids = item.reference_ids
if (!Array.isArray(ids) || !ids.includes(rename.from)) continue
const after = ids.map((id: unknown) =>
id === rename.from ? rename.to : id,
)
record(ctx, target, 'reference_ids', { before: ids, after })
item.reference_ids = after
}
}
export function propagateRename(ctx: OpContext, rename: Rename): void {
if (rename.kind === 'reference') return followCitations(ctx, rename)
for (const link of LINKS[rename.kind] ?? []) followLink(ctx, link, rename)
}
@@ -0,0 +1,206 @@
import type { AnatomicalSheetDocumentInput } from '@faunosteo/domain'
import type { Anomaly } from '../legacy/types'
import { code, table } from '../markdown'
import { compactValue, recordSubject } from './changelog'
import { KIND_LABELS, PRIORITY_LABELS } from './labels'
import {
needsConfirmation,
type ChangePriority,
type ChangeSummary,
} from './schema'
import { statRows, type DocumentStats } from './stats'
import { allFindings, zoneFindings, type Item } from './targets'
import type { ChangeRecord } from './types'
/**
* French review report for the osteopath, ten fixed sections. It only
* formats data (changes, records, stats, references): no medical content
* is written here, every statement comes from the authored changeset.
*/
export interface ReviewReportInput {
changes: readonly ChangeSummary[]
records: readonly ChangeRecord[]
document: AnatomicalSheetDocumentInput
statsBefore: DocumentStats
legacyAnomalies: readonly Anomaly[]
}
type Section = (input: ReviewReportInput) => string
const NONE = 'Aucun élément dans cette révision.'
const PRIORITY_ORDER: readonly ChangePriority[] = ['high', 'medium', 'low']
function subjects(input: ReviewReportInput, change: ChangeSummary): string {
const own = input.records.filter((r) => r.change.id === change.id)
return [...new Set(own.map(recordSubject))].map(code).join(', ')
}
function references(ids: readonly string[]): string {
return ids.length === 0 ? 'aucune' : ids.map(code).join(', ')
}
function changeLine(input: ReviewReportInput, change: ChangeSummary): string {
const confirm = needsConfirmation(change.level) ? 'oui' : 'non'
return (
`- ${code(change.id)} ${change.title.fr} (niveau ${change.level}, ` +
`${KIND_LABELS[change.kind]}, confirmation requise : ${confirm}). ` +
`${change.rationale} Objets : ${subjects(input, change)}. ` +
`Références : ${references(change.reference_ids)}.` +
(change.question ? ` Question : ${change.question}` : '')
)
}
function changeList(
input: ReviewReportInput,
keep: (c: ChangeSummary) => boolean,
) {
const lines = input.changes.filter(keep).map((c) => changeLine(input, c))
return lines.length === 0 ? NONE : lines.join('\n')
}
const initialQuality: Section = (input) => {
const toValidate = input.legacyAnomalies.filter(
(a) => a.level === 'a_valider',
)
return [
`L'import historique signale ${input.legacyAnomalies.length} anomalies, ` +
`dont ${toValidate.length} à valider (détail dans ` +
'`legacy-import/IMPORT-REPORT.md`).',
'',
table(
['Indicateur (import historique)', 'Valeur'],
statRows(input.statsBefore),
),
].join('\n')
}
const mainErrors: Section = (input) =>
changeList(
input,
(c) => c.level === 'A' && (c.kind === 'correction' || c.kind === 'removal'),
)
const translations: Section = (input) => {
const changes = input.changes.filter((c) => c.kind === 'translation')
const ids = new Set(changes.map((c) => c.id))
const touched = input.records.filter((r) => ids.has(r.change.id))
const targets = [...new Set(touched.map(recordSubject))]
const head =
`${changes.length} changement(s) de traduction, ` +
`${targets.length} objet(s) traduit(s).`
return targets.length === 0
? head
: `${head}\n\n${targets.map((t) => `- ${code(t)}`).join('\n')}`
}
function vetFlagChanges(input: ReviewReportInput): string {
const flips = input.records.filter((r) => r.field === 'requires_vet_referral')
if (flips.length === 0)
return 'Aucun renvoi vétérinaire modifié dans cette révision.'
const line = (r: ChangeRecord) =>
`- ${code(r.target)} : ${compactValue(r.before)} → ` +
`${compactValue(r.after)} (${code(r.change.id)})`
return flips.map(line).join('\n')
}
function vetFlagsPerZone(doc: AnatomicalSheetDocumentInput): string {
const rows = (doc.finding_zones as unknown as Item[]).flatMap((zone) => {
const flags = zoneFindings(zone).filter(
(e) => e.item.requires_vet_referral === true,
)
return flags.length === 0 ? [] : [[code(String(zone.id)), flags.length]]
})
return rows.length === 0
? 'Aucun renvoi vétérinaire.'
: table(['Zone', 'Renvois vétérinaires'], rows)
}
const clinicalVigilance: Section = (input) =>
[
'Renvois vétérinaires modifiés :',
'',
vetFlagChanges(input),
'',
'Renvois vétérinaires de la fiche, par zone :',
'',
vetFlagsPerZone(input.document),
].join('\n')
function citationCount(doc: AnatomicalSheetDocumentInput, id: string): number {
return allFindings(doc as unknown as Item).filter((e) => {
const ids = e.item.reference_ids
return Array.isArray(ids) && ids.includes(id)
}).length
}
const bibliography: Section = (input) => {
const lines = input.document.references.map((ref, index) => {
const links = [
ref.url ? `URL : ${ref.url}` : '',
ref.doi ? `DOI : ${ref.doi}` : '',
].filter(Boolean)
const where = links.length > 0 ? ` (${links.join(', ')})` : ''
const cited = citationCount(input.document, ref.id)
return (
`${index + 1}. ${code(ref.id)} ${ref.citation}${where}, ` +
`cité par ${cited} nœud(s).`
)
})
return lines.length === 0 ? 'Aucune référence déclarée.' : lines.join('\n')
}
function byPriorityThenId(a: ChangeSummary, b: ChangeSummary): number {
const rank =
PRIORITY_ORDER.indexOf(a.priority) - PRIORITY_ORDER.indexOf(b.priority)
if (rank !== 0) return rank
if (a.id === b.id) return 0
return a.id < b.id ? -1 : 1
}
const professionalDecisions: Section = (input) => {
const questions = input.changes
.filter((c) => c.level === 'C')
.sort(byPriorityThenId)
if (questions.length === 0) return 'Aucune question ouverte.'
return questions
.map(
(c, index) =>
`${index + 1}. ${code(c.id)} (priorité ${PRIORITY_LABELS[c.priority]}) : ` +
`${c.question ?? ''} Références : ${references(c.reference_ids)}.`,
)
.join('\n')
}
const SECTIONS: ReadonlyArray<[string, Section]> = [
['1. Qualité des données initiales', initialQuality],
['2. Principales erreurs anatomiques et ostéopathiques', mainErrors],
['3. Corrections effectuées', (i) => changeList(i, (c) => c.level === 'A')],
['4. Ajouts', (i) => changeList(i, (c) => c.kind === 'enrichment')],
[
'5. Réorganisations du catalogue',
(i) => changeList(i, (c) => c.kind === 'restructure'),
],
['6. Éléments incertains', (i) => changeList(i, (c) => c.level === 'C')],
['7. Traductions', translations],
['8. Points de vigilance clinique', clinicalVigilance],
['9. Bibliographie', bibliography],
['10. Décisions réservées au professionnel', professionalDecisions],
]
function intro(): string {
return [
'# Rapport de revue : révision de travail',
'',
'Généré par `pnpm import:equine` à partir des changements rédigés ' +
'(`curation/changes.json`). Ne pas modifier à la main. Rien n’est ' +
'publié : la révision reste un brouillon jusqu’à la décision du professionnel.',
].join('\n')
}
export function renderReviewReport(input: ReviewReportInput): string {
const sections = SECTIONS.map(
([title, render]) => `## ${title}\n\n${render(input)}`,
)
return `${[intro(), ...sections].join('\n\n')}\n`
}
+172
View File
@@ -0,0 +1,172 @@
import { ReferenceSchema } from '@faunosteo/domain'
import { z } from 'zod'
/**
* Authored curation inputs (supabase/seed/anatomical-sheets/<species>/
* curation/): a changeset of traceable changes applied on the legacy
* baseline, and the references registry they cite. Every object is strict
* so a typo in a hand-written file fails loud instead of being ignored.
*/
/** A demonstrated error, B supported improvement, C uncertain (question). */
export const ChangeLevelSchema = z.enum(['A', 'B', 'C'])
export const ChangeKindSchema = z.enum([
'correction',
'terminology',
'translation',
'restructure',
'enrichment',
'reference',
'geometry',
'removal',
'technical',
])
export const ChangePrioritySchema = z.enum(['high', 'medium', 'low'])
/** Reserved for the asset step of the pipeline, never authored. */
export const ASSET_CHANGE_ID = 'CHG-000'
const TargetSchema = z.string().min(1)
const PositionSchema = z.union([
z.number().int().min(0),
z.object({ after: z.string().min(1) }).strict(),
z.object({ before: z.string().min(1) }).strict(),
])
const ScopeSchema = z.enum(['self', 'subtree'])
/** Document-level collections an `add` on 'document' may extend. */
export const DocumentCollectionSchema = z.enum([
'references',
'categories',
'views',
'annotations',
'finding_zones',
'regions',
])
const SetOpSchema = z
.object({
op: z.literal('set'),
target: TargetSchema,
field: z.string().min(1),
value: z.unknown(),
scope: ScopeSchema.optional(),
})
.strict()
const RenameOpSchema = z
.object({
op: z.literal('rename'),
target: TargetSchema,
id: z.string().min(1),
})
.strict()
const AddOpSchema = z
.object({
op: z.literal('add'),
target: TargetSchema,
field: DocumentCollectionSchema.optional(),
value: z.unknown(),
position: PositionSchema.optional(),
})
.strict()
const RemoveOpSchema = z
.object({ op: z.literal('remove'), target: TargetSchema })
.strict()
const MoveOpSchema = z
.object({
op: z.literal('move'),
target: TargetSchema,
to: TargetSchema,
position: PositionSchema.optional(),
})
.strict()
const CiteOpSchema = z
.object({
op: z.literal('cite'),
target: TargetSchema,
reference_ids: z.array(z.string().min(1)).min(1),
scope: ScopeSchema.optional(),
})
.strict()
export const OpSchema = z.discriminatedUnion('op', [
SetOpSchema,
RenameOpSchema,
AddOpSchema,
RemoveOpSchema,
MoveOpSchema,
CiteOpSchema,
])
export const ChangeSchema = z
.object({
id: z.string().regex(/^CHG-\d{3,}$/),
level: ChangeLevelSchema,
kind: ChangeKindSchema,
title: z.object({ fr: z.string().min(1), en: z.string().min(1) }).strict(),
rationale: z.string().min(1),
reference_ids: z.array(z.string().min(1)),
question: z.string().min(1).optional(),
priority: ChangePrioritySchema.default('medium'),
ops: z.array(OpSchema).min(1),
})
.strict()
.refine((change) => change.level !== 'C' || change.question !== undefined, {
message: 'a level C change needs a question',
path: ['question'],
})
function duplicates(ids: readonly string[]): string[] {
return ids.filter((id, index) => ids.indexOf(id) !== index)
}
export const ChangesetSchema = z
.object({ changes: z.array(ChangeSchema) })
.strict()
.superRefine((set, ctx) => {
for (const id of duplicates(set.changes.map((c) => c.id))) {
ctx.addIssue({ code: 'custom', message: `duplicate change id ${id}` })
}
})
export const ReferencesFileSchema = z
.object({ references: z.array(ReferenceSchema) })
.strict()
.superRefine((file, ctx) => {
for (const id of duplicates(file.references.map((r) => r.id))) {
ctx.addIssue({ code: 'custom', message: `duplicate reference id ${id}` })
}
})
export type ChangeLevel = z.infer<typeof ChangeLevelSchema>
export type ChangeKind = z.infer<typeof ChangeKindSchema>
export type ChangePriority = z.infer<typeof ChangePrioritySchema>
export type Position = z.infer<typeof PositionSchema>
export type Op = z.infer<typeof OpSchema>
export type Change = z.output<typeof ChangeSchema>
export type ChangeInput = z.input<typeof ChangeSchema>
export type Changeset = z.output<typeof ChangesetSchema>
export type ReferencesFile = z.output<typeof ReferencesFileSchema>
/** A change as cited by its records: everything but the ops. */
export type ChangeSummary = Omit<Change, 'ops'>
/** Derived, never stored: only a demonstrated error needs no sign-off. */
export function needsConfirmation(level: ChangeLevel): boolean {
return level !== 'A'
}
export function changeSummary(change: Change): ChangeSummary {
const summary: Partial<Change> = { ...change }
delete summary.ops
return summary as ChangeSummary
}
+125
View File
@@ -0,0 +1,125 @@
import type { AssetRecord } from '../legacy/types'
/**
* Idempotent and converging PostgreSQL seed of an official sheet's working
* DRAFT. Runs as the database owner in `supabase db reset` and in the
* PGlite harness. A fresh database gets the draft through
* private.insert_sheet_draft (audited, null actor); a database still
* holding an older draft as the sheet's only version gets its content
* replaced in place. Published rows are never touched and nothing is
* published: that stays a human act through publish_sheet_version.
*/
export const DOCUMENT_DOLLAR_TAG = '$equine_doc$'
const SHEET_DESCRIPTION =
'Fiche anatomique officielle du cheval ' +
'(import des données historiques, brouillon à valider)'
export const DRAFT_CHANGE_NOTE =
'Révision de travail 4c (audit anatomique et ostéopathique) ' +
'sur l’import des données historiques'
export interface DraftSeedParams {
sheetId: string
assets: readonly AssetRecord[]
/** document.json text, embedded verbatim in a dollar-quoted literal. */
documentJson: string
changeNote: string
}
/** Only ever fed fixed values; doubled quotes keep it literal-safe. */
function sqlText(value: string): string {
return `'${value.replace(/'/g, "''")}'`
}
function header(): string {
return [
'-- Official equine anatomical sheet: working revision, DRAFT.',
'-- Generated by `pnpm import:equine` (packages/anatomy): do not edit by hand.',
'-- Idempotent and converging. Never publishes: the version stays in status',
'-- draft until a platform admin validates REVIEW-REPORT.md and publishes it.',
].join('\n')
}
function sheetInsert(sheetId: string): string {
return [
'insert into public.anatomical_sheets',
' (id, species_id, name, slug, description, creator_user_id, is_official, visibility)',
'values (',
` ${sqlText(sheetId)}, 'equine', 'Faunosteo / Cheval', 'faunosteo-cheval',`,
` ${sqlText(SHEET_DESCRIPTION)},`,
" null, true, 'private'",
')',
'on conflict (id) do nothing;',
].join('\n')
}
function assetInserts(sheetId: string, assets: readonly AssetRecord[]): string {
const rows = assets.map(
(a) =>
` (${sqlText(a.svg_asset_id)}, ${sqlText(sheetId)}, ${sqlText(a.sha256)}, ` +
`${a.byte_size}, 'image/svg+xml', ${sqlText(a.file)})`,
)
return [
'insert into public.anatomical_sheet_assets',
' (id, sheet_id, sha256, byte_size, content_type, file_name)',
'values',
rows.join(',\n'),
'on conflict (sheet_id, sha256) do nothing;',
].join('\n')
}
function documentLiteral(documentJson: string): string {
if (documentJson.includes(DOCUMENT_DOLLAR_TAG)) {
throw new Error(
`document JSON contains the dollar-quote tag ${DOCUMENT_DOLLAR_TAG}`,
)
}
return `${DOCUMENT_DOLLAR_TAG}${documentJson.trimEnd()}${DOCUMENT_DOLLAR_TAG}::jsonb`
}
function draftInsert(params: DraftSeedParams, literal: string): string {
const sheet = sqlText(params.sheetId)
return [
'select private.insert_sheet_draft(',
' null,',
` ${sheet},`,
` ${literal},`,
` ${sqlText(params.changeNote)}`,
')',
'where not exists (',
` select 1 from public.anatomical_sheet_versions where sheet_id = ${sheet}`,
');',
].join('\n')
}
/**
* Only when the sheet's single version is a draft whose content differs;
* the document literal is read once through the derived table.
*/
function draftConverge(params: DraftSeedParams, literal: string): string {
const sheet = sqlText(params.sheetId)
return [
'update public.anatomical_sheet_versions v',
`set content = d.content, change_note = ${sqlText(params.changeNote)}`,
`from (select ${literal} as content) d`,
`where v.sheet_id = ${sheet} and v.status = 'draft'`,
' and v.content <> d.content',
' and (select count(*) from public.anatomical_sheet_versions o',
` where o.sheet_id = ${sheet}) = 1;`,
].join('\n')
}
export function renderDraftSeedSql(params: DraftSeedParams): string {
const literal = documentLiteral(params.documentJson)
return (
[
header(),
sheetInsert(params.sheetId),
assetInserts(params.sheetId, params.assets),
draftInsert(params, literal),
draftConverge(params, literal),
].join('\n\n') + '\n'
)
}
+38
View File
@@ -0,0 +1,38 @@
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'
import type { Reference } from '@faunosteo/domain'
import { EQUINE_CURATION_DIR } from '../legacy/sources'
import { ChangesetSchema, ReferencesFileSchema, type Changeset } from './schema'
/**
* The authored curation files of the equine sheet. Both are required: a
* missing or invalid file stops the pipeline (no silent empty changeset).
*/
export const CURATION_FILES = {
references: 'references.json',
changes: 'changes.json',
} as const
export interface CurationInput {
references: Reference[]
changeset: Changeset
}
async function readJson(path: string): Promise<unknown> {
return JSON.parse(await readFile(path, 'utf8')) as unknown
}
export async function readEquineCuration(
repoRoot: string,
): Promise<CurationInput> {
const dir = join(repoRoot, EQUINE_CURATION_DIR)
const [references, changes] = await Promise.all([
readJson(join(dir, CURATION_FILES.references)),
readJson(join(dir, CURATION_FILES.changes)),
])
return {
references: ReferencesFileSchema.parse(references).references,
changeset: ChangesetSchema.parse(changes),
}
}
+133
View File
@@ -0,0 +1,133 @@
import type { AnatomicalSheetDocumentInput } from '@faunosteo/domain'
import { allFindings, type FindingEntry, type Item } from './targets'
/**
* Volumes of a sheet document, compared before / after curation in the
* CHANGELOG and shown for the baseline in the review report. Nodes count
* finding categories too, as countTree does in the import report.
*/
const ANNOTATION_KINDS = ['point', 'zone', 'detail_trigger'] as const
const REVIEW_STATUSES = ['inherited', 'reviewed', 'to_confirm'] as const
type Counts = Record<string, number>
export interface DocumentStats {
views: number
assets: number
annotations: number
annotationsByKind: Counts
annotationCategories: number
findingZones: number
findingCategories: number
nodes: number
leaves: number
vetReferrals: number
descriptions: number
descriptionsFrOnly: number
references: number
citedNodes: number
nodesByReviewStatus: Counts
annotationsByReviewStatus: Counts
regionsWithCountRange: number
}
function countBy<T>(
items: readonly T[],
keys: readonly string[],
key: (item: T) => string,
) {
const counts: Counts = Object.fromEntries(keys.map((k) => [k, 0]))
for (const item of items) counts[key(item)] = (counts[key(item)] ?? 0) + 1
return counts
}
function description(item: Item): { fr: boolean; en: boolean } {
const text = (item.description ?? {}) as { fr?: string; en?: string }
return { fr: Boolean(text.fr), en: Boolean(text.en) }
}
function isLeaf(entry: FindingEntry): boolean {
const children = entry.item.children
return !Array.isArray(children) || children.length === 0
}
function isCited(entry: FindingEntry): boolean {
const ids = entry.item.reference_ids
return Array.isArray(ids) && ids.length > 0
}
function findingStats(findings: readonly FindingEntry[]) {
const texts = findings.map((entry) => description(entry.item))
return {
findingCategories: findings.filter((entry) => entry.isCategory).length,
nodes: findings.length,
leaves: findings.filter(isLeaf).length,
vetReferrals: findings.filter((e) => e.item.requires_vet_referral === true)
.length,
descriptions: texts.filter((t) => t.fr || t.en).length,
descriptionsFrOnly: texts.filter((t) => t.fr && !t.en).length,
citedNodes: findings.filter(isCited).length,
nodesByReviewStatus: countBy(findings, REVIEW_STATUSES, (e) =>
String(e.item.review_status ?? 'inherited'),
),
}
}
export function documentStats(
doc: AnatomicalSheetDocumentInput,
): DocumentStats {
const assets = doc.views.flatMap((v) =>
v.svg_asset_id ? [v.svg_asset_id] : [],
)
return {
views: doc.views.length,
assets: new Set(assets).size,
annotations: doc.annotations.length,
annotationsByKind: countBy(
doc.annotations,
ANNOTATION_KINDS,
(a) => a.kind,
),
annotationCategories: doc.categories.length,
findingZones: doc.finding_zones.length,
...findingStats(allFindings(doc as unknown as Item)),
references: doc.references.length,
annotationsByReviewStatus: countBy(doc.annotations, REVIEW_STATUSES, (a) =>
String(a.review_status ?? 'inherited'),
),
regionsWithCountRange: doc.vertebral_config.regions.filter(
(r) => r.count_range,
).length,
}
}
function countRows(label: string, counts: Counts): Array<[string, number]> {
return Object.entries(counts).map(([key, value]) => [
`${label} (${key})`,
value,
])
}
/** Labelled rows, fixed order, French labels. */
export function statRows(stats: DocumentStats): Array<[string, number]> {
return [
['Vues', stats.views],
['Dessins SVG distincts', stats.assets],
['Annotations', stats.annotations],
...countRows('Annotations', stats.annotationsByKind),
...countRows('Annotations, revue', stats.annotationsByReviewStatus),
["Catégories d'annotation", stats.annotationCategories],
['Zones de constats', stats.findingZones],
['Catégories de constats', stats.findingCategories],
['Nœuds (catégories incluses)', stats.nodes],
['Feuilles', stats.leaves],
['Renvois vétérinaires', stats.vetReferrals],
...countRows('Nœuds, revue', stats.nodesByReviewStatus),
['Descriptions', stats.descriptions],
['Descriptions en français seulement', stats.descriptionsFrOnly],
['Références bibliographiques', stats.references],
['Nœuds cités', stats.citedNodes],
['Régions vertébrales avec plage documentée', stats.regionsWithCountRange],
]
}
+195
View File
@@ -0,0 +1,195 @@
/**
* Target grammar of the changeset (one string per target):
*
* document | region:<code> | reference:<id> | category:<id> | view:<id>
* annotation:<id> | zone:<zoneId> | finding:<zoneId>/<catId>[/<nodeId>…]
*
* A finding path walks ids from the zone down; ids are unique among
* siblings, so the path names one category or node. Resolution works on
* the plain JSON form of the document: the changeset reaches any field
* without one accessor per type, and the final Zod parse checks the shape.
*/
export type Item = Record<string, unknown>
export type TargetKind =
| 'document'
| 'region'
| 'reference'
| 'category'
| 'view'
| 'annotation'
| 'zone'
| 'finding'
export interface ParsedTarget {
kind: TargetKind
ids: string[]
}
/** A resolved target: the item and the list that holds it (null: root). */
export interface Located {
target: ParsedTarget
siblings: Item[] | null
item: Item
}
/** One finding category or node met while walking a zone's tree. */
export interface FindingEntry {
target: string
item: Item
isCategory: boolean
}
const COLLECTION_KINDS: ReadonlySet<string> = new Set([
'region',
'reference',
'category',
'view',
'annotation',
'zone',
'finding',
])
export function isItem(value: unknown): value is Item {
return typeof value === 'object' && value !== null && !Array.isArray(value)
}
export function parseTarget(target: string): ParsedTarget {
if (target === 'document') return { kind: 'document', ids: [] }
const colon = target.indexOf(':')
const kind = target.slice(0, colon)
const rest = target.slice(colon + 1)
if (colon < 1 || !COLLECTION_KINDS.has(kind) || rest === '') {
throw new Error(`unknown target "${target}"`)
}
const ids = kind === 'finding' ? rest.split('/') : [rest]
if (ids.includes('') || (kind === 'finding' && ids.length < 2)) {
throw new Error(`malformed target "${target}"`)
}
return { kind: kind as TargetKind, ids }
}
export function formatTarget(target: ParsedTarget): string {
if (target.kind === 'document') return 'document'
return `${target.kind}:${target.ids.join('/')}`
}
/** Regions are keyed by their free code, everything else by a stable id. */
export function keyField(kind: TargetKind): 'id' | 'code' {
return kind === 'region' ? 'code' : 'id'
}
function listAt(holder: Item, key: string): Item[] {
const list = holder[key]
if (!Array.isArray(list)) throw new Error(`document has no list "${key}"`)
return list as Item[]
}
/** Top-level list holding the items of a target kind. */
export function topCollection(doc: Item, kind: TargetKind): Item[] {
switch (kind) {
case 'region':
return listAt(doc.vertebral_config as Item, 'regions')
case 'reference':
return listAt(doc, 'references')
case 'category':
return listAt(doc, 'categories')
case 'view':
return listAt(doc, 'views')
case 'annotation':
return listAt(doc, 'annotations')
default:
return listAt(doc, 'finding_zones')
}
}
function findIn(list: Item[], key: string, id: string, target: string): Item {
const item = list.find((entry) => entry[key] === id)
if (!item) throw new Error(`unknown target "${target}" (no "${id}")`)
return item
}
/** Children of a finding item; lean leaves get an empty list on demand. */
export function childrenOf(item: Item): Item[] {
if (!Array.isArray(item.children)) item.children = []
return item.children as Item[]
}
function locateFinding(doc: Item, target: ParsedTarget, raw: string) {
const zone = findIn(topCollection(doc, 'zone'), 'id', target.ids[0]!, raw)
let siblings = listAt(zone, 'categories')
let item = findIn(siblings, 'id', target.ids[1]!, raw)
for (const id of target.ids.slice(2)) {
siblings = Array.isArray(item.children) ? (item.children as Item[]) : []
item = findIn(siblings, 'id', id, raw)
}
return { target, siblings, item }
}
/** Resolves a target string or throws "unknown target". */
export function locate(doc: Item, raw: string): Located {
const target = parseTarget(raw)
if (target.kind === 'document') return { target, siblings: null, item: doc }
if (target.kind === 'finding') return locateFinding(doc, target, raw)
const siblings = topCollection(doc, target.kind)
const item = findIn(siblings, keyField(target.kind), target.ids[0]!, raw)
return { target, siblings, item }
}
/** The item and every descendant node, depth first, in document order. */
function walk(item: Item, target: string, depth: number): FindingEntry[] {
const own = { target, item, isCategory: depth === 0 }
const children = Array.isArray(item.children) ? (item.children as Item[]) : []
const nested = children.flatMap((child) =>
walk(child, `${target}/${String(child.id)}`, depth + 1),
)
return [own, ...nested]
}
/** Every finding category and node of a zone, depth first. */
export function zoneFindings(zone: Item): FindingEntry[] {
return listAt(zone, 'categories').flatMap((category) =>
walk(category, `finding:${String(zone.id)}/${String(category.id)}`, 0),
)
}
/** Every finding category and node of the document. */
export function allFindings(doc: Item): FindingEntry[] {
return topCollection(doc, 'zone').flatMap(zoneFindings)
}
/**
* Finding items an op touches. A finding target alone ('self') or with its
* descendants ('subtree'); a zone target stands for its categories alone
* ('self') or its whole tree ('subtree'): a zone carries no citation.
*/
export function findingScope(
located: Located,
scope: 'self' | 'subtree',
): FindingEntry[] {
const { target, item } = located
if (target.kind === 'zone') {
const entries = zoneFindings(item)
return scope === 'subtree' ? entries : entries.filter((e) => e.isCategory)
}
if (target.kind !== 'finding') {
throw new Error(`"${formatTarget(target)}" is not a finding or a zone`)
}
const depth = target.ids.length === 2 ? 0 : 1
const entries = walk(item, formatTarget(target), depth)
return scope === 'subtree' ? entries : entries.slice(0, 1)
}
/** The list an add or a move inserts into under a zone or a finding. */
export function childList(parent: Located): Item[] {
if (parent.target.kind === 'zone') return listAt(parent.item, 'categories')
if (parent.target.kind === 'finding') return childrenOf(parent.item)
throw new Error(`"${formatTarget(parent.target)}" holds no findings`)
}
/** Target prefix of the items of childList(parent). */
export function childPrefix(parent: Located): string {
if (parent.target.kind === 'zone') return `finding:${parent.target.ids[0]}/`
return `${formatTarget(parent.target)}/`
}
+47
View File
@@ -0,0 +1,47 @@
import type { AnatomicalSheetDocumentInput } from '@faunosteo/domain'
import type { ChangeSummary, Op } from './schema'
import type { Item } from './targets'
/**
* One elementary edit of the curated document, kept for the CHANGELOG.
* `before` / `after` are deep copies: the field value for a set, the whole
* item for a rename, remove or move, null on the missing side.
*/
export interface ChangeRecord {
change: ChangeSummary
op: Op
target: string
field: string | null
before: unknown
after: unknown
}
export interface CurationResult {
document: AnatomicalSheetDocumentInput
records: ChangeRecord[]
}
/** State shared by the op functions of one change. */
export interface OpContext {
doc: Item
change: ChangeSummary
op: Op
records: ChangeRecord[]
}
/** Absent values are recorded as null so records stay plain JSON. */
export function record(
ctx: OpContext,
target: string,
field: string | null,
values: { before: unknown; after: unknown },
): void {
ctx.records.push({
change: ctx.change,
op: ctx.op,
target,
field,
before: structuredClone(values.before ?? null),
after: structuredClone(values.after ?? null),
})
}
+30
View File
@@ -0,0 +1,30 @@
import { format } from 'prettier'
/**
* Prettier formatting of the generated artifacts with the repository
* options, so `prettier --check` accepts the committed files as generated
* (no exclusion needed). Shared by the legacy import and the draft.
*/
const PRETTIER_OPTIONS = {
semi: false,
singleQuote: true,
tabWidth: 2,
useTabs: false,
trailingComma: 'all',
printWidth: 80,
bracketSpacing: true,
arrowParens: 'always',
endOfLine: 'lf',
} as const
export function formatJson(value: unknown): Promise<string> {
return format(JSON.stringify(value, null, 2), {
...PRETTIER_OPTIONS,
parser: 'json',
})
}
export function formatMarkdown(text: string): Promise<string> {
return format(text, { ...PRETTIER_OPTIONS, parser: 'markdown' })
}
+1
View File
@@ -1 +1,2 @@
export * from './legacy'
export * from './curation'
+12 -4
View File
@@ -1,4 +1,8 @@
import type { Annotation, Geometry, Laterality } from '@faunosteo/domain'
import type {
AnatomicalSheetDocumentInput,
Geometry,
Laterality,
} from '@faunosteo/domain'
import { normaliseCategoryId } from './categories'
import { slugify } from './ids'
import { inferRegionCode } from './regions'
@@ -19,8 +23,12 @@ export interface AnnotationContext {
zoneByNames: ReadonlyMap<string, string>
}
/** Authoring form: review_status stays implicit ('inherited'). */
export type AnnotationInput =
AnatomicalSheetDocumentInput['annotations'][number]
export interface MappedAnnotation {
annotation: Annotation
annotation: AnnotationInput
row: AnnotationRow
region: RegionInference | null
anomalies: Anomaly[]
@@ -105,7 +113,7 @@ function mapTrigger(
ctx: AnnotationContext,
out: Anomaly[],
) {
const annotation: Annotation = {
const annotation: AnnotationInput = {
id: `${a.opensDetail}-trigger`,
kind: 'detail_trigger',
view_id: ctx.viewId,
@@ -159,7 +167,7 @@ function mapObservable(
)
}
const region = regionOf(a, out)
const annotation: Annotation = {
const annotation: AnnotationInput = {
id: zoneId ?? slugify(name.en),
kind: a.tagName === 'circle' ? 'point' : 'zone',
view_id: ctx.viewId,
+7 -34
View File
@@ -1,49 +1,22 @@
import { format } from 'prettier'
import { formatJson, formatMarkdown } from '../format'
import { renderImportReport } from './report'
import { renderSeedSql } from './seed'
import type { ImportResult } from './types'
/**
* Text artifacts of the generated seed folder, keyed by path relative to
* supabase/seed/anatomical-sheets/equine/v1/. JSON and Markdown go
* through Prettier with the repository options so `prettier --check`
* accepts the committed files as generated (no exclusion needed).
* Text artifacts of the generated legacy-import folder, keyed by path
* relative to supabase/seed/anatomical-sheets/equine/legacy-import/. This
* folder is the baseline of the curation: it carries no SQL, the draft
* folder holds the only seed.
*/
export const SEED_SQL_FILE = 'equine_v1.sql'
const PRETTIER_OPTIONS = {
semi: false,
singleQuote: true,
tabWidth: 2,
useTabs: false,
trailingComma: 'all',
printWidth: 80,
bracketSpacing: true,
arrowParens: 'always',
endOfLine: 'lf',
} as const
function formatJson(value: unknown): Promise<string> {
return format(JSON.stringify(value, null, 2), {
...PRETTIER_OPTIONS,
parser: 'json',
})
}
/** Deterministic: same result in, same bytes out. */
export async function renderArtifacts(
result: ImportResult,
): Promise<Record<string, string>> {
const documentJson = await formatJson(result.document)
return {
'document.json': documentJson,
'document.json': await formatJson(result.document),
'legacy-id-map.json': await formatJson(result.legacyIdMap),
'assets.json': await formatJson(result.assets),
'IMPORT-REPORT.md': await format(renderImportReport(result), {
...PRETTIER_OPTIONS,
parser: 'markdown',
}),
[SEED_SQL_FILE]: renderSeedSql({ result, documentJson }),
'IMPORT-REPORT.md': await formatMarkdown(renderImportReport(result)),
}
}
+3 -3
View File
@@ -3,12 +3,12 @@ import {
SHEET_DOCUMENT_SCHEMA_VERSION,
validateSheetDocument,
type AnatomicalSheetDocumentInput,
type Annotation,
type SheetView,
} from '@faunosteo/domain'
import {
mapAnnotation,
zoneNameKey,
type AnnotationInput,
type MappedAnnotation,
} from './annotations'
import {
@@ -176,8 +176,8 @@ function buildIdMap(sources: ParsedSources, mapped: Mapped): LegacyIdMap {
}
function countBy(
annotations: readonly Annotation[],
test: (a: Annotation) => boolean,
annotations: readonly AnnotationInput[],
test: (a: AnnotationInput) => boolean,
) {
return annotations.filter(test).length
}
+4 -3
View File
@@ -1,10 +1,11 @@
export { importEquineLegacy, HEAD_VIEW_ID, MAIN_VIEW_ID } from './importer'
export { renderArtifacts, SEED_SQL_FILE } from './artifacts'
export { renderArtifacts } from './artifacts'
export { renderImportReport } from './report'
export { renderSeedSql, DOCUMENT_DOLLAR_TAG } from './seed'
export {
readEquineSources,
EQUINE_SEED_DIR,
EQUINE_CURATION_DIR,
EQUINE_DRAFT_DIR,
EQUINE_LEGACY_IMPORT_DIR,
EQUINE_SOURCE_PATHS,
} from './sources'
export {
+1 -17
View File
@@ -1,6 +1,7 @@
import { SHEET_DOCUMENT_SCHEMA_VERSION } from '@faunosteo/domain'
import { AUTHORED_LABEL_CODE, regionLabelSubject } from './authored-labels'
import { countTree } from './catalog'
import { code, table } from '../markdown'
import type { Anomaly, ImportResult } from './types'
/**
@@ -9,23 +10,6 @@ import type { Anomaly, ImportResult } from './types'
* no environment data: the report is a committed, byte-stable artifact.
*/
function cell(value: string | number | null): string {
if (value === null) return '-'
return String(value).replace(/\|/g, '\\|').replace(/\n/g, ' ')
}
function table(
head: string[],
rows: Array<Array<string | number | null>>,
): string {
const lines = [head, head.map(() => '---'), ...rows.map((r) => r.map(cell))]
return lines.map((line) => `| ${line.join(' | ')} |`).join('\n')
}
function code(value: string | null): string {
return value === null ? '-' : `\`${value}\``
}
function intro(result: ImportResult): string {
return [
"# Rapport d'import : fiche anatomique équine v1",
-92
View File
@@ -1,92 +0,0 @@
import type { ImportResult } from './types'
/**
* Idempotent PostgreSQL seed of the official equine sheet as a DRAFT.
* Runs as the database owner in `supabase db reset` and in the PGlite
* harness. It never publishes: publication is a human act through
* publish_sheet_version once the import report is validated.
*/
export const DOCUMENT_DOLLAR_TAG = '$equine_doc$'
const SHEET_DESCRIPTION =
'Fiche anatomique officielle du cheval ' +
'(import des données historiques, brouillon à valider)'
export interface SeedSqlParams {
result: ImportResult
/** document.json text, embedded verbatim in a dollar-quoted literal. */
documentJson: string
}
/** Only ever fed fixed ASCII values; doubled quotes keep it literal-safe. */
function sqlText(value: string): string {
return `'${value.replace(/'/g, "''")}'`
}
function header(): string {
return [
'-- Official equine anatomical sheet, version 1, DRAFT.',
'-- Generated by `pnpm import:equine` (packages/anatomy): do not edit by hand.',
'-- Idempotent. Never publishes: the version stays in status draft until a',
'-- platform admin validates IMPORT-REPORT.md and publishes it by hand.',
].join('\n')
}
function sheetInsert(sheetId: string): string {
return [
'insert into public.anatomical_sheets',
' (id, species_id, name, slug, description, creator_user_id, is_official, visibility)',
'values (',
` ${sqlText(sheetId)}, 'equine', 'Faunosteo / Cheval', 'faunosteo-cheval',`,
` ${sqlText(SHEET_DESCRIPTION)},`,
" null, true, 'private'",
')',
'on conflict (id) do nothing;',
].join('\n')
}
function assetInserts(result: ImportResult): string {
const rows = result.assets.map(
(a) =>
` (${sqlText(a.svg_asset_id)}, ${sqlText(result.sheetId)}, ${sqlText(a.sha256)}, ` +
`${a.byte_size}, 'image/svg+xml', ${sqlText(a.file)})`,
)
return [
'insert into public.anatomical_sheet_assets',
' (id, sheet_id, sha256, byte_size, content_type, file_name)',
'values',
rows.join(',\n'),
'on conflict (sheet_id, sha256) do nothing;',
].join('\n')
}
function draftInsert(sheetId: string, documentJson: string): string {
if (documentJson.includes(DOCUMENT_DOLLAR_TAG)) {
throw new Error(
`document JSON contains the dollar-quote tag ${DOCUMENT_DOLLAR_TAG}`,
)
}
return [
'select private.insert_sheet_draft(',
' null,',
` ${sqlText(sheetId)},`,
` ${DOCUMENT_DOLLAR_TAG}${documentJson.trimEnd()}${DOCUMENT_DOLLAR_TAG}::jsonb,`,
" 'Import des données équines historiques (Horse.svg, Horse_head.svg, pathologies.json)'",
')',
'where not exists (',
` select 1 from public.anatomical_sheet_versions where sheet_id = ${sqlText(sheetId)}`,
');',
].join('\n')
}
export function renderSeedSql({ result, documentJson }: SeedSqlParams): string {
return (
[
header(),
sheetInsert(result.sheetId),
assetInserts(result),
draftInsert(result.sheetId, documentJson),
].join('\n\n') + '\n'
)
}
+11 -2
View File
@@ -3,7 +3,7 @@ import { join } from 'node:path'
import type { EquineLegacyInput } from './types'
/**
* Locations of the legacy equine sources and of the generated seed, both
* Locations of the legacy equine sources and of the seed folders, all
* relative to the repository root. Shared by the CLI and the golden tests.
*/
@@ -14,7 +14,16 @@ export const EQUINE_SOURCE_PATHS = {
vertebrae: 'apps/app/src/domain/species/equine/vertebrae.ts',
} as const
export const EQUINE_SEED_DIR = 'supabase/seed/anatomical-sheets/equine/v1'
const EQUINE_SEED_ROOT = 'supabase/seed/anatomical-sheets/equine'
/** GENERATED baseline: the legacy import, untouched by curation. */
export const EQUINE_LEGACY_IMPORT_DIR = `${EQUINE_SEED_ROOT}/legacy-import`
/** AUTHORED inputs: changes.json and references.json, never generated. */
export const EQUINE_CURATION_DIR = `${EQUINE_SEED_ROOT}/curation`
/** GENERATED working revision: curated document, cleaned asset, seed. */
export const EQUINE_DRAFT_DIR = `${EQUINE_SEED_ROOT}/draft`
function fileName(path: string): string {
return path.slice(path.lastIndexOf('/') + 1)
+21
View File
@@ -0,0 +1,21 @@
/**
* Markdown building blocks of the generated French reports. Cells are
* escaped so a pipe or a newline in data never breaks a table.
*/
export function cell(value: string | number | null): string {
if (value === null) return '-'
return String(value).replace(/\|/g, '\\|').replace(/\n/g, ' ')
}
export function table(
head: string[],
rows: Array<Array<string | number | null>>,
): string {
const lines = [head, head.map(() => '---'), ...rows.map((r) => r.map(cell))]
return lines.map((line) => `| ${line.join(' | ')} |`).join('\n')
}
export function code(value: string | null): string {
return value === null ? '-' : `\`${value}\``
}