rigortype 0.4.1 → 0.4.2

data/lib/rigor/analysis/check_rules.rb

@@ -6,6 +6,7 @@ require_relative "../reflection"
 require_relative "../source/node_walker"
 require_relative "../source/constant_path"
 require_relative "../inference/singleton_object_constant"
+require_relative "../inference/object_mixins"
 require_relative "shadow_harness"
 require_relative "../type"
 require_relative "diagnostic"
@@ -29,6 +30,7 @@ require_relative "check_rules/self_closedness_scanner"
 require_relative "check_rules/source_arity"
 require_relative "check_rules/lexical_method_sites"
 require_relative "check_rules/special_global_setters"
+require_relative "check_rules/ruby_deprecations"
 
 module Rigor
   module Analysis
@@ -66,6 +68,17 @@ module Rigor
       # resolution chain's.
       VISIBILITY_RANK = { public: 2, protected: 1, private: 0 }.freeze
 
+      # ADR-35 WD10 (issue #1716) — the object-lifecycle hooks the three override rules skip. `initialize` is
+      # reached through `Class#new` on the class the caller names, and the copy hooks are handed an instance
+      # of the receiver's own class by `dup` / `clone`, so neither is called with the PARENT's declared
+      # arguments through a parent-typed reference; `new` / `dup` / `clone` discard all four returns.
+      LIFECYCLE_HOOKS = %i[initialize initialize_copy initialize_dup initialize_clone].freeze
+
+      # The names CRuby makes private on every non-singleton `def` whatever section it is written in
+      # (`vm_method.c` `rb_method_entry_make`), so a source-discovered visibility for them is not the
+      # runtime one and `def.override-visibility-reduced` cannot prove a reduction.
+      IMPLICITLY_PRIVATE_METHODS = (LIFECYCLE_HOOKS + %i[respond_to_missing?]).freeze
+
       # Resolves a user-supplied rule token (`undefined-method`,
       # `call.undefined-method`, or the family wildcard `call`)
       # to the set of canonical rule identifiers it disables.
@@ -96,8 +109,11 @@ module Rigor
       # direct caller with no plugin walk, e.g. a unit test), the standalone
       # {RuleWalk} walk runs here instead, so `diagnose` stays correct
       # without the converged path.
-      def diagnose(path:, root:, scope_index:, self_call_misses: [], comments: [], disabled_rules: [],
-                   node_collectors: nil)
+      #
+      # @param stated_runtime_ruby — {Configuration#stated_runtime_ruby}: the explicit `target_ruby`, or nil. Only
+      #   {RubyDeprecations} reads it, and it walks the file only when the stated Ruby deprecates something.
+      def diagnose(path:, root:, scope_index:, self_call_misses: [], comments: [], disabled_rules: [], # rubocop:disable Metrics/ParameterLists
+                   node_collectors: nil, stated_runtime_ruby: nil)
         collectors = node_collectors || run_node_collectors(path, root, scope_index)
         diagnostics = collectors[:main_pass].results.dup
         diagnostics.concat(self_undefined_method_diagnostics(path, self_call_misses, root, scope_index))
@@ -109,6 +125,9 @@ module Rigor
         # `suppression.*` joins the list, which stays reportable inside a dead arm — a malformed
         # `# rigor:disable` marker is an authoring error regardless of whether its code runs.
         diagnostics = DeadVersionGuardArms.filter(diagnostics, root)
+        # The ADR-47 WD5 amendment (#1692) — joined after that filter: the deprecation rule reads each version guard
+        # against the stated Ruby itself, and the analyzer's own Ruby says nothing about where the call runs.
+        diagnostics.concat(RubyDeprecations.diagnostics(path, root, scope_index, stated_runtime_ruby))
         # Suppression-marker validation (`suppression.*`) runs BEFORE the filter so its own diagnostics are
         # suppressible like any other rule — `# rigor:disable suppression.unknown-rule` on the offending
         # comment's line works, with no regress (the token itself is known, so it never re-fires).
@@ -166,7 +185,7 @@ module Rigor
         diagnostic = return_type_mismatch_diagnostic(path, node, scope_index)
         return diagnostic if diagnostic.nil? || lexical_sites.nil?
 
-        lexical_sites.refinement_def?(node) ? nil : diagnostic
+        lexical_sites.refinements.refinement_def?(node) ? nil : diagnostic
       end
 
       # Constructs the fresh, unpopulated built-in collector set keyed by
@@ -178,7 +197,7 @@ module Rigor
       # diagnostics carry it (ADR-53 B3c hosts it on the same walk).
       def build_node_collectors(path, scope_index, root = nil)
         eval_ranges = receiver_eval_block_ranges(root)
-        lexical_sites = LexicalMethodSites.new(root)
+        lexical_sites = LexicalMethodSites.new(root, stamped_refinements(scope_index, root))
         main_pass = ->(node) { main_pass_node_diagnostics(path, node, scope_index, eval_ranges, lexical_sites) }
         {
           main_pass: MainPassCollector.new(main_pass),
@@ -252,6 +271,14 @@ module Rigor
         collector.class.new(scope_index).collect(root)
       end
 
+      # Issue #1673 — the in-effect refinements `Inference::ScopeIndexer` stamped for `root`, read off the root's scope
+      # so the rules answer from the query the typer reads; nil where the index holds no scope for it.
+      def stamped_refinements(scope_index, root)
+        return nil if root.nil? || scope_index.nil?
+
+        scope_index[root]&.discovery&.in_effect_refinements
+      end
+
       # The former inline main pass, kept as the shadow oracle: walks the
       # tree with `Source::NodeWalker.each` and accumulates the same
       # per-node diagnostics in the same order {MainPassCollector} now
@@ -259,7 +286,7 @@ module Rigor
       def main_pass_oracle(path, root, scope_index)
         diagnostics = []
         eval_ranges = receiver_eval_block_ranges(root)
-        lexical_sites = LexicalMethodSites.new(root)
+        lexical_sites = LexicalMethodSites.new(root, stamped_refinements(scope_index, root))
         Source::NodeWalker.each(root) do |node|
           diagnostics.concat(main_pass_node_diagnostics(path, node, scope_index, eval_ranges, lexical_sites))
         end
@@ -284,15 +311,15 @@ module Rigor
       def call_node_diagnostics(path, node, scope_index, eval_ranges = nil, lexical_sites = nil)
         [
           undefined_method_diagnostic(path, node, scope_index, lexical_sites),
-          unresolved_toplevel_diagnostic(path, node, scope_index, eval_ranges),
-          wrong_arity_diagnostic(path, node, scope_index),
-          argument_type_diagnostic(path, node, scope_index),
-          nil_receiver_diagnostic(path, node, scope_index),
+          unresolved_toplevel_diagnostic(path, node, scope_index, eval_ranges, lexical_sites),
+          wrong_arity_diagnostic(path, node, scope_index, lexical_sites),
+          argument_type_diagnostic(path, node, scope_index, lexical_sites),
+          nil_receiver_diagnostic(path, node, scope_index, lexical_sites),
           dump_type_diagnostic(path, node, scope_index),
           assert_type_diagnostic(path, node, scope_index),
-          always_raises_diagnostic(path, node, scope_index),
+          always_raises_diagnostic(path, node, scope_index, lexical_sites),
           raise_non_exception_diagnostic(path, node, scope_index),
-          visibility_mismatch_diagnostic(path, node, scope_index)
+          visibility_mismatch_diagnostic(path, node, scope_index, lexical_sites)
         ].compact
       end
 
@@ -316,6 +343,10 @@ module Rigor
       #   Class-level ivars (`@x = 1` outside any def, in the
       #   class body) are also skipped — they're a separate
       #   surface (`Module#@var`) the engine doesn't yet model.
+      # - A divergence the class's RBS declaration admits is withheld: when the ivar is declared (`@x: T`,
+      #   or the slot an `attr_*` member implies) and that type accepts both the first write and the
+      #   later one, the union is the author's intent. The declaration only silences here; checking
+      #   writes against it is #1406.
       def ivar_write_mismatch_diagnostics(path, ivar_writes)
         ivar_writes.flat_map do |class_name, writes_by_ivar|
           writes_by_ivar.flat_map do |ivar_name, writes|
@@ -427,11 +458,18 @@ module Rigor
         writes[(canonical_index + 1)..].filter_map do |write|
           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])
 
           build_ivar_write_mismatch_diagnostic(path, write[:node], class_name, ivar_name, first_class, other_class)
         end
       end
 
+      def declaration_admits?(declared, *write_types)
+        return false if declared.nil?
+
+        write_types.none? { |type| Inference::Acceptance.accepts(declared, type, mode: :gradual).no? }
+      end
+
       # v0.0.2 #6 — diagnostic suppression. Three kinds of
       # suppression compose:
       #
@@ -516,7 +554,7 @@ module Rigor
         line_suppressions = Hash.new { |h, k| h[k] = Set.new }
         file_suppressions = Set.new
         comments.each do |comment|
-          source = comment.location.slice
+          source = comment_text(comment)
           if (match = FILE_SUPPRESSION_PATTERN.match(source))
             absorb_suppression_tokens(match[:rules], file_suppressions)
           elsif (match = LINE_SUPPRESSION_PATTERN.match(source))
@@ -526,6 +564,15 @@ module Rigor
         [line_suppressions, file_suppressions]
       end
 
+      # The comment's text for the suppression regexps. A comment is not validated by Ruby, so it may hold a
+      # byte that is invalid in the file's encoding, and a regexp raises on such a string; the marker grammar
+      # is ASCII, so scrubbing the bad bytes loses nothing. Positions come from `comment.location`, which is
+      # byte-offset based and untouched.
+      def comment_text(comment)
+        text = comment.location.slice
+        text.valid_encoding? ? text : text.scrub("?")
+      end
+
       def absorb_suppression_tokens(raw, target)
         raw.to_s.split(/[\s,]+/).reject(&:empty?).each do |token|
           target.merge(expand_token(token))
@@ -543,7 +590,7 @@ module Rigor
       # that token is known, so acknowledging it never re-fires the rule.
       def suppression_marker_diagnostics(path, comments)
         comments.each_with_object([]) do |comment, diagnostics|
-          source = comment.location.slice
+          source = comment_text(comment)
           if (match = FILE_SUPPRESSION_PATTERN.match(source))
             validate_suppression_tokens(match[:rules], "rigor:disable-file", path, comment, diagnostics)
           elsif (match = LINE_SUPPRESSION_PATTERN.match(source))
@@ -678,13 +725,13 @@ module Rigor
       class << self
         private
 
-        def undefined_method_diagnostic(path, call_node, scope_index, lexical_sites = nil) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        def undefined_method_diagnostic(path, call_node, scope_index, lexical_sites = nil) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
           return nil if call_node.receiver.nil?
 
           scope = scope_index[call_node]
           return nil if scope.nil?
 
-          # The two exemptions that hold whatever shape the receiver has. Ahead of the receiver-shape
+          # The exemptions that hold whatever shape the receiver has. Ahead of the receiver-shape
           # branch below because a plugin is consulted ONCE for the whole receiver, union included, so the
           # gate belongs where that one consult is rather than duplicated into each shape's path.
           #
@@ -722,12 +769,18 @@ module Rigor
           # the recorded name only: `Merger.nope` still fires.
           return nil if Inference::SingletonObjectConstant.recorded?(call_node, receiver_type, call_node.name, scope)
 
+          # Issue #1699 — judged as its one class; the message still names the union. See
+          # {#single_class_literal_union}.
+          rendered_receiver = receiver_type
+          receiver_type = single_class_literal_union(receiver_type)
           class_name = concrete_class_name(receiver_type)
           # A union receiver has no single concrete class. The scalar path
           # below cannot reason about it, but the call is still definitely
           # undefined when EVERY arm lacks the method — see
           # `union_undefined_method_diagnostic`.
-          return union_undefined_method_diagnostic(path, call_node, receiver_type, scope) if class_name.nil?
+          if class_name.nil?
+            return union_undefined_method_diagnostic(path, call_node, receiver_type, scope, lexical_sites)
+          end
 
           # ADR-26 — a plugin may declare a class "open": one
           # known to respond beyond its RBS-declared method
@@ -782,50 +835,107 @@ module Rigor
           # `call.undefined-method` into 171 through exactly this reading, 49 of them here.
           return nil if project_sidecar_owns_method?(scope, class_name, call_node.name, kind)
 
-          build_undefined_method_diagnostic(path, call_node, receiver_type, definition_site, class_name)
+          build_undefined_method_diagnostic(path, call_node, rendered_receiver, definition_site, class_name)
+        end
+
+        # Issue #1717 — an explicit `self.m` / `self.m = v` inside a block whose `self` the engine does not know
+        # (`Scope#block_self_unknown?`, set where issue #316's opaque mark is). The receiver still types as the
+        # ENCLOSING `self`, but the yielding method may `instance_exec` the block on another object
+        # (`ActionController::Renderers.add` runs its block on the controller), so a method missing on the
+        # enclosing `self` is no evidence. The implicit `m` in the same block is already silent; the explicit
+        # spelling must not be stricter. A block
+        # whose `self` IS narrowed (`block_as_methods:`, `define_method`, a `Class.new` body) has cleared the
+        # mark and keeps being checked, unless the narrowing was read off an unknown enclosing `self`.
+        def unknown_block_self_receiver?(call_node, scope)
+          call_node.receiver.is_a?(Prism::SelfNode) && scope.block_self_unknown?
         end
 
         # Issue #1120 — the method exists at THIS call site but not everywhere: a refinement whose `using` is in
         # effect here, or a `def o.m` on the receiver local in this scope. Asked from {#last_resort_surface_answers?},
         # once every project-wide table has come back "absent", so the file walk behind {LexicalMethodSites} runs
         # only for a call about to fire.
-        # A refinement answers instance-side receivers only: a refined singleton (`refine X.singleton_class`) names
-        # no constant target, so nothing records it.
         def lexically_defined_method?(class_name, call_node, scope, kind, lexical_sites)
           return false if lexical_sites.nil?
           return true if lexical_sites.singleton_local_def?(call_node)
-          return false unless kind == :instance
 
-          # ADR-46 — the answer below is a function of every refinement of this name in the project, so the
-          # consumer depends on the name whichever way it answers; a refine body edited in another file must
-          # re-check it (`IncrementalSession#refinement_affected`).
-          DependencyRecorder.read_name(:refinement, call_node.name) if DependencyRecorder.active?
-          modules = refining_modules(scope, class_name, call_node.name)
-          !modules.nil? && lexical_sites.refinement_active?(call_node, modules)
+          refined_method_in_effect?(class_name, call_node, scope, kind, lexical_sites)
         end
 
-        # Issue #1120 — every module that refines `method_name` into `class_name` or one of its ancestors (a
-        # refinement of `Object` reaches a `String` receiver), or nil when none does. The table is empty on a
-        # project that refines nothing, which answers without a lookup.
-        def refining_modules(scope, class_name, method_name)
-          refinements = scope.discovered_refinements
-          return nil if refinements.empty?
+        # Is a refinement of `call_node`'s method name into `class_name` (or an ancestor) in effect at the call?
+        # Issue #1120 asks it for a method the class lacks. The two argument rules ask
+        # {#refined_redefinition_in_effect?} instead (issue #1740), and this only for a class-object receiver.
+        # Typing the call from the refine body is #1664.
+        # A refinement answers instance-side receivers only: a refined singleton (`refine X.singleton_class`) names
+        # no constant target, so nothing records it. Issue #1673 — the answer is derived from the file's in-effect
+        # refinements ({Inference::InEffectRefinements}), the list the typer reads, with each `using` expanded
+        # through its module's includes (issue #1671).
+        #
+        # ADR-121 WD7 — a module in effect whose refinements Rigor cannot read
+        # ({Inference::InEffectRefinements.opaque_module?}: a gem's, one from outside the analysed paths, one with an
+        # unreadable `refine`) may refine any class, a class object's included, so the call declines whatever its
+        # receiver. Issue #1796; both argument rules ask this predicate too.
+        def refined_method_in_effect?(class_name, call_node, scope, kind, lexical_sites)
+          return false if lexical_sites.nil?
+          return true if opaque_refinement_in_effect?(call_node, scope, lexical_sites)
 
-          modules = nil
-          refinements.each do |refined, methods|
-            names = methods[method_name]
-            next if names.nil? || !refined_receiver_class?(scope, class_name, refined)
+          modules =
+            if kind == :instance
+              Inference::InEffectRefinements.refining_modules(scope, class_name, call_node.name)
+            else
+              # ADR-121 WD7 — a row whose class the walk could not name (`refine(k)` with `k` a singleton class)
+              # reaches a class object too.
+              Inference::InEffectRefinements.class_unknown_refining_modules(scope, call_node.name)
+            end
+          !modules.nil? &&
+            lexical_sites.refinements.refinement_active?(call_node.location.start_offset, modules,
+                                                         scope.declared_refinements) do |name|
+              Inference::InEffectRefinements.activated_modules(scope, name)
+            end
+        end
 
-            (modules ||= []).concat(names)
+        # Issues #1663, #1740 — the decline `call.wrong-arity` and `call.argument-type-mismatch` ask once a report
+        # would fire: a refinement that REDEFINES a method the class already has replaces the signature those rules
+        # check against, but Ruby finds a method the receiver's class (or a nearer ancestor) defines before it
+        # consults an ancestor's refinement (`refine Object do def center(a, b, c)` leaves `"x".center(1, 2, 3)` an
+        # `ArgumentError`). It stands on its own rather than behind {#refined_method_in_effect?}, whose ancestor
+        # reach declines `class Inc; def bar(a); include N; end` under `refine N do def bar(a, b, c)` (issue #1797).
+        #
+        # A call with nothing in effect is checked. Otherwise it reports only from positive knowledge: the list
+        # carries no unknown marker and no opaque module, and {Inference::RefinedDispatch::OwnMethod} proves the
+        # receiver's own definer answers first. A class-object receiver keeps {#refined_method_in_effect?}'s
+        # answer: its singleton-side levels are not walked yet.
+        def refined_redefinition_in_effect?(class_name, call_node, scope, kind, lexical_sites)
+          return false if lexical_sites.nil?
+
+          list = refinement_list_at(call_node, scope, lexical_sites)
+          return false if list.empty?
+          return true if list.include?(Inference::InEffectRefinements::UNKNOWN)
+          return true if opaque_refinement_in_effect?(call_node, scope, lexical_sites)
+          return refined_method_in_effect?(class_name, call_node, scope, kind, lexical_sites) unless kind == :instance
+
+          !Inference::RefinedDispatch::OwnMethod.answers?(scope, class_name, call_node.name, list)
+        end
+
+        # The in-effect list at the call as the typer reads it: the lexical activations, each `using` expanded,
+        # then the plugin-declared modules (#1667).
+        def refinement_list_at(call_node, scope, lexical_sites)
+          query = lexical_sites.refinements
+          declared = scope.declared_refinements
+          return Inference::InEffectRefinements::EMPTY if query.empty? && declared.empty?
+
+          query.at(call_node.location.start_offset, declared) do |name|
+            Inference::InEffectRefinements.activated_modules(scope, name)
           end
-          modules
         end
 
-        def refined_receiver_class?(scope, class_name, refined)
-          return true if class_name == refined
+        # ADR-121 WD7 — does the call's in-effect list (its lexical activations, each `using` expanded; a
+        # plugin-declared module is the plugin's declaration and never opaque) hold an opaque module?
+        def opaque_refinement_in_effect?(call_node, scope, lexical_sites)
+          query = lexical_sites.refinements
+          return false if query.empty?
 
-          environment = scope.environment
-          !environment.nil? && environment.class_ordering(class_name, refined) == :subclass
+          list = Inference::InEffectRefinements.lexical_list(scope, query, call_node.location.start_offset)
+          Inference::InEffectRefinements.opaque_in?(scope, list)
         end
 
         # The probes that run only once every cheaper answer has come back "absent", kept together
@@ -858,10 +968,25 @@ module Rigor
           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)
 
           ancestry_declares_method?(scope, class_name, call_node.name, kind)
         end
 
+        # Issue #1697 — a module the project mixes into `Object` (a top-level `include M`, or `include M` in
+        # `class Object`) gives every object its instance methods, and the RBS lookup above only saw core's
+        # `Object`. A class object is an `Object` whatever class it is, so the singleton side always reaches
+        # it; the instance side does when the receiver's class descends from `Object`. A mixed-in module
+        # whose surface is unknown, or a `module_function` reached only privately, does not count here
+        # ({Inference::ObjectMixins.may_define?}).
+        def object_mixin_may_define?(receiver_type, class_name, method_name, scope)
+          unless receiver_type.is_a?(Type::Singleton) || Inference::ObjectMixins.reaches_object?(scope, class_name)
+            return false
+          end
+
+          Inference::ObjectMixins.may_define?(scope, method_name, receiver: :explicit)
+        end
+
         # Issue #739 — the singleton twin of the module-mixin receiver, and the only shape that reaches the
         # singleton side legitimately. `self.class` inside a mixin's instance method is the INCLUDER's class
         # at runtime; the engine types it `Singleton[<the module>]`, one hop along from the same wrong
@@ -999,6 +1124,15 @@ module Rigor
         # 3. The standard `Kernel` / `Object` private-method
         #    surface (`puts`, `p`, `require`, `loop`, `raise`,
         #    …) drawn from the loaded RBS environment.
+        # 4. The private singleton methods of the top-level `main`
+        #    object (`using`, `include`, `public`, `private`,
+        #    `define_method`), read from RBS core's
+        #    `RBS::Unnamed::TopLevelSelfClass`, plus
+        #    `ruby2_keywords` (issue #1383).
+        # 5. The instance methods of a module the project mixes
+        #    into `Object` — a top-level `include M`, or an
+        #    `include M` in `class Object` — or any call at all
+        #    when such a module's surface is unknown (issue #1697).
         #
         # The rule deliberately does NOT generalise to
         # implicit-self calls inside `def` / `class` / `module`
@@ -1010,7 +1144,7 @@ module Rigor
         # Authored severity is `:warning`; the severity profile
         # remaps it (`strict` → `:error`, `balanced` →
         # `:warning`, `lenient` → `:off` / suppressed).
-        def unresolved_toplevel_diagnostic(path, call_node, scope_index, eval_ranges = nil)
+        def unresolved_toplevel_diagnostic(path, call_node, scope_index, eval_ranges = nil, lexical_sites = nil)
           return nil unless call_node.receiver.nil?
 
           scope = scope_index[call_node]
@@ -1021,15 +1155,38 @@ 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)
+          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
           # but leaves the eval body with a nil `self_type`, so `toplevel?` still holds. An eval
           # 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)
 
           build_unresolved_toplevel_diagnostic(path, call_node)
         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.
+        # rbs 3.x has no `TopLevelSelfClass`, so there only `ruby2_keywords` is covered.
+        # A call inside a top-level block (`describe do include M end`) is judged here too;
+        # silencing it is the cheaper error.
+        MAIN_SINGLETON_CLASS_NAME = "RBS::Unnamed::TopLevelSelfClass"
+        MAIN_SINGLETON_METHODS_MISSING_FROM_RBS = %i[ruby2_keywords].freeze
+        private_constant :MAIN_SINGLETON_CLASS_NAME, :MAIN_SINGLETON_METHODS_MISSING_FROM_RBS
+
+        def main_singleton_method?(name, scope)
+          return true if MAIN_SINGLETON_METHODS_MISSING_FROM_RBS.include?(name)
+          # `TopLevelSelfClass < Object`: when the project's own RBS broke `Object`, building it would only
+          # fail again and report a second, unfixable class name beside `Object` (#696's report).
+          return false if Rigor::Reflection.instance_definition("Object", scope: scope).nil?
+
+          !Rigor::Reflection.instance_method_definition(MAIN_SINGLETON_CLASS_NAME, name, scope: scope).nil?
+        end
+
         # ScopeIndexer keeps RECEIVER_EVAL_CALLS private; this list is the same family
         # (`class_eval` / `module_eval` / `class_exec` / `module_exec` / `instance_eval` /
         # `instance_exec`). Used only to decline ADR-34 inside those blocks.
@@ -1305,8 +1462,11 @@ module Rigor
         # - ADR-67 WD6b — an inferred-parameter receiver's type is an open-call-site lower bound, so firing
         #   undefined-method against it is a false positive by construction.
         # - Issue #653 — a plugin answered this call site ({#plugin_typed_call?}).
+        # - Issue #1717 — an explicit `self` receiver in a block whose `self` is unmodelled
+        #   ({#unknown_block_self_receiver?}).
         def call_site_exempt?(call_node, scope)
-          inferred_param_receiver?(call_node, scope) || plugin_typed_call?(call_node, scope)
+          inferred_param_receiver?(call_node, scope) || plugin_typed_call?(call_node, scope) ||
+            unknown_block_self_receiver?(call_node, scope)
         end
 
         # Issue #653 — true when a plugin's `dynamic_return` supplied the return type for THIS call node
@@ -1568,7 +1728,7 @@ module Rigor
         # when the call's receiver / RBS coverage / call shape
         # disqualifies the rule.
         # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-        def wrong_arity_diagnostic(path, call_node, scope_index)
+        def wrong_arity_diagnostic(path, call_node, scope_index, lexical_sites = nil)
           return nil if call_node.receiver.nil?
           return nil unless plain_positional_call?(call_node)
 
@@ -1609,11 +1769,18 @@ module Rigor
             source_arity&.settle_by_definitions
             return nil
           end
+          return nil if arity_report_withheld?(source_arity, class_name, call_node, scope, kind, lexical_sites)
+
+          build_arity_diagnostic(path, call_node, class_name, min, max, actual)
+        end
+
+        # The declines `call.wrong-arity` asks only once the arity is out of the envelope.
+        def arity_report_withheld?(source_arity, class_name, call_node, scope, kind, lexical_sites)
           # Issue #992 — a source envelope's remaining declines can only withhold, so they run only now.
           source_arity&.settle_by_walk
-          return nil if source_arity && !source_arity.authoritative?(class_name)
+          return true if source_arity && !source_arity.authoritative?(class_name)
 
-          build_arity_diagnostic(path, call_node, class_name, min, max, actual)
+          refined_redefinition_in_effect?(class_name, call_node, scope, kind, lexical_sites)
         end
 
         # The `[min, max]` the call is checked against — a declared signature's, or (issue #992) the project
@@ -1813,7 +1980,7 @@ module Rigor
         # and union receivers where every member already
         # disqualifies the call (avoid duplicating the
         # undefined-method diagnostic).
-        def nil_receiver_diagnostic(path, call_node, scope_index)
+        def nil_receiver_diagnostic(path, call_node, scope_index, lexical_sites = nil)
           return nil if call_node.receiver.nil?
           # Safe-navigation calls (`recv&.method`) already
           # short-circuit on nil at runtime, so a nil-bearing
@@ -1862,10 +2029,22 @@ module Rigor
           return nil unless Rigor::Reflection.rbs_class_known?("NilClass", scope: scope)
 
           return nil unless nil_bearing_union_witnesses?(receiver_type, call_node.name, scope)
+          return nil if nil_receiver_withheld?(call_node, receiver_type, scope, scope_index, lexical_sites)
 
           build_nil_receiver_diagnostic(path, call_node)
         end
 
+        # The declines `call.possible-nil-receiver` asks only once a report would fire.
+        def nil_receiver_withheld?(call_node, receiver_type, scope, scope_index, lexical_sites)
+          # Issue #1703 — a `nil` that only a `key?` guard on the same receiver and key rules out. It re-walks the file
+          # once with guards on, and only to withhold this report.
+          return true if Inference::KeyPresenceGuard.withholds_nil?(call_node, receiver_type, lexical_sites&.root,
+                                                                    scope_index)
+
+          # ADR-121 WD7 — a refinement of `NilClass` (or one Rigor cannot read) in effect may define the name.
+          refined_method_in_effect?("NilClass", call_node, scope, :instance, lexical_sites)
+        end
+
         # The receiver-type half of the rule, factored out of the node-shape
         # guards above: the union must carry nil, must carry a non-nil arm the
         # presence question can be asked of, must support the method on every
@@ -1957,7 +2136,9 @@ module Rigor
 
           # 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.
-          ancestry_declares_method?(scope, class_name, method_name, :instance)
+          return true if ancestry_declares_method?(scope, class_name, method_name, :instance)
+
+          object_mixin_may_define?(member, class_name, method_name, scope)
         end
 
         def nil_class_has_method?(method_name, scope)
@@ -1984,7 +2165,7 @@ module Rigor
         # `possible-nil-receiver` rule, safe-navigation, and ADR-58
         # declaration-sourced nil. Slice 1 handles pure non-nil unions
         # (e.g. `String | Symbol`).
-        def union_undefined_method_diagnostic(path, call_node, receiver_type, scope)
+        def union_undefined_method_diagnostic(path, call_node, receiver_type, scope, lexical_sites = nil)
           return nil unless receiver_type.is_a?(Type::Union)
           return nil if call_node.safe_navigation?
 
@@ -2006,10 +2187,44 @@ module Rigor
           # `.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)
 
           build_undefined_method_diagnostic(path, call_node, receiver_type)
         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|
+            refined_method_in_effect?(concrete_class_name(member), call_node, scope, :instance, lexical_sites)
+          end
+        end
+
+        # Issue #1699 — a union of one class's literals, alone or beside that class's plain nominal
+        # (`0 | Integer`, which `gets.to_i` types; `"a" | "b"`; `1 | 2`), holds nothing but instances of
+        # that class, so it answers a method-existence question exactly as the class does. The union rule
+        # above declines it through its distinct-class guard, which exists for SHAPE joins
+        # (`Hash[K1, V1] | Hash[K2, V2]`, a corpus misinference on mail), and the scalar rule declined it
+        # for having no single concrete class, so neither judged it. Returns that class's nominal, or `type`
+        # itself. Literal-and-plain-nominal arms only: a generic, shape or refinement arm keeps the union
+        # declined, and so does a union spanning two classes.
+        def single_class_literal_union(type)
+          return type unless type.is_a?(Type::Union)
+
+          members = type.members
+          return type unless members.any?(Type::Constant)
+          return type unless members.all? do |member|
+            member.is_a?(Type::Constant) || (member.is_a?(Type::Nominal) && member.type_args.empty?)
+          end
+
+          class_names = members.map { |member| concrete_class_name(member) }.uniq
+          return type unless class_names.size == 1
+
+          class_name = class_names.first
+          return type if class_name.nil? || class_name == "NilClass"
+
+          Type::Combinator.nominal_of(class_name)
+        end
+
         # An arm that makes a sound "undefined on every arm" verdict impossible: a non-class surface
         # (Dynamic / Top / Bot), a singleton (slice 1 reasons about instance arms only), the generic
         # metaclass `Class` / `Module` (a value typed as one is *some* class/module object whose singleton
@@ -2150,9 +2365,13 @@ module Rigor
         INTEGER_RAISING_OPERATORS = %i[/ % div modulo divmod].freeze
         private_constant :INTEGER_RAISING_OPERATORS
 
-        def always_raises_diagnostic(path, call_node, scope_index)
+        def always_raises_diagnostic(path, call_node, scope_index, lexical_sites = nil)
           return nil unless integer_zero_division?(call_node, scope_index)
 
+          # ADR-121 WD7 — a refinement of `Integer`'s operator (or one Rigor cannot read) in effect may not raise.
+          scope = scope_index[call_node]
+          return nil if refined_method_in_effect?("Integer", call_node, scope, :instance, lexical_sites)
+
           build_always_raises_diagnostic(path, call_node)
         end
 
@@ -2493,7 +2712,7 @@ module Rigor
           names = [method_name, *GLOBAL_WRITE_HATCHES]
           census = global_write_census(scope)
           program_may_answer?(ancestors, names, census, scope) ||
-            (method_name == :write && refined_writer_in_effect?(census, node, lexical_sites))
+            (method_name == :write && refined_writer_in_effect?(census, node, scope, lexical_sites))
         end
 
         def overridden_hatch?(definition)
@@ -2549,9 +2768,10 @@ module Rigor
         # refine(T)`), so a refined `write` on any class declines every literal. `respond_to?(:write)` honours an
         # 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, lexical_sites)
+        def refined_writer_in_effect?(census, node, scope, lexical_sites)
           Inference::GlobalWriteCensus.refines_write?(census) &&
-            (lexical_sites.nil? || lexical_sites.using_in_effect?(node))
+            (lexical_sites.nil? || !scope.declared_refinements.empty? ||
+              lexical_sites.refinements.any_at?(node.location.start_offset))
         end
 
         def build_global_write_type_diagnostic(path, node, contract, class_name)
@@ -2634,7 +2854,7 @@ 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}).
-        def visibility_mismatch_diagnostic(path, call_node, scope_index)
+        def visibility_mismatch_diagnostic(path, call_node, scope_index, lexical_sites = nil)
           return nil unless explicit_non_self_receiver?(call_node.receiver)
 
           scope = scope_index[call_node]
@@ -2653,6 +2873,8 @@ module Rigor
           reached = reached_definer_visibility(scope, receiver_type.class_name, call_node.name)
           return nil if reached == :undecided
           return nil unless reached.nil? || reached == :private
+          # 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)
         end
@@ -2905,7 +3127,7 @@ module Rigor
         COERCE_DISPATCH_METHODS = %i[+ - * / % ** & | ^ << >> < > <= >=].to_set.freeze
         private_constant :COERCE_DISPATCH_METHODS
 
-        def argument_type_diagnostic(path, call_node, scope_index)
+        def argument_type_diagnostic(path, call_node, scope_index, lexical_sites = nil)
           return nil if call_node.receiver.nil?
           return nil if UNIVERSAL_EQUALITY_METHODS.include?(call_node.name)
           return nil unless plain_positional_call?(call_node)
@@ -2932,11 +3154,19 @@ module Rigor
           param_overrides = Rigor::RbsExtended.param_type_override_map(method_def, environment: scope.environment)
           mismatch = argument_mismatch(method_def.method_types, call_node, scope, param_overrides, scope_index)
           return nil if mismatch.nil?
-          return nil if inferred_param_mismatch_verdict?(call_node, mismatch, scope)
+          return nil if argument_report_withheld?(receiver_type, class_name, call_node, mismatch, scope, lexical_sites)
 
           build_argument_type_diagnostic(path, call_node, class_name, mismatch)
         end
 
+        # The declines `call.argument-type-mismatch` asks only once an argument mismatches.
+        def argument_report_withheld?(receiver_type, class_name, call_node, mismatch, scope, lexical_sites)
+          return true if inferred_param_mismatch_verdict?(call_node, mismatch, scope)
+
+          kind = receiver_type.is_a?(Type::Singleton) ? :singleton : :instance
+          refined_redefinition_in_effect?(class_name, call_node, scope, kind, lexical_sites)
+        end
+
         # ADR-67 WD6b — an argument-type-mismatch verdict resting on an open-call-site lower bound, on
         # either side of the call. The ARGUMENT side: the mismatching argument is an inferred-parameter
         # local, so firing against it is an FP by construction. The RECEIVER side: when the receiver roots
@@ -3738,6 +3968,7 @@ module Rigor
         # silent.
         def override_visibility_diagnostic(path, def_node, scope_index)
           return nil unless def_node.receiver.nil? # instance methods only
+          return nil if IMPLICITLY_PRIVATE_METHODS.include?(def_node.name)
 
           scope = scope_index[def_node]
           return nil if scope.nil?
@@ -3869,6 +4100,7 @@ module Rigor
         # fire) when any gate is unmet.
         def resolve_authored_override(def_node, scope_index)
           return nil unless def_node.receiver.nil? # instance methods only (singleton: follow-on)
+          return nil if LIFECYCLE_HOOKS.include?(def_node.name) # ADR-35 WD10: outside substitutability
 
           scope = scope_index[def_node]
           return nil if scope.nil?