codebase_index 0.1.0

data/lib/codebase_index/builder.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative 'retriever'
+require_relative 'storage/vector_store'
+require_relative 'storage/pgvector'
+require_relative 'storage/qdrant'
+require_relative 'storage/metadata_store'
+require_relative 'storage/graph_store'
+require_relative 'embedding/provider'
+require_relative 'embedding/openai'
+
+module CodebaseIndex
+  # Builder reads a {Configuration} and instantiates the appropriate adapters,
+  # returning a fully wired {Retriever} ready for use.
+  #
+  # Named presets are provided for common deployment scenarios. All presets can
+  # be further customized with a block passed to {CodebaseIndex.configure_with_preset}.
+  #
+  # @example Using a preset
+  #   CodebaseIndex.configure_with_preset(:local)
+  #   result = CodebaseIndex.retrieve("How does the User model work?")
+  #
+  # @example Using a preset with block customization
+  #   CodebaseIndex.configure_with_preset(:production) do |config|
+  #     config.embedding_options = { api_key: ENV['OPENAI_API_KEY'] }
+  #     config.vector_store_options = { url: ENV['QDRANT_URL'], collection: 'myapp' }
+  #   end
+  #
+  class Builder
+    # Named presets mapping to default adapter types.
+    #
+    # :local      — fully local, no external services required
+    # :postgresql — pgvector for vectors, OpenAI for embeddings
+    # :production — Qdrant for vectors, OpenAI for embeddings
+    PRESETS = {
+      local: {
+        vector_store: :in_memory,
+        metadata_store: :sqlite,
+        graph_store: :in_memory,
+        embedding_provider: :ollama
+      },
+      postgresql: {
+        vector_store: :pgvector,
+        metadata_store: :sqlite,
+        graph_store: :in_memory,
+        embedding_provider: :openai
+      },
+      production: {
+        vector_store: :qdrant,
+        metadata_store: :sqlite,
+        graph_store: :in_memory,
+        embedding_provider: :openai
+      }
+    }.freeze
+
+    # Build a {Configuration} populated with the named preset's adapter types.
+    #
+    # @param name [Symbol] Preset name — one of :local, :postgresql, or :production
+    # @return [Configuration] A new Configuration with preset values applied
+    # @raise [ArgumentError] if the preset name is not recognized
+    def self.preset_config(name)
+      preset = PRESETS.fetch(name) do
+        raise ArgumentError, "Unknown preset: #{name}. Valid: #{PRESETS.keys.join(', ')}"
+      end
+      config = Configuration.new
+      preset.each { |key, value| config.public_send(:"#{key}=", value) }
+      config
+    end
+
+    # @param config [Configuration] Configuration to read adapter types from
+    def initialize(config = CodebaseIndex.configuration)
+      @config = config
+    end
+
+    # Build a {Retriever} wired with adapters from the configuration.
+    #
+    # @return [Retriever] A fully instantiated, wired retriever
+    def build_retriever
+      Retriever.new(
+        vector_store: build_vector_store,
+        metadata_store: build_metadata_store,
+        graph_store: build_graph_store,
+        embedding_provider: build_embedding_provider
+      )
+    end
+
+    # Instantiate the vector store adapter specified by the configuration.
+    #
+    # @return [Storage::VectorStore::Interface] Vector store adapter instance
+    # @raise [ArgumentError] if the configured type is not recognized
+    def build_vector_store
+      case @config.vector_store
+      when :in_memory then Storage::VectorStore::InMemory.new
+      when :pgvector then Storage::VectorStore::Pgvector.new(**(@config.vector_store_options || {}))
+      when :qdrant then Storage::VectorStore::Qdrant.new(**(@config.vector_store_options || {}))
+      else raise ArgumentError, "Unknown vector_store: #{@config.vector_store}"
+      end
+    end
+
+    # Instantiate the embedding provider specified by the configuration.
+    #
+    # @return [Embedding::Provider::Interface] Embedding provider instance
+    # @raise [ArgumentError] if the configured type is not recognized
+    def build_embedding_provider
+      case @config.embedding_provider
+      when :openai then Embedding::Provider::OpenAI.new(**(@config.embedding_options || {}))
+      when :ollama then Embedding::Provider::Ollama.new(**(@config.embedding_options || {}))
+      else raise ArgumentError, "Unknown embedding_provider: #{@config.embedding_provider}"
+      end
+    end
+
+    private
+
+    # Instantiate the metadata store adapter specified by the configuration.
+    #
+    # @return [Storage::MetadataStore::Interface] Metadata store adapter instance
+    # @raise [ArgumentError] if the configured type is not recognized
+    def build_metadata_store
+      case @config.metadata_store
+      when :in_memory then Storage::MetadataStore::InMemory.new
+      when :sqlite then Storage::MetadataStore::SQLite.new(**(@config.metadata_store_options || {}))
+      else raise ArgumentError, "Unknown metadata_store: #{@config.metadata_store}"
+      end
+    end
+
+    # Instantiate the graph store adapter specified by the configuration.
+    #
+    # @return [Storage::GraphStore::Interface] Graph store adapter instance
+    # @raise [ArgumentError] if the configured type is not recognized
+    def build_graph_store
+      case @config.graph_store
+      when :in_memory then Storage::GraphStore::Memory.new
+      else raise ArgumentError, "Unknown graph_store: #{@config.graph_store}"
+      end
+    end
+  end
+end

data/lib/codebase_index/chunking/chunk.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module CodebaseIndex
+  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/codebase_index/chunking/semantic_chunker.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+require_relative 'chunk'
+
+module CodebaseIndex
+  module Chunking
+    # 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
+      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,
+        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
+
+      # @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),
+    # then one chunk per public action method.
+    #
+    # @api private
+    class ControllerChunker
+      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)
+        @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
+
+      # @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/cache_adapter.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module CodebaseIndex
+  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/codebase_index/console/adapters/good_job_adapter.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module CodebaseIndex
+  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
+        # Check if GoodJob is available in the current environment.
+        #
+        # @return [Boolean]
+        def self.available?
+          defined?(::GoodJob) ? true : false
+        end
+
+        # Get queue statistics (sizes, latencies).
+        #
+        # @return [Hash] Bridge request
+        def queue_stats
+          { tool: 'good_job_queue_stats', params: {} }
+        end
+
+        # 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 } }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module CodebaseIndex
+  module Console
+    module Adapters
+      # Job backend adapter for Sidekiq.
+      #
+      # Builds bridge requests for Sidekiq queue stats, failure listing,
+      # job lookup, scheduled jobs, and retry operations.
+      #
+      # @example
+      #   adapter = SidekiqAdapter.new
+      #   adapter.queue_stats  # => { tool: 'sidekiq_queue_stats', params: {} }
+      #
+      class SidekiqAdapter
+        # Check if Sidekiq is available in the current environment.
+        #
+        # @return [Boolean]
+        def self.available?
+          defined?(::Sidekiq) ? true : false
+        end
+
+        # Get queue statistics (sizes, latencies).
+        #
+        # @return [Hash] Bridge request
+        def queue_stats
+          { tool: 'sidekiq_queue_stats', params: {} }
+        end
+
+        # 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: 'sidekiq_recent_failures', params: { limit: limit } }
+        end
+
+        # Find a job by its ID.
+        #
+        # @param id [String] Sidekiq job ID
+        # @return [Hash] Bridge request
+        def find_job(id:)
+          { tool: 'sidekiq_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: 'sidekiq_scheduled_jobs', params: { limit: limit } }
+        end
+
+        # Retry a failed job.
+        #
+        # @param id [String] Sidekiq job ID
+        # @return [Hash] Bridge request
+        def retry_job(id:)
+          { tool: 'sidekiq_retry_job', params: { id: id } }
+        end
+      end
+    end
+  end
+end