rigortype 0.4.4 → 0.4.5

data/docs/manual/plugins/rigor-rspec.md

@@ -5,7 +5,9 @@ Validates RSpec `let` / `subject` declarations within each
 checks it ships have the lowest false-positive risk of the
 proposed RSpec surface, run in pure syntactic-walk mode, and
 catch real bugs that `rspec` / `rubocop-rspec` don't always
-surface clearly. No RSpec runtime dependency.
+surface clearly. It also narrows a local through `expect(x).to`
+matchers, described under [Matcher narrowing](#matcher-narrowing).
+No RSpec runtime dependency.
 
 It ships bundled in `rigortype`. Activate it under `plugins:`:
 
@@ -50,6 +52,104 @@ The walker recognises `RSpec.describe … do` (root), nested
 `describe` / `context … do`, `let(:name)` / `let!(:name)`, and
 `subject(:name)` / bare `subject` (the implicit `:subject`).
 
+## Matcher narrowing
+
+`expect(x).to MATCHER` narrows the local `x` for the rest of the
+example body, so downstream calls resolve against the matched type.
+Only a plain local is a target.
+
+```ruby
+RSpec.describe "Counter" do
+  it "narrows through the matcher" do
+    count = rand(10) if rand(2).zero?  # count is Integer?
+    expect(count).to eq(42)            # count is 42 from here on
+    count + 1                          # no possible-nil-receiver warning
+  end
+end
+```
+
+| Matcher | Effect on `x` |
+| --- | --- |
+| `eq(literal)` / `eql(literal)` | meet with `Constant<literal>` (see below) |
+| `be_a(T)` / `be_kind_of(T)` / `be_instance_of(T)` / `be_an_instance_of(T)` | meet with `T` |
+| `be_nil` | narrow to `Constant<nil>` |
+| `match(/regex/)` | narrow to `String` |
+| `not_to be_nil` / `to_not be_nil` | narrow away from `nil` |
+| `not_to be_a(T)` / `not_to be_kind_of(T)` / `not_to be_instance_of(T)` / `not_to be_an_instance_of(T)` | narrow away from `T` |
+| `not_to eq(literal)` / `not_to eql(literal)` (and `to_not`) | unchanged (see below) |
+
+Other matchers emit nothing. `be_truthy` is not narrowed, nor is
+`expect { ... }.to raise_error(...)` (the block form), nor an
+`expect(foo.bar)` whose argument is not a local.
+
+### Equality is a meet, not a replacement
+
+`eq(literal)` passes when `x == literal`, and `eql(literal)` when
+`x.eql?(literal)`. The local is the receiver, so `x`'s own operator
+decides, and that operator can hold across classes: `1 == 1.0`, and a
+class with its own `==` (a `ModInt` that compares `to_i`) passes
+`expect(m).to eq(9)`. The matcher therefore never replaces `x`'s
+type. It narrows each member of `x`'s type on its own.
+
+The core equality classes are the nine in `EQUALITY_CORE_CLASSES`
+(`plugins/rigor-rspec/lib/rigor/plugin/rspec/matcher_analyzer.rb`):
+`Integer`, `Float`, `Rational`, `Complex`, `String`, `Symbol`,
+`NilClass`, `TrueClass`, and `FalseClass`. The first four are the
+numeric classes.
+
+- a member of the literal's own class narrows to the literal,
+  refinements of that class included. After `x = rand(10)`,
+  `expect(x).to eq(9)` gives `9`; `Integer?` with `eq(9)` gives `9`,
+  because the `nil` member cannot equal `9`. A refinement such as
+  `decimal-int-string?` (from `y = x && x.to_s` with `x` an
+  `Integer?`) gives `"3"` under `eq("3")`. A `Constant` member is kept
+  when it equals the literal and dropped otherwise;
+- a `Float` member meets `0.0` and is kept, since `-0.0` also equals
+  it;
+- a numeric member of another class (`Integer`, `Float`, `Rational`,
+  `Complex`) is kept under `eq`: `Integer | Float` with `eq(1)` gives
+  `1 | Float`;
+- any other member of a core equality class is dropped:
+  `String | Integer` with `eq(9)` gives `9`;
+- `eql(literal)` takes the same path, except that a numeric member of
+  another class is dropped, because `eql?` compares classes:
+  `Integer | Float` with `eql(1)` gives `1`.
+
+### A member, or the whole local, keeps its type in these cases
+
+A member outside the core equality classes makes the whole fact
+unavailable, so the local keeps its type, not just that member:
+
+- a member is `Dynamic`, or of a class outside `EQUALITY_CORE_CLASSES`,
+  such as a user class (`ModInt`), `Numeric`, or a generic `Array` or
+  `Hash`. Under `eq(9)` the whole local stays unchanged, so `9 | [1]`
+  and `9 | { a: 1 }` do not narrow;
+- the project defines the operator (`==` for `eq`, `eql?` for `eql`)
+  on the literal's class, in any analysed file. A `def` or a
+  `define_method` both count. A core `==` can call back into the
+  literal's own `==` (`Integer#==` for a non-numeric argument,
+  `String#==` for one that responds to `to_str`), so the plugin does
+  not narrow there even when a kept member would survive;
+- the project reopens a core ancestor of the member's class and
+  defines the operator there, such as `class Numeric; def eql?` or
+  `class Object; def ==`. Under `eql(9)` an `Integer` stays
+  `Integer`; under `eq(9)` the `nil` member of `Integer?` stays `nil`
+  while the `Integer` member narrows (`9?`);
+- the literal is `nil`, `true`, or a Symbol, and a member is a user
+  class or `Dynamic`: the local's own `==` can match these literals
+  too, so the local keeps its type as it does for `9`;
+- the local is unbound, no scope is available, or no member survives
+  the match (`nil` with `eq(9)`).
+
+A reopening that defines only other methods, such as
+`class String; def shout`, does not count: `String?` with
+`eq("a")` still narrows to `"a"`. A `class Symbol; def ==` in the
+project keeps the `Symbol` member and narrows the rest:
+`Symbol | Integer | nil` with `eq(9)` gives `9 | Symbol`.
+
+`not_to eq(literal)`, `to_not eq(literal)`, and their `eql` forms do
+not narrow: `x` keeps the type it had before the matcher.
+
 ## Configuration
 
 No configuration knobs. The plugin walks every file on the

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

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../../inference/narrowing"
+require_relative "../../environment/member_consistency"
+
+module Rigor
+  module Analysis
+    module CheckRules
+      # Issue #1485 — whether a `case` clause the engine reads as exhausted by the earlier clauses (`:prior_exhaustion`
+      # in {UnreachableClauseCollector}) is dead whatever the subject holds. The engine's `Bot` says only that the
+      # earlier clauses covered every member of the subject's type, and a type Rigor inferred or read from a signature
+      # may be narrower than what the program holds: `STDOUT` is typed `IO`, a test passes a `StringIO`, which is not an
+      # `IO`, and `case io when IO … when StringIO` runs the second arm.
+      #
+      # So the verdict stands when the subject entering the `case` is made only of carriers that record what the file
+      # literally shows (`x = 1; case x when Integer … when String`), or when every class the clause names is at or
+      # below a class an earlier clause names (`when IO … when File`, `when Enumerable … when Array`, a repeated
+      # `when IO`): any object the clause could match then matches the earlier clause first. The ancestry is RBS's, or
+      # the project's own superclass and mixin edges, never past a class whose RBS ancestry Ruby contradicts
+      # (`Tempfile`, `< File` in RBS and `< Delegator` in Ruby). A clause that is not a class test (`in [a]`) names no
+      # class, so on a non-literal subject it is never proven.
+      #
+      # The proof assumes `when Base` matches every instance of a class below `Base`, as `Module#===` does. A class that
+      # defines its own `self.===` could break that; no such case has been observed.
+      class ClauseCoverage
+        # The carriers issue #1429 counts as literal, plus the value-pinned `nil`, `true` and `false`, whose `Nominal`
+        # is the single value itself.
+        LITERAL_CARRIERS = [Type::Constant, Type::Tuple, Type::HashShape, Type::Singleton].freeze
+        VALUE_PINNED_CLASSES = %w[NilClass TrueClass FalseClass].freeze
+
+        UNRELIABLE_ANCESTRY = Environment::MemberConsistency::RbsProof::UNRELIABLE_ANCESTRY
+
+        # @param scope — the `case` node's scope, which resolves the clauses' class constants.
+        # @param subject_type — the subject's type entering the `case`.
+        def initialize(scope, subject_type)
+          @scope = scope
+          @literal_subject = literal?(subject_type)
+          @earlier = []
+        end
+
+        # Adds the classes `clause` matches by class alone to those a later clause may be covered by: each class
+        # condition of a `when` (`when IO, nil` still matches every `IO` first), and the bare class pattern of an `in`.
+        def record(clause)
+          return if @scope.nil?
+
+          parts = clause.is_a?(Prism::WhenNode) ? clause.conditions : (pattern_alternatives(clause.pattern) || [])
+          @earlier.concat(parts.filter_map { |part| class_name(part) })
+        end
+
+        # True when the `:prior_exhaustion` verdict on `clause` may stand.
+        def proven?(clause)
+          return true if @literal_subject
+          return false if @scope.nil?
+
+          names = clause_class_names(clause)
+          return false if names.nil?
+
+          names.all? do |name|
+            ancestors = ancestor_names(name)
+            !ancestors.nil? && @earlier.any? { |earlier| ancestors.any? { |ancestor| covered_by?(ancestor, earlier) } }
+          end
+        end
+
+        private
+
+        def literal?(type)
+          members = type.is_a?(Type::Union) ? type.members : [type]
+          members.all? do |member|
+            LITERAL_CARRIERS.any? { |carrier| member.is_a?(carrier) } ||
+              (member.is_a?(Type::Nominal) && VALUE_PINNED_CLASSES.include?(member.class_name))
+          end
+        end
+
+        # The class names `clause` matches by class alone, or nil when any part of it is something else: every
+        # condition of a `when`, and the bare class pattern of an `in` (`in C`, `in C => x`, `in A | B`).
+        def clause_class_names(clause)
+          parts = clause.is_a?(Prism::WhenNode) ? clause.conditions : pattern_alternatives(clause.pattern)
+          return nil if parts.nil? || parts.empty?
+
+          names = parts.map { |part| class_name(part) }
+          names.include?(nil) ? nil : names
+        end
+
+        def class_name(node)
+          return nil unless node.is_a?(Prism::ConstantReadNode) || node.is_a?(Prism::ConstantPathNode)
+
+          Inference::Narrowing.lexical_class_name(node, @scope)
+        end
+
+        def pattern_alternatives(pattern)
+          case pattern
+          when Prism::CapturePatternNode then pattern_alternatives(pattern.value)
+          when Prism::AlternationPatternNode
+            left = pattern_alternatives(pattern.left)
+            right = pattern_alternatives(pattern.right)
+            left && right && (left + right)
+          when Prism::ConstantReadNode, Prism::ConstantPathNode then [pattern]
+          end
+        end
+
+        # `name` and the ancestors the project gives it: the project classes and modules on its chain, and the first
+        # candidate the environment knows of each ancestor the project does not declare (`< StandardError`,
+        # `include Enumerable`). Nil when the chain was cut, so no coverage rests on part of it.
+        def ancestor_names(name)
+          return [name] unless @scope.known_user_class?(name)
+
+          external = @scope.external_ancestor_name_candidates(name).map do |candidates|
+            candidates.find { |candidate| Reflection.class_known?(candidate, scope: @scope) }
+          end
+          chain = Scope::ResolutionChain.for(@scope, name, :instance, :methods)
+          return nil if chain.truncated?
+
+          ([name] + chain.entries.reject(&:external?).map(&:name) + external.compact).uniq
+        end
+
+        # True when every instance of `name` is an instance of `earlier` by the environment's class ordering, past no
+        # class whose RBS ancestry Ruby contradicts.
+        def covered_by?(name, earlier)
+          environment = @scope.environment
+          case environment.class_ordering(name, earlier)
+          when :equal then true
+          when :subclass
+            UNRELIABLE_ANCESTRY.none? do |unreliable|
+              unreliable != earlier && %i[equal subclass].include?(environment.class_ordering(name, unreliable))
+            end
+          else false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -17,6 +17,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 +41,45 @@ 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?
+        # 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 +94,7 @@ module Rigor
 
           @built = true
           @singleton_defs = []
+          @clones = []
           @scopes = []
           return if @root.nil?
 
@@ -78,11 +109,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 +137,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,190 @@
+# frozen_string_literal: true
+
+require_relative "../../reflection"
+require_relative "../dependency_recorder"
+require_relative "../../inference/singleton_hook_decline"
+
+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
+
+        # 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) ||
+              (open_mixins && Inference::SingletonHookDecline.entry_hook_capable?(scope, entry))
+          end
+        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 only through RBS.
+        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
+
+          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

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

@@ -168,7 +168,9 @@ module Rigor
       # Bare (dot-less) diagnostic ids the engine emits outside the catalogue (see the `rule:` literals in
       # `Analysis::Runner` / `Runner::DiagnosticAggregator`). A token equal to one of these is treated as
       # known by `suppression.unknown-rule` even though it carries no family prefix; extend the list when
-      # the runner grows a new bare id.
+      # the runner grows a new bare id. Ids a marker or `disable:` cannot suppress (the `--explain`
+      # `fallback` row, the `contribution_merge` conflict reasons) stay out: they are
+      # `ConfigAudit::SEVERITY_ONLY_IDS`, known to the `severity_overrides:` audit alone.
       NON_CHECK_DIAGNOSTIC_IDS = %w[
         configuration-error load-error pool-degraded runtime-error source-rbs-synthesis-failed
         source-rbs-annotation-not-honoured