codebase_index 0.1.0

data/lib/codebase_index/flow_precomputer.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+require_relative 'flow_assembler'
+
+module CodebaseIndex
+  # Orchestrates pre-computation of request flow maps for all controller actions.
+  #
+  # After the dependency graph is built, FlowPrecomputer iterates controller units,
+  # runs FlowAssembler for each action, and writes flow documents to disk.
+  #
+  # @example
+  #   precomputer = FlowPrecomputer.new(units: all_units, graph: dep_graph, output_dir: out)
+  #   flow_map = precomputer.precompute
+  #   flow_map["OrdersController#create"] #=> "/tmp/codebase_index/flows/OrdersController_create.json"
+  #
+  class FlowPrecomputer
+    # Default maximum recursion depth for flow assembly
+    DEFAULT_MAX_DEPTH = 3
+
+    # @param units [Array<ExtractedUnit>] All extracted units
+    # @param graph [DependencyGraph] The dependency graph
+    # @param output_dir [String] Base output directory
+    # @param max_depth [Integer] Maximum flow assembly depth
+    def initialize(units:, graph:, output_dir:, max_depth: DEFAULT_MAX_DEPTH)
+      @units = units
+      @graph = graph
+      @output_dir = output_dir
+      @max_depth = max_depth
+      @flows_dir = File.join(output_dir, 'flows')
+    end
+
+    # Pre-compute flow documents for all controller actions.
+    #
+    # @return [Hash{String => String}] Map of entry_point to flow file path
+    def precompute
+      FileUtils.mkdir_p(@flows_dir)
+
+      assembler = FlowAssembler.new(graph: @graph, extracted_dir: @output_dir)
+      flow_map = {}
+
+      controller_units.each do |unit|
+        actions = unit.metadata[:actions] || unit.metadata['actions'] || []
+        unit_flow_paths = {}
+
+        actions.each do |action|
+          entry_point = "#{unit.identifier}##{action}"
+          flow_path = assemble_and_write(assembler, entry_point, unit.identifier, action)
+          next unless flow_path
+
+          flow_map[entry_point] = flow_path
+          unit_flow_paths[action] = flow_path
+        end
+
+        unit.metadata[:flow_paths] = unit_flow_paths if unit_flow_paths.any?
+      end
+
+      write_flow_index(flow_map)
+
+      flow_map
+    end
+
+    private
+
+    # Filter units to only controllers.
+    #
+    # @return [Array<ExtractedUnit>]
+    def controller_units
+      @units.select { |u| u.type.to_s == 'controller' }
+    end
+
+    # Assemble a flow for one entry point and write the JSON file.
+    #
+    # @param assembler [FlowAssembler]
+    # @param entry_point [String]
+    # @param controller_id [String]
+    # @param action [String]
+    # @return [String, nil] The written file path, or nil on failure
+    def assemble_and_write(assembler, entry_point, controller_id, action)
+      flow = assembler.assemble(entry_point, max_depth: @max_depth)
+
+      filename = "#{controller_id.gsub('::', '__')}_#{action}.json"
+      flow_path = File.join(@flows_dir, filename)
+
+      File.write(flow_path, JSON.pretty_generate(flow.to_h))
+
+      flow_path
+    rescue StandardError => e
+      Rails.logger.error("[CodebaseIndex] Flow precompute failed for #{entry_point}: #{e.message}")
+      nil
+    end
+
+    # Write the flow index mapping entry points to file paths.
+    #
+    # @param flow_map [Hash{String => String}]
+    def write_flow_index(flow_map)
+      index_path = File.join(@flows_dir, 'flow_index.json')
+      File.write(index_path, JSON.pretty_generate(flow_map))
+    end
+  end
+end

data/lib/codebase_index/formatting/base.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module CodebaseIndex
+  module Formatting
+    # Abstract base class for formatting adapters.
+    #
+    # Each adapter transforms an AssembledContext into a format suitable for
+    # a specific LLM or output target. Subclasses must implement {#format}.
+    #
+    # @abstract Subclass and override {#format} to implement.
+    #
+    # @example
+    #   class MyAdapter < Base
+    #     def format(assembled_context)
+    #       "Content: #{assembled_context.context}"
+    #     end
+    #   end
+    #
+    class Base
+      # Format an assembled context for output.
+      #
+      # @param _assembled_context [CodebaseIndex::Retrieval::AssembledContext]
+      # @return [String] Formatted output
+      # @raise [NotImplementedError] if not overridden by subclass
+      def format(_assembled_context)
+        raise NotImplementedError, "#{self.class}#format must be implemented"
+      end
+
+      private
+
+      # Estimate token count using the project convention.
+      #
+      # @param text [String]
+      # @return [Integer]
+      def estimate_tokens(text)
+        (text.length / 4.0).ceil
+      end
+    end
+  end
+end

data/lib/codebase_index/formatting/claude_adapter.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module CodebaseIndex
+  module Formatting
+    # Formats assembled context as XML for Claude models.
+    #
+    # Produces structured XML with:
+    # - `<codebase-context>` root element
+    # - `<meta>` tag with token usage and budget
+    # - `<content>` section with indented context text
+    # - `<sources>` section with self-closing `<source>` elements
+    #
+    # @example
+    #   adapter = ClaudeAdapter.new
+    #   xml = adapter.format(assembled_context)
+    #   # => "<codebase-context>\n  <meta tokens=\"42\" budget=\"8000\" />\n..."
+    #
+    class ClaudeAdapter < Base
+      # Format assembled context as XML for Claude.
+      #
+      # @param assembled_context [CodebaseIndex::Retrieval::AssembledContext]
+      # @return [String] XML-formatted context
+      def format(assembled_context)
+        parts = []
+        parts << '<codebase-context>'
+        parts << "  <meta tokens=\"#{assembled_context.tokens_used}\" budget=\"#{assembled_context.budget}\" />"
+        parts << format_content(assembled_context.context)
+        parts << format_sources(assembled_context.sources)
+        parts << '</codebase-context>'
+        parts.join("\n")
+      end
+
+      private
+
+      # Format the content section with indentation.
+      #
+      # @param context [String]
+      # @return [String]
+      def format_content(context)
+        lines = []
+        lines << '  <content>'
+        lines << indent(escape_xml(context), 4) unless context.empty?
+        lines << '  </content>'
+        lines.join("\n")
+      end
+
+      # Format the sources section.
+      #
+      # @param sources [Array<Hash>]
+      # @return [String]
+      def format_sources(sources)
+        lines = []
+        lines << '  <sources>'
+        sources.each do |source|
+          lines << "    <source #{source_attributes(source)} />"
+        end
+        lines << '  </sources>'
+        lines.join("\n")
+      end
+
+      # Build attribute string for a source element.
+      #
+      # @param source [Hash]
+      # @return [String]
+      def source_attributes(source)
+        [
+          "identifier=\"#{escape_xml(source[:identifier].to_s)}\"",
+          "type=\"#{escape_xml(source[:type].to_s)}\"",
+          "score=\"#{source[:score]}\"",
+          "file=\"#{escape_xml(source[:file_path].to_s)}\""
+        ].join(' ')
+      end
+
+      # Indent every line of text by the given number of spaces.
+      #
+      # @param text [String]
+      # @param spaces [Integer]
+      # @return [String]
+      def indent(text, spaces)
+        prefix = ' ' * spaces
+        text.lines.map { |line| "#{prefix}#{line.chomp}" }.join("\n")
+      end
+
+      # Escape XML special characters.
+      #
+      # @param text [String]
+      # @return [String]
+      def escape_xml(text)
+        text.gsub('&', '&amp;')
+            .gsub('<', '&lt;')
+            .gsub('>', '&gt;')
+            .gsub('"', '&quot;')
+      end
+    end
+  end
+end

data/lib/codebase_index/formatting/generic_adapter.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module CodebaseIndex
+  module Formatting
+    # Formats assembled context as plain text for generic LLM consumption.
+    #
+    # Produces plain text with:
+    # - `=== CODEBASE CONTEXT ===` header
+    # - Token usage line
+    # - Content separated by `---` dividers
+    # - Sources in bracket notation
+    #
+    # @example
+    #   adapter = GenericAdapter.new
+    #   text = adapter.format(assembled_context)
+    #   # => "=== CODEBASE CONTEXT ===\nTokens: 42 / 8000\n..."
+    #
+    class GenericAdapter < Base
+      # Format assembled context as plain text.
+      #
+      # @param assembled_context [CodebaseIndex::Retrieval::AssembledContext]
+      # @return [String] Plain text formatted context
+      def format(assembled_context)
+        parts = []
+        parts << '=== CODEBASE CONTEXT ==='
+        parts << "Tokens: #{assembled_context.tokens_used} / #{assembled_context.budget}"
+        parts << '---'
+        parts << assembled_context.context
+        parts.concat(format_sources(assembled_context.sources))
+        parts.join("\n")
+      end
+
+      private
+
+      # Format sources in bracket notation.
+      #
+      # @param sources [Array<Hash>]
+      # @return [Array<String>] Lines to append
+      def format_sources(sources)
+        return [] if sources.empty?
+
+        lines = []
+        lines << '---'
+        sources.each do |source|
+          identifier = source[:identifier]
+          type = source[:type]
+          score = source[:score]
+          lines << "[Source: #{identifier} (#{type}) \u2014 score: #{score}]"
+        end
+        lines
+      end
+    end
+  end
+end

data/lib/codebase_index/formatting/gpt_adapter.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module CodebaseIndex
+  module Formatting
+    # Formats assembled context as Markdown for GPT models.
+    #
+    # Produces Markdown with:
+    # - `## Codebase Context` heading
+    # - Token usage in bold
+    # - Content in a fenced Ruby code block
+    # - Sources as a bullet list
+    #
+    # @example
+    #   adapter = GptAdapter.new
+    #   md = adapter.format(assembled_context)
+    #   # => "## Codebase Context\n\n**Tokens:** 42/8000\n..."
+    #
+    class GptAdapter < Base
+      # Format assembled context as Markdown for GPT.
+      #
+      # @param assembled_context [CodebaseIndex::Retrieval::AssembledContext]
+      # @return [String] Markdown-formatted context
+      def format(assembled_context)
+        parts = []
+        parts << '## Codebase Context'
+        parts << ''
+        parts << "**Tokens:** #{assembled_context.tokens_used}/#{assembled_context.budget}"
+        parts << ''
+        parts << '---'
+        parts << ''
+        parts << '```ruby'
+        parts << assembled_context.context
+        parts << '```'
+        parts.concat(format_sources(assembled_context.sources))
+        parts.join("\n")
+      end
+
+      private
+
+      # Format sources as a Markdown bullet list.
+      #
+      # @param sources [Array<Hash>]
+      # @return [Array<String>] Lines to append
+      def format_sources(sources)
+        return [] if sources.empty?
+
+        lines = []
+        lines << ''
+        lines << '### Sources'
+        lines << ''
+        sources.each do |source|
+          identifier = source[:identifier]
+          type = source[:type]
+          score = source[:score]
+          file_path = source[:file_path]
+          lines << "- **#{identifier}** (#{type}) \u2014 score: #{score}, file: #{file_path}"
+        end
+        lines
+      end
+    end
+  end
+end

data/lib/codebase_index/formatting/human_adapter.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module CodebaseIndex
+  module Formatting
+    # Formats assembled context with box-drawing characters for human display.
+    #
+    # Produces visually rich output with:
+    # - Box-drawn header using Unicode box characters
+    # - Token usage summary
+    # - Content section
+    # - Source entries with box-drawing decorators
+    #
+    # @example
+    #   adapter = HumanAdapter.new
+    #   output = adapter.format(assembled_context)
+    #
+    class HumanAdapter < Base
+      HEADER_WIDTH = 50
+
+      # Format assembled context for human-readable display.
+      #
+      # @param assembled_context [CodebaseIndex::Retrieval::AssembledContext]
+      # @return [String] Box-drawing formatted context
+      def format(assembled_context)
+        parts = []
+        parts.concat(format_header(assembled_context))
+        parts << ''
+        parts << assembled_context.context unless assembled_context.context.empty?
+        parts.concat(format_sources(assembled_context.sources))
+        parts.join("\n")
+      end
+
+      private
+
+      # Format the box-drawing header.
+      #
+      # @param assembled_context [CodebaseIndex::Retrieval::AssembledContext]
+      # @return [Array<String>]
+      def format_header(assembled_context)
+        title = 'Codebase Context'
+        token_info = "Tokens: #{assembled_context.tokens_used} / #{assembled_context.budget}"
+        width = [HEADER_WIDTH, title.length + 4, token_info.length + 4].max
+
+        [
+          "\u2554#{'═' * width}\u2557",
+          "\u2551 #{title.ljust(width - 2)} \u2551",
+          "\u255A#{'═' * width}\u255D",
+          token_info
+        ]
+      end
+
+      # Format sources with box-drawing decorators.
+      #
+      # @param sources [Array<Hash>]
+      # @return [Array<String>]
+      def format_sources(sources)
+        return [] if sources.empty?
+
+        lines = ['', 'Sources:']
+        sources.each { |source| lines.concat(format_source_entry(source)) }
+        lines
+      end
+
+      # Format a single source entry.
+      #
+      # @param source [Hash]
+      # @return [Array<String>]
+      def format_source_entry(source)
+        header = "\u2500\u2500 #{source[:identifier]} (#{source[:type]}) "
+        header += "\u2500" * [1, HEADER_WIDTH - header.length - 12].max
+        header += " score: #{source[:score]}"
+        [header, "   #{source[:file_path]}"]
+      end
+    end
+  end
+end