386 lines
13 KiB
TypeScript
386 lines
13 KiB
TypeScript
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
|
|
}
|