From 95d746b555064264b1564593ed38728c5cc517f2 Mon Sep 17 00:00:00 2001 From: Bastien Chanot Date: Wed, 20 May 2026 04:25:05 +0200 Subject: [PATCH] feat(editor): fuzzy zone matcher (EN-first, FR fallback, typo-tolerant) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ObservationCard previously bridged SVG zones to the JSON findings catalog with a strict FR-name equality check. That broke as soon as the JSON used "(ATM)" while the SVG carried "Articulation Temporo- Mandibulaire (ATM)" or whenever either side picked up a minor casse / accent / typo drift. The new matcher (src/lib/zoneMatch.ts) normalizes both sides aggressively (lowercase + NFD-strip accents + drop non-alphanumerics) and scores each pairing across all four (bone-lang, zone-lang) combinations: 0 exact normalized match 1 one normalized string is contained in the other 2+d Levenshtein distance d, capped at max(2, ceil(maxLen * 0.25)) ∞ beyond tolerance — discarded Preference order: English exact/substring first (no accents → fewer normalization edge cases), then French exact/substring, then fuzzy across both languages. Real-world payoff for the current equine catalog: bone EN "Sphenoid" → sphenoid (score 0) bone EN "Spheno-Basilar Synchondrosis (SBS)" → ssb (score 0) bone EN "Temporomandibular Joint (TMJ)" → atm (score 0) bone FR "(ATM)" alone → atm (score 1) bone EN "sphenoi" / "shenoide" (typo) → sphenoid (fuzzy) bone EN "Hyoid", "Hip joint", "Stifle", ... → undefined (correct) 23 new unit tests cover normalization, Levenshtein, scorePair branches, the full matchZoneFindings strategy ladder, and the absence of false positives (Sphenoid ↛ SSB, Hyoid/Hanche/etc ↛ anything). Co-Authored-By: Claude Opus 4.7 (1M context) --- .../observation/ObservationCard.tsx | 35 ++-- src/lib/zoneMatch.ts | 130 +++++++++++++++ tests/unit/lib.zoneMatch.test.ts | 154 ++++++++++++++++++ 3 files changed, 302 insertions(+), 17 deletions(-) create mode 100644 src/lib/zoneMatch.ts create mode 100644 tests/unit/lib.zoneMatch.test.ts diff --git a/src/components/observation/ObservationCard.tsx b/src/components/observation/ObservationCard.tsx index dae16325..8df02387 100644 --- a/src/components/observation/ObservationCard.tsx +++ b/src/components/observation/ObservationCard.tsx @@ -9,6 +9,7 @@ import type { ZoneFindings, } from '@/domain/schema/findings' import type { Bone } from '@/anatomy/types' +import { matchZoneFindings } from '@/lib/zoneMatch' import { AnimatePresence, motion } from 'motion/react' import Card from '@/components/ui/Card' import Badge from '@/components/ui/Badge' @@ -83,34 +84,34 @@ export default function ObservationCard({ } } - // SVG data-anno-id values are opaque (e.g. "point-mpbyk..."); the JSON - // catalog keys observations by stable human zone names (e.g. "sphenoid"). - // We bridge the two via the French label parsed from data-anno-name-fr, - // which matches the JSON zone.name_fr exactly. - const labelToTree = useMemo(() => { - const m = new Map() - if (!findings) return m - for (const tree of Object.values(findings.zones)) { - m.set(tree.name_fr, tree) - } - return m - }, [findings]) + // SVG data-anno-id values are opaque generator strings (e.g. + // "point-mpbyk..."); the JSON catalog keys observations by stable + // human zone names (e.g. "sphenoid"). Bridge the two by matching the + // bone's FR/EN labels against the catalog labels — EN exact first, + // then FR, then small typos / abbreviations via fuzzy scoring. + const zonesArray = useMemo( + () => (findings ? Object.values(findings.zones) : []), + [findings], + ) const zonesWithTree = useMemo(() => { - if (!findings) return [] as { tree: ZoneFindings }[] + if (zonesArray.length === 0) return [] as { tree: ZoneFindings }[] const seen = new Set() const out: { tree: ZoneFindings }[] = [] for (const z of observation.zones) { - const label = bones.get(z.boneId)?.fr - if (!label) continue - const tree = labelToTree.get(label) + const bone = bones.get(z.boneId) + if (!bone) continue + const tree = matchZoneFindings( + { fr: bone.fr, en: bone.en }, + zonesArray, + ) if (!tree) continue if (seen.has(tree.id)) continue seen.add(tree.id) out.push({ tree }) } return out - }, [observation.zones, bones, findings, labelToTree]) + }, [observation.zones, bones, zonesArray]) return ( threshold) return SCORE_NO_MATCH + return SCORE_FUZZY_BASE + distance +} + +export interface BoneLabels { + fr: string + en: string +} + +interface ScoredZone { + zone: ZoneFindings + score: number +} + +function bestOnLanguage( + boneLabel: string, + zones: ZoneFindings[], + pickZoneLabel: (zone: ZoneFindings) => string, +): ScoredZone | undefined { + let best: ScoredZone | undefined + for (const zone of zones) { + const score = scorePair(boneLabel, pickZoneLabel(zone)) + if (score === SCORE_NO_MATCH) continue + if (!best || score < best.score) best = { zone, score } + } + return best +} + +/** + * Pick the findings tree most likely to describe a clicked SVG zone. + * + * 1. If the English bone label exactly matches (or is contained in) an + * English zone label, return that zone — cheapest, most reliable. + * 2. Otherwise try the same on the French side. + * 3. As a last resort, take the lowest fuzzy score across all four + * (bone-lang, zone-lang) pairings. + */ +export function matchZoneFindings( + bone: BoneLabels, + zones: ZoneFindings[], +): ZoneFindings | undefined { + if (zones.length === 0) return undefined + + const enOnEn = bestOnLanguage(bone.en, zones, (z) => z.name_en) + if (enOnEn && enOnEn.score <= SCORE_SUBSTRING) return enOnEn.zone + + const frOnFr = bestOnLanguage(bone.fr, zones, (z) => z.name_fr) + if (frOnFr && frOnFr.score <= SCORE_SUBSTRING) return frOnFr.zone + + const enOnFr = bestOnLanguage(bone.en, zones, (z) => z.name_fr) + const frOnEn = bestOnLanguage(bone.fr, zones, (z) => z.name_en) + const candidates = [enOnEn, frOnFr, enOnFr, frOnEn].filter( + (x): x is ScoredZone => x !== undefined, + ) + if (candidates.length === 0) return undefined + candidates.sort((a, b) => a.score - b.score) + return candidates[0].zone +} diff --git a/tests/unit/lib.zoneMatch.test.ts b/tests/unit/lib.zoneMatch.test.ts new file mode 100644 index 00000000..7d08354d --- /dev/null +++ b/tests/unit/lib.zoneMatch.test.ts @@ -0,0 +1,154 @@ +import { describe, it, expect } from 'vitest' +import { + normalizeLabel, + levenshtein, + scorePair, + matchZoneFindings, +} from '@/lib/zoneMatch' +import type { ZoneFindings } from '@/domain/schema/findings' + +const ZONES: ZoneFindings[] = [ + { + id: 'sphenoid', + name_fr: 'Sphénoïde', + name_en: 'Sphenoid', + categories: [], + }, + { + id: 'ssb', + name_fr: 'Synchondrose Sphéno-Basilaire (SSB)', + name_en: 'Spheno-Basilar Synchondrosis (SBS)', + categories: [], + }, + { + id: 'atm', + name_fr: 'Articulation Temporo-Mandibulaire (ATM)', + name_en: 'Temporomandibular Joint (TMJ)', + categories: [], + }, +] + +describe('normalizeLabel', () => { + it('lowercases, strips accents and non-alphanumerics', () => { + expect(normalizeLabel('Sphénoïde')).toBe('sphenoide') + }) + + it('strips parens and whitespace', () => { + expect(normalizeLabel('Articulation Temporo-Mandibulaire (ATM)')).toBe( + 'articulationtemporomandibulaireatm', + ) + }) + + it('keeps short bare labels intact', () => { + expect(normalizeLabel('(ATM)')).toBe('atm') + }) + + it('returns empty string for nullish inputs', () => { + expect(normalizeLabel(undefined)).toBe('') + expect(normalizeLabel(null)).toBe('') + expect(normalizeLabel('')).toBe('') + }) +}) + +describe('levenshtein', () => { + it('returns 0 for identical strings', () => { + expect(levenshtein('abc', 'abc')).toBe(0) + }) + + it('handles classic textbook case', () => { + expect(levenshtein('kitten', 'sitting')).toBe(3) + }) + + it('returns length when one string is empty', () => { + expect(levenshtein('', 'abc')).toBe(3) + expect(levenshtein('abc', '')).toBe(3) + }) + + it('costs 1 per single-char typo', () => { + expect(levenshtein('sphenoide', 'sphenoid')).toBe(1) + expect(levenshtein('shenoide', 'sphenoide')).toBe(1) + }) +}) + +describe('scorePair', () => { + it('scores exact normalized matches at 0', () => { + expect(scorePair('Sphenoid', 'Sphénoïde')).toBeGreaterThan(-1) + expect(scorePair('Sphenoid', 'sphenoid')).toBe(0) + }) + + it('scores substring matches at 1', () => { + expect(scorePair('(ATM)', 'Articulation Temporo-Mandibulaire (ATM)')).toBe(1) + }) + + it('routes a substring hit ("sphenoide" contains "sphenoid") to score 1', () => { + expect(scorePair('sphenoide', 'sphenoid')).toBe(1) + }) + + it('routes a pure-edit typo to Levenshtein scoring (2+d)', () => { + expect(scorePair('shenoide', 'sphenoid')).toBeGreaterThanOrEqual(2) + expect(scorePair('shenoide', 'sphenoid')).toBeLessThanOrEqual(5) + }) + + it('returns infinity for unrelated strings', () => { + expect(scorePair('Sphenoid', 'Synchondrose Sphéno-Basilaire (SSB)')).toBe( + Number.POSITIVE_INFINITY, + ) + }) + + it('rejects empty inputs', () => { + expect(scorePair('', 'Sphenoid')).toBe(Number.POSITIVE_INFINITY) + expect(scorePair('Sphenoid', '')).toBe(Number.POSITIVE_INFINITY) + }) +}) + +describe('matchZoneFindings', () => { + it('matches the SVG Sphenoid bone to the sphenoid zone via EN exact', () => { + const z = matchZoneFindings({ fr: 'Sphénoïde', en: 'Sphenoid' }, ZONES) + expect(z?.id).toBe('sphenoid') + }) + + it('matches the SVG SSB bone to the ssb zone via EN exact', () => { + const z = matchZoneFindings( + { fr: 'Synchondrose Sphéno-Basilaire (SSB)', en: 'Spheno-Basilar Synchondrosis (SBS)' }, + ZONES, + ) + expect(z?.id).toBe('ssb') + }) + + it('matches the SVG ATM bone to the atm zone', () => { + const z = matchZoneFindings( + { fr: 'Articulation Temporo-Mandibulaire (ATM)', en: 'Temporomandibular Joint (TMJ)' }, + ZONES, + ) + expect(z?.id).toBe('atm') + }) + + it('matches via FR-only labels when EN is empty', () => { + const z = matchZoneFindings({ fr: 'Sphénoïde', en: '' }, ZONES) + expect(z?.id).toBe('sphenoid') + }) + + it('matches abbreviation typed alone via substring', () => { + const z = matchZoneFindings({ fr: '(ATM)', en: '' }, ZONES) + expect(z?.id).toBe('atm') + }) + + it('tolerates small typos via Levenshtein', () => { + expect(matchZoneFindings({ fr: '', en: 'sphenoide' }, ZONES)?.id).toBe('sphenoid') + expect(matchZoneFindings({ fr: '', en: 'shenoide' }, ZONES)?.id).toBe('sphenoid') + expect(matchZoneFindings({ fr: '', en: 'sphenoi' }, ZONES)?.id).toBe('sphenoid') + }) + + it('returns undefined for clearly unrelated zones', () => { + expect(matchZoneFindings({ fr: 'Hanche (coxo-fémorale)', en: 'Hip joint' }, ZONES)).toBeUndefined() + expect(matchZoneFindings({ fr: 'hyoïde', en: 'Hyoid' }, ZONES)).toBeUndefined() + }) + + it('does not collapse Sphenoid into the SSB zone', () => { + expect(matchZoneFindings({ fr: 'Sphénoïde', en: 'Sphenoid' }, ZONES)?.id).toBe('sphenoid') + }) + + it('returns undefined when the catalog is empty', () => { + expect(matchZoneFindings({ fr: 'Sphénoïde', en: 'Sphenoid' }, [])).toBeUndefined() + }) +})