rubydex 0.2.0 → 0.2.2

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::ids::{DeclarationId, DefinitionId, 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);
     };
@@ -470,6 +674,153 @@ fn method_argument_completion<'a>(
     Ok(candidates)
 }
 
+/// Reasons [`find_member_in_ancestors`] could not produce a target declaration.
+#[derive(Debug, PartialEq, Eq)]
+pub enum FindMemberError {
+    /// The provided declaration id does not exist in the graph.
+    DeclarationNotFound,
+    /// The declaration exists but is not a namespace, so it has no members or ancestor chain to search.
+    NotNamespace,
+    /// The declaration is a namespace, but no matching member exists on it or any of its ancestors.
+    MemberNotFound,
+}
+
+/// Finds the given member on the ancestor chain of the declaration. Use `only_inherited` to skip all ancestors until
+/// the main namespace and start from its parent.
+///
+/// # Errors
+///
+/// Returns a [`FindMemberError`] describing why no target declaration could be produced (declaration not found, not a
+/// namespace, or member missing on the ancestor chain).
+///
+/// # Panics
+///
+/// Will panic if we incorrectly store ancestors that are not namespaces.
+pub fn find_member_in_ancestors(
+    graph: &Graph,
+    declaration_id: DeclarationId,
+    member_str_id: StringId,
+    only_inherited: bool,
+) -> Result<DeclarationId, FindMemberError> {
+    let declaration = graph
+        .declarations()
+        .get(&declaration_id)
+        .ok_or(FindMemberError::DeclarationNotFound)?;
+    let namespace = declaration.as_namespace().ok_or(FindMemberError::NotNamespace)?;
+    let mut found_main_namespace = false;
+
+    for ancestor in namespace.ancestors() {
+        let Ancestor::Complete(ancestor_id) = ancestor else {
+            continue;
+        };
+
+        if only_inherited && !found_main_namespace {
+            if *ancestor_id == declaration_id {
+                found_main_namespace = true;
+            }
+            continue;
+        }
+
+        if let Some(member_id) = graph
+            .declarations()
+            .get(ancestor_id)
+            .unwrap()
+            .as_namespace()
+            .unwrap()
+            .member(&member_str_id)
+        {
+            return Ok(*member_id);
+        }
+    }
+
+    Err(FindMemberError::MemberNotFound)
+}
+
+/// Reasons [`follow_method_alias`] could not produce a target declaration.
+#[derive(Debug, PartialEq, Eq)]
+pub enum AliasResolutionError {
+    /// The provided definition id is not a `MethodAlias`.
+    NotAnAlias,
+    /// The alias's owner could not be resolved (e.g., a `ConstantReceiver` whose name never resolved to a declaration,
+    /// or a singleton-class chain whose attached object isn't resolvable).
+    UnresolvedOwner,
+    /// The chain of aliases forms a cycle. The chain was abandoned at the first revisit.
+    Cycle,
+    /// The alias's `old_name` does not exist on the owner or any of its ancestors.
+    TargetNotFound,
+    /// The resolved target is not a method declaration. Indicates a graph inconsistency since method-name lookups
+    /// should only land on `Declaration::Method`.
+    TargetNotMethod,
+}
+
+/// Follows `alias_id` through any chain of further `MethodAlias` definitions and returns the `DeclarationId` of the
+/// final method declaration that has at least one non-alias definition (a regular `def`, `attr_*`, etc.).
+///
+/// # Errors
+///
+/// Returns an `AliasResolutionError` describing why the chain could not be resolved (not an alias, unresolved owner,
+/// cyclic chain, target missing, or target not a method).
+///
+/// # Panics
+///
+/// Panics if the graph is internally inconsistent
+pub fn follow_method_alias(graph: &Graph, alias_id: DefinitionId) -> Result<DeclarationId, AliasResolutionError> {
+    let mut seen: IdentityHashSet<DeclarationId> = IdentityHashSet::default();
+    let mut current = alias_id;
+
+    loop {
+        let Some(Definition::MethodAlias(alias)) = graph.definitions().get(&current) else {
+            return Err(AliasResolutionError::NotAnAlias);
+        };
+
+        let owner_id = graph
+            .definition_id_to_declaration_id(current)
+            .and_then(|decl_id| graph.declarations().get(decl_id))
+            .map(|decl| *decl.owner_id())
+            .ok_or(AliasResolutionError::UnresolvedOwner)?;
+
+        let target_id = match find_member_in_ancestors(graph, owner_id, *alias.old_name_str_id(), false) {
+            Ok(id) => id,
+            Err(FindMemberError::MemberNotFound) => return Err(AliasResolutionError::TargetNotFound),
+            Err(err @ (FindMemberError::DeclarationNotFound | FindMemberError::NotNamespace)) => {
+                unreachable!("alias owner must be a valid namespace declaration, got {err:?}")
+            }
+        };
+
+        if !seen.insert(target_id) {
+            return Err(AliasResolutionError::Cycle);
+        }
+
+        let Declaration::Method(target) = graph
+            .declarations()
+            .get(&target_id)
+            .expect("member returned by find_member_in_ancestors must exist")
+        else {
+            return Err(AliasResolutionError::TargetNotMethod);
+        };
+
+        // Stop at the first non-alias definition; otherwise track the smallest alias `DefinitionId` so the trace stays
+        // deterministic across runs. (If two aliases target different methods, we just pick one of them.)
+        let mut maybe_next_alias: Option<DefinitionId> = None;
+
+        for &def_id in target.definitions() {
+            if !matches!(
+                graph
+                    .definitions()
+                    .get(&def_id)
+                    .expect("declaration definition_id must exist in the graph"),
+                Definition::MethodAlias(_),
+            ) {
+                return Ok(target_id);
+            }
+
+            maybe_next_alias = Some(maybe_next_alias.map_or(def_id, |m| m.min(def_id)));
+        }
+
+        current = maybe_next_alias.ok_or(AliasResolutionError::TargetNotFound)?;
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use std::str::FromStr;
@@ -523,30 +874,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 +1119,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 +1134,6 @@ mod tests {
                 "Foo",
                 "Object",
                 "Child#baz()",
-                "Foo::CONST",
                 "Foo#bar()",
                 "Parent#initialize()",
                 "Parent#@var"
@@ -807,7 +1168,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 +1217,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 +1267,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 +1287,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 +1339,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 +1351,7 @@ mod tests {
                 "Kernel",
                 "Foo",
                 "Bar",
+                "Foo::CONST_A",
                 "Bar#bar_m()",
                 "Bar#bar_m2()"
             ]
@@ -984,7 +1360,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 +1404,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 +1451,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 +1482,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 +1518,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 +1559,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 +1585,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 +1610,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 +1643,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 +1678,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 +1708,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 +1745,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 +1776,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 +1809,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 +1837,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 +1867,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 +1897,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 +1928,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 +1956,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 +1982,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 +2018,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 +2044,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 +2088,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 +2115,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 +2181,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 +2247,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 +2265,1490 @@ 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()"
+            ]
+        );
+    }
+
+    /// Returns the smallest `MethodAlias` `DefinitionId` for the declaration named `alias_decl_fqn`
+    /// (e.g., `"Foo#aliased()"`). Picking the smallest mirrors `follow_method_alias`'s own
+    /// determinism rule for tests where multiple aliases share a declaration (e.g. cross-file fixtures).
+    fn alias_def_id(context: &GraphTest, alias_decl_fqn: &str) -> DefinitionId {
+        let decl = context
+            .graph()
+            .declarations()
+            .get(&DeclarationId::from(alias_decl_fqn))
+            .unwrap_or_else(|| panic!("expected declaration {alias_decl_fqn}"));
+
+        decl.definitions()
+            .iter()
+            .copied()
+            .filter(|def_id| {
+                matches!(
+                    context.graph().definitions().get(def_id),
+                    Some(Definition::MethodAlias(_)),
+                )
+            })
+            .min()
+            .unwrap_or_else(|| panic!("declaration {alias_decl_fqn} has no MethodAlias definition"))
+    }
+
+    /// Asserts that the alias declared as `$alias_fqn` follows to the declaration `$target_fqn`.
+    macro_rules! assert_alias_target {
+        ($context:expr, $alias_fqn:expr, $target_fqn:expr $(,)?) => {{
+            let context = $context;
+            assert_eq!(
+                follow_method_alias(context.graph(), alias_def_id(context, $alias_fqn)),
+                Ok(DeclarationId::from($target_fqn)),
+            );
+        }};
+    }
+
+    #[test]
+    fn follow_method_alias_to_local_method() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class Foo
+              def original; end
+              alias aliased original
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_alias_target!(&context, "Foo#aliased()", "Foo#original()");
+    }
+
+    #[test]
+    fn follow_method_alias_through_chain_of_aliases() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class Foo
+              def real; end
+              alias mid real
+              alias outer mid
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_alias_target!(&context, "Foo#outer()", "Foo#real()");
+    }
+
+    #[test]
+    fn follow_method_alias_detects_two_step_cycle() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class Foo
+              alias a b
+              alias b a
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_eq!(
+            follow_method_alias(context.graph(), alias_def_id(&context, "Foo#a()")),
+            Err(AliasResolutionError::Cycle),
+        );
+        assert_eq!(
+            follow_method_alias(context.graph(), alias_def_id(&context, "Foo#b()")),
+            Err(AliasResolutionError::Cycle),
+        );
+    }
+
+    #[test]
+    fn follow_method_alias_detects_multi_step_cycle() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class Foo
+              alias a b
+              alias b c
+              alias c a
+            end
+            ",
+        );
+        context.resolve();
+
+        for alias_fqn in ["Foo#a()", "Foo#b()", "Foo#c()"] {
+            assert_eq!(
+                follow_method_alias(context.graph(), alias_def_id(&context, alias_fqn)),
+                Err(AliasResolutionError::Cycle),
+                "expected {alias_fqn} to be detected as part of the cycle",
+            );
+        }
+    }
+
+    #[test]
+    fn follow_method_alias_detects_self_cycle() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class Foo
+              alias foo foo
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_eq!(
+            follow_method_alias(context.graph(), alias_def_id(&context, "Foo#foo()")),
+            Err(AliasResolutionError::Cycle),
+        );
+    }
+
+    #[test]
+    fn follow_method_alias_to_inherited_method() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class Parent
+              def inherited_m; end
+            end
+
+            class Child < Parent
+              alias aliased inherited_m
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_alias_target!(&context, "Child#aliased()", "Parent#inherited_m()");
+    }
+
+    #[test]
+    fn follow_method_alias_with_constant_receiver() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class Bar
+              def to_s; end
+            end
+
+            class Foo
+              Bar.alias_method(:new_to_s, :to_s)
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_alias_target!(&context, "Bar#new_to_s()", "Bar#to_s()");
+    }
+
+    #[test]
+    fn follow_method_alias_in_singleton_class_body() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class Foo
+              def self.find; end
+
+              class << self
+                alias_method :find_old, :find
+              end
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_alias_target!(&context, "Foo::<Foo>#find_old()", "Foo::<Foo>#find()");
+    }
+
+    #[test]
+    fn follow_method_alias_in_singleton_class_body_misses_instance_method() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class Foo
+              def regular; end
+
+              class << self
+                alias_method :other, :regular
+              end
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_eq!(
+            follow_method_alias(context.graph(), alias_def_id(&context, "Foo::<Foo>#other()")),
+            Err(AliasResolutionError::TargetNotFound),
+        );
+    }
+
+    #[test]
+    fn follow_method_alias_to_attr_reader() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class Foo
+              attr_reader :name
+              alias display name
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_alias_target!(&context, "Foo#display()", "Foo#name()");
+    }
+
+    #[test]
+    fn follow_method_alias_to_attr_accessor() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class Foo
+              attr_accessor :age
+              alias years age
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_alias_target!(&context, "Foo#years()", "Foo#age()");
+    }
+
+    #[test]
+    fn follow_method_alias_to_method_in_prepended_module() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            module M
+              def original; end
+            end
+
+            class Foo
+              prepend M
+              alias aliased original
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_alias_target!(&context, "Foo#aliased()", "M#original()");
+    }
+
+    #[test]
+    fn follow_method_alias_ignores_visibility_of_target() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class Foo
+              private def secret; end
+              alias revealed secret
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_alias_target!(&context, "Foo#revealed()", "Foo#secret()");
+    }
+
+    #[test]
+    fn follow_method_alias_picks_last_when_multiple_targets() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class Foo
+              def bar; end
+              def qux; end
+              alias double bar
+              alias double qux
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_alias_target!(&context, "Foo#double()", "Foo#qux()");
+    }
+
+    #[test]
+    fn follow_method_alias_returns_target_not_found_when_target_missing() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class Foo
+              alias aliased nonexistent
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_eq!(
+            follow_method_alias(context.graph(), alias_def_id(&context, "Foo#aliased()")),
+            Err(AliasResolutionError::TargetNotFound),
+        );
+    }
+
+    #[test]
+    fn find_member_in_ancestors_returns_member_in_main_namespace() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class Foo
+              def bar; end
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_eq!(
+            find_member_in_ancestors(
+                context.graph(),
+                DeclarationId::from("Foo"),
+                StringId::from("bar()"),
+                false,
+            ),
+            Ok(DeclarationId::from("Foo#bar()")),
+        );
+    }
+
+    #[test]
+    fn find_member_in_ancestors_returns_inherited_member() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class Parent
+              def inherited_method; end
+            end
+
+            class Child < Parent
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_eq!(
+            find_member_in_ancestors(
+                context.graph(),
+                DeclarationId::from("Child"),
+                StringId::from("inherited_method()"),
+                false,
+            ),
+            Ok(DeclarationId::from("Parent#inherited_method()")),
+        );
+    }
+
+    #[test]
+    fn find_member_in_ancestors_returns_member_not_found_when_member_missing() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class Foo
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_eq!(
+            find_member_in_ancestors(
+                context.graph(),
+                DeclarationId::from("Foo"),
+                StringId::from("missing()"),
+                false,
+            ),
+            Err(FindMemberError::MemberNotFound),
+        );
+    }
+
+    #[test]
+    fn find_member_in_ancestors_returns_not_a_namespace_for_method_declaration() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class Foo
+              def bar; end
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_eq!(
+            find_member_in_ancestors(
+                context.graph(),
+                DeclarationId::from("Foo#bar()"),
+                StringId::from("anything"),
+                false,
+            ),
+            Err(FindMemberError::NotNamespace),
+        );
+    }
+
+    #[test]
+    fn find_member_in_ancestors_returns_declaration_not_found_for_unknown_id() {
+        let mut context = GraphTest::new();
+        context.index_uri(
+            "file:///foo.rb",
+            r"
+            class Foo
+            end
+            ",
+        );
+        context.resolve();
+
+        assert_eq!(
+            find_member_in_ancestors(
+                context.graph(),
+                DeclarationId::from("DoesNotExist"),
+                StringId::from("anything"),
+                false,
+            ),
+            Err(FindMemberError::DeclarationNotFound),
+        );
+    }
 }