fix(importer): bind an existing file to the best title match, not the first (#2941)

[vavallee]

Summary

Refs #2941; complements #2978.

LibrarySnapshot.FindExisting returned the first file that cleared titleWordsMatch, not the best one. On the add author path that meant "Harry Potter" took an untracked "Harry Potter en het vervloekte kind.epub", skipped its search, and the exact book was then refused the file as already owned. #2978 fixes the same first match problem in the library scan's reconcileByTitle; this applies the same file ranking to the add paths (add author, add book, series fill, recommendations). No file in #2978's diff is changed except one godoc line in scanner.go that #2978 does not touch.

Implementation notes

Direction	Rule
Files for the book (bestExistingFile)	Score every matching file by Jaro-Winkler on normalised titles. The best answers when no file of a different title competes, when it is an exact normalised match strictly ahead, or when it leads by 0.05 (same margin as #2978). Otherwise no match, so the book stays Wanted and searchable. A title group answers with its best scoring member ("Dune" gets Dune.epub, not Dune 2.epub beside it).
Books for the files (dropRivalFiles)	Before ranking, a file is dropped when its normalised title is exactly another non excluded book's of the author and not the wanted one, so the next best file can answer ("Dune" still gets its own file beside "Dune Messiah.epub").

Why the second direction: when the library holds only the Dutch epub, ranking files cannot stop "Harry Potter" from taking it, because it is the only candidate. That is the exact layout in the report. Why exact only: an earlier scored version of this PR withdrew real matches during review ("Project Hail Mary A Novel.epub" vs a "Proyecto Hail Mary" row, "Mistborn.epub" vs the rest of the series, an excluded duplicate blocking the canonical book). All of those are now tests.

Wiring: FindExistingAmong(ctx, title, author, mediaType, rivals) on LibrarySnapshot, reached through a new optional rivalAwareFinder capability; LibraryFinder is unchanged. FetchAuthorBooks passes the catalogue it already holds (allBooks plus createdBooks) through handleNewWantedBookAmong. The single book callers read ListByAuthor once per new book. The rival aware lookup always runs, because dropping a rival's file can also settle a near tie. Excluded books and other users' books are not rivals.

Kept as before:

• Supplement tier (A .txt sidecar can claim a book's ebook slot ahead of the .epub, decided by directory walk order #2188, #2188's supplement ranking doesn't reach LibrarySnapshot.FindExisting, so a new book can be bound to a .cue.txt in another book's folder #2240) and the volume veto (FindExisting binds a newly added series volume to volume 1's file when filenames omit the volume number #2810, Library scan reconciles an untracked series volume onto a different wanted volume (title tier has no volume check) #2860).
• Files whose titles differ only in digits (tracks, parts, formats) are one title.
• A numbered book folder groups and scores its files and skips the rival step (Libation layout, FindExisting binds a newly added series volume to volume 1's file when filenames omit the volume number #2810).

Follow-ups (not in this PR)

• Known residual: with "Stormlight Archive The Way of Kings.epub" and "The Way of Kings Prime.epub" on disk but "The Way of Kings Prime" NOT in the catalogue, "The Way of Kings" binds the Prime file, because nothing marks it as another book and it outscores the real one.

Checklist

• Tests added or updated
• Doc-update gate cleared (godoc; Scanner.FindExisting godoc corrected)
• Changelog fragment changelog.d/findexisting-best-match.md

Test plan

Fail before, against main for the first commit and against the previous PR head for the review fixes:

• TestFetchAuthorBooks_FileGoesToExactTitleNotShorterBook, TestLibrarySnapshot_ExactTitleWinsRegardlessOfWalkOrder, TestLibrarySnapshot_AmbiguousTitlesBindNothing, TestLibrarySnapshot_RivalBookKeepsItsExactFile failed on main.
• TestLibrarySnapshot_PartialRivalDoesNotWithdrawFile (4 cases), TestLibrarySnapshot_GroupAnswersWithItsBestMember, TestHandleNewWantedBook_ExcludedRowDoesNotBlockBind failed on 500c4f6.
• TestLibrarySnapshot_RivalFileStepsAsideForNextBest (Way of Kings, Dune) and TestHandleNewWantedBook_RivalFileStepsAside failed on 2bc2c0d.

After (on the branch with origin/main merged in):

• gofmt -l: clean
• go vet ./internal/importer/ ./internal/api/
• golangci-lint v2.11.4 on ./internal/importer/... ./internal/api/...: 0 issues
• go test -timeout 40m ./internal/importer/... ./internal/api/...
• Earlier full go test ./cmd/... ./internal/... on the first commit: green except a load dependent timing budget in internal/duplicates (no importer dependency), which passed when rerun. Not rerun after the review fixes.

🤖 Generated with Claude Code

https://claude.ai/code/session_016fJcCVbNnKsmj2MAAMwWj9

[codecov]

Codecov Report

❌ Patch coverage is 95.61404% with 5 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/api/authors.go	81.48%	3 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!

[github-actions]

Reviewed the full diff + surrounding code. No blockers.

Correctness

dropRivalFiles runs before bestExistingFile, which is the right sequencing: rivals are pruned before ranking, so a rival's file can reveal the wanted file rather than just withdrawing the answer after the fact. The margin/exact-lead logic in clearLead matches #2978's scanner behaviour, keeping the two paths consistent.

fileBelongsToRival correctly rejects partial matches (only exact normalised title drops a file) and skips numbered-folder entries, which addresses the "Project Hail Mary A Novel.epub" and Mistborn series regressions documented in the PR description. All these cases are tested.

One double-normalisation call worth knowing about

findExistingForNewBook (authors.go:2958) calls snapshotFinder(finder), but on the add-author path the caller at line 2129 already snapshotted h.finder. When finder arrives as a *LibrarySnapshot, snapshotFinder returns it unchanged (no librarySnapshotter impl), so there is no bug — just a harmless extra interface check per call. Not a blocker, but worth knowing if you ever add SnapshotFinder() to LibrarySnapshot.

Two siblings paths fetch differently

• Pre-built path (runCatalogueSync): allBooks comes from ListByAuthorIncludingExcluded; excluded rows enter authorCatalogue but are filtered out in the rival loop (s.Excluded check at authors.go:2981). ✓
• Lazy path (findExistingForNewBook when siblings == nil): calls ListByAuthor, which already has excluded = 0. ✓

Both paths agree on the final rivals list. No bug, just worth documenting if this function is touched again.

Tenancy

Cross-user rivals are excluded from steering each other (authors.go:2985–2988). NULL-owner (global) books act as universal rivals for all users, which matches the existing tenancy model. ListByAuthor fetches unscoped rows but the filter handles the cross-user case before titles are passed to FindExistingAmong. No cross-user visibility issue.

License

JaroWinkler is internal/textutil, not a new external module. No new deps in go.mod.

Tests

12 new test functions covering walk-order independence, the ambiguous/no-answer case, partial rivals, numbered-folder carve-out, duplicate catalogue rows, and the end-to-end add-author path. Coverage matches the documented failure scenarios.

— 🤖 Bindery triage bot (automated). Reply to correct me; a human will see it.