rigortype 0.4.1 → 0.4.3

data/lib/rigor/inference/refine_self.rb

@@ -0,0 +1,317 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../source/constant_path"
+require_relative "refine_census"
+
+module Rigor
+  module Inference
+    # ADR-121 WD7 — the one function that answers what `self` a `refine` (or a `:refine` literal) at a program point
+    # runs on. The in-effect walk ({InEffectRefinements}) works a {Context} out with these functions for every body,
+    # method and block it enters and records it for each `refine`-shaped node; the census (`ScopeIndexer`'s module-body
+    # walk and its scan of method and refine bodies) reads that record back ({InEffectRefinements#refine_context}), so
+    # the table and the activations charge the same module.
+    module RefineSelf
+      # `here`, for a `refine` call directly at that point; `literal`, for a `:refine` literal there (which names
+      # `Module#refine` for an alias or a `send` whose method runs where a method defined there does: in a module's
+      # `class << self` body that is the module, though a `refine` call there runs on the singleton class); and
+      # `instance` / `singleton`, for a method defined there on the instance / singleton side. Each is a module name,
+      # the names a constant's spelling can denote (an Array, innermost first, for a module only another file may
+      # declare), the wildcard (a module the walk cannot name), {CLASS}, {MAIN}, {ANONYMOUS} or {REFINEMENT}.
+      # `deferred` is true inside a method body (a `def`, a `define_method` block), where a `refine` runs only once the
+      # method is called.
+      # `own_method` is true inside a singleton `def` of a module the walk names ({.def_body}), and in the blocks that
+      # keep its `self`: `here` is then that module itself, so a `refine X do … end` written there refines X for it
+      # once the method is called, and the census records its rows where it would otherwise charge a wildcard.
+      # `remote` is true in the body of an eval on a constant (`M.module_eval { … }`, and a `class << self` there),
+      # whose file need not declare the module it runs on: a singleton method defined there is not `own_method`.
+      Context = Data.define(:here, :literal, :instance, :singleton, :deferred, :own_method, :remote)
+      # A plain class, or an instance of one: `Class` undefines `refine`, so a `refine` there is the class's own
+      # method (#1689) and a `:refine` literal is data.
+      CLASS = :class
+      # The top level's `main`, which has no `refine`.
+      MAIN = :main
+      # A module a bare `Module.new { … }` creates, which the census names by its position.
+      ANONYMOUS = :anonymous
+      # The refinement a `refine` block creates, where a method defined on its singleton side (`def self.x`, a
+      # `define_singleton_method` block, a `class << self` body) runs. `using` rejects a refinement with `TypeError`,
+      # so a `refine` there reaches no `using` span and the census charges it to nothing.
+      REFINEMENT = :refinement
+
+      # Core iteration methods: the Enumerable protocol never rebinds `self` in their block.
+      CORE_ITERATORS = Set[
+        :each, :each_with_index, :each_with_object, :each_pair, :each_key, :each_value, :map, :flat_map, :times,
+        :select, :reject
+      ].freeze
+      LITERALS = [Prism::ArrayNode, Prism::HashNode, Prism::RangeNode, Prism::IntegerNode, Prism::FloatNode,
+                  Prism::StringNode, Prism::InterpolatedStringNode, Prism::SymbolNode].freeze
+      NAMED_RECEIVERS = [Prism::ConstantReadNode, Prism::ConstantPathNode, Prism::LocalVariableReadNode,
+                         Prism::InstanceVariableReadNode].freeze
+      METHOD_BLOCK_CALLS = Set[:define_method, :define_singleton_method].freeze
+      INSTANCE_EVAL_CALLS = Set[:instance_eval, :instance_exec].freeze
+      # Bindings of a local or an instance variable that are not a plain write: each may hold any value.
+      VARIABLE_BINDINGS = [
+        Prism::LocalVariableOperatorWriteNode, Prism::LocalVariableOrWriteNode, Prism::LocalVariableAndWriteNode,
+        Prism::LocalVariableTargetNode, Prism::RequiredParameterNode, Prism::OptionalParameterNode,
+        Prism::RestParameterNode, Prism::KeywordRestParameterNode, Prism::RequiredKeywordParameterNode,
+        Prism::OptionalKeywordParameterNode, Prism::BlockParameterNode, Prism::BlockLocalVariableNode,
+        Prism::InstanceVariableOperatorWriteNode, Prism::InstanceVariableOrWriteNode,
+        Prism::InstanceVariableAndWriteNode, Prism::InstanceVariableTargetNode
+      ].freeze
+      # Bindings of a constant other than a bare `K = …`, matched by the constant's last segment.
+      CONSTANT_BINDINGS = [
+        Prism::ConstantOrWriteNode, Prism::ConstantOperatorWriteNode, Prism::ConstantAndWriteNode,
+        Prism::ConstantTargetNode, Prism::ConstantPathTargetNode
+      ].freeze
+      CONSTANT_PATH_BINDINGS = [
+        Prism::ConstantPathWriteNode, Prism::ConstantPathOrWriteNode, Prism::ConstantPathOperatorWriteNode,
+        Prism::ConstantPathAndWriteNode
+      ].freeze
+
+      private_constant :CORE_ITERATORS, :LITERALS, :NAMED_RECEIVERS, :METHOD_BLOCK_CALLS, :INSTANCE_EVAL_CALLS,
+                       :VARIABLE_BINDINGS, :CONSTANT_BINDINGS, :CONSTANT_PATH_BINDINGS
+
+      module_function
+
+      def wildcard = RefineCensus.wildcard
+
+      # The top level: `main`; a method defined there is `Object`'s, which any module may run.
+      def top = context(MAIN, wildcard, MAIN)
+
+      # A body whose `self` the walk cannot name.
+      def unknown = context(wildcard, wildcard, wildcard)
+
+      def context(here, instance, singleton, deferred: false, literal: here, own_method: false, remote: false)
+        Context.new(here: here, literal: literal, instance: instance, singleton: singleton, deferred: deferred,
+                    own_method: own_method, remote: remote)
+      end
+
+      # A `module` body (or a `Module.new` block) of the module `name` (nil when the walk cannot name it, or
+      # {ANONYMOUS}): its instance methods run on whatever includes or extends it, its singleton methods on it.
+      def module_body(name)
+        return unknown if name.nil?
+
+        context(name, wildcard, name)
+      end
+
+      # A `class` body (or a `Class.new` / `Struct.new` / `Data.define` block): `self` is a class; a `Module`
+      # subclass's instances are modules the walk cannot name.
+      def class_body(module_subclass) = context(CLASS, module_subclass ? wildcard : CLASS, CLASS)
+
+      # A `class << expr` body: `self` is a singleton class, so a `refine` call there is its own method; for
+      # `class << self` its methods (and a `:refine` literal an alias there names) run on the enclosing `self`, for any
+      # other expression on an object the walk cannot name.
+      def singleton_class_body(parent, of_self)
+        runs_on = of_self ? parent.singleton : wildcard
+        context(CLASS, runs_on, CLASS, literal: runs_on, remote: of_self && parent.remote)
+      end
+
+      # A method body defined in `parent` on the instance or singleton side: `self` is what that side runs on, and a
+      # method defined inside it is defined on something the walk cannot name.
+      def method_body(parent, singleton)
+        context(singleton ? parent.singleton : parent.instance, wildcard, wildcard, deferred: true)
+      end
+
+      # A `def` body in `parent`: on no receiver an instance method, on `self` (or on the constant that is the last
+      # segment of the module `parent` names, `def M.x` inside `module M`) a singleton one, and on any other object a
+      # method defined on something the walk cannot name. A singleton method of a module the walk names is the
+      # module's own (`own_method`): `def self.x`, or a `def` written in that module's `class << self`
+      # (`parent.instance` is the module there). `self` is then the module itself, whichever way the method is called,
+      # so a `refine` in it refines for that module; for an instance `def`, whose `parent.instance` is the wildcard,
+      # Ruby runs it on whatever module extends the owner. `def M.x` is not marked, as the constant names the module by
+      # its last segment only, and neither is a method an eval on a constant defines (`remote`): its file need not
+      # declare the module, so the lookup of a refine body, which consults the files that do, would not see it.
+      def def_body(parent, receiver)
+        return mark_own_method(method_body(parent, false), parent) if receiver.nil?
+        return unknown.with(deferred: true) unless lexical_self_receiver?(receiver, parent)
+
+        context = method_body(parent, true)
+        receiver.is_a?(Prism::SelfNode) ? mark_own_method(context, parent) : context
+      end
+
+      def mark_own_method(context, parent)
+        named_module?(context.here) && !parent.remote ? context.with(own_method: true) : context
+      end
+
+      def lexical_self_receiver?(receiver, context)
+        return true if receiver.is_a?(Prism::SelfNode)
+
+        here = context.here
+        receiver.is_a?(Prism::ConstantReadNode) && here.is_a?(String) && here.split("::").last == receiver.name.to_s
+      end
+
+      # A module name the walk can charge a `refine` to: not the wildcard, {CLASS}, {MAIN} or {ANONYMOUS}, and not the
+      # several names a constant's spelling can denote.
+      def named_module?(here) = here.is_a?(String) && here != wildcard
+
+      # The context inside the block of `node` (a block-carrying call, or a lambda) written in `parent`. `eval_names`
+      # are the modules a `*_eval` / `*_exec` call's constant receiver may name ({.eval_receiver_names}), or nil; the
+      # given block answers whether a constant, local or instance variable receiver holds a literal ({.keeps_self?}).
+      # A block keeps `self` only where its call is known to: a core iteration method on a receiver whose value is a
+      # literal in this file, and a `refine` call (its body is the refinement, handled by the reader). A `*_eval` /
+      # `*_exec` block runs on its receiver, a `define_method` / `define_singleton_method` block is a method body, and
+      # a `Module.new` / `Class.new` block is a module / class body. Any other block (a DSL may `module_eval` it,
+      # `tap`, `loop`, a project method, a core method's name on any other receiver), a lambda, and every block at the
+      # top level may run under any `self`.
+      def block(parent, node, eval_names, &)
+        return unknown if node.is_a?(Prism::LambdaNode)
+        return refinement_body(parent) if node.name == :refine
+        return eval_body(parent, node, eval_names) if RefineCensus::SELF_EVAL_CALLS.include?(node.name)
+        return meta_new_body(node) if ScopeIndexer.meta_new_constant_rvalue?(node)
+        return unknown if parent.here == MAIN
+        return method_body(parent, node.name == :define_singleton_method) if method_block?(node)
+        return parent if keeps_self?(node, &)
+
+        unknown
+      end
+
+      def method_block?(node) = METHOD_BLOCK_CALLS.include?(node.name) && RefineCensus.self_call?(node)
+
+      # The block of a `refine` call: a `refine` written in it (a nested one) is charged where the call is, but `self`
+      # is the refinement, so a method defined in it is defined on something the walk cannot name: a singleton method
+      # on the refinement itself ({REFINEMENT}, whichever the method the `refine` call sits in, as long as the module it
+      # refines for is one), an instance method on an instance of the refined class (the wildcard), not on the module
+      # around.
+      def refinement_body(parent)
+        singleton = module_here?(parent.here) ? REFINEMENT : parent.singleton
+        parent.with(instance: refinement_side(parent.instance), singleton: singleton, own_method: false)
+      end
+
+      def refinement_side(side) = side.is_a?(String) || side.is_a?(Array) ? wildcard : side
+
+      # Is `here` a module a `refine` there refines for (so its block is a refinement's body), or the refinement itself?
+      def module_here?(here) = named_module?(here) || here.is_a?(Array) || here == ANONYMOUS || here == REFINEMENT
+
+      def meta_new_body(node)
+        ScopeIndexer.module_new_call?(node) ? module_body(ANONYMOUS) : class_body(false)
+      end
+
+      # A core iteration method on a receiver whose value is a literal in this file: a literal, or a constant, local
+      # or instance variable the block answers true for ({.literal_bindings}). Any other name, even on a literal, and
+      # any other receiver may be a project method that runs the block under another `self`: on Ruby 4.0.5
+      # `Config.each { refine(String) { … } }` with `def self.each(&blk) = Ext.module_eval(&blk)` refines for `Ext`,
+      # and so does `[1].configure { … }` with `class Array; def configure(&blk) = Ext.module_eval(&blk); end`.
+      def keeps_self?(node)
+        return false unless CORE_ITERATORS.include?(node.name)
+
+        receiver = node.receiver
+        return true if literal?(receiver)
+
+        NAMED_RECEIVERS.any? { |klass| receiver.is_a?(klass) } && block_given? && yield(receiver)
+      end
+
+      def literal?(node) = LITERALS.any? { |klass| node.is_a?(klass) }
+
+      # A literal, or a literal's `.freeze`.
+      def literal_value?(node)
+        return true if literal?(node)
+
+        node.is_a?(Prism::CallNode) && node.name == :freeze && node.arguments.nil? && node.block.nil? &&
+          literal?(node.receiver)
+      end
+
+      # The constants (by qualified name), locals and instance variables (by name) that `root` binds, every binding a
+      # plain write of a literal ({.literal_value?}). A name any other binding gives a value (a parameter, a
+      # multiple assignment, `||=`, `+=`, a `const_set`, a path write `A::K = …`) is not one, wherever in the file
+      # it sits.
+      def literal_bindings(root)
+        literal = Set.new
+        other = Set.new
+        spoiled = ScopeIndexer.loose_constant_segments(root).dup
+        collect_bindings(root, [], literal, other, spoiled)
+        (literal - other).reject { |key| key.is_a?(String) && spoiled.include?(key.split("::").last) }.to_set.freeze
+      end
+
+      def collect_bindings(node, prefix, literal, other, spoiled)
+        case node
+        when Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode
+          return collect_declaration_bindings(node, prefix, literal, other, spoiled)
+        when Prism::LocalVariableWriteNode, Prism::InstanceVariableWriteNode
+          bind(node.value, node.name, literal, other)
+        when *VARIABLE_BINDINGS then other << node.name if node.name
+        else collect_constant_binding(node, prefix, literal, other, spoiled)
+        end
+        node.rigor_each_child { |child| collect_bindings(child, prefix, literal, other, spoiled) }
+      end
+
+      def collect_constant_binding(node, prefix, literal, other, spoiled)
+        case node
+        when Prism::ConstantWriteNode then bind(node.value, (prefix + [node.name.to_s]).join("::"), literal, other)
+        when *CONSTANT_BINDINGS then spoiled << node.name.to_s
+        when *CONSTANT_PATH_BINDINGS then spoiled << node.target.name.to_s
+        end
+      end
+
+      # A `class` / `module` body's constants are its own; a `class << expr` body's are the singleton class's, which
+      # no read outside it names.
+      def collect_declaration_bindings(node, prefix, literal, other, spoiled)
+        if node.is_a?(Prism::SingletonClassNode)
+          collect_bindings(node.expression, prefix, literal, other, spoiled)
+          inner = prefix + ["<singleton>"]
+        else
+          inner = Source::ConstantPath.declaration_prefix(prefix, node.constant_path) || prefix
+          superclass = node.is_a?(Prism::ClassNode) && node.superclass
+          collect_bindings(superclass, prefix, literal, other, spoiled) if superclass
+        end
+        collect_bindings(node.body, inner, literal, other, spoiled) if node.body
+      end
+
+      def bind(value, key, literal, other) = (literal_value?(value) ? literal : other) << key
+
+      # The key {.literal_bindings} holds for a receiver read in `prefix`: a constant's innermost lexical candidate (the
+      # one Ruby's lookup finds once this file's write defines it), a local's or an instance variable's name.
+      def binding_key(receiver, prefix)
+        case receiver
+        when Prism::ConstantReadNode, Prism::ConstantPathNode
+          ScopeIndexer.constant_receiver_candidates(receiver, prefix).first
+        else receiver.name
+        end
+      end
+
+      # A `*_eval` / `*_exec` block: on `self` (or no receiver) it keeps `self`, on a constant it runs on the module the
+      # constant names (any name its spelling can denote), on anything else on a module the walk cannot name. A `def` in
+      # an `instance_eval` binds on the receiver's singleton, so its instance side is the receiver itself.
+      def eval_body(parent, node, eval_names)
+        here = RefineCensus.self_call?(node) ? parent.here : eval_names
+        here = here.first if here.is_a?(Array) && here.size == 1
+        return context(CLASS, CLASS, CLASS, deferred: parent.deferred) if here == CLASS
+        return unknown unless here.is_a?(String) || here.is_a?(Array) || here == ANONYMOUS || here == REFINEMENT
+        return unknown if here == wildcard
+
+        instance = INSTANCE_EVAL_CALLS.include?(node.name) ? here : wildcard
+        remote = parent.remote || !RefineCensus.self_call?(node)
+        context(here, instance, here, deferred: parent.deferred, remote: remote)
+      end
+
+      # The modules a `*_eval` / `*_exec` call `node` written in `context` at the lexical `prefix` may run its block
+      # on, when its receiver is a constant: every name the constant's spelling can denote, innermost first, as another
+      # file may declare any of them (`M.module_eval { … }` in `module L` runs on `L::M` where some file declares it);
+      # a `self::`-anchored one as the method walk resolves it (`ScopeIndexer.eval_receiver_prefix`). Else nil.
+      def eval_receiver_names(node, prefix, context)
+        return nil unless RefineCensus::SELF_EVAL_CALLS.include?(node.name) && !RefineCensus.self_call?(node)
+
+        receiver = node.receiver
+        if Source::ConstantPath.qualified_name_or_nil(receiver)
+          return ScopeIndexer.constant_receiver_candidates(receiver, prefix)
+        end
+
+        here = context.here
+        self_prefix = here.is_a?(String) && here != wildcard ? here.split("::") : []
+        resolved = ScopeIndexer.eval_receiver_prefix(node, self_prefix, prefix, unnameable_self: self_prefix.empty?)
+        [resolved.join("::")] unless resolved.nil? || resolved.empty?
+      end
+
+      # The modules a context's `refine` call (or, with `literal`, its `:refine` literal) may refine for, as names a
+      # table row can hold: the module, each name a constant's spelling can denote, else the wildcard.
+      def charged_modules(context, literal: false)
+        here = literal ? context.literal : context.here
+        case here
+        when String then [here]
+        when Array then here
+        else [wildcard]
+        end
+      end
+    end
+  end
+end

data/lib/rigor/inference/refined_dispatch/class_object.rb

@@ -0,0 +1,350 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Inference
+    module RefinedDispatch
+      # Issue #1752 — the lookup of a class object, which Ruby walks like any object's: a refinement of `Object`,
+      # `Module`, `Class`, `Kernel` or `BasicObject` answers `Integer.oo`, because a class object is an `Object`.
+      #
+      # The walk is `C`'s singleton class with the modules it extends, then each superclass's singleton class with its
+      # extends, then the instance levels of `Class` (a class only), `Module`, `Object`, `Kernel` and `BasicObject`.
+      # A singleton class is a level whose own entry is a {SingletonClass}: a refinement table key names an instance
+      # side, so it never matches one (`refine C.singleton_class` records a class-unknown row), and it defines the
+      # name through its own singleton methods. An extended module is an instance-side entry, so `refine(Ext)`
+      # answers `C.z` where `C` extends `Ext` (Ruby 4.0.5).
+      #
+      # Every place the walk cannot read makes the whole walk unreadable (nil), where each reader declines: a chain
+      # cut at its limit or holding a mixin the tables cannot name, a superclass the tables do not know (`class K <
+      # <expr>`, `K = Class.new(Parent)`, an external superclass RBS does not declare), a class some constant write
+      # may have made (`Point = Struct.new(:x)`, whose superclass the tables do not record). A singleton level whose
+      # class records an `extend` the chain did not place there is read as `mixed` ({.skipped_extend?}).
+      module ClassObject
+        EMPTY = [].freeze
+        # The classes on every class object's lookup: the instance sides that hold `Class#new`, `Module#name` and
+        # `Object#tap`. A class no table places among them may still be one a class object reaches only when it is a
+        # module or a class the walk cannot place (`ClassObject.reachable?`).
+        TAIL_CLASSES = %w[Class Module Object Kernel BasicObject].freeze
+        private_constant :EMPTY
+
+        module_function
+
+        # `[[level class, entries, mixed, every entry], …]` in {RefinedDispatch.levels}' shape for the class object
+        # `class_name`, or nil when the walk cannot be read. A singleton level's class is a {SingletonClass}.
+        def levels(scope, class_name)
+          environment = scope.environment
+          return nil if environment.nil?
+          return rbs_levels(scope, class_name) if environment.class_known?(class_name)
+
+          project_levels(scope, class_name)
+        end
+
+        # RBS's singleton ancestry: each singleton class a level of its own, `mixed` where the project extends it at
+        # a position RBS does not record, and each instance side (a declared `extend`, `Class`, `Module`, …) a level
+        # `mixed` where the project mixes into it. `from` drops the leading singleton classes a project level already
+        # holds.
+        def rbs_levels(scope, class_name, from: 0)
+          loader = scope.environment&.rbs_loader
+          pairs = loader ? loader.singleton_ancestors_for(class_name) : EMPTY
+          return nil if pairs.empty?
+
+          readable(pairs.drop(from).map do |kind, name|
+            kind == :instance ? instance_level(scope, name) : singleton_level(scope, name)
+          end)
+        end
+
+        # RBS's instance ancestry of `class_name` (`Module`'s, for a module object's tail), each a level.
+        def rbs_instance_levels(scope, class_name)
+          loader = scope.environment&.rbs_loader
+          names = loader ? loader.ancestor_names_for(class_name) : EMPTY
+          return nil if names.empty?
+
+          readable(names.map { |name| instance_level(scope, name) })
+        end
+
+        def readable(levels) = levels.include?(nil) ? nil : levels
+
+        # A `mixed` level carries the modules the project mixes in beside its own entry, so a refinement of one of them
+        # makes the walk past the level {UNKNOWN} (`RefinedDispatch.targeted_after?`) and `call.undefined-method`'s
+        # reach holds it. Nil when that mixin chain cannot be read.
+        def instance_level(scope, name)
+          return [name, [name], false] unless RefinedDispatch.project_mixin?(scope, name)
+
+          mixins = mixin_entries(scope, name, :instance)
+          mixins && [name, [name, *mixins], true]
+        end
+
+        def singleton_level(scope, name)
+          return nil if instance_unreadable?(scope, name)
+
+          own = SingletonClass.new(name)
+          return [own, [own], false] unless singleton_mixin?(scope, name)
+
+          mixins = mixin_entries(scope, name, :singleton)
+          mixins && [own, [own, *mixins], true]
+        end
+
+        # The names of the modules on `name`'s own level of its project chain on `side`, an unnamed entry's candidate
+        # names included, or nil when the chain is cut or holds a mixin the tables cannot name.
+        def mixin_entries(scope, name, side)
+          chain = Scope::ResolutionChain.for(scope, name, side, :methods)
+          chain.record(scope) if Analysis::DependencyRecorder.active?
+          return nil if unreadable?(chain)
+          return EMPTY if chain.level_count.zero?
+
+          names = level_names(chain, 0)
+          return nil if side == :singleton && skipped_extend?(scope, name, names)
+
+          names.reject { |entry| entry == name }
+        end
+
+        # The names on level `index` of `chain` (an unnamed entry's candidate names included), the level's own
+        # singleton entry left out.
+        def level_names(chain, index)
+          chain.level_entries(index).flat_map do |entry|
+            next entry.candidates if entry.external?
+
+            entry.side == :instance ? [entry.name] : EMPTY
+          end.uniq
+        end
+
+        # Does `name` record an `extend` that the chain did not place on `name`'s own singleton level (`entries`, its
+        # names or candidate lists)? The chain skips an `extend` of a module already on the lookup, as Ruby does, but
+        # the tables record `class << self; prepend M` (and `singleton_class.prepend(M)`) as an `extend` too, and
+        # Ruby's `prepend` puts the module ahead of the class's own singleton methods again (`class Base3 < Top;
+        # class << self; prepend Ext` with `Top` extending `Ext`). Such a level cannot place that module, so it reads as
+        # `mixed`.
+        def skipped_extend?(scope, name, entries)
+          raws = scope.discovered_extends[name]
+          return false if raws.nil? || raws.empty?
+
+          placed = entries.flat_map { |entry| entry.is_a?(Array) ? entry : [entry] }
+          raws.any? { |raw| scope.ancestor_name_candidates(name, raw).none? { |candidate| placed.include?(candidate) } }
+        end
+
+        # The project's singleton-side `Scope::ResolutionChain` (`C`'s singleton, its `extend`s' instance chains,
+        # then each project superclass's), spliced into RBS's singleton ancestry at an external superclass, or
+        # followed by the implicit tail after the last project class.
+        def project_levels(scope, class_name)
+          chain = Scope::ResolutionChain.for(scope, class_name, :singleton, :methods)
+          chain.record(scope) if Analysis::DependencyRecorder.active?
+          return nil if unreadable?(chain) || chain.level_count.zero?
+
+          out = []
+          chain.level_count.times do |index|
+            level_class = chain.level_classes[index]
+            return splice_external(scope, out, chain.level_entries(index)) if level_class.nil?
+            return nil if instance_unreadable?(scope, level_class)
+
+            own = SingletonClass.new(level_class)
+            every = chain.level_entries(index).map { |entry| level_entry(scope, entry, own) }
+            out << [own, every.grep_v(Array), skipped_extend?(scope, level_class, every), every]
+          end
+          tail = implicit_tail(scope, chain.level_classes[chain.level_count - 1])
+          tail && out.concat(tail)
+        end
+
+        # A chain cut at its limit, or holding a mixin the tables cannot name.
+        def unreadable?(chain) = chain.truncated? || chain.wildcard_mixin?
+
+        # Is `name`'s instance chain unreadable? A mixin the tables cannot name there includes the one an
+        # `included` hook makes (`base.extend(ClassMethods)`, `base.singleton_class.include(CM)`), which installs
+        # singleton methods on `name` that its singleton chain never records.
+        def instance_unreadable?(scope, name)
+          chain = Scope::ResolutionChain.for(scope, name, :instance, :methods)
+          chain.record(scope) if Analysis::DependencyRecorder.active?
+          unreadable?(chain)
+        end
+
+        def level_entry(scope, entry, own)
+          return own if !entry.external? && entry.side == :singleton && entry.name == own.of
+          return SingletonClass.new(entry.name) if !entry.external? && entry.side == :singleton
+
+          RefinedDispatch.entry_name(scope, entry) || RefinedDispatch.unnamed(entry)
+        end
+
+        # An external superclass stands for its whole singleton ancestry, which RBS gives when it declares the class.
+        #
+        # ADR-46 — a project superclass with no methods is not admitted by the `:methods` resolver, so it is external
+        # here and the walk is unreadable; each candidate's `class:` edge lets a new file that gives it a method (and so
+        # a project entry) re-check the consumer.
+        def splice_external(scope, out, entries)
+          external = entries.find(&:external?)
+          if Analysis::DependencyRecorder.active?
+            external&.candidates&.each { |candidate| Analysis::DependencyRecorder.read_last_segment(:class, candidate) }
+          end
+          name = external&.candidates&.find { |candidate| scope.environment&.class_known?(candidate) }
+          tail = name && rbs_levels(scope, name)
+          tail && out.concat(tail)
+        end
+
+        # What follows the last project class on the walk: `Module` onwards for a module; RBS's singleton ancestry
+        # past the class's own singleton for a class RBS declares (a reopened core class, a `sig/` class);
+        # `Object`'s for a class with no superclass written. Nil where the superclass is not known: one the tables
+        # record as unknown, and one a constant write may have given the class (a class only a constant write names
+        # carries no superclass entry, and a reopening keeps the superclass that write made).
+        def implicit_tail(scope, name)
+          return rbs_instance_levels(scope, "Module") if module?(scope, name)
+          return nil if unknown_superclass?(scope, name)
+          return rbs_levels(scope, name, from: 1) if scope.environment&.class_known?(name)
+
+          rbs_levels(scope, "Object")
+        end
+
+        def module?(scope, name)
+          scope.discovered_parameter_envelopes[name]&.key?(Scope::DiscoveryIndex::ENVELOPE_MODULE_MARK) ||
+            scope.environment&.rbs_module?(name) || false
+        end
+
+        def unknown_superclass?(scope, name)
+          superclasses = scope.discovered_superclasses
+          return true if superclasses.key?(name) && superclasses[name].nil?
+          return true if scope.discovered_parameter_envelopes[name]&.key?(
+            Scope::DiscoveryIndex::ENVELOPE_META_SUPERCLASS_MARK
+          )
+
+          Analysis::DependencyRecorder.read_last_segment(:constant, name) if Analysis::DependencyRecorder.active?
+          !scope.bound_constant_names(name).empty?
+        end
+
+        # Does the project mix a module into `name`'s singleton class, at a position RBS does not record?
+        def singleton_mixin?(scope, name)
+          Analysis::DependencyRecorder.read_last_segment(:class, name) if Analysis::DependencyRecorder.active?
+          return true if scope.discovered_extends.key?(name)
+
+          Scope::ResolutionChain.for(scope, name, :singleton, :methods).wildcard_mixin?
+        end
+
+        # Does the singleton class of `name` define `method_name` itself: a singleton method the project writes in
+        # `name`'s own body (`def self.x`, `class << self`, an `attr_*` there), or one RBS declares on `name`'s
+        # singleton? A method the extends fold copied onto the singleton from a module `name` extends is that
+        # module's, found where the module sits.
+        def defines?(scope, name, method_name)
+          return true if own_singleton_definer?(scope, name, method_name)
+
+          definition = ExternalAncestorResolution.method_definition(name, method_name, :singleton, scope: scope)
+          ExternalAncestorResolution.declared_on_class?(definition, name)
+        end
+
+        # A singleton `def` is the class's own unless it is the def a module the class extends holds, which the extends
+        # fold copied ({.fold_copy?}). A singleton name without a node of its own (`attr_reader` or `define_method` in
+        # `class << self`) counts when the existence table holds it and the class's envelope table records it, which
+        # the fold never writes. A `define_singleton_method` in the body records only the opaque envelope entry, so it
+        # is no definer here; the typed arm reads that entry as a rewritten singleton name ({.rewritten?}).
+        def own_singleton_definer?(scope, name, method_name)
+          node = scope.singleton_def_for(name, method_name)
+          return true if node && !fold_copy?(scope, name, method_name)
+          return false unless scope.discovered_method?(name, method_name, :singleton)
+
+          node.nil? || scope.parameter_envelopes_of(name).key?([:singleton, method_name.to_sym])
+        end
+
+        # Is `name`'s singleton `def` of the name the receiverless instance `def` of the module its `Module.nesting`
+        # starts with, which the extends fold copied? The node is that module's own
+        # (`SingletonHookDecline.copied_from?`), or, where the two tables came from two parses of the file, one with
+        # its location and text, and no site of a singleton `def` of the name is recorded for `name` (the fold copies
+        # nodes, not sites).
+        def fold_copy?(scope, name, method_name)
+          head = SingletonHookDecline.def_head(scope, name, method_name)
+          return false if head.nil? || head == name
+          return true if SingletonHookDecline.copied_from?(scope, head, method_name, name)
+
+          node = scope.singleton_def_for(name, method_name)
+          source = scope.user_def_for(head, method_name)
+          !node.nil? && node.receiver.nil? && !source.nil? && same_def?(node, source) &&
+            scope.discovery.discovered_singleton_def_sources.dig(name, method_name.to_sym).nil?
+        end
+
+        def same_def?(node, other)
+          node.location.start_offset == other.location.start_offset &&
+            node.location.end_offset == other.location.end_offset && node.slice == other.slice
+        end
+
+        # The typed arm's answer at a singleton level (`entries` is every entry, an unnamed one kept as its candidate
+        # names): {Winner}, {UNKNOWN}, nil (the class object's own lookup answers), `:continue`, or `:continue_unsure`
+        # when only an unnamed entry may answer, so a refinement the walk reaches later is {UNKNOWN}
+        # (`RefinedDispatch.walk`). The tables record `class << self; prepend M` (and `singleton_class.prepend(M)`) as
+        # an `extend`, so a module on the level may sit ahead of the singleton class or of another module: one entry
+        # that answers decides, several that answer decide only when none of them is refined.
+        def walk_level(scope, entries, method_name, targets, unread)
+          answers = entries.filter_map { |entry| entry_answer(scope, entry, method_name, targets, unread) }
+          return :continue if answers.empty?
+
+          known = answers.reject { |answer| answer == UNNAMED }
+          return :continue_unsure if known.empty?
+          return known.first.answer if answers.size == 1
+
+          known.all? { |answer| answer.answer.nil? } ? nil : UNKNOWN
+        end
+
+        Answer = Data.define(:answer)
+        # An entry no table names (an `extend` of a module from outside the analysed paths): it may define the name.
+        UNNAMED = Answer.new(:unnamed)
+        private_constant :Answer, :UNNAMED
+
+        def entry_answer(scope, entry, method_name, targets, unread)
+          if entry.is_a?(Array)
+            refined = entry.any? { |candidate| targets.key?(candidate) || unread.key?(candidate) }
+            return refined ? Answer.new(UNKNOWN) : UNNAMED
+          end
+
+          if entry.is_a?(SingletonClass)
+            return Answer.new(UNKNOWN) if rewritten?(scope, entry.of, method_name)
+          else
+            return Answer.new(UNKNOWN) if unread.key?(entry)
+
+            refining = targets[entry]
+            return Answer.new(Winner.new(module_name: refining, refined_class: entry)) if refining
+          end
+          Answer.new(nil) if RefinedDispatch.defines?(scope, entry, method_name)
+        end
+
+        # Does the project rewrite `name`'s singleton methods in a way the walk cannot read: the class's dynamic mark
+        # (a `class_eval`, a computed definer, a `send`), or an opaque envelope entry for the singleton name (a
+        # `define_singleton_method`, a `def Const.x` written outside `name`'s body, an alias or a wrapping macro)?
+        def rewritten?(scope, name, method_name)
+          bucket = scope.parameter_envelopes_of(name)
+          bucket.key?(Scope::DiscoveryIndex::ENVELOPE_DYNAMIC_MARK) ||
+            Source::ParameterEnvelope.opaque?(bucket[[:singleton, method_name.to_sym]])
+        end
+
+        # Every class and module whose refinements a call on the class object `class_name` may reach, for
+        # `call.undefined-method`'s decline: each name on the levels (an unnamed entry's candidates and a `mixed`
+        # level's project mixins included), and the RBS ancestry of a module an extend names that the project does
+        # not declare. Nil when the walk cannot be read.
+        def reach(scope, class_name)
+          levels = levels(scope, class_name)
+          return nil if levels.nil?
+
+          names = Set.new
+          levels.each do |_level_class, entries, _mixed, every|
+            (every || entries).each { |entry| add_reach(scope, names, entry) }
+          end
+          names
+        end
+
+        def add_reach(scope, names, entry)
+          return names.merge(entry) if entry.is_a?(Array)
+          return if entry.is_a?(SingletonClass)
+
+          names << entry
+          return if scope.discovered_classes.key?(entry)
+
+          loader = scope.environment&.rbs_loader
+          names.merge(loader.ancestor_names_for(entry)) if loader
+        end
+
+        # Can a refined-class key sit on some class object's lookup the walk could not read? Every class object
+        # reaches the {TAIL_CLASSES} and whatever modules it extends, so only a class known to be none of those is
+        # out of reach: a project class that is not a module, or one RBS declares as a class. A key nothing declares
+        # may be a module.
+        def reachable?(scope, key)
+          return true if TAIL_CLASSES.include?(key)
+          return false if scope.discovered_classes.key?(key) && !module?(scope, key)
+
+          environment = scope.environment
+          !(environment&.class_known?(key) && !environment.rbs_module?(key))
+        end
+      end
+    end
+  end
+end