rubydex 0.3.0 → 0.4.0

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

@@ -1,10 +1,9 @@
 use std::collections::HashSet;
 use std::collections::hash_map::Entry;
-use std::path::{Path, PathBuf};
+use std::path::Path;
 
 use crate::config::Config;
 use crate::diagnostic::Diagnostic;
-use crate::errors::Errors;
 use crate::indexing::local_graph::LocalGraph;
 use crate::model::built_in::{OBJECT_ID, add_built_in_data};
 use crate::model::declaration::{Ancestor, Declaration, Namespace};
@@ -93,7 +92,7 @@ pub struct Graph {
     /// Project configuration
     config: Config,
 }
-assert_mem_size!(Graph, 352);
+assert_mem_size!(Graph, 368);
 assert_send_sync!(Graph);
 
 impl Graph {
@@ -110,7 +109,7 @@ impl Graph {
             position_encoding: Encoding::default(),
             name_dependents: IdentityHashMap::default(),
             pending_work: Vec::default(),
-            config: Config::new(),
+            config: Config::default(),
         };
 
         add_built_in_data(&mut graph);
@@ -147,25 +146,9 @@ impl Graph {
         self.config.workspace_path()
     }
 
-    /// Sets the root directory of the workspace being indexed.
-    pub fn set_workspace_path(&mut self, workspace_path: PathBuf) {
-        self.config.set_workspace_path(workspace_path);
-    }
-
-    /// Loads a configuration file. Pass `None` to load the default `rubydex.toml` configuration file if it exists
-    ///
-    /// # Errors
-    ///
-    /// Returns an [`Errors::ConfigNotFound`] if an explicitly requested file does not exist or an
-    /// [`Errors::ConfigError`] if a file cannot otherwise be read or its contents are malformed.
-    pub fn load_config(&mut self, config_path: Option<&Path>) -> Result<(), Errors> {
-        match config_path {
-            Some(path) => {
-                let path = self.config.workspace_path().join(path);
-                self.config.load_file(&path)
-            }
-            None => self.config.load_default(),
-        }
+    /// Loads a config for the graph
+    pub fn load_config(&mut self, config: &Config) {
+        self.config = config.clone();
     }
 
     /// # Panics
@@ -207,7 +190,15 @@ impl Graph {
                 if should_promote {
                     let mut new_declaration = constructor(fully_qualified_name);
                     let removed_declaration = occupied_entry.remove();
-                    new_declaration.as_namespace_mut().unwrap().extend(removed_declaration);
+                    let singleton_class_id = removed_declaration
+                        .as_namespace()
+                        .and_then(Namespace::singleton_class)
+                        .copied();
+                    let new_namespace = new_declaration.as_namespace_mut().unwrap();
+                    new_namespace.extend(removed_declaration);
+                    if let Some(singleton_class_id) = singleton_class_id {
+                        new_namespace.set_singleton_class_id(singleton_class_id);
+                    }
                     new_declaration.add_definition(definition_id);
                     self.declarations.insert(declaration_id, new_declaration);
                 } else {
@@ -540,7 +531,8 @@ impl Graph {
     /// Registers a name in the graph unless already registered. In regular indexing, this only happens in the local
     /// graph. This method is only used to back the `Graph#resolve_constant` Ruby API because every name must be
     /// registered in the graph to properly resolve
-    pub fn add_name(&mut self, name: Name) -> NameId {
+    pub fn add_name(&mut self, str: StringId, parent_scope: ParentScope, nesting: Option<NameId>) -> NameId {
+        let name = Name::new(&self.names, str, parent_scope, nesting);
         let name_id = name.id();
 
         match self.names.entry(name_id) {
@@ -893,12 +885,7 @@ impl Graph {
     ) {
         if let Some(declaration) = self.declarations.get_mut(owner_id) {
             match declaration {
-                Declaration::Namespace(Namespace::Class(it)) => it.add_member(member_str_id, member_declaration_id),
-                Declaration::Namespace(Namespace::Module(it)) => it.add_member(member_str_id, member_declaration_id),
-                Declaration::Namespace(Namespace::SingletonClass(it)) => {
-                    it.add_member(member_str_id, member_declaration_id);
-                }
-                Declaration::Namespace(Namespace::Todo(it)) => it.add_member(member_str_id, member_declaration_id),
+                Declaration::Namespace(namespace) => namespace.add_member(member_str_id, member_declaration_id),
                 Declaration::Constant(_) => {
                     // TODO: temporary hack to avoid crashing on `Struct.new`, `Class.new` and `Module.new`
                 }
@@ -1293,7 +1280,7 @@ impl Graph {
                         && let Some(anc_decl) = self.declarations.get_mut(&ancestor_id)
                         && let Some(ns) = anc_decl.as_namespace_mut()
                     {
-                        ns.remove_descendant(&decl_id);
+                        ns.remove_descendant(decl_id);
                     }
                 }
             }
@@ -1317,7 +1304,7 @@ impl Graph {
                     && let Some(anc_decl) = self.declarations.get_mut(ancestor_id)
                     && let Some(ns) = anc_decl.as_namespace_mut()
                 {
-                    ns.remove_descendant(&decl_id);
+                    ns.remove_descendant(decl_id);
                 }
             }
 
@@ -1811,7 +1798,7 @@ mod tests {
         context.index_uri("file:///a.rb", "");
 
         {
-            let Declaration::Namespace(Namespace::Class(foo)) =
+            let Declaration::Namespace(foo @ Namespace::Class(_)) =
                 context.graph().declarations().get(&DeclarationId::from("Foo")).unwrap()
             else {
                 panic!("Expected Foo to be a class");
@@ -1819,7 +1806,7 @@ mod tests {
             assert!(matches!(foo.ancestors(), Ancestors::Partial(a) if a.is_empty()));
             assert!(foo.descendants().is_empty());
 
-            let Declaration::Namespace(Namespace::Class(baz)) =
+            let Declaration::Namespace(baz @ Namespace::Class(_)) =
                 context.graph().declarations().get(&DeclarationId::from("Baz")).unwrap()
             else {
                 panic!("Expected Baz to be a class");
@@ -1827,7 +1814,7 @@ mod tests {
             assert!(matches!(baz.ancestors(), Ancestors::Partial(a) if a.is_empty()));
             assert!(baz.descendants().is_empty());
 
-            let Declaration::Namespace(Namespace::Module(bar)) =
+            let Declaration::Namespace(bar @ Namespace::Module(_)) =
                 context.graph().declarations().get(&DeclarationId::from("Bar")).unwrap()
             else {
                 panic!("Expected Bar to be a module");
@@ -2198,9 +2185,9 @@ mod tests {
 
         assert_eq!(
             vec![
-                "parse-error: expected an `end` to close the `class` statement (file:///foo1.rb)",
-                "parse-error: unexpected end-of-input, assuming it is closing the parent top level context (file:///foo1.rb)",
-                "parse-warning: assigned but unused variable - foo (file:///foo2.rb)",
+                "ParseError: expected an `end` to close the `class` statement (file:///foo1.rb)",
+                "ParseError: unexpected end-of-input, assuming it is closing the parent top level context (file:///foo1.rb)",
+                "ParseWarning: assigned but unused variable - foo (file:///foo2.rb)",
             ],
             diagnostics,
         );
@@ -2522,7 +2509,7 @@ mod tests {
         );
 
         // Delete bar.rb — the Bar name should be fully removed
-        let bar_name_id = Name::new(StringId::from("Bar"), ParentScope::None, None).id();
+        let bar_name_id = Name::new(context.graph().names(), StringId::from("Bar"), ParentScope::None, None).id();
         context.index_uri("file:///bar.rb", "");
         context.resolve();
 

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

@@ -4,6 +4,7 @@ use crate::{
     assert_mem_size,
     model::{
         id::id_from_parts,
+        identity_maps::IdentityHashMap,
         ids::{DeclarationId, NameId, StringId},
     },
 };
@@ -93,31 +94,58 @@ pub struct Name {
     /// list of names to represent the nesting
     nesting: Option<NameId>,
     ref_count: u32,
+    /// The depth of the name, which combines the depths of the parent scope and nesting
+    depth: u16,
 }
+assert_mem_size!(Name, 40);
 
 impl PartialEq for Name {
     fn eq(&self, other: &Self) -> bool {
         self.str == other.str && self.parent_scope == other.parent_scope && self.nesting == other.nesting
     }
 }
-assert_mem_size!(Name, 40);
 
 impl Name {
     #[must_use]
-    pub fn new(str: StringId, parent_scope: ParentScope, nesting: Option<NameId>) -> Self {
+    pub fn new(
+        names: &IdentityHashMap<NameId, NameRef>,
+        str: StringId,
+        parent_scope: ParentScope,
+        nesting: Option<NameId>,
+    ) -> Self {
         Self {
             str,
             parent_scope,
             nesting,
             ref_count: 1,
+            depth: Self::name_depth(names, parent_scope, nesting),
         }
     }
 
+    #[must_use]
+    fn name_depth(names: &IdentityHashMap<NameId, NameRef>, parent_scope: ParentScope, nesting: Option<NameId>) -> u16 {
+        if parent_scope.is_top_level() {
+            return 1;
+        }
+
+        let parent_depth = parent_scope
+            .as_ref()
+            .map_or(0, |id| names.get(id).map_or(0, NameRef::depth));
+        let nesting_depth = nesting.map_or(0, |id| names.get(&id).map_or(0, NameRef::depth));
+
+        parent_depth.saturating_add(nesting_depth).saturating_add(1)
+    }
+
     #[must_use]
     pub fn str(&self) -> &StringId {
         &self.str
     }
 
+    #[must_use]
+    pub fn depth(&self) -> u16 {
+        self.depth
+    }
+
     #[must_use]
     pub fn parent_scope(&self) -> &ParentScope {
         &self.parent_scope
@@ -227,6 +255,14 @@ impl NameRef {
         }
     }
 
+    #[must_use]
+    pub fn depth(&self) -> u16 {
+        match self {
+            NameRef::Unresolved(name) => name.depth(),
+            NameRef::Resolved(resolved_name) => resolved_name.name.depth(),
+        }
+    }
+
     /// # Panics
     ///
     /// Panics if we exceed the maximum size of the reference count
@@ -281,42 +317,47 @@ mod tests {
 
     #[test]
     fn same_parent_scope_and_nesting() {
-        let name_1 = Name::new(StringId::from("Foo"), ParentScope::None, None);
-        let name_2 = Name::new(StringId::from("Foo"), ParentScope::None, None);
+        let names = IdentityHashMap::default();
+
+        let name_1 = Name::new(&names, StringId::from("Foo"), ParentScope::None, None);
+        let name_2 = Name::new(&names, StringId::from("Foo"), ParentScope::None, None);
         assert_eq!(name_1.id(), name_2.id());
 
-        let name_3 = Name::new(StringId::from("Foo"), ParentScope::Some(name_1.id()), None);
-        let name_4 = Name::new(StringId::from("Foo"), ParentScope::Some(name_2.id()), None);
+        let name_3 = Name::new(&names, StringId::from("Foo"), ParentScope::Some(name_1.id()), None);
+        let name_4 = Name::new(&names, StringId::from("Foo"), ParentScope::Some(name_2.id()), None);
         assert_eq!(name_3.id(), name_4.id());
 
-        let name_5 = Name::new(StringId::from("Foo"), ParentScope::None, Some(name_1.id()));
-        let name_6 = Name::new(StringId::from("Foo"), ParentScope::None, Some(name_2.id()));
+        let name_5 = Name::new(&names, StringId::from("Foo"), ParentScope::None, Some(name_1.id()));
+        let name_6 = Name::new(&names, StringId::from("Foo"), ParentScope::None, Some(name_2.id()));
         assert_eq!(name_5.id(), name_6.id());
         assert_ne!(name_3.id(), name_5.id());
         assert_ne!(name_4.id(), name_6.id());
 
         let name_7 = Name::new(
+            &names,
             StringId::from("Foo"),
-            ParentScope::Some(Name::new(StringId::from("Foo"), ParentScope::None, None).id()),
-            Some(Name::new(StringId::from("Foo"), ParentScope::None, None).id()),
+            ParentScope::Some(Name::new(&names, StringId::from("Foo"), ParentScope::None, None).id()),
+            Some(Name::new(&names, StringId::from("Foo"), ParentScope::None, None).id()),
         );
         let name_8 = Name::new(
+            &names,
             StringId::from("Foo"),
-            ParentScope::Some(Name::new(StringId::from("Foo"), ParentScope::None, None).id()),
-            Some(Name::new(StringId::from("Foo"), ParentScope::None, None).id()),
+            ParentScope::Some(Name::new(&names, StringId::from("Foo"), ParentScope::None, None).id()),
+            Some(Name::new(&names, StringId::from("Foo"), ParentScope::None, None).id()),
         );
         assert_eq!(name_7.id(), name_8.id());
     }
 
     #[test]
     fn parent_scope_variants_are_distinct() {
-        let inner = Name::new(StringId::from("Foo"), ParentScope::None, None).id();
+        let names = IdentityHashMap::default();
+        let inner = Name::new(&names, StringId::from("Foo"), ParentScope::None, None).id();
 
         let ids = [
-            Name::new(StringId::from("Foo"), ParentScope::None, None).id(),
-            Name::new(StringId::from("Foo"), ParentScope::TopLevel, None).id(),
-            Name::new(StringId::from("Foo"), ParentScope::Some(inner), None).id(),
-            Name::new(StringId::from("Foo"), ParentScope::Attached(inner), None).id(),
+            Name::new(&names, StringId::from("Foo"), ParentScope::None, None).id(),
+            Name::new(&names, StringId::from("Foo"), ParentScope::TopLevel, None).id(),
+            Name::new(&names, StringId::from("Foo"), ParentScope::Some(inner), None).id(),
+            Name::new(&names, StringId::from("Foo"), ParentScope::Attached(inner), None).id(),
         ];
 
         for (i, a) in ids.iter().enumerate() {

data/rust/rubydex/src/operation/ruby_builder.rs

@@ -154,7 +154,8 @@ impl<'a> RubyOperationBuilder<'a> {
         string_id
     }
 
-    fn add_name(&mut self, name: Name) -> NameId {
+    fn add_name(&mut self, str: StringId, parent_scope: ParentScope, nesting: Option<NameId>) -> NameId {
+        let name = Name::new(&self.names, str, parent_scope, nesting);
         let name_id = name.id();
 
         match self.names.entry(name_id) {
@@ -360,11 +361,7 @@ impl<'a> RubyOperationBuilder<'a> {
         let offset = Offset::from_prism_location(&location);
         let name = Self::location_to_string(&location);
         let string_id = self.intern_string(name);
-        let name_id = self.add_name(Name::new(
-            string_id,
-            parent_scope_id,
-            self.current_lexical_scope_name_id(),
-        ));
+        let name_id = self.add_name(string_id, parent_scope_id, self.current_lexical_scope_name_id());
 
         if push_final_reference {
             self.operations
@@ -443,7 +440,7 @@ impl<'a> RubyOperationBuilder<'a> {
                 }
                 None => {
                     let str_id = self.intern_string("Object".into());
-                    Some(self.add_name(Name::new(str_id, ParentScope::None, None)))
+                    Some(self.add_name(str_id, ParentScope::None, None))
                 }
             },
             Some(ruby_prism::Node::CallNode { .. }) => {
@@ -477,7 +474,7 @@ impl<'a> RubyOperationBuilder<'a> {
         };
 
         let string_id = self.intern_string(singleton_class_name);
-        let new_name_id = self.add_name(Name::new(string_id, ParentScope::Attached(name_id), None));
+        let new_name_id = self.add_name(string_id, ParentScope::Attached(name_id), None);
 
         let location = receiver.map_or(fallback_location, ruby_prism::Node::location);
         let offset = Offset::from_prism_location(&location);
@@ -689,10 +686,7 @@ impl<'a> RubyOperationBuilder<'a> {
             )
         } else {
             let string_id = self.intern_string(format!("{}:{}<anonymous>", self.uri_id, offset.start()));
-            (
-                Some(self.add_name(Name::new(string_id, ParentScope::None, None))),
-                offset.clone(),
-            )
+            (Some(self.add_name(string_id, ParentScope::None, None)), offset.clone())
         };
 
         if let Some(name_id) = name_id {
@@ -754,10 +748,7 @@ impl<'a> RubyOperationBuilder<'a> {
             )
         } else {
             let string_id = self.intern_string(format!("{}:{}<anonymous>", self.uri_id, offset.start()));
-            (
-                Some(self.add_name(Name::new(string_id, ParentScope::None, None))),
-                offset.clone(),
-            )
+            (Some(self.add_name(string_id, ParentScope::None, None)), offset.clone())
         };
 
         if let Some(name_id) = name_id {
@@ -849,7 +840,7 @@ impl<'a> RubyOperationBuilder<'a> {
                     }
 
                     Some((
-                        self.current_lexical_scope_name_id().unwrap(),
+                        self.current_owner_name_id().unwrap(),
                         Offset::from_prism_location(&arg.location()),
                     ))
                 } else if let Some(name_id) = self.index_constant_reference(&arg, false) {
@@ -1361,6 +1352,14 @@ impl<'a> RubyOperationBuilder<'a> {
                 flags,
             }));
     }
+
+    fn visit_method_body(&mut self, receiver: Option<NestingReceiver>, body: Option<&ruby_prism::Node<'_>>) {
+        self.nesting_stack.push(Nesting::Method { receiver });
+        if let Some(body) = body {
+            self.visit(body);
+        }
+        self.nesting_stack.pop();
+    }
 }
 
 struct CommentGroup {
@@ -1483,7 +1482,7 @@ impl Visit<'_> for RubyOperationBuilder<'_> {
 
         let string_id = self.intern_string(singleton_class_name);
         let nesting = self.current_lexical_scope_name_id();
-        let name_id = self.add_name(Name::new(string_id, ParentScope::Attached(attached_target), nesting));
+        let name_id = self.add_name(string_id, ParentScope::Attached(attached_target), nesting);
         self.operations
             .push(Operation::EnterSingletonClass(op::EnterSingletonClass {
                 name_id,
@@ -1567,8 +1566,10 @@ impl Visit<'_> for RubyOperationBuilder<'_> {
         };
 
         if receiver.is_none() && visibility == Visibility::ModuleFunction {
-            // module_function: emit two EnterMethod/ExitScope pairs (singleton + instance),
-            // each visiting the body so ivars are associated with both methods.
+            // Each EnterMethod creates a method definition, so emit one for the public singleton
+            // method and one for the private instance method. Emit body definitions and references
+            // only under the instance method because emitting them in both scopes would duplicate
+            // their source-based IDs.
             let singleton_receiver = Some(Target::ExplicitSelf);
             let body = node.body();
 
@@ -1582,13 +1583,6 @@ impl Visit<'_> for RubyOperationBuilder<'_> {
                 signatures: Signatures::Simple(parameters.clone().into_boxed_slice()),
                 receiver: singleton_receiver,
             }));
-            self.nesting_stack.push(Nesting::Method {
-                receiver: method_nesting_receiver,
-            });
-            if let Some(ref body) = body {
-                self.visit(body);
-            }
-            self.nesting_stack.pop();
             self.operations.push(Operation::ExitScope);
 
             self.operations.push(Operation::EnterMethod(op::EnterMethod {
@@ -1601,13 +1595,7 @@ impl Visit<'_> for RubyOperationBuilder<'_> {
                 signatures: Signatures::Simple(parameters.into_boxed_slice()),
                 receiver,
             }));
-            self.nesting_stack.push(Nesting::Method {
-                receiver: method_nesting_receiver,
-            });
-            if let Some(ref body) = body {
-                self.visit(body);
-            }
-            self.nesting_stack.pop();
+            self.visit_method_body(method_nesting_receiver, body.as_ref());
             self.operations.push(Operation::ExitScope);
         } else {
             // Singleton methods at top level have receiver=None (no class to point self to).
@@ -1636,13 +1624,8 @@ impl Visit<'_> for RubyOperationBuilder<'_> {
                 signatures: Signatures::Simple(parameters.into_boxed_slice()),
                 receiver,
             }));
-            self.nesting_stack.push(Nesting::Method {
-                receiver: method_nesting_receiver,
-            });
-            if let Some(body) = node.body() {
-                self.visit(&body);
-            }
-            self.nesting_stack.pop();
+            let body = node.body();
+            self.visit_method_body(method_nesting_receiver, body.as_ref());
             self.operations.push(Operation::ExitScope);
 
             if let Some(prev) = previous_visibility {
@@ -2464,14 +2447,15 @@ mod tests {
     }
 
     #[test]
-    fn build_module_function_with_ivar() {
-        assert_operations(
+    fn build_module_function_with_body() {
+        assert_operations_with_references(
             "
             module Foo
               module_function
 
               def bar
-                @x = 1
+                @x = CONST
+                baz(1)
               end
             end
             ",
@@ -2479,10 +2463,11 @@ mod tests {
             EnterModule(Foo)
               SetDefaultVisibility(module_function)
               EnterMethod(self.bar())
-                DefineInstanceVariable(@x)
               ExitScope
               EnterMethod(bar())
                 DefineInstanceVariable(@x)
+                ReferenceConstant(CONST)
+                ReferenceMethod(baz)
               ExitScope
             ExitScope
             ",

data/rust/rubydex/src/path_helpers.rs

@@ -0,0 +1,77 @@
+use std::fs;
+use std::io;
+use std::path::{Path, PathBuf};
+
+/// Resolves `path` into the spelling rubydex knows a path by: absolute, with symlinks expanded and, on Windows, spelled
+/// plainly instead of verbatim.
+///
+/// # Errors
+///
+/// Returns an error if the path cannot be canonicalized, as for one that does not exist.
+pub(crate) fn resolved(path: &Path) -> io::Result<PathBuf> {
+    Ok(simplified(fs::canonicalize(path)?))
+}
+
+/// Only Windows spells a path verbatim, so everywhere else there is nothing to simplify.
+#[cfg(not(windows))]
+pub(crate) fn simplified(path: PathBuf) -> PathBuf {
+    path
+}
+
+/// Since we canonicalize paths, we must simplify Windows paths in order to use them correctly with glob patterns, like
+/// stripping the `\\?\` prefix.
+#[cfg(windows)]
+pub(crate) fn simplified(path: PathBuf) -> PathBuf {
+    use std::path::Component;
+    use std::path::Prefix;
+
+    let mut components = path.components();
+    let Some(Component::Prefix(prefix)) = components.next() else {
+        return path;
+    };
+
+    // Only a verbatim drive or share has a plain equivalent: `\\?\D:\dir` is `D:\dir`, and `\\?\UNC\server\share` is
+    // the share `\\server\share`. Any other verbatim prefix names a device, such as `\\?\pipe\name`, which has none.
+    let root = match prefix.kind() {
+        Prefix::VerbatimDisk(drive) => format!("{}:\\", char::from(drive)),
+        Prefix::VerbatimUNC(server, share) => {
+            format!(r"\\{}\{}\", server.to_string_lossy(), share.to_string_lossy())
+        }
+        _ => return path,
+    };
+
+    // The root already carries the separator that follows it, so the one spelled as its own component is dropped rather
+    // than pushed, which would otherwise reset the path back to the root it was just given.
+    let mut simplified = PathBuf::from(root);
+    simplified.extend(components.filter(|component| !matches!(component, Component::RootDir)));
+    simplified
+}
+
+#[cfg(all(test, windows))]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn simplified_rewrites_a_verbatim_path_into_its_plain_spelling() {
+        assert_eq!(
+            simplified(PathBuf::from(r"\\?\D:\a\project")),
+            PathBuf::from(r"D:\a\project")
+        );
+    }
+
+    #[test]
+    fn simplified_keeps_a_verbatim_share_rooted_on_that_share() {
+        assert_eq!(
+            simplified(PathBuf::from(r"\\?\UNC\server\share\project")),
+            PathBuf::from(r"\\server\share\project")
+        );
+    }
+
+    #[test]
+    fn simplified_leaves_a_path_with_no_plain_equivalent_alone() {
+        // A device path is not addressable without the prefix, and a plain path has nothing to simplify.
+        for path in [r"\\?\pipe\rubydex", r"D:\a\project", r"\\server\share\project"] {
+            assert_eq!(simplified(PathBuf::from(path)), PathBuf::from(path));
+        }
+    }
+}

data/rust/rubydex/src/query/cypher/schema.rs

@@ -39,6 +39,22 @@ pub enum NodeRef {
     Document(UriId),
 }
 
+impl NodeRef {
+    /// Decodes the opaque id produced by [`GraphProvider::node_id`] back into a `NodeRef`. Returns
+    /// `None` if the string is not a recognized `tag:id` form.
+    #[must_use]
+    pub fn decode(encoded: &str) -> Option<NodeRef> {
+        let (tag, rest) = encoded.split_once(':')?;
+        let value: u64 = rest.parse().ok()?;
+        match tag {
+            "decl" => Some(NodeRef::Declaration(DeclarationId::new(value))),
+            "def" => Some(NodeRef::Definition(DefinitionId::new(value))),
+            "doc" => Some(NodeRef::Document(UriId::new(value))),
+            _ => None,
+        }
+    }
+}
+
 /// A relationship type.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum RelType {
@@ -377,6 +393,10 @@ impl GraphProvider for Graph {
         RelType::parse(rel_type).map_or_else(Vec::new, |rel| rel_source_nodes(self, rel))
     }
 
+    fn expand_in(&self, node: NodeRef, rel_type: &str) -> Option<Vec<NodeRef>> {
+        RelType::parse(rel_type).and_then(|rel| expand_in(self, node, rel))
+    }
+
     fn property(&self, node: NodeRef, prop: &str) -> CypherValue {
         property(self, node, prop)
     }
@@ -388,6 +408,17 @@ impl GraphProvider for Graph {
     fn name(&self, node: NodeRef) -> String {
         node_name(self, node)
     }
+
+    fn node_id(&self, node: NodeRef) -> String {
+        // Encode the node category plus the underlying hashed id so a consumer can decode it back to
+        // the right handle. The category tag is required because labels alone are ambiguous
+        // (a class declaration and a class definition both have the label "Class").
+        match node {
+            NodeRef::Declaration(id) => format!("decl:{}", *id),
+            NodeRef::Definition(id) => format!("def:{}", *id),
+            NodeRef::Document(id) => format!("doc:{}", *id),
+        }
+    }
 }
 
 /// Returns all nodes matching the given labels. An empty slice matches every node; otherwise a node
@@ -582,6 +613,38 @@ pub fn rel_source_nodes(graph: &Graph, rel: RelType) -> Vec<NodeRef> {
     }
 }
 
+/// Expands the *incoming* edges of `node` for the given relationship type — the targeted reverse of
+/// [`expand_out`], returning `Some` only when the graph stores the reverse cheaply and exactly.
+/// Returning `None` lets the executor fall back to `rel_sources` + `expand` (always correct, but an
+/// O(all sources) whole-graph build).
+///
+/// Only the Document → Definition → Declaration spine is answered directly:
+/// - reverse `DEFINES`: a definition's document (each definition belongs to exactly one).
+/// - reverse `DECLARES`: the per-file definitions composing a declaration.
+///
+/// The remaining edges either have no stored reverse (e.g. direct subclasses of `HAS_PARENT`) or a
+/// reverse that isn't an exact set match (the `HAS_DESCENDANT` set is self-inclusive, unlike the
+/// `HAS_ANCESTOR` walk), so they fall through to the default.
+#[must_use]
+pub fn expand_in(graph: &Graph, node: NodeRef, rel: RelType) -> Option<Vec<NodeRef>> {
+    match (node, rel) {
+        (NodeRef::Definition(def_id), RelType::Defines) => {
+            let uri_id = *graph.definitions().get(&def_id)?.uri_id();
+            Some(vec![NodeRef::Document(uri_id)])
+        }
+        (NodeRef::Declaration(decl_id), RelType::Declares) => Some(
+            graph
+                .declarations()
+                .get(&decl_id)?
+                .definitions()
+                .iter()
+                .map(|id| NodeRef::Definition(*id))
+                .collect(),
+        ),
+        _ => None,
+    }
+}
+
 /// Expands the outgoing edges of `node` for the given relationship type.
 #[must_use]
 pub fn expand_out(graph: &Graph, node: NodeRef, rel: RelType) -> Vec<NodeRef> {