import { ReportV2Schema, findingPathKey, type ArchiveReadOutcome, type Finding, type FindingV2, type ObservationZoneV2, type Report, type ReportZone, } from '@faunosteo/domain' import type { Locale } from '../../src/i18n/types' import { pickLabel, type SheetIndex } from '../../src/services/sheetIndex' /** * Pure comparison of a report document found in a PDF with its v3 reading: * a v2 archive is shown legacy id → canonical id line by line, a v3 report * is checked against the bundled sheet. Every item the sheet cannot place is * marked `!! UNRESOLVED` with the reason, nothing is summarised away. A Step 6 * envelope adds one header line saying whether its snapshot was kept. */ export const UNRESOLVED = '!! UNRESOLVED' export interface CompareOptions { locale: Locale /** Print names and the real free texts (off by default: placeholders). */ full: boolean } export interface Comparison { /** `v2` when the attachment was migrated, `v3` when read as is. */ source: 'v2' | 'v3' header: string[] observations: string[][] footer: string[] /** Lines in the v3 vocabulary only, for `--diff` between two PDFs. */ normalized: string[] counts: Counts } export interface Counts { observations: number zones: number unresolvedZones: number findings: number unresolvedFindings: number } /** * Escapes Unicode control (C0, DEL, C1) and format characters (bidi * overrides, zero-width) plus the line and paragraph separators as `\uXXXX` * (newline and carriage return included): a PDF is untrusted, and a raw * escape sequence printed to a terminal can rewrite the screen or fake a line. */ export function esc(text: string): string { return text.replace( /[\p{Cc}\p{Cf}\u2028\u2029]/gu, (c) => `\\u${c.codePointAt(0)!.toString(16).padStart(4, '0')}`, ) } const q = (text: string) => `"${esc(text)}"` function zoneRef(z: { annotationId: string; viewId: string; side?: string }) { return esc(`${z.annotationId}@${z.viewId}${z.side ? ' ' + z.side : ''}`) } function findingRef(f: { findingZoneId: string; path: readonly string[] }) { return esc(findingPathKey(f.findingZoneId, f.path)) } function vertebraeOf(z: { vertebrae?: { region: string; index: number }[] }) { return z.vertebrae?.length ? ` [${z.vertebrae.map((v) => esc(`${v.region}${v.index}`)).join(', ')}]` : '' } /** Free-text lines: the texts with `full`, else only how many there are. */ function textLines(texts: readonly string[], full: boolean): string[] { if (texts.length === 0) return [] if (!full) return [`text (${texts.length} entries)`] return texts.map((t) => `text ${q(t)}`) } /** A single free-text field: its content with `full`, else a placeholder. */ function fieldLine(label: string, value: string | undefined, full: boolean) { if (!value) return [] return [full ? `${label} ${q(value)}` : `${label} (present)`] } /** A v3 zone against the sheet: current label, or why it cannot be shown. */ function describeZone( z: ReportZone, sheet: SheetIndex, locale: Locale, ): string { const ref = `${zoneRef(z)}${vertebraeOf(z)}` const anno = sheet.annotation(z.annotationId) if (z.unresolved) { return `${ref} ${q(z.labelFrSnapshot ?? '')} ${UNRESOLVED} legacy zone kept from the archive` } if (!anno || anno.view_id !== z.viewId) { return `${ref} ${q(z.labelFrSnapshot ?? '')} !! not in the sheet (unflagged)` } return `${ref} ${q(pickLabel(sheet.name(anno), locale))}` } /** A v3 finding against the sheet: current label, or why it cannot be shown. */ function describeFinding( f: Finding, sheet: SheetIndex, locale: Locale, ): string { const snapshot = q(locale === 'en' ? f.labelEnSnapshot : f.labelFrSnapshot) const vet = f.requiresVetReferral ? ' (!)' : '' const side = f.side ? ` ${esc(f.side)}` : '' const ref = `${findingRef(f)}${side}${vet}` if (f.unresolved) { return `${ref} ${snapshot} ${UNRESOLVED} kept with its snapshot` } const node = sheet.nodeAt(f.findingZoneId, f.path) if (!node) return `${ref} ${snapshot} !! not in the sheet (unflagged)` if (node.children.length > 0) { return `${ref} ${snapshot} !! points at a category, not a leaf` } return `${ref} ${q(pickLabel(node.name, locale))}` } /** Legacy zone → migrated zone. */ function describeZoneMigration( legacy: ObservationZoneV2, out: ReportZone, sheet: SheetIndex, locale: Locale, ): string { const side = legacy.side ? ` ${legacy.side}` : '' const detail = legacy.detailSourceId ? '@' + legacy.detailSourceId : '' const from = `${esc(legacy.boneId + detail + side)}${vertebraeOf(legacy)}` if (out.unresolved) { return `${from} ${UNRESOLVED} unknown legacy id, kept as ${zoneRef(out)}` } const anno = sheet.annotation(out.annotationId) const label = anno ? q(pickLabel(sheet.name(anno), locale)) : '!! missing' return `${from} ${q(out.labelFrSnapshot ?? '')} → ${zoneRef(out)} ${label}` } /** Legacy finding → migrated finding, with the fate the map decided. */ function describeFindingMigration( legacy: FindingV2, out: Finding, sheet: SheetIndex, locale: Locale, ): string { const map = sheet.sheet.migrationMap.finding_paths const vet = legacy.requiresVetReferral ? ' (!)' : '' const legacyKey = findingPathKey(legacy.zoneId, legacy.path) const key = `${esc(legacyKey)}${vet}` const snapshot = q( locale === 'en' ? legacy.labelEnSnapshot : legacy.labelFrSnapshot, ) if (out.unresolved) { const why = Object.hasOwn(map, legacyKey) ? 'removed from the sheet, kept with its label' : 'never in the legacy catalog, kept with its label' return `${key} ${snapshot} ${UNRESOLVED} ${why}` } const node = sheet.nodeAt(out.findingZoneId, out.path) const label = node ? q(pickLabel(node.name, locale)) : '!! missing' const target = findingRef(out) === esc(legacyKey) ? 'same' : findingRef(out) return `${key} ${snapshot} → ${target} ${label}` } function observationLines( obs: Report['observations'][number], sheet: SheetIndex, opts: CompareOptions, ): string[] { const lines = [ `[${esc(obs.id)}] severity ${esc(obs.severity ?? 'none')}`, ...obs.zones.map((z) => `zone ${describeZone(z, sheet, opts.locale)}`), ...obs.findings.map( (f) => `finding ${describeFinding(f, sheet, opts.locale)}`, ), ...textLines(obs.freeTextFindings, opts.full), ...fieldLine('comment ', obs.comment, opts.full), ] return lines } /** The report document inside the attachment: the envelope's, or the bare one. */ function reportDataOf(raw: unknown): unknown { const isEnvelope = typeof raw === 'object' && raw !== null && typeof (raw as { envelopeVersion?: unknown }).envelopeVersion === 'number' return isEnvelope ? (raw as { report: unknown }).report : raw } function migratedObservationLines( raw: unknown, report: Report, sheet: SheetIndex, opts: CompareOptions, ): string[][] { const v2 = ReportV2Schema.parse(reportDataOf(raw)) return v2.observations.map((legacy, i) => { const out = report.observations[i]! const severity = legacy.severity ? esc(`${legacy.severity} → ${out.severity}`) : 'none' const lines = [`[${esc(legacy.id)}] severity ${severity}`] legacy.zones.forEach((z, j) => { const line = describeZoneMigration(z, out.zones[j]!, sheet, opts.locale) lines.push(`zone ${line}`) }) legacy.findings.forEach((f, j) => { const line = describeFindingMigration( f, out.findings[j]!, sheet, opts.locale, ) lines.push(`finding ${line}`) }) lines.push(...textLines(legacy.freeTextFindings, opts.full)) lines.push(...fieldLine('comment ', legacy.comment, opts.full)) return lines }) } function countsOf(report: Report): Counts { const zones = report.observations.flatMap((o) => o.zones) const findings = report.observations.flatMap((o) => o.findings) return { observations: report.observations.length, zones: zones.length, unresolvedZones: zones.filter((z) => z.unresolved).length, findings: findings.length, unresolvedFindings: findings.filter((f) => f.unresolved).length, } } /** The envelope line: present only when the attachment was an archive. */ function archiveLine(outcome: ArchiveReadOutcome): string[] { if (outcome.archive) return ['archive v1 (snapshot kept)'] if (outcome.snapshotRejected) { return [`archive v1 (snapshot rejected: ${esc(outcome.snapshotRejected)})`] } return [] } function headerLines( source: 'v2' | 'v3', outcome: ArchiveReadOutcome, sheet: SheetIndex, opts: CompareOptions, ): string[] { const { report } = outcome const ref = sheet.sheet.ref const sameSheet = report.sheet.sheetId === ref.sheetId && report.sheet.documentSha256 === ref.documentSha256 const sheetLine = sameSheet ? `sheet ${esc(ref.sheetId)} (${sheet.sheet.status}, matches the bundled sheet)` : `sheet ${esc(report.sheet.sheetId)} !! written on another sheet document (sha ${esc(report.sheet.documentSha256.slice(0, 12))}…)` const c = countsOf(report) const lines = [ source === 'v2' ? 'v2 → v3 (migrated)' : 'v3 (read as is)', ...archiveLine(outcome), sheetLine, `id ${esc(report.id)} · date ${esc(report.date)} · ${c.observations} observations · ${c.zones} zones (${c.unresolvedZones} unresolved) · ${c.findings} findings (${c.unresolvedFindings} unresolved)`, ] if (opts.full) { lines.push( `practitioner ${q(report.practitioner.name)} · animal ${q(report.animal.name)} · owner ${q(report.owner.name)}`, ) } return lines } function footerLines(report: Report, full: boolean): string[] { const appointment = report.nextAppointment return [ ...fieldLine('conclusion', report.conclusion, full), ...fieldLine('recommendations', report.recommendations, full), ...(appointment ? [ full ? `next appointment ${esc(JSON.stringify(appointment))}` : `next appointment (${appointment.kind})`, ] : []), ] } /** * `raw` is the attachment as found in the PDF (bare report or envelope), * `outcome` its layered reading (`readArchiveDocument`); `outcome.migrated` * tells which vocabulary the lines use. */ export function compareReport( raw: unknown, outcome: ArchiveReadOutcome, sheet: SheetIndex, opts: CompareOptions, ): Comparison { const { report, migrated } = outcome const source = migrated ? 'v2' : 'v3' const v3Lines = report.observations.map((o) => observationLines(o, sheet, opts), ) // Same privacy default as the listing: texts are compared with `--full`. const normalized = [ ...report.observations.flatMap((o) => observationLines(o, sheet, opts)), ...footerLines(report, opts.full), ] return { source, header: headerLines(source, outcome, sheet, opts), observations: migrated ? migratedObservationLines(raw, report, sheet, opts) : v3Lines, footer: footerLines(report, opts.full), normalized, counts: countsOf(report), } } export function renderComparison(name: string, c: Comparison): string[] { return [ `== ${name}`, ...c.header.map((l) => ` ${l}`), ...c.observations.flatMap((lines) => lines.map((l, i) => (i === 0 ? ` ${l}` : ` ${l}`)), ), ...c.footer.map((l) => ` ${l}`), ] } export function renderSummary(name: string, c: Comparison): string { const n = c.counts return `${name} · ${c.source === 'v2' ? 'v2→v3' : 'v3'} · ${n.observations} obs · zones ${n.zones}/${n.unresolvedZones} unresolved · findings ${n.findings}/${n.unresolvedFindings} unresolved` } /** Lines of A absent from B and lines of B absent from A, in order. */ export function diffLines(a: string[], b: string[]): string[] { const inB = new Set(b) const inA = new Set(a) return [ ...a.filter((l) => !inB.has(l)).map((l) => `- ${l}`), ...b.filter((l) => !inA.has(l)).map((l) => `+ ${l}`), ] } export interface CliArgs extends CompareOptions { files: string[] summary: boolean diff: boolean } export function parseArgs(argv: string[]): CliArgs { const args: CliArgs = { files: [], locale: 'fr', full: false, summary: false, diff: false, } for (let i = 0; i < argv.length; i += 1) { const arg = argv[i]! if (arg === '--full') args.full = true else if (arg === '--summary') args.summary = true else if (arg === '--diff') args.diff = true else if (arg === '--locale') { const value = argv[++i] if (value !== 'fr' && value !== 'en') { throw new Error('--locale takes fr or en') } args.locale = value } else if (arg.startsWith('--')) throw new Error(`unknown option ${esc(arg)}`) else args.files.push(arg) } return args }