kotoshu 0.3.0

data/lib/kotoshu/data_structures/bloom_filter.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  module DataStructures
+    # Bloom filter - probabilistic data structure for fast membership testing.
+    #
+    # A Bloom filter is a space-efficient probabilistic data structure that
+    # is used to test whether an element is a member of a set. False positive
+    # matches are possible, but false negatives are not.
+    #
+    # @example Basic usage
+    #   filter = BloomFilter.new
+    #   filter.add("hello")
+    #   filter.include?("hello")  # => true (definitely in set)
+    #   filter.include?("world")  # => false (probably not in set)
+    #
+    # @see https://en.wikipedia.org/wiki/Bloom_filter Bloom filter Wikipedia
+    class BloomFilter
+      # Default false positive rate (1%)
+      DEFAULT_FALSE_POSITIVE_RATE = 0.01
+
+      # Default expected number of elements
+      DEFAULT_EXPECTED_SIZE = 10_000
+
+      # @return [Integer] Size of the bit array
+      attr_reader :size
+
+      # @return [Integer] Number of hash functions
+      attr_reader :hash_count
+
+      # @return [Integer] Number of items added
+      attr_reader :item_count
+
+      # Create a new Bloom filter.
+      #
+      # @param expected_size [Integer] Expected number of elements (default: 10_000)
+      # @param false_positive_rate [Float] Desired false positive rate (default: 0.01)
+      # @param case_sensitive [Boolean] Whether lookups are case-sensitive (default: false)
+      def initialize(expected_size: DEFAULT_EXPECTED_SIZE,
+                     false_positive_rate: DEFAULT_FALSE_POSITIVE_RATE,
+                     case_sensitive: false)
+        @case_sensitive = case_sensitive
+        @item_count = 0
+
+        # Calculate optimal size and hash count
+        # m = -n * ln(p) / (ln(2)^2)
+        # k = (m/n) * ln(2)
+        @size = calculate_size(expected_size, false_positive_rate)
+        @hash_count = calculate_hash_count(@size, expected_size)
+
+        # Initialize bit array
+        @bits = Array.new(@size, false)
+      end
+
+      # Add an element to the filter.
+      #
+      # @param item [String] The item to add
+      # @return [self] Self for chaining
+      def add(item)
+        normalized_item = normalize_item(item)
+
+        @hash_count.times do |i|
+          index = hash_index(normalized_item, i)
+          @bits[index] = true
+        end
+
+        @item_count += 1
+        self
+      end
+
+      # Check if an element might be in the filter.
+      #
+      # Note: Returns false if the element is definitely NOT in the filter.
+      # Returns true if the element is PROBABLY in the filter (may be false positive).
+      #
+      # @param item [String] The item to check
+      # @return [Boolean] True if possibly in filter, false if definitely not
+      def include?(item)
+        normalized_item = normalize_item(item)
+
+        @hash_count.times do |i|
+          index = hash_index(normalized_item, i)
+          return false unless @bits[index]
+        end
+
+        true
+      end
+      alias include? include?
+      alias might_include? include?
+
+      # Merge another bloom filter into this one.
+      #
+      # @param other [BloomFilter] Another bloom filter with same parameters
+      # @return [self] Self for chaining
+      def merge(other)
+        raise ArgumentError, "Cannot merge filters with different sizes" unless other.size == @size
+        raise ArgumentError, "Cannot merge filters with different hash counts" unless other.hash_count == @hash_count
+
+        @size.times do |i|
+          @bits[i] = @bits[i] || other.instance_variable_get(:@bits)[i]
+        end
+
+        @item_count += other.item_count
+        self
+      end
+
+      # Clear all elements from the filter.
+      #
+      # @return [self] Self for chaining
+      def clear
+        @bits = Array.new(@size, false)
+        @item_count = 0
+        self
+      end
+
+      # Get filter statistics.
+      #
+      # @return [Hash] Statistics including :size, :hash_count, :item_count
+      def stats
+        {
+          size: @size,
+          hash_count: @hash_count,
+          item_count: @item_count
+        }
+      end
+
+      private
+
+      # Normalize item for consistent hashing.
+      #
+      # @param item [String] The item to normalize
+      # @return [String] Normalized item
+      def normalize_item(item)
+        @case_sensitive ? item.to_s : item.to_s.downcase
+      end
+
+      # Calculate optimal bit array size.
+      #
+      # @param n [Integer] Expected number of elements
+      # @param p [Float] False positive rate
+      # @return [Integer] Optimal size in bits
+      def calculate_size(n, p)
+        # m = -n * ln(p) / (ln(2)^2)
+        m = (-n * Math.log(p)) / (Math.log(2)**2)
+        m.ceil.to_i
+      end
+
+      # Calculate optimal number of hash functions.
+      #
+      # @param m [Integer] Size of bit array
+      # @param n [Integer] Expected number of elements
+      # @return [Integer] Optimal number of hash functions
+      def calculate_hash_count(m, n)
+        # k = (m/n) * ln(2)
+        k = (m.to_f / n) * Math.log(2)
+        [1, k.ceil.to_i].max # At least 1 hash function
+      end
+
+      # Calculate hash index for item with seed.
+      #
+      # Uses double hashing for multiple hash functions:
+      # hash_i(item) = (hash1(item) + i * hash2(item)) % m
+      #
+      # @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
+
+        (hash1 + seed * hash2.abs) % @size
+      end
+    end
+  end
+end

data/lib/kotoshu/debug_logger.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  module Debug
+    # Debug logger for detailed spellchecking information.
+    #
+    # Provides structured logging for lookup operations, suggestion generation,
+    # cache behavior, and decision trees.
+    class Logger
+      # Log levels
+      LEVELS = %i[info verbose trace].freeze
+
+      attr_reader :output, :level
+
+      # Create a new debug logger.
+      #
+      # @param output [IO] Output stream (default: $stderr)
+      # @param level [Symbol] Log level (:info, :verbose, :trace)
+      def initialize(output: $stderr, level: :info)
+        @output = output
+        @level = level
+        @indent = 0
+      end
+
+      # Log lookup operation.
+      #
+      # @param word [String] The word being looked up
+      # @param result [Boolean] The lookup result
+      # @param time [Float] Time taken in milliseconds
+      def debug_lookup(word, result:, time:)
+        return unless should_log?(:info)
+
+        status = result ? "✓" : "✗"
+        output.puts "DEBUG: lookup #{status} \"#{word}\" - #{time.round(3)}ms"
+      end
+
+      # Log suggestion generation.
+      #
+      # @param word [String] The input word
+      # @param suggestions [Array] Generated suggestions
+      # @param time [Float] Time taken in milliseconds
+      def debug_suggestions(word, suggestions:, time:)
+        return unless should_log?(:verbose)
+
+        output.puts "DEBUG: suggestions for \"#{word}\" (#{time.round(3)}ms)"
+
+        return unless should_log?(:trace)
+
+        @indent += 2
+        suggestions.each do |suggestion|
+          dist = suggestion.distance
+          conf = suggestion.confidence
+          source = suggestion.source
+          output.puts "#{" " * @indent}#{suggestion.word} (dist: #{dist}, conf: #{conf.round(2)}, src: #{source})"
+        end
+        @indent -= 2
+      end
+
+      # Log cache operation.
+      #
+      # @param cache_type [String] Type of cache
+      # @param key [String] The cache key
+      # @param hit [Boolean] True if cache hit
+      def debug_cache(cache_type, key, hit:)
+        return unless should_log?(:trace)
+
+        status = hit ? "HIT" : "MISS"
+        output.puts "DEBUG: cache #{cache_type.upcase} #{status} \"#{key}\""
+      end
+
+      # Log decision tree.
+      #
+      # @param word [String] The input word
+      # @param decisions [Array] Array of decision nodes
+      def debug_decision_tree(word, decisions:)
+        return unless should_log?(:trace)
+
+        output.puts "DEBUG: decision tree for \"#{word}\""
+        @indent += 2
+        print_decisions(decisions)
+        @indent -= 2
+      end
+
+      # Log info message.
+      #
+      # @param message [String] The message
+      def info(message)
+        return unless should_log?(:info)
+
+        output.puts "DEBUG: #{message}"
+      end
+
+      # Log verbose message.
+      #
+      # @param message [String] The message
+      def verbose(message)
+        return unless should_log?(:verbose)
+
+        output.puts "DEBUG: #{message}"
+      end
+
+      # Log trace message.
+      #
+      # @param message [String] The message
+      def trace(message)
+        return unless should_log?(:trace)
+
+        output.puts "DEBUG: #{message}"
+      end
+
+      private
+
+      # Check if should log at current level.
+      #
+      # @param required_level [Symbol] Required level
+      # @return [Boolean] True if should log
+      def should_log?(required_level)
+        LEVELS.index(required_level) <= LEVELS.index(@level)
+      end
+
+      # Print decisions tree.
+      #
+      # @param decisions [Array] Decision nodes
+      def print_decisions(decisions, index = 0)
+        decisions.each do |decision|
+          prefix = "#{" " * @indent}#{index}. "
+          output.puts "#{prefix}#{decision[:description]}"
+
+          if should_log?(:trace) && decision[:details]
+            @indent += 2
+            decision[:details].each do |key, value|
+              output.puts "#{" " * @indent}#{key}: #{value}"
+            end
+            @indent -= 2
+          end
+
+          next unless decision[:children] && !decision[:children].empty?
+
+          @indent += 2
+          print_decisions(decision[:children], index + 1)
+          @indent -= 2
+        end
+      end
+    end
+  end
+end

data/lib/kotoshu/debug_mode.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  # Debug mode for detailed spellchecking insights.
+  #
+  # When enabled, debug mode provides:
+  # - Lookup timing information
+  # - Suggestion scoring details
+  # - Decision tree visualization
+  # - Cache hit/miss tracking
+  # - Performance metrics
+  #
+  # @example Enable debug mode
+  #   Kotoshu::Debug.enable
+  #   Kotoshu.correct?("hello")
+  #   # Output: DEBUG: lookup "hello" - 0.001ms
+  #
+  # @example Disable debug mode
+  #   Kotoshu::Debug.disable
+  module Debug
+    class << self
+      # Enable debug mode.
+      #
+      # @param output [IO] Output stream (default: $stderr)
+      # @param level [Symbol] Debug level (:info, :verbose, :trace)
+      def enable(output: $stderr, level: :info)
+        @enabled = true
+        @output = output
+        @level = level
+        @logger = Debug::Logger.new(output: output, level: level)
+      end
+
+      # Disable debug mode.
+      def disable
+        @enabled = false
+        @logger = nil
+      end
+
+      # Check if debug mode is enabled.
+      #
+      # @return [Boolean] True if enabled
+      def enabled?
+        @enabled ||= false
+      end
+
+      # Get the debug logger.
+      #
+      # @return [Debug::Logger, nil] The logger instance
+      attr_reader :logger
+
+      # Log a lookup operation.
+      #
+      # @param word [String] The word being looked up
+      # @param result [Boolean] The lookup result
+      # @param time [Float] Time taken in milliseconds
+      def log_lookup(word, result:, time:)
+        return unless enabled?
+
+        logger&.debug_lookup(word, result: result, time: time)
+      end
+
+      # Log a suggestion generation.
+      #
+      # @param word [String] The input word
+      # @param suggestions [Array] Generated suggestions
+      # @param time [Float] Time taken in milliseconds
+      def log_suggestions(word, suggestions:, time:)
+        return unless enabled?
+
+        logger&.debug_suggestions(word, suggestions: suggestions, time: time)
+      end
+
+      # Log a cache hit/miss.
+      #
+      # @param cache_type [String] Type of cache (lookup, suggestion)
+      # @param key [String] The cache key
+      # @param hit [Boolean] True if cache hit
+      def log_cache(cache_type, key, hit:)
+        return unless enabled?
+
+        logger&.debug_cache(cache_type, key, hit: hit)
+      end
+
+      # Log a decision tree.
+      #
+      # @param word [String] The input word
+      # @param decisions [Array] Array of decision nodes
+      def log_decision_tree(word, decisions:)
+        return unless enabled?
+
+        logger&.debug_decision_tree(word, decisions: decisions)
+      end
+
+      # Start a timing context.
+      #
+      # @yield Block to time
+      # @return [Object] Block result
+      def time(label)
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result = yield
+        elapsed = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000
+
+        logger&.info("#{label}: #{elapsed.round(3)}ms")
+        result
+      end
+
+      # Measure and log a lookup.
+      #
+      # @yield Block that performs the lookup
+      # @return [Object] Block result
+      def measure_lookup(word)
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result = yield
+        elapsed = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000
+
+        log_lookup(word, result: result, time: elapsed)
+        result
+      end
+
+      # Measure and log suggestions.
+      #
+      # @yield Block that generates suggestions
+      # @return [Object] Block result
+      def measure_suggestions(word)
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result = yield
+        elapsed = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000
+
+        log_suggestions(word, suggestions: result, time: elapsed)
+        result
+      end
+    end
+  end
+end

data/lib/kotoshu/defaults.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "configuration/builder"
+
+module Kotoshu
+  # Sensible defaults for Kotoshu configuration.
+  #
+  # Provides auto-detection of system dictionaries and fallback
+  # to bundled dictionaries, ensuring Kotoshu works out of the box.
+  module Defaults
+    # Standard system dictionary paths.
+    SYSTEM_DICTIONARY_PATHS = [
+      "/usr/share/dict/words",
+      "/usr/share/dict/web2",
+      "/usr/share/dict/web2a",
+      "/usr/dict/words"
+    ].freeze
+
+    # Bundled dictionary paths (relative to gem root).
+    BUNDLED_DICTIONARY_PATHS = [
+      "dictionaries/unix_words/words",
+      "dictionaries/unix_words/web2",
+      "dictionaries/unix_words/web2a"
+    ].freeze
+
+    class << self
+      # Detect system dictionary.
+      #
+      # @return [String, nil] Path to system dictionary or nil
+      def detect_system_dictionary
+        SYSTEM_DICTIONARY_PATHS.find do |path|
+          File.exist?(path)
+        end
+      end
+
+      # Get path to bundled dictionary.
+      #
+      # @return [String, nil] Path to bundled dictionary or nil
+      def bundled_dictionary_path
+        BUNDLED_DICTIONARY_PATHS.find do |path|
+          full_path = File.expand_path("../../#{path}", __dir__)
+          File.exist?(full_path)
+        end
+      end
+
+      # Get default dictionary.
+      #
+      # Tries system dictionary first, then bundled dictionary,
+      # then falls back to an empty custom dictionary.
+      #
+      # @return [Dictionary::Base] A working dictionary
+      def default_dictionary
+        # Try system dictionary
+        system_path = detect_system_dictionary
+        return Dictionary::PlainText.new(system_path, language_code: "en") if system_path
+
+        # Try bundled dictionary
+        bundled_path = bundled_dictionary_path
+        if bundled_path
+          full_path = File.expand_path("../../#{bundled_path}", __dir__)
+          return Dictionary::PlainText.new(full_path, language_code: "en")
+        end
+
+        # Fall back to minimal dictionary with common words
+        Dictionary::PlainText.from_words(
+          %w[the and for are but not you all any can had has him his how her its now our our was what],
+          language_code: "en"
+        )
+      end
+
+      # Configure Kotoshu with sensible defaults.
+      #
+      # @return [Configuration] The configured instance
+      def configure
+        default_dictionary
+
+        Configuration::Builder.build do |c|
+          c.dictionary_type = :plain_text
+          c.language = "en-US"
+          c.max_suggestions = 10
+          c.case_sensitive = false
+        end
+      end
+    end
+  end
+end