rigortype 0.4.1 → 0.4.2

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

@@ -0,0 +1,403 @@
+# frozen_string_literal: true
+
+require_relative "../builtins/cruby_definers"
+
+module Rigor
+  module Inference
+    module RefinedDispatch
+      # Issue #1740 — does the receiver's own lookup answer a call ahead of every refinement in effect, so that
+      # `call.wrong-arity` and `call.argument-type-mismatch` may check it against the receiver's own method? Ruby
+      # finds a method the receiver's class (or a nearer ancestor) defines before it consults an ancestor's
+      # refinement: under `refine Object do def center(a, b, c)`, `"x".center(1, 2, 3)` still runs `String#center`
+      # and raises.
+      #
+      # It answers yes only from positive knowledge (the caller has already declined on an in-effect list that
+      # carries {InEffectRefinements::UNKNOWN} or an opaque module), and every condition it cannot prove is a no:
+      #
+      # - it reads the RAW refinement table, every name a `refine` argument's spelling can denote and the wildcard
+      #   rows included, never {RefinedDispatch.resolved}'s typing subset: a decline needs only that a row may
+      #   denote a class on the walk;
+      # - no in-effect row may name a class the walk cannot name, a project subclass of the receiver's class (a
+      #   value typed as the class may be one), or a module the receiver's levels do not hold (`obj.extend(M)`,
+      #   or a subclass's mixin);
+      # - walking {RefinedDispatch.levels} from the most derived, the first level or entry that is refined or
+      #   defines the name must define it, with no `mixed` level (a project mixin RBS does not place) before it;
+      # - that definer must be proven ({.proven_definer?}): RBS alone is not proof.
+      #
+      # It shares the level walk with the typed arm's {RefinedDispatch.winner} and nothing else: the typer types
+      # only from rows the lexical lookup resolves, while a decline must count every row.
+      module OwnMethod # rubocop:disable Metrics/ModuleLength
+        # One candidate definer as `DefinerResolution`'s per-chain answer function reports it, read through the
+        # same four readers as the module's own hit (a call site may not name that one).
+        DefinerHit = Data.define(:answer, :owner, :index, :side)
+        EMPTY = [].freeze
+        private_constant :DefinerHit, :EMPTY
+
+        module_function
+
+        # Is `method_name` on an instance of `class_name` answered by the receiver's own method, ahead of every
+        # refinement the in-effect list `list` (no unknown marker, no opaque module) puts in effect?
+        def answers?(scope, class_name, method_name, list)
+          InEffectRefinements.record_refinement_names(method_name)
+          raw = raw_targets(scope.discovered_refinements, method_name, list)
+          return true if raw.nil?
+
+          add_ancestor_spellings(scope, raw)
+
+          record_targets(scope, raw)
+          return false if raw.each_key.any? { |refined| InEffectRefinements.class_wildcard_key?(scope, refined) }
+
+          levels = RefinedDispatch.levels(scope, class_name)
+          return false if levels.nil?
+          return false if refined_off_levels?(scope, class_name, levels, raw)
+
+          shadowing_definer?(scope, class_name, levels, method_name, raw)
+        end
+
+        # `{refined-class key => [its in-effect refining modules]}` for every key with a row for `method_name` or a
+        # names-wildcard row that `list` puts in effect, by every spelling the table records, or nil when there is
+        # none.
+        def raw_targets(refinements, method_name, list)
+          out = nil
+          refinements.each do |refined, methods|
+            modules = in_effect_modules(methods[method_name], list) |
+                      in_effect_modules(methods[RefinedDispatch.wildcard], list)
+            (out ||= {})[refined] = modules unless modules.empty?
+          end
+          out
+        end
+
+        # Ruby looks a constant up through the refining module's ancestors before the top level, so `refine(Bar)` in
+        # a module that includes `Foo` refines `Foo::Bar` when `Foo` holds one; the table records the lexical
+        # spellings only (`R::Bar`, `Bar`). Each declared `<ancestor>::<last segment>` joins the raw targets for the
+        # same refining module: over-adding only declines.
+        def add_ancestor_spellings(scope, raw)
+          raw.to_a.each do |refined, modules|
+            segment = refined.split("::").last
+            modules.each do |module_name|
+              ancestor_modules(scope, module_name).each do |ancestor|
+                spelling = "#{ancestor}::#{segment}"
+                next unless declared_class?(scope, spelling)
+
+                raw[spelling] = (raw[spelling] || EMPTY) | [module_name]
+              end
+            end
+          end
+        end
+
+        # The modules `module_name` includes or prepends, transitively (`InEffectRefinements.activated_modules`, which
+        # records the chain's edges), itself left out.
+        def ancestor_modules(scope, module_name)
+          return EMPTY if module_name == RefinedDispatch.wildcard
+
+          ancestors = InEffectRefinements.activated_modules(scope, module_name)
+          ancestors.is_a?(Array) ? ancestors - [module_name] : EMPTY
+        end
+
+        def in_effect_modules(rows, list)
+          return EMPTY if rows.nil?
+
+          rows.select { |name| RefinedDispatch.in_effect?([name], list) }
+        end
+
+        # ADR-46 — a refined class appearing or vanishing (a new subclass declaration, a module turning up where a
+        # spelling named nothing), or an edit to a file declaring one (`class Kid` becoming `class Kid < Base`),
+        # moves the answer.
+        def record_targets(scope, raw)
+          return unless Analysis::DependencyRecorder.active?
+
+          raw.each_key do |refined|
+            next if refined == RefinedDispatch.wildcard
+
+            Analysis::DependencyRecorder.read_last_segment(:class, refined)
+            Scope::ResolutionChain.record_class(scope, refined)
+          end
+        end
+
+        # A refined class the receiver's levels do not show, but which a value typed as the receiver's class may
+        # still reach (critique F4): a project subclass of the class, or one whose own level mixes in a refined
+        # module (a module already on the class's levels is prepended again by `prepend`); a class RBS declares as
+        # a subclass; a module not on the levels, which `obj.extend` or a subclass's mixin can put ahead of the
+        # definer; and a module on the levels that some code prepends to an object's singleton class.
+        def refined_off_levels?(scope, class_name, levels, raw)
+          return true if unplaced_target?(scope, raw) || subclass_refined?(scope, class_name, raw)
+
+          on_levels = level_names(levels)
+          raw.each_key.any? do |refined|
+            next object_prepended?(scope, refined) if on_levels.include?(refined)
+            next true if module_name?(scope, refined)
+
+            declared_class?(scope, refined) && !placed_away?(scope, refined, class_name)
+          end
+        end
+
+        # Issue #1820 — can the class `key`, off the receiver's levels, be proven never to sit at or below
+        # `class_name` in an object's ancestry? Only when RBS does not declare it a subclass and its whole instance
+        # chain is read: no cut, no mixin the tables cannot name, no superclass the tables do not know (`class K <
+        # <expr>`, `K = Class.new(Parent)`, a superclass RBS does not declare), and `class_name` nowhere on it.
+        def placed_away?(scope, key, class_name)
+          return false if rbs_subclass?(scope, key, class_name)
+          return rbs_away?(scope, key, class_name) unless project_class?(scope, key)
+
+          chain = Scope::ResolutionChain.for(scope, key, :instance, :methods)
+          chain.record(scope) if Analysis::DependencyRecorder.active?
+          return false if chain.truncated? || chain.wildcard_mixin?
+
+          chain.level_count.times.all? { |index| level_away?(scope, chain, index, class_name) }
+        end
+
+        # A project level is away when it is not `class_name` and its superclass is known; an external superclass
+        # level when RBS declares it and its RBS ancestors do not hold `class_name`.
+        def level_away?(scope, chain, index, class_name)
+          level_class = chain.level_classes[index]
+          return level_class != class_name && !unknown_superclass?(scope, level_class) if level_class
+
+          external = chain.level_entries(index).find(&:external?)
+          name = external&.candidates&.find { |candidate| scope.environment&.class_known?(candidate) }
+          !name.nil? && rbs_away?(scope, name, class_name)
+        end
+
+        def rbs_away?(scope, name, class_name)
+          loader = scope.environment&.rbs_loader
+          ancestors = loader ? loader.ancestor_names_for(name) : EMPTY
+          !ancestors.empty? && !ancestors.include?(class_name)
+        end
+
+        def project_class?(scope, name)
+          scope.discovered_classes.key?(name) || !(scope.discovered_class_sources[name] || EMPTY).empty? ||
+            scope.known_user_class?(name)
+        end
+
+        # A project class whose superclass the tables do not know: `class K < <expr>` (the superclass table records
+        # `nil`) or `K = Class.new(Parent)` (`ENVELOPE_META_SUPERCLASS_MARK`).
+        def unknown_superclass?(scope, name)
+          superclasses = scope.discovered_superclasses
+          return true if superclasses.key?(name) && superclasses[name].nil?
+
+          scope.discovered_parameter_envelopes[name]&.key?(Scope::DiscoveryIndex::ENVELOPE_META_SUPERCLASS_MARK) ||
+            false
+        end
+
+        # A module some code `prepend`s to an object's singleton class (or `extend`s an object with in a method
+        # body), which puts it ahead of the object's class even where the class already includes it.
+        def object_prepended?(scope, name)
+          scope.discovered_parameter_envelopes[name]&.key?(Scope::DiscoveryIndex::ENVELOPE_OBJECT_EXTENDED_MARK) ||
+            false
+        end
+
+        # Is some in-effect row under a class no table declares by any spelling of it (the keys sharing its last
+        # segment that the same refining module refines)? Ruby resolved that `refine` argument to some class, through
+        # a lookup the table did not follow (the refining module's own ancestors: `module R; include Foo;
+        # refine(Bar)` refines `Foo::Bar`) or to a class outside the analysed paths (a vendored `VendorStr <
+        # String`), and Rigor cannot place it in the receiver's hierarchy.
+        def unplaced_target?(scope, raw)
+          raw.any? do |refined, modules|
+            segment = refined.split("::").last
+            modules.any? do |module_name|
+              raw.none? do |other, others|
+                others.include?(module_name) && other.split("::").last == segment && declared_class?(scope, other)
+              end
+            end
+          end
+        end
+
+        def declared_class?(scope, name)
+          scope.discovered_classes.key?(name) || !(scope.discovered_class_sources[name] || EMPTY).empty? ||
+            scope.known_user_class?(name) || scope.environment&.class_known?(name) || false
+        end
+
+        def level_names(levels)
+          names = Set.new
+          levels.each do |level_class, entries, _mixed, every|
+            names << level_class if level_class
+            (every || entries).each { |entry| entry.is_a?(Array) ? names.merge(entry) : names << entry }
+          end
+          names
+        end
+
+        def module_name?(scope, name)
+          bucket = scope.discovered_parameter_envelopes[name]
+          return true if bucket&.key?(Scope::DiscoveryIndex::ENVELOPE_MODULE_MARK)
+
+          scope.environment&.rbs_module?(name) || false
+        end
+
+        def rbs_subclass?(scope, refined, class_name)
+          environment = scope.environment
+          !environment.nil? && environment.class_known?(refined) &&
+            environment.class_ordering(refined, class_name) == :subclass
+        end
+
+        # Does a project subclass of `class_name` (the `discovered_superclasses` walk `SourceArity` makes, its
+        # parents resolved to any class the project or RBS knows, so a subclass of a core class counts) carry a
+        # refined entry on its own level, or a level the walk cannot read?
+        #
+        # A subclass level the walk cannot read (a truncated chain, or a mixin the tables cannot name) hides only
+        # modules, so it declines only when some in-effect row names a module.
+        def subclass_refined?(scope, class_name, raw)
+          each_subclass(scope, class_name) do |subclass|
+            chain = Scope::ResolutionChain.for(scope, subclass, :instance, :methods)
+            chain.record(scope) if Analysis::DependencyRecorder.active?
+            if chain.truncated? || chain.wildcard_mixin? || chain.level_count.zero?
+              return true if raw.each_key.any? { |refined| module_name?(scope, refined) }
+
+              next
+            end
+            return true if chain.level_entries(0).any? { |entry| refined_entry?(entry, raw) }
+          end
+          false
+        end
+
+        def refined_entry?(entry, raw)
+          return entry.candidates.any? { |candidate| raw.include?(candidate) } if entry.external?
+
+          raw.include?(entry.name)
+        end
+
+        # ADR-46 — every class whose subclasses are enumerated records `subclass_of:<last segment>`, which a class
+        # declaration with that superclass appearing or vanishing fires (`IncrementalSession#negative_affected`).
+        # A class whose superclass the tables do not know may be a subclass of any class, so it joins the walk too
+        # (`subclass_of:*`, which any class declaration appearing or vanishing fires).
+        def each_subclass(scope, class_name)
+          children = children_by_parent(scope)
+          record_subclasses_read(class_name)
+          queue = children.fetch(class_name.to_s, []) + unknown_superclass_classes(scope, class_name)
+          seen = {}
+          until queue.empty?
+            subclass = queue.shift
+            next if seen[subclass]
+
+            seen[subclass] = true
+            record_subclasses_read(subclass)
+            yield subclass
+            queue.concat(children.fetch(subclass, []))
+          end
+        end
+
+        def unknown_superclass_classes(scope, class_name)
+          Analysis::DependencyRecorder.read_name(:subclass_of, "*") if Analysis::DependencyRecorder.active?
+          mark = Scope::DiscoveryIndex::ENVELOPE_META_SUPERCLASS_MARK
+          computed = scope.discovered_superclasses.filter_map { |child, parent| child if parent.nil? }
+          meta = scope.discovered_parameter_envelopes.filter_map { |name, bucket| name if bucket.key?(mark) }
+          (computed + meta).uniq - [class_name.to_s]
+        end
+
+        def record_subclasses_read(class_name)
+          return unless Analysis::DependencyRecorder.active?
+
+          Analysis::DependencyRecorder.read_last_segment(:subclass_of, class_name.to_s)
+        end
+
+        def children_by_parent(scope)
+          scope.discovered_superclasses.each_with_object({}) do |(child, raw_parent), children|
+            parent = scope.ancestor_name_candidates(child, raw_parent).find { |name| known_class?(scope, name) }
+            (children[parent] ||= []) << child if parent
+          end
+        end
+
+        def known_class?(scope, name)
+          scope.known_user_class?(name) || scope.discovered_parameter_envelopes.key?(name) ||
+            scope.environment&.class_known?(name) || false
+        end
+
+        # Walks the levels from the most derived: true when the first level or entry that a raw target names or
+        # that defines `method_name` defines it, and that definer is proven. A refined level or entry (an entry no
+        # table names by any of its candidate names), a `mixed` level (a project mixin RBS does not place, which
+        # may be prepended or refined), an unproven definer, and the end of the walk all answer false. An entry no
+        # table names is passed over otherwise: it cannot be proven a definer, and a definer the walk misses there
+        # sits ahead of every refinement the walk then reaches.
+        def shadowing_definer?(scope, class_name, levels, method_name, raw)
+          levels.each do |level_class, entries, mixed, every|
+            return false if mixed || (level_class && raw.include?(level_class))
+
+            (every || entries).each do |entry|
+              case entry_answer(scope, entry, level_class, method_name, raw)
+              when :refined then return false
+              when :defines then return proven_definer?(scope, class_name, entry, method_name)
+              end
+            end
+          end
+          false
+        end
+
+        # `:refined`, `:defines`, or nil to move on. The level's own class was asked before its entries.
+        def entry_answer(scope, entry, level_class, method_name, raw)
+          return entry.any? { |candidate| raw.include?(candidate) } ? :refined : nil if entry.is_a?(Array)
+          return :refined if entry != level_class && raw.include?(entry)
+
+          :defines if RefinedDispatch.defines?(scope, entry, method_name)
+        end
+
+        # Is Ruby known to find `method_name` on `entry`, the first definer the walk reached for an instance of
+        # `class_name`? Neither proof stands on a class that rewrites its method table in a way no literal names
+        # (`ENVELOPE_DYNAMIC_MARK`), nor for a name the project removes from it with a literal `undef`,
+        # `remove_method` or `undef_method` anywhere (`ENVELOPE_REMOVED_KIND`), whatever defined it.
+        #
+        # - A project `def`, `attr_*` or `define_method` (ADR-119 A7): `DefinerResolution` must answer `Known` with
+        #   `entry` as the owner, on the receiver's chain, so a definer that may not have run (a `def` under `if`,
+        #   which Ruby skips, leaving the ancestor's refinement to answer) or that an unplaced mixin or fork may
+        #   precede is not proof. A `def` whose envelope something made opaque (`remove_method`, `undef`, an
+        #   alias, a wrapping macro) is not proof either.
+        # - A core method the offline CRuby catalogue lists on `entry` itself ({Builtins::CRubyDefiners}), which the
+        #   project has not removed or rewritten there (A9: no opaque envelope for the name, which `remove_method`
+        #   and `undef` record). Core RBS is not proof: it redeclares some inherited methods on a subclass
+        #   (`Integer#quo`, `File#to_path`, owned by `Numeric` and `IO`) and declares some CRuby no longer defines
+        #   (`Process::Status#&`).
+        #
+        # ADR-46 — the envelope bucket records the files declaring `entry`, and the class edge a new file reopening
+        # it (to `remove_method` the name, say) fires.
+        def proven_definer?(scope, class_name, entry, method_name)
+          Analysis::DependencyRecorder.read_last_segment(:class, entry) if Analysis::DependencyRecorder.active?
+          bucket = scope.parameter_envelopes_of(entry)
+          return false if bucket.key?(Scope::DiscoveryIndex::ENVELOPE_DYNAMIC_MARK)
+          return false if bucket.key?([Scope::DiscoveryIndex::ENVELOPE_REMOVED_KIND, method_name.to_sym])
+
+          opaque = Source::ParameterEnvelope.opaque?(bucket[[:instance, method_name.to_sym]])
+          return true if project_definer?(scope, class_name, entry, method_name, opaque)
+
+          !opaque && Builtins::CRubyDefiners.defines?(entry, method_name)
+        end
+
+        # A `def` counts while its envelope is its own (an alias or a wrapping macro makes it opaque); an `attr_*` or
+        # `define_method` always records an opaque one, so for those the existence table and the certainty read are
+        # the proof, beside the removal check above.
+        def project_definer?(scope, class_name, entry, method_name, opaque)
+          if scope.user_def_for(entry, method_name)
+            return false if opaque
+          elsif !scope.discovered_method?(entry, method_name, :instance)
+            return false
+          end
+
+          certain_owner?(scope, class_name, entry, method_name)
+        end
+
+        # ADR-119 WD2 — the candidate-set read over the receiver's chain, with every project `def`, `attr_*` and
+        # `define_method` as a candidate: true only for a `Known` answer whose owner is `entry`.
+        def certain_owner?(scope, class_name, entry, method_name)
+          case DefinerResolution.resolve(scope, class_name, method_name, :instance, question: :definer,
+                                         &definer_answer(scope, method_name))
+          in DefinerResolution::Known(answer: _answer, owner:) then owner == entry
+          in DefinerResolution::UNKNOWN then false
+          in DefinerResolution::ABSENT then false # rubocop:disable Lint/DuplicateBranch
+          end
+        end
+
+        # The first project entry at or after `from` that defines `method_name` on its instance side, by a `def` or
+        # by another definer the existence table records (`attr_*`, `define_method`).
+        def definer_answer(scope, method_name)
+          lambda do |chain, from|
+            index = from - 1
+            chain.search(scope, from) do |entry|
+              index += 1
+              next if entry.external? || entry.side != :instance
+              next unless scope.user_def_for(entry.name, method_name) ||
+                          scope.discovered_method?(entry.name, method_name, :instance)
+
+              DefinerHit.new(entry.name, entry.name, index, entry.side)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rigor/inference/refined_dispatch.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Inference
+    # ADR-121 WD2 (issue #1664) — which in-effect refinement, if any, answers a call on an instance of a class. The
+    # typed refined arm (`ExpressionTyper#try_refined_dispatch`) asks it before every other answer, because those
+    # answer from the method a refinement replaces.
+    #
+    # Precedence follows `doc/syntax/refinements.rdoc` § Method Lookup: walk the receiver's classes from the most
+    # derived. At each class, the latest in-effect module refining the name for that class wins; otherwise its
+    # prepended modules, its own method and its included modules answer in that order, and the refinement
+    # declines; otherwise move on. A refinement of a module is decided where that module sits in the walk.
+    #
+    # The walk reads RBS ancestors for a class RBS knows (each ancestor a level of its own, so a core class's
+    # prepends are not told apart), and the project's `Scope::ResolutionChain` levels for one only the project
+    # declares, splicing in the RBS ancestors of the superclass it does not declare. "Defines the method" is an RBS
+    # declaration on that class itself, or a project `def`, `attr_*` or `define_method` of it. Core RBS sometimes
+    # redeclares an inherited method on a subclass, which stops the walk there: a known imprecision, in the
+    # declining direction.
+    #
+    # Issue #1740 — {OwnMethod} shares {.levels} with the walk below and asks the opposite question for the two
+    # argument checks: does the receiver's own method answer ahead of every refinement in effect?
+    module RefinedDispatch
+      # The refinement that answers: `module_name` refines `refined_class` (a class or module on the walk).
+      Winner = Data.define(:module_name, :refined_class)
+
+      # The answer when the in-effect list carries {InEffectRefinements::UNKNOWN} and some refinement defines the
+      # name on a class the walk reaches: any of them may answer.
+      UNKNOWN = :unknown
+
+      NO_TARGETS = {}.freeze
+      private_constant :NO_TARGETS
+
+      module_function
+
+      # `Scope::DiscoveryIndex::REFINEMENT_WILDCARD`, read when asked: this file loads before `Scope`.
+      def wildcard = Scope::DiscoveryIndex::REFINEMENT_WILDCARD
+
+      # A {Winner}, {UNKNOWN}, or nil when no in-effect refinement answers `method_name` on an instance of
+      # `class_name` (the class's own lookup does). `list` is the call site's in-effect refinements.
+      #
+      # ADR-121 WD7 — a row the walk could not read never yields a {Winner}: an in-effect module's row for the name
+      # whose class the walk could not name reaches every receiver, and a names-wildcard row of a level the walk
+      # reaches before a definer may define the name, so both answer {UNKNOWN}. So does a winner whose module shares
+      # its last segment with another listed module (A1): which of a `using`'s declared candidates Ruby finds can
+      # depend on load order.
+      def winner(scope, class_name, method_name, list)
+        refinements = scope.discovered_refinements
+        return UNKNOWN if class_unknown_row?(scope, refinements, method_name, list)
+
+        targets = resolved(scope, targets(refinements, method_name, list), method_name)
+        unread = targets(refinements, wildcard, list)
+        unknown = list.include?(InEffectRefinements::UNKNOWN)
+        return nil if targets.nil? && unread.nil? && !unknown
+
+        levels = levels(scope, class_name)
+        return nil if levels.nil?
+        return UNKNOWN if unknown && unknown_reaches?(scope, refinements, method_name, levels)
+
+        walk_targets(scope, levels, method_name, [targets, unread], list)
+      end
+
+      def walk_targets(scope, levels, method_name, (targets, unread), list)
+        return nil if targets.nil? && unread.nil?
+
+        answer = walk(scope, levels, method_name, targets || NO_TARGETS, unread || NO_TARGETS)
+        answer.is_a?(Winner) && rival_spelling?(answer.module_name, list) ? UNKNOWN : answer
+      end
+
+      # ADR-121 WD7 (A2) — does an in-effect module have a row for `method_name` (or a names-wildcard row) whose
+      # class the walk could not name ({InEffectRefinements.class_wildcard_key?})? It may refine the receiver's class.
+      def class_unknown_row?(scope, refinements, method_name, list)
+        refinements.any? do |refined, methods|
+          rows = [methods[method_name], methods[wildcard]].compact
+          !rows.empty? && rows.any? { |modules| in_effect?(modules, list) } &&
+            InEffectRefinements.class_wildcard_key?(scope, refined)
+        end
+      end
+
+      # Is one of `modules` (a row's refining modules) in `list`? The wildcard module, which the walk could not name,
+      # is any listed module.
+      def in_effect?(modules, list)
+        return list.any? { |name| name != InEffectRefinements::UNKNOWN } if modules.include?(wildcard)
+
+        modules.any? { |name| list.include?(name) }
+      end
+
+      def rival_spelling?(module_name, list)
+        segment = module_name.split("::").last
+        list.any? { |other| other.is_a?(String) && other != module_name && other.split("::").last == segment }
+      end
+
+      # `{refined class => the latest in-effect module refining method_name for it}`, or nil when none is in effect.
+      def targets(refinements, method_name, list)
+        out = nil
+        refinements.each do |refined, methods|
+          modules = methods[method_name]
+          next if modules.nil?
+
+          best = latest(modules, list)
+          (out ||= {})[refined] = best if best
+        end
+        out
+      end
+
+      # The refinement table records every name a `refine` argument's spelling can denote (`refine String` inside
+      # `module M` records `M::String` and `String`), which only withholds a check. To type, a key must be the class
+      # Ruby's lexical lookup resolves: one the project or RBS knows, with no longer spelling of the same last segment
+      # that the same module refines the name for and that is known too (that one is innermost, so it wins). Nil
+      # when no key survives.
+      def resolved(scope, targets, method_name)
+        return nil if targets.nil?
+
+        refinements = scope.discovered_refinements
+        kept = targets.select do |refined, module_name|
+          known_class?(scope, refined) && !shadowed?(scope, refinements, refined, module_name, method_name)
+        end
+        kept.empty? ? nil : kept
+      end
+
+      def shadowed?(scope, refinements, refined, module_name, method_name)
+        suffix = "::#{refined.split('::').last}"
+        depth = refined.count(":")
+        refinements.any? do |other, methods|
+          other.count(":") > depth && other.end_with?(suffix) && methods[method_name]&.include?(module_name) &&
+            known_class?(scope, other)
+        end
+      end
+
+      def known_class?(scope, name)
+        scope.discovered_classes.key?(name) || scope.environment&.class_known?(name) || false
+      end
+
+      def latest(modules, list)
+        best = nil
+        best_index = -1
+        modules.each do |module_name|
+          index = list.index(module_name)
+          next unless index && index > best_index
+
+          best = module_name
+          best_index = index
+        end
+        best
+      end
+
+      # ADR-121 WD7 — a names-wildcard row counts as a row for every name, and a row whose class the walk could not
+      # name reaches every level.
+      def unknown_reaches?(scope, refinements, method_name, levels)
+        unread_class = refinements.any? do |refined, methods|
+          (methods.key?(method_name) || methods.key?(wildcard)) &&
+            InEffectRefinements.class_wildcard_key?(scope, refined)
+        end
+        return true if unread_class
+
+        levels.any? do |_level_class, entries|
+          entries.any? do |entry|
+            methods = refinements[entry]
+            !methods.nil? && (methods.key?(method_name) || methods.key?(wildcard))
+          end
+        end
+      end
+
+      # A level the project mixes a module into whose position RBS does not record (`mixed`) is decided by its own
+      # refinement first, as any level is; past that, the mixin may define the name, so a refinement further up the
+      # walk may or may not win and the answer is {UNKNOWN}, never the replaced method's. ADR-121 WD7: a level an
+      # in-effect module has a names-wildcard row for (`unread`) may define the name too, so it answers {UNKNOWN}.
+      def walk(scope, levels, method_name, targets, unread)
+        levels.each_with_index do |(level_class, entries, mixed), index|
+          return UNKNOWN if level_class && unread.key?(level_class)
+
+          refining = level_class && targets[level_class]
+          return Winner.new(module_name: refining, refined_class: level_class) if refining
+          return targeted_after?(levels, index, targets, unread) ? UNKNOWN : nil if mixed
+
+          answer = walk_entries(scope, entries, level_class, method_name, targets, unread)
+          return answer unless answer == :continue
+        end
+        nil
+      end
+
+      # A level's prepended modules, its own method and its included modules, in that order: `:continue` when none
+      # answers, so the walk moves on.
+      def walk_entries(scope, entries, level_class, method_name, targets, unread)
+        entries.each do |entry|
+          unless entry == level_class
+            return UNKNOWN if unread.key?(entry)
+
+            refining = targets[entry]
+            return Winner.new(module_name: refining, refined_class: entry) if refining
+          end
+          return nil if defines?(scope, entry, method_name)
+        end
+        :continue
+      end
+
+      def targeted_after?(levels, index, targets, unread)
+        levels.drop(index).any? do |_level_class, entries|
+          entries.any? { |entry| targets.key?(entry) || unread.key?(entry) }
+        end
+      end
+
+      # `[[level class, [entries in lookup order], mixed, every entry], …]` for an instance of `class_name`, or nil
+      # when the walk cannot be trusted: a chain cut at its limit, or one that records a mixin the tables cannot
+      # name. `every entry` (project levels only) is the level's entries in lookup order with each one that
+      # neither the project's resolver nor RBS can name kept as its candidate names (an Array) where `entries`
+      # leaves it out: the typer never reads it, and {OwnMethod} declines where a refinement may name one.
+      def levels(scope, class_name)
+        environment = scope.environment
+        return rbs_levels(scope, class_name) if environment&.class_known?(class_name)
+
+        project_levels(scope, class_name)
+      end
+
+      # The RBS ancestors, each a level of its own, `mixed` where the project reopens one to mix a module in (`class
+      # String; include Loud; end`), whose position among them RBS does not record. Each ancestor's name is a
+      # dependency, so a file that adds such a reopening re-checks the consumer.
+      def rbs_levels(scope, class_name)
+        loader = scope.environment.rbs_loader
+        names = loader ? loader.ancestor_names_for(class_name) : []
+        names = [class_name] if names.empty?
+        names.map { |name| [name, [name], project_mixin?(scope, name)] }
+      end
+
+      def project_mixin?(scope, name)
+        Analysis::DependencyRecorder.read_last_segment(:class, name) if Analysis::DependencyRecorder.active?
+        !scope.includes_of(name).empty? || scope.discovery.discovered_prepends.key?(name) ||
+          (scope.discovered_classes.key?(name) &&
+            Scope::ResolutionChain.for(scope, name, :instance, :methods).wildcard_mixin?)
+      end
+
+      def project_levels(scope, class_name)
+        chain = Scope::ResolutionChain.for(scope, class_name, :instance, :methods)
+        chain.record(scope) if Analysis::DependencyRecorder.active?
+        return nil if chain.truncated? || chain.wildcard_mixin?
+
+        out = []
+        chain.level_count.times do |index|
+          level_class = chain.level_classes[index]
+          every = chain.level_entries(index).map { |entry| entry_name(scope, entry) || unnamed(entry) }
+          names = every.grep(String)
+          next out << [level_class, names, false, every] if level_class
+
+          names.each { |name| out.concat(rbs_levels(scope, name)) }
+        end
+        out
+      end
+
+      def unnamed(entry) = entry.candidates.empty? ? [entry.raw.to_s] : entry.candidates
+
+      def entry_name(scope, entry)
+        return entry.name unless entry.external?
+
+        environment = scope.environment
+        entry.candidates.find { |candidate| environment&.class_known?(candidate) }
+      end
+
+      # Does `name` define `method_name` on its instance side itself: a project `def` (its dependency edge recorded
+      # through `Scope#user_def_for`), another project definer (`attr_*`, `define_method`), or an RBS declaration
+      # written on `name` rather than on an ancestor?
+      def defines?(scope, name, method_name)
+        return true if scope.user_def_for(name, method_name)
+        return true if scope.discovered_method?(name, method_name, :instance)
+
+        definition = ExternalAncestorResolution.method_definition(name, method_name, :instance, scope: scope)
+        ExternalAncestorResolution.declared_on_class?(definition, name)
+      end
+    end
+  end
+end
+
+require_relative "refined_dispatch/own_method"