rubydex 0.2.9 → 0.4.0

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

@@ -291,7 +291,8 @@ pub unsafe extern "C" fn rdx_declaration_singleton_class(pointer: GraphPointer,
     })
 }
 
-/// Returns the owner of the declaration (attached object in the case of singleton classes)
+/// Returns the owner of the declaration (attached object in the case of singleton classes), or NULL if the declaration
+/// cannot be found.
 ///
 /// # Safety
 ///
@@ -299,11 +300,13 @@ pub unsafe extern "C" fn rdx_declaration_singleton_class(pointer: GraphPointer,
 ///
 /// # Panics
 ///
-/// Will panic if invoked on a non-existing or non-namespace declaration
+/// This function will panic if the owner declaration cannot be found.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn rdx_declaration_owner(pointer: GraphPointer, decl_id: u64) -> *const CDeclaration {
     with_graph(pointer, |graph| {
-        let declaration = graph.declarations().get(&DeclarationId::new(decl_id)).unwrap();
+        let Some(declaration) = graph.declarations().get(&DeclarationId::new(decl_id)) else {
+            return ptr::null();
+        };
         let owner_id = *declaration.owner_id();
         Box::into_raw(Box::new(CDeclaration::from_declaration(
             owner_id,

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

@@ -156,21 +156,22 @@ pub struct CommentArray {
     pub len: usize,
 }
 
-/// Returns a newly allocated array of comments (string and location) for the given definition id.
-/// Caller must free the returned pointer with `rdx_definition_comments_free` and each inner string with `free_c_string` if needed.
+/// Returns a newly allocated array of comments (string and location) for the given definition id, or NULL if the
+/// definition cannot be found. Caller must free the returned pointer and its contents with
+/// `rdx_definition_comments_free`.
 ///
 /// # Safety
 /// - `pointer` must be a valid pointer previously returned by `rdx_graph_new`.
 /// - `definition_id` must be a valid definition id.
 ///
 /// # Panics
-/// This function will panic if a definition or document cannot be found.
+/// This function will panic if the definition's document cannot be found.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn rdx_definition_comments(pointer: GraphPointer, definition_id: u64) -> *mut CommentArray {
     with_graph(pointer, |graph| {
         let def_id = DefinitionId::new(definition_id);
         let Some(defn) = graph.definitions().get(&def_id) else {
-            panic!("Definition not found: {definition_id:?}");
+            return ptr::null_mut();
         };
 
         let uri_id = *defn.uri_id();
@@ -229,7 +230,7 @@ pub unsafe extern "C" fn rdx_definition_comments_free(ptr: *mut CommentArray) {
     // arr is dropped here
 }
 
-/// Returns a newly allocated `Location` for the given definition id.
+/// Returns a newly allocated `Location` for the given definition id, or NULL if the definition cannot be found.
 /// Caller must free the returned pointer with `rdx_location_free`.
 ///
 /// # Safety
@@ -238,13 +239,13 @@ pub unsafe extern "C" fn rdx_definition_comments_free(ptr: *mut CommentArray) {
 ///
 /// # Panics
 ///
-/// This function will panic if a definition or document cannot be found.
+/// This function will panic if the definition's document cannot be found.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn rdx_definition_location(pointer: GraphPointer, definition_id: u64) -> *mut Location {
     with_graph(pointer, |graph| {
         let def_id = DefinitionId::new(definition_id);
         let Some(defn) = graph.definitions().get(&def_id) else {
-            panic!("Definition not found: {definition_id:?}");
+            return ptr::null_mut();
         };
 
         let document = graph.documents().get(defn.uri_id()).expect("document should exist");
@@ -493,6 +494,25 @@ pub unsafe extern "C" fn rdx_definition_mixins(pointer: GraphPointer, definition
     })
 }
 
+/// Returns a pointer to the URI ID of the document a definition belongs to, or
+/// NULL if the definition cannot be found. Caller must free the returned pointer
+/// with `free_u64`.
+///
+/// # Safety
+/// - `pointer` must be a valid pointer previously returned by `rdx_graph_new`.
+/// - `definition_id` must be a valid definition id.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_definition_document(pointer: GraphPointer, definition_id: u64) -> *const u64 {
+    with_graph(pointer, |graph| {
+        let def_id = DefinitionId::new(definition_id);
+        if let Some(defn) = graph.definitions().get(&def_id) {
+            Box::into_raw(Box::new(**defn.uri_id())).cast_const()
+        } else {
+            ptr::null()
+        }
+    })
+}
+
 /// Status of a `MethodAliasDefinition#target` resolution.
 #[repr(u8)]
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]

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

@@ -3,12 +3,87 @@
 use crate::graph_api::{GraphPointer, with_graph};
 use crate::location_api::{Location, create_location_for_uri_and_offset};
 use libc::c_char;
+use rubydex::diagnostic::{Rule, Severity};
 use std::{ffi::CString, mem, ptr};
 
+/// C-compatible enum representing diagnostic severity levels.
+#[repr(C)]
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+pub enum DiagnosticSeverity {
+    Error = 1,
+    Warning = 2,
+    Information = 3,
+    Hint = 4,
+}
+
+impl From<Severity> for DiagnosticSeverity {
+    fn from(severity: Severity) -> Self {
+        match severity {
+            Severity::Error => DiagnosticSeverity::Error,
+            Severity::Warning => DiagnosticSeverity::Warning,
+            Severity::Information => DiagnosticSeverity::Information,
+            Severity::Hint => DiagnosticSeverity::Hint,
+        }
+    }
+}
+
+#[repr(C)]
+#[derive(Debug)]
+pub struct CRule {
+    pub name: *const c_char,
+    pub name_length: usize,
+    pub default_severity: DiagnosticSeverity,
+}
+
+impl From<Rule> for CRule {
+    fn from(rule: Rule) -> Self {
+        let name = rule.name();
+
+        Self {
+            name: name.as_ptr().cast::<c_char>(),
+            name_length: name.len(),
+            default_severity: DiagnosticSeverity::from(rule.default_severity()),
+        }
+    }
+}
+
+#[repr(C)]
+pub struct CRuleArray {
+    pub items: *mut CRule,
+    pub len: usize,
+}
+
+/// Returns every rule the graph can report. Caller must free it with `rdx_rules_free`.
+#[unsafe(no_mangle)]
+pub extern "C" fn rdx_rules() -> CRuleArray {
+    let items = Rule::all().iter().copied().map(CRule::from).collect::<Box<[CRule]>>();
+
+    CRuleArray {
+        len: items.len(),
+        items: Box::into_raw(items).cast::<CRule>(),
+    }
+}
+
+/// Frees an array previously returned by `rdx_rules`.
+///
+/// # Safety
+///
+/// - `rules` must have been returned by `rdx_rules` and must not be used afterwards.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_rules_free(rules: CRuleArray) {
+    if rules.items.is_null() {
+        return;
+    }
+
+    unsafe {
+        let _ = Box::from_raw(ptr::slice_from_raw_parts_mut(rules.items, rules.len));
+    }
+}
+
 /// C-compatible struct representing a diagnostic entry.
 #[repr(C)]
 pub struct DiagnosticEntry {
-    pub rule: *const c_char,
+    pub rule: CRule,
     pub message: *const c_char,
     pub location: *mut Location,
 }
@@ -50,10 +125,7 @@ pub unsafe extern "C" fn rdx_graph_diagnostics(pointer: GraphPointer) -> *mut Di
                 let location = create_location_for_uri_and_offset(graph, document, diagnostic.offset());
 
                 DiagnosticEntry {
-                    rule: CString::new(diagnostic.rule().to_string())
-                        .unwrap()
-                        .into_raw()
-                        .cast_const(),
+                    rule: CRule::from(*diagnostic.rule()),
                     message: CString::new(diagnostic.message()).unwrap().into_raw().cast_const(),
                     location,
                 }
@@ -82,9 +154,6 @@ pub unsafe extern "C" fn rdx_diagnostics_free(ptr: *mut DiagnosticArray) {
         let mut boxed_slice: Box<[DiagnosticEntry]> = unsafe { Box::from_raw(slice_ptr) };
 
         for entry in &mut *boxed_slice {
-            if !entry.rule.is_null() {
-                let _ = unsafe { CString::from_raw(entry.rule.cast_mut()) };
-            }
             if !entry.message.is_null() {
                 let _ = unsafe { CString::from_raw(entry.message.cast_mut()) };
             }

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

@@ -1,5 +1,6 @@
 //! This file provides the C API for the Graph object
 
+use crate::config_api::ConfigPointer;
 use crate::declaration_api::CDeclaration;
 use crate::declaration_api::DeclarationsIter;
 use crate::declaration_api::decl_id_from_char_ptr;
@@ -7,7 +8,7 @@ use crate::document_api::DocumentsIter;
 use crate::reference_api::{CConstantReference, CMethodReference, ConstantReferencesIter, MethodReferencesIter};
 use crate::{name_api, utils};
 use libc::{c_char, c_void};
-use rubydex::errors::Errors;
+use rubydex::config::Config;
 use rubydex::indexing::LanguageId;
 use rubydex::model::encoding::Encoding;
 use rubydex::model::graph::Graph;
@@ -19,43 +20,46 @@ use rubydex::query::{CompletionCandidate, CompletionContext, CompletionReceiver}
 use rubydex::resolution::Resolver;
 use rubydex::{indexing, integrity, listing, query};
 use std::ffi::CString;
-use std::path::{Path, PathBuf};
-use std::{mem, ptr};
+use std::path::PathBuf;
+use std::{mem, ptr, sync::RwLock};
 
 pub type GraphPointer = *mut c_void;
 
-/// Creates a new graph within a mutex. This is meant to be used when creating new Graph objects in Ruby
+/// Creates a new graph wrapped in a `Box<RwLock<Graph>>` for thread-safe shared access across Ractors.
 #[unsafe(no_mangle)]
 pub extern "C" fn rdx_graph_new() -> GraphPointer {
-    Box::into_raw(Box::new(Graph::new())) as GraphPointer
+    Box::into_raw(Box::new(RwLock::new(Graph::new()))) as GraphPointer
 }
 
 /// Frees a Graph through its pointer
 #[unsafe(no_mangle)]
 pub extern "C" fn rdx_graph_free(pointer: GraphPointer) {
     unsafe {
-        let _ = Box::from_raw(pointer.cast::<Graph>());
+        let _ = Box::from_raw(pointer.cast::<RwLock<Graph>>());
     }
 }
 
+/// Runs `action` against the graph referenced by `pointer` under a read lock.
+///
+/// # Panics
+///
+/// Panics if the `RwLock` is poisoned (a writer panicked while holding the lock).
 pub fn with_graph<F, T>(pointer: GraphPointer, action: F) -> T
 where
     F: FnOnce(&Graph) -> T,
 {
-    let mut graph = unsafe { Box::from_raw(pointer.cast::<Graph>()) };
-    let result = action(&mut graph);
-    mem::forget(graph);
-    result
+    let rwlock = unsafe { &*pointer.cast::<RwLock<Graph>>() };
+    let guard = rwlock.read().unwrap();
+    action(&guard)
 }
 
 fn with_mut_graph<F, T>(pointer: GraphPointer, action: F) -> T
 where
     F: FnOnce(&mut Graph) -> T,
 {
-    let mut graph = unsafe { Box::from_raw(pointer.cast::<Graph>()) };
-    let result = action(&mut graph);
-    mem::forget(graph);
-    result
+    let rwlock = unsafe { &*pointer.cast::<RwLock<Graph>>() };
+    let mut guard = rwlock.write().unwrap();
+    action(&mut guard)
 }
 
 /// Searches the graph using exact substring matching, returning every declaration whose name matches any of the
@@ -212,14 +216,8 @@ pub unsafe extern "C" fn rdx_graph_excluded_patterns(
 
         let c_strings: Vec<*const c_char> = excluded
             .iter()
-            .filter_map(|path| {
-                // Normalize all paths to use forward slashes. Otherwise, you get mixed backslashes and forward slashes
-                // on Windows if a configuration file is using forward slashes. For example:
-                //
-                // C:\project/vendor/bundle
-                let normalized = path.replace(std::path::MAIN_SEPARATOR, "/");
-
-                CString::new(normalized)
+            .filter_map(|pattern| {
+                CString::new(pattern.as_ref())
                     .ok()
                     .map(|c_string| c_string.into_raw().cast_const())
             })
@@ -232,23 +230,6 @@ pub unsafe extern "C" fn rdx_graph_excluded_patterns(
     })
 }
 
-/// Sets the workspace path used as the root directory for indexing and relative path resolution. Silently ignores the
-/// call if the given path is not valid UTF-8, leaving the existing workspace path untouched (mirrors
-/// `rdx_graph_set_encoding`). This avoids unwinding across the FFI boundary on malformed input.
-///
-/// # Safety
-///
-/// - `pointer` must be a valid `GraphPointer` previously returned by this crate.
-/// - `path` must be a valid, null-terminated string.
-#[unsafe(no_mangle)]
-pub unsafe extern "C" fn rdx_graph_set_workspace_path(pointer: GraphPointer, path: *const c_char) {
-    let Ok(path) = (unsafe { utils::convert_char_ptr_to_string(path) }) else {
-        return;
-    };
-
-    with_mut_graph(pointer, |graph| graph.set_workspace_path(PathBuf::from(path)));
-}
-
 /// Returns the workspace path as a C string. Caller must free with `free_c_string`.
 ///
 /// # Safety
@@ -257,42 +238,23 @@ pub unsafe extern "C" fn rdx_graph_set_workspace_path(pointer: GraphPointer, pat
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn rdx_graph_workspace_path(pointer: GraphPointer) -> *const c_char {
     with_graph(pointer, |graph| {
-        CString::new(graph.workspace_path().to_string_lossy().as_ref())
+        CString::new(utils::interop_path(graph.workspace_path()))
             .map_or(ptr::null(), |c_string| c_string.into_raw().cast_const())
     })
 }
 
-/// Loads configuration into the graph. A null `config_path` attempts to load the default configuration file.
-///
-/// Returns NULL on success. On failure returns an owned, null-terminated error message that the caller must free with
-/// `free_c_string`.
-///
-/// A `config_path` that is not valid UTF-8 is reported as an error message.
+/// Applies a parsed configuration file to the graph, which adopts the workspace it was loaded for along with the
+/// settings of its `[graph]` section. This is the only way to point the graph at a workspace other than the current
+/// directory, and it replaces any previously applied configuration. Tool-specific sections are ignored.
 ///
 /// # Safety
 ///
 /// - `pointer` must be a valid `GraphPointer` previously returned by this crate.
-/// - `config_path` must either be NULL or a valid, null-terminated string.
+/// - `config` must be a valid `ConfigPointer` previously returned by `rdx_config_load`.
 #[unsafe(no_mangle)]
-pub unsafe extern "C" fn rdx_graph_load_config(pointer: GraphPointer, config_path: *const c_char) -> *const c_char {
-    let result = with_mut_graph(pointer, |graph| {
-        if config_path.is_null() {
-            graph.load_config(None)
-        } else {
-            match unsafe { utils::convert_char_ptr_to_string(config_path) } {
-                Ok(config_path) => graph.load_config(Some(Path::new(&config_path))),
-                Err(_) => Err(Errors::ConfigError("config file path is not valid UTF-8".to_string())),
-            }
-        }
-    });
-
-    match result {
-        Ok(()) => ptr::null(),
-        Err(error) => CString::new(error.to_string())
-            .unwrap_or_default()
-            .into_raw()
-            .cast_const(),
-    }
+pub unsafe extern "C" fn rdx_graph_load_config(pointer: GraphPointer, config: ConfigPointer) {
+    let config = unsafe { &*config.cast::<Config>() };
+    with_mut_graph(pointer, |graph| graph.load_config(config));
 }
 
 /// Indexes all given file paths in parallel using the provided Graph pointer.
@@ -1170,7 +1132,7 @@ mod tests {
                 .ref_count()
         );
 
-        let graph_ptr = Box::into_raw(Box::new(graph)) as GraphPointer;
+        let graph_ptr = Box::into_raw(Box::new(RwLock::new(graph))) as GraphPointer;
 
         // Build the nesting array: ["Foo"] since BAR is inside class Foo
         let nesting_strings = [CString::new("Foo").unwrap()];
@@ -1186,7 +1148,8 @@ mod tests {
             assert_eq!((*decl).id(), *DeclarationId::from("Foo::BAR"));
         };
 
-        let graph = unsafe { Box::from_raw(graph_ptr.cast::<Graph>()) };
+        let graph = unsafe { Box::from_raw(graph_ptr.cast::<RwLock<Graph>>()) };
+        let graph = graph.read().unwrap();
 
         assert_eq!(
             1,

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

@@ -68,6 +68,8 @@ macro_rules! iterator {
     };
 }
 
+pub mod config_api;
+pub mod cypher_api;
 pub mod declaration_api;
 pub mod definition_api;
 pub mod diagnostic_api;

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

@@ -1,8 +1,4 @@
-use rubydex::model::{
-    graph::Graph,
-    ids::NameId,
-    name::{Name, ParentScope},
-};
+use rubydex::model::{graph::Graph, ids::NameId, name::ParentScope};
 
 /// Takes a constant name and a nesting stack (e.g.: `["Foo", "Bar::Baz", "Qux"]`) and transforms it into a `NameId`,
 /// registering each required part in the graph. Returns the `NameId` and a list of name ids that need to be untracked
@@ -74,7 +70,7 @@ fn process_qualified_name(
         };
 
         let str_id = graph.intern_string(part.to_owned());
-        let name_id = graph.add_name(Name::new(str_id, parent_scope, nesting_for_part));
+        let name_id = graph.add_name(str_id, parent_scope, nesting_for_part);
         names_to_untrack.push(name_id);
         *current_name = ParentScope::Some(name_id);
     }

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

@@ -120,7 +120,7 @@ pub unsafe extern "C" fn rdx_method_references_iter_free(iter: *mut MethodRefere
     unsafe { MethodReferencesIter::free(iter) }
 }
 
-/// Returns the UTF-8 name string for a constant reference id.
+/// Returns the UTF-8 name string for a constant reference id, or NULL if the reference cannot be found.
 /// Caller must free with `free_c_string`.
 ///
 /// # Safety
@@ -129,12 +129,14 @@ pub unsafe extern "C" fn rdx_method_references_iter_free(iter: *mut MethodRefere
 ///
 /// # Panics
 ///
-/// This function will panic if the reference cannot be found.
+/// This function will panic if the reference's name cannot be found.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn rdx_constant_reference_name(pointer: GraphPointer, reference_id: u64) -> *const c_char {
     with_graph(pointer, |graph| {
         let ref_id = ConstantReferenceId::new(reference_id);
-        let reference = graph.constant_references().get(&ref_id).expect("Reference not found");
+        let Some(reference) = graph.constant_references().get(&ref_id) else {
+            return ptr::null();
+        };
         let name = graph.names().get(reference.name_id()).expect("Name ID should exist");
 
         let name_string = graph
@@ -146,7 +148,7 @@ pub unsafe extern "C" fn rdx_constant_reference_name(pointer: GraphPointer, refe
     })
 }
 
-/// Returns the UTF-8 name string for a method reference id.
+/// Returns the UTF-8 name string for a method reference id, or NULL if the reference cannot be found.
 /// Caller must free with `free_c_string`.
 ///
 /// # Safety
@@ -155,12 +157,14 @@ pub unsafe extern "C" fn rdx_constant_reference_name(pointer: GraphPointer, refe
 ///
 /// # Panics
 ///
-/// This function will panic if the reference cannot be found.
+/// This function will panic if the reference's name cannot be found.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn rdx_method_reference_name(pointer: GraphPointer, reference_id: u64) -> *const c_char {
     with_graph(pointer, |graph| {
         let ref_id = MethodReferenceId::new(reference_id);
-        let reference = graph.method_references().get(&ref_id).expect("Reference not found");
+        let Some(reference) = graph.method_references().get(&ref_id) else {
+            return ptr::null();
+        };
         let name = graph
             .strings()
             .get(reference.str())
@@ -170,7 +174,7 @@ pub unsafe extern "C" fn rdx_method_reference_name(pointer: GraphPointer, refere
     })
 }
 
-/// Returns a newly allocated `Location` for the given constant reference id.
+/// Returns a newly allocated `Location` for the given constant reference id, or NULL if the reference cannot be found.
 /// Caller must free the returned pointer with `rdx_location_free`.
 ///
 /// # Safety
@@ -180,12 +184,14 @@ pub unsafe extern "C" fn rdx_method_reference_name(pointer: GraphPointer, refere
 ///
 /// # Panics
 ///
-/// This function will panic if a reference or document cannot be found.
+/// This function will panic if the reference's document cannot be found.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn rdx_constant_reference_location(pointer: GraphPointer, reference_id: u64) -> *mut Location {
     with_graph(pointer, |graph| {
         let ref_id = ConstantReferenceId::new(reference_id);
-        let reference = graph.constant_references().get(&ref_id).expect("Reference not found");
+        let Some(reference) = graph.constant_references().get(&ref_id) else {
+            return ptr::null_mut();
+        };
         let document = graph
             .documents()
             .get(&reference.uri_id())
@@ -226,6 +232,25 @@ pub unsafe extern "C" fn rdx_resolved_constant_reference_declaration(
     })
 }
 
+/// Returns a pointer to the URI ID of the document a constant reference belongs
+/// to, or NULL if the reference cannot be found. Caller must free the returned
+/// pointer with `free_u64`.
+///
+/// # Safety
+/// - `pointer` must be a valid pointer previously returned by `rdx_graph_new`.
+/// - `reference_id` must be a valid reference id.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_constant_reference_document(pointer: GraphPointer, reference_id: u64) -> *const u64 {
+    with_graph(pointer, |graph| {
+        let ref_id = ConstantReferenceId::new(reference_id);
+        if let Some(reference) = graph.constant_references().get(&ref_id) {
+            Box::into_raw(Box::new(*reference.uri_id())).cast_const()
+        } else {
+            ptr::null()
+        }
+    })
+}
+
 /// Returns the declaration of the resolved receiver for the given method reference. Returns NULL when the method
 /// reference has no tracked receiver or when the receiver could not be resolved. Caller must free with
 /// `free_c_declaration`.
@@ -263,7 +288,7 @@ pub unsafe extern "C" fn rdx_method_reference_receiver_declaration(
     })
 }
 
-/// Returns a newly allocated `Location` for the given method reference id.
+/// Returns a newly allocated `Location` for the given method reference id, or NULL if the reference cannot be found.
 /// Caller must free the returned pointer with `rdx_location_free`.
 ///
 /// # Safety
@@ -273,12 +298,14 @@ pub unsafe extern "C" fn rdx_method_reference_receiver_declaration(
 ///
 /// # Panics
 ///
-/// This function will panic if a reference or document cannot be found.
+/// This function will panic if the reference's document cannot be found.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn rdx_method_reference_location(pointer: GraphPointer, reference_id: u64) -> *mut Location {
     with_graph(pointer, |graph| {
         let ref_id = MethodReferenceId::new(reference_id);
-        let reference = graph.method_references().get(&ref_id).expect("Reference not found");
+        let Some(reference) = graph.method_references().get(&ref_id) else {
+            return ptr::null_mut();
+        };
         let document = graph
             .documents()
             .get(&reference.uri_id())
@@ -288,6 +315,25 @@ pub unsafe extern "C" fn rdx_method_reference_location(pointer: GraphPointer, re
     })
 }
 
+/// Returns a pointer to the URI ID of the document a method reference belongs
+/// to, or NULL if the reference cannot be found. Caller must free the returned
+/// pointer with `free_u64`.
+///
+/// # Safety
+/// - `pointer` must be a valid pointer previously returned by `rdx_graph_new`.
+/// - `reference_id` must be a valid reference id.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_method_reference_document(pointer: GraphPointer, reference_id: u64) -> *const u64 {
+    with_graph(pointer, |graph| {
+        let ref_id = MethodReferenceId::new(reference_id);
+        if let Some(reference) = graph.method_references().get(&ref_id) {
+            Box::into_raw(Box::new(*reference.uri_id())).cast_const()
+        } else {
+            ptr::null()
+        }
+    })
+}
+
 /// Frees a `CConstantReference` previously returned by an FFI function.
 ///
 /// # Safety

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

@@ -1,5 +1,6 @@
 use libc::{c_char, size_t};
 use std::ffi::{CStr, CString};
+use std::path::Path;
 use std::slice;
 use std::str::Utf8Error;
 
@@ -68,3 +69,39 @@ pub unsafe extern "C" fn free_c_string_array(ptr: *const *const c_char, count: u
         .map(|arg| unsafe { CString::from_raw((*arg).cast_mut()) })
         .collect();
 }
+
+/// Converts a Rust `&str` to an owned C string (`*const c_char`), suitable for returning across the
+/// FFI boundary. The caller is responsible for freeing it with `free_c_string`.
+///
+/// # Panics
+///
+/// Panics if `value` contains an interior null byte, which should never occur in rubydex data.
+#[must_use]
+pub fn cstring_raw(value: &str) -> *const c_char {
+    CString::new(value).unwrap().into_raw().cast_const()
+}
+
+/// Rust uses backslashes as separators on Windows, but Ruby prefers forward slashes everywhere. We need to make sure
+/// we're maintaining the right separators at the boundary.
+#[must_use]
+pub fn interop_path(path: &Path) -> String {
+    path.to_string_lossy().replace(std::path::MAIN_SEPARATOR, "/")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[cfg(unix)]
+    #[test]
+    fn interop_path_leaves_a_unix_path_untouched() {
+        // A backslash is an ordinary character in a Unix file name, so rewriting it would name a different file.
+        assert_eq!(interop_path(Path::new(r"/tmp/we\ird")), r"/tmp/we\ird");
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn interop_path_separates_a_windows_path_with_forward_slashes() {
+        assert_eq!(interop_path(Path::new(r"D:\a\_temp\project")), "D:/a/_temp/project");
+    }
+}