woods 1.0.0

data/lib/woods/cache/redis_cache_store.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'cache_store'
+
+module Woods
+  module Cache
+    # Redis-backed cache store using GET/SET with TTL.
+    #
+    # Uses simple key-value operations (not Lists like SessionTracer::RedisStore).
+    # Values are JSON-serialized on write and deserialized on read. TTL is
+    # enforced natively by Redis via the EX option on SET.
+    #
+    # Requires the `redis` gem at runtime.
+    #
+    # @example
+    #   store = RedisCacheStore.new(redis: Redis.new, default_ttl: 3600)
+    #   store.write("ci:emb:abc", [0.1, 0.2], ttl: 86_400)
+    #   store.read("ci:emb:abc") # => [0.1, 0.2]
+    #
+    class RedisCacheStore < CacheStore
+      # @param redis [Redis] A Redis client instance
+      # @param default_ttl [Integer, nil] Default TTL in seconds when none specified (nil = no expiry)
+      # @raise [ConfigurationError] if the redis gem is not loaded
+      def initialize(redis:, default_ttl: nil)
+        super()
+        unless defined?(::Redis)
+          raise ConfigurationError,
+                'The redis gem is required for RedisCacheStore. Add `gem "redis"` to your Gemfile.'
+        end
+
+        @redis = redis
+        @default_ttl = default_ttl
+      end
+
+      # Read a value from Redis.
+      #
+      # @param key [String] Cache key
+      # @return [Object, nil] Deserialized value or nil
+      def read(key)
+        raw = @redis.get(key)
+        return nil unless raw
+
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        delete_silently(key)
+        nil
+      rescue ::Redis::BaseError, Errno::ECONNREFUSED, Errno::ECONNRESET => e
+        logger.warn("[Woods] RedisCacheStore#read failed for #{key}: #{e.message}")
+        nil
+      end
+
+      # Write a value to Redis with optional TTL.
+      #
+      # @param key [String] Cache key
+      # @param value [Object] Value to cache (must be JSON-serializable)
+      # @param ttl [Integer, nil] TTL in seconds (falls back to default_ttl)
+      # @return [void]
+      def write(key, value, ttl: nil)
+        serialized = JSON.generate(value)
+        effective_ttl = ttl || @default_ttl
+
+        if effective_ttl
+          @redis.set(key, serialized, ex: effective_ttl)
+        else
+          @redis.set(key, serialized)
+        end
+      rescue ::Redis::BaseError, Errno::ECONNREFUSED, Errno::ECONNRESET => e
+        logger.warn("[Woods] RedisCacheStore#write failed for #{key}: #{e.message}")
+        nil
+      end
+
+      # Delete a key from Redis.
+      #
+      # @param key [String] Cache key
+      # @return [void]
+      def delete(key)
+        @redis.del(key)
+      rescue ::Redis::BaseError, Errno::ECONNREFUSED, Errno::ECONNRESET => e
+        logger.warn("[Woods] RedisCacheStore#delete failed for #{key}: #{e.message}")
+        nil
+      end
+
+      # Check if a key exists in Redis.
+      #
+      # @param key [String] Cache key
+      # @return [Boolean]
+      def exist?(key)
+        @redis.exists?(key)
+      rescue ::Redis::BaseError, Errno::ECONNREFUSED, Errno::ECONNRESET => e
+        logger.warn("[Woods] RedisCacheStore#exist? failed for #{key}: #{e.message}")
+        false
+      end
+
+      # Clear cached entries by namespace or all woods cache keys.
+      #
+      # Uses SCAN (not KEYS) to avoid blocking Redis on large keyspaces.
+      #
+      # @param namespace [Symbol, nil] Domain to clear, or nil for all cache keys
+      # @return [void]
+      def clear(namespace: nil)
+        pattern = clear_pattern(namespace)
+
+        cursor = '0'
+        loop do
+          cursor, keys = @redis.scan(cursor, match: pattern, count: 100)
+          @redis.del(*keys) if keys.any?
+          break if cursor == '0'
+        end
+      rescue ::Redis::BaseError, Errno::ECONNREFUSED, Errno::ECONNRESET => e
+        logger.warn("[Woods] RedisCacheStore#clear failed: #{e.message}")
+        nil
+      end
+    end
+  end
+end

data/lib/woods/cache/solid_cache_store.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'cache_store'
+
+module Woods
+  module Cache
+    # SolidCache-backed (or any ActiveSupport::Cache::Store) cache store.
+    #
+    # Delegates to a Rails-compatible cache backend. Values are JSON-serialized
+    # to avoid Marshal dependency issues across Ruby versions. TTL is passed
+    # as `expires_in:` to the underlying cache.
+    #
+    # @example With SolidCache
+    #   store = SolidCacheStore.new(cache: SolidCache::Store.new, default_ttl: 3600)
+    #   store.write("ci:emb:abc", [0.1, 0.2], ttl: 86_400)
+    #   store.read("ci:emb:abc") # => [0.1, 0.2]
+    #
+    # @example With Rails.cache (any backend)
+    #   store = SolidCacheStore.new(cache: Rails.cache)
+    #
+    class SolidCacheStore < CacheStore
+      # @param cache [ActiveSupport::Cache::Store] A SolidCache or compatible cache instance
+      # @param default_ttl [Integer, nil] Default TTL in seconds (nil = no expiry)
+      def initialize(cache:, default_ttl: nil)
+        super()
+        @cache = cache
+        @default_ttl = default_ttl
+      end
+
+      # Read a value from the cache.
+      #
+      # @param key [String] Cache key
+      # @return [Object, nil] Deserialized value or nil
+      def read(key)
+        raw = @cache.read(key)
+        return nil unless raw
+
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        delete_silently(key)
+        nil
+      rescue StandardError => e
+        logger.warn("[Woods] SolidCacheStore#read failed for #{key}: #{e.message}")
+        nil
+      end
+
+      # Write a value with optional TTL.
+      #
+      # @param key [String] Cache key
+      # @param value [Object] Value to cache (must be JSON-serializable)
+      # @param ttl [Integer, nil] TTL in seconds (falls back to default_ttl)
+      # @return [void]
+      def write(key, value, ttl: nil)
+        serialized = JSON.generate(value)
+        effective_ttl = ttl || @default_ttl
+
+        opts = effective_ttl ? { expires_in: effective_ttl } : {}
+        @cache.write(key, serialized, **opts)
+      rescue StandardError => e
+        logger.warn("[Woods] SolidCacheStore#write failed for #{key}: #{e.message}")
+        nil
+      end
+
+      # Delete a key from the cache.
+      #
+      # @param key [String] Cache key
+      # @return [void]
+      def delete(key)
+        @cache.delete(key)
+      rescue StandardError => e
+        logger.warn("[Woods] SolidCacheStore#delete failed for #{key}: #{e.message}")
+        nil
+      end
+
+      # Check if a key exists in the cache.
+      #
+      # @param key [String] Cache key
+      # @return [Boolean]
+      def exist?(key)
+        @cache.exist?(key)
+      rescue StandardError => e
+        logger.warn("[Woods] SolidCacheStore#exist? failed for #{key}: #{e.message}")
+        false
+      end
+
+      # Clear cached entries by namespace or all woods cache keys.
+      #
+      # Uses `delete_matched` if the underlying cache supports it (Redis, Memcached).
+      # Falls back to a no-op if pattern deletion is not available (some backends
+      # like SolidCache don't support wildcard deletion).
+      #
+      # @param namespace [Symbol, nil] Domain to clear, or nil for all cache keys
+      # @return [void]
+      def clear(namespace: nil)
+        pattern = clear_pattern(namespace)
+
+        unless @cache.respond_to?(:delete_matched)
+          logger.warn("[Woods] Cache#clear(namespace: #{namespace.inspect}) is a no-op: " \
+                      "backend #{@cache.class} does not support delete_matched")
+          return
+        end
+
+        @cache.delete_matched(pattern)
+      rescue StandardError => e
+        logger.warn("[Woods] SolidCacheStore#clear failed: #{e.message}")
+        nil
+      end
+    end
+  end
+end

data/lib/woods/chunking/chunk.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Woods
+  module Chunking
+    # A single semantic chunk extracted from an ExtractedUnit.
+    #
+    # Chunks represent meaningful subsections of a code unit — associations,
+    # callbacks, validations, individual actions, etc. Each chunk is independently
+    # embeddable and retrievable, with a back-reference to its parent unit.
+    #
+    # @example
+    #   chunk = Chunk.new(
+    #     content: "has_many :posts\nhas_many :comments",
+    #     chunk_type: :associations,
+    #     parent_identifier: "User",
+    #     parent_type: :model
+    #   )
+    #   chunk.token_count  # => 20
+    #   chunk.identifier   # => "User#associations"
+    #
+    class Chunk
+      attr_reader :content, :chunk_type, :parent_identifier, :parent_type, :metadata
+
+      # @param content [String] The chunk's source code or text
+      # @param chunk_type [Symbol] Semantic type (:summary, :associations, :callbacks, etc.)
+      # @param parent_identifier [String] Identifier of the parent ExtractedUnit
+      # @param parent_type [Symbol] Type of the parent unit (:model, :controller, etc.)
+      # @param metadata [Hash] Optional chunk-specific metadata
+      def initialize(content:, chunk_type:, parent_identifier:, parent_type:, metadata: {})
+        @content = content
+        @chunk_type = chunk_type
+        @parent_identifier = parent_identifier
+        @parent_type = parent_type
+        @metadata = metadata
+      end
+
+      # Estimated token count using project convention.
+      #
+      # @return [Integer]
+      def token_count
+        @token_count ||= (content.length / 4.0).ceil
+      end
+
+      # SHA256 hash of content for change detection.
+      #
+      # @return [String]
+      def content_hash
+        @content_hash ||= Digest::SHA256.hexdigest(content)
+      end
+
+      # Unique identifier combining parent and chunk type.
+      #
+      # @return [String]
+      def identifier
+        "#{parent_identifier}##{chunk_type}"
+      end
+
+      # Whether the chunk has no meaningful content.
+      #
+      # @return [Boolean]
+      def empty?
+        content.nil? || content.strip.empty?
+      end
+
+      # Serialize to hash for JSON output.
+      #
+      # @return [Hash]
+      def to_h
+        {
+          content: content,
+          chunk_type: chunk_type,
+          parent_identifier: parent_identifier,
+          parent_type: parent_type,
+          identifier: identifier,
+          token_count: token_count,
+          content_hash: content_hash,
+          metadata: metadata
+        }
+      end
+    end
+  end
+end

data/lib/woods/chunking/semantic_chunker.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+require_relative 'chunk'
+
+module Woods
+  module Chunking
+    # Shared method-detection patterns used by ModelChunker and ControllerChunker.
+    METHOD_PATTERN = /^\s*def\s+/
+    PRIVATE_PATTERN = /^\s*(private|protected)\s*$/
+
+    # Mixin that provides the shared build_chunk helper for chunker classes.
+    #
+    # Requires the including class to have an @unit ivar (ExtractedUnit).
+    module ChunkBuilder
+      private
+
+      # Build a Chunk for a given section.
+      #
+      # @param chunk_type [Symbol]
+      # @param content [String]
+      # @return [Chunk]
+      def build_chunk(chunk_type, content)
+        Chunk.new(
+          content: content,
+          chunk_type: chunk_type,
+          parent_identifier: @unit.identifier,
+          parent_type: @unit.type
+        )
+      end
+    end
+
+    # Splits ExtractedUnits into semantic chunks based on unit type.
+    #
+    # Models are split by: summary, associations, validations, callbacks,
+    # scopes, methods. Controllers are split by: summary (filters), per-action.
+    # Other types use whole-unit or method-level splitting based on size.
+    #
+    # Units below the token threshold are returned as a single :whole chunk.
+    #
+    # @example
+    #   chunker = SemanticChunker.new(threshold: 200)
+    #   chunks = chunker.chunk(extracted_unit)
+    #   chunks.map(&:chunk_type) # => [:summary, :associations, :validations, :methods]
+    #
+    class SemanticChunker
+      # Default token threshold below which units stay whole.
+      DEFAULT_THRESHOLD = 200
+
+      # @param threshold [Integer] Token count threshold for chunking
+      def initialize(threshold: DEFAULT_THRESHOLD)
+        @threshold = threshold
+      end
+
+      # Split an ExtractedUnit into semantic chunks.
+      #
+      # @param unit [ExtractedUnit] The unit to chunk
+      # @return [Array<Chunk>] Ordered list of chunks
+      def chunk(unit)
+        return [] if unit.source_code.nil? || unit.source_code.strip.empty?
+        return [build_whole_chunk(unit)] if unit.estimated_tokens <= @threshold
+
+        case unit.type
+        when :model then ModelChunker.new(unit).chunk
+        when :controller then ControllerChunker.new(unit).chunk
+        else [build_whole_chunk(unit)]
+        end
+      end
+
+      private
+
+      # Build a single :whole chunk for small units.
+      #
+      # @param unit [ExtractedUnit]
+      # @return [Chunk]
+      def build_whole_chunk(unit)
+        Chunk.new(
+          content: unit.source_code,
+          chunk_type: :whole,
+          parent_identifier: unit.identifier,
+          parent_type: unit.type
+        )
+      end
+    end
+
+    # Chunks a model unit by semantic sections: summary, associations,
+    # validations, callbacks, scopes, methods.
+    #
+    # @api private
+    class ModelChunker
+      include ChunkBuilder
+
+      ASSOCIATION_PATTERN = /^\s*(has_many|has_one|belongs_to|has_and_belongs_to_many)\b/
+      VALIDATION_PATTERN = /^\s*validates?\b/
+      CALLBACK_ACTIONS = '(save|create|update|destroy|validation|action|commit|rollback|find|initialize|touch)'
+      CALLBACK_PATTERN = /^\s*(before_|after_|around_)#{CALLBACK_ACTIONS}\b/
+      SCOPE_PATTERN = /^\s*scope\s+:/
+
+      SECTION_PATTERNS = {
+        associations: ASSOCIATION_PATTERN,
+        validations: VALIDATION_PATTERN,
+        callbacks: CALLBACK_PATTERN,
+        scopes: SCOPE_PATTERN
+      }.freeze
+
+      SEMANTIC_SECTIONS = %i[associations validations callbacks scopes].freeze
+
+      # @param unit [ExtractedUnit]
+      def initialize(unit)
+        @unit = unit
+      end
+
+      # @return [Array<Chunk>]
+      def chunk
+        sections = classify_lines(@unit.source_code.lines)
+        build_chunks(sections).reject(&:empty?)
+      end
+
+      private
+
+      # @param sections [Hash<Symbol, Array<String>>]
+      # @return [Array<Chunk>]
+      def build_chunks(sections)
+        chunks = []
+        chunks << build_chunk(:summary, sections[:summary].join) if sections[:summary].any?
+
+        SEMANTIC_SECTIONS.each do |type|
+          next if sections[type].empty?
+
+          chunks << build_chunk(type, sections[type].join)
+        end
+
+        chunks << build_chunk(:methods, sections[:methods].join) if sections[:methods].any?
+        chunks
+      end
+
+      # Classify each line into a semantic section.
+      #
+      # @param lines [Array<String>]
+      # @return [Hash<Symbol, Array<String>>]
+      def classify_lines(lines)
+        state = { sections: empty_sections, current: :summary, in_method: false,
+                  depth: 0 }
+        lines.each do |line|
+          if state[:in_method]
+            track_method_line(state, line)
+          else
+            classify_line(state, line)
+          end
+        end
+
+        state[:sections]
+      end
+
+      # @return [Hash<Symbol, Array<String>>]
+      def empty_sections
+        { summary: [], associations: [], validations: [], callbacks: [], scopes: [], methods: [] }
+      end
+
+      # Track lines inside a method body.
+      def track_method_line(state, line)
+        state[:sections][:methods] << line
+        update_method_depth(state, line)
+        state[:in_method] = false if state[:depth] <= 0 && line.strip.match?(/^end\s*$/)
+      end
+
+      def update_method_depth(state, line)
+        state[:depth] += 1 if line.match?(/\bdo\b|\bdef\b/) && !line.match?(/\bend\b/)
+        state[:depth] -= 1 if line.strip == 'end' || (line.match?(/\bend\s*$/) && state[:depth].positive?)
+      end
+
+      # Classify a single non-method line.
+      def classify_line(state, line)
+        section = detect_semantic_section(line)
+        if section
+          state[:current] = section
+          state[:sections][section] << line
+        elsif line.match?(PRIVATE_PATTERN)
+          state[:sections][:methods] << line
+        elsif line.match?(METHOD_PATTERN)
+          start_method(state, line)
+        else
+          assign_fallback(state, line)
+        end
+      end
+
+      # Detect which semantic section a line belongs to, if any.
+      #
+      # @return [Symbol, nil] the section name, or nil if no pattern matched
+      def detect_semantic_section(line)
+        SECTION_PATTERNS.each do |section, pattern|
+          return section if line.match?(pattern)
+        end
+        nil
+      end
+
+      def start_method(state, line)
+        state[:in_method] = true
+        state[:depth] = 1
+        state[:sections][:methods] << line
+      end
+
+      def assign_fallback(state, line)
+        if state[:current] == :summary || line.strip.empty? || line.match?(/^\s*#/)
+          state[:sections][:summary] << line
+        else
+          state[:sections][state[:current]] << line
+        end
+      end
+    end
+
+    # Chunks a controller unit by actions: summary (class + filters),
+    # then one chunk per public action method.
+    #
+    # @api private
+    class ControllerChunker
+      include ChunkBuilder
+
+      FILTER_PATTERN = /^\s*(before_action|after_action|around_action|skip_before_action)\b/
+
+      # @param unit [ExtractedUnit]
+      def initialize(unit)
+        @unit = unit
+      end
+
+      # @return [Array<Chunk>]
+      def chunk
+        state = parse_lines(@unit.source_code.lines)
+        build_chunks(state).reject(&:empty?)
+      end
+
+      private
+
+      # Parse controller lines into summary + action buffers.
+      #
+      # @param lines [Array<String>]
+      # @return [Hash]
+      def parse_lines(lines)
+        state = { summary: [], actions: {}, current_action: nil, depth: 0,
+                  in_private: false }
+        lines.each do |line|
+          if state[:current_action]
+            track_action_line(state, line)
+          else
+            classify_controller_line(state, line)
+          end
+        end
+
+        state
+      end
+
+      def track_action_line(state, line)
+        state[:actions][state[:current_action]] << line
+        state[:depth] += 1 if line.match?(/\bdo\b/) && !line.match?(/\bend\b/)
+        return unless line.strip.match?(/^end\s*$/)
+
+        state[:depth] -= 1
+        return unless state[:depth] <= 0
+
+        state[:current_action] = nil
+        state[:depth] = 0
+      end
+
+      def classify_controller_line(state, line)
+        if line.match?(PRIVATE_PATTERN)
+          state[:in_private] = true
+          state[:summary] << line
+        elsif !state[:in_private] && line.match?(METHOD_PATTERN)
+          start_action(state, line)
+        else
+          state[:summary] << line
+        end
+      end
+
+      def start_action(state, line)
+        action_name = line[/def\s+(\w+)/, 1]
+        state[:current_action] = action_name
+        state[:depth] = 1
+        state[:actions][action_name] = [line]
+      end
+
+      # @param state [Hash]
+      # @return [Array<Chunk>]
+      def build_chunks(state)
+        chunks = []
+        chunks << build_chunk(:summary, state[:summary].join) if state[:summary].any?
+
+        state[:actions].each do |action_name, action_lines|
+          chunks << build_chunk(:"action_#{action_name}", action_lines.join)
+        end
+
+        chunks
+      end
+    end
+  end
+end

data/lib/woods/console/adapters/cache_adapter.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Woods
+  module Console
+    module Adapters
+      # Cache adapter that auto-detects the active cache store.
+      #
+      # Supports Redis, Solid Cache, memory, and file cache stores.
+      # Detection checks Rails.cache class name first, then falls back
+      # to checking for SolidCache constant.
+      #
+      # @example
+      #   CacheAdapter.detect  # => :redis
+      #   CacheAdapter.stats   # => { tool: 'cache_stats', params: {} }
+      #
+      module CacheAdapter
+        STORE_PATTERNS = {
+          'RedisCacheStore' => :redis,
+          'MemoryStore' => :memory,
+          'FileStore' => :file
+        }.freeze
+
+        module_function
+
+        # Detect the active cache store backend.
+        #
+        # @return [Symbol] One of :redis, :solid_cache, :memory, :file, :unknown
+        def detect
+          if defined?(::Rails) && ::Rails.respond_to?(:cache) && ::Rails.cache
+            class_name = ::Rails.cache.class.name.to_s
+            STORE_PATTERNS.each do |pattern, backend|
+              return backend if class_name.include?(pattern)
+            end
+          end
+
+          return :solid_cache if defined?(::SolidCache)
+
+          :unknown
+        end
+
+        # Get cache store statistics.
+        #
+        # @param namespace [String, nil] Cache namespace filter
+        # @return [Hash] Bridge request
+        def stats(namespace: nil)
+          { tool: 'cache_stats', params: { namespace: namespace }.compact }
+        end
+
+        # Get cache store info (backend type, configuration).
+        #
+        # @return [Hash] Bridge request
+        def info
+          { tool: 'cache_info', params: {} }
+        end
+      end
+    end
+  end
+end

data/lib/woods/console/adapters/good_job_adapter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'job_adapter'
+
+module Woods
+  module Console
+    module Adapters
+      # Job backend adapter for GoodJob.
+      #
+      # Builds bridge requests for GoodJob queue stats, failure listing,
+      # job lookup, scheduled jobs, and retry operations.
+      #
+      # @example
+      #   adapter = GoodJobAdapter.new
+      #   adapter.queue_stats  # => { tool: 'good_job_queue_stats', params: {} }
+      #
+      class GoodJobAdapter < JobAdapter
+        # Check if GoodJob is available in the current environment.
+        #
+        # @return [Boolean]
+        def self.available?
+          !!defined?(::GoodJob)
+        end
+
+        private
+
+        def prefix
+          'good_job'
+        end
+      end
+    end
+  end
+end