rubydex 0.4.0 → 0.4.1

data/rust/rubydex/src/query.rs

@@ -5,7 +5,7 @@ use std::thread;
 
 use url::Url;
 
-use crate::model::built_in::OBJECT_ID;
+use crate::model::built_in::{BUILT_IN_URI_ID, OBJECT_ID};
 use crate::model::declaration::{Ancestor, Declaration, Namespace};
 use crate::model::definitions::{Definition, Parameter};
 use crate::model::graph::Graph;
@@ -833,6 +833,63 @@ pub fn follow_method_alias(graph: &Graph, alias_id: DefinitionId) -> Result<Decl
     }
 }
 
+/// Returns `true` when any definition of `declaration` was seeded by rubydex rather than read from indexed source.
+///
+/// Dead code candidates are reported at declaration granularity, so a seeded definition disqualifies the declaration
+/// even when user code also reopens it.
+fn is_built_in(graph: &Graph, declaration: &Declaration) -> bool {
+    declaration.definitions().iter().any(|definition_id| {
+        graph
+            .definitions()
+            .get(definition_id)
+            .is_some_and(|definition| definition.uri_id() == &*BUILT_IN_URI_ID)
+    })
+}
+
+/// Returns a list of declarations that may be unused in the codebase, which means
+/// that the analysis could not find any references to them. This misses
+/// meta-programming or untyped code, which is why the term candidates is used.
+///
+/// Currently, only supports constants.
+///
+/// # Panics
+///
+/// Will panic if any of the threads panic
+pub fn dead_code_candidates(graph: &Graph) -> Vec<DeclarationId> {
+    let num_threads = thread::available_parallelism().map_or(4, std::num::NonZero::get);
+    let declarations = graph.declarations();
+
+    let ids: Vec<DeclarationId> = declarations.keys().copied().collect();
+    let chunk_size = ids.len().div_ceil(num_threads);
+
+    if chunk_size == 0 {
+        return Vec::new();
+    }
+
+    thread::scope(|s| {
+        let handles: Vec<_> = ids
+            .chunks(chunk_size)
+            .map(|chunk| {
+                s.spawn(|| {
+                    chunk
+                        .iter()
+                        .filter(|id| {
+                            let decl = declarations.get(id).unwrap();
+                            decl.constant_references().is_some_and(HashSet::is_empty)
+                                && !matches!(decl, Declaration::Namespace(Namespace::SingletonClass(_)))
+                                && !decl.has_no_definitions()
+                                && !is_built_in(graph, decl)
+                        })
+                        .copied()
+                        .collect::<Vec<_>>()
+                })
+            })
+            .collect();
+
+        handles.into_iter().flat_map(|h| h.join().unwrap()).collect()
+    })
+}
+
 #[cfg(test)]
 mod tests {
     use std::str::FromStr;
@@ -920,6 +977,21 @@ mod tests {
         };
     }
 
+    macro_rules! assert_dead_code_candidates {
+        ($context:expr, [$($expected:expr),* $(,)?]) => {
+            let mut actual: Vec<String> = dead_code_candidates($context.graph())
+                .iter()
+                .map(|id| $context.graph().declarations().get(id).unwrap().name().to_string())
+                .collect();
+            actual.sort();
+
+            let mut expected: Vec<String> = vec![$(String::from($expected)),*];
+            expected.sort();
+
+            assert_eq!(expected, actual);
+        };
+    }
+
     #[test]
     fn fuzzy_search_returns_partial_matches() {
         let mut context = GraphTest::new();
@@ -3982,4 +4054,122 @@ mod tests {
             Err(FindMemberError::DeclarationNotFound),
         );
     }
+
+    #[test]
+    fn dead_code_candidates_returns_unreferenced_constants() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class UnusedClass; end
+            module UnusedModule; end
+            UNUSED_CONSTANT = 1
+            ",
+        );
+        context.resolve();
+
+        assert_dead_code_candidates!(context, ["UnusedClass", "UnusedModule", "UNUSED_CONSTANT"]);
+    }
+
+    #[test]
+    fn dead_code_candidates_excludes_referenced_constants() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class UsedClass; end
+            USED_CONSTANT = 1
+            ",
+        );
+        context.index_uri(
+            "file:///bar.rb",
+            r"
+            UsedClass
+            USED_CONSTANT
+            ",
+        );
+        context.resolve();
+
+        assert_dead_code_candidates!(context, []);
+    }
+
+    #[test]
+    fn dead_code_candidates_excludes_methods_and_variables() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            $global_var = 1
+
+            class Holder
+              @@class_var = 1
+
+              def initialize
+                @instance_var = 1
+              end
+
+              def never_called; end
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_dead_code_candidates!(context, ["Holder"]);
+    }
+
+    #[test]
+    fn dead_code_candidates_counts_references_rather_than_reachability() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class Target; end
+            AliasName = Target
+            ",
+        );
+        context.resolve();
+
+        // `AliasName` is itself dead, but it still references `Target`, giving `Target` a non-zero count.
+        // A single pass only peels the outermost layer of a dead subgraph.
+        assert_dead_code_candidates!(context, ["AliasName"]);
+    }
+
+    #[test]
+    fn dead_code_candidates_excludes_built_ins_and_definitionless_declarations() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class Unused
+              def self.class_method; end
+            end
+
+            class Class
+            end
+            ",
+        );
+        context.resolve();
+
+        // A reopened built-in remains excluded regardless of definition order.
+        assert_dead_code_candidates!(context, ["Unused"]);
+    }
+
+    #[test]
+    fn dead_code_candidates_excludes_singleton_classes() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class Unused; end
+            class Attached; end
+
+            class << Attached
+              def never_called; end
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_dead_code_candidates!(context, ["Unused"]);
+    }
 }

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

@@ -6,7 +6,9 @@ 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 rubydex::model::graph::Graph;
+use rubydex::model::ids::{DefinitionId, NameId};
+use rubydex::model::name::ParentScope;
 use rubydex::query::AliasResolutionError;
 use std::ffi::CString;
 use std::ptr;
@@ -110,6 +112,71 @@ pub unsafe extern "C" fn rdx_definition_name(pointer: GraphPointer, definition_i
     })
 }
 
+fn raw_name_for_name(graph: &Graph, name_id: NameId) -> String {
+    let mut raw_name = String::new();
+    append_raw_name(graph, name_id, &mut raw_name);
+    raw_name
+}
+
+fn append_raw_name(graph: &Graph, name_id: NameId, raw_name: &mut String) {
+    let name = graph
+        .names()
+        .get(&name_id)
+        .expect("name should exist while building raw_name");
+    let simple_name = graph
+        .strings()
+        .get(name.str())
+        .expect("string should exist while building raw_name")
+        .as_str();
+
+    match name.parent_scope() {
+        ParentScope::None => {}
+        ParentScope::TopLevel => raw_name.push_str("::"),
+        ParentScope::Some(parent_id) | ParentScope::Attached(parent_id) => {
+            append_raw_name(graph, *parent_id, raw_name);
+            raw_name.push_str("::");
+        }
+    }
+
+    raw_name.push_str(simple_name);
+}
+
+fn raw_name_id(definition: &Definition) -> Option<&NameId> {
+    match definition {
+        Definition::Class(_) | Definition::Module(_) | Definition::Constant(_) | Definition::ConstantAlias(_) => {
+            definition.name_id()
+        }
+        _ => None,
+    }
+}
+
+/// Returns the UTF-8 raw name string for a class, module, constant, or constant-alias definition id.
+///
+/// The raw name is reconstructed from the definition's `Name`, preserving explicit parent scopes like `Foo::Bar` and
+/// rooted paths like `::Bar`. Returns null if the definition cannot be found or does not support raw names. Caller must
+/// free a non-null result with `free_c_string`.
+///
+/// # Panics
+///
+/// Panics if the graph contains an invalid name or string reference, or if the name contains an embedded null byte.
+///
+/// # Safety
+///
+/// Assumes pointer is valid.
+///
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_definition_raw_name(pointer: GraphPointer, definition_id: u64) -> *const c_char {
+    with_graph(pointer, |graph| {
+        let def_id = DefinitionId::new(definition_id);
+        let Some(name_id) = graph.definitions().get(&def_id).and_then(raw_name_id) else {
+            return ptr::null();
+        };
+
+        let name = raw_name_for_name(graph, *name_id);
+        CString::new(name).unwrap().into_raw().cast_const()
+    })
+}
+
 /// Shared iterator over definition (id, kind) pairs
 #[derive(Debug)]
 pub struct DefinitionsIter {

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

@@ -32,7 +32,6 @@ impl From<Severity> for DiagnosticSeverity {
 pub struct CRule {
     pub name: *const c_char,
     pub name_length: usize,
-    pub default_severity: DiagnosticSeverity,
 }
 
 impl From<Rule> for CRule {
@@ -42,44 +41,10 @@ impl From<Rule> for CRule {
         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 {

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

@@ -10,9 +10,10 @@ use crate::{name_api, utils};
 use libc::{c_char, c_void};
 use rubydex::config::Config;
 use rubydex::indexing::LanguageId;
+use rubydex::model::definitions::Definition;
 use rubydex::model::encoding::Encoding;
 use rubydex::model::graph::Graph;
-use rubydex::model::ids::{DeclarationId, NameId, UriId, declaration_id_from_lookup_name};
+use rubydex::model::ids::{DeclarationId, DefinitionId, NameId, UriId, declaration_id_from_lookup_name};
 use rubydex::model::keywords;
 use rubydex::model::name::NameRef;
 use rubydex::model::visibility::Visibility;
@@ -133,6 +134,27 @@ pub unsafe extern "C" fn rdx_graph_declarations_fuzzy_search(
     DeclarationsIter::new(entries)
 }
 
+/// Returns an iterator over all dead code candidates in the graph.
+///
+/// # Safety
+///
+/// Expects `pointer` to be a valid graph. The returned iterator must be freed with `rdx_graph_declarations_iter_free`.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_graph_dead_code_candidates(pointer: GraphPointer) -> *mut DeclarationsIter {
+    let entries = with_graph(pointer, |graph| {
+        query::dead_code_candidates(graph)
+            .into_iter()
+            .filter_map(|id| {
+                let decl = graph.declarations().get(&id)?;
+                Some(CDeclaration::from_declaration(id, decl))
+            })
+            .collect::<Vec<CDeclaration>>()
+            .into_boxed_slice()
+    });
+
+    DeclarationsIter::new(entries)
+}
+
 /// # Panics
 ///
 /// Will panic if the nesting cannot be transformed into a vector of strings
@@ -155,24 +177,103 @@ pub unsafe extern "C" fn rdx_graph_resolve_constant(
             return ptr::null();
         };
 
-        let mut resolver = Resolver::new(graph);
+        resolve_constant_name(graph, name_id, names_to_untrack)
+    })
+}
+
+/// Result of resolving a constant using a namespace definition as its lexical context.
+#[repr(u8)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CDefinitionConstantResolution {
+    Resolved = 0,
+    NotFound = 1,
+    DefinitionNotFound = 2,
+    InvalidDefinitionKind = 3,
+}
 
-        let declaration = match resolver.resolve_constant(name_id) {
-            Some(id) => {
-                let decl = graph.declarations().get(&id).unwrap();
-                Box::into_raw(Box::new(CDeclaration::from_declaration(id, decl))).cast_const()
+#[repr(C)]
+#[derive(Debug)]
+pub struct CDefinitionConstantResolutionResult {
+    pub status: CDefinitionConstantResolution,
+    pub declaration: *const CDeclaration,
+}
+
+/// Resolves a constant using a namespace definition as its lexical context.
+///
+/// # Panics
+///
+/// Panics if `const_name` cannot be converted to a string.
+///
+/// # Safety
+///
+/// Assumes that `pointer` and `const_name` are valid.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn rdx_graph_resolve_constant_from_definition(
+    pointer: GraphPointer,
+    const_name: *const c_char,
+    definition_id: u64,
+) -> CDefinitionConstantResolutionResult {
+    with_mut_graph(pointer, |graph| {
+        let const_name: String = unsafe { utils::convert_char_ptr_to_string(const_name).unwrap() };
+        let nesting = match class_or_module_definition_name_id(graph, DefinitionId::new(definition_id)) {
+            Ok(nesting) => nesting,
+            Err(status) => {
+                return CDefinitionConstantResolutionResult {
+                    status,
+                    declaration: ptr::null(),
+                };
             }
-            None => ptr::null(),
         };
 
-        for name_id in names_to_untrack {
-            graph.untrack_name(name_id);
-        }
+        let Some((name_id, names_to_untrack)) = name_api::name_in_nesting_to_name_id(graph, &const_name, Some(nesting))
+        else {
+            return CDefinitionConstantResolutionResult {
+                status: CDefinitionConstantResolution::NotFound,
+                declaration: ptr::null(),
+            };
+        };
 
-        declaration
+        let declaration = resolve_constant_name(graph, name_id, names_to_untrack);
+        let status = if declaration.is_null() {
+            CDefinitionConstantResolution::NotFound
+        } else {
+            CDefinitionConstantResolution::Resolved
+        };
+
+        CDefinitionConstantResolutionResult { status, declaration }
     })
 }
 
+fn class_or_module_definition_name_id(
+    graph: &Graph,
+    definition_id: DefinitionId,
+) -> Result<NameId, CDefinitionConstantResolution> {
+    let Some(definition) = graph.definitions().get(&definition_id) else {
+        return Err(CDefinitionConstantResolution::DefinitionNotFound);
+    };
+
+    match definition {
+        Definition::Class(definition) => Ok(*definition.name_id()),
+        Definition::SingletonClass(definition) => Ok(*definition.name_id()),
+        Definition::Module(definition) => Ok(*definition.name_id()),
+        _ => Err(CDefinitionConstantResolution::InvalidDefinitionKind),
+    }
+}
+
+fn resolve_constant_name(graph: &mut Graph, name_id: NameId, names_to_untrack: Vec<NameId>) -> *const CDeclaration {
+    let declaration_id = Resolver::new(graph).resolve_constant(name_id);
+    let declaration = declaration_id.map_or(ptr::null(), |id| {
+        let declaration = graph.declarations().get(&id).unwrap();
+        Box::into_raw(Box::new(CDeclaration::from_declaration(id, declaration))).cast_const()
+    });
+
+    for name_id in names_to_untrack {
+        graph.untrack_name(name_id);
+    }
+
+    declaration
+}
+
 /// Adds glob patterns to exclude from file discovery during indexing.
 ///
 /// # Panics

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

@@ -13,13 +13,7 @@ pub fn nesting_stack_to_name_id(
     let mut names_to_untrack = Vec::new();
 
     for entry in nesting {
-        process_qualified_name(
-            graph,
-            &entry,
-            &mut current_name,
-            &mut current_nesting,
-            &mut names_to_untrack,
-        );
+        process_qualified_name(graph, &entry, current_nesting, &mut current_name, &mut names_to_untrack);
         current_nesting = current_name.as_ref().copied();
         current_name = ParentScope::None;
     }
@@ -27,12 +21,39 @@ pub fn nesting_stack_to_name_id(
     process_qualified_name(
         graph,
         const_name,
+        current_nesting,
         &mut current_name,
-        &mut current_nesting,
         &mut names_to_untrack,
     );
 
     let (ParentScope::Some(name_id) | ParentScope::Attached(name_id)) = current_name else {
+        // Invalid names may leave temporary parts in the graph (e.g. `Foo` from `Foo::`).
+        for name_id in names_to_untrack {
+            graph.untrack_name(name_id);
+        }
+        return None;
+    };
+
+    Some((name_id, names_to_untrack))
+}
+
+/// Takes a constant name and an existing lexical nesting 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.
+pub fn name_in_nesting_to_name_id(
+    graph: &mut Graph,
+    const_name: &str,
+    nesting: Option<NameId>,
+) -> Option<(NameId, Vec<NameId>)> {
+    let mut current_name = ParentScope::None;
+    let mut names_to_untrack = Vec::new();
+
+    process_qualified_name(graph, const_name, nesting, &mut current_name, &mut names_to_untrack);
+
+    let (ParentScope::Some(name_id) | ParentScope::Attached(name_id)) = current_name else {
+        // Invalid names may leave temporary parts in the graph (e.g. `Foo` from `Foo::`).
+        for name_id in names_to_untrack {
+            graph.untrack_name(name_id);
+        }
         return None;
     };
 
@@ -47,8 +68,8 @@ pub fn nesting_stack_to_name_id(
 fn process_qualified_name(
     graph: &mut Graph,
     qualified_name: &str,
+    current_nesting: Option<NameId>,
     current_name: &mut ParentScope,
-    current_nesting: &mut Option<NameId>,
     names_to_untrack: &mut Vec<NameId>,
 ) {
     for part in qualified_name.split("::") {
@@ -60,13 +81,13 @@ fn process_qualified_name(
         let (parent_scope, nesting_for_part) = if part.starts_with('<') {
             let attached_id = match *current_name {
                 ParentScope::Some(id) | ParentScope::Attached(id) => Some(id),
-                _ => *current_nesting,
+                _ => current_nesting,
             };
 
             let attached = attached_id.map_or(ParentScope::None, ParentScope::Attached);
             (attached, attached_id)
         } else {
-            (*current_name, *current_nesting)
+            (*current_name, current_nesting)
         };
 
         let str_id = graph.intern_string(part.to_owned());
@@ -182,4 +203,19 @@ mod tests {
         assert!(foo_name.parent_scope().is_none());
         assert!(foo_name.nesting().is_none());
     }
+
+    #[test]
+    fn invalid_names_are_untracked() {
+        let mut graph = Graph::new();
+        let name_count = graph.names().len();
+        let string_count = graph.strings().len();
+
+        assert!(nesting_stack_to_name_id(&mut graph, "Foo::", vec!["Bar".into()]).is_none());
+        assert_eq!(name_count, graph.names().len());
+        assert_eq!(string_count, graph.strings().len());
+
+        assert!(name_in_nesting_to_name_id(&mut graph, "Foo::", None).is_none());
+        assert_eq!(name_count, graph.names().len());
+        assert_eq!(string_count, graph.strings().len());
+    }
 }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubydex
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Shopify
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-20 00:00:00.000000000 Z
+date: 2026-09-02 00:00:00.000000000 Z
 dependencies: []
 description: A high-performance static analysis suite for Ruby, built in Rust with
   Ruby APIs
@@ -89,6 +89,16 @@ files:
 - lib/rubydex/reference.rb
 - lib/rubydex/related_information.rb
 - lib/rubydex/rule.rb
+- lib/rubydex/rules/dynamic_ancestor.rb
+- lib/rubydex/rules/dynamic_constant_reference.rb
+- lib/rubydex/rules/dynamic_singleton_definition.rb
+- lib/rubydex/rules/invalid_constant_visibility.rb
+- lib/rubydex/rules/invalid_method_visibility.rb
+- lib/rubydex/rules/parse_error.rb
+- lib/rubydex/rules/parse_warning.rb
+- lib/rubydex/rules/top_level_mixin_self.rb
+- lib/rubydex/rules/undefined_constant_visibility_target.rb
+- lib/rubydex/rules/undefined_method_visibility_target.rb
 - lib/rubydex/severity.rb
 - lib/rubydex/signature.rb
 - lib/rubydex/skill.rb
@@ -119,6 +129,7 @@ files:
 - rust/rubydex-sys/src/utils.rs
 - rust/rubydex/Cargo.toml
 - rust/rubydex/benches/graph_memory.rs
+- rust/rubydex/src/bin/generate_ruby_rules.rs
 - rust/rubydex/src/compile_assertions.rs
 - rust/rubydex/src/config.rs
 - rust/rubydex/src/diagnostic.rs