spica 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4a579cb27fdbf3fc9b7fb3424f3f27b4a5eeac40c40ef41138859d8045c6391b
+  data.tar.gz: ca38a0b1d70c243fc92e5afd392fd91da6ac2683e4207586e2c0ea1c75e0c067
+SHA512:
+  metadata.gz: a7ca15fc297224b006f3d07c76e29da2e5904bff478c4382e1025b83c5de93a317e19e6ba8e85b216b3f6ea9137063a7d7e4a9336cb7d24aa9e303a6c8bed4a7
+  data.tar.gz: 2fac9201df2b43d04e0f60c5ad6644ed3c01e4302983eb6cbc5d1c032a76e0148254f821c6c02c1fd8620b961b67041ef47d0fe5d6d245078ec87dc8f70556b7

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 — Unreleased
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+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.

data/README.md

@@ -0,0 +1,132 @@
+# Spica
+
+A pure Ruby fuzzy subsequence matcher with scores, highlight positions and incremental filtering for command palettes and quick-open lists.
+
+Edit-distance similarity is not enough for a palette: `amu` should find `app/models/user.rb`, rank its alignment, and tell the UI which characters to highlight. Spica combines that contract with reusable candidate preprocessing and query history. It requires Ruby 3.1+ and has no runtime gems or native extensions.
+
+## Five-line example
+
+```ruby
+require "spica"
+index = Spica::Index.new(["app/models/user.rb", "app/models/order.rb", "README.md"])
+session = index.session
+session.query = "amu"
+p session.matches(50).map { |match| [match.candidate, match.score, match.positions] }
+```
+
+## Installation
+
+```sh
+gem install spica
+```
+
+## Stateless or incremental
+
+```ruby
+Spica.score("amf", "app/models/foo.rb")  # Float; -Float::INFINITY if absent
+match = Spica.match("amu", "app/models/user.rb")
+match.positions                           # [0, 4, 11]
+match.score                               # optimal weighted alignment score
+Spica.match("xyz", "README.md")          # nil
+Spica.filter("srcm", candidates, limit: 50)  # Array<Match>
+```
+
+Positions are Unicode **character offsets**, not bytes or grapheme-cluster indices. Results, their strings/positions, and returned top arrays are immutable. `Match#text` aliases `candidate`; `index` is the stable registration ID.
+
+```ruby
+index = Spica::Index.new(paths)
+session = index.session
+session.query = "c";   session.matches(50)
+session.query = "co";  session.matches(50)  # only previous matches are rescored
+session.query = "con"; session.matches(50)
+session.query = "co";  session.matches(50)  # cached match set and results
+
+index.add(["new/file.rb"])
+index.remove(["deleted/file.rb"])
+session.matches(50)                    # index generation invalidates old history
+session.total_matches                  # all matches, not only the first 50
+```
+
+Indices deduplicate identical text; removing and re-adding a path gives it a new registration ID. Original input strings can be edited without changing indexed records. A session retains the active prefix chain; unrelated pasted queries restart from the full index. Limiting the displayed top list never discards candidates needed for the next query.
+
+A larger `matches(limit)` recomputes partial selection; a repeated or smaller limit reuses cached results. Build one Index per candidate collection and one Session per independent palette. Candidate records and Options are frozen, while Index mutations and Session operations are explicitly stateful: serialize mutations, and do not share a Session between concurrent callers.
+
+## Scoring and options
+
+The score is an optimal fzy-style subsequence alignment for inputs within the configured ceilings. A sparse D/M recurrence visits matching positions, carrying the best intervening-gap score instead of materializing every matrix cell. Score-only scans reuse two rows; highlight backtracking runs only for selected results. One-/two-character queries have equivalent scalar recurrences, and a contiguous match can stop early only when it reaches a proven global score upper bound.
+
+The subsequence precheck also scores an alignment directly when every remaining query character has exactly one occurrence. Ambiguous alignments still use the full recurrence. Membership masks and DP scratch rows are prepared only when needed, avoiding unused preprocessing in stateless calls.
+
+```ruby
+options = Spica::Options.new(
+  case_sensitivity: :smart,  # :smart, :insensitive, :sensitive
+  path_mode: true,
+  limit: 100,
+  tie_break: :shorter
+)
+index = Spica::Index.new(paths, options:)
+Spica.match("cf", "core/File.rb", options:)
+```
+
+Smart case is case-insensitive unless the query contains an uppercase character. Default ties are resolved by score descending, candidate character length ascending, then registration ID ascending. `tie_break: :index` skips the length criterion. Exact matches score positive infinity; an empty query matches every candidate with score zero.
+
+Default weights preserve the upstream public fzy ranking cases:
+
+| Option | Default |
+| --- | ---: |
+| `consecutive` | 1.0 |
+| `slash` (also start of candidate / Windows separator) | 0.9 |
+| `boundary` (after dash, underscore or space) | 0.8 |
+| `camel` | 0.7 |
+| `dot` | 0.6 |
+| `leading_gap` / `trailing_gap` | -0.005 |
+| `inner_gap` | -0.01 |
+| `case_bonus` (exact-case micro-bonus, opt-in) | 0.0 |
+| `basename_bonus` (used when `path_mode: true`) | 0.2 |
+
+Path mode adds a configurable bonus to nonconsecutive matches within the basename. Its default is off for fzy-compatible ranking. All weights are configurable finite real numbers; millipoint-exact weights use integer internal arithmetic so mathematically equal scores do not flicker from floating-point accumulation order.
+
+The index precomputes folded ASCII strings, a 128-bit membership mask plus Unicode membership, boundary codes and basename offsets. Non-ASCII text keeps one lowercase mapping per original character. This preserves highlight positions through expanding lowercase mappings, but deliberately does not perform full Unicode case folding, normalization or grapheme matching: `ss` is not a substitute for `ß`, and composed/decomposed text is not silently normalized.
+
+Candidates longer than `max_length: 1024` or queries longer than `max_query: 256` use bounded-memory greedy alignment when an exact fast path is unavailable. They remain valid subsequence matches, but their score/positions are not promised optimal. No edit distance, token rearrangement, transliteration or phonetic matching is performed. Invalid text/options raise `ArgumentError`.
+
+## Verification
+
+```sh
+bundle install
+bundle exec rake
+bundle exec rake test:oracle
+BUDGET=1 bundle exec rake bench
+rbs -I sig validate
+yard doc
+```
+
+Tests include 2,000 Unicode position properties, 3,000 comparisons against an independent dense recurrence with varied weights, randomized heap/top and session consistency, encoding/case behavior, deterministic ties, cache invalidation and malformed options.
+
+The optional native oracle compiles the pinned, unmodified [upstream fzy scorer](test/vendor/fzy/README.md) in a temporary directory. It checks **all eight public ranking assertions** plus 500 seeded ASCII score comparisons. A compiler is only needed for this development oracle; the library works with `ruby --disable-gems`. `FZY_REQUIRED=1` makes a missing compiler fail instead of skip. Linux CI requires the oracle; macOS/Windows run it when a compiler is available. Isolation checks build/install the gem into a temporary GEM_HOME and emit results without development/application dependencies.
+
+## Measured performance
+
+Ruby 4.0.0 + YJIT, arm64 macOS; median of five warmed runs. The representative corpus has 100,000 paths, of which the first query `c` retains 10,000; the next query scans those 10,000. Timings include `query=` and `matches(50)`.
+
+| Workload | Measured | Goal |
+| --- | ---: | ---: |
+| Build 100,000-candidate index | 87.83ms | <400ms |
+| First key, 100,000 → 10,000 matches | 4.93ms | <40ms |
+| Second key `co`, 10,000 candidates | 2.39ms | <5ms |
+| Noncontiguous `cm`, 10,000 candidates | 3.13ms | — |
+| Longer `component_123` query | 2.82ms | — |
+| Cached backspace | 0.002ms | <1ms |
+| Stateless `score("amf", "app/models/foo.rb")` | 2.18µs | <3µs |
+| Adversarial first key matching all 100,000 | 15.23ms | — |
+| Adversarial second key still matching all 100,000 | 11.54ms | — |
+
+The 5ms second-key target applies to the specified **10,000 remaining candidates**, not 100,000 matches. The benchmark retains and reports the all-hit stress case separately. Performance depends on candidate/query distribution and hardware; these measurements are not worst-case guarantees.
+
+A subsequent stateless-score CI regression check compared `4af16c3` with the unique-alignment/lazy-preparation fix on Ruby 4.0.6 + YJIT, Linux arm64, Bundler 4.0.19. Three alternating `BUDGET=1 bundle exec rake bench` pairs (each reporting five warmed runs) reduced the median stateless call from 2.62µs to 1.20µs; all gates passed in all three corrected runs. The same-call allocation count fell from 15 to 6 objects. The original failing GitHub x86_64 runner measured 5.17µs; these local measurements are not a rerun on that hardware. Neither the 3µs limit nor the benchmark workload was changed.
+
+Retained candidate records measured 34.33MiB, about 360 bytes per candidate, excluding the Index hash and input array. This exceeds the design estimate of roughly 100 bytes per candidate / 10MB for 100,000; it is a known Ruby object-overhead tradeoff, not a passed memory target. `bench/search.rb` reports both timing gates and retained-size measurements.
+
+## Name and license
+
+A spica separates grain from chaff; this library separates useful palette matches from a large candidate list. MIT, see [LICENSE.txt](LICENSE.txt). Test-only fzy sources retain their [upstream MIT license](test/vendor/fzy/LICENSE).

data/examples/palette.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "spica"
+
+index = Spica::Index.new(%w[app/models/user.rb app/models/order.rb app/controllers/users_controller.rb README.md])
+session = index.session
+(ARGV.empty? ? %w[a am amu am] : ARGV).each do |query|
+  session.query = query
+  puts "#{query.inspect}: #{session.total_matches} matches"
+  session.matches(5).each do |match|
+    highlighted = match.candidate.each_char.with_index.map { |character, position| match.positions.include?(position) ? "[#{character}]" : character }.join
+    puts "  #{highlighted} (#{match.score})"
+  end
+end

data/lib/spica/index.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Spica
+  # Mutable registry; immutable candidate records can be shared by sessions.
+  class Index
+    attr_reader :options, :generation
+
+    # @param candidates [Array<String>] initial candidate collection
+    # @param options [Options] shared immutable scoring policy
+    def initialize(candidates = [], options: DEFAULT_OPTIONS, **settings)
+      @options = settings.empty? ? options : Options.new(**options.to_h.merge(settings))
+      @entries, @sequence, @generation = {}, 0, 0
+      add(candidates)
+    end
+
+    # Add unique text, retaining monotonic registration IDs.
+    # @return [self]
+    def add(candidates)
+      Array(candidates).each do |text|
+        next if @entries.key?(text)
+        candidate = Candidate.new(text, @sequence)
+        next if @entries.key?(candidate.text)
+        @entries[candidate.text] = candidate
+        @sequence += 1
+        @generation += 1
+      end
+      self
+    end
+
+    # Remove text and invalidate active session histories via generation.
+    # @return [self]
+    def remove(candidates)
+      Array(candidates).each do |text|
+        raise ArgumentError, "candidate must be valid text" unless text.is_a?(String) && text.valid_encoding?
+        @generation += 1 if @entries.delete(text.encode(Encoding::UTF_8))
+      end
+      self
+    rescue EncodingError => error
+      raise ArgumentError, "candidate encoding: #{error.message}"
+    end
+
+    # @return [Integer] number of registered unique candidates
+    def size = @entries.size
+    # @return [Array<Candidate>] immutable records in registration order
+    def candidates = @entries.values
+    # @return [Session] independent query history over this index
+    def session = Session.new(self)
+  end
+
+  # Incremental match sets and cached top results. A session is thread-confined;
+  # separate sessions keep independent query history and reusable DP scratch.
+  class Session
+    # Session-owned cached match set, scorer and largest requested top list.
+    Snapshot = Struct.new(:candidates, :scores, :matcher, :top_limit, :top_matches)
+    private_constant :Snapshot
+    attr_reader :query
+
+    # @param index [Index] registry observed for generation changes
+    def initialize(index)
+      @index, @query, @generation = index, "", -1
+      @history = {}
+      @shorter = index.options.tie_break == :shorter
+    end
+
+    # Narrow the previous match set or restore a cached query prefix.
+    # @param query [String] new query (copied/frozen internally)
+    # @return [String] caller's query
+    def query=(query)
+      raise ArgumentError, "query must be valid text" unless query.is_a?(String) && query.encoding.ascii_compatible? && query.valid_encoding?
+      @query = query.encode(Encoding::UTF_8).freeze
+      refresh
+      query
+    rescue EncodingError => error
+      raise ArgumentError, "query encoding: #{error.message}"
+    end
+
+    # Select only the best candidates, then reconstruct their highlights.
+    # @return [Array<Match>] frozen deterministic result list
+    def matches(limit = @index.options.limit)
+      raise ArgumentError, "limit must be nonnegative" unless limit.is_a?(Integer) && limit >= 0
+      refresh
+      state = @history.fetch(@query)
+      limit = [limit, state.candidates.length].min
+      if state.top_matches && limit <= state.top_limit
+        return limit == state.top_limit ? state.top_matches : state.top_matches.first(limit).freeze
+      end
+      state.top_limit = limit
+      state.top_matches = best_matches(state, limit)
+    end
+
+    # @return [Integer] complete match count, independent from display limit
+    def total_matches
+      refresh
+      @history.fetch(@query).candidates.length
+    end
+
+    private
+
+    def best_matches(state, limit)
+      candidates, scores = state.candidates, state.scores
+      heap = []
+      unless limit.zero?
+        candidates.each_index do |index|
+          if heap.length < limit
+            heap << index
+            child = heap.length - 1
+            while child.positive?
+              parent = (child - 1) / 2
+              break unless better?(heap[parent], heap[child], candidates, scores)
+              heap[parent], heap[child] = heap[child], heap[parent]
+              child = parent
+            end
+          elsif better?(index, heap[0], candidates, scores)
+            heap[0] = index
+            parent = 0
+            loop do
+              left = parent * 2 + 1
+              break if left >= heap.length
+              right = left + 1
+              child = right < heap.length && better?(heap[left], heap[right], candidates, scores) ? right : left
+              break unless better?(heap[parent], heap[child], candidates, scores)
+              heap[parent], heap[child] = heap[child], heap[parent]
+              parent = child
+            end
+          end
+        end
+      end
+      heap.sort! { |a, b| compare(a, b, candidates, scores) }
+      heap.map { |index| state.matcher.match(candidates[index]) }.freeze
+    end
+
+    def better?(a, b, candidates, scores)
+      left, right = scores[a], scores[b]
+      return left > right unless left == right
+      x, y = candidates[a], candidates[b]
+      return x.length < y.length if @shorter && x.length != y.length
+      x.index < y.index
+    end
+
+    def compare(a, b, candidates, scores)
+      comparison = scores[b] <=> scores[a]
+      return comparison unless comparison.zero?
+      x, y = candidates[a], candidates[b]
+      comparison = x.length <=> y.length if @shorter
+      comparison.zero? ? x.index <=> y.index : comparison
+    end
+
+    def refresh
+      if @generation != @index.generation
+        @history.clear
+        @generation = @index.generation
+      end
+      return if @history.key?(@query)
+      prefix = @history.keys.select { |key| @query.start_with?(key) }.max_by(&:length)
+      candidates = prefix ? @history[prefix].candidates : @index.candidates
+      matcher = Matcher.new(@query, @index.options)
+      matched, scores = [], []
+      candidates.each do |candidate|
+        score = matcher.score(candidate)
+        next unless score
+        matched << candidate
+        scores << score
+      end
+      # Keep only the current prefix chain, including cached top lists so a
+      # backspace never has to score or select those results again.
+      @history.delete_if { |key, _| !@query.start_with?(key) }
+      @history[@query] = Snapshot.new(matched.freeze, scores.freeze, matcher)
+    end
+  end
+end

data/lib/spica/matcher.rb

@@ -0,0 +1,459 @@
+# frozen_string_literal: true
+
+module Spica
+  # Immutable scoring policy. Defaults preserve fzy's ranking.
+  Options = Struct.new(:case_sensitivity, :path_mode, :limit, :tie_break,
+                       :consecutive, :boundary, :slash, :camel, :dot, :basename_bonus,
+                       :leading_gap, :inner_gap, :trailing_gap, :case_bonus,
+                       :max_length, :max_query, keyword_init: true) do
+    attr_reader :scoring
+    def initialize(case_sensitivity: :smart, path_mode: false, limit: 100,
+                   tie_break: :shorter, consecutive: 1.0, boundary: 0.8,
+                   slash: 0.9, camel: 0.7, dot: 0.6, basename_bonus: 0.2,
+                   leading_gap: -0.005, inner_gap: -0.01, trailing_gap: -0.005,
+                   case_bonus: 0.0, max_length: 1024, max_query: 256)
+      super
+      raise ArgumentError, "invalid case sensitivity" unless %i[smart sensitive insensitive].include?(case_sensitivity)
+      raise ArgumentError, "invalid tie break" unless %i[shorter index].include?(tie_break)
+      raise ArgumentError, "path_mode must be boolean" unless path_mode == true || path_mode == false
+      raise ArgumentError, "limit must be nonnegative" unless limit.is_a?(Integer) && limit >= 0
+      %i[max_length max_query].each { |name| raise ArgumentError, "#{name} must be positive" unless self[name].is_a?(Integer) && self[name].positive? }
+      %i[consecutive boundary slash camel dot basename_bonus leading_gap inner_gap trailing_gap case_bonus].each do |name|
+        number = self[name]
+        raise ArgumentError, "#{name} must be finite and real" unless number.is_a?(Numeric) && number.real? && number.to_f.finite?
+        self[name] = number.to_f
+      end
+      bonuses = [0.0, self.slash, self.boundary, self.dot, self.camel]
+      path = path_mode ? self.basename_bonus : 0.0
+      weights = [*bonuses, self.leading_gap, self.inner_gap, self.trailing_gap, self.consecutive, self.case_bonus, path]
+      scale = weights.all? { |weight| (weight * 1000).finite? && weight * 1000 == (weight * 1000).round } ? 1000.0 : 1.0
+      weights.map! { |weight| (weight * scale).round } if scale == 1000.0
+      bonuses = weights.shift(5).freeze
+      leading, inner, trailing, consecutive_weight, case_weight, path_weight = weights
+      max_bonus = bonuses.max + [case_weight, 0].max + [path_weight, 0].max
+      contiguous = leading == trailing && inner <= leading && consecutive_weight >= bonuses.max + [path_weight, 0].max
+      @scoring = [scale, bonuses, leading, inner, trailing, consecutive_weight, case_weight, path_weight, max_bonus, contiguous].freeze
+      freeze
+    end
+  end
+  # Shared immutable fzy-compatible default policy.
+  DEFAULT_OPTIONS = Options.new
+
+  # Immutable UI result; positions are Unicode character offsets, not bytes.
+  Match = Struct.new(:candidate, :score, :positions, :index, keyword_init: true) do
+    alias text candidate
+    # @return [String] candidate text
+    def to_s = candidate
+  end
+
+  # Compact ASCII representation; Unicode keeps per-character folds so an
+  # expanding lowercase mapping never shifts the original highlight offsets.
+  class Candidate
+    # Shared byte used to allocate compact per-character boundary codes.
+    ZERO_BYTE = "\0".b.freeze
+    attr_reader :text, :chars, :folded, :mask, :unicode, :index, :basename,
+                :bonuses, :length
+
+    def ascii_only? = @ascii
+
+    # @param text [String] candidate text, copied unless already immutable
+    # @param index [Integer] registration ID for stable tie resolution
+    # @param precompute_mask [Boolean] cache memberships for repeated queries
+    def initialize(text, index, precompute_mask: true)
+      raise ArgumentError, "candidate must be valid text" unless text.is_a?(String) && text.encoding.ascii_compatible? && text.valid_encoding?
+      @text = text.encoding == Encoding::UTF_8 ? (text.frozen? ? text : text.dup.freeze) : text.encode(Encoding::UTF_8).freeze
+      @index = index
+      @ascii = @text.ascii_only?
+      @basename = 0
+      low = high = 0
+      if @ascii
+        @chars = @text
+        @folded = @text.match?(/[A-Z]/) ? @text.downcase.freeze : @text
+        @length = @text.bytesize
+        @unicode = nil
+        @bonuses = ZERO_BYTE * @length
+        previous = 47
+        position = 0
+        while position < @length
+          original = @text.getbyte(position)
+          if precompute_mask
+            folded = @folded.getbyte(position)
+            if folded < 64
+              low |= 1 << folded
+            else
+              high |= 1 << (folded - 64)
+            end
+          end
+          kind = if previous == 47 || previous == 92
+            1
+          elsif previous == 45 || previous == 95 || previous == 32
+            2
+          elsif previous == 46
+            3
+          elsif previous >= 97 && previous <= 122 && original >= 65 && original <= 90
+            4
+          else
+            0
+          end
+          @bonuses.setbyte(position, kind)
+          @basename = position + 1 if original == 47 || original == 92
+          previous = original
+          position += 1
+        end
+      else
+        @chars = @text.each_char.map(&:freeze).freeze
+        @folded = @chars.map { |character| character.downcase.freeze }.freeze
+        @length = @chars.length
+        @unicode = precompute_mask ? {} : nil
+        @bonuses = ZERO_BYTE * @length
+        previous = "/"
+        @chars.each_with_index do |original, position|
+          folded = @folded[position]
+          if precompute_mask
+            if folded.ascii_only?
+              code = folded.ord
+              code < 64 ? low |= 1 << code : high |= 1 << (code - 64)
+            else
+              @unicode[folded] = true
+            end
+          end
+          kind = if previous == "/" || previous == "\\"
+            1
+          elsif ["-", "_", " "].include?(previous)
+            2
+          elsif previous == "."
+            3
+          elsif previous.match?(/\p{Lower}/) && original.match?(/\p{Upper}/)
+            4
+          else
+            0
+          end
+          @bonuses.setbyte(position, kind)
+          @basename = position + 1 if original == "/" || original == "\\"
+          previous = original
+        end
+        @unicode.freeze
+      end
+      @mask = precompute_mask ? low | (high << 64) : nil
+      @bonuses.freeze
+      freeze
+    rescue EncodingError => error
+      raise ArgumentError, "candidate encoding: #{error.message}"
+    end
+  end
+
+  # Sparse form of the fzy D/M recurrence. Only matching character positions
+  # need a cell; the maximum across intervening gaps is carried analytically.
+  class Matcher
+    # Sentinel for unreachable DP states.
+    NEGATIVE_INFINITY = -Float::INFINITY
+    # Immutable one-byte query strings shared across scorers.
+    ASCII_CHARACTERS = Array.new(128) { |code| code.chr(Encoding::UTF_8).freeze }.freeze
+    # Shared empty non-ASCII membership list.
+    EMPTY_CHARACTERS = [].freeze
+
+    # @param query [String] query to preprocess once
+    # @param options [Options] scoring policy
+    def initialize(query, options = DEFAULT_OPTIONS)
+      raise ArgumentError, "query must be valid text" unless query.is_a?(String) && query.encoding.ascii_compatible? && query.valid_encoding?
+      query = query.encoding == Encoding::UTF_8 ? (query.frozen? ? query : query.dup.freeze) : query.encode(Encoding::UTF_8).freeze
+      @original_text = query
+      @options = options
+      @sensitive = options.case_sensitivity == :sensitive ||
+        (options.case_sensitivity == :smart && query.match?(/\p{Upper}/))
+      @scale, @bonus_values, @leading, @inner, @trailing, @consecutive, @case_bonus, @path_bonus, @max_bonus, @contiguous_bound = options.scoring
+      if query.ascii_only?
+        @query_text = @sensitive ? query : query.downcase
+        @query = []
+        @query_text.each_byte { |code| @query << ASCII_CHARACTERS[code] }
+        @original = query.each_byte.map { |code| ASCII_CHARACTERS[code] } unless @case_bonus.zero?
+      else
+        @original = query.each_char.to_a
+        folded = @original.map(&:downcase)
+        @query = @sensitive ? @original : folded
+        @query_text = @query.join.freeze
+      end
+      @size = @query.length
+      # Keep one object layout even when these caches remain unused.
+      @mask = @unicode = @positions_a = @positions_b = @scores_a = @scores_b = nil
+    rescue EncodingError => error
+      raise ArgumentError, "query encoding: #{error.message}"
+    end
+
+    # @return [Float, nil] optimal score, or nil for a non-match
+    def score(candidate)
+      value = evaluate(candidate, false)
+      raise ArgumentError, "scoring overflow; reduce option weights" if value.is_a?(Float) && value.nan?
+      value / @scale if value
+    end
+
+    # Backtracking is only performed for results actually returned to the UI.
+    # @return [Match, nil]
+    def match(candidate)
+      value = evaluate(candidate, true)
+      return unless value
+      raise ArgumentError, "scoring overflow; reduce option weights" if value.is_a?(Float) && value.nan?
+      Match.new(candidate: candidate.text, score: value / @scale, positions: @aligned.freeze, index: candidate.index).freeze
+    end
+
+    private
+
+    # Membership masks only help indexed candidates. Stateless calls and short
+    # queries never inspect them, so avoid building their arbitrary-size integers.
+    def prepare_mask
+      @unicode = @query_text.ascii_only? ? EMPTY_CHARACTERS : []
+      low = high = 0
+      @query.each do |character|
+        character = character.downcase if @sensitive
+        if character.ascii_only?
+          code = character.ord
+          code < 64 ? low |= 1 << code : high |= 1 << (code - 64)
+        else
+          @unicode << character
+        end
+      end
+      @mask = low.zero? ? high << 64 : low | (high << 64)
+    end
+
+    def find(chars, needle, offset)
+      return chars.index(needle, offset) if chars.is_a?(String)
+      while offset < chars.length
+        return offset if chars[offset] == needle
+        offset += 1
+      end
+      nil
+    end
+
+    def bonus(candidate, position)
+      value = @bonus_values[candidate.bonuses.getbyte(position)]
+      @path_bonus.zero? || position < candidate.basename ? value : value + @path_bonus
+    end
+
+    def case_bonus(candidate, position, query_index)
+      return 0.0 if @case_bonus.zero?
+      character = candidate.ascii_only? ? candidate.text.getbyte(position) : candidate.chars[position]
+      expected = candidate.ascii_only? ? @original[query_index].ord : @original[query_index]
+      character == expected ? @case_bonus : 0.0
+    end
+
+    def evaluate(candidate, backtrack)
+      n, m = candidate.length, @size
+      if m.zero?
+        @aligned = [] if backtrack
+        return 0.0
+      end
+      return if m > n
+      if m > 2 && candidate.mask
+        prepare_mask unless @mask
+        return if (candidate.mask & @mask) != @mask || @unicode.any? { |character| !candidate.unicode || !candidate.unicode[character] }
+      end
+      chars = @sensitive ? candidate.chars : candidate.folded
+      # A consecutive run starting at the strongest possible boundary reaches
+      # the global DP upper bound. This is an exact shortcut, not a heuristic.
+      if m > 1 && candidate.ascii_only? && @query_text.ascii_only? && @contiguous_bound
+        position = chars.index(@query_text)
+        if position && bonus(candidate, position) + @case_bonus == @max_bonus && (@case_bonus.zero? || candidate.text.index(@original_text, position) == position)
+          @aligned = (position...(position + m)).to_a if backtrack
+          return Float::INFINITY if m == n
+          return (n - m) * @leading + bonus(candidate, position) + (m - 1) * @consecutive + m * @case_bonus
+        end
+      end
+      return score_one_character(candidate, chars, backtrack) if m == 1
+      return score_two_characters(candidate, chars, backtrack) if m == 2
+      # Cheap C-level subsequence checks precede the sparse DP.
+      cursor = 0
+      unique = n <= @options.max_length && m <= @options.max_query
+      total = 0
+      aligned = [] if backtrack
+      i = 0
+      while i < m
+        character = @query[i]
+        position = find(chars, character, cursor)
+        return unless position
+        # If each remaining character occurs only once, there is no alignment
+        # choice for DP to resolve. Stop checking as soon as one is ambiguous.
+        unique &&= find(chars, character, position + 1).nil?
+        if unique
+          value = bonus(candidate, position)
+          value = @consecutive if i.positive? && position == cursor && @consecutive > value
+          total += value + (i.zero? ? position * @leading : (position - cursor) * @inner)
+          total += case_bonus(candidate, position, i) unless @case_bonus.zero?
+          aligned << position if backtrack
+        end
+        cursor = position + 1
+        i += 1
+      end
+      if m == n
+        @aligned = (0...m).to_a if backtrack
+        return Float::INFINITY
+      end
+      if unique
+        @aligned = aligned if backtrack
+        return total + (n - cursor) * @trailing
+      end
+      # ponytail: exceptionally long text uses greedy alignment; configurable
+      # ceilings bound memory/time without dropping valid subsequence matches.
+      return score_greedily(candidate, chars, backtrack) if n > @options.max_length || m > @options.max_query
+
+      score_ambiguous_alignment(candidate, chars, backtrack)
+    end
+
+    def score_one_character(candidate, chars, backtrack)
+      length = candidate.length
+      position = find(chars, @query[0], 0)
+      return unless position
+      if length == 1
+        @aligned = [0] if backtrack
+        return Float::INFINITY
+      end
+      best, finish = NEGATIVE_INFINITY, nil
+      while position
+        value = bonus(candidate, position)
+        value += case_bonus(candidate, position, 0) unless @case_bonus.zero?
+        value += @leading == @trailing ? (length - 1) * @leading : position * @leading + (length - position - 1) * @trailing
+        if value >= best
+          best, finish = value, position
+        end
+        break if !backtrack && @leading == @trailing && value >= (length - 1) * @leading + @max_bonus
+        position = find(chars, @query[0], position + 1)
+      end
+      @aligned = [finish] if backtrack
+      best
+    end
+
+    # Two rows collapse to scalar prefix maxima: no temporary arrays, while
+    # retaining every alignment and the exact same D/M recurrence.
+    def score_two_characters(candidate, chars, backtrack)
+      first = find(chars, @query[0], 0)
+      return unless first
+      second = find(chars, @query[1], first + 1)
+      return unless second
+      if candidate.length == 2
+        @aligned = [0, 1] if backtrack
+        return Float::INFINITY
+      end
+      maximum = best = NEGATIVE_INFINITY
+      maximum_position = last_position = last_score = finish_first = finish_second = nil
+      while second
+        while first && first < second
+          score = first * @leading + bonus(candidate, first)
+          score += case_bonus(candidate, first, 0) unless @case_bonus.zero?
+          adjusted = score - first * @inner
+          if adjusted >= maximum
+            maximum, maximum_position = adjusted, first
+          end
+          last_position, last_score = first, score
+          first = find(chars, @query[0], first + 1)
+        end
+        separated = maximum + (second - 1) * @inner + bonus(candidate, second)
+        adjacent = last_position == second - 1 ? last_score + @consecutive : NEGATIVE_INFINITY
+        if adjacent >= separated
+          score, start = adjacent, last_position
+        else
+          score, start = separated, maximum_position
+        end
+        score += case_bonus(candidate, second, 1) unless @case_bonus.zero?
+        score += (candidate.length - second - 1) * @trailing
+        if score >= best
+          best, finish_first, finish_second = score, start, second
+        end
+        second = find(chars, @query[1], second + 1)
+      end
+      @aligned = [finish_first, finish_second] if backtrack
+      best
+    end
+
+    def score_greedily(candidate, chars, backtrack)
+      cursor = 0
+      previous = nil
+      total = 0.0
+      @aligned = [] if backtrack
+      @query.each_with_index do |character, i|
+        position = find(chars, character, cursor)
+        @aligned << position if backtrack
+        total += if previous && position == previous + 1
+          @consecutive
+        else
+          bonus(candidate, position) + (previous ? (position - previous - 1) * @inner : position * @leading)
+        end
+        total += case_bonus(candidate, position, i)
+        previous = position
+        cursor = position + 1
+      end
+      total + (candidate.length - previous - 1) * @trailing
+    end
+
+    def score_ambiguous_alignment(candidate, chars, backtrack)
+      n, m = candidate.length, @size
+
+      previous_positions, current_positions = (@positions_a ||= []), (@positions_b ||= [])
+      previous_scores, current_scores = (@scores_a ||= []), (@scores_b ||= [])
+      previous_positions.clear
+      previous_scores.clear
+      rows = [] if backtrack
+      parents = [] if backtrack
+      i = 0
+      while i < m
+        current_positions.clear
+        current_scores.clear
+        parent_row = [] if backtrack
+        position = find(chars, @query[i], i)
+        previous_cursor = 0
+        maximum = NEGATIVE_INFINITY
+        maximum_index = nil
+        while position && position <= n - m + i
+          if i.zero?
+            value = position * @leading + bonus(candidate, position)
+            parent_index = nil
+          else
+            while previous_cursor < previous_positions.length && previous_positions[previous_cursor] < position
+              adjusted = previous_scores[previous_cursor] - previous_positions[previous_cursor] * @inner
+              if adjusted >= maximum
+                maximum, maximum_index = adjusted, previous_cursor
+              end
+              previous_cursor += 1
+            end
+            if maximum_index.nil?
+              position = find(chars, @query[i], position + 1)
+              next
+            end
+            separated = maximum + (position - 1) * @inner + bonus(candidate, position)
+            adjacent = previous_cursor.positive? && previous_positions[previous_cursor - 1] == position - 1 ? previous_scores[previous_cursor - 1] + @consecutive : NEGATIVE_INFINITY
+            if adjacent >= separated
+              value, parent_index = adjacent, previous_cursor - 1
+            else
+              value, parent_index = separated, maximum_index
+            end
+          end
+          value += case_bonus(candidate, position, i) unless @case_bonus.zero?
+          current_positions << position
+          current_scores << value
+          parent_row << parent_index if backtrack
+          position = find(chars, @query[i], position + 1)
+        end
+        if backtrack
+          rows << current_positions.dup
+          parents << parent_row
+        end
+        previous_positions, current_positions = current_positions, previous_positions
+        previous_scores, current_scores = current_scores, previous_scores
+        i += 1
+      end
+      best, finish = NEGATIVE_INFINITY, nil
+      previous_positions.each_with_index do |position, index|
+        value = previous_scores[index] + (n - position - 1) * @trailing
+        if value >= best
+          best, finish = value, index
+        end
+      end
+      if backtrack
+        @aligned = Array.new(m)
+        (m - 1).downto(0) do |row|
+          @aligned[row] = rows[row][finish]
+          finish = parents[row][finish]
+        end
+      end
+      best
+    end
+  end
+end

data/lib/spica/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Spica
+  # Library semantic version.
+  VERSION = "0.1.0"
+end

data/lib/spica.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "spica/version"
+require_relative "spica/matcher"
+require_relative "spica/index"
+
+# Fuzzy subsequence search for palettes and quick-open interfaces.
+module Spica
+  # Base error class reserved for library-level failures.
+  class Error < StandardError; end
+
+  # Match a query subsequence and return its score and character positions.
+  # @param query [String] valid query text
+  # @param candidate [String] valid candidate text
+  # @param options [Options] immutable scoring policy
+  # @return [Match, nil] optimal alignment, or nil if there is no subsequence
+  # @raise [ArgumentError] on invalid text/options
+  def self.match(query, candidate, options: DEFAULT_OPTIONS, **settings)
+    options = Options.new(**options.to_h.merge(settings)) unless settings.empty?
+    Matcher.new(query, options).match(Candidate.new(candidate, 0, precompute_mask: false))
+  end
+
+  # Compute a score without reconstructing highlighted positions.
+  # @return [Float] score, or negative infinity if the query does not match
+  def self.score(query, candidate, options: DEFAULT_OPTIONS, **settings)
+    options = Options.new(**options.to_h.merge(settings)) unless settings.empty?
+    Matcher.new(query, options).score(Candidate.new(candidate, 0, precompute_mask: false)) || -Float::INFINITY
+  end
+
+  # One-shot ranked filtering. Reuse Index/Session for repeated queries.
+  # @return [Array<Match>] at most limit results, sorted deterministically
+  def self.filter(query, candidates, limit: nil, **settings)
+    index = Index.new(candidates, **settings)
+    index.session.tap { |session| session.query = query }.matches(limit || index.options.limit)
+  end
+end

data/sig/spica.rbs

@@ -0,0 +1,84 @@
+module Spica
+  VERSION: String
+  DEFAULT_OPTIONS: Options
+
+  class Error < StandardError
+  end
+
+  def self.match: (String query, String candidate, ?options: Options, **untyped settings) -> Match?
+  def self.score: (String query, String candidate, ?options: Options, **untyped settings) -> Float
+  def self.filter: (String query, Array[String] candidates, ?limit: Integer?, **untyped settings) -> Array[Match]
+
+  class Options < Struct[untyped]
+    attr_reader case_sensitivity: Symbol
+    attr_reader path_mode: bool
+    attr_reader limit: Integer
+    attr_reader tie_break: Symbol
+    attr_reader consecutive: Float
+    attr_reader boundary: Float
+    attr_reader slash: Float
+    attr_reader camel: Float
+    attr_reader dot: Float
+    attr_reader basename_bonus: Float
+    attr_reader leading_gap: Float
+    attr_reader inner_gap: Float
+    attr_reader trailing_gap: Float
+    attr_reader case_bonus: Float
+    attr_reader max_length: Integer
+    attr_reader max_query: Integer
+    attr_reader scoring: Array[untyped]
+    def initialize: (?case_sensitivity: Symbol, ?path_mode: bool, ?limit: Integer, ?tie_break: Symbol,
+      ?consecutive: Numeric, ?boundary: Numeric, ?slash: Numeric, ?camel: Numeric, ?dot: Numeric,
+      ?basename_bonus: Numeric, ?leading_gap: Numeric, ?inner_gap: Numeric, ?trailing_gap: Numeric,
+      ?case_bonus: Numeric, ?max_length: Integer, ?max_query: Integer) -> void
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  class Match < Struct[untyped]
+    attr_reader candidate: String
+    attr_reader score: Float
+    attr_reader positions: Array[Integer]
+    attr_reader index: Integer
+    alias text candidate
+    def to_s: () -> String
+  end
+
+  class Candidate
+    attr_reader text: String
+    attr_reader chars: String | Array[String]
+    attr_reader folded: String | Array[String]
+    attr_reader mask: Integer?
+    attr_reader unicode: Hash[String, bool]?
+    attr_reader index: Integer
+    attr_reader basename: Integer
+    attr_reader bonuses: String
+    attr_reader length: Integer
+    def ascii_only?: () -> bool
+    def initialize: (String text, Integer index, ?precompute_mask: bool) -> void
+  end
+
+  class Matcher
+    def initialize: (String query, ?Options options) -> void
+    def score: (Candidate candidate) -> Float?
+    def match: (Candidate candidate) -> Match?
+  end
+
+  class Index
+    attr_reader options: Options
+    attr_reader generation: Integer
+    def initialize: (?Array[String] candidates, ?options: Options, **untyped settings) -> void
+    def add: (String | Array[String] candidates) -> self
+    def remove: (String | Array[String] candidates) -> self
+    def size: () -> Integer
+    def candidates: () -> Array[Candidate]
+    def session: () -> Session
+  end
+
+  class Session
+    attr_reader query: String
+    def initialize: (Index index) -> void
+    def query=: (String query) -> String
+    def matches: (?Integer limit) -> Array[Match]
+    def total_matches: () -> Integer
+  end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: spica
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- examples/palette.rb
+- lib/spica.rb
+- lib/spica/index.rb
+- lib/spica/matcher.rb
+- lib/spica/version.rb
+- sig/spica.rbs
+homepage: https://github.com/noxdea/spica
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/noxdea/spica
+  changelog_uri: https://github.com/noxdea/spica/blob/main/CHANGELOG.md
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.19
+specification_version: 4
+summary: Deterministic fuzzy subsequence matching with incremental filtering
+test_files: []