rigortype 0.3.9 → 0.4.0

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

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../../inference/scope_indexer"
+require_relative "../../source/constant_path"
+require_relative "../../source/node_children"
+
+module Rigor
+  module Analysis
+    module CheckRules
+      # Issue #1120 — the two ways one file makes a method callable at some sites and not at others, which
+      # `call.undefined-method` has to ask the file's syntax about because no project-wide table can answer:
+      #
+      # - **Refinements.** `using M` activates M's refinements from the end of the call to the end of the body
+      #   that holds it — the file's top level or a `class` / `module` body, including everything nested in it —
+      #   and nowhere else, not even in another file. A `refine X do … end` block is active inside itself. What
+      #   each module refines is the project-wide `Scope#discovered_refinements`; this answers whether any of
+      #   those modules is in effect at a call site. A `using` whose argument is not a constant
+      #   (`using Module.new { refine … }`) names no module, so every refinement counts as in effect throughout
+      #   its file. A `using` inside a `def` raises in Ruby and activates nothing.
+      # - **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).
+      #
+      # 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.
+      class LexicalMethodSites
+        def initialize(root)
+          @root = root
+          @built = false
+        end
+
+        # Is a refinement from one of `modules` (refining-module names) in effect at `call_node`?
+        def refinement_active?(call_node, modules)
+          build
+          return true if @unresolved_using
+
+          offset = call_node.location.start_offset
+          return true if @refine_blocks.any? { |start, stop| offset >= start && offset < stop }
+
+          @usings.any? do |start, stop, candidates|
+            offset >= start && offset < stop && candidates.any? { |name| modules.include?(name) }
+          end
+        end
+
+        # Issue #1367 — is any refinement in effect at `node`: a `using` of any module, a `using` of a non-constant, or
+        # the inside of a `refine` block? The `global.*` stream check asks it where it cannot name the refining
+        # module (a `define_method` or `alias_method` inside `refine` records none).
+        def using_in_effect?(node)
+          build
+          return true if @unresolved_using
+
+          offset = node.location.start_offset
+          @refine_blocks.any? { |start, stop| offset >= start && offset < stop } ||
+            @usings.any? { |start, stop, _candidates| offset >= start && offset < stop }
+        end
+
+        # Is `def_node` one of the defs a `refine X do … end` body defines on X? Such a def redefines X's method by
+        # design, so X's declared signature for the name is not its contract (issue #1120, maintainer ruling a′).
+        def refinement_def?(def_node)
+          build
+          @refinement_defs.include?(def_node.location.start_offset)
+        end
+
+        # Does a `def <local>.<name>` for this call's local receiver and method name 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
+        end
+
+        private
+
+        # 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)
+          @scopes.any? do |inner_start, inner_stop|
+            (inner_start > start || inner_stop < stop) && inner_start >= start && inner_stop <= stop &&
+              offset >= inner_start && offset < inner_stop
+          end
+        end
+
+        def build
+          return if @built
+
+          @built = true
+          @usings = []
+          @refine_blocks = []
+          @singleton_defs = []
+          @scopes = []
+          @refinement_defs = Set.new
+          @unresolved_using = false
+          return if @root.nil?
+
+          location = @root.location
+          span = [location.start_offset, location.end_offset]
+          walk(@root, [], span, span, false)
+        end
+
+        # `body` is the `[start, end]` of the body a `using` here stays in effect to the end of; `locals` is the
+        # span of the scope a local written here belongs to.
+        def walk(node, prefix, body, locals, in_def)
+          case node
+          when Prism::ClassNode, Prism::ModuleNode
+            span = scope_span(node)
+            inner = Source::ConstantPath.declaration_prefix(prefix, node.constant_path) || prefix
+            return walk_children(node.body, inner, span, span, false)
+          when Prism::SingletonClassNode
+            walk(node.expression, prefix, body, locals, in_def)
+            span = scope_span(node)
+            return walk_children(node.body, prefix, span, span, false)
+          when Prism::DefNode
+            record_singleton_def(node, locals)
+            return walk_children(node.body, prefix, body, scope_span(node), true)
+          when Prism::CallNode
+            record_call(node, prefix, body, in_def)
+          end
+
+          walk_children(node, prefix, body, locals, in_def)
+        end
+
+        def walk_children(node, prefix, body, locals, in_def)
+          return if node.nil?
+
+          node.rigor_each_child { |child| walk(child, prefix, body, locals, in_def) }
+        end
+
+        def record_singleton_def(node, locals)
+          receiver = node.receiver
+          return unless receiver.is_a?(Prism::LocalVariableReadNode)
+
+          @singleton_defs << [receiver.name, node.name, *locals]
+        end
+
+        def record_call(node, prefix, body, in_def)
+          if Inference::ScopeIndexer.refine_target(node)
+            @refine_blocks << span_of(node.block)
+            record_refinement_defs(node.block.body)
+          elsif using_call?(node) && !in_def
+            record_using(node, prefix, body)
+          end
+        end
+
+        def record_refinement_defs(body)
+          return if body.nil?
+
+          Inference::ScopeIndexer.each_refinement_def(body) do |def_node|
+            @refinement_defs << def_node.location.start_offset
+          end
+        end
+
+        def using_call?(node)
+          node.name == :using && (node.receiver.nil? || node.receiver.is_a?(Prism::SelfNode)) &&
+            node.arguments&.arguments&.size == 1
+        end
+
+        def record_using(node, prefix, body)
+          argument = node.arguments.arguments.first
+          if argument.is_a?(Prism::ConstantReadNode) || argument.is_a?(Prism::ConstantPathNode)
+            candidates = Inference::ScopeIndexer.constant_receiver_candidates(argument, prefix)
+            @usings << [node.location.end_offset, body.last, candidates]
+          else
+            @unresolved_using = true
+          end
+        end
+
+        # The span of a node that opens a local scope, recorded for {#nested_scope_holds?}.
+        def scope_span(node)
+          span = span_of(node)
+          @scopes << span
+          span
+        end
+
+        def span_of(node)
+          location = node.location
+          [location.start_offset, location.end_offset]
+        end
+      end
+    end
+  end
+end

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

@@ -19,10 +19,12 @@ module Rigor
       # accumulated {Diagnostic}s, in the same emission order the inline `NodeWalker.each` produced them (the
       # shared walk is the same visit-before-descend DFS over `compact_child_nodes`).
       class MainPassCollector
-        # The node classes the former inline pass branched on. A plain `Prism::IfNode` covers ternaries and
-        # postfix `if` too (the legacy `when Prism::IfNode, Prism::UnlessNode` arm did the same).
+        # The node classes the main pass branches on. A plain `Prism::IfNode` covers ternaries and postfix `if`
+        # too (the legacy `when Prism::IfNode, Prism::UnlessNode` arm did the same). The three global-write
+        # classes carry issue #1367's `global.*` rules.
         NODE_CLASSES = [
-          Prism::CallNode, Prism::DefNode, Prism::IfNode, Prism::UnlessNode
+          Prism::CallNode, Prism::DefNode, Prism::IfNode, Prism::UnlessNode,
+          Prism::GlobalVariableWriteNode, Prism::GlobalVariableOperatorWriteNode, Prism::MultiWriteNode
         ].freeze
 
         # @param node_diagnostics — maps a `Prism::Node` to the array of diagnostics the main pass emits

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

@@ -6,9 +6,9 @@ module Rigor
       # Canonical identifiers for each rule. Per ADR-8 § "Diagnostic ID family hierarchy", rule names are
       # `family.rule-name` two-segment strings; the families group diagnostics by where they originate
       # (`call.*` for call-site rules, `flow.*` for flow-analysis proofs, `assert.*` for runtime-assertion
-      # rules, `dump.*` for debug helpers, `def.*` for method-definition rules). Used by the configuration
-      # `disable:` list and the in-source `# rigor:disable <rule>` suppression comment system; new rules MUST
-      # register here so user configuration can refer to them.
+      # rules, `dump.*` for debug helpers, `def.*` for method-definition rules, `global.*` for writes to special
+      # globals). Used by the configuration `disable:` list and the in-source `# rigor:disable <rule>`
+      # suppression comment system; new rules MUST register here so user configuration can refer to them.
       #
       # ADR-87 WD4 — this pure-data constant table is split out of the (engine-heavy) `check_rules.rb` so
       # {Analysis::RuleCatalog} — which the CLI's JSON `evidence_tier` / `documentation_url` enrichment reads
@@ -66,6 +66,18 @@ module Rigor
       # annotation must never turn collection on by itself (that would be a project-wide cost cliff
       # nobody asked for), and it must equally never be silently inert.
       RULE_EFFECT_ANNOTATIONS_UNCHECKED = "effect.annotations-unchecked"
+      # ADR-112 WD5 / #1075 — two statements of one member's contract that contradict: a `sig/` declaration
+      # against an inline `@rbs` / `#:` one (and, once #1073 reads it, `@rbs` / `#:` against `@extrbs`), or a
+      # `rigor:v1:` refinement outside the member's own declared type. `rbs.` because the finding is about
+      # the RBS the environment is built from, whichever file spelled it; not `rbs_extended.`, whose rows
+      # are payload validity, since most contradictions involve no `RBS::Extended` annotation at all.
+      RULE_CONTRADICTING_SIGNATURE = "rbs.contradicting-signature"
+      # Issue #1367 (ADR-117 WD2) — the `global.*` family: a write to a special global that its setter rejects, so
+      # the write raises on every run. Two ids so a project can tune the type check without hiding read-only
+      # writes; the `write` wording follows `def.ivar-write-mismatch`. The envelope is the interpreter's setter
+      # (`SpecialGlobalSetters`), not the global's RBS declaration.
+      RULE_GLOBAL_WRITE_TYPE_MISMATCH = "global.write-type-mismatch"
+      RULE_GLOBAL_READONLY_WRITE = "global.readonly-write"
 
       ALL_RULES = [
         RULE_UNDEFINED_METHOD,
@@ -91,6 +103,8 @@ module Rigor
         RULE_OVERRIDE_RETURN_WIDENED,
         RULE_OVERRIDE_PARAM_NARROWED,
         RULE_IVAR_WRITE_MISMATCH,
+        RULE_GLOBAL_WRITE_TYPE_MISMATCH,
+        RULE_GLOBAL_READONLY_WRITE,
         RULE_SUPPRESSION_UNKNOWN_RULE,
         RULE_SUPPRESSION_EMPTY,
         RULE_SUPPRESSION_UNKNOWN_MARKER,
@@ -98,7 +112,8 @@ module Rigor
         RULE_EFFECT_ENVELOPE_EXCEEDED,
         RULE_EFFECT_LISKOV_WIDENED,
         RULE_EFFECT_UNKNOWN_LABEL,
-        RULE_EFFECT_ANNOTATIONS_UNCHECKED
+        RULE_EFFECT_ANNOTATIONS_UNCHECKED,
+        RULE_CONTRADICTING_SIGNATURE
       ].freeze
 
       # Backward-compat alias table (ADR-8 § "Backward compatibility"). Existing user code with
@@ -128,7 +143,7 @@ module Rigor
 
       # Family wildcard — a `<family>` token in a suppression comment or `disable:` list disables every rule
       # whose canonical id starts with `<family>.`. Per ADR-8 § "1".
-      RULE_FAMILIES = %w[call flow assert dump def suppression static effect].freeze
+      RULE_FAMILIES = %w[call flow assert dump def global suppression static effect].freeze
 
       # Families of diagnostics the engine emits OUTSIDE the CheckRules catalogue (aggregator-level and
       # reporter-level diagnostics such as `rbs_extended.unsatisfied-conformance`,

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

@@ -50,6 +50,7 @@ module Rigor
           Struct: %i[new],
           Data: %i[define]
         }.freeze
+        Ractor.make_shareable(DETACHED_CLASS_FACTORIES)
         private_constant :DETACHED_CLASS_FACTORIES
 
         EMPTY_METHODS = [].freeze
@@ -108,7 +109,7 @@ module Rigor
             end
           end
 
-          # The context the children of `node` descend under. Mirrors {RuleWalk.descend}.
+          # Mirrors {RuleWalk.descend}.
           def descend(node, context)
             RuleWalk.descend(node, context)
           end

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

@@ -0,0 +1,323 @@
+# frozen_string_literal: true
+
+require_relative "../../reflection"
+require_relative "../../source/parameter_envelope"
+
+module Rigor
+  module Analysis
+    module CheckRules
+      # Issue #992 — the positional envelope `call.wrong-arity` may check a call against when no signature
+      # declares the method: the {Source::ParameterEnvelope} the project's own `def` records in
+      # `Scope::DiscoveryIndex#discovered_parameter_envelopes`, and only when nothing the project can see
+      # could make a different definition of that name the one that runs.
+      #
+      # Asked in two stages, because every condition past the first can only WITHHOLD a firing:
+      #
+      # 1. {#owner_envelope} walks the receiver's superclass chain to the first class whose own body, or one of
+      #    whose project mixins, records the name. Every record at that level must agree — `include` and
+      #    `prepend` share one table, so a mixin's definition may shadow the class's own — and none may be
+      #    opaque. A call that fits this envelope is silent, and nothing below is consulted.
+      # 2. {#authoritative?} runs only for a call that would fire. It declines when a `method_missing` /
+      #    `respond_to_missing?` hook or a dynamic-surface mark sits anywhere in the chain; when a mixin the
+      #    project does not declare is not a known RBS module that lacks the name; when a `pre_eval:` patch or
+      #    a plugin's synthetic method names it; when the owner does not make the method public; and when any
+      #    project subclass of the receiver — whose instances the receiver's type admits — records a different
+      #    or opaque envelope for it.
+      #
+      # Deliberately NOT in scope: a constructor reached through `Class#new` (nothing records `initialize` as
+      # `[:singleton, :new]`, so `.new` finds no owner unless the class writes `def self.new` itself); keyword
+      # arity (the envelope's required-keyword flag declines, as `compute_arity_envelope` declines an RBS
+      # function with required keywords); and a `class_eval` whose receiver is not a constant, which the
+      # discovery walk cannot name.
+      class SourceArity
+        MISSING_HOOKS = %i[method_missing respond_to_missing?].freeze
+        private_constant :MISSING_HOOKS
+
+        # One class on the walk: its own name, the project modules its mixins resolve to (transitively through
+        # their own `include`s), and the candidate-name lists of the mixins that resolve to no project module.
+        Level = Data.define(:class_name, :modules, :externals)
+        private_constant :Level
+
+        def initialize(scope, method_name, kind)
+          @scope = scope
+          @method_name = method_name.to_sym
+          @kind = kind
+          @name_memo = {}
+        end
+
+        # The nearest definition's envelope, or nil when there is none or it is not one shape. Remembers the
+        # levels it walked for {#authoritative?}.
+        #
+        # Its ADR-46 reads are withheld ({Analysis::DependencyRecorder.withhold}) until the caller settles
+        # the verdict with {#settle_by_definitions} or {#settle_by_walk}.
+        def owner_envelope(class_name)
+          @owner_entries = []
+          @ambiguous = false
+          envelope, @withheld = Analysis::DependencyRecorder.withhold { walk_to_owner(class_name) }
+          envelope
+        end
+
+        # True when the nearest level recorded the name but not as one envelope.
+        def ambiguous? = @ambiguous
+
+        # For a silent verdict that only a definition can overturn — the call fits, the owner takes a required
+        # keyword, or nothing on the chain records the name: the owner `def`s themselves (their symbol edges)
+        # and a definition appearing at a level the walk passed over (a name-keyed negative edge). A mixin or
+        # reopening added at the owner's level makes it opaque, and everything {#authoritative?} reads can only
+        # withhold, so none of these needs the file-level class edge the bucket reads would otherwise record.
+        def settle_by_definitions
+          return if @withheld.nil?
+
+          @owner_entries.each do |name, kind|
+            if kind == :singleton
+              @scope.user_singleton_def_site_for(name, @method_name)
+            else
+              @scope.user_def_site_for(name, @method_name)
+            end
+          end
+          separator = @kind == :singleton ? "." : "#"
+          @passed.each { |name| Analysis::DependencyRecorder.read_missing(:method, "#{name}#{separator}#{@method_name}") }
+        end
+
+        # For every other verdict — a firing, or an opaque owner level whose opacity another file's edit can
+        # lift — the walk's reads are the dependency, so they are recorded as read.
+        def settle_by_walk
+          Analysis::DependencyRecorder.replay(@withheld) unless @withheld.nil?
+        end
+
+        # Stage 2, for the class {#owner_envelope} last answered.
+        def authoritative?(class_name)
+          !load_order_dependent?(class_name) && !object_extension_may_shadow? &&
+            @levels.all? { |level| clean_level?(level) && public_at?(level.class_name) } &&
+            chain_free_of_hooks?(class_name) &&
+            subclasses_agree?(class_name, @envelope)
+        end
+
+        private
+
+        def walk_to_owner(class_name)
+          @levels = []
+          @passed = []
+          walked_whole_chain?(class_name) do |current|
+            level = level_for(current)
+            @levels << level
+            found = level_envelopes(level)
+            if found.empty?
+              @passed.concat([current] + level.modules)
+              next
+            end
+
+            envelope = found.first
+            @owner_entries = owner_entries(level)
+            unless found.all?(envelope) && !Source::ParameterEnvelope.opaque?(envelope)
+              @ambiguous = true
+              return nil
+            end
+
+            return @envelope = envelope
+          end
+          nil
+        end
+
+        def owner_entries(level)
+          own = @scope.parameter_envelopes_of(level.class_name).key?([@kind, @method_name])
+          entries = own ? [[level.class_name, @kind]] : []
+          level.modules.each do |mod|
+            entries << [mod, :instance] if @scope.parameter_envelopes_of(mod).key?([:instance, @method_name])
+          end
+          entries
+        end
+
+        # The survey corpus's own lesson. `PStore.new(path).transaction { … }` inside `module TDiary::IO`
+        # resolves `PStore` to the project's `TDiary::IO::PStore` when that class's file is loaded, and to the
+        # stdlib `::PStore` when it is not — and tdiary loads it only under one `io_class` setting, so under
+        # the default one the call is correct code. The analysis universe holds every file at once, so it
+        # always picks the inner class. Whenever the receiver's class is one of SEVERAL known classes the
+        # call site's `Module.nesting` spells with the same last segment, which one the receiver is depends
+        # on load order, and a verdict against the project class's `def` is not one the program backs.
+        def load_order_dependent?(class_name)
+          segment = class_name.to_s.split("::").last
+          candidates = Rigor::Reflection.lexical_nesting_chain(@scope).map { |entry| "#{entry}::#{segment}" }
+          candidates << segment
+          known = candidates.uniq.select { |name| known_class?(name) }
+          known.include?(class_name.to_s) && known.size > 1
+        end
+
+        # A module some method body hands to `obj.extend` sits ahead of the object's class, so if it defines
+        # the name at all, that object answers with the module's definition.
+        def object_extension_may_shadow?
+          @scope.discovered_parameter_envelopes.any? do |_name, bucket|
+            bucket.key?(Scope::DiscoveryIndex::ENVELOPE_OBJECT_EXTENDED_MARK) && bucket.key?([:instance, @method_name])
+          end
+        end
+
+        def known_class?(name)
+          @scope.discovered_classes.key?(name) || Rigor::Reflection.rbs_class_known?(name, scope: @scope)
+        end
+
+        # False when the walk stopped at the ADR-41 budget rather than at the top of the chain: budget
+        # exhaustion is uncertainty, and every caller reads it as a reason to decline.
+        def walked_whole_chain?(class_name)
+          current = class_name.to_s
+          seen = {}
+          while current && !seen[current]
+            return false if seen.size >= Scope::ANCESTOR_WALK_LIMIT
+
+            seen[current] = true
+            yield current
+            current = resolve(current, @scope.superclass_of(current))
+          end
+          true
+        end
+
+        def level_for(class_name)
+          modules = []
+          externals = []
+          collect_mixins(class_name, own_mixins(class_name), modules, externals, {})
+          Level.new(class_name: class_name, modules: modules, externals: externals)
+        end
+
+        # Instance methods reach a receiver through `include` / `prepend`; class methods through `extend`, and
+        # an extended module's own `include`s reach the same singleton.
+        def own_mixins(class_name)
+          @kind == :singleton ? (@scope.discovered_extends[class_name] || []) : @scope.includes_of(class_name)
+        end
+
+        # Issue #986 — a name the compact-header rename collision left ambiguous resolves to no ONE class,
+        # but BOTH classes it names are ancestors at runtime; only their MRO order is unknowable. Taking
+        # both as levels is what keeps this rule alive for the rest of the receiver: a method only one of
+        # them declares still has one envelope and still fires, a method they disagree about lands two on
+        # `#envelope_for`'s join and declines there, and the class's own `def`s, its superclass's and its
+        # unambiguous mixins are untouched. Letting the decline arrive as an unknown EXTERNAL mixin instead
+        # suppressed the rule for every level of the receiver.
+        def collect_mixins(owner, raw_names, modules, externals, seen)
+          raw_names.each do |raw|
+            resolved = resolve(owner, raw)
+            names = resolved ? [resolved] : @scope.ambiguous_ancestor_resolutions(owner, raw)
+            next externals << @scope.ancestor_name_candidates(owner, raw) if names.empty?
+
+            names.each do |name|
+              next if seen[name]
+
+              seen[name] = true
+              modules << name
+              collect_mixins(name, @scope.includes_of(name), modules, externals, seen)
+            end
+          end
+        end
+
+        def resolve(owner, raw)
+          return nil if raw.nil?
+
+          bucket = (@name_memo[owner] ||= {})
+          return bucket[raw] if bucket.key?(raw)
+
+          bucket[raw] = @scope.ancestor_name_candidates(owner, raw).find { |name| project_class?(name) }
+        end
+
+        def project_class?(name)
+          @scope.known_user_class?(name) || @scope.discovered_parameter_envelopes.key?(name)
+        end
+
+        # A module's methods reach the receiver as instance methods whichever side the receiver is on.
+        def level_envelopes(level)
+          own = @scope.parameter_envelopes_of(level.class_name)[[@kind, @method_name]]
+          mixed = level.modules.map { |mod| @scope.parameter_envelopes_of(mod)[[:instance, @method_name]] }
+          ([own] + mixed).compact
+        end
+
+        def clean_level?(level)
+          ([level.class_name] + level.modules).none? { |name| dynamic_surface?(name) || project_patched?(name) } &&
+            level.externals.all? { |candidates| external_mixin_lacks_method?(candidates) }
+        end
+
+        def dynamic_surface?(class_name)
+          Scope::DiscoveryIndex.rewritten_surface?(@scope.parameter_envelopes_of(class_name))
+        end
+
+        def project_patched?(class_name)
+          environment = @scope.environment
+          patched = environment&.project_patched_methods
+          return true if patched && !patched.empty? && patch_names_method?(patched, class_name)
+
+          synthetic = environment&.synthetic_method_index
+          return false if synthetic.nil? || synthetic.empty?
+
+          synthetic.knows_class?(class_name) || !synthetic.lookup_instance(class_name, @method_name).empty? ||
+            !synthetic.lookup_singleton(class_name, @method_name).empty?
+        end
+
+        def patch_names_method?(patched, class_name)
+          %i[instance singleton].any? do |kind|
+            !patched.lookup(class_name: class_name, method_name: @method_name, kind: kind).nil?
+          end
+        end
+
+        # A mixin the project does not declare may define the name with any arity, and `prepend` lets it win
+        # over the class's own `def`. Only a module RBS knows, and whose declaration lacks the name, is
+        # evidence that it does not.
+        def external_mixin_lacks_method?(candidates)
+          name = candidates.find { |candidate| Rigor::Reflection.rbs_class_known?(candidate, scope: @scope) }
+          return false if name.nil?
+
+          Rigor::Reflection.instance_method_definition(name, @method_name, scope: @scope).nil?
+        rescue StandardError
+          false
+        end
+
+        def public_at?(class_name)
+          visibility = @scope.discovered_method_visibility(class_name, @method_name)
+          visibility.nil? || visibility == :public
+        end
+
+        # A hook anywhere in the chain, including above the owner, and on either side: a class that answers
+        # names it does not define is a class whose `def`s are not the whole story of what a call reaches.
+        def chain_free_of_hooks?(class_name)
+          walked_whole_chain?(class_name) do |current|
+            ([current] + level_for(current).modules).each do |name|
+              envelopes = @scope.parameter_envelopes_of(name)
+              return false if dynamic_surface?(name)
+              return false if MISSING_HOOKS.any? { |hook| hook_recorded?(envelopes, hook) }
+            end
+          end
+        end
+
+        def hook_recorded?(envelopes, hook)
+          envelopes.key?([:instance, hook]) || envelopes.key?([:singleton, hook])
+        end
+
+        # Every project class whose superclass chain reaches the receiver's class: a value typed as the
+        # receiver may be any of them, and each one's own definition of the name is what runs for it.
+        def subclasses_agree?(class_name, envelope)
+          each_subclass(class_name) do |subclass|
+            level = level_for(subclass)
+            return false unless clean_level?(level)
+            return false unless level_envelopes(level).all?(envelope)
+          end
+          true
+        end
+
+        def each_subclass(class_name)
+          children = children_by_parent
+          queue = children.fetch(class_name.to_s, []).dup
+          seen = {}
+          until queue.empty?
+            subclass = queue.shift
+            next if seen[subclass]
+
+            seen[subclass] = true
+            yield subclass
+            queue.concat(children.fetch(subclass, []))
+          end
+        end
+
+        def children_by_parent
+          @scope.discovered_superclasses.each_with_object({}) do |(child, raw_parent), children|
+            parent = resolve(child, raw_parent)
+            (children[parent] ||= []) << child if parent
+          end
+        end
+      end
+    end
+  end
+end