rigortype 0.2.7 → 0.2.8

data/lib/rigor/inference/origin_lookup.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  module Inference
+    # ADR-82 — the effective {DynamicOrigin} cause of a receiver *expression*, unifying the two provenance
+    # lookups so a chain and a bare variable resolve the same way:
+    #
+    # - the cause recorded on the expression's own node (`Scope#dynamic_origins`), covering a call node whose
+    #   dispatch recorded a cause (WD2's user-method tiers, or WD6's chain inheritance), and
+    # - for a bare local / instance-variable read, the cause propagated from its binding (WD1's
+    #   `Scope#local_origins` / `#ivar_origins`) — the read node itself carries none, the cause was recorded
+    #   on the assignment's rhs.
+    #
+    # Consulted by `ProtectionScanner` (to label a hole) and `ExpressionTyper` (WD6 — to inherit a Dynamic
+    # receiver's cause onto the call it produces, so provenance survives a method chain).
+    module OriginLookup
+      module_function
+
+      # @param scope [Rigor::Scope]
+      # @param node [Prism::Node, nil] the receiver expression's node (nil for an implicit-self receiver)
+      # @return [Symbol, nil] the effective dynamic-origin cause, or nil when none is known
+      def origin_for(scope, node)
+        return nil if node.nil?
+
+        scope.dynamic_origins[node] || propagated(scope, node)
+      end
+
+      def propagated(scope, node)
+        case node
+        when Prism::LocalVariableReadNode then scope.local_origin(node.name)
+        when Prism::InstanceVariableReadNode then scope.ivar_origin(node.name)
+        end
+      end
+    end
+  end
+end

data/lib/rigor/inference/parameter_inference_collector.rb

@@ -7,10 +7,10 @@ require_relative "../source/node_walker"
 
 module Rigor
   module Inference
-    # Pure argument-type classification for {ParameterInferenceCollector} — no
-    # collector state, so it lives outside the orchestration class. Decides which
-    # argument types may seed a parameter (concrete enough for the protection
-    # metric to bite) and widens a literal argument to its nominal.
+    # Pure argument-type classification for {ParameterInferenceCollector} — no collector state,
+    # so it lives outside the orchestration class. Decides which argument types may seed a
+    # parameter (concrete enough for the protection metric to bite) and widens a literal
+    # argument to its nominal.
     module ParameterArgTypes
       module_function
 
@@ -20,10 +20,9 @@ module Rigor
         FalseClass => "FalseClass", NilClass => "NilClass"
       }.freeze
 
-      # A parameter holds a *value of* a type across its lifetime, not a pinned
-      # literal — so a `Constant<"text">` argument widens to its nominal
-      # (`String`); recurses through unions so `Constant<"a"> | Constant<"b">`
-      # collapses to `String`.
+      # A parameter holds a *value of* a type across its lifetime, not a pinned literal — so a
+      # `Constant<"text">` argument widens to its nominal (`String`); recurses through unions so
+      # `Constant<"a"> | Constant<"b">` collapses to `String`.
       def widen_for_param(type)
         case type
         when Type::Constant
@@ -41,10 +40,10 @@ module Rigor
         nil
       end
 
-      # The dispatch class for a receiver type, for the subset the collector
-      # resolves to a user `def` (mirrors `CheckRules#concrete_class_name` for the
-      # carriers a user-method receiver is typed as). `class_name_of` is the
-      # Nominal/Singleton-only variant for an implicit-self `self_type`.
+      # The dispatch class for a receiver type, for the subset the collector resolves to a user
+      # `def` (mirrors `CheckRules#concrete_class_name` for the carriers a user-method receiver
+      # is typed as). `class_name_of` is the Nominal/Singleton-only variant for an implicit-self
+      # `self_type`.
       def concrete_class_name(type)
         case type
         when Type::Nominal, Type::Singleton then type.class_name
@@ -57,9 +56,8 @@ module Rigor
         type.class_name if type.is_a?(Type::Nominal) || type.is_a?(Type::Singleton)
       end
 
-      # Whether `type` is too gradual to seed (not a concrete dispatch target) —
-      # the negation of `ProtectionScanner#concrete_receiver?` (a union is
-      # concrete only when every arm is).
+      # Whether `type` is too gradual to seed (not a concrete dispatch target) — the negation of
+      # `ProtectionScanner#concrete_receiver?` (a union is concrete only when every arm is).
       def non_concrete?(type)
         case type
         when Type::Dynamic, Type::Top, Type::Bot then true
@@ -71,55 +69,50 @@ module Rigor
 
     # ADR-67 WD3 + WD5 — call-site parameter type inference (capped fixpoint).
     #
-    # A `def` parameter with no RBS signature types `untyped` (the gradual entry
-    # point), so a param flowing into an ivar or a receiver drains everything
-    # downstream to `Dynamic`. This pass closes that hole: it walks every project
-    # file, types each call's positional arguments in their lexical scope,
-    # resolves which user-defined `def` each call targets, and records the
-    # **union of resolved call-site argument types** per parameter — TypeProf's
-    # "a parameter's type is the union of every actual argument across all call
-    # sites". WD5: it iterates (cap {DEFAULT_ROUNDS}), re-seeding each round with
-    # the previous round's inferred parameters, so a parameter passed *another*
-    # parameter is typed one hop further per round (round 1 alone is the
-    # single-level pass).
+    # A `def` parameter with no RBS signature types `untyped` (the gradual entry point), so a
+    # param flowing into an ivar or a receiver drains everything downstream to `Dynamic`. This
+    # pass closes that hole: it walks every project file, types each call's positional
+    # arguments in their lexical scope, resolves which user-defined `def` each call targets,
+    # and records the **union of resolved call-site argument types** per parameter — TypeProf's
+    # "a parameter's type is the union of every actual argument across all call sites". WD5: it
+    # iterates (cap {DEFAULT_ROUNDS}), re-seeding each round with the previous round's inferred
+    # parameters, so a parameter passed *another* parameter is typed one hop further per round
+    # (round 1 alone is the single-level pass).
     #
     # The result is keyed by `[class_name, method_name, kind]` — the same triple
-    # `StatementEvaluator#build_method_entry_scope` reconstructs from the lexical
-    # class path — so the consumer can seed an undeclared parameter with its
-    # inferred type. The table is precision-additive only: it never feeds a
-    # parameter-boundary diagnostic (an inferred type lives solely as a body
-    # local, and the boundary rules consult RBS, not body locals — see ADR-67
-    # WD1), so being wrong cannot manufacture a false positive at a caller.
+    # `StatementEvaluator#build_method_entry_scope` reconstructs from the lexical class path —
+    # so the consumer can seed an undeclared parameter with its inferred type. The table is
+    # precision-additive only: it never feeds a parameter-boundary diagnostic (an inferred type
+    # lives solely as a body local, and the boundary rules consult RBS, not body locals — see
+    # ADR-67 WD1), so being wrong cannot manufacture a false positive at a caller.
     #
-    # Soundness (WD4): the inferred type is a sound over-approximation only when
-    # every contributed call site resolves to a concrete argument type. Any
-    # `Dynamic` / `Top` / `Bot` argument (a `send`/dynamic-dispatch caller, or a
-    # parameter not yet typed in an earlier round) **poisons** the parameter,
-    # which then contributes nothing this round (it may type in a later round
-    # once its own argument resolves). Unresolved call sites do not contribute.
+    # Soundness (WD4): the inferred type is a sound over-approximation only when every
+    # contributed call site resolves to a concrete argument type. Any `Dynamic` / `Top` /
+    # `Bot` argument (a `send`/dynamic-dispatch caller, or a parameter not yet typed in an
+    # earlier round) **poisons** the parameter, which then contributes nothing this round (it
+    # may type in a later round once its own argument resolves). Unresolved call sites do not
+    # contribute.
     #
-    # What it does NOT do yet (deferred — the check-wiring slice): feeding the
-    # table into the `check` walk (only `coverage --protection` consumes it
-    # today), keyword / optional / rest / block parameters, inherited-method
-    # receivers, top-level helpers, and a rigorous closed-call-site-set proof
-    # (the union is optimistic over resolved sites — acceptable because the only
-    # consumer is the protection metric, which runs no diagnostics).
+    # What it does NOT do yet (deferred — the check-wiring slice): feeding the table into the
+    # `check` walk (only `coverage --protection` consumes it today), keyword / optional / rest
+    # / block parameters, inherited-method receivers, top-level helpers, and a rigorous
+    # closed-call-site-set proof (the union is optimistic over resolved sites — acceptable
+    # because the only consumer is the protection metric, which runs no diagnostics).
     class ParameterInferenceCollector
       EMPTY = {}.freeze
 
-      # A defensive widening cap (ADR-41): a parameter unioned from more than
-      # this many distinct concrete call-site types is widened to `untyped`
-      # (poisoned) rather than carrying an unbounded union.
+      # A defensive widening cap (ADR-41): a parameter unioned from more than this many distinct
+      # concrete call-site types is widened to `untyped` (poisoned) rather than carrying an
+      # unbounded union.
       MAX_CALL_SITE_TYPES = 16
 
-      # WD5 — the call-site union is a worklist fixpoint: each round re-types the
-      # project with the previous round's inferred parameters seeded, so a
-      # parameter passed *another* parameter is typed one hop further per round.
-      # Capped (no true-convergence requirement — the metric tolerates a bounded
-      # approximation, and the table can oscillate at the margin since a newly
-      # resolved receiver can surface a fresh untyped-argument call site). The
-      # cap matches the `Inference::BodyFixpoint` cap-3 convention. Round 1 alone
-      # is the single-level pass.
+      # WD5 — the call-site union is a worklist fixpoint: each round re-types the project with
+      # the previous round's inferred parameters seeded, so a parameter passed *another*
+      # parameter is typed one hop further per round. Capped (no true-convergence requirement —
+      # the metric tolerates a bounded approximation, and the table can oscillate at the margin
+      # since a newly resolved receiver can surface a fresh untyped-argument call site). The cap
+      # matches the `Inference::BodyFixpoint` cap-3 convention. Round 1 alone is the
+      # single-level pass.
       DEFAULT_ROUNDS = 3
 
       # @param files [Array<String>] project `.rb` paths to scan for call sites.
@@ -136,10 +129,10 @@ module Rigor
         @environment = environment
         @target_ruby = target_ruby
         @max_rounds = max_rounds
-        # Reset per round (see {#run_round}). `[[class, method, kind], param_sym]`
-        # => [Type] of observed concrete arguments (a default-block Hash, not a
-        # `{}` literal, so the analyzer types its reads generically — {#finalize}),
-        # plus the ids widened to `untyped` (an untyped / over-cap argument).
+        # Reset per round (see {#run_round}). `[[class, method, kind], param_sym]` => [Type] of
+        # observed concrete arguments (a default-block Hash, not a `{}` literal, so the
+        # analyzer types its reads generically — {#finalize}), plus the ids widened to
+        # `untyped` (an untyped / over-cap argument).
         @type_observations = Hash.new { |hash, id| hash[id] = [] }
         @poisoned_params = Set.new
       end
@@ -159,8 +152,8 @@ module Rigor
 
       private
 
-      # Parse every project file once; rounds re-index the cached ASTs against an
-      # evolving seed rather than re-parsing.
+      # Parse every project file once; rounds re-index the cached ASTs against an evolving seed
+      # rather than re-parsing.
       def parse_all
         @files.filter_map do |path|
           result = Prism.parse(File.read(path), filepath: path, version: @target_ruby)
@@ -170,8 +163,8 @@ module Rigor
         end
       end
 
-      # One fixpoint round: re-type every file with `seed_table` (the previous
-      # round's inferred parameters) seeded, collecting the next round's table.
+      # One fixpoint round: re-type every file with `seed_table` (the previous round's inferred
+      # parameters) seeded, collecting the next round's table.
       def run_round(parsed, discovery_tables, seed_table)
         @type_observations = Hash.new { |hash, id| hash[id] = [] }
         @poisoned_params = Set.new
@@ -185,10 +178,10 @@ module Rigor
         finalize
       end
 
-      # A scope carrying the cross-file discovery index (so `Foo.new` receivers
-      # and implicit-self calls resolve to a user `def`) plus the prior round's
-      # inferred parameters (so an argument that reads a parameter types to its
-      # current inferred type — the WD5 propagation).
+      # A scope carrying the cross-file discovery index (so `Foo.new` receivers and
+      # implicit-self calls resolve to a user `def`) plus the prior round's inferred parameters
+      # (so an argument that reads a parameter types to its current inferred type — the WD5
+      # propagation).
       def build_seed_scope(discovery_tables, seed_table)
         base = Scope.empty(environment: @environment)
         tables = discovery_tables
@@ -209,9 +202,8 @@ module Rigor
         end
         tables
       rescue StandardError
-        # Discovery is best-effort; a malformed corner of the project must not
-        # crash the protection scan. Without discovery the collector simply
-        # resolves fewer call sites.
+        # Discovery is best-effort; a malformed corner of the project must not crash the
+        # protection scan. Without discovery the collector simply resolves fewer call sites.
         {}
       end
 
@@ -240,35 +232,41 @@ module Rigor
         return if callee.nil?
 
         class_name, method, kind, def_node = callee
-        requireds = simple_requireds(def_node)
-        return if requireds.nil? || requireds.size != args.size
+        requireds = leading_requireds(def_node)
+        # Enough positional arguments to fill every leading required (extra args map to trailing
+        # optional / rest parameters, which this pass does not infer). Fewer would be an arity error
+        # or a mis-resolved callee; skip rather than mis-attribute.
+        return if requireds.nil? || args.size < requireds.size
 
         key = [class_name, method, kind]
-        args.each_with_index do |arg, i|
-          arg_scope = index[arg]
-          accumulate(key, requireds[i].name, arg_scope&.type_of(arg))
+        requireds.each_with_index do |param, i|
+          arg_scope = index[args[i]]
+          accumulate(key, param.name, arg_scope&.type_of(args[i]))
         end
       end
 
-      # The plain positional arguments, or nil when the call carries any
-      # non-plain argument (splat / keyword / block-pass / forwarding) — those
-      # break the positional-index ↔ parameter mapping, so the call site is
-      # skipped rather than mis-attributed.
+      # The plain leading positional arguments. A trailing keyword hash (`f(x, k: 1)`) or block-pass
+      # (`f(x, &blk)`) is dropped — it occupies no positional slot, so the leading args still map to
+      # the leading required parameters. Returns nil when the call carries a splat (`f(*xs, x)`) or
+      # forwarding (`f(...)`) argument: those make an argument's position depend on runtime length,
+      # breaking the positional-index ↔ parameter mapping, so the call site is skipped.
       def positional_args(call_node)
         arguments = call_node.arguments
         return [] if arguments.nil?
 
         list = arguments.arguments
-        return nil if list.any? { |arg| non_plain_argument?(arg) }
+        return nil if list.any? { |arg| position_breaking_argument?(arg) }
 
-        list
+        list.reject { |arg| non_positional_argument?(arg) }
       end
 
-      def non_plain_argument?(arg)
-        arg.is_a?(Prism::SplatNode) ||
-          arg.is_a?(Prism::KeywordHashNode) ||
+      def position_breaking_argument?(arg)
+        arg.is_a?(Prism::SplatNode) || arg.is_a?(Prism::ForwardingArgumentsNode)
+      end
+
+      def non_positional_argument?(arg)
+        arg.is_a?(Prism::KeywordHashNode) ||
           arg.is_a?(Prism::BlockArgumentNode) ||
-          arg.is_a?(Prism::ForwardingArgumentsNode) ||
           arg.is_a?(Prism::AssocNode) ||
           arg.is_a?(Prism::AssocSplatNode)
       end
@@ -307,16 +305,19 @@ module Rigor
         per_class && per_class[method]
       end
 
-      # The required-positional parameters, or nil when the method's parameter
-      # list is not a simple all-required shape (matching the single-level
-      # contract `ExpressionTyper#user_method_param_shape_simple?` uses) or
-      # contains a destructured `(a, b)` slot (no bindable name).
-      def simple_requireds(def_node)
+      # The leading required-positional parameters — the ones a call's leading positional arguments
+      # map to. Ruby orders parameters requireds-first, so optional / rest / keyword / block
+      # parameters that FOLLOW the requireds do not disturb the leading positional-index ↔
+      # required-parameter mapping; this covers the common `def f(x, opts = {}, **kw)` /
+      # `def f(x, y, &block)` shapes the earlier all-required contract skipped entirely. Returns nil
+      # only when a required slot is a destructured `(a, b)` (no bindable name) or a post-rest
+      # required (`def f(a, *b, c)` — `c` maps to a trailing arg, breaking the leading-prefix
+      # assumption for the whole call), which would mis-attribute arguments.
+      def leading_requireds(def_node)
         params = def_node.parameters
         return [] if params.nil?
         return nil unless params.is_a?(Prism::ParametersNode)
-        return nil unless params.optionals.empty? && params.rest.nil? && params.posts.empty? &&
-                          params.keywords.empty? && params.keyword_rest.nil? && params.block.nil?
+        return nil unless params.posts.empty?
         return nil unless params.requireds.all?(Prism::RequiredParameterNode)
 
         params.requireds
@@ -335,26 +336,25 @@ module Rigor
         end
       end
 
-      # A poisoned parameter is dropped from the observation store and recorded
-      # so later call sites short-circuit. `id` is the `[[class, method, kind],
-      # param]` pair.
+      # A poisoned parameter is dropped from the observation store and recorded so later call
+      # sites short-circuit. `id` is the `[[class, method, kind], param]` pair.
       def poison(id)
         @poisoned_params << id
         @type_observations.delete(id)
       end
 
       def finalize
-        # `result` is a default-block Hash (not a `{}` literal) so the analyzer
-        # types its reads generically rather than folding the empty shape — the
-        # nesting writes stay plain assignments, no literal-fold conditions.
+        # `result` is a default-block Hash (not a `{}` literal) so the analyzer types its reads
+        # generically rather than folding the empty shape — the nesting writes stay plain
+        # assignments, no literal-fold conditions.
         result = Hash.new { |hash, key| hash[key] = {} }
         @type_observations.each do |id, observations|
           next if @poisoned_params.include?(id)
           next if observations.empty?
 
           union = Type::Combinator.union(*observations)
-          # A union that collapsed to a non-concrete shape (e.g. a gradual arm
-          # leaked in) is no better than `untyped`; drop it.
+          # A union that collapsed to a non-concrete shape (e.g. a gradual arm leaked in) is no
+          # better than `untyped`; drop it.
           next if ParameterArgTypes.non_concrete?(union)
 
           key, param = id

data/lib/rigor/inference/precision_scanner.rb

@@ -6,15 +6,13 @@ require_relative "scope_indexer"
 
 module Rigor
   module Inference
-    # Measures the *type quality* of inferred expressions — not whether the
-    # engine recognises an AST node class (that is `CoverageScanner`'s job),
-    # but whether the type it produces carries useful static information.
+    # Measures the *type quality* of inferred expressions — not whether the engine recognises an AST node
+    # class (that is `CoverageScanner`'s job), but whether the type it produces carries useful static
+    # information.
     #
-    # Each visited *expression* node is classified into one of eight
-    # precision tiers (non-expression syntax nodes — argument /
-    # parameter lists, parameter declarations, hash pairs, statement
-    # wrappers, clause headers — are skipped; see
-    # {NON_EXPRESSION_NODE_TYPES}):
+    # Each visited *expression* node is classified into one of eight precision tiers (non-expression syntax
+    # nodes — argument / parameter lists, parameter declarations, hash pairs, statement wrappers, clause
+    # headers — are skipped; see {NON_EXPRESSION_NODE_TYPES}):
     #
     #   :constant         — Constant[T]: literal value known exactly
     #   :nominal          — Nominal/Singleton: class identity known
@@ -25,42 +23,35 @@ module Rigor
     #   :dynamic_top      — Dynamic[Top]: completely opaque (the "untyped" hole)
     #   :top              — Top: universal supertype (no information)
     #
-    # The summary exposes `precision_ratio` (constant+nominal+shaped+refined+bot
-    # over total) and `opaque_ratio` (dynamic_top+top over total).
+    # The summary exposes `precision_ratio` (constant+nominal+shaped+refined+bot over total) and
+    # `opaque_ratio` (dynamic_top+top over total).
     #
-    # For Union types the *worst* member tier is used, since the union is only
-    # as precise as its least-precise constituent. Intersection uses the *best*
-    # member (the most specific side wins). Difference follows its base type.
+    # For Union types the *worst* member tier is used, since the union is only as precise as its
+    # least-precise constituent. Intersection uses the *best* member (the most specific side wins).
+    # Difference follows its base type.
     class PrecisionScanner
       TIERS = %i[
         constant nominal shaped refined bot
         dynamic_specific dynamic_top top
       ].freeze
 
-      # Prism node classes that do not denote a value-producing
-      # expression, so typing them is meaningless — they have no
-      # runtime value to carry a type. Counting them (they always fall
-      # to the `dynamic_top` fallback) silently diluted the precision
-      # ratio: on a real survey target (shugo/textbringer) they were
-      # ~49% of every "opaque" node, dragging the headline number ~13
-      # points below the true expression-level precision. We exclude
-      # them from BOTH numerator and denominator so the ratio measures
-      # what it claims to — the type quality of actual expressions.
+      # Prism node classes that do not denote a value-producing expression, so typing them is meaningless —
+      # they have no runtime value to carry a type. Counting them (they always fall to the `dynamic_top`
+      # fallback) silently diluted the precision ratio: on a real survey target (shugo/textbringer) they
+      # were ~49% of every "opaque" node, dragging the headline number ~13 points below the true
+      # expression-level precision. We exclude them from BOTH numerator and denominator so the ratio
+      # measures what it claims to — the type quality of actual expressions.
       #
-      # The set is deliberately CONSERVATIVE: only nodes that are
-      # unambiguously non-expressions in Ruby's grammar are listed —
-      # argument / parameter list containers and the parameter
-      # declarations inside them; the `key => value` pair node (its key
-      # and value are themselves walked and counted); the program /
-      # statements sequence wrappers (their value is the last child,
-      # already counted — listing them avoids double-counting); and the
-      # clause-header nodes whose body, not the header, carries the
-      # value. Anything that *could* be a value expression (`BlockNode`,
-      # `BeginNode`, `ImplicitNode`, `ParenthesesNode`, splats, …) is
-      # left in so a genuine inference gap stays visible.
+      # The set is deliberately CONSERVATIVE: only nodes that are unambiguously non-expressions in Ruby's
+      # grammar are listed — argument / parameter list containers and the parameter declarations inside
+      # them; the `key => value` pair node (its key and value are themselves walked and counted); the
+      # program / statements sequence wrappers (their value is the last child, already counted — listing
+      # them avoids double-counting); and the clause-header nodes whose body, not the header, carries the
+      # value. Anything that *could* be a value expression (`BlockNode`, `BeginNode`, `ImplicitNode`,
+      # `ParenthesesNode`, splats, …) is left in so a genuine inference gap stays visible.
       #
-      # Compared by class NAME so a Prism version that lacks one of the
-      # newer node classes does not break loading.
+      # Compared by class NAME so a Prism version that lacks one of the newer node classes does not break
+      # loading.
       NON_EXPRESSION_NODE_TYPES = %w[
         Prism::ProgramNode
         Prism::StatementsNode

data/lib/rigor/inference/project_patched_methods.rb

@@ -2,33 +2,24 @@
 
 module Rigor
   module Inference
-    # ADR-17 § "Inference contract" — project-wide patched-method
-    # registry populated by the pre-eval pre-pass (slice 2) from
-    # the user's `.rigor.yml` `pre_eval:` list.
+    # ADR-17 § "Inference contract" — project-wide patched-method registry populated by the pre-eval
+    # pre-pass (slice 2) from the user's `.rigor.yml` `pre_eval:` list.
     #
-    # Each entry records one `def` declaration the pre-pass
-    # observed inside a class / module body. The dispatcher's
-    # `try_project_patched_method` tier consults this registry
-    # between the plugin tier and the dependency-source tier so
-    # project-side `lib/core_ext/string_extensions.rb` patches
-    # are visible to cross-file dispatch.
+    # Each entry records one `def` declaration the pre-pass observed inside a class / module body. The
+    # dispatcher's `try_project_patched_method` tier consults this registry between the plugin tier and
+    # the dependency-source tier so project-side `lib/core_ext/string_extensions.rb` patches are visible
+    # to cross-file dispatch.
     #
-    # The dispatcher answers `Dynamic[T]` (with a heuristic static
-    # facet) when `Entry#return_type` is non-nil, or `Dynamic[Top]`
-    # when the heuristic declined (`nil`). See {Entry} for the
-    # per-field contract.
+    # The dispatcher answers `Dynamic[T]` (with a heuristic static facet) when `Entry#return_type` is
+    # non-nil, or `Dynamic[Top]` when the heuristic declined (`nil`). See {Entry} for the per-field
+    # contract.
     class ProjectPatchedMethods
-      # Frozen value-object recording one `def` observed by the
-      # pre-pass. `class_name` is the qualified prefix
-      # (`"String"`, `"Foo::Bar"`); `method_name` is the
-      # declared name; `kind` is `:instance` or `:singleton`;
-      # `source_path` / `source_line` carry attribution for
-      # diagnostics; `return_type` is the
-      # {Analysis::DependencySourceInference::ReturnTypeHeuristic}-
-      # extracted static facet (a `Rigor::Type::*`) or `nil`
-      # when the heuristic declined. The dispatcher wraps a
-      # non-nil `return_type` in `Dynamic[T]`; a `nil`
-      # `return_type` falls back to `Dynamic[top]`.
+      # Frozen value-object recording one `def` observed by the pre-pass. `class_name` is the qualified
+      # prefix (`"String"`, `"Foo::Bar"`); `method_name` is the declared name; `kind` is `:instance` or
+      # `:singleton`; `source_path` / `source_line` carry attribution for diagnostics; `return_type` is
+      # the {Analysis::DependencySourceInference::ReturnTypeHeuristic}-extracted static facet (a
+      # `Rigor::Type::*`) or `nil` when the heuristic declined. The dispatcher wraps a non-nil
+      # `return_type` in `Dynamic[T]`; a `nil` `return_type` falls back to `Dynamic[top]`.
       Entry = Data.define(:class_name, :method_name, :kind, :source_path, :source_line, :return_type) do
         def initialize(class_name:, method_name:, kind:, source_path:, source_line:, return_type: nil)
           super
@@ -37,11 +28,9 @@ module Rigor
 
       attr_reader :by_key
 
-      # @param entries [Array<Entry>] flat list of declarations
-      #   observed during the pre-pass. First-write-wins on
-      #   `(class_name, method_name, kind)` duplicates so the
-      #   `pre-eval.duplicate-declaration` diagnostic emission
-      #   stays decoupled from registry behaviour.
+      # @param entries [Array<Entry>] flat list of declarations observed during the pre-pass.
+      #   First-write-wins on `(class_name, method_name, kind)` duplicates so the
+      #   `pre-eval.duplicate-declaration` diagnostic emission stays decoupled from registry behaviour.
       def initialize(entries: [])
         @by_key = entries.each_with_object({}) do |entry, acc|
           key = [entry.class_name, entry.method_name, entry.kind]
@@ -50,9 +39,8 @@ module Rigor
         freeze
       end
 
-      # @return [Entry, nil] the recorded entry for the given
-      #   `(class_name, method_name, kind)` triple, or `nil`
-      #   when no pre-eval file declared it.
+      # @return [Entry, nil] the recorded entry for the given `(class_name, method_name, kind)` triple,
+      #   or `nil` when no pre-eval file declared it.
       def lookup(class_name:, method_name:, kind:)
         @by_key[[class_name, method_name, kind]]
       end

data/lib/rigor/inference/project_patched_scanner.rb

@@ -8,22 +8,17 @@ require_relative "../source/constant_path"
 
 module Rigor
   module Inference
-    # ADR-17 slice 2 — pre-pass scanner. Walks every file the user
-    # listed under `pre_eval:` and harvests every `def` /
-    # `def self.` declaration inside a class / module body into a
-    # {ProjectPatchedMethods} registry the dispatcher consults
-    # below the plugin tier.
+    # ADR-17 slice 2 — pre-pass scanner. Walks every file the user listed under `pre_eval:` and
+    # harvests every `def` / `def self.` declaration inside a class / module body into a
+    # {ProjectPatchedMethods} registry the dispatcher consults below the plugin tier.
     #
-    # The walker is intentionally a strict subset of
-    # {Rigor::Inference::ScopeIndexer}'s machinery: it only needs
-    # `class C; def m; end; end` shape recognition, not full
-    # inference. Parse errors degrade to a fail-soft `:warning`
-    # `pre-eval.parse-error` diagnostic accumulated alongside
-    # the registry; per ADR-17 § "Failure modes" a parse failure
-    # in a pre-eval file MUST NOT abort the rest of the run.
+    # The walker is intentionally a strict subset of {Rigor::Inference::ScopeIndexer}'s machinery: it
+    # only needs `class C; def m; end; end` shape recognition, not full inference. Parse errors degrade
+    # to a fail-soft `:warning` `pre-eval.parse-error` diagnostic accumulated alongside the registry;
+    # per ADR-17 § "Failure modes" a parse failure in a pre-eval file MUST NOT abort the rest of the run.
     module ProjectPatchedScanner
-      # Frozen scan outcome carrying the populated registry and
-      # the per-file warnings the runner emits at run start.
+      # Frozen scan outcome carrying the populated registry and the per-file warnings the runner emits
+      # at run start.
       class Result < Data.define(:registry, :diagnostics)
         def initialize(registry:, diagnostics: [])
           super(
@@ -35,18 +30,13 @@ module Rigor
 
       module_function
 
-      # @param paths [Array<String>] absolute paths to the
-      #   pre-eval files. The runner has already validated that
-      #   each path exists (slice-1 `pre-eval.file-not-found`
-      #   `:error` covers missing entries); the scanner does NOT
-      #   re-check existence.
-      # @param buffer [Rigor::Analysis::BufferBinding, nil]
-      #   editor-mode buffer binding. When set, the scanner reads
-      #   the buffer's physical bytes if a pre-eval entry matches
-      #   the logical path, so users editing a monkey-patch file
-      #   see the in-flight version in their analysis.
-      # @return [Result] the populated registry plus any
-      #   per-file warnings.
+      # @param paths [Array<String>] absolute paths to the pre-eval files. The runner has already
+      #   validated that each path exists (slice-1 `pre-eval.file-not-found` `:error` covers missing
+      #   entries); the scanner does NOT re-check existence.
+      # @param buffer [Rigor::Analysis::BufferBinding, nil] editor-mode buffer binding. When set, the
+      #   scanner reads the buffer's physical bytes if a pre-eval entry matches the logical path, so
+      #   users editing a monkey-patch file see the in-flight version in their analysis.
+      # @return [Result] the populated registry plus any per-file warnings.
       def scan(paths, buffer: nil)
         entries = []
         diagnostics = []
@@ -58,13 +48,10 @@ 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.
+      # 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.
       def duplicate_declaration_diagnostics(entries)
         seen = {}
         entries.each_with_object([]) do |entry, acc|
@@ -129,10 +116,9 @@ module Rigor
       end
       private_class_method :parse_error_diagnostic
 
-      # Builds a diagnostic Hash-shape the runner translates to a
-      # `Rigor::Analysis::Diagnostic`. The scanner intentionally
-      # does NOT depend on the analysis layer (it's a pre-pass);
-      # the runner adapts at the call site.
+      # Builds a diagnostic Hash-shape the runner translates to a `Rigor::Analysis::Diagnostic`. The
+      # scanner intentionally does NOT depend on the analysis layer (it's a pre-pass); the runner
+      # adapts at the call site.
       def build_diagnostic(path:, line:, column:, severity:, rule:, message:)
         { path: path, line: line, column: column, severity: severity, rule: rule, message: message }
       end