rubydex 0.3.0 → 0.4.1

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

@@ -1,8 +1,4 @@
-use rubydex::model::{
-    graph::Graph,
-    ids::NameId,
-    name::{Name, ParentScope},
-};
+use rubydex::model::{graph::Graph, ids::NameId, name::ParentScope};
 
 /// Takes a constant name and a nesting stack (e.g.: `["Foo", "Bar::Baz", "Qux"]`) and transforms it into a `NameId`,
 /// registering each required part in the graph. Returns the `NameId` and a list of name ids that need to be untracked
@@ -17,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;
     }
@@ -31,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;
     };
 
@@ -51,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("::") {
@@ -64,17 +81,17 @@ 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());
-        let name_id = graph.add_name(Name::new(str_id, parent_scope, nesting_for_part));
+        let name_id = graph.add_name(str_id, parent_scope, nesting_for_part);
         names_to_untrack.push(name_id);
         *current_name = ParentScope::Some(name_id);
     }
@@ -186,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());
+    }
 }

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

@@ -1,5 +1,6 @@
 use libc::{c_char, size_t};
 use std::ffi::{CStr, CString};
+use std::path::Path;
 use std::slice;
 use std::str::Utf8Error;
 
@@ -68,3 +69,39 @@ pub unsafe extern "C" fn free_c_string_array(ptr: *const *const c_char, count: u
         .map(|arg| unsafe { CString::from_raw((*arg).cast_mut()) })
         .collect();
 }
+
+/// Converts a Rust `&str` to an owned C string (`*const c_char`), suitable for returning across the
+/// FFI boundary. The caller is responsible for freeing it with `free_c_string`.
+///
+/// # Panics
+///
+/// Panics if `value` contains an interior null byte, which should never occur in rubydex data.
+#[must_use]
+pub fn cstring_raw(value: &str) -> *const c_char {
+    CString::new(value).unwrap().into_raw().cast_const()
+}
+
+/// Rust uses backslashes as separators on Windows, but Ruby prefers forward slashes everywhere. We need to make sure
+/// we're maintaining the right separators at the boundary.
+#[must_use]
+pub fn interop_path(path: &Path) -> String {
+    path.to_string_lossy().replace(std::path::MAIN_SEPARATOR, "/")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[cfg(unix)]
+    #[test]
+    fn interop_path_leaves_a_unix_path_untouched() {
+        // A backslash is an ordinary character in a Unix file name, so rewriting it would name a different file.
+        assert_eq!(interop_path(Path::new(r"/tmp/we\ird")), r"/tmp/we\ird");
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn interop_path_separates_a_windows_path_with_forward_slashes() {
+        assert_eq!(interop_path(Path::new(r"D:\a\_temp\project")), "D:/a/_temp/project");
+    }
+}

data/skills/send-private-method/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: send-private-method
+description: Remediate a `send`/`__send__` call that reaches a private method, restoring a real public seam instead of bypassing visibility. Use when send is being used to invoke private functionality in a class.
+---
+
+# Send Private Method
+
+A test calls `obj.send(:some_private_method)` (or `__send__`) to invoke a method Ruby's visibility system would otherwise forbid. `send` deliberately bypasses encapsulation. `__send__` behaves identically and is the conventional spelling when a class defines its own `send`; Ruby warns when you redefine `__send__`, but it is not un-overridable. Remediation is the same for both. The smell is not "you used `send`" — it is "the test reaches past the public API into an implementation detail," which breaks the moment the private method is renamed, reorganized, or removed even though the public contract is unchanged.
+
+## Confirm the receiver and the method
+
+You have a call site: a file path and a line number. Before changing anything, answer two questions:
+
+1. **What is the receiver's real type?** Trace the receiver expression at the flagged line back to its class. If it is a local/ivar, find where it is assigned (a `let`, `setup`, factory, or constructor).
+2. **Where is the private method defined?** Search the workspace for `def <method_name>` (and `define_method :<method_name>`). Confirm the definition is under `private` (or `private :<method_name>`). Note its enclosing class/module and read the method body — you cannot decide the fix without knowing what the method does.
+
+A name-based search matches by method *name* across the whole workspace, so a public method and a private method sharing the same unqualified name on different classes can produce a false positive. If the receiver's type has a *public* method of that name, this is not the smell — stop here.
+
+## Decide which situation you are in
+
+Read the method body and the test. Exactly one of these applies:
+
+- **The caller needs behavior that should be public.** The private method does something the application legitimately depends on, and there is no public entry point that exposes it. The encapsulation boundary was drawn too tightly.
+- **The caller is a test reaching past an existing public API.** A public method already wraps or drives this private one; the test bypassed it to assert on an intermediate result instead of the observable outcome. If the public outcome is already tested elsewhere, the private-method test is redundant — delete it rather than rewriting it.
+- **The private method is the wrong home for the logic.** The behavior is genuinely useful to more than one caller, but it lives tucked away inside one class's private section. Both production and tests want it.
+
+## Fix per situation
+
+### 1. Promote to public (or `protected`)
+
+If the behavior is part of the object's real contract, make it public and document it as API. Use `protected` only when every legitimate caller is an instance inside the same class hierarchy as the class that defines the method — never to paper over a single test's reach-in.
+
+Before:
+```ruby
+class Foo
+  def bar = qux.sum
+
+  private
+
+  def qux
+    @items.reject(&:voided?).map { |i| i.baz - i.discount }
+  end
+end
+# test
+foo.send(:qux)
+```
+
+After:
+```ruby
+class Foo
+  def bar = qux.sum
+
+  # Public: items with discounts applied, voided items excluded.
+  # Used by reporting and by #bar's total.
+  def qux
+    @items.reject(&:voided?).map { |i| i.baz - i.discount }
+  end
+end
+# test
+foo.qux
+```
+
+### 2. Drive the public entry point, assert on the observable outcome
+
+If a public method already exercises the private one, call the public method and assert on what it produces — not on the private intermediate.
+
+Before:
+```ruby
+class Foo
+  def bar(baz) = Receipt.new(tax: baz.amount * qux(baz.quux))
+
+  private
+
+  def qux(quux) = RATES.fetch(quux)
+end
+# test
+foo.send(:qux, "CA") # => 0.05
+```
+
+After:
+```ruby
+# test — assert on the observable result of the public API
+result = foo.bar(baz_with(quux: "CA", amount: 100))
+assert_equal 5.0, result.tax
+```
+
+### 3. Extract to its own object/module
+
+When the logic serves multiple callers but is trapped in one class's private section, move it to a dedicated object or module with a public interface both callers can use.
+
+Before:
+```ruby
+class Foo
+  private
+
+  def bar(raw) = raw.transform_keys(&:to_s).compact
+end
+# test
+foo.send(:bar, { baz: "Q" })
+```
+
+After:
+```ruby
+class Bar
+  def call(raw) = raw.transform_keys(&:to_s).compact
+end
+
+class Foo
+  def initialize(bar: Bar.new) = @bar = bar
+  def baz(raw) = @bar.call(raw)
+end
+# test
+assert_equal({ "baz" => "Q" }, Bar.new.call({ baz: "Q" }))
+```
+
+## Private class methods and `module_function`
+
+The three situations above cover instance methods. Two related visibility forms need special handling:
+
+- **Private class methods** (`private_class_method :bar`, or a `def bar` under `private` inside `class << self`). A bare `private` does **not** apply to `def self.bar`: that singleton method stays public wherever it sits relative to the `private` line, so a public `def self.bar` under `private` is not this smell. A `send` like `Foo.send(:bar)` reaches a genuinely private singleton method. The remediation mirrors instance methods — promote with `public_class_method :bar` (or drop the `private_class_method :bar` call), drive an existing public class method, or extract. Do not use the instance-method patterns verbatim; the fix targets the singleton class.
+- **`module_function`**. `module_function :foo` creates a public singleton method and a private instance method. If the test calls `instance.send(:foo)` on the private instance side, the public entry point already exists: call `MyModule.foo` directly. This is situation 2 — drive the public singleton method, do not promote the instance method.
+
+## Legitimate exceptions — and what to do about them
+
+Not every `send` to a private name is a smell to remove. Handle these deliberately:
+
+- **Dynamic dispatch over a validated allowlist.** The method name is genuinely computed (`send(action)`), and the action set is bounded and checked. Constrain it: define an `ALLOWED_ACTIONS = %i[...].freeze` constant, guard with `raise unless ALLOWED_ACTIONS.include?(action)`, and call `public_send(action)` so the visibility system still applies. If every allowed action is public, the smell is gone.
+- **Framework or DSL callbacks.** Some libraries require `send` to reach hooks they themselves marked private. If the method name is dictated by the framework contract, leave the call but add a one-line comment naming the framework and the callback it satisfies.
+- **Third-party code you cannot change.** The private method belongs to a gem or an owned-elsewhere class you must not edit. Wrap the reach-in behind a single named adapter method in your own code with a comment stating why (e.g. `# Sends :bar to avoid the gem's private API; remove when upstream exposes a public hook.`). The adapter localizes the violation so it is auditable and removable in one place.
+
+## What does NOT fix it
+
+Switching `send` to `public_send` on a method that is *still private* does not fix anything — it just moves the failure from "silently bypassed encapsulation" to a `NoMethodError` at runtime. Answer the encapsulation question first; only then choose `public_send` (for dynamic dispatch over public methods) or a direct call (once promoted).

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubydex
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Shopify
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-22 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
@@ -24,6 +24,8 @@ files:
 - README.md
 - THIRD_PARTY_LICENSES.html
 - exe/rdx
+- ext/rubydex/config.c
+- ext/rubydex/config.h
 - ext/rubydex/declaration.c
 - ext/rubydex/declaration.h
 - ext/rubydex/definition.c
@@ -47,8 +49,18 @@ files:
 - ext/rubydex/signature.h
 - ext/rubydex/utils.c
 - ext/rubydex/utils.h
+- lib/ruby_lsp/rubydex/addon.rb
 - lib/rubydex.rb
+- lib/rubydex/cli.rb
+- lib/rubydex/cli/command.rb
+- lib/rubydex/cli/command/console.rb
+- lib/rubydex/cli/command/lint.rb
+- lib/rubydex/cli/command/lint/explain.rb
+- lib/rubydex/cli/command/mcp.rb
+- lib/rubydex/cli/command/query.rb
+- lib/rubydex/cli/command/skill.rb
 - lib/rubydex/comment.rb
+- lib/rubydex/config.rb
 - lib/rubydex/declaration.rb
 - lib/rubydex/diagnostic.rb
 - lib/rubydex/errors.rb
@@ -56,6 +68,13 @@ files:
 - lib/rubydex/graph.rb
 - lib/rubydex/keyword.rb
 - lib/rubydex/keyword_parameter.rb
+- lib/rubydex/linter.rb
+- lib/rubydex/linter/custom_rule.rb
+- lib/rubydex/linter/helpers/path_helpers.rb
+- lib/rubydex/linter/helpers/source_access_helpers.rb
+- lib/rubydex/linter/rule_loader.rb
+- lib/rubydex/linter/rule_test_case.rb
+- lib/rubydex/linter/runner.rb
 - lib/rubydex/location.rb
 - lib/rubydex/mcp_server.rb
 - lib/rubydex/mcp_server/protocol.rb
@@ -68,8 +87,24 @@ files:
 - lib/rubydex/mcp_server/tools/search_declarations_tool.rb
 - lib/rubydex/mixin.rb
 - 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
+- lib/rubydex/skill_registry.rb
 - lib/rubydex/version.rb
+- lib/rubydex_linter/rules/rule_structure.rb
 - rbi/rubydex.rbi
 - rust/Cargo.lock
 - rust/Cargo.toml
@@ -79,6 +114,8 @@ files:
 - rust/rubydex-sys/Cargo.toml
 - rust/rubydex-sys/build.rs
 - rust/rubydex-sys/cbindgen.toml
+- rust/rubydex-sys/src/config_api.rs
+- rust/rubydex-sys/src/cypher_api.rs
 - rust/rubydex-sys/src/declaration_api.rs
 - rust/rubydex-sys/src/definition_api.rs
 - rust/rubydex-sys/src/diagnostic_api.rs
@@ -92,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
@@ -128,6 +166,7 @@ files:
 - rust/rubydex/src/operation/mod.rs
 - rust/rubydex/src/operation/printer.rs
 - rust/rubydex/src/operation/ruby_builder.rs
+- rust/rubydex/src/path_helpers.rs
 - rust/rubydex/src/position.rs
 - rust/rubydex/src/query.rs
 - rust/rubydex/src/query/cypher.rs
@@ -146,6 +185,7 @@ files:
 - rust/rubydex/src/test_utils/local_graph_test.rs
 - rust/rubydex/tests/cli.rs
 - rust/rustfmt.toml
+- skills/send-private-method/SKILL.md
 homepage: https://github.com/Shopify/rubydex
 licenses:
 - MIT