diff --git a/apps/app/scripts/compare-reports.ts b/apps/app/scripts/compare-reports.ts index 80d30e17..3ca73abc 100644 --- a/apps/app/scripts/compare-reports.ts +++ b/apps/app/scripts/compare-reports.ts @@ -2,14 +2,17 @@ * Archive check: reads the report attached to one or more Faunosteo PDFs and * prints it next to its v3 reading on the bundled reference sheet. * - * pnpm report:compare ... [--summary] [--identity] + * pnpm report:compare ... [--summary] [--full] * [--locale fr|en] [--diff a.pdf b.pdf] * * A v2 archive PDF is shown legacy id → canonical id, line by line; a v3 PDF * is checked against the sheet. Items the sheet cannot place are marked * `!! UNRESOLVED` with the reason. `--diff` compares the v3 content of two - * PDFs (an archive and its re-export after import, typically). Names are - * printed only with `--identity`. Reads only; never writes a file. + * PDFs (an archive and its re-export after import, typically) and prints a + * differing text line in clear. By default only identifiers, catalog labels, + * counts and placeholders are printed; names and free texts need `--full`. + * Untrusted strings are printed with control characters escaped. It writes + * no output file. */ import { readFileSync, readdirSync, statSync } from 'node:fs' import { basename, join, resolve } from 'node:path' @@ -27,6 +30,7 @@ import { buildSheetIndex, type SheetIndex } from '../src/services/sheetIndex' import { compareReport, diffLines, + esc, parseArgs, renderComparison, renderSummary, @@ -56,18 +60,18 @@ function loadSheet(): SheetIndex { ) } -function expandFiles(args: string[]): string[] { - const out: string[] = [] - for (const arg of args) { - const path = resolve(CWD, arg) - if (statSync(path).isDirectory()) { - const pdfs = readdirSync(path) - .filter((f) => f.toLowerCase().endsWith('.pdf')) - .sort() - out.push(...pdfs.map((f) => join(path, f))) - } else out.push(path) +/** A folder stands for its PDFs; any other argument stays one entry. */ +function expandArg(arg: string): string[] { + const path = resolve(CWD, arg) + try { + if (!statSync(path).isDirectory()) return [path] + } catch { + return [path] // reported as a failed entry by compareFile } - return out + return readdirSync(path) + .filter((f) => f.toLowerCase().endsWith('.pdf')) + .sort() + .map((f) => join(path, f)) } async function compareFile( @@ -75,8 +79,8 @@ async function compareFile( sheet: SheetIndex, args: CliArgs, ): Promise { + if (statSync(path).size > MAX_PDF_BYTES) throw new Error('file too large') const bytes = new Uint8Array(readFileSync(path)) - if (bytes.byteLength > MAX_PDF_BYTES) throw new Error('file too large') const pdf = await PDFDocument.load(bytes, { ignoreEncryption: true }) const raw = await readAttachedDocument(pdf) const version = (raw as { version: number }).version @@ -91,12 +95,20 @@ async function compareFile( } } +/** A missing or unreadable file is a failed entry, not a crash. */ +function failureReason(err: unknown): string { + const code = (err as NodeJS.ErrnoException | undefined)?.code + if (code === 'ENOENT') return 'file not found' + if (code === 'EACCES') return 'file not readable' + return err instanceof Error ? err.message : String(err) +} + async function main(argv: string[]): Promise { const args = parseArgs(argv) - const files = expandFiles(args.files) + const files = args.files.flatMap(expandArg) if (files.length === 0 || (args.diff && files.length !== 2)) { console.error( - 'usage: pnpm report:compare ... [--summary] [--identity] [--locale fr|en] [--diff a.pdf b.pdf]', + 'usage: pnpm report:compare ... [--summary] [--full] [--locale fr|en] [--diff a.pdf b.pdf]', ) return 1 } @@ -104,7 +116,7 @@ async function main(argv: string[]): Promise { const results: Comparison[] = [] let failures = 0 for (const file of files) { - const name = basename(file) + const name = esc(basename(file)) try { const c = await compareFile(file, sheet, args) results.push(c) @@ -116,7 +128,7 @@ async function main(argv: string[]): Promise { } } catch (err) { failures += 1 - console.log(`!! ${name}: ${err instanceof Error ? err.message : err}`) + console.log(`!! ${name}: ${esc(failureReason(err))}`) } } if (args.diff && results.length === 2) { @@ -129,7 +141,7 @@ async function main(argv: string[]): Promise { main(process.argv.slice(2)).then( (code) => process.exit(code), (err) => { - console.error(err instanceof Error ? err.message : err) + console.error(esc(err instanceof Error ? err.message : String(err))) process.exit(1) }, ) diff --git a/apps/app/scripts/compare/report.ts b/apps/app/scripts/compare/report.ts index 451f6b1a..e55f1d83 100644 --- a/apps/app/scripts/compare/report.ts +++ b/apps/app/scripts/compare/report.ts @@ -22,8 +22,8 @@ export const UNRESOLVED = '!! UNRESOLVED' export interface CompareOptions { locale: Locale - /** Print practitioner, animal and owner names (off by default). */ - identity: boolean + /** Print names and the real free texts (off by default: placeholders). */ + full: boolean } export interface Comparison { @@ -45,22 +45,47 @@ export interface Counts { unresolvedFindings: number } -const q = (text: string) => `"${text}"` +/** + * Escapes C0, DEL and C1 control characters 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( + /[\u0000-\u001f\u007f-\u009f]/g, + (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`, + ) +} + +const q = (text: string) => `"${esc(text)}"` function zoneRef(z: { annotationId: string; viewId: string; side?: string }) { - return `${z.annotationId}@${z.viewId}${z.side ? ' ' + z.side : ''}` + return esc(`${z.annotationId}@${z.viewId}${z.side ? ' ' + z.side : ''}`) } function findingRef(f: { findingZoneId: string; path: readonly string[] }) { - return findingPathKey(f.findingZoneId, f.path) + return esc(findingPathKey(f.findingZoneId, f.path)) } function vertebraeOf(z: { vertebrae?: { region: string; index: number }[] }) { return z.vertebrae?.length - ? ` [${z.vertebrae.map((v) => `${v.region}${v.index}`).join(', ')}]` + ? ` [${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, @@ -86,7 +111,7 @@ function describeFinding( ): string { const snapshot = q(locale === 'en' ? f.labelEnSnapshot : f.labelFrSnapshot) const vet = f.requiresVetReferral ? ' (!)' : '' - const side = f.side ? ` ${f.side}` : '' + const side = f.side ? ` ${esc(f.side)}` : '' const ref = `${findingRef(f)}${side}${vet}` if (f.unresolved) { return `${ref} ${snapshot} ${UNRESOLVED} kept with its snapshot` @@ -107,7 +132,8 @@ function describeZoneMigration( locale: Locale, ): string { const side = legacy.side ? ` ${legacy.side}` : '' - const from = `${legacy.boneId}${legacy.detailSourceId ? '@' + legacy.detailSourceId : ''}${side}${vertebraeOf(legacy)}` + 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)}` } @@ -125,22 +151,20 @@ function describeFindingMigration( ): string { const map = sheet.sheet.migrationMap.finding_paths const vet = legacy.requiresVetReferral ? ' (!)' : '' - const key = `${findingPathKey(legacy.zoneId, legacy.path)}${vet}` + 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, findingPathKey(legacy.zoneId, legacy.path)) + 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) === findingPathKey(legacy.zoneId, legacy.path) - ? 'same' - : findingRef(out) + const target = findingRef(out) === esc(legacyKey) ? 'same' : findingRef(out) return `${key} ${snapshot} → ${target} ${label}` } @@ -150,14 +174,14 @@ function observationLines( opts: CompareOptions, ): string[] { const lines = [ - `[${obs.id}] severity ${obs.severity ?? 'none'}`, + `[${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)}`, ), - ...obs.freeTextFindings.map((t) => `text ${q(t)}`), + ...textLines(obs.freeTextFindings, opts.full), + ...fieldLine('comment ', obs.comment, opts.full), ] - if (obs.comment) lines.push(`comment ${q(obs.comment)}`) return lines } @@ -171,9 +195,9 @@ function migratedObservationLines( return v2.observations.map((legacy, i) => { const out = report.observations[i]! const severity = legacy.severity - ? `${legacy.severity} → ${out.severity}` + ? esc(`${legacy.severity} → ${out.severity}`) : 'none' - const lines = [`[${legacy.id}] severity ${severity}`] + 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}`) @@ -187,8 +211,8 @@ function migratedObservationLines( ) lines.push(`finding ${line}`) }) - lines.push(...legacy.freeTextFindings.map((t) => `text ${q(t)}`)) - if (legacy.comment) lines.push(`comment ${q(legacy.comment)}`) + lines.push(...textLines(legacy.freeTextFindings, opts.full)) + lines.push(...fieldLine('comment ', legacy.comment, opts.full)) return lines }) } @@ -216,15 +240,15 @@ function headerLines( report.sheet.sheetId === ref.sheetId && report.sheet.documentSha256 === ref.documentSha256 const sheetLine = sameSheet - ? `sheet ${ref.sheetId} (${sheet.sheet.status}, matches the bundled sheet)` - : `sheet ${report.sheet.sheetId} !! written on another sheet document (sha ${report.sheet.documentSha256.slice(0, 12)}…)` + ? `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)', sheetLine, - `id ${report.id} · date ${report.date} · ${c.observations} observations · ${c.zones} zones (${c.unresolvedZones} unresolved) · ${c.findings} findings (${c.unresolvedFindings} unresolved)`, + `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.identity) { + if (opts.full) { lines.push( `practitioner ${q(report.practitioner.name)} · animal ${q(report.animal.name)} · owner ${q(report.owner.name)}`, ) @@ -232,16 +256,19 @@ function headerLines( return lines } -function footerLines(report: Report): string[] { - const lines: string[] = [] - if (report.conclusion) lines.push(`conclusion ${q(report.conclusion)}`) - if (report.recommendations) { - lines.push(`recommendations ${q(report.recommendations)}`) - } - if (report.nextAppointment) { - lines.push(`next appointment ${JSON.stringify(report.nextAppointment)}`) - } - 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})`, + ] + : []), + ] } /** @@ -260,14 +287,20 @@ export function compareReport( const v3Lines = report.observations.map((o) => observationLines(o, sheet, opts), ) + // A diff must see a lost conclusion: its lines always carry the full texts. + const fullOpts = { ...opts, full: true } + const normalized = [ + ...report.observations.flatMap((o) => observationLines(o, sheet, fullOpts)), + ...footerLines(report, true), + ] return { source, header: headerLines(source, report, sheet, opts), observations: migrated ? migratedObservationLines(raw, report, sheet, opts) : v3Lines, - footer: footerLines(report), - normalized: [...v3Lines.flat(), ...footerLines(report)], + footer: footerLines(report, opts.full), + normalized, counts: countsOf(report), } } @@ -308,13 +341,13 @@ export function parseArgs(argv: string[]): CliArgs { const args: CliArgs = { files: [], locale: 'fr', - identity: false, + full: false, summary: false, diff: false, } for (let i = 0; i < argv.length; i += 1) { const arg = argv[i]! - if (arg === '--identity') args.identity = true + if (arg === '--full') args.full = true else if (arg === '--summary') args.summary = true else if (arg === '--diff') args.diff = true else if (arg === '--locale') { @@ -323,7 +356,8 @@ export function parseArgs(argv: string[]): CliArgs { throw new Error('--locale takes fr or en') } args.locale = value - } else if (arg.startsWith('--')) throw new Error(`unknown option ${arg}`) + } else if (arg.startsWith('--')) + throw new Error(`unknown option ${esc(arg)}`) else args.files.push(arg) } return args diff --git a/apps/app/src/pdf/import.ts b/apps/app/src/pdf/import.ts index 3080ce88..e4a4ee8e 100644 --- a/apps/app/src/pdf/import.ts +++ b/apps/app/src/pdf/import.ts @@ -26,14 +26,14 @@ export class ImportError extends Error { } } +/** A Faunosteo PDF weighs a few hundred KB; anything larger is not one. */ +export const MAX_PDF_BYTES = 50 * 1024 * 1024 + /** * Reads a Faunosteo PDF back into a report document (v3, or v2 migrated * through the reference sheet's map). The outcome says whether a migration * happened and how many zones or findings it could not place. */ -/** A Faunosteo PDF weighs a few hundred KB; anything larger is not one. */ -export const MAX_PDF_BYTES = 50 * 1024 * 1024 - export async function importReportFromPdf( pdfBytes: Uint8Array, map: ReportMigrationMap, diff --git a/apps/app/tests/unit/scripts.compare.test.ts b/apps/app/tests/unit/scripts.compare.test.ts index 568337fb..6f388cab 100644 --- a/apps/app/tests/unit/scripts.compare.test.ts +++ b/apps/app/tests/unit/scripts.compare.test.ts @@ -21,7 +21,7 @@ import { import { loadTestSheet, minimalReport } from '../helpers/sheet' const HERE = dirname(fileURLToPath(import.meta.url)) -const OPTS = { locale: 'fr' as const, identity: false } +const OPTS = { locale: 'fr' as const, full: false } let sheet: SheetIndex @@ -31,10 +31,10 @@ function minimalV2(): ReportV2 { ) as ReportV2 } -function compareRaw(raw: unknown, identity = false) { +function compareRaw(raw: unknown, full = false) { const outcome = readReportDocument(raw, sheet.sheet.migrationMap) const migrated = (raw as { version: number }).version !== 3 - return compareReport(raw, outcome, migrated, sheet, { ...OPTS, identity }) + return compareReport(raw, outcome, migrated, sheet, { ...OPTS, full }) } beforeAll(async () => { @@ -70,6 +70,7 @@ describe('compareReport on the frozen v2 archive PDF', () => { 'full.pdf · v2→v3 · 3 obs · zones 5/0 unresolved · findings 4/0 unresolved', ) expect(lines.join('\n')).not.toContain('practitioner') + expect(lines.join('\n')).not.toContain('Dupont') expect(renderComparison('x', compareRaw(raw, true)).join('\n')).toContain( 'practitioner "Dr. Claire Dupont"', ) @@ -192,12 +193,103 @@ describe('diff and arguments', () => { expect(parseArgs(['a.pdf', '--summary', 'dir', '--locale', 'en'])).toEqual({ files: ['a.pdf', 'dir'], locale: 'en', - identity: false, + full: false, summary: true, diff: false, }) - expect(parseArgs(['--identity', '--diff', 'a', 'b']).identity).toBe(true) + expect(parseArgs(['--full', '--diff', 'a', 'b']).full).toBe(true) + expect(() => parseArgs(['--identity'])).toThrow('unknown option') expect(() => parseArgs(['--locale', 'de'])).toThrow('fr or en') expect(() => parseArgs(['--json'])).toThrow('unknown option') }) }) + +describe('terminal safety and privacy', () => { + const ESC = '\u001b[2K' + + it('escapes control characters in every untrusted string', () => { + const report = minimalReport(sheet, { + observations: [ + { + id: `o${ESC}\n1`, + zones: [], + findings: [ + { + findingZoneId: 'hip', + path: ['hip-dysfunctions', `x${ESC}\ny`], + labelFrSnapshot: `L${ESC}`, + labelEnSnapshot: 'L', + unresolved: true, + }, + ], + freeTextFindings: [`t${ESC}\nu`], + comment: `c${ESC}\nd`, + }, + ], + }) + const lines = renderComparison('x', compareRaw(report, true)) + const text = lines.join('\n') + expect(text).not.toContain('\u001b') + expect(lines.every((l) => !l.includes('\n'))).toBe(true) + expect(text).toContain('\\u001b') + expect(text).toContain('\\u000a') + expect(text).toContain('[o\\u001b[2K\\u000a1]') + }) + + it('does not throw on prototype-chain names used as legacy ids', () => { + const v2: ReportV2 = { + ...minimalV2(), + observations: [ + { + id: 'o', + zones: [{ boneId: '__proto__' }, { boneId: 'constructor' }], + findings: [ + { + zoneId: '__proto__', + path: ['constructor'], + labelFrSnapshot: 'X', + labelEnSnapshot: 'X', + }, + ], + freeTextFindings: [], + comment: '', + }, + ], + } + const text = renderComparison('p.pdf', compareRaw(v2)).join('\n') + expect(text).toContain(`__proto__ ${UNRESOLVED}`) + expect(text).toContain(`constructor ${UNRESOLVED}`) + expect(text).toContain(`__proto__/constructor "X" ${UNRESOLVED}`) + }) + + it('hides names and free texts by default, shows them with --full', () => { + const report = minimalReport(sheet, { + conclusion: 'SECRET-CONCLUSION', + recommendations: 'SECRET-RECO', + nextAppointment: { kind: 'period', text: 'SECRET-WHEN' }, + observations: [ + { + id: 'o', + zones: [], + findings: [], + freeTextFindings: ['SECRET-TEXT'], + comment: 'SECRET-COMMENT', + }, + ], + }) + const hidden = renderComparison('x', compareRaw(report)).join('\n') + expect(hidden).not.toContain('SECRET') + expect(hidden).toContain('text (1 entries)') + expect(hidden).toContain('comment (present)') + expect(hidden).toContain('conclusion (present)') + expect(hidden).toContain('recommendations (present)') + expect(hidden).toContain('next appointment (period)') + const shown = renderComparison('x', compareRaw(report, true)).join('\n') + for (const word of ['TEXT', 'COMMENT', 'CONCLUSION', 'RECO', 'WHEN']) { + expect(shown).toContain(`SECRET-${word}`) + } + expect(compareRaw(report).normalized.join('\n')).toContain( + 'SECRET-CONCLUSION', + ) + }) +}) diff --git a/docs/PDF-FORMAT.md b/docs/PDF-FORMAT.md index 1ffd04d2..e8a5bb60 100644 --- a/docs/PDF-FORMAT.md +++ b/docs/PDF-FORMAT.md @@ -33,7 +33,7 @@ Import (`importReportFromPdf(bytes, migrationMap)`) accepts: `pnpm report:compare ...` reads the attachment of one or more PDFs and prints it next to its v3 reading on the bundled reference -sheet, without writing anything: +sheet. It writes no output file: - a v2 archive PDF: every legacy zone (`data-anno-id`, side, vertebrae) and every legacy finding path is shown with its canonical target and the @@ -46,8 +46,12 @@ sheet, without writing anything: finding flagged `unresolved` in the report itself. Options: `--summary` (one line per file, counts and unresolved counts), -`--identity` (print the practitioner, animal and owner names, off by -default), `--locale fr|en` (labels), `--diff a.pdf b.pdf` (compare the v3 +`--full` (add the practitioner, animal and owner names and the real free +texts; by default only identifiers, catalog labels, snapshots of unresolved +items, counts and placeholders such as `comment (present)` are printed), +`--locale fr|en` (labels), `--diff a.pdf b.pdf` (compare the v3 content of two PDFs: an archive and the PDF exported after importing it -should print `identical v3 content`). The tool exits 2 when a file could not +should print `identical v3 content`; a differing text line is printed in +clear, whatever `--full`). Every untrusted string is printed with control +characters escaped as `\uXXXX`. The tool exits 2 when a file could not be read (no attachment, unknown version, oversized) and prints the reason. diff --git a/packages/anatomy/tests/legacy.regions.test.ts b/packages/anatomy/tests/legacy.regions.test.ts new file mode 100644 index 00000000..6cc082db --- /dev/null +++ b/packages/anatomy/tests/legacy.regions.test.ts @@ -0,0 +1,43 @@ +import { describe, expect, it } from 'vitest' +import { inferRegionCode } from '../src/legacy/regions' + +const code = (fr: string | null, en: string | null = null) => + inferRegionCode(fr, en)?.code + +describe('inferRegionCode', () => { + it('matches FR roots, with and without accents', () => { + expect(code('Vertèbres cervicales')).toBe('C') + expect(code('Vertebres cervicales')).toBe('C') + expect(code('Vertèbres thoraciques')).toBe('T') + expect(code('Vertebres thoraciques')).toBe('T') + expect(code('Vertèbres lombaires')).toBe('L') + expect(code('Vertèbres sacrales')).toBe('S') + expect(code('Vertèbres sacrées')).toBe('S') + expect(code('Vertèbres caudales')).toBe('Cd') + expect(code('Vertèbres coccygiennes')).toBe('Cd') + expect(code('Région dorsale')).toBe('T') + }) + + it('matches EN roots when the FR label is absent', () => { + expect(code(null, 'Cervical Vertebrae')).toBe('C') + expect(code(null, 'Thoracic Vertebrae')).toBe('T') + expect(code(null, 'Lumbar Vertebrae')).toBe('L') + expect(code(null, 'Sacral Vertebrae')).toBe('S') + expect(code(null, 'Coccygeal Vertebrae')).toBe('Cd') + }) + + it('returns null when no root matches', () => { + expect(inferRegionCode('Épaule', 'Shoulder')).toBeNull() + expect(inferRegionCode('', '')).toBeNull() + expect(inferRegionCode(null, null)).toBeNull() + }) + + it('reports the matched root and label, FR before EN', () => { + expect(inferRegionCode('Vertèbres lombaires', 'Cervical')).toEqual({ + code: 'L', + root: 'lombair', + label: 'Vertèbres lombaires', + }) + expect(code('Épaule', 'Cervical Vertebrae')).toBe('C') + }) +})