rubydex 0.1.0.beta3-x86_64-linux → 0.1.0.beta4-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2de40c7335743a85b7d61d9a513d40b29fcecf62e19cfff8ef2637cd4297b6a8
-  data.tar.gz: 99bed4d413ab7e1bd97f76965906037d1da29f12af8dba7f19f48d5665c73bc5
+  metadata.gz: 5092c197150819521964a1d1d88c5080da95f9a6ca24e11837acf5dd51b6780b
+  data.tar.gz: 3aee088ac6701a796266b4f53a0cdebc67077c67387690c1f74fdbac0cc7b498
 SHA512:
-  metadata.gz: 29ef5b84c94af6eb1608d42acbc7a0c5c115fef6317645b369fca27c1c1714c64a21dba7a1b10f490939fbf547583fbed20db30d26e9ad4f42b9c8079c8b7e6c
-  data.tar.gz: e4d9dce9acf24ef5c704dab14d89a82143c39e259e8923fc71830abe600b54240094a8e287aa647b62e419fac42db6e1c3f4b59d20b29498d1b5872865083dd5
+  metadata.gz: 5d5fbd813087afac50aa5a09985a6dfd11a1432a63261931e4ffe78e1a9b39df65a3cb09c62154ef40b740047bded05e649ab4aad44faa9169ce45de7312a495
+  data.tar.gz: '09cc63dc59639e3636ff5fff1847c3dd1c12cf05108ee5e25670c7787179b9eb9a0c3f795bb6ab191d590357d1990e5898b7e4086b9bba34ef20d536d66e5808'

data/README.md

@@ -11,13 +11,70 @@ of using the Ruby API:
 ```ruby
 # Create a new graph representing the current workspace
 graph = Rubydex::Graph.new
+# Configuring graph LSP encoding
+graph.set_encoding("utf16")
 # Index the entire workspace with all dependencies
 graph.index_workspace
+# Or index specific file paths
+graph.index_all(["path/to/file.rb"])
 # Transform the initially collected information into its semantic understanding by running resolution
 graph.resolve
+# Get all diagnostics acquired during the analysis
+graph.diagnostics
 
-# Access the information as needed
-graph["Foo"]
+# Iterating over graph nodes
+graph.declarations
+graph.documents
+graph.constant_references
+graph.method_references
+
+# Analyzing require paths
+graph.resolve_require_path("rails/engine", load_paths) # => document pointed by `rails/engine`
+graph.require_paths(load_paths) # => array of all indexed require paths
+
+# Querying
+graph["Foo"] # Get declaration by fully qualified name
+graph.search("Foo#b") # Name search
+graph.resolve_constant("Bar", ["Foo", "Baz::Qux"]) # Resolve constant reference based on nesting
+
+# Declarations
+declaration = graph["Foo"]
+
+# All declarations include
+declaration.name
+declaration.unqualified_name
+declaration.definitions
+declaration.owner
+
+# Namespace declarations include
+declaration.member("bar()")
+declaration.member("@ivar")
+declaration.singleton_class
+declaration.ancestors
+declaration.descendants
+
+# Documents
+document = graph.documents.first
+document.uri
+document.definitions # => list of definitions discovered in this document
+
+# Definitions
+definition = declaration.definitions.first
+definition.location
+definition.comments
+definition.name
+definition.deprecated?
+definition.name_location
+
+# Locations
+location = definition.location
+location.path
+
+# Diagnostics
+diagnostic = graph.diagnostics.first
+diagnostic.rule
+diagnostic.message
+diagnostic.location
 ```
 
 ## Contributing

data/ext/rubydex/graph.c

@@ -9,7 +9,6 @@
 #include "utils.h"
 
 static VALUE cGraph;
-static VALUE eIndexingError;
 
 // Free function for the custom Graph allocator. We always have to call into Rust to free data allocated by it
 static void graph_free(void *ptr) {
@@ -27,8 +26,8 @@ static VALUE rdxr_graph_alloc(VALUE klass) {
     return TypedData_Wrap_Struct(klass, &graph_type, graph);
 }
 
-// Graph#index_all: (Array[String] file_paths) -> nil
-// Raises IndexingError if anything failed during indexing
+// Graph#index_all: (Array[String] file_paths) -> Array[String]
+// Returns an array of IO error messages encountered during indexing
 static VALUE rdxr_graph_index_all(VALUE self, VALUE file_paths) {
     rdxi_check_array_of_strings(file_paths);
 
@@ -36,10 +35,12 @@ static VALUE rdxr_graph_index_all(VALUE self, VALUE file_paths) {
     size_t length = RARRAY_LEN(file_paths);
     char **converted_file_paths = rdxi_str_array_to_char(file_paths, length);
 
-    // Get the underying graph pointer and then invoke the Rust index all implementation
+    // Get the underlying graph pointer and then invoke the Rust index all implementation
     void *graph;
     TypedData_Get_Struct(self, void *, &graph_type, graph);
-    const char *error_messages = rdx_index_all(graph, (const char **)converted_file_paths, length);
+
+    size_t error_count = 0;
+    const char *const *errors = rdx_index_all(graph, (const char **)converted_file_paths, length, &error_count);
 
     // Free the converted file paths and allow the GC to collect them
     for (size_t i = 0; i < length; i++) {
@@ -47,15 +48,17 @@ static VALUE rdxr_graph_index_all(VALUE self, VALUE file_paths) {
     }
     free(converted_file_paths);
 
-    // If indexing errors were returned, turn them into a Ruby string, call Rust to free the CString it allocated and
-    // return the Ruby string
-    if (error_messages != NULL) {
-        VALUE error_string = rb_utf8_str_new_cstr(error_messages);
-        free_c_string(error_messages);
-        rb_raise(eIndexingError, "%s", StringValueCStr(error_string));
+    if (errors == NULL) {
+        return rb_ary_new();
     }
 
-    return Qnil;
+    VALUE array = rb_ary_new_capa((long)error_count);
+    for (size_t i = 0; i < error_count; i++) {
+        rb_ary_push(array, rb_utf8_str_new_cstr(errors[i]));
+    }
+
+    free_c_string_array(errors, error_count);
+    return array;
 }
 
 // Size function for the declarations enumerator
@@ -272,6 +275,25 @@ static VALUE rdxr_graph_method_references(VALUE self) {
     return self;
 }
 
+// Graph#delete_document: (String uri) -> Document?
+// Deletes a document and all of its definitions from the graph.
+// Returns the removed Document or nil if it doesn't exist.
+static VALUE rdxr_graph_delete_document(VALUE self, VALUE uri) {
+    Check_Type(uri, T_STRING);
+
+    void *graph;
+    TypedData_Get_Struct(self, void *, &graph_type, graph);
+    const uint64_t *uri_id = rdx_graph_delete_document(graph, StringValueCStr(uri));
+
+    if (uri_id == NULL) {
+        return Qnil;
+    }
+
+    VALUE argv[] = {self, ULL2NUM(*uri_id)};
+    free_u64(uri_id);
+    return rb_class_new_instance(2, argv, cDocument);
+}
+
 // Graph#resolve: () -> self
 // Runs the resolver to compute declarations and ownership
 static VALUE rdxr_graph_resolve(VALUE self) {
@@ -358,6 +380,38 @@ static VALUE rdxr_graph_resolve_require_path(VALUE self, VALUE require_path, VAL
     return rb_class_new_instance(2, argv, cDocument);
 }
 
+// Graph#require_paths: (Array[String] load_path) -> Array[String]
+// Returns all require paths for completion.
+static VALUE rdxr_graph_require_paths(VALUE self, VALUE load_path) {
+    rdxi_check_array_of_strings(load_path);
+
+    void *graph;
+    TypedData_Get_Struct(self, void *, &graph_type, graph);
+
+    size_t paths_len = RARRAY_LEN(load_path);
+    char **converted_paths = rdxi_str_array_to_char(load_path, paths_len);
+
+    size_t out_count = 0;
+    const char *const *results = rdx_require_paths(graph, (const char **)converted_paths, paths_len, &out_count);
+
+    for (size_t i = 0; i < paths_len; i++) {
+        free(converted_paths[i]);
+    }
+    free(converted_paths);
+
+    if (results == NULL) {
+        return rb_ary_new();
+    }
+
+    VALUE array = rb_ary_new_capa((long)out_count);
+    for (size_t i = 0; i < out_count; i++) {
+        rb_ary_push(array, rb_utf8_str_new_cstr(results[i]));
+    }
+
+    free_c_string_array(results, out_count);
+    return array;
+}
+
 // Graph#diagnostics -> Array[Rubydex::Diagnostic]
 static VALUE rdxr_graph_diagnostics(VALUE self) {
     void *graph;
@@ -392,12 +446,10 @@ static VALUE rdxr_graph_diagnostics(VALUE self) {
 }
 
 void rdxi_initialize_graph(VALUE mRubydex) {
-    VALUE eRubydexError = rb_const_get(mRubydex, rb_intern("Error"));
-    eIndexingError = rb_define_class_under(mRubydex, "IndexingError", eRubydexError);
-
     cGraph = rb_define_class_under(mRubydex, "Graph", rb_cObject);
     rb_define_alloc_func(cGraph, rdxr_graph_alloc);
     rb_define_method(cGraph, "index_all", rdxr_graph_index_all, 1);
+    rb_define_method(cGraph, "delete_document", rdxr_graph_delete_document, 1);
     rb_define_method(cGraph, "resolve", rdxr_graph_resolve, 0);
     rb_define_method(cGraph, "resolve_constant", rdxr_graph_resolve_constant, 2);
     rb_define_method(cGraph, "declarations", rdxr_graph_declarations, 0);
@@ -409,4 +461,5 @@ void rdxi_initialize_graph(VALUE mRubydex) {
     rb_define_method(cGraph, "search", rdxr_graph_search, 1);
     rb_define_method(cGraph, "set_encoding", rdxr_graph_set_encoding, 1);
     rb_define_method(cGraph, "resolve_require_path", rdxr_graph_resolve_require_path, 2);
+    rb_define_method(cGraph, "require_paths", rdxr_graph_require_paths, 1);
 }

data/lib/rubydex/graph.rb

@@ -5,40 +5,68 @@ module Rubydex
   #
   # Note: this class is partially defined in C to integrate with the Rust backend
   class Graph
+    IGNORED_DIRECTORIES = [
+      ".bundle",
+      ".git",
+      ".github",
+      "node_modules",
+      "tmp",
+    ].freeze
+
     #: (?workspace_path: String) -> void
     def initialize(workspace_path: Dir.pwd)
       @workspace_path = workspace_path
     end
 
     # Index all files and dependencies of the workspace that exists in `@workspace_path`
-    #: -> String?
+    #: -> Array[String]
     def index_workspace
-      paths = Dir.glob("#{@workspace_path}/**/*.rb")
-      paths.concat(
-        workspace_dependency_paths.flat_map do |path|
-          Dir.glob("#{path}/**/*.rb")
-        end,
-      )
-      index_all(paths)
+      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
+    #
+    #: -> Array[String]
+    def workspace_paths
+      paths = []
+
+      Dir.each_child(@workspace_path) do |entry|
+        full_path = File.join(@workspace_path, entry)
+
+        if File.directory?(full_path)
+          paths << full_path unless IGNORED_DIRECTORIES.include?(entry)
+        elsif File.extname(entry) == ".rb"
+          paths << full_path
+        end
+      end
+
+      add_workspace_dependency_paths(paths)
+      paths.uniq!
+      paths
     end
 
     private
 
     # Gathers the paths we have to index for all workspace dependencies
-    def workspace_dependency_paths
+    #: (Array[String]) -> void
+    def add_workspace_dependency_paths(paths)
       specs = Bundler.locked_gems&.specs
-      return [] unless specs
+      return unless specs
 
-      paths = specs.filter_map do |lazy_spec|
+      specs.each do |lazy_spec|
         spec = Gem::Specification.find_by_name(lazy_spec.name)
-        spec.require_paths.map { |path| File.join(spec.full_gem_path, path) }
+        spec.require_paths.each do |path|
+          # For native extensions, RubyGems inserts an absolute require path pointing to
+          # `gems/some-gem-1.0.0/extensions`. Those paths don't actually include any Ruby files inside, so we can skip
+          # descending them
+          next if File.absolute_path?(path)
+
+          paths << File.join(spec.full_gem_path, path)
+        end
       rescue Gem::MissingSpecError
         nil
       end
-
-      paths.flatten!
-      paths.uniq!
-      paths
     end
   end
 end

data/lib/rubydex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rubydex
-  VERSION = "0.1.0.beta3"
+  VERSION = "0.1.0.beta4"
 end

data/rust/rubydex/src/indexing/rbs_indexer.rs

@@ -0,0 +1,29 @@
+//! Visit the RBS AST and create type definitions.
+
+use crate::{
+    indexing::local_graph::LocalGraph,
+    model::{document::Document, ids::UriId},
+};
+
+pub struct RBSIndexer {
+    #[allow(dead_code)]
+    uri_id: UriId,
+    local_graph: LocalGraph,
+}
+
+impl RBSIndexer {
+    #[must_use]
+    pub fn new(uri: String, source: &str) -> Self {
+        let uri_id = UriId::from(&uri);
+        let local_graph = LocalGraph::new(uri_id, Document::new(uri, source));
+
+        Self { uri_id, local_graph }
+    }
+
+    #[must_use]
+    pub fn local_graph(self) -> LocalGraph {
+        self.local_graph
+    }
+
+    pub fn index(&mut self) {}
+}

data/rust/rubydex/src/indexing.rs

@@ -1,6 +1,6 @@
 use crate::{
     errors::Errors,
-    indexing::{local_graph::LocalGraph, ruby_indexer::RubyIndexer},
+    indexing::{local_graph::LocalGraph, rbs_indexer::RBSIndexer, ruby_indexer::RubyIndexer},
     job_queue::{Job, JobQueue},
     model::graph::Graph,
 };
@@ -9,16 +9,17 @@ use std::{fs, path::PathBuf, sync::Arc};
 use url::Url;
 
 pub mod local_graph;
+pub mod rbs_indexer;
 pub mod ruby_indexer;
 
-/// Job that indexes a single Ruby file
-pub struct IndexingRubyFileJob {
+/// Job that indexes a single file
+pub struct IndexingJob {
     path: PathBuf,
     local_graph_tx: Sender<LocalGraph>,
     errors_tx: Sender<Errors>,
 }
 
-impl IndexingRubyFileJob {
+impl IndexingJob {
     #[must_use]
     pub fn new(path: PathBuf, local_graph_tx: Sender<LocalGraph>, errors_tx: Sender<Errors>) -> Self {
         Self {
@@ -35,7 +36,7 @@ impl IndexingRubyFileJob {
     }
 }
 
-impl Job for IndexingRubyFileJob {
+impl Job for IndexingJob {
     fn run(&self) {
         let Ok(source) = fs::read_to_string(&self.path) else {
             self.send_error(Errors::FileError(format!(
@@ -55,11 +56,20 @@ impl Job for IndexingRubyFileJob {
             return;
         };
 
-        let mut ruby_indexer = RubyIndexer::new(url.to_string(), &source);
-        ruby_indexer.index();
+        let local_graph = if let Some(ext) = self.path.extension()
+            && ext == "rbs"
+        {
+            let mut indexer = RBSIndexer::new(url.to_string(), &source);
+            indexer.index();
+            indexer.local_graph()
+        } else {
+            let mut indexer = RubyIndexer::new(url.to_string(), &source);
+            indexer.index();
+            indexer.local_graph()
+        };
 
         self.local_graph_tx
-            .send(ruby_indexer.local_graph())
+            .send(local_graph)
             .expect("graph receiver dropped before merge");
     }
 }
@@ -75,7 +85,7 @@ pub fn index_files(graph: &mut Graph, paths: Vec<PathBuf>) -> Vec<Errors> {
     let (errors_tx, errors_rx) = unbounded();
 
     for path in paths {
-        queue.push(Box::new(IndexingRubyFileJob::new(
+        queue.push(Box::new(IndexingJob::new(
             path,
             local_graphs_tx.clone(),
             errors_tx.clone(),

data/rust/rubydex/src/main.rs

@@ -27,6 +27,16 @@ struct Args {
 
     #[arg(long = "stats", help = "Show detailed performance statistics")]
     stats: bool,
+
+    #[arg(
+        long = "report-orphans",
+        value_name = "PATH",
+        num_args = 0..=1,
+        require_equals = true,
+        default_missing_value = "/tmp/rubydex-orphan-report.txt",
+        help = "Write orphan definitions report to specified file"
+    )]
+    report_orphans: Option<String>,
 }
 
 #[derive(Debug, Clone, ValueEnum)]
@@ -101,6 +111,20 @@ fn main() {
         MemoryStats::print_memory_usage();
     }
 
+    // Orphan report
+    if let Some(ref path) = args.report_orphans {
+        match std::fs::File::create(path) {
+            Ok(mut file) => {
+                if let Err(e) = graph.write_orphan_report(&mut file) {
+                    eprintln!("Failed to write orphan report: {e}");
+                } else {
+                    println!("Orphan report written to {path}");
+                }
+            }
+            Err(e) => eprintln!("Failed to create orphan report file: {e}"),
+        }
+    }
+
     // Generate visualization or print statistics
     if args.visualize {
         println!("{}", dot::generate(&graph));

data/rust/rubydex/src/model/definitions.rs

@@ -142,7 +142,16 @@ impl Definition {
             Definition::SingletonClass(d) => Some(d.name_id()),
             Definition::Module(d) => Some(d.name_id()),
             Definition::Constant(d) => Some(d.name_id()),
-            _ => None,
+            Definition::ConstantAlias(d) => Some(d.name_id()),
+            Definition::GlobalVariable(_)
+            | Definition::InstanceVariable(_)
+            | Definition::ClassVariable(_)
+            | Definition::AttrAccessor(_)
+            | Definition::AttrReader(_)
+            | Definition::AttrWriter(_)
+            | Definition::Method(_)
+            | Definition::MethodAlias(_)
+            | Definition::GlobalVariableAlias(_) => None,
         }
     }
 

data/rust/rubydex/src/model/graph.rs

@@ -191,60 +191,42 @@ impl Graph {
             Definition::ConstantAlias(it) => {
                 return self.name_id_to_declaration_id(*it.name_id());
             }
-            Definition::GlobalVariable(it) => {
-                let nesting_definition = it
-                    .lexical_nesting_id()
-                    .and_then(|id| self.definitions().get(&id).unwrap().name_id());
-                (nesting_definition, it.str_id())
-            }
-            Definition::GlobalVariableAlias(it) => {
-                let nesting_definition = it
-                    .lexical_nesting_id()
-                    .and_then(|id| self.definitions().get(&id).unwrap().name_id());
-                (nesting_definition, it.new_name_str_id())
-            }
-            Definition::InstanceVariable(it) => {
-                let nesting_definition = it
-                    .lexical_nesting_id()
-                    .and_then(|id| self.definitions().get(&id).unwrap().name_id());
-                (nesting_definition, it.str_id())
-            }
-            Definition::ClassVariable(it) => {
-                let nesting_definition = it
-                    .lexical_nesting_id()
-                    .and_then(|id| self.definitions().get(&id).unwrap().name_id());
-                (nesting_definition, it.str_id())
-            }
-            Definition::AttrAccessor(it) => {
-                let nesting_definition = it
-                    .lexical_nesting_id()
-                    .and_then(|id| self.definitions().get(&id).unwrap().name_id());
-                (nesting_definition, it.str_id())
-            }
-            Definition::AttrReader(it) => {
-                let nesting_definition = it
-                    .lexical_nesting_id()
-                    .and_then(|id| self.definitions().get(&id).unwrap().name_id());
-                (nesting_definition, it.str_id())
-            }
-            Definition::AttrWriter(it) => {
-                let nesting_definition = it
-                    .lexical_nesting_id()
-                    .and_then(|id| self.definitions().get(&id).unwrap().name_id());
-                (nesting_definition, it.str_id())
-            }
-            Definition::Method(it) => {
-                let nesting_definition = it
-                    .lexical_nesting_id()
-                    .and_then(|id| self.definitions().get(&id).unwrap().name_id());
-                (nesting_definition, it.str_id())
-            }
-            Definition::MethodAlias(it) => {
-                let nesting_definition = it
-                    .lexical_nesting_id()
-                    .and_then(|id| self.definitions().get(&id).unwrap().name_id());
-                (nesting_definition, it.new_name_str_id())
-            }
+            Definition::GlobalVariable(it) => (
+                self.find_enclosing_namespace_name_id(it.lexical_nesting_id().as_ref()),
+                it.str_id(),
+            ),
+            Definition::GlobalVariableAlias(it) => (
+                self.find_enclosing_namespace_name_id(it.lexical_nesting_id().as_ref()),
+                it.new_name_str_id(),
+            ),
+            Definition::InstanceVariable(it) => (
+                self.find_enclosing_namespace_name_id(it.lexical_nesting_id().as_ref()),
+                it.str_id(),
+            ),
+            Definition::ClassVariable(it) => (
+                self.find_enclosing_namespace_name_id(it.lexical_nesting_id().as_ref()),
+                it.str_id(),
+            ),
+            Definition::AttrAccessor(it) => (
+                self.find_enclosing_namespace_name_id(it.lexical_nesting_id().as_ref()),
+                it.str_id(),
+            ),
+            Definition::AttrReader(it) => (
+                self.find_enclosing_namespace_name_id(it.lexical_nesting_id().as_ref()),
+                it.str_id(),
+            ),
+            Definition::AttrWriter(it) => (
+                self.find_enclosing_namespace_name_id(it.lexical_nesting_id().as_ref()),
+                it.str_id(),
+            ),
+            Definition::Method(it) => (
+                self.find_enclosing_namespace_name_id(it.lexical_nesting_id().as_ref()),
+                it.str_id(),
+            ),
+            Definition::MethodAlias(it) => (
+                self.find_enclosing_namespace_name_id(it.lexical_nesting_id().as_ref()),
+                it.new_name_str_id(),
+            ),
         };
 
         let nesting_declaration_id = match nesting_name_id {
@@ -253,13 +235,28 @@ impl Graph {
         }?;
 
         self.declarations
-            .get(nesting_declaration_id)
-            .unwrap()
-            .as_namespace()
-            .unwrap()
+            .get(nesting_declaration_id)?
+            .as_namespace()?
             .member(member_str_id)
     }
 
+    /// Finds the closest namespace name ID to connect a definition to its declaration
+    fn find_enclosing_namespace_name_id(&self, starting_id: Option<&DefinitionId>) -> Option<&NameId> {
+        let mut current = starting_id;
+
+        while let Some(id) = current {
+            let def = self.definitions.get(id).unwrap();
+
+            if let Some(name_id) = def.name_id() {
+                return Some(name_id);
+            }
+
+            current = def.lexical_nesting_id().as_ref();
+        }
+
+        None
+    }
+
     #[must_use]
     pub fn name_id_to_declaration_id(&self, name_id: NameId) -> Option<&DeclarationId> {
         let name = self.names.get(&name_id);
@@ -515,11 +512,13 @@ impl Graph {
         }
     }
 
-    //// Handles the deletion of a document identified by `uri`
-    pub fn delete_uri(&mut self, uri: &str) {
+    /// Handles the deletion of a document identified by `uri`.
+    /// Returns the `UriId` of the removed document, or `None` if it didn't exist.
+    pub fn delete_document(&mut self, uri: &str) -> Option<UriId> {
         let uri_id = UriId::from(uri);
-        self.remove_definitions_for_uri(uri_id);
-        self.documents.remove(&uri_id);
+        let document = self.documents.remove(&uri_id)?;
+        self.remove_definitions_for_document(&document);
+        Some(uri_id)
     }
 
     /// Merges everything in `other` into this Graph. This method is meant to merge all graph representations from
@@ -581,18 +580,17 @@ impl Graph {
         // For each URI that was indexed through `other`, check what was discovered and update our current global
         // representation
         let uri_id = other.uri_id();
-        self.remove_definitions_for_uri(uri_id);
+        if let Some(document) = self.documents.remove(&uri_id) {
+            self.remove_definitions_for_document(&document);
+        }
 
         self.extend(other);
     }
 
-    // Removes all nodes and relationships associated to the given URI. This is used to clean up stale data when a
-    // document (identified by `uri_id`) changes or when a document is closed and we need to clean up the memory
-    fn remove_definitions_for_uri(&mut self, uri_id: UriId) {
-        let Some(document) = self.documents.remove(&uri_id) else {
-            return;
-        };
-
+    // Removes all nodes and relationships associated to the given document. This is used to clean up stale data when a
+    // document changes or when a document is deleted and we need to clean up the memory.
+    // The document must already have been removed from `self.documents` before calling this.
+    fn remove_definitions_for_document(&mut self, document: &Document) {
         // TODO: Remove method references from method declarations once method inference is implemented
         for ref_id in document.method_references() {
             if let Some(method_ref) = self.method_references.remove(ref_id) {
@@ -1502,4 +1500,85 @@ mod tests {
         assert!(context.graph().get("Foo::<Foo>").is_none());
         assert!(context.graph().get("Foo::<Foo>::<<Foo>>").is_none());
     }
+
+    #[test]
+    fn indexing_the_same_document_twice() {
+        let mut context = GraphTest::new();
+        let source = "
+          module Bar; end
+
+          $global_var_1 = 1
+          alias $global_alias_1 $global_var_1
+          ALIAS_CONST_1 = Bar
+
+          class Foo
+            alias $global_alias_2 $global_var_1
+            attr_reader :attr_1
+            attr_writer :attr_2
+            attr_accessor :attr_3
+            ALIAS_CONST_2 = Bar
+
+            $global_var_2 = 1
+            @ivar_1 = 1
+            @@class_var_1 = 1
+
+            def method_1
+              $global_var_3 = 1
+              @ivar_2 = 1
+              @@class_var_2 = 1
+              ALIAS_CONST_3 = Bar
+            end
+            alias_method :aliased_method_1, :method_1
+
+            def self.method_2
+              $global_var_4 = 1
+              @ivar_3 = 1
+              @@class_var_3 = 1
+              ALIAS_CONST_4 = Bar
+            end
+
+            class << self
+              alias $global_alias_3 $global_var_1
+              attr_reader :attr_4
+              attr_writer :attr_5
+              attr_accessor :attr_6
+              ALIAS_CONST_5 = Bar
+
+              $global_var_3 = 1
+              @ivar_4 = 1
+              @@class_var_4 = 1
+
+              def method_3
+                $global_var_4 = 1
+                @ivar_5 = 1
+                @@class_var_5 = 1
+                ALIAS_CONST_6 = Bar
+              end
+              alias_method :aliased_method_1, :method_1
+
+              def self.method_4
+                $global_var_5 = 1
+                @ivar_6 = 1
+                @@class_var_6 = 1
+                ALIAS_CONST_7 = Bar
+              end
+            end
+          end
+        ";
+
+        context.index_uri("file:///foo.rb", source);
+        assert_eq!(44, context.graph().definitions.len());
+        assert_eq!(7, context.graph().constant_references.len());
+        assert_eq!(2, context.graph().method_references.len());
+        assert_eq!(1, context.graph().documents.len());
+        assert_eq!(12, context.graph().names.len());
+        assert_eq!(41, context.graph().strings.len());
+        context.index_uri("file:///foo.rb", source);
+        assert_eq!(44, context.graph().definitions.len());
+        assert_eq!(7, context.graph().constant_references.len());
+        assert_eq!(2, context.graph().method_references.len());
+        assert_eq!(1, context.graph().documents.len());
+        assert_eq!(12, context.graph().names.len());
+        assert_eq!(41, context.graph().strings.len());
+    }
 }

data/rust/rubydex/src/offset.rs

@@ -4,7 +4,6 @@
 //! within a file. It can be used to track positions in source code and convert
 //! between byte offsets and line/column positions.
 
-#[cfg(any(test, feature = "test_utils"))]
 use crate::model::document::Document;
 
 /// Represents a byte offset range within a specific file.
@@ -59,7 +58,6 @@ impl Offset {
     }
 
     /// Converts an offset to a display range like `1:1-1:5`
-    #[cfg(any(test, feature = "test_utils"))]
     #[must_use]
     pub fn to_display_range(&self, document: &Document) -> String {
         let line_index = document.line_index();

data/rust/rubydex/src/stats/orphan_report.rs

@@ -0,0 +1,262 @@
+use std::collections::HashSet;
+use std::io::Write;
+
+use crate::model::declaration::Declaration;
+use crate::model::definitions::Definition;
+use crate::model::graph::Graph;
+use crate::model::ids::{DefinitionId, NameId, StringId};
+use crate::model::name::{NameRef, ParentScope};
+
+impl Graph {
+    /// Writes a report of orphan definitions (definitions not linked to any declaration).
+    ///
+    /// Format: `type\tconcatenated_name\tlocation` (TSV)
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if writing fails.
+    pub fn write_orphan_report(&self, writer: &mut impl Write) -> std::io::Result<()> {
+        // Collect all definition IDs that are linked to declarations
+        let linked_definition_ids: HashSet<&DefinitionId> = self
+            .declarations()
+            .values()
+            .flat_map(Declaration::definitions)
+            .collect();
+
+        // Find orphan definitions
+        let mut orphans: Vec<_> = self
+            .definitions()
+            .iter()
+            .filter(|(id, _)| !linked_definition_ids.contains(id))
+            .collect();
+
+        // Sort by type, then by location for consistent output
+        orphans.sort_by(|(_, a), (_, b)| {
+            a.kind()
+                .cmp(b.kind())
+                .then_with(|| a.uri_id().cmp(b.uri_id()))
+                .then_with(|| a.offset().cmp(b.offset()))
+        });
+
+        for (_, definition) in orphans {
+            let kind = definition.kind();
+            let name = match definition.name_id().copied() {
+                Some(id) => self.build_concatenated_name_from_name(id),
+                None => self.build_concatenated_name_from_lexical_nesting(definition),
+            };
+            let location = self.definition_location(definition);
+
+            writeln!(writer, "{kind}\t{name}\t{location}")?;
+        }
+
+        Ok(())
+    }
+
+    /// Walks the Name system's `parent_scope` chain to reconstruct the constant path.
+    /// Falls back to `nesting` for enclosing scope context when there is no explicit parent scope.
+    ///
+    /// Note: this produces a concatenated name by piecing together name parts, not a properly
+    /// resolved qualified name.
+    pub(crate) fn build_concatenated_name_from_name(&self, name_id: NameId) -> String {
+        let Some(name_ref) = self.names().get(&name_id) else {
+            return "<unknown>".to_string();
+        };
+        let simple_name = self.string_id_to_string(*name_ref.str());
+
+        match name_ref.parent_scope() {
+            ParentScope::Some(parent_id) | ParentScope::Attached(parent_id) => {
+                let parent_name = self.build_concatenated_name_from_name(*parent_id);
+                format!("{parent_name}::{simple_name}")
+            }
+            ParentScope::TopLevel => format!("::{simple_name}"),
+            ParentScope::None => {
+                let prefix = name_ref
+                    .nesting()
+                    .as_ref()
+                    .map(|nesting_id| self.build_nesting_prefix(*nesting_id))
+                    .unwrap_or_default();
+
+                if prefix.is_empty() {
+                    simple_name
+                } else {
+                    format!("{prefix}::{simple_name}")
+                }
+            }
+        }
+    }
+
+    /// Resolves the enclosing nesting `NameId` to a string prefix.
+    /// For resolved names, uses the declaration's fully qualified name.
+    /// For unresolved names, recursively walks the name chain.
+    fn build_nesting_prefix(&self, nesting_id: NameId) -> String {
+        let Some(name_ref) = self.names().get(&nesting_id) else {
+            return String::new();
+        };
+        match name_ref {
+            NameRef::Resolved(resolved) => self
+                .declarations()
+                .get(resolved.declaration_id())
+                .map_or_else(String::new, |decl| decl.name().to_string()),
+            NameRef::Unresolved(_) => self.build_concatenated_name_from_name(nesting_id),
+        }
+    }
+
+    /// Builds a concatenated name for non-constant definitions by walking the `lexical_nesting_id` chain.
+    ///
+    /// Note: this pieces together name parts from the lexical nesting, not a properly resolved
+    /// qualified name.
+    pub(crate) fn build_concatenated_name_from_lexical_nesting(&self, definition: &Definition) -> String {
+        let simple_name = self.string_id_to_string(self.definition_string_id(definition));
+
+        // Collect enclosing nesting names from inner to outer
+        let mut nesting_parts = Vec::new();
+        let mut current_nesting = *definition.lexical_nesting_id();
+
+        while let Some(nesting_id) = current_nesting {
+            let Some(nesting_def) = self.definitions().get(&nesting_id) else {
+                break;
+            };
+            nesting_parts.push(self.string_id_to_string(self.definition_string_id(nesting_def)));
+            current_nesting = *nesting_def.lexical_nesting_id();
+        }
+
+        if nesting_parts.is_empty() {
+            return simple_name;
+        }
+
+        // Reverse to get outer-to-inner order for the prefix
+        nesting_parts.reverse();
+        let prefix = nesting_parts.join("::");
+
+        let separator = match definition {
+            Definition::Method(_)
+            | Definition::AttrAccessor(_)
+            | Definition::AttrReader(_)
+            | Definition::AttrWriter(_)
+            | Definition::MethodAlias(_)
+            | Definition::InstanceVariable(_) => "#",
+            Definition::Class(_)
+            | Definition::SingletonClass(_)
+            | Definition::Module(_)
+            | Definition::Constant(_)
+            | Definition::ConstantAlias(_)
+            | Definition::GlobalVariable(_)
+            | Definition::ClassVariable(_)
+            | Definition::GlobalVariableAlias(_) => "::",
+        };
+
+        format!("{prefix}{separator}{simple_name}")
+    }
+
+    /// Converts a `StringId` to its string value.
+    fn string_id_to_string(&self, string_id: StringId) -> String {
+        self.strings().get(&string_id).unwrap().to_string()
+    }
+
+    /// Get location in the format of `uri#L<line>` for a definition.
+    /// The format is clickable in VS Code.
+    pub(crate) fn definition_location(&self, definition: &Definition) -> String {
+        let uri_id = definition.uri_id();
+
+        let Some(document) = self.documents().get(uri_id) else {
+            return format!("{uri_id}:<unknown>");
+        };
+
+        let uri = document.uri();
+        let line_index = document.line_index();
+        let start = line_index.line_col(definition.offset().start().into());
+        format!("{uri}#L{}", start.line + 1)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::test_utils::GraphTest;
+
+    #[test]
+    fn build_concatenated_name_from_name_for_constants() {
+        let cases = vec![
+            ("class Foo; end", "Foo"),
+            ("module Foo; class Bar; end; end", "Foo::Bar"),
+            ("module Foo; module Bar; class Baz; end; end; end", "Foo::Bar::Baz"),
+        ];
+
+        for (source, expected_name) in cases {
+            let mut context = GraphTest::new();
+            context.index_uri("file:///test.rb", source);
+            context.resolve();
+
+            let definitions = context.graph().get(expected_name).unwrap();
+            let definition = definitions.first().unwrap();
+            let name_id = *definition.name_id().unwrap();
+            let actual = context.graph().build_concatenated_name_from_name(name_id);
+
+            assert_eq!(actual, expected_name, "For source: {source}");
+        }
+    }
+
+    #[test]
+    fn build_concatenated_name_from_lexical_nesting_for_methods() {
+        let cases = vec![
+            ("class Foo; def bar; end; end", "Foo#bar()"),
+            ("module Foo; class Bar; def baz; end; end; end", "Foo::Bar#baz()"),
+            ("def bar; end", "bar()"),
+        ];
+
+        for (source, expected_name) in cases {
+            let mut context = GraphTest::new();
+            // Index without resolution so methods remain orphans
+            context.index_uri("file:///test.rb", source);
+
+            let definition = context
+                .graph()
+                .definitions()
+                .values()
+                .find(|d| d.kind() == "Method" && d.name_id().is_none())
+                .unwrap_or_else(|| panic!("No Method definition without name_id found for source: {source}"));
+
+            let actual = context.graph().build_concatenated_name_from_lexical_nesting(definition);
+            assert_eq!(actual, expected_name, "For source: {source}");
+        }
+    }
+
+    #[test]
+    fn build_concatenated_name_from_lexical_nesting_for_instance_variables() {
+        let mut context = GraphTest::new();
+        context.index_uri("file:///test.rb", "class Foo; def initialize; @ivar = 1; end; end");
+
+        let definition = context
+            .graph()
+            .definitions()
+            .values()
+            .find(|d| d.kind() == "InstanceVariable")
+            .unwrap();
+
+        let actual = context.graph().build_concatenated_name_from_lexical_nesting(definition);
+        assert_eq!(actual, "Foo::initialize()#@ivar");
+    }
+
+    #[test]
+    fn definition_location_uses_clickable_uri_fragment() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            class Foo
+              def bar
+              end
+            end
+            ",
+        );
+
+        let definition = context
+            .graph()
+            .definitions()
+            .values()
+            .find(|d| d.kind() == "Method")
+            .unwrap();
+
+        let actual = context.graph().definition_location(definition);
+        assert_eq!(actual, "file:///foo.rb#L2");
+    }
+}

data/rust/rubydex/src/stats.rs

@@ -1,4 +1,6 @@
 pub mod memory;
+// TODO: When the rubydex is stable enough, turn this into a debug-only feature or revisit if we still need it.
+pub mod orphan_report;
 pub mod timer;
 
 /// Helper function to compute percentage

data/rust/rubydex/src/test_utils/graph_test.rs

@@ -36,7 +36,7 @@ impl GraphTest {
     }
 
     pub fn delete_uri(&mut self, uri: &str) {
-        self.graph.delete_uri(uri);
+        self.graph.delete_document(uri);
     }
 
     pub fn resolve(&mut self) {

data/rust/rubydex-sys/src/graph_api.rs

@@ -115,7 +115,9 @@ pub unsafe extern "C" fn rdx_graph_resolve_constant(
     })
 }
 
-/// Indexes all given file paths in parallel using the provided Graph pointer
+/// Indexes all given file paths in parallel using the provided Graph pointer.
+/// Returns an array of error message strings and writes the count to `out_error_count`.
+/// Returns NULL if there are no errors. Caller must free with `free_c_string_array`.
 ///
 /// # Panics
 ///
@@ -130,34 +132,57 @@ pub unsafe extern "C" fn rdx_index_all(
     pointer: GraphPointer,
     file_paths: *const *const c_char,
     count: usize,
-) -> *const c_char {
+    out_error_count: *mut usize,
+) -> *const *const c_char {
     let file_paths: Vec<String> = unsafe { utils::convert_double_pointer_to_vec(file_paths, count).unwrap() };
-    let (file_paths, errors) = listing::collect_file_paths(file_paths);
-
-    if !errors.is_empty() {
-        let error_messages = errors
-            .iter()
-            .map(std::string::ToString::to_string)
-            .collect::<Vec<_>>()
-            .join("\n");
-
-        return CString::new(error_messages).unwrap().into_raw().cast_const();
-    }
+    let (file_paths, listing_errors) = listing::collect_file_paths(file_paths);
 
     with_mut_graph(pointer, |graph| {
-        let errors = indexing::index_files(graph, file_paths);
+        let indexing_errors = indexing::index_files(graph, file_paths);
 
-        if !errors.is_empty() {
-            let error_messages = errors
-                .iter()
-                .map(std::string::ToString::to_string)
-                .collect::<Vec<_>>()
-                .join("\n");
+        let all_errors: Vec<String> = listing_errors
+            .into_iter()
+            .chain(indexing_errors)
+            .map(|e| e.to_string())
+            .collect();
 
-            return CString::new(error_messages).unwrap().into_raw().cast_const();
+        if all_errors.is_empty() {
+            unsafe { *out_error_count = 0 };
+            return ptr::null();
         }
 
-        ptr::null()
+        let c_strings: Vec<*const c_char> = all_errors
+            .into_iter()
+            .filter_map(|string| {
+                CString::new(string)
+                    .ok()
+                    .map(|c_string| c_string.into_raw().cast_const())
+            })
+            .collect();
+
+        unsafe { *out_error_count = c_strings.len() };
+
+        let boxed = c_strings.into_boxed_slice();
+        Box::into_raw(boxed).cast::<*const c_char>()
+    })
+}
+
+/// Deletes a document and all of its definitions from the graph.
+/// Returns a pointer to the URI ID if the document was found and removed, or NULL if it didn't exist.
+/// Caller must free the returned pointer with `free_u64`.
+///
+/// # Safety
+///
+/// Expects both the graph pointer and uri string pointer to be valid
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_graph_delete_document(pointer: GraphPointer, uri: *const c_char) -> *const u64 {
+    let Ok(uri_str) = (unsafe { utils::convert_char_ptr_to_string(uri) }) else {
+        return ptr::null();
+    };
+
+    with_mut_graph(pointer, |graph| match graph.delete_document(&uri_str) {
+        Some(uri_id) => Box::into_raw(Box::new(*uri_id)),
+        None => ptr::null(),
     })
 }
 
@@ -443,6 +468,44 @@ pub unsafe extern "C" fn rdx_resolve_require_path(
     })
 }
 
+/// Returns all require paths for completion.
+/// Returns array of C strings and writes count to `out_count`.
+/// Returns null if `load_path` contain invalid UTF-8.
+/// Caller must free with `free_c_string_array`.
+///
+/// # Safety
+/// - `pointer` must be a valid `GraphPointer` previously returned by this crate.
+/// - `load_path` must be an array of `load_path_count` valid, null-terminated UTF-8 strings.
+/// - `out_count` must be a valid, writable pointer.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_require_paths(
+    pointer: GraphPointer,
+    load_path: *const *const c_char,
+    load_path_count: usize,
+    out_count: *mut usize,
+) -> *const *const c_char {
+    let Ok(paths_vec) = (unsafe { utils::convert_double_pointer_to_vec(load_path, load_path_count) }) else {
+        return ptr::null_mut();
+    };
+    let paths_vec = paths_vec.into_iter().map(PathBuf::from).collect::<Vec<_>>();
+
+    let results = with_graph(pointer, |graph| query::require_paths(graph, &paths_vec));
+
+    let c_strings: Vec<*const c_char> = results
+        .into_iter()
+        .filter_map(|string| {
+            CString::new(string)
+                .ok()
+                .map(|c_string| c_string.into_raw().cast_const())
+        })
+        .collect();
+
+    unsafe { *out_count = c_strings.len() };
+
+    let boxed = c_strings.into_boxed_slice();
+    Box::into_raw(boxed).cast::<*const c_char>()
+}
+
 #[cfg(test)]
 mod tests {
     use rubydex::indexing::ruby_indexer::RubyIndexer;

data/rust/rubydex-sys/src/utils.rs

@@ -48,3 +48,23 @@ pub extern "C" fn free_u64(ptr: *const u64) {
         let _ = Box::from_raw(ptr.cast_mut());
     }
 }
+
+/// Frees an array of C strings allocated by Rust.
+///
+/// # Safety
+/// - `ptr` must be a pointer to a boxed slice of C strings previously allocated by this crate.
+/// - `count` must be the length of the array.
+/// - `ptr` must not be used after being freed.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn free_c_string_array(ptr: *const *const c_char, count: usize) {
+    if ptr.is_null() {
+        return;
+    }
+
+    let slice = unsafe { Box::from_raw(std::ptr::slice_from_raw_parts_mut(ptr.cast_mut(), count)) };
+    let _: Vec<_> = slice
+        .iter()
+        .filter(|p| !p.is_null())
+        .map(|arg| unsafe { CString::from_raw((*arg).cast_mut()) })
+        .collect();
+}

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubydex
 version: !ruby/object:Gem::Version
-  version: 0.1.0.beta3
+  version: 0.1.0.beta4
 platform: x86_64-linux
 authors:
 - Shopify
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-02-06 00:00:00.000000000 Z
+date: 2026-02-10 00:00:00.000000000 Z
 dependencies: []
 description: A high performance static analysis suite for Ruby, built in Rust with
   Ruby APIs
@@ -76,6 +76,7 @@ files:
 - rust/rubydex/src/errors.rs
 - rust/rubydex/src/indexing.rs
 - rust/rubydex/src/indexing/local_graph.rs
+- rust/rubydex/src/indexing/rbs_indexer.rs
 - rust/rubydex/src/indexing/ruby_indexer.rs
 - rust/rubydex/src/job_queue.rs
 - rust/rubydex/src/lib.rs
@@ -101,6 +102,7 @@ files:
 - rust/rubydex/src/resolution.rs
 - rust/rubydex/src/stats.rs
 - rust/rubydex/src/stats/memory.rs
+- rust/rubydex/src/stats/orphan_report.rs
 - rust/rubydex/src/stats/timer.rs
 - rust/rubydex/src/test_utils.rs
 - rust/rubydex/src/test_utils/context.rs