codebase_index 0.1.0

data/lib/codebase_index/flow_analysis/response_code_mapper.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module CodebaseIndex
+  module FlowAnalysis
+    # Maps render/redirect AST nodes to HTTP status codes.
+    #
+    # Uses a built-in STATUS_CODES hash rather than depending on Rack at runtime.
+    # Handles explicit status kwargs, render_<status> conventions, head calls,
+    # and redirect_to defaults.
+    #
+    # @example Resolving a render call
+    #   ResponseCodeMapper.resolve_method("render_created", arguments: []) #=> 201
+    #   ResponseCodeMapper.resolve_method("redirect_to", arguments: ["/home"]) #=> 302
+    #   ResponseCodeMapper.resolve_method("head", arguments: [":no_content"]) #=> 204
+    #
+    class ResponseCodeMapper
+      # Subset of Rack::Utils::SYMBOL_TO_STATUS_CODE, inlined to avoid runtime Rack dependency.
+      STATUS_CODES = {
+        continue: 100,
+        switching_protocols: 101,
+        processing: 102,
+        early_hints: 103,
+        ok: 200,
+        created: 201,
+        accepted: 202,
+        non_authoritative_information: 203,
+        no_content: 204,
+        reset_content: 205,
+        partial_content: 206,
+        multi_status: 207,
+        already_reported: 208,
+        im_used: 226,
+        multiple_choices: 300,
+        moved_permanently: 301,
+        found: 302,
+        see_other: 303,
+        not_modified: 304,
+        use_proxy: 305,
+        temporary_redirect: 307,
+        permanent_redirect: 308,
+        bad_request: 400,
+        unauthorized: 401,
+        payment_required: 402,
+        forbidden: 403,
+        not_found: 404,
+        method_not_allowed: 405,
+        not_acceptable: 406,
+        proxy_authentication_required: 407,
+        request_timeout: 408,
+        conflict: 409,
+        gone: 410,
+        length_required: 411,
+        precondition_failed: 412,
+        payload_too_large: 413,
+        uri_too_long: 414,
+        unsupported_media_type: 415,
+        range_not_satisfiable: 416,
+        expectation_failed: 417,
+        misdirected_request: 421,
+        unprocessable_entity: 422,
+        locked: 423,
+        failed_dependency: 424,
+        too_early: 425,
+        upgrade_required: 426,
+        precondition_required: 428,
+        too_many_requests: 429,
+        request_header_fields_too_large: 431,
+        unavailable_for_legal_reasons: 451,
+        internal_server_error: 500,
+        not_implemented: 501,
+        bad_gateway: 502,
+        service_unavailable: 503,
+        gateway_timeout: 504,
+        http_version_not_supported: 505,
+        variant_also_negotiates: 506,
+        insufficient_storage: 507,
+        loop_detected: 508,
+        not_extended: 510,
+        network_authentication_required: 511
+      }.freeze
+
+      # Resolve a render/redirect/head method call to an HTTP status code.
+      #
+      # Strategies tried in order:
+      # 1. Explicit status kwarg: `render json: x, status: :created` -> 201
+      # 2. render_<status> convention: `render_created` -> 201
+      # 3. head with status arg: `head :no_content` -> 204
+      # 4. redirect_to default: 302
+      #
+      # @param method_name [String] The method name (render, redirect_to, head, render_created, etc.)
+      # @param arguments [Array<String>] Argument representations from AST
+      # @return [Integer, nil] HTTP status code or nil if unresolvable
+      def self.resolve_method(method_name, arguments: [])
+        # Case 1: Look for explicit status kwarg in arguments
+        status_from_kwarg = extract_status_from_args(arguments)
+        return resolve_status(status_from_kwarg) if status_from_kwarg
+
+        # Case 2: render_<status> convention
+        if method_name.start_with?('render_')
+          status_name = method_name.delete_prefix('render_')
+          code = STATUS_CODES[status_name.to_sym]
+          return code if code
+        end
+
+        # Case 3: head :status
+        return resolve_status(arguments.first) if method_name == 'head' && arguments.first
+
+        # Case 4: redirect_to defaults to 302
+        return 302 if method_name == 'redirect_to'
+
+        nil
+      end
+
+      # Resolve a status value (symbol name, integer, or string) to an integer code.
+      #
+      # @param value [String, Integer, Symbol] Status representation
+      # @return [Integer, nil] HTTP status code or nil
+      def self.resolve_status(value)
+        case value
+        when Integer
+          value
+        when Symbol
+          STATUS_CODES[value]
+        when String
+          # Strip leading colon from AST symbol representation (":created" -> "created")
+          cleaned = value.delete_prefix(':')
+          # Try as symbol name first
+          code = STATUS_CODES[cleaned.to_sym]
+          return code if code
+
+          # Try as integer string
+          return cleaned.to_i if cleaned.match?(/\A\d+\z/)
+
+          nil
+        end
+      end
+
+      # Extract a status value from argument strings.
+      #
+      # Looks for patterns like "status: :created" or "status: 201" in argument list.
+      #
+      # @param arguments [Array<String>] Argument representations
+      # @return [String, nil] The status value if found
+      def self.extract_status_from_args(arguments)
+        arguments.each do |arg|
+          if arg.is_a?(String) && (match = arg.match(/status:\s*(.+)/))
+            return match[1].strip
+          end
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/codebase_index/flow_assembler.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+require 'set'
+require_relative 'ast/parser'
+require_relative 'ast/method_extractor'
+require_relative 'flow_analysis/operation_extractor'
+require_relative 'flow_document'
+
+module CodebaseIndex
+  # Orchestrates execution flow tracing from an entry point through the dependency graph.
+  #
+  # Given an entry point (e.g., "PostsController#create"), FlowAssembler:
+  # 1. Loads the ExtractedUnit JSON from disk
+  # 2. Parses its source_code with the AST layer
+  # 3. Extracts operations in source line order
+  # 4. Recursively expands targets that resolve to other units
+  # 5. Detects cycles and respects max_depth
+  # 6. Assembles a FlowDocument
+  #
+  # @example Assembling a flow
+  #   assembler = FlowAssembler.new(graph: graph, extracted_dir: "/tmp/codebase_index")
+  #   flow = assembler.assemble("PostsController#create", max_depth: 5)
+  #   puts flow.to_markdown
+  #
+  class FlowAssembler
+    # @param graph [DependencyGraph] The dependency graph for resolving targets
+    # @param extracted_dir [String] Directory containing extracted unit JSON files
+    def initialize(graph:, extracted_dir:)
+      @graph = graph
+      @extracted_dir = extracted_dir
+      @parser = Ast::Parser.new
+      @method_extractor = Ast::MethodExtractor.new(parser: @parser)
+      @operation_extractor = FlowAnalysis::OperationExtractor.new
+    end
+
+    # Assemble an execution flow from the given entry point.
+    #
+    # @param entry_point [String] Unit identifier, optionally with #method_name
+    # @param max_depth [Integer] Maximum recursion depth
+    # @return [FlowDocument] The assembled flow document
+    def assemble(entry_point, max_depth: 5)
+      visited = Set.new
+      steps = []
+
+      expand(entry_point, steps, visited, depth: 0, max_depth: max_depth)
+
+      route = extract_route(entry_point)
+
+      FlowDocument.new(
+        entry_point: entry_point,
+        route: route,
+        max_depth: max_depth,
+        steps: steps
+      )
+    end
+
+    private
+
+    # Recursively expand a unit into flow steps.
+    #
+    # @param identifier [String] Unit identifier (may include #method)
+    # @param steps [Array<Hash>] Accumulator for step hashes
+    # @param visited [Set<String>] Visited unit identifiers for cycle detection
+    # @param depth [Integer] Current recursion depth
+    # @param max_depth [Integer] Maximum recursion depth
+    def expand(identifier, steps, visited, depth:, max_depth:)
+      return if depth > max_depth
+
+      # Parse identifier into unit name and optional method
+      unit_id, method_name = parse_identifier(identifier)
+
+      if visited.include?(unit_id)
+        # Cycle detected - emit a marker step
+        steps << {
+          unit: unit_id,
+          type: 'cycle',
+          operations: [{ type: :cycle, target: unit_id, line: nil }]
+        }
+        return
+      end
+
+      visited.add(unit_id)
+
+      # Load the unit data from disk
+      unit_data = load_unit(unit_id)
+      return unless unit_data
+
+      source_code = unit_data[:source_code]
+      return unless source_code && !source_code.empty?
+
+      metadata = unit_data[:metadata] || {}
+      unit_type = unit_data[:type]&.to_s
+      file_path = unit_data[:file_path]
+
+      # Extract operations from the relevant method
+      operations = extract_operations(source_code, method_name, metadata, unit_type)
+
+      step = {
+        unit: identifier,
+        type: unit_type,
+        file_path: file_path,
+        operations: operations
+      }
+
+      steps << step
+
+      # Recursively expand targets that resolve to known units
+      operations.each do |op|
+        expand_operation(op, identifier, steps, visited, depth: depth, max_depth: max_depth)
+      end
+    end
+
+    # Extract operations from source code for a specific method.
+    def extract_operations(source_code, method_name, metadata, unit_type)
+      operations = []
+
+      # For controllers, prepend before_action callbacks
+      prepend_callbacks(operations, metadata, method_name) if unit_type == 'controller'
+
+      if method_name
+        # Extract specific method
+        method_node = @method_extractor.extract_method(source_code, method_name)
+        if method_node
+          ops = @operation_extractor.extract(method_node)
+          operations.concat(ops)
+        end
+      else
+        # No specific method - parse entire source
+        root = @parser.parse(source_code)
+        ops = @operation_extractor.extract(root)
+        operations.concat(ops)
+      end
+
+      operations
+    end
+
+    # Prepend before_action callbacks from controller metadata.
+    #
+    # Handles two metadata formats:
+    # - metadata[:callbacks] with :name key (legacy/test format)
+    # - metadata[:filters] with :filter key (ControllerExtractor format)
+    def prepend_callbacks(operations, metadata, method_name)
+      callbacks = metadata[:callbacks] || metadata[:filters]
+      return unless callbacks.is_a?(Array)
+
+      callbacks.each do |cb|
+        cb_kind = cb[:kind]&.to_s
+        next unless cb_kind == 'before'
+
+        # Handle both :name (callbacks format) and :filter (controller filters format)
+        cb_name = cb[:name] || cb[:filter]
+        next unless cb_name
+
+        # Check if callback applies to this action (via :only/:except)
+        only = cb[:only]
+        except = cb[:except]
+
+        next if only.is_a?(Array) && method_name && !only.map(&:to_s).include?(method_name.to_s)
+
+        next if except.is_a?(Array) && method_name && except.map(&:to_s).include?(method_name.to_s)
+
+        operations << {
+          type: :call,
+          target: nil,
+          method: cb_name.to_s,
+          line: nil
+        }
+      end
+    end
+
+    # Recursively expand an operation's target if it resolves to a known unit.
+    #
+    # @param op [Hash] The operation to potentially expand
+    # @param current_unit [String] The identifier of the unit containing this operation
+    # @param steps [Array<Hash>] Accumulator for step hashes
+    # @param visited [Set<String>] Visited unit identifiers for cycle detection
+    # @param depth [Integer] Current recursion depth
+    # @param max_depth [Integer] Maximum recursion depth
+    def expand_operation(op, current_unit, steps, visited, depth:, max_depth:)
+      case op[:type]
+      when :call, :async
+        target = op[:target]
+        return unless target
+
+        candidate = resolve_target(target)
+        return unless candidate
+
+        expand(candidate, steps, visited, depth: depth + 1, max_depth: max_depth)
+      when :transaction
+        (op[:nested] || []).each do |nested_op|
+          expand_operation(nested_op, current_unit, steps, visited, depth: depth, max_depth: max_depth)
+        end
+      when :conditional
+        ((op[:then_ops] || []) + (op[:else_ops] || [])).each do |branch_op|
+          expand_operation(branch_op, current_unit, steps, visited, depth: depth, max_depth: max_depth)
+        end
+      end
+    end
+
+    # Resolve a call target to a unit identifier using graph-wide lookup.
+    #
+    # Uses node existence checks rather than dependency edges, because
+    # dependency edges are structural (associations, includes) and don't
+    # represent actual call relationships in execution flows.
+    #
+    # Tier 1: Graph-wide lookup — checks if the node exists anywhere in the graph,
+    #          including suffix matching for unqualified class names.
+    # Tier 2: Disk fallback — attempts to load the unit JSON from disk, covering
+    #          units that exist in the index but were not loaded into the graph.
+    #
+    # @param target [String] The call target name to resolve
+    # @return [String, nil] The resolved unit identifier, or nil if not found
+    def resolve_target(target)
+      # Tier 1: Graph-wide lookup
+      return target if @graph.node_exists?(target)
+
+      graph_match = @graph.find_node_by_suffix(target)
+      return graph_match if graph_match
+
+      # Tier 2: Disk fallback (unit JSON exists but isn't in the graph)
+      unit_data = load_unit(target)
+      return target if unit_data
+
+      nil
+    end
+
+    # Parse an identifier into [unit_id, method_name].
+    # "PostsController#create" => ["PostsController", "create"]
+    # "PostService" => ["PostService", nil]
+    def parse_identifier(identifier)
+      if identifier.include?('#')
+        identifier.split('#', 2)
+      else
+        [identifier, nil]
+      end
+    end
+
+    # Load an ExtractedUnit's data from its JSON file on disk.
+    #
+    # Uses {Extractor#collision_safe_filename} convention (with SHA256 digest suffix).
+    # Falls back to legacy {Extractor#safe_filename} for older indexes.
+    # Searches across type subdirectories since the extractor writes to
+    # `<output_dir>/<type>/<filename>.json`.
+    def load_unit(unit_id)
+      base = unit_id.gsub('::', '__').gsub(/[^a-zA-Z0-9_-]/, '_')
+      digest = Digest::SHA256.hexdigest(unit_id)[0, 8]
+      filenames = [
+        "#{base}_#{digest}.json",
+        "#{base}.json"
+      ]
+
+      filenames.each do |filename|
+        Dir[File.join(@extracted_dir, '*', filename)].each do |path|
+          return JSON.parse(File.read(path), symbolize_names: true)
+        rescue JSON::ParserError
+          next
+        end
+      end
+
+      nil
+    end
+
+    # Extract route information from controller metadata.
+    def extract_route(entry_point)
+      unit_id, method_name = parse_identifier(entry_point)
+      unit_data = load_unit(unit_id)
+      return nil unless unit_data
+
+      metadata = unit_data[:metadata] || {}
+      routes = metadata[:routes]
+      return nil unless routes.is_a?(Array)
+
+      # Find route matching the method name
+      route = if method_name
+                routes.find { |r| r[:action]&.to_s == method_name }
+              else
+                routes.first
+              end
+
+      return nil unless route
+
+      {
+        verb: route[:verb],
+        path: route[:path]
+      }
+    end
+  end
+end

data/lib/codebase_index/flow_document.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module CodebaseIndex
+  # Value object representing an assembled execution flow trace.
+  #
+  # Contains an ordered list of steps from an entry point through the dependency graph,
+  # with each step holding operations extracted from source code in line order.
+  #
+  # @example Creating and serializing a flow document
+  #   doc = FlowDocument.new(
+  #     entry_point: "PostsController#create",
+  #     route: { verb: "POST", path: "/posts" },
+  #     max_depth: 5,
+  #     steps: [{ unit: "PostsController#create", type: "controller", operations: [...] }]
+  #   )
+  #   doc.to_h        # => JSON-serializable Hash
+  #   doc.to_markdown  # => human-readable table
+  #
+  class FlowDocument
+    attr_reader :entry_point, :route, :max_depth, :steps, :generated_at
+
+    # @param entry_point [String] The entry point identifier (e.g., "PostsController#create")
+    # @param route [Hash, nil] Route info with :verb and :path keys
+    # @param max_depth [Integer] Maximum recursion depth used during assembly
+    # @param steps [Array<Hash>] Ordered list of step hashes
+    # @param generated_at [String, nil] ISO8601 timestamp (defaults to now)
+    def initialize(entry_point:, route: nil, max_depth: 5, steps: [], generated_at: nil)
+      @entry_point = entry_point
+      @route = route
+      @max_depth = max_depth
+      @steps = steps
+      @generated_at = generated_at || Time.now.iso8601
+    end
+
+    # Serialize to a JSON-compatible Hash.
+    #
+    # @return [Hash] Complete flow document data
+    def to_h
+      {
+        entry_point: @entry_point,
+        route: @route,
+        max_depth: @max_depth,
+        generated_at: @generated_at,
+        steps: @steps
+      }
+    end
+
+    # Reconstruct a FlowDocument from a serialized Hash.
+    #
+    # Handles both symbol and string keys for JSON round-trip compatibility.
+    #
+    # @param data [Hash] Previously serialized flow document data
+    # @return [FlowDocument]
+    def self.from_h(data)
+      data = deep_symbolize_keys(data)
+
+      new(
+        entry_point: data[:entry_point],
+        route: data[:route],
+        max_depth: data[:max_depth] || 5,
+        steps: data[:steps] || [],
+        generated_at: data[:generated_at]
+      )
+    end
+
+    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
+
+    # Render as human-readable Markdown.
+    #
+    # Produces a document with a header showing the route and entry point,
+    # followed by one section per step with an operations table.
+    #
+    # @return [String] Markdown-formatted flow document
+    def to_markdown
+      lines = []
+      lines << format_header
+      lines << ''
+
+      @steps.each_with_index do |step, idx|
+        lines << format_step(step, idx + 1)
+        lines << ''
+      end
+
+      lines.join("\n")
+    end
+
+    private
+
+    # Format the document header with route and entry point info.
+    def format_header
+      if @route
+        verb = @route[:verb] || '?'
+        path = @route[:path] || '?'
+        "## #{verb} #{path} → #{@entry_point}"
+      else
+        "## #{@entry_point}"
+      end
+    end
+
+    # Format a single step as a Markdown section with operations table.
+    def format_step(step, number)
+      unit = step[:unit]
+      file_path = step[:file_path]
+      operations = step[:operations] || []
+
+      lines = []
+      lines << "### #{number}. #{unit}"
+      lines << "_#{file_path}_" if file_path
+      lines << ''
+
+      if operations.any?
+        lines << '| # | Operation | Target | Line |'
+        lines << '|---|-----------|--------|------|'
+        format_operations(operations, lines)
+      else
+        lines << '_No significant operations_'
+      end
+
+      lines.join("\n")
+    end
+
+    # Format operations into table rows, handling nesting for transactions and conditionals.
+    def format_operations(operations, lines, prefix: '')
+      operations.each_with_index do |op, idx|
+        num = "#{prefix}#{idx + 1}"
+        op_type = op[:type]
+        op_type_str = op_type.to_s
+
+        case op_type_str
+        when 'transaction'
+          receiver = op[:receiver]
+          line = op[:line]
+          lines << "| #{num} | transaction | #{receiver}.transaction | #{line} |"
+          nested = op[:nested] || []
+          format_operations(nested, lines, prefix: "#{num}.")
+        when 'conditional'
+          condition = op[:condition]
+          kind = op[:kind] || 'if'
+          line = op[:line]
+          lines << "| #{num} | #{kind} #{condition} | | #{line} |"
+          then_ops = op[:then_ops] || []
+          else_ops = op[:else_ops] || []
+          format_operations(then_ops, lines, prefix: "#{num}a.")
+          format_operations(else_ops, lines, prefix: "#{num}b.")
+        when 'response'
+          status = op[:status_code]
+          method = op[:render_method]
+          line = op[:line]
+          status_text = status ? status.to_s : '?'
+          lines << "| #{num} | response | #{status_text} (via #{method}) | #{line} |"
+        when 'async'
+          target = op[:target]
+          method = op[:method]
+          args = op[:args_hint]
+          line = op[:line]
+          args_text = args&.any? ? "(#{args.join(', ')})" : ''
+          lines << "| #{num} | async | #{target}.#{method}#{args_text} | #{line} |"
+        when 'cycle'
+          target = op[:target]
+          line = op[:line]
+          lines << "| #{num} | cycle | #{target} (revisit) | #{line} |"
+        when 'dynamic_dispatch'
+          target = op[:target]
+          method = op[:method]
+          line = op[:line]
+          lines << "| #{num} | dynamic_dispatch | #{target}.#{method} | #{line} |"
+        else
+          target = op[:target]
+          method = op[:method]
+          line = op[:line]
+          target_text = [target, method].compact.join('.')
+          lines << "| #{num} | #{op_type_str} | #{target_text} | #{line} |"
+        end
+      end
+    end
+  end
+end