kotoshu 0.3.0

data/lib/kotoshu/suggestions/suggestion.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  module Suggestions
+    # A single suggestion with associated metadata and behavior.
+    # This is MORE model-driven than Spylls which returns plain strings.
+    class Suggestion
+      attr_reader :word, :distance, :confidence, :source, :metadata
+
+      # @param word [String] The suggested word
+      # @param distance [Integer] Edit distance from original (lower is better)
+      # @param confidence [Float] Confidence score (0.0 to 1.0, higher is better)
+      # @param source [String, Symbol] The strategy that produced this suggestion
+      # @param metadata [Hash] Additional metadata about the suggestion
+      def initialize(word:, distance: 0, confidence: 1.0, source: :unknown, **metadata)
+        @word = word
+        @distance = distance
+        @confidence = confidence
+        @source = source
+        @metadata = metadata
+        freeze
+      end
+
+      # Check if this is a high-confidence suggestion.
+      #
+      # @return [Boolean] True if confidence >= 0.8
+      def high_confidence?
+        @confidence >= 0.8
+      end
+
+      # Check if this is a low-confidence suggestion.
+      #
+      # @return [Boolean] True if confidence < 0.5
+      def low_confidence?
+        @confidence < 0.5
+      end
+
+      # Calculate combined score considering distance and confidence.
+      #
+      # @param distance_weight [Float] Weight for distance (default: 0.3)
+      # @param confidence_weight [Float] Weight for confidence (default: 0.7)
+      # @return [Float] Combined score (0.0 to 1.0, higher is better)
+      def combined_score(distance_weight: 0.3, confidence_weight: 0.7)
+        # Normalize distance (assume max meaningful distance is 5)
+        normalized_distance = [@distance, 5].min / 5.0
+        distance_score = 1.0 - normalized_distance
+
+        (distance_score * distance_weight) + (@confidence * confidence_weight)
+      end
+
+      # Check if this suggestion is the same word as another.
+      #
+      # @param other [Suggestion, String] The other suggestion or word string
+      # @return [Boolean] True if words match (case-insensitive)
+      def same_word?(other)
+        other_word = other.is_a?(Suggestion) ? other.word : other.to_s
+        @word.downcase == other_word.downcase
+      end
+
+      # Check if this suggestion comes from a specific source.
+      #
+      # @param source [String, Symbol] The source to check
+      # @return [Boolean] True if this suggestion came from the source
+      def from_source?(source)
+        @source == source
+      end
+
+      # Compare suggestions for sorting (higher combined score first).
+      #
+      # Ranking priority (following CSpell/Hunspell approach):
+      # 1. Combined score (higher is better)
+      # 2. Edit distance (lower is better)
+      # 3. Length similarity (prefer similar length to original word)
+      # 4. N-gram similarity (more shared n-grams is better)
+      # 5. Alphabetical (ONLY as final tiebreaker)
+      #
+      # @param other [Suggestion] The other suggestion
+      # @return [Integer] -1, 0, or 1
+      def <=>(other)
+        # First by combined score (descending)
+        score_cmp = other.combined_score <=> combined_score
+        return score_cmp unless score_cmp.zero?
+
+        # Then by distance (ascending)
+        distance_cmp = @distance <=> other.distance
+        return distance_cmp unless distance_cmp.zero?
+
+        # Then by length similarity (like CSpell - prefer words of similar length)
+        # We need access to original word length, which is stored in metadata
+        orig_len = @metadata[:original_length] || @word.length
+        other_orig_len = other.metadata[:original_length] || other.word.length
+
+        # Calculate absolute difference from original length
+        my_len_diff = (@word.length - orig_len).abs
+        other_len_diff = (other.word.length - other_orig_len).abs
+
+        len_cmp = my_len_diff <=> other_len_diff
+        return len_cmp unless len_cmp.zero?
+
+        # Then by n-gram similarity (like Hunspell - more shared n-grams is better)
+        # We use pre-computed n-gram score from metadata if available
+        my_ngram = @metadata[:ngram_score] || 0
+        other_ngram = other.metadata[:ngram_score] || 0
+
+        ngram_cmp = other_ngram <=> my_ngram  # Higher is better
+        return ngram_cmp unless ngram_cmp.zero?
+
+        # Finally by word alphabetically (ascending) - ONLY as final tiebreaker
+        @word.downcase <=> other.word.downcase
+      end
+
+      # Check equality with another suggestion.
+      #
+      # @param other [Object] The other object
+      # @return [Boolean] True if equal
+      def ==(other)
+        return false unless other.is_a?(Suggestion)
+
+        @word.downcase == other.word.downcase
+      end
+      alias eql? ==
+
+      # Hash value for use in Hash keys.
+      #
+      # @return [Integer] Hash code
+      def hash
+        @word.downcase.hash
+      end
+
+      # Convert suggestion to hash.
+      #
+      # @return [Hash] Suggestion as hash
+      def to_h
+        {
+          word: @word,
+          distance: @distance,
+          confidence: @confidence,
+          source: @source,
+          combined_score: combined_score
+        }.merge(@metadata)
+      end
+
+      # Convert suggestion to JSON-compatible hash.
+      #
+      # @return [Hash] JSON-compatible hash
+      def as_json(*)
+        to_h
+      end
+
+      # String representation.
+      #
+      # @return [String] String representation
+      def to_s
+        "Suggestion(word: '#{@word}', distance: #{@distance}, confidence: #{format("%.2f", @confidence)}, source: #{@source})"
+      end
+
+      # Inspect the suggestion.
+      #
+      # @return [String] Inspection string
+      def inspect
+        to_s
+      end
+
+      # Create a suggestion from a simple word (convenience method).
+      #
+      # @param word [String] The word
+      # @param source [String, Symbol] The source
+      # @return [Suggestion] New suggestion
+      def self.from_word(word, source: :unknown)
+        new(word: word, distance: 0, confidence: 1.0, source: source)
+      end
+    end
+  end
+end

data/lib/kotoshu/suggestions/suggestion_set.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require_relative "suggestion"
+
+module Kotoshu
+  module Suggestions
+    # A collection of suggestions with rich query methods.
+    # This is MORE OOP than Spylls which returns plain iterators of strings.
+    class SuggestionSet
+      include Enumerable
+
+      attr_reader :suggestions, :max_size
+
+      # @param suggestions [Array<Suggestion>] Initial suggestions
+      # @param max_size [Integer] Maximum number of suggestions to keep
+      def initialize(suggestions = [], max_size: 10)
+        @suggestions = suggestions
+        @max_size = max_size
+        sort_and_limit!
+      end
+
+      # Add a suggestion to the set.
+      #
+      # @param suggestion [Suggestion] The suggestion to add
+      # @return [SuggestionSet] Self for chaining
+      def add(suggestion)
+        @suggestions << suggestion
+        sort_and_limit!
+        self
+      end
+      alias << add
+
+      # Add multiple suggestions.
+      #
+      # @param new_suggestions [Array<Suggestion>] Suggestions to add
+      # @return [SuggestionSet] Self for chaining
+      def concat(new_suggestions)
+        @suggestions.concat(new_suggestions)
+        sort_and_limit!
+        self
+      end
+
+      # Merge another suggestion set into this one.
+      #
+      # @param other [SuggestionSet] The other set
+      # @return [SuggestionSet] Self for chaining
+      def merge!(other)
+        concat(other.suggestions)
+        self
+      end
+
+      # Get suggestions by source.
+      #
+      # @param source [String, Symbol] The source to filter by
+      # @return [SuggestionSet] New set with filtered suggestions
+      def from_source(source)
+        SuggestionSet.new(@suggestions.select { |s| s.from_source?(source) }, max_size: @max_size)
+      end
+
+      # Get high-confidence suggestions.
+      #
+      # @return [SuggestionSet] New set with high-confidence suggestions
+      def high_confidence
+        SuggestionSet.new(@suggestions.select(&:high_confidence?), max_size: @max_size)
+      end
+
+      # Get low-confidence suggestions.
+      #
+      # @return [SuggestionSet] New set with low-confidence suggestions
+      def low_confidence
+        SuggestionSet.new(@suggestions.select(&:low_confidence?), max_size: @max_size)
+      end
+
+      # Get suggestions within a distance range.
+      #
+      # @param min_distance [Integer] Minimum distance
+      # @param max_distance [Integer] Maximum distance
+      # @return [SuggestionSet] New set with filtered suggestions
+      def within_distance(min_distance: 0, max_distance: 2)
+        filtered = @suggestions.select do |s|
+          s.distance >= min_distance && s.distance <= max_distance
+        end
+        SuggestionSet.new(filtered, max_size: @max_size)
+      end
+
+      # Check if set contains a specific word.
+      #
+      # @param word [String] The word to check
+      # @return [Boolean] True if word is in suggestions
+      def include?(word)
+        @suggestions.any? { |s| s.same_word?(word) }
+      end
+      alias has_word? include?
+
+      # Find a suggestion by word.
+      #
+      # @param word [String] The word to find
+      # @return [Suggestion, nil] The suggestion or nil
+      def find_word(word)
+        @suggestions.find { |s| s.same_word?(word) }
+      end
+
+      # Get the top N suggestions.
+      #
+      # @param n [Integer] Number of suggestions to get
+      # @return [Array<Suggestion>] Top N suggestions
+      def top(n)
+        @suggestions.first(n)
+      end
+
+      # Get the first (best) suggestion.
+      #
+      # @return [Suggestion, nil] The best suggestion or nil
+      def first
+        @suggestions.first
+      end
+
+      # Get the last suggestion.
+      #
+      # @return [Suggestion, nil] The last suggestion or nil
+      def last
+        @suggestions.last
+      end
+
+      # Check if the set is empty.
+      #
+      # @return [Boolean] True if no suggestions
+      def empty?
+        @suggestions.empty?
+      end
+
+      # Get the number of suggestions.
+      #
+      # @return [Integer] Number of suggestions
+      def size
+        @suggestions.size
+      end
+      alias count size
+      alias length size
+
+      # Iterate over suggestions.
+      #
+      # @yield [suggestion] Each suggestion
+      # @return [Enumerator] Enumerator if no block given
+      def each(&block)
+        return enum_for(:each) unless block_given?
+
+        @suggestions.each(&block)
+      end
+
+      # Get unique suggestions (by word, case-insensitive).
+      #
+      # @return [SuggestionSet] New set with unique suggestions
+      def unique
+        seen = {}
+        unique_suggestions = @suggestions.select do |s|
+          word = s.word.downcase
+          if seen[word]
+            false
+          else
+            seen[word] = true
+            true
+          end
+        end
+        SuggestionSet.new(unique_suggestions, max_size: @max_size)
+      end
+
+      # Convert to array of words.
+      #
+      # @return [Array<String>] Array of suggestion words
+      def to_words
+        @suggestions.map(&:word)
+      end
+      alias words to_words
+
+      # Convert to array of hashes.
+      #
+      # @return [Array<Hash>] Array of suggestion hashes
+      def to_a
+        @suggestions.map(&:to_h)
+      end
+
+      # Convert to JSON-compatible array.
+      #
+      # @return [Array<Hash>] JSON-compatible array
+      def as_json(*)
+        to_a
+      end
+
+      # String representation.
+      #
+      # @return [String] String representation
+      def to_s
+        "SuggestionSet(size: #{size}, max_size: #{@max_size})"
+      end
+
+      # Inspect the suggestion set.
+      #
+      # @return [String] Inspection string
+      def inspect
+        if @suggestions.empty?
+          to_s
+        else
+          "#{self} [#{@suggestions.map(&:word).join(", ")}]"
+        end
+      end
+
+      # Create an empty suggestion set.
+      #
+      # @param max_size [Integer] Maximum size
+      # @return [SuggestionSet] Empty set
+      def self.empty(max_size: 10)
+        new([], max_size: max_size)
+      end
+
+      # Create a suggestion set from an array of words.
+      #
+      # @param words [Array<String>] Array of words
+      # @param source [String, Symbol] The source
+      # @param max_size [Integer] Maximum size
+      # @return [SuggestionSet] New set
+      def self.from_words(words, source: :unknown, max_size: 10)
+        suggestions = words.map { |w| Suggestion.from_word(w, source: source) }
+        new(suggestions, max_size: max_size)
+      end
+
+      private
+
+      # Sort suggestions by combined score and limit to max_size.
+      #
+      def sort_and_limit!
+        @suggestions.sort!
+        @suggestions.uniq! { |s| s.word.downcase }
+        @suggestions = @suggestions.first(@max_size)
+      end
+    end
+  end
+end

data/lib/kotoshu/version.rb

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