rubydex 0.1.0.beta12-aarch64-linux

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

@@ -0,0 +1,79 @@
+/// Helper macro to generate all required functions for an iterator. We use iterators to go over any collection of data
+/// that exists on the Rust side (e.g.: definitions, documents, declarations, references). The goal is to avoid eager
+/// allocation of large collections when possible.
+///
+/// Note: structs must be defined manually so that the cbindgen can see them. The actual methods are not extern "C" and
+/// so they can be expanded from the macro.
+///
+/// # Example
+///
+/// ```ignore
+/// pub struct FoosIter {
+///     entries: Box<[Foo]>,
+///     index: usize,
+/// }
+///
+/// iterator!(FoosIter, entries: Foo);
+/// ```
+macro_rules! iterator {
+    ($name:ident, $field:ident : $entry:ty) => {
+        impl $name {
+            #[must_use]
+            pub fn new($field: Box<[$entry]>) -> *mut $name {
+                Box::into_raw(Box::new($name { $field, index: 0 }))
+            }
+
+            /// # Safety
+            /// `iter` must be a valid pointer returned by `new`, or null.
+            pub unsafe fn len(iter: *const Self) -> usize {
+                if iter.is_null() {
+                    return 0;
+                }
+                unsafe { (&*iter).$field.len() }
+            }
+
+            /// # Safety
+            /// - `iter` must be a valid pointer returned by `new`, or null.
+            /// - `out` must be a valid, writable pointer, or null.
+            pub unsafe fn next(iter: *mut Self, out: *mut $entry) -> bool {
+                if iter.is_null() || out.is_null() {
+                    return false;
+                }
+
+                let it = unsafe { &mut *iter };
+                if it.index >= it.$field.len() {
+                    return false;
+                }
+
+                let entry = it.$field[it.index];
+                it.index += 1;
+                unsafe {
+                    *out = entry;
+                }
+
+                true
+            }
+
+            /// # Safety
+            /// `iter` must be a pointer returned by `new` (or null). Must not be used after.
+            pub unsafe fn free(iter: *mut Self) {
+                if iter.is_null() {
+                    return;
+                }
+                unsafe {
+                    let _ = Box::from_raw(iter);
+                }
+            }
+        }
+    };
+}
+
+pub mod declaration_api;
+pub mod definition_api;
+pub mod diagnostic_api;
+pub mod document_api;
+pub mod graph_api;
+pub mod location_api;
+pub mod name_api;
+pub mod reference_api;
+pub mod utils;

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

@@ -0,0 +1,79 @@
+//! Location-related C API and structs
+
+use libc::c_char;
+use rubydex::model::document::Document;
+use rubydex::model::graph::Graph;
+use rubydex::offset::Offset;
+use std::ffi::CString;
+
+/// C-compatible struct representing a definition location with offsets and line/column positions.
+#[repr(C)]
+#[derive(Debug, Clone)]
+pub struct Location {
+    pub uri: *const c_char,
+    pub start_line: u32,
+    pub end_line: u32,
+    pub start_column: u32,
+    pub end_column: u32,
+}
+
+/// Helper to create a location for a given URI and byte-offset range.
+/// Allocates and returns a pointer to `Location`. Caller must free with `rdx_location_free`.
+///
+/// # Panics
+///
+/// - If the URI cannot be converted to a file path.
+/// - If the file cannot be read.
+/// - If the offset cannot be converted to a position.
+#[must_use]
+pub(crate) fn create_location_for_uri_and_offset(graph: &Graph, document: &Document, offset: &Offset) -> *mut Location {
+    let line_index = document.line_index();
+    let start_pos = line_index.line_col(offset.start().into());
+    let end_pos = line_index.line_col(offset.end().into());
+
+    let loc = if let Some(wide_encoding) = graph.encoding().to_wide() {
+        let wide_start_pos = line_index.to_wide(wide_encoding, start_pos).unwrap();
+        let wide_end_pos = line_index.to_wide(wide_encoding, end_pos).unwrap();
+
+        Location {
+            uri: CString::new(document.uri()).unwrap().into_raw().cast_const(),
+            start_line: wide_start_pos.line,
+            end_line: wide_end_pos.line,
+            start_column: wide_start_pos.col,
+            end_column: wide_end_pos.col,
+        }
+    } else {
+        Location {
+            uri: CString::new(document.uri()).unwrap().into_raw().cast_const(),
+            start_line: start_pos.line,
+            end_line: end_pos.line,
+            start_column: start_pos.col,
+            end_column: end_pos.col,
+        }
+    };
+
+    Box::into_raw(Box::new(loc))
+}
+
+/// Frees a `Location` struct and its owned inner strings.
+///
+/// # Safety
+///
+/// - `ptr` must be a valid pointer previously returned by `create_location_for_uri_and_offset`.
+/// - `ptr` must not be used after being freed.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_location_free(ptr: *mut Location) {
+    if ptr.is_null() {
+        return;
+    }
+    unsafe {
+        // Take ownership of the box so we can free inner allocations first
+        let boxed = Box::from_raw(ptr);
+
+        if !boxed.uri.is_null() {
+            let _ = CString::from_raw(boxed.uri.cast_mut());
+        }
+
+        // Box drops here, freeing the struct memory
+    }
+}

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

@@ -0,0 +1,135 @@
+use rubydex::model::{
+    graph::Graph,
+    ids::NameId,
+    name::{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
+/// afterwards
+///
+/// # Panics
+///
+/// Should not panic because `const_name` will always be turned into a name
+pub fn nesting_stack_to_name_id(graph: &mut Graph, const_name: &str, nesting: Vec<String>) -> (NameId, Vec<NameId>) {
+    let mut current_nesting = None;
+    let mut current_name = ParentScope::None;
+    let mut names_to_untrack = Vec::new();
+
+    for entry in nesting {
+        for part in entry.split("::").map(String::from) {
+            if part.is_empty() {
+                current_name = ParentScope::TopLevel;
+                continue;
+            }
+
+            let str_id = graph.intern_string(part);
+            let name_id = graph.add_name(Name::new(str_id, current_name, current_nesting));
+            names_to_untrack.push(name_id);
+            current_name = ParentScope::Some(name_id);
+        }
+
+        current_nesting = current_name.map_or(None, |id| Some(*id));
+        current_name = ParentScope::None;
+    }
+
+    for part in const_name.split("::").map(String::from) {
+        if part.is_empty() {
+            current_name = ParentScope::TopLevel;
+            continue;
+        }
+
+        let str_id = graph.intern_string(part);
+        let name_id = graph.add_name(Name::new(str_id, current_name, current_nesting));
+        names_to_untrack.push(name_id);
+        current_name = ParentScope::Some(name_id);
+    }
+
+    (
+        current_name.expect("The NameId cannot be None since it contains at least `const_name`"),
+        names_to_untrack,
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use rubydex::model::ids::StringId;
+
+    use super::*;
+
+    #[test]
+    fn nesting_is_converted_to_name_id() {
+        let mut graph = Graph::new();
+
+        let (name_id, _) = nesting_stack_to_name_id(
+            &mut graph,
+            "Some::CONST",
+            vec!["Foo".into(), "Bar::Zip".into(), "Qux".into()],
+        );
+
+        let const_name = graph.names().get(&name_id).unwrap();
+        assert_eq!(StringId::from("CONST"), *const_name.str());
+
+        let some_name = graph
+            .names()
+            .get(&const_name.parent_scope().expect("Parent scope should exist"))
+            .unwrap();
+        assert_eq!(StringId::from("Some"), *some_name.str());
+        assert_eq!(const_name.nesting(), some_name.nesting());
+
+        let qux_name = graph.names().get(&some_name.nesting().unwrap()).unwrap();
+        assert_eq!(StringId::from("Qux"), *qux_name.str());
+        assert!(qux_name.parent_scope().is_none());
+
+        let zip_name = graph.names().get(&qux_name.nesting().unwrap()).unwrap();
+        assert_eq!(StringId::from("Zip"), *zip_name.str());
+
+        let bar_name = graph
+            .names()
+            .get(&zip_name.parent_scope().expect("Parent scope should exist"))
+            .unwrap();
+        assert_eq!(StringId::from("Bar"), *bar_name.str());
+        assert_eq!(zip_name.nesting(), bar_name.nesting());
+
+        let foo_name = graph.names().get(&bar_name.nesting().unwrap()).unwrap();
+        assert_eq!(StringId::from("Foo"), *foo_name.str());
+        assert!(foo_name.parent_scope().is_none());
+        assert!(foo_name.nesting().is_none());
+    }
+
+    #[test]
+    fn top_level_reference_is_converted_to_name_id() {
+        let mut graph = Graph::new();
+
+        let (name_id, _) = nesting_stack_to_name_id(&mut graph, "::CONST", vec!["Foo".into()]);
+
+        let const_name = graph.names().get(&name_id).unwrap();
+        assert_eq!(StringId::from("CONST"), *const_name.str());
+        assert!(const_name.parent_scope().is_top_level());
+
+        let foo_name = graph.names().get(&const_name.nesting().unwrap()).unwrap();
+        assert_eq!(StringId::from("Foo"), *foo_name.str());
+        assert!(foo_name.nesting().is_none());
+        assert!(foo_name.parent_scope().is_none());
+    }
+
+    #[test]
+    fn top_level_nesting_is_converted_to_name_id() {
+        let mut graph = Graph::new();
+
+        let (name_id, _) = nesting_stack_to_name_id(&mut graph, "CONST", vec!["Foo".into(), "::Bar".into()]);
+
+        let const_name = graph.names().get(&name_id).unwrap();
+        assert_eq!(StringId::from("CONST"), *const_name.str());
+        assert!(const_name.parent_scope().is_none());
+
+        let bar_name = graph.names().get(&const_name.nesting().unwrap()).unwrap();
+        assert_eq!(StringId::from("Bar"), *bar_name.str());
+        assert!(bar_name.parent_scope().is_top_level());
+
+        let foo_name = graph.names().get(&bar_name.nesting().unwrap()).unwrap();
+        assert_eq!(StringId::from("Foo"), *foo_name.str());
+        assert!(foo_name.parent_scope().is_none());
+        assert!(foo_name.nesting().is_none());
+    }
+}

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

@@ -0,0 +1,267 @@
+//! C API for exposing references through ID handles (like definitions)
+
+use std::ffi::CString;
+use std::ptr;
+
+use crate::declaration_api::CDeclaration;
+use crate::graph_api::{GraphPointer, with_graph};
+use crate::location_api::{Location, create_location_for_uri_and_offset};
+use libc::c_char;
+use rubydex::model::graph::Graph;
+use rubydex::model::ids::{ConstantReferenceId, MethodReferenceId};
+use rubydex::model::name::NameRef;
+
+#[repr(C)]
+#[derive(Debug, Clone, Copy)]
+pub struct CConstantReference {
+    pub id: u64,
+    pub declaration_id: u64,
+}
+
+impl CConstantReference {
+    /// Build a `CConstantReference` from a graph and reference ID. Sets `declaration_id` to 0 when the reference is
+    /// unresolved.
+    ///
+    /// # Panics
+    ///
+    /// This function will panic if there's inconsistent data in the graph
+    #[must_use]
+    pub fn from_id(graph: &Graph, ref_id: ConstantReferenceId) -> Self {
+        let reference = graph
+            .constant_references()
+            .get(&ref_id)
+            .expect("Constant reference not found");
+
+        let name_ref = graph.names().get(reference.name_id()).expect("Name ID should exist");
+
+        let declaration_id = match name_ref {
+            NameRef::Resolved(resolved) => **resolved.declaration_id(),
+            NameRef::Unresolved(_) => 0,
+        };
+
+        Self {
+            id: *ref_id,
+            declaration_id,
+        }
+    }
+}
+
+#[derive(Debug)]
+pub struct ConstantReferencesIter {
+    entries: Box<[CConstantReference]>,
+    index: usize,
+}
+
+iterator!(ConstantReferencesIter, entries: CConstantReference);
+
+/// # Safety
+/// `iter` must be a valid pointer previously returned by `ConstantReferencesIter::new`.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_constant_references_iter_len(iter: *const ConstantReferencesIter) -> usize {
+    unsafe { ConstantReferencesIter::len(iter) }
+}
+
+/// # Safety
+/// - `iter` must be a valid pointer previously returned by `ConstantReferencesIter::new`.
+/// - `out` must be a valid, writable pointer.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_constant_references_iter_next(
+    iter: *mut ConstantReferencesIter,
+    out: *mut CConstantReference,
+) -> bool {
+    unsafe { ConstantReferencesIter::next(iter, out) }
+}
+
+/// # Safety
+/// - `iter` must be a pointer previously returned by `ConstantReferencesIter::new`.
+/// - `iter` must not be used after being freed.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_constant_references_iter_free(iter: *mut ConstantReferencesIter) {
+    unsafe { ConstantReferencesIter::free(iter) }
+}
+
+#[repr(C)]
+#[derive(Debug, Clone, Copy)]
+pub struct CMethodReference {
+    pub id: u64,
+}
+
+#[derive(Debug)]
+pub struct MethodReferencesIter {
+    entries: Box<[CMethodReference]>,
+    index: usize,
+}
+
+iterator!(MethodReferencesIter, entries: CMethodReference);
+
+/// # Safety
+/// `iter` must be a valid pointer previously returned by `MethodReferencesIter::new`.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_method_references_iter_len(iter: *const MethodReferencesIter) -> usize {
+    unsafe { MethodReferencesIter::len(iter) }
+}
+
+/// # Safety
+/// - `iter` must be a valid pointer previously returned by `MethodReferencesIter::new`.
+/// - `out` must be a valid, writable pointer.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_method_references_iter_next(
+    iter: *mut MethodReferencesIter,
+    out: *mut CMethodReference,
+) -> bool {
+    unsafe { MethodReferencesIter::next(iter, out) }
+}
+
+/// # Safety
+/// - `iter` must be a pointer previously returned by `MethodReferencesIter::new`.
+/// - `iter` must not be used after being freed.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_method_references_iter_free(iter: *mut MethodReferencesIter) {
+    unsafe { MethodReferencesIter::free(iter) }
+}
+
+/// Returns the UTF-8 name string for a constant reference id.
+/// Caller must free with `free_c_string`.
+///
+/// # Safety
+///
+/// Assumes pointer is valid.
+///
+/// # Panics
+///
+/// This function will panic if the reference 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 name = graph.names().get(reference.name_id()).expect("Name ID should exist");
+
+        let name_string = graph
+            .strings()
+            .get(name.str())
+            .expect("String ID should exist")
+            .to_string();
+        CString::new(name_string).unwrap().into_raw().cast_const()
+    })
+}
+
+/// Returns the UTF-8 name string for a method reference id.
+/// Caller must free with `free_c_string`.
+///
+/// # Safety
+///
+/// Assumes pointer is valid.
+///
+/// # Panics
+///
+/// This function will panic if the reference 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 name = graph
+            .strings()
+            .get(reference.str())
+            .expect("Name ID should exist")
+            .to_string();
+        CString::new(name).unwrap().into_raw().cast_const()
+    })
+}
+
+/// Returns a newly allocated `Location` for the given constant reference id.
+/// Caller must free the returned pointer with `rdx_location_free`.
+///
+/// # Safety
+///
+/// - `pointer` must be a valid pointer previously returned by `rdx_graph_new`.
+/// - `reference_id` must be a valid reference id.
+///
+/// # Panics
+///
+/// This function will panic if a reference or 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 document = graph
+            .documents()
+            .get(&reference.uri_id())
+            .expect("Document should exist");
+
+        create_location_for_uri_and_offset(graph, document, reference.offset())
+    })
+}
+
+/// Returns the declaration that the given resolved constant reference points to. Returns NULL if the reference is
+/// unresolved. Caller must free with `free_c_declaration`.
+///
+/// # Safety
+///
+/// Assumes pointer is valid.
+///
+/// # Panics
+///
+/// This function will panic if the reference cannot be found.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_resolved_constant_reference_declaration(
+    pointer: GraphPointer,
+    reference_id: u64,
+) -> *const CDeclaration {
+    with_graph(pointer, |graph| {
+        let ref_id = ConstantReferenceId::new(reference_id);
+        let reference = graph.constant_references().get(&ref_id).expect("Reference not found");
+        let name_ref = graph.names().get(reference.name_id()).expect("Name ID should exist");
+
+        match name_ref {
+            NameRef::Resolved(resolved) => {
+                let decl_id = *resolved.declaration_id();
+                let decl = graph.declarations().get(&decl_id).expect("Declaration not found");
+                Box::into_raw(Box::new(CDeclaration::from_declaration(decl_id, decl))).cast_const()
+            }
+            NameRef::Unresolved(_) => ptr::null(),
+        }
+    })
+}
+
+/// Returns a newly allocated `Location` for the given method reference id.
+/// Caller must free the returned pointer with `rdx_location_free`.
+///
+/// # Safety
+///
+/// - `pointer` must be a valid pointer previously returned by `rdx_graph_new`.
+/// - `reference_id` must be a valid reference id.
+///
+/// # Panics
+///
+/// This function will panic if a reference or 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 document = graph
+            .documents()
+            .get(&reference.uri_id())
+            .expect("Document should exist");
+
+        create_location_for_uri_and_offset(graph, document, reference.offset())
+    })
+}
+
+/// Frees a `CConstantReference` previously returned by an FFI function.
+///
+/// # Safety
+/// - `ptr` must be a valid pointer previously returned by an FFI function that allocates a `CConstantReference`, or
+///   NULL.
+/// - `ptr` must not be used after being freed.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn free_c_constant_reference(ptr: *const CConstantReference) {
+    if !ptr.is_null() {
+        unsafe {
+            let _ = Box::from_raw(ptr.cast_mut());
+        }
+    }
+}

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

@@ -0,0 +1,70 @@
+use libc::{c_char, size_t};
+use std::ffi::{CStr, CString};
+use std::slice;
+use std::str::Utf8Error;
+
+/// Converts a C array of strings into a Vec<String>
+///
+/// # Safety
+///
+/// This function is unsafe because it attempts to instantiate a Vec<String> from a raw char** pointer
+///
+/// # Errors
+///
+/// This function errors if any of the strings inside the array contain invalid UTF-8 data
+pub unsafe fn convert_double_pointer_to_vec(data: *const *const c_char, len: size_t) -> Result<Vec<String>, Utf8Error> {
+    unsafe {
+        slice::from_raw_parts(data, len)
+            .iter()
+            .map(|arg| CStr::from_ptr(*arg).to_str().map(ToString::to_string))
+            .collect()
+    }
+}
+
+/// # Safety
+///
+/// This function is unsafe because it dereferences the char pointer, which needs to be valid for the duration of the
+/// function
+///
+/// # Errors
+///
+/// This function errors if any of the strings inside the array contain invalid UTF-8 data
+pub unsafe fn convert_char_ptr_to_string(data: *const c_char) -> Result<String, Utf8Error> {
+    unsafe { CStr::from_ptr(data).to_str().map(ToString::to_string) }
+}
+
+/// Frees a `CString` allocated on the Rust side
+#[unsafe(no_mangle)]
+pub extern "C" fn free_c_string(ptr: *const c_char) {
+    unsafe {
+        let _ = CString::from_raw(ptr.cast_mut());
+    }
+}
+
+/// Frees a boxed u64 allocated on the Rust side
+#[unsafe(no_mangle)]
+pub extern "C" fn free_u64(ptr: *const u64) {
+    unsafe {
+        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();
+}

data/rust/rustfmt.toml

@@ -0,0 +1,2 @@
+max_width = 120
+edition = "2024"