README's "Ranking a Collection" example ranks the prefix match "Storage Provider" last, not first: actual scores are Data Store 19, AppDataStorage 17, Storage Provider 15

[matt-edmondson]

What's wrong

The README's only end-to-end example of the library's main use case, Ranking a Collection, prints this for pattern "stor":

// Storage Provider (Score: 15)
// Data Store (Score: 14)
// AppDataStorage (Score: 10)

Running the sample exactly as written against main (ebb0555) gives the opposite order:

Item	README	Actual
Data Store	14 (2nd)	19 (1st)
AppDataStorage	10 (3rd)	17 (2nd)
Storage Provider	15 (1st)	15 (3rd)

For comparison, "Storage" scores 22 and "Stor" 25.

Why it matters

A user who types stor gets the one candidate that starts with the pattern ranked last, behind a mid-word match. The README promises the opposite. Either the scoring has regressed, or the README advertises a ranking the library doesn't produce. The sample probably went stale when the prefix-penalty refund and cap changed (#82, #94 area), but I didn't bisect it.

The root of the order is that the per-letter unmatched penalty (unmatchedLetterPenalty, Fuzzy.cs:263) has no cap. "Storage Provider" is charged for its 12 trailing letters, and that outweighs its word-start and no-prefix advantage over "Data Store".

ReadmeTests.cs only checks that the API names used in the README exist, not what the samples print, so nothing caught the drift.

Suggested fix / acceptance criteria

• Decide which ranking is intended:
  • If a word-start prefix match should win, as the README says, reduce, scale or cap the trailing unmatched-letter penalty so that Storage Provider outranks Data Store for stor.
  • Otherwise, update the README's printed scores and order.
• Add a test that runs the README's ranking sample and asserts its printed order and scores, so the README can't drift again.

Related, but separate scoring issues: #89, #91.

[matt-edmondson]

Triage

• Category: Bug. The ranking in the README's main example is wrong, either because the documentation is out of date or because scoring has regressed.
• Priority: Medium. A maintainer has to decide the intended behavior: should a word-start prefix match beat a mid-word match? That decides whether this is a scoring change in Fuzzy.cs or a README fix. Either way, a test that runs the README sample should come with it.
• Area / suggested assignment: FuzzySearch/Fuzzy.cs (unmatchedLetterPenalty) and ReadmeTests.cs.
• Duplicates: none. Related scoring issues: Repeated pattern letters are sometimes free: "aaaaaaaaaab" scores the same as an exact "ab" and outranks "abx" #89 and Exact match scores lower than the same text with a suffix (Score("itemMap","item") = 32 > Score("item","item") = 25) #91. Changing the trailing-letter penalty will likely shift their results too, so review them together.
• In progress: no matching open PR.

---

Generated by Claude Code