rigortype 0.4.4 → 0.4.6

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

@@ -5,6 +5,7 @@ require "prism"
 require_relative "../../source/node_children"
 require_relative "../../inference/narrowing"
 require_relative "inferred_param_guard"
+require_relative "clause_coverage"
 
 module Rigor
   module Analysis
@@ -36,6 +37,10 @@ module Rigor
       # is code evidence that the subject can hold such an object (`io = STDOUT; case io when StringIO`), and Rigor's
       # reading of the subject's type is what the evidence contradicts. The body scope stays `Bot`, so no call on the
       # subject in it is checked. A subject that is a literal carrier (`x = 1; case x when String`) is still reported.
+      #
+      # Issue #1485 — the same holds for a `:prior_exhaustion` clause: on a subject that is not a literal carrier it is
+      # reported only when every class it names is at or below a class an earlier clause names ({ClauseCoverage}), so
+      # `io = STDOUT; case io when IO … when StringIO` is quiet and `when IO … when File` still reports.
       class UnreachableClauseCollector
         LOOP_OR_BLOCK_NODE_CLASSES = [
           Prism::WhileNode, Prism::UntilNode, Prism::ForNode, Prism::BlockNode
@@ -48,6 +53,24 @@ module Rigor
         # `else`-only.
         DEFENSIVE_EXIT_CALLS = %i[raise fail throw abort exit].freeze
 
+        # Issue #2071 — core classes whose idiomatic stand-ins are not their subclasses: a `StringIO` answers the
+        # IO protocol without being an `IO`, and a `Tempfile` delegates to a `File` without being one (or an `IO`).
+        # A subject Rigor types as one of these classes (`$stdout` by idiom, ADR-117) may hold such a stand-in,
+        # which no `when IO` / `in File` matches, so the `else` still runs for it.
+        DUCK_STAND_INS = {
+          "IO" => %w[StringIO Tempfile].freeze,
+          "File" => %w[Tempfile].freeze
+        }.freeze
+
+        # Each stand-in's ancestors as Ruby 4.0.5 has them (`StringIO.ancestors`, `Tempfile.ancestors` without the
+        # anonymous `DelegateClass` entries): a clause naming one matches the stand-in. Written out rather than read
+        # from RBS, which declares `class Tempfile < File`; a `Tempfile` is a `Delegator`, so neither `Object` nor
+        # `Kernel` matches it.
+        STAND_IN_ANCESTORS = {
+          "StringIO" => %w[StringIO Enumerable Object Kernel BasicObject].freeze,
+          "Tempfile" => %w[Tempfile Delegator BasicObject].freeze
+        }.freeze
+
         # @!attribute kind
         #   @return `:disjoint` (this clause's type is disjoint
         #     from the still-possible subject), `:prior_exhaustion` (an
@@ -124,21 +147,56 @@ module Rigor
           return if entry_type.nil? || entry_type.is_a?(Type::Bot) || entry_type.is_a?(Type::Dynamic)
 
           keyword = node.is_a?(Prism::CaseMatchNode) ? "in" : "when"
+          coverage = ClauseCoverage.new(scope, entry_type)
           node.conditions.each do |clause|
             case clause
-            when Prism::WhenNode then collect_when(clause, subject.name)
-            when Prism::InNode then collect_in(clause, subject.name)
+            when Prism::WhenNode then collect_when(clause, subject.name, coverage)
+            when Prism::InNode then collect_in(clause, subject.name, coverage)
             end
+            coverage.record(clause)
           end
+          return if stand_in_reaches_else?(node, entry_type)
+
           collect_else(node.else_clause, subject.name, keyword)
         end
 
+        # Issue #2071 — whether the subject, as the `case` binds it, has a `Nominal` member of a {DUCK_STAND_INS}
+        # class with a stand-in no clause names an ancestor of ({STAND_IN_ANCESTORS}). `io = STDOUT; case io when IO
+        # then … else … end` runs the `else` for a `StringIO`, which the type `IO` stands for in idiomatic Ruby; a
+        # literal subject is a `Constant`, not a `Nominal`, and keeps its verdict. Asked of the `else` only: a dead
+        # `when` has its own evidence rules (#1429, #1485).
+        def stand_in_reaches_else?(node, entry_type)
+          members = entry_type.is_a?(Type::Union) ? entry_type.members : [entry_type]
+          stand_ins = members.flat_map do |member|
+            member.is_a?(Type::Nominal) ? DUCK_STAND_INS.fetch(member.class_name.delete_prefix("::"), []) : []
+          end
+          return false if stand_ins.empty?
+
+          named = clause_class_names(node)
+          stand_ins.any? { |stand_in| named.none? { |name| STAND_IN_ANCESTORS.fetch(stand_in).include?(name) } }
+        end
+
+        # The classes the clauses name as bare constants (`when A, B`, `in A`, `in A => x`).
+        def clause_class_names(node)
+          node.conditions.flat_map do |clause|
+            patterns = clause.is_a?(Prism::WhenNode) ? clause.conditions : [bare_pattern(clause.pattern)]
+            patterns.filter_map do |pattern|
+              entry = @scope_index[pattern]
+              entry && Inference::Narrowing.lexical_class_name(pattern, entry)
+            end
+          end
+        end
+
+        def bare_pattern(pattern)
+          pattern.is_a?(Prism::CapturePatternNode) ? pattern.value : pattern
+        end
+
         def entry_subject_type(case_node, subject_name)
           scope = @scope_index[case_node]
           scope&.local(subject_name)
         end
 
-        def collect_when(clause, subject_name)
+        def collect_when(clause, subject_name, coverage)
           return if clause.statements.nil? # empty body → no useful location
           return unless all_constant_conditions?(clause)
 
@@ -149,6 +207,7 @@ module Rigor
           kind = when_clause_kind(clause, subject_name)
           return if kind == :disjoint &&
                     disjoint_nominal_subject?(@scope_index[clause.conditions.first], subject_name, clause.conditions)
+          return if kind == :prior_exhaustion && !coverage.proven?(clause)
 
           @results << Result.new(
             clause: clause, body: clause.statements, subject_name: subject_name,
@@ -187,7 +246,7 @@ module Rigor
         # (prior-exhaustion — true for ANY pattern downstream of a covering set). Non-bare patterns are not
         # narrowed, so their body is `bot` ONLY under prior-exhaustion; they never produce a spurious
         # `:disjoint`.
-        def collect_in(clause, subject_name)
+        def collect_in(clause, subject_name, coverage)
           return if clause.statements.nil?
 
           scope = @scope_index[clause]
@@ -196,6 +255,7 @@ module Rigor
 
           kind = in_clause_kind(clause, subject_name)
           return if kind == :disjoint && disjoint_nominal_pattern?(clause, subject_name)
+          return if kind == :prior_exhaustion && !coverage.proven?(clause)
 
           @results << Result.new(
             clause: clause, body: clause.statements, subject_name: subject_name,

data/lib/rigor/analysis/check_rules.rb

@@ -29,6 +29,8 @@ require_relative "check_rules/void_value_use_collector"
 require_relative "check_rules/self_closedness_scanner"
 require_relative "check_rules/source_arity"
 require_relative "check_rules/lexical_method_sites"
+require_relative "check_rules/rebinding_block_callees"
+require_relative "check_rules/rbs_receiver_surface"
 require_relative "check_rules/special_global_setters"
 require_relative "check_rules/ruby_deprecations"
 
@@ -449,11 +451,31 @@ module Rigor
           other_class = ivar_class_for(write[:type])
           next nil if other_class.nil? || other_class == "NilClass" || other_class == first_class
           next nil if declaration_admits?(write[:declared], canonical[:type], write[:type])
+          next nil if separate_invocations?(write, other_class, writes)
 
           build_ivar_write_mismatch_diagnostic(path, write[:node], class_name, ivar_name, first_class, other_class)
         end
       end
 
+      # ADR-125 — a divergent write is never live together with the writes it conflicts with when the class
+      # serves one entry point per instance (a plugin-declared per-invocation class, e.g. a Rails controller:
+      # one action per request) and every conflicting write — non-nil, of a concrete class other than this
+      # write's — sits in a DIFFERENT action of the same class. An action is a public method no declared
+      # non-action macro names (`before_action :x`, `helper_method :y`); {IvarWriteCollector} decides it. A
+      # conflicting write in a private or protected helper, a callback target, a `helper_method`,
+      # `initialize`, or the same method keeps the finding. Which helper each action reaches is not proved
+      # here.
+      def separate_invocations?(write, write_class, writes)
+        return false unless write[:action]
+
+        writes.all? do |other|
+          other_class = ivar_class_for(other[:type])
+          next true if other_class.nil? || other_class == "NilClass" || other_class == write_class
+
+          other[:action] && other[:method_name] != write[:method_name]
+        end
+      end
+
       def declaration_admits?(declared, *write_types)
         return false if declared.nil?
 
@@ -801,7 +823,7 @@ module Rigor
           # rule must not surface a false `undefined-method`
           # for them.
           kind = receiver_type.is_a?(Type::Singleton) ? :singleton : :instance
-          return nil if source_declared_method?(scope, class_name, call_node.name, kind)
+          return nil if source_declared_method?(scope, class_name, call_node.name, kind, call_node: call_node)
 
           return nil unless Rigor::Reflection.rbs_class_known?(class_name, scope: scope)
 
@@ -817,6 +839,8 @@ module Rigor
           return nil if method_def
 
           return nil if last_resort_surface_answers?(receiver_type, class_name, call_node, scope, kind, lexical_sites)
+          return nil if subclass_instance_may_answer?(rendered_receiver, class_name, call_node.name, scope,
+                                                      call_node.receiver)
 
           definition_site = project_definition_site(scope, class_name, call_node.name, kind)
           # Issue #735 — the site is evidence, and whose RBS this is decides what it is evidence OF. On a
@@ -951,12 +975,52 @@ module Rigor
         #   (see {#ancestry_declares_method?} for why that placement is load-bearing, not tidiness).
         def last_resort_surface_answers?(receiver_type, class_name, call_node, scope, kind, lexical_sites = nil)
           return true if lexically_defined_method?(class_name, call_node, scope, kind, lexical_sites)
+          return true if project_patched_through_ancestors?(scope, class_name, call_node.name, kind,
+                                                            call_node: call_node)
           return true if module_mixin_receiver?(receiver_type, scope)
           return true if mixin_self_class_receiver?(call_node, scope)
           return true if unknown_mixin_includer?(class_name, scope)
           return true if object_mixin_may_define?(receiver_type, class_name, call_node.name, scope)
+          return true if ancestry_declares_method?(scope, class_name, call_node.name, kind)
+
+          rbs_ancestor_may_answer?(class_name, call_node.name, scope, kind)
+        end
+
+        # Issue #1722 — a `method_missing`, or a project mixin, on one of the class's RBS ancestors
+        # ({RbsReceiverSurface}). Last for {#ancestry_declares_method?}'s reason: it walks the class graph.
+        def rbs_ancestor_may_answer?(class_name, method_name, scope, kind)
+          if kind == :singleton
+            RbsReceiverSurface.singleton_hook?(scope, class_name) ||
+              RbsReceiverSurface.singleton_mixin_may_answer?(scope, class_name, method_name)
+          else
+            RbsReceiverSurface.ancestor_may_answer?(scope, class_name, method_name)
+          end
+        end
 
-          ancestry_declares_method?(scope, class_name, call_node.name, kind)
+        # Issue #1722 — a receiver typed by its class's name, rather than by a literal, may hold an instance of a
+        # subclass (a `#: () -> String` signature admits a `MyStr < String`), so a method a project subclass
+        # defines, or a subclass's `method_missing`, may be the one that runs. A value the engine built from a
+        # literal is exactly its class and keeps firing: a literal type (`"a"`, `1`, a union of them), a shape
+        # carrier (`{a: 1}`, `[1, 2]`, `{}`, `[]`, and what folds to one), or a receiver written as a literal
+        # (`"a#{x}b"`, which types as plain `String`). A local holding an interpolated String types as plain
+        # `String` with no origin, so it still declines. Instance side only.
+        def subclass_instance_may_answer?(receiver_type, class_name, method_name, scope, receiver_node = nil)
+          return false if receiver_type.is_a?(Type::Singleton)
+          return false if exact_literal_receiver?(receiver_type) || LITERAL_RECEIVER_NODES.include?(receiver_node.class)
+
+          RbsReceiverSurface.subclass_may_define?(scope, class_name, method_name)
+        end
+
+        EXACT_TYPES = [Type::Constant, Type::Tuple, Type::HashShape].freeze
+        LITERAL_RECEIVER_NODES = [
+          Prism::StringNode, Prism::InterpolatedStringNode, Prism::XStringNode, Prism::InterpolatedXStringNode,
+          Prism::ArrayNode, Prism::HashNode, Prism::RegularExpressionNode, Prism::InterpolatedRegularExpressionNode
+        ].to_set.freeze
+        private_constant :EXACT_TYPES, :LITERAL_RECEIVER_NODES
+
+        def exact_literal_receiver?(receiver_type)
+          members = receiver_type.is_a?(Type::Union) ? receiver_type.members : [receiver_type]
+          members.all? { |member| EXACT_TYPES.any? { |kind| member.is_a?(kind) } }
         end
 
         # Issue #1697 — a module the project mixes into `Object` (a top-level `include M`, or `include M` in
@@ -1058,10 +1122,13 @@ module Rigor
         # Both paths sit at the same dispatcher precedence; the
         # check must hold them together so neither rule fires a
         # false positive.
-        def source_declared_method?(scope, class_name, method_name, kind)
+        #
+        # `call_node:` (issue #1708), when given, is the call asking: a private or protected `pre_eval:` patch
+        # it may not reach does not count ({#patch_callable?}).
+        def source_declared_method?(scope, class_name, method_name, kind, call_node: nil)
           return true if scope.discovered_method?(class_name, method_name, kind)
 
-          project_patched_method?(scope, class_name, method_name, kind)
+          project_patched_method?(scope, class_name, method_name, kind, call_node: call_node)
         end
 
         # Issue #723 — the same question as {#source_declared_method?}, asked through the project's own
@@ -1087,12 +1154,42 @@ module Rigor
         # inference (between plugins and dependency-source).
         # Returns false when the environment carries no registry
         # (legacy path) or the lookup misses.
-        def project_patched_method?(scope, class_name, method_name, kind)
+        def project_patched_method?(scope, class_name, method_name, kind, call_node: nil)
+          environment = scope.environment
+          registry = environment&.project_patched_methods
+          return false if registry.nil? || registry.empty?
+
+          entry = registry.lookup(class_name: class_name.to_s, method_name: method_name.to_sym, kind: kind)
+          !entry.nil? && patch_callable?(registry, entry, scope, call_node)
+        end
+
+        # Issue #1708 — {#project_patched_method?} asked through the receiver's ancestors: a `pre_eval:` patch on
+        # `Object`, `Numeric` or `Enumerable` gives an `Integer` or `Array` the method. Asked only once the
+        # receiver's RBS has come back without the method, so a nearer class's own declaration still decides arity
+        # and argument types; {#source_declared_method?} stays exact for the rules that read it for those.
+        #
+        # `call_node:` as {#source_declared_method?} reads it.
+        def project_patched_through_ancestors?(scope, class_name, method_name, kind, call_node: nil)
           environment = scope.environment
           registry = environment&.project_patched_methods
           return false if registry.nil? || registry.empty?
 
-          !registry.lookup(class_name: class_name.to_s, method_name: method_name.to_sym, kind: kind).nil?
+          entry = registry.lookup_through_ancestors(class_name: class_name.to_s, method_name: method_name.to_sym,
+                                                    kind: kind, rbs_loader: environment.rbs_loader)
+          !entry.nil? && patch_callable?(registry, entry, scope, call_node)
+        end
+
+        # Issue #1708 — whether `call_node` may reach the patch `entry`: Ruby raises NoMethodError for a private
+        # patch called with an explicit receiver other than `self` (`1.kp` on `module Kernel; private def kp`), and
+        # for a protected one called from outside its owner's instances. No call node, and a declined verdict (another
+        # definer the call may reach, {Inference::ProjectPatchedMethods#callable?}), are the permissive answer.
+        def patch_callable?(registry, entry, scope, call_node)
+          return true if call_node.nil?
+
+          receiver = call_node.receiver
+          verdict = registry.callable?(entry, explicit: !receiver.nil? && !receiver.is_a?(Prism::SelfNode),
+                                              self_type: scope.self_type, rbs_loader: scope.environment.rbs_loader)
+          verdict != false
         end
 
         # ADR-34 — `call.unresolved-toplevel`. Fires on an
@@ -1141,6 +1238,8 @@ module Rigor
           return nil if scope.top_level_def_for(name)
           return nil if source_declared_method?(scope, "Object", name, :instance)
           return nil if Rigor::Reflection.instance_method_definition("Object", name, scope: scope)
+          # Issue #1708 — `main` is an Object, so a `pre_eval:` patch on `Kernel` or `BasicObject` defines the name too.
+          return nil if project_patched_through_ancestors?(scope, "Object", name, :instance)
           return nil if main_singleton_method?(name, scope)
           return nil if Inference::ObjectMixins.may_define?(scope, name, receiver: :implicit)
           # `Target.class_eval { def added = 1; def use_added = added }` files the defs on Target
@@ -1148,12 +1247,22 @@ module Rigor
           # body is morally a class body, so ADR-34 stays silent there — including on a genuinely
           # undefined name inside the block. Ranges are computed once per file.
           return nil if call_inside_receiver_eval_ranges?(eval_ranges, call_node)
-          # ADR-121 WD7 — a refinement of `Object` (or one Rigor cannot read) in effect here may define the name.
-          return nil if refined_method_in_effect?("Object", call_node, scope, :instance, lexical_sites)
+          return nil if lexically_declined_toplevel_call?(call_node, scope, lexical_sites, scope_index)
 
           build_unresolved_toplevel_diagnostic(path, call_node)
         end
 
+        # The `call.unresolved-toplevel` declines that read the file's syntax, asked last because they walk it.
+        def lexically_declined_toplevel_call?(call_node, scope, lexical_sites, scope_index = nil)
+          # ADR-121 WD7 — a refinement of `Object` (or one Rigor cannot read) in effect here may define the name.
+          return true if refined_method_in_effect?("Object", call_node, scope, :instance, lexical_sites)
+          return false if lexical_sites.nil?
+
+          # Issue #1817 — a block handed to a project method that may `module_eval` / `instance_exec` it runs under
+          # another `self`, so a call in it is not a top-level one ({RebindingBlockCallees}).
+          RebindingBlockCallees.inside_rebound_block?(call_node, scope, lexical_sites.block_calls, scope_index)
+        end
+
         # Issue #1383 — RBS core declares `main`'s private singleton methods on
         # `RBS::Unnamed::TopLevelSelfClass`, so the set follows RBS rather than a hand-kept
         # list. CRuby 4.0's `main` also has `ruby2_keywords`, which RBS does not declare.
@@ -1410,12 +1519,27 @@ module Rigor
         # overlay open receiver ({GEM_OVERLAY_OPEN_RECEIVERS}) whose
         # bundled directory this run actually loaded, a core-overlay
         # open receiver ({CORE_OVERLAY_OPEN_RECEIVERS}), or a
-        # Rigor-synthesized stub type (see `RbsLoader#synthesized_type_names`).
+        # Rigor-synthesized stub type (see `RbsLoader#synthesized_type_names`),
+        # or a project-only reopen of a Ruby library class whose own RBS
+        # did not load ({#ruby_library_reopen?}).
         def unbounded_receiver_surface?(class_name, scope)
           bare_name = class_name.to_s.sub(/\A::/, "")
           open_receiver?(class_name, scope) || synthesized_stub_receiver?(class_name, scope) ||
             CORE_OVERLAY_OPEN_RECEIVERS.include?(bare_name) ||
-            (GEM_OVERLAY_OPEN_RECEIVERS.include?(bare_name) && gem_overlay_loaded?(scope))
+            (GEM_OVERLAY_OPEN_RECEIVERS.include?(bare_name) && gem_overlay_loaded?(scope)) ||
+            ruby_library_reopen?(class_name, scope)
+        end
+
+        # Issue #2174 — `class Matrix` reopened with one `#:`-annotated method, and no `matrix` signatures
+        # loaded, gives Matrix a declaration holding only that method ({RbsLoader#ruby_library_reopen?}).
+        # `Matrix.identity(2)` is correct Ruby, so the class's surface is treated as open: `call.undefined-method`
+        # declines on it, and a signature it only inherits (`Object#initialize` for `Matrix.new(rows)`) stops
+        # deciding arity and argument types. Methods the project's own declaration lists stay checked.
+        def ruby_library_reopen?(class_name, scope)
+          loader = scope.environment&.rbs_loader
+          return false if loader.nil? || !loader.respond_to?(:ruby_library_reopen?)
+
+          loader.ruby_library_reopen?(class_name)
         end
 
         def open_receiver?(class_name, scope)
@@ -2143,6 +2267,7 @@ module Rigor
           return true unless Rigor::Reflection.rbs_class_known?(class_name, scope: scope)
           return true unless definition_available?(member, class_name, scope)
           return true if lookup_method(member, class_name, method_name, scope)
+          return true if project_patched_through_ancestors?(scope, class_name, method_name, :instance)
 
           # Issue #723 — the arm's own RBS does not have it; its project ancestry still might. Last, for
           # the reason {#ancestry_declares_method?} carries: this is the probe that walks the class graph.
@@ -2196,12 +2321,30 @@ module Rigor
           # `compose_codepoints` typed `Hash | Hash` for an `Array`, flagging
           # `.pack`). Require at least two distinct arm classes.
           return nil if members.map { |member| concrete_class_name(member) }.uniq.size < 2
-          return nil if members.any? { |member| method_present_anywhere?(member, call_node.name, scope) }
-          return nil if refined_on_some_arm?(members, call_node, scope, lexical_sites)
+          return nil if union_may_answer?(members, call_node, scope, lexical_sites)
 
           build_undefined_method_diagnostic(path, call_node, receiver_type)
         end
 
+        # Whether some arm of a non-nil union of classes may answer the call, which keeps the union rule silent.
+        def union_may_answer?(members, call_node, scope, lexical_sites)
+          return true if members.any? { |member| method_present_anywhere?(member, call_node.name, scope) }
+          return true if members.any? { |member| arm_surface_may_answer?(member, call_node.name, scope) }
+          # Issue #1722 — `def o.m`, `o.extend(M)` and their kin give the one object the method, whatever its class.
+          return true if lexical_sites&.singleton_local_def?(call_node)
+
+          refined_on_some_arm?(members, call_node, scope, lexical_sites)
+        end
+
+        # Issue #1722 — the scalar rule's RBS-ancestor and subclass declines, asked of one arm. Kept out of
+        # {#method_present_anywhere?}, which `call.possible-nil-receiver` also asks: there a "present" answer is
+        # what lets the rule fire, and a `method_missing` on `Object` answers on the `nil` arm too.
+        def arm_surface_may_answer?(member, method_name, scope)
+          class_name = concrete_class_name(member)
+          rbs_ancestor_may_answer?(class_name, method_name, scope, :instance) ||
+            subclass_instance_may_answer?(member, class_name, method_name, scope)
+        end
+
         # ADR-121 WD7 — a refinement in effect (or one Rigor cannot read) may define the name on one arm's class.
         def refined_on_some_arm?(members, call_node, scope, lexical_sites)
           members.any? do |member|
@@ -2684,9 +2827,37 @@ module Rigor
 
         # Whether any project or `pre_eval:` file aliases `name`, on either side, which can make it another variable.
         def global_aliased?(scope, name)
+          record_global_census(Inference::GlobalWriteCensus.alias_entry(name))
           Inference::GlobalWriteCensus.aliased?(global_write_census(scope), name)
         end
 
+        # Issue #2158 — a read of the whole-program census records the `global_census:` key of each entry it asks
+        # about ({Inference::GlobalWriteCensus.dependency_key}): a file that starts or stops writing the entry (a `def
+        # write`, an `alias $stdout $x`, a computed `define_method`) re-checks the write. A `pre_eval:` file moves the
+        # snapshot's own fingerprint.
+        def record_global_census(*entries)
+          return unless DependencyRecorder.active?
+
+          entries.each do |entry|
+            DependencyRecorder.read_name(:global_census, Inference::GlobalWriteCensus.dependency_key(entry))
+          end
+        end
+
+        # Whether the census holds any of `entries`, recording only what can flip the answer: the entries present
+        # when it holds one (the answer stays true until every one of them vanishes, and another appearing changes
+        # nothing), every entry when it holds none.
+        #
+        # This rests on an invariant: every census entry can only move a write toward being silenced, and a reported
+        # write is always re-checked through `IncrementalSession#global_write_reporters`, so recording only the
+        # present entries on a yes is sound. A future census entry that makes a write reported would break it, and
+        # its reader would have to record every entry. Recording every entry on a no is defence in depth, since the
+        # write that answer leaves reported re-checks through `global_write_reporters` anyway.
+        def census_holds_any?(census, entries)
+          present = entries.select { |entry| census.include?(entry) }
+          record_global_census(*(present.empty? ? entries : present))
+          !present.empty?
+        end
+
         # A literal is rejected when its class is none the setter takes and, for a setter that also converts
         # (`to_str`, `to_int`) or asks for `write`, the literal's object cannot answer that method.
         def literal_rejected?(class_name, contract, node, scope, lexical_sites)
@@ -2734,11 +2905,15 @@ module Rigor
         end
 
         def program_may_answer?(ancestors, names, census, scope)
-          return true if Inference::GlobalWriteCensus.defines_any_of?(census, names)
+          defines = [Inference::GlobalWriteCensus::DEFINES_ANY, *names.map { |name| [:defines, name] }]
+          return true if census_holds_any?(census, defines)
 
           dynamic_mark = Scope::DiscoveryIndex::ENVELOPE_DYNAMIC_MARK
           return true if ancestors.any? { |owner| scope.parameter_envelopes_of(owner).key?(dynamic_mark) }
 
+          # One key for every top-level mixin, a deliberate trade-off: the reader asks about each, so a mixin
+          # appearing or vanishing anywhere re-checks every write that reached this step.
+          record_global_census(%i[main_mixin *])
           main_mixins = Inference::GlobalWriteCensus.main_mixins(census)
           main_mixins.any? { |mixin| rbs_mixin_may_answer?(mixin, names, scope) } ||
             mixin_may_answer?(ancestors, names, scope)
@@ -2780,7 +2955,7 @@ module Rigor
         # active refinement on Ruby 4.0.5; a refined `respond_to_missing?` or `respond_to?`, and every implicit
         # conversion, do not, so a refinement that adds only those leaves the write reported.
         def refined_writer_in_effect?(census, node, scope, lexical_sites)
-          Inference::GlobalWriteCensus.refines_write?(census) &&
+          census_holds_any?(census, [Inference::GlobalWriteCensus::REFINES_ANY, %i[refines write]]) &&
             (lexical_sites.nil? || !scope.declared_refinements.empty? ||
               lexical_sites.refinements.any_at?(node.location.start_offset))
         end
@@ -2865,6 +3040,13 @@ module Rigor
         # - Issue #1568 — a module the class PREPENDS sits ahead of it in Ruby's order, so a definition there
         #   is what the call reaches; the class's own private `def` answers only when nothing prepended
         #   defines the name ({#reached_definer_visibility}).
+        # - Issue #1984 — a class-object receiver (`Type::Singleton`, `K.x`) is checked against the singleton side:
+        #   the definition the call reaches on `K`'s singleton chain (its own singleton methods, its extended
+        #   modules' instance methods, then the superclass's singleton chain) must be recorded `:private`
+        #   (`private_class_method`, `class << self` with `private`, a private method of an extended module).
+        # - Issue #1984 — Ruby hands a private call to `method_missing`, so a `method_missing` or
+        #   `respond_to_missing?` a project entry on the receiver's chain records, on the side the call reaches,
+        #   declines the rule ({#missing_hook_on_chain?}).
         def visibility_mismatch_diagnostic(path, call_node, scope_index, lexical_sites = nil)
           return nil unless explicit_non_self_receiver?(call_node.receiver)
 
@@ -2876,18 +3058,128 @@ module Rigor
           return nil if inferred_param_receiver?(call_node, scope)
 
           receiver_type = scope.type_of(call_node.receiver)
-          return nil unless receiver_type.is_a?(Type::Nominal)
+          case receiver_type
+          when Type::Nominal then instance_visibility_mismatch(path, call_node, scope, receiver_type, lexical_sites)
+          when Type::Singleton then singleton_visibility_mismatch(path, call_node, scope, receiver_type, lexical_sites)
+          end
+        end
 
+        def instance_visibility_mismatch(path, call_node, scope, receiver_type, lexical_sites)
           visibility = scope.discovered_method_visibility(receiver_type.class_name, call_node.name)
           return nil unless visibility == :private
 
           reached = reached_definer_visibility(scope, receiver_type.class_name, call_node.name)
           return nil if reached == :undecided
           return nil unless reached.nil? || reached == :private
+          return nil if missing_hook_on_chain?(scope, receiver_type.class_name, :instance)
           # ADR-121 WD7 — a refinement in effect (or one Rigor cannot read) may redefine the method, public.
           return nil if refined_method_in_effect?(receiver_type.class_name, call_node, scope, :instance, lexical_sites)
 
-          build_visibility_mismatch_diagnostic(path, call_node, receiver_type)
+          build_visibility_mismatch_diagnostic(path, call_node, receiver_type.class_name)
+        end
+
+        # Issue #1984 — the singleton side reads only the reached definer: a private singleton method may be inherited
+        # (`private_class_method :new` on a superclass) or come from an extended module, so there is no own-table
+        # gate as on the instance side. It reports only:
+        #
+        # - a constant receiver (`K.x`, `A::K.x`): `self.class.x` or a local may hold a subclass that makes the name
+        #   public again (`public_class_method :new`, a template-method `def self.x`);
+        # - a call inside a `def` ({#load_time_call?}): code that runs while the files load (a class body's
+        #   `ALL = [K.new]` before its `private_class_method :new`) may run before the call is private;
+        # - no class on the chain may have had every singleton name made public (`K.public_class_method(*names)`,
+        #   `K.singleton_class.class_eval { … }`; {#singleton_wildcard_contested?}).
+        def singleton_visibility_mismatch(path, call_node, scope, receiver_type, lexical_sites)
+          class_name = receiver_type.class_name
+          return nil unless call_node.receiver.is_a?(Prism::ConstantReadNode) ||
+                            call_node.receiver.is_a?(Prism::ConstantPathNode)
+          return nil unless private_singleton_candidate?(scope, call_node.name)
+          return nil if load_time_call?(scope, call_node)
+          return nil unless reached_definer_visibility(scope, class_name, call_node.name, :singleton) == :private
+          return nil if missing_hook_on_chain?(scope, class_name, :singleton)
+          return nil if singleton_wildcard_contested?(scope, class_name)
+          return nil if refined_method_in_effect?(class_name, call_node, scope, :singleton, lexical_sites)
+
+          build_visibility_mismatch_diagnostic(path, call_node, "singleton(#{class_name})")
+        end
+
+        PRIVATE_NAMES_MEMO = :rigor_check_rules_private_singleton_names
+        private_constant :PRIVATE_NAMES_MEMO
+
+        # Issue #1984 — the table-only gate the singleton side asks before it reads a chain, as the instance side asks
+        # its own table first: whether any class records `name` private, on its singleton side or on its instance
+        # side (an extended module's private method is private on the extender's singleton). Without it every
+        # `Widget.new` would read, and file the dependency edges of, the whole singleton chain. The set is memoised per
+        # discovery index.
+        def private_singleton_candidate?(scope, name)
+          DependencyRecorder.read_visibility("*", name) if DependencyRecorder.active?
+          discovery = scope.discovery
+          slot = Thread.current[PRIVATE_NAMES_MEMO]
+          unless slot && slot[0].equal?(discovery)
+            slot = [discovery, private_recorded_names(discovery.discovered_method_visibilities)]
+            Thread.current[PRIVATE_NAMES_MEMO] = slot
+          end
+          slot[1].include?(name.to_sym)
+        end
+
+        def private_recorded_names(tables)
+          tables.each_value.with_object(Set.new) do |table, names|
+            table.each { |slot, visibility| names << (slot.is_a?(Array) ? slot.last : slot) if visibility == :private }
+          end
+        end
+
+        # Issue #1984 — whether the call is outside every `def` the file's deferred ranges name. A `def` is named
+        # wherever it is written in a class body, at the top level or in a `class_eval` block, so a call in it is not
+        # load time and may be reported. The top level, class bodies, and blocks and lambdas that are not such a `def`
+        # (a `map { … }` or `define_method` block, a `-> { }`) are load time and decline: such code may run while the
+        # files load, before a later `private_class_method` or in a load order where the private declaration has not
+        # run yet.
+        def load_time_call?(scope, call_node)
+          rows = scope.discovered_deferred_ranges[scope.source_path]
+          return true if rows.nil?
+
+          offset = call_node.location.start_offset
+          # A row with no side (a `def` in a block, a `define_method` name) is a block's range or no range at all.
+          rows.none? { |(start, finish, _name, kind, _owner)| !kind.nil? && start <= offset && offset < finish }
+        end
+
+        SINGLETON_WILDCARD_SLOT = %i[singleton *].freeze
+        private_constant :SINGLETON_WILDCARD_SLOT
+
+        # Issue #1984 — whether a project class on `class_name`'s singleton chain has its wildcard singleton slot
+        # contested: a call the walk saw may have made any of its singleton methods public.
+        def singleton_wildcard_contested?(scope, class_name)
+          discovery = scope.discovery
+          chain = Scope::ResolutionChain.for(scope, class_name.to_s, :singleton, :methods)
+          chain.entries.any? do |entry|
+            DependencyRecorder.read_visibility(entry.name, SINGLETON_WILDCARD_SLOT.last) unless entry.external?
+            !entry.external? && discovery.contested?(:discovered_method_visibilities,
+                                                     [entry.name, SINGLETON_WILDCARD_SLOT])
+          end
+        end
+
+        VISIBILITY_MISSING_HOOKS = %i[method_missing respond_to_missing?].freeze
+        private_constant :VISIBILITY_MISSING_HOOKS
+
+        # Issue #1984 — whether a project entry on `class_name`'s chain for `side` records a `method_missing` or
+        # `respond_to_missing?` on the side that entry stands for (a singleton entry's singleton methods, a mixin's
+        # instance methods), or the chain cannot be read whole. Ruby sends a private call to `method_missing`, so
+        # such a hook may answer it.
+        def missing_hook_on_chain?(scope, class_name, side)
+          chain = Scope::ResolutionChain.for(scope, class_name.to_s, side, :methods)
+          return true if chain.truncated?
+
+          chain.entries.any? do |entry|
+            next false if entry.external?
+
+            kind = entry.side == :singleton ? :singleton : :instance
+            VISIBILITY_MISSING_HOOKS.any? { |hook| records_hook?(scope, entry.name, hook, kind) }
+          end
+        end
+
+        def records_hook?(scope, owner, hook, kind)
+          return true if scope.discovered_method?(owner, hook, kind)
+
+          !(kind == :singleton ? scope.singleton_def_for(owner, hook) : scope.user_def_for(owner, hook)).nil?
         end
 
         # Issue #1568, ADR-119 C1c — the recorded visibility of the definition a call on `class_name` reaches: the
@@ -2899,8 +3191,8 @@ module Rigor
         # producers contest is not alone (`DefinerResolution` asks the next candidate too), so it is `:undecided`
         # there without a read of the table here. nil is nothing recording the name at all, and the class's own
         # visibility stands. An ancestor the project does not declare is passed over, as the method lookup passes it.
-        def reached_definer_visibility(scope, class_name, method_name)
-          case Inference::DefinerResolution.resolve(scope, class_name, method_name, :instance, question: :visibility)
+        def reached_definer_visibility(scope, class_name, method_name, side = :instance)
+          case Inference::DefinerResolution.resolve(scope, class_name, method_name, side, question: :visibility)
           in Inference::DefinerResolution::Known(answer:)
             answer
           in Inference::DefinerResolution::UNKNOWN
@@ -2917,14 +3209,14 @@ module Rigor
           true
         end
 
-        def build_visibility_mismatch_diagnostic(path, call_node, receiver_type)
+        def build_visibility_mismatch_diagnostic(path, call_node, receiver_name)
           Diagnostic.from_message_loc(
             call_node,
             rule: RULE_VISIBILITY_MISMATCH,
             path: path,
-            message: "private method `#{call_node.name}' called on #{receiver_type.class_name} receiver",
+            message: "private method `#{call_node.name}' called on #{receiver_name} receiver",
             severity: :error,
-            receiver_type: receiver_type.class_name,
+            receiver_type: receiver_name,
             method_name: call_node.name.to_s
           )
         end
@@ -3992,6 +4284,9 @@ module Rigor
 
           override_visibility = scope.discovered_method_visibility(class_name, method_name)
           return nil if override_visibility.nil?
+          # Issue #2013 — a contested slot (a later `define_method` or alias gave the name another visibility, or a
+          # write the walk cannot place) proves no reduction.
+          return nil if scope.discovery.contested?(:discovered_method_visibilities, [class_name, method_name])
 
           parent = nearest_ancestor_visibility(scope, class_name, method_name)
           return nil if parent.nil?
@@ -4001,6 +4296,9 @@ module Rigor
           # prove a reduction, stay silent.
           return nil if parent_visibility.nil?
           return nil unless visibility_reduced?(parent_visibility, override_visibility)
+          # Issue #1569 — a module function's instance copy is private because `module_function` made it so; the
+          # author's intent is the public singleton copy, so that reduction is not reported.
+          return nil if scope.module_function_def?(class_name, def_node)
 
           build_override_visibility_diagnostic(
             path, def_node, parent_class, parent_visibility, override_visibility