codebase_index 0.1.0

data/lib/codebase_index/ruby_analyzer.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative 'ast'
+require_relative 'extracted_unit'
+require_relative 'ruby_analyzer/class_analyzer'
+require_relative 'ruby_analyzer/method_analyzer'
+require_relative 'ruby_analyzer/dataflow_analyzer'
+require_relative 'ruby_analyzer/trace_enricher'
+
+module CodebaseIndex
+  # Analyzes plain Ruby source code and produces ExtractedUnit objects.
+  #
+  # Orchestrates ClassAnalyzer, MethodAnalyzer, DataFlowAnalyzer, and
+  # optional TraceEnricher to extract structured data from Ruby files.
+  #
+  # @example Analyze gem source
+  #   units = CodebaseIndex::RubyAnalyzer.analyze(paths: ["lib/"])
+  #   units.select { |u| u.type == :ruby_class }.map(&:identifier)
+  #
+  module RubyAnalyzer
+    class << self
+      # Analyze Ruby source files and produce ExtractedUnit objects.
+      #
+      # @param paths [Array<String>] File paths or directories to analyze
+      # @param trace_data [Array<Hash>, nil] Optional runtime trace data for enrichment
+      # @return [Array<ExtractedUnit>] All extracted units
+      def analyze(paths:, trace_data: nil)
+        files = discover_files(paths)
+        return [] if files.empty?
+
+        parser = Ast::Parser.new
+        class_analyzer = ClassAnalyzer.new(parser: parser)
+        method_analyzer = MethodAnalyzer.new(parser: parser)
+        dataflow_analyzer = DataFlowAnalyzer.new(parser: parser)
+
+        units = []
+
+        files.each do |file_path|
+          source = read_file(file_path)
+          next unless source
+
+          units.concat(class_analyzer.analyze(source: source, file_path: file_path))
+          units.concat(method_analyzer.analyze(source: source, file_path: file_path))
+        rescue CodebaseIndex::ExtractionError
+          # Skip files that fail to parse
+          next
+        end
+
+        dataflow_analyzer.annotate(units)
+        TraceEnricher.merge(units: units, trace_data: trace_data) if trace_data
+
+        units
+      end
+
+      private
+
+      # Discover .rb files from a list of paths (files and/or directories).
+      #
+      # @param paths [Array<String>] File paths or directory paths
+      # @return [Array<String>] Absolute paths to .rb files
+      def discover_files(paths)
+        files = []
+        paths.each do |path|
+          expanded = File.expand_path(path)
+          if File.directory?(expanded)
+            Dir.glob(File.join(expanded, '**', '*.rb')).each do |f|
+              files << f
+            end
+          elsif File.file?(expanded) && expanded.end_with?('.rb')
+            files << expanded
+          end
+        end
+        files.uniq
+      end
+
+      # Read a file safely, returning nil on failure.
+      #
+      # @param path [String] File path
+      # @return [String, nil] File contents or nil
+      def read_file(path)
+        File.read(path)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/codebase_index/session_tracer/file_store.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+require_relative 'store'
+
+module CodebaseIndex
+  module SessionTracer
+    # File-backed session store using JSONL (one JSON object per line).
+    #
+    # Sessions are stored as individual files in a configurable directory:
+    #   {base_dir}/{session_id}.jsonl
+    #
+    # Append-only with file locking for concurrency safety. Zero external dependencies.
+    #
+    # @example
+    #   store = FileStore.new(base_dir: "tmp/codebase_index/sessions")
+    #   store.record("abc123", { controller: "PostsController", action: "create" })
+    #   store.read("abc123") # => [{ "controller" => "PostsController", ... }]
+    #
+    class FileStore < Store
+      # @param base_dir [String] Directory for session JSONL files
+      def initialize(base_dir:)
+        super()
+        @base_dir = base_dir
+        FileUtils.mkdir_p(@base_dir)
+      end
+
+      # Append a request record to a session's JSONL file.
+      #
+      # Uses file locking (LOCK_EX) for concurrency safety.
+      #
+      # @param session_id [String] The session identifier
+      # @param request_data [Hash] Request metadata to store
+      # @return [void]
+      def record(session_id, request_data)
+        path = session_path(session_id)
+        line = "#{JSON.generate(request_data)}\n"
+
+        File.open(path, 'a') do |f|
+          f.flock(File::LOCK_EX)
+          f.write(line)
+        end
+      end
+
+      # Read all request records for a session, ordered by file line order (timestamp).
+      #
+      # @param session_id [String] The session identifier
+      # @return [Array<Hash>] Request records, oldest first
+      def read(session_id)
+        path = session_path(session_id)
+        return [] unless File.exist?(path)
+
+        File.readlines(path).filter_map do |line|
+          stripped = line.strip
+          next if stripped.empty?
+
+          JSON.parse(stripped)
+        rescue JSON::ParserError
+          nil
+        end
+      end
+
+      # List recent session summaries, sorted by last modification time (newest first).
+      #
+      # @param limit [Integer] Maximum number of sessions to return
+      # @return [Array<Hash>] Session summaries
+      def sessions(limit: 20)
+        pattern = File.join(@base_dir, '*.jsonl')
+        files = Dir.glob(pattern).sort_by { |f| -File.mtime(f).to_f }
+
+        files.first(limit).map do |file|
+          session_id = File.basename(file, '.jsonl')
+          requests = read(session_id)
+
+          {
+            'session_id' => session_id,
+            'request_count' => requests.size,
+            'first_request' => requests.first&.fetch('timestamp', nil),
+            'last_request' => requests.last&.fetch('timestamp', nil)
+          }
+        end
+      end
+
+      # Remove all data for a single session.
+      #
+      # @param session_id [String] The session identifier
+      # @return [void]
+      def clear(session_id)
+        path = session_path(session_id)
+        FileUtils.rm_f(path)
+      end
+
+      # Remove all session data.
+      #
+      # @return [void]
+      def clear_all
+        pattern = File.join(@base_dir, '*.jsonl')
+        Dir.glob(pattern).each { |f| File.delete(f) }
+      end
+
+      private
+
+      # @param session_id [String]
+      # @return [String] Full path to the session's JSONL file
+      def session_path(session_id)
+        File.join(@base_dir, "#{sanitize_session_id(session_id)}.jsonl")
+      end
+    end
+  end
+end

data/lib/codebase_index/session_tracer/middleware.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module CodebaseIndex
+  module SessionTracer
+    # Rack middleware that captures request metadata for session tracing.
+    #
+    # Wraps `@app.call(env)`, records after response. Extracts controller/action
+    # from `env['action_dispatch.request.path_parameters']`. Session ID from
+    # `X-Trace-Session` header first, falls back to `request.session.id`.
+    #
+    # Fire-and-forget writes — `rescue StandardError` on recording, never breaks the request.
+    #
+    # @example Inserting into a Rails middleware stack
+    #   app.middleware.insert_after ActionDispatch::Session::CookieStore,
+    #                               CodebaseIndex::SessionTracer::Middleware
+    #
+    class Middleware
+      # @param app [#call] The downstream Rack application
+      # @param store [Store] Session trace store backend
+      # @param session_id_proc [Proc, nil] Custom session ID extraction (receives env)
+      # @param exclude_paths [Array<String>] Path prefixes to skip
+      def initialize(app, store:, session_id_proc: nil, exclude_paths: [])
+        @app = app
+        @store = store
+        @session_id_proc = session_id_proc
+        @exclude_paths = exclude_paths
+      end
+
+      # @param env [Hash] Rack environment
+      # @return [Array] Rack response triple [status, headers, body]
+      def call(env)
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+        status, headers, body = @app.call(env)
+        duration_ms = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond) - start_time
+
+        begin
+          record_request(env, status, duration_ms)
+        rescue StandardError
+          # Fire-and-forget — recording failures never break the request
+        end
+
+        [status, headers, body]
+      end
+
+      private
+
+      # Record the request metadata to the store.
+      #
+      # @param env [Hash] Rack environment
+      # @param status [Integer] HTTP response status
+      # @param duration_ms [Integer] Request duration in milliseconds
+      # rubocop:disable Metrics/MethodLength
+      def record_request(env, status, duration_ms)
+        path = env['PATH_INFO'] || ''
+        return if excluded?(path)
+
+        session_id = extract_session_id(env)
+        return unless session_id
+
+        path_params = env['action_dispatch.request.path_parameters'] || {}
+        controller = path_params[:controller]
+        action = path_params[:action]
+        return unless controller
+
+        # Classify controller name (e.g., "orders" -> "OrdersController")
+        controller_class = classify_controller(controller)
+
+        request_data = {
+          'session_id' => session_id,
+          'trace_tag' => env['HTTP_X_TRACE_SESSION'],
+          'timestamp' => Time.now.utc.iso8601,
+          'method' => env['REQUEST_METHOD'],
+          'path' => path,
+          'controller' => controller_class,
+          'action' => action.to_s,
+          'status' => status.to_i,
+          'duration_ms' => duration_ms.to_i,
+          'format' => extract_format(env)
+        }
+
+        @store.record(session_id, request_data)
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Extract session ID: X-Trace-Session header first, then session cookie, then fallback.
+      #
+      # @param env [Hash] Rack environment
+      # @return [String, nil] Session identifier
+      def extract_session_id(env)
+        return @session_id_proc.call(env) if @session_id_proc
+
+        # 1. X-Trace-Session header (explicit trace tag doubles as session ID)
+        trace_header = env['HTTP_X_TRACE_SESSION']
+        return trace_header if trace_header && !trace_header.empty?
+
+        # 2. Rack session ID
+        session = env['rack.session']
+        session_id = session&.id || session&.dig('session_id')
+        return session_id.to_s if session_id
+
+        nil
+      end
+
+      # Check if the path should be excluded from tracing.
+      #
+      # @param path [String] Request path
+      # @return [Boolean]
+      def excluded?(path)
+        @exclude_paths.any? { |prefix| path.start_with?(prefix) }
+      end
+
+      # Classify a Rails controller path segment into a controller class name.
+      #
+      # @param controller [String] e.g., "orders" or "admin/orders"
+      # @return [String] e.g., "OrdersController" or "Admin::OrdersController"
+      def classify_controller(controller)
+        parts = controller.to_s
+                          .split('/')
+                          .map { |segment| segment.split('_').map(&:capitalize).join }
+        "#{parts.join('::')}Controller"
+      end
+
+      # Extract response format from the Rack env.
+      #
+      # @param env [Hash] Rack environment
+      # @return [String] Format string (e.g., "html", "json")
+      def extract_format(env)
+        # Check action_dispatch format first
+        path_params = env['action_dispatch.request.path_parameters'] || {}
+        return path_params[:format].to_s if path_params[:format]
+
+        # Infer from content type or Accept header
+        accept = env['HTTP_ACCEPT'] || ''
+        return 'json' if accept.include?('application/json')
+        return 'html' if accept.include?('text/html')
+
+        'html'
+      end
+    end
+  end
+end

data/lib/codebase_index/session_tracer/redis_store.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'store'
+
+module CodebaseIndex
+  module SessionTracer
+    # Redis-backed session store using Lists.
+    #
+    # Each session is stored as a Redis List keyed `codebase_index:session:{id}`.
+    # RPUSH per request for append-only ordering. Native TTL for automatic cleanup.
+    #
+    # Requires the `redis` gem at runtime.
+    #
+    # @example
+    #   store = RedisStore.new(redis: Redis.new, ttl: 3600)
+    #   store.record("abc123", { controller: "OrdersController", action: "create" })
+    #
+    class RedisStore < Store
+      KEY_PREFIX = 'codebase_index:session:'
+      SESSIONS_KEY = 'codebase_index:sessions'
+
+      # @param redis [Redis] A Redis client instance
+      # @param ttl [Integer, nil] Time-to-live in seconds for session keys (nil = no expiry)
+      def initialize(redis:, ttl: nil)
+        super()
+        unless defined?(::Redis)
+          raise SessionTracerError, 'The redis gem is required for RedisStore. Add `gem "redis"` to your Gemfile.'
+        end
+
+        @redis = redis
+        @ttl = ttl
+      end
+
+      # Append a request record to a session's Redis List.
+      #
+      # @param session_id [String] The session identifier
+      # @param request_data [Hash] Request metadata to store
+      # @return [void]
+      def record(session_id, request_data)
+        key = session_key(session_id)
+        @redis.rpush(key, JSON.generate(request_data))
+        @redis.expire(key, @ttl) if @ttl
+        @redis.sadd(SESSIONS_KEY, session_id)
+      end
+
+      # Read all request records for a session.
+      #
+      # @param session_id [String] The session identifier
+      # @return [Array<Hash>] Request records, oldest first
+      def read(session_id)
+        key = session_key(session_id)
+        @redis.lrange(key, 0, -1).filter_map do |json|
+          JSON.parse(json)
+        rescue JSON::ParserError
+          nil
+        end
+      end
+
+      # List recent session summaries.
+      #
+      # @param limit [Integer] Maximum number of sessions to return
+      # @return [Array<Hash>] Session summaries
+      def sessions(limit: 20)
+        all_ids = @redis.smembers(SESSIONS_KEY)
+
+        # Filter to sessions that still have data (TTL may have expired)
+        active = all_ids.select { |id| @redis.exists?(session_key(id)) }
+
+        # Remove expired session IDs from the set
+        expired = all_ids - active
+        expired.each { |id| @redis.srem(SESSIONS_KEY, id) } if expired.any?
+
+        active.first(limit).map do |session_id|
+          requests = read(session_id)
+          {
+            'session_id' => session_id,
+            'request_count' => requests.size,
+            'first_request' => requests.first&.fetch('timestamp', nil),
+            'last_request' => requests.last&.fetch('timestamp', nil)
+          }
+        end
+      end
+
+      # Remove all data for a single session.
+      #
+      # @param session_id [String] The session identifier
+      # @return [void]
+      def clear(session_id)
+        @redis.del(session_key(session_id))
+        @redis.srem(SESSIONS_KEY, session_id)
+      end
+
+      # Remove all session data.
+      #
+      # @return [void]
+      def clear_all
+        all_ids = @redis.smembers(SESSIONS_KEY)
+        all_ids.each { |id| @redis.del(session_key(id)) }
+        @redis.del(SESSIONS_KEY)
+      end
+
+      private
+
+      # @param session_id [String]
+      # @return [String] Redis key for this session
+      def session_key(session_id)
+        "#{KEY_PREFIX}#{sanitize_session_id(session_id)}"
+      end
+    end
+  end
+end