codebase_index 0.1.0

data/lib/codebase_index/session_tracer/session_flow_assembler.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'set'
+require_relative 'session_flow_document'
+
+module CodebaseIndex
+  module SessionTracer
+    # Assembles a context tree from captured session requests against the extracted index.
+    #
+    # Does NOT require Rails — reads from a store + on-disk extracted index.
+    #
+    # Algorithm:
+    # 1. Load requests from store for session_id
+    # 2. For each request, resolve "Controller#action" via IndexReader
+    # 3. Expand dependencies via DependencyGraph — filter :job/:mailer as async side effects
+    # 4. Deduplicate units across steps (include source once, reference by identifier)
+    # 5. Token budget allocation with priority-based truncation
+    # 6. Build SessionFlowDocument
+    #
+    # @example
+    #   assembler = SessionFlowAssembler.new(store: store, reader: reader)
+    #   doc = assembler.assemble("abc123", budget: 8000, depth: 1)
+    #   puts doc.to_context
+    #
+    # rubocop:disable Metrics/ClassLength
+    class SessionFlowAssembler
+      ASYNC_TYPES = %w[job mailer].to_set.freeze
+
+      # @param store [Store] Session trace store
+      # @param reader [MCP::IndexReader] Index reader for unit lookups
+      def initialize(store:, reader:)
+        @store = store
+        @reader = reader
+      end
+
+      # Assemble a context tree for a session.
+      #
+      # @param session_id [String] The session to assemble
+      # @param budget [Integer] Maximum token budget (default: 8000)
+      # @param depth [Integer] Expansion depth (0=metadata only, 1=direct deps, 2+=full flow)
+      # @return [SessionFlowDocument] The assembled document
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+      def assemble(session_id, budget: 8000, depth: 1)
+        requests = @store.read(session_id)
+        return empty_document(session_id) if requests.empty?
+
+        steps = []
+        context_pool = {}
+        side_effects = []
+        dependency_map = {}
+        seen_units = Set.new
+
+        requests.each_with_index do |req, idx|
+          step = build_step(req, idx)
+          steps << step
+
+          next if depth.zero?
+
+          controller_id = req['controller']
+          next unless controller_id
+
+          # Resolve controller unit
+          unit = @reader.find_unit(controller_id)
+          if unit && !seen_units.include?(controller_id)
+            seen_units.add(controller_id)
+            context_pool[controller_id] = unit_summary(unit)
+          end
+          step[:unit_refs] = [controller_id].compact
+
+          # Expand dependencies
+          next unless unit
+
+          deps = resolve_dependencies(controller_id, seen_units, context_pool,
+                                      side_effects, step, dependency_map, depth)
+          step[:unit_refs].concat(deps)
+        end
+
+        # Apply token budget
+        token_count = apply_budget(context_pool, budget)
+
+        SessionFlowDocument.new(
+          session_id: session_id,
+          steps: steps,
+          context_pool: context_pool,
+          side_effects: side_effects,
+          dependency_map: dependency_map,
+          token_count: token_count
+        )
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+
+      private
+
+      # Build a timeline step from a request record.
+      #
+      # @param req [Hash] Request data from store
+      # @param index [Integer] Step index
+      # @return [Hash] Step hash
+      def build_step(req, index)
+        {
+          index: index,
+          method: req['method'],
+          path: req['path'],
+          controller: req['controller'],
+          action: req['action'],
+          status: req['status'],
+          duration_ms: req['duration_ms'],
+          unit_refs: [],
+          side_effects: []
+        }
+      end
+
+      # Resolve dependencies for a unit, separating sync deps from async side effects.
+      #
+      # @return [Array<String>] Non-async dependency identifiers added
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/ParameterLists, Metrics/PerceivedComplexity
+      def resolve_dependencies(unit_id, seen_units, context_pool,
+                               side_effects, step, dependency_map, depth)
+        graph = @reader.dependency_graph
+        dep_ids = graph.dependencies_of(unit_id)
+        added = []
+
+        dep_ids.each do |dep_id|
+          dep_unit = @reader.find_unit(dep_id)
+          next unless dep_unit
+
+          dep_type = dep_unit['type']&.to_s
+
+          if ASYNC_TYPES.include?(dep_type)
+            effect = {
+              type: dep_type.to_sym,
+              identifier: dep_id,
+              trigger_step: "#{step[:controller]}##{step[:action]}"
+            }
+            side_effects << effect
+            step[:side_effects] << effect
+          else
+            unless seen_units.include?(dep_id)
+              seen_units.add(dep_id)
+              context_pool[dep_id] = unit_summary(dep_unit)
+              added << dep_id
+
+              # Depth 2+: expand transitive dependencies
+              expand_transitive(dep_id, seen_units, context_pool, dependency_map, depth - 1) if depth >= 2
+            end
+          end
+        end
+
+        # Record dependency map for this unit
+        all_deps = dep_ids.select { |id| @reader.find_unit(id) }
+        dependency_map[unit_id] = all_deps if all_deps.any?
+
+        added
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/ParameterLists, Metrics/PerceivedComplexity
+
+      # Expand transitive dependencies (depth 2+).
+      #
+      # @param unit_id [String] Unit to expand from
+      # @param seen_units [Set<String>] Already-seen unit identifiers
+      # @param context_pool [Hash] Accumulator for unit data
+      # @param dependency_map [Hash] Accumulator for dependency edges
+      # @param remaining_depth [Integer] Remaining expansion depth
+      def expand_transitive(unit_id, seen_units, context_pool, dependency_map, remaining_depth)
+        return if remaining_depth <= 0
+
+        graph = @reader.dependency_graph
+        dep_ids = graph.dependencies_of(unit_id)
+        resolved_deps = []
+
+        dep_ids.each do |dep_id|
+          dep_unit = @reader.find_unit(dep_id)
+          next unless dep_unit
+
+          resolved_deps << dep_id
+          next if seen_units.include?(dep_id)
+
+          seen_units.add(dep_id)
+          context_pool[dep_id] = unit_summary(dep_unit)
+
+          expand_transitive(dep_id, seen_units, context_pool, dependency_map, remaining_depth - 1)
+        end
+
+        dependency_map[unit_id] = resolved_deps if resolved_deps.any?
+      end
+
+      # Extract a summary hash from a full unit data hash.
+      #
+      # @param unit [Hash] Full unit data from IndexReader
+      # @return [Hash] Summary with :type, :file_path, :source_code
+      def unit_summary(unit)
+        {
+          type: unit['type'],
+          file_path: unit['file_path'],
+          source_code: unit['source_code']
+        }
+      end
+
+      # Apply token budget by truncating source code from lowest-priority units.
+      #
+      # Priority order (highest first):
+      # 1. Controller action chunks (directly hit by requests)
+      # 2. Direct dependencies (models, services)
+      # 3. Transitive dependencies
+      #
+      # @param context_pool [Hash] Unit data to budget
+      # @param budget [Integer] Maximum tokens
+      # @return [Integer] Actual token count
+      def apply_budget(context_pool, budget)
+        total = estimate_tokens(context_pool)
+        return total if total <= budget
+
+        # Truncate from the end (lowest priority = last added)
+        identifiers = context_pool.keys.reverse
+        identifiers.each do |id|
+          break if total <= budget
+
+          unit = context_pool[id]
+          source = unit[:source_code]
+          next unless source
+
+          source_tokens = estimate_token_count(source)
+          unit[:source_code] = "# source truncated (#{source_tokens} tokens)"
+          total -= source_tokens
+          total += estimate_token_count(unit[:source_code])
+        end
+
+        [total, 0].max
+      end
+
+      # Estimate total tokens for the context pool.
+      #
+      # @param context_pool [Hash] Unit data
+      # @return [Integer] Estimated token count
+      def estimate_tokens(context_pool)
+        context_pool.values.sum do |unit|
+          source = unit[:source_code] || ''
+          estimate_token_count(source) + 20 # overhead for tags/metadata
+        end
+      end
+
+      # Estimate token count for a string.
+      # Uses project convention: (string.length / 4.0).ceil
+      # See docs/TOKEN_BENCHMARK.md — conservative floor (~10.6% overestimate).
+      #
+      # @param text [String] Text to estimate
+      # @return [Integer] Estimated token count
+      def estimate_token_count(text)
+        (text.length / 4.0).ceil
+      end
+
+      # Build an empty document for sessions with no requests.
+      #
+      # @param session_id [String]
+      # @return [SessionFlowDocument]
+      def empty_document(session_id)
+        SessionFlowDocument.new(session_id: session_id)
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/codebase_index/session_tracer/session_flow_document.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module CodebaseIndex
+  module SessionTracer
+    # Value object representing an assembled session flow trace.
+    #
+    # Contains a two-level structure:
+    # - **Timeline** — ordered steps with unit_refs and side_effects (lightweight)
+    # - **Context pool** — deduplicated ExtractedUnit data (heavy, included once each)
+    #
+    # Follows the FlowDocument pattern for serialization and rendering.
+    #
+    # @example
+    #   doc = SessionFlowDocument.new(
+    #     session_id: "abc123",
+    #     steps: [...],
+    #     context_pool: { "OrdersController" => { ... } },
+    #     generated_at: Time.now.utc.iso8601
+    #   )
+    #   doc.to_h         # => JSON-serializable Hash
+    #   doc.to_markdown   # => human-readable document
+    #   doc.to_context    # => LLM XML format
+    #
+    # rubocop:disable Metrics/ClassLength
+    class SessionFlowDocument
+      attr_reader :session_id, :steps, :context_pool, :side_effects,
+                  :dependency_map, :token_count, :generated_at
+
+      # @param session_id [String] The session identifier
+      # @param steps [Array<Hash>] Ordered timeline steps
+      # @param context_pool [Hash<String, Hash>] Deduplicated unit data keyed by identifier
+      # @param side_effects [Array<Hash>] Async side effects (jobs, mailers)
+      # @param dependency_map [Hash<String, Array<String>>] Unit -> dependency identifiers
+      # @param token_count [Integer] Estimated total tokens
+      # @param generated_at [String, nil] ISO8601 timestamp (defaults to now)
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(session_id:, steps: [], context_pool: {}, side_effects: [],
+                     dependency_map: {}, token_count: 0, generated_at: nil)
+        @session_id = session_id
+        @steps = steps
+        @context_pool = context_pool
+        @side_effects = side_effects
+        @dependency_map = dependency_map
+        @token_count = token_count
+        @generated_at = generated_at || Time.now.utc.iso8601
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      # Serialize to a JSON-compatible Hash.
+      #
+      # @return [Hash]
+      def to_h
+        {
+          session_id: @session_id,
+          generated_at: @generated_at,
+          token_count: @token_count,
+          steps: @steps,
+          context_pool: @context_pool,
+          side_effects: @side_effects,
+          dependency_map: @dependency_map
+        }
+      end
+
+      # Reconstruct from a serialized Hash.
+      #
+      # Handles both symbol and string keys for JSON round-trip compatibility.
+      #
+      # @param data [Hash] Previously serialized document data
+      # @return [SessionFlowDocument]
+      def self.from_h(data)
+        data = deep_symbolize_keys(data)
+
+        new(
+          session_id: data[:session_id],
+          steps: data[:steps] || [],
+          context_pool: data[:context_pool] || {},
+          side_effects: data[:side_effects] || [],
+          dependency_map: data[:dependency_map] || {},
+          token_count: data[:token_count] || 0,
+          generated_at: data[:generated_at]
+        )
+      end
+
+      # Render as human-readable Markdown.
+      #
+      # @return [String]
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def to_markdown
+        lines = []
+        lines << "## Session: #{@session_id}"
+        lines << "_Generated at #{@generated_at} | #{@steps.size} requests | ~#{@token_count} tokens_"
+        lines << ''
+
+        # Timeline
+        lines << '### Timeline'
+        lines << ''
+        @steps.each_with_index do |step, idx|
+          status = step[:status] || '?'
+          duration = step[:duration_ms] ? " (#{step[:duration_ms]}ms)" : ''
+          entry = "#{idx + 1}. #{step[:method]} #{step[:path]} → " \
+                  "#{step[:controller]}##{step[:action]} [#{status}]#{duration}"
+          lines << entry
+        end
+        lines << ''
+
+        # Side effects
+        if @side_effects.any?
+          lines << '### Side Effects'
+          lines << ''
+          @side_effects.each do |effect|
+            lines << "- #{effect[:type]}: #{effect[:identifier]} (triggered by #{effect[:trigger_step]})"
+          end
+          lines << ''
+        end
+
+        # Context pool
+        if @context_pool.any?
+          lines << '### Code Units'
+          lines << ''
+          @context_pool.each do |identifier, unit|
+            type = unit[:type] || 'unknown'
+            file_path = unit[:file_path]
+            lines << "#### #{identifier} (#{type})"
+            lines << "_#{file_path}_" if file_path
+            lines << ''
+            next unless unit[:source_code]
+
+            lines << '```ruby'
+            lines << unit[:source_code]
+            lines << '```'
+            lines << ''
+          end
+        end
+
+        # Dependencies
+        if @dependency_map.any?
+          lines << '### Dependencies'
+          lines << ''
+          @dependency_map.each do |unit_id, deps|
+            lines << "- #{unit_id} → #{deps.join(', ')}"
+          end
+          lines << ''
+        end
+
+        lines.join("\n")
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+      # Render as LLM-consumable XML context.
+      #
+      # Follows the format from docs/CONTEXT_AND_CHUNKING.md.
+      #
+      # @return [String]
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def to_context
+        lines = []
+        header = "<session_context session_id=\"#{@session_id}\" requests=\"#{@steps.size}\" " \
+                 "tokens=\"#{@token_count}\" units=\"#{@context_pool.size}\">"
+        lines << header
+
+        # Timeline
+        lines << '<session_timeline>'
+        @steps.each_with_index do |step, idx|
+          status = step[:status] || '?'
+          duration = step[:duration_ms] ? ", #{step[:duration_ms]}ms" : ''
+          entry = "#{idx + 1}. #{step[:method]} #{step[:path]} → " \
+                  "#{step[:controller]}##{step[:action]} (#{status}#{duration})"
+          lines << entry
+        end
+        lines << '</session_timeline>'
+
+        # Units
+        @context_pool.each do |identifier, unit|
+          type = unit[:type] || 'unknown'
+          file_path = unit[:file_path] || 'unknown'
+          lines << %(<unit identifier="#{identifier}" type="#{type}" file="#{file_path}">)
+          lines << (unit[:source_code] || '# source not available')
+          lines << '</unit>'
+        end
+
+        # Side effects
+        if @side_effects.any?
+          lines << '<side_effects>'
+          @side_effects.each do |effect|
+            lines << "#{effect[:identifier]} (triggered by #{effect[:trigger_step]}, #{effect[:type]})"
+          end
+          lines << '</side_effects>'
+        end
+
+        # Dependencies
+        if @dependency_map.any?
+          lines << '<dependencies>'
+          @dependency_map.each do |unit_id, deps|
+            lines << "#{unit_id} → #{deps.join(', ')}"
+          end
+          lines << '</dependencies>'
+        end
+
+        lines << '</session_context>'
+        lines.join("\n")
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+      # @api private
+      def self.deep_symbolize_keys(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(key, value), result|
+            result[key.to_sym] = deep_symbolize_keys(value)
+          end
+        when Array
+          obj.map { |item| deep_symbolize_keys(item) }
+        else
+          obj
+        end
+      end
+      private_class_method :deep_symbolize_keys
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/codebase_index/session_tracer/solid_cache_store.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'store'
+
+module CodebaseIndex
+  module SessionTracer
+    # SolidCache-backed session store.
+    #
+    # Uses SolidCache key-value storage with `expires_in`. Single JSON blob
+    # per session (read-modify-write pattern). Requires the `solid_cache` gem.
+    #
+    # @example
+    #   store = SolidCacheStore.new(cache: SolidCache::Store.new, expires_in: 3600)
+    #   store.record("abc123", { controller: "OrdersController", action: "create" })
+    #
+    class SolidCacheStore < Store
+      KEY_PREFIX = 'codebase_index:session:'
+      INDEX_KEY = 'codebase_index:session_index'
+
+      # @param cache [ActiveSupport::Cache::Store] A SolidCache (or compatible) cache instance
+      # @param expires_in [Integer, nil] Expiry time in seconds (nil = no expiry)
+      def initialize(cache:, expires_in: nil)
+        super()
+        @cache = cache
+        @expires_in = expires_in
+      end
+
+      # Append a request record to a session (read-modify-write).
+      #
+      # NOTE: Not atomic — concurrent writes to the same session may lose data.
+      # Acceptable for development tracing. For high-concurrency tracing, use
+      # RedisStore (RPUSH is atomic) or FileStore (LOCK_EX).
+      #
+      # @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)
+        existing = @cache.read(key)
+        requests = existing ? JSON.parse(existing) : []
+        requests << request_data
+
+        write_opts = @expires_in ? { expires_in: @expires_in } : {}
+        @cache.write(key, JSON.generate(requests), **write_opts)
+
+        update_index(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)
+        raw = @cache.read(key)
+        return [] unless raw
+
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        []
+      end
+
+      # List recent session summaries.
+      #
+      # @param limit [Integer] Maximum number of sessions to return
+      # @return [Array<Hash>] Session summaries
+      def sessions(limit: 20)
+        index = read_index
+        active = index.select { |id| @cache.exist?(session_key(id)) }
+
+        # Clean up expired entries from the index
+        write_index(active) if active.size != index.size
+
+        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)
+        @cache.delete(session_key(session_id))
+        index = read_index
+        index.delete(session_id)
+        write_index(index)
+      end
+
+      # Remove all session data.
+      #
+      # @return [void]
+      def clear_all
+        index = read_index
+        index.each { |id| @cache.delete(session_key(id)) }
+        @cache.delete(INDEX_KEY)
+      end
+
+      private
+
+      # @param session_id [String]
+      # @return [String] Cache key for this session
+      def session_key(session_id)
+        "#{KEY_PREFIX}#{sanitize_session_id(session_id)}"
+      end
+
+      # Read the session index (list of known session IDs).
+      #
+      # @return [Array<String>]
+      def read_index
+        raw = @cache.read(INDEX_KEY)
+        return [] unless raw
+
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        []
+      end
+
+      # Write the session index.
+      #
+      # @param ids [Array<String>]
+      def write_index(ids)
+        @cache.write(INDEX_KEY, JSON.generate(ids))
+      end
+
+      # Add a session ID to the index if not already present.
+      #
+      # @param session_id [String]
+      def update_index(session_id)
+        index = read_index
+        return if index.include?(session_id)
+
+        index << session_id
+        write_index(index)
+      end
+    end
+  end
+end

data/lib/codebase_index/session_tracer/store.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module CodebaseIndex
+  module SessionTracer
+    # Abstract store interface for session trace data.
+    #
+    # Concrete implementations must define:
+    # - `record(session_id, request_data)` — append a request record
+    # - `read(session_id)` — return all requests for a session, ordered by timestamp
+    # - `sessions(limit:)` — return recent session summaries
+    # - `clear(session_id)` — remove a single session
+    # - `clear_all` — remove all sessions
+    #
+    # @abstract Subclass and implement the required methods.
+    class Store
+      # Append a request record to a session.
+      #
+      # @param session_id [String] The session identifier
+      # @param request_data [Hash] Request metadata to store
+      # @return [void]
+      def record(session_id, request_data)
+        raise NotImplementedError, "#{self.class}#record must be implemented"
+      end
+
+      # Read all request records for a session, ordered by timestamp.
+      #
+      # @param session_id [String] The session identifier
+      # @return [Array<Hash>] Request records, oldest first
+      def read(session_id)
+        raise NotImplementedError, "#{self.class}#read must be implemented"
+      end
+
+      # List recent session summaries.
+      #
+      # @param limit [Integer] Maximum number of sessions to return
+      # @return [Array<Hash>] Session summaries with :session_id, :request_count, :first_request, :last_request
+      def sessions(limit: 20)
+        raise NotImplementedError, "#{self.class}#sessions must be implemented"
+      end
+
+      # Remove all data for a single session.
+      #
+      # @param session_id [String] The session identifier
+      # @return [void]
+      def clear(session_id)
+        raise NotImplementedError, "#{self.class}#clear must be implemented"
+      end
+
+      # Remove all session data.
+      #
+      # @return [void]
+      def clear_all
+        raise NotImplementedError, "#{self.class}#clear_all must be implemented"
+      end
+
+      private
+
+      # Sanitize a session ID for use in keys/filenames.
+      #
+      # @param session_id [String] Raw session identifier
+      # @return [String] Sanitized identifier (alphanumeric, hyphens, underscores only)
+      def sanitize_session_id(session_id)
+        session_id.to_s.gsub(/[^a-zA-Z0-9_-]/, '_')
+      end
+    end
+  end
+end