rigortype 0.2.7 → 0.2.8

data/lib/rigor/analysis/dependency_recorder.rb

@@ -2,26 +2,21 @@
 
 module Rigor
   module Analysis
-    # ADR-46 slice 1 — records, per analyzed file, which OTHER source
-    # files its analysis read declarations / method bodies from (the
-    # cross-file dependency edges), plus the cross-file lookups that
-    # resolved to nothing (negative edges — adding that symbol later must
-    # re-check the consumer).
+    # ADR-46 slice 1 — records, per analyzed file, which OTHER source files its analysis read declarations /
+    # method bodies from (the cross-file dependency edges), plus the cross-file lookups that resolved to
+    # nothing (negative edges — adding that symbol later must re-check the consumer).
     #
-    # Thread-local and activated per `analyze_file` only when the runner
-    # opts in (`record_dependencies: true`); a normal run never activates
-    # it, so {active?} is a single nil-check and the instrumented `Scope`
-    # accessors pay nothing. Recording is purely observational — it never
-    # changes a diagnostic.
+    # Thread-local and activated per `analyze_file` only when the runner opts in (`record_dependencies: true`);
+    # a normal run never activates it, so {active?} is a single nil-check and the instrumented `Scope`
+    # accessors pay nothing. Recording is purely observational — it never changes a diagnostic.
     #
-    # Modelled on {Inference::BudgetTrace}: process-thread-local state, a
-    # cheap disabled fast path, and a frozen snapshot for consumers.
+    # Modelled on {Inference::BudgetTrace}: process-thread-local state, a cheap disabled fast path, and a
+    # frozen snapshot for consumers.
     module DependencyRecorder
       KEY = :__rigor_dependency_recorder__
       private_constant :KEY
 
-      # Mutable per-consumer accumulator. Frozen into a {Record} snapshot
-      # when `record_for` returns.
+      # Mutable per-consumer accumulator. Frozen into a {Record} snapshot when `record_for` returns.
       class Accumulator
         attr_reader :consumer, :sources, :missing, :symbol_sources, :ancestry_sources
 
@@ -31,8 +26,8 @@ module Rigor
           @missing = Set.new
           # ADR-46 slice 4 — symbol-granularity tracking.
           # `symbol_sources`: source_path → Set<"ClassName#method"> for method-call deps.
-          # `ancestry_sources`: Set<source_path> for class-ancestry (superclass / include)
-          # deps — file-granularity by nature (a superclass edge touches the whole class).
+          # `ancestry_sources`: Set<source_path> for class-ancestry (superclass / include) deps —
+          # file-granularity by nature (a superclass edge touches the whole class).
           @symbol_sources = Hash.new { |h, k| h[k] = Set.new }
           @ancestry_sources = Set.new
         end
@@ -54,22 +49,19 @@ module Rigor
       # `ancestry_sources`: frozen Set<source_path> (class-ancestry edges, file-granularity).
       Record = Data.define(:consumer, :sources, :missing, :symbol_sources, :ancestry_sources)
 
-      # Module-level activation count so the disabled fast path
-      # ({active?}) is a plain integer read rather than a `Thread.current`
-      # hash lookup — `user_def_for` (the instrumented accessor) is on the
-      # per-dispatch hot path, so a normal (non-recording) run must pay as
-      # little as possible. The per-thread accumulator still isolates the
-      # actual recording, so a non-recording thread seeing `active?` true
+      # Module-level activation count so the disabled fast path ({active?}) is a plain integer read rather
+      # than a `Thread.current` hash lookup — `user_def_for` (the instrumented accessor) is on the
+      # per-dispatch hot path, so a normal (non-recording) run must pay as little as possible. The per-thread
+      # accumulator still isolates the actual recording, so a non-recording thread seeing `active?` true
       # (another thread is recording) just performs an extra nil-check.
       @active_count = 0
       @mutex = Mutex.new
 
       module_function
 
-      # Activates recording for `consumer` (the path being analyzed) for
-      # the duration of the block and returns the frozen {Record}. Nests
-      # safely (the inner consumer's reads do not leak to the outer one);
-      # restores the previous recorder on exit.
+      # Activates recording for `consumer` (the path being analyzed) for the duration of the block and returns
+      # the frozen {Record}. Nests safely (the inner consumer's reads do not leak to the outer one); restores
+      # the previous recorder on exit.
       def record_for(consumer)
         previous = Thread.current[KEY]
         accumulator = Accumulator.new(consumer.to_s)
@@ -82,20 +74,16 @@ module Rigor
         @mutex.synchronize { @active_count -= 1 }
       end
 
-      # Plain integer read (GVL-atomic) — no `Thread.current` lookup on the
-      # disabled fast path.
+      # Plain integer read (GVL-atomic) — no `Thread.current` lookup on the disabled fast path.
       def active?
         @active_count.positive?
       end
 
-      # Records that the current consumer read a declaration / body whose
-      # definition site is `path_line` (a `"path:line"` String, or nil).
-      # When `symbol` is given (a `"ClassName#method"` String), the read is
-      # a method-call edge and is recorded at symbol granularity in
-      # `symbol_sources` in addition to the coarse `sources` set.
-      # Without `symbol` the read is a class-ancestry edge (file-granularity)
-      # and is added to `ancestry_sources` only.
-      # Self-reads and nil sites are ignored in all cases.
+      # Records that the current consumer read a declaration / body whose definition site is `path_line` (a
+      # `"path:line"` String, or nil). When `symbol` is given (a `"ClassName#method"` String), the read is a
+      # method-call edge and is recorded at symbol granularity in `symbol_sources` in addition to the coarse
+      # `sources` set. Without `symbol` the read is a class-ancestry edge (file-granularity) and is added to
+      # `ancestry_sources` only. Self-reads and nil sites are ignored in all cases.
       def read_site(path_line, symbol = nil)
         accumulator = Thread.current[KEY]
         return if accumulator.nil? || path_line.nil?
@@ -111,8 +99,8 @@ module Rigor
         end
       end
 
-      # Records a cross-file lookup of `name` (kind `:method` / `:class` /
-      # `:const` / …) that resolved to nothing — a negative dependency.
+      # Records a cross-file lookup of `name` (kind `:method` / `:class` / `:const` / …) that resolved to
+      # nothing — a negative dependency.
       def read_missing(kind, name)
         accumulator = Thread.current[KEY]
         accumulator&.missing&.add("#{kind}:#{name}")

data/lib/rigor/analysis/dependency_source_inference/boundary_cross_reporter.rb

@@ -3,26 +3,19 @@
 module Rigor
   module Analysis
     module DependencySourceInference
-      # ADR-10 slice 5c — per-run accumulator for the
-      # `dynamic.dependency-source.boundary-cross` `:info`
+      # ADR-10 slice 5c — per-run accumulator for the `dynamic.dependency-source.boundary-cross` `:info`
       # diagnostic.
       #
-      # The diagnostic fires when both an authoritative source
-      # (RBS today; plugins later) AND a `mode: :full` opt-in
-      # gem's source catalog resolve the same `(class_name,
-      # method_name)`. The dispatcher takes the authoritative
-      # source's answer (per ADR-10's tier order), but records
-      # the boundary crossing so the user can audit whether RBS
-      # and the gem source have drifted.
+      # The diagnostic fires when both an authoritative source (RBS today; plugins later) AND a `mode: :full`
+      # opt-in gem's source catalog resolve the same `(class_name, method_name)`. The dispatcher takes the
+      # authoritative source's answer (per ADR-10's tier order), but records the boundary crossing so the user
+      # can audit whether RBS and the gem source have drifted.
       #
-      # The accumulator deduplicates per `(class_name,
-      # method_name, gem_name)` so a method called from many
+      # The accumulator deduplicates per `(class_name, method_name, gem_name)` so a method called from many
       # files yields one diagnostic.
       #
-      # Used in the same pattern as
-      # {Rigor::RbsExtended::Reporter}: the dispatcher writes
-      # events into the per-run instance; {Rigor::Analysis::Runner}
-      # drains it at end-of-run into a flat
+      # Used in the same pattern as {Rigor::RbsExtended::Reporter}: the dispatcher writes events into the
+      # per-run instance; {Rigor::Analysis::Runner} drains it at end-of-run into a flat
       # `Rigor::Analysis::Diagnostic` list.
       class BoundaryCrossReporter
         Entry = Data.define(:class_name, :method_name, :gem_name, :rbs_display)
@@ -32,12 +25,9 @@ module Rigor
           @mutex = Mutex.new
         end
 
-        # @return [Array<Entry>] frozen snapshot of the recorded
-        #   boundary-cross events. Each entry is a Data with
-        #   `class_name` (String), `method_name` (Symbol),
-        #   `gem_name` (String), and `rbs_display` (String —
-        #   the authoritative-side type's human-facing form,
-        #   embedded into the diagnostic message).
+        # @return [Array<Entry>] frozen snapshot of the recorded boundary-cross events. Each entry is a Data
+        #   with `class_name` (String), `method_name` (Symbol), `gem_name` (String), and `rbs_display` (String
+        #   — the authoritative-side type's human-facing form, embedded into the diagnostic message).
         def entries
           @mutex.synchronize { @entries.dup.freeze }
         end
@@ -46,10 +36,8 @@ module Rigor
           @mutex.synchronize { @entries.empty? }
         end
 
-        # Records one boundary-cross event. Deduplicates on the
-        # `(class_name, method_name, gem_name)` triple — the
-        # diagnostic per-receiver-per-method-per-owning-gem is
-        # the actionable unit.
+        # Records one boundary-cross event. Deduplicates on the `(class_name, method_name, gem_name)` triple —
+        # the diagnostic per-receiver-per-method-per-owning-gem is the actionable unit.
         def record(class_name:, method_name:, gem_name:, rbs_display:)
           entry = Entry.new(
             class_name: class_name, method_name: method_name,

data/lib/rigor/analysis/dependency_source_inference/builder.rb

@@ -7,17 +7,13 @@ require_relative "walker"
 module Rigor
   module Analysis
     module DependencySourceInference
-      # Folds a `Configuration::Dependencies` value into a
-      # frozen {Index}. Resolves each non-disabled entry through
-      # {GemResolver}, walks each resolved gem's `roots:` via
-      # {Walker.walk} under the configured `budget_per_gem` cap,
-      # and aggregates the per-gem method catalogs into the
-      # Index's flat `(class_name, method_name) → kind` table.
+      # Folds a `Configuration::Dependencies` value into a frozen {Index}. Resolves each non-disabled entry
+      # through {GemResolver}, walks each resolved gem's `roots:` via {Walker.walk} under the configured
+      # `budget_per_gem` cap, and aggregates the per-gem method catalogs into the Index's flat
+      # `(class_name, method_name) → kind` table.
       #
-      # Entries with `mode: :disabled` are skipped without
-      # resolution attempts so users can "list and disable" a
-      # gem in configuration without provoking a missing-gem
-      # diagnostic.
+      # Entries with `mode: :disabled` are skipped without resolution attempts so users can "list and disable"
+      # a gem in configuration without provoking a missing-gem diagnostic.
       module Builder
         module_function
 
@@ -36,12 +32,9 @@ module Rigor
           state.to_index(dependencies)
         end
 
-        # Per-build mutable accumulator. The original inline
-        # variables (`resolved` / `unresolvable` / `catalog` /
-        # `class_to_gem` / `budget_exceeded` / `gem_modes`)
-        # pushed the method past the AbcSize budget; the
-        # struct collects the same fields, narrows
-        # `absorb`'s branching, and yields one
+        # Per-build mutable accumulator. The original inline variables (`resolved` / `unresolvable` /
+        # `catalog` / `class_to_gem` / `budget_exceeded` / `gem_modes`) pushed the method past the AbcSize
+        # budget; the struct collects the same fields, narrows `absorb`'s branching, and yields one
         # `Index.new(...)` call from `to_index`.
         class BuildState
           def initialize
@@ -82,26 +75,20 @@ module Rigor
           end
         end
 
-        # ADR-10 5b — per-class reverse-lookup table (β budget
-        # semantics). Records `class_name → gem_name` for every
-        # class observed in the gem's catalog. First-write-wins:
-        # if two opt-in gems re-open the same class, the first
-        # gem to harvest the class owns it in the reverse index.
-        # The dispatcher only consults this map when the
-        # `budget_overrun_strategy` is `:dependency_silence`,
-        # so the storage cost is never paid back unless the
-        # user opts in.
+        # ADR-10 5b — per-class reverse-lookup table (β budget semantics). Records `class_name → gem_name` for
+        # every class observed in the gem's catalog. First-write-wins: if two opt-in gems re-open the same
+        # class, the first gem to harvest the class owns it in the reverse index. The dispatcher only consults
+        # this map when the `budget_overrun_strategy` is `:dependency_silence`, so the storage cost is never
+        # paid back unless the user opts in.
         def record_class_to_gem(catalog, gem_name, class_to_gem)
           catalog.each_key do |(class_name, _method_name)|
             class_to_gem[class_name] ||= gem_name
           end
         end
 
-        # Per-resolved-gem walk. Isolated so a single gem's
-        # filesystem error / parse failure cannot abort the
-        # build; the walker swallows its own per-file errors,
-        # and a top-level raise here degrades the gem to "no
-        # contributions" without touching the rest of the run.
+        # Per-resolved-gem walk. Isolated so a single gem's filesystem error / parse failure cannot abort the
+        # build; the walker swallows its own per-file errors, and a top-level raise here degrades the gem to
+        # "no contributions" without touching the rest of the run.
         def walker_outcome_for(resolved, budget)
           Walker.walk(gem_dir: resolved.gem_dir, roots: resolved.roots, budget: budget)
         rescue StandardError

data/lib/rigor/analysis/dependency_source_inference/gem_resolver.rb

@@ -3,34 +3,26 @@
 module Rigor
   module Analysis
     module DependencySourceInference
-      # Maps a `Configuration::Dependencies::Entry` to the gem's
-      # on-disk installation directory by consulting RubyGems
-      # (`Gem.loaded_specs` first, falling back to
-      # `Gem::Specification.find_by_name`). Returns either a
-      # frozen {Resolved} value object or an {Unresolvable} value
-      # describing why the gem cannot participate in this run.
+      # Maps a `Configuration::Dependencies::Entry` to the gem's on-disk installation directory by consulting
+      # RubyGems (`Gem.loaded_specs` first, falling back to `Gem::Specification.find_by_name`). Returns either
+      # a frozen {Resolved} value object or an {Unresolvable} value describing why the gem cannot participate
+      # in this run.
       #
-      # Resolution failures are surfaced as
-      # `dynamic.dependency-source.gem-not-found` diagnostics by
-      # {Analysis::Runner} rather than crashing the run, so a
-      # missing gem in `dependencies.source_inference` degrades
-      # cleanly to "no contributions from that gem" — every other
-      # gem and the project source remain unaffected.
+      # Resolution failures are surfaced as `dynamic.dependency-source.gem-not-found` diagnostics by
+      # {Analysis::Runner} rather than crashing the run, so a missing gem in `dependencies.source_inference`
+      # degrades cleanly to "no contributions from that gem" — every other gem and the project source remain
+      # unaffected.
       module GemResolver
-        # Successful resolution. `version` is the spec version as
-        # a String so it round-trips into cache descriptors
-        # (slice 3) without leaking a `Gem::Version` instance
-        # through public surfaces.
+        # Successful resolution. `version` is the spec version as a String so it round-trips into cache
+        # descriptors (slice 3) without leaking a `Gem::Version` instance through public surfaces.
         class Resolved < Data.define(:gem_name, :version, :gem_dir, :mode, :roots)
           def descriptor_key
             [gem_name, version, mode].freeze
           end
         end
 
-        # Unresolvable reasons. `:not_in_bundle` covers both the
-        # "RubyGems doesn't know this gem" case and the
-        # `LoadError`-style raise from `find_by_name`. Future
-        # reasons (`:c_extension_only`, `:no_lib_root`) are
+        # Unresolvable reasons. `:not_in_bundle` covers both the "RubyGems doesn't know this gem" case and the
+        # `LoadError`-style raise from `find_by_name`. Future reasons (`:c_extension_only`, `:no_lib_root`) are
         # introduced as the walker discovers them in slice 2b.
         Unresolvable = Data.define(:gem_name, :reason)
 
@@ -53,12 +45,9 @@ module Rigor
           )
         end
 
-        # Locator. `Gem.loaded_specs` reflects the bundle (cheap
-        # lookup, no filesystem walk); `find_by_name` is the
-        # broader fallback for gems present on the gem path but
-        # not yet `require`'d. `Gem::MissingSpecError` is a
-        # `LoadError` subclass, so the rescue covers both
-        # missing-spec and load-error signals.
+        # Locator. `Gem.loaded_specs` reflects the bundle (cheap lookup, no filesystem walk); `find_by_name` is
+        # the broader fallback for gems present on the gem path but not yet `require`'d. `Gem::MissingSpecError`
+        # is a `LoadError` subclass, so the rescue covers both missing-spec and load-error signals.
         def locate_gem_spec(name)
           Gem.loaded_specs[name] || begin
             Gem::Specification.find_by_name(name)

data/lib/rigor/analysis/dependency_source_inference/index.rb

@@ -5,45 +5,31 @@ require_relative "../../cache/descriptor"
 module Rigor
   module Analysis
     module DependencySourceInference
-      # Per-run collection of gem-source-inference state. Holds
-      # the resolved gems the walker visits plus the unresolvable
-      # entries the runner surfaces as
-      # `dynamic.dependency-source.gem-not-found` diagnostics.
-      # The method table is fully populated by {Walker} at build
-      # time; {#contribution_for} returns live entries.
+      # Per-run collection of gem-source-inference state. Holds the resolved gems the walker visits plus the
+      # unresolvable entries the runner surfaces as `dynamic.dependency-source.gem-not-found` diagnostics.
+      # The method table is fully populated by {Walker} at build time; {#contribution_for} returns live
+      # entries.
       class Index
         attr_reader :resolved_gems, :unresolvable, :method_catalog, :budget_exceeded,
                     :class_to_gem, :budget_overrun_strategy, :gem_modes
 
-        # @param method_catalog [Hash{[String, Symbol] => Symbol}]
-        #   the flat `(class_name, method_name) → :instance | :singleton`
-        #   table produced by {Walker.walk}, aggregated across
-        #   every resolved gem in the run. The Index itself stays
-        #   gem-agnostic — the per-gem attribution that slice 3's
-        #   cache descriptor needs lives on `Resolved`, not here.
-        # @param budget_exceeded [Array<String>] gem names whose
-        #   {Walker} run hit the per-gem catalog cap (slice 4).
-        #   The Runner consumes this list to emit one
-        #   `dynamic.dependency-source.budget-exceeded` warning
-        #   per gem.
-        # @param class_to_gem [Hash<String, String>] reverse
-        #   lookup `class_name → gem_name` (slice 5b). Built
-        #   first-write-wins: when two opt-in gems re-open the
-        #   same class, the first gem owns it. The dispatcher
-        #   consults this map under the `:dependency_silence`
-        #   budget overrun strategy so call sites on a
-        #   budget-exceeded gem's classes degrade to
-        #   `Dynamic[top]` instead of falling through to the
-        #   user-class fallback.
-        # @param gem_modes [Hash<String, Symbol>] per-gem mode
-        #   table (`gem_name → :disabled | :when_missing |
-        #   :full`). ADR-10 slice 5c consults this through
-        #   {#mode_for} to identify call sites where gem-source
-        #   and RBS both contribute under `mode: :full`. The map
-        #   is keyed on `gem_name` (not class) because re-opened
-        #   classes belong to the first gem they appeared in
-        #   per `class_to_gem`; `mode_for(class_name)` chains
-        #   the two lookups.
+        # @param method_catalog [Hash{[String, Symbol] => Symbol}] the flat
+        #   `(class_name, method_name) → :instance | :singleton` table produced by {Walker.walk}, aggregated
+        #   across every resolved gem in the run. The Index itself stays gem-agnostic — the per-gem
+        #   attribution that slice 3's cache descriptor needs lives on `Resolved`, not here.
+        # @param budget_exceeded [Array<String>] gem names whose {Walker} run hit the per-gem catalog cap
+        #   (slice 4). The Runner consumes this list to emit one `dynamic.dependency-source.budget-exceeded`
+        #   warning per gem.
+        # @param class_to_gem [Hash<String, String>] reverse lookup `class_name → gem_name` (slice 5b). Built
+        #   first-write-wins: when two opt-in gems re-open the same class, the first gem owns it. The
+        #   dispatcher consults this map under the `:dependency_silence` budget overrun strategy so call
+        #   sites on a budget-exceeded gem's classes degrade to `Dynamic[top]` instead of falling through to
+        #   the user-class fallback.
+        # @param gem_modes [Hash<String, Symbol>] per-gem mode table (`gem_name → :disabled | :when_missing |
+        #   :full`). ADR-10 slice 5c consults this through {#mode_for} to identify call sites where
+        #   gem-source and RBS both contribute under `mode: :full`. The map is keyed on `gem_name` (not
+        #   class) because re-opened classes belong to the first gem they appeared in per `class_to_gem`;
+        #   `mode_for(class_name)` chains the two lookups.
         def initialize(
           resolved_gems: [], unresolvable: [], method_catalog: {},
           budget_exceeded: [], class_to_gem: {},
@@ -59,12 +45,10 @@ module Rigor
           freeze
         end
 
-        # Accepts both the post-heuristic `CatalogEntry` shape
-        # (the Walker's current output) and the legacy bare-Symbol
-        # `:instance` / `:singleton` shape (older tests + earlier
-        # in-tree callers). Symbol values are wrapped into
-        # `CatalogEntry(kind: value, return_type: nil)` so the
-        # downstream dispatcher always sees a single shape.
+        # Accepts both the post-heuristic `CatalogEntry` shape (the Walker's current output) and the legacy
+        # bare-Symbol `:instance` / `:singleton` shape (older tests + earlier in-tree callers). Symbol values
+        # are wrapped into `CatalogEntry(kind: value, return_type: nil)` so the downstream dispatcher always
+        # sees a single shape.
         def normalize_catalog(catalog)
           catalog.transform_values do |value|
             value.is_a?(Symbol) ? Walker::CatalogEntry.new(kind: value) : value
@@ -72,16 +56,14 @@ module Rigor
         end
         private :normalize_catalog
 
-        # @return [String, nil] the gem that owns `class_name`
-        #   (first-write-wins); `nil` when the class isn't in
-        #   any opt-in gem's catalog.
+        # @return [String, nil] the gem that owns `class_name` (first-write-wins); `nil` when the class isn't
+        #   in any opt-in gem's catalog.
         def gem_for(class_name)
           @class_to_gem[class_name]
         end
 
-        # ADR-10 slice 5c — per-class mode lookup. Chains
-        # `class_to_gem` + `gem_modes`; returns `nil` when the
-        # class isn't owned by any opt-in gem in this run.
+        # ADR-10 slice 5c — per-class mode lookup. Chains `class_to_gem` + `gem_modes`; returns `nil` when
+        # the class isn't owned by any opt-in gem in this run.
         def mode_for(class_name)
           gem_name = @class_to_gem[class_name]
           return nil if gem_name.nil?
@@ -89,22 +71,17 @@ module Rigor
           @gem_modes[gem_name]
         end
 
-        # ADR-10 slice 5c — true when the receiver class belongs
-        # to a gem the user opted into `mode: :full` for. The
-        # dispatcher consults this AFTER an authoritative-source
-        # (RBS / plugin) dispatch resolves so it can record the
-        # boundary-crossing for audit.
+        # ADR-10 slice 5c — true when the receiver class belongs to a gem the user opted into `mode: :full`
+        # for. The dispatcher consults this AFTER an authoritative-source (RBS / plugin) dispatch resolves
+        # so it can record the boundary-crossing for audit.
         def full_mode?(class_name)
           mode_for(class_name) == :full
         end
 
-        # Looks up the recorded method kind for a
-        # `(class_name, method_name)` pair. Returns `:instance`
-        # / `:singleton` when the walker observed a definition
-        # under one of the resolved gems' `roots:`, or `nil`
-        # otherwise. Slice 2b-ii enriches this with the inferred
-        # return type so the dispatcher tier can build a
-        # `Type::Dynamic` directly from the lookup result.
+        # Looks up the recorded method kind for a `(class_name, method_name)` pair. Returns `:instance` /
+        # `:singleton` when the walker observed a definition under one of the resolved gems' `roots:`, or
+        # `nil` otherwise. Slice 2b-ii enriches this with the inferred return type so the dispatcher tier can
+        # build a `Type::Dynamic` directly from the lookup result.
         def contribution_for(class_name:, method_name:)
           @method_catalog[[class_name, method_name]]
         end
@@ -113,20 +90,14 @@ module Rigor
           @resolved_gems.empty?
         end
 
-        # Builds a frozen `Cache::Descriptor` carrying one
-        # `DependencyEntry` row per resolved gem in this run.
-        # Cache producers that observe ADR-10 inference outputs
-        # compose this descriptor with their own (RBS, plugin,
-        # file-digest) descriptors so a `bundle update` on a
-        # listed gem invalidates exactly that gem's slice while
-        # leaving the rest of the cache hot.
+        # Builds a frozen `Cache::Descriptor` carrying one `DependencyEntry` row per resolved gem in this
+        # run. Cache producers that observe ADR-10 inference outputs compose this descriptor with their own
+        # (RBS, plugin, file-digest) descriptors so a `bundle update` on a listed gem invalidates exactly
+        # that gem's slice while leaving the rest of the cache hot.
         #
-        # Unresolvable entries contribute nothing — there is no
-        # version to key on, and the runner already surfaces them
-        # as `dynamic.dependency-source.gem-not-found`
-        # diagnostics. Resolved-but-disabled entries are also
-        # absent: the {Builder} skips them before resolution, so
-        # they never reach the index.
+        # Unresolvable entries contribute nothing — there is no version to key on, and the runner already
+        # surfaces them as `dynamic.dependency-source.gem-not-found` diagnostics. Resolved-but-disabled
+        # entries are also absent: the {Builder} skips them before resolution, so they never reach the index.
         def cache_descriptor
           dependencies = @resolved_gems.map do |resolved|
             Cache::Descriptor::DependencyEntry.new(
@@ -139,10 +110,8 @@ module Rigor
         end
       end
 
-      # Frozen empty index — the runner uses this when
-      # `Configuration#dependencies.source_inference` is empty
-      # so the dispatcher tier holds a stable, non-nil
-      # reference even on default configurations.
+      # Frozen empty index — the runner uses this when `Configuration#dependencies.source_inference` is
+      # empty so the dispatcher tier holds a stable, non-nil reference even on default configurations.
       Index::EMPTY = Index.new.freeze
     end
   end

data/lib/rigor/analysis/dependency_source_inference/return_type_heuristic.rb

@@ -7,42 +7,30 @@ require_relative "../../type"
 module Rigor
   module Analysis
     module DependencySourceInference
-      # Walker enhancement (ADR-10 § "Open questions"): pulls a
-      # **heuristic** return type out of a method body's tail
-      # expression. The heuristic is intentionally narrow — only
-      # the trivially-decidable shapes contribute. Everything
-      # else returns `nil`, which the dispatcher consumes as
-      # "fall back to `Dynamic[top]`" (the pre-enhancement
-      # behaviour).
+      # Walker enhancement (ADR-10 § "Open questions"): pulls a **heuristic** return type out of a method
+      # body's tail expression. The heuristic is intentionally narrow — only the trivially-decidable shapes
+      # contribute. Everything else returns `nil`, which the dispatcher consumes as "fall back to
+      # `Dynamic[top]`" (the pre-enhancement behaviour).
       #
       # The contract is a strict floor:
       #
-      # - Last statement is a literal scalar (Integer / Float /
-      #   Symbol / true / false / nil) → `Constant<value>`.
-      # - Last statement is a String literal → `Nominal[String]`
-      #   (NOT `Constant<"x">`; a String literal is mutable under
-      #   `# frozen_string_literal: false`, so the analyzer cannot
-      #   claim object identity).
-      # - Last statement is an Array / Hash literal →
-      #   `Nominal[Array]` / `Nominal[Hash]` (element-type
-      #   inference stays deferred — too expensive for the
-      #   heuristic tier).
-      # - Last statement is `self` → `nil` (the caller's receiver
-      #   nominal would be more accurate but the walker doesn't
-      #   carry the receiver context; deferred).
+      # - Last statement is a literal scalar (Integer / Float / Symbol / true / false / nil) → `Constant<value>`.
+      # - Last statement is a String literal → `Nominal[String]` (NOT `Constant<"x">`; a String literal is
+      #   mutable under `# frozen_string_literal: false`, so the analyzer cannot claim object identity).
+      # - Last statement is an Array / Hash literal → `Nominal[Array]` / `Nominal[Hash]` (element-type
+      #   inference stays deferred — too expensive for the heuristic tier).
+      # - Last statement is `self` → `nil` (the caller's receiver nominal would be more accurate but the
+      #   walker doesn't carry the receiver context; deferred).
       # - Anything else → `nil`.
       #
-      # The dispatcher wraps the returned type in `Dynamic[T]`
-      # before returning to the user per ADR-10's `Dynamic`-origin
-      # contract. The wrapping is the dispatcher's responsibility,
-      # not the heuristic's.
+      # The dispatcher wraps the returned type in `Dynamic[T]` before returning to the user per ADR-10's
+      # `Dynamic`-origin contract. The wrapping is the dispatcher's responsibility, not the heuristic's.
       module ReturnTypeHeuristic
         module_function
 
         # @param def_node [Prism::DefNode]
-        # @return [Rigor::Type, nil] heuristic return type, or
-        #   `nil` when the body's tail expression doesn't match
-        #   any of the recognised shapes.
+        # @return [Rigor::Type, nil] heuristic return type, or `nil` when the body's tail expression doesn't
+        #   match any of the recognised shapes.
         def extract(def_node)
           body = def_node.body
           return nil if body.nil?
@@ -51,11 +39,9 @@ module Rigor
           literal_return_type(tail)
         end
 
-        # Extracts the last evaluated expression of the method
-        # body. A `Prism::DefNode`'s body is either a
-        # `StatementsNode` (multi-statement body) or a single
-        # expression node directly. We dig past `BeginNode` /
-        # rescue wrappers to the protected body's tail.
+        # Extracts the last evaluated expression of the method body. A `Prism::DefNode`'s body is either a
+        # `StatementsNode` (multi-statement body) or a single expression node directly. We dig past
+        # `BeginNode` / rescue wrappers to the protected body's tail.
         def tail_expression(node)
           case node
           when Prism::StatementsNode
@@ -70,11 +56,9 @@ module Rigor
         end
         private_class_method :tail_expression
 
-        # The per-shape heuristic. Per the module docstring,
-        # immutable scalar literals fold to `Constant<value>`;
-        # mutable container literals (String, Array, Hash) fold
-        # to the appropriate Nominal; everything else returns
-        # nil.
+        # The per-shape heuristic. Per the module docstring, immutable scalar literals fold to `Constant<value>`;
+        # mutable container literals (String, Array, Hash) fold to the appropriate Nominal; everything else
+        # returns nil.
         def literal_return_type(node)
           case node
           when Prism::IntegerNode, Prism::FloatNode then Type::Combinator.constant_of(node.value)
@@ -89,9 +73,8 @@ module Rigor
         end
         private_class_method :literal_return_type
 
-        # `Prism::SymbolNode#value` returns the Symbol's name as
-        # a String. We `.to_sym` it for the Constant carrier so
-        # `:foo` is `Constant<:foo>`, not `Constant<"foo">`.
+        # `Prism::SymbolNode#value` returns the Symbol's name as a String. We `.to_sym` it for the Constant
+        # carrier so `:foo` is `Constant<:foo>`, not `Constant<"foo">`.
         def symbol_constant(node)
           value = node.value
           return nil if value.nil?