rigortype 0.3.9 → 0.4.1

data/lib/rigor/inference/method_dispatcher.rb

@@ -21,12 +21,15 @@ require_relative "method_dispatcher/iterator_dispatch"
 require_relative "method_dispatcher/reduce_folding"
 require_relative "method_dispatcher/block_folding"
 require_relative "method_dispatcher/array_to_h_folding"
+require_relative "method_dispatcher/hash_transform_keys_folding"
 require_relative "method_dispatcher/file_folding"
 require_relative "method_dispatcher/shellwords_folding"
 require_relative "method_dispatcher/math_folding"
 require_relative "method_dispatcher/random_folding"
 require_relative "method_dispatcher/time_folding"
 require_relative "method_dispatcher/regexp_folding"
+require_relative "method_dispatcher/match_data_folding"
+require_relative "method_dispatcher/process_folding"
 require_relative "method_dispatcher/cgi_folding"
 require_relative "method_dispatcher/uri_folding"
 require_relative "method_dispatcher/set_folding"
@@ -57,7 +60,6 @@ module Rigor
 
       # @param receiver_type — type of the receiver expression, or
       #   `nil` for an implicit-self call.
-      # @param arg_types — positional argument types.
       # @param block_type — inferred return type of the
       #   accompanying `do ... end` / `{ ... }` block (Slice 6 phase C
       #   sub-phase 2). When non-nil, the dispatcher prefers an
@@ -94,9 +96,12 @@ module Rigor
         result
       end
 
-      def resolve(receiver_type:, method_name:, arg_types:, # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      # `plugin_typed_sink` is internal bookkeeping for the composite-receiver tier below: when it is an
+      # Array, an answering plugin tier PUSHES the call node instead of recording it on the scope, and
+      # the tier commits the buffer only if it goes on to answer. See {#try_composite_receiver}.
+      def resolve(receiver_type:, method_name:, arg_types:, # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/ParameterLists
                   block_type: nil, environment: nil,
-                  call_node: nil, scope: nil)
+                  call_node: nil, scope: nil, plugin_typed_sink: nil)
         return nil if receiver_type.nil?
 
         # Build the call context once and thread it — unchanged — through every tier
@@ -126,7 +131,22 @@ module Rigor
           # RBS's, and `call.undefined-method` reads that record instead of re-deciding from the receiver's
           # (possibly partial) signature. Recorded for EVERY plugin answer, dynamic or precise: the
           # incoherence the record closes is about which subsystem typed the call, not about the type.
-          scope&.record_plugin_typed_call(call_node)
+          #
+          # Under a composite-receiver projection the record is BUFFERED instead (#1101). It is the one
+          # recording in this method that is set-only — `Scope#plugin_typed_calls` has no removal, and
+          # `CheckRules#call_site_exempt?` / `#source_arity_envelope` read it as an exemption — so a
+          # member a plugin answers beside a member that declines would exempt a call this dispatcher
+          # never typed, silencing `call.undefined-method` and `call.wrong-arity` on a firing that stands.
+          # `call_site_exempt?` runs ahead of the receiver-shape branch, so the union rule is covered by
+          # it too and the suppression is reachable end to end — the arms are measured in
+          # `spec/integration/composite_receiver_plugin_typed_suppression_spec.rb`. The
+          # `record_dynamic_origin` writes below and in the tiers that follow need no such care: that
+          # table is last-wins and the caller's fail-soft widening overwrites it.
+          if plugin_typed_sink
+            plugin_typed_sink << call_node
+          else
+            scope&.record_plugin_typed_call(call_node)
+          end
           if plugin_result.is_a?(Type::Dynamic)
             scope&.record_dynamic_origin(call_node, DynamicOrigin::FRAMEWORK_DSL_BOUNDARY)
           end
@@ -255,7 +275,13 @@ module Rigor
         if fallback_result.is_a?(Type::Dynamic)
           scope&.record_dynamic_origin(call_node, DynamicOrigin::INFERRED_RETURN_UNTYPED)
         end
-        fallback_result
+        return fallback_result if fallback_result
+
+        # Issue #1101 — composite-receiver projection, the last tier. Every tier above needs a
+        # receiver it can name; a `Union` or a `Difference` is not one, so a composite receiver whose
+        # members WOULD each resolve still lands `Dynamic[top]`. Retry per projected member through
+        # this same chain. See {#try_composite_receiver} for the projection rule and why it sits here.
+        try_composite_receiver(context)
       end
 
       # ADR-100 WD4 — records the transitive `-> void` provenance when the called method is a
@@ -451,6 +477,52 @@ module Rigor
         FlowContribution::Merger.merge(contributions).return_type
       end
 
+      # Issue #963 item 2 — the MEMBERSHIP half of the two plugin tiers, for #618's own-method veto.
+      #
+      # `ExpressionTyper#try_local_def_dispatch` has to decide whether the call's own `self` answers the
+      # name before a same-named top-level `def` may bind, and a plugin-supplied member is an answer Ruby
+      # really dispatches to: a model's column reader, an association, a scope, a macro-synthesised
+      # reader. The veto asked neither tier, so a top-level `def name` bound ahead of the member and
+      # typed the read as the def's `nil` — #618's false positive at a source the veto could not see.
+      #
+      # The question is asked HERE, of the same two tiers `resolve` consults and in the same order, rather
+      # than reconstructed in the veto: a name this reports as answered is a name the dispatch really would
+      # resolve, and no plugin knowledge moves into the engine's veto. The tiers are the gated
+      # `dynamic_return` walk and the ADR-16 synthetic-method index (Tier C `heredoc_templates` emissions
+      # today; the Tier B `Plugin::Macro::TraitRegistry` explosions share that table but cannot populate it
+      # until #476 threads a real environment into the pre-pass that builds it, so no trait member reaches
+      # this predicate in production yet — it will when #476 lands, with no change here).
+      #
+      # It is a predicate, not a type: the veto's job is to stop the top-level bind, after which the call
+      # falls through to the ordinary dispatch chain and the tier that answered here answers there too. The
+      # walk is not on the hot path — it runs only once `Scope#bindable_top_level_def_for` has already
+      # produced a candidate, which needs a project top-level `def` of the same name.
+      def plugin_member_answers?(call_node:, scope:, receiver_type:, method_name:)
+        return false if receiver_type.nil?
+        return true unless try_plugin_contribution(call_node, scope, receiver_type).nil?
+
+        synthetic_method_member?(receiver_type, method_name, scope&.environment)
+      end
+
+      # The synthetic-method half of {#plugin_member_answers?} — the same `(class_name, method_name, kind)`
+      # probe {#try_synthetic_method} makes, without the return-type promotion the veto has no use for.
+      def synthetic_method_member?(receiver_type, method_name, environment)
+        index = environment&.synthetic_method_index
+        return false if index.nil? || index.empty?
+
+        class_name = synthetic_method_class_name(receiver_type)
+        return false if class_name.nil?
+
+        matches = if receiver_type.is_a?(Type::Singleton)
+                    index.lookup_singleton(class_name, method_name)
+                  else
+                    index.lookup_instance(class_name, method_name)
+                  end
+        !matches.empty?
+      rescue StandardError
+        false
+      end
+
       # ADR-16 synthetic-method tier. Slice 2b shipped the floor — a match short-circuits at the
       # right precedence (above dep-source / discovered / user-class-fallback; below RBS) and
       # returns `Dynamic[T]`. Slice 6 (precision promotion):
@@ -766,6 +838,7 @@ module Rigor
         "Random" => RandomFolding,
         "Time" => TimeFolding,
         "Regexp" => RegexpFolding,
+        "Process" => ProcessFolding,
         "CGI" => CGIFolding,
         "URI" => URIFolding,
         "Set" => SetFolding,
@@ -774,7 +847,7 @@ module Rigor
       private_constant :STDLIB_SINGLETON_FOLDERS
 
       PRECISE_TIERS_TAIL = Ractor.make_shareable([
-        MethodFolding, ReduceFolding, ArrayToHFolding, BlockFolding
+        MethodFolding, ReduceFolding, ArrayToHFolding, HashTransformKeysFolding, BlockFolding
       ].freeze)
       private_constant :PRECISE_TIERS_TAIL
 
@@ -802,11 +875,8 @@ module Rigor
           return result if result
         end
 
-        receiver = context.receiver
-        if receiver.is_a?(Type::Singleton) && (folder = STDLIB_SINGLETON_FOLDERS[receiver.class_name])
-          result = folder.try_dispatch(context)
-          return result if result
-        end
+        folder_result = dispatch_receiver_keyed_folder(context)
+        return folder_result if folder_result
 
         kernel_result = dispatch_kernel_intrinsic(context)
         return kernel_result if kernel_result
@@ -818,6 +888,19 @@ module Rigor
         nil
       end
 
+      # The folders the receiver's class selects, at most one per call: a stdlib singleton folder, or for a
+      # `MatchData` receiver the slice fold of the proven `$~` (issue #1381). Every other receiver skips them without
+      # a trial.
+      def dispatch_receiver_keyed_folder(context)
+        receiver = context.receiver
+        folder =
+          case receiver
+          when Type::Singleton then STDLIB_SINGLETON_FOLDERS[receiver.class_name]
+          when Type::Nominal then MatchDataFolding if receiver.class_name == "MatchData"
+          end
+        folder&.try_dispatch(context)
+      end
+
       # ADR-91 WD1 — the single dispatcher-held ownership gate for the Kernel module-function surface
       # (gate-by-held-key, the same move STDLIB_SINGLETON_FOLDERS made above). The tier runs only when
       # the method name is in the compiled `INTRINSIC_NAMES` table AND the call is attributable to
@@ -895,6 +978,123 @@ module Rigor
         end
       end
 
+      # Issue #1101 — the composite-receiver projection tier, the LAST thing `resolve` tries.
+      #
+      # Every tier above needs a receiver it can *name*: `receiver_descriptor`, the discovered-method
+      # lookup, the dependency-source and synthesized-stub tiers and the user-class fallback all switch
+      # on `Nominal` / `Singleton` / a member carrier. A `Union` or a `Difference` is none of those, so a
+      # composite receiver whose members would each resolve perfectly well still fell through the whole
+      # chain and landed `Dynamic[top]`.
+      #
+      # `RbsDispatch` already distributes over a `Union` (and erases a `Difference` to its base, #533),
+      # but it does so INSIDE one tier, so a member that needs a LOWER tier — a user class with no RBS,
+      # a discovered `def`, an opt-in gem — makes the whole union decline. That is the corpus shape:
+      # rigor-actionpack types `params[:k]` as `ActionController::Parameters | nil`, the `Parameters` arm
+      # resolves only through the user-class fallback, and so `params[:k].present?` / `#==` / `#blank?` /
+      # `#to_s` read opaque on every Rails app. Measured by toggling this file alone: the named-pair
+      # census drains 137 sites on redmine and 56 on mastodon, and `rigor check` reports the same
+      # diagnostics on both arms across eight survey targets.
+      #
+      # **Why the bottom and not next to `RbsDispatch`.** Sitting here, the tier can only ever replace a
+      # `Dynamic[top]` the typer was about to produce — the same ADR-5 argument {UniversalObjectDispatch}
+      # makes. Hoisting the projection above `RbsDispatch` would change answers that resolve today, which
+      # is a different change with a different measurement.
+      #
+      # **The projection rule** (`receiver_projection` below; the normative statement lives in
+      # [`inference-engine.md`](docs/internal-spec/inference-engine.md) § "Composite receivers"):
+      #
+      # - `Union[A, B, …]` projects to its members. Each is dispatched through this same chain and the
+      #   results are unioned; if ANY member declines, the whole tier declines. Never a partial answer —
+      #   a union whose members disagree about whether the method exists is exactly the case where an
+      #   answer would be a guess.
+      # - `Difference[base, nil]` projects to `base` with its nil-valued members removed. Removing `nil`
+      #   from a receiver cannot change method resolution at all: `NilClass` is nobody's ancestor, so
+      #   every remaining inhabitant looks a method up exactly as a plain `base` inhabitant does, and the
+      #   carrier is value-set-equal to the projection. This is `T.must(x)` (rigor-sorbet's
+      #   `strip_nil`), which builds `Difference[inferred(x), Constant[nil]]` — over a `T?` local that
+      #   base IS a union, which is why the two arms compose rather than being separate features.
+      # - Any other `Difference` DECLINES. `A − B` for a real `B` is a claim about which inhabitants
+      #   survive, and the projection has nowhere to put it: dispatching on `A` re-admits exactly the
+      #   overrides `B` contributed, and over a union base (`(String | Integer) − Integer` is Strings
+      #   only) it re-admits a member the difference eliminated and unions in its answer — a WIDER type
+      #   than today's decline, on a shape no corpus target produces. Subtracting a class from a union
+      #   needs an algebra the `Difference` carrier does not have (it removes a value set, not a member),
+      #   so the honest answer is to keep declining until something demands it. `RbsDispatch`'s #533
+      #   erasure is untouched and still answers these for an RBS-known base.
+      #
+      # `self` binds to the PROJECTED receiver, not to the composite: the projection is the exact set of
+      # inhabitants that can reach the method, so a `-> self` method (`dup`, `itself`, `tap`) answers per
+      # member and the union reassembles them — `(String | Symbol)#itself` is `String | Symbol`. Nothing is
+      # lost on the `Difference` arm because the projection is value-set-equal to the carrier there. This
+      # falls out of re-entering `resolve` rather than needing a `self_type_override`.
+      def try_composite_receiver(context)
+        members = receiver_projection(context.receiver)
+        return nil if members.nil? || members.size > COMPOSITE_PROJECTION_MEMBERS
+
+        plugin_typed = []
+        results = members.map do |member|
+          resolve(
+            receiver_type: member, method_name: context.method_name, arg_types: context.args,
+            block_type: context.block_type, environment: context.environment,
+            call_node: context.call_node, scope: context.scope, plugin_typed_sink: plugin_typed
+          )
+        end
+        return nil if results.any?(&:nil?)
+
+        plugin_typed.uniq.each { |node| context.scope&.record_plugin_typed_call(node) }
+        Type::Combinator.union(*results)
+      end
+
+      # An upper bound on the fan-out, because this tier re-runs the FULL dispatch chain per member.
+      # Real unions are two or three members wide; a receiver wider than this is a join the engine has
+      # already lost precision on, and paying N chain walks to union N answers is not worth it.
+      COMPOSITE_PROJECTION_MEMBERS = 8
+      private_constant :COMPOSITE_PROJECTION_MEMBERS
+
+      # The receivers each member of a composite carrier is dispatched as, or nil when the carrier is not
+      # projectable. Every member returned MUST itself be non-composite: that is what bounds the re-entry
+      # into `resolve` at one level, by construction rather than by a counter — the nested call reaches
+      # this tier with a receiver it declines immediately. A normalized `Union` never holds a `Union`, so
+      # the shapes the guard turns away are a `Difference` over a `Difference` (`T.must(T.must(x))`) and a
+      # `Union` holding one (`c ? T.must(y) : Bar.new`, which normalizes to `(A - nil) | Bar`). Both
+      # decline exactly as they did before this tier existed; neither appears in the survey corpus.
+      def receiver_projection(receiver)
+        members =
+          case receiver
+          when Type::Union then receiver.members
+          when Type::Difference then difference_projection(receiver)
+          end
+        return nil if members.nil? || members.empty?
+        return nil if members.any? { |member| member.is_a?(Type::Union) || member.is_a?(Type::Difference) }
+
+        members
+      end
+
+      # `Difference[base, nil]` projects to `base` minus its nil-valued members; every other difference
+      # declines. The nil filter runs over a scalar base as well as a union one, so the rule stays total:
+      # `Combinator.difference` does not normalize `NilClass - nil` (or `nil - nil`) to `Bot`, and this
+      # tier must not project `[NilClass]` and answer a NilClass method for a carrier with no inhabitant.
+      # Nothing observable turns on it today — `RbsDispatch`'s #533 erasure sits above this tier and
+      # already answers a nil-only base from the base's own descriptor — which is why the guard is here
+      # rather than in `Combinator`, where it would be a normalization change with its own blast radius.
+      def difference_projection(difference)
+        return nil unless nil_valued_type?(difference.removed)
+
+        base = difference.base
+        members = base.is_a?(Type::Union) ? base.members : [base]
+        retained = members.reject { |member| nil_valued_type?(member) }
+        return nil if retained.empty?
+
+        retained
+      end
+
+      # `nil` as either carrier spells it: the value-pinned `Constant[nil]` the engine normally produces,
+      # and the `Nominal[NilClass]` a widened or RBS-sourced position carries.
+      def nil_valued_type?(type)
+        (type.is_a?(Type::Constant) && type.value.nil?) ||
+          (type.is_a?(Type::Nominal) && type.class_name == "NilClass")
+      end
+
       # Slice 7 phase 8 — meta-introspection shortcuts. The default `Object#class` RBS return
       # type is `Class`, but for a receiver of known nominal identity we can do better:
       # `instance_of(Foo).class` is `Singleton[Foo]` (the class object itself), which downstream
@@ -1355,12 +1555,13 @@ module Rigor
       # method definition, or selected overload does not provide statically declared block
       # parameter types. Callers MUST treat the empty array as "no information"; the binder
       # falls back to `Dynamic[Top]` for every parameter slot in that case.
-      def expected_block_param_types(receiver_type:, method_name:, arg_types:, environment: nil)
+      def expected_block_param_types(receiver_type:, method_name:, arg_types:, environment: nil,
+                                     scope: nil)
         return [] if receiver_type.nil?
 
         context = CallContext.build(
           receiver: receiver_type, method_name: method_name,
-          args: arg_types, environment: environment
+          args: arg_types, environment: environment, scope: scope
         )
         iterator_result = IteratorDispatch.block_param_types(context)
         return iterator_result if iterator_result

data/lib/rigor/inference/method_parameter_binder.rb

@@ -198,7 +198,14 @@ module Rigor
       # both `()` and `(int)` overloads — only the second matches a `def first(n)` redefinition)
       # are silently skipped, so the binder defaults to the most informative type the RBS
       # signature provides without having to know which overload the runtime will pick.
+      #
+      # An overload declared `(?)` (`RBS::Types::UntypedFunction`, issue #1430) has no parameter lists and
+      # accepts any argument in every slot, so no slot can be narrowed below `Dynamic[Top]`: binding a typed
+      # sibling overload's parameter type would read a value that overload legitimately passes as a
+      # contradiction inside the body. Every slot keeps its default; the declared return type still applies.
       def apply_rbs_overloads(types, slots, method_types)
+        return unless method_types.all? { |mt| mt.type.respond_to?(:required_positionals) }
+
         slots.each do |slot|
           next if slot.name.nil?
 
@@ -258,9 +265,7 @@ module Rigor
         return nil if contracts.empty?
 
         singleton = def_node.receiver.is_a?(Prism::SelfNode) || @singleton
-        contracts.find do |contract|
-          contract.method_name == def_node.name && contract.singleton == singleton
-        end
+        contracts.find { |contract| contract.method_name == def_node.name && contract.singleton == singleton }
       end
 
       def positional_slot_at(slots, index)

data/lib/rigor/inference/module_function_state.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "../source/node_children"
+
+module Rigor
+  module Inference
+    # The one home for what a receiverless `module_function` call does to the methods around it
+    # ([#1507](https://github.com/rigortype/rigor/issues/1507),
+    # [#1197](https://github.com/rigortype/rigor/issues/1197)). Four readers used to compute it in four
+    # places. They disagree with each other and, in places, with Ruby. Each entry point below reproduces
+    # one reader's answer exactly: this module gives the readings one place to live, and does not yet make
+    # them agree. A change to one reading lands here, beside the other three. Examples are #1550's
+    # named-form snapshot and the reset a bare `public`, `private` or `protected` makes.
+    #
+    # - The singleton def-node table (`ScopeIndexer#walk_singleton_body`) reads
+    #   {.each_singleton_sibling} and {.each_singleton_copy}. A bare call covers the later direct
+    #   statements of its own body and is never reset.
+    # - The deferred ranges (`ScopeIndexer#walk_deferred_body`) read {.prescan_deferred} and
+    #   {.deferred_module_function?}. A bare call covers every later def by offset, and a call inside
+    #   control flow or a block counts.
+    # - The extends table (`ScopeIndexer#record_extend_call`) reads {.extends_self?}. A bare call covers
+    #   every instance def of the module, in any order.
+    # - sig-gen (`SigGen::Generator#walk_statements`) reads {.each_sig_gen_statement} and
+    #   {.sig_gen_module_function?}. A bare call covers the later statements of its own statement list and
+    #   what nests in them.
+    #
+    # A fifth reader does not come here yet: `rigor-activerecord`'s `ModelDiscoverer#table_name_decorators`
+    # (`plugins/rigor-activerecord/lib/rigor/plugin/activerecord/model_discoverer.rb`) reads a module body's
+    # direct statements for its table-name readers. It also accepts `self.module_function`, and there a bare
+    # call covers the instance methods written before it as well as after it, while a named call takes only a
+    # def written before it. A change to what `module_function` means must decide whether that reader follows.
+    #
+    # The deferred-ranges prescan asks `ScopeIndexer.receiver_eval_call?` and `ScopeIndexer.def_singleton?`, so
+    # `rigor/inference/scope_indexer` must be loaded before it runs. This file does not require it:
+    # `scope_indexer.rb` requires this file, and a require back would be circular. The other entry points need
+    # only Prism.
+    #
+    # `spec/rigor/inference/module_function_state_spec.rb` pins each reader's answers, and marks the ones
+    # Ruby contradicts with a "flip this when" note.
+    module ModuleFunctionState
+      module_function
+
+      # A receiverless `module_function` call, bare or named.
+      def call?(node)
+        node.name == :module_function && node.receiver.nil?
+      end
+
+      # The toggle form: a `module_function` call with no arguments.
+      def bare?(node)
+        node.arguments.nil? || node.arguments.arguments.empty?
+      end
+
+      # The singleton def-node table's reading, over one class-ish body's direct statements in source
+      # order. `ScopeIndexer#statements_of` builds that list, folding a body-level `rescue`, `else` or
+      # `ensure` clause into it. Yields `stmt, module_function_on, named_call` for every statement except a
+      # bare call:
+      #
+      # - `module_function_on` says whether a bare call precedes the statement. The toggle never switches
+      #   off, although a later bare `public`, `private` or `protected` resets it in Ruby.
+      # - `named_call` is true for a named call (`module_function :a` or `module_function def x`), which
+      #   {.each_singleton_copy} resolves; the caller records nothing else for it.
+      #
+      # A call nested in control flow or a block is not seen.
+      def each_singleton_sibling(statements)
+        module_function_on = false
+        statements.each do |stmt|
+          if stmt.is_a?(Prism::CallNode) && call?(stmt)
+            if bare?(stmt)
+              module_function_on = true
+            else
+              yield stmt, module_function_on, true
+            end
+            next
+          end
+          yield stmt, module_function_on, false
+        end
+      end
+
+      # The defs a named call copies onto the module's singleton, for the singleton def-node table. Yields
+      # `name, def_node` for each Symbol or String argument that names a receiverless def among the body's
+      # direct `statements`. The last def of that name wins wherever it sits. A def written after the call
+      # is therefore taken, although Ruby copies the one in effect at the call (#1550), and a name defined
+      # only after the call resolves, although Ruby raises `NameError` there. A `module_function def x`
+      # argument names nothing here.
+      def each_singleton_copy(call, statements)
+        defs_by_name = statements.each_with_object({}) do |stmt, acc|
+          acc[stmt.name] = stmt if stmt.is_a?(Prism::DefNode) && stmt.receiver.nil?
+        end
+        call.arguments&.arguments&.each do |arg|
+          name = symbol_argument_name(arg)
+          def_node = name && defs_by_name[name]
+          yield name, def_node if def_node
+        end
+      end
+
+      # The deferred-ranges reading, over one class-ish body's subtree. Appends to `offsets` the start of
+      # every bare call; each def that starts after one is a module function
+      # ({.deferred_module_function?}). Appends to `ranges` one row per named call, in the table's
+      # `[start, end, name, kind, owner]` shape:
+      #
+      # - a `:name` argument gives a `:singleton` row over the call itself, because the copy happens at
+      #   the call and not at the def;
+      # - a `module_function def x` argument gives a `:both` row over the def, or a `:singleton` row for
+      #   `def self.x`.
+      #
+      # The prescan looks through control flow and blocks, because a call that ran there still flips the
+      # later defs. It stops at a nested class, module, `class <<` or def body, where the call targets
+      # another module. It skips an `END` body, which runs after every def, and a `*_eval` / `*_exec`
+      # block, whose self is the receiver's module; that block gets its own prescan as a body. Nothing
+      # resets it.
+      #
+      # `qualified_prefix` names the owner, and `in_singleton_class` says whether the body is a
+      # `class <<` body; both feed `ScopeIndexer.def_singleton?`.
+      def prescan_deferred(node, qualified_prefix, in_singleton_class, offsets, ranges)
+        return unless node.is_a?(Prism::Node)
+        return if node.is_a?(Prism::ClassNode) || node.is_a?(Prism::ModuleNode) ||
+                  node.is_a?(Prism::SingletonClassNode) || node.is_a?(Prism::DefNode) ||
+                  node.is_a?(Prism::PostExecutionNode)
+
+        if node.is_a?(Prism::CallNode)
+          return prescan_call(node, qualified_prefix, in_singleton_class, offsets, ranges) if call?(node)
+          if ScopeIndexer.receiver_eval_call?(node)
+            return prescan_eval_call(node, qualified_prefix, in_singleton_class, offsets, ranges)
+          end
+        end
+
+        node.rigor_each_child do |child|
+          prescan_deferred(child, qualified_prefix, in_singleton_class, offsets, ranges)
+        end
+      end
+
+      # Whether the deferred-ranges reading makes a def starting at `start` a module function: a bare call
+      # starts before it, at any depth the prescan entered.
+      def deferred_module_function?(offsets, start)
+        offsets.any? { |offset| offset < start }
+      end
+
+      # The extends table's reading. A bare call makes the module extend itself, so every instance def the
+      # module has also answers on its singleton. That holds for defs before and after the call, and
+      # whatever a later `public` or `private` says. The over-approximation is deliberate (#526): the
+      # extra names only silence `call.undefined-method` on calls that raise. The walk reaches a call in
+      # control flow, and one in a `class_eval`-family block under that block's receiver. It does not reach
+      # one in an ordinary block, an `END` body or a `class << self` body.
+      def extends_self?(call)
+        call?(call) && bare?(call)
+      end
+
+      # sig-gen's reading, over one statement list. Yields every statement except a bare call, with
+      # whether a bare call came before it in this list or `active` was already true on entry. The
+      # generator passes the enclosing list's answer into an `if`, a block or a `begin`, but not into a
+      # nested class, module or `class << self`. A bare call in a nested list covers only that list's
+      # later statements. Nothing resets it, and a named call is not a directive at all.
+      def each_sig_gen_statement(statements, active)
+        statements.each do |stmt|
+          if sig_gen_directive?(stmt)
+            active = true
+            next
+          end
+          yield stmt, active
+        end
+      end
+
+      # A bare receiverless call, as sig-gen's statement-level directive.
+      def sig_gen_directive?(node)
+        node.is_a?(Prism::CallNode) && call?(node) && bare?(node)
+      end
+
+      # Whether sig-gen renders a def as `def self?.name`: an instance-side def under an active directive,
+      # in a class or a module alike. `kind` is `:singleton` for `def self.x` and a `class << self` body.
+      def sig_gen_module_function?(active, kind)
+        active && kind == :instance
+      end
+
+      # The prescan's call arm.
+      def prescan_call(node, qualified_prefix, in_singleton_class, offsets, ranges)
+        if bare?(node)
+          offsets << node.location.start_offset
+        else
+          owner = qualified_prefix.empty? ? nil : qualified_prefix.join("::")
+          node.arguments&.arguments&.each do |arg|
+            if arg.is_a?(Prism::DefNode)
+              kind = ScopeIndexer.def_singleton?(arg, qualified_prefix, in_singleton_class) ? :singleton : :both
+              ranges << [arg.location.start_offset, arg.location.end_offset, arg.name, kind, owner]
+            elsif (name = symbol_argument_name(arg))
+              ranges << [node.location.start_offset, node.location.end_offset, name, :singleton, owner]
+            else
+              prescan_deferred(arg, qualified_prefix, in_singleton_class, offsets, ranges)
+            end
+          end
+        end
+        return unless node.block
+
+        prescan_deferred(node.block, qualified_prefix, in_singleton_class, offsets, ranges)
+      end
+
+      # The prescan's eval arm: only the call's receiver and arguments keep this module's context.
+      def prescan_eval_call(node, qualified_prefix, in_singleton_class, offsets, ranges)
+        prescan_deferred(node.receiver, qualified_prefix, in_singleton_class, offsets, ranges) if node.receiver
+        node.arguments&.arguments&.each do |arg|
+          prescan_deferred(arg, qualified_prefix, in_singleton_class, offsets, ranges)
+        end
+      end
+
+      # The Symbol a `:name` or `"name"` literal argument names, or nil.
+      def symbol_argument_name(arg)
+        arg.unescaped.to_sym if arg.is_a?(Prism::SymbolNode) || arg.is_a?(Prism::StringNode)
+      end
+
+      private_class_method :prescan_call, :prescan_eval_call, :symbol_argument_name
+    end
+  end
+end