rubydex 0.2.9 → 0.3.0

data/rust/rubydex/src/resolution.rs

@@ -14,8 +14,9 @@ use crate::model::{
     definitions::{Definition, Mixin, Receiver},
     graph::{Graph, Unit},
     identity_maps::{IdentityHashBuilder, IdentityHashMap, IdentityHashSet},
-    ids::{ConstantReferenceId, DeclarationId, DefinitionId, NameId, StringId},
+    ids::{ConstantReferenceId, DeclarationId, DefinitionId, NameId, StringId, UriId},
     name::{Name, NameRef, ParentScope},
+    visibility::Visibility,
 };
 
 enum Outcome {
@@ -635,7 +636,7 @@ impl<'a> Resolver<'a> {
     }
 
     /// Resolves retroactive method visibility changes (`private :foo`, `protected :foo`, `public :foo`,
-    /// `private_class_method :foo`, `public_class_method :foo`).
+    /// `private_class_method :foo`, `public_class_method :foo`, `module_function :foo`).
     ///
     /// Runs as a second pass after all methods/attrs are declared, so `private :bar` works
     /// regardless of whether `def bar` appeared before or after it in source.
@@ -652,12 +653,14 @@ impl<'a> Resolver<'a> {
             let offset = method_visibility.offset().clone();
             let lexical_nesting_id = *method_visibility.lexical_nesting_id();
             let is_singleton = method_visibility.flags().is_singleton_method_visibility();
+            let is_module_function = *method_visibility.visibility() == Visibility::ModuleFunction;
+            let is_module_function_singleton = is_singleton && is_module_function;
 
             let Some(lexical_owner_id) = self.resolve_lexical_owner(lexical_nesting_id, id) else {
                 continue;
             };
 
-            let owner_id = if is_singleton {
+            let namespace_id = if is_singleton && !is_module_function {
                 let Some(singleton_id) =
                     self.get_or_create_singleton_class(lexical_owner_id, SingletonAncestors::Eager)
                 else {
@@ -668,12 +671,12 @@ impl<'a> Resolver<'a> {
                 lexical_owner_id
             };
 
-            let Some(Declaration::Namespace(namespace)) = self.graph.declarations().get(&owner_id) else {
+            let Some(Declaration::Namespace(namespace)) = self.graph.declarations().get(&namespace_id) else {
                 continue;
             };
 
-            let mut visibility_applied = false;
-            let mut has_partial = false;
+            let mut visibility_definition_attached = false;
+            let mut ancestor_chain_is_incomplete = false;
 
             for ancestor in namespace.ancestors() {
                 match ancestor {
@@ -687,40 +690,51 @@ impl<'a> Resolver<'a> {
                             .is_some();
 
                         if has_member {
-                            // Direct member: `create_declaration`'s fully qualified name dedup attaches
-                            // this visibility definition to the existing method declaration.
-                            // Inherited: a new child-owned declaration is created.
-                            self.create_declaration(str_id, id, owner_id, |name| {
-                                Declaration::Method(Box::new(MethodDeclaration::new(name, owner_id)))
-                            });
-                            visibility_applied = true;
+                            if is_module_function_singleton {
+                                let Some(singleton_id) =
+                                    self.get_or_create_singleton_class(lexical_owner_id, SingletonAncestors::Eager)
+                                else {
+                                    break;
+                                };
+
+                                self.create_declaration(str_id, id, singleton_id, |name| {
+                                    Declaration::Method(Box::new(MethodDeclaration::new(name, singleton_id)))
+                                });
+                            } else {
+                                self.create_declaration(str_id, id, namespace_id, |name| {
+                                    Declaration::Method(Box::new(MethodDeclaration::new(name, namespace_id)))
+                                });
+                            }
+                            visibility_definition_attached = true;
                             break;
                         }
                     }
-                    Ancestor::Partial(_) => has_partial = true,
+                    Ancestor::Partial(_) => ancestor_chain_is_incomplete = true,
                 }
             }
 
-            if visibility_applied {
+            if visibility_definition_attached {
                 continue;
             }
 
-            if has_partial {
-                // Method might exist on an unresolved ancestor — requeue for retry.
+            if ancestor_chain_is_incomplete {
                 pending_work.push(Unit::Definition(id));
-            } else {
-                // Ancestors are fully resolved — method definitively doesn't exist.
-                let method_name = self.graph.strings().get(&str_id).unwrap().as_str().to_string();
-                let owner_name = self.graph.declarations().get(&owner_id).unwrap().name().to_string();
-                let diagnostic = Diagnostic::new(
-                    Rule::UndefinedMethodVisibilityTarget,
-                    uri_id,
-                    offset,
-                    format!("undefined method `{owner_name}#{method_name}` for visibility change"),
-                );
-
-                self.graph.add_document_diagnostic(uri_id, diagnostic);
+                continue;
+            }
+
+            if is_module_function_singleton {
+                continue;
             }
+
+            let method_name = self.graph.strings().get(&str_id).unwrap().as_str().to_string();
+            let owner_name = self.graph.declarations().get(&namespace_id).unwrap().name().to_string();
+            let diagnostic = Diagnostic::new(
+                Rule::UndefinedMethodVisibilityTarget,
+                uri_id,
+                offset,
+                format!("undefined method `{owner_name}#{method_name}` for visibility change"),
+            );
+            self.graph.add_document_diagnostic(uri_id, diagnostic);
         }
 
         // Must extend work here so incremental resolution can resolve previously unresolved visibility operations
@@ -850,7 +864,7 @@ impl<'a> Resolver<'a> {
     /// Gets or creates a singleton class declaration for a given class/module declaration.  For class `Foo`, this
     /// returns the declaration for `Foo::<Foo>`.
     ///
-    /// If the declaration is a `Constant` with all-promotable definitions, it is automatically promoted to a `Class`
+    /// If the declaration is a `Constant` with all-promotable definitions, it is automatically promoted to an unknown
     /// namespace before creating the singleton. Returns `None` if the declaration is not a namespace and cannot be
     /// promoted (e.g., `FOO = 42`).
     /// `ancestors` controls how the singleton's ancestor chain is scheduled for linearization —
@@ -863,6 +877,10 @@ impl<'a> Resolver<'a> {
     ) -> Option<DeclarationId> {
         let attached_decl = self.graph.declarations().get(&attached_id).unwrap();
 
+        if let Some(singleton_id) = attached_decl.as_namespace().and_then(|d| d.singleton_class()) {
+            return Some(*singleton_id);
+        }
+
         // If the attached object is a constant alias, follow the alias chain to find the actual namespace
         if matches!(attached_decl, Declaration::ConstantAlias(_)) {
             return match self.resolve_to_namespace(attached_id) {
@@ -874,7 +892,7 @@ impl<'a> Resolver<'a> {
         if matches!(attached_decl, Declaration::Constant(_)) {
             if self.graph.all_definitions_promotable(attached_decl) {
                 self.graph.promote_constant_to_namespace(attached_id, |name, owner_id| {
-                    Declaration::Namespace(Namespace::Module(Box::new(ModuleDeclaration::new(name, owner_id))))
+                    Declaration::Namespace(Namespace::Todo(Box::new(TodoDeclaration::new(name, owner_id))))
                 });
 
                 self.schedule_singleton_ancestors(attached_id, mode);
@@ -890,10 +908,6 @@ impl<'a> Resolver<'a> {
             .as_namespace_mut()
             .expect("constants are handled above; all other callers pass namespace declarations");
 
-        if let Some(singleton_id) = namespace_decl.singleton_class() {
-            return Some(*singleton_id);
-        }
-
         let decl_id = DeclarationId::from(&fully_qualified_name);
         namespace_decl.set_singleton_class_id(decl_id);
 
@@ -1067,17 +1081,11 @@ impl<'a> Resolver<'a> {
         declaration_id: DeclarationId,
         context: &mut LinearizationContext,
     ) -> Option<Vec<Ancestor>> {
-        if declaration_id == *BASIC_OBJECT_ID {
-            return None;
-        }
-
         let declaration = self.graph.declarations().get(&declaration_id).unwrap();
 
         match declaration {
             Declaration::Namespace(Namespace::Class(_)) => {
-                let definition_ids = declaration.definitions().to_vec();
-
-                Some(match self.linearize_parent_class(&definition_ids, context) {
+                Some(match self.linearize_superclass(declaration_id, context)? {
                     Ancestors::Complete(ids) => ids,
                     Ancestors::Cyclic(ids) => {
                         context.cyclic = true;
@@ -1229,14 +1237,16 @@ impl<'a> Resolver<'a> {
         if !descendants.is_empty() {
             for ancestor in cached {
                 if let Ancestor::Complete(ancestor_id) = ancestor {
+                    let namespace = self
+                        .graph
+                        .declarations_mut()
+                        .get_mut(ancestor_id)
+                        .unwrap()
+                        .as_namespace_mut()
+                        .unwrap();
+
                     for descendant in descendants.iter() {
-                        self.graph
-                            .declarations_mut()
-                            .get_mut(ancestor_id)
-                            .unwrap()
-                            .as_namespace_mut()
-                            .unwrap()
-                            .add_descendant(*descendant);
+                        namespace.add_descendant(*descendant);
                     }
                 }
             }
@@ -1280,8 +1290,8 @@ impl<'a> Resolver<'a> {
             Outcome::Resolved(owner_id) => {
                 let mut fully_qualified_name = self.graph.strings().get(&str_id).unwrap().to_string();
 
-                // If the owner is a promotable constant and something is being defined inside it, promote it to a
-                // module
+                // If the owner is a promotable constant and something is being defined inside it, promote it to an
+                // unknown namespace. A later explicit class or module definition selects the concrete kind.
                 {
                     let owner = self.graph.declarations().get(&owner_id).unwrap();
                     let is_promotable_constant =
@@ -1289,7 +1299,7 @@ impl<'a> Resolver<'a> {
 
                     if is_promotable_constant {
                         self.graph.promote_constant_to_namespace(owner_id, |name, owner_id| {
-                            Declaration::Namespace(Namespace::Module(Box::new(ModuleDeclaration::new(name, owner_id))))
+                            Declaration::Namespace(Namespace::Todo(Box::new(TodoDeclaration::new(name, owner_id))))
                         });
                         self.unit_queue.push_back(Unit::Ancestors(owner_id));
                     }
@@ -1468,139 +1478,139 @@ impl<'a> Resolver<'a> {
     /// resolved
     #[allow(clippy::too_many_lines)]
     fn resolve_constant_internal(&mut self, name_id: NameId) -> Outcome {
-        let name_ref = self.graph.names().get(&name_id).unwrap().clone();
+        let name = match self.graph.names().get(&name_id).unwrap() {
+            NameRef::Resolved(resolved) => return Outcome::Resolved(*resolved.declaration_id()),
+            NameRef::Unresolved(name) => name.as_ref().clone(),
+        };
 
-        match name_ref {
-            NameRef::Unresolved(name) => {
-                match name.parent_scope() {
-                    ParentScope::TopLevel => {
-                        let result = self.search_ancestors(*OBJECT_ID, *name.str());
+        match name.parent_scope() {
+            ParentScope::TopLevel => {
+                let result = self.search_ancestors(*OBJECT_ID, *name.str());
 
-                        if let Outcome::Resolved(declaration_id) = result {
-                            self.graph.record_resolved_name(name_id, declaration_id);
-                        }
+                if let Outcome::Resolved(declaration_id) = result {
+                    self.graph.record_resolved_name(name_id, declaration_id);
+                }
 
-                        result
-                    }
-                    ParentScope::Attached(parent_scope_id) => {
-                        let NameRef::Resolved(parent_scope) = self.graph.names().get(parent_scope_id).unwrap() else {
-                            return Outcome::Retry {
-                                partial_ancestors: false,
-                            };
+                result
+            }
+            ParentScope::Attached(parent_scope_id) => {
+                let NameRef::Resolved(parent_scope) = self.graph.names().get(parent_scope_id).unwrap() else {
+                    return Outcome::Retry {
+                        partial_ancestors: false,
+                    };
+                };
+
+                let mut target_decl_id = *parent_scope.declaration_id();
+                let target_decl = self.graph.declarations().get(&target_decl_id).unwrap();
+
+                // If the attached object is a constant alias, resolve it to the target namespace
+                // (e.g., ALIAS.bar where ALIAS = Foo should create the singleton class on Foo, not ALIAS)
+                if matches!(target_decl, Declaration::ConstantAlias(_)) {
+                    let resolved_ids = self.resolve_alias_chains(target_decl_id);
+
+                    if resolved_ids
+                        .iter()
+                        .any(|id| matches!(self.graph.declarations().get(id), Some(Declaration::ConstantAlias(_))))
+                    {
+                        return Outcome::Retry {
+                            partial_ancestors: false,
                         };
+                    }
 
-                        let mut target_decl_id = *parent_scope.declaration_id();
-                        let target_decl = self.graph.declarations().get(&target_decl_id).unwrap();
+                    let Some(&namespace_id) = resolved_ids
+                        .iter()
+                        .find(|id| matches!(self.graph.declarations().get(id), Some(Declaration::Namespace(_))))
+                    else {
+                        return Outcome::Unresolved;
+                    };
 
-                        // If the attached object is a constant alias, resolve it to the target namespace
-                        // (e.g., ALIAS.bar where ALIAS = Foo should create the singleton class on Foo, not ALIAS)
-                        if matches!(target_decl, Declaration::ConstantAlias(_)) {
-                            let resolved_ids = self.resolve_alias_chains(target_decl_id);
+                    target_decl_id = namespace_id;
+                }
 
-                            if resolved_ids.iter().any(|id| {
-                                matches!(self.graph.declarations().get(id), Some(Declaration::ConstantAlias(_)))
-                            }) {
-                                return Outcome::Retry {
-                                    partial_ancestors: false,
-                                };
-                            }
+                // If we found a singleton reference with a resolved attached object parent scope, we
+                // automatically create the singleton class
+                let Some(singleton_id) =
+                    self.get_or_create_singleton_class(target_decl_id, SingletonAncestors::Enqueue)
+                else {
+                    return Outcome::Unresolved;
+                };
+                self.graph.record_resolved_name(name_id, singleton_id);
+                // `get_or_create_singleton_class` already enqueued the singleton's ancestors on
+                // creation, so there is nothing to hand back for re-enqueueing.
+                Outcome::Resolved(singleton_id)
+            }
+            ParentScope::None => {
+                // Otherwise, it's a simple constant read and we can resolve it directly
+                let result = self.run_resolution(&name);
 
-                            let Some(&namespace_id) = resolved_ids.iter().find(|id| {
-                                matches!(self.graph.declarations().get(id), Some(Declaration::Namespace(_)))
-                            }) else {
-                                return Outcome::Unresolved;
-                            };
+                if let Outcome::Resolved(declaration_id) = result {
+                    self.graph.record_resolved_name(name_id, declaration_id);
+                }
 
-                            target_decl_id = namespace_id;
-                        }
+                result
+            }
+            ParentScope::Some(parent_scope_id) => {
+                let NameRef::Resolved(parent_scope) = self.graph.names().get(parent_scope_id).unwrap() else {
+                    return Outcome::Retry {
+                        partial_ancestors: false,
+                    };
+                };
 
-                        // If we found a singleton reference with a resolved attached object parent scope, we
-                        // automatically create the singleton class
-                        let Some(singleton_id) =
-                            self.get_or_create_singleton_class(target_decl_id, SingletonAncestors::Enqueue)
-                        else {
-                            return Outcome::Unresolved;
-                        };
-                        self.graph.record_resolved_name(name_id, singleton_id);
-                        // `get_or_create_singleton_class` already enqueued the singleton's ancestors on
-                        // creation, so there is nothing to hand back for re-enqueueing.
-                        Outcome::Resolved(singleton_id)
-                    }
-                    ParentScope::None => {
-                        // Otherwise, it's a simple constant read and we can resolve it directly
-                        let result = self.run_resolution(&name);
+                // Resolve the namespace in case it's an alias (e.g., ALIAS::CONST where ALIAS = Foo)
+                // An alias can have multiple targets, so we try all of them in order.
+                let resolved_ids = self.resolve_alias_chains(*parent_scope.declaration_id());
 
-                        if let Outcome::Resolved(declaration_id) = result {
-                            self.graph.record_resolved_name(name_id, declaration_id);
-                        }
+                // Search each resolved target for the constant. Return early if found.
+                let mut missing_partial = false;
+                let mut found_namespace = false;
 
-                        result
-                    }
-                    ParentScope::Some(parent_scope_id) => {
-                        let NameRef::Resolved(parent_scope) = self.graph.names().get(parent_scope_id).unwrap() else {
+                for &id in &resolved_ids {
+                    match self.graph.declarations().get(&id) {
+                        Some(Declaration::ConstantAlias(_)) => {
+                            // Alias not fully resolved yet
                             return Outcome::Retry {
                                 partial_ancestors: false,
                             };
-                        };
+                        }
+                        Some(Declaration::Namespace(_)) => {
+                            found_namespace = true;
 
-                        // Resolve the namespace in case it's an alias (e.g., ALIAS::CONST where ALIAS = Foo)
-                        // An alias can have multiple targets, so we try all of them in order.
-                        let resolved_ids = self.resolve_alias_chains(*parent_scope.declaration_id());
-
-                        // Search each resolved target for the constant. Return early if found.
-                        let mut missing_partial = false;
-                        let mut found_namespace = false;
-
-                        for &id in &resolved_ids {
-                            match self.graph.declarations().get(&id) {
-                                Some(Declaration::ConstantAlias(_)) => {
-                                    // Alias not fully resolved yet
-                                    return Outcome::Retry {
-                                        partial_ancestors: false,
-                                    };
+                            match self.search_ancestors(id, *name.str()) {
+                                Outcome::Resolved(declaration_id) => {
+                                    self.graph.record_resolved_name(name_id, declaration_id);
+                                    return Outcome::Resolved(declaration_id);
                                 }
-                                Some(Declaration::Namespace(_)) => {
-                                    found_namespace = true;
-
-                                    match self.search_ancestors(id, *name.str()) {
-                                        Outcome::Resolved(declaration_id) => {
-                                            self.graph.record_resolved_name(name_id, declaration_id);
-                                            return Outcome::Resolved(declaration_id);
-                                        }
-                                        Outcome::Retry {
-                                            partial_ancestors: true,
-                                        } => {
-                                            missing_partial = true;
-                                        }
-                                        Outcome::Unresolved => {}
-                                        Outcome::Retry {
-                                            partial_ancestors: false,
-                                        } => {
-                                            unreachable!("search_ancestors never returns a non-partial Retry")
-                                        }
-                                    }
+                                Outcome::Retry {
+                                    partial_ancestors: true,
+                                } => {
+                                    missing_partial = true;
                                 }
-                                _ => {
-                                    // Not a namespace (e.g., a constant) - skip
+                                Outcome::Unresolved => {}
+                                Outcome::Retry {
+                                    partial_ancestors: false,
+                                } => {
+                                    unreachable!("search_ancestors never returns a non-partial Retry")
                                 }
                             }
                         }
-
-                        // If no namespaces were found, this constant path can never resolve.
-                        if !found_namespace {
-                            return Outcome::Unresolved;
-                        }
-
-                        // Member not found in any namespace yet - retry in case it's added later. `partial` records
-                        // whether the miss was due to a still-partial ancestor chain, so the unit is re-checked once
-                        // that chain completes.
-                        Outcome::Retry {
-                            partial_ancestors: missing_partial,
+                        _ => {
+                            // Not a namespace (e.g., a constant) - skip
                         }
                     }
                 }
+
+                // If no namespaces were found, this constant path can never resolve.
+                if !found_namespace {
+                    return Outcome::Unresolved;
+                }
+
+                // Member not found in any namespace yet - retry in case it's added later. `partial` records
+                // whether the miss was due to a still-partial ancestor chain, so the unit is re-checked once
+                // that chain completes.
+                Outcome::Retry {
+                    partial_ancestors: missing_partial,
+                }
             }
-            NameRef::Resolved(resolved) => Outcome::Resolved(*resolved.declaration_id()),
         }
     }
 
@@ -1884,19 +1894,6 @@ impl<'a> Resolver<'a> {
         depth
     }
 
-    /// Pre-compute name depths for all names into a `NameId → depth` map. Each name's depth is
-    /// computed once via memoized recursion, then used as an O(1) lookup key during sorting in
-    /// `prepare_units`.
-    pub(crate) fn compute_name_depths(names: &IdentityHashMap<NameId, NameRef>) -> IdentityHashMap<NameId, u32> {
-        let mut cache = IdentityHashMap::with_capacity_and_hasher(names.len(), IdentityHashBuilder);
-
-        for &name_id in names.keys() {
-            Self::name_depth(name_id, names, &mut cache);
-        }
-
-        cache
-    }
-
     /// Drains `pending_work` and classifies items into the resolution queue.
     /// Namespace definitions and constant references are sorted by name depth for deterministic
     /// resolution order. Non-namespace definitions (methods, attrs, variables) are returned
@@ -1910,7 +1907,28 @@ impl<'a> Resolver<'a> {
         let mut const_refs = Vec::new();
         let mut ancestors = vec![*BASIC_OBJECT_ID, *KERNEL_ID, *OBJECT_ID, *MODULE_ID, *CLASS_ID];
         let names = self.graph.names();
-        let depths = Self::compute_name_depths(names);
+        // Memoize name depths on demand for only the names referenced by the pending work. During incremental
+        // resolution this avoids walking every name in the graph just to sort the small subset of units below.
+        // A pending unit references at most one name, so `estimated` (bounded by the total number of names) is a
+        // reasonable capacity that avoids rehashing as depths accumulate.
+        let mut depths: IdentityHashMap<NameId, u32> =
+            IdentityHashMap::with_capacity_and_hasher(estimated.min(names.len()), IdentityHashBuilder);
+
+        // Precompute the lexicographic rank of every document URI. Definitions and references are sorted by
+        // (name depth, URI, offset) below; storing precomputed integer sort keys instead of looking up name
+        // depths and comparing URI strings on every comparison makes sorting substantially cheaper on large graphs.
+        let mut uris: Vec<(&str, UriId)> = self
+            .graph
+            .documents()
+            .iter()
+            .map(|(uri_id, document)| (document.uri(), *uri_id))
+            .collect();
+        uris.sort_unstable();
+        let mut uri_ranks: IdentityHashMap<UriId, u32> =
+            IdentityHashMap::with_capacity_and_hasher(uris.len(), IdentityHashBuilder);
+        for (rank, (_, uri_id)) in uris.into_iter().enumerate() {
+            uri_ranks.insert(uri_id, u32::try_from(rank).expect("more documents than u32::MAX"));
+        }
 
         // Dedup: when multiple files are indexed before resolution runs, pending_work accumulates
         // and the same definition/reference ID can be enqueued more than once.
@@ -1928,23 +1946,28 @@ impl<'a> Resolver<'a> {
                     let Some(definition) = self.graph.definitions().get(&id) else {
                         continue;
                     };
-                    let uri = self.graph.documents().get(definition.uri_id()).unwrap().uri();
+                    let uri_rank = *uri_ranks.get(definition.uri_id()).unwrap();
 
                     match definition {
                         Definition::Class(def) => {
-                            definitions.push((Unit::Definition(id), (*def.name_id(), uri, definition.offset())));
+                            let depth = Self::name_depth(*def.name_id(), names, &mut depths);
+                            definitions.push((Unit::Definition(id), (depth, uri_rank, definition.offset())));
                         }
                         Definition::Module(def) => {
-                            definitions.push((Unit::Definition(id), (*def.name_id(), uri, definition.offset())));
+                            let depth = Self::name_depth(*def.name_id(), names, &mut depths);
+                            definitions.push((Unit::Definition(id), (depth, uri_rank, definition.offset())));
                         }
                         Definition::Constant(def) => {
-                            definitions.push((Unit::Definition(id), (*def.name_id(), uri, definition.offset())));
+                            let depth = Self::name_depth(*def.name_id(), names, &mut depths);
+                            definitions.push((Unit::Definition(id), (depth, uri_rank, definition.offset())));
                         }
                         Definition::ConstantAlias(def) => {
-                            definitions.push((Unit::Definition(id), (*def.name_id(), uri, definition.offset())));
+                            let depth = Self::name_depth(*def.name_id(), names, &mut depths);
+                            definitions.push((Unit::Definition(id), (depth, uri_rank, definition.offset())));
                         }
                         Definition::SingletonClass(def) => {
-                            definitions.push((Unit::Definition(id), (*def.name_id(), uri, definition.offset())));
+                            let depth = Self::name_depth(*def.name_id(), names, &mut depths);
+                            definitions.push((Unit::Definition(id), (depth, uri_rank, definition.offset())));
                         }
                         // SelfReceiver methods create singleton classes, which need
                         // ancestor linearization. Process them in the convergence loop
@@ -1965,11 +1988,9 @@ impl<'a> Resolver<'a> {
                     let Some(constant_ref) = self.graph.constant_references().get(&id) else {
                         continue;
                     };
-                    let uri = self.graph.documents().get(&constant_ref.uri_id()).unwrap().uri();
-                    const_refs.push((
-                        Unit::ConstantRef(id),
-                        (*constant_ref.name_id(), uri, constant_ref.offset()),
-                    ));
+                    let uri_rank = *uri_ranks.get(&constant_ref.uri_id()).unwrap();
+                    let depth = Self::name_depth(*constant_ref.name_id(), names, &mut depths);
+                    const_refs.push((Unit::ConstantRef(id), (depth, uri_rank, constant_ref.offset())));
                 }
                 Unit::Ancestors(id) => {
                     if !seen_ancestors.insert(id) {
@@ -1984,14 +2005,10 @@ impl<'a> Resolver<'a> {
         }
 
         // Sort namespaces based on their name complexity so that simpler names are always first
-        // When the depth is the same, sort by URI and offset to maintain determinism
-        definitions.sort_unstable_by(|(_, (name_a, uri_a, offset_a)), (_, (name_b, uri_b, offset_b))| {
-            (depths.get(name_a).unwrap(), uri_a, offset_a).cmp(&(depths.get(name_b).unwrap(), uri_b, offset_b))
-        });
+        // When the depth is the same, sort by URI rank and offset to maintain determinism
+        definitions.sort_unstable_by_key(|(_, key)| *key);
 
-        const_refs.sort_unstable_by(|(_, (name_a, uri_a, offset_a)), (_, (name_b, uri_b, offset_b))| {
-            (depths.get(name_a).unwrap(), uri_a, offset_a).cmp(&(depths.get(name_b).unwrap(), uri_b, offset_b))
-        });
+        const_refs.sort_unstable_by_key(|(_, key)| *key);
 
         others.sort_unstable_by_key(|(_, key)| *key);
 
@@ -2011,15 +2028,11 @@ impl<'a> Resolver<'a> {
     /// - Class: parent is the singleton class of the original parent class
     /// - Singleton class: recurse as many times as necessary to wrap the original attached object's parent class
     fn singleton_parent_id(&mut self, attached_id: DeclarationId) -> (DeclarationId, bool) {
-        // Base case: if we reached `BasicObject`, then the parent is `Class`
-        if attached_id == *BASIC_OBJECT_ID {
-            return (*CLASS_ID, false);
-        }
-
         let decl = self.graph.declarations().get(&attached_id).unwrap();
 
         match decl {
-            Declaration::Namespace(Namespace::Module(_)) => (*MODULE_ID, false),
+            // Todo may later become a class or module. Until then, use Module as the singleton-parent fallback.
+            Declaration::Namespace(Namespace::Module(_) | Namespace::Todo(_)) => (*MODULE_ID, false),
             Declaration::Namespace(Namespace::SingletonClass(_)) => {
                 // For singleton classes, we keep recursively wrapping parents until we can reach the original attached
                 // object
@@ -2033,14 +2046,15 @@ impl<'a> Resolver<'a> {
                 )
             }
             Declaration::Namespace(Namespace::Class(_)) => {
-                // For classes (the regular case), we need to return the singleton class of its parent
-                let definition_ids = decl.definitions().to_vec();
-
-                let (picked_parent, unresolved_parent) = self.get_parent_class(&definition_ids);
+                // For classes (the regular case), we need to return the singleton class of its superclass
+                let Some((superclass_id, unresolved_superclass)) = self.get_superclass(attached_id) else {
+                    // BasicObject has no superclass, but its singleton class inherits from Class
+                    return (*CLASS_ID, false);
+                };
                 (
-                    self.get_or_create_singleton_class(picked_parent, SingletonAncestors::Deferred)
-                        .expect("parent class should always be a namespace"),
-                    unresolved_parent.is_some(),
+                    self.get_or_create_singleton_class(superclass_id, SingletonAncestors::Deferred)
+                        .expect("superclass should always be a namespace"),
+                    unresolved_superclass.is_some(),
                 )
             }
             _ => {
@@ -2051,11 +2065,18 @@ impl<'a> Resolver<'a> {
         }
     }
 
-    fn get_parent_class(&self, definition_ids: &[DefinitionId]) -> (DeclarationId, Option<NameId>) {
-        let mut explicit_parents = Vec::new();
-        let mut unresolved_parent = None;
+    /// Returns the selected superclass and any unresolved explicit superclass. The top-level `BasicObject` declaration
+    /// is Ruby's root class and is the only class without a superclass.
+    fn get_superclass(&self, declaration_id: DeclarationId) -> Option<(DeclarationId, Option<NameId>)> {
+        if declaration_id == *BASIC_OBJECT_ID {
+            return None;
+        }
 
-        for definition_id in definition_ids {
+        let declaration = self.graph.declarations().get(&declaration_id).unwrap();
+        let mut explicit_superclasses = Vec::new();
+        let mut unresolved_superclass = None;
+
+        for definition_id in declaration.definitions() {
             let definition = self.graph.definitions().get(definition_id).unwrap();
 
             if let Definition::Class(class) = definition
@@ -2066,47 +2087,47 @@ impl<'a> Resolver<'a> {
 
                 match name {
                     NameRef::Resolved(resolved) => {
-                        if let Some(parent_id) = self.resolve_to_namespace(*resolved.declaration_id()) {
-                            explicit_parents.push(parent_id);
+                        if let Some(superclass_id) = self.resolve_to_namespace(*resolved.declaration_id()) {
+                            explicit_superclasses.push(superclass_id);
                         }
                     }
                     NameRef::Unresolved(_) => {
-                        unresolved_parent = Some(*constant_reference.name_id());
+                        unresolved_superclass = Some(*constant_reference.name_id());
                     }
                 }
             }
         }
 
-        // If there's more than one parent class that isn't `Object` and they are different, then there's a superclass
+        // If there's more than one superclass that isn't `Object` and they are different, then there's a superclass
         // mismatch error. TODO: We should add a diagnostic here
-        (
-            explicit_parents.first().copied().unwrap_or(*OBJECT_ID),
-            unresolved_parent,
-        )
+        Some((
+            explicit_superclasses.first().copied().unwrap_or(*OBJECT_ID),
+            unresolved_superclass,
+        ))
     }
 
-    fn linearize_parent_class(
+    fn linearize_superclass(
         &mut self,
-        definition_ids: &[DefinitionId],
+        declaration_id: DeclarationId,
         context: &mut LinearizationContext,
-    ) -> Ancestors {
-        let (picked_parent, unresolved_parent) = self.get_parent_class(definition_ids);
-        let mut result = self.linearize_ancestors(picked_parent, context);
+    ) -> Option<Ancestors> {
+        let (superclass_id, unresolved_superclass) = self.get_superclass(declaration_id)?;
+        let mut result = self.linearize_ancestors(superclass_id, context);
 
-        if let Some(name_id) = unresolved_parent {
+        if let Some(name_id) = unresolved_superclass {
             context.partial = true;
 
-            // Insert the unresolved parent as a Partial ancestor at the front of the chain, so it
+            // Insert the unresolved superclass as a Partial ancestor at the front of the chain, so it
             // appears before the default Object ancestors
             let ancestors = match &mut result {
                 Ancestors::Complete(ids) | Ancestors::Cyclic(ids) | Ancestors::Partial(ids) => ids,
             };
             ancestors.insert(0, Ancestor::Partial(name_id));
 
-            result.to_partial()
-        } else {
-            result
+            result = result.to_partial();
         }
+
+        Some(result)
     }
 
     fn mixins_of(&self, definition_id: DefinitionId) -> Option<Vec<Mixin>> {