rigortype 0.4.4 → 0.4.6

data/lib/rigor/analysis/check_rules/ivar_write_collector.rb

@@ -3,6 +3,7 @@
 require "prism"
 
 require_relative "rule_walk"
+require_relative "../../scope/resolution_chain"
 require_relative "../../source/constant_path"
 require_relative "../../source/node_children"
 
@@ -37,36 +38,54 @@ module Rigor
         # `def` that sits directly in a class / module body, never one nested in another `def`. On the
         # shared full DFS that prune becomes the `:inside_def` gate; the enclosing class / module name stack
         # the legacy walk threaded as `qualified_prefix` is now `context.qualified_prefix`.
-        NODE_CLASSES = [Prism::DefNode].freeze
+        #
+        # ADR-125 — the walk also visits class-body `CallNode`s (a `def` body is gated off), to record the
+        # macro calls whose literal arguments name a method (`before_action :load_roles`).
+        NODE_CLASSES = [Prism::DefNode, Prism::CallNode].freeze
         RULE_WALK_GATES = %i[inside_def detached_ivar_facet].freeze
 
-        # Returns `Hash[class_name (String) => Hash[ivar_name (Symbol) => Array<{node:, type:, declared:}>]]`.
-        # Empty when the tree has no qualifying writes. `declared` is the translated type of the class's RBS
-        # declaration of the ivar — an `@x: T` member or the slot an `attr_*` member implies, own or
-        # inherited — and nil when the RBS declares none.
+        # Returns `Hash[class_name (String) => Hash[ivar_name (Symbol) => Array<{node:, type:, declared:,
+        # method_name:, visibility:, per_invocation:, action:}>]]`. Empty when the tree has no qualifying writes.
+        # `declared` is the translated type of the class's RBS declaration of the ivar — an `@x: T` member or
+        # the slot an `attr_*` member implies, own or inherited — and nil when the RBS declares none.
+        #
+        # ADR-125 — `method_name` is the enclosing `def`'s name and `visibility` its instance visibility
+        # (`:public` / `:protected` / `:private`, or nil when the discovery table has no settled answer).
+        # `per_invocation` is whether the class is, or descends from, a class a loaded plugin declares in
+        # `per_invocation_classes:`. `action` is whether the enclosing method is one of that class's entry
+        # points: public, and named by none of the declaring plugin's `per_invocation_non_action_macros:` in a
+        # class body of this file (`before_action :load_roles`, `helper_method :current_roles`).
         def initialize(scope_index)
           @scope_index = scope_index
           @accumulator = {}
+          @per_invocation = {}
+          @macro_arguments = {}
         end
 
         # Legacy single-collector walk — kept as the oracle the ADR-53 Track B equivalence harness compares
         # {RuleWalk} against; deleted when Track B completes.
         def collect(root)
           walk(root, [])
-          @accumulator.transform_values(&:freeze).freeze
+          results
         end
 
         # {RuleWalk} entry point: the legacy walk's per-`def` logic, invoked at each class-/module-body `def`
         # under the shared traversal contract. `collect_def_writes`' verbatim body reads the enclosing class
         # prefix from `context.qualified_prefix`.
-        def visit(def_node, context)
-          collect_def_writes(def_node, context.qualified_prefix)
+        def visit(node, context)
+          if node.is_a?(Prism::CallNode)
+            record_macro_call(node, context.qualified_prefix)
+          else
+            collect_def_writes(node, context.qualified_prefix)
+          end
         end
 
         # The accumulated result, frozen the same way `#collect` returns it — used by {RuleWalk}-driven
         # callers after the walk completes.
         def results
-          @accumulator.transform_values(&:freeze).freeze
+          @accumulator.to_h do |class_name, writes_by_ivar|
+            [class_name, writes_by_ivar.transform_values { |writes| with_actions(class_name, writes) }.freeze]
+          end.freeze
         end
 
         private
@@ -87,29 +106,71 @@ module Rigor
           when Prism::DefNode
             collect_def_writes(node, qualified_prefix)
             return
+          when Prism::CallNode
+            record_macro_call(node, qualified_prefix)
           end
 
           node.rigor_each_child { |child| walk(child, qualified_prefix) }
         end
 
+        # A receiverless (or `self.`) call in a class body, with the method names its literal Symbol / String
+        # arguments spell. Kept for every such call: which macro names count is the registry's answer, read
+        # once per class when the writes are finalised.
+        def record_macro_call(call_node, qualified_prefix)
+          return if qualified_prefix.empty?
+          return unless call_node.receiver.nil? || call_node.receiver.is_a?(Prism::SelfNode)
+
+          names = (call_node.arguments&.arguments || []).filter_map { |argument| literal_method_name(argument) }
+          return if names.empty?
+
+          ((@macro_arguments[qualified_prefix.join("::")] ||= {})[call_node.name] ||= []).concat(names)
+        end
+
+        # A Symbol / String literal's name, or the name of a `def` passed inline (`helper_method def
+        # current_user … end`). A literal with bytes no Symbol can hold (`before_action "\xff"`, #1821) names no
+        # method, so it answers nil.
+        def literal_method_name(argument)
+          return argument.name if argument.is_a?(Prism::DefNode) && argument.receiver.nil?
+          return nil unless argument.is_a?(Prism::SymbolNode) || argument.is_a?(Prism::StringNode)
+
+          text = argument.unescaped
+          text.valid_encoding? ? text.to_sym : nil
+        end
+
+        # Each write with `action` set (see {#initialize}). A frozen copy, so `#results` stays repeatable.
+        def with_actions(class_name, writes)
+          macros = @per_invocation[class_name]
+          excluded = macros ? non_action_names(class_name, macros) : nil
+          writes.map do |write|
+            action = !excluded.nil? && write[:visibility] == :public && !excluded.include?(write[:method_name])
+            write.merge(action: action).freeze
+          end.freeze
+        end
+
+        def non_action_names(class_name, macros)
+          (@macro_arguments[class_name] || {}).each_with_object(Set.new) do |(macro, names), set|
+            set.merge(names) if macros.include?(macro)
+          end
+        end
+
         def collect_def_writes(def_node, qualified_prefix)
           return if def_node.body.nil? || qualified_prefix.empty?
           return if def_node.receiver.is_a?(Prism::SelfNode)
 
           class_name = qualified_prefix.join("::")
-          gather_writes(def_node.body, class_name)
+          gather_writes(def_node.body, class_name, def_node.name)
         end
 
-        def gather_writes(node, class_name)
+        def gather_writes(node, class_name, method_name)
           return unless node.is_a?(Prism::Node)
 
-          record_write(node, class_name) if node.is_a?(Prism::InstanceVariableWriteNode)
+          record_write(node, class_name, method_name) if node.is_a?(Prism::InstanceVariableWriteNode)
           return if BARRIER_NODES.any? { |klass| node.is_a?(klass) }
 
-          node.rigor_each_child { |child| gather_writes(child, class_name) }
+          node.rigor_each_child { |child| gather_writes(child, class_name, method_name) }
         end
 
-        def record_write(node, class_name)
+        def record_write(node, class_name, method_name)
           scope = @scope_index[node]
           return if scope.nil?
 
@@ -117,7 +178,73 @@ module Rigor
           declared = declared_ivar(scope, class_name, node.name)
           @accumulator[class_name] ||= {}
           @accumulator[class_name][node.name] ||= []
-          @accumulator[class_name][node.name] << { node: node, type: rvalue_type, declared: declared }
+          @accumulator[class_name][node.name] << {
+            node: node, type: rvalue_type, declared: declared, method_name: method_name,
+            visibility: method_visibility(scope, class_name, method_name),
+            per_invocation: !per_invocation_macros(scope, class_name).nil?
+          }
+        end
+
+        # The enclosing `def`'s instance visibility, or nil when it is not a settled fact: a slot the
+        # discovery table does not hold, or one a later `define_method` / alias / unplaceable write contests
+        # (#2013). `initialize` and the other lifecycle hooks are private whatever the table says.
+        def method_visibility(scope, class_name, method_name)
+          return :private if CheckRules::IMPLICITLY_PRIVATE_METHODS.include?(method_name)
+          return nil if scope.discovery.contested?(:discovered_method_visibilities, [class_name, method_name])
+
+          scope.discovered_method_visibility(class_name, method_name)
+        end
+
+        # ADR-125 — when `class_name` is, or descends from, a class a loaded plugin declares per-invocation, the
+        # non-action macros its declaring manifests list (a Set, possibly empty); nil otherwise. Read off the
+        # class's instance {Scope::ResolutionChain}, so a project superclass chain
+        # (`UsersController < ApplicationController < ActionController::Base`) is followed as Ruby resolves it.
+        # A project entry matches by name. An external superclass matches through the first of its candidate
+        # spellings the environment knows, by name or by an RBS-known `:equal` / `:subclass` ordering. When the
+        # environment knows none of them (rigor-actionpack leaves `ActionController::Base` undeclared on
+        # purpose), a candidate that is literally a declared name matches, unless some candidate names a class
+        # the project itself declares: then the spelling may resolve there instead. An ambiguous spelling (no
+        # candidates) and a truncated chain answer nil: the carve-out only ever withholds a finding, so an
+        # unproved descent keeps the rule firing. Memoised per class.
+        def per_invocation_macros(scope, class_name)
+          return @per_invocation[class_name] if @per_invocation.key?(class_name)
+
+          @per_invocation[class_name] = matched_per_invocation_macros(scope, class_name)
+        end
+
+        def matched_per_invocation_macros(scope, class_name)
+          environment = scope.environment
+          registry = environment&.plugin_registry
+          return nil if registry.nil? || registry.per_invocation_classes.empty?
+
+          chain = Scope::ResolutionChain.for(scope, class_name, :instance, :methods)
+          return nil if chain.truncated?
+
+          declared = chain.search(scope) { |entry| matched_declarations(entry, registry, scope) }
+          declared&.each_with_object(Set.new) { |name, set| set.merge(registry.per_invocation_non_action_macros(name)) }
+        end
+
+        # The declared per-invocation names `entry` matches, or nil (so {ResolutionChain#search} moves on).
+        def matched_declarations(entry, registry, scope)
+          return (registry.per_invocation_class?(entry.name.to_s) ? [entry.name.to_s] : nil) unless entry.external?
+          return nil unless entry.superclass_edge
+
+          environment = scope.environment
+          names = entry.candidates.map { |name| name.to_s.delete_prefix("::") }
+          known = names.find { |name| environment.class_known?(name) }
+          return literal_declarations(names, registry, scope) if known.nil?
+
+          matched = registry.per_invocation_classes.select do |declared|
+            %i[equal subclass].include?(environment.class_ordering(known, declared))
+          end
+          matched.empty? ? nil : matched
+        end
+
+        def literal_declarations(names, registry, scope)
+          return nil if names.any? { |name| scope.discovered_classes.key?(name) }
+
+          matched = names.select { |name| registry.per_invocation_class?(name) }
+          matched.empty? ? nil : matched
         end
 
         def declared_ivar(scope, class_name, ivar_name)

data/lib/rigor/analysis/check_rules/lexical_method_sites.rb

@@ -4,6 +4,7 @@ require "prism"
 
 require_relative "../../inference/scope_indexer"
 require_relative "../../source/node_children"
+require_relative "rebinding_block_callees"
 
 module Rigor
   module Analysis
@@ -17,6 +18,13 @@ module Rigor
       # - **Singleton defs on locals.** `def o.m` defines `m` on the one object `o` holds. The local's type
       #   is not changed; `o.m` is simply not reported within the scope the `def` is written in (the
       #   enclosing `def`, `class` / `module` body, or file — a block shares its enclosing scope's locals).
+      #   Issue #1722 — the other spellings that give that one object methods make the local opaque for every
+      #   name in the same scope: `o.extend(M)`, `o.define_singleton_method(...)` (only the literal name it
+      #   defines, when it names one), any call on `o.singleton_class` (`class_eval { def m }`, `define_method`,
+      #   `include`), `class << o`, and an `o.instance_eval` / `o.instance_exec` that is given a String or whose
+      #   block writes a `def` or calls `extend` / `define_singleton_method`. Where in the scope the call sits,
+      #   and whether it runs, are not read: a call under an `if` may run. A local assigned `o.clone` shares
+      #   what `o` has (`clone` copies the singleton class, `dup` does not).
       #
       # Built lazily: the walk runs the first time a would-fire call asks, so a file with no such call pays
       # one small object and nothing else.
@@ -34,22 +42,48 @@ module Rigor
 
         def refinements = (@refinements ||= Inference::InEffectRefinements.new(@root))
 
-        # Does a `def <local>.<name>` for this call's local receiver and method name sit in the scope the call
-        # is in?
+        # Issue #1817 — the file's block-passing calls, for `call.unresolved-toplevel`'s rebinding-callee decline.
+        def block_calls = (@block_calls ||= RebindingBlockCallees::Sites.new(@root))
+
+        # Does a `def <local>.<name>` for this call's local receiver and method name — or a call that gives the
+        # local's object methods Rigor does not enumerate (issue #1722) — sit in the scope the call is in?
         def singleton_local_def?(call_node)
           receiver = call_node.receiver
           return false unless receiver.is_a?(Prism::LocalVariableReadNode)
 
           build
-          offset = call_node.location.start_offset
-          @singleton_defs.any? do |local, method_name, start, stop|
-            local == receiver.name && method_name == call_node.name && offset >= start && offset < stop &&
-              !nested_scope_holds?(offset, start, stop)
-          end
+          singleton_local_holds?(receiver.name, call_node.name, call_node.location.start_offset, CLONE_DEPTH)
         end
 
+        # The name an opening records when it may define any method on the local's object.
+        ANY_METHOD = Object.new.freeze
+        # How many `t = s.clone` links a lookup follows.
+        CLONE_DEPTH = 4
+        EVAL_CALLS = %i[instance_eval instance_exec].freeze
+        EVAL_BLOCK_CALLS = %i[extend define_singleton_method].freeze
+        private_constant :ANY_METHOD, :CLONE_DEPTH, :EVAL_CALLS, :EVAL_BLOCK_CALLS
+
         private
 
+        def singleton_local_holds?(local_name, method_name, offset, depth)
+          opened = in_scope?(@singleton_defs, offset) do |local, name|
+            local == local_name && (name.equal?(ANY_METHOD) || name == method_name)
+          end
+          return true if opened
+          return false if depth.zero?
+
+          @clones.any? do |target, source, start, stop|
+            target == local_name && offset >= start && offset < stop && !nested_scope_holds?(offset, start, stop) &&
+              singleton_local_holds?(source, method_name, offset, depth - 1)
+          end
+        end
+
+        def in_scope?(rows, offset)
+          rows.any? do |local, name, start, stop|
+            yield(local, name) && offset >= start && offset < stop && !nested_scope_holds?(offset, start, stop)
+          end
+        end
+
         # Is `offset` inside a local scope nested in the one `[start, stop)` spans? A `def` in the file's top level
         # does not see the top level's `o`.
         def nested_scope_holds?(offset, start, stop)
@@ -64,6 +98,7 @@ module Rigor
 
           @built = true
           @singleton_defs = []
+          @clones = []
           @scopes = []
           return if @root.nil?
 
@@ -78,11 +113,16 @@ module Rigor
           when Prism::ClassNode, Prism::ModuleNode
             return walk_children(node.body, scope_span(node))
           when Prism::SingletonClassNode
+            record_opened_local(node.expression, ANY_METHOD, locals)
             walk(node.expression, locals)
             return walk_children(node.body, scope_span(node))
           when Prism::DefNode
             record_singleton_def(node, locals)
             return walk_children(node.body, scope_span(node))
+          when Prism::CallNode
+            record_singleton_opening(node, locals)
+          when Prism::LocalVariableWriteNode
+            record_clone(node, locals)
           end
 
           walk_children(node, locals)
@@ -101,6 +141,74 @@ module Rigor
           @singleton_defs << [receiver.name, node.name, *locals]
         end
 
+        # Issue #1722 — a call that gives the object its receiver local holds singleton methods.
+        def record_singleton_opening(node, locals)
+          receiver = node.receiver
+          if singleton_class_of_local?(receiver)
+            record_opened_local(receiver.receiver, ANY_METHOD, locals)
+          elsif receiver.is_a?(Prism::LocalVariableReadNode)
+            name = opened_method_name(node)
+            record_opened_local(receiver, name, locals) if name
+          end
+        end
+
+        # `o.singleton_class`.
+        def singleton_class_of_local?(node)
+          node.is_a?(Prism::CallNode) && node.name == :singleton_class && node.arguments.nil? &&
+            node.receiver.is_a?(Prism::LocalVariableReadNode)
+        end
+
+        # The method name a call on a local defines on the local's object: the literal name given to
+        # `define_singleton_method`, {ANY_METHOD} where it may be any name, or nil when the call defines none.
+        def opened_method_name(node)
+          case node.name
+          when :extend then ANY_METHOD
+          when :define_singleton_method then literal_name(node.arguments&.arguments&.first) || ANY_METHOD
+          when *EVAL_CALLS then ANY_METHOD if eval_defines?(node)
+          end
+        end
+
+        def literal_name(node)
+          node.unescaped.to_sym if node.is_a?(Prism::SymbolNode) || node.is_a?(Prism::StringNode)
+        end
+
+        # An `instance_eval` given code as a String, or whose block writes a `def` or calls `extend` /
+        # `define_singleton_method` on its `self`.
+        def eval_defines?(node)
+          return true unless node.arguments.nil?
+
+          block = node.block
+          block.is_a?(Prism::BlockNode) && defines_on_self?(block.body)
+        end
+
+        def defines_on_self?(node)
+          return false if node.nil?
+          return true if node.is_a?(Prism::DefNode)
+          if node.is_a?(Prism::CallNode) && EVAL_BLOCK_CALLS.include?(node.name) &&
+             (node.receiver.nil? || node.receiver.is_a?(Prism::SelfNode))
+            return true
+          end
+
+          found = false
+          node.rigor_each_child { |child| found ||= defines_on_self?(child) }
+          found
+        end
+
+        def record_opened_local(node, method_name, locals)
+          return unless node.is_a?(Prism::LocalVariableReadNode)
+
+          @singleton_defs << [node.name, method_name, *locals]
+        end
+
+        # `t = s.clone`: `clone` copies the singleton class, so `t` holds what `s` was given.
+        def record_clone(node, locals)
+          value = node.value
+          return unless value.is_a?(Prism::CallNode) && value.name == :clone
+          return unless value.receiver.is_a?(Prism::LocalVariableReadNode)
+
+          @clones << [node.name, value.receiver.name, *locals]
+        end
+
         # The span of a node that opens a local scope, recorded for {#nested_scope_holds?}.
         def scope_span(node)
           span = span_of(node)

data/lib/rigor/analysis/check_rules/rbs_receiver_surface.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require_relative "../../reflection"
+require_relative "../dependency_recorder"
+require_relative "../../inference/singleton_hook_decline"
+require_relative "../../inference/object_mixins"
+
+module Rigor
+  module Analysis
+    module CheckRules
+      # Issue #1722 — what the project may give an instance of an RBS-declared class beyond the class's RBS, asked
+      # by `call.undefined-method` once the RBS lookup and the project's own tables for the class itself have come
+      # back "absent". Three places the earlier probes do not look:
+      #
+      # - **A `method_missing` on an RBS ancestor.** `class Integer; def method_missing(*)` (or one on `Numeric`,
+      #   `Comparable`, `Object`, `Kernel`, `BasicObject`, or a project module mixed into any of them) answers
+      #   every name Ruby dispatches to an Integer. `respond_to_missing?` is not read: Ruby dispatches to
+      #   `method_missing` whether or not it is defined.
+      # - **A project mixin of the class or an RBS ancestor.** `Integer.include(Ext)` in another file, or
+      #   `Comparable.include(Ext)` / `module Comparable; def zzz`, gives every Integer `zzz`. The earlier probes
+      #   read the class's own chain through `discovered_methods`, which holds no plain `def` written in another
+      #   file than the one being checked; this reads the def table too for a project module, and walks the
+      #   ancestors RBS lists after the class. A cross-file `def` on an RBS-declared class or module itself stays
+      #   ADR-17's monkey-patch report ({.mixin_defines?}). A mixin with an open surface — a project module with a
+      #   recorded `included` / `extended` / … hook, a `"*"` mixin or `ActiveSupport::Concern`, or one neither RBS nor
+      #   the project declares — answers any name, except on `Object`, `Kernel` and `BasicObject`: there only a
+      #   module that defines the name answers, #1697's reading (`Inference::ObjectMixins`) of a module mixed into
+      #   every object.
+      # - **A project subclass** ({.subclass_may_define?}). A value typed by its class's name through a signature
+      #   (`#: () -> String`) may be an instance of any subclass, so a method a project subclass defines may be
+      #   the one that runs.
+      #
+      # Each ancestor's name is filed as an ADR-46 class dependency, so a file that later reopens one re-checks
+      # the call, and the subclass walk files a `subclass_of` edge per class it reads.
+      module RbsReceiverSurface
+        MISSING_HOOK = :method_missing
+        # The roots whose project mixins `Inference::ObjectMixins` answers for.
+        OBJECT_ROOTS = %w[Object Kernel BasicObject].to_set.freeze
+        private_constant :MISSING_HOOK, :OBJECT_ROOTS
+
+        module_function
+
+        # Whether the project may answer `method_name` on an instance of `class_name` through one of its RBS
+        # ancestors.
+        def ancestor_may_answer?(scope, class_name, method_name)
+          ancestor_names(scope, class_name).any? do |name|
+            DependencyRecorder.read_last_segment(:class, name) if DependencyRecorder.active?
+            next false unless scope.known_user_class?(name)
+
+            chain_answers?(scope, name, method_name, open_mixins: !OBJECT_ROOTS.include?(name))
+          end
+        end
+
+        # Whether the singleton side of `class_name` may reach a project `method_missing`: a `def self.method_missing`
+        # on the class or an RBS superclass, or an instance `method_missing` on `Class`, `Module`, `Object`,
+        # `Kernel` or `BasicObject` (a class object is an instance of each).
+        def singleton_hook?(scope, class_name)
+          loader = scope.environment&.rbs_loader
+          pairs = loader ? loader.singleton_ancestors_for(class_name.to_s) : []
+          pairs = [[:singleton, class_name.to_s]] if pairs.empty?
+          pairs.any? do |kind, name|
+            DependencyRecorder.read_last_segment(:class, name) if DependencyRecorder.active?
+            if kind == :singleton
+              !scope.singleton_def_for(name, MISSING_HOOK).nil? ||
+                scope.discovered_method?(name, MISSING_HOOK, :singleton)
+            else
+              scope.known_user_class?(name) && hook_on_chain?(scope, name)
+            end
+          end
+        end
+
+        # Issue #2094 — the singleton side's twin of {.ancestor_may_answer?}: a module the class or an RBS superclass
+        # `extend`s (in its body, as `Float.extend(Ext)`, or as `Float.singleton_class.include(Ext)`) may answer
+        # `method_name` on the class object, read as {.mixin_defines?} / {.external_may_answer?} read an instance-side
+        # mixin. Only each level's own singleton segment is read: the class's further singleton ancestors are the
+        # RBS superclasses this walk visits in turn, and `Class` / `Module` are {.singleton_hook?}'s.
+        def singleton_mixin_may_answer?(scope, class_name, method_name)
+          singleton_class_names(scope, class_name).any? do |name|
+            DependencyRecorder.read_last_segment(:class, name) if DependencyRecorder.active?
+
+            extends_answer?(scope, name, method_name, open_mixins: !OBJECT_ROOTS.include?(name))
+          end
+        end
+
+        def singleton_class_names(scope, class_name)
+          loader = scope.environment&.rbs_loader
+          pairs = loader ? loader.singleton_ancestors_for(class_name.to_s) : []
+          names = pairs.filter_map { |kind, name| name if kind == :singleton }
+          names.empty? ? [class_name.to_s] : names
+        end
+
+        def extends_answer?(scope, name, method_name, open_mixins:)
+          chain = Scope::ResolutionChain.for(scope, name, :singleton, :methods)
+          return true if chain.truncated?
+          # A mixin call the indexer could not record (`Integer.extend(m)`, `Symbol.singleton_class.send(:include,
+          # M)`) leaves the side tainted: some module the tables do not name may answer any name.
+          return true if open_mixins && chain.wildcard_mixin?
+
+          entries = chain.level_count.zero? ? chain.entries : chain.level_entries(0)
+          entries.any? do |entry|
+            if entry.external?
+              external_may_answer?(scope, entry, method_name, open_mixins)
+            else
+              entry.name != name && mixin_defines?(scope, entry, method_name, open_mixins)
+            end
+          end
+        end
+
+        # Whether a project subclass of `class_name`, at any depth, defines `method_name` (through its own
+        # ancestry, which reaches its project mixins) or a `method_missing`. Its parent is read as written and
+        # resolved the way the class header resolves it: the first project class the spelling can denote, else the
+        # top-level name, which is the RBS class.
+        def subclass_may_define?(scope, class_name, method_name)
+          each_subclass(scope, class_name.to_s) do |subclass|
+            return true if project_defines?(scope, subclass, method_name) ||
+                           project_defines?(scope, subclass, MISSING_HOOK) ||
+                           !scope.user_def_through_ancestors(subclass, method_name).first.nil? ||
+                           scope.discovered_method_through_ancestors?(subclass, method_name, :instance)
+          end
+          false
+        end
+
+        def ancestor_names(scope, class_name)
+          loader = scope.environment&.rbs_loader
+          names = loader ? loader.ancestor_names_for(class_name.to_s) : []
+          names.empty? ? [class_name.to_s] : names
+        end
+
+        # A search of `name`'s project chain for an entry that may answer: a project entry that defines
+        # `method_name` or a `method_missing`, or an external mixin RBS declares `method_name` on. When
+        # `open_mixins` (every ancestor but `Object`, `Kernel` and `BasicObject`, #1697), also a mixin whose surface
+        # is open: a project module SingletonHookDecline reads as hook-capable, or an external neither RBS nor the
+        # project declares. A chain cut at its budget may hold an answer past the cut.
+        def chain_answers?(scope, name, method_name, open_mixins:)
+          chain = Scope::ResolutionChain.for(scope, name, :instance, :methods)
+          found = chain.search(scope, side: :instance) do |entry|
+            if entry.external?
+              external_may_answer?(scope, entry, method_name, open_mixins)
+            else
+              project_defines?(scope, entry.name, MISSING_HOOK) ||
+                mixin_defines?(scope, entry, method_name, open_mixins)
+            end
+          end
+          found || chain.truncated?
+        end
+
+        # The singleton side's question of an instance chain: does a project entry on it define `method_missing`?
+        def hook_on_chain?(scope, name)
+          chain = Scope::ResolutionChain.for(scope, name, :instance, :methods)
+          found = chain.search(scope, side: :instance) do |entry|
+            !entry.external? && project_defines?(scope, entry.name, MISSING_HOOK)
+          end
+          found || chain.truncated?
+        end
+
+        def project_defines?(scope, owner, method_name)
+          !scope.user_def_for(owner, method_name).nil? || scope.discovered_method?(owner, method_name, :instance)
+        end
+
+        # ADR-17 — a `def` the project writes on a class or module RBS declares (`class String; def x`, `module
+        # Comparable; def x`) in another file than the call is a monkey-patch Rigor does not apply cross-file, and the
+        # rule reports it with the `pre_eval:` advice, so on such an entry only what `discovered_methods` carries
+        # answers. A project module's own `def` answers from any file.
+        #
+        # When `open_mixins`, a project module {Inference::SingletonHookDecline} reads as hook-capable — one that
+        # records an `included` / `extended` / … hook (`def self.included(base) = base.class_eval { def x }`), lists
+        # a `"*"` mixin, or extends `ActiveSupport::Concern` — may answer any name.
+        def mixin_defines?(scope, entry, method_name, open_mixins)
+          owner = entry.name
+          if Rigor::Reflection.rbs_class_known?(owner, scope: scope)
+            scope.discovered_method?(owner, method_name, :instance)
+          else
+            project_defines?(scope, owner, method_name) || macro_names?(scope, owner, method_name) ||
+              (open_mixins && (Inference::SingletonHookDecline.entry_hook_capable?(scope, entry) ||
+                               open_extend?(scope, owner)))
+          end
+        end
+
+        # Issue #2094 — a class-body macro of the module names the method ({Inference::ObjectMixins.macro_named?}).
+        # Answers the named method only, so it holds on `Object`, `Kernel` and `BasicObject` too, where a module
+        # that defines the name answers.
+        def macro_names?(scope, owner, method_name)
+          Inference::ObjectMixins.macro_named?(scope, owner, method_name)
+        end
+
+        # Issue #2094 — the module `extend`s a module whose surface is open: one neither RBS nor the project declares
+        # (a gem's DSL with no signatures), or a project module {Inference::SingletonHookDecline} reads as
+        # hook-capable. Any macro the module's body calls may come from it and define any name, and its `extended`
+        # hook may too, so the module answers any name, the reading an undeclared `include` already gets. A chain cut
+        # at its budget may hold such a module past the cut.
+        def open_extend?(scope, owner)
+          chain = Scope::ResolutionChain.for(scope, owner, :singleton, :methods)
+          return true if chain.truncated?
+
+          entries = chain.level_count.zero? ? chain.entries : chain.level_entries(0)
+          entries.any? { |extended| Inference::SingletonHookDecline.entry_hook_capable?(scope, extended) }
+        end
+
+        # An external the project declares (a module with no `def`, which the chain does not hold as a project entry)
+        # is known, and answers through RBS, or through what its own body's macros and `extend`s may define (issue
+        # #2094: {.macro_names?} and {.open_extend?}, asked of each candidate the project declares).
+        def external_may_answer?(scope, entry, method_name, open_mixins)
+          candidates = entry.candidates
+          return open_mixins if candidates.empty?
+          return true if candidates.any? do |candidate|
+            Rigor::Reflection.instance_method_definition(candidate, method_name, scope: scope)
+          end
+          return true if candidates.any? do |candidate|
+            macro_names?(scope, candidate, method_name) || (open_mixins && open_extend?(scope, candidate))
+          end
+
+          open_mixins && candidates.none? { |candidate| declared?(scope, candidate) }
+        end
+
+        def declared?(scope, name)
+          scope.discovered_classes.key?(name) || Rigor::Reflection.rbs_class_known?(name, scope: scope)
+        end
+
+        def each_subclass(scope, class_name)
+          children = children_by_parent(scope)
+          queue = children.fetch(class_name, []).dup
+          seen = {}
+          record_subclasses_read(class_name)
+          until queue.empty?
+            subclass = queue.shift
+            next if seen[subclass]
+
+            seen[subclass] = true
+            record_subclasses_read(subclass)
+            yield subclass
+            queue.concat(children.fetch(subclass, []))
+          end
+        end
+
+        def children_by_parent(scope)
+          scope.discovered_superclasses.each_with_object({}) do |(child, raw_parent), children|
+            next if raw_parent.nil?
+
+            candidates = scope.ancestor_name_candidates(child, raw_parent.to_s)
+            parent = candidates.find { |name| scope.known_user_class?(name) } || candidates.last
+            (children[parent] ||= []) << child if parent
+          end
+        end
+
+        def record_subclasses_read(class_name)
+          return unless DependencyRecorder.active?
+
+          DependencyRecorder.read_last_segment(:subclass_of, class_name)
+        end
+      end
+    end
+  end
+end