rubydex 0.1.0.beta1-x86_64-linux → 0.1.0.beta2-x86_64-linux

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

@@ -0,0 +1,114 @@
+//! This file provides the C API for the Graph object
+
+use libc::c_char;
+use rubydex::model::declaration::Declaration;
+use std::ffi::CString;
+use std::ptr;
+
+use crate::definition_api::{DefinitionKind, DefinitionsIter, rdx_definitions_iter_new_from_ids};
+use crate::graph_api::{GraphPointer, with_graph};
+use crate::utils;
+use rubydex::model::ids::{DeclarationId, StringId};
+
+/// Returns the UTF-8 name string for a declaration id.
+/// Caller must free with `free_c_string`.
+///
+/// # Safety
+///
+/// Assumes pointer is valid.
+///
+/// # Panics
+///
+/// This function will panic if the name pointer is invalid.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_declaration_name(pointer: GraphPointer, name_id: i64) -> *const c_char {
+    with_graph(pointer, |graph| {
+        let name_id = DeclarationId::new(name_id);
+        if let Some(decl) = graph.declarations().get(&name_id) {
+            CString::new(decl.name()).unwrap().into_raw().cast_const()
+        } else {
+            ptr::null()
+        }
+    })
+}
+
+/// Returns the declaration ID for a member from a declaration.
+/// Returns NULL if the member is not found.
+///
+/// # Safety
+/// - `member` must be a valid, null-terminated UTF-8 string
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_declaration_member(
+    pointer: GraphPointer,
+    name_id: i64,
+    member: *const c_char,
+) -> *const i64 {
+    let Ok(member_str) = (unsafe { utils::convert_char_ptr_to_string(member) }) else {
+        return ptr::null();
+    };
+
+    with_graph(pointer, |graph| {
+        let name_id = DeclarationId::new(name_id);
+        if let Some(Declaration::Namespace(decl)) = graph.declarations().get(&name_id) {
+            let member_id = StringId::from(member_str.as_str());
+
+            if let Some(member_decl_id) = decl.member(&member_id) {
+                return Box::into_raw(Box::new(**member_decl_id)).cast_const();
+            }
+        }
+
+        ptr::null()
+    })
+}
+
+/// Returns the UTF-8 unqualified name string for a declaration id.
+/// Caller must free with `free_c_string`.
+///
+/// # Safety
+///
+/// Assumes pointer is valid.
+///
+/// # Panics
+///
+/// This function will panic if the name pointer is invalid.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_declaration_unqualified_name(pointer: GraphPointer, name_id: i64) -> *const c_char {
+    with_graph(pointer, |graph| {
+        let name_id = DeclarationId::new(name_id);
+        if let Some(decl) = graph.declarations().get(&name_id) {
+            CString::new(decl.unqualified_name()).unwrap().into_raw().cast_const()
+        } else {
+            ptr::null()
+        }
+    })
+}
+
+/// An iterator over definition IDs and kinds for a given declaration
+///
+/// We snapshot the IDs at iterator creation so if the graph is modified, the iterator will not see the changes
+// Use shared DefinitionsIter directly in signatures
+/// Creates a new iterator over definition IDs for a given declaration by snapshotting the current set of IDs.
+///
+/// # Safety
+///
+/// - `pointer` must be a valid `GraphPointer` previously returned by this crate.
+/// - The returned pointer must be freed with `rdx_declaration_definitions_iter_free`.
+///
+/// # Panics
+///
+/// This function will panic if acquiring a read lock fails
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_declaration_definitions_iter_new(
+    pointer: GraphPointer,
+    decl_id: i64,
+) -> *mut DefinitionsIter {
+    // Snapshot the IDs and kinds at iterator creation to avoid borrowing across FFI calls
+    with_graph(pointer, |graph| {
+        let decl_id = DeclarationId::new(decl_id);
+        if let Some(decl) = graph.declarations().get(&decl_id) {
+            rdx_definitions_iter_new_from_ids(graph, decl.definitions())
+        } else {
+            DefinitionsIter::new(Vec::<(i64, DefinitionKind)>::new().into_boxed_slice())
+        }
+    })
+}

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

@@ -0,0 +1,350 @@
+//! This file provides the C API for Definition accessors
+
+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::definitions::Definition;
+use rubydex::model::ids::DefinitionId;
+use std::ffi::CString;
+use std::ptr;
+
+/// C-compatible enum representing the kind of a definition.
+#[repr(C)]
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+pub enum DefinitionKind {
+    Class = 0,
+    SingletonClass = 1,
+    Module = 2,
+    Constant = 3,
+    ConstantAlias = 4,
+    Method = 5,
+    AttrAccessor = 6,
+    AttrReader = 7,
+    AttrWriter = 8,
+    GlobalVariable = 9,
+    InstanceVariable = 10,
+    ClassVariable = 11,
+    MethodAlias = 12,
+    GlobalVariableAlias = 13,
+}
+
+pub(crate) fn map_definition_to_kind(defn: &Definition) -> DefinitionKind {
+    match defn {
+        Definition::Class(_) => DefinitionKind::Class,
+        Definition::SingletonClass(_) => DefinitionKind::SingletonClass,
+        Definition::Module(_) => DefinitionKind::Module,
+        Definition::Constant(_) => DefinitionKind::Constant,
+        Definition::ConstantAlias(_) => DefinitionKind::ConstantAlias,
+        Definition::Method(_) => DefinitionKind::Method,
+        Definition::AttrAccessor(_) => DefinitionKind::AttrAccessor,
+        Definition::AttrReader(_) => DefinitionKind::AttrReader,
+        Definition::AttrWriter(_) => DefinitionKind::AttrWriter,
+        Definition::GlobalVariable(_) => DefinitionKind::GlobalVariable,
+        Definition::InstanceVariable(_) => DefinitionKind::InstanceVariable,
+        Definition::ClassVariable(_) => DefinitionKind::ClassVariable,
+        Definition::MethodAlias(_) => DefinitionKind::MethodAlias,
+        Definition::GlobalVariableAlias(_) => DefinitionKind::GlobalVariableAlias,
+    }
+}
+
+/// Returns the enum kind for a definition id (e.g. Class, Module).
+///
+/// # Safety
+///
+/// Assumes pointer is valid.
+///
+/// # Panics
+///
+/// This function will panic if the definition cannot be found.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_definition_kind(pointer: GraphPointer, definition_id: i64) -> DefinitionKind {
+    with_graph(pointer, |graph| {
+        let definition_id = DefinitionId::new(definition_id);
+        if let Some(defn) = graph.definitions().get(&definition_id) {
+            map_definition_to_kind(defn)
+        } else {
+            panic!("Definition not found: {definition_id:?}");
+        }
+    })
+}
+
+/// Returns the UTF-8 unqualified name string for a definition id.
+/// Caller must free with `free_c_string`.
+///
+/// # Safety
+///
+/// Assumes pointer is valid.
+///
+/// # Panics
+///
+/// This function will panic if the definition cannot be found.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_definition_name(pointer: GraphPointer, definition_id: i64) -> *const c_char {
+    with_graph(pointer, |graph| {
+        let def_id = DefinitionId::new(definition_id);
+        if let Some(defn) = graph.definitions().get(&def_id) {
+            let string_id = graph.definition_string_id(defn);
+
+            if let Some(name) = graph.strings().get(&string_id) {
+                CString::new(name.as_str()).unwrap().into_raw().cast_const()
+            } else {
+                ptr::null()
+            }
+        } else {
+            ptr::null()
+        }
+    })
+}
+
+/// Shared iterator over definition (id, kind) pairs
+#[derive(Debug)]
+pub struct DefinitionsIter {
+    pub entries: Box<[(i64, DefinitionKind)]>,
+    pub index: usize,
+}
+
+impl DefinitionsIter {
+    #[must_use]
+    pub fn new(entries: Box<[(i64, DefinitionKind)]>) -> *mut DefinitionsIter {
+        Box::into_raw(Box::new(DefinitionsIter { entries, index: 0 }))
+    }
+}
+
+/// Returns the total number of entries in the iterator snapshot.
+///
+/// # Safety
+/// - `iter` must be a valid pointer previously returned by `DefinitionsIter::new`.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_definitions_iter_len(iter: *const DefinitionsIter) -> usize {
+    if iter.is_null() {
+        return 0;
+    }
+    unsafe { (&*iter).entries.len() }
+}
+
+/// Advances the iterator and writes the next (ID, Kind) into `out_id` and `out_kind`.
+/// Returns `true` if a pair was written, or `false` if the iterator is exhausted or inputs are invalid.
+///
+/// # Safety
+/// - `iter` must be a valid pointer previously returned by `DefinitionsIter::new`.
+/// - `out_id` and `out_kind` must be valid, writable pointers.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_definitions_iter_next(
+    iter: *mut DefinitionsIter,
+    out_id: *mut i64,
+    out_kind: *mut DefinitionKind,
+) -> bool {
+    if iter.is_null() || out_id.is_null() || out_kind.is_null() {
+        return false;
+    }
+
+    let it = unsafe { &mut *iter };
+    if it.index >= it.entries.len() {
+        return false;
+    }
+
+    let (id, kind) = it.entries[it.index];
+    it.index += 1;
+    unsafe {
+        *out_id = id;
+        *out_kind = kind;
+    }
+    true
+}
+
+/// Frees an iterator created by `DefinitionsIter::new`.
+///
+/// # Safety
+/// - `iter` must be a pointer previously returned by `DefinitionsIter::new`.
+/// - `iter` must not be used after being freed.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_definitions_iter_free(iter: *mut DefinitionsIter) {
+    if iter.is_null() {
+        return;
+    }
+    unsafe {
+        let _ = Box::from_raw(iter);
+    }
+}
+
+/// C-compatible struct representing a single comment with its string and location
+#[repr(C)]
+pub struct CommentEntry {
+    pub string: *const c_char,
+    pub location: *mut Location,
+}
+
+/// C-compatible array of comments
+#[repr(C)]
+pub struct CommentArray {
+    pub items: *mut CommentEntry,
+    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.
+///
+/// # 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.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_definition_comments(pointer: GraphPointer, definition_id: i64) -> *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:?}");
+        };
+
+        let uri_id = *defn.uri_id();
+        let document = graph.documents().get(&uri_id).expect("document should exist");
+
+        let mut entries = defn
+            .comments()
+            .iter()
+            .map(|c| CommentEntry {
+                string: CString::new(c.string().as_str()).unwrap().into_raw().cast_const(),
+                location: create_location_for_uri_and_offset(graph, document, c.offset()),
+            })
+            .collect::<Vec<CommentEntry>>()
+            .into_boxed_slice();
+
+        let len = entries.len();
+        let items_ptr = entries.as_mut_ptr();
+        std::mem::forget(entries);
+
+        Box::into_raw(Box::new(CommentArray { items: items_ptr, len }))
+    })
+}
+
+/// Frees a `CommentArray` previously returned by `rdx_definition_comments`.
+///
+/// # Safety
+/// - `ptr` must be a valid pointer previously returned by `rdx_definition_comments`.
+/// - `ptr` must not be used after being freed.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_definition_comments_free(ptr: *mut CommentArray) {
+    if ptr.is_null() {
+        return;
+    }
+
+    // Take ownership of the CommentArray
+    let arr = unsafe { Box::from_raw(ptr) };
+
+    if !arr.items.is_null() && arr.len > 0 {
+        // Reconstruct the boxed slice so we can drop it after freeing inner allocations
+        let slice_ptr = ptr::slice_from_raw_parts_mut(arr.items, arr.len);
+        let mut boxed_slice: Box<[CommentEntry]> = unsafe { Box::from_raw(slice_ptr) };
+
+        for item in &mut boxed_slice {
+            if !item.string.is_null() {
+                // Free the CString allocated for the comment string
+                let _ = unsafe { CString::from_raw(item.string.cast_mut()) };
+            }
+            if !item.location.is_null() {
+                unsafe { crate::location_api::rdx_location_free(item.location) };
+                item.location = ptr::null_mut();
+            }
+        }
+
+        // boxed_slice is dropped here, freeing the items buffer
+    }
+    // arr is dropped here
+}
+
+/// Returns a newly allocated `Location` for the given definition id.
+/// Caller must free the returned pointer with `rdx_location_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.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_definition_location(pointer: GraphPointer, definition_id: i64) -> *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:?}");
+        };
+
+        let document = graph.documents().get(defn.uri_id()).expect("document should exist");
+        create_location_for_uri_and_offset(graph, document, defn.offset())
+    })
+}
+
+/// Creates a new iterator over definition IDs for a given declaration by snapshotting the current set of IDs.
+///
+/// # Panics
+///
+/// This function will panic if a definition cannot be found.
+pub(crate) fn rdx_definitions_iter_new_from_ids<'a, I>(
+    graph: &rubydex::model::graph::Graph,
+    ids: I,
+) -> *mut DefinitionsIter
+where
+    I: IntoIterator<Item = &'a DefinitionId>,
+{
+    let entries = ids
+        .into_iter()
+        .map(|def_id| {
+            let id = **def_id;
+            let kind = graph
+                .definitions()
+                .get(&DefinitionId::new(id))
+                .map_or_else(|| panic!("Definition not found: {id:?}"), map_definition_to_kind);
+            (id, kind)
+        })
+        .collect::<Vec<(i64, DefinitionKind)>>()
+        .into_boxed_slice();
+
+    DefinitionsIter::new(entries)
+}
+
+/// Returns true if the definition is deprecated.
+///
+/// # 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 cannot be found.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_definition_is_deprecated(pointer: GraphPointer, definition_id: i64) -> bool {
+    with_graph(pointer, |graph| {
+        let def_id = DefinitionId::new(definition_id);
+        let defn = graph.definitions().get(&def_id).expect("definition not found");
+        defn.is_deprecated()
+    })
+}
+
+/// Returns a newly allocated `Location` for the name portion of a definition id.
+/// For class, module, and singleton class definitions, this returns the location of just
+/// the name (e.g., "Bar" in `class Foo::Bar`).
+/// For other definition types, returns NULL.
+/// Caller must free the returned pointer with `rdx_location_free`.
+///
+/// # Safety
+/// - `pointer` must be a valid pointer previously returned by `rdx_graph_new`.
+/// - `definition_id` must be a valid definition id.
+///
+/// # Panics
+/// Panics if the definition's document does not exist in the graph.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_definition_name_location(pointer: GraphPointer, definition_id: i64) -> *mut Location {
+    with_graph(pointer, |graph| {
+        let def_id = DefinitionId::new(definition_id);
+        let Some(defn) = graph.definitions().get(&def_id) else {
+            return ptr::null_mut();
+        };
+        let Some(name_offset) = defn.name_offset() else {
+            return ptr::null_mut();
+        };
+        let document = graph.documents().get(defn.uri_id()).expect("document should exist");
+        create_location_for_uri_and_offset(graph, document, name_offset)
+    })
+}

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

@@ -0,0 +1,99 @@
+//! Diagnostics-related FFI helpers
+
+use crate::graph_api::{GraphPointer, with_graph};
+use crate::location_api::{Location, create_location_for_uri_and_offset};
+use libc::c_char;
+use std::{ffi::CString, mem, ptr};
+
+/// C-compatible struct representing a diagnostic entry.
+#[repr(C)]
+pub struct DiagnosticEntry {
+    pub rule: *const c_char,
+    pub message: *const c_char,
+    pub location: *mut Location,
+}
+
+/// C-compatible array wrapper for diagnostics.
+#[repr(C)]
+pub struct DiagnosticArray {
+    pub items: *mut DiagnosticEntry,
+    pub len: usize,
+}
+
+impl DiagnosticArray {
+    fn from_vec(mut entries: Vec<DiagnosticEntry>) -> *mut DiagnosticArray {
+        let len = entries.len();
+        let ptr = entries.as_mut_ptr();
+        mem::forget(entries);
+        Box::into_raw(Box::new(DiagnosticArray { items: ptr, len }))
+    }
+}
+
+/// Returns all diagnostics currently recorded in the global graph.
+///
+/// # Safety
+///
+/// - `pointer` must be a valid `GraphPointer` previously returned by this crate.
+/// - The pointed graph must remain alive for the duration of the call.
+///
+/// # Panics
+///
+/// - If a diagnostic references a URI whose file cannot be read to build a location.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_graph_diagnostics(pointer: GraphPointer) -> *mut DiagnosticArray {
+    with_graph(pointer, |graph| {
+        let entries = graph
+            .all_diagnostics()
+            .iter()
+            .map(|diagnostic| {
+                let document = graph.documents().get(diagnostic.uri_id()).unwrap();
+                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(),
+                    message: CString::new(diagnostic.message()).unwrap().into_raw().cast_const(),
+                    location,
+                }
+            })
+            .collect::<Vec<DiagnosticEntry>>();
+
+        DiagnosticArray::from_vec(entries)
+    })
+}
+
+/// Frees a diagnostic array previously returned by `rdx_graph_diagnostics`.
+///
+/// # Safety
+///
+/// - `ptr` must be a valid pointer previously returned by `rdx_graph_diagnostics`.
+/// - `ptr` must not be used after being freed.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_diagnostics_free(ptr: *mut DiagnosticArray) {
+    if ptr.is_null() {
+        return;
+    }
+
+    let array = unsafe { Box::from_raw(ptr) };
+    if !array.items.is_null() && array.len > 0 {
+        let slice_ptr = ptr::slice_from_raw_parts_mut(array.items, array.len);
+        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()) };
+            }
+            if !entry.location.is_null() {
+                unsafe { crate::location_api::rdx_location_free(entry.location) };
+                entry.location = ptr::null_mut();
+            }
+        }
+        // boxed_slice drops here, releasing the buffer
+    }
+    // array drops here
+}

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

@@ -0,0 +1,54 @@
+//! This file provides the C API for Document accessors
+
+use libc::c_char;
+use std::ffi::CString;
+use std::ptr;
+
+use crate::definition_api::{DefinitionKind, DefinitionsIter, rdx_definitions_iter_new_from_ids};
+use crate::graph_api::{GraphPointer, with_graph};
+use rubydex::model::ids::UriId;
+
+/// Returns the UTF-8 URI string for a document id.
+/// Caller must free with `free_c_string`.
+///
+/// # Safety
+///
+/// Assumes pointer is valid.
+///
+/// # Panics
+///
+/// This function will panic if the URI pointer is invalid.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_document_uri(pointer: GraphPointer, uri_id: i64) -> *const c_char {
+    with_graph(pointer, |graph| {
+        let uri_id = UriId::new(uri_id);
+        if let Some(doc) = graph.documents().get(&uri_id) {
+            CString::new(doc.uri()).unwrap().into_raw().cast_const()
+        } else {
+            ptr::null()
+        }
+    })
+}
+
+/// An iterator over definition IDs and kinds for a given document (URI)
+///
+/// We snapshot the IDs at iterator creation so if the graph is modified, the iterator will not see the changes
+// Use shared DefinitionsIter directly in signatures
+/// Creates a new iterator over definition IDs for a given document by snapshotting the current set of IDs.
+///
+/// # Safety
+///
+/// - `pointer` must be a valid `GraphPointer` previously returned by this crate.
+/// - The returned pointer must be freed with `rdx_document_definitions_iter_free`.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_document_definitions_iter_new(pointer: GraphPointer, uri_id: i64) -> *mut DefinitionsIter {
+    // Snapshot the IDs and kinds at iterator creation to avoid borrowing across FFI calls
+    with_graph(pointer, |graph| {
+        let uri_id = UriId::new(uri_id);
+        if let Some(doc) = graph.documents().get(&uri_id) {
+            rdx_definitions_iter_new_from_ids(graph, doc.definitions())
+        } else {
+            DefinitionsIter::new(Vec::<(i64, DefinitionKind)>::new().into_boxed_slice())
+        }
+    })
+}