rigortype 0.0.1 → 0.0.3

data/lib/rigor/inference/narrowing.rb

@@ -155,6 +155,61 @@ module Rigor
         end
       end
 
+      # Integer-comparison fragment of `type` against an Integer
+      # literal `bound`. Narrows the receiver of `x < n`, `x <= n`,
+      # `x > n`, `x >= n` (and the reversed forms) to the subset of
+      # the existing domain that satisfies the comparison. Hooks in:
+      # - `Constant<Integer>` is preserved when it satisfies the
+      #   comparison, otherwise collapsed to `Bot`.
+      # - `IntegerRange[a..b]` becomes the intersection with the
+      #   half-line implied by the comparison; an empty intersection
+      #   collapses to `Bot`, a single-point intersection collapses
+      #   to `Constant<Integer>`.
+      # - `Nominal[Integer]` becomes the half-line itself (e.g.
+      #   `x > 0` on `Nominal[Integer]` is `positive_int`).
+      # - `Union` narrows each member independently.
+      # - Other carriers (Float, String, Top, Dynamic) flow through
+      #   unchanged: the analyzer does not have a Float-range carrier
+      #   today, and no other carrier participates in numeric ordering.
+      def narrow_integer_comparison(type, comparator, bound)
+        return type unless bound.is_a?(Integer) && %i[< <= > >=].include?(comparator)
+
+        narrow_integer_comparison_dispatch(type, comparator, bound)
+      end
+
+      # Equality fragment of `type` against an Integer `value`.
+      # `Constant<Integer>` is preserved when it equals `value`,
+      # otherwise collapses to `Bot`. `IntegerRange` covers? `value`
+      # narrows to `Constant[value]`; an out-of-range comparison
+      # collapses to `Bot`. `Nominal[Integer]` narrows to
+      # `Constant[value]`. `Union` narrows each member.
+      def narrow_integer_equal(type, value)
+        return type unless value.is_a?(Integer)
+
+        narrow_integer_equal_dispatch(type, value)
+      end
+
+      # Complement of {.narrow_integer_equal}. Removes a single
+      # integer value from the domain when one endpoint of an
+      # `IntegerRange` is exactly that value (so the result stays a
+      # contiguous range). Domains where the value sits strictly
+      # between the endpoints stay unchanged: punching a hole would
+      # require a two-piece carrier the lattice does not yet model.
+      def narrow_integer_not_equal(type, value)
+        return type unless value.is_a?(Integer)
+
+        case type
+        when Type::Constant
+          type.value == value ? Type::Combinator.bot : type
+        when Type::IntegerRange
+          narrow_integer_range_not_equal(type, value)
+        when Type::Union
+          Type::Combinator.union(*type.members.map { |m| narrow_integer_not_equal(m, value) })
+        else
+          type
+        end
+      end
+
       # Class-membership fragment of `type`: the subset whose
       # inhabitants are instances of `class_name` (or its subclasses
       # when `exact: false`). `class_name` is the qualified name of
@@ -424,10 +479,49 @@ module Rigor
           # `rigor:v1:predicate-if-true` / `predicate-if-false`
           # annotations, apply them to narrow the corresponding
           # local-variable arguments on each edge.
-          analyse_rbs_extended_predicate(node, scope)
+          predicate_result = analyse_rbs_extended_predicate(node, scope)
+          assert_result = analyse_rbs_extended_assert_if(node, scope)
+          merge_extended_results(predicate_result, assert_result, scope)
+        end
+
+        # Combines two `[truthy_scope, falsey_scope]` pair
+        # results from sibling RBS::Extended analysers
+        # (`predicate-if-*` and `assert-if-*`). When only one
+        # side fires, return it directly; when both fire the
+        # right side's per-local deltas are applied on top of
+        # the left side's edges so the rules compose.
+        def merge_extended_results(left, right, base_scope)
+          return left if right.nil?
+          return right if left.nil?
+
+          [
+            merge_scope_pair(left[0], right[0], base_scope),
+            merge_scope_pair(left[1], right[1], base_scope)
+          ]
+        end
+
+        def merge_scope_pair(left_scope, right_scope, base_scope)
+          right_scope.locals.reduce(left_scope) do |acc, (name, type)|
+            base_type = base_scope.local(name)
+            type.equal?(base_type) ? acc : acc.with_local(name, type)
+          end
         end
 
+        ZERO_CLASS_PREDICATES = %i[positive? negative? zero? nonzero?].freeze
+        COMPARISON_OPERATORS = %i[< <= > >=].freeze
+        private_constant :ZERO_CLASS_PREDICATES, :COMPARISON_OPERATORS
+
         def dispatch_call(node, scope, name)
+          return dispatch_call_simple(node, scope, name) if simple_dispatch_name?(name)
+
+          dispatch_call_numeric(node, scope, name)
+        end
+
+        def simple_dispatch_name?(name)
+          %i[nil? ! is_a? kind_of? instance_of? == != ===].include?(name)
+        end
+
+        def dispatch_call_simple(node, scope, name)
           case name
           when :nil?, :! then dispatch_unary_predicate(node, scope, name)
           when :is_a?, :kind_of? then analyse_class_predicate(node, scope, exact: false)
@@ -437,6 +531,92 @@ module Rigor
           end
         end
 
+        def dispatch_call_numeric(node, scope, name)
+          if COMPARISON_OPERATORS.include?(name)
+            analyse_comparison_predicate(node, scope, comparator: name)
+          elsif ZERO_CLASS_PREDICATES.include?(name)
+            analyse_zero_class_predicate(node, scope, predicate: name)
+          elsif name == :between?
+            analyse_between_predicate(node, scope)
+          end
+        end
+
+        # `:positive?` / `:negative?` / `:zero?` / `:nonzero?` are
+        # zero-arg predicates on `Numeric`. We model them as
+        # comparisons against the literal 0 so the existing range
+        # narrowing handles them uniformly.
+        ZERO_CLASS_PREDICATE_RULES = {
+          positive?: { truthy: [:>, 0],  falsey: [:<=, 0] },
+          negative?: { truthy: [:<, 0],  falsey: [:>=, 0] },
+          zero?: { truthy: [:eq, 0], falsey: [:ne, 0] },
+          nonzero?: { truthy: [:ne, 0], falsey: [:eq, 0] }
+        }.freeze
+        private_constant :ZERO_CLASS_PREDICATE_RULES
+
+        def analyse_zero_class_predicate(node, scope, predicate:)
+          return nil unless argument_free?(node)
+          return nil unless node.receiver.is_a?(Prism::LocalVariableReadNode)
+
+          local_name = node.receiver.name
+          current = scope.local(local_name)
+          return nil if current.nil?
+
+          rules = ZERO_CLASS_PREDICATE_RULES[predicate]
+          truthy = apply_zero_rule(current, rules[:truthy])
+          falsey = apply_zero_rule(current, rules[:falsey])
+          [scope.with_local(local_name, truthy), scope.with_local(local_name, falsey)]
+        end
+
+        def apply_zero_rule(type, rule)
+          case rule[0]
+          when :eq then narrow_integer_equal(type, rule[1])
+          when :ne then narrow_integer_not_equal(type, rule[1])
+          else
+            narrow_integer_comparison(type, rule[0], rule[1])
+          end
+        end
+
+        # `x.between?(a, b)` truthy edge narrows to
+        # `narrow_integer_comparison(>=, a)` ∩
+        # `narrow_integer_comparison(<=, b)`. The falsey edge is left
+        # unchanged because the complement is a two-piece domain
+        # (`x < a || x > b`) that the lattice cannot express
+        # precisely. `a` and `b` MUST both be integer literals.
+        def analyse_between_predicate(node, scope)
+          return nil unless node.receiver.is_a?(Prism::LocalVariableReadNode)
+          return nil if node.arguments.nil?
+          return nil unless node.arguments.arguments.size == 2
+
+          low, high = node.arguments.arguments
+          return nil unless low.is_a?(Prism::IntegerNode) && high.is_a?(Prism::IntegerNode)
+
+          local_name = node.receiver.name
+          current = scope.local(local_name)
+          return nil if current.nil?
+
+          truthy = narrow_integer_comparison(
+            narrow_integer_comparison(current, :>=, low.value),
+            :<=, high.value
+          )
+          [scope.with_local(local_name, truthy), scope]
+        end
+
+        # Helper for {.narrow_integer_not_equal}. Only adjusts when the
+        # value sits exactly on one endpoint, so the result stays
+        # contiguous; otherwise the input range is preserved.
+        def narrow_integer_range_not_equal(range, value)
+          return range if range.lower > value || range.upper < value
+          return Type::Combinator.bot if single_point_range_equal?(range, value)
+          return build_narrowing_integer_range(value + 1, range.upper) if range.lower == value
+          return build_narrowing_integer_range(range.lower, value - 1) if range.upper == value
+
+          range
+        end
+
+        def single_point_range_equal?(range, value)
+          range.finite? && range.min == value && range.max == value
+        end
+
         def dispatch_unary_predicate(node, scope, name)
           return nil unless argument_free?(node)
 
@@ -466,6 +646,126 @@ module Rigor
           equality == :== ? [positive, negative] : [negative, positive]
         end
 
+        # Comparison predicate analyser. Recognised shapes:
+        #   x  <  Int        x  <=  Int        x  >  Int        x  >=  Int
+        #   Int <  x         Int <=  x         Int >  x         Int >=  x
+        # The reversed (literal-on-left) form is normalised by
+        # transposing the operator so the receiver-local always
+        # appears on the left of the rule.
+        INVERT_COMPARISON_OP = { :< => :>=, :<= => :>, :> => :<=, :>= => :< }.freeze
+        REVERSE_COMPARISON_OP = { :< => :>, :<= => :>=, :> => :<, :>= => :<= }.freeze
+        private_constant :INVERT_COMPARISON_OP, :REVERSE_COMPARISON_OP
+
+        def analyse_comparison_predicate(node, scope, comparator:)
+          return nil if node.arguments.nil?
+          return nil unless node.arguments.arguments.size == 1
+
+          match = comparison_local_literal(node.receiver, node.arguments.arguments.first, comparator)
+          return nil if match.nil?
+
+          local_name, normalised_op, bound = match
+          current = scope.local(local_name)
+          return nil if current.nil?
+
+          truthy = narrow_integer_comparison(current, normalised_op, bound)
+          falsey = narrow_integer_comparison(current, INVERT_COMPARISON_OP[normalised_op], bound)
+          [scope.with_local(local_name, truthy), scope.with_local(local_name, falsey)]
+        end
+
+        def comparison_local_literal(left, right, comparator)
+          if left.is_a?(Prism::LocalVariableReadNode) && right.is_a?(Prism::IntegerNode)
+            return [left.name, comparator, right.value]
+          end
+          return nil unless right.is_a?(Prism::LocalVariableReadNode) && left.is_a?(Prism::IntegerNode)
+
+          [right.name, REVERSE_COMPARISON_OP[comparator], left.value]
+        end
+
+        def narrow_integer_equal_dispatch(type, value)
+          case type
+          when Type::Constant then narrow_integer_equal_constant(type, value)
+          when Type::IntegerRange then narrow_integer_equal_range(type, value)
+          when Type::Nominal then narrow_integer_equal_nominal(type, value)
+          when Type::Union
+            Type::Combinator.union(*type.members.map { |m| narrow_integer_equal(m, value) })
+          else type
+          end
+        end
+
+        def narrow_integer_equal_constant(constant, value)
+          constant.value == value ? constant : Type::Combinator.bot
+        end
+
+        def narrow_integer_equal_range(range, value)
+          range.covers?(value) ? Type::Combinator.constant_of(value) : Type::Combinator.bot
+        end
+
+        def narrow_integer_equal_nominal(nominal, value)
+          return nominal unless nominal.class_name == "Integer" && nominal.type_args.empty?
+
+          Type::Combinator.constant_of(value)
+        end
+
+        def narrow_integer_comparison_dispatch(type, comparator, bound)
+          case type
+          when Type::Constant
+            integer_constant_satisfies?(type.value, comparator, bound) ? type : Type::Combinator.bot
+          when Type::IntegerRange
+            intersect_integer_range(type, comparator, bound)
+          when Type::Nominal
+            narrow_integer_comparison_nominal(type, comparator, bound)
+          when Type::Union
+            Type::Combinator.union(
+              *type.members.map { |m| narrow_integer_comparison(m, comparator, bound) }
+            )
+          else
+            type
+          end
+        end
+
+        def narrow_integer_comparison_nominal(nominal, comparator, bound)
+          return nominal unless nominal.class_name == "Integer" && nominal.type_args.empty?
+
+          intersect_integer_range(Type::Combinator.universal_int, comparator, bound)
+        end
+
+        def integer_constant_satisfies?(value, comparator, bound)
+          return false unless value.is_a?(Integer)
+
+          case comparator
+          when :<  then value < bound
+          when :<= then value <= bound
+          when :>  then value > bound
+          when :>= then value >= bound
+          end
+        end
+
+        def intersect_integer_range(range, comparator, bound)
+          new_lower, new_upper = comparison_endpoints(range, comparator, bound)
+          return Type::Combinator.bot if new_lower > new_upper
+
+          build_narrowing_integer_range(new_lower, new_upper)
+        end
+
+        def comparison_endpoints(range, comparator, bound)
+          case comparator
+          when :<  then [range.lower, [range.upper, bound - 1].min]
+          when :<= then [range.lower, [range.upper, bound].min]
+          when :>  then [[range.lower, bound + 1].max, range.upper]
+          when :>= then [[range.lower, bound].max, range.upper]
+          end
+        end
+
+        def build_narrowing_integer_range(lower, upper)
+          min = lower == -Float::INFINITY ? Type::IntegerRange::NEG_INFINITY : Integer(lower)
+          max = upper == Float::INFINITY ? Type::IntegerRange::POS_INFINITY : Integer(upper)
+          if min.is_a?(Integer) && max.is_a?(Integer) && min == max
+            Type::Combinator.constant_of(min)
+          else
+            Type::Combinator.integer_range(min, max)
+          end
+        end
+
         def equality_local_literal(left, right, scope)
           if left.is_a?(Prism::LocalVariableReadNode)
             literal = static_literal_type(right, scope)
@@ -669,6 +969,73 @@ module Rigor
           [truthy_scope, falsey_scope]
         end
 
+        # v0.0.2 — `assert-if-true` / `assert-if-false`. Reads
+        # the conditional assertion effects off the called
+        # method and narrows the matching argument on the
+        # corresponding edge. The unconditional `assert`
+        # variant is NOT applied here; `StatementEvaluator`
+        # applies it directly to the post-call scope.
+        def analyse_rbs_extended_assert_if(node, scope)
+          method_def = resolve_rbs_extended_method(node, scope)
+          return nil if method_def.nil?
+
+          effects = RbsExtended.read_assert_effects(method_def).reject(&:always?)
+          return nil if effects.empty?
+
+          truthy_scope = scope
+          falsey_scope = scope
+          effects.each do |effect|
+            truthy_scope, falsey_scope =
+              apply_assert_if_effect(effect, node, scope, truthy_scope, falsey_scope, method_def)
+          end
+          [truthy_scope, falsey_scope]
+        end
+
+        # rubocop:disable Metrics/ParameterLists
+        def apply_assert_if_effect(effect, call_node, entry_scope, truthy_scope, falsey_scope, method_def)
+          target_node = effect_target_node(effect, call_node, method_def)
+          return [truthy_scope, falsey_scope] unless target_node.is_a?(Prism::LocalVariableReadNode)
+
+          local_name = target_node.name
+          current = entry_scope.local(local_name)
+          return [truthy_scope, falsey_scope] if current.nil?
+
+          narrowed = narrow_for_effect(current, effect, entry_scope.environment)
+          if effect.if_truthy_return?
+            [truthy_scope.with_local(local_name, narrowed), falsey_scope]
+          else
+            [truthy_scope, falsey_scope.with_local(local_name, narrowed)]
+          end
+        end
+        # rubocop:enable Metrics/ParameterLists
+
+        # v0.0.2 #3 — resolves an effect's target node. For
+        # `target: <param>` we look up the matching positional
+        # argument; for `target: self` we use the call's
+        # receiver. In both cases the caller still requires a
+        # `Prism::LocalVariableReadNode` for narrowing to
+        # actually fire (the engine's narrowing surface only
+        # rebinds locals).
+        def effect_target_node(effect, call_node, method_def)
+          if effect.target_kind == :self
+            call_node.receiver
+          else
+            lookup_positional_arg(call_node, method_def, effect.target_name)
+          end
+        end
+
+        # v0.0.2 — selects `narrow_class` (positive) or
+        # `narrow_not_class` (negative `~T` form) based on
+        # the effect's `negative?` flag. Shared between
+        # predicate-if-* and assert-if-* application paths.
+        def narrow_for_effect(current, effect, environment)
+          if effect.negative?
+            narrow_not_class(current, effect.class_name, exact: false, environment: environment)
+          else
+            narrow_class(current, effect.class_name, exact: false, environment: environment)
+          end
+        end
+
         def resolve_rbs_extended_method(node, scope)
           loader = scope.environment.rbs_loader
           return nil if loader.nil?
@@ -709,15 +1076,14 @@ module Rigor
 
         # rubocop:disable Metrics/ParameterLists
         def apply_predicate_effect(effect, call_node, entry_scope, truthy_scope, falsey_scope, method_def)
-          arg_node = lookup_positional_arg(call_node, method_def, effect.target_name)
-          return [truthy_scope, falsey_scope] if effect.target_kind != :parameter
-          return [truthy_scope, falsey_scope] unless arg_node.is_a?(Prism::LocalVariableReadNode)
+          target_node = effect_target_node(effect, call_node, method_def)
+          return [truthy_scope, falsey_scope] unless target_node.is_a?(Prism::LocalVariableReadNode)
 
-          local_name = arg_node.name
+          local_name = target_node.name
           current = entry_scope.local(local_name)
           return [truthy_scope, falsey_scope] if current.nil?
 
-          narrowed = narrow_class(current, effect.class_name, exact: false, environment: entry_scope.environment)
+          narrowed = narrow_for_effect(current, effect, entry_scope.environment)
           if effect.truthy_only?
             [truthy_scope.with_local(local_name, narrowed), falsey_scope]
           else
@@ -759,10 +1125,11 @@ module Rigor
           fully_narrowable = true
 
           conditions.each do |condition|
-            target = static_class_name(condition) || case_equality_target_class(condition)
-            if target
-              truthy_members << narrow_class(current, target, exact: false, environment: scope.environment)
-              falsey_type = narrow_not_class(falsey_type, target, exact: false, environment: scope.environment)
+            applied = apply_case_when_condition(scope, current, condition, falsey_type)
+            if applied
+              truthy_members << applied[:truthy]
+              falsey_type = applied[:falsey]
+              fully_narrowable &&= applied[:fully_narrowable]
             else
               fully_narrowable = false
             end
@@ -775,6 +1142,100 @@ module Rigor
           ]
         end
 
+        # Per-condition rule. Returns `nil` when the condition shape
+        # is not recognised (caller marks `fully_narrowable = false`),
+        # or `{truthy:, falsey:, fully_narrowable:}` when it is.
+        def apply_case_when_condition(scope, current, condition, falsey_acc)
+          int_range = case_equality_integer_range(condition)
+          return integer_range_when_result(current, int_range, falsey_acc) if int_range && integer_rooted_type?(current)
+
+          int_literal = case_equality_integer_literal(condition)
+          if int_literal && integer_rooted_type?(current)
+            return integer_literal_when_result(current, int_literal, falsey_acc)
+          end
+
+          target = static_class_name(condition) || case_equality_target_class(condition)
+          return class_when_result(scope, current, target, falsey_acc) if target
+
+          nil
+        end
+
+        def case_equality_integer_literal(condition)
+          condition = unwrap_parens(condition)
+          condition.is_a?(Prism::IntegerNode) ? condition.value : nil
+        end
+
+        def integer_literal_when_result(current, value, falsey_acc)
+          # `case n when k` is `k === n` which for Integer is value
+          # equality. The truthy edge collapses the local to
+          # `Constant[k]`; the falsey edge tightens via
+          # `narrow_integer_not_equal` (only effective when k sits
+          # at one endpoint of the current range).
+          {
+            truthy: narrow_integer_equal(current, value),
+            falsey: narrow_integer_not_equal(falsey_acc, value),
+            fully_narrowable: true
+          }
+        end
+
+        def integer_range_when_result(current, range_pair, falsey_acc)
+          low, high = range_pair
+          truthy = narrow_integer_comparison(
+            narrow_integer_comparison(current, :>=, low),
+            :<=, high
+          )
+          # The falsey edge of `n in [a, b]` is two-piece; we cannot
+          # express the complement precisely with a single carrier,
+          # so keep the accumulator unchanged. `fully_narrowable: false`
+          # forces the else-branch to see `current` (the unmodified
+          # entry type), which mirrors `between?` falsey behaviour.
+          { truthy: truthy, falsey: falsey_acc, fully_narrowable: false }
+        end
+
+        def class_when_result(scope, current, target, falsey_acc)
+          {
+            truthy: narrow_class(current, target, exact: false, environment: scope.environment),
+            falsey: narrow_not_class(falsey_acc, target, exact: false, environment: scope.environment),
+            fully_narrowable: true
+          }
+        end
+
+        # Returns `[low, high]` for a `Prism::RangeNode` whose
+        # endpoints are both `Prism::IntegerNode` literals, with
+        # `..`/`...` exclusivity respected. Open-ended ranges use
+        # the symbolic infinities so the existing comparison
+        # narrowing tier handles them. Returns `nil` for any other
+        # shape (Float endpoints, String endpoints, dynamic
+        # expressions).
+        def case_equality_integer_range(condition)
+          condition = unwrap_parens(condition)
+          return nil unless condition.is_a?(Prism::RangeNode)
+
+          low = integer_range_endpoint(condition.left, default: Type::IntegerRange::NEG_INFINITY)
+          high = integer_range_endpoint(condition.right, default: Type::IntegerRange::POS_INFINITY)
+          return nil if low.nil? || high.nil?
+
+          high -= 1 if condition.exclude_end? && high.is_a?(Integer)
+          [low, high]
+        end
+
+        def integer_range_endpoint(node, default:)
+          return default if node.nil?
+          return node.value if node.is_a?(Prism::IntegerNode)
+
+          nil
+        end
+
+        def integer_rooted_type?(type)
+          case type
+          when Type::Constant then type.value.is_a?(Integer)
+          when Type::IntegerRange then true
+          when Type::Nominal then type.class_name == "Integer" && type.type_args.empty?
+          when Type::Union then type.members.all? { |m| integer_rooted_type?(m) }
+          else false
+          end
+        end
+
         def range_target_class(range_node)
           left = range_node.left
           right = range_node.right

data/lib/rigor/inference/scope_indexer.rb

@@ -98,6 +98,13 @@ module Rigor
         discovered_methods = build_discovered_methods(root)
         seeded_scope = seeded_scope.with_discovered_methods(discovered_methods)
 
+        # v0.0.2 #5 — also record the def node itself for
+        # instance methods so the engine can re-type the body
+        # when a call site dispatches against a user-defined
+        # method without an RBS sig.
+        discovered_def_nodes = build_discovered_def_nodes(root)
+        seeded_scope = seeded_scope.with_discovered_def_nodes(discovered_def_nodes)
+
         table = {}.compare_by_identity
         table.default = seeded_scope
 
@@ -369,6 +376,65 @@ module Rigor
         accumulator[class_name][def_node.name] = kind
       end
 
+      # v0.0.2 #5 — instance-side def-node recording. Walks
+      # class bodies the same way as `build_discovered_methods`
+      # but records the actual `Prism::DefNode` for each
+      # **instance** method so `ExpressionTyper` can re-type
+      # the body at the call site for inter-procedural return
+      # inference. Singleton methods and `define_method` calls
+      # are intentionally skipped: the inference path needs a
+      # statically introspectable body, and singleton dispatch
+      # has its own complications (Class / Module ancestry)
+      # the first-iteration rule does not yet model.
+      def build_discovered_def_nodes(root)
+        accumulator = {}
+        walk_def_nodes(root, [], false, accumulator)
+        accumulator.transform_values(&:freeze).freeze
+      end
+
+      def walk_def_nodes(node, qualified_prefix, in_singleton_class, accumulator) # rubocop:disable Metrics/CyclomaticComplexity
+        return unless node.is_a?(Prism::Node)
+
+        case node
+        when Prism::ClassNode, Prism::ModuleNode
+          name = qualified_name_for(node.constant_path)
+          if name
+            child_prefix = qualified_prefix + [name]
+            walk_def_nodes(node.body, child_prefix, false, accumulator) if node.body
+            return
+          end
+        when Prism::SingletonClassNode
+          if node.expression.is_a?(Prism::SelfNode) && node.body
+            walk_def_nodes(node.body, qualified_prefix, true, accumulator)
+            return
+          end
+        when Prism::DefNode
+          record_def_node(node, qualified_prefix, in_singleton_class, accumulator)
+          return
+        end
+
+        node.compact_child_nodes.each do |child|
+          walk_def_nodes(child, qualified_prefix, in_singleton_class, accumulator)
+        end
+      end
+
+      # v0.0.3 A — sentinel key under which `record_def_node`
+      # files DefNodes that live outside any class / module
+      # body (top-level helpers, `def`s nested inside DSL
+      # blocks like `RSpec.describe ... do; def helper; end`).
+      # Looked up by `Scope#top_level_def_for` to give
+      # implicit-self calls priority over RBS dispatch when
+      # the file defines a same-named local method.
+      TOP_LEVEL_DEF_KEY = "<toplevel>"
+
+      def record_def_node(def_node, qualified_prefix, in_singleton_class, accumulator)
+        return if def_node.receiver.is_a?(Prism::SelfNode) || in_singleton_class
+
+        class_name = qualified_prefix.empty? ? TOP_LEVEL_DEF_KEY : qualified_prefix.join("::")
+        accumulator[class_name] ||= {}
+        accumulator[class_name][def_node.name] = def_node
+      end
+
       def record_define_method(call_node, qualified_prefix, in_singleton_class, accumulator)
         return if qualified_prefix.empty?
         return if call_node.arguments.nil? || call_node.arguments.arguments.empty?