rigortype 0.2.7 → 0.2.9

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

@@ -3,14 +3,15 @@
 require "prism"
 
 require_relative "scope_indexer"
+require_relative "fork_map"
 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 +21,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 +41,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 +57,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 +70,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.
@@ -127,25 +121,34 @@ module Rigor
       # @param target_ruby [String, nil] Prism parse target.
       # @param max_rounds [Integer] the WD5 fixpoint cap (1 = single-level).
       # @return [Hash{[String,Symbol,Symbol] => Hash{Symbol => Rigor::Type}}] frozen.
-      def self.collect(files:, environment:, target_ruby: nil, max_rounds: DEFAULT_ROUNDS)
-        new(files: files, environment: environment, target_ruby: target_ruby, max_rounds: max_rounds).collect
+      def self.collect(files:, environment:, target_ruby: nil, max_rounds: DEFAULT_ROUNDS, workers: 0)
+        new(files: files, environment: environment, target_ruby: target_ruby,
+            max_rounds: max_rounds, workers: workers).collect
       end
 
-      def initialize(files:, environment:, target_ruby: nil, max_rounds: DEFAULT_ROUNDS)
+      def initialize(files:, environment:, target_ruby: nil, max_rounds: DEFAULT_ROUNDS, workers: 0)
         @files = files
         @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).
+        # P3-10 — fork-parallelism for the per-round re-typing (the dominant coverage-protection cost). A
+        # round's per-file typing is independent; contributions merge associatively (see {#merge_round}), so
+        # forking over file slices is byte-identical to the sequential pass. 0/1 → sequential.
+        @workers = workers
+        # 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
 
       def collect
         parsed = parse_all
+        # Force the full RBS load on the parent so forked round-workers copy-on-write inherit a warm
+        # environment instead of each rebuilding it (mirrors the check / scan fork pools). A no-op on the
+        # sequential path.
+        @environment.rbs_loader&.prewarm if ForkMap.parallel?([@workers, parsed.size].min)
         discovery = discovery_seed_tables
         table = EMPTY
         @max_rounds.times do
@@ -159,8 +162,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,25 +173,58 @@ 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. The per-file typing is fork-mapped over
+      # `@workers` (byte-identical to sequential — see {#merge_round}); each slice returns a marshalable
+      # `[observations, poisoned]` contribution the parent merges in slice order.
       def run_round(parsed, discovery_tables, seed_table)
+        seed_scope = build_seed_scope(discovery_tables, seed_table)
+        contributions = ForkMap.call(items: parsed, workers: @workers) do |slice|
+          accumulate_slice(slice, seed_scope)
+        end
+        merge_round(contributions)
+      end
+
+      # Types every call in one contiguous file slice, returning a marshalable contribution: the per-`id`
+      # observed argument types (default proc stripped for `Marshal`) and the poisoned-`id` list. Uses the
+      # per-process observation ivars, so a forked worker and the sequential single-slice call share this
+      # exact code.
+      def accumulate_slice(parsed_slice, seed_scope)
         @type_observations = Hash.new { |hash, id| hash[id] = [] }
         @poisoned_params = Set.new
-        seed_scope = build_seed_scope(discovery_tables, seed_table)
-        parsed.each do |path, ast|
+        parsed_slice.each do |path, ast|
           index = ScopeIndexer.index(ast, default_scope: seed_scope.with_source_path(path))
           Source::NodeWalker.each(ast) do |node|
             record_call(node, index) if node.is_a?(Prism::CallNode)
           end
         end
-        finalize
+        # Copy into a plain Hash, dropping the default proc — a Marshal-unfriendly proc the fork worker
+        # would otherwise fail to dump. (`.to_h` returns self here, keeping the proc, so copy explicitly.)
+        observations = @type_observations.each_with_object({}) { |(id, types), plain| plain[id] = types }
+        [observations, @poisoned_params.to_a]
       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).
+      # Merges the per-slice contributions into the round's table. Associative and order-preserving, so the
+      # result is identical to a sequential single-slice run: a parameter is poisoned if ANY slice poisoned
+      # it, its observations are the file-order concatenation across slices, and the {MAX_CALL_SITE_TYPES}
+      # cap re-applies over the merged total (a per-slice sub-cap can undercount, so the parent enforces the
+      # real cap — the same "poisoned" outcome the sequential mid-stream cap reaches).
+      def merge_round(contributions)
+        poisoned = contributions.each_with_object(Set.new) { |(_obs, pois), set| set.merge(pois) }
+        observations = {}
+        contributions.each do |(obs, _pois)|
+          obs.each do |id, types|
+            (observations[id] ||= []).concat(types) unless poisoned.include?(id)
+          end
+        end
+        observations.each { |id, types| poisoned << id if types.length > MAX_CALL_SITE_TYPES }
+        finalize(observations, poisoned)
+      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).
       def build_seed_scope(discovery_tables, seed_table)
         base = Scope.empty(environment: @environment)
         tables = discovery_tables
@@ -209,9 +245,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 +275,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.reject { |arg| non_positional_argument?(arg) }
+      end
 
-        list
+      def position_breaking_argument?(arg)
+        arg.is_a?(Prism::SplatNode) || arg.is_a?(Prism::ForwardingArgumentsNode)
       end
 
-      def non_plain_argument?(arg)
-        arg.is_a?(Prism::SplatNode) ||
-          arg.is_a?(Prism::KeywordHashNode) ||
+      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 +348,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 +379,27 @@ 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.
+      # Builds the round's frozen `[class, method, kind] => {param => Type}` table from the merged
+      # observations and poisoned set.
+      def finalize(merged_observations, poisoned)
+        # `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)
+        merged_observations.each do |id, observations|
+          next if poisoned.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