rigortype 0.3.9 → 0.4.1

data/lib/rigor/inference/block_auto_splat.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require_relative "../type"
+require_relative "multi_target_binder"
+
+module Rigor
+  module Inference
+    # The auto-splat half of {BlockParameterBinder}: given a block's positional parameter shape and the one
+    # value the receiver yields, it answers the positional table the block's names are bound from.
+    #
+    # Ruby blocks (NOT lambdas) spread a single yielded array-ish value across their positionals, and CRuby
+    # decides that on the PARAMETER LIST alone ({ParameterShape#splats?}) — never on the value. So the
+    # carrier only decides how precisely each position can be filled, and a carrier this module cannot
+    # decompose lowers the positions to `Dynamic[Top]` rather than cancelling the spread (issue #1116).
+    #
+    # Each member of the carrier (a union distributes; anything else is its own single member) contributes
+    # one {Table}, and {join} folds them into the answer:
+    #
+    # - a `Type::Tuple` spreads element-wise, leading positionals (required, then optional) from the head
+    #   and, with a rest present, trailing positionals from the tail with the rest absorbing the middle —
+    #   the split `MultiTargetBinder` applies to `a, *r, b = tuple`, so `|*r, v|` over `[K, V]` binds `v` to
+    #   `V`. A slot past the tuple is left unfilled and lands on `Dynamic[Top]`;
+    # - an `Array[T]` ({MultiTargetBinder.array_element_type}) binds `T` to every required and trailing
+    #   positional, `Dynamic[Top]` to every optional one (a short array hands it its default, not `nil`),
+    #   and `Array[T]` to a named rest. A short array pads the fixed positions with `nil` at runtime, so
+    #   those positions are reported optimistic (issue #1093);
+    # - an opaque array carrier — a raw `Array`, an `Array[untyped]` / `Array[top]`, a `Refined` /
+    #   `Difference` over either, or a `Dynamic` over any `Array` however precise — binds `Dynamic[Top]` to
+    #   every position: the floor `MultiTargetBinder` binds for the same undecomposable right-hand side, and
+    #   the reason `[1, 2].tap { |a, b| a.succ }` no longer reads `a` as the whole `Array` (issue #1116);
+    # - a bare `nil` binds `nil` to every position. `nil` has no `to_ary`, so CRuby passes it as the one
+    #   argument and `|a, b|` sees `nil, nil` — which is also what the wrap `[nil]` pads to, so the two
+    #   readings agree here, and {join} takes that `nil` back out of any position another member fills;
+    # - every other member takes the same `Dynamic[Top]` floor as the opaque one, and does NOT license the
+    #   spread on its own. It is the member the union knows least about, and joining it as a value would put
+    #   a nil-bearing element beside a nil-free one: `String#scan`'s `String | Array[String?]` yield joins a
+    #   capture's `String?` against the whole match's `String` and fires `call.possible-nil-receiver` on the
+    #   correlated-invariant `refinements[name.to_sym]`, which ADR-5 ranks above the precision.
+    #
+    # The spread needs at least one Tuple, `Array[T]` or opaque array member; a carrier with none of them
+    # ({#for} answers nil) leaves the binder's declared types alone, which binds the value to the first
+    # parameter and `Dynamic[Top]` after. So a lone value with no `to_ary` is NOT wrapped as `[value]` the
+    # way `a, b = value` wraps it: the one-value premise of auto-splat is the RBS block signature's arity,
+    # which nothing here can check against the actual yield, and a wrong wrap binds `nil` to a parameter the
+    # block receives a value in.
+    #
+    # See docs/internal-spec/inference-engine.md for the binding contract.
+    module BlockAutoSplat
+      # The positional part of a parameter list, as counts: all the auto-splat rule reads. An explicit
+      # `BlockParametersNode` list and a numbered-parameter block (`maximum` required positionals) both
+      # reduce to it, so the two spellings cannot drift.
+      ParameterShape = Data.define(:required, :optional, :post, :rest) do
+        def self.of(params_node)
+          new(required: params_node.requireds.size, optional: params_node.optionals.size,
+              post: params_node.posts.size, rest: !params_node.rest.nil?)
+        end
+
+        # The `_1` / `_2` form, read as the explicit list of `arity` required positionals.
+        def self.of_arity(arity)
+          new(required: arity, optional: 0, post: 0, rest: false)
+        end
+
+        def positional_count = required + optional + post
+
+        # CRuby's own condition (`vm_callee_setup_block_arg` / `setup_parameters_complex`): a block splats a
+        # lone array argument when it has a mandatory positional (`lead + post > 0`) or more than one
+        # optional, except a bare `|a|` (the iseq's `ambiguous_param0`). So `|k, *r|`, `|*r, v|`,
+        # `|a = 1, b = 2|` and the trailing-comma `|k,|` (Prism's `ImplicitRestNode`) splat, while `|*r|`,
+        # `|a = 1, *r|` and `|a, &b|` / `|a, k: 1|` do not.
+        def splats?
+          mandatory = required + post
+          return false unless mandatory.positive? || optional > 1
+
+          !(mandatory == 1 && optional.zero? && !rest)
+        end
+      end
+
+      # A positional table: the type per position, the positions bound optimistically, and the named rest's
+      # type (nil for the `Array[Dynamic[Top]]` default). One arm produces one; {join} folds them into one.
+      # Private as a name — {#for} hands the folded value out, and nothing outside constructs one.
+      Table = Data.define(:types, :optimistic_positions, :rest_type)
+      private_constant :Table
+
+      # The arm kinds that make a member an array as far as the spread is concerned, so that a union
+      # carrying one of them spreads even where its other members do not decompose.
+      ARRAY_CARRIER_ARMS = %i[tuple array opaque].freeze
+      private_constant :ARRAY_CARRIER_ARMS
+
+      module_function
+
+      # @param shape — the block's {ParameterShape}.
+      # @param carrier — the one value the receiver yields.
+      # @return the folded {Table}, or nil when no member is an array carrier and the
+      #   spread must leave the declared types alone.
+      def for(shape, carrier)
+        arms = arms_of(carrier)
+        return nil if arms.nil?
+
+        join(arms.map { |member, kind| table_for(shape, member, kind) })
+      end
+
+      def arms_of(carrier)
+        members = carrier.is_a?(Type::Union) ? carrier.members : [carrier]
+        arms = members.map { |member| [member, arm_of(member)] }
+        arms.any? { |_, kind| ARRAY_CARRIER_ARMS.include?(kind) } ? arms : nil
+      end
+
+      def arm_of(member)
+        return :tuple if member.is_a?(Type::Tuple)
+        return :array if MultiTargetBinder.array_element_type(member)
+        return :opaque if opaque_array_carrier?(member)
+        return :nil_value if nil_literal?(member)
+
+        :unknown
+      end
+
+      # A carrier that is an array the module may not decompose into per-position types: the raw `Array`, an
+      # `Array[untyped]` / `Array[top]`, a `Refined` / `Difference` over either, and a `Dynamic` over ANY
+      # carrier that would license the spread — `Dynamic[Array[Integer]]`, `Dynamic[[Integer, String]]`,
+      # `Dynamic[Array[Integer] | nil]` alike. {MultiTargetBinder.array_element_type} declines every
+      # `Dynamic` wrapper on purpose: the value is gradual, and projecting its static facet would hand each
+      # position a bare `T` that licenses the negative rules (issue #1093, ADR-5). That is a reason to floor
+      # the positions, not a reason to leave the whole value on the first parameter, so the facet decides
+      # only whether CRuby would splat.
+      def opaque_array_carrier?(type)
+        case type
+        when Type::Nominal then type.class_name == "Array"
+        when Type::Refined, Type::Difference then opaque_array_carrier?(type.base)
+        when Type::Dynamic then !arms_of(type.static_facet).nil?
+        else false
+        end
+      end
+
+      def table_for(shape, member, kind)
+        case kind
+        when :tuple then tuple_table(shape, member.elements)
+        when :array then array_table(shape, MultiTargetBinder.array_element_type(member))
+        when :nil_value then uniform_table(shape, member)
+        else uniform_table(shape, Type::Combinator.untyped)
+        end
+      end
+
+      # The split is mirrored rather than delegated to `MultiTargetBinder.decompose_tuple` because that one
+      # pads a missing slot with `Constant[nil]` and softens `X | nil`; a block slot past the tuple has
+      # always bound `Dynamic[Top]`. Without a rest the trailing positionals continue from the head (Ruby
+      # fills `|a, b = 1, c|` from the head when the tuple is long enough).
+      def tuple_table(shape, elements)
+        head = shape.required + shape.optional
+        posts = shape.post
+        tail_start = shape.rest ? [elements.size - posts, head].max : head
+        types = Array.new(head) { |i| elements[i] } + Array.new(posts) { |j| elements[tail_start + j] }
+        Table.new(types: types, optimistic_positions: [], rest_type: nil)
+      end
+
+      def array_table(shape, element)
+        required = shape.required
+        optional = shape.optional
+        posts = shape.post
+        Table.new(
+          types: Array.new(required) { element } + Array.new(optional) { Type::Combinator.untyped } +
+                 Array.new(posts) { element },
+          optimistic_positions: (0...required).to_a + ((required + optional)...(required + optional + posts)).to_a,
+          rest_type: Type::Combinator.nominal_of("Array", type_args: [element])
+        )
+      end
+
+      # One type for every position: the `Dynamic[Top]` floor of a member the module cannot decompose, or
+      # the `nil` a `nil` member hands each of them. The `nil` rest_type leaves a named rest on the binder's
+      # `Array[Dynamic[Top]]` default, which is right for both — CRuby gives `nil.tap { |a, *r| }` an empty
+      # `r`, and an opaque carrier says nothing about the leftovers.
+      def uniform_table(shape, type)
+        Table.new(types: Array.new(shape.positional_count) { type }, optimistic_positions: [], rest_type: nil)
+      end
+
+      # A single member's table is used as is. Across members, a position any member leaves unfilled (a slot
+      # past a short Tuple) or fills with `Dynamic[Top]` stays `Dynamic[Top]`, and a member's bare `nil`
+      # drops out of a position another member fills with a value, that position then being optimistic —
+      # `MultiTargetBinder`'s cross-member softening. A named rest joins only when every member supplies
+      # one; otherwise the binder's `Array[Dynamic[Top]]` default stands.
+      def join(tables)
+        types, softened = join_types(tables.map(&:types))
+        rests = tables.map(&:rest_type)
+        Table.new(
+          types: types,
+          optimistic_positions: (tables.flat_map(&:optimistic_positions) + softened).uniq,
+          rest_type: rests.include?(nil) ? nil : Type::Combinator.union(*rests)
+        )
+      end
+
+      # @return the joined table and the positions it softened.
+      def join_types(tables)
+        return [tables.first, []] if tables.size == 1
+
+        softened = []
+        joined = Array.new(tables.map(&:size).max) do |i|
+          column = tables.map { |table| table[i] }
+          next Type::Combinator.untyped if column.any? { |t| t.nil? || t == Type::Combinator.untyped }
+
+          firm = column.reject { |t| nil_literal?(t) }
+          next Type::Combinator.union(*column) if firm.empty? || firm.size == column.size
+
+          softened << i
+          Type::Combinator.union(*firm)
+        end
+        [joined, softened]
+      end
+
+      def nil_literal?(type) = type.is_a?(Type::Constant) && type.value.nil?
+
+      # {#for} is the whole surface; the arms and the fold are this module's own business, and keeping them
+      # off the singleton stops a caller reaching past the fold for one member's table.
+      private_class_method :arms_of, :arm_of, :opaque_array_carrier?, :table_for, :tuple_table, :array_table,
+                           :uniform_table, :join, :join_types, :nil_literal?
+    end
+  end
+end

data/lib/rigor/inference/block_call_timing.rb

@@ -0,0 +1,338 @@
+# frozen_string_literal: true
+
+require_relative "../type"
+require_relative "../reflection"
+
+module Rigor
+  module Inference
+    # Issue #1095 — the first slice of the block call-timing summary that
+    # `docs/type-specification/control-flow-analysis.md` § "Block call timing" asks for: which callees invoke
+    # their block **immediately, exactly once, and before they return**.
+    #
+    # The fact matters for the value of the call. Since #853 a block-level `break` joins the yielding call's
+    # type, unioned with what the callee returns when the block completes normally. For an arbitrary callee
+    # that normal return must stay — `each` may never yield on an empty receiver. For a callee that always
+    # yields exactly once before returning, a block whose normal completion is unreachable means the normal
+    # return is unreachable too, so the call's value is its `break` arms alone (`bot` when there are none):
+    # `[1, 2].tap { break "s" }` is `"s"`, `[1, 2].tap { raise "x" }` is `bot`.
+    #
+    # ## Catalogue
+    #
+    # Like {ClosureEscapeAnalyzer}'s `OBJECT_NON_ESCAPING` — a weaker "block is not retained" fact that `each`
+    # and `map` also satisfy — this ships as a hardcoded table keyed by `(owner, method)`, where the owner is
+    # the module whose declaration Ruby dispatches to. The sub-phase that replaces the escape catalogue with an
+    # `RBS::Extended` call-timing effect (`rbs-extended.md` reserves the bundle slot) is expected to absorb
+    # this table in the same move, which is why it is keyed by the declaring owner, the way a signature-borne
+    # effect would be, rather than by the receiver's class.
+    #
+    # The owner is `Kernel` for all three, in CRuby (`Object.instance_method(:tap).owner`) and in the bundled
+    # core RBS alike. `Object` is deliberately NOT accepted: every class inherits these methods through
+    # `Object`, so a declaration that resolves to `Object` itself is a project or gem override written on top
+    # of Kernel's, and that override is not known to yield exactly once.
+    #
+    # The summary is a pure query. It never raises on unrecognised input and answers `false` — keep the
+    # `break | normal-return` union — whenever it cannot prove the call reaches the catalogued declaration.
+    module BlockCallTiming
+      EXACTLY_ONCE_IMMEDIATE = {
+        "Kernel" => %i[tap then yield_self].freeze
+      }.freeze
+
+      CANDIDATE_NAMES = EXACTLY_ONCE_IMMEDIATE.values.flatten.uniq.freeze
+      private_constant :CANDIDATE_NAMES
+
+      # The roots a project monkey-patch would redefine the method on for every receiver at once.
+      PATCHABLE_ROOTS = %w[Object Kernel BasicObject].freeze
+      private_constant :PATCHABLE_ROOTS
+
+      # A class object's own metaclass ancestry adds these ahead of `Object`, so a patch on either one
+      # redefines the method for every class-object receiver.
+      SINGLETON_ROOTS = %w[Class Module].freeze
+      private_constant :SINGLETON_ROOTS
+
+      # Receiver-less (or `self.` / `Kernel.`) calls that never return normally: they raise, throw, or end
+      # the process. Anything else — including `loop`, whose RBS return is `bot` although a `StopIteration`
+      # ends it normally ({.loop_may_complete?}) — proves nothing.
+      NON_RETURNING_CALLS = %i[raise fail throw exit exit! abort].freeze
+      private_constant :NON_RETURNING_CALLS
+
+      # Issue #1107 — the nodes a `loop` body may consist of while still provably unable to raise
+      # `StopIteration`: none of them dispatches a method, so nothing in the body can run code that raises.
+      # Everything else — every call (operators and `[]` included), `yield`, `super`, interpolation, a splat,
+      # a constant read (`const_missing`), a `rescue` — may, and declines.
+      STOP_ITERATION_FREE_NODES = [
+        Prism::StatementsNode, Prism::ParenthesesNode, Prism::ArgumentsNode,
+        Prism::BreakNode, Prism::NextNode, Prism::RedoNode, Prism::ReturnNode,
+        Prism::IntegerNode, Prism::FloatNode, Prism::RationalNode, Prism::ImaginaryNode,
+        Prism::StringNode, Prism::SymbolNode, Prism::NilNode, Prism::TrueNode, Prism::FalseNode, Prism::SelfNode,
+        Prism::LocalVariableReadNode, Prism::LocalVariableWriteNode,
+        Prism::InstanceVariableReadNode, Prism::InstanceVariableWriteNode,
+        Prism::IfNode, Prism::UnlessNode, Prism::ElseNode, Prism::AndNode, Prism::OrNode, Prism::ArrayNode
+      ].freeze
+      private_constant :STOP_ITERATION_FREE_NODES
+
+      module_function
+
+      # Issue #1107 — whether a `loop` call can complete normally although its declared return is `bot`.
+      #
+      # `Kernel#loop` is `() { () -> void } -> bot` in core RBS, yet it rescues a `StopIteration` its block
+      # raises and returns that exception's `result` — the enumerator-draining idiom `loop { out << e.next }`
+      # returns `e`'s own `each` value. So the declared `bot` holds only for a body that provably cannot raise
+      # `StopIteration`: one built from {STOP_ITERATION_FREE_NODES} alone (`loop {}`, `loop { break 1 }`), in a
+      # block that declares no parameters. A `&blk` block-pass has no body to prove anything about and completes
+      # too.
+      #
+      # Gated on the spellings that reach the private `Kernel#loop` — receiver-less, `self.`, `Kernel.`,
+      # `::Kernel.` — so `obj.loop { ... }` is some other method, whose declared `bot` is that author's
+      # promise. A project redefinition of `loop` itself is not excluded: widening its `bot` costs precision,
+      # never a false positive.
+      def loop_may_complete?(call_node)
+        return false unless call_node.name == :loop && kernel_spelled_receiver?(call_node.receiver)
+
+        block = call_node.block
+        return false if block.nil?
+        return true unless block.is_a?(Prism::BlockNode)
+        # A parameter default (`|v = e.next|`) is evaluated on every iteration, since `loop` yields no
+        # arguments. Rather than walk the parameter list, any declared parameter widens.
+        return true if block.parameters
+        return false if block.body.nil?
+
+        may_raise_stop_iteration?(block.body)
+      end
+
+      def may_raise_stop_iteration?(node)
+        return true unless STOP_ITERATION_FREE_NODES.any? { |klass| node.is_a?(klass) }
+
+        node.compact_child_nodes.any? { |child| may_raise_stop_iteration?(child) }
+      end
+
+      # Cheap name-only pre-gate, so a call that cannot be catalogued pays nothing further.
+      def candidate_name?(method_name)
+        CANDIDATE_NAMES.include?(method_name)
+      end
+
+      def exactly_once_owner?(owner_name, method_name)
+        methods = EXACTLY_ONCE_IMMEDIATE[owner_name.to_s.delete_prefix("::")]
+        methods ? methods.include?(method_name) : false
+      end
+
+      # Whether a call of `method_name` on `receiver_type` reaches a catalogued exactly-once declaration.
+      #
+      # Gated on the RESOLVED owner, not the name: a class that defines its own `tap` (in source, in a
+      # project `sig/`, or through a project ancestor), a top-level `def tap` (a private `Object` method,
+      # ahead of `Kernel` in every MRO) and an `Object` / `Kernel` monkey-patch all decline. A union receiver
+      # qualifies only when every member does; `Dynamic` and the other carriers that name no class decline.
+      def exactly_once_call?(receiver_type:, method_name:, scope:)
+        return false unless candidate_name?(method_name)
+        return false if scope.nil? || project_redefines_root?(method_name, scope)
+
+        targets = receiver_targets(receiver_type)
+        return false if targets.nil? || targets.empty?
+
+        targets.all? { |class_name, kind| resolves_to_catalogue?(class_name, kind, method_name, scope) }
+      rescue StandardError
+        false
+      end
+
+      # Syntactic proof that a block body cannot complete normally: every path through it ends in a
+      # block-level `break` (which targets the yielding call), `return`, `redo`, or a non-returning Kernel call
+      # ({NON_RETURNING_CALLS}) — or in an expression that must evaluate one of those first. This is ANDed
+      # with the block-return pass's `bot`, never used alone, because a `bot` can also flow out of a callee's
+      # declared return that is not a promise the call never completes (`Kernel#loop` is `-> bot`, yet a
+      # `StopIteration` from `e.next` ends it normally). A shape the walk does not recognise declines.
+      #
+      # Only unconditionally evaluated children are descended: a nested block, lambda, `def` or loop is never
+      # entered (its body may not run, and it retargets `break`), a call's block is not a child the call
+      # promises to run, and `&&` / `||` count only their left operand. A `begin` with `rescue` qualifies only
+      # when its body and every rescue clause must exit; an `ensure` that must exit qualifies on its own.
+      def never_completes_normally?(node, scope)
+        case node
+        when Prism::StatementsNode then node.body.any? { |statement| never_completes_normally?(statement, scope) }
+        when Prism::BreakNode, Prism::ReturnNode, Prism::RedoNode, Prism::RetryNode then true
+        when Prism::ParenthesesNode then never_completes_normally?(node.body, scope)
+        when Prism::CallNode then call_never_returns?(node, scope)
+        when Prism::IfNode, Prism::UnlessNode then conditional_never_completes?(node, scope)
+        when Prism::AndNode, Prism::OrNode then never_completes_normally?(node.left, scope)
+        when Prism::BeginNode then begin_never_completes?(node, scope)
+        when Prism::ArrayNode then node.elements.any? { |element| never_completes_normally?(element, scope) }
+        when Prism::LocalVariableWriteNode, Prism::InstanceVariableWriteNode
+          never_completes_normally?(node.value, scope)
+        else false
+        end
+      end
+
+      # Deliberately coarse: ANY project definition of the name — top-level, on any class or module, either
+      # side, or a `pre_eval:` patch — declines. Resolving the call-site `self`'s ancestry precisely buys
+      # nothing for names this rare, and the block-return pass is no independent check here: it types a
+      # self-call to an overridden `raise` as Kernel's `bot` too, so a missed override is a wrong `bot`.
+      # {LastLine.reads_line?} declines on it the same way for `gets` and `readline`.
+      def project_defines_anywhere?(method_name, scope)
+        return true if scope.top_level_def_for(method_name)
+        # `discovered_methods` withholds a plain cross-file `def` (the ADR-17 monkey-patch contract); the
+        # def-node tables still carry it, on both sides.
+        return true if [scope.discovered_methods, scope.discovered_def_nodes, scope.discovered_singleton_def_nodes]
+                       .any? { |tables| tables.any? { |_class_name, table| table.key?(method_name) } }
+
+        patched = scope.environment&.project_patched_methods
+        !patched.nil? && patched.by_key.any? { |(_class_name, name, _kind), _entry| name == method_name }
+      end
+
+      class << self
+        private
+
+        def call_never_returns?(node, scope)
+          return true if never_completes_normally?(node.receiver, scope)
+          return true if node.arguments&.arguments&.any? { |argument| never_completes_normally?(argument, scope) }
+          return false unless NON_RETURNING_CALLS.include?(node.name)
+
+          kernel_spelled_receiver?(node.receiver) && !project_defines_anywhere?(node.name, scope)
+        end
+
+        # Implicit self, `self.`, or the `Kernel` module itself (`Kernel.` or the root-anchored `::Kernel.`) —
+        # the spellings that reach Kernel's function.
+        def kernel_spelled_receiver?(receiver)
+          case receiver
+          when nil, Prism::SelfNode then true
+          when Prism::ConstantReadNode then receiver.name == :Kernel
+          when Prism::ConstantPathNode then receiver.parent.nil? && receiver.name == :Kernel
+          else false
+          end
+        end
+
+        def conditional_never_completes?(node, scope)
+          return true if never_completes_normally?(node.predicate, scope)
+
+          alternative = node.is_a?(Prism::IfNode) ? node.subsequent : node.else_clause
+          return false if node.statements.nil? || alternative.nil?
+
+          never_completes_normally?(node.statements, scope) && branch_never_completes?(alternative, scope)
+        end
+
+        def branch_never_completes?(branch, scope)
+          case branch
+          when Prism::ElseNode then never_completes_normally?(branch.statements, scope)
+          else never_completes_normally?(branch, scope)
+          end
+        end
+
+        def begin_never_completes?(node, scope)
+          return true if node.ensure_clause && never_completes_normally?(node.ensure_clause.statements, scope)
+          return false unless never_completes_normally?(node.statements, scope)
+
+          rescue_clause = node.rescue_clause
+          while rescue_clause
+            return false unless never_completes_normally?(rescue_clause.statements, scope)
+
+            rescue_clause = rescue_clause.subsequent
+          end
+          true
+        end
+
+        def project_redefines_root?(method_name, scope)
+          return true if scope.top_level_def_for(method_name)
+
+          patched = scope.environment&.project_patched_methods
+          PATCHABLE_ROOTS.any? do |root|
+            scope.discovered_method?(root, method_name, :instance) ||
+              patched&.lookup(class_name: root, method_name: method_name, kind: :instance)
+          end
+        end
+
+        # `[class_name, :instance | :singleton]` pairs the receiver can dispatch through, or nil when some
+        # part of it names no class. `Tuple` / `HashShape` project to `Array` / `Hash`, `Constant[v]` through
+        # the value's class, the same projection {ClosureEscapeAnalyzer} uses.
+        def receiver_targets(receiver_type)
+          case receiver_type
+          when Type::Union
+            members = receiver_type.members.map { |member| receiver_targets(member) }
+            members.any?(&:nil?) ? nil : members.flatten(1)
+          when Type::Nominal then [[receiver_type.class_name, :instance]]
+          when Type::Singleton then [[receiver_type.class_name, :singleton]]
+          when Type::Tuple then [["Array", :instance]]
+          when Type::HashShape then [["Hash", :instance]]
+          when Type::Constant then [[receiver_type.value.class.name, :instance]]
+          end
+        end
+
+        def resolves_to_catalogue?(class_name, kind, method_name, scope)
+          return false if class_name.nil?
+          return false if scope.discovered_method_through_ancestors?(class_name, method_name, kind)
+
+          if kind == :singleton
+            definition = Rigor::Reflection.singleton_method_definition(class_name, method_name, scope: scope)
+            return false if singleton_ancestor_patched?(class_name, method_name, scope)
+
+            return declared_on_catalogue?(definition, method_name)
+          end
+
+          definition = Rigor::Reflection.instance_method_definition(class_name, method_name, scope: scope)
+          if definition
+            return false if rbs_ancestor_patched?(class_name, method_name, scope)
+
+            return declared_on_catalogue?(definition, method_name)
+          end
+          return false if Rigor::Reflection.rbs_class_known?(class_name, scope: scope)
+
+          project_class_resolves_to_catalogue?(class_name, method_name, scope)
+        end
+
+        def declared_on_catalogue?(definition, method_name)
+          return false if definition.nil? || !definition.respond_to?(:defined_in)
+
+          exactly_once_owner?(definition.defined_in, method_name)
+        end
+
+        # A project class the RBS environment does not know: its project ancestry was already cleared by the
+        # discovery walk, so the answer rests on the ancestors it reaches OUTSIDE the project. Each is asked
+        # on its own terms; an ancestor nobody can resolve is uncertainty and declines. No external ancestor
+        # at all is the implicit `< Object`, which reaches `Kernel`.
+        def project_class_resolves_to_catalogue?(class_name, method_name, scope)
+          return false unless scope.known_user_class?(class_name)
+
+          scope.external_ancestor_name_candidates(class_name).all? do |candidates|
+            external_ancestor_resolves_to_catalogue?(candidates, method_name, scope)
+          end
+        end
+
+        def external_ancestor_resolves_to_catalogue?(candidates, method_name, scope)
+          known = candidates.find { |candidate| Rigor::Reflection.rbs_class_known?(candidate, scope: scope) }
+          return false if known.nil?
+
+          definition = Rigor::Reflection.instance_method_definition(known, method_name, scope: scope)
+          # A mixin whose RBS does not mention the method contributes nothing; a CLASS that lacks it is a
+          # `BasicObject` lineage, where the call does not reach `Kernel` at all.
+          return false if rbs_ancestor_patched?(known, method_name, scope)
+          return scope.environment.rbs_module?(known) if definition.nil?
+
+          declared_on_catalogue?(definition, method_name)
+        end
+
+        # The RBS declaration says where the method was DECLARED; a project reopening of a core ancestor
+        # (`module Enumerable; def tap = :x; end`) redefines it without touching RBS, and discovery records
+        # it under the ancestor's own name. So every RBS ancestor — mixins included — is asked.
+        def rbs_ancestor_patched?(class_name, method_name, scope)
+          names_patched?(rbs_ancestor_names(class_name, scope), method_name, :instance, scope)
+        end
+
+        # A class object dispatches through its own and its superclasses' singleton methods, then through
+        # `Class`, `Module`, `Object`, `Kernel` as instance methods.
+        def singleton_ancestor_patched?(class_name, method_name, scope)
+          names_patched?(rbs_ancestor_names(class_name, scope), method_name, :singleton, scope) ||
+            names_patched?(SINGLETON_ROOTS, method_name, :instance, scope)
+        end
+
+        def names_patched?(names, method_name, kind, scope)
+          patched = scope.environment&.project_patched_methods
+          names.any? do |name|
+            scope.discovered_method?(name, method_name, kind) ||
+              patched&.lookup(class_name: name, method_name: method_name, kind: kind)
+          end
+        end
+
+        def rbs_ancestor_names(class_name, scope)
+          loader = scope.environment&.rbs_loader
+          loader ? loader.ancestor_names_for(class_name.to_s) : []
+        end
+      end
+    end
+  end
+end