kotoshu 0.3.0

data/lib/kotoshu/suggestions/strategies/keyboard_proximity_strategy.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  module Suggestions
+    module Strategies
+      # Keyboard proximity suggestion strategy.
+      #
+      # Generates suggestions by finding words that can be formed by
+      # substituting adjacent keys on a QWERTY keyboard.
+      #
+      # @example Creating a keyboard proximity strategy
+      #   strategy = KeyboardProximityStrategy.new
+      #   result = strategy.generate(context)
+      class KeyboardProximityStrategy < BaseStrategy
+        # QWERTY keyboard layout (US).
+        #
+        # Each key maps to its adjacent keys.
+        KEYBOARD_LAYOUT = {
+          "`" => %w[1 tab],
+          "1" => ["`", "2", "q"],
+          "2" => %w[1 3 w q],
+          "3" => %w[2 4 e w],
+          "4" => %w[3 5 r e],
+          "5" => %w[4 6 t r],
+          "6" => %w[5 7 y t],
+          "7" => %w[6 8 u y],
+          "8" => %w[7 9 i u],
+          "9" => %w[8 0 o i],
+          "0" => %w[9 p o],
+          "-" => ["0", "="],
+          "=" => ["-"],
+          "q" => %w[tab w a 1],
+          "w" => %w[q e a s 2],
+          "e" => %w[w r s d 3],
+          "r" => %w[e t d f 4],
+          "t" => %w[r y f g 5],
+          "y" => %w[t u g h 6],
+          "u" => %w[y i h j 7],
+          "i" => %w[u o j k 8],
+          "o" => %w[i p k l 9],
+          "p" => ["o", "l", ";", "0"],
+          "[" => ["p", "'"],
+          "]" => ["enter", "\\"],
+          "\\" => ["enter"], # Backslash neighbors
+          "a" => %w[caps s z q],
+          "s" => %w[a d z x w],
+          "d" => %w[s f x c e],
+          "f" => %w[d g c v r],
+          "g" => %w[f h v b t],
+          "h" => %w[g j b n y],
+          "j" => %w[h k n m u],
+          "k" => ["j", "l", "m", ",", "i"],
+          "l" => ["k", ";", ",", ".", "o"],
+          ";" => ["l", "'", ".", "p"],
+          "'" => [";"],
+          "z" => %w[shift s x a],
+          "x" => %w[z c s d],
+          "c" => %w[x v d f],
+          "v" => %w[c b f g],
+          "b" => %w[v n g h],
+          "n" => %w[b m h j],
+          "m" => ["n", ",", "j", "k"],
+          "," => ["m", ".", "k", "l"],
+          "." => [",", "/", "l", ";"],
+          "/" => [".", "shift"],
+          " " => [] # Space has no neighbors
+        }.freeze
+
+        # Create a new keyboard proximity strategy.
+        #
+        # @param name [String, Symbol] Name of the strategy
+        # @param config [Hash] Configuration options
+        # @option config [Integer] max_distance Maximum keyboard distance
+        # @option config [Integer] max_results Maximum results to return
+        def initialize(name: :keyboard_proximity, **config)
+          super(name: name, **config)
+        end
+
+        # Generate suggestions based on keyboard proximity.
+        #
+        # @param context [Context] The suggestion context
+        # @return [SuggestionSet] Suggestions within keyboard distance
+        def generate(context)
+          word = context.word
+          max_dist = get_config(:max_distance, 2)
+          min_similarity = get_config(:min_similarity, 0.70)  # Filter low-similarity suggestions
+
+          all_words = dictionary_words(context)
+
+          # Generate keyboard variants
+          variants = keyboard_variants(word, max_dist)
+
+          # Find matching dictionary words with their edit distances and similarity
+          results_with_distances = {}
+          variants.each do |variant|
+            dict_word = find_word(all_words, variant)
+            next unless dict_word && dict_word != word
+
+            # Calculate edit distance from original word
+            dist = edit_distance(word, dict_word)
+            next if dist > max_dist
+
+            # Calculate typo correction similarity
+            similarity = calculate_ngram_similarity(word, dict_word)
+            next if similarity < min_similarity  # Filter by similarity threshold
+
+            # Keep the minimum distance for each word
+            results_with_distances[dict_word] ||= dist
+            results_with_distances[dict_word] = dist if dist < results_with_distances[dict_word]
+          end
+
+          # Sort by distance and create suggestions
+          sorted_words = results_with_distances.sort_by { |_, dist| dist }.map(&:first)
+          create_suggestion_set(sorted_words, distances: results_with_distances, original_word: word)
+        end
+
+        # Check if this strategy should handle the context.
+        #
+        # @param context [Context] The suggestion context
+        # @return [Boolean] True if the word needs correction
+        def handles?(context)
+          return false unless enabled?
+
+          !dictionary_lookup(context, context.word)
+        end
+
+        private
+
+        # Calculate edit distance between two strings.
+        # Uses Levenshtein distance (substitution, insertion, deletion).
+        #
+        # @param str1 [String] First string
+        # @param str2 [String] Second string
+        # @return [Integer] Edit distance
+        def edit_distance(str1, str2)
+          return str2.length if str1.empty?
+          return str1.length if str2.empty?
+
+          len1 = str1.length
+          len2 = str2.length
+
+          # Create a 2D array for dynamic programming
+          d = Array.new(len1 + 1) { Array.new(len2 + 1, 0) }
+
+          # Initialize the first row and column
+          (0..len1).each { |i| d[i][0] = i }
+          (0..len2).each { |j| d[0][j] = j }
+
+          # Fill the matrix
+          (1..len1).each do |i|
+            (1..len2).each do |j|
+              cost = (str1[i - 1] == str2[j - 1]) ? 0 : 1
+
+              d[i][j] = [
+                d[i - 1][j] + 1,      # deletion
+                d[i][j - 1] + 1,      # insertion
+                d[i - 1][j - 1] + cost  # substitution
+              ].min
+            end
+          end
+
+          d[len1][len2]
+        end
+
+        # Get neighbors for a key.
+        #
+        # @param char [String] The character
+        # @return [Array<String>] Neighbor keys
+        def neighbors(char)
+          KEYBOARD_LAYOUT[char.downcase] || []
+        end
+
+        # Generate keyboard variants of a word.
+        #
+        # @param word [String] The word
+        # @param max_distance [Integer] Maximum edit distance
+        # @return [Array<String>] Keyboard variants
+        def keyboard_variants(word, max_distance)
+          return [] if word.nil? || word.empty?
+
+          word = word.downcase
+          variants = Set.new([word])
+
+          max_distance.times do
+            new_variants = Set.new
+
+            variants.each do |variant|
+              # Generate all single-key substitutions
+              variant.each_char.with_index do |char, i|
+                neighbors(char).each do |neighbor|
+                  new_word = variant[0...i] + neighbor + variant[(i + 1)..]
+                  new_variants.add(new_word)
+
+                  # Also try insertions and deletions
+                  new_variants.add(variant[0...i] + variant[(i + 1)..]) # Delete
+                  new_variants.add(variant[0...i] + neighbor + variant[i..]) # Insert
+                end
+              end
+            end
+
+            variants = new_variants
+          end
+
+          variants.to_a
+        end
+
+        # Find a word in the dictionary (case-insensitive).
+        #
+        # @param all_words [Array<String>] All dictionary words
+        # @param word [String] The word to find
+        # @return [String, nil] The dictionary word or nil
+        def find_word(all_words, word)
+          return nil if word.nil? || word.empty?
+
+          word_lower = word.downcase
+
+          # First try exact match
+          return word if all_words.include?(word_lower)
+
+          # Then try case-insensitive search
+          all_words.find { |w| w.downcase == word_lower }
+        end
+      end
+    end
+  end
+end
+
+require "set" if RUBY_VERSION < "3.0"

data/lib/kotoshu/suggestions/strategies/ngram_strategy.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  module Suggestions
+    module Strategies
+      # N-gram suggestion strategy.
+      #
+      # Generates suggestions by finding words with high n-gram similarity.
+      # N-grams are contiguous sequences of n characters.
+      #
+      # @example Creating an n-gram strategy
+      #   strategy = NgramStrategy.new(n: 3)
+      #   result = strategy.generate(context)
+      class NgramStrategy < BaseStrategy
+        # Create a new n-gram strategy.
+        #
+        # @param name [String, Symbol] Name of the strategy
+        # @param config [Hash] Configuration options
+        # @option config [Integer] n N-gram size (default: 3)
+        # @option config [Float] min_similarity Minimum similarity threshold (0-1)
+        # @option config [Integer] max_results Maximum results to return
+        def initialize(name: :ngram, **config)
+          super(name: name, **config)
+        end
+
+        # Generate suggestions based on n-gram similarity.
+        #
+        # @param context [Context] The suggestion context
+        # @return [SuggestionSet] Suggestions with high n-gram similarity
+        def generate(context)
+          word = context.word
+          n = get_config(:n, 3)
+          min_sim = get_config(:min_similarity, 0.3)
+          min_typo_similarity = get_config(:min_typo_similarity, 0.70)  # Filter by typo correction similarity
+
+          return create_suggestion_set([]) if word.length < n
+
+          all_words = dictionary_words(context)
+
+          # Get n-grams for input word
+          word_ngrams = extract_ngrams(word, n)
+
+          # Calculate n-gram similarity for each dictionary word
+          results = {}
+          all_words.each do |dict_word|
+            next if dict_word == word
+            next if dict_word.length < n
+
+            similarity = ngram_similarity(word_ngrams, dict_word, n)
+            next if similarity < min_sim
+
+            # Also check typo correction similarity for filtering
+            typo_sim = calculate_ngram_similarity(word, dict_word)
+            next if typo_sim < min_typo_similarity
+
+            # Convert similarity to distance (higher similarity = lower distance)
+            dist = ((1 - similarity) * 10).to_i
+            next if dist.zero?
+
+            results[dict_word] ||= dist
+            results[dict_word] = dist if dist < results[dict_word]
+          end
+
+          # Convert to suggestions sorted by similarity
+          sorted_words = results.sort_by { |_, dist| dist }.map(&:first)
+          create_suggestion_set(sorted_words, distances: results, original_word: word)
+        end
+
+        # Check if this strategy should handle the context.
+        #
+        # @param context [Context] The suggestion context
+        # @return [Boolean] True if the word needs correction
+        def handles?(context)
+          return false unless enabled?
+
+          !dictionary_lookup(context, context.word)
+        end
+
+        private
+
+        # Extract n-grams from a word.
+        #
+        # @param word [String] The word
+        # @param n [Integer] N-gram size
+        # @return [Hash] N-gram to count mapping
+        def extract_ngrams(word, n)
+          ngrams = Hash.new(0)
+
+          (word.length - n + 1).times do |i|
+            ngram = word[i...i + n]
+            ngrams[ngram] += 1
+          end
+
+          ngrams
+        end
+
+        # Calculate n-gram similarity between two words.
+        #
+        # Uses the Jaccard similarity coefficient:
+        # similarity = |intersection| / |union|
+        #
+        # @param word_ngrams [Hash] N-grams for the first word
+        # @param other_word [String] The second word
+        # @param n [Integer] N-gram size
+        # @return [Float] Similarity score (0-1)
+        def ngram_similarity(word_ngrams, other_word, n)
+          other_ngrams = extract_ngrams(other_word, n)
+
+          # Calculate intersection
+          intersection = 0
+          word_ngrams.each do |ngram, count|
+            other_count = other_ngrams[ngram]
+            intersection += [count, other_count].min if other_count
+          end
+
+          # Calculate union
+          all_ngrams = word_ngrams.keys | other_ngrams.keys
+          union = 0
+          all_ngrams.each do |ngram|
+            union += [word_ngrams[ngram] || 0, other_ngrams[ngram] || 0].max
+          end
+
+          return 0.0 if union.zero?
+
+          intersection.to_f / union
+        end
+      end
+    end
+  end
+end

data/lib/kotoshu/suggestions/strategies/phonetic_strategy.rb

@@ -0,0 +1,329 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  module Suggestions
+    module Strategies
+      # Phonetic suggestion strategy.
+      #
+      # Generates suggestions by finding words with similar phonetic codes
+      # using algorithms like Soundex and Metaphone.
+      #
+      # @example Creating a phonetic strategy
+      #   strategy = PhoneticStrategy.new(algorithm: :soundex)
+      #   result = strategy.generate(context)
+      class PhoneticStrategy < BaseStrategy
+        # Supported algorithms.
+        ALGORITHMS = %i[soundex metaphone].freeze
+
+        # Create a new phonetic strategy.
+        #
+        # @param name [String, Symbol] Name of the strategy
+        # @param config [Hash] Configuration options
+        # @option config [Symbol] algorithm The algorithm to use (:soundex or :metaphone)
+        # @option config [Integer] max_results Maximum results to return
+        def initialize(name: :phonetic, **config)
+          super(name: name, **config)
+        end
+
+        # Generate suggestions based on phonetic similarity.
+        #
+        # @param context [Context] The suggestion context
+        # @return [SuggestionSet] Suggestions with same phonetic code
+        def generate(context)
+          word = context.word
+          algorithm = get_config(:algorithm, :soundex)
+          max_dist = 2
+
+          all_words = dictionary_words(context)
+
+          # Get phonetic code for input word
+          word_code = phonetic_code(word, algorithm)
+
+          # Find words with same phonetic code
+          results = []
+          all_words.each do |dict_word|
+            next if dict_word == word
+
+            dict_code = phonetic_code(dict_word, algorithm)
+            next unless dict_code == word_code
+
+            dist = edit_distance(word, dict_word)
+            next if dist > max_dist || dist.zero?
+
+            results << [dict_word, dist]
+          end
+
+          # Sort by distance and convert to suggestions
+          sorted_words = results.sort_by { |_, dist| dist }.map(&:first)
+          create_suggestion_set(sorted_words)
+        end
+
+        # Check if this strategy should handle the context.
+        #
+        # @param context [Context] The suggestion context
+        # @return [Boolean] True if the word needs correction
+        def handles?(context)
+          return false unless enabled?
+
+          !dictionary_lookup(context, context.word)
+        end
+
+        private
+
+        # Get phonetic code for a word.
+        #
+        # @param word [String] The word
+        # @param algorithm [Symbol] The algorithm to use
+        # @return [String] The phonetic code
+        def phonetic_code(word, algorithm = :soundex)
+          case algorithm
+          when :soundex
+            soundex_code(word)
+          when :metaphone
+            metaphone_code(word)
+          else
+            soundex_code(word)
+          end
+        end
+
+        # Calculate Soundex code for a word.
+        #
+        # Soundex is a phonetic algorithm developed by Robert C. Russell
+        # and Margaret King Odell in the early 1900s.
+        #
+        # @param word [String] The word
+        # @return [String] The Soundex code (letter + 3 digits)
+        #
+        # @example
+        #   soundex_code("Robert")  # => "R163"
+        #   soundex_code("Rupert")  # => "R163"
+        #   soundex_code("Ashcraft") # => "A226"
+        def soundex_code(word)
+          return "" if word.nil? || word.empty?
+
+          word = word.upcase.gsub(/[^A-Z]/, "")
+          return "" if word.empty?
+
+          # Keep first letter
+          first_letter = word[0]
+          rest = word[1..]
+
+          # Encode remaining letters
+          code = first_letter
+
+          prev_code = soundex_encode(first_letter)
+          i = 0
+
+          while code.length < 4 && i < rest.length
+            char = rest[i]
+            encoded = soundex_encode(char)
+
+            # Add code if different from previous (ignore h and w)
+            code += encoded if encoded != "0" && encoded != prev_code
+
+            prev_code = encoded if encoded != "0"
+            i += 1
+          end
+
+          # Pad with zeros if needed
+          code.ljust(4, "0")[0...4]
+        end
+
+        # Soundex encoding table.
+        #
+        # @param char [String] The character
+        # @return [String] The encoded digit or "0" for no code
+        def soundex_encode(char)
+          case char.upcase
+          when "B", "P", "F", "V"
+            "1"
+          when "C", "S", "K", "G", "J", "Q", "X", "Z"
+            "2"
+          when "D", "T"
+            "3"
+          when "L"
+            "4"
+          when "M", "N"
+            "5"
+          when "R"
+            "6"
+          else
+            "0"
+          end
+        end
+
+        # Calculate Metaphone code for a word.
+        #
+        # Metaphone is an improved phonetic algorithm developed by
+        # Lawrence Philips in 1990.
+        #
+        # @param word [String] The word
+        # @return [String] The Metaphone code
+        #
+        # @example
+        #   metaphone_code("Schmidt")  # => "XMT"
+        #   metaphone_code("Smith")    # => "SM0"
+        def metaphone_code(word)
+          return "" if word.nil? || word.empty?
+
+          word = word.upcase.gsub(/[^A-Z]/, "")
+          return "" if word.empty?
+
+          # Metaphone rules (simplified implementation)
+          code = ""
+          i = 0
+          length = word.length
+
+          while i < length && code.length < 4
+            char = word[i]
+            next_char = i + 1 < length ? word[i + 1] : ""
+
+            case char
+            when "A", "E", "I", "O", "U"
+              # Vowels are only encoded at the beginning
+              code += char if i.zero?
+            when "B"
+              code += "B"
+            when "C"
+              if next_char == "H" && i + 2 < length && %w[A E I O U].include?(word[i + 2])
+                # "CH" followed by vowel => "X"
+                code += "X"
+                i += 1
+              elsif next_char == "I" && i + 2 < length && word[i + 2] == "A"
+                # "CIA" => "X"
+                code += "X"
+                i += 2
+              elsif %w[S G].include?(next_char)
+                # "CS", "CG" => "X"
+                code += "X"
+                i += 1
+              else
+                code += "K"
+              end
+            when "D"
+              if next_char == "G" && i + 2 < length && %w[I E Y].include?(word[i + 2])
+                # "DG" followed by I, E, Y => "J"
+                code += "J"
+                i += 1
+              else
+                code += "T"
+              end
+            when "F"
+              code += "F"
+            when "G"
+              if next_char == "H"
+                # "GH" => silent unless at beginning or after vowel
+                if i.zero?
+                  code += "K"
+                  i += 1
+                end
+              elsif next_char == "N"
+                # "GN" => "N" (silent G)
+                i += 1
+              elsif next_char == "N" && i + 2 < length && word[i + 2] == "E" && i + 3 < length && word[i + 3] == "D"
+                # "GNED" => "N" (silent G)
+                i += 3
+              else
+                code += "K"
+              end
+            when "H"
+              # H is silent unless at beginning
+              code += "H" if i.zero?
+            when "J"
+              code += "J"
+            when "K"
+              code += "K"
+              i += 1 if next_char == "N" # "KN" => "N"
+            when "L"
+              code += "L"
+            when "M"
+              code += "M"
+            when "N"
+              code += "N"
+            when "P"
+              if next_char == "H"
+                # "PH" => "F"
+                code += "F"
+                i += 1
+              else
+                code += "P"
+              end
+            when "Q"
+              code += "K"
+            when "R"
+              code += "R"
+            when "S"
+              if next_char == "H"
+                # "SH" => "X"
+                code += "X"
+                i += 1
+              elsif next_char == "I" && i + 2 < length && word[i + 2] == "O"
+                # "SIO" or "SIA" => "X"
+                code += "X"
+                i += 2
+              else
+                code += "S"
+              end
+            when "T"
+              if next_char == "I" && i + 2 < length && %w[O A].include?(word[i + 2])
+                # "TIO" or "TIA" => "X"
+                code += "X"
+                i += 2
+              elsif next_char == "H"
+                # "TH" => "0"
+                code += "0"
+                i += 1
+              else
+                code += "T"
+              end
+            when "V"
+              code += "F"
+            when "W", "Y"
+              # W and Y are semi-vowels, only encode at beginning
+              code += char if i.zero?
+            when "X"
+              code += "KS"
+            when "Z"
+              code += "S"
+            end
+
+            i += 1
+          end
+
+          code[0...4] # Max 4 characters
+        end
+
+        # Calculate Levenshtein edit distance.
+        #
+        # @param str1 [String] First string
+        # @param str2 [String] Second string
+        # @return [Integer] Edit distance
+        def edit_distance(str1, str2)
+          return str2.length if str1.empty?
+          return str1.length if str2.empty?
+
+          # Use smaller string for inner loop
+          str1, str2 = str2, str1 if str1.length > str2.length
+
+          previous = (0..str1.length).to_a
+
+          str2.each_char.with_index do |char2, j|
+            current = [j + 1]
+
+            str1.each_char.with_index do |char1, i|
+              insert_cost = current[i] + 1
+              delete_cost = previous[i + 1] + 1
+              substitute_cost = previous[i] + (char1 == char2 ? 0 : 1)
+
+              current << [insert_cost, delete_cost, substitute_cost].min
+            end
+
+            previous = current
+          end
+
+          previous.last
+        end
+      end
+    end
+  end
+end