rubydex 0.2.5 → 0.2.7

data/ext/rubydex/reference.c

@@ -4,6 +4,12 @@
 #include "handle.h"
 #include "location.h"
 #include "rustbindings.h"
+#include "utils.h"
+
+/*
+ * RDoc parser workaround for https://github.com/ruby/rdoc/issues/1744:
+ * mRubydex = rb_define_module("Rubydex")
+ */
 
 VALUE cReference;
 VALUE cConstantReference;
@@ -11,31 +17,29 @@ VALUE cUnresolvedConstantReference;
 VALUE cResolvedConstantReference;
 VALUE cMethodReference;
 
-// ConstantReference#name -> String
+/*
+ * call-seq:
+ *   name -> String
+ *
+ * Returns the unresolved constant name.
+ */
 static VALUE rdxr_constant_reference_name(VALUE self) {
     HandleData *data;
-    TypedData_Get_Struct(self, HandleData, &handle_type, data);
-
-    void *graph;
-    TypedData_Get_Struct(data->graph_obj, void *, &graph_type, graph);
+    void *graph = rdxi_graph_from_handle(self, &data);
 
     const char *name = rdx_constant_reference_name(graph, data->id);
-    if (name == NULL) {
-        return Qnil;
-    }
-
-    VALUE str = rb_utf8_str_new_cstr(name);
-    free_c_string(name);
-    return str;
+    return rdxi_owned_c_string_to_ruby(name);
 }
 
-// ConstantReference#location -> Rubydex::Location
+/*
+ * call-seq:
+ *   location -> Rubydex::Location
+ *
+ * Returns the source location for this constant reference.
+ */
 static VALUE rdxr_constant_reference_location(VALUE self) {
     HandleData *data;
-    TypedData_Get_Struct(self, HandleData, &handle_type, data);
-
-    void *graph;
-    TypedData_Get_Struct(data->graph_obj, void *, &graph_type, graph);
+    void *graph = rdxi_graph_from_handle(self, &data);
 
     Location *loc = rdx_constant_reference_location(graph, data->id);
     VALUE location = rdxi_build_location_value(loc);
@@ -43,31 +47,29 @@ static VALUE rdxr_constant_reference_location(VALUE self) {
     return location;
 }
 
-// MethodReference#name -> String
+/*
+ * call-seq:
+ *   name -> String
+ *
+ * Returns the referenced method name.
+ */
 static VALUE rdxr_method_reference_name(VALUE self) {
     HandleData *data;
-    TypedData_Get_Struct(self, HandleData, &handle_type, data);
-
-    void *graph;
-    TypedData_Get_Struct(data->graph_obj, void *, &graph_type, graph);
+    void *graph = rdxi_graph_from_handle(self, &data);
 
     const char *name = rdx_method_reference_name(graph, data->id);
-    if (name == NULL) {
-        return Qnil;
-    }
-
-    VALUE str = rb_utf8_str_new_cstr(name);
-    free_c_string(name);
-    return str;
+    return rdxi_owned_c_string_to_ruby(name);
 }
 
-// MethodReference#location -> Rubydex::Location
+/*
+ * call-seq:
+ *   location -> Rubydex::Location
+ *
+ * Returns the source location for this method reference.
+ */
 static VALUE rdxr_method_reference_location(VALUE self) {
     HandleData *data;
-    TypedData_Get_Struct(self, HandleData, &handle_type, data);
-
-    void *graph;
-    TypedData_Get_Struct(data->graph_obj, void *, &graph_type, graph);
+    void *graph = rdxi_graph_from_handle(self, &data);
 
     Location *loc = rdx_method_reference_location(graph, data->id);
     VALUE location = rdxi_build_location_value(loc);
@@ -75,15 +77,16 @@ static VALUE rdxr_method_reference_location(VALUE self) {
     return location;
 }
 
-// MethodReference#receiver -> Rubydex::Declaration?
-// Returns the resolved declaration for the receiver of the method call. Returns nil when the receiver is not a
-// tracked constant or cannot be resolved.
+/*
+ * call-seq:
+ *   receiver -> Rubydex::Declaration?
+ *
+ * Returns the resolved declaration for the receiver of the method call. Returns nil when the receiver is not a tracked
+ * constant or cannot be resolved.
+ */
 static VALUE rdxr_method_reference_receiver(VALUE self) {
     HandleData *data;
-    TypedData_Get_Struct(self, HandleData, &handle_type, data);
-
-    void *graph;
-    TypedData_Get_Struct(data->graph_obj, void *, &graph_type, graph);
+    void *graph = rdxi_graph_from_handle(self, &data);
 
     const struct CDeclaration *decl = rdx_method_reference_receiver_declaration(graph, data->id);
     if (decl == NULL) {
@@ -97,13 +100,15 @@ static VALUE rdxr_method_reference_receiver(VALUE self) {
     return rb_class_new_instance(2, argv, decl_class);
 }
 
-// ResolvedConstantReference#declaration -> Declaration
+/*
+ * call-seq:
+ *   declaration -> Rubydex::Declaration
+ *
+ * Returns the resolved declaration.
+ */
 static VALUE rdxr_resolved_constant_reference_declaration(VALUE self) {
     HandleData *data;
-    TypedData_Get_Struct(self, HandleData, &handle_type, data);
-
-    void *graph;
-    TypedData_Get_Struct(data->graph_obj, void *, &graph_type, graph);
+    void *graph = rdxi_graph_from_handle(self, &data);
 
     const struct CDeclaration *decl = rdx_resolved_constant_reference_declaration(graph, data->id);
     if (decl == NULL) {

data/ext/rubydex/rubydex.c

@@ -12,6 +12,11 @@ VALUE mRubydex;
 void Init_rubydex(void) {
     rb_ext_ractor_safe(true);
 
+    /*
+     * Document-module: Rubydex
+     *
+     * Namespace for Rubydex's Ruby API.
+     */
     mRubydex = rb_define_module("Rubydex");
     rdxi_initialize_graph(mRubydex);
     rdxi_initialize_declaration(mRubydex);

data/ext/rubydex/signature.c

@@ -1,6 +1,11 @@
 #include "signature.h"
 #include "location.h"
 
+/*
+ * RDoc parser workaround for https://github.com/ruby/rdoc/issues/1744:
+ * mRubydex = rb_define_module("Rubydex")
+ */
+
 static VALUE empty_params = Qundef;
 
 VALUE cSignature;

data/ext/rubydex/utils.c

@@ -39,6 +39,19 @@ void rdxi_check_array_of_strings(VALUE array) {
     }
 }
 
+// Convert a Rust-owned C string to a Ruby string and release it with free_c_string.
+// Returns nil when the Rust side returned NULL.
+VALUE rdxi_owned_c_string_to_ruby(const char *string) {
+    if (string == NULL) {
+        return Qnil;
+    }
+
+    VALUE value = rb_utf8_str_new_cstr(string);
+    free_c_string(string);
+
+    return value;
+}
+
 // Yield body for iterating over declarations
 VALUE rdxi_declarations_yield(VALUE args) {
     VALUE self = rb_ary_entry(args, 0);

data/ext/rubydex/utils.h

@@ -13,6 +13,10 @@ void rdxi_free_str_array(char **array, size_t length);
 // Verify that the Ruby object is an array of strings or raise `TypeError`
 void rdxi_check_array_of_strings(VALUE array);
 
+// Convert a Rust-owned C string to a Ruby string and release it with free_c_string.
+// Returns nil when the Rust side returned NULL.
+VALUE rdxi_owned_c_string_to_ruby(const char *string);
+
 // Yield body for iterating over declarations
 VALUE rdxi_declarations_yield(VALUE args);
 

data/lib/rubydex/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Rubydex
+  class Error < StandardError; end
+
+  # Raised when `MethodAliasDefinition#target` walks an alias chain that loops back on itself.
+  class AliasCycleError < Error; end
+
+  # Raised by `Graph#load_config` when the requested config file does not exist, cannot be read, or is malformed
+  class ConfigError < Error; end
+end

data/lib/rubydex/graph.rb

@@ -5,49 +5,30 @@ module Rubydex
   #
   # Note: this class is partially defined in C to integrate with the Rust backend
   class Graph
-    IGNORED_DIRECTORIES = [
-      ".bundle",
-      ".claude",
-      ".git",
-      ".github",
-      ".ruby-lsp",
-      ".vscode",
-      "log",
-      "node_modules",
-      "tmp",
-    ].freeze
-
     INDEXABLE_EXTENSIONS = [".rb", ".rake", ".rbs", ".ru"].freeze
 
-    #: String
-    attr_accessor :workspace_path
-
-    #: (?workspace_path: String) -> void
-    def initialize(workspace_path: Dir.pwd)
-      @workspace_path = workspace_path
-
-      exclude_paths(IGNORED_DIRECTORIES.map { |dir| File.join(@workspace_path, dir) })
+    #: (?workspace_path: String?) -> void
+    def initialize(workspace_path: nil)
+      self.workspace_path = workspace_path if workspace_path
     end
 
-    # Index all files and dependencies of the workspace that exists in `@workspace_path`
+    # Index all files and dependencies of the workspace that exists in `workspace_path`
     #: -> Array[String]
     def index_workspace
       index_all(workspace_paths)
     end
 
-    # Returns all workspace paths that should be indexed, excluding directories that we don't need to descend into such
-    # as `.git`, `node_modules`. Also includes any top level Ruby files
+    # Returns all workspace paths that should be indexed
     #
     #: -> Array[String]
     def workspace_paths
       paths = []
+      root = workspace_path
 
-      Dir.each_child(@workspace_path) do |entry|
-        full_path = File.join(@workspace_path, entry)
+      Dir.each_child(root) do |entry|
+        full_path = File.join(root, entry)
 
-        if File.directory?(full_path)
-          paths << full_path unless IGNORED_DIRECTORIES.include?(entry)
-        elsif INDEXABLE_EXTENSIONS.include?(File.extname(entry))
+        if File.directory?(full_path) || INDEXABLE_EXTENSIONS.include?(File.extname(entry))
           paths << full_path
         end
       end

data/lib/rubydex/location.rb

@@ -14,6 +14,19 @@ module Rubydex
     #: Integer
     attr_reader :start_line, :end_line, :start_column, :end_column
 
+    class << self
+      #: (Prism::Location prism_location, uri: String) -> Location
+      def from_prism(prism_location, uri:)
+        Location.new(
+          uri: uri,
+          start_line: prism_location.start_line - 1,
+          start_column: prism_location.start_column,
+          end_line: prism_location.end_line - 1,
+          end_column: prism_location.end_column,
+        )
+      end
+    end
+
     #: (?uri: String, ?start_line: Integer, ?end_line: Integer, ?start_column: Integer, ?end_column: Integer) -> void
     def initialize(uri:, start_line:, end_line:, start_column:, end_column:)
       @uri = uri
@@ -68,6 +81,17 @@ module Rubydex
   # A one based location intended for display purposes. This is what should be used when displaying a location to users,
   # like in CLIs
   class DisplayLocation < Location
+    class << self
+      #: (Prism::Location prism_location, uri: String) -> Location
+      def from_prism(prism_location, uri:)
+        raise NotImplementedError, <<~MESSAGE
+          Cannot convert Prism::Location directly to a Rubydex::DisplayLocation.
+          Start with `Rubydex::Location.from_prism(...)` and then convert the resulting
+          location with `to_display`
+        MESSAGE
+      end
+    end
+
     # Returns itself
     #
     #: () -> DisplayLocation

data/lib/rubydex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rubydex
-  VERSION = "0.2.5"
+  VERSION = "0.2.7"
 end

data/lib/rubydex.rb

@@ -14,6 +14,7 @@ rescue LoadError
   require "rubydex/rubydex"
 end
 
+require "rubydex/errors"
 require "rubydex/failures"
 require "rubydex/location"
 require "rubydex/comment"

data/rbi/rubydex.rbi

@@ -174,7 +174,12 @@ class Rubydex::ConstantDefinition < Rubydex::Definition; end
 class Rubydex::GlobalVariableAliasDefinition < Rubydex::Definition; end
 class Rubydex::GlobalVariableDefinition < Rubydex::Definition; end
 class Rubydex::InstanceVariableDefinition < Rubydex::Definition; end
-class Rubydex::MethodAliasDefinition < Rubydex::Definition; end
+
+class Rubydex::MethodAliasDefinition < Rubydex::Definition
+  sig { returns(T.nilable(Rubydex::Method)) }
+  def target; end
+end
+
 class Rubydex::MethodDefinition < Rubydex::Definition; end
 
 class Rubydex::ModuleDefinition < Rubydex::Definition
@@ -246,6 +251,9 @@ class Rubydex::Document
   sig { returns(T::Enumerable[Rubydex::Definition]) }
   def definitions; end
 
+  sig { returns(T::Enumerable[Rubydex::MethodReference]) }
+  def method_references; end
+
   sig { returns(String) }
   def uri; end
 
@@ -257,6 +265,8 @@ class Rubydex::Document
 end
 
 class Rubydex::Error < StandardError; end
+class Rubydex::AliasCycleError < Rubydex::Error; end
+class Rubydex::ConfigError < Rubydex::Error; end
 
 class Rubydex::Failure
   sig { params(message: String).void }
@@ -269,8 +279,6 @@ end
 class Rubydex::IntegrityFailure < Rubydex::Failure; end
 
 class Rubydex::Graph
-  IGNORED_DIRECTORIES = T.let(T.unsafe(nil), T::Array[String])
-
   sig { params(workspace_path: T.nilable(String)).void }
   def initialize(workspace_path: nil); end
 
@@ -301,10 +309,17 @@ class Rubydex::Graph
   sig { params(uri: String, source: String, language_id: String).void }
   def index_source(uri, source, language_id); end
 
-  # Index all files and dependencies of the workspace that exists in `@workspace_path`
+  # Index all files and dependencies of the workspace that exists in `workspace_path`
   sig { returns(T::Array[String]) }
   def index_workspace; end
 
+  # Loads configuration, merging its excluded paths into the graph's configuration (the workspace path is never
+  # overridden). With `config_path` (resolved relative to the workspace path), an explicitly named file that does not
+  # exist raises `Rubydex::ConfigError`. With no argument, the default `.rubydex` is loaded if present and ignored if
+  # missing. Raises `Rubydex::ConfigError` if a file cannot be read or is malformed.
+  sig { params(config_path: T.nilable(String)).void }
+  def load_config(config_path = nil); end
+
   sig { returns(T::Enumerable[Rubydex::MethodReference]) }
   def method_references; end
 
@@ -344,48 +359,48 @@ class Rubydex::Graph
   # Returns completion candidates for an expression context. This includes all keywords, constants, methods, instance
   # variables, class variables and global variables reachable from the current lexical scope and self type.
   #
-  # The nesting array represents the lexical scope stack. The optional `self_receiver` keyword argument overrides the
+  # The nesting array represents the lexical scope stack. The required `self_receiver` keyword argument overrides the
   # self type independently of the lexical scope (e.g., `"Foo::<Foo>"` for `def Foo.bar`). This distinction is important
   # because constants and class variables are always attached to the lexical scope. Meanwhile, methods and instance
-  # variables are attached to the type of `self` and those don't always match.
+  # variables are attached to the type of `self` and those don't always match. Pass `nil` when the self type is unknown
   sig do
     params(
       nesting: T::Array[String],
       self_receiver: T.nilable(String),
     ).returns(T::Array[T.any(Rubydex::Declaration, Rubydex::Keyword)])
   end
-  def complete_expression(nesting, self_receiver: nil); end
+  def complete_expression(nesting, self_receiver:); end
 
   # Returns completion candidates after a namespace access operator (e.g., `Foo::`). This includes all constants and
   # singleton methods for the namespace and its ancestors.
   #
-  # The optional `self_receiver` kwarg is the caller's runtime self type. It's used to filter visibility-restricted
-  # singleton methods (e.g., `private_class_method`). Pass `nil` (the default) for top-level/script scope.
+  # The required `self_receiver` kwarg is the caller's runtime self type. It's used to filter visibility-restricted
+  # singleton methods (e.g., `private_class_method`). Pass `nil` for top-level/script scope.
   sig do
     params(
       name: String,
       self_receiver: T.nilable(String),
     ).returns(T::Array[Rubydex::Declaration])
   end
-  def complete_namespace_access(name, self_receiver: nil); end
+  def complete_namespace_access(name, self_receiver:); end
 
   # Returns completion candidates after a method call operator (e.g., `foo.`). This includes all methods that exist on
   # the type of the receiver and its ancestors.
   #
-  # The optional `self_receiver` kwarg is the caller's runtime self type. It's used for visibility checks for `private`
-  # and `protected` methods. Pass `nil` (the default) for top-level/script scope.
+  # The required `self_receiver` kwarg is the caller's runtime self type. It's used for visibility checks for `private`
+  # and `protected` methods. Pass `nil` for top-level/script scope.
   sig do
     params(
       name: String,
       self_receiver: T.nilable(String),
     ).returns(T::Array[Rubydex::Method])
   end
-  def complete_method_call(name, self_receiver: nil); end
+  def complete_method_call(name, self_receiver:); end
 
   # Returns completion candidates inside a method call's argument list (e.g., `foo.bar(|)`). This includes everything
   # that expression completion provides plus keyword argument names of the method being called.
   #
-  # See `complete_expression` for the semantics of `nesting` and `self_receiver`.
+  # See `complete_expression` for the semantics of `nesting` and `self_receiver` (required, may be `nil`).
   sig do
     params(
       name: String,
@@ -393,7 +408,7 @@ class Rubydex::Graph
       self_receiver: T.nilable(String),
     ).returns(T::Array[T.any(Rubydex::Declaration, Rubydex::Keyword, Rubydex::KeywordParameter)])
   end
-  def complete_method_argument(name, nesting, self_receiver: nil); end
+  def complete_method_argument(name, nesting, self_receiver:); end
 
   private
 
@@ -411,6 +426,11 @@ class Rubydex::Graph
 end
 
 class Rubydex::DisplayLocation < Rubydex::Location
+  class << self
+    sig { params(prism_location: Prism::Location, uri: String).returns(T.noreturn) }
+    def from_prism(prism_location, uri:); end
+  end
+
   sig { returns([String, Integer, Integer, Integer, Integer]) }
   def comparable_values; end
 
@@ -424,6 +444,11 @@ end
 class Rubydex::Location
   include ::Comparable
 
+  class << self
+    sig { params(prism_location: Prism::Location, uri: String).returns(Rubydex::Location) }
+    def from_prism(prism_location, uri:); end
+  end
+
   sig do
     params(
       uri: String,