codebase_index 0.2.1 → 0.3.1

data/lib/codebase_index/cache/cache_store.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+require 'logger'
+
+module CodebaseIndex
+  module Cache
+    # Default TTLs (in seconds) for each cache domain.
+    #
+    # Embedding vectors are stable (same text → same vector) so they get 24h.
+    # Metadata and structural context refresh on re-extraction (1h).
+    # Search results and formatted context are session-scoped (15min).
+    DEFAULT_TTLS = {
+      embeddings: 86_400,
+      metadata: 3_600,
+      structural: 3_600,
+      search: 900,
+      context: 900
+    }.freeze
+
+    # Build a namespaced cache key from a domain and raw parts.
+    #
+    # @param domain [Symbol] Cache domain (:embeddings, :metadata, etc.)
+    # @param parts [Array<String>] Key components (will be SHA256-hashed if long)
+    # @return [String] Namespaced key
+    def self.cache_key(domain, *parts)
+      raw = parts.join(':')
+      suffix = raw.length > 64 ? Digest::SHA256.hexdigest(raw) : raw
+      "codebase_index:cache:#{domain}:#{suffix}"
+    end
+
+    # Abstract cache store interface.
+    #
+    # All cache backends must implement these methods. The interface is modeled
+    # after ActiveSupport::Cache::Store for familiarity but kept minimal.
+    #
+    # @abstract Subclass and override all public methods.
+    class CacheStore
+      # Read a value from the cache.
+      #
+      # @param key [String] Cache key
+      # @return [Object, nil] Cached value or nil if missing/expired
+      def read(key)
+        raise NotImplementedError
+      end
+
+      # Write a value to the cache.
+      #
+      # @param key [String] Cache key
+      # @param value [Object] Value to cache (must be JSON-serializable)
+      # @param ttl [Integer, nil] Time-to-live in seconds (nil = use domain default)
+      # @return [void]
+      def write(key, value, ttl: nil)
+        raise NotImplementedError
+      end
+
+      # Delete a key from the cache.
+      #
+      # @param key [String] Cache key
+      # @return [void]
+      def delete(key)
+        raise NotImplementedError
+      end
+
+      # Check if a key exists and is not expired.
+      #
+      # @param key [String] Cache key
+      # @return [Boolean]
+      def exist?(key)
+        raise NotImplementedError
+      end
+
+      # Clear cached entries. If namespace is given, only clear that domain.
+      #
+      # @param namespace [Symbol, nil] Cache domain to clear, or nil for all
+      # @return [void]
+      def clear(namespace: nil)
+        raise NotImplementedError
+      end
+
+      # Read-through cache: return cached value or execute block and cache result.
+      #
+      # @note nil is treated as a cache miss. If the wrapped operation legitimately
+      #   returns nil, every call will re-execute the block. Custom backend
+      #   implementers should preserve this semantic — do not return nil for keys
+      #   that were written with a non-nil value. This is acceptable for the
+      #   built-in use cases (embeddings and formatted context are never nil).
+      #
+      # @param key [String] Cache key
+      # @param ttl [Integer, nil] TTL in seconds
+      # @yield Block that computes the value on cache miss
+      # @return [Object] Cached or freshly computed value
+      def fetch(key, ttl: nil)
+        cached = read(key)
+        return cached unless cached.nil?
+
+        value = yield
+        begin
+          write(key, value, ttl: ttl)
+        rescue StandardError => e
+          logger.warn("[CodebaseIndex] CacheStore#fetch write failed for #{key}: #{e.message}")
+        end
+        value
+      end
+
+      private
+
+      # Return a logger instance (Rails.logger in Rails apps, stderr elsewhere).
+      #
+      # @return [Logger]
+      def logger
+        @logger ||= defined?(Rails) ? Rails.logger : Logger.new($stderr)
+      end
+
+      # Build a wildcard pattern for clearing cache entries.
+      #
+      # @param namespace [Symbol, nil] Cache domain, or nil for all entries
+      # @return [String]
+      def clear_pattern(namespace)
+        namespace ? "codebase_index:cache:#{namespace}:*" : 'codebase_index:cache:*'
+      end
+
+      # Delete a key, silently swallowing any errors.
+      #
+      # Used for cleanup on corrupt/stale entries where failure is acceptable.
+      #
+      # @param key [String]
+      # @return [nil]
+      def delete_silently(key)
+        delete(key)
+      rescue StandardError
+        nil
+      end
+    end
+
+    # In-memory cache store with LRU eviction and TTL support.
+    #
+    # Zero external dependencies. Suitable for single-process use, development,
+    # and as a fallback when Redis/SolidCache are not available. Thread-safe.
+    #
+    # @example
+    #   store = InMemory.new(max_entries: 200)
+    #   store.write("ci:emb:abc", [0.1, 0.2], ttl: 3600)
+    #   store.read("ci:emb:abc") # => [0.1, 0.2]
+    #
+    class InMemory < CacheStore
+      # @param max_entries [Integer] Maximum cached entries before LRU eviction
+      def initialize(max_entries: 500)
+        super()
+        @max_entries = max_entries
+        @entries = {}
+        @access_order = []
+        @mutex = Mutex.new
+      end
+
+      # Read a value, returning nil if missing or expired.
+      #
+      # @param key [String] Cache key
+      # @return [Object, nil]
+      def read(key)
+        @mutex.synchronize do
+          entry = @entries[key]
+          return nil unless entry
+
+          if entry[:expires_at] && Time.now > entry[:expires_at]
+            evict_key(key)
+            return nil
+          end
+
+          touch(key)
+          entry[:value]
+        end
+      end
+
+      # Write a value with optional TTL.
+      #
+      # @param key [String] Cache key
+      # @param value [Object] Value to cache
+      # @param ttl [Integer, nil] TTL in seconds
+      # @return [void]
+      def write(key, value, ttl: nil)
+        @mutex.synchronize do
+          evict_key(key) if @entries.key?(key)
+
+          if @entries.size >= @max_entries
+            oldest = @access_order.shift
+            @entries.delete(oldest) if oldest
+          end
+
+          expires_at = ttl ? Time.now + ttl : nil
+          @entries[key] = { value: value, expires_at: expires_at }
+          @access_order.push(key)
+        end
+      end
+
+      # Delete a key.
+      #
+      # @param key [String] Cache key
+      # @return [void]
+      def delete(key)
+        @mutex.synchronize { evict_key(key) }
+      end
+
+      # Check if a key exists and is not expired.
+      #
+      # @param key [String] Cache key
+      # @return [Boolean]
+      def exist?(key)
+        @mutex.synchronize do
+          entry = @entries[key]
+          return false unless entry
+          return false if entry[:expires_at] && Time.now > entry[:expires_at]
+
+          true
+        end
+      end
+
+      # Clear entries. If namespace is given, only clear keys matching that domain.
+      #
+      # @param namespace [Symbol, nil] Domain to clear (:embeddings, :metadata, etc.)
+      # @return [void]
+      def clear(namespace: nil)
+        @mutex.synchronize do
+          if namespace
+            prefix = "codebase_index:cache:#{namespace}:"
+            keys_to_delete = @entries.keys.select { |k| k.start_with?(prefix) }
+            keys_to_delete.each { |k| evict_key(k) }
+          else
+            @entries.clear
+            @access_order.clear
+          end
+        end
+      end
+
+      # Number of entries currently in the cache (for testing/diagnostics).
+      #
+      # @return [Integer]
+      def size
+        @mutex.synchronize { @entries.size }
+      end
+
+      private
+
+      # Remove a key from both the entry hash and access order.
+      #
+      # @param key [String]
+      # @return [void]
+      def evict_key(key)
+        @entries.delete(key)
+        @access_order.delete(key)
+      end
+
+      # Move a key to the end of the access order (most recently used).
+      #
+      # @param key [String]
+      # @return [void]
+      def touch(key)
+        @access_order.delete(key)
+        @access_order.push(key)
+      end
+    end
+  end
+end

data/lib/codebase_index/cache/redis_cache_store.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'cache_store'
+
+module CodebaseIndex
+  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("[CodebaseIndex] 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("[CodebaseIndex] 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("[CodebaseIndex] 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("[CodebaseIndex] RedisCacheStore#exist? failed for #{key}: #{e.message}")
+        false
+      end
+
+      # Clear cached entries by namespace or all codebase_index 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("[CodebaseIndex] RedisCacheStore#clear failed: #{e.message}")
+        nil
+      end
+    end
+  end
+end

data/lib/codebase_index/cache/solid_cache_store.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'cache_store'
+
+module CodebaseIndex
+  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("[CodebaseIndex] 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("[CodebaseIndex] 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("[CodebaseIndex] 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("[CodebaseIndex] SolidCacheStore#exist? failed for #{key}: #{e.message}")
+        false
+      end
+
+      # Clear cached entries by namespace or all codebase_index 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("[CodebaseIndex] 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("[CodebaseIndex] SolidCacheStore#clear failed: #{e.message}")
+        nil
+      end
+    end
+  end
+end

data/lib/codebase_index/chunking/semantic_chunker.rb

@@ -4,6 +4,31 @@ require_relative 'chunk'
 
 module CodebaseIndex
   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,
@@ -62,13 +87,13 @@ module CodebaseIndex
     #
     # @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+:/
-      METHOD_PATTERN = /^\s*def\s+/
-      PRIVATE_PATTERN = /^\s*(private|protected)\s*$/
 
       SECTION_PATTERNS = {
         associations: ASSOCIATION_PATTERN,
@@ -181,16 +206,6 @@ module CodebaseIndex
           state[:sections][state[:current]] << line
         end
       end
-
-      # @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
 
     # Chunks a controller unit by actions: summary (class + filters),
@@ -198,9 +213,9 @@ module CodebaseIndex
     #
     # @api private
     class ControllerChunker
+      include ChunkBuilder
+
       FILTER_PATTERN = /^\s*(before_action|after_action|around_action|skip_before_action)\b/
-      METHOD_PATTERN = /^\s*def\s+/
-      PRIVATE_PATTERN = /^\s*(private|protected)\s*$/
 
       # @param unit [ExtractedUnit]
       def initialize(unit)
@@ -275,16 +290,6 @@ module CodebaseIndex
 
         chunks
       end
-
-      # @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
   end
 end

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'job_adapter'
+
 module CodebaseIndex
   module Console
     module Adapters
@@ -12,53 +14,18 @@ module CodebaseIndex
       #   adapter = GoodJobAdapter.new
       #   adapter.queue_stats  # => { tool: 'good_job_queue_stats', params: {} }
       #
-      class GoodJobAdapter
+      class GoodJobAdapter < JobAdapter
         # Check if GoodJob is available in the current environment.
         #
         # @return [Boolean]
         def self.available?
-          defined?(::GoodJob) ? true : false
+          !!defined?(::GoodJob)
         end
 
-        # Get queue statistics (sizes, latencies).
-        #
-        # @return [Hash] Bridge request
-        def queue_stats
-          { tool: 'good_job_queue_stats', params: {} }
-        end
+        private
 
-        # List recent job failures.
-        #
-        # @param limit [Integer] Max failures (default: 10, max: 100)
-        # @return [Hash] Bridge request
-        def recent_failures(limit: 10)
-          limit = [limit, 100].min
-          { tool: 'good_job_recent_failures', params: { limit: limit } }
-        end
-
-        # Find a job by its ID.
-        #
-        # @param id [Object] GoodJob job ID
-        # @return [Hash] Bridge request
-        def find_job(id:)
-          { tool: 'good_job_find_job', params: { id: id } }
-        end
-
-        # List scheduled jobs.
-        #
-        # @param limit [Integer] Max jobs (default: 20, max: 100)
-        # @return [Hash] Bridge request
-        def scheduled_jobs(limit: 20)
-          limit = [limit, 100].min
-          { tool: 'good_job_scheduled_jobs', params: { limit: limit } }
-        end
-
-        # Retry a failed job.
-        #
-        # @param id [Object] GoodJob job ID
-        # @return [Hash] Bridge request
-        def retry_job(id:)
-          { tool: 'good_job_retry_job', params: { id: id } }
+        def prefix
+          'good_job'
         end
       end
     end