kotoshu 0.3.0

data/lib/kotoshu/fluent_checker.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  class Spellchecker
+    # Fluent checker for chainable configuration.
+    #
+    # Provides a convenient API for spell checking with method chaining.
+    #
+    # @example Basic usage
+    #   result = Kotoshu.fluent.check("Hello wrold")
+    #
+    # @example With options
+    #   Kotoshu.fluent
+    #     .ignore_words(/https?:\/\/\S+/)
+    #     .max_suggestions(5)
+    #     .check("Hello wrold")
+    class FluentChecker
+      # @return [Spellchecker] The underlying spellchecker
+      attr_reader :spellchecker
+
+      # @return [Hash] Configuration options
+      attr_reader :options
+
+      # Create a new fluent checker.
+      #
+      # @param spellchecker [Spellchecker] The underlying spellchecker
+      # @param options [Hash] Configuration options
+      def initialize(spellchecker:, options: {})
+        @spellchecker = spellchecker
+        @options = options
+        @progress_callback = nil
+        @error_callback = nil
+      end
+
+      # Check text for spelling errors.
+      #
+      # @param text [String] Text to check
+      # @return [Models::Result::DocumentResult] Check result
+      def check(text)
+        @spellchecker.check(text)
+      end
+
+      # Ignore words matching pattern.
+      #
+      # @param pattern [Regexp] Pattern to ignore
+      # @return [FluentChecker] Self for chaining
+      #
+      # @example
+      #   fluent.ignore_words(/https?:\/\/\S+/)
+      def ignore_words(pattern)
+        @options[:ignore_patterns] ||= []
+        @options[:ignore_patterns] << pattern
+        self
+      end
+
+      # Set maximum suggestions.
+      #
+      # @param max [Integer] Maximum suggestions
+      # @return [FluentChecker] Self for chaining
+      def max_suggestions(max)
+        @options[:max_suggestions] = max
+        self
+      end
+
+      # Set progress callback.
+      #
+      # @param block [Proc] Callback proc
+      # @return [FluentChecker] Self for chaining
+      def on_progress(&block)
+        @progress_callback = block
+        self
+      end
+
+      # Set error callback.
+      #
+      # @param block [Proc] Callback proc
+      # @return [FluentChecker] Self for chaining
+      def on_error(&block)
+        @error_callback = block
+        self
+      end
+
+      # Get the result.
+      #
+      # @return [Models::Result::ResultDocumentResult] Check result
+      def result
+        check(@text)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  module Grammar
+    module PatternMatchers
+      # Base class for pattern matchers.
+      #
+      # Pattern matchers check token sequences against specific patterns
+      # defined in YAML configuration.
+      class BaseMatcher
+        def initialize(pattern, exceptions = {})
+          @pattern = pattern
+          @exceptions = exceptions
+        end
+
+        # Match tokens against the pattern.
+        #
+        # @param tokens [Array<Hash>] Array of token hashes
+        # @param rule [Rule] The rule being checked
+        # @return [Array<Hash>] Array of error hashes
+        def match(tokens, rule)
+          []
+        end
+
+        protected
+
+        # Extract target tokens from context specification.
+        #
+        # @param tokens [Array<Hash>] Array of token hashes
+        # @param context_spec [Hash] Context specification from pattern
+        # @return [Array<Hash>] Array of matching tokens with their indices
+        def extract_tokens_from_context(tokens, context_spec)
+          result = []
+          context_spec.each do |spec|
+            if spec['target_token']
+              tokens.each_with_index do |token, idx|
+                if token[:token]&.downcase == spec['target_token']
+                  result << { token: token, index: idx }
+                end
+              end
+            end
+          end
+          result
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative 'base_matcher'
+
+module Kotoshu
+  module Grammar
+    module PatternMatchers
+      # Matcher for double negative rules.
+      #
+      # This matcher detects when multiple negative words appear
+      # within a certain distance.
+      class DoubleNegativeMatcher < BaseMatcher
+        # Match tokens against the double negative pattern.
+        #
+        # @param tokens [Array<Hash>] Array of token hashes
+        # @param rule [Rule] The rule being checked
+        # @return [Array<Hash>] Array of error hashes
+        def match(tokens, rule)
+          errors = []
+          exceptions = rule.exceptions || {}
+          exception_phrases = exceptions['phrases'] || []
+
+          conditions = @pattern['conditions'] || []
+          distance_condition = conditions.find { |c| c['type'] == 'distance_check' }
+          max_distance = distance_condition&.dig('max_distance') || 15
+
+          negative_indices = []
+          tokens.each_with_index do |token, idx|
+            word = token[:token]&.downcase
+            next unless is_negative?(word)
+
+            # Skip "not only... but also" pattern
+            next if in_exception_phrase?(idx, tokens, exception_phrases)
+
+            negative_indices << idx
+          end
+
+          negative_indices.each_cons(2) do |idx1, idx2|
+            pos1 = tokens[idx1][:position]
+            pos2 = tokens[idx2][:position]
+            distance = pos2 - pos1
+            next if distance > max_distance
+
+            error = build_error(tokens, idx1, idx2, rule)
+            errors << error if error
+          end
+          errors
+        end
+
+        private
+
+        # Check if a word is a negative.
+        #
+        # @param word [String] The word to check
+        # @return [Boolean] True if the word is a negative
+        def is_negative?(word)
+          return false if word.nil? || word.empty?
+
+          negatives = %w[not no neither nobody never nothing nowhere hardly barely scarcely]
+          return true if negatives.include?(word)
+          return true if word.end_with?("n't")
+
+          false
+        end
+
+        # Check if an index is part of an exception phrase.
+        #
+        # @param idx [Integer] The token index
+        # @param tokens [Array<Hash>] Array of token hashes
+        # @param exception_phrases [Array<String>] Exception phrases
+        # @return [Boolean] True if in exception phrase
+        def in_exception_phrase?(idx, tokens, exception_phrases)
+          return false if exception_phrases.empty?
+
+          # Check "not only... but also" pattern
+          if idx > 0 && tokens[idx - 1][:token] == 'not' && tokens[idx + 1]&.dig(:token) == 'only'
+            return true
+          end
+
+          false
+        end
+
+        # Build an error hash.
+        #
+        # @param tokens [Array<Hash>] Array of token hashes
+        # @param idx1 [Integer] First negative index
+        # @param idx2 [Integer] Second negative index
+        # @param rule [Rule] The rule being checked
+        # @return [Hash] Error hash
+        def build_error(tokens, idx1, idx2, rule)
+          words = tokens[idx1..idx2].map { |t| t[:token] }.join(' ')
+
+          {
+            rule_id: rule.id,
+            position: tokens[idx1][:position],
+            message: rule.message,
+            suggestion: rule.suggestion,
+            context: words,
+            suggestions: rule.suggestion ? [rule.suggestion] : []
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative 'base_matcher'
+
+module Kotoshu
+  module Grammar
+    module PatternMatchers
+      # Matcher for there/their/they're confusion rules.
+      #
+      # This matcher detects when "there" is used where "their"
+      # (possessive) is intended.
+      class PossessiveContextMatcher < BaseMatcher
+        # Match tokens against the there/their pattern.
+        #
+        # @param tokens [Array<Hash>] Array of token hashes
+        # @param rule [Rule] The rule being checked
+        # @return [Array<Hash>] Array of error hashes
+        def match(tokens, rule)
+          errors = []
+          exceptions = rule.exceptions || {}
+
+          location_indicators = exceptions['location_indicators'] || {}
+          location_verbs = location_indicators['verbs'] || []
+          possessive_nouns = location_indicators['possessive_nouns'] || []
+
+          tokens.each_with_index do |token, idx|
+            word = token[:token]&.downcase
+            next unless word == 'there'
+
+            next_token = tokens[idx + 1]
+            next unless next_token
+
+            next_word = next_token[:token]&.downcase
+
+            # Skip if followed by verb (location/existence context)
+            next if location_verbs.include?(next_word)
+
+            uses_their = false
+
+            # Check POS tags first
+            next_pos = next_token[:pos_tag]
+            if next_pos && ['NOUN', 'NOUN_PROPER', 'ADJ'].include?(next_pos)
+              uses_their = true
+            # Fallback to word list
+            elsif possessive_nouns.include?(next_word)
+              uses_their = true
+            end
+
+            if uses_their
+              errors << build_error(token, next_token, rule)
+            end
+          end
+          errors
+        end
+
+        private
+
+        # Build an error hash.
+        #
+        # @param token [Hash] The token with "there"
+        # @param next_token [Hash] The next token
+        # @param rule [Rule] The rule being checked
+        # @return [Hash] Error hash
+        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/vowel_sound_matcher.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative 'base_matcher'
+
+module Kotoshu
+  module Grammar
+    module PatternMatchers
+      # Matcher for a/an article usage rules.
+      #
+      # This matcher checks if "a" or "an" is used correctly before
+      # vowel and consonant sounds.
+      class VowelSoundMatcher < BaseMatcher
+        VOWEL_SOUNDS = %w[a e i o u].freeze
+
+        # Match tokens against the a/an pattern.
+        #
+        # @param tokens [Array<Hash>] Array of token hashes
+        # @param rule [Rule] The rule being checked
+        # @return [Array<Hash>] Array of error hashes
+        def match(tokens, rule)
+          errors = []
+          tokens.each_cons(2) do |prev_token, current_token|
+            prev_word = prev_token[:token]&.downcase
+            next unless %w[a an].include?(prev_word)
+            next unless prev_token[:pos_tag] == 'DET' || prev_token[:pos_tag].nil?
+
+            next_word = current_token[:token]
+            next if next_word.nil? || next_word.empty?
+
+            expected = article_for(next_word, rule)
+            if prev_word != expected
+              errors << build_error(prev_token, current_token, expected, rule)
+            end
+          end
+          errors
+        end
+
+        private
+
+        # Determine the correct article for a word.
+        #
+        # @param word [String] The word to check
+        # @param rule [Rule] The rule with exceptions
+        # @return [String] "a" or "an"
+        def article_for(word, rule)
+          word_downcase = word.downcase
+          exceptions = rule.exceptions || {}
+
+          consonant_exceptions = exceptions['consonant_sound_exceptions'] || []
+          return 'a' if consonant_exceptions.include?(word_downcase)
+
+          silent_exceptions = exceptions['silent_consonant_exceptions'] || []
+          return 'an' if silent_exceptions.include?(word_downcase)
+
+          first_char = word_downcase[0]
+          VOWEL_SOUNDS.include?(first_char) ? 'an' : 'a'
+        end
+
+        # Build an error hash.
+        #
+        # @param prev_token [Hash] The previous token (article)
+        # @param current_token [Hash] The current token (word)
+        # @param expected [String] The expected article
+        # @param rule [Rule] The rule being checked
+        # @return [Hash] Error hash
+        def build_error(prev_token, current_token, expected, rule)
+          prev_word = prev_token[:token]
+          next_word = current_token[:token]
+          message = rule.message.gsub('{expected}', expected).gsub('{word}', next_word)
+
+          {
+            rule_id: rule.id,
+            position: prev_token[:position],
+            message: message,
+            suggestion: expected,
+            context: "#{prev_word} #{next_word}",
+            suggestions: [expected]
+          }
+        end
+      end
+    end
+  end
+end

data/lib/kotoshu/grammar/rule.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  module Grammar
+    # Base class for grammar rules.
+    #
+    # All grammar rules inherit from this class and implement
+    # the #check method to validate tokens.
+    class Rule
+      attr_reader :id, :name, :category, :severity, :description,
+                  :exceptions, :message, :suggestion
+
+      def initialize(id:, name:, category:, severity:, description:,
+                     patterns:, exceptions: {}, message:, suggestion:)
+        @id = id
+        @name = name
+        @category = category
+        @severity = severity
+        @description = description
+        @patterns = patterns
+        @exceptions = exceptions
+        @message = message
+        @suggestion = suggestion
+      end
+
+      # Factory method to create Rule from YAML configuration.
+      #
+      # @param config [Hash] YAML configuration hash
+      # @return [Rule] A new rule instance
+      def self.from_yaml(config)
+        new(
+          id: config['id'],
+          name: config['name'],
+          category: config['category'],
+          severity: config['severity'],
+          description: config['description'],
+          patterns: config['patterns'],
+          exceptions: config['exceptions'] || {},
+          message: config['message'],
+          suggestion: config['suggestion']
+        )
+      end
+
+      # Check tokens against this rule.
+      #
+      # @param tokens [Array<Hash>] Array of token hashes
+      # @return [Array<Hash>] Array of error hashes
+      def check(tokens)
+        errors = []
+        @patterns.each do |pattern|
+          pattern_errors = check_pattern(tokens, pattern)
+          errors.concat(pattern_errors)
+        end
+        errors
+      end
+
+      private
+
+      # Check a single pattern against tokens.
+      #
+      # @param tokens [Array<Hash>] Array of token hashes
+      # @param pattern [Hash] Pattern configuration hash
+      # @return [Array<Hash>] Array of error hashes
+      def check_pattern(tokens, pattern)
+        matcher = create_matcher(pattern)
+        matcher.match(tokens, self)
+      end
+
+      # Create appropriate pattern matcher based on pattern type.
+      #
+      # @param pattern [Hash] Pattern configuration hash
+      # @return [PatternMatchers::BaseMatcher] A pattern matcher instance
+      def create_matcher(pattern)
+        conditions = pattern['conditions'] || []
+        return PatternMatchers::BaseMatcher.new(pattern) if conditions.empty?
+
+        condition_types = conditions.map { |c| c['type'] }
+
+        if condition_types.include?('vowel_check')
+          require_relative 'pattern_matchers/vowel_sound_matcher'
+          PatternMatchers::VowelSoundMatcher.new(pattern, exceptions)
+        elsif condition_types.include?('context_check')
+          require_relative 'pattern_matchers/possessive_context_matcher'
+          PatternMatchers::PossessiveContextMatcher.new(pattern, exceptions)
+        elsif condition_types.include?('distance_check')
+          require_relative 'pattern_matchers/double_negative_matcher'
+          PatternMatchers::DoubleNegativeMatcher.new(pattern, exceptions)
+        else
+          require_relative 'pattern_matchers/base_matcher'
+          PatternMatchers::BaseMatcher.new(pattern)
+        end
+      end
+    end
+  end
+end

data/lib/kotoshu/grammar/rule_engine.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative 'rule_loader'
+require_relative '../configuration'
+
+module Kotoshu
+  module Grammar
+    # Engine for loading and executing grammar rules from YAML configuration.
+    #
+    # This implements configuration-driven design where all linguistic data
+    # (rules, patterns, exceptions) is stored in YAML files, not hardcoded.
+    #
+    # @example Loading rules for English
+    #   engine = RuleEngine.new(language: 'en')
+    #   errors = engine.check(tokens)
+    #
+    class RuleEngine
+      attr_reader :language, :rules
+
+      # Create a new rule engine for a language.
+      #
+      # @param language [String] Language code (e.g., 'en', 'de', 'fr')
+      # @param rules_path [String, nil] Optional custom path to grammar rules
+      # @param dictionaries_path [String, nil] Optional custom path to dictionaries directory
+      def initialize(language:, rules_path: nil, dictionaries_path: nil)
+        @language = language
+        @rules_path = rules_path || default_rules_path(dictionaries_path)
+        @loader = RuleLoader.new(@rules_path)
+        @rules = @loader.load_rules
+      end
+
+      # Check tokens against all loaded rules.
+      #
+      # @param tokens [Array<Hash>] Array of token hashes with :token, :pos_tag, :position keys
+      # @return [Array<Hash>] Array of error hashes
+      def check(tokens)
+        errors = []
+        @rules.each do |rule|
+          rule_errors = rule.check(tokens)
+          errors.concat(rule_errors)
+        end
+        errors
+      end
+
+      # Get list of rule IDs.
+      #
+      # @return [Array<String>] Array of rule IDs
+      def rule_names
+        @rules.map(&:id)
+      end
+
+      # Get a specific rule by ID.
+      #
+      # @param id [String] Rule ID
+      # @return [Rule, nil] The rule if found, nil otherwise
+      def get_rule(id)
+        @rules.find { |r| r.id == id }
+      end
+
+      # Check if a rule exists.
+      #
+      # @param id [String] Rule ID
+      # @return [Boolean] True if rule exists
+      def rule_exists?(id)
+        @rules.any? { |r| r.id == id }
+      end
+
+      private
+
+      # Get default path to grammar rules for a language.
+      #
+      # @param dictionaries_path [String, nil] Optional custom dictionaries path
+      # @return [String] Path to grammar rules directory
+      def default_rules_path(dictionaries_path = nil)
+        base_path = dictionaries_path || default_dictionaries_path
+        File.join(base_path, @language, 'grammar')
+      end
+
+      # Get default dictionaries path.
+      #
+      # Checks in order:
+      # 1. Environment variable KOTOSHU_DICTIONARIES_PATH
+      # 2. Configuration.dictionaries_path
+      # 3. Default: dictionaries/ adjacent to gem root
+      #
+      # @return [String] Path to dictionaries directory
+      def default_dictionaries_path
+        # Check for environment variable first
+        if ENV['KOTOSHU_DICTIONARIES_PATH']
+          return ENV['KOTOSHU_DICTIONARIES_PATH']
+        end
+
+        # Check for configuration setting
+        config = Configuration.instance
+        if config.respond_to?(:dictionaries_path) && config.dictionaries_path
+          return config.dictionaries_path
+        end
+
+        # Default: dictionaries/ directory at project root
+        # The kotoshu gem is at src/kotoshu/kotoshu/, so dictionaries is at src/kotoshu/dictionaries
+        # From lib/kotoshu/grammar/:
+        #   - grammar/ -> kotoshu/lib/kotoshu/ (1)
+        #   - kotoshu/lib/kotoshu/ -> lib/kotoshu/ (2)
+        #   - lib/kotoshu/ -> kotoshu/ (3)
+        #   - kotoshu/ -> src/kotoshu/ (4)
+        #   - Then add dictionaries/
+        __dir__ + '/../../../../dictionaries'
+      end
+    end
+  end
+end

data/lib/kotoshu/grammar/rule_loader.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require_relative 'rule'
+
+module Kotoshu
+  module Grammar
+    # Loads grammar rules from YAML configuration files.
+    #
+    # This class reads rule definitions from YAML files in the
+    # dictionaries/{language}/grammar/ directory.
+    class RuleLoader
+      def initialize(rules_path)
+        @rules_path = rules_path
+      end
+
+      # Load all rules from the rules.yaml file.
+      #
+      # @return [Array<Rule>] Array of rule instances
+      def load_rules
+        rules_file = File.join(@rules_path, 'rules.yaml')
+        return [] unless File.exist?(rules_file)
+
+        config = YAML.load_file(rules_file)
+        return [] unless config && config['rules']
+
+        config['rules'].map { |rule_config| Rule.from_yaml(rule_config) }
+      end
+    end
+  end
+end

data/lib/kotoshu/grammar.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'grammar/rule_engine'
+require_relative 'grammar/rule_loader'
+require_relative 'grammar/rule'
+require_relative 'grammar/pattern_matchers/base_matcher'
+require_relative 'grammar/pattern_matchers/vowel_sound_matcher'
+require_relative 'grammar/pattern_matchers/possessive_context_matcher'
+require_relative 'grammar/pattern_matchers/double_negative_matcher'
+
+module Kotoshu
+  # Grammar rules infrastructure for Kotoshu.
+  #
+  # This module provides configuration-driven grammar checking
+  # where all linguistic data is stored in YAML files.
+  module Grammar
+  end
+end