codebase_index 0.1.0

data/lib/codebase_index/evaluation/query_set.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module CodebaseIndex
+  module Evaluation
+    # Manages a set of evaluation queries with expected results.
+    #
+    # Each query has a natural language question, a list of expected unit
+    # identifiers (ground truth), an intent classification, scope, and tags
+    # for filtering. QuerySets can be loaded from and saved to JSON files.
+    #
+    # @example
+    #   qs = QuerySet.load("spec/fixtures/eval_queries.json")
+    #   qs.queries.each { |q| puts q.query }
+    #   qs.filter(intent: :lookup).size
+    #
+    class QuerySet
+      # A single evaluation query with ground-truth annotations.
+      #
+      # @!attribute [r] query
+      #   @return [String] Natural language query
+      # @!attribute [r] expected_units
+      #   @return [Array<String>] Expected unit identifiers (ground truth)
+      # @!attribute [r] intent
+      #   @return [Symbol] Query intent (:lookup, :trace, :explain, :compare)
+      # @!attribute [r] scope
+      #   @return [Symbol] Query scope (:specific, :bounded, :broad)
+      # @!attribute [r] tags
+      #   @return [Array<String>] Tags for filtering queries
+      Query = Struct.new(:query, :expected_units, :intent, :scope, :tags, keyword_init: true)
+
+      VALID_INTENTS = %i[lookup trace explain compare].freeze
+      VALID_SCOPES = %i[specific bounded broad].freeze
+
+      # @return [Array<Query>] The queries in this set
+      attr_reader :queries
+
+      # Initialize a QuerySet with an array of queries.
+      #
+      # @param queries [Array<Query>] Evaluation queries
+      def initialize(queries: [])
+        @queries = queries
+      end
+
+      # Load a QuerySet from a JSON file.
+      #
+      # @param path [String] Path to JSON file
+      # @return [QuerySet] Loaded query set
+      # @raise [CodebaseIndex::Error] if the file cannot be read or parsed
+      def self.load(path)
+        data = JSON.parse(File.read(path))
+        queries = data.fetch('queries', []).map { |q| parse_query(q) }
+        new(queries: queries)
+      rescue JSON::ParserError => e
+        raise CodebaseIndex::Error, "Invalid JSON in query set: #{e.message}"
+      rescue Errno::ENOENT => e
+        raise CodebaseIndex::Error, "Query set file not found: #{e.message}"
+      end
+
+      # Save this QuerySet to a JSON file.
+      #
+      # @param path [String] Path to write JSON file
+      # @return [void]
+      def save(path)
+        data = {
+          'queries' => queries.map { |q| serialize_query(q) }
+        }
+        File.write(path, JSON.pretty_generate(data))
+      end
+
+      # Filter queries by intent, scope, or tags.
+      #
+      # @param intent [Symbol, nil] Filter by intent
+      # @param scope [Symbol, nil] Filter by scope
+      # @param tags [Array<String>, nil] Filter by tags (any match)
+      # @return [Array<Query>] Matching queries
+      def filter(intent: nil, scope: nil, tags: nil)
+        result = queries
+        result = result.select { |q| q.intent == intent } if intent
+        result = result.select { |q| q.scope == scope } if scope
+        result = result.select { |q| (q.tags & tags).any? } if tags
+        result
+      end
+
+      # Add a query to this set.
+      #
+      # @param query [Query] Query to add
+      # @return [void]
+      # @raise [ArgumentError] if intent or scope is invalid
+      def add(query)
+        validate_query!(query)
+        @queries << query
+      end
+
+      # Number of queries in this set.
+      #
+      # @return [Integer]
+      def size
+        @queries.size
+      end
+
+      private
+
+      # Parse a query hash from JSON into a Query struct.
+      #
+      # @param hash [Hash] Raw query data
+      # @return [Query]
+      def self.parse_query(hash)
+        Query.new(
+          query: hash.fetch('query'),
+          expected_units: hash.fetch('expected_units', []),
+          intent: hash.fetch('intent', 'lookup').to_sym,
+          scope: hash.fetch('scope', 'specific').to_sym,
+          tags: hash.fetch('tags', [])
+        )
+      end
+
+      private_class_method :parse_query
+
+      # Serialize a Query to a hash for JSON output.
+      #
+      # @param query [Query] Query to serialize
+      # @return [Hash]
+      def serialize_query(query)
+        {
+          'query' => query.query,
+          'expected_units' => query.expected_units,
+          'intent' => query.intent.to_s,
+          'scope' => query.scope.to_s,
+          'tags' => query.tags
+        }
+      end
+
+      # Validate intent and scope values.
+      #
+      # @param query [Query] Query to validate
+      # @raise [ArgumentError] if intent or scope is invalid
+      def validate_query!(query)
+        unless VALID_INTENTS.include?(query.intent)
+          raise ArgumentError, "Invalid intent: #{query.intent}. Must be one of #{VALID_INTENTS.join(', ')}"
+        end
+
+        return if VALID_SCOPES.include?(query.scope)
+
+        raise ArgumentError, "Invalid scope: #{query.scope}. Must be one of #{VALID_SCOPES.join(', ')}"
+      end
+    end
+  end
+end

data/lib/codebase_index/evaluation/report_generator.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module CodebaseIndex
+  module Evaluation
+    # Generates JSON reports from evaluation results.
+    #
+    # Takes an EvaluationReport and produces a structured JSON document
+    # with per-query scores, aggregate metrics, and metadata.
+    #
+    # @example
+    #   generator = ReportGenerator.new
+    #   json = generator.generate(report)
+    #   generator.save(report, "tmp/eval_report.json")
+    #
+    class ReportGenerator
+      # Generate a JSON string from an evaluation report.
+      #
+      # @param report [Evaluator::EvaluationReport] Evaluation report
+      # @param metadata [Hash] Optional metadata to include
+      # @return [String] Pretty-printed JSON
+      def generate(report, metadata: {})
+        data = build_report_hash(report, metadata)
+        JSON.pretty_generate(data)
+      end
+
+      # Save an evaluation report to a JSON file.
+      #
+      # @param report [Evaluator::EvaluationReport] Evaluation report
+      # @param path [String] Output file path
+      # @param metadata [Hash] Optional metadata to include
+      # @return [void]
+      def save(report, path, metadata: {})
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, generate(report, metadata: metadata))
+      end
+
+      private
+
+      # Build the complete report hash.
+      #
+      # @param report [Evaluator::EvaluationReport] Evaluation report
+      # @param metadata [Hash] Additional metadata
+      # @return [Hash]
+      def build_report_hash(report, metadata)
+        {
+          'metadata' => build_metadata(metadata),
+          'aggregates' => serialize_aggregates(report.aggregates),
+          'results' => report.results.map { |r| serialize_result(r) }
+        }
+      end
+
+      # Build the metadata section.
+      #
+      # @param extra [Hash] Additional metadata
+      # @return [Hash]
+      def build_metadata(extra)
+        {
+          'generated_at' => Time.now.iso8601,
+          'version' => defined?(CodebaseIndex::VERSION) ? CodebaseIndex::VERSION : 'unknown'
+        }.merge(extra.transform_keys(&:to_s))
+      end
+
+      # Serialize aggregate metrics.
+      #
+      # @param aggregates [Hash] Aggregate metrics with symbol keys
+      # @return [Hash] String-keyed hash
+      def serialize_aggregates(aggregates)
+        aggregates.transform_keys(&:to_s).transform_values do |v|
+          v.is_a?(Float) ? v.round(4) : v
+        end
+      end
+
+      # Serialize a single query result.
+      #
+      # @param result [Evaluator::QueryResult] Query result
+      # @return [Hash]
+      def serialize_result(result)
+        {
+          'query' => result.query,
+          'expected_units' => result.expected_units,
+          'retrieved_units' => result.retrieved_units,
+          'scores' => result.scores.transform_keys(&:to_s).transform_values { |v| v.round(4) },
+          'tokens_used' => result.tokens_used
+        }
+      end
+    end
+  end
+end

data/lib/codebase_index/extracted_unit.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+
+module CodebaseIndex
+  # ExtractedUnit represents a single meaningful unit of code from the codebase.
+  #
+  # This could be a model, controller, service, component, or framework source.
+  # Each unit is self-contained with its source code, metadata, and relationship
+  # information. Units are serialized to JSON for consumption by the indexing pipeline.
+  #
+  # @example Creating a model unit
+  #   unit = ExtractedUnit.new(
+  #     type: :model,
+  #     identifier: "User",
+  #     file_path: "app/models/user.rb"
+  #   )
+  #   unit.source_code = File.read(unit.file_path)
+  #   unit.metadata = { associations: [...], callbacks: [...] }
+  #   unit.dependencies = [{ type: :service, target: "UserService" }]
+  #
+  class ExtractedUnit
+    attr_accessor :type,           # Symbol: :model, :controller, :service, :component, :job, :rails_source, :gem_source
+                  :identifier,     # String: Unique key, e.g., "User", "Users::RegistrationsController#create"
+                  :file_path,      # String: Absolute path to source file
+                  :namespace,      # String: Module namespace if any
+                  :source_code,    # String: The actual code, with concerns inlined for models
+                  :metadata,       # Hash: Type-specific structured data
+                  :dependencies,   # Array<Hash>: What this unit calls/references
+                  :dependents,     # Array<Hash>: What references this unit (populated in second pass)
+                  :chunks          # Array<Hash>: Pre-chunked versions if unit is large
+
+    def initialize(type:, identifier:, file_path:)
+      @type = type
+      @identifier = identifier
+      @file_path = file_path
+      @metadata = {}
+      @dependencies = []
+      @dependents = []
+      @chunks = []
+    end
+
+    # Serialize to hash for JSON output
+    #
+    # @return [Hash] Complete unit data for indexing pipeline
+    def to_h
+      {
+        type: type,
+        identifier: identifier,
+        file_path: file_path,
+        namespace: namespace,
+        source_code: source_code,
+        metadata: metadata,
+        dependencies: dependencies,
+        dependents: dependents,
+        chunks: chunks,
+        extracted_at: Time.now.iso8601,
+        source_hash: Digest::SHA256.hexdigest(source_code || '')
+      }
+    end
+
+    # Estimate token count for chunking decisions.
+    # Benchmarked against tiktoken (cl100k_base) on 19 Ruby source files.
+    # Actual mean is 4.41 chars/token. Uses 4.0 as a conservative floor
+    # (~10.6% overestimate). See docs/TOKEN_BENCHMARK.md.
+    #
+    # @return [Integer] Estimated token count
+    def estimated_tokens
+      source_tokens = source_code ? (source_code.length / 4.0).ceil : 0
+      metadata_tokens = metadata.any? ? (metadata.to_json.length / 4.0).ceil : 0
+      source_tokens + metadata_tokens
+    end
+
+    # Check if unit needs chunking based on size
+    #
+    # @param threshold [Integer] Token threshold for chunking (default: 1500)
+    # @return [Boolean]
+    def needs_chunking?(threshold: 1500)
+      estimated_tokens > threshold
+    end
+
+    # Build semantic chunks for large units
+    # Preserves context by including unit header in each chunk
+    #
+    # @param max_tokens [Integer] Maximum tokens per chunk
+    # @return [Array<Hash>] List of chunk hashes
+    def build_default_chunks(max_tokens: 1500)
+      return [] unless needs_chunking?
+
+      chunks = []
+      current_chunk = []
+      current_tokens = 0
+
+      # Always include a header with unit context
+      header = build_chunk_header
+      header_tokens = (header.length / 4.0).ceil
+
+      source_code.lines.each do |line|
+        line_tokens = (line.length / 4.0).ceil
+
+        if current_tokens + line_tokens > max_tokens && current_chunk.any?
+          content = header + current_chunk.join
+          chunks << {
+            chunk_index: chunks.size,
+            identifier: "#{identifier}#chunk_#{chunks.size}",
+            content: content,
+            content_hash: Digest::SHA256.hexdigest(content),
+            estimated_tokens: current_tokens + header_tokens
+          }
+          current_chunk = []
+          current_tokens = 0
+        end
+
+        current_chunk << line
+        current_tokens += line_tokens
+      end
+
+      # Final chunk
+      if current_chunk.any?
+        content = header + current_chunk.join
+        chunks << {
+          chunk_index: chunks.size,
+          identifier: "#{identifier}#chunk_#{chunks.size}",
+          content: content,
+          content_hash: Digest::SHA256.hexdigest(content),
+          estimated_tokens: current_tokens + header_tokens
+        }
+      end
+
+      chunks
+    end
+
+    private
+
+    def build_chunk_header
+      <<~HEADER
+        # Unit: #{identifier} (#{type})
+        # File: #{file_path}
+        # Namespace: #{namespace || '(root)'}
+        # ---
+      HEADER
+    end
+  end
+end