kotoshu 0.3.0

data/lib/kotoshu/spellchecker.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+require_relative "configuration"
+require_relative "suggestions/generator"
+require_relative "core/models/result/word_result"
+require_relative "core/models/result/document_result"
+
+module Kotoshu
+  # Main spellchecker class.
+  #
+  # This is the primary facade for spell checking operations,
+  # providing methods to check words, text, and files.
+  #
+  # @example Creating a spellchecker with a dictionary
+  #   dict = Kotoshu::Dictionary::UnixWords.new("/usr/share/dict/words", language_code: "en-US")
+  #   spellchecker = Spellchecker.new(dictionary: dict)
+  #   spellchecker.correct?("hello")  # => true
+  #
+  # @example Using configuration
+  #   spellchecker = Spellchecker.new(
+  #     dictionary_path: "/usr/share/dict/words",
+  #     language: "en-US"
+  #   )
+  class Spellchecker
+    # @return [Suggestions::Generator] The suggestion generator
+    attr_reader :generator
+
+    # @return [Configuration] The configuration
+    attr_reader :config
+
+    # @return [ResourceBundle, nil] The resource bundle if provided
+    attr_reader :resource_bundle
+
+    # Create a new spellchecker.
+    #
+    # @param dictionary [Dictionary::Base, nil] The dictionary (optional)
+    # @param config [Configuration, Hash] Configuration or settings
+    # @param resource_bundle [ResourceBundle, nil] Pre-resolved resource bundle
+    # @param kwargs [Hash] Additional configuration options
+    #
+    # @example With dictionary
+    #   spellchecker = Spellchecker.new(dictionary: dict)
+    #
+    # @example With resource bundle (0.2+)
+    #   bundle = Kotoshu::ResourceManager.resolve(language: "en")
+    #   spellchecker = Spellchecker.new(resource_bundle: bundle)
+    #   spellchecker.correct?("hello")  # => true
+    #
+    # @example With configuration hash
+    #   spellchecker = Spellchecker.new(
+    #     dictionary_path: "/usr/share/dict/words",
+    #     language: "en-US"
+    #   )
+    #
+    # @example With Configuration object
+    #   config = Configuration.new(dictionary_path: "words.txt")
+    #   spellchecker = Spellchecker.new(config: config)
+    def initialize(dictionary: nil, config: nil, resource_bundle: nil, **kwargs)
+      @resource_bundle = resource_bundle
+
+      if resource_bundle
+        dictionary ||= resource_bundle.dictionary
+        kwargs[:language] = resource_bundle.language unless kwargs.key?(:language)
+      end
+
+      if config.is_a?(Configuration)
+        @config = config
+      else
+        settings = kwargs.dup
+        settings[:dictionary_path] = dictionary.path if dictionary.respond_to?(:path)
+        @config = Configuration.new(settings)
+      end
+
+      @config.dictionary = dictionary if dictionary
+
+      dict = @config.dictionary
+      max_suggestions = @config.max_suggestions
+
+      @generator = Suggestions::Generator.new(
+        dict,
+        max_suggestions: max_suggestions,
+        algorithms: @config.suggestion_algorithms
+      )
+    end
+
+    # Check if a word is spelled correctly.
+    #
+    # @param word [String] The word to check
+    # @return [Boolean] True if the word is correct
+    #
+    # @example
+    #   spellchecker.correct?("hello")  # => true
+    #   spellchecker.correct?("helo")   # => false
+    def correct?(word)
+      return false if word.nil? || word.empty?
+
+      @generator.correct?(word)
+    end
+
+    # Check if a word is misspelled.
+    #
+    # @param word [String] The word to check
+    # @return [Boolean] True if the word is misspelled
+    def incorrect?(word)
+      !correct?(word)
+    end
+
+    # Get spelling suggestions for a word.
+    #
+    # @param word [String] The misspelled word
+    # @param max_suggestions [Integer] Maximum suggestions (optional)
+    # @return [Suggestions::SuggestionSet] Generated suggestions
+    #
+    # @example
+    #   suggestions = spellchecker.suggest("helo")
+    #   suggestions.to_words  # => ["hello", "help", "held", ...]
+    def suggest(word, max_suggestions: nil)
+      return Suggestions::SuggestionSet.empty if word.nil? || word.empty?
+
+      @generator.generate(word, max_suggestions: max_suggestions)
+    end
+
+    # Check a word and return a result object.
+    #
+    # @param word [String] The word to check
+    # @return [Models::Result::WordResult] The check result
+    #
+    # @example
+    #   result = spellchecker.check_word("hello")
+    #   result.correct?  # => true
+    #
+    # @example With misspelled word
+    #   result = spellchecker.check_word("helo")
+    #   result.correct?         # => false
+    #   result.suggestions      # => SuggestionSet with suggestions
+    def check_word(word)
+      if word.nil? || word.empty?
+        return Models::Result::WordResult.new("", correct: false,
+                                                  suggestions: Suggestions::SuggestionSet.empty)
+      end
+
+      if correct?(word)
+        Models::Result::WordResult.correct(word)
+      else
+        suggestions = suggest(word)
+        Models::Result::WordResult.incorrect(word, suggestions: suggestions)
+      end
+    end
+
+    # Check text for spelling errors.
+    #
+    # @param text [String] The text to check
+    # @return [Models::Result::DocumentResult] The check result
+    #
+    # @example
+    #   result = spellchecker.check("Hello wrold")
+    #   result.success?    # => false
+    #   result.errors.map(&:word)  # => ["wrold"]
+    def check(text)
+      return Models::Result::DocumentResult.success if text.nil? || text.empty?
+
+      words = tokenize(text)
+      errors = []
+      position = 0
+
+      words.each do |word_data|
+        word, pos = word_data
+        result = check_word(word)
+
+        if result.incorrect?
+          errors << Models::Result::WordResult.new(
+            word,
+            correct: false,
+            suggestions: result.suggestions,
+            position: pos
+          )
+        end
+
+        position = pos
+      end
+
+      Models::Result::DocumentResult.new(
+        file: nil,
+        errors: errors,
+        word_count: words.size
+      )
+    end
+
+    # Check a file for spelling errors.
+    #
+    # @param path [String] The file path
+    # @return [Models::Result::DocumentResult] The check result
+    #
+    # @example
+    #   result = spellchecker.check_file("README.md")
+    #   result.to_s  # => "File 'README.md': 3 spelling error(s) found"
+    def check_file(path)
+      raise DictionaryNotFoundError, path unless File.exist?(path)
+
+      text = File.read(path, encoding: @config.encoding)
+      result = check(text)
+
+      # Create a new result with the file path
+      Models::Result::DocumentResult.new(
+        file: path,
+        errors: result.errors,
+        word_count: result.word_count
+      )
+    end
+
+    # Check a directory for spelling errors.
+    #
+    # @param path [String] The directory path
+    # @param pattern [String] File pattern to match (default: "*.txt")
+    # @return [Array<Models::Result::DocumentResult>] Results for each file
+    #
+    # @example
+    #   results = spellchecker.check_directory("docs/")
+    #   results.select(&:failed?).map(&:file)
+    def check_directory(path, pattern: "*.txt")
+      raise DictionaryNotFoundError, path unless File.exist?(path) && File.directory?(path)
+
+      files = Dir.glob(File.join(path, pattern))
+      files.map { |file| check_file(file) }
+    end
+
+    # Tokenize text into words.
+    #
+    # @param text [String] The text to tokenize
+    # @return [Array<Array>] Array of [word, position] pairs
+    #
+    # @example
+    #   spellchecker.tokenize("Hello world!")
+    #   # => [["Hello", 0], ["world", 6]]
+    def tokenize(text)
+      return [] if text.nil? || text.empty?
+
+      words = []
+      position = 0
+      word_buffer = String.new
+      word_start = 0
+
+      text.each_char.with_index do |char, i|
+        if word_char?(char)
+          word_buffer << char
+          word_start = i if word_buffer.length == 1
+          position = i
+        elsif !word_buffer.empty?
+          words << [word_buffer.dup.freeze, word_start]
+          word_buffer.clear
+        end
+      end
+
+      # Don't forget the last word
+      words << [word_buffer.dup.freeze, word_start] unless word_buffer.empty?
+
+      words
+    end
+
+    # Get the dictionary being used.
+    #
+    # @return [Dictionary::Base] The dictionary
+    def dictionary
+      @generator.dictionary
+    end
+
+    # Reload the dictionary.
+    #
+    # @return [self] Self for chaining
+    def reload_dictionary
+      @config.reset_dictionary
+
+      dict = @config.dictionary
+      @generator = Suggestions::Generator.new(
+        dict,
+        max_suggestions: @config.max_suggestions,
+        algorithms: @config.suggestion_algorithms
+      )
+
+      self
+    end
+
+    private
+
+    # Check if a character is part of a word.
+    #
+    # @param char [String] The character
+    # @return [Boolean] True if it's a word character
+    def word_char?(char)
+      case char
+      when "a".."z", "A".."Z", "'"
+        true
+      else
+        false
+      end
+    end
+  end
+end

data/lib/kotoshu/string_metrics.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  # String similarity metrics for spell checking.
+  #
+  # Ported from Spylls (Python) string_metrics.py
+  #
+  # These metrics are used for:
+  # - Computing word similarity
+  # - Ranking suggestions
+  # - N-gram based scoring
+  module StringMetrics
+    # Number of occurrences of the exactly same characters in exactly same position.
+    #
+    # @param s1 [String] First string
+    # @param s2 [String] Second string
+    # @return [Integer] Count of matching characters at same positions
+    #
+    # @example
+    #   Kotoshu::StringMetrics.commoncharacters("hello", "hallo")  # => 4 ('h', 'l', 'l', 'o' match)
+    def self.commoncharacters(s1, s2)
+      return 0 if s1.nil? || s2.nil?
+
+      # Zip strings and count matching character pairs
+      [s1.length, s2.length].min.times.count do |i|
+        s1[i] == s2[i]
+      end
+    end
+
+    # Size of the common start of two strings.
+    #
+    # @param s1 [String] First string
+    # @param s2 [String] Second string
+    # @return [Integer] Length of common prefix
+    #
+    # @example
+    #   Kotoshu::StringMetrics.leftcommonsubstring("foo", "bar")       # => 0
+    #   Kotoshu::StringMetrics.leftcommonsubstring("built", "build")   # => 4
+    #   Kotoshu::StringMetrics.leftcommonsubstring("cat", "cats")      # => 3
+    def self.leftcommonsubstring(s1, s2)
+      return 0 if s1.nil? || s2.nil?
+
+      # Find first position where characters differ
+      s1.chars.zip(s2.chars).each_with_index do |(c1, c2), i|
+        return i if c1 != c2
+      end
+
+      # All characters matched up to shorter string length
+      [s1.length, s2.length].min
+    end
+
+    # Calculate n-gram similarity between two strings.
+    #
+    # Calculates how many n-grams of s1 are contained in s2 (the more the number,
+    # the more words are similar).
+    #
+    # @param max_ngram_size [Integer] Maximum n-gram size to check
+    # @param s1 [String] String to compare
+    # @param s2 [String] String to compare
+    # @param weighted [Boolean] Subtract from result for ngrams NOT contained
+    # @param any_mismatch [Boolean] Add penalty for any string length difference
+    # @param longer_worse [Boolean] Add penalty when second string is longer
+    # @return [Integer] N-gram similarity score (higher is more similar)
+    #
+    # @example
+    #   Kotoshu::StringMetrics.ngram(4, "hello", "help")                 # => 6
+    #   Kotoshu::StringMetrics.ngram(4, "teachings", "teaching")       # => higher score
+    def self.ngram(max_ngram_size, s1, s2, weighted: false, any_mismatch: false, longer_worse: false)
+      l2 = s2.length
+      return 0 if l2.zero?
+
+      l1 = s1.length
+      nscore = 0
+
+      # For all sizes of ngram up to desired...
+      (1..max_ngram_size).each do |ngram_size|
+        ns = 0
+
+        # Check every position in the first string
+        (0..(l1 - ngram_size)).each do |pos|
+          ngram = s1[pos, ngram_size]
+
+          # If the ngram is present in ANY place in second string, increase score
+          if s2.include?(ngram)
+            ns += 1
+          elsif weighted
+            # For "weighted" ngrams, decrease score if ngram is not found
+            ns -= 1
+            # Decrease once more if it was the beginning or end of first string
+            ns -= 1 if pos.zero? || pos + ngram_size == l1
+          end
+        end
+
+        nscore += ns
+
+        # There is no need to check for 4-gram if there were only one 3-gram
+        break if ns < 2 && !weighted
+      end
+
+      # Calculate penalty based on settings
+      penalty = if longer_worse
+                  # Add penalty when second string is longer
+                  (l2 - l1) - 2
+                elsif any_mismatch
+                  # Add penalty for any string length difference
+                  (l2 - l1).abs - 2
+                else
+                  0
+                end
+
+      # Apply penalty if positive
+      penalty > 0 ? nscore - penalty : nscore
+    end
+
+    # Calculate LCS (Longest Common Subsequence) length.
+    #
+    # Classic dynamic programming algorithm. This is different from
+    # longest common substring - subsequence doesn't require contiguity.
+    #
+    # @param s1 [String] First string
+    # @param s2 [String] Second string
+    # @return [Integer] Length of longest common subsequence
+    #
+    # @example
+    #   Kotoshu::StringMetrics.lcslen("AGGTAB", "GXTXAYB")  # => 4 ("GTAB")
+    def self.lcslen(s1, s2)
+      return 0 if s1.nil? || s2.nil? || s1.empty? || s2.empty?
+
+      m = s1.length
+      n = s2.length
+
+      # Create DP table
+      # Using a 2D array for clarity, though we could optimize space
+      c = Array.new(m + 1) { Array.new(n + 1, 0) }
+
+      (0...m).each do |i|
+        (0...n).each do |j|
+          if s1[i] == s2[j]
+            # Characters match - extend diagonal
+            c[i + 1][j + 1] = c[i][j] + 1
+          elsif c[i][j + 1] >= c[i + 1][j]
+            # Take max from top or left
+            c[i + 1][j + 1] = c[i][j + 1]
+          else
+            c[i + 1][j + 1] = c[i + 1][j]
+          end
+        end
+      end
+
+      c[m][n]
+    end
+  end
+end

data/lib/kotoshu/suggestions/context.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  module Suggestions
+    # Context object passed to suggestion strategies.
+    # Encapsulates the state and parameters for suggestion generation.
+    class Context
+      attr_reader :word, :dictionary, :max_results, :options
+
+      def initialize(word:, dictionary:, max_results: 10, **options)
+        @word = word
+        @dictionary = dictionary
+        @max_results = max_results
+        @options = options
+      end
+
+      # Get an option value.
+      #
+      # @param key [Symbol] The option key
+      # @param default [Object] Default value if not found
+      # @return [Object] The option value
+      def option(key, default = nil)
+        @options.fetch(key, default)
+      end
+
+      # Check if an option is present.
+      #
+      # @param key [Symbol] The option key
+      # @return [Boolean] True if option exists
+      def has_option?(key)
+        @options.key?(key)
+      end
+
+      # Convert context to hash.
+      #
+      # @return [Hash] Context as hash
+      def to_h
+        {
+          word: @word,
+          dictionary: @dictionary,
+          max_results: @max_results,
+          options: @options
+        }
+      end
+
+      # Inspect the context.
+      #
+      # @return [String] Inspection string
+      def inspect
+        "Context(word: '#{@word}', max_results: #{@max_results})"
+      end
+      alias to_s inspect
+    end
+  end
+end

data/lib/kotoshu/suggestions/generator.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require_relative "context"
+require_relative "suggestion_set"
+require_relative "strategies/base_strategy"
+require_relative "strategies/composite_strategy"
+require_relative "strategies/edit_distance_strategy"
+require_relative "strategies/phonetic_strategy"
+require_relative "strategies/keyboard_proximity_strategy"
+require_relative "strategies/ngram_strategy"
+require_relative "strategies/semantic_strategy"
+
+module Kotoshu
+  module Suggestions
+    # Generator for spelling suggestions.
+    #
+    # This class orchestrates multiple suggestion algorithms to generate
+    # comprehensive spelling suggestions.
+    #
+    # @example Using default algorithms
+    #   generator = Generator.new(dictionary)
+    #   suggestions = generator.generate("helo")
+    #
+    # @example Using custom algorithms
+    #   custom_strategy = MyStrategy.new
+    #   generator = Generator.new(dictionary, algorithms: [custom_strategy])
+    class Generator
+      # Default suggestion algorithms.
+      DEFAULT_ALGORITHMS = [
+        Strategies::EditDistanceStrategy,
+        Strategies::PhoneticStrategy,
+        Strategies::KeyboardProximityStrategy,
+        Strategies::NgramStrategy
+      ].freeze
+
+      # @return [Object] The dictionary (any dictionary backend)
+      attr_reader :dictionary
+
+      # @return [Strategies::CompositeStrategy] The composite strategy
+      attr_reader :strategy
+
+      # Create a new suggestion generator.
+      #
+      # @param dictionary [Object] The dictionary instance
+      # @param algorithms [Array<Class, Strategies::BaseStrategy>, nil] Algorithm classes or instances
+      # @param max_suggestions [Integer] Maximum suggestions to return
+      # @param config [Hash] Configuration options
+      def initialize(dictionary, algorithms: nil, max_suggestions: 10, **config)
+        @dictionary = dictionary
+        @max_suggestions = max_suggestions
+        # Use default algorithms if none provided
+        algorithms_to_use = algorithms || DEFAULT_ALGORITHMS
+        @strategy = build_strategy(algorithms_to_use, config)
+      end
+
+      # Generate suggestions for a word.
+      #
+      # @param word [String] The misspelled word
+      # @param max_suggestions [Integer] Maximum suggestions (optional)
+      # @return [SuggestionSet] Generated suggestions
+      #
+      # @example
+      #   generator.generate("helo")
+      #   # => #<Kotoshu::Suggestions::SuggestionSet ...>
+      def generate(word, max_suggestions: nil)
+        return SuggestionSet.empty if word.nil? || word.empty?
+
+        context = Context.new(
+          word: word,
+          dictionary: @dictionary,
+          max_results: max_suggestions || @max_suggestions
+        )
+
+        @strategy.generate(context)
+      end
+
+      # Alias for generate for API consistency.
+      #
+      # @param word [String] The misspelled word
+      # @param max_suggestions [Integer] Maximum suggestions (optional)
+      # @return [SuggestionSet] Generated suggestions
+      #
+      # @example
+      #   generator.suggest("helo")
+      #   # => #<Kotoshu::Suggestions::SuggestionSet ...>
+      alias suggest generate
+
+      # Check if a word is correct.
+      #
+      # @param word [String] The word to check
+      # @return [Boolean] True if the word is in the dictionary
+      #
+      # @example
+      #   generator.correct?("hello")  # => true
+      #   generator.correct?("helo")   # => false
+      def correct?(word)
+        return false if word.nil? || word.empty?
+
+        dictionary_lookup(word)
+      end
+
+      # Check if a word is incorrect.
+      #
+      # @param word [String] The word to check
+      # @return [Boolean] True if the word is not in the dictionary
+      def incorrect?(word)
+        !correct?(word)
+      end
+      alias misspelled? incorrect?
+
+      # Get the default algorithms.
+      #
+      # @return [Array<Class>] Default algorithm classes
+      #
+      # @example
+      #   Generator.default_algorithms
+      def self.default_algorithms
+        DEFAULT_ALGORITHMS.dup
+      end
+
+      # Set the default algorithms.
+      #
+      # @param algorithms [Array<Class>] Algorithm classes
+      #
+      # @example
+      #   Generator.default_algorithms = [MyCustomStrategy]
+      class << self
+        attr_writer :default_algorithms
+      end
+
+      private
+
+      # Build the composite strategy from algorithm classes.
+      #
+      # @param algorithms [Array<Class, Strategies::BaseStrategy>] Algorithm classes or instances
+      # @param config [Hash] Configuration options
+      # @return [Strategies::CompositeStrategy] The composite strategy
+      def build_strategy(algorithms, config)
+        composite = Strategies::CompositeStrategy.new(name: :default, **config)
+
+        algorithms.each do |alg|
+          strategy = if alg.is_a?(Strategies::BaseStrategy)
+                       alg
+                     elsif alg.is_a?(Class) && alg < Strategies::BaseStrategy
+                       alg.new(**config)
+                     else
+                       raise ArgumentError, "Invalid algorithm: #{alg.inspect}"
+                     end
+
+          composite.add(strategy)
+        end
+
+        composite
+      end
+
+      # Look up a word in the dictionary.
+      #
+      # @param word [String] The word
+      # @return [Boolean] True if found
+      def dictionary_lookup(word)
+        if @dictionary.respond_to?(:lookup)
+          @dictionary.lookup(word)
+        elsif @dictionary.respond_to?(:include?)
+          @dictionary.include?(word)
+        elsif @dictionary.is_a?(Hash)
+          @dictionary.key?(word)
+        elsif @dictionary.is_a?(Array)
+          @dictionary.include?(word)
+        else
+          false
+        end
+      end
+    end
+  end
+end