rubydex 0.1.0.beta12-aarch64-linux

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

@@ -0,0 +1,443 @@
+//! 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 crate::reference_api::CConstantReference;
+use libc::c_char;
+use rubydex::model::definitions::{Definition, Mixin};
+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,
+    ConstantVisibility = 5,
+    MethodVisibility = 6,
+    Method = 7,
+    AttrAccessor = 8,
+    AttrReader = 9,
+    AttrWriter = 10,
+    GlobalVariable = 11,
+    InstanceVariable = 12,
+    ClassVariable = 13,
+    MethodAlias = 14,
+    GlobalVariableAlias = 15,
+}
+
+#[repr(C)]
+#[derive(Debug, Clone, Copy)]
+pub struct CDefinition {
+    pub id: u64,
+    pub kind: DefinitionKind,
+}
+
+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::ConstantVisibility(_) => DefinitionKind::ConstantVisibility,
+        Definition::MethodVisibility(_) => DefinitionKind::MethodVisibility,
+        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: u64) -> 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: u64) -> *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 {
+    entries: Box<[CDefinition]>,
+    index: usize,
+}
+
+iterator!(DefinitionsIter, entries: CDefinition);
+
+/// # 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 {
+    unsafe { DefinitionsIter::len(iter) }
+}
+
+/// # Safety
+/// - `iter` must be a valid pointer previously returned by `DefinitionsIter::new`.
+/// - `out` must be a valid, writable pointer.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_definitions_iter_next(iter: *mut DefinitionsIter, out: *mut CDefinition) -> bool {
+    unsafe { DefinitionsIter::next(iter, out) }
+}
+
+/// # 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) {
+    unsafe { DefinitionsIter::free(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: 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:?}");
+        };
+
+        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: 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:?}");
+        };
+
+        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);
+            CDefinition { id, kind }
+        })
+        .collect::<Vec<_>>()
+        .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: u64) -> 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: u64) -> *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)
+    })
+}
+
+/// Returns the superclass constant reference for a class definition, or NULL if the class has no superclass. Caller
+/// must free with `free_c_constant_reference`.
+///
+/// # Safety
+/// - `pointer` must be a valid pointer previously returned by `rdx_graph_new`.
+/// - `definition_id` must be a valid definition id for a class definition.
+///
+/// # Panics
+/// This function will panic if the definition cannot be found or is not a class definition.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_class_definition_superclass(
+    pointer: GraphPointer,
+    definition_id: u64,
+) -> *const CConstantReference {
+    with_graph(pointer, |graph| {
+        let def_id = DefinitionId::new(definition_id);
+        let defn = graph.definitions().get(&def_id).expect("Definition not found");
+
+        let Definition::Class(class_def) = defn else {
+            panic!("Definition is not a class: {definition_id}");
+        };
+
+        let Some(ref_id) = class_def.superclass_ref() else {
+            return ptr::null();
+        };
+
+        Box::into_raw(Box::new(CConstantReference::from_id(graph, *ref_id))).cast_const()
+    })
+}
+
+/// C-compatible enum representing the kind of a mixin.
+#[repr(C)]
+#[derive(Debug, Clone, Copy)]
+pub enum MixinKind {
+    Include = 0,
+    Prepend = 1,
+    Extend = 2,
+}
+
+/// C-compatible struct representing a mixin (kind + constant reference).
+#[repr(C)]
+#[derive(Debug, Clone, Copy)]
+pub struct CMixin {
+    pub kind: MixinKind,
+    pub constant_reference: CConstantReference,
+}
+
+#[derive(Debug)]
+pub struct MixinsIter {
+    entries: Box<[CMixin]>,
+    index: usize,
+}
+
+iterator!(MixinsIter, entries: CMixin);
+
+/// # Safety
+/// `iter` must be a valid pointer previously returned by `rdx_definition_mixins`.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_mixins_iter_len(iter: *const MixinsIter) -> usize {
+    unsafe { MixinsIter::len(iter) }
+}
+
+/// # Safety
+/// - `iter` must be a valid pointer previously returned by `rdx_definition_mixins`.
+/// - `out` must be a valid, writable pointer.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_mixins_iter_next(iter: *mut MixinsIter, out: *mut CMixin) -> bool {
+    unsafe { MixinsIter::next(iter, out) }
+}
+
+/// # Safety
+/// - `iter` must be a pointer previously returned by `rdx_definition_mixins`.
+/// - `iter` must not be used after being freed.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_mixins_iter_free(iter: *mut MixinsIter) {
+    unsafe { MixinsIter::free(iter) }
+}
+
+fn map_mixin_kind(mixin: &Mixin) -> MixinKind {
+    match mixin {
+        Mixin::Include(_) => MixinKind::Include,
+        Mixin::Prepend(_) => MixinKind::Prepend,
+        Mixin::Extend(_) => MixinKind::Extend,
+    }
+}
+
+/// Returns an iterator over the mixins for a definition (class, module, or singleton class).
+/// Returns NULL for definition types that do not support mixins.
+///
+/// # 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 the definition cannot be found.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_definition_mixins(pointer: GraphPointer, definition_id: u64) -> *mut MixinsIter {
+    with_graph(pointer, |graph| {
+        let def_id = DefinitionId::new(definition_id);
+        let defn = graph.definitions().get(&def_id).expect("Definition not found");
+
+        let mixins = match defn {
+            Definition::Class(class_def) => class_def.mixins(),
+            Definition::Module(mod_def) => mod_def.mixins(),
+            Definition::SingletonClass(singleton_def) => singleton_def.mixins(),
+            _ => return ptr::null_mut(),
+        };
+
+        let entries: Vec<CMixin> = mixins
+            .iter()
+            .map(|mixin| CMixin {
+                kind: map_mixin_kind(mixin),
+                constant_reference: CConstantReference::from_id(graph, *mixin.constant_reference_id()),
+            })
+            .collect();
+
+        MixinsIter::new(entries.into_boxed_slice())
+    })
+}

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,85 @@
+//! This file provides the C API for Document accessors
+
+use libc::c_char;
+use std::ffi::CString;
+use std::ptr;
+
+use crate::definition_api::{DefinitionsIter, rdx_definitions_iter_new_from_ids};
+use crate::graph_api::{GraphPointer, with_graph};
+use rubydex::model::ids::UriId;
+
+#[derive(Debug)]
+pub struct DocumentsIter {
+    entries: Box<[u64]>,
+    index: usize,
+}
+
+iterator!(DocumentsIter, entries: u64);
+
+/// # Safety
+/// `iter` must be a valid pointer previously returned by `DocumentsIter::new`.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_graph_documents_iter_len(iter: *const DocumentsIter) -> usize {
+    unsafe { DocumentsIter::len(iter) }
+}
+
+/// # Safety
+/// - `iter` must be a valid pointer previously returned by `DocumentsIter::new`.
+/// - `out` must be a valid, writable pointer.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_graph_documents_iter_next(iter: *mut DocumentsIter, out: *mut u64) -> bool {
+    unsafe { DocumentsIter::next(iter, out) }
+}
+
+/// # Safety
+/// - `iter` must be a pointer previously returned by `DocumentsIter::new`.
+/// - `iter` must not be used after being freed.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_graph_documents_iter_free(iter: *mut DocumentsIter) {
+    unsafe { DocumentsIter::free(iter) }
+}
+
+/// 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: u64) -> *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: u64) -> *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::<_>::new().into_boxed_slice())
+        }
+    })
+}