rigortype 0.0.1 → 0.0.3

data/lib/rigor/inference/statement_evaluator.rb

@@ -335,7 +335,17 @@ module Rigor
       # nil-injection on half-bound names so a name set in one branch
       # but not the other is observable as `T | nil` after the if.
       def eval_if(node)
-        _pred_type, post_pred = sub_eval(node.predicate, scope)
+        pred_type, post_pred = sub_eval(node.predicate, scope)
+
+        # When the predicate is a known-truthy / known-falsey type
+        # (notably `Constant[true]` / `Constant[false]` after the
+        # constant-fold tier), only the live branch contributes a
+        # type and a post-scope. The dead branch is skipped so the
+        # result type is precise (`Constant[:even]` instead of the
+        # joined `Constant[:even] | Constant[:odd]`).
+        live = live_branch_for_if(node, pred_type, post_pred)
+        return live if live
+
         truthy_scope, falsey_scope = Narrowing.predicate_scopes(node.predicate, post_pred)
         then_type, then_scope = eval_branch_or_nil(node.statements, truthy_scope)
         else_type, else_scope = eval_branch_or_nil(node.subsequent, falsey_scope)
@@ -360,7 +370,11 @@ module Rigor
       # narrower's truthy/falsey edges are routed in swapped form
       # because `unless` runs its body when the predicate is falsey.
       def eval_unless(node)
-        _pred_type, post_pred = sub_eval(node.predicate, scope)
+        pred_type, post_pred = sub_eval(node.predicate, scope)
+
+        live = live_branch_for_unless(node, pred_type, post_pred)
+        return live if live
+
         truthy_scope, falsey_scope = Narrowing.predicate_scopes(node.predicate, post_pred)
         then_type, then_scope = eval_branch_or_nil(node.statements, falsey_scope)
         else_type, else_scope = eval_branch_or_nil(node.else_clause, truthy_scope)
@@ -378,6 +392,38 @@ module Rigor
         ]
       end
 
+      # Returns the `[type, post_scope]` of the live branch when the
+      # predicate is provably truthy / falsey, else nil so the
+      # caller falls through to the standard both-branch evaluation.
+      # Constant `true`/`false` is the obvious trigger; non-falsey
+      # carriers like `Nominal[Integer]` (Integer is always truthy
+      # in Ruby — including 0) also collapse the dead else.
+      def live_branch_for_if(node, pred_type, post_pred)
+        case predicate_certainty(pred_type)
+        when :always_truthy then eval_branch_or_nil(node.statements, post_pred)
+        when :always_falsey then eval_branch_or_nil(node.subsequent, post_pred)
+        end
+      end
+
+      def live_branch_for_unless(node, pred_type, post_pred)
+        case predicate_certainty(pred_type)
+        when :always_truthy then eval_branch_or_nil(node.else_clause, post_pred)
+        when :always_falsey then eval_branch_or_nil(node.statements, post_pred)
+        end
+      end
+
+      def predicate_certainty(pred_type)
+        return nil if pred_type.nil? || pred_type.is_a?(Type::Bot)
+
+        truthy_bot = Narrowing.narrow_truthy(pred_type).is_a?(Type::Bot)
+        falsey_bot = Narrowing.narrow_falsey(pred_type).is_a?(Type::Bot)
+
+        return :always_falsey if truthy_bot && !falsey_bot
+        return :always_truthy if !truthy_bot && falsey_bot
+
+        nil
+      end
+
       def eval_else(node)
         return [Type::Combinator.constant_of(nil), scope] if node.statements.nil?
 
@@ -605,9 +651,266 @@ module Rigor
         call_type = scope.type_of(node, tracer: tracer)
         evaluate_block_if_present(node)
         post_scope = record_closure_escape_if_any(node)
+        post_scope = apply_rbs_extended_assertions(node, post_scope)
+        post_scope = apply_rspec_matcher_narrowing(node, post_scope)
         [call_type, post_scope]
       end
 
+      # v0.0.3 — recognises a small catalogue of RSpec
+      # matcher patterns as assert-shaped narrows on the
+      # local passed to `expect(...)`. The pattern is
+      # matched purely on AST shape; no RBS for RSpec is
+      # required (and none is shipped today).
+      #
+      # Recognised today:
+      #
+      #   expect(x).not_to(be_nil)
+      #   expect(x).to_not(be_nil)
+      #     → narrow `x` AWAY from `NilClass`.
+      #
+      #   expect(x).to(be_a(C))
+      #   expect(x).to(be_kind_of(C))
+      #   expect(x).to(be_an_instance_of(C))
+      #     → narrow `x` to `C` (exact for
+      #       `be_an_instance_of`, subtype-permitting
+      #       otherwise).
+      #
+      # Anything else is silently passed through. Symmetric
+      # negative class assertions (`not_to be_a(C)`) and
+      # narrowing TO `NilClass` are intentionally NOT
+      # modelled: they are rarely useful in practice and
+      # risk masking bugs if the assertion later fails.
+      def apply_rspec_matcher_narrowing(call_node, current_scope)
+        narrow = rspec_matcher_narrowing_request(call_node)
+        return current_scope if narrow.nil?
+
+        local_name = narrow.fetch(:local)
+        current_type = current_scope.local(local_name)
+        return current_scope if current_type.nil?
+
+        narrowed = apply_rspec_narrow(current_type, narrow, current_scope.environment)
+        current_scope.with_local(local_name, narrowed)
+      end
+
+      # Decodes an `expect(x).<chain>` outer call into a
+      # narrowing request hash, or `nil` when the shape is
+      # not recognised. The hash carries `:local` (the local
+      # name being narrowed) plus the narrowing parameters.
+      def rspec_matcher_narrowing_request(call_node)
+        local_name = rspec_expectation_target(call_node)
+        return nil if local_name.nil?
+
+        case call_node.name
+        when :not_to, :to_not
+          rspec_negative_narrow(call_node, local_name)
+        when :to
+          rspec_positive_narrow(call_node, local_name)
+        end
+      end
+
+      def rspec_negative_narrow(call_node, local_name)
+        return nil unless rspec_matcher_argument?(call_node, :be_nil)
+
+        { local: local_name, kind: :not_class, class_name: "NilClass", exact: false }
+      end
+
+      def rspec_positive_narrow(call_node, local_name)
+        matcher = rspec_matcher_node(call_node)
+        return nil if matcher.nil?
+
+        case matcher.name
+        when :be_a, :be_kind_of
+          rspec_be_a_narrow(matcher, local_name, exact: false)
+        when :be_an_instance_of, :be_instance_of
+          rspec_be_a_narrow(matcher, local_name, exact: true)
+        end
+      end
+
+      # `be_a` / `be_kind_of` / `be_an_instance_of` accept a
+      # single class argument — either a `ConstantReadNode`
+      # (`Integer`) or a `ConstantPathNode` (`Rigor::Type::Nominal`).
+      def rspec_be_a_narrow(matcher, local_name, exact:)
+        args = matcher.arguments&.arguments || []
+        return nil unless args.size == 1
+
+        class_name = constant_node_name(args.first)
+        return nil if class_name.nil?
+
+        { local: local_name, kind: :class, class_name: class_name, exact: exact }
+      end
+
+      def apply_rspec_narrow(current_type, narrow, environment)
+        case narrow.fetch(:kind)
+        when :not_class
+          Narrowing.narrow_not_class(current_type, narrow.fetch(:class_name),
+                                     exact: narrow.fetch(:exact), environment: environment)
+        when :class
+          Narrowing.narrow_class(current_type, narrow.fetch(:class_name),
+                                 exact: narrow.fetch(:exact), environment: environment)
+        end
+      end
+
+      # Returns the local name passed to `expect(...)` when
+      # the receiver chain matches `expect(<local>)` exactly,
+      # or nil otherwise. Centralised so each per-matcher
+      # decoder can short-circuit on a non-matching outer
+      # call.
+      def rspec_expectation_target(call_node) # rubocop:disable Metrics/CyclomaticComplexity
+        receiver = call_node.receiver
+        return nil unless receiver.is_a?(Prism::CallNode) && receiver.name == :expect
+        return nil unless receiver.receiver.nil?
+
+        args = receiver.arguments&.arguments || []
+        return nil unless args.size == 1
+
+        target = args.first
+        target.is_a?(Prism::LocalVariableReadNode) ? target.name : nil
+      end
+
+      def rspec_matcher_node(call_node)
+        args = call_node.arguments&.arguments || []
+        return nil unless args.size == 1
+
+        matcher = args.first
+        return nil unless matcher.is_a?(Prism::CallNode) && matcher.receiver.nil? && matcher.block.nil?
+
+        matcher
+      end
+
+      # True when `call_node`'s sole argument is an
+      # implicit-self matcher call with the given name and
+      # no positional arguments — used by the no-arg
+      # matchers (`be_nil`).
+      def rspec_matcher_argument?(call_node, matcher_name)
+        matcher = rspec_matcher_node(call_node)
+        return false if matcher.nil?
+        return false unless matcher.name == matcher_name
+
+        matcher.arguments.nil? || matcher.arguments.arguments.empty?
+      end
+
+      # Decodes a `Prism::ConstantReadNode` /
+      # `Prism::ConstantPathNode` into a colon-joined class
+      # name string, or returns nil for any other node
+      # shape. Mirrors the conservative envelope used by the
+      # `is_a?` / `kind_of?` predicate narrower.
+      def constant_node_name(node)
+        case node
+        when Prism::ConstantReadNode
+          node.name.to_s
+        when Prism::ConstantPathNode
+          flatten_constant_path(node)
+        end
+      end
+
+      def flatten_constant_path(node)
+        parts = []
+        cursor = node
+        while cursor.is_a?(Prism::ConstantPathNode)
+          parts.unshift(cursor.name.to_s)
+          cursor = cursor.parent
+        end
+        case cursor
+        when Prism::ConstantReadNode then parts.unshift(cursor.name.to_s)
+        when nil then nil # ::Foo absolute root — preserve as-is
+        else return nil
+        end
+        parts.join("::")
+      end
+
+      # v0.0.2 — applies `RBS::Extended` `assert <target> is T`
+      # directives to the post-call scope. The conditional
+      # variants (`assert-if-true` / `assert-if-false`) are
+      # NOT applied here — they refine the scope only when the
+      # call is observed as a truthy / falsey predicate, which
+      # `Narrowing.predicate_scopes` handles separately.
+      def apply_rbs_extended_assertions(call_node, current_scope)
+        method_def = resolve_call_method(call_node, current_scope)
+        return current_scope if method_def.nil?
+
+        effects = RbsExtended.read_assert_effects(method_def)
+        return current_scope if effects.empty?
+
+        effects.reduce(current_scope) do |scope_acc, effect|
+          next scope_acc unless effect.always?
+
+          apply_assert_effect(effect, call_node, scope_acc, method_def)
+        end
+      end
+
+      def resolve_call_method(call_node, current_scope) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        receiver_node = call_node.receiver
+        receiver_type =
+          if receiver_node
+            current_scope.type_of(receiver_node, tracer: tracer)
+          else
+            current_scope.self_type
+          end
+        return nil if receiver_type.nil?
+
+        loader = current_scope.environment.rbs_loader
+        return nil if loader.nil?
+
+        class_name = assertion_class_name(receiver_type)
+        return nil if class_name.nil?
+        return nil unless loader.class_known?(class_name)
+
+        if receiver_type.is_a?(Type::Singleton)
+          loader.singleton_method(class_name: class_name, method_name: call_node.name)
+        else
+          loader.instance_method(class_name: class_name, method_name: call_node.name)
+        end
+      rescue StandardError
+        nil
+      end
+
+      def assertion_class_name(receiver_type)
+        case receiver_type
+        when Type::Nominal, Type::Singleton then receiver_type.class_name
+        end
+      end
+
+      def apply_assert_effect(effect, call_node, current_scope, method_def)
+        target_node = assert_effect_target_node(effect, call_node, method_def)
+        return current_scope unless target_node.is_a?(Prism::LocalVariableReadNode)
+
+        local_name = target_node.name
+        current_type = current_scope.local(local_name)
+        return current_scope if current_type.nil?
+
+        narrowed = narrow_for_assert_effect(current_type, effect, current_scope.environment)
+        current_scope.with_local(local_name, narrowed)
+      end
+
+      # v0.0.2 #3 — same `target: self` accommodation as
+      # `Narrowing.effect_target_node`: the call's receiver
+      # serves as the target for self-targeted directives.
+      def assert_effect_target_node(effect, call_node, method_def)
+        if effect.target_kind == :self
+          call_node.receiver
+        else
+          lookup_assert_arg(call_node, method_def, effect.target_name)
+        end
+      end
+
+      def narrow_for_assert_effect(current_type, effect, environment)
+        if effect.negative?
+          Narrowing.narrow_not_class(current_type, effect.class_name, exact: false, environment: environment)
+        else
+          Narrowing.narrow_class(current_type, effect.class_name, exact: false, environment: environment)
+        end
+      end
+
+      def lookup_assert_arg(call_node, method_def, target_name)
+        arguments = call_node.arguments&.arguments || []
+        method_def.method_types.each do |mt|
+          params = mt.type.required_positionals + mt.type.optional_positionals
+          index = params.find_index { |param| param.name == target_name }
+          return arguments[index] if index && arguments[index]
+        end
+        nil
+      end
+
       def evaluate_block_if_present(node)
         block = node.block
         return unless block.is_a?(Prism::BlockNode)

data/lib/rigor/rbs_extended.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "type"
+require_relative "builtins/imported_refinements"
 
 module Rigor
   # Slice 7 phase 15 — first-preview reader for the
@@ -10,20 +11,28 @@ module Rigor
   # This module reads `%a{rigor:v1:<directive> <payload>}`
   # annotations off RBS method definitions and returns
   # well-typed effect objects the inference engine can
-  # consume. The first preview ships only the **type
-  # predicate** directives:
+  # consume. v0.0.2 recognises:
   #
   # - `rigor:v1:predicate-if-true <target> is <ClassName>`
   # - `rigor:v1:predicate-if-false <target> is <ClassName>`
+  # - `rigor:v1:assert <target> is <ClassName>`
+  # - `rigor:v1:assert-if-true <target> is <ClassName>`
+  # - `rigor:v1:assert-if-false <target> is <ClassName>`
   #
-  # Other directives in the spec (`assert`, `assert-if-true`,
-  # `assert-if-false`, `param`, `return`, `conforms-to`, ...)
-  # are intentionally deferred. Annotations whose key is in
-  # the `rigor:v1:` namespace but whose directive is
-  # unrecognised are silently ignored at first-preview
-  # quality (a future slice MAY surface them as
-  # diagnostics-on-Rigor-itself per the spec's "unsupported
-  # metadata" guidance).
+  # `predicate-if-*` fires when the call is used as an
+  # `if` / `unless` condition; `assert` fires unconditionally
+  # at the call's post-scope; `assert-if-true` /
+  # `assert-if-false` fire at the post-scope only when the
+  # call's return value can be observed as truthy / falsey
+  # (currently: when the call is the predicate of a
+  # subsequent `if` / `unless`). Other directives in the spec
+  # (`param`, `return`, `conforms-to`, negation `~T`,
+  # `target: self` narrowing, ...) remain on the v0.0.x
+  # roadmap. Annotations whose key is in the `rigor:v1:`
+  # namespace but whose directive is unrecognised are
+  # silently ignored at first-preview quality (a future slice
+  # MAY surface them as diagnostics-on-Rigor-itself per the
+  # spec's "unsupported metadata" guidance).
   #
   # The parser is minimal: it accepts a strict shape
   # `<target> is <ClassName>` where `<target>` is a Ruby
@@ -32,15 +41,41 @@ module Rigor
   # `::Foo::Bar` style constant path. Negative refinements
   # (`~T`), intersections, and unions are deferred to the
   # next iteration.
-  module RbsExtended
+  module RbsExtended # rubocop:disable Metrics/ModuleLength
     DIRECTIVE_PREFIX = "rigor:v1:"
 
     # Returned for `predicate-if-true` / `predicate-if-false`.
     # `target_kind` is `:parameter` (with `target_name` the
-    # Ruby parameter symbol) or `:self`.
-    PredicateEffect = Data.define(:edge, :target_kind, :target_name, :class_name) do
+    # Ruby parameter symbol) or `:self`. `negative` is true
+    # when the directive uses the `~ClassName` form, in
+    # which case the engine narrows AWAY from `class_name`
+    # (`Narrowing.narrow_not_class`) instead of toward it.
+    PredicateEffect = Data.define(:edge, :target_kind, :target_name, :class_name, :negative) do
       def truthy_only? = edge == :truthy_only
       def falsey_only? = edge == :falsey_only
+      def negative? = negative == true
+    end
+
+    # Returned for `assert` / `assert-if-true` /
+    # `assert-if-false`. `condition` is one of:
+    #
+    # - `:always`           — refines `target` at the call's
+    #                        post-scope unconditionally
+    #                        (`assert`).
+    # - `:if_truthy_return` — refines `target` only when the
+    #                        call's return value is observed
+    #                        as truthy (currently: as the
+    #                        predicate of a subsequent
+    #                        `if` / `unless`).
+    # - `:if_falsey_return` — symmetric for falsey.
+    #
+    # `negative` mirrors `PredicateEffect`: true when the
+    # directive uses `~ClassName` syntax.
+    AssertEffect = Data.define(:condition, :target_kind, :target_name, :class_name, :negative) do
+      def always? = condition == :always
+      def if_truthy_return? = condition == :if_truthy_return
+      def if_falsey_return? = condition == :if_falsey_return
+      def negative? = negative == true
     end
 
     module_function
@@ -71,6 +106,7 @@ module Rigor
       \s+
       (?<target>self|[a-z_][a-zA-Z0-9_]*)
       \s+is\s+
+      (?<negation>~?)
       (?<class_name>(?:::)?[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*)
       \s*
       \z
@@ -91,8 +127,132 @@ module Rigor
         edge: edge,
         target_kind: target_kind,
         target_name: target_name,
-        class_name: class_name
+        class_name: class_name,
+        negative: match[:negation].to_s == "~"
+      )
+    end
+
+    # Reads RBS::Extended assertion effects (`assert`,
+    # `assert-if-true`, `assert-if-false`) off
+    # `RBS::Definition::Method#annotations`. Returns an empty
+    # array when no recognised assertion directives are
+    # attached to the method.
+    def read_assert_effects(method_def)
+      return [] if method_def.nil?
+
+      annotations = method_def.annotations
+      return [] if annotations.nil? || annotations.empty?
+
+      effects = []
+      annotations.each do |annotation|
+        effect = parse_assert_annotation(annotation.string)
+        effects << effect if effect
+      end
+      effects.uniq
+    end
+
+    ASSERT_DIRECTIVE_PATTERN = /
+      \A
+      rigor:v1:(?<directive>assert(?:-if-(?:true|false))?)
+      \s+
+      (?<target>self|[a-z_][a-zA-Z0-9_]*)
+      \s+is\s+
+      (?<negation>~?)
+      (?<class_name>(?:::)?[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*)
+      \s*
+      \z
+    /x
+    private_constant :ASSERT_DIRECTIVE_PATTERN
+
+    ASSERT_CONDITIONS = {
+      "assert" => :always,
+      "assert-if-true" => :if_truthy_return,
+      "assert-if-false" => :if_falsey_return
+    }.freeze
+    private_constant :ASSERT_CONDITIONS
+
+    def parse_assert_annotation(string)
+      match = ASSERT_DIRECTIVE_PATTERN.match(string)
+      return nil if match.nil?
+
+      directive = match[:directive].to_s
+      condition = ASSERT_CONDITIONS[directive]
+      return nil if condition.nil?
+
+      target = match[:target].to_s
+      class_name = match[:class_name].to_s.sub(/\A::/, "")
+      target_kind = target == "self" ? :self : :parameter
+      target_name = target == "self" ? :self : target.to_sym
+      AssertEffect.new(
+        condition: condition,
+        target_kind: target_kind,
+        target_name: target_name,
+        class_name: class_name,
+        negative: match[:negation].to_s == "~"
       )
     end
+
+    # Reads the `rigor:v1:return: <kebab-name>` directive off
+    # `RBS::Definition::Method#annotations`. The directive
+    # overrides a method's RBS-declared return type with one of
+    # the imported-built-in refinements registered in
+    # `Rigor::Builtins::ImportedRefinements`. The override is the
+    # primary integration path for refinement carriers
+    # (`non-empty-string`, `positive-int`, `non-empty-array`, …)
+    # in v0.0 — annotation-driven, opt-in per method, and never
+    # silently rewrites a hand-authored RBS signature outside the
+    # annotation.
+    #
+    # Example annotation in an RBS file:
+    #
+    #   class User
+    #     %a{rigor:v1:return: non-empty-string}
+    #     def name: () -> String
+    #   end
+    #
+    # The RBS-declared return is `String`. The override
+    # tightens it to `non-empty-string` (i.e.
+    # `Difference[String, ""]`) for callers; RBS erasure of the
+    # tightened return goes back to `String` so the round-trip
+    # to ordinary RBS is unaffected.
+    #
+    # Returns the resolved `Rigor::Type` value, or `nil` when:
+    # - the method has no annotations,
+    # - none of the annotations match the `rigor:v1:return:`
+    #   directive,
+    # - the directive's payload names a refinement not
+    #   registered in `Rigor::Builtins::ImportedRefinements`
+    #   (the analyzer prefers a silent miss over crashing on a
+    #   typo; future slices MAY surface the miss as a
+    #   `:warning` self-diagnostic).
+    def read_return_type_override(method_def)
+      return nil if method_def.nil?
+
+      annotations = method_def.annotations
+      return nil if annotations.nil? || annotations.empty?
+
+      annotations.each do |annotation|
+        type = parse_return_type_override(annotation.string)
+        return type if type
+      end
+      nil
+    end
+
+    RETURN_DIRECTIVE_PATTERN = /
+      \A
+      rigor:v1:return:
+      \s+
+      (?<refinement>[a-z][a-z0-9-]*)
+      \s*
+      \z
+    /x
+    private_constant :RETURN_DIRECTIVE_PATTERN
+
+    def parse_return_type_override(string)
+      match = RETURN_DIRECTIVE_PATTERN.match(string)
+      return nil if match.nil?
+
+      Builtins::ImportedRefinements.lookup(match[:refinement])
+    end
   end
 end

data/lib/rigor/scope.rb

@@ -19,7 +19,8 @@ module Rigor
     attr_reader :environment, :locals, :fact_store, :self_type, :declared_types,
                 :ivars, :cvars, :globals,
                 :class_ivars, :class_cvars, :program_globals,
-                :discovered_classes, :in_source_constants, :discovered_methods
+                :discovered_classes, :in_source_constants, :discovered_methods,
+                :discovered_def_nodes
 
     EMPTY_DECLARED_TYPES = {}.compare_by_identity.freeze
     EMPTY_VAR_BINDINGS = {}.freeze
@@ -45,7 +46,8 @@ module Rigor
       program_globals: EMPTY_VAR_BINDINGS,
       discovered_classes: EMPTY_VAR_BINDINGS,
       in_source_constants: EMPTY_VAR_BINDINGS,
-      discovered_methods: EMPTY_CLASS_BINDINGS
+      discovered_methods: EMPTY_CLASS_BINDINGS,
+      discovered_def_nodes: EMPTY_CLASS_BINDINGS
     )
       @environment = environment
       @locals = locals
@@ -61,6 +63,7 @@ module Rigor
       @discovered_classes = discovered_classes
       @in_source_constants = in_source_constants
       @discovered_methods = discovered_methods
+      @discovered_def_nodes = discovered_def_nodes
       freeze
     end
 
@@ -231,6 +234,40 @@ module Rigor
       rebuild(discovered_methods: table)
     end
 
+    # v0.0.2 #5 — per-class table mapping
+    # `method_name (Symbol) → Prism::DefNode`. Populated by
+    # `ScopeIndexer` alongside `discovered_methods` for
+    # instance-side defs only (singleton-side and
+    # `define_method`-introduced methods do not contribute a
+    # static body the engine can re-type). Consumed by
+    # `ExpressionTyper` to do inter-procedural return-type
+    # inference when the receiver class is user-defined and
+    # has no RBS sig.
+    def user_def_for(class_name, method_name)
+      table = @discovered_def_nodes[class_name.to_s]
+      return nil unless table
+
+      table[method_name.to_sym]
+    end
+
+    # v0.0.3 A — top-level def lookup for implicit-self
+    # calls. Returns the `Prism::DefNode` for a top-level
+    # (or DSL-block-nested, outside any class body) `def
+    # <method_name>` in the file, or nil. The sentinel key
+    # is owned by `Inference::ScopeIndexer::TOP_LEVEL_DEF_KEY`;
+    # consumers should treat its presence as an opaque
+    # implementation detail and go through this accessor.
+    def top_level_def_for(method_name)
+      table = @discovered_def_nodes[Inference::ScopeIndexer::TOP_LEVEL_DEF_KEY]
+      return nil unless table
+
+      table[method_name.to_sym]
+    end
+
+    def with_discovered_def_nodes(table)
+      rebuild(discovered_def_nodes: table)
+    end
+
     def facts_for(target: nil, bucket: nil)
       fact_store.facts_for(target: target, bucket: bucket)
     end
@@ -297,7 +334,7 @@ module Rigor
       declared_types: @declared_types, ivars: @ivars, cvars: @cvars, globals: @globals,
       class_ivars: @class_ivars, class_cvars: @class_cvars, program_globals: @program_globals,
       discovered_classes: @discovered_classes, in_source_constants: @in_source_constants,
-      discovered_methods: @discovered_methods
+      discovered_methods: @discovered_methods, discovered_def_nodes: @discovered_def_nodes
     )
       self.class.new(
         environment: environment, locals: locals,
@@ -308,7 +345,8 @@ module Rigor
         program_globals: program_globals,
         discovered_classes: discovered_classes,
         in_source_constants: in_source_constants,
-        discovered_methods: discovered_methods
+        discovered_methods: discovered_methods,
+        discovered_def_nodes: discovered_def_nodes
       )
     end
 
@@ -332,7 +370,8 @@ module Rigor
         program_globals: program_globals,
         discovered_classes: discovered_classes,
         in_source_constants: in_source_constants,
-        discovered_methods: discovered_methods
+        discovered_methods: discovered_methods,
+        discovered_def_nodes: discovered_def_nodes
       )
     end
   end