rubydex 0.2.8 → 0.3.0

data/ext/rubydex/utils.h

@@ -17,6 +17,11 @@ void rdxi_check_array_of_strings(VALUE array);
 // Returns nil when the Rust side returned NULL.
 VALUE rdxi_owned_c_string_to_ruby(const char *string);
 
+// Coerce an optional String, Symbol, or nil to a C string, returning `default_value` when the value
+// is nil. A non-nil value must be a String or Symbol, otherwise a `TypeError` is raised. The
+// returned pointer is owned by the Ruby VALUE and is only valid while it stays live.
+const char *rdxi_symbol_or_string_cstr(VALUE value, const char *default_value);
+
 // Yield body for iterating over declarations
 VALUE rdxi_declarations_yield(VALUE args);
 

data/lib/rubydex/mcp_server/protocol.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rubydex
+  module MCPServer
+    module JSONRPC
+      PARSE_ERROR = -32_700
+      INVALID_REQUEST = -32_600
+      METHOD_NOT_FOUND = -32_601
+      INVALID_PARAMS = -32_602
+      INTERNAL_ERROR = -32_603
+
+      class << self
+        #: (untyped, Integer, String, ?data: untyped) -> Hash
+        def error_response(id, code, message, data: nil)
+          {
+            jsonrpc: "2.0",
+            id: id,
+            error: {
+              code: code,
+              message: message,
+              data: data,
+            }.compact,
+          }
+        end
+      end
+    end
+
+    class Error
+      #: (String, ?String, ?String) -> void
+      def initialize(error, message = nil, suggestion = nil)
+        @error = error
+        @message = message
+        @suggestion = suggestion
+      end
+
+      #: (*untyped) -> String
+      def to_json(*args)
+        payload = { error: @error }
+        payload[:message] = @message if @message
+        payload[:suggestion] = @suggestion if @suggestion
+        payload.to_json(*args)
+      end
+    end
+
+    class Tool
+      @tools = []
+
+      class Response
+        #: (Array[Hash], ?bool) -> void
+        def initialize(content, error: false)
+          @content = content
+          @error = error
+        end
+
+        attr_reader :content
+
+        #: -> bool
+        def error?
+          @error
+        end
+
+        #: -> Hash
+        def to_h
+          {
+            content: content,
+            isError: error?,
+          }
+        end
+      end
+
+      class << self
+        attr_reader :tools
+
+        #: (Class) -> void
+        def inherited(tool)
+          Tool.tools << tool unless tool.name&.end_with?("::BaseTool")
+          super
+        end
+
+        #: -> Hash[String, Class]
+        def tools_by_name
+          tools.to_h { |tool| [tool.tool_name, tool] }
+        end
+
+        #: (?String) -> String
+        def tool_name(value = nil)
+          @tool_name = value if value
+          @tool_name || raise(NotImplementedError, "#{name} must define tool_name")
+        end
+
+        #: (?String) -> String
+        def description(value = nil)
+          @description = value if value
+          @description || raise(NotImplementedError, "#{name} must define description")
+        end
+
+        #: (?Hash, ?Array[String]) -> Hash
+        def input_schema(properties: nil, required: nil)
+          if properties
+            @input_schema = {
+              type: "object",
+              properties: properties,
+            }
+            @input_schema[:required] = required if required
+          end
+
+          @input_schema || { type: "object", properties: {} }
+        end
+
+        #: -> Hash
+        def to_h
+          {
+            name: tool_name,
+            description: description,
+            inputSchema: input_schema,
+          }
+        end
+      end
+    end
+
+    class StdioTransport
+      #: -> void
+      def initialize
+        @input = $stdin
+        @output = $stdout
+        @input.binmode
+        @input.sync = true
+        @output.binmode
+        @output.sync = true
+      end
+
+      #: { (Hash | Array?, Hash?) -> void } -> void
+      def open
+        @input.each_line do |line|
+          yield JSON.parse(line, symbolize_names: true)
+        rescue JSON::ParserError
+          yield nil, JSONRPC.error_response(nil, JSONRPC::PARSE_ERROR, "Parse error", data: "Invalid JSON")
+        end
+      end
+
+      #: (Hash | Array[Hash]?) -> void
+      def write(response)
+        return unless response
+
+        @output.puts(JSON.generate(response))
+      end
+
+      #: -> void
+      def close
+        @output.flush
+      end
+    end
+  end
+end

data/lib/rubydex/mcp_server/tools/base_tool.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+require "uri"
+
+module Rubydex
+  module MCPServer
+    class BaseTool < Tool
+      DEFAULT_LIMIT = 50
+
+      #: (Graph) -> void
+      def initialize(graph)
+        super()
+        @graph = graph
+        @root_path = graph.workspace_path
+      end
+
+      #: (Hash | Error) -> Tool::Response
+      def response(payload)
+        Tool::Response.new([{ type: "text", text: JSON.generate(payload) }])
+      end
+
+      #: (Declaration) -> String
+      def declaration_kind(declaration)
+        return "<TODO>" if declaration.is_a?(Rubydex::Todo)
+
+        declaration.class.name.delete_prefix("Rubydex::")
+      end
+
+      #: (String) -> String
+      def format_path(uri)
+        path = file_path_for_uri(uri)
+        return uri unless path
+
+        absolute_path = File.expand_path(path)
+        absolute_root = File.expand_path(@root_path)
+        relative_path = Pathname.new(absolute_path).relative_path_from(Pathname.new(absolute_root)).to_s
+
+        relative_path.start_with?("..") ? absolute_path : relative_path
+      end
+
+      #: (String) -> String?
+      def file_path_for_uri(uri)
+        parsed = URI.parse(uri)
+        return unless parsed.scheme == "file"
+
+        path = URI.decode_uri_component(parsed.path)
+        path.delete_prefix!("/") if Gem.win_platform?
+        path
+      rescue URI::InvalidURIError, ArgumentError
+        nil
+      end
+
+      #: (String) -> Document?
+      def document_for_path(file_path)
+        absolute_target = if Pathname.new(file_path).absolute?
+          file_path
+        else
+          File.join(@root_path, file_path)
+        end
+        canonical_target = File.realpath(absolute_target)
+        @graph.documents.find do |document|
+          path = file_path_for_uri(document.uri)
+          path && File.expand_path(path) == canonical_target
+        end
+      end
+
+      #: (Location) -> Hash
+      def display_location(location)
+        display = location.to_display
+        {
+          path: format_path(display.uri),
+          line: display.start_line,
+        }
+      end
+
+      #: (Enumerable, Integer?, Integer?, Integer) -> [Array, Integer]
+      def paginate(items, offset, limit, max_limit)
+        offset = (offset || 0).to_i
+        offset = 0 unless offset.positive?
+        limit = (limit || DEFAULT_LIMIT).to_i
+        limit = DEFAULT_LIMIT unless limit.positive?
+        limit = [limit, max_limit].min
+
+        page = []
+        index = 0
+        items.each do |item|
+          page << item if index >= offset && page.length < limit
+          index += 1
+        end
+
+        [page, index]
+      end
+
+      #: (String) -> Declaration | Error
+      def lookup_declaration(name)
+        declaration = @graph[name]
+        return declaration if declaration
+
+        Error.new(
+          "not_found",
+          "Declaration '#{name}' not found",
+          "Try search_declarations with a partial name to find the correct FQN",
+        )
+      end
+    end
+  end
+end

data/lib/rubydex/mcp_server/tools/codebase_stats_tool.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Rubydex
+  module MCPServer
+    class CodebaseStatsTool < BaseTool
+      tool_name "codebase_stats"
+      description "Get an overview of the indexed Ruby codebase: total file count, declaration counts, and breakdown by kind (classes, modules, methods, constants). Use this to understand codebase size and composition, or to verify that indexing completed successfully."
+      input_schema(properties: {})
+
+      #: -> Tool::Response
+      def call
+        declaration_count = 0
+        breakdown = Hash.new(0)
+        @graph.declarations.each do |declaration|
+          declaration_count += 1
+          breakdown[declaration_kind(declaration)] += 1
+        end
+
+        response(
+          files: @graph.documents.count,
+          declarations: declaration_count,
+          definitions: @graph.documents.sum { |document| document.definitions.count },
+          constant_references: @graph.constant_references.count,
+          method_references: @graph.method_references.count,
+          breakdown_by_kind: breakdown,
+        )
+      end
+    end
+  end
+end

data/lib/rubydex/mcp_server/tools/find_constant_references_tool.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Rubydex
+  module MCPServer
+    class FindConstantReferencesTool < BaseTool
+      tool_name "find_constant_references"
+      description "Find all resolved references to a Ruby class, module, or constant across the codebase. Returns file paths, line numbers, and columns for each usage. Results are paginated: the response includes `total`. If `total` exceeds the number of returned results, use `offset` to fetch subsequent pages."
+      input_schema(
+        properties: {
+          name: { type: "string", description: "Fully qualified name of the class, module, or constant to find references for" },
+          limit: { type: "integer", description: "Maximum number of references to return (default 50, max 200)" },
+          offset: { type: "integer", description: "Number of references to skip for pagination (default 0)" },
+        },
+        required: ["name"],
+      )
+
+      #: (name: String, ?limit: Integer, ?offset: Integer) -> Tool::Response
+      def call(name:, limit: nil, offset: nil)
+        declaration = lookup_declaration(name)
+
+        case declaration
+        when Error
+          response(declaration)
+        else
+          references = case declaration
+          when Rubydex::Namespace, Rubydex::Constant, Rubydex::ConstantAlias
+            declaration.references
+          else
+            []
+          end
+          page, total = paginate(references, offset, limit, 200)
+          payload = page.map do |reference|
+            display = reference.location.to_display
+            {
+              path: format_path(display.uri),
+              line: display.start_line,
+              column: display.start_column,
+            }
+          end
+
+          response(name: name, references: payload, total: total)
+        end
+      end
+    end
+  end
+end

data/lib/rubydex/mcp_server/tools/get_declaration_tool.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Rubydex
+  module MCPServer
+    class GetDeclarationTool < BaseTool
+      tool_name "get_declaration"
+      description 'Get complete information about a Ruby class, module, method, or constant by its exact fully qualified name. Returns file locations, documentation comments, ancestor chain, and members with locations. FQN format: "Foo::Bar" for classes/modules/constants, "Foo::Bar#method_name" for instance methods, "Foo::Bar::<Bar>" for singleton classes, and "Foo::Bar::<Bar>#method_name" for class methods.'
+      input_schema(
+        properties: {
+          name: { type: "string", description: "Fully qualified name of the declaration (e.g. 'Foo::Bar', 'Foo::Bar#baz')" },
+        },
+        required: ["name"],
+      )
+
+      #: (name: String) -> Tool::Response
+      def call(name:)
+        declaration = lookup_declaration(name)
+
+        case declaration
+        when Error
+          response(declaration)
+        else
+          definitions = declaration.definitions.map do |definition|
+            display_location(definition.location).merge(
+              comments: definition.comments.map do |comment|
+                comment.string.delete_prefix("# ")
+              end,
+            )
+          end
+
+          ancestors = if declaration.is_a?(Rubydex::Namespace)
+            declaration.ancestors.map do |ancestor|
+              {
+                name: ancestor.name,
+                kind: declaration_kind(ancestor),
+              }
+            end
+          else
+            []
+          end
+
+          members = if declaration.is_a?(Rubydex::Namespace)
+            declaration.members.map do |member|
+              payload = {
+                name: member.name,
+                kind: declaration_kind(member),
+              }
+
+              definition = member.definitions.first
+              payload[:location] = display_location(definition.location) if definition
+              payload
+            end
+          else
+            []
+          end
+
+          response(
+            name: declaration.name,
+            kind: declaration_kind(declaration),
+            definitions: definitions,
+            ancestors: ancestors,
+            members: members,
+          )
+        end
+      end
+    end
+  end
+end

data/lib/rubydex/mcp_server/tools/get_descendants_tool.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Rubydex
+  module MCPServer
+    class GetDescendantsTool < BaseTool
+      tool_name "get_descendants"
+      description "Returns all known descendants for the given namespace including itself and all transitive descendants. Can be used to understand how a module/class is used across the codebase. Results are paginated: the response includes `total`. If `total` exceeds the number of returned results, use `offset` to fetch subsequent pages."
+      input_schema(
+        properties: {
+          name: { type: "string", description: "Fully qualified name of the class or module" },
+          limit: { type: "integer", description: "Maximum number of descendants to return (default 50, max 500)" },
+          offset: { type: "integer", description: "Number of descendants to skip for pagination (default 0)" },
+        },
+        required: ["name"],
+      )
+
+      #: (name: String, ?limit: Integer, ?offset: Integer) -> Tool::Response
+      def call(name:, limit: nil, offset: nil)
+        declaration = lookup_declaration(name)
+
+        case declaration
+        when Error
+          response(declaration)
+        when Rubydex::Namespace
+          page, total = paginate(declaration.descendants, offset, limit, 500)
+          descendants = page.map do |descendant|
+            {
+              name: descendant.name,
+              kind: declaration_kind(descendant),
+            }
+          end
+
+          response(name: declaration.name, descendants: descendants, total: total)
+        else
+          response(
+            Error.new(
+              "invalid_kind",
+              "'#{name}' is not a class or module (it is a #{declaration_kind(declaration)})",
+              "get_descendants only works on classes and modules, not methods or constants",
+            ),
+          )
+        end
+      end
+    end
+  end
+end

data/lib/rubydex/mcp_server/tools/get_file_declarations_tool.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Rubydex
+  module MCPServer
+    class GetFileDeclarationsTool < BaseTool
+      tool_name "get_file_declarations"
+      description "List all Ruby classes, modules, methods, and constants defined in a specific file. Returns a structural overview with names, kinds, and line numbers. Use this to understand a file's structure before reading it, or to see what a file contributes to the codebase. Accepts relative or absolute paths."
+      input_schema(
+        properties: {
+          file_path: { type: "string", description: "File path (relative or absolute) to list declarations for" },
+        },
+        required: ["file_path"],
+      )
+
+      #: (file_path: String) -> Tool::Response
+      def call(file_path:)
+        absolute_target = if Pathname.new(file_path).absolute?
+          file_path
+        else
+          File.join(@root_path, file_path)
+        end
+        return file_not_found_response(file_path) unless File.exist?(absolute_target)
+
+        document = document_for_path(file_path)
+        return file_not_found_response(file_path) unless document
+
+        declarations = document.definitions.filter_map do |definition|
+          declaration = definition.declaration
+          next unless declaration
+
+          {
+            name: declaration.name,
+            kind: declaration_kind(declaration),
+            line: definition.location.to_display.start_line,
+          }
+        end
+
+        response(file: format_path(document.uri), declarations: declarations)
+      end
+
+      private
+
+      #: (String) -> Tool::Response
+      def file_not_found_response(file_path)
+        response(
+          Error.new(
+            "not_found",
+            "File '#{file_path}' not found in the index",
+            "Use a relative path like 'app/models/user.rb' or an absolute path matching the indexed project",
+          ),
+        )
+      end
+    end
+  end
+end

data/lib/rubydex/mcp_server/tools/search_declarations_tool.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Rubydex
+  module MCPServer
+    class SearchDeclarationsTool < BaseTool
+      tool_name "search_declarations"
+      description 'Search for Ruby classes, modules, methods, or constants by name. Use this INSTEAD OF Grep when you know part of a Ruby identifier name and want to find its definition. Returns fully qualified names, kinds, and file locations. Use the `kind` filter ("Class", "Module", "Method", "Constant") to narrow results. Set `match_mode` to "exact" for precise substring matching or "fuzzy" for LSP-style workspace symbol search (default). Results are paginated: the response includes `total` (the full count of matches). If `total` exceeds the number of returned results, use `offset` to fetch subsequent pages.'
+      input_schema(
+        properties: {
+          query: { type: "string", description: "Search query to match against declaration names" },
+          kind: { type: "string", description: "Filter by declaration kind: Class, Module, Method, Constant, etc." },
+          match_mode: { type: "string", description: 'Matching mode: "fuzzy" (default) for LSP-style workspace symbol search, or "exact" for precise substring matching' },
+          limit: { type: "integer", description: "Maximum number of results to return (default 50, max 100)" },
+          offset: { type: "integer", description: "Number of results to skip for pagination (default 0)" },
+        },
+        required: ["query"],
+      )
+
+      #: (query: String, ?kind: String, ?match_mode: String, ?limit: Integer, ?offset: Integer) -> Tool::Response
+      def call(query:, kind: nil, match_mode: nil, limit: nil, offset: nil)
+        declarations = case match_mode
+        when nil, "fuzzy"
+          @graph.fuzzy_search(query)
+        when "exact"
+          @graph.search(query)
+        else
+          return response(
+            Error.new(
+              "invalid_match_mode",
+              "Invalid match_mode '#{match_mode}'",
+              'Use "fuzzy" or "exact"',
+            ),
+          )
+        end
+
+        if kind
+          declarations = declarations.lazy.select { |declaration| declaration_kind(declaration).casecmp?(kind) }
+        end
+
+        page, total = paginate(declarations, offset, limit, 100)
+        results = page.map do |declaration|
+          {
+            name: declaration.name,
+            kind: declaration_kind(declaration),
+            locations: declaration.definitions.map do |definition|
+              display_location(definition.location)
+            end,
+          }
+        end
+
+        response(results: results, total: total)
+      end
+    end
+  end
+end