codebase_index 0.1.0

data/exe/codebase-index-mcp-start

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Self-healing wrapper for the CodebaseIndex MCP server.
+# Ensures Ruby dependencies are installed, validates the index directory,
+# and starts the stdio MCP server.
+#
+# Usage (direct):
+#   codebase-index-mcp-start /path/to/index_dir
+#
+# Usage (.mcp.json):
+#   {
+#     "command": "${HOME}/work/codebase_index/exe/codebase-index-mcp-start",
+#     "args": ["${HOME}/my-rails-app/tmp/codebase_index"]
+#   }
+#
+# All diagnostic output goes to stderr to keep stdio clean for MCP protocol.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+GEM_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+INDEX_DIR="${1:-${CODEBASE_INDEX_DIR:-}}"
+
+# --- Validate index directory ---
+if [[ -z "$INDEX_DIR" ]]; then
+  echo "Error: No index directory specified." >&2
+  echo "Usage: codebase-index-mcp-start /path/to/index_dir" >&2
+  exit 1
+fi
+
+if [[ ! -d "$INDEX_DIR" ]]; then
+  echo "Error: Index directory does not exist: $INDEX_DIR" >&2
+  echo "Run extraction first: bundle exec rake codebase_index:extract" >&2
+  exit 1
+fi
+
+if [[ ! -f "$INDEX_DIR/manifest.json" ]]; then
+  echo "Error: No manifest.json in: $INDEX_DIR" >&2
+  echo "Run extraction first: bundle exec rake codebase_index:extract" >&2
+  exit 1
+fi
+
+# --- Ensure Ruby dependencies are installed ---
+export BUNDLE_GEMFILE="${GEM_DIR}/Gemfile"
+
+if ! bundle check > /dev/null 2>&1; then
+  echo "Installing codebase_index dependencies..." >&2
+  if ! bundle install --quiet >&2 2>&1; then
+    echo "Error: bundle install failed. Check Ruby version and network." >&2
+    exit 1
+  fi
+  echo "Dependencies installed." >&2
+fi
+
+# --- Pin MCP protocol version for Claude Code compatibility ---
+export MCP_PROTOCOL_VERSION="${MCP_PROTOCOL_VERSION:-2024-11-05}"
+
+# --- Start the MCP server ---
+exec bundle exec ruby "${GEM_DIR}/exe/codebase-index-mcp" "$INDEX_DIR"

data/lib/codebase_index/ast/call_site_extractor.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'set'
+require_relative 'node'
+
+module CodebaseIndex
+  module Ast
+    # Method names that are too common to be useful in call graphs.
+    INSIGNIFICANT_METHODS = Set.new(%w[
+                                      to_s to_i to_f to_a to_h to_sym to_r to_c to_str to_proc
+                                      nil? present? blank? empty? any? none? frozen? is_a? kind_of?
+                                      respond_to? respond_to_missing? instance_of? equal?
+                                      == != eql? <=> === =~ !~ >= <= > <
+                                      ! & | ^ ~ + - * / % **
+                                      freeze dup clone inspect hash object_id class
+                                      send __send__ method tap then yield_self itself
+                                      new allocate
+                                      [] []=
+                                      length size count
+                                      first last
+                                      map each select reject flat_map collect detect find_index
+                                      merge merge! update
+                                      keys values
+                                      push pop shift unshift
+                                      strip chomp chop downcase upcase
+                                      puts print p pp warn raise fail
+                                      require require_relative load autoload
+                                      attr_reader attr_writer attr_accessor
+                                      private protected public
+                                      include extend prepend
+                                    ]).freeze
+
+    # Extracts call sites from an AST node tree.
+    #
+    # Returns method calls found in the tree, ordered by source line number.
+    # Used by both RubyAnalyzer (call graph building) and FlowAssembler
+    # (execution flow ordering).
+    #
+    # @example Extracting calls from a method body
+    #   parser = Ast::Parser.new
+    #   root = parser.parse(source)
+    #   calls = Ast::CallSiteExtractor.new.extract(root)
+    #   calls.first #=> { receiver: "User", method_name: "find", arguments: ["id"], line: 3, block: false }
+    #
+    class CallSiteExtractor
+      # Extract all call sites from an AST node, ordered by line number.
+      #
+      # @param node [Ast::Node] The AST node to search
+      # @return [Array<Hash>] Call site hashes ordered by line ascending
+      def extract(node)
+        calls = []
+        collect_calls(node, calls)
+        calls.sort_by { |c| c[:line] }
+      end
+
+      # Extract only significant call sites, filtering out noise.
+      #
+      # @param node [Ast::Node] The AST node to search
+      # @param known_units [Array<String>] Known unit identifiers for relevance filtering
+      # @return [Array<Hash>] Filtered call site hashes
+      def extract_significant(node, known_units: [])
+        calls = extract(node)
+        known_set = Set.new(known_units)
+
+        calls.reject do |call|
+          INSIGNIFICANT_METHODS.include?(call[:method_name]) &&
+            (known_units.empty? || !known_set.include?(call[:receiver]))
+        end
+      end
+
+      private
+
+      def collect_calls(node, calls)
+        return unless node.is_a?(Ast::Node)
+
+        case node.type
+        when :send
+          calls << {
+            receiver: node.receiver,
+            method_name: node.method_name,
+            arguments: node.arguments || [],
+            line: node.line,
+            block: false
+          }
+        when :block
+          # The send node in a block gets block: true
+          send_child = node.children&.first
+          if send_child.is_a?(Ast::Node) && send_child.type == :send
+            calls << {
+              receiver: send_child.receiver,
+              method_name: send_child.method_name,
+              arguments: send_child.arguments || [],
+              line: send_child.line,
+              block: true
+            }
+          end
+          # Also recurse into block body (children[1])
+          node.children&.drop(1)&.each { |child| collect_calls(child, calls) }
+          return # Don't double-recurse into children
+        end
+
+        (node.children || []).each { |child| collect_calls(child, calls) }
+      end
+    end
+  end
+end

data/lib/codebase_index/ast/method_extractor.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative 'parser'
+require_relative 'node'
+
+module CodebaseIndex
+  module Ast
+    # Extracts method definitions and their source from Ruby source code.
+    #
+    # Replaces the fragile ~240 lines of `nesting_delta` / `neutralize_strings_and_comments`
+    # / `detect_heredoc_start` indentation heuristics in controller and mailer extractors.
+    #
+    # @example Extracting a method's source
+    #   extractor = Ast::MethodExtractor.new
+    #   source = extractor.extract_method_source(code, "create")
+    #   # => "def create\n  @user = User.find(params[:id])\nend\n"
+    #
+    class MethodExtractor
+      # @param parser [Ast::Parser, nil] Parser instance (creates default if nil)
+      def initialize(parser: nil)
+        @parser = parser || Parser.new
+      end
+
+      # Extract a method definition node by name.
+      #
+      # @param source [String] Ruby source code
+      # @param method_name [String] Method name to find
+      # @param class_method [Boolean] If true, look for `def self.method_name`
+      # @return [Ast::Node, nil] The :def or :defs node, or nil if not found
+      def extract_method(source, method_name, class_method: false)
+        root = @parser.parse(source)
+        target_type = class_method ? :defs : :def
+
+        root.find_all(target_type).find do |node|
+          node.method_name == method_name.to_s
+        end
+      end
+
+      # Extract all method definition nodes from source.
+      #
+      # @param source [String] Ruby source code
+      # @return [Array<Ast::Node>] All :def and :defs nodes
+      def extract_all_methods(source)
+        root = @parser.parse(source)
+        root.find_all(:def) + root.find_all(:defs)
+      end
+
+      # Extract the raw source text of a method, including def...end.
+      #
+      # This is the key replacement for `extract_action_source` in the controller
+      # and mailer extractors. Uses AST line tracking instead of indentation heuristics.
+      #
+      # @param source [String] Ruby source code
+      # @param method_name [String] Method name to find
+      # @param class_method [Boolean] If true, look for `def self.method_name`
+      # @return [String, nil] The method source text, or nil if not found
+      def extract_method_source(source, method_name, class_method: false)
+        node = extract_method(source, method_name, class_method: class_method)
+        return nil unless node
+
+        # If the node has a source field populated by the parser, use it
+        return node.source if node.source
+
+        # Fallback: extract by line range
+        return nil unless node.line && node.end_line
+
+        lines = source.lines
+        start_idx = node.line - 1
+        end_idx = node.end_line - 1
+        return nil if start_idx.negative? || end_idx >= lines.length
+
+        lines[start_idx..end_idx].join
+      end
+    end
+  end
+end

data/lib/codebase_index/ast/node.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module CodebaseIndex
+  module Ast
+    # Normalized AST node struct used by all consumers.
+    #
+    # Provides a parser-independent representation of Ruby AST nodes.
+    # Both Prism and the parser gem are normalized to this common structure.
+    #
+    # @example Creating a send node
+    #   node = Ast::Node.new(
+    #     type: :send,
+    #     children: [],
+    #     line: 42,
+    #     receiver: "User",
+    #     method_name: "find",
+    #     arguments: ["id"]
+    #   )
+    #
+    Node = Struct.new(
+      :type,        # Symbol: :send, :block, :if, :def, :defs, :class, :module, :const, :begin, etc.
+      :children,    # Array<Ast::Node | String | Symbol | Integer | nil>
+      :line,        # Integer: 1-based source line number
+      :receiver,    # String | nil: method call receiver (for :send)
+      :method_name, # String | nil: method name (for :send, :def, :defs)
+      :arguments,   # Array<String>: argument representations (for :send)
+      :source,      # String | nil: raw source text of this node
+      :end_line,    # Integer | nil: 1-based end line number (when available)
+      keyword_init: true
+    ) do
+      # Find all descendant nodes matching a type.
+      #
+      # @param target_type [Symbol] The node type to search for
+      # @return [Array<Ast::Node>] All matching descendant nodes
+      def find_all(target_type)
+        results = []
+        queue = [self]
+        while (current = queue.shift)
+          results << current if current.type == target_type
+          (current.children || []).each do |child|
+            queue << child if child.is_a?(Ast::Node)
+          end
+        end
+        results
+      end
+
+      # Find the first descendant node matching a type (depth-first).
+      #
+      # @param target_type [Symbol] The node type to search for
+      # @return [Ast::Node, nil] The first matching node or nil
+      def find_first(target_type)
+        return self if type == target_type
+
+        (children || []).each do |child|
+          next unless child.is_a?(Ast::Node)
+
+          result = child.find_first(target_type)
+          return result if result
+        end
+        nil
+      end
+
+      # Return source text representation.
+      #
+      # @return [String] The source field if present, otherwise a reconstruction
+      def to_source
+        return source if source
+
+        case type
+        when :send
+          parts = []
+          parts << receiver if receiver
+          parts << method_name if method_name
+          parts.join('.')
+        when :const
+          parts = []
+          parts << receiver if receiver
+          parts << method_name if method_name
+          parts.join('::')
+        when :def, :defs
+          "def #{method_name}"
+        else
+          type.to_s
+        end
+      end
+    end
+  end
+end