Resolve companion ranges across filename case differences

[imnasnainaec]

A LIFT folder written on Windows can spell its pair inconsistently — Dict.LIFT beside Dict.lift-ranges, or the reverse — and load fine there, because the filesystem folds case. On a case-sensitive filesystem the sibling candidate is built from the .lift's own name, so it missed: the companion was skipped silently, and every range it defined went absent.

Zip packages inherit the fix: load_zip extracts and calls Lexicon.load, so _zip.py needs no change.

Matching a companion filename

A candidate that matches no file exactly falls back to one whose name folds onto it (_folded_matches).

• Reached only after an exact miss, so it can only turn a miss into a hit — an exact match is always returned as-is. A case variant sitting beside an exactly named companion is not a collision, and the cost lands only where the lookup was already failing.
• Case and normalization form — casefold() over NFC, not lower(). Decomposed filenames arrive from macOS, which stores and zips them that way, and neither NTFS nor ext4 folds the two forms.
• Only the final path component, so an href under a directory spelled in another case still does not resolve. The hrefs this serves are bare basenames or same-folder relatives.
• One directory read per folder, cached across a load's candidates.

Three things the fallback must not resolve to

Each is reachable once a miss can match something other than the exact name:

• The .lift itself. A header href spelling Dict.lift beside a Dict.LIFT folds onto the lexicon, and RangesFile.load rejects a <lift> root — failing the whole load rather than skipping one companion.
• A file beside a folder. An href of "" normalizes to the LIFT folder itself. Folding a folder's own name searches its parent, so any file up there spelled like the folder came back as the companion. A candidate that exists as a directory stops the lookup.
• A companion already tracked. Path.resolve() leaves case alone on macOS, so one file reached under two spellings was loaded twice and written twice by save().

An ambiguous name resolves to nothing

Where several files in the folder fold onto one candidate, which of them the name meant is not recoverable — the filesystem that wrote them could not have told them apart. None is loaded, and validation reports the collision as a new ambiguous-ranges-file warning:

warning [ambiguous-ranges-file] Dict.LIFT: companion 'Dict.LIFT-ranges' matches
'Dict.Lift-ranges', 'Dict.lift-ranges'; they differ only in case or Unicode
normalization, so none of them is loaded

• Every spelling named by code point, since two can differ only in normalization and render identically.
• One finding per colliding group, however many candidate names fold onto it.
• The sibling name is covered too — the case no header href reports on, and the one a folder authored on Windows most often collides over.

--strict promotes the warning to an error, so a CI run can refuse such a folder outright.

Validation and loading agree on what exists

dangling-ranges-href decides existence with the same lookup and the same refusals, so a companion spelled in another case is no longer reported missing on a case-sensitive filesystem, and an href resolving to the .lift still warns. Where a collision blocks the lookup both findings appear: one says why nothing resolved, the other which range went unmet. _same_file resolves its own arguments rather than trusting the caller's spelling, so the two sides cannot disagree about a path spelled two ways.

The candidate list moved out of _resolve_ranges into _ranges_candidates for validation to walk, and yields each path once — an href repeated across ranges, or agreeing with the sibling, was looked up as many times as it was written. Building the sibling candidate with with_name rather than with_suffix also keeps a .lift loaded under a name with no extension from raising, which parse_document has always accepted.

Tests

Twelve in test_ranges_folder.py. Two spellings of one name cannot coexist where the filesystem folds them together, so:

• Three tests need a case-sensitive filesystem and skip elsewhere.
• The collision test that runs everywhere separates its two companions by which of two accents is decomposed — the one difference NTFS and APFS keep — so the refusal, the warning, and the per-group deduplication are exercised on the Windows leg too. It skips only where normalization forms fold, as on macOS.

python scripts/check.py green: 581 passed, 3 skipped, 97.55% coverage.

Media hrefs have the same case problem and are deliberately untouched here — #34 carries the design question that makes them different from companions.

🤖 Generated with Claude Code

---

Devin review: https://app.devin.ai/review/sillsdev/python-sil-lift/pull/19

---

This change is

[jasonleenaylor]

@jasonleenaylor reviewed 5 files and all commit messages.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on imnasnainaec).

[jasonleenaylor]

This looks good and I am for merging it. with_name over with_suffix also quietly fixes a latent ValueError on an extensionless .lift, which parse_document has always accepted.

One question inline, which I expect has a good answer.

This review was assisted by Claude Opus 5.

[jasonleenaylor]

A fold match that turns out not to be a ranges document takes the whole load down with it. A folder holding Ñandú.lift (NFC) beside a Ñandú.lift-ranges (NFD) whose root is not <lift-ranges> raises LiftParseError out of load() — I ran it — where on a case-sensitive filesystem it previously loaded fine with no companion tracked.

That is the same outcome the .lift refusal above exists to prevent, and the reasoning there — failing the whole load rather than skipping one companion — reads like it generalizes to any folded match. I expect the answer is that a file named X.lift-ranges in any spelling that is not a ranges document is a broken folder and deserves to be loud, and that an exactly-named companion and a folded one are alike in that respect. Was the asymmetry deliberate?

[imnasnainaec]

Deliberate, and your expected answer is the one. The .lift skip is identity, not error tolerance: the file is the document being loaded, so nothing there is a companion whatever it holds. (A name claiming to be a ranges document is different, and exact and folded matches behave alike there.)

Skipping would also be silent in your example: a sibling match leaves no href to dangle and no collision to report, so on main that folder loads and validates clean. To address the source of the question: 2928de6 gives the
identity reason instead of the crash; d8b1a9b pins the counterpart in a new test.

--drafted by Claude; lightly edited by me--

[imnasnainaec]

@imnasnainaec reviewed 5 files and all commit messages.
Reviewable status: 2 of 5 files reviewed, all discussions resolved (waiting on jasonleenaylor).