kotoshu 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9985d7382788ffadb4cb749614c8358dcb26bf25ba4ad6408843773a301a0ca6
-  data.tar.gz: 15daa8e23f8cf5a4f4d23ce8a13cb5ed71c9b2973c61f87e3b68ddd76b96b8fd
+  metadata.gz: 503b4db65b4971cdc8854123771d9c1855af0de6f408f625d63219d5470c848c
+  data.tar.gz: caa57938fc7a76f3c0f7d026346db8e7f247db34b1a9b51d79ab2e9962668f57
 SHA512:
-  metadata.gz: 9aa241732513b7cf36b3bcea16a59180b920e0f6582f750e68d865311c1d74b05d6531e769f2bfb8e8c54700a8dad4b67c8858bce7bfa9a6c009c09b41d573fa
-  data.tar.gz: e48730e02792163a07bec84e450abfabe0e401ce45eda2decdd9ea6b2456dba11dbbece9934c256edad505a1eeb35030d5efa11043b42313479a1b243cb07251
+  metadata.gz: 9bb38cd338777586b8bf3c4700d36c5bd083b81f002fc9df0ee3ab667bde36a2a31b0dd8ebd9096543b57de8e151c18b9265df900306c7c71ae06cdc8e33825f
+  data.tar.gz: 6a11f2cbc34632d9533af0665308943063f06d952816e277fd1e995adfbbe84a56915693a6b9a9a53a4c64589ff8d09399c66ace9c7f7c657f865e4b0ef7adc4

data/data/en/grammar/rules.yaml

@@ -466,3 +466,277 @@ rules:
             suggestion: "used to"
     message: '"use to" should be "used to"'
     suggestion: 'used to'
+
+  - id: EN_ITS_IT_S
+    name: "its/it's"
+    category: confusion
+    severity: warning
+    description: |
+      "its" (no apostrophe) is the possessive pronoun — like "his"
+      or "her". "it's" (with apostrophe) is a contraction of "it is"
+      or "it has". When "its" is followed by an adjective, adverb,
+      or past participle, the writer usually meant the contraction.
+    message: "Did you mean \"it's\" (contraction of \"it is\")?"
+    suggestion: "it's"
+    patterns:
+      - context:
+          target_token: "its"
+          trigger_when_followed_by:
+            tags: [ADJ, ADV]
+            words:
+              - been
+              - going
+              - getting
+              - becoming
+              - appearing
+              - seeming
+              - looking
+              - feeling
+              - sounding
+              - tasting
+              - smelling
+        conditions:
+          - type: possessive_contraction_check
+
+  - id: EN_YOUR_YOURE
+    name: "your/you're"
+    category: confusion
+    severity: warning
+    description: |
+      "your" is the possessive pronoun. "you're" is a contraction of
+      "you are". When "your" is followed by an adjective or past
+      participle, the writer usually meant the contraction.
+    message: "Did you mean \"you're\" (contraction of \"you are\")?"
+    suggestion: "you're"
+    patterns:
+      - context:
+          target_token: "your"
+          trigger_when_followed_by:
+            tags: [ADJ, ADV]
+            words:
+              - going
+              - getting
+              - becoming
+              - coming
+              - leaving
+              - arriving
+              - doing
+              - making
+              - saying
+              - thinking
+              - feeling
+              - looking
+              - sounding
+        conditions:
+          - type: possessive_contraction_check
+
+  - id: EN_WHOSE_WHOS
+    name: "whose/who's"
+    category: confusion
+    severity: warning
+    description: |
+      "whose" is the possessive form of "who". "who's" is a
+      contraction of "who is" or "who has". When "whose" is followed
+      by a verb form, the writer usually meant the contraction.
+    message: "Did you mean \"who's\" (contraction of \"who is\")?"
+    suggestion: "who's"
+    patterns:
+      - context:
+          target_token: "whose"
+          trigger_when_followed_by:
+            tags: [VERB]
+            words:
+              - coming
+              - going
+              - here
+              - there
+              - talking
+              - speaking
+              - calling
+              - looking
+              - watching
+              - working
+              - doing
+              - making
+              - been
+              - got
+        conditions:
+          - type: possessive_contraction_check
+
+  - id: EN_SENTENCE_START_CAP
+    name: "Sentence start capitalization"
+    category: capitalization
+    severity: error
+    description: |
+      The first word of a sentence should be capitalized. Sentence
+      boundaries are: the start of the stream, or any token whose
+      final character is ".", "!", or "?".
+    message: "Sentences should start with a capital letter"
+    suggestion: "Capitalize the first letter"
+    patterns:
+      - conditions:
+          - type: sentence_start_check
+
+  - id: EN_PROPER_NOUN_CAP
+    name: "Proper noun capitalization"
+    category: capitalization
+    severity: error
+    description: |
+      Days of the week, months, languages, and some other common
+      proper nouns must be capitalized in English.
+    message: "Proper nouns should be capitalized"
+    suggestion: "Capitalize the proper noun"
+    patterns:
+      - conditions:
+          - type: word_list_check
+            corrections:
+              # Days of the week
+              monday: Monday
+              tuesday: Tuesday
+              wednesday: Wednesday
+              thursday: Thursday
+              friday: Friday
+              saturday: Saturday
+              sunday: Sunday
+              # Months
+              january: January
+              february: February
+              march: March
+              april: April
+              june: June
+              july: July
+              august: August
+              september: September
+              october: October
+              november: November
+              december: December
+              # Languages and nationalities
+              english: English
+              spanish: Spanish
+              french: French
+              german: German
+              italian: Italian
+              russian: Russian
+              chinese: Chinese
+              japanese: Japanese
+              korean: Korean
+              arabic: Arabic
+              hebrew: Hebrew
+              hindi: Hindi
+              portuguese: Portuguese
+              dutch: Dutch
+              swedish: Swedish
+              polish: Polish
+              turkish: Turkish
+              greek: Greek
+              latin: Latin
+
+  - id: EN_MORE_THEN
+    name: "more then → more than"
+    category: grammar
+    severity: error
+    description: |
+      "more then" is a common confusion. The comparative "more"
+      takes "than" (the comparison conjunction), not "then"
+      (the time adverb).
+    patterns:
+      - conditions:
+          - type: phrase_check
+            wrong_phrase: "more then"
+            suggestion: "more than"
+    message: '"more then" should be "more than"'
+    suggestion: 'more than'
+
+  - id: EN_LESS_THEN
+    name: "less then → less than"
+    category: grammar
+    severity: error
+    description: |
+      "less then" is a common confusion. "less" takes "than" for
+      comparison.
+    patterns:
+      - conditions:
+          - type: phrase_check
+            wrong_phrase: "less then"
+            suggestion: "less than"
+    message: '"less then" should be "less than"'
+    suggestion: 'less than'
+
+  - id: EN_RATHER_THEN
+    name: "rather then → rather than"
+    category: grammar
+    severity: error
+    description: |
+      "rather then" is a common confusion. "rather" takes "than"
+      in preference constructions ("I would rather X than Y").
+    patterns:
+      - conditions:
+          - type: phrase_check
+            wrong_phrase: "rather then"
+            suggestion: "rather than"
+    message: '"rather then" should be "rather than"'
+    suggestion: 'rather than'
+
+  - id: EN_OTHER_THEN
+    name: "other then → other than"
+    category: grammar
+    severity: error
+    description: |
+      "other then" is a common confusion. "other than" is the
+      correct idiom for "except for" or "apart from".
+    patterns:
+      - conditions:
+          - type: phrase_check
+            wrong_phrase: "other then"
+            suggestion: "other than"
+    message: '"other then" should be "other than"'
+    suggestion: 'other than'
+
+  - id: EN_COULD_CARE_LESS
+    name: "could care less → couldn't care less"
+    category: grammar
+    severity: warning
+    description: |
+      "I could care less" literally means you DO care (because
+      it's possible to care less). The intended idiom is
+      "I couldn't care less" (it's impossible to care less
+      because you already care zero).
+    patterns:
+      - conditions:
+          - type: phrase_check
+            wrong_phrase: "could care less"
+            suggestion: "couldn't care less"
+    message: "\"could care less\" should be \"couldn't care less\""
+    suggestion: "couldn't care less"
+
+  - id: EN_FOR_FREE
+    name: "for free → free"
+    category: grammar
+    severity: suggestion
+    description: |
+      "for free" is redundant — "free" already means "at no cost".
+      Prefer just "free" (e.g., "I got it free", not "I got it
+      for free").
+    patterns:
+      - conditions:
+          - type: phrase_check
+            wrong_phrase: "for free"
+            suggestion: "free"
+    message: '"for free" is redundant — consider just "free"'
+    suggestion: 'free'
+
+  - id: EN_ALOT
+    name: "alot → a lot"
+    category: grammar
+    severity: error
+    description: |
+      "alot" is not a word. The correct spelling is "a lot"
+      (two words). "allot" (verb, to distribute) is a different
+      word.
+    patterns:
+      - conditions:
+          - type: phrase_check
+            wrong_phrase: "alot"
+            suggestion: "a lot"
+    message: '"alot" is not a word — use "a lot"'
+    suggestion: 'a lot'

data/lib/kotoshu/algorithms/edit_distance.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  module Algorithms
+    # Damerau-Levenshtein edit distance.
+    #
+    # Counts the minimum number of operations (insertion, deletion,
+    # substitution, or transposition of adjacent characters) needed
+    # to transform one string into another. The transposition
+    # extension distinguishes this from plain Levenshtein — a
+    # transposition (e.g. "teh" → "the") costs 1 instead of 2.
+    #
+    # Extracted from EditDistanceStrategy so that the algorithm is
+    # reusable independent of the strategy pipeline and testable
+    # without send-to-private.
+    module EditDistance
+      module_function
+
+      # Compute the Damerau-Levenshtein distance between two strings.
+      #
+      # @param str1 [String] First string
+      # @param str2 [String] Second string
+      # @return [Integer] Edit distance (0 when str1 == str2)
+      def distance(str1, str2)
+        return str2.length if str1.empty?
+        return str1.length if str2.empty?
+
+        len1 = str1.length
+        len2 = str2.length
+
+        d = Array.new(len1 + 1) { Array.new(len2 + 1, 0) }
+
+        (0..len1).each { |i| d[i][0] = i }
+        (0..len2).each { |j| d[0][j] = j }
+
+        (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
+
+            next unless i > 1 && j > 1 &&
+              str1[i - 1] == str2[j - 2] &&
+              str1[i - 2] == str2[j - 1]
+
+            d[i][j] = [d[i][j], d[i - 2][j - 2] + 1].min
+          end
+        end
+
+        d[len1][len2]
+      end
+
+      # Compute edit distance with early-exit threshold.
+      #
+      # Returns nil when the true distance exceeds +threshold+,
+      # letting callers prune candidate pairs without paying for
+      # the full computation. The current implementation computes
+      # the full distance and then thresholds — kept as a seam so
+      # a future banded-DP optimization can drop in here.
+      #
+      # @param str1 [String] First string
+      # @param str2 [String] Second string
+      # @param threshold [Integer] Maximum distance to report
+      # @return [Integer, nil] Distance if ≤ threshold, else nil
+      def distance_with_threshold(str1, str2, threshold)
+        dist = distance(str1, str2)
+        dist <= threshold ? dist : nil
+      end
+    end
+  end
+end

data/lib/kotoshu/algorithms.rb

@@ -17,5 +17,6 @@ module Kotoshu
     autoload :NgramSuggest, "kotoshu/algorithms/ngram_suggest"
     autoload :PhonetSuggest, "kotoshu/algorithms/phonet_suggest"
     autoload :Capitalization, "kotoshu/algorithms/capitalization"
+    autoload :EditDistance, "kotoshu/algorithms/edit_distance"
   end
 end

data/lib/kotoshu/data_structures/bloom_filter.rb

@@ -164,17 +164,23 @@ module Kotoshu
 
       # Calculate hash index for item with seed.
       #
-      # Uses double hashing for multiple hash functions:
-      # hash_i(item) = (hash1(item) + i * hash2(item)) % m
+      # Uses double hashing (Kirsch-Mitzenmacher):
+      #   h_i(x) = (h1(x) + i * h2(x)) mod m
+      #
+      # The scheme requires h1 and h2 to be *independent* hash
+      # functions. Using `item.hash` for both (as an earlier version
+      # did) makes them linearly dependent and inflates the false-
+      # positive rate well above the configured target — observed
+      # ~6–16% versus the theoretical 1% on a filter sized for
+      # 1% FPR. Deriving h2 from a salted copy of the item restores
+      # independence and brings the observed rate back into line.
       #
       # @param item [String] The item to hash
       # @param seed [Integer] Hash function index
       # @return [Integer] Bit array index
       def hash_index(item, seed)
-        # Use Ruby's built-in hash with different seeds
         hash1 = item.hash
-        hash2 = (item.hash * 31) + seed
-
+        hash2 = "#{item}#bloom#salt".hash
         (hash1 + (seed * hash2.abs)) % @size
       end
     end

data/lib/kotoshu/dictionary/base.rb

@@ -232,6 +232,14 @@ module Kotoshu
       @registry ||= {}
     end
 
+    # Reset the type registry. Used by specs that register throw-away
+    # dictionary classes; not part of the runtime contract.
+    #
+    # @return [void]
+    def self.reset_registry!
+      @registry = {}
+    end
+
     # Register a dictionary type.
     #
     # @param type [Symbol] The type key

data/lib/kotoshu/grammar/pattern_matchers/possessive_contraction_matcher.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  module Grammar
+    module PatternMatchers
+      # Matcher for possessive-vs-contraction confusion rules.
+      #
+      # Detects when a possessive form ("its", "your", "whose") is
+      # used where the corresponding contraction ("it's", "you're",
+      # "who's") is intended — or vice versa. The trigger is the
+      # following token's POS tag or word form.
+      #
+      # Rule shape:
+      #
+      #   patterns:
+      #     - context:
+      #         target_token: "its"
+      #         trigger_when_followed_by:
+      #           tags: [ADJ, ADV]
+      #           words: [been, going, getting]
+      #       conditions:
+      #         - type: possessive_contraction_check
+      #
+      # When the target token is followed by a token whose POS tag is
+      # in +tags+ OR whose lowercased form is in +words+, emit an
+      # error with +rule.suggestion+ as the replacement.
+      #
+      # Examples:
+      #   "its cold"      → suggest "it's"  (cold is ADJ)
+      #   "your ready"    → suggest "you're"
+      #   "whose coming"  → suggest "who's"
+      class PossessiveContractionMatcher < BaseMatcher
+        def match(tokens, rule)
+          errors = []
+          target = pattern_target_token
+          triggers = pattern_triggers
+
+          tokens.each_with_index do |token, idx|
+            next unless matches_target?(token, target)
+
+            next_token = tokens[idx + 1]
+            next unless next_token
+            next unless triggers_match?(next_token, triggers)
+
+            errors << build_error(token, next_token, rule)
+          end
+          errors
+        end
+
+        protected
+
+        def pattern_target_token
+          @pattern.dig('context', 'target_token')
+        end
+
+        def pattern_triggers
+          @pattern.dig('context', 'trigger_when_followed_by') || {}
+        end
+
+        def matches_target?(token, target)
+          target && token[:token]&.downcase == target.downcase
+        end
+
+        def triggers_match?(next_token, triggers)
+          trigger_tags = triggers['tags'] || []
+          trigger_words = (triggers['words'] || []).map(&:downcase)
+
+          tag = next_token[:pos_tag]
+          word = next_token[:token]&.downcase
+
+          trigger_tags.include?(tag) || trigger_words.include?(word)
+        end
+
+        def build_error(token, next_token, rule)
+          {
+            rule_id: rule.id,
+            position: token[:position],
+            message: rule.message,
+            suggestion: rule.suggestion,
+            context: "\"#{token[:token]} #{next_token[:token]}\"",
+            suggestions: [rule.suggestion]
+          }
+        end
+      end
+    end
+  end
+end

data/lib/kotoshu/grammar/pattern_matchers/sentence_start_matcher.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  module Grammar
+    module PatternMatchers
+      # Matcher for sentence-start capitalization rules.
+      #
+      # English (and most Latin-script languages) capitalizes the
+      # first word of every sentence. This matcher walks the token
+      # stream tracking sentence boundaries and flags lowercase
+      # sentence starts.
+      #
+      # A sentence starts:
+      #   - at the beginning of the stream, OR
+      #   - immediately after a token whose final character is a
+      #     sentence-ending punctuation mark (. ! ?).
+      #
+      # The matcher only considers alphabetic tokens. Numbers,
+      # symbols, and whitespace don't reset the sentence-start flag.
+      #
+      # Rule shape:
+      #
+      #   patterns:
+      #     - conditions:
+      #         - type: sentence_start_check
+      #
+      class SentenceStartMatcher < BaseMatcher
+        SENTENCE_ENDERS = %w[. ! ?].freeze
+
+        def match(tokens, rule)
+          errors = []
+          expecting_capital = true
+
+          tokens.each do |token|
+            word = token[:token]
+            next if word.nil? || word.empty?
+
+            if sentence_start_word?(word, expecting_capital)
+              errors << build_error(token, rule)
+            end
+
+            # Any non-empty token resets the sentence-start expectation.
+            # Only sentence-ending punctuation re-arms it (below).
+            expecting_capital = false
+            expecting_capital = true if ends_sentence?(word)
+          end
+
+          errors
+        end
+
+        protected
+
+        def sentence_start_word?(word, expecting_capital)
+          expecting_capital && alphabetic_word?(word) && first_letter_lowercase?(word)
+        end
+
+        def alphabetic_word?(word)
+          !word.nil? && !word.empty? && word[0].match?(/[[:alpha:]]/)
+        end
+
+        def first_letter_lowercase?(word)
+          first = word[0]
+          first == first.downcase && first != first.upcase
+        end
+
+        def ends_sentence?(word)
+          SENTENCE_ENDERS.include?(word[-1])
+        end
+
+        def build_error(token, rule)
+          capitalized = token[:token].sub(/\A(\w)/) { $1.upcase }
+          {
+            rule_id: rule.id,
+            position: token[:position],
+            message: rule.message,
+            suggestion: capitalized,
+            context: "\"#{token[:token]}\"",
+            suggestions: [capitalized]
+          }
+        end
+      end
+    end
+  end
+end

data/lib/kotoshu/grammar/pattern_matchers/word_list_matcher.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  module Grammar
+    module PatternMatchers
+      # Matcher for word-list corrections.
+      #
+      # Flags any token whose lowercase form is a key in the rule's
+      # +corrections+ map. Useful for proper-noun capitalization
+      # (monday → Monday, english → English) where a single rule
+      # covers dozens of word pairs.
+      #
+      # Rule shape:
+      #
+      #   patterns:
+      #     - conditions:
+      #         - type: word_list_check
+      #           corrections:
+      #             monday: Monday
+      #             tuesday: Tuesday
+      #             english: English
+      #
+      # The matcher only fires when the actual token text differs from
+      # the mapped correction (so "Monday" doesn't get flagged).
+      #
+      class WordListMatcher < BaseMatcher
+        def match(tokens, rule)
+          corrections = word_list_condition&.dig('corrections') || {}
+          return [] if corrections.empty?
+
+          errors = []
+          tokens.each do |token|
+            word = token[:token]
+            next unless word
+
+            correction = corrections[word.downcase]
+            next unless correction
+            next if word == correction # already correct
+
+            errors << build_error(token, correction, rule)
+          end
+          errors
+        end
+
+        private
+
+        def word_list_condition
+          @word_list_condition ||= @pattern['conditions']&.find do |c|
+            c['type'] == 'word_list_check'
+          end
+        end
+
+        def build_error(token, correction, rule)
+          {
+            rule_id: rule.id,
+            position: token[:position],
+            message: rule.message,
+            suggestion: correction,
+            context: "\"#{token[:token]}\"",
+            suggestions: [correction]
+          }
+        end
+      end
+    end
+  end
+end

data/lib/kotoshu/grammar/rule.rb

@@ -80,10 +80,16 @@ module Kotoshu
           PatternMatchers::VowelSoundMatcher.new(pattern, exceptions)
         elsif condition_types.include?('context_check')
           PatternMatchers::PossessiveContextMatcher.new(pattern, exceptions)
+        elsif condition_types.include?('possessive_contraction_check')
+          PatternMatchers::PossessiveContractionMatcher.new(pattern, exceptions)
         elsif condition_types.include?('distance_check')
           PatternMatchers::DoubleNegativeMatcher.new(pattern, exceptions)
         elsif condition_types.include?('phrase_check')
           PatternMatchers::PhraseMatcher.new(pattern, exceptions)
+        elsif condition_types.include?('sentence_start_check')
+          PatternMatchers::SentenceStartMatcher.new(pattern, exceptions)
+        elsif condition_types.include?('word_list_check')
+          PatternMatchers::WordListMatcher.new(pattern, exceptions)
         else
           PatternMatchers::BaseMatcher.new(pattern)
         end

data/lib/kotoshu/grammar.rb

@@ -14,8 +14,11 @@ module Kotoshu
       autoload :BaseMatcher, "kotoshu/grammar/pattern_matchers/base_matcher"
       autoload :VowelSoundMatcher, "kotoshu/grammar/pattern_matchers/vowel_sound_matcher"
       autoload :PossessiveContextMatcher, "kotoshu/grammar/pattern_matchers/possessive_context_matcher"
+      autoload :PossessiveContractionMatcher, "kotoshu/grammar/pattern_matchers/possessive_contraction_matcher"
       autoload :DoubleNegativeMatcher, "kotoshu/grammar/pattern_matchers/double_negative_matcher"
       autoload :PhraseMatcher, "kotoshu/grammar/pattern_matchers/phrase_matcher"
+      autoload :SentenceStartMatcher, "kotoshu/grammar/pattern_matchers/sentence_start_matcher"
+      autoload :WordListMatcher, "kotoshu/grammar/pattern_matchers/word_list_matcher"
     end
   end
 end

data/lib/kotoshu/language/normalizer/base.rb

@@ -78,8 +78,6 @@ module Kotoshu
           normalize(str1) == normalize(str2)
         end
 
-        protected
-
         # Strip punctuation from text.
         #
         # @param text [String] Text to strip

data/lib/kotoshu/languages/en/language.rb

@@ -274,6 +274,10 @@ module Kotoshu
           @lookup_cache.clear
         end
 
+        def cache_size
+          @lookup_cache.size
+        end
+
         private
 
         def lookup_with_pos(word)

data/lib/kotoshu/languages/es/language.rb

@@ -204,6 +204,10 @@ module Kotoshu
           @lookup_cache.clear
         end
 
+        def cache_size
+          @lookup_cache.size
+        end
+
         private
 
         def lookup_with_pos(word)

data/lib/kotoshu/languages/pt/language.rb

@@ -206,6 +206,10 @@ module Kotoshu
           @lookup_cache.clear
         end
 
+        def cache_size
+          @lookup_cache.size
+        end
+
         private
 
         def lookup_with_pos(word)

data/lib/kotoshu/languages/ru/language.rb

@@ -211,6 +211,10 @@ module Kotoshu
           @lookup_cache.clear
         end
 
+        def cache_size
+          @lookup_cache.size
+        end
+
         private
 
         def lookup_with_pos(word)

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

@@ -61,21 +61,19 @@ module Kotoshu
           @strategies.select { |s| s.handles?(context) }
         end
 
-        # Generate suggestions by delegating to all child strategies.
+        # Generate suggestions by delegating to all applicable strategies.
+        #
+        # Candidates are collected from every strategy first, then handed
+        # to a single SuggestionSet so dedup and ranking run once over the
+        # full pool (not as a side effect of each merge). TODO 56 T5.1.
         #
         # @param context [Context] The suggestion context
         # @return [SuggestionSet] Combined suggestions from all strategies
         def generate(context)
-          # Create result set
-          result = SuggestionSet.empty(max_size: context.max_results)
-
-          # Process each applicable strategy
-          applicable_strategies(context).each do |strategy|
-            strategy_result = strategy.generate(context)
-            result.merge!(strategy_result)
+          candidates = applicable_strategies(context).flat_map do |strategy|
+            strategy.generate(context).suggestions
           end
-
-          result
+          SuggestionSet.new(candidates, max_size: context.max_results)
         end
 
         # Check if any strategy can handle the context.

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

@@ -267,52 +267,13 @@ module Kotoshu
         end
 
         # Calculate Damerau-Levenshtein edit distance between two strings.
-        # This extends Levenshtein by treating transposition of adjacent characters as 1 operation.
-        #
-        # Examples:
-        #   "wrold" → "world" = 1 (transposition of 'r' and 'o')
-        #   "hello" → "hell" = 1 (deletion)
-        #   "cat" → "cut" = 1 (substitution)
+        # Delegates to Algorithms::EditDistance.
         #
         # @param str1 [String] First string
         # @param str2 [String] Second string
         # @return [Integer] Edit distance
         def edit_distance(str1, str2)
-          # Handle empty strings
-          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
-
-              # Check for transposition (Damerau extension)
-              if i > 1 && j > 1 &&
-                  str1[i - 1] == str2[j - 2] &&
-                  str1[i - 2] == str2[j - 1]
-                d[i][j] = [d[i][j], d[i - 2][j - 2] + 1].min
-              end
-            end
-          end
-
-          d[len1][len2]
+          Algorithms::EditDistance.distance(str1, str2)
         end
 
         # Optimized edit distance with early termination.
@@ -323,12 +284,11 @@ module Kotoshu
         # @param threshold [Integer] Maximum distance to calculate
         # @return [Integer, nil] Distance or nil if exceeds threshold
         def edit_distance_with_threshold(str1, str2, threshold)
-          # For now, use the regular implementation
-          # This can be optimized later with early termination
-          dist = edit_distance(str1, str2)
-          dist <= threshold ? dist : nil
+          Algorithms::EditDistance.distance_with_threshold(str1, str2, threshold)
         end
 
+        public
+
         # Calculate enhanced score combining multiple factors.
         #
         # Lower score = better suggestion
@@ -479,6 +439,8 @@ module Kotoshu
           bonus
         end
 
+        private
+
         # Resolve keyboard layout using OOP registry pattern
         #
         # @param keyboard_layout [Keyboard::Layout, String, nil] Layout override

data/lib/kotoshu/suggestions/suggestion_set.rb

@@ -7,13 +7,16 @@ module Kotoshu
     class SuggestionSet
       include Enumerable
 
-      attr_reader :suggestions, :max_size
+      # @return [Integer] Number of duplicate suggestions removed by the
+      #   last call to {#deduplicate!}. Zero until deduplicate! runs.
+      attr_reader :suggestions, :max_size, :duplicates_removed
 
       # @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
+        @duplicates_removed = 0
         sort_and_limit!
       end
 
@@ -227,13 +230,34 @@ module Kotoshu
 
       private
 
-      # Sort suggestions by combined score and limit to max_size.
-      #
-      def sort_and_limit!
+      # Sort suggestions by combined score.
+      def sort!
         @suggestions.sort!
+      end
+
+      # Remove duplicate suggestions (same word, case-insensitive).
+      # Called explicitly so the dedup is visible as a named step,
+      # not buried inside sort_and_limit as a side effect (TODO 56 T5.1).
+      # Tracks the count of removed duplicates for diagnostics.
+      def deduplicate!
+        before = @suggestions.length
         @suggestions.uniq! { |s| s.word.downcase }
+        @duplicates_removed = before - @suggestions.length
+      end
+
+      # Truncate to max_size.
+      def limit!
         @suggestions = @suggestions.first(@max_size)
       end
+
+      # Sort, deduplicate, then limit. The canonical pipeline called
+      # after every mutation (add, concat, merge!). Each step is a
+      # named method so callers can reason about the order.
+      def sort_and_limit!
+        sort!
+        deduplicate!
+        limit!
+      end
     end
   end
 end

data/lib/kotoshu/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kotoshu
-  VERSION = '0.5.1'
+  VERSION = '0.6.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kotoshu
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-03 00:00:00.000000000 Z
+date: 2026-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -87,6 +87,7 @@ files:
 - lib/kotoshu.rb
 - lib/kotoshu/algorithms.rb
 - lib/kotoshu/algorithms/capitalization.rb
+- lib/kotoshu/algorithms/edit_distance.rb
 - lib/kotoshu/algorithms/lookup.rb
 - lib/kotoshu/algorithms/ngram_suggest.rb
 - lib/kotoshu/algorithms/permutations.rb
@@ -187,7 +188,10 @@ files:
 - lib/kotoshu/grammar/pattern_matchers/double_negative_matcher.rb
 - lib/kotoshu/grammar/pattern_matchers/phrase_matcher.rb
 - lib/kotoshu/grammar/pattern_matchers/possessive_context_matcher.rb
+- lib/kotoshu/grammar/pattern_matchers/possessive_contraction_matcher.rb
+- lib/kotoshu/grammar/pattern_matchers/sentence_start_matcher.rb
 - lib/kotoshu/grammar/pattern_matchers/vowel_sound_matcher.rb
+- lib/kotoshu/grammar/pattern_matchers/word_list_matcher.rb
 - lib/kotoshu/grammar/rule.rb
 - lib/kotoshu/grammar/rule_engine.rb
 - lib/kotoshu/grammar/rule_loader.rb