fzy_score 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a6f6146dd91063312cd225fe2d7c73f76fa5a3ddb4859138a5a37740320ce1d6
+  data.tar.gz: 3ab14c673a173547b8e8e41a1f6678468394da630a38cb84572121aa5ad809d1
+SHA512:
+  metadata.gz: 46e4486951489bc057893837456250c2f3e17e4c2f4b48ad3768bf2e04cee2419b7140f298120ba772ae6363ff60e3eb013a171bae7a052655c3112994d50712
+  data.tar.gz: bc864f1b8639a15d3ee41820e16dfd93c9bff85d47d127fe237adc4918949466f55c0a405d31330595b158e095e56ff3f01046a516c49235a743b9100cf6cd38

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-28
+
+### Added
+- Initial release.
+- `FzyScore.score(needle, haystack)` — relevance score (higher is better).
+- `FzyScore.match(needle, haystack, positions:)` — score plus matched positions
+  for highlighting, returned as a `FzyScore::Match`.
+- `FzyScore.match?(needle, haystack)` — O(n) boolean pre-filter.
+- `FzyScore.filter(needle, candidates, positions:, key:)` — rank a list,
+  best-first, with stable tie-breaking and an optional key extractor.
+- Faithful port of fzy's scoring constants from `config.def.h`.
+
+[Unreleased]: https://github.com/tachyurgy/fzy_score/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/tachyurgy/fzy_score/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,40 @@
+MIT License
+
+Copyright (c) 2026 Levelbrook Consulting
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The scoring algorithm and constants in this gem are ported from fzy
+(https://github.com/jhawthorn/fzy), which is also MIT licensed:
+
+Copyright (c) 2014 John Hawthorn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

data/README.md

@@ -0,0 +1,126 @@
+# fzy_score
+
+A tiny, dependency-free Ruby port of the [fzy](https://github.com/jhawthorn/fzy)
+fuzzy-matching **scoring** algorithm — the same family of algorithm used by
+[fzf](https://github.com/junegunn/fzf) and [fzf-for-js](https://github.com/ajitid/fzf-for-js).
+
+Unlike Ruby's existing fuzzy gems (which solve *record linkage* with
+Levenshtein/Dice/Jaro, or only answer the boolean "does it match?"),
+`fzy_score` returns **both a relevance score and the matched character
+positions** — exactly what you need to build:
+
+- a command palette / quick-open
+- an autocomplete dropdown
+- a CLI picker with highlighted matches
+
+It's pure Ruby, has zero runtime dependencies, and ports fzy's published
+scoring constants verbatim so ranking matches the reference tool.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "fzy_score"
+```
+
+```sh
+gem install fzy_score
+```
+
+## Usage
+
+### Score a single candidate
+
+```ruby
+require "fzy_score"
+
+FzyScore.score("amf", "app/models/foo.rb")  # => 3.58 (higher is better)
+FzyScore.score("zzz", "app/models/foo.rb")  # => -Infinity (no match)
+FzyScore.score("abc", "abc")                # => Infinity (exact match)
+```
+
+### Get matched positions for highlighting
+
+```ruby
+m = FzyScore.match("amu", "app/models/user.rb")
+m.score       # => Float
+m.positions   # => [0, 4, 11]   indices into the haystack to highlight
+m.matched?    # => true
+
+# Highlight in a terminal:
+def highlight(haystack, positions)
+  set = positions.to_set
+  haystack.each_char.with_index.map { |c, i| set.include?(i) ? "\e[33m#{c}\e[0m" : c }.join
+end
+puts highlight("app/models/user.rb", m.positions)
+```
+
+### Filter and rank a list (best first)
+
+```ruby
+files = ["spec/match_spec.rb", "src/match.rb", "README.md"]
+
+FzyScore.filter("srcmatch", files)
+# => [["src/match.rb", 6.97, nil]]   (non-matches dropped, sorted best-first)
+
+# Want positions too?
+FzyScore.filter("srcmatch", files, positions: true)
+# => [["src/match.rb", 6.97, [0,1,2,4,5,6,7,8]]]
+
+# Filtering objects? Pass a key extractor — the original object comes back.
+people = [{ name: "Alice" }, { name: "Bob" }, { name: "Albert" }]
+FzyScore.filter("al", people, key: ->(p) { p[:name] })
+# => [[{name: "Albert"}, ...], [{name: "Alice"}, ...]]
+```
+
+### Cheap pre-filter
+
+If you only need to know *whether* something matches (no scoring), use the
+O(n) predicate:
+
+```ruby
+FzyScore.match?("amf", "app/models/foo.rb")  # => true
+```
+
+`filter` already uses this internally to skip the DP for non-matches.
+
+## How scoring works
+
+`fzy_score` implements fzy's modified Smith–Waterman dynamic program. Matches
+earn bonuses for landing at "good" places and pay small penalties for gaps:
+
+| Situation | Bonus / penalty |
+|---|---|
+| Consecutive characters | `+1.0` |
+| First char after `/` (path component) | `+0.9` |
+| First char after `-`, `_`, space (word start) | `+0.8` |
+| Uppercase after lowercase (camelCase) | `+0.7` |
+| First char after `.` (file extension) | `+0.6` |
+| Leading / trailing gap | `-0.005` per char |
+| Inner gap | `-0.01` per char |
+
+An exact (case-insensitive) match returns `Float::INFINITY`; a non-match
+returns `-Float::INFINITY` so it sorts last. These are the exact constants
+from fzy's `config.def.h`.
+
+## Comparison with other Ruby gems
+
+| Gem | What it does | Returns a score? | Returns positions? |
+|---|---|---|---|
+| `fuzzy_match`, `amatch` | record linkage (Levenshtein/Dice/Jaro) | similarity | no |
+| `fuzzyfinder` | boolean filter | no | no |
+| **`fzy_score`** | **fzf/fzy-style ranking** | **yes** | **yes** |
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+## License
+
+MIT © Levelbrook Consulting. See [LICENSE](LICENSE).
+
+The scoring algorithm and constants are ported from
+[jhawthorn/fzy](https://github.com/jhawthorn/fzy) (MIT).

data/lib/fzy_score/match.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module FzyScore
+  # Result of a scored fuzzy match.
+  #
+  # +score+    Float relevance score. Higher is better. {SCORE_MAX} for an
+  #            exact (case-insensitive) match, {SCORE_MIN} for no match / empty
+  #            needle / oversized candidate.
+  # +positions+ Array<Integer> of the indices in +haystack+ that the needle
+  #            matched, suitable for highlighting. +nil+ unless positions were
+  #            requested.
+  Match = Struct.new(:score, :positions) do
+    # @return [Boolean] true when the candidate actually matched.
+    def matched?
+      score > SCORE_MIN
+    end
+  end
+end

data/lib/fzy_score/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FzyScore
+  VERSION = "0.1.0"
+end

data/lib/fzy_score.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+require_relative "fzy_score/version"
+require_relative "fzy_score/match"
+
+# FzyScore is a faithful, dependency-free Ruby port of the {https://github.com/jhawthorn/fzy
+# fzy} fuzzy-matching scoring algorithm (the same family of algorithm used by
+# {https://github.com/junegunn/fzf fzf} and {https://github.com/ajitid/fzf-for-js fzf-for-js}).
+#
+# Unlike Ruby's existing fuzzy gems (which do Levenshtein/Dice record linkage, or a
+# boolean "does it match" filter), FzyScore returns BOTH a relevance *score* and the
+# matched character *positions* — exactly what you need to build a command palette,
+# quick-open, autocomplete, or CLI picker with highlighting.
+#
+# @example Quick scoring
+#   FzyScore.score("amf", "app/models/foo.rb") # => Float
+#
+# @example Ranking candidates
+#   FzyScore.filter("srcmtch", ["src/match.rb", "spec/match_spec.rb", "README.md"])
+#   # => [["src/match.rb", <score>, [0,1,2,4,5,6,7]], ...]   (best first)
+#
+# @example Highlighting
+#   m = FzyScore.match("mr", "app/models/user.rb", positions: true)
+#   m.positions # => indices to highlight
+module FzyScore
+  # Scoring constants, taken verbatim from fzy's config.def.h so that ranking
+  # matches the reference implementation.
+  SCORE_GAP_LEADING      = -0.005
+  SCORE_GAP_TRAILING     = -0.005
+  SCORE_GAP_INNER        = -0.01
+  SCORE_MATCH_CONSECUTIVE = 1.0
+  SCORE_MATCH_SLASH      = 0.9
+  SCORE_MATCH_WORD       = 0.8
+  SCORE_MATCH_CAPITAL    = 0.7
+  SCORE_MATCH_DOT        = 0.6
+
+  SCORE_MAX = Float::INFINITY
+  SCORE_MIN = -Float::INFINITY
+
+  # Candidates longer than this are not scored with the full DP (treated as
+  # SCORE_MIN), matching fzy's behaviour of not penalising the rest of the UI
+  # for one unreasonably large entry.
+  MATCH_MAX_LEN = 1024
+
+  # Bonus awarded to a character based on the character that precedes it.
+  # Mirrors fzy's bonus_states table.
+  WORD_BREAK = { "-" => SCORE_MATCH_WORD, "_" => SCORE_MATCH_WORD, " " => SCORE_MATCH_WORD }.freeze
+
+  module_function
+
+  # Does +needle+ fuzzily match +haystack+ at all (case-insensitive, in order)?
+  #
+  # This is the cheap O(n) pre-filter; it does not compute a score.
+  #
+  # @param needle [String]
+  # @param haystack [String]
+  # @return [Boolean]
+  def match?(needle, haystack)
+    n = needle.downcase
+    h = haystack.downcase
+    j = 0
+    n.each_char do |ch|
+      j = h.index(ch, j)
+      return false if j.nil?
+
+      j += 1
+    end
+    true
+  end
+
+  # Score how well +needle+ matches +haystack+. Returns {SCORE_MIN} when there
+  # is no match (so it sorts last). Higher is better.
+  #
+  # @param needle [String]
+  # @param haystack [String]
+  # @return [Float]
+  def score(needle, haystack)
+    do_match(needle, haystack, positions: false).score
+  end
+
+  # Score +needle+ against +haystack+ and (optionally) return the matched
+  # positions for highlighting.
+  #
+  # @param needle [String]
+  # @param haystack [String]
+  # @param positions [Boolean] also compute the matched indices (slightly more work)
+  # @return [FzyScore::Match]
+  def match(needle, haystack, positions: true)
+    do_match(needle, haystack, positions: positions)
+  end
+
+  # Filter and rank a list of candidates against +needle+, best first.
+  #
+  # Each returned row is +[candidate, score, positions]+. Candidates that do
+  # not match are dropped. Sorting is stable on ties (preserves input order),
+  # matching the intuition users expect from a picker.
+  #
+  # @param needle [String]
+  # @param candidates [Array<#to_s>]
+  # @param positions [Boolean] include matched positions in each row
+  # @param key [Proc, nil] extract the string to match from each candidate
+  # @return [Array<Array>] rows of [candidate, score, positions_or_nil]
+  def filter(needle, candidates, positions: false, key: nil)
+    rows = []
+    candidates.each_with_index do |candidate, idx|
+      str = key ? key.call(candidate) : candidate.to_s
+      next unless match?(needle, str)
+
+      m = do_match(needle, str, positions: positions)
+      rows << [candidate, m.score, m.positions, idx]
+    end
+    # Stable sort: higher score first, original index breaks ties.
+    rows.sort_by! { |row| [-row[1], row[3]] }
+    rows.map { |candidate, sc, pos, _| [candidate, sc, pos] }
+  end
+
+  # --- internal -------------------------------------------------------------
+
+  # @api private
+  def do_match(needle, haystack, positions:)
+    return Match.new(SCORE_MIN, nil) if needle.nil? || needle.empty?
+    return Match.new(SCORE_MIN, nil) unless match?(needle, haystack)
+
+    n = needle.length
+    m = haystack.length
+
+    if m > MATCH_MAX_LEN || n > m
+      return Match.new(SCORE_MIN, nil)
+    elsif n == m
+      # Same length AND it matched => identical (case-insensitive).
+      return Match.new(SCORE_MAX, positions ? (0...n).to_a : nil)
+    end
+
+    lower_needle = needle.downcase
+    lower_haystack = haystack.downcase
+    match_bonus = precompute_bonus(haystack)
+
+    if positions
+      compute_with_positions(lower_needle, lower_haystack, match_bonus, n, m)
+    else
+      Match.new(compute_score(lower_needle, lower_haystack, match_bonus, n, m), nil)
+    end
+  end
+
+  # Per-position bonus based on the *preceding* character (word starts, slashes,
+  # dots, camelCase transitions). The first character is treated as if preceded
+  # by a slash, matching fzy.
+  # @api private
+  def precompute_bonus(haystack)
+    bonus = Array.new(haystack.length, 0.0)
+    last_ch = "/"
+    haystack.each_char.with_index do |ch, i|
+      bonus[i] = compute_bonus(last_ch, ch)
+      last_ch = ch
+    end
+    bonus
+  end
+
+  # @api private
+  def compute_bonus(last_ch, ch)
+    # Bonus only applies to alphanumeric current characters.
+    return 0.0 unless ch.match?(/[a-z0-9]/i)
+
+    case last_ch
+    when "/"
+      SCORE_MATCH_SLASH
+    when "-", "_", " "
+      SCORE_MATCH_WORD
+    when "."
+      SCORE_MATCH_DOT
+    else
+      # camelCase: an uppercase current char after a lowercase previous char.
+      if ch.match?(/[A-Z]/) && last_ch.match?(/[a-z]/)
+        SCORE_MATCH_CAPITAL
+      else
+        0.0
+      end
+    end
+  end
+
+  # Score-only DP. Two rolling rows (D and M), matching fzy's match().
+  # @api private
+  def compute_score(needle, haystack, match_bonus, n, m)
+    d_last = Array.new(m, SCORE_MIN)
+    m_last = Array.new(m, SCORE_MIN)
+    d_curr = Array.new(m, SCORE_MIN)
+    m_curr = Array.new(m, SCORE_MIN)
+
+    n.times do |i|
+      match_row(i, n, needle, haystack, match_bonus, m, d_curr, m_curr, d_last, m_last)
+      d_curr, d_last = d_last, d_curr
+      m_curr, m_last = m_last, m_curr
+    end
+
+    # After the swap, the last computed row is in *_last.
+    m_last[m - 1]
+  end
+
+  # Full DP keeping every row so positions can be backtracked. Mirrors fzy's
+  # match_positions().
+  # @api private
+  def compute_with_positions(needle, haystack, match_bonus, n, m)
+    d = Array.new(n) { Array.new(m, SCORE_MIN) }
+    mm = Array.new(n) { Array.new(m, SCORE_MIN) }
+
+    match_row(0, n, needle, haystack, match_bonus, m, d[0], mm[0], d[0], mm[0])
+    (1...n).each do |i|
+      match_row(i, n, needle, haystack, match_bonus, m, d[i], mm[i], d[i - 1], mm[i - 1])
+    end
+
+    positions = Array.new(n, 0)
+    match_required = false
+    j = m - 1
+    i = n - 1
+    while i >= 0
+      while j >= 0
+        if d[i][j] != SCORE_MIN && (match_required || d[i][j] == mm[i][j])
+          match_required =
+            i.positive? && j.positive? &&
+            mm[i][j] == d[i - 1][j - 1] + SCORE_MATCH_CONSECUTIVE
+          positions[i] = j
+          j -= 1
+          break
+        end
+        j -= 1
+      end
+      i -= 1
+    end
+
+    Match.new(mm[n - 1][m - 1], positions)
+  end
+
+  # Compute one row of the DP. Faithful translation of fzy's match_row().
+  # @api private
+  def match_row(i, n, needle, haystack, match_bonus, m, d_curr, m_curr, d_last, m_last)
+    prev_score = SCORE_MIN
+    gap_score = i == n - 1 ? SCORE_GAP_TRAILING : SCORE_GAP_INNER
+    needle_ch = needle[i]
+
+    j = 0
+    while j < m
+      if needle_ch == haystack[j]
+        score = SCORE_MIN
+        if i.zero?
+          score = (j * SCORE_GAP_LEADING) + match_bonus[j]
+        elsif j.positive?
+          consecutive = d_last[j - 1] + SCORE_MATCH_CONSECUTIVE
+          via_bonus = m_last[j - 1] + match_bonus[j]
+          score = via_bonus > consecutive ? via_bonus : consecutive
+        end
+        d_curr[j] = score
+        candidate = prev_score + gap_score
+        m_curr[j] = prev_score = score > candidate ? score : candidate
+      else
+        d_curr[j] = SCORE_MIN
+        m_curr[j] = prev_score = prev_score + gap_score
+      end
+      j += 1
+    end
+  end
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: fzy_score
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Levelbrook Team
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: |-
+  A tiny, dependency-free fuzzy matcher that returns both a relevance score and the
+  matched character positions (for highlighting) — the same algorithm family used by
+  fzy, fzf, and fzf-for-js. Unlike Ruby's record-linkage fuzzy gems, fzy_score is built
+  for command palettes, quick-open, autocomplete, and CLI pickers.
+email:
+- levelbrookteam@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/fzy_score.rb
+- lib/fzy_score/match.rb
+- lib/fzy_score/version.rb
+homepage: https://consulting.levelbrook.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://consulting.levelbrook.com
+  source_code_uri: https://github.com/tachyurgy/fzy_score
+  changelog_uri: https://github.com/tachyurgy/fzy_score/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Faithful Ruby port of the fzy/fzf fuzzy-matching scoring algorithm.
+test_files: []