kotoshu 0.3.0

data/lib/kotoshu/models/word_embedding.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  module Models
+    # Immutable value object for word embeddings.
+    #
+    # Represents a word and its vector representation in a semantic space.
+    # Used for semantic similarity calculations and nearest neighbor searches.
+    #
+    # @example Creating an embedding
+    #   embedding = WordEmbedding.new("hello", [0.1, -0.2, 0.3], "en")
+    #   embedding.similarity(other_embedding)  # => 0.85
+    #
+    # @see https://fasttext.cc/docs/en/crawl-vectors.html FastText crawl vectors
+    class WordEmbedding
+      attr_reader :word, :vector, :language_code, :dimension
+
+      # Create a new word embedding.
+      #
+      # @param word [String] The word
+      # @param vector [Array<Float>] The word's vector representation
+      # @param language_code [String] ISO 639-1 language code
+      # @param dimension [Integer] Vector dimension (default: 300 for FastText)
+      # @raise [ArgumentError] if vector doesn't match dimension
+      def initialize(word, vector, language_code, dimension: 300)
+        raise ArgumentError, "Vector dimension mismatch" unless vector.size == dimension
+
+        @word = word
+        @vector = vector.freeze
+        @language_code = language_code
+        @dimension = dimension
+
+        freeze
+      end
+
+      # Calculate cosine similarity with another embedding.
+      #
+      # Cosine similarity measures the cosine of the angle between two vectors.
+      # Returns 1.0 for identical vectors, 0.0 for orthogonal vectors.
+      #
+      # @param other [WordEmbedding] Another embedding
+      # @return [Float] Similarity score (0.0 to 1.0)
+      # @raise [TypeError] if other is not a WordEmbedding
+      def similarity(other)
+        raise TypeError, "Must be WordEmbedding" unless other.is_a?(WordEmbedding)
+
+        return 0.0 if @dimension != other.dimension
+
+        dot_product = @vector.zip(other.vector).map { |a, b| a * b }.sum
+        magnitude_a = vector_magnitude
+        magnitude_b = other.vector_magnitude
+
+        return 0.0 if magnitude_a.zero? || magnitude_b.zero?
+
+        dot_product / (magnitude_a * magnitude_b)
+      end
+
+      # Calculate Euclidean distance from another embedding.
+      #
+      # @param other [WordEmbedding] Another embedding
+      # @return [Float] Euclidean distance
+      # @raise [TypeError] if other is not a WordEmbedding
+      def distance(other)
+        raise TypeError, "Must be WordEmbedding" unless other.is_a?(WordEmbedding)
+
+        return Float::INFINITY if @dimension != other.dimension
+
+        Math.sqrt(@vector.zip(other.vector).map { |a, b| (a - b)**2 }.sum)
+      end
+
+      # Check if this embedding is equal to another.
+      #
+      # @param other [Object] Another object
+      # @return [Boolean] True if words and languages match
+      def ==(other)
+        return false unless other.is_a?(WordEmbedding)
+
+        @word == other.word && @language_code == other.language_code
+      end
+      alias_method :eql?, :==
+
+      # Hash code for hash table usage.
+      #
+      # @return [Integer] Hash code
+      def hash
+        [@word, @language_code].hash
+      end
+
+      # String representation.
+      #
+      # @return [String] Human-readable representation
+      def to_s
+        "#{self.class.name}[#{@word}, #{@language_code}, #{@dimension}D]"
+      end
+      alias_method :inspect, :to_s
+
+      private
+
+      # Calculate vector magnitude (Euclidean norm).
+      #
+      # @return [Float] Magnitude
+      def vector_magnitude
+        @magnitude ||= Math.sqrt(@vector.map { |x| x * x }.sum)
+      end
+    end
+  end
+end

data/lib/kotoshu/paths.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Kotoshu
+  # Centralized XDG Base Directory paths.
+  #
+  # Resolves cache, config, and data paths per the XDG Base Directory
+  # Specification. Kotoshu-specific env vars (KOTOSHU_CACHE_PATH etc.)
+  # take precedence over the generic XDG_*_HOME vars, which take
+  # precedence over the hardcoded defaults.
+  #
+  # Default layout:
+  #   ~/.cache/kotoshu/         downloaded dicts, models, frequency lists
+  #   ~/.config/kotoshu/        user-edited config, personal dictionary
+  #   ~/.local/share/kotoshu/   append-only data (audit log)
+  module Paths
+    class << self
+      def cache_path
+        ENV.fetch("KOTOSHU_CACHE_PATH", nil) || xdg("CACHE", "cache")
+      end
+
+      def config_path
+        ENV.fetch("KOTOSHU_CONFIG_PATH", nil) || xdg("CONFIG", "config")
+      end
+
+      def data_path
+        ENV.fetch("KOTOSHU_DATA_PATH", nil) || xdg("DATA", "local/share")
+      end
+
+      def audit_log_path
+        ENV.fetch("KOTOSHU_AUDIT_LOG", nil) || File.join(data_path, "audit.log")
+      end
+
+      def personal_dictionary_path
+        ENV.fetch("KOTOSHU_PERSONAL_DIC", nil) || File.join(config_path, "personal.dic")
+      end
+
+      def ensure_exist!
+        FileUtils.mkdir_p(cache_path)
+        FileUtils.mkdir_p(config_path)
+        FileUtils.mkdir_p(data_path)
+      end
+
+      private
+
+      def xdg(suffix, default_subdir)
+        base = ENV.fetch("XDG_#{suffix}_HOME", nil) || File.join(Dir.home, ".#{default_subdir}")
+        File.join(base, "kotoshu")
+      end
+    end
+  end
+end

data/lib/kotoshu/personal_dictionary.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Kotoshu
+  # Personal dictionary for user-specific words.
+  #
+  # Stored in ~/.config/kotoshu/personal.dic (Hunspell format) under the
+  # XDG config directory. Override via KOTOSHU_PERSONAL_DIC.
+  class PersonalDictionary
+    PERSONAL_FILE = Kotoshu::Paths.personal_dictionary_path
+
+    class << self
+      # Add a word to personal dictionary.
+      #
+      # @param word [String] Word to add
+      # @return [Boolean] True if added
+      def add_word(word)
+        return false if word.nil? || word.empty?
+
+        ensure_directory
+        words = load_words
+
+        unless words.include?(word.downcase)
+          words << word.downcase
+          save_words(words)
+        end
+
+        true
+      end
+
+      # Get all personal words.
+      #
+      # @return [Array<String>] All personal words
+      def words
+        load_words
+      end
+
+      # Remove a word from personal dictionary.
+      #
+      # @param word [String] Word to remove
+      # @return [Boolean] True if removed
+      def remove_word(word)
+        return false if word.nil? || word.empty?
+
+        words = load_words
+        if words.delete(word.downcase)
+          save_words(words)
+          true
+        else
+          false
+        end
+      end
+
+      # Check if word is in personal dictionary.
+      #
+      # @param word [String] Word to check
+      # @return [Boolean] True if present
+      def include?(word)
+        return false if word.nil? || word.empty?
+
+        load_words.include?(word.downcase)
+      end
+
+      private
+
+      # Ensure personal dictionary's parent directory exists.
+      def ensure_directory
+        FileUtils.mkdir_p(File.dirname(PERSONAL_FILE))
+      end
+
+      # Load words from personal dictionary file.
+      #
+      # @return [Array<String>] List of words
+      def load_words
+        return [] unless File.exist?(PERSONAL_FILE)
+
+        File.readlines(PERSONAL_FILE, chomp: true)
+            .reject { |line| line.empty? || line.start_with?("#") }
+            .map(&:strip)
+      end
+
+      # Save words to personal dictionary file.
+      #
+      # @param words [Array<String>] Words to save
+      def save_words(words)
+        ensure_directory
+        File.open(PERSONAL_FILE, "w") do |f|
+          words.sort.uniq.each { |word| f.puts word }
+        end
+      end
+    end
+  end
+end

data/lib/kotoshu/plugins/plugin.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  module Plugins
+    # Base class for plugins.
+    #
+    # Plugins provide extensible functionality with dependency injection.
+    #
+    # @example Creating a plugin
+    #   class MyPlugin < Kotoshu::Plugins::Plugin
+    #     def self.plugin_name
+    #       :my_plugin
+    #     end
+    #
+    #     def self.dependencies
+    #       [:dictionary]
+    #     end
+    #
+    #     def self.provides
+    #       [:suggestions]
+    #     end
+    #
+    #     def initialize(dictionary:)
+    #       @dictionary = dictionary
+    #     end
+    #   end
+    class Plugin
+      # @return [Symbol] Plugin name
+      def self.plugin_name
+        raise NotImplementedError, "#{name} must define .plugin_name"
+      end
+
+      # @return [Array<Symbol>] Dependencies
+      def self.dependencies
+        []
+      end
+
+      # @return [Array<Symbol>] Provided services
+      def self.provides
+        []
+      end
+
+      # Lifecycle hook called before plugin starts.
+      #
+      # Override in subclass to add startup logic.
+      def before_start
+        # Override in subclass
+      end
+
+      # Lifecycle hook called after plugin stops.
+      #
+      # Override in subclass to add cleanup logic.
+      def after_stop
+        # Override in subclass
+      end
+    end
+
+    # Error raised when a dependency cannot be resolved.
+    class DependencyError < StandardError; end
+  end
+end

data/lib/kotoshu/plugins/registry.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative "plugin"
+
+module Kotoshu
+  module Plugins
+    # Registry for managing plugins and their dependencies.
+    #
+    # @example Registering a plugin
+    #   registry = Registry.new
+    #   registry.register(:dictionary, MyDictionary)
+    #   registry.register(:suggestions, MySuggestions)
+    #
+    # @example Creating an instance with DI
+    #   suggestions = registry.create_instance(MySuggestions)
+    class Registry
+      # @return [Hash] Registered services
+      attr_reader :services
+
+      # @return [Hash] Registered plugins
+      attr_reader :plugins
+
+      # Create a new registry.
+      def initialize
+        @services = {}
+        @plugins = {}
+        @singletons = {}
+      end
+
+      # Register a service.
+      #
+      # @param name [Symbol] Service name
+      # @param klass [Class] Service class or instance
+      # @return [self] Self for chaining
+      def register(name, klass)
+        @services[name] = klass
+        self
+      end
+
+      # Register a plugin.
+      #
+      # @param plugin [Class] Plugin class
+      # @return [self] Self for chaining
+      def register_plugin(plugin)
+        @plugins[plugin.plugin_name] = plugin
+        self
+      end
+
+      # Get a service instance.
+      #
+      # @param name [Symbol] Service name
+      # @return [Object] Service instance
+      def get_service(name)
+        service = @services[name]
+
+        raise DependencyError, "Unknown service: #{name}" unless service
+
+        # Return singleton if already created
+        return @singletons[name] if @singletons.key?(name)
+
+        # Create new instance
+        instance = service.is_a?(Class) ? service.new : service
+
+        # Store singleton
+        @singletons[name] = instance if service.is_a?(Class)
+        instance
+      end
+
+      # Create an instance with dependency injection.
+      #
+      # @param klass [Class] Class to instantiate
+      # @return [Object] Created instance
+      def create_instance(klass)
+        return klass.new unless klass.is_a?(Class)
+
+        # Get dependencies if it's a Plugin
+        if klass < Plugin
+          dependencies = resolve_dependencies(klass)
+          klass.new(**dependencies)
+        else
+          klass.new
+        end
+      rescue ArgumentError => e
+        raise DependencyError, "Failed to create instance of #{klass}: #{e.message}"
+      end
+
+      # Check if a service is registered.
+      #
+      # @param name [Symbol] Service name
+      # @return [Boolean] True if registered
+      def registered?(name)
+        @services.key?(name)
+      end
+
+      # Clear all singletons (force re-instantiation).
+      #
+      # @return [self] Self for chaining
+      def clear_singletons
+        @singletons.clear
+        self
+      end
+
+      private
+
+      # Resolve dependencies for a plugin.
+      #
+      # @param plugin [Class] Plugin class
+      # @return [Hash] Keyword arguments for initialization
+      def resolve_dependencies(plugin)
+        deps = {}
+
+        plugin.dependencies.each do |dep|
+          deps[dep] = get_service(dep)
+        end
+
+        deps
+      end
+    end
+  end
+end

data/lib/kotoshu/project_config.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  # Project configuration for .kotoshu file.
+  #
+  # Auto-discovers .kotoshu file by searching up directory tree.
+  class ProjectConfig
+    CONFIG_FILE = ".kotoshu"
+
+    class << self
+      # Load project config for given path.
+      #
+      # @param start_path [String] Starting directory
+      # @return [Hash, nil] Configuration hash or nil
+      def load(start_path = Dir.pwd)
+        path = find_config_file(start_path)
+        return nil unless path
+
+        parse_config_file(path)
+      end
+
+      # Check if project config exists.
+      #
+      # @param start_path [String] Starting directory
+      # @return [Boolean] True if config exists
+      def exists?(start_path = Dir.pwd)
+        !find_config_file(start_path).nil?
+      end
+
+      # Get ignore patterns from project config.
+      #
+      # @param start_path [String] Starting directory
+      # @return [Hash] Configuration with ignore patterns
+      def ignore_patterns(start_path = Dir.pwd)
+        config = load(start_path) || {}
+        {
+          words: config["ignore_words"] || [],
+          patterns: (config["ignore_patterns"] || []).map { |p| Regexp.new(p) }
+        }
+      end
+
+      private
+
+      # Find .kotoshu file by searching up directory tree.
+      #
+      # @param start_path [String] Starting directory
+      # @return [String, nil] Path to config file or nil
+      def find_config_file(start_path)
+        path = Pathname.new(start_path)
+
+        while path
+          config_file = path.join(CONFIG_FILE)
+          return config_file.to_s if config_file.file?
+
+          parent = path.parent
+          break if parent == path # Reached root
+
+          path = parent
+        end
+
+        nil
+      end
+
+      # Parse .kotoshu YAML file.
+      #
+      # @param path [String] Path to config file
+      # @return [Hash] Parsed configuration
+      def parse_config_file(path)
+        require "yaml"
+        YAML.load_file(path) || {}
+      rescue ArgumentError, Psych::SyntaxError
+        {}
+      end
+    end
+  end
+end