rigortype 0.4.2 → 0.4.4

data/lib/rigor/inference/narrowing.rb

@@ -511,7 +511,8 @@ module Rigor
       # none of the condition shapes are recognised, both returned scopes equal the input
       # scope. The catalogue mirrors {.case_equality_target_class}: static class/module
       # constants narrow as `is_a?`; integer/float-endpoint ranges narrow to `Numeric`;
-      # string-endpoint ranges and regexp literals narrow to `String`.
+      # string-endpoint ranges and regexp literals narrow to `String`; a `nil`, `true` or
+      # `false` literal narrows as its class does ({.when_condition_class}).
       def case_when_scopes(subject, conditions, scope)
         # C1 — `case x when /re/` runs `/re/ === x`, which sets the regex match-data globals
         # exactly as a successful `=~` does. Narrow `$~`/`$&`/`$1..$N` on the clause body (the
@@ -535,6 +536,30 @@ module Rigor
       CASE_SUBJECT_KINDS = %i[local ivar global constant].freeze
       private_constant :CASE_SUBJECT_KINDS
 
+      # Returns `[body_scope, falsey_scope]` for one clause of a `case` with a subject: a `when` clause narrows
+      # through {.case_when_scopes}, and an `in` clause only for a bare class pattern ({.bare_class_pattern_node}),
+      # which matches exactly when `subject.is_a?(C)`. Every other pattern can fail to match where a class test
+      # passes (deconstruction arity, hash keys, a guard), so it narrows neither edge. The pattern's bindings are
+      # the caller's to apply.
+      def case_clause_scopes(subject, clause, scope)
+        return case_when_scopes(subject, clause.conditions, scope) if clause.is_a?(Prism::WhenNode)
+
+        class_node = bare_class_pattern_node(clause.pattern)
+        class_node ? case_when_scopes(subject, [class_node], scope) : [scope, scope]
+      end
+
+      # ADR-47 WD3a — the class-constant node of a `in C` / `in C => x` pattern (the only `in` shapes whose match is
+      # pure `is_a?`), or nil for any pattern that deconstructs, binds, or matches a value.
+      def bare_class_pattern_node(pattern)
+        case pattern
+        when Prism::ConstantReadNode, Prism::ConstantPathNode
+          pattern
+        when Prism::CapturePatternNode
+          value = pattern.value
+          value if value.is_a?(Prism::ConstantReadNode) || value.is_a?(Prism::ConstantPathNode)
+        end
+      end
+
       # When the clause has exactly one `RegularExpressionNode` literal condition, narrow the
       # match-data globals on the body edge (same rule as `analyse_regex_match_predicate`'s
       # truthy edge). With multiple regex conditions (`when /a/, /b/`) the body is reachable
@@ -1088,12 +1113,17 @@ module Rigor
         # in {Rigor::Builtins::RegexRefinement::RULES}, the truthy branch narrows further than
         # `String` to the matching imported refinement (e.g. `decimal-int-string` for `\d+`).
         # Bodies outside the table fall back to the v0.1.0 baseline (plain `String`).
+        #
+        # The match rebinds `$~` and the other match globals on both edges, and this rule binds none of them (#1482),
+        # so each edge forgets what an earlier match bound. The statement evaluator's walk already forgets them in the
+        # scope the match leaves; the per-node scope walk of a conditional it did not enter narrows from the scope
+        # before the match, where the falsey edge of an earlier `=~` had bound `$1` to `nil` (#1495).
         def analyse_match_write(node, scope)
           string_t = Type::Combinator.nominal_of("String")
           nil_t = Type::Combinator.constant_of(nil)
           refinements = match_write_capture_refinements(node)
-          truthy = scope
-          falsey = scope
+          truthy = scope.forget_match_globals
+          falsey = truthy
           node.targets.each do |target|
             next unless target.is_a?(Prism::LocalVariableTargetNode)
 
@@ -1575,23 +1605,59 @@ module Rigor
         end
 
         # Survey item (b): `/regex/ =~ str` and `str =~ /regex/` bind the regex match-data
-        # globals on each edge.
+        # globals on each edge ({#regex_match_edges}), gated on the subject (#1494): an edge is
+        # narrowed only when the receiver proves what the frame holds on it
+        # ({#match_receiver_edges}), and an edge it cannot vouch for keeps the match globals
+        # forgotten. A `String?` subject keeps the match edge only, since `NilClass#=~` answers
+        # nil with the previous match still bound; an untyped one is read the same way.
         #
-        # - Truthy edge (`=~` returned an Integer position — the match succeeded): `$~` to
+        # Returns nil (no narrowing) when the receiver / argument pair does not resolve to exactly one
+        # regex pattern we can count (see {#regex_match_pattern}).
+        def analyse_regex_match_predicate(node, scope)
+          gated_regex_match_edges(node, scope)
+        end
+
+        # Issue #1379 — `subject !~ pattern` is `Kernel#!~`, which returns `!(subject =~ pattern)`. It runs the same
+        # match in the caller's frame, so its edges are {#analyse_regex_match_predicate}'s swapped: the falsey edge is
+        # the match edge (`$~` a `MatchData`, an unconditional `$N` a `String`, and the whole-receiver refinement), the
+        # truthy edge the no-match edge (`$~` and `$N` nil). The same patterns are recognised and the same ones
+        # declined (a non-regex operand, an ambiguous constant, `//x`), and the receiver gates the edges alike.
+        def analyse_regex_not_match_predicate(node, scope)
+          gated_regex_match_edges(node, scope)&.reverse
+        end
+
+        # `[match_edge, no_match_edge]` of a `=~` / `!~` predicate, each kept only where
+        # {#match_receiver_edges} lets it be; an edge it cannot vouch for is the entry scope with the
+        # match globals forgotten, since the call may still have rebound them. The whole-receiver
+        # refinement is kept only when the local it would narrow is known to be a String on the
+        # match edge ({#refinable_operand?}).
+        def gated_regex_match_edges(node, scope)
+          edges = regex_match_edges(node, scope, refine: refinable_operand?(node, scope))
+          return nil if edges.nil?
+
+          match, no_match = edges
+          forgotten = scope.forget_match_globals
+          case match_receiver_edges(node, scope)
+          when :both then [match, no_match]
+          when :match then [match, forgotten]
+          else [forgotten, forgotten]
+          end
+        end
+
+        # The ungated edges of a match:
+        #
+        # - Match edge (`=~` returned an Integer position — the match succeeded): `$~` to
         #   `Nominal[MatchData]`; `$&` and `$1..$N` (where N is the number of capture groups in
         #   the regex source) to `Nominal[String]`. This is the same optimistic-narrowing shape
         #   the existing `analyse_match_write` uses for named captures inside `if /(?<x>...)/
         #   =~ str` — optional groups in the regex source (`(\d+)?`) would bind `$N` to `nil`
         #   at runtime, but the floor here matches the common idiom (required captures) and
         #   lets `unless /(\d+)/ =~ s; raise; end; $1.to_i` resolve cleanly.
-        # - Falsey edge (`=~` returned nil — no match): `$~` and every numbered / back-reference
+        # - No-match edge (`=~` returned nil): `$~` and every numbered / back-reference
         #   global bound to `Constant<nil>`.
         #
-        # Returns nil (no narrowing) when the receiver / argument pair does not resolve to exactly one
-        # regex pattern we can count (see {#regex_match_pattern}).
-        #
         # `refine: false` leaves out the whole-receiver refinement, which names a String.
-        def analyse_regex_match_predicate(node, scope, refine: true)
+        def regex_match_edges(node, scope, refine:)
           return nil if node.arguments.nil?
           return nil unless node.arguments.arguments.size == 1
 
@@ -1615,90 +1681,113 @@ module Rigor
           [truthy, falsey]
         end
 
-        # Issue #1379 — `subject !~ pattern` is `Kernel#!~`, which returns `!(subject =~ pattern)`. It runs the same
-        # match in the caller's frame, so its edges are {#analyse_regex_match_predicate}'s swapped: the falsey edge is
-        # the match edge (`$~` a `MatchData`, an unconditional `$N` a `String`, and the whole-receiver refinement), the
-        # truthy edge the no-match edge (`$~` and `$N` nil). The same patterns are recognised and the same ones
-        # declined (a non-regex operand, an ambiguous constant, `//x`).
-        #
-        # Unlike `=~`'s, an edge here is narrowed only when the receiver proves what the frame holds on it
-        # ({#not_match_receiver_edges}). An edge it cannot vouch for keeps the match globals forgotten, since the call
-        # may still have rebound them. The refinement is kept only when the local it would narrow is known to be a
-        # String on the match edge ({#refinable_operand?}).
-        def analyse_regex_not_match_predicate(node, scope)
-          edges = analyse_regex_match_predicate(node, scope, refine: refinable_operand?(node, scope))
-          return nil if edges.nil?
-
-          match, no_match = edges
-          forgotten = scope.forget_match_globals
-          case not_match_receiver_edges(node, scope)
-          when :both then [no_match, match]
-          when :match then [forgotten, match]
-          else [forgotten, forgotten]
-          end
-        end
-
-        # Which edges of `recv !~ pattern` the receiver lets {#analyse_regex_not_match_predicate} narrow. `Kernel#!~`
-        # dispatches `=~` on the receiver:
+        # Which edges of `recv =~ pattern` / `recv !~ pattern` the receiver lets {#gated_regex_match_edges} narrow:
+        # `:both`, `:match` (the match edge only) or nil. `Kernel#!~` dispatches `=~` on the receiver:
         #
         # - A Regexp receiver (the pattern on the left) runs `Regexp#=~`, which sets `$~` on both outcomes, a `nil`
         #   argument included: `:both`.
-        # - `String#=~` and `Symbol#=~` do the same: `:both` when every member of the receiver's type is a String or a
-        #   Symbol.
+        # - `String#=~` and `Symbol#=~` do the same: `:both` when every member of the receiver's type is a String
+        #   (a project subclass of String included) or a Symbol.
         # - `NilClass#=~` answers nil and leaves `$~` alone, so a nil receiver reaches the no-match edge with the
         #   previous match still bound; it never reaches the match edge. A `Dynamic` receiver may be nil at run time
-        #   whatever its static facet says: `:match` when every member is a String, a Symbol, nil, or a `Dynamic`
-        #   that is untyped or whose facet holds only those.
-        # - Any other receiver may define `=~` in Ruby, which binds `$~` in its own frame, not the caller's: nil.
+        #   whatever its static facet says. So does a safe-navigation call, which answers nil without matching on a
+        #   nil receiver.
         #
-        # A safe-navigation `recv&.!~(pattern)` answers nil without matching on a nil receiver, so it declines too.
-        def not_match_receiver_edges(node, scope)
-          return nil if node.receiver.nil? || node.safe_navigation?
-          return :both if regex_operand_pattern(node.receiver, scope).is_a?(RegexMatchPattern)
+        # The two operators part over a receiver that is none of those ({#match_operator_edges},
+        # {#not_match_operator_edges}).
+        def match_receiver_edges(node, scope)
+          return nil if node.receiver.nil?
+
+          edges =
+            if regex_operand_pattern(node.receiver, scope).is_a?(RegexMatchPattern)
+              :both
+            else
+              kinds = match_member_kinds(scope.type_of(node.receiver), scope)
+              node.name == :=~ ? match_operator_edges(kinds) : not_match_operator_edges(kinds)
+            end
+          return edges unless node.safe_navigation?
 
-          kinds = not_match_member_kinds(scope.type_of(node.receiver), scope)
-          return :both if kinds.all? { |kind| %i[string symbol].include?(kind) }
+          :match if edges && node.name == :=~
+        end
+
+        STRING_MATCH_KINDS = %i[string string_subclass symbol].freeze
+        private_constant :STRING_MATCH_KINDS
 
-          :match if kinds.all? { |kind| %i[string symbol nil dynamic].include?(kind) }
+        # `recv =~ pattern`'s match edge is the truthy one. Only a member known to define its own `=~` in the
+        # project keeps it out (#1494): that method binds `$~` in its own frame, not the caller's. Any other member
+        # either matches in the caller's frame, answers nil (`NilClass`), or has no `=~` at all (`Integer` since
+        # Ruby 3.2 drops `Object#=~`) and so never reaches the edge; a receiver the analyzer cannot classify keeps the
+        # edge, as every `=~` did before #1494.
+        def match_operator_edges(kinds)
+          return nil if kinds.include?(:custom)
+          return :both if kinds.all? { |kind| STRING_MATCH_KINDS.include?(kind) }
+
+          :match
+        end
+
+        # `recv !~ pattern`'s match edge is the falsey one, which a receiver whose `=~` is not the caller's match
+        # also reaches, so it is kept only when every member is a String, a Symbol, nil, or a `Dynamic` that is
+        # untyped or whose facet holds only those (#1379).
+        def not_match_operator_edges(kinds)
+          return :both if kinds.all? { |kind| STRING_MATCH_KINDS.include?(kind) }
+
+          :match if kinds.all? { |kind| (STRING_MATCH_KINDS + %i[nil dynamic]).include?(kind) }
         end
 
         # Whether the local operand {#apply_whole_receiver_refinement} would narrow holds only Strings and nil, which
         # the match edge excludes. The refinement names a String, so a member that may be a Symbol — a Symbol, or an
-        # untyped `Dynamic` that `Kernel#!~` accepts as the receiver or `Regexp#=~` as the argument — keeps it out:
-        # `return if raw !~ /\A\d+\z/` on an untyped `raw` must not make `raw.to_proc` an undefined method.
+        # untyped `Dynamic` that may be one at run time — keeps it out: `return unless raw =~ /\A\d+\z/` on an untyped
+        # `raw` must not make `raw.to_proc` an undefined method (#1379, #1494).
         def refinable_operand?(node, scope)
           operand = [node.receiver, *node.arguments&.arguments].find { |o| o.is_a?(Prism::LocalVariableReadNode) }
           type = operand && scope.local(operand.name)
           return true if type.nil?
 
-          not_match_member_kinds(type, scope).all? { |kind| %i[string nil].include?(kind) }
+          match_member_kinds(type, scope).all? { |kind| %i[string nil].include?(kind) }
         end
 
-        def not_match_member_kinds(type, scope)
-          (type.is_a?(Type::Union) ? type.members : [type]).map { |member| not_match_member_kind(member, scope) }
+        def match_member_kinds(type, scope)
+          (type.is_a?(Type::Union) ? type.members : [type]).map { |member| match_member_kind(member, scope) }
         end
 
-        # `:string` or `:symbol` for a member {.narrow_not_class} proves a String or a Symbol (a value or refinement of
-        # either, or a class the environment orders below it; a project subclass it cannot order reads as neither),
-        # `:nil`, `:dynamic` for a `Dynamic` whose facet is untyped or holds only Strings, Symbols and nil, or nil for
-        # anything else.
-        def not_match_member_kind(member, scope)
-          return not_match_dynamic_kind(member, scope) if member.is_a?(Type::Dynamic)
+        # `:custom` for a member whose class the project gives a `=~` of its own (in its ancestry, a reopened
+        # `String` included); `:string` or `:symbol` for a member {.narrow_not_class} proves a String or a Symbol (a
+        # value or refinement of either, or a class the environment orders below it); `:string_subclass` for a
+        # project class whose superclass chain reaches `String`, which the environment cannot order; `:nil`;
+        # `:dynamic` for a `Dynamic` whose facet is untyped or holds only Strings, Symbols and nil; or nil for anything
+        # else.
+        def match_member_kind(member, scope)
+          return match_dynamic_kind(member, scope) if member.is_a?(Type::Dynamic)
           return :nil if narrow_nil(member) == member && !member.is_a?(Type::Bot)
+          return :custom if custom_match_operator?(member, scope)
 
           environment = scope.environment
           { "String" => :string, "Symbol" => :symbol }.each do |class_name, kind|
             return kind if narrow_not_class(member, class_name, environment: environment, scope: scope).is_a?(Type::Bot)
           end
-          nil
+          :string_subclass if project_string_subclass?(member, scope)
         end
 
-        def not_match_dynamic_kind(member, scope)
+        def match_dynamic_kind(member, scope)
           facet = member.static_facet
           return :dynamic if facet.is_a?(Type::Top)
 
-          facet_kinds = not_match_member_kinds(facet, scope)
-          :dynamic if facet_kinds.all? { |kind| %i[string symbol nil].include?(kind) }
+          facet_kinds = match_member_kinds(facet, scope)
+          :dynamic if facet_kinds.all? { |kind| (STRING_MATCH_KINDS + [:nil]).include?(kind) }
+        end
+
+        def custom_match_operator?(member, scope)
+          targets = ProjectMethodOwnership.targets(member)
+          return false if targets.nil?
+
+          targets.any? { |class_name, kind| ProjectMethodOwnership.defines?(class_name, :=~, kind, scope) }
+        end
+
+        def project_string_subclass?(member, scope)
+          return false unless member.is_a?(Type::Nominal) && scope.known_user_class?(member.class_name)
+
+          scope.external_ancestor_name_candidates(member.class_name, mixins: false)
+               .flatten.any? { |name| name.to_s.delete_prefix("::") == "String" }
         end
 
         # `str.match?(/\A\d+\z/)` — `String#match?` is a pure boolean predicate whose truthy edge
@@ -2626,6 +2715,21 @@ module Rigor
           ]
         end
 
+        # The class a `when` condition narrows the subject to, as `is_a?` would, or nil when the condition is no class
+        # test Rigor reads: a class or module constant, a range or regexp literal ({.case_equality_target_class}),
+        # or (#1925) a `nil` / `true` / `false` literal. `nil === x` runs `NilClass#===`, which holds only for `nil`
+        # itself whatever the subject's class defines, and `nil` is `NilClass`'s only instance, so `when nil` is
+        # `when NilClass`; `true` and `false` likewise.
+        def when_condition_class(condition, scope)
+          lexical_class_name(condition, scope) || case_equality_target_class(condition) ||
+            SINGLETON_WHEN_LITERAL_CLASSES[unwrap_parens(condition).class]
+        end
+
+        SINGLETON_WHEN_LITERAL_CLASSES = {
+          Prism::NilNode => "NilClass", Prism::TrueNode => "TrueClass", Prism::FalseNode => "FalseClass"
+        }.freeze
+        private_constant :SINGLETON_WHEN_LITERAL_CLASSES
+
         # Maps a case-equality literal receiver to the class whose membership is implied by the
         # truthy edge. `Prism::ParenthesesNode` wrappers are transparently unwrapped (`(1..10)
         # === x` is parsed with the range inside parentheses).  Range literals: integer
@@ -2818,15 +2922,15 @@ module Rigor
         # narrowed type for the subject as if `condition === subject`, and accumulates them.
         # The body's narrowed type is the union across all conditions; the falsey type is the
         # running result after subtracting every condition's class. Conditions whose shape we
-        # cannot statically classify are treated as "no narrowing": the body falls back to the
-        # union of what we did learn (or the entry type when nothing learned), and the falsey
-        # edge is the entry type (because we cannot prove the unknown condition didn't match).
+        # cannot statically classify narrow neither edge: the body reads as
+        # {.case_when_body_type} says, and the falsey edge is the entry type.
         #
         # `[body type, next-clause type]` of a `when` clause's conditions over the subject type `current`.
         def case_when_types(scope, current, conditions)
           truthy_members = []
           falsey_type = current
           fully_narrowable = true
+          unread = false
 
           conditions.each do |condition|
             applied = apply_case_when_condition(scope, current, condition, falsey_type)
@@ -2835,12 +2939,24 @@ module Rigor
               falsey_type = applied[:falsey]
               fully_narrowable &&= applied[:fully_narrowable]
             else
+              unread = true
               fully_narrowable = false
             end
           end
 
-          truthy = truthy_members.empty? ? current : Type::Combinator.union(*truthy_members)
-          [truthy, fully_narrowable ? falsey_type : current]
+          [case_when_body_type(current, truthy_members, unread), fully_narrowable ? falsey_type : current]
+        end
+
+        # #1925 — the body type of a `when` clause. A clause whose conditions are all unread keeps the entry type. A
+        # clause mixing read conditions with an unread one reads `Dynamic[top]`: the body may run because the unread
+        # condition matched, so the read conditions' union is unsound (`when nil, ""` is not `nil`), and the entry
+        # type is wider than what reaches the body when the unread condition is itself a test
+        # (`when /a/, ->(v) { !v.nil? }` never enters with `nil`), so reading it would report a call no `nil` reaches.
+        def case_when_body_type(current, truthy_members, unread)
+          return current if truthy_members.empty?
+          return Type::Combinator.untyped if unread
+
+          Type::Combinator.union(*truthy_members)
         end
 
         # Per-condition rule. Returns `nil` when the condition shape is not recognised (caller
@@ -2855,7 +2971,7 @@ module Rigor
             return integer_literal_when_result(current, int_literal, falsey_acc)
           end
 
-          target = lexical_class_name(condition, scope) || case_equality_target_class(condition)
+          target = when_condition_class(condition, scope)
           return class_when_result(scope, current, target, falsey_acc) if target
 
           nil

data/lib/rigor/inference/project_patched_definedness_guard.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../source/node_children"
+
+module Rigor
+  module Inference
+    module ProjectPatchedScanner
+      # Finds the `def`s of a `pre_eval:` file written under a definedness guard naming the same method
+      # (`def foo = 1 unless method_defined?(:foo)`): polyfills that run only when nothing bound the name before.
+      module DefinednessGuard
+        DEFINEDNESS_PREDICATES = %i[
+          method_defined? private_method_defined? public_method_defined? protected_method_defined? respond_to?
+        ].freeze
+        INSTANCE_METHOD_LISTS = %i[
+          instance_methods public_instance_methods private_instance_methods protected_instance_methods
+        ].freeze
+        private_constant :DEFINEDNESS_PREDICATES, :INSTANCE_METHOD_LISTS
+
+        module_function
+
+        # The `def` nodes (by identity) that sit on the "name not yet defined" side of a definedness guard naming the
+        # same method: `def foo = 1 unless method_defined?(:foo)`, or the same inside an `unless` / `if !` block.
+        def defs(root)
+          found = {}.compare_by_identity
+          collect_guarded(root, found)
+          found
+        end
+
+        def collect_guarded(node, found)
+          return unless node.is_a?(Prism::Node)
+
+          if node.is_a?(Prism::IfNode) || node.is_a?(Prism::UnlessNode)
+            name, negated = definedness_guard(node.predicate)
+            mark_guarded_defs(undefined_branch(node, negated), name, found) if name
+          end
+          node.rigor_each_child { |child| collect_guarded(child, found) }
+        end
+        private_class_method :collect_guarded
+
+        # `[method_name, negated]` for a predicate like `method_defined?(:m)` / `!respond_to?(:m)`, else nil.
+        def definedness_guard(predicate)
+          predicate = predicate.body if predicate.is_a?(Prism::ParenthesesNode) && predicate.body
+          predicate = predicate.body.first if predicate.is_a?(Prism::StatementsNode) && predicate.body.size == 1
+          if predicate.is_a?(Prism::CallNode) && predicate.name == :! && predicate.receiver
+            name, negated = definedness_guard(predicate.receiver)
+            return name && [name, !negated]
+          end
+          name = guard_method_name(predicate)
+          name && [name, false]
+        end
+        private_class_method :definedness_guard
+
+        def guard_method_name(call)
+          return unless call.is_a?(Prism::CallNode)
+
+          listed = %i[include? member?].include?(call.name)
+          listed &&= call.receiver.is_a?(Prism::CallNode) && INSTANCE_METHOD_LISTS.include?(call.receiver.name)
+          return unless listed || DEFINEDNESS_PREDICATES.include?(call.name)
+
+          arg = call.arguments&.arguments&.first
+          arg.unescaped.to_sym if arg.is_a?(Prism::SymbolNode) || arg.is_a?(Prism::StringNode)
+        end
+        private_class_method :guard_method_name
+
+        # The branch that runs when the guarded name is NOT defined yet.
+        def undefined_branch(node, negated)
+          branch_when_true = node.is_a?(Prism::IfNode) ? node.statements : node.else_clause
+          branch_when_false = node.is_a?(Prism::IfNode) ? node.subsequent : node.statements
+          # The predicate is true when the name is defined (unless negated).
+          negated ? branch_when_true : branch_when_false
+        end
+        private_class_method :undefined_branch
+
+        def mark_guarded_defs(node, name, found)
+          return unless node.is_a?(Prism::Node)
+
+          found[node] = true if node.is_a?(Prism::DefNode) && node.name == name
+          node.rigor_each_child { |child| mark_guarded_defs(child, name, found) } unless node.is_a?(Prism::DefNode)
+        end
+        private_class_method :mark_guarded_defs
+      end
+    end
+  end
+end

data/lib/rigor/inference/project_patched_methods.rb

@@ -36,14 +36,14 @@ module Rigor
       attr_reader :by_key, :write_census
 
       # @param entries — flat list of declarations observed during the pre-pass.
-      #   First-write-wins on `(class_name, method_name, kind)` duplicates so the
+      #   Last-write-wins on `(class_name, method_name, kind)` duplicates, as at runtime (ADR-17); the
       #   `pre-eval.duplicate-declaration` diagnostic emission stays decoupled from registry behaviour.
       # @param write_census — issue #1367: the `pre_eval:` files' {GlobalWriteCensus}, which the `global.*` write
       #   rules join with the project's, since a patch file is loaded ahead of the code it patches.
       def initialize(entries: [], write_census: GlobalWriteCensus::EMPTY)
         @by_key = entries.each_with_object({}) do |entry, acc|
           key = [entry.class_name, entry.method_name, entry.kind]
-          acc[key] ||= entry
+          acc[key] = entry
         end.freeze
         @write_census = write_census.frozen? ? write_census : write_census.dup.freeze
         freeze

data/lib/rigor/inference/project_patched_scanner.rb

@@ -3,6 +3,7 @@
 require "prism"
 
 require_relative "project_patched_methods"
+require_relative "project_patched_definedness_guard"
 require_relative "../analysis/dependency_source_inference/return_type_heuristic"
 require_relative "../source/alias_names"
 require_relative "../source/constant_path"
@@ -35,6 +36,13 @@ module Rigor
       PendingAlias = Data.define(:class_name, :new_name, :old_name, :kind, :source_path, :source_line)
       private_constant :PendingAlias
 
+      # A `def` written under a definedness guard (`def foo ... unless method_defined?(:foo)`): a polyfill that runs
+      # only when nothing bound the name before it, so it never replaces an earlier binding.
+      GuardedDef = Data.define(:entry) do
+        def source_path = entry.source_path
+      end
+      private_constant :GuardedDef
+
       module_function
 
       # @param paths — absolute paths to the pre-eval files. The runner has already
@@ -58,29 +66,28 @@ module Rigor
       end
 
       # ADR-17 § "Failure modes" — when two pre-eval entries declare the same `(class_name, method_name,
-      # kind)` triple, emit one `:info` `pre-eval.duplicate-declaration` diagnostic per collision. The
-      # registry's first-write-wins behaviour is unchanged; the diagnostic just makes the shadowing
-      # visible so users notice when a later patch is silently masked.
+      # kind)` triple, the last-listed one wins, as at runtime where the later `def` replaces the earlier. Emit
+      # one `:info` `pre-eval.duplicate-declaration` diagnostic per SHADOWED entry, reported on that earlier
+      # declaration (the declaration that never takes effect) and naming the
+      # winning declaration it yields to.
       def duplicate_declaration_diagnostics(entries)
-        seen = {}
-        entries.each_with_object([]) do |entry, acc|
-          key = [entry.class_name, entry.method_name, entry.kind]
-          if (first = seen[key])
-            acc << build_diagnostic(
-              path: entry.source_path,
-              line: entry.source_line,
-              column: 1,
-              severity: :info,
-              rule: "pre-eval.duplicate-declaration",
-              message: "pre-eval duplicate declaration: " \
-                       "#{entry.class_name}##{entry.method_name} " \
-                       "(#{entry.kind}) is already declared at " \
-                       "#{first.source_path}:#{first.source_line}. " \
-                       "The first declaration wins; this entry is shadowed."
-            )
-          else
-            seen[key] = entry
-          end
+        winners = entries.to_h { |entry| [[entry.class_name, entry.method_name, entry.kind], entry] }
+        entries.filter_map do |entry|
+          winner = winners[[entry.class_name, entry.method_name, entry.kind]]
+          next if winner.equal?(entry)
+
+          build_diagnostic(
+            path: entry.source_path,
+            line: entry.source_line,
+            column: 1,
+            severity: :info,
+            rule: "pre-eval.duplicate-declaration",
+            message: "pre-eval duplicate declaration: " \
+                     "#{entry.class_name}##{entry.method_name} " \
+                     "(#{entry.kind}) is declared again at " \
+                     "#{winner.source_path}:#{winner.source_line}. " \
+                     "The last-listed declaration wins; this entry is shadowed."
+          )
         end
       end
       private_class_method :duplicate_declaration_diagnostics
@@ -97,14 +104,17 @@ module Rigor
       # Within one file the later binding of a name replaces the earlier, as at runtime: the alias-method-chain
       # idiom (`def foo`, `alias_method :foo_without_x, :foo`, `alias_method :foo, :foo_with_x`) leaves `foo` the
       # alias. Bindings of one name in DIFFERENT files are what `pre-eval.duplicate-declaration` reports, and the
-      # registry keeps the first of those, as it always has for `def`s.
+      # registry keeps the last of those, as Ruby does.
       def resolve_aliases(collected)
         bound = {}
         per_file = collected.group_by(&:source_path).values.map do |items|
           final = {}
           items.each do |item|
             entry = item.is_a?(PendingAlias) ? alias_entry(item, bound) : item
+            entry = entry.entry if entry.is_a?(GuardedDef)
             key = [entry.class_name, entry.method_name, entry.kind]
+            next if item.is_a?(GuardedDef) && bound.key?(key)
+
             bound[key] = entry
             final.delete(key)
             final[key] = entry
@@ -138,6 +148,7 @@ module Rigor
           return
         end
 
+        Thread.current[:rigor_guarded_defs] = DefinednessGuard.defs(parse_result.value)
         walk_node(parse_result.value, [], false, path, entries)
         # Issue #1367 — the file's `global.*` write facts: a patch file may alias a special or give a class the
         # method a setter asks for, as any project file may.
@@ -151,6 +162,8 @@ module Rigor
                    "#{e.class}: #{e.message}. Pre-evaluation skipped for this file; " \
                    "the rest of the run proceeds."
         )
+      ensure
+        Thread.current[:rigor_guarded_defs] = nil
       end
       private_class_method :scan_file
 
@@ -233,11 +246,12 @@ module Rigor
         kind = node.receiver.is_a?(Prism::SelfNode) || in_singleton_class ? :singleton : :instance
         line = node.location&.start_line || 1
         return_type = Analysis::DependencySourceInference::ReturnTypeHeuristic.extract(node)
-        entries << ProjectPatchedMethods::Entry.new(
+        entry = ProjectPatchedMethods::Entry.new(
           class_name: class_name, method_name: node.name, kind: kind,
           source_path: source_path, source_line: line,
           return_type: return_type
         )
+        entries << (Thread.current[:rigor_guarded_defs]&.key?(node) ? GuardedDef.new(entry: entry) : entry)
       end
       private_class_method :record_def_node