rubydex 0.4.0-aarch64-linux → 0.4.2-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0ae408bab2d715dbc24c9788310c8387d479578b43f3ed91a5613694da7c7f3
-  data.tar.gz: f91df4834446b385e52a407f3a45dea75c3cbb1e01f843a7a0176a3441a9c952
+  metadata.gz: 6ef406f89b33ab38d3e0cc4423e9f651003144c22c55feebfc0b5750878ec1e3
+  data.tar.gz: 719fa68c55a21101cf13115a6089c23cb145073d4bd9d87e6730335742e71ba1
 SHA512:
-  metadata.gz: 59f82f4466af541704a9a8967b022234130ae4c12be48f1a7b7f50b8a1d58bf63c0c42ae3e90d8ed6f6068bd69fab3f5e8a08ecb388398b530a500effb9e4b85
-  data.tar.gz: 896414c62dcac91658b49031afe905b74f3ef1d68d07205ff292805f2b05cf50dee1155305d45e83c82a172a8ea24f550cb7e590aa5a649c56abaa6890992f75
+  metadata.gz: 0e4e82d8b4a75b1eac0cb42b43e1c053cf3088167b6c742ee04ff8a3de8f4e97a278ba1f24cb08cfc150ea2244de26e02c84ab3435f641b0899040c8e54a5272
+  data.tar.gz: 0ff32e86e8eb8e5f11745e796f8e1a3834080f489b084c93c5a3eab8260d5fb9353890de4367f0a71bf758eef0db98344982144d788f0b045aa8544a8d3ec478

data/README.md

@@ -114,7 +114,7 @@ Thread safety comes from an `RwLock` on the Rust side, **not** from Ruby's
 
 All built-in tools are experimental. These tools can change without deprecation warnings.
 
-### `rdx query`
+### Querying
 
 Rubydex exposes the indexed graph through a read-only subset of the
 [Cypher](https://opencypher.org/) query language. Only read clauses (`MATCH`,
@@ -153,27 +153,21 @@ puts result.render("json")
 puts Rubydex::Query.schema("table")
 ```
 
-### `rdx lint`
+### Linter
 
-Put rule files under `rubydex_linter/rules`. Each rule must inherit from `Rubydex::Linter::CustomRule`.
+See the [linter docs](docs/linter.md).
 
-Run the linter:
+### Dead code candidates
 
 ```bash
-bundle exec rdx lint
+bundle exec rdx dead_code
 ```
 
-Rubydex uses the bundle root, or the current directory when no bundle is available.
+Prints a list of potentially dead code candidates. The list is composed of all declarations for which the analysis found no references for in the codebase.
 
-Configure a rule in `rubydex.toml`:
+Since some declarations may be used through meta-programming or otherwise untyped code, there may be false positives and the removal of candidates must be done carefully with context about the codebase.
 
-```toml
-[linter.rules.<Rule name>]
-enabled = true
-exclude = ["path_to_skip/**"]
-```
-
-### `rdx mcp`
+### MCP server
 
 Rubydex can run as an MCP (Model Context Protocol) server, enabling AI assistants
 like Claude to semantically query your Ruby codebase.
@@ -214,6 +208,7 @@ like Claude to semantically query your Ruby codebase.
 | `get_declaration` | Full details by fully qualified name with docs, ancestors, members |
 | `get_descendants` | What classes/modules inherit from or include this one |
 | `find_constant_references` | All precise, resolved constant references across the codebase |
+| `find_dead_code_candidates` | List of potentially unused code |
 | `get_file_declarations` | List declarations defined in a specific file |
 | `codebase_stats` | High-level statistics about the indexed codebase |
 

data/THIRD_PARTY_LICENSES.html

@@ -50,7 +50,7 @@
 
         <h2>Overview of licenses:</h2>
         <ul class="licenses-overview">
-            <li><a href="#Apache-2.0">Apache License 2.0</a> (119)</li>
+            <li><a href="#Apache-2.0">Apache License 2.0</a> (120)</li>
             <li><a href="#Unicode-3.0">Unicode License v3</a> (19)</li>
             <li><a href="#MIT">MIT License</a> (17)</li>
             <li><a href="#BSD-2-Clause">BSD 2-Clause &quot;Simplified&quot; License</a> (2)</li>
@@ -2515,6 +2515,9 @@ limitations under the License.
                     <li><a
                             href=" https://github.com/comex/rust-shlex ">shlex
                             1.3.0</a></li>
+                    <li><a
+                            href=" https://github.com/comex/rust-shlex ">shlex
+                            2.0.1</a></li>
                     <li><a
                             href=" https://github.com/dtolnay/syn ">syn
                             2.0.104</a></li>
@@ -2670,7 +2673,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
                 <ul class="license-used-by">
                     <li><a
                             href=" https://github.com/DoumanAsh/xxhash-rust ">xxhash-rust
-                            0.8.15</a></li>
+                            0.8.16</a></li>
                 </ul>
                 <pre class="license-text">Boost Software License - Version 1.0 - August 17th, 2003
 
@@ -2821,26 +2824,6 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of
 
 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED &quot;AS IS&quot;, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-</pre>
-            </li>
-            <li class="license">
-                <h3 id="MIT">MIT License</h3>
-                <h4>Used by:</h4>
-                <ul class="license-used-by">
-                    <li><a
-                            href=" https://github.com/ruby/prism ">ruby-prism-sys
-                            1.9.0</a></li>
-                    <li><a
-                            href=" https://github.com/ruby/prism ">ruby-prism
-                            1.9.0</a></li>
-                </ul>
-                <pre class="license-text">Copyright 2022-present, Shopify Inc.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the &quot;Software&quot;), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
 THE SOFTWARE IS PROVIDED &quot;AS IS&quot;, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 </pre>
             </li>
@@ -2881,13 +2864,19 @@ SOFTWARE.
                 <ul class="license-used-by">
                     <li><a
                             href=" https://github.com/Shopify/rubydex ">rubydex
-                            0.2.6</a></li>
+                            0.4.2</a></li>
                     <li><a
                             href=" https://github.com/Shopify/rubydex ">rubydex-sys
-                            0.2.6</a></li>
+                            0.4.2</a></li>
                     <li><a
                             href=" https://github.com/DimaKudosh/difflib ">difflib
                             0.4.0</a></li>
+                    <li><a
+                            href=" https://github.com/ruby/prism ">ruby-prism-sys
+                            2.0.0-rc.2</a></li>
+                    <li><a
+                            href=" https://github.com/ruby/prism ">ruby-prism
+                            2.0.0-rc.2</a></li>
                 </ul>
                 <pre class="license-text">MIT License
 

data/ext/rubydex/definition.c

@@ -38,6 +38,17 @@ VALUE cClassVariableDefinition;
 VALUE cMethodAliasDefinition;
 VALUE cGlobalVariableAliasDefinition;
 
+uint64_t rdxi_definition_id_for_graph(VALUE definition, VALUE graph_obj) {
+    HandleData *data;
+    TypedData_Get_Struct(definition, HandleData, &handle_type, data);
+
+    if (data->graph_obj != graph_obj) {
+        rb_raise(rb_eArgError, "definition must belong to this graph");
+    }
+
+    return data->id;
+}
+
 // Keep this in sync with definition.rs
 VALUE rdxi_definition_class_for_kind(DefinitionKind kind) {
     switch (kind) {
@@ -153,6 +164,25 @@ static VALUE rdxr_definition_name(VALUE self) {
     return rdxi_owned_c_string_to_ruby(name);
 }
 
+/*
+ * call-seq:
+ *   raw_name -> String
+ *
+ * Returns the class, module, or constant name as written in source, preserving explicit parent scopes like "Foo::Bar"
+ * and rooted paths like "::Bar".
+ */
+static VALUE rdxr_definition_raw_name(VALUE self) {
+    HandleData *data;
+    void *graph = rdxi_graph_from_handle(self, &data);
+
+    const char *name = rdx_definition_raw_name(graph, data->id);
+    if (name == NULL) {
+        rb_raise(rb_eRuntimeError, "Definition not found");
+    }
+
+    return rdxi_owned_c_string_to_ruby(name);
+}
+
 /*
  * call-seq:
  *   deprecated? -> bool
@@ -442,6 +472,7 @@ void rdxi_initialize_definition(VALUE mod) {
     rb_define_method(cDefinition, "document", rdxr_definition_document, 0);
 
     cClassDefinition = rb_define_class_under(mRubydex, "ClassDefinition", cDefinition);
+    rb_define_method(cClassDefinition, "raw_name", rdxr_definition_raw_name, 0);
     rb_define_method(cClassDefinition, "superclass", rdxr_class_definition_superclass, 0);
     rb_define_method(cClassDefinition, "mixins", rdxr_definition_mixins, 0);
 
@@ -449,10 +480,13 @@ void rdxi_initialize_definition(VALUE mod) {
     rb_define_method(cSingletonClassDefinition, "mixins", rdxr_definition_mixins, 0);
 
     cModuleDefinition = rb_define_class_under(mRubydex, "ModuleDefinition", cDefinition);
+    rb_define_method(cModuleDefinition, "raw_name", rdxr_definition_raw_name, 0);
     rb_define_method(cModuleDefinition, "mixins", rdxr_definition_mixins, 0);
 
     cConstantDefinition = rb_define_class_under(mRubydex, "ConstantDefinition", cDefinition);
+    rb_define_method(cConstantDefinition, "raw_name", rdxr_definition_raw_name, 0);
     cConstantAliasDefinition = rb_define_class_under(mRubydex, "ConstantAliasDefinition", cDefinition);
+    rb_define_method(cConstantAliasDefinition, "raw_name", rdxr_definition_raw_name, 0);
     cConstantVisibilityDefinition = rb_define_class_under(mRubydex, "ConstantVisibilityDefinition", cDefinition);
     cMethodVisibilityDefinition = rb_define_class_under(mRubydex, "MethodVisibilityDefinition", cDefinition);
     cMethodDefinition = rb_define_class_under(mRubydex, "MethodDefinition", cDefinition);

data/ext/rubydex/definition.h

@@ -22,6 +22,9 @@ extern VALUE cGlobalVariableAliasDefinition;
 
 void rdxi_initialize_definition(VALUE mRubydex);
 
+// Returns the definition ID after verifying that the definition belongs to `graph_obj`.
+uint64_t rdxi_definition_id_for_graph(VALUE definition, VALUE graph_obj);
+
 // Returns the Ruby class for a given DefinitionKind without calling back into Rust
 VALUE rdxi_definition_class_for_kind(DefinitionKind kind);
 

data/ext/rubydex/diagnostic.c

@@ -6,11 +6,8 @@
  * mRubydex = rb_define_module("Rubydex")
  */
 
-static VALUE mRubydex;
 static VALUE mRules;
 VALUE cDiagnostic;
-static VALUE cRule;
-static ID id_default_severity;
 
 VALUE rdxi_build_diagnostic_severity_value(VALUE mRubydex, DiagnosticSeverity severity) {
     VALUE mSeverity = rb_const_get(mRubydex, rb_intern("Severity"));
@@ -31,55 +28,11 @@ VALUE rdxi_build_diagnostic_severity_value(VALUE mRubydex, DiagnosticSeverity se
     return Qnil;
 }
 
-/*
- * call-seq:
- *   default_severity -> Rubydex::Severity::Base
- *
- * Returns the Rubydex::Severity subclass the diagnostics of this rule get unless the configuration overrides it.
- */
-static VALUE rdxr_generated_rule_default_severity(VALUE self) {
-    VALUE severity = rb_attr_get(self, id_default_severity);
-
-    // Class-level instance variables are not inherited, so a class inheriting from a generated rule reaches this without
-    // a severity of its own.
-    if (NIL_P(severity)) {
-        rb_raise(rb_eRuntimeError, "Rule %s has no default severity", rb_class2name(self));
-    }
-
-    return severity;
-}
-
-// Generates a rule class for every rule the graph can report. Severities are resolved here rather than when they are
-// read, which is why Rubydex::Severity is loaded before this extension (see `lib/rubydex.rb`).
-static void define_generated_rules(void) {
-    CRuleArray rule_array = rdx_rules();
-    VALUE rules = rb_ary_new_capa((long)rule_array.len);
-
-    for (size_t i = 0; i < rule_array.len; i++) {
-        CRule built_in_rule = rule_array.items[i];
-        VALUE name = rb_utf8_str_new(built_in_rule.name, (long)built_in_rule.name_length);
-        VALUE rule = rb_define_class_under(mRules, StringValueCStr(name), cRule);
-        VALUE severity = rdxi_build_diagnostic_severity_value(mRubydex, built_in_rule.default_severity);
-
-        rb_ivar_set(rule, id_default_severity, severity);
-        rb_define_singleton_method(rule, "default_severity", rdxr_generated_rule_default_severity, 0);
-        rb_ary_push(rules, rule);
-    }
-
-    rdx_rules_free(rule_array);
-    rb_define_const(mRules, "ALL", rb_obj_freeze(rules));
-}
-
 VALUE rdxi_rule_class_from_name(const char *name, size_t length) {
     return rb_const_get_at(mRules, rb_intern2(name, (long)length));
 }
 
 void rdxi_initialize_diagnostic(VALUE moduleRubydex) {
-    mRubydex = moduleRubydex;
-    id_default_severity = rb_intern("@default_severity");
-
-    cDiagnostic = rb_define_class_under(mRubydex, "Diagnostic", rb_cObject);
-    cRule = rb_define_class_under(mRubydex, "Rule", rb_cObject);
-    mRules = rb_define_module_under(mRubydex, "Rules");
-    define_generated_rules();
+    cDiagnostic = rb_define_class_under(moduleRubydex, "Diagnostic", rb_cObject);
+    mRules = rb_define_module_under(moduleRubydex, "Rules");
 }

data/ext/rubydex/extconf.rb

@@ -23,12 +23,12 @@ release = ENV["RELEASE"] || !developing_rubydex
 root_dir = gem_dir.join("rust")
 target_dir = root_dir.join("target")
 target_dir = target_dir.join("x86_64-pc-windows-gnu") if Gem.win_platform?
-target_dir = target_dir.join(release ? "release" : "debug")
+target_dir = target_dir.join("$(RUST_PROFILE)")
 
 bindings_path = root_dir.join("rubydex-sys").join("rustbindings.h")
 
 cargo_args = ["--manifest-path #{root_dir.join("Cargo.toml")}"]
-cargo_args << "--release" if release
+cargo_args << "$(CARGO_PROFILE_FLAG)"
 
 if Gem.win_platform?
   cargo_args << "--target x86_64-pc-windows-gnu"
@@ -102,6 +102,8 @@ makefile = File.read("Makefile")
 
 new_makefile = makefile.gsub("$(OBJS): $(HDRS) $(ruby_headers)", <<~MAKEFILE.chomp)
   .PHONY: compile_rust
+  RUST_PROFILE = $(if $(strip $(RELEASE)),release,#{developing_rubydex ? "debug" : "release"})
+  CARGO_PROFILE_FLAG = $(if $(filter release,$(RUST_PROFILE)),--release)
   RUST_SRCS = #{File.expand_path("Cargo.toml", root_dir)} #{File.expand_path("Cargo.lock", root_dir)} #{rust_srcs.join(" ")}
 
   .rust_built: $(RUST_SRCS)

data/ext/rubydex/graph.c

@@ -1,6 +1,7 @@
 #include "graph.h"
 #include "config.h"
 #include "declaration.h"
+#include "definition.h"
 #include "diagnostic.h"
 #include "document.h"
 #include "location.h"
@@ -256,6 +257,30 @@ static VALUE rdxr_graph_fuzzy_search(int argc, VALUE *argv, VALUE self) {
     return rdxr_graph_yield_search_results(self, iter);
 }
 
+/*
+ * call-seq:
+ *   dead_code_candidates -> Enumerator[Rubydex::Declaration]
+ *
+ * Returns an enumerator over declarations that may be unused because the analysis could not find any references to
+ * them. This misses metaprogramming or untyped code, which is why the term candidates is used.
+ *
+ * Currently, only supports constants.
+ */
+static VALUE rdxr_graph_dead_code_candidates(VALUE self) {
+    if (!rb_block_given_p()) {
+        return rb_enumeratorize(self, rb_str_new2("dead_code_candidates"), 0, NULL);
+    }
+
+    void *graph;
+    TypedData_Get_Struct(self, void *, &graph_type, graph);
+
+    void *iter = rdx_graph_dead_code_candidates(graph);
+    VALUE args = rb_ary_new_from_args(2, self, ULL2NUM((uintptr_t)iter));
+    rb_ensure(rdxi_declarations_yield, args, rdxi_declarations_ensure, args);
+
+    return self;
+}
+
 // Body function for rb_ensure in Graph#documents
 static VALUE graph_documents_yield(VALUE args) {
     VALUE self = rb_ary_entry(args, 0);
@@ -486,26 +511,48 @@ static VALUE rdxr_graph_set_encoding(VALUE self, VALUE encoding) {
 
 /*
  * call-seq:
- *   resolve_constant(name, nesting) -> Rubydex::Declaration?
+ *   resolve_constant(name, context) -> Rubydex::Declaration?
  *
- * Runs the resolver on a single constant reference to determine what it points to.
+ * Runs the resolver on a single constant reference using an array of nesting names or a namespace definition as its
+ * context.
  */
-static VALUE rdxr_graph_resolve_constant(VALUE self, VALUE const_name, VALUE nesting) {
+static VALUE rdxr_graph_resolve_constant(VALUE self, VALUE const_name, VALUE context) {
     Check_Type(const_name, T_STRING);
-    rdxi_check_array_of_strings(nesting);
     const char *const_name_string = StringValueCStr(const_name);
 
-    // Convert the given file paths into a char** array, so that we can pass to Rust
-    size_t length = RARRAY_LEN(nesting);
-    char **converted_file_paths = rdxi_str_array_to_char(nesting, length);
-
     void *graph;
     TypedData_Get_Struct(self, void *, &graph_type, graph);
 
-    const CDeclaration *decl =
-        rdx_graph_resolve_constant(graph, const_name_string, (const char **)converted_file_paths, length);
+    const CDeclaration *decl;
+    if (RB_TYPE_P(context, T_ARRAY)) {
+        rdxi_check_array_of_strings(context);
+
+        size_t length = RARRAY_LEN(context);
+        char **converted_names = rdxi_str_array_to_char(context, length);
+        decl = rdx_graph_resolve_constant(graph, const_name_string, (const char **)converted_names, length);
+        rdxi_free_str_array(converted_names, length);
+    } else if (rb_obj_is_kind_of(context, cClassDefinition) ||
+               rb_obj_is_kind_of(context, cSingletonClassDefinition) ||
+               rb_obj_is_kind_of(context, cModuleDefinition)) {
+        uint64_t definition_id = rdxi_definition_id_for_graph(context, self);
+        CDefinitionConstantResolutionResult result =
+            rdx_graph_resolve_constant_from_definition(graph, const_name_string, definition_id);
+
+        if (result.status == CDefinitionConstantResolution_DefinitionNotFound) {
+            rb_raise(rb_eRuntimeError, "Definition not found");
+        }
+        if (result.status == CDefinitionConstantResolution_InvalidDefinitionKind) {
+            // This is unreachable because the rb_obj_is_kind_of checks above only accept supported definition kinds.
+            rb_raise(rb_eRuntimeError, "Unexpected definition kind");
+        }
 
-    rdxi_free_str_array(converted_file_paths, length);
+        decl = result.declaration;
+    } else {
+        rb_raise(
+            rb_eTypeError,
+            "context must be an Array of Strings, ClassDefinition, SingletonClassDefinition, or ModuleDefinition"
+        );
+    }
 
     if (decl == NULL) {
         return Qnil;
@@ -938,6 +985,7 @@ void rdxi_initialize_graph(VALUE moduleRubydex) {
     rb_define_method(cGraph, "[]", rdxr_graph_aref, 1);
     rb_define_method(cGraph, "search", rdxr_graph_search, -1);
     rb_define_method(cGraph, "fuzzy_search", rdxr_graph_fuzzy_search, -1);
+    rb_define_method(cGraph, "dead_code_candidates", rdxr_graph_dead_code_candidates, 0);
     rb_define_method(cGraph, "encoding=", rdxr_graph_set_encoding, 1);
     rb_define_method(cGraph, "resolve_require_path", rdxr_graph_resolve_require_path, 2);
     rb_define_method(cGraph, "require_paths", rdxr_graph_require_paths, 1);

data/lib/rubydex/cli/command/dead_code.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "rubydex/cli/command"
+
+module Rubydex
+  module CLI
+    # `rdx dead_code` — lists dead code candidates in the current workspace.
+    class Command
+      class DeadCode < Command
+        command "dead_code"
+        summary "List dead code candidates in the current workspace"
+
+        #: -> void
+        def run
+          parse_options!
+          abort_with_usage("unexpected argument: #{argv.first}") unless argv.empty?
+
+          require "rubydex/linter/helpers/path_helpers"
+
+          $stderr.puts("Looking for potentially dead code...")
+          graph = build_graph($stderr, workspace_path: current_workspace_path)
+          candidates = graph.dead_code_candidates.sort_by(&:name)
+
+          candidates.each do |candidate|
+            puts(candidate.name)
+            candidate.definitions.map(&:location).sort.each do |location|
+              display = location.to_display
+              path = Rubydex::Linter::Helpers::PathHelpers.display_path(display, workspace: graph.workspace_path)
+              puts("  #{path}:#{display.start_line},#{display.start_column}-#{display.end_line},#{display.end_column}")
+            end
+            puts
+          end
+
+          print_summary(graph.documents.count, candidates.length)
+        end
+
+        private
+
+        #: (Integer file_count, Integer candidate_count) -> void
+        def print_summary(file_count, candidate_count)
+          if candidate_count.zero?
+            puts("#{file_count} #{pluralize("file", file_count)} inspected, no dead code candidates found")
+            return
+          end
+
+          puts(
+            "#{file_count} #{pluralize("file", file_count)} inspected, " \
+              "#{candidate_count} dead code #{pluralize("candidate", candidate_count)} found",
+          )
+        end
+
+        #: (String word, Integer count) -> String
+        def pluralize(word, count)
+          count == 1 ? word : "#{word}s"
+        end
+      end
+    end
+  end
+end

data/lib/rubydex/cli/command/lint/explain.rb

@@ -9,8 +9,10 @@ module Rubydex
       class Lint
         # `rdx lint explain <RULE>` — prints documentation for rules with a matching name.
         class Explain < Command
-          BASE_RULE_NAME = "Rubydex::Linter::CustomRule" #: String
-          BASE_RULE_PATH = File.expand_path("../../../linter/custom_rule.rb", __dir__) #: String
+          BASE_PATHS = [
+            File.expand_path("../../../linter/custom_rule.rb", __dir__),
+            File.expand_path("../../../rule.rb", __dir__),
+          ] #: Array[String]
 
           class << self
             #: -> String
@@ -30,17 +32,17 @@ module Rubydex
             workspace_path = current_workspace_path
 
             graph = Rubydex::Graph.configure_for_workspace(workspace_path)
-            graph.index_all([BASE_RULE_PATH, *Rubydex::Linter::RuleLoader.paths(workspace_path)])
+            graph.index_all([*BASE_PATHS, *Rubydex::Linter::RuleLoader.paths(workspace_path)])
             graph.resolve
 
-            base_rule = graph[BASE_RULE_NAME]
-            abort("Base rule class #{BASE_RULE_NAME} is not found. This is likely an issue in Rubydex itself") unless base_rule.is_a?(Rubydex::Class)
+            base_rule = graph["Rubydex::Rule"]
+            abort("Base rule class is not found. This is an issue in Rubydex itself") unless base_rule.is_a?(Rubydex::Class)
 
             rule_declarations = base_rule.descendants.grep(Rubydex::Class) #: as Array[Rubydex::Class]
             matched_rule_names = rule_declarations.filter_map do |declaration|
               declaration_name = declaration.name
               next unless declaration_name
-              next if declaration_name == BASE_RULE_NAME
+              next if declaration_name == "Rubydex::Rule" || declaration_name == "Rubydex::Linter::CustomRule"
               next unless declaration_name.end_with?(rule_name)
 
               declaration

data/lib/rubydex/cli/command/lint.rb

@@ -35,7 +35,7 @@ module Rubydex
           require "rubydex/linter"
 
           custom_rules = load_linter_rules(workspace_path)
-          warn_unknown_rules(custom_rules)
+          warn_unknown_rules
 
           graph = build_graph($stderr, workspace_path:, config:)
           runner = Rubydex::Linter::Runner.new(graph, custom_rules:, config: linter_config)
@@ -64,9 +64,15 @@ module Rubydex
           @linter_config ||= config.linter #: Rubydex::LinterConfig?
         end
 
-        #: (Array[singleton(Rubydex::Linter::CustomRule)] custom_rule_classes) -> void
-        def warn_unknown_rules(custom_rule_classes)
-          known_rule_names = (Rubydex::Rules::ALL + custom_rule_classes).map(&:rule_name).uniq.sort
+        #: () -> void
+        def warn_unknown_rules
+          known_rule_names = (Rule.subclasses + Rubydex::Linter::CustomRule.subclasses).filter_map do |rule|
+            name = rule.rule_name
+            name unless name == "CustomRule"
+          end
+          known_rule_names.uniq!
+          known_rule_names.sort!
+
           unknown_rule_names = linter_config.rules.keys.reject { |name| known_rule_names.include?(name) }.sort
           return if unknown_rule_names.empty?
 

data/lib/rubydex/linter/rule_loader.rb

@@ -4,7 +4,7 @@ module Rubydex
   module Linter
     # Loads project and bundled-gem rules using the Rubydex linter path convention.
     class RuleLoader
-      BUILT_IN_RULE_GLOB = File.expand_path("../../rubydex_linter/rules/**/*.rb", __dir__) #: String
+      BUILT_IN_RULE_GLOB = File.expand_path("../../{rubydex_linter,rubydex}/rules/**/*.rb", __dir__) #: String
       RULE_GLOB = "rubydex_linter/rules/**/*.rb" #: String
 
       class << self

data/lib/rubydex/mcp_server/tools/codebase_stats_tool.rb

@@ -4,7 +4,7 @@ module Rubydex
   module MCPServer
     class CodebaseStatsTool < BaseTool
       tool_name "codebase_stats"
-      description "Get an overview of the indexed Ruby codebase: total file count, declaration counts, and breakdown by kind (classes, modules, methods, constants). Use this to understand codebase size and composition, or to verify that indexing completed successfully."
+      description "Count indexed files, declarations, definitions, and references, with declarations grouped by kind."
       input_schema(properties: {})
 
       #: -> Tool::Response

data/lib/rubydex/mcp_server/tools/find_constant_references_tool.rb

@@ -4,12 +4,12 @@ module Rubydex
   module MCPServer
     class FindConstantReferencesTool < BaseTool
       tool_name "find_constant_references"
-      description "Find all resolved references to a Ruby class, module, or constant across the codebase. Returns file paths, line numbers, and columns for each usage. Results are paginated: the response includes `total`. If `total` exceeds the number of returned results, use `offset` to fetch subsequent pages."
+      description "Locate resolved references to a Ruby class, module, or constant."
       input_schema(
         properties: {
-          name: { type: "string", description: "Fully qualified name of the class, module, or constant to find references for" },
-          limit: { type: "integer", description: "Maximum number of references to return (default 50, max 200)" },
-          offset: { type: "integer", description: "Number of references to skip for pagination (default 0)" },
+          name: { type: "string", description: "Fully qualified class, module, or constant name" },
+          limit: { type: "integer", description: "Page size (default 50, capped at 200)" },
+          offset: { type: "integer", description: "Number of results to skip (default 0)" },
         },
         required: ["name"],
       )

data/lib/rubydex/mcp_server/tools/find_dead_code_candidates_tool.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Rubydex
+  module MCPServer
+    class FindDeadCodeCandidatesTool < BaseTool
+      tool_name "find_dead_code_candidates"
+      description "Find Ruby classes, modules, and constants with no detected references, including dependency code. Dynamic usage through DSLs or metaprogramming may not be detected."
+      input_schema(
+        properties: {
+          limit: { type: "integer", description: "Page size (default 50, capped at 100)" },
+          offset: { type: "integer", description: "Number of results to skip (default 0)" },
+        },
+      )
+
+      #: (?limit: Integer, ?offset: Integer) -> Tool::Response
+      def call(limit: nil, offset: nil)
+        declarations = @graph.dead_code_candidates.sort_by(&:name)
+        page, total = paginate(declarations, offset, limit, 100)
+        candidates = page.map do |declaration|
+          {
+            name: declaration.name,
+            kind: declaration_kind(declaration),
+            locations: declaration.definitions.sort_by(&:location).map do |definition|
+              display_location(definition.location)
+            end,
+          }
+        end
+
+        response(candidates: candidates, total: total)
+      end
+    end
+  end
+end

data/lib/rubydex/mcp_server/tools/get_declaration_tool.rb

@@ -4,10 +4,10 @@ module Rubydex
   module MCPServer
     class GetDeclarationTool < BaseTool
       tool_name "get_declaration"
-      description 'Get complete information about a Ruby class, module, method, or constant by its exact fully qualified name. Returns file locations, documentation comments, ancestor chain, and members with locations. FQN format: "Foo::Bar" for classes/modules/constants, "Foo::Bar#method_name" for instance methods, "Foo::Bar::<Bar>" for singleton classes, and "Foo::Bar::<Bar>#method_name" for class methods.'
+      description "Get a Ruby declaration's definition locations, documentation, ancestors, and members."
       input_schema(
         properties: {
-          name: { type: "string", description: "Fully qualified name of the declaration (e.g. 'Foo::Bar', 'Foo::Bar#baz')" },
+          name: { type: "string", description: 'Exact fully qualified name: "Foo::Bar", "Foo::Bar#method_name()" (instance method), "Foo::Bar::<Bar>" (singleton class), or "Foo::Bar::<Bar>#method_name()" (class method)' },
         },
         required: ["name"],
       )