rubydex 0.2.9 → 0.3.0

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

@@ -15,47 +15,51 @@ use rubydex::model::ids::{DeclarationId, NameId, UriId, declaration_id_from_look
 use rubydex::model::keywords;
 use rubydex::model::name::NameRef;
 use rubydex::model::visibility::Visibility;
+use rubydex::query::cypher::{self, OutputFormat};
 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::{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
@@ -1062,6 +1066,145 @@ pub unsafe extern "C" fn rdx_keyword_get(name: *const c_char) -> *const CKeyword
     }
 }
 
+/// The result of running a Cypher query, carrying either the formatted output or an error message.
+#[repr(C)]
+pub struct CQueryResult {
+    /// Non-null on success; null on error. Caller must free with `free_c_string`.
+    pub output: *const c_char,
+    /// Non-null on error; null on success. Caller must free with `free_c_string`.
+    pub error: *const c_char,
+}
+
+impl CQueryResult {
+    fn success(output: &str) -> Self {
+        match CString::new(output) {
+            Ok(c_string) => Self {
+                output: c_string.into_raw().cast_const(),
+                error: ptr::null(),
+            },
+            Err(_) => Self::error("query output contained an interior NUL byte"),
+        }
+    }
+
+    fn error(message: &str) -> Self {
+        Self {
+            output: ptr::null(),
+            error: CString::new(message).map_or(ptr::null(), |s| s.into_raw().cast_const()),
+        }
+    }
+}
+
+/// The result of parsing a Cypher query into an opaque, reusable parsed-query object.
+#[repr(C)]
+pub struct CParseResult {
+    /// Non-null on success: a heap-allocated parsed query. Free with `rdx_cypher_query_free`.
+    pub query: *mut c_void,
+    /// Non-null on error; null on success. Caller must free with `free_c_string`.
+    pub error: *const c_char,
+}
+
+/// Parses a Cypher query string into an opaque parsed-query object, without needing a graph.
+///
+/// On success, `query` is a heap-allocated parsed query that can be executed against a graph with
+/// `rdx_query_run` and must eventually be freed with `rdx_cypher_query_free`. On failure, `error`
+/// holds the message.
+///
+/// # Safety
+///
+/// - `query` must be a valid, null-terminated UTF-8 string.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_cypher_parse(query: *const c_char) -> CParseResult {
+    let Ok(query_str) = (unsafe { utils::convert_char_ptr_to_string(query) }) else {
+        return CParseResult {
+            query: ptr::null_mut(),
+            error: CString::new("query is not valid UTF-8").map_or(ptr::null(), |s| s.into_raw().cast_const()),
+        };
+    };
+
+    match cypher::parse(&query_str) {
+        Ok(parsed) => CParseResult {
+            query: Box::into_raw(Box::new(parsed)).cast::<c_void>(),
+            error: ptr::null(),
+        },
+        Err(error) => CParseResult {
+            query: ptr::null_mut(),
+            error: CString::new(error.to_string()).map_or(ptr::null(), |s| s.into_raw().cast_const()),
+        },
+    }
+}
+
+/// Frees a parsed query previously returned by `rdx_cypher_parse`.
+///
+/// # Safety
+///
+/// - `query` must be a pointer returned by `rdx_cypher_parse`, or null. It must not be used after.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_cypher_query_free(query: *mut c_void) {
+    if query.is_null() {
+        return;
+    }
+    let _ = unsafe { Box::from_raw(query.cast::<cypher::Query>()) };
+}
+
+/// Executes a previously parsed query (from `rdx_cypher_parse`) against the graph and returns the
+/// formatted output or an error message. `format` must be `"table"` or `"json"`.
+///
+/// # Safety
+///
+/// - `query` must be a valid pointer returned by `rdx_cypher_parse`.
+/// - `pointer` must be a valid `GraphPointer` previously returned by this crate.
+/// - `format` must be a valid, null-terminated UTF-8 string.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_query_run(
+    query: *const c_void,
+    pointer: GraphPointer,
+    format: *const c_char,
+) -> CQueryResult {
+    if query.is_null() {
+        return CQueryResult::error("query is null");
+    }
+
+    let Ok(format_str) = (unsafe { utils::convert_char_ptr_to_string(format) }) else {
+        return CQueryResult::error("format is not valid UTF-8");
+    };
+
+    let output_format = match format_str.as_str() {
+        "table" => OutputFormat::Table,
+        "json" => OutputFormat::Json,
+        other => {
+            return CQueryResult::error(&format!("unknown query format `{other}` (expected `table` or `json`)"));
+        }
+    };
+
+    let parsed = unsafe { &*query.cast::<cypher::Query>() };
+
+    with_graph(pointer, |graph| {
+        match cypher::run_parsed(graph, parsed, output_format) {
+            Ok(output) => CQueryResult::success(&output),
+            Err(error) => CQueryResult::error(&error.to_string()),
+        }
+    })
+}
+
+/// Returns a description of the queryable Cypher schema (node labels, relationship types, and
+/// properties) in the given format (`"table"` or `"json"`). The schema is static and requires no
+/// graph. Caller must free the returned pointer with `free_c_string`.
+///
+/// # Safety
+///
+/// - `format` must be a valid, null-terminated UTF-8 string.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_cypher_schema(format: *const c_char) -> *const c_char {
+    let format_str = unsafe { utils::convert_char_ptr_to_string(format) }.unwrap_or_else(|_| "table".to_string());
+    let output_format = if format_str == "json" {
+        OutputFormat::Json
+    } else {
+        OutputFormat::Table
+    };
+
+    CString::new(cypher::schema(output_format)).map_or(ptr::null(), |s| s.into_raw().cast_const())
+}
+
 #[repr(u8)]
 #[derive(Debug, Clone, Copy)]
 pub enum CVisibility {
@@ -1170,7 +1313,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 +1329,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/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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubydex
 version: !ruby/object:Gem::Version
-  version: 0.2.9
+  version: 0.3.0
 platform: ruby
 authors:
 - Shopify
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-09 00:00:00.000000000 Z
+date: 2026-07-22 00:00:00.000000000 Z
 dependencies: []
 description: A high-performance static analysis suite for Ruby, built in Rust with
   Ruby APIs
@@ -38,6 +38,8 @@ files:
 - ext/rubydex/handle.h
 - ext/rubydex/location.c
 - ext/rubydex/location.h
+- ext/rubydex/query.c
+- ext/rubydex/query.h
 - ext/rubydex/reference.c
 - ext/rubydex/reference.h
 - ext/rubydex/rubydex.c
@@ -128,6 +130,10 @@ files:
 - rust/rubydex/src/operation/ruby_builder.rs
 - rust/rubydex/src/position.rs
 - rust/rubydex/src/query.rs
+- rust/rubydex/src/query/cypher.rs
+- rust/rubydex/src/query/cypher/schema.rs
+- rust/rubydex/src/query/cypher/schema_info.rs
+- rust/rubydex/src/query/cypher/tests.rs
 - rust/rubydex/src/resolution.rs
 - rust/rubydex/src/resolution_tests.rs
 - rust/rubydex/src/stats.rs