rigortype 0.4.1 → 0.4.2

data/lib/rigor/inference/narrowing.rb

@@ -10,6 +10,7 @@ require_relative "../rbs_extended"
 require_relative "../analysis/fact_store"
 require_relative "../builtins/regex_refinement"
 require_relative "guard_rebinding"
+require_relative "key_presence_guard"
 require_relative "last_line"
 require_relative "operand_effects"
 require_relative "optimistic_origin"
@@ -1273,7 +1274,7 @@ module Rigor
         end
 
         def simple_dispatch_name?(name)
-          %i[nil? ! is_a? kind_of? instance_of? == != === =~ !~ match? key? has_key? empty? any?
+          %i[nil? ! is_a? kind_of? instance_of? == != === =~ !~ match? key? has_key? include? member? empty? any?
              none? respond_to? nan? finite?].include?(name)
         end
 
@@ -1286,7 +1287,7 @@ module Rigor
           when :=== then analyse_case_equality_predicate(node, scope)
           when :=~, :!~ then dispatch_regex_match_predicate(node, scope, name)
           when :match? then analyse_whole_regex_match_predicate(node, scope)
-          when :key?, :has_key? then analyse_key_presence_predicate(node, scope)
+          when :key?, :has_key?, :include?, :member? then analyse_key_presence_predicate(node, scope)
           when :empty?, :any?, :none? then analyse_array_emptiness_predicate(node, scope, name)
           when :respond_to? then analyse_respond_to_predicate(node, scope)
           when :nan?, :finite? then analyse_float_class_predicate(node, scope, name)
@@ -1462,14 +1463,16 @@ module Rigor
         # `h[:foo]` nil-typed). The falsey edge is left unchanged — "key absent" is the
         # conservative no-op. Only literal `Symbol`/`String` arguments and
         # `LocalVariableReadNode`/`InstanceVariableReadNode` receivers narrow; everything else
-        # (Dynamic, `Nominal[Hash]`, method-chain receivers, dynamic keys) bails to no
-        # narrowing.
+        # (Dynamic, `Nominal[Hash]`, method-chain receivers) bails to no narrowing. A non-literal
+        # key goes to {#analyse_computed_key_presence_predicate} (issue #1703).
         def analyse_key_presence_predicate(node, scope)
           return nil if node.arguments.nil?
           return nil unless node.arguments.arguments.size == 1
 
-          key = static_hash_key(node.arguments.arguments.first)
-          return nil if key.nil?
+          # A literal key promotes a shape's optional key only for `key?` / `has_key?`; `include?` / `member?` reach
+          # the computed-key guard alone, so a String or Array receiver's `include?` keeps its own narrowings.
+          key = static_hash_key(node.arguments.arguments.first) if %i[key? has_key?].include?(node.name)
+          return analyse_computed_key_presence_predicate(node, scope) if key.nil?
 
           case node.receiver
           when Prism::LocalVariableReadNode
@@ -1479,6 +1482,17 @@ module Rigor
           end
         end
 
+        # Issue #1703 — `H.key?(k)` / `has_key?` / `include?` / `member?` with a non-literal key (a local, an ivar,
+        # or a reader chain such as `prop.column_type`) on a closed hash shape held in a local, an ivar or a
+        # constant. The truthy edge records the guard, and a later `H[k]` of the same receiver and structurally the
+        # same key drops the miss `nil` ({KeyPresenceGuard}). The falsey edge is the no-op: an
+        # absent computed key says nothing a shape can record. Nil when the guard does not apply, so a collection's
+        # `include?` still reaches the membership and String predicates.
+        def analyse_computed_key_presence_predicate(node, scope)
+          truthy = KeyPresenceGuard.record(node, scope)
+          truthy && [truthy, scope]
+        end
+
         def key_presence_scopes(name, key, scope, reader:, writer:)
           current = scope.public_send(reader, name)
           return nil if current.nil?

data/lib/rigor/inference/object_mixins.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require_relative "../reflection"
+require_relative "../analysis/dependency_recorder"
+
+module Rigor
+  module Inference
+    # Issue #1697 — the modules the project mixes into `Object`, and what they say about a method name.
+    #
+    # A top-level `include M` is `main.include`, which is `Object.include`, so M's instance methods exist on
+    # every object: bare top-level calls (`main` is an `Object`) and calls on any receiver whose class
+    # descends from `Object`. `ScopeIndexer` records that statement under its own owner key
+    # ({TOPLEVEL_INCLUDE_KEY}), and an `include M` inside `class Object ... end` on `Object`. The RBS
+    # environment knows nothing of either: `Object`'s RBS ancestry is core's, so a direct lookup on an
+    # RBS-known receiver misses every one of M's methods. This module is the one place that asks the
+    # project's `Object` edges instead, for the
+    # `call.unresolved-toplevel` and `call.undefined-method` silences in `Analysis::CheckRules`. Nothing
+    # types a call through these edges yet: what Ruby reaches first, even for a bare top-level call, depends
+    # on more than the chain shows (a block that rebinds `self`, an `extend` or a singleton `def` on `main`),
+    # so typing is issue #1715's.
+    #
+    # The edges are read through `Scope::ResolutionChain`, the two owners' instance chains, whose search
+    # files the ADR-46 class edge of every project entry it passes, the declaring files among them (a file
+    # that wrote a top-level `include` is one), so a consumer re-checks when the include that answered for
+    # it is edited away. A project that never reopens `Object` and writes no top-level `include` returns
+    # before reading anything. The question is a union over the chain, not "which definer does Ruby call":
+    # any entry that may define the name answers, so the chain's `settle` verdict is not asked.
+    module ObjectMixins
+      OWNER = "Object"
+      # The owner key `ScopeIndexer` files a top-level `include` under, beside `Object`'s own key, so that
+      # no ancestry walk that types a call reaches it (see `ScopeIndexer#toplevel_include_owner`).
+      TOPLEVEL_INCLUDE_KEY = "<toplevel-include>"
+
+      module_function
+
+      # How the project's `Object` mixins answer `method_name`, nearest edge first:
+      #
+      # - `[:rbs, module_name, definition]` — an RBS-declared module declares it; `definition` is its
+      #   `RBS::Definition::Method`. `:private_rbs` is the same for a private declaration, which a bare call
+      #   reaches and a call with a receiver does not.
+      # - `[:source, module_name]` — a project module (or `Object` itself) defines it.
+      # - `[:singleton_function, module_name]` — an RBS-declared module declares it only as a singleton method.
+      #   Core declares `Math`'s functions that way (`def self.sqrt`) although they are `module_function`s,
+      #   whose private instance copies a bare call reaches after `include Math`. RBS cannot tell such a
+      #   function from a plain `def self.`, so the answer silences a bare call only.
+      # - `[:opaque, module_name]` — a module neither RBS nor the project declares. Its surface cannot be
+      #   enumerated, so it may define the name.
+      # - `[:truncated, "Object"]` — the chain was cut at its budget with no answer before the cut: a definer
+      #   may sit past it, which is uncertainty, not absence.
+      # - `nil` — no edge, or every edge names a module known not to declare it.
+      #
+      # `skip:` names the kinds a caller cannot use; an entry of one of them is passed over and the search
+      # goes on to the next, so the answer is a union over the chain for those callers rather than the
+      # nearest entry only.
+      def answer(scope, method_name, skip: NO_SKIP)
+        return nil if scope.nil?
+
+        # ADR-46 — the answer depends on whether a top-level `include` exists anywhere, so a consumer checked
+        # while none did must re-check when one appears. The key appears as a declared "class" of the file that
+        # writes it (`discovered_class_sources`), which is what this name-keyed existence edge listens for.
+        if Analysis::DependencyRecorder.active?
+          Analysis::DependencyRecorder.read_last_segment(:class, TOPLEVEL_INCLUDE_KEY)
+        end
+        EDGE_OWNERS.each do |owner|
+          next unless scope.known_user_class?(owner)
+
+          found = answer_on_chain(scope, owner, method_name, skip)
+          return found if found
+        end
+        nil
+      end
+
+      # Where `Object`'s project edges are recorded: a top-level `include` under the indexer's own key, and
+      # `Object` itself for `include M` in `class Object` (and `Object`'s own definitions).
+      EDGE_OWNERS = [TOPLEVEL_INCLUDE_KEY, OWNER].freeze
+      private_constant :EDGE_OWNERS
+
+      def answer_on_chain(scope, owner, method_name, skip)
+        chain = Scope::ResolutionChain.for(scope, owner, :instance, :methods)
+        found = chain.search(scope, side: :instance) do |entry|
+          entry_answer = answer_for_entry(scope, entry, method_name)
+          entry_answer unless entry_answer.nil? || skip.include?(entry_answer.first)
+        end
+        return found if found
+
+        chain.truncated? ? [:truncated, owner] : nil
+      end
+      private_class_method :answer_on_chain
+
+      NO_SKIP = [].freeze
+      # An explicit receiver reaches neither a private method (a `module_function`'s instance copy among
+      # them) nor, on #746's
+      # reading of an ancestor's unknown include (the receiver's own includes only), a module whose surface
+      # is unknown: one top-level `include` of an undeclared module would otherwise silence
+      # `call.undefined-method` on every receiver in the project.
+      EXPLICIT_RECEIVER_SKIP = %i[private_rbs singleton_function opaque].freeze
+      private_constant :NO_SKIP, :EXPLICIT_RECEIVER_SKIP
+
+      # Whether some `Object` mixin may define `method_name`: the question the silences ask. A bare
+      # top-level call (`receiver: :implicit`, `call.unresolved-toplevel`) counts every answer, an unknown
+      # module's included: such an include is the likeliest source of a bare name, and silencing a typo
+      # there is the cheaper error. A call with a receiver (`receiver: :explicit`, `call.undefined-method`)
+      # counts only a declared, public definition.
+      def may_define?(scope, method_name, receiver:)
+        skip = receiver == :explicit ? EXPLICIT_RECEIVER_SKIP : NO_SKIP
+        !answer(scope, method_name, skip: skip).nil?
+      end
+
+      # Whether a receiver of `class_name` reaches `Object`'s mixins at all: `Object` itself, or an RBS
+      # class the environment orders below it. A `BasicObject` subclass does not; a class the environment
+      # cannot order is not claimed.
+      def reaches_object?(scope, class_name)
+        name = class_name.to_s.delete_prefix("::")
+        return true if name == OWNER
+
+        environment = scope&.environment
+        !environment.nil? && environment.class_ordering(name, OWNER) == :subclass
+      end
+
+      # A project entry (`Object` itself, or a project module mixed into it) answers when it defines the name;
+      # an external one when RBS declares the name on one of the names its spelling can denote (as an instance
+      # method, or as a module's singleton function), and is opaque when none of those names is declared at
+      # all.
+      def answer_for_entry(scope, entry, method_name)
+        unless entry.external?
+          return source_defines?(scope, entry.name, method_name) ? [:source, entry.name] : nil
+        end
+
+        entry.candidates.each do |candidate|
+          definition = Rigor::Reflection.instance_method_definition(candidate, method_name, scope: scope)
+          return [private_definition?(definition) ? :private_rbs : :rbs, candidate, definition] if definition
+          return [:singleton_function, candidate] if singleton_function?(scope, candidate, method_name)
+        end
+        return nil if entry.candidates.any? { |candidate| declared?(scope, candidate) }
+
+        [:opaque, entry.raw.to_s]
+      end
+      private_class_method :answer_for_entry
+
+      def private_definition?(definition)
+        definition.respond_to?(:accessibility) && definition.accessibility == :private
+      end
+      private_class_method :private_definition?
+
+      def singleton_function?(scope, name, method_name)
+        environment = scope.environment
+        return false if environment.nil? || !environment.rbs_module?(name)
+
+        definition = Rigor::Reflection.singleton_method_definition(name, method_name, scope: scope)
+        # Declared on the module itself: its singleton class also answers every `Module` method
+        # (`include`, `name`), which no `include` of it brings to the top level.
+        !definition.nil? && definition.defined_in.to_s.delete_prefix("::") == name
+      end
+      private_class_method :singleton_function?
+
+      # Asked of both tables a project method lands in, as `RbsDispatch#source_declares_through_ancestors?`
+      # does: `discovered_methods` withholds a plain `def` written in another file, which is exactly where a
+      # top-level `include` usually finds its module. The chain already expands each module's own ancestry, so
+      # one entry's own tables are asked.
+      def source_defines?(scope, name, method_name)
+        scope.discovered_method?(name, method_name, :instance) || !scope.user_def_for(name, method_name).nil?
+      end
+      private_class_method :source_defines?
+
+      # The same "is this mixin's surface enumerable" reading `Analysis::CheckRules#known_mixin?` gives a
+      # class's own includes (#746): a project class or module, or an RBS declaration Rigor did not
+      # synthesize to keep a broken signature buildable.
+      def declared?(scope, name)
+        return true if scope.discovered_classes.key?(name)
+        return false unless Rigor::Reflection.rbs_class_known?(name, scope: scope)
+
+        loader = scope.environment&.rbs_loader
+        return true if loader.nil? || !loader.respond_to?(:synthesized_type_names)
+
+        !loader.synthesized_type_names.include?(name)
+      end
+      private_class_method :declared?
+    end
+  end
+end

data/lib/rigor/inference/project_patched_methods.rb

@@ -7,9 +7,9 @@ module Rigor
     # ADR-17 § "Inference contract" — project-wide patched-method registry populated by the pre-eval
     # pre-pass (slice 2) from the user's `.rigor.yml` `pre_eval:` list.
     #
-    # Each entry records one `def` declaration the pre-pass observed inside a class / module body. The
-    # dispatcher's `try_project_patched_method` tier consults this registry between the plugin tier and
-    # the dependency-source tier so project-side `lib/core_ext/string_extensions.rb` patches are visible
+    # Each entry records one `def`, `alias` or `alias_method` declaration the pre-pass observed inside a class /
+    # module body. The dispatcher's `try_project_patched_method` tier consults this registry between the plugin
+    # tier and the dependency-source tier so project-side `lib/core_ext/string_extensions.rb` patches are visible
     # to cross-file dispatch.
     #
     # The dispatcher answers `Dynamic[T]` (with a heuristic static facet) when `Entry#return_type` is
@@ -22,8 +22,13 @@ module Rigor
       # the {Analysis::DependencySourceInference::ReturnTypeHeuristic}-extracted static facet (a
       # `Rigor::Type::*`) or `nil` when the heuristic declined. The dispatcher wraps a non-nil
       # `return_type` in `Dynamic[T]`; a `nil` `return_type` falls back to `Dynamic[top]`.
-      Entry = Data.define(:class_name, :method_name, :kind, :source_path, :source_line, :return_type) do
-        def initialize(class_name:, method_name:, kind:, source_path:, source_line:, return_type: nil)
+      #
+      # Issue #1702 — an `alias new old` / `alias_method :new, :old` in a patch is recorded too. When a `def` or
+      # alias earlier in the `pre_eval:` files binds `old`, the alias's entry copies that entry's `return_type` (and
+      # its `alias_of`); otherwise `alias_of` names `old`, a method the class had before the patch, and the
+      # dispatcher answers the alias with what that method answers. `alias_of` is nil for a `def`.
+      Entry = Data.define(:class_name, :method_name, :kind, :source_path, :source_line, :return_type, :alias_of) do
+        def initialize(class_name:, method_name:, kind:, source_path:, source_line:, return_type: nil, alias_of: nil)
           super
         end
       end

data/lib/rigor/inference/project_patched_scanner.rb

@@ -4,6 +4,7 @@ require "prism"
 
 require_relative "project_patched_methods"
 require_relative "../analysis/dependency_source_inference/return_type_heuristic"
+require_relative "../source/alias_names"
 require_relative "../source/constant_path"
 require_relative "../source/node_children"
 
@@ -11,7 +12,8 @@ module Rigor
   module Inference
     # ADR-17 slice 2 — pre-pass scanner. Walks every file the user listed under `pre_eval:` and
     # harvests every `def` / `def self.` declaration inside a class / module body into a
-    # {ProjectPatchedMethods} registry the dispatcher consults below the plugin tier.
+    # {ProjectPatchedMethods} registry the dispatcher consults below the plugin tier, together with every
+    # `alias new old` / `alias_method :new, :old` there (issue #1702, read through {Source::AliasNames}).
     #
     # The walker is intentionally a strict subset of {Rigor::Inference::ScopeIndexer}'s machinery: it
     # only needs `class C; def m; end; end` shape recognition, not full inference. Parse errors degrade
@@ -29,6 +31,10 @@ module Rigor
         end
       end
 
+      # An alias the walk met, before {resolve_aliases} knows whether its old name is one the patch files define.
+      PendingAlias = Data.define(:class_name, :new_name, :old_name, :kind, :source_path, :source_line)
+      private_constant :PendingAlias
+
       module_function
 
       # @param paths — absolute paths to the pre-eval files. The runner has already
@@ -39,10 +45,11 @@ module Rigor
       #   users editing a monkey-patch file see the in-flight version in their analysis.
       # @return the populated registry plus any per-file warnings.
       def scan(paths, buffer: nil)
-        entries = []
+        collected = []
         diagnostics = []
         census = Set.new
-        paths.each { |path| scan_file(path, entries, diagnostics, buffer, census) }
+        paths.each { |path| scan_file(path, collected, diagnostics, buffer, census) }
+        entries = resolve_aliases(collected)
         diagnostics.concat(duplicate_declaration_diagnostics(entries))
         Result.new(
           registry: ProjectPatchedMethods.new(entries: entries, write_census: census.freeze),
@@ -78,6 +85,46 @@ module Rigor
       end
       private_class_method :duplicate_declaration_diagnostics
 
+      # Turns each {PendingAlias} into the entry it publishes, walking the bindings in configuration-then-source
+      # order as Ruby runs them. An alias binds to the body its old name has WHEN IT RUNS, so only a `def` or alias
+      # earlier in that order may supply its return type: `alias to_m to_modint` after `def to_modint` answers what
+      # `to_modint` does, while `alias_method :orig_succ, :succ` ahead of a patch's `def succ` is the method
+      # Integer already had. An alias whose old name nothing earlier binds records that name as `alias_of`, for the
+      # dispatcher to answer with the class's existing method (`alias old_plus +` on Integer), or with
+      # `Dynamic[top]` when nothing knows the name: the alias is still published, since a call to it is not the
+      # undefined method a dropped entry would report.
+      #
+      # Within one file the later binding of a name replaces the earlier, as at runtime: the alias-method-chain
+      # idiom (`def foo`, `alias_method :foo_without_x, :foo`, `alias_method :foo, :foo_with_x`) leaves `foo` the
+      # alias. Bindings of one name in DIFFERENT files are what `pre-eval.duplicate-declaration` reports, and the
+      # registry keeps the first of those, as it always has for `def`s.
+      def resolve_aliases(collected)
+        bound = {}
+        per_file = collected.group_by(&:source_path).values.map do |items|
+          final = {}
+          items.each do |item|
+            entry = item.is_a?(PendingAlias) ? alias_entry(item, bound) : item
+            key = [entry.class_name, entry.method_name, entry.kind]
+            bound[key] = entry
+            final.delete(key)
+            final[key] = entry
+          end
+          final.values
+        end
+        per_file.flatten(1)
+      end
+      private_class_method :resolve_aliases
+
+      def alias_entry(item, bound)
+        target = bound[[item.class_name, item.old_name, item.kind]]
+        ProjectPatchedMethods::Entry.new(
+          class_name: item.class_name, method_name: item.new_name, kind: item.kind,
+          source_path: item.source_path, source_line: item.source_line,
+          return_type: target&.return_type, alias_of: target ? target.alias_of : item.old_name
+        )
+      end
+      private_class_method :alias_entry
+
       def scan_file(path, entries, diagnostics, buffer = nil, census = Set.new)
         physical = buffer ? buffer.resolve(path) : path
         parse_result =
@@ -139,6 +186,13 @@ module Rigor
           descend_singleton_class(node, qualified_prefix, source_path, entries)
         when Prism::DefNode
           record_def_node(node, qualified_prefix, in_singleton_class, source_path, entries)
+        when Prism::AliasMethodNode
+          record_alias(node, Source::AliasNames.keyword_names(node), qualified_prefix, in_singleton_class,
+                       source_path, entries)
+        when Prism::CallNode
+          record_alias(node, Source::AliasNames.alias_method_call_names(node), qualified_prefix,
+                       in_singleton_class, source_path, entries)
+          walk_children(node, qualified_prefix, in_singleton_class, source_path, entries)
         else
           walk_children(node, qualified_prefix, in_singleton_class, source_path, entries)
         end
@@ -186,6 +240,20 @@ module Rigor
         )
       end
       private_class_method :record_def_node
+
+      # `names` is the alias's `[new_name, old_name]`, or nil for a computed name or a call that is not an alias.
+      # The side follows the body it is written in, as a `def`'s does: `alias` and `alias_method` inside
+      # `class << self` both bind on the singleton.
+      def record_alias(node, names, qualified_prefix, in_singleton_class, source_path, entries)
+        return if names.nil? || qualified_prefix.empty?
+
+        entries << PendingAlias.new(
+          class_name: qualified_prefix.join("::"), new_name: names.first, old_name: names.last,
+          kind: in_singleton_class ? :singleton : :instance,
+          source_path: source_path, source_line: node.location&.start_line || 1
+        )
+      end
+      private_class_method :record_alias
     end
   end
 end

data/lib/rigor/inference/refine_census.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../source/alias_names"
+require_relative "../source/node_children"
+
+module Rigor
+  module Inference
+    # ADR-121 WD7 (issues #1796, #1799) — what a `refine` body tells the refinement table, read the one way the project
+    # walk (`ScopeIndexer#record_refinement_defs`) and the gem source walker
+    # (`Analysis::DependencySourceInference::Walker#walk_refine_body`) both use, so the two cannot drift. The table is
+    # `{refined class => {method => [refining modules]}}`; `Scope::DiscoveryIndex::REFINEMENT_WILDCARD` stands for
+    # what could not be read.
+    #
+    # A body is fully read when every call on its own `self` (the refinement module) is one that defines a name the
+    # walk can spell, or one that defines nothing: a `def`, an `alias` or `alias_method` of two literal names, a
+    # `define_method` of a literal name, an `attr_*` of literal names, an `undef`, a visibility call, or
+    # `Refinement#target`. Anything
+    # else (`import_methods`, `send`, a computed `define_method`, `include`, a nested `refine`, any other call on
+    # `self`) may define a name the walk cannot spell, so the body's names are incomplete and the table gets a
+    # names-wildcard row for each target. A call on another receiver cannot define a method on the refinement, and
+    # a call inside a `def` or `define_method` body runs on an instance of the refined class, so neither counts.
+    module RefineCensus
+      # `names`, every name the body is read to define, in textual order; `complete`, whether those are all of them;
+      # `defs`, the typed refined arm's bodies in textual order: `[name, Prism::DefNode]` for a `def` or an alias of
+      # an earlier `def`, and `[name, nil]` for any other definer (`define_method`, `attr_*`, `undef`, an alias of a
+      # name the body did not define earlier). A later definer replaces an earlier one, as Ruby's method table
+      # keeps the last, so a name whose last definer has no `DefNode` types as `Dynamic[top]`.
+      BodyReading = Struct.new(:names, :complete, :defs)
+
+      # Calls on the refinement that define nothing: visibility, with no argument, literal names, a `def`, or an
+      # allowlisted definer call.
+      VISIBILITY_CALLS = Set[:private, :public, :protected, :module_function, :private_constant].freeze
+      # `Refinement#target`, a reader of the refined class (the other `Refinement` method on Ruby 4.0.5 is
+      # `import_methods`).
+      READER_CALLS = Set[:target].freeze
+      # `attr_*` and whether each defines the reader and the writer.
+      ATTR_CALLS = {
+        attr_reader: [true, false].freeze, attr_writer: [false, true].freeze, attr_accessor: [true, true].freeze,
+        attr: [true, false].freeze
+      }.freeze
+
+      # A3 — the calls whose String argument may hold `refine` as code or as a method name, and the two families
+      # whose `self` is their receiver (so `M.send(:refine, …)` runs `refine` on `M`).
+      SEND_CALLS = Set[:send, :__send__, :public_send].freeze
+      SELF_EVAL_CALLS = Set[:instance_eval, :class_eval, :module_eval, :instance_exec, :class_exec, :module_exec].freeze
+      NAMING_CALLS = Set[
+        :method, :public_method, :singleton_method, :instance_method, :public_instance_method, :define_method,
+        :define_singleton_method, :alias_method
+      ].freeze
+      REFINE_WORD = /\brefine\b/
+
+      private_constant :VISIBILITY_CALLS, :READER_CALLS, :ATTR_CALLS, :REFINE_WORD
+
+      module_function
+
+      def wildcard = Scope::DiscoveryIndex::REFINEMENT_WILDCARD
+
+      # §2.2 — what `body` (a refine block's body, or nil) defines on the refined class.
+      def read_body(body)
+        reading = BodyReading.new([], true, [])
+        scan_body(body, reading, {}, true) if body
+        reading.names.uniq!
+        reading
+      end
+
+      # Records `reading`'s names for each of `targets` under `refining` into `table` (nil starts one), plus a
+      # names-wildcard row per target when the body's names are incomplete. Returns the table.
+      def record_rows(table, targets, reading, refining)
+        table ||= {}
+        targets.each do |class_name|
+          reading.names.each { |name| add_row(table, class_name, name, refining) }
+          add_row(table, class_name, wildcard, refining) unless reading.complete
+        end
+        table
+      end
+
+      # One `{class_name => {method_key => [refining]}}` entry, `refining` once.
+      def add_row(table, class_name, method_key, refining)
+        modules = ((table[class_name] ||= {})[method_key] ||= [])
+        modules << refining unless modules.include?(refining)
+        table
+      end
+
+      # A3 — a `:refine` Symbol literal: it may name `Module#refine` for `send`, `alias_method`, `method`, ….
+      def refine_symbol?(node) = node.is_a?(Prism::SymbolNode) && node.unescaped == "refine"
+
+      # A3 — a String literal (or a heredoc's literal part) holding the word `refine`, as code an eval runs or as a
+      # method name.
+      def refine_string?(node)
+        case node
+        # As bytes: a literal whose bytes are not valid in its encoding (`"\xff …"`) must not raise.
+        when Prism::StringNode then REFINE_WORD.match?(node.unescaped.b)
+        when Prism::InterpolatedStringNode then node.parts.any? { |part| refine_string?(part) }
+        else false
+        end
+      end
+
+      # A3 — does a String argument of `call` count: an eval, `send` or method-naming call?
+      def string_literal_call?(call)
+        name = call.name
+        name == :eval || SELF_EVAL_CALLS.include?(name) || SEND_CALLS.include?(name) || NAMING_CALLS.include?(name)
+      end
+
+      # A3 — the `self` a refine literal argument of `call` runs `refine` on: `:receiver` for a `send` or `*_eval`
+      # / `*_exec` call (the receiver, or the caller's `self` when it has none or it is `self`), `:unknown` for an
+      # `eval` on a binding, `:self` for everything else (the caller's `self`).
+      def literal_target(call)
+        receiver = call.receiver
+        self_receiver = receiver.nil? || receiver.is_a?(Prism::SelfNode)
+        if SEND_CALLS.include?(call.name) || SELF_EVAL_CALLS.include?(call.name)
+          self_receiver ? :self : :receiver
+        elsif call.name == :eval
+          self_receiver ? :self : :unknown
+        else
+          :self
+        end
+      end
+
+      # An implicit- or `self`-receiver call: one whose `self` is the walk's `self`.
+      def self_call?(node) = node.receiver.nil? || node.receiver.is_a?(Prism::SelfNode)
+
+      # `classify` is false inside a `define_method` block or its arguments, whose calls run on an instance of the
+      # refined class (or before the method exists), so they define nothing on the refinement. `latest` maps each
+      # name to the last `def` the body wrote for it so far, which an alias copies.
+      def scan_body(node, reading, latest, classify)
+        case node
+        when Prism::DefNode
+          record_def(node, reading, latest) if node.receiver.nil?
+          return
+        when Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode
+          return
+        when Prism::AliasMethodNode
+          return record_alias(Source::AliasNames.keyword_names(node), reading, latest)
+        when Prism::UndefNode
+          return record_undef(node, reading, latest)
+        when Prism::CallNode
+          if classify && self_call?(node)
+            classify_call(node, reading, latest)
+            classify = node.name != :define_method
+          end
+        end
+
+        node.rigor_each_child { |child| scan_body(child, reading, latest, classify) }
+      end
+
+      def record_def(node, reading, latest)
+        reading.names << node.name
+        reading.defs << [node.name, node]
+        latest[node.name] = node
+      end
+
+      # `alias new old` / `alias_method :new, :old`: `new` is defined; it copies `old`'s body when the refine body
+      # wrote `old` earlier (Ruby copies at the alias, so a later `def old` does not move it), and otherwise it
+      # copies the refined class's own method, whose body the walk does not hold.
+      def record_alias(pair, reading, latest)
+        return reading.complete = false if pair.nil?
+
+        new_name, old_name = pair
+        reading.names << new_name
+        def_node = latest[old_name]
+        return record_bodiless(new_name, reading, latest) if def_node.nil?
+
+        reading.defs << [new_name, def_node]
+        latest[new_name] = def_node
+      end
+
+      # A name a definer with no `DefNode` defines: it replaces any earlier `def` of the name, so the typed arm
+      # finds no body for it (`refine(String) { def center(a) = 1; define_method(:center) { |a| "dm" } }` answers
+      # `"dm"` on Ruby 4.0.5), and an alias of it copies no body either.
+      def record_bodiless(name, reading, latest)
+        reading.names << name
+        reading.defs << [name, nil]
+        latest.delete(name)
+      end
+
+      def record_undef(node, reading, latest)
+        node.names.each do |name|
+          symbol = literal_name(name)
+          symbol ? record_bodiless(symbol, reading, latest) : reading.complete = false
+        end
+      end
+
+      # Classifies a call on the refinement.
+      def classify_call(node, reading, latest)
+        name = node.name
+        arguments = node.arguments&.arguments || []
+        if (attr = ATTR_CALLS[name])
+          record_attr(arguments, attr, reading, latest)
+        elsif name == :define_method
+          record_define_method(arguments, reading, latest)
+        elsif name == :alias_method
+          record_alias(Source::AliasNames.alias_method_call_names(node), reading, latest)
+        else
+          reading.complete = false unless defines_nothing?(node, arguments)
+        end
+      end
+
+      # A visibility call with no argument, literal names, a `def` or a call; `Refinement#target` with none.
+      def defines_nothing?(node, arguments)
+        return arguments.all? { |argument| visibility_argument?(argument) } if VISIBILITY_CALLS.include?(node.name)
+
+        READER_CALLS.include?(node.name) && arguments.empty? && node.block.nil?
+      end
+
+      def record_attr(arguments, (reader, writer), reading, latest)
+        arguments.each do |argument|
+          name = literal_name(argument)
+          next reading.complete = false if name.nil?
+
+          record_bodiless(name, reading, latest) if reader
+          record_bodiless(:"#{name}=", reading, latest) if writer
+        end
+      end
+
+      def record_define_method(arguments, reading, latest)
+        name = arguments.first && literal_name(arguments.first)
+        name ? record_bodiless(name, reading, latest) : reading.complete = false
+      end
+
+      # `private`, `private :a, "b"`, `private def x`, `private attr_reader :x`: the nested call is classified on
+      # its own when the walk descends into it.
+      def visibility_argument?(argument)
+        argument.is_a?(Prism::SymbolNode) || argument.is_a?(Prism::StringNode) || argument.is_a?(Prism::DefNode) ||
+          argument.is_a?(Prism::CallNode)
+      end
+
+      # A literal's name, or nil for none and for bytes no Symbol holds: `define_method("\xff")` raises
+      # EncodingError on Ruby 4.0.5, so the body is not read.
+      def literal_name(node)
+        return nil unless node.is_a?(Prism::SymbolNode) || node.is_a?(Prism::StringNode)
+
+        name = node.unescaped
+        name.to_sym if name&.valid_encoding?
+      end
+    end
+  end
+end