rubydex 0.2.0 → 0.2.1

data/rust/rubydex/src/query.rs

@@ -6,13 +6,14 @@ use std::thread;
 use url::Url;
 
 use crate::model::built_in::OBJECT_ID;
-use crate::model::declaration::{Ancestor, Declaration};
+use crate::model::declaration::{Ancestor, Declaration, Namespace};
 use crate::model::definitions::{Definition, Parameter};
 use crate::model::graph::Graph;
 use crate::model::identity_maps::IdentityHashSet;
 use crate::model::ids::{DeclarationId, NameId, StringId, UriId};
 use crate::model::keywords::{self, Keyword};
 use crate::model::name::NameRef;
+use crate::model::visibility::Visibility;
 
 /// Controls how declaration names are matched against the search query.
 #[derive(Default)]
@@ -169,18 +170,37 @@ pub enum CompletionCandidate {
 pub enum CompletionReceiver {
     /// Completion requested for an expression with no previous token (e.g.: at the start of a line with nothing before)
     /// Includes: all keywords, all global variables and reacheable instance variables, class variables, constants and methods
-    Expression(NameId),
+    ///
+    /// `nesting_name_id` represents the lexical scope. It is walked for constants and drives class-variable
+    /// lookup (cvars follow lexical scope in Ruby, not self).
+    /// `self_decl_id` overrides the self-type used for methods and instance variables when the runtime `self`
+    /// diverges from the innermost lexical scope — for example `def Foo.bar` (where self is `Foo` but the
+    /// lexical scope is the outer namespace) or `def self.bar`. Callers may pass a `ConstantAlias` id; it is
+    /// unwrapped to the target namespace. When `None`, self is derived from the innermost lexical scope.
+    Expression {
+        self_decl_id: Option<DeclarationId>,
+        nesting_name_id: NameId,
+    },
     /// Completion requested after a namespace access operator (e.g.: `Foo::`)
-    /// Includes: all constants and singleton methods for the namespace and its ancestors
-    NamespaceAccess(DeclarationId),
+    /// Includes: all constants and singleton methods for the namespace and its ancestors.
+    NamespaceAccess {
+        self_decl_id: Option<DeclarationId>,
+        namespace_decl_id: DeclarationId,
+    },
     /// Completion requested after a method call operator (e.g.: `foo.`, `@bar.`, `@@baz.`, `Qux.`).
     /// In the case of singleton completion (e.g.: `Foo.`), the declaration ID should be for the singleton class (i.e.: `Foo::<Foo>`)
-    /// Includes: all methods that exist on the type of the receiver and its ancestors
-    MethodCall(DeclarationId),
+    /// Includes: all methods that exist on the type of the receiver and its ancestors.
+    MethodCall {
+        self_decl_id: Option<DeclarationId>,
+        receiver_decl_id: DeclarationId,
+    },
     /// Completion requested inside a method call's argument list (e.g.: `foo.bar(|)`)
     /// Includes: everything expressions do plus keyword parameter names of the method being called
+    ///
+    /// Same `self_decl_id` / `nesting_name_id` split as `Expression`.
     MethodArgument {
-        self_name_id: NameId,
+        self_decl_id: Option<DeclarationId>,
+        nesting_name_id: NameId,
         method_decl_id: DeclarationId,
     },
 }
@@ -204,26 +224,58 @@ impl<'a> CompletionContext<'a> {
     }
 }
 
-/// Collects completion candidate members
-macro_rules! collect_candidates {
-    // Collect all members with no filtering
-    ($declaration:expr, $context:expr, $candidates:expr) => {
-        for (member_str_id, member_declaration_id) in $declaration.members() {
-            if $context.dedup(member_str_id) {
-                $candidates.push(CompletionCandidate::Declaration(*member_declaration_id));
-            }
-        }
+/// Method visibility depends both on the type of self and the current lexical scope (due to protected methods)
+fn method_visible_at_call(
+    graph: &Graph,
+    method_id: DeclarationId,
+    defined_in: DeclarationId,
+    caller_self: Option<DeclarationId>,
+    receiver: DeclarationId,
+) -> bool {
+    let Some(visibility) = graph.visibility(&method_id) else {
+        return true;
     };
-    // Collect only members matching certain kinds
-    ($graph:expr, $declaration:expr, $context:expr, $candidates:expr, $kinds:pat) => {
-        for (member_str_id, member_declaration_id) in $declaration.members() {
-            let member = $graph.declarations().get(member_declaration_id).unwrap();
 
-            if matches!(member, $kinds) && $context.dedup(member_str_id) {
-                $candidates.push(CompletionCandidate::Declaration(*member_declaration_id));
-            }
+    match visibility {
+        Visibility::Public => true,
+        Visibility::Private | Visibility::ModuleFunction => caller_self == Some(receiver),
+        Visibility::Protected => caller_self.is_some_and(|cs| {
+            let defined_in = graph.declarations().get(&defined_in).unwrap().as_namespace().unwrap();
+            let descendants = defined_in.descendants();
+            descendants.contains(&cs) && descendants.contains(&receiver)
+        }),
+    }
+}
+
+/// Walks one namespace's direct members. `kind_filter` selects the declaration kinds to surface; `visibility_filter`
+/// decides whether each surviving candidate is reachable from the access site.
+fn collect_members<'a>(
+    graph: &'a Graph,
+    namespace_id: DeclarationId,
+    kind_filter: fn(&Declaration) -> bool,
+    visibility_filter: impl Fn(DeclarationId) -> bool,
+    completion_ctx: &mut CompletionContext<'a>,
+    candidates: &mut Vec<CompletionCandidate>,
+) {
+    let namespace = graph.declarations().get(&namespace_id).unwrap().as_namespace().unwrap();
+
+    for (member_str_id, member_decl_id) in namespace.members() {
+        let member = graph.declarations().get(member_decl_id).unwrap();
+
+        if !kind_filter(member) {
+            continue;
         }
-    };
+
+        if !completion_ctx.dedup(member_str_id) {
+            continue;
+        }
+
+        if !visibility_filter(*member_decl_id) {
+            continue;
+        }
+
+        candidates.push(CompletionCandidate::Declaration(*member_decl_id));
+    }
 }
 
 /// Determines all possible completion candidates based on the current context of the cursor. There are multiple cases
@@ -233,7 +285,6 @@ macro_rules! collect_candidates {
 ///   global variables that are reacheable from the current lexical scope and self type
 /// - Expression in method arguments collects everything that expressions do and all keyword parameter names that are
 ///   applicable to the method being called
-///   everything else
 /// - Namespace access (e.g.: `Foo::`) collects all constants and singleton methods for the namespace that `Foo`
 ///   resolves to
 /// - Method calls on anything (e.g.: `foo.`, `@bar.`, `@@baz.`, `Qux.`) collects all methods that exist on the type
@@ -245,19 +296,30 @@ macro_rules! collect_candidates {
 ///
 /// # Errors
 ///
-/// Will error if the given `self_name_id` does not point to a namespace declaration
+/// Will error if the given `self_decl_id` does not resolve to a namespace declaration (directly or via
+/// a constant alias).
 pub fn completion_candidates<'a>(
     graph: &'a Graph,
     context: CompletionContext<'a>,
 ) -> Result<Vec<CompletionCandidate>, Box<dyn Error>> {
     match context.completion_receiver {
-        CompletionReceiver::Expression(self_name_id) => expression_completion(graph, self_name_id, context),
-        CompletionReceiver::NamespaceAccess(decl_id) => namespace_access_completion(graph, decl_id, context),
-        CompletionReceiver::MethodCall(decl_id) => method_call_completion(graph, decl_id, context),
+        CompletionReceiver::Expression {
+            self_decl_id,
+            nesting_name_id,
+        } => expression_completion(graph, self_decl_id, nesting_name_id, context),
+        CompletionReceiver::NamespaceAccess {
+            self_decl_id,
+            namespace_decl_id,
+        } => namespace_access_completion(graph, self_decl_id, namespace_decl_id, context),
+        CompletionReceiver::MethodCall {
+            self_decl_id,
+            receiver_decl_id,
+        } => method_call_completion(graph, self_decl_id, receiver_decl_id, context),
         CompletionReceiver::MethodArgument {
-            self_name_id,
+            self_decl_id,
+            nesting_name_id,
             method_decl_id,
-        } => method_argument_completion(graph, self_name_id, method_decl_id, context),
+        } => method_argument_completion(graph, self_decl_id, nesting_name_id, method_decl_id, context),
     }
 }
 
@@ -286,12 +348,14 @@ fn resolve_to_namespace(graph: &Graph, decl_id: DeclarationId) -> Result<Option<
 /// Collect completion for a namespace access (e.g.: `Foo::`)
 fn namespace_access_completion<'a>(
     graph: &'a Graph,
+    self_decl_id: Option<DeclarationId>,
     namespace_decl_id: DeclarationId,
     mut context: CompletionContext<'a>,
 ) -> Result<Vec<CompletionCandidate>, Box<dyn Error>> {
     let Some(resolved_id) = resolve_to_namespace(graph, namespace_decl_id)? else {
         return Ok(Vec::new());
     };
+    let resolved_caller_self_id = self_decl_id.map(|id| resolve_self_namespace(graph, id)).transpose()?;
     let namespace = graph.declarations().get(&resolved_id).unwrap().as_namespace().unwrap();
     let mut candidates = Vec::new();
 
@@ -305,26 +369,35 @@ fn namespace_access_completion<'a>(
                 break;
             }
 
-            let ancestor_decl = graph.declarations().get(ancestor_id).unwrap().as_namespace().unwrap();
-
-            collect_candidates!(
+            collect_members(
                 graph,
-                &ancestor_decl,
-                context,
-                candidates,
-                Declaration::Namespace(_) | Declaration::Constant(_) | Declaration::ConstantAlias(_)
+                *ancestor_id,
+                |d| d.as_namespace().is_some() || d.as_constant().is_some() || d.as_constant_alias().is_some(),
+                |id| !matches!(graph.visibility(&id), Some(Visibility::Private)),
+                &mut context,
+                &mut candidates,
             );
         }
     }
 
-    // Collect singleton methods from the singleton class and its ancestors
+    // The receiver of an explicit `Foo::` call is the singleton class, so visibility checks
+    // compare against it (not against `Foo` itself).
     if let Some(singleton_id) = namespace.singleton_class() {
         let singleton = graph.declarations().get(singleton_id).unwrap().as_namespace().unwrap();
+        let receiver = *singleton_id;
 
         for ancestor in singleton.ancestors() {
             if let Ancestor::Complete(ancestor_id) = ancestor {
-                let ancestor_decl = graph.declarations().get(ancestor_id).unwrap().as_namespace().unwrap();
-                collect_candidates!(graph, &ancestor_decl, context, candidates, Declaration::Method(_));
+                let defined_in = *ancestor_id;
+
+                collect_members(
+                    graph,
+                    defined_in,
+                    |d| d.as_method().is_some(),
+                    |id| method_visible_at_call(graph, id, defined_in, resolved_caller_self_id, receiver),
+                    &mut context,
+                    &mut candidates,
+                );
             }
         }
     }
@@ -335,117 +408,248 @@ fn namespace_access_completion<'a>(
 /// Collect completion for a method call (e.g.: `foo.`, `@bar.`, `Baz.`)
 fn method_call_completion<'a>(
     graph: &'a Graph,
+    self_decl_id: Option<DeclarationId>,
     receiver_decl_id: DeclarationId,
     mut context: CompletionContext<'a>,
 ) -> Result<Vec<CompletionCandidate>, Box<dyn Error>> {
     let Some(resolved_id) = resolve_to_namespace(graph, receiver_decl_id)? else {
         return Ok(Vec::new());
     };
+    let resolved_caller_self_id = self_decl_id.map(|id| resolve_self_namespace(graph, id)).transpose()?;
     let namespace = graph.declarations().get(&resolved_id).unwrap().as_namespace().unwrap();
     let mut candidates = Vec::new();
 
     for ancestor in namespace.ancestors() {
         if let Ancestor::Complete(ancestor_id) = ancestor {
-            let ancestor_decl = graph.declarations().get(ancestor_id).unwrap().as_namespace().unwrap();
-            collect_candidates!(graph, &ancestor_decl, context, candidates, Declaration::Method(_));
+            let defined_in = *ancestor_id;
+            collect_members(
+                graph,
+                defined_in,
+                |d| d.as_method().is_some(),
+                |id| method_visible_at_call(graph, id, defined_in, resolved_caller_self_id, resolved_id),
+                &mut context,
+                &mut candidates,
+            );
         }
     }
 
     Ok(candidates)
 }
 
+fn resolve_self_namespace(graph: &Graph, decl_id: DeclarationId) -> Result<DeclarationId, Box<dyn Error>> {
+    resolve_to_namespace(graph, decl_id)?
+        .ok_or_else(|| format!("self declaration {decl_id:?} not found in graph").into())
+}
+
 /// Collect completion for an expression
 fn expression_completion<'a>(
     graph: &'a Graph,
-    self_name_id: NameId,
+    self_decl_id: Option<DeclarationId>,
+    nesting_name_id: NameId,
     mut context: CompletionContext<'a>,
 ) -> Result<Vec<CompletionCandidate>, Box<dyn Error>> {
-    let Some(name_ref) = graph.names().get(&self_name_id) else {
-        return Err(format!("Name {self_name_id} not found in graph").into());
+    let Some(name_ref) = graph.names().get(&nesting_name_id) else {
+        return Err(format!("Name {nesting_name_id} not found in graph").into());
     };
     let NameRef::Resolved(name_ref) = name_ref else {
-        return Err(format!("Expected name {self_name_id} to be resolved").into());
+        return Err(format!("Expected name {nesting_name_id} to be resolved").into());
+    };
+    // When no explicit self is given, self is the innermost lexical scope (the nesting's own declaration).
+    // When explicit, follow constant aliases so callers can pass whatever the expression that set self
+    // resolves to without having to unwrap aliases themselves. Missing or non-namespace decls are graph
+    // inconsistencies and surfaced as errors.
+    let resolved_self_decl_id = match self_decl_id {
+        Some(id) => resolve_self_namespace(graph, id)?,
+        None => *name_ref.declaration_id(),
     };
-    let Some(self_decl) = graph
+    let self_decl = graph
+        .declarations()
+        .get(&resolved_self_decl_id)
+        .unwrap()
+        .as_namespace()
+        .ok_or("Expected associated declaration to be a namespace")?;
+    let innermost_lexical_decl = graph
         .declarations()
         .get(name_ref.declaration_id())
-        .and_then(|d| d.as_namespace())
-    else {
-        return Err("Expected associated declaration to be a namespace".into());
-    };
+        .unwrap()
+        .as_namespace()
+        .unwrap();
+
     let mut candidates = Vec::new();
 
-    // Walk the name's lexical scopes, collecting all constant completion members
-    let mut current_name_id = Some(self_name_id);
+    // Collect constants. Immediate scope includes inheritance. Outer scopes only include `Object` inheritance when it's a module
+    collect_constants_from_lexical_scope(graph, innermost_lexical_decl, &mut context, &mut candidates);
+    collect_constants_from_outer_nesting(graph, name_ref, &mut context, &mut candidates);
 
-    while let Some(id) = current_name_id {
-        let NameRef::Resolved(name_ref) = graph.names().get(&id).unwrap() else {
-            break;
-        };
+    // Collect class variables, which are based on the inheritance chain of the attached object of the immediate lexical scope
+    collect_class_variables_from_lexical_scope(graph, name_ref, &mut context, &mut candidates);
+
+    // Globals are accessible from anywhere, regardless of lexical scope or `self` type.
+    collect_members(
+        graph,
+        *OBJECT_ID,
+        |d| d.as_global_variable().is_some(),
+        |_| true,
+        &mut context,
+        &mut candidates,
+    );
+
+    // Collect methods and instance variables, which are based on the inheritance chain of the `self` type (which may
+    // not match the immediate lexical scope)
+    collect_methods_and_ivars_from_self(graph, self_decl, &mut context, &mut candidates);
+
+    // Keywords are always available in expression contexts
+    candidates.extend(keywords::KEYWORDS.iter().map(CompletionCandidate::Keyword));
+    Ok(candidates)
+}
+
+/// Collects constants reachable from the innermost lexical scope's ancestor chain. Module bodies also fall back to
+/// `Object`'s ancestor chain to mirror Ruby's resolution rules.
+fn collect_constants_from_lexical_scope<'a>(
+    graph: &'a Graph,
+    innermost_lexical_decl: &'a Namespace,
+    context: &mut CompletionContext<'a>,
+    candidates: &mut Vec<CompletionCandidate>,
+) {
+    for ancestor in innermost_lexical_decl.ancestors() {
+        if let Ancestor::Complete(ancestor_id) = ancestor {
+            collect_members(
+                graph,
+                *ancestor_id,
+                |d| d.as_namespace().is_some() || d.as_constant().is_some() || d.as_constant_alias().is_some(),
+                |_| true,
+                context,
+                candidates,
+            );
+        }
+    }
+
+    if matches!(innermost_lexical_decl, Namespace::Module(_)) {
+        let object = graph.declarations().get(&OBJECT_ID).unwrap().as_namespace().unwrap();
+
+        for ancestor in object.ancestors() {
+            if let Ancestor::Complete(ancestor_id) = ancestor {
+                collect_members(
+                    graph,
+                    *ancestor_id,
+                    |d| d.as_namespace().is_some() || d.as_constant().is_some() || d.as_constant_alias().is_some(),
+                    |_| true,
+                    context,
+                    candidates,
+                );
+            }
+        }
+    }
+}
+
+/// Collects class variables visible from the current lexical scope. Class variables are resolved
+/// lexically and singleton classes are skipped: inside `class Bar; class << Foo; @@cvar` the
+/// cvar belongs to `Bar`, not `Foo`. We walk the lexical chain (innermost outward) until we find
+/// a non-singleton namespace, then walk that namespace's ancestors.
+fn collect_class_variables_from_lexical_scope<'a>(
+    graph: &'a Graph,
+    name_ref: &crate::model::name::ResolvedName,
+    context: &mut CompletionContext<'a>,
+    candidates: &mut Vec<CompletionCandidate>,
+) {
+    let mut decl = graph
+        .declarations()
+        .get(name_ref.declaration_id())
+        .unwrap()
+        .as_namespace()
+        .unwrap();
+    let mut current_name_id = *name_ref.nesting();
 
-        let nesting_decl = graph
+    while matches!(decl, Namespace::SingletonClass(_)) {
+        let Some(parent_name_id) = current_name_id else {
+            // No non-singleton lexical scope (invalid Ruby). Skip cvar collection.
+            return;
+        };
+        let NameRef::Resolved(parent_ref) = graph.names().get(&parent_name_id).unwrap() else {
+            return;
+        };
+        decl = graph
             .declarations()
-            .get(name_ref.declaration_id())
+            .get(parent_ref.declaration_id())
             .unwrap()
             .as_namespace()
             .unwrap();
+        current_name_id = *parent_ref.nesting();
+    }
+
+    for ancestor in decl.ancestors() {
+        if let Ancestor::Complete(ancestor_id) = ancestor {
+            collect_members(
+                graph,
+                *ancestor_id,
+                |d| d.as_class_variable().is_some(),
+                |_| true,
+                context,
+                candidates,
+            );
+        }
+    }
+}
+
+/// Walks the outer lexical nesting chain (excluding the innermost scope) to collect constants reachable through
+/// enclosing classes/modules.
+fn collect_constants_from_outer_nesting<'a>(
+    graph: &'a Graph,
+    name_ref: &crate::model::name::ResolvedName,
+    context: &mut CompletionContext<'a>,
+    candidates: &mut Vec<CompletionCandidate>,
+) {
+    let mut current_name_id = *name_ref.nesting();
+
+    while let Some(id) = current_name_id {
+        let NameRef::Resolved(parent_ref) = graph.names().get(&id).unwrap() else {
+            break;
+        };
 
-        collect_candidates!(
+        collect_members(
             graph,
-            &nesting_decl,
+            *parent_ref.declaration_id(),
+            |d| d.as_namespace().is_some() || d.as_constant().is_some() || d.as_constant_alias().is_some(),
+            |_| true,
             context,
             candidates,
-            Declaration::Namespace(_) | Declaration::Constant(_) | Declaration::ConstantAlias(_)
         );
 
-        current_name_id = *name_ref.nesting();
+        current_name_id = *parent_ref.nesting();
     }
+}
 
-    // Include all top level constants and globals, which are accessible everywhere
-    let object = graph.declarations().get(&OBJECT_ID).unwrap().as_namespace().unwrap();
-    collect_candidates!(
-        graph,
-        &object,
-        context,
-        candidates,
-        Declaration::Namespace(_)
-            | Declaration::Constant(_)
-            | Declaration::ConstantAlias(_)
-            | Declaration::GlobalVariable(_)
-    );
-
-    // Walk ancestors collecting all applicable completion members
+/// Collects methods and instance variables along `self`'s ancestor chain. The chain may differ
+/// from the lexical chain when `self` was rebound (e.g., `def Foo.baz` written inside `class Bar`).
+fn collect_methods_and_ivars_from_self<'a>(
+    graph: &'a Graph,
+    self_decl: &'a Namespace,
+    context: &mut CompletionContext<'a>,
+    candidates: &mut Vec<CompletionCandidate>,
+) {
     for ancestor in self_decl.ancestors() {
         if let Ancestor::Complete(ancestor_id) = ancestor {
-            let ancestor_decl = graph.declarations().get(ancestor_id).unwrap().as_namespace().unwrap();
-            collect_candidates!(&ancestor_decl, context, candidates);
-
-            // Collect class variables from the attached object, which are available at any singleton class level
-            // within self
-            let attached_object = graph.attached_object(ancestor_decl);
-            collect_candidates!(
+            collect_members(
                 graph,
-                &attached_object,
+                *ancestor_id,
+                |d| d.as_method().is_some() || d.as_instance_variable().is_some(),
+                |_| true,
                 context,
                 candidates,
-                Declaration::ClassVariable(_)
             );
         }
     }
-
-    // Keywords are always available in expression contexts
-    candidates.extend(keywords::KEYWORDS.iter().map(CompletionCandidate::Keyword));
-    Ok(candidates)
 }
 
 /// Collect completion for a method argument (e.g.: `foo.bar(|)`)
 fn method_argument_completion<'a>(
     graph: &'a Graph,
-    self_name_id: NameId,
+    self_decl_id: Option<DeclarationId>,
+    nesting_name_id: NameId,
     method_decl_id: DeclarationId,
     context: CompletionContext<'a>,
 ) -> Result<Vec<CompletionCandidate>, Box<dyn Error>> {
-    let mut candidates = expression_completion(graph, self_name_id, context)?;
+    let mut candidates = expression_completion(graph, self_decl_id, nesting_name_id, context)?;
     let Some(method_decl) = graph.declarations().get(&method_decl_id) else {
         return Ok(candidates);
     };
@@ -523,30 +727,37 @@ mod tests {
 
     macro_rules! assert_completion_eq {
         ($context:expr, $receiver:expr, $expected:expr) => {
-            assert_eq!(
-                $expected,
-                *completion_candidates($context.graph(), CompletionContext::new($receiver))
-                    .unwrap()
-                    .iter()
-                    .map(|candidate| candidate_label(&$context, candidate))
-                    .collect::<Vec<_>>()
-            );
+            let mut actual: Vec<String> = completion_candidates($context.graph(), CompletionContext::new($receiver))
+                .unwrap()
+                .iter()
+                .map(|candidate| candidate_label(&$context, candidate))
+                .collect();
+            actual.sort();
+
+            let mut expected: Vec<String> = $expected.into_iter().map(String::from).collect();
+            expected.sort();
+
+            assert_eq!(expected, actual);
         };
     }
 
     /// Asserts declaration and keyword argument completion candidates, excluding language keywords.
     /// Language keywords are always present in expression contexts and tested separately.
+    /// Both sides are sorted before comparison so tests are not coupled to candidate emission order.
     macro_rules! assert_declaration_completion_eq {
         ($context:expr, $receiver:expr, $expected:expr) => {
-            assert_eq!(
-                $expected,
-                *completion_candidates($context.graph(), CompletionContext::new($receiver))
-                    .unwrap()
-                    .iter()
-                    .filter(|c| !matches!(c, CompletionCandidate::Keyword(_)))
-                    .map(|candidate| candidate_label(&$context, candidate))
-                    .collect::<Vec<_>>()
-            );
+            let mut actual: Vec<String> = completion_candidates($context.graph(), CompletionContext::new($receiver))
+                .unwrap()
+                .iter()
+                .filter(|c| !matches!(c, CompletionCandidate::Keyword(_)))
+                .map(|candidate| candidate_label(&$context, candidate))
+                .collect();
+            actual.sort();
+
+            let mut expected: Vec<String> = $expected.into_iter().map(String::from).collect();
+            expected.sort();
+
+            assert_eq!(expected, actual);
         };
     }
 
@@ -761,8 +972,12 @@ mod tests {
         let name_id = Name::new(StringId::from("Child"), ParentScope::None, None).id();
         assert_declaration_completion_eq!(
             context,
-            CompletionReceiver::Expression(name_id),
+            CompletionReceiver::Expression {
+                self_decl_id: None,
+                nesting_name_id: name_id,
+            },
             [
+                "Foo::CONST",
                 "Class",
                 "BasicObject",
                 "Child",
@@ -772,7 +987,6 @@ mod tests {
                 "Foo",
                 "Object",
                 "Child#baz()",
-                "Foo::CONST",
                 "Foo#bar()",
                 "Parent#initialize()",
                 "Parent#@var"
@@ -807,7 +1021,10 @@ mod tests {
         let name_id = Name::new(StringId::from("Child"), ParentScope::None, None).id();
         assert_declaration_completion_eq!(
             context,
-            CompletionReceiver::Expression(name_id),
+            CompletionReceiver::Expression {
+                self_decl_id: None,
+                nesting_name_id: name_id,
+            },
             [
                 "Class",
                 "BasicObject",
@@ -853,7 +1070,10 @@ mod tests {
         let name_id = Name::new(StringId::from("Foo"), ParentScope::None, None).id();
         assert_declaration_completion_eq!(
             context,
-            CompletionReceiver::Expression(name_id),
+            CompletionReceiver::Expression {
+                self_decl_id: None,
+                nesting_name_id: name_id,
+            },
             [
                 "Foo",
                 "Class",
@@ -900,7 +1120,10 @@ mod tests {
         let name_id = Name::new(StringId::from("<Foo>"), ParentScope::Attached(foo_id), Some(foo_id)).id();
         assert_declaration_completion_eq!(
             context,
-            CompletionReceiver::Expression(name_id),
+            CompletionReceiver::Expression {
+                self_decl_id: None,
+                nesting_name_id: name_id,
+            },
             [
                 "Module",
                 "Class",
@@ -917,7 +1140,10 @@ mod tests {
         let name_id = Name::new(StringId::from("Bar"), ParentScope::None, None).id();
         assert_declaration_completion_eq!(
             context,
-            CompletionReceiver::Expression(name_id),
+            CompletionReceiver::Expression {
+                self_decl_id: None,
+                nesting_name_id: name_id,
+            },
             [
                 "Module",
                 "Class",
@@ -966,9 +1192,11 @@ mod tests {
         .id();
         assert_declaration_completion_eq!(
             context,
-            CompletionReceiver::Expression(name_id),
+            CompletionReceiver::Expression {
+                self_decl_id: None,
+                nesting_name_id: name_id,
+            },
             [
-                "Foo::CONST_A",
                 "Module",
                 "Class",
                 "Object",
@@ -976,6 +1204,7 @@ mod tests {
                 "Kernel",
                 "Foo",
                 "Bar",
+                "Foo::CONST_A",
                 "Bar#bar_m()",
                 "Bar#bar_m2()"
             ]
@@ -984,7 +1213,10 @@ mod tests {
         let name_id = Name::new(StringId::from("Bar"), ParentScope::None, None).id();
         assert_declaration_completion_eq!(
             context,
-            CompletionReceiver::Expression(name_id),
+            CompletionReceiver::Expression {
+                self_decl_id: None,
+                nesting_name_id: name_id,
+            },
             [
                 "Module",
                 "Class",
@@ -1025,16 +1257,19 @@ mod tests {
         // when the user types the unqualified name CONST
         assert_declaration_completion_eq!(
             context,
-            CompletionReceiver::Expression(name_id),
+            CompletionReceiver::Expression {
+                self_decl_id: None,
+                nesting_name_id: name_id,
+            },
             [
-                "Foo::CONST",
-                "Foo::Bar",
                 "Class",
                 "Object",
                 "BasicObject",
                 "Kernel",
                 "Foo",
                 "Module",
+                "Foo::CONST",
+                "Foo::Bar",
                 "Foo::Bar#baz()"
             ]
         );
@@ -1069,19 +1304,11 @@ mod tests {
         .id();
         assert_declaration_completion_eq!(
             context,
-            CompletionReceiver::Expression(name_id),
-            [
-                "Foo::Bar",
-                "$var2",
-                "$var",
-                "BasicObject",
-                "Object",
-                "Kernel",
-                "Module",
-                "Foo",
-                "Class",
-                "Foo::Bar#bar_m()"
-            ]
+            CompletionReceiver::Expression {
+                self_decl_id: None,
+                nesting_name_id: name_id,
+            },
+            ["Foo::Bar", "$var2", "$var", "Foo::Bar#bar_m()"]
         );
     }
 
@@ -1108,7 +1335,10 @@ mod tests {
 
         assert_completion_eq!(
             context,
-            CompletionReceiver::NamespaceAccess(DeclarationId::from("Foo")),
+            CompletionReceiver::NamespaceAccess {
+                self_decl_id: None,
+                namespace_decl_id: DeclarationId::from("Foo")
+            },
             ["Foo::CONST", "Foo::Bar", "Foo::<Foo>#class_method()"]
         );
     }
@@ -1141,7 +1371,10 @@ mod tests {
 
         assert_completion_eq!(
             context,
-            CompletionReceiver::NamespaceAccess(DeclarationId::from("Child")),
+            CompletionReceiver::NamespaceAccess {
+                self_decl_id: None,
+                namespace_decl_id: DeclarationId::from("Child")
+            },
             [
                 "Child::CHILD_CONST",
                 "Parent::PARENT_CONST",
@@ -1179,7 +1412,10 @@ mod tests {
 
         assert_completion_eq!(
             context,
-            CompletionReceiver::NamespaceAccess(DeclarationId::from("Child")),
+            CompletionReceiver::NamespaceAccess {
+                self_decl_id: None,
+                namespace_decl_id: DeclarationId::from("Child")
+            },
             ["Child::CONST", "Child::<Child>#shared_method()"]
         );
     }
@@ -1202,7 +1438,10 @@ mod tests {
 
         assert_completion_eq!(
             context,
-            CompletionReceiver::NamespaceAccess(DeclarationId::from("Foo")),
+            CompletionReceiver::NamespaceAccess {
+                self_decl_id: None,
+                namespace_decl_id: DeclarationId::from("Foo")
+            },
             ["Foo::CONST"]
         );
     }
@@ -1224,7 +1463,10 @@ mod tests {
 
         assert_completion_eq!(
             context,
-            CompletionReceiver::NamespaceAccess(DeclarationId::from("Foo")),
+            CompletionReceiver::NamespaceAccess {
+                self_decl_id: None,
+                namespace_decl_id: DeclarationId::from("Foo")
+            },
             ["Foo::CONST", "Foo::Bar"]
         );
     }
@@ -1254,7 +1496,10 @@ mod tests {
 
         assert_completion_eq!(
             context,
-            CompletionReceiver::NamespaceAccess(DeclarationId::from("Foo::MyOriginal")),
+            CompletionReceiver::NamespaceAccess {
+                self_decl_id: None,
+                namespace_decl_id: DeclarationId::from("Foo::MyOriginal")
+            },
             [
                 "Original::CONST",
                 "Original::Nested",
@@ -1286,7 +1531,10 @@ mod tests {
 
         assert_completion_eq!(
             context,
-            CompletionReceiver::NamespaceAccess(DeclarationId::from("Alias2")),
+            CompletionReceiver::NamespaceAccess {
+                self_decl_id: None,
+                namespace_decl_id: DeclarationId::from("Alias2")
+            },
             ["Original::CONST", "Original::<Original>#class_method()"]
         );
     }
@@ -1313,7 +1561,10 @@ mod tests {
 
         assert_completion_eq!(
             context,
-            CompletionReceiver::NamespaceAccess(DeclarationId::from("Foo")),
+            CompletionReceiver::NamespaceAccess {
+                self_decl_id: None,
+                namespace_decl_id: DeclarationId::from("Foo")
+            },
             ["Foo::CONST", "Foo::<Foo>#class_method()"]
         );
     }
@@ -1347,7 +1598,10 @@ mod tests {
 
         assert_completion_eq!(
             context,
-            CompletionReceiver::NamespaceAccess(DeclarationId::from("Foo")),
+            CompletionReceiver::NamespaceAccess {
+                self_decl_id: None,
+                namespace_decl_id: DeclarationId::from("Foo")
+            },
             ["Foo::FOO_CONST", "Bar::CONST", "Foo::<Foo>#foo_class_method()"]
         );
     }
@@ -1375,7 +1629,10 @@ mod tests {
 
         assert_completion_eq!(
             context,
-            CompletionReceiver::MethodCall(DeclarationId::from("Foo")),
+            CompletionReceiver::MethodCall {
+                self_decl_id: None,
+                receiver_decl_id: DeclarationId::from("Foo")
+            },
             ["Foo#baz()", "Foo#bar()"]
         );
     }
@@ -1405,7 +1662,10 @@ mod tests {
 
         assert_completion_eq!(
             context,
-            CompletionReceiver::MethodCall(DeclarationId::from("Foo::MyOriginal")),
+            CompletionReceiver::MethodCall {
+                self_decl_id: None,
+                receiver_decl_id: DeclarationId::from("Foo::MyOriginal")
+            },
             ["Original#baz()", "Original#bar()"]
         );
     }
@@ -1430,7 +1690,10 @@ mod tests {
 
         assert_completion_eq!(
             context,
-            CompletionReceiver::MethodCall(DeclarationId::from("Child")),
+            CompletionReceiver::MethodCall {
+                self_decl_id: None,
+                receiver_decl_id: DeclarationId::from("Child")
+            },
             ["Child#child_method()", "Parent#parent_method()"]
         );
     }
@@ -1457,7 +1720,10 @@ mod tests {
 
         assert_completion_eq!(
             context,
-            CompletionReceiver::MethodCall(DeclarationId::from("Foo")),
+            CompletionReceiver::MethodCall {
+                self_decl_id: None,
+                receiver_decl_id: DeclarationId::from("Foo")
+            },
             ["Foo#foo_method()", "Mixin#mixin_method()"]
         );
     }
@@ -1484,7 +1750,10 @@ mod tests {
 
         assert_completion_eq!(
             context,
-            CompletionReceiver::MethodCall(DeclarationId::from("Child")),
+            CompletionReceiver::MethodCall {
+                self_decl_id: None,
+                receiver_decl_id: DeclarationId::from("Child")
+            },
             ["Child#shared_method()", "Child#child_only()", "Parent#parent_only()"]
         );
     }
@@ -1512,7 +1781,10 @@ mod tests {
 
         assert_completion_eq!(
             context,
-            CompletionReceiver::MethodCall(DeclarationId::from("Foo")),
+            CompletionReceiver::MethodCall {
+                self_decl_id: None,
+                receiver_decl_id: DeclarationId::from("Foo")
+            },
             ["Foo#initialize()", "Foo#bar()"]
         );
     }
@@ -1537,7 +1809,10 @@ mod tests {
 
         assert_completion_eq!(
             context,
-            CompletionReceiver::MethodCall(DeclarationId::from("Foo::<Foo>")),
+            CompletionReceiver::MethodCall {
+                self_decl_id: None,
+                receiver_decl_id: DeclarationId::from("Foo::<Foo>")
+            },
             ["Foo::<Foo>#baz()", "Foo::<Foo>#bar()"]
         );
     }
@@ -1560,7 +1835,8 @@ mod tests {
         assert_declaration_completion_eq!(
             context,
             CompletionReceiver::MethodArgument {
-                self_name_id: name_id,
+                self_decl_id: None,
+                nesting_name_id: name_id,
                 method_decl_id: DeclarationId::from("Foo#greet()"),
             },
             [
@@ -1595,7 +1871,8 @@ mod tests {
         assert_declaration_completion_eq!(
             context,
             CompletionReceiver::MethodArgument {
-                self_name_id: name_id,
+                self_decl_id: None,
+                nesting_name_id: name_id,
                 method_decl_id: DeclarationId::from("Foo#bar()"),
             },
             ["Class", "Object", "BasicObject", "Kernel", "Foo", "Module", "Foo#bar()"]
@@ -1620,7 +1897,8 @@ mod tests {
         assert_declaration_completion_eq!(
             context,
             CompletionReceiver::MethodArgument {
-                self_name_id: name_id,
+                self_decl_id: None,
+                nesting_name_id: name_id,
                 method_decl_id: DeclarationId::from("Foo#search()"),
             },
             // Only RequiredKeyword and OptionalKeyword, not RestKeyword (**opts)
@@ -1663,7 +1941,8 @@ mod tests {
         assert_declaration_completion_eq!(
             context,
             CompletionReceiver::MethodArgument {
-                self_name_id: name_id,
+                self_decl_id: None,
+                nesting_name_id: name_id,
                 method_decl_id: DeclarationId::from("Foo#bar()"),
             },
             [
@@ -1689,7 +1968,10 @@ mod tests {
         let name_id = Name::new(StringId::from("Foo"), ParentScope::None, None).id();
         assert_completion_eq!(
             context,
-            CompletionReceiver::Expression(name_id),
+            CompletionReceiver::Expression {
+                self_decl_id: None,
+                nesting_name_id: name_id,
+            },
             [
                 "Class",
                 "Object",
@@ -1752,7 +2034,8 @@ mod tests {
         assert_completion_eq!(
             context,
             CompletionReceiver::MethodArgument {
-                self_name_id: name_id,
+                self_decl_id: None,
+                nesting_name_id: name_id,
                 method_decl_id: DeclarationId::from("Foo#bar()"),
             },
             [
@@ -1817,7 +2100,10 @@ mod tests {
 
         let candidates = completion_candidates(
             context.graph(),
-            CompletionContext::new(CompletionReceiver::NamespaceAccess(DeclarationId::from("Foo"))),
+            CompletionContext::new(CompletionReceiver::NamespaceAccess {
+                self_decl_id: None,
+                namespace_decl_id: DeclarationId::from("Foo"),
+            }),
         )
         .unwrap();
 
@@ -1832,10 +2118,1040 @@ mod tests {
 
         let candidates = completion_candidates(
             context.graph(),
-            CompletionContext::new(CompletionReceiver::MethodCall(DeclarationId::from("Foo"))),
+            CompletionContext::new(CompletionReceiver::MethodCall {
+                self_decl_id: None,
+                receiver_decl_id: DeclarationId::from("Foo"),
+            }),
         )
         .unwrap();
 
         assert!(!candidates.iter().any(|c| matches!(c, CompletionCandidate::Keyword(_))));
     }
+
+    #[test]
+    fn expression_completion_class_variables_follow_lexical_scope() {
+        // `@@cvar` in Ruby is resolved via the innermost lexical class/module's ancestor chain,
+        // NOT `self`'s ancestor chain. Inside `def Foo.bar` written inside `Outer`, the lexical
+        // scope is `[Outer]`, so `@@outer_cvar` is reachable and `@@foo_cvar` (which lives on
+        // `Foo`, not on any lexical ancestor) must not be offered.
+        let mut context = GraphTest::new();
+
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            module Outer
+              @@outer_cvar = 1
+
+              class Foo
+                @@foo_cvar = 2
+                def self.singleton_m; end
+              end
+            end
+            ",
+        );
+        context.resolve();
+
+        let outer_name_id = Name::new(StringId::from("Outer"), ParentScope::None, None).id();
+        assert_declaration_completion_eq!(
+            context,
+            CompletionReceiver::Expression {
+                self_decl_id: Some(DeclarationId::from("Outer::Foo::<Foo>")),
+                nesting_name_id: outer_name_id,
+            },
+            [
+                "Module",
+                "Class",
+                "Object",
+                "BasicObject",
+                "Kernel",
+                "Outer",
+                "Outer::Foo",
+                "Outer#@@outer_cvar",
+                "Outer::Foo::<Foo>#singleton_m()"
+            ]
+        );
+    }
+
+    #[test]
+    fn expression_completion_follows_self_decl_alias() {
+        let mut context = GraphTest::new();
+
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            module Outer
+              class Original
+                def original_m; end
+              end
+
+              MyAlias = Original
+            end
+            ",
+        );
+        context.resolve();
+
+        let name_id = Name::new(StringId::from("Outer"), ParentScope::None, None).id();
+        // `self_decl_id` points to the alias `Outer::MyAlias`, which is a `ConstantAlias` rather than a `Namespace`.
+        // The completion should still collect members from the aliased namespace (`Outer::Original`) instead of
+        // returning an error, so callers do not have to unwrap aliases themselves.
+        assert_declaration_completion_eq!(
+            context,
+            CompletionReceiver::Expression {
+                self_decl_id: Some(DeclarationId::from("Outer::MyAlias")),
+                nesting_name_id: name_id,
+            },
+            [
+                "Outer::MyAlias",
+                "Outer::Original",
+                "Class",
+                "Object",
+                "BasicObject",
+                "Outer",
+                "Kernel",
+                "Module",
+                "Outer::Original#original_m()"
+            ]
+        );
+    }
+
+    #[test]
+    fn expression_completion_in_method_definition_with_receiver_uses_lexical_scope_for_class_variables() {
+        let mut context = GraphTest::new();
+
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            class Foo
+              @@class_var = 1
+            end
+
+            class Bar
+              @@other_class_var = 2
+
+              def Foo.baz
+                # completion here
+              end
+            end
+            ",
+        );
+        context.resolve();
+
+        let name_id = Name::new(StringId::from("Bar"), ParentScope::None, None).id();
+        assert_declaration_completion_eq!(
+            context,
+            CompletionReceiver::Expression {
+                self_decl_id: Some(DeclarationId::from("Foo::<Foo>")),
+                nesting_name_id: name_id,
+            },
+            [
+                "Module",
+                "Class",
+                "Object",
+                "BasicObject",
+                "Kernel",
+                "Foo",
+                "Bar",
+                "Foo::<Foo>#baz()",
+                "Bar#@@other_class_var"
+            ]
+        );
+    }
+
+    #[test]
+    fn expression_completion_in_method_definition_with_receiver_uses_lexical_scope_for_constants() {
+        let mut context = GraphTest::new();
+
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            class Foo
+              CONST = 1
+            end
+
+            class Bar
+              OTHER_CONST = 2
+
+              def Foo.baz
+                # completion here
+              end
+            end
+            ",
+        );
+        context.resolve();
+
+        let name_id = Name::new(StringId::from("Bar"), ParentScope::None, None).id();
+        assert_declaration_completion_eq!(
+            context,
+            CompletionReceiver::Expression {
+                self_decl_id: Some(DeclarationId::from("Foo::<Foo>")),
+                nesting_name_id: name_id,
+            },
+            [
+                "Bar::OTHER_CONST",
+                "Module",
+                "Class",
+                "Object",
+                "BasicObject",
+                "Kernel",
+                "Foo",
+                "Bar",
+                "Foo::<Foo>#baz()"
+            ]
+        );
+    }
+
+    #[test]
+    fn expression_completion_does_not_leak_constants_reachable_only_through_self_ancestors() {
+        let mut context = GraphTest::new();
+
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            module Mixin
+              MIXIN_CONST = 1
+            end
+
+            class Foo
+              extend Mixin
+            end
+
+            class Bar
+              def Foo.baz
+                # completion here
+              end
+            end
+            ",
+        );
+        context.resolve();
+
+        let name_id = Name::new(StringId::from("Bar"), ParentScope::None, None).id();
+        assert_declaration_completion_eq!(
+            context,
+            CompletionReceiver::Expression {
+                self_decl_id: Some(DeclarationId::from("Foo::<Foo>")),
+                nesting_name_id: name_id,
+            },
+            [
+                "Class",
+                "BasicObject",
+                "Mixin",
+                "Object",
+                "Kernel",
+                "Module",
+                "Foo",
+                "Bar",
+                "Foo::<Foo>#baz()"
+            ]
+        );
+    }
+
+    #[test]
+    fn expression_completion_at_top_level_includes_object_constants() {
+        let mut context = GraphTest::new();
+
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            class Foo
+              CONST = 1
+            end
+
+            TOP_CONST = 2
+            ",
+        );
+        context.resolve();
+
+        let name_id = Name::new(StringId::from("Object"), ParentScope::None, None).id();
+        assert_declaration_completion_eq!(
+            context,
+            CompletionReceiver::Expression {
+                self_decl_id: None,
+                nesting_name_id: name_id,
+            },
+            ["Module", "Class", "Object", "BasicObject", "Kernel", "Foo", "TOP_CONST"]
+        );
+    }
+
+    #[test]
+    fn expression_completion_in_module_body_falls_back_to_object_constants() {
+        let mut context = GraphTest::new();
+
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            TOP_CONST = 1
+
+            module Mod
+              MOD_CONST = 2
+            end
+            ",
+        );
+        context.resolve();
+
+        let name_id = Name::new(StringId::from("Mod"), ParentScope::None, None).id();
+        assert_declaration_completion_eq!(
+            context,
+            CompletionReceiver::Expression {
+                self_decl_id: None,
+                nesting_name_id: name_id,
+            },
+            [
+                "Mod::MOD_CONST",
+                "Module",
+                "Class",
+                "Object",
+                "BasicObject",
+                "Kernel",
+                "TOP_CONST",
+                "Mod"
+            ]
+        );
+    }
+
+    #[test]
+    fn expression_completion_in_module_body_falls_back_to_object_ancestors() {
+        let mut context = GraphTest::new();
+
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            module Kernel
+              CONST = 1
+            end
+
+            module Mod
+              # completion here
+            end
+            ",
+        );
+        context.resolve();
+
+        let name_id = Name::new(StringId::from("Mod"), ParentScope::None, None).id();
+        assert_declaration_completion_eq!(
+            context,
+            CompletionReceiver::Expression {
+                self_decl_id: None,
+                nesting_name_id: name_id,
+            },
+            [
+                "Class",
+                "Object",
+                "Kernel",
+                "BasicObject",
+                "Mod",
+                "Module",
+                "Kernel::CONST",
+            ]
+        );
+    }
+
+    #[test]
+    fn expression_completion_at_top_level_offers_methods_from_object_chain() {
+        let mut context = GraphTest::new();
+
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            def my_top_method; end
+
+            module Kernel
+              def kernel_helper; end
+            end
+            ",
+        );
+        context.resolve();
+
+        let name_id = Name::new(StringId::from("Object"), ParentScope::None, None).id();
+        assert_declaration_completion_eq!(
+            context,
+            CompletionReceiver::Expression {
+                self_decl_id: None,
+                nesting_name_id: name_id,
+            },
+            [
+                "Object",
+                "Kernel",
+                "BasicObject",
+                "Module",
+                "Class",
+                "Object#my_top_method()",
+                "Kernel#kernel_helper()"
+            ]
+        );
+    }
+
+    #[test]
+    fn expression_completion_in_basic_object_subclass_excludes_object_constants() {
+        let mut context = GraphTest::new();
+
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            TOP_CONST = 1
+
+            class Bar < BasicObject
+              BAR_CONST = 2
+            end
+            ",
+        );
+        context.resolve();
+
+        let name_id = Name::new(StringId::from("Bar"), ParentScope::None, None).id();
+        assert_declaration_completion_eq!(
+            context,
+            CompletionReceiver::Expression {
+                self_decl_id: None,
+                nesting_name_id: name_id,
+            },
+            ["Bar::BAR_CONST"]
+        );
+    }
+
+    #[test]
+    fn expression_completion_class_variables_in_singleton_class_block_use_outer_lexical_scope() {
+        let mut context = GraphTest::new();
+
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            class Foo
+              @@foo_cvar = 1
+            end
+
+            class Bar
+              @@bar_cvar = 2
+
+              class << Foo
+                # completion here
+              end
+            end
+            ",
+        );
+        context.resolve();
+
+        let bar_id = Name::new(StringId::from("Bar"), ParentScope::None, None).id();
+        let foo_ref_id = Name::new(StringId::from("Foo"), ParentScope::None, Some(bar_id)).id();
+        let nesting_name_id = Name::new(StringId::from("<Foo>"), ParentScope::Attached(foo_ref_id), Some(bar_id)).id();
+
+        assert_declaration_completion_eq!(
+            context,
+            CompletionReceiver::Expression {
+                self_decl_id: None,
+                nesting_name_id,
+            },
+            ["Bar#@@bar_cvar"]
+        );
+    }
+
+    #[test]
+    fn expression_completion_in_def_self_method_inside_module_body() {
+        let mut context = GraphTest::new();
+
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            module Mod
+              MOD_CONST = 1
+
+              def self.helper
+                # completion here
+              end
+            end
+            ",
+        );
+        context.resolve();
+
+        let name_id = Name::new(StringId::from("Mod"), ParentScope::None, None).id();
+        assert_declaration_completion_eq!(
+            context,
+            CompletionReceiver::Expression {
+                self_decl_id: Some(DeclarationId::from("Mod::<Mod>")),
+                nesting_name_id: name_id,
+            },
+            [
+                "Mod::MOD_CONST",
+                "Module",
+                "Class",
+                "Object",
+                "BasicObject",
+                "Kernel",
+                "Mod",
+                "Mod::<Mod>#helper()"
+            ]
+        );
+    }
+
+    #[test]
+    fn expression_completion_in_singleton_class_block_at_top_level() {
+        let mut context = GraphTest::new();
+
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            class Foo
+              @@foo_cvar = 1
+            end
+
+            class << Foo
+              # completion here
+            end
+            ",
+        );
+        context.resolve();
+
+        let foo_ref_id = Name::new(StringId::from("Foo"), ParentScope::None, None).id();
+        let nesting_name_id = Name::new(StringId::from("<Foo>"), ParentScope::Attached(foo_ref_id), None).id();
+
+        assert_declaration_completion_eq!(
+            context,
+            CompletionReceiver::Expression {
+                self_decl_id: None,
+                nesting_name_id,
+            },
+            ["Module", "Class", "Object", "BasicObject", "Kernel", "Foo"]
+        );
+    }
+
+    #[test]
+    fn expression_completion_errors_when_self_decl_id_does_not_exist() {
+        let mut context = GraphTest::new();
+
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            class Foo
+            end
+            ",
+        );
+        context.resolve();
+
+        let name_id = Name::new(StringId::from("Foo"), ParentScope::None, None).id();
+        let result = completion_candidates(
+            context.graph(),
+            CompletionContext::new(CompletionReceiver::Expression {
+                self_decl_id: Some(DeclarationId::from("Nonexistent")),
+                nesting_name_id: name_id,
+            }),
+        );
+
+        assert!(result.is_err(), "missing self_decl_id should surface as an error");
+    }
+
+    #[test]
+    fn expression_completion_errors_when_self_decl_id_is_not_a_namespace() {
+        let mut context = GraphTest::new();
+
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            class Foo
+              CONST = 1
+            end
+            ",
+        );
+        context.resolve();
+
+        let name_id = Name::new(StringId::from("Foo"), ParentScope::None, None).id();
+        let result = completion_candidates(
+            context.graph(),
+            CompletionContext::new(CompletionReceiver::Expression {
+                // CONST resolves to a `Constant`, not a `Namespace` and not an alias.
+                self_decl_id: Some(DeclarationId::from("Foo::CONST")),
+                nesting_name_id: name_id,
+            }),
+        );
+
+        assert!(result.is_err(), "non-namespace self_decl_id should surface as an error");
+    }
+
+    #[test]
+    fn expression_completion_follows_chained_self_decl_alias() {
+        let mut context = GraphTest::new();
+
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            module Outer
+              class Original
+                def original_m; end
+              end
+
+              FirstAlias = Original
+              SecondAlias = FirstAlias
+            end
+            ",
+        );
+        context.resolve();
+
+        let name_id = Name::new(StringId::from("Outer"), ParentScope::None, None).id();
+        assert_declaration_completion_eq!(
+            context,
+            CompletionReceiver::Expression {
+                self_decl_id: Some(DeclarationId::from("Outer::SecondAlias")),
+                nesting_name_id: name_id,
+            },
+            [
+                "Outer::FirstAlias",
+                "Outer::SecondAlias",
+                "Outer::Original",
+                "Module",
+                "Class",
+                "Object",
+                "BasicObject",
+                "Outer",
+                "Kernel",
+                "Outer::Original#original_m()"
+            ]
+        );
+    }
+
+    #[test]
+    fn expression_completion_includes_private_singleton_method_when_self_matches_owner() {
+        let mut context = GraphTest::new();
+
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            class Foo
+              def self.bar; end
+              private_class_method :bar
+            end
+
+            class Bar
+              def Foo.baz
+                # completion here
+              end
+            end
+            ",
+        );
+        context.resolve();
+
+        let name_id = Name::new(StringId::from("Bar"), ParentScope::None, None).id();
+        assert_declaration_completion_eq!(
+            context,
+            CompletionReceiver::Expression {
+                self_decl_id: Some(DeclarationId::from("Foo::<Foo>")),
+                nesting_name_id: name_id,
+            },
+            [
+                "Module",
+                "Class",
+                "Object",
+                "BasicObject",
+                "Kernel",
+                "Foo",
+                "Bar",
+                "Foo::<Foo>#bar()",
+                "Foo::<Foo>#baz()"
+            ]
+        );
+    }
+
+    #[test]
+    fn method_call_completion_excludes_private_method_for_external_call() {
+        let mut context = GraphTest::new();
+
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            class Foo
+              private
+
+              def bar; end
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_completion_eq!(
+            context,
+            CompletionReceiver::MethodCall {
+                self_decl_id: None,
+                receiver_decl_id: DeclarationId::from("Foo")
+            },
+            [] as [&str; 0]
+        );
+    }
+
+    #[test]
+    fn expression_completion_includes_private_instance_method_inside_self_ancestor_chain() {
+        let mut context = GraphTest::new();
+
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            class Foo
+              def baz
+                # completion here
+              end
+
+              private
+
+              def bar; end
+            end
+
+            class Bar < Foo
+              def qux
+                # completion here
+              end
+            end
+            ",
+        );
+        context.resolve();
+
+        let foo_name_id = Name::new(StringId::from("Foo"), ParentScope::None, None).id();
+        assert_declaration_completion_eq!(
+            context,
+            CompletionReceiver::Expression {
+                self_decl_id: None,
+                nesting_name_id: foo_name_id,
+            },
+            [
+                "Module",
+                "Class",
+                "Object",
+                "BasicObject",
+                "Kernel",
+                "Foo",
+                "Bar",
+                "Foo#baz()",
+                "Foo#bar()"
+            ]
+        );
+
+        let bar_name_id = Name::new(StringId::from("Bar"), ParentScope::None, None).id();
+        assert_declaration_completion_eq!(
+            context,
+            CompletionReceiver::Expression {
+                self_decl_id: None,
+                nesting_name_id: bar_name_id,
+            },
+            [
+                "Module",
+                "Class",
+                "Object",
+                "BasicObject",
+                "Kernel",
+                "Foo",
+                "Bar",
+                "Foo#baz()",
+                "Foo#bar()",
+                "Bar#qux()"
+            ]
+        );
+    }
+
+    #[test]
+    fn method_call_completion_includes_protected_method_when_caller_shares_ancestor_with_receiver() {
+        let mut context = GraphTest::new();
+
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            class Account
+              protected
+
+              def balance; end
+            end
+
+            class Savings < Account
+            end
+
+            class Checking < Account
+            end
+            ",
+        );
+        context.resolve();
+
+        // Caller's self is `Account` (or any descendant). Both caller and receiver descend from
+        // the defining class, satisfying MRI's `caller.class <= defined_class && recv.class <= defined_class`.
+        assert_completion_eq!(
+            context,
+            CompletionReceiver::MethodCall {
+                self_decl_id: Some(DeclarationId::from("Account")),
+                receiver_decl_id: DeclarationId::from("Savings"),
+            },
+            ["Account#balance()"]
+        );
+
+        assert_completion_eq!(
+            context,
+            CompletionReceiver::MethodCall {
+                self_decl_id: Some(DeclarationId::from("Savings")),
+                receiver_decl_id: DeclarationId::from("Checking"),
+            },
+            ["Account#balance()"]
+        );
+    }
+
+    #[test]
+    fn method_call_completion_excludes_protected_method_when_caller_does_not_share_ancestor() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            class Account
+              protected
+
+              def balance; end
+            end
+
+            class Unrelated
+            end
+            ",
+        );
+        context.resolve();
+
+        // Receiver is `Account`; caller's self is `Unrelated`. Caller is not a descendant of the
+        // defining class, so the protected check fails and `balance` is hidden.
+        assert_completion_eq!(
+            context,
+            CompletionReceiver::MethodCall {
+                self_decl_id: Some(DeclarationId::from("Unrelated")),
+                receiver_decl_id: DeclarationId::from("Account"),
+            },
+            [] as [&str; 0]
+        );
+    }
+
+    #[test]
+    fn method_call_completion_includes_private_method_when_receiver_is_self() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            class Foo
+              def public_method; end
+
+              private
+
+              def private_method; end
+            end
+            ",
+        );
+        context.resolve();
+
+        // Caller's self is `Foo`, matching the receiver — `private_method` becomes visible
+        // (Ruby 3.0+ allows `self.foo` for private methods, and our completion treats receiver-equals-self as the
+        // implicit-receiver case).
+        assert_completion_eq!(
+            context,
+            CompletionReceiver::MethodCall {
+                self_decl_id: Some(DeclarationId::from("Foo")),
+                receiver_decl_id: DeclarationId::from("Foo"),
+            },
+            ["Foo#public_method()", "Foo#private_method()"]
+        );
+    }
+
+    #[test]
+    fn method_call_completion_includes_protected_method_through_included_module() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            module Sharable
+              protected
+
+              def shared_secret; end
+            end
+
+            class A
+              include Sharable
+            end
+
+            class B
+              include Sharable
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_completion_eq!(
+            context,
+            CompletionReceiver::MethodCall {
+                self_decl_id: Some(DeclarationId::from("A")),
+                receiver_decl_id: DeclarationId::from("B"),
+            },
+            ["Sharable#shared_secret()"]
+        );
+    }
+
+    #[test]
+    fn method_call_completion_excludes_protected_when_caller_class_is_not_descendant_of_defined_class() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            class Animal
+            end
+
+            class Dog < Animal
+              protected
+
+              def secret_trick; end
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_completion_eq!(
+            context,
+            CompletionReceiver::MethodCall {
+                self_decl_id: Some(DeclarationId::from("Animal")),
+                receiver_decl_id: DeclarationId::from("Dog"),
+            },
+            [] as [&str; 0]
+        );
+    }
+
+    #[test]
+    fn method_call_completion_excludes_visibility_restricted_methods_at_top_level() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            class Foo
+              def pub_inst; end
+
+              protected
+
+              def prot_inst; end
+
+              private
+
+              def priv_inst; end
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_completion_eq!(
+            context,
+            CompletionReceiver::MethodCall {
+                self_decl_id: None,
+                receiver_decl_id: DeclarationId::from("Foo"),
+            },
+            ["Foo#pub_inst()"]
+        );
+    }
+
+    #[test]
+    fn method_call_completion_hides_method_when_subclass_overrides_with_stricter_visibility() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            class Parent
+              def foo; end
+            end
+
+            class Child < Parent
+              private
+
+              def foo; end
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_completion_eq!(
+            context,
+            CompletionReceiver::MethodCall {
+                self_decl_id: None,
+                receiver_decl_id: DeclarationId::from("Child"),
+            },
+            [] as [&str; 0]
+        );
+    }
+
+    #[test]
+    fn namespace_access_completion_excludes_private_constant() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            class Foo
+              PUB = 1
+              PRIV = 2
+              private_constant :PRIV
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_completion_eq!(
+            context,
+            CompletionReceiver::NamespaceAccess {
+                self_decl_id: None,
+                namespace_decl_id: DeclarationId::from("Foo"),
+            },
+            ["Foo::PUB"]
+        );
+    }
+
+    #[test]
+    fn namespace_access_completion_excludes_inherited_private_constant() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            class Parent
+              SECRET = 1
+              private_constant :SECRET
+            end
+
+            class Child < Parent
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_completion_eq!(
+            context,
+            CompletionReceiver::NamespaceAccess {
+                self_decl_id: None,
+                namespace_decl_id: DeclarationId::from("Child"),
+            },
+            [] as [&str; 0]
+        );
+    }
+
+    #[test]
+    fn expression_completion_includes_private_constant_within_lexical_scope() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            "
+            class Foo
+              SECRET = 1
+              private_constant :SECRET
+
+              def use_it
+                # completion here
+              end
+            end
+            ",
+        );
+        context.resolve();
+
+        let foo_name_id = Name::new(StringId::from("Foo"), ParentScope::None, None).id();
+        assert_declaration_completion_eq!(
+            context,
+            CompletionReceiver::Expression {
+                self_decl_id: None,
+                nesting_name_id: foo_name_id,
+            },
+            [
+                "Module",
+                "Class",
+                "Object",
+                "BasicObject",
+                "Kernel",
+                "Foo",
+                "Foo::SECRET",
+                "Foo#use_it()"
+            ]
+        );
+    }
 }