feat(editor): fuzzy zone matcher (EN-first, FR fallback, typo-tolerant)

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) <noreply@anthropic.com>
This commit is contained in:
Bastien ChanotandClaude Opus 4.7 committed 2026-05-20 04:25:05 +02:00
1 parent 1731adf620
commit 95d746b555
3 files changed
+302 -17

No files matched your search

+18 -17
View File
@@ -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<string, ZoneFindings>()
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<string>()
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 (
<Card
+130
View File
@@ -0,0 +1,130 @@
import type { ZoneFindings } from '@/domain/schema/findings'
/**
* Bridges SVG anatomy labels to the JSON findings catalog when the two
* carry slightly different strings (casse, accents, abbreviations like
* "(ATM)" vs "Articulation Temporo-Mandibulaire (ATM)", or genuine typos).
*
* Strategy: normalize aggressively (lowercase + NFD-strip accents + drop
* non-alphanumerics), then score each (boneLabel, zoneLabel) pair:
*
* 0 exact normalized match
* 1 one normalized string is contained in the other (substring)
* 2+d Levenshtein distance d, within a length-relative threshold
* ∞ beyond tolerance — discarded
*
* Language strategy: English first (no accents → fewer normalization
* edge cases), French as fallback, fuzzy matching across both languages
* as last resort. Falls through silently when nothing matches.
*/
export function normalizeLabel(s: string | undefined | null): string {
if (!s) return ''
return s
.toLowerCase()
.normalize('NFD')
.replace(/[\u0300-\u036f]/g, '')
.replace(/[^a-z0-9]+/g, '')
}
export function levenshtein(a: string, b: string): number {
if (a === b) return 0
const al = a.length
const bl = b.length
if (al === 0) return bl
if (bl === 0) return al
let prev: number[] = new Array(bl + 1)
let curr: number[] = new Array(bl + 1)
for (let j = 0; j <= bl; j += 1) prev[j] = j
for (let i = 1; i <= al; i += 1) {
curr[0] = i
for (let j = 1; j <= bl; j += 1) {
const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1
curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost)
}
const tmp = prev
prev = curr
curr = tmp
}
return prev[bl]
}
const SCORE_EXACT = 0
const SCORE_SUBSTRING = 1
const SCORE_FUZZY_BASE = 2
const SCORE_NO_MATCH = Number.POSITIVE_INFINITY
/**
* Compares two raw labels after normalization. Lower scores beat higher
* ones; SCORE_NO_MATCH means the inputs are too dissimilar to be linked
* confidently.
*/
export function scorePair(boneLabel: string, zoneLabel: string): number {
const a = normalizeLabel(boneLabel)
const b = normalizeLabel(zoneLabel)
if (!a || !b) return SCORE_NO_MATCH
if (a === b) return SCORE_EXACT
if (a.includes(b) || b.includes(a)) return SCORE_SUBSTRING
const distance = levenshtein(a, b)
const longest = Math.max(a.length, b.length)
// 25% character tolerance, with a minimum of 2 edits so short labels
// (e.g. "Hip") still admit one typo without exploding into the matcher.
const threshold = Math.max(2, Math.floor(longest * 0.25))
if (distance > 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
}
+154
View File
@@ -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()
})
})