rigortype 0.2.7 → 0.2.8

data/lib/rigor/analysis/incremental.rb

@@ -2,34 +2,28 @@
 
 module Rigor
   module Analysis
-    # ADR-46 slice 2 — the pure set-algebra core of the incremental step,
-    # kept side-effect-free and Runner-independent so the soundness
-    # property it encodes is unit-testable without the analysis machinery.
+    # ADR-46 slice 2 — the pure set-algebra core of the incremental step, kept side-effect-free and
+    # Runner-independent so the soundness property it encodes is unit-testable without the analysis machinery.
     #
-    # Given the files that changed since the baseline run and the
-    # baseline's `dependents` index ({Runner#file_dependents}), the
-    # **affected closure** the body tier must re-analyse is the changed set
-    # plus every file that read a declaration or method body from a changed
-    # file. Every other file is served from the per-file diagnostic cache.
+    # Given the files that changed since the baseline run and the baseline's `dependents` index
+    # ({Runner#file_dependents}), the **affected closure** the body tier must re-analyse is the changed set
+    # plus every file that read a declaration or method body from a changed file. Every other file is served
+    # from the per-file diagnostic cache.
     #
-    # The soundness invariant (the {Runner}-driven `--verify-incremental`
-    # gate and the spec assert it): for an edit whose declaration-structure
-    # fingerprint is unchanged (a method-body edit — no symbol created,
-    # destroyed, moved, or re-parented), the set of files whose diagnostics
-    # actually change is a SUBSET of {affected}. A file outside the closure
-    # whose diagnostics changed would be served stale — a manufactured
-    # false positive/negative, the failure mode this design exists to
-    # prevent. Structural edits (fingerprint changed) are out of this
-    # tier's scope — they widen via the negative-dependency / full fallback
-    # path (slice 3).
+    # The soundness invariant (the {Runner}-driven `--verify-incremental` gate and the spec assert it): for an
+    # edit whose declaration-structure fingerprint is unchanged (a method-body edit — no symbol created,
+    # destroyed, moved, or re-parented), the set of files whose diagnostics actually change is a SUBSET of
+    # {affected}. A file outside the closure whose diagnostics changed would be served stale — a manufactured
+    # false positive/negative, the failure mode this design exists to prevent. Structural edits (fingerprint
+    # changed) are out of this tier's scope — they widen via the negative-dependency / full fallback path
+    # (slice 3).
     module Incremental
       module_function
 
-      # Inverts a per-consumer source map (`consumer → enumerable of source
-      # files it read from`) into the `dependents` index (`source → Set of
-      # consumers that read from it`). The reverse edge the incremental step
-      # walks. Returns a frozen hash of frozen Sets; a missing key reads as
-      # nil (the default proc is dropped before freezing).
+      # Inverts a per-consumer source map (`consumer → enumerable of source files it read from`) into the
+      # `dependents` index (`source → Set of consumers that read from it`). The reverse edge the incremental
+      # step walks. Returns a frozen hash of frozen Sets; a missing key reads as nil (the default proc is
+      # dropped before freezing).
       def invert(sources_by_consumer)
         index = Hash.new { |hash, key| hash[key] = Set.new }
         sources_by_consumer.each do |consumer, sources|
@@ -40,20 +34,18 @@ module Rigor
         index.freeze
       end
 
-      # The closure the body tier re-analyses. `changed` is any Enumerable
-      # of paths; `dependents` maps a source path to the Set of files that
-      # read from it (missing key → no dependents). Returns a frozen Set.
+      # The closure the body tier re-analyses. `changed` is any Enumerable of paths; `dependents` maps a
+      # source path to the Set of files that read from it (missing key → no dependents). Returns a frozen Set.
       def affected(changed, dependents)
         closure = changed.to_set
         changed.each { |file| closure.merge(dependents[file] || []) }
         closure.freeze
       end
 
-      # ADR-46 slice 4 — inverts a per-consumer symbol-sources map
-      # (`consumer → { source_path → Set<"ClassName#method"> }`) into the
-      # symbol-level dependents index: `[source_path, symbol] → Set<consumer>`.
-      # Used by {affected_with_symbols} to limit fan-out to callers of
-      # symbols that actually changed rather than all callers of the file.
+      # ADR-46 slice 4 — inverts a per-consumer symbol-sources map (`consumer → { source_path →
+      # Set<"ClassName#method"> }`) into the symbol-level dependents index: `[source_path, symbol] →
+      # Set<consumer>`. Used by {affected_with_symbols} to limit fan-out to callers of symbols that actually
+      # changed rather than all callers of the file.
       def invert_symbols(symbol_sources_by_consumer)
         index = Hash.new { |h, k| h[k] = Set.new }
         symbol_sources_by_consumer.each do |consumer, sources_by_file|
@@ -66,10 +58,9 @@ module Rigor
         index.freeze
       end
 
-      # ADR-46 slice 4 — given a set of changed file paths and two per-file
-      # symbol fingerprint maps (before and after), returns the frozen Set of
-      # `[path, symbol]` pairs whose fingerprints differ (added, removed, or
-      # body-changed).
+      # ADR-46 slice 4 — given a set of changed file paths and two per-file symbol fingerprint maps (before
+      # and after), returns the frozen Set of `[path, symbol]` pairs whose fingerprints differ (added,
+      # removed, or body-changed).
       def changed_symbol_pairs(changed_files, fingerprints_before, fingerprints_after)
         pairs = Set.new
         changed_files.each do |path|
@@ -89,8 +80,8 @@ module Rigor
       # (b) it has an ancestry dep on a changed file (always re-checked — file-level), or
       # (c) it has a symbol dep on a `[file, symbol]` pair that changed.
       #
-      # Consumers that only have symbol deps on a changed file, and none of
-      # their tracked symbols changed, are NOT included — the slice 4 precision win.
+      # Consumers that only have symbol deps on a changed file, and none of their tracked symbols changed,
+      # are NOT included — the slice 4 precision win.
       def affected_with_symbols(changed_files, changed_pairs, symbol_dependents, ancestry_dependents)
         closure = changed_files.to_set
         changed_files.each { |file| closure.merge(ancestry_dependents[file] || []) }
@@ -98,13 +89,11 @@ module Rigor
         closure.freeze
       end
 
-      # ADR-46 slice 3 — the symbol keys (`"ClassName#method"`) that are
-      # present in a changed file's after-fingerprints but were absent from
-      # its before-fingerprints: a symbol that *appeared* in this edit. A
-      # symbol that merely moved between files still appears here for the
-      # destination file, but its negative-dependents set is empty (nobody
-      # missed a name that already resolved elsewhere), so the over-report
-      # costs nothing. Returns a frozen Set of symbol-key Strings.
+      # ADR-46 slice 3 — the symbol keys (`"ClassName#method"`) that are present in a changed file's
+      # after-fingerprints but were absent from its before-fingerprints: a symbol that *appeared* in this
+      # edit. A symbol that merely moved between files still appears here for the destination file, but its
+      # negative-dependents set is empty (nobody missed a name that already resolved elsewhere), so the
+      # over-report costs nothing. Returns a frozen Set of symbol-key Strings.
       def appeared_symbols(changed_files, fingerprints_before, fingerprints_after)
         appeared = Set.new
         changed_files.each do |path|
@@ -115,14 +104,12 @@ module Rigor
         appeared.freeze
       end
 
-      # ADR-46 slice 3 — the qualified class/module names *declared* in a
-      # changed file's after-state that were absent from its before-state: a
-      # class that appeared in this edit. (For an added file the before-set
-      # is empty, so every class it declares appears.) A class that merely
-      # moved files still appears here, but its negative-dependents are empty,
-      # so the over-report costs nothing. Returns a frozen Set of qualified
-      # class-name Strings. `decls_before` / `decls_after` map a path to its
-      # Set of declared class names.
+      # ADR-46 slice 3 — the qualified class/module names *declared* in a changed file's after-state that
+      # were absent from its before-state: a class that appeared in this edit. (For an added file the
+      # before-set is empty, so every class it declares appears.) A class that merely moved files still
+      # appears here, but its negative-dependents are empty, so the over-report costs nothing. Returns a
+      # frozen Set of qualified class-name Strings. `decls_before` / `decls_after` map a path to its Set of
+      # declared class names.
       def appeared_classes(changed_files, decls_before, decls_after)
         appeared = Set.new
         changed_files.each do |path|
@@ -133,23 +120,20 @@ module Rigor
         appeared.freeze
       end
 
-      # ADR-46 slice 3 — the consumers to re-check because a name they
-      # looked up and *missed* (a negative dependency) now resolves. `keys`
-      # is the set of negative-dependency keys (`"toplevel:foo"` /
-      # `"method:C#m"`) the appeared symbols would satisfy; `negative_dependents`
-      # maps each key to the Set of consumers that recorded the miss. Returns
-      # a frozen Set of consumer paths.
+      # ADR-46 slice 3 — the consumers to re-check because a name they looked up and *missed* (a negative
+      # dependency) now resolves. `keys` is the set of negative-dependency keys (`"toplevel:foo"` /
+      # `"method:C#m"`) the appeared symbols would satisfy; `negative_dependents` maps each key to the Set of
+      # consumers that recorded the miss. Returns a frozen Set of consumer paths.
       def negative_closure(keys, negative_dependents)
         closure = Set.new
         keys.each { |key| closure.merge(negative_dependents[key] || []) }
         closure.freeze
       end
 
-      # The files whose per-file diagnostics differ between two runs.
-      # Each argument maps a path to its diagnostic list; diagnostics are
-      # compared structurally via {Diagnostic#to_h} so identity / ordering
-      # of the objects themselves does not matter. A file present in one
-      # run and absent (zero diagnostics) in the other counts as changed.
+      # The files whose per-file diagnostics differ between two runs. Each argument maps a path to its
+      # diagnostic list; diagnostics are compared structurally via {Diagnostic#to_h} so identity / ordering
+      # of the objects themselves does not matter. A file present in one run and absent (zero diagnostics) in
+      # the other counts as changed.
       def changed_files(before_by_file, after_by_file)
         (before_by_file.keys | after_by_file.keys).each_with_object(Set.new) do |path, changed|
           before = (before_by_file[path] || []).map(&:to_h)

data/lib/rigor/analysis/incremental_session.rb

@@ -7,38 +7,30 @@ require_relative "../inference/scope_indexer"
 
 module Rigor
   module Analysis
-    # ADR-46 slice 2 — the in-memory incremental orchestrator that composes
-    # the recorded dependency graph ({Runner#file_dependents}), the affected
-    # closure ({Incremental.affected}), and the subset-analysis hook
+    # ADR-46 slice 2 — the in-memory incremental orchestrator that composes the recorded dependency graph
+    # ({Runner#file_dependents}), the affected closure ({Incremental.affected}), and the subset-analysis hook
     # ({Runner} `analyze_only:`) into a working incremental re-check.
     #
-    # `#baseline` runs a full analysis with dependency recording and keeps,
-    # per analyzed file, its diagnostics (the cache), its content digest,
-    # and the per-file source set (to maintain the dependents index across
-    # rounds). `#recheck` digests the files again, computes the changed set
-    # ΔF, re-analyzes only `ΔF ∪ dependents[ΔF]`, and serves every other
-    # analyzed file from the cache — the body tier.
+    # `#baseline` runs a full analysis with dependency recording and keeps, per analyzed file, its
+    # diagnostics (the cache), its content digest, and the per-file source set (to maintain the dependents
+    # index across rounds). `#recheck` digests the files again, computes the changed set ΔF, re-analyzes
+    # only `ΔF ∪ dependents[ΔF]`, and serves every other analyzed file from the cache — the body tier.
     #
-    # The invariant the verify harness (and the spec) assert: `#recheck`'s
-    # merged diagnostics are byte-identical (as a sorted set) to a full
-    # `--no-cache` re-analysis of the edited tree. This is the
-    # `--verify-incremental` acceptance gate, here without disk persistence
-    # or CLI wiring (the cache is in-process). It models the body tier only:
-    # an edit that adds / removes / moves a *file* is outside the analyzed
-    # set it maintains and falls to a fresh {#baseline} (the structural tier
-    # is a later slice).
+    # The invariant the verify harness (and the spec) assert: `#recheck`'s merged diagnostics are
+    # byte-identical (as a sorted set) to a full `--no-cache` re-analysis of the edited tree. This is the
+    # `--verify-incremental` acceptance gate, here without disk persistence or CLI wiring (the cache is
+    # in-process). It models the body tier only: an edit that adds / removes / moves a *file* is outside
+    # the analyzed set it maintains and falls to a fresh {#baseline} (the structural tier is a later slice).
     class IncrementalSession
-      # The outcome of a {#recheck}: the merged diagnostics plus the file
-      # sets, so a caller (or the verify gate) can report what was
-      # re-analyzed versus served from cache.
+      # The outcome of a {#recheck}: the merged diagnostics plus the file sets, so a caller (or the verify
+      # gate) can report what was re-analyzed versus served from cache.
       Recheck = Data.define(:diagnostics, :changed, :affected, :reused)
 
-      # @param paths [Array<String>, nil] explicit analysis roots; nil
-      #   (the default) uses the configuration's `paths:`.
-      # @param environment [Rigor::Environment, nil] optional shared
-      #   environment to thread into each internal Runner. Long-lived
-      #   callers and specs can use this to avoid rebuilding the same
-      #   RBS universe for every baseline / recheck / oracle run.
+      # @param paths [Array<String>, nil] explicit analysis roots; nil (the default) uses the configuration's
+      #   `paths:`.
+      # @param environment [Rigor::Environment, nil] optional shared environment to thread into each internal
+      #   Runner. Long-lived callers and specs can use this to avoid rebuilding the same RBS universe for
+      #   every baseline / recheck / oracle run.
       def initialize(configuration:, paths: nil, environment: nil)
         @configuration = configuration
         @paths = paths
@@ -63,15 +55,14 @@ module Rigor
         @class_decls = {}          # path => Set<qualified class name declared in the file>
       end
 
-      # The project files analyzed at the last baseline / recheck — the set
-      # a verify pass partitions and the merge subtracts the affected
-      # closure from.
+      # The project files analyzed at the last baseline / recheck — the set a verify pass partitions and the
+      # merge subtracts the affected closure from.
       def analyzed_files
         @analyzed
       end
 
-      # Full baseline analysis with recording. Returns the run's
-      # diagnostics; populates the in-process cache + dependency state.
+      # Full baseline analysis with recording. Returns the run's diagnostics; populates the in-process cache
+      # + dependency state.
       def baseline
         runner = build_runner(record_dependencies: true)
         diagnostics = run_runner(runner).diagnostics
@@ -82,9 +73,8 @@ module Rigor
         diagnostics
       end
 
-      # Re-check after on-disk edits, including files added or removed since
-      # the last run (the structural tier). Re-analyzes only the affected
-      # closure and serves the rest from cache; refreshes the cache +
+      # Re-check after on-disk edits, including files added or removed since the last run (the structural
+      # tier). Re-analyzes only the affected closure and serves the rest from cache; refreshes the cache +
       # dependency state so a subsequent #recheck sees the new world.
       def recheck
         previous = @analyzed
@@ -102,13 +92,11 @@ module Rigor
         Recheck.new(diagnostics: merged, changed: changed.to_set, affected: affected, reused: reused.to_set)
       end
 
-      # The frozen set of files a #recheck must re-analyse: the
-      # symbol/ancestry-granularity closure of the changed files (slice 4),
-      # the added files themselves, the consumers of any symbol / class that
-      # *appeared* in a changed OR added file (slice 3 — a now-defined
-      # `call.unresolved-toplevel` target or `def.override-*` ancestor), and
-      # the consumers of every removed file (which now miss what it provided).
-      # An added file has no before-state, so all its symbols / classes appear.
+      # The frozen set of files a #recheck must re-analyse: the symbol/ancestry-granularity closure of the
+      # changed files (slice 4), the added files themselves, the consumers of any symbol / class that
+      # *appeared* in a changed OR added file (slice 3 — a now-defined `call.unresolved-toplevel` target or
+      # `def.override-*` ancestor), and the consumers of every removed file (which now miss what it
+      # provided). An added file has no before-state, so all its symbols / classes appear.
       def affected_closure(changed, added, removed)
         scan = changed + added
         new_fps = symbol_fingerprints_for(scan)
@@ -124,21 +112,18 @@ module Rigor
         closure.freeze
       end
 
-      # The current project file set (cheap directory expansion, no analysis),
-      # used to detect files added / removed since the last run.
+      # The current project file set (cheap directory expansion, no analysis), used to detect files added /
+      # removed since the last run.
       def current_files
         runner = build_runner
         @paths ? runner.analysis_file_set(@paths) : runner.analysis_file_set
       end
 
-      # Verification engine (the `--verify-incremental` gate): with NO
-      # source edit, re-analyze `subset` fresh and serve every other
-      # analyzed file from the baseline cache. Because nothing on disk
-      # changed, the merged result MUST equal a full analysis — so this
-      # exercises the subset-analysis and cache-merge paths against a
-      # known-good oracle (a full `--no-cache` run) for an arbitrary
-      # partition, without mutating session state. Returns the merged
-      # diagnostics.
+      # Verification engine (the `--verify-incremental` gate): with NO source edit, re-analyze `subset` fresh
+      # and serve every other analyzed file from the baseline cache. Because nothing on disk changed, the
+      # merged result MUST equal a full analysis — so this exercises the subset-analysis and cache-merge
+      # paths against a known-good oracle (a full `--no-cache` run) for an arbitrary partition, without
+      # mutating session state. Returns the merged diagnostics.
       def reanalyze_subset(subset)
         affected = subset.to_set
         runner = build_runner(analyze_only: affected)
@@ -147,14 +132,12 @@ module Rigor
         fresh + reused.flat_map { |path| @cache[path] || [] }
       end
 
-      # Cross-process incremental run (the `--incremental` flag's engine).
-      # With a disk `snapshot` whose `fingerprint` matches, restore the
-      # prior per-file state and `#recheck` (re-analyze only the changed
-      # closure, serve the rest from the restored cache); otherwise run a
-      # full `#baseline`. Either way, persist the updated snapshot for the
-      # next process. Returns `[diagnostics, warm]` — `warm` is true when a
-      # snapshot was restored. A nil `fingerprint` (uncomputable inputs)
-      # disables persistence: a plain full run.
+      # Cross-process incremental run (the `--incremental` flag's engine). With a disk `snapshot` whose
+      # `fingerprint` matches, restore the prior per-file state and `#recheck` (re-analyze only the changed
+      # closure, serve the rest from the restored cache); otherwise run a full `#baseline`. Either way,
+      # persist the updated snapshot for the next process. Returns `[diagnostics, warm]` — `warm` is true
+      # when a snapshot was restored. A nil `fingerprint` (uncomputable inputs) disables persistence: a
+      # plain full run.
       def run_incremental(snapshot:, fingerprint:)
         restored = fingerprint && snapshot.load(fingerprint: fingerprint)
         if restored
@@ -171,26 +154,22 @@ module Rigor
 
       private
 
-      # Adopt a persisted snapshot's per-file state as this session's
-      # baseline (the warm-start path).
+      # Adopt a persisted snapshot's per-file state as this session's baseline (the warm-start path).
       def restore(payload)
         @analyzed = payload.analyzed
         @cache = payload.cache
         @sources = payload.sources
         @digests = payload.digests
         @dependents = Incremental.invert(@sources)
-        # ADR-46 slice 4 — restore symbol-granularity state if present in the
-        # payload (absent in snapshots written before slice 4 → fall back to
-        # file-level dependents, which is always sound).
+        # ADR-46 slice 4 — restore symbol-granularity state if present in the payload (absent in snapshots
+        # written before slice 4 → fall back to file-level dependents, which is always sound).
         @symbol_sources    = payload.symbol_sources    || {}
         @ancestry_sources  = payload.ancestry_sources  || {}
         @symbol_fingerprints = payload.symbol_fingerprints || {}
-        # ADR-46 slice 3 — restore negative edges if present (absent in
-        # pre-slice-3 snapshots → empty, which only loses the appeared-symbol
-        # re-check refinement; such a snapshot is never loaded by a slice-3+
-        # engine because the engine version + schema is part of the snapshot
-        # fingerprint, and `--verify-incremental` backstops any residual
-        # under-capture, so it is never unsound).
+        # ADR-46 slice 3 — restore negative edges if present (absent in pre-slice-3 snapshots → empty, which
+        # only loses the appeared-symbol re-check refinement; such a snapshot is never loaded by a slice-3+
+        # engine because the engine version + schema is part of the snapshot fingerprint, and
+        # `--verify-incremental` backstops any residual under-capture, so it is never unsound).
         @missing           = payload.missing || {}
         @class_decls       = payload.class_decls || {}
         @symbol_dependents = Incremental.invert_symbols(@symbol_sources)
@@ -207,10 +186,9 @@ module Rigor
         )
       end
 
-      # Fold a #recheck's fresh results back into the cache + graph so the
-      # session is correct across multiple edits: the analyzed set gets fresh
-      # diagnostics + digests + dependency edges, removed files are evicted
-      # from every map, and the analyzed-file list advances to `current`.
+      # Fold a #recheck's fresh results back into the cache + graph so the session is correct across
+      # multiple edits: the analyzed set gets fresh diagnostics + digests + dependency edges, removed files
+      # are evicted from every map, and the analyzed-file list advances to `current`.
       def absorb(runner, fresh, current, analyze_set, removed)
         removed.each { |path| forget(path) }
         @analyzed = current
@@ -222,8 +200,8 @@ module Rigor
         absorb_dependency_graph(runner)
       end
 
-      # Evict a removed file from every per-file map so its stale diagnostics
-      # are never served and it drops out of the inverted dependency indexes.
+      # Evict a removed file from every per-file map so its stale diagnostics are never served and it drops
+      # out of the inverted dependency indexes.
       def forget(path)
         @cache.delete(path)
         @digests.delete(path)
@@ -236,8 +214,8 @@ module Rigor
         # pre-pass in absorb_dependency_graph, and is frozen, so no delete.
       end
 
-      # Fold a runner's dependency recording (file-level and symbol-level) back
-      # into the session's graph state. Rebuilds all derived indexes.
+      # Fold a runner's dependency recording (file-level and symbol-level) back into the session's graph
+      # state. Rebuilds all derived indexes.
       def absorb_dependency_graph(runner)
         runner.file_dependencies.each do |path, record|
           @sources[path] = record.sources.dup
@@ -250,17 +228,15 @@ module Rigor
         @ancestry_dependents = Incremental.invert(@ancestry_sources)
         @negative_dependents = Incremental.invert(@missing)
         @symbol_fingerprints.merge!(runner.symbol_fingerprints)
-        # Wholesale replace (the subset runner's pre-pass is complete): a file
-        # that lost its last class must drop out of the map so a later re-add
-        # registers as an appearance.
+        # Wholesale replace (the subset runner's pre-pass is complete): a file that lost its last class must
+        # drop out of the map so a later re-add registers as an appearance.
         @class_decls = runner.class_declarations
       end
 
-      # Compute per-symbol body fingerprints for `paths` via a quick indexing
-      # re-pass (Prism parse + def extraction, no type inference). Returns a
-      # hash of the form `{ path => { "ClassName#method" => sha256_hex } }`.
-      # Used by {#recheck} to detect which symbols in a changed file actually
-      # changed, so only their callers are added to the affected closure.
+      # Compute per-symbol body fingerprints for `paths` via a quick indexing re-pass (Prism parse + def
+      # extraction, no type inference). Returns a hash of the form `{ path => { "ClassName#method" =>
+      # sha256_hex } }`. Used by {#recheck} to detect which symbols in a changed file actually changed, so
+      # only their callers are added to the affected closure.
       def symbol_fingerprints_for(paths)
         return {} if paths.empty?
 
@@ -281,11 +257,10 @@ module Rigor
         result.transform_values(&:freeze).freeze
       end
 
-      # ADR-46 slice 3 — the consumers to re-check because a symbol that
-      # appeared in a changed file resolves a prior missed lookup. Maps each
-      # appeared `"ClassName#method"` to the negative-dependency key it would
-      # satisfy (`toplevel:foo` for a top-level def, `method:C#m` otherwise),
-      # then unions the recorded negative-dependents of those keys.
+      # ADR-46 slice 3 — the consumers to re-check because a symbol that appeared in a changed file resolves
+      # a prior missed lookup. Maps each appeared `"ClassName#method"` to the negative-dependency key it
+      # would satisfy (`toplevel:foo` for a top-level def, `method:C#m` otherwise), then unions the recorded
+      # negative-dependents of those keys.
       def negative_affected(changed, new_fingerprints, new_class_decls)
         appeared_methods = Incremental.appeared_symbols(changed, @symbol_fingerprints, new_fingerprints)
         appeared_classes = Incremental.appeared_classes(changed, @class_decls, new_class_decls)
@@ -294,9 +269,9 @@ module Rigor
         Incremental.negative_closure(keys, @negative_dependents)
       end
 
-      # The qualified class/module names declared in `paths`, via the same
-      # quick indexing re-pass {#symbol_fingerprints_for} uses (Prism parse +
-      # declaration extraction, no inference). `{ path => Set<class name> }`.
+      # The qualified class/module names declared in `paths`, via the same quick indexing re-pass
+      # {#symbol_fingerprints_for} uses (Prism parse + declaration extraction, no inference). `{ path =>
+      # Set<class name> }`.
       def class_declarations_for(paths)
         return {} if paths.empty?
 
@@ -320,16 +295,15 @@ module Rigor
         Runner.new(configuration: @configuration, cache_store: nil, environment: @environment, **)
       end
 
-      # Run the runner over the session's explicit paths (or, when none were
-      # given, the configuration's `paths:` via `Runner#run`'s default).
+      # Run the runner over the session's explicit paths (or, when none were given, the configuration's
+      # `paths:` via `Runner#run`'s default).
       def run_runner(runner)
         @paths ? runner.run(@paths) : runner.run
       end
 
-      # Group diagnostics by their file path, keeping only those whose path
-      # is an analyzed project file — run-level streams (the gem-RBS info
-      # diagnostic, keyed on `.rigor.yml`) are recomputed fresh every run
-      # and must not be served from the per-file cache.
+      # Group diagnostics by their file path, keeping only those whose path is an analyzed project file —
+      # run-level streams (the gem-RBS info diagnostic, keyed on `.rigor.yml`) are recomputed fresh every
+      # run and must not be served from the per-file cache.
       def per_file(diagnostics)
         diagnostics.group_by(&:path).slice(*@analyzed)
       end

data/lib/rigor/analysis/project_scan.rb

@@ -2,31 +2,20 @@
 
 module Rigor
   module Analysis
-    # Frozen snapshot of the project-wide state {Runner} consumes
-    # before per-file analysis fires: the loaded plugin registry
-    # (with `#prepare` already invoked), the dependency-source
-    # index, the synthetic-method and project-patched indexes
-    # produced by the pre-pass scanners, and the diagnostics
-    # those passes emitted.
+    # Frozen snapshot of the project-wide state {Runner} consumes before per-file analysis fires: the loaded
+    # plugin registry (with `#prepare` already invoked), the dependency-source index, the synthetic-method and
+    # project-patched indexes produced by the pre-pass scanners, and the diagnostics those passes emitted.
     #
-    # Owners (`Rigor::LanguageServer::ProjectContext`, future
-    # editor / sig-gen integrations) build a ProjectScan once
-    # per project-state generation via
-    # `Runner#prepare_project_scan` and pass it to
-    # `Runner.new(prebuilt: ...)` so per-buffer publishes skip
-    # the scanner walks and `#prepare` re-runs. When watched
-    # project files change, the owner discards the ProjectScan
-    # and a fresh one builds on next read.
+    # Owners (`Rigor::LanguageServer::ProjectContext`, future editor / sig-gen integrations) build a ProjectScan
+    # once per project-state generation via `Runner#prepare_project_scan` and pass it to
+    # `Runner.new(prebuilt: ...)` so per-buffer publishes skip the scanner walks and `#prepare` re-runs. When
+    # watched project files change, the owner discards the ProjectScan and a fresh one builds on next read.
     #
-    # Editor mode v1 contract reminder: scanners observe the
-    # bytes that were on disk at scan time, NOT the in-flight
-    # buffer. Edits to a file that itself declares synthetic
-    # methods (or `pre_eval:`-listed patches) are NOT visible
-    # until the owner invalidates the scan — typically via
-    # `workspace/didChangeWatchedFiles`. This is the same
-    # trade-off the LSP made when slice 7 cached only the
-    # `Environment`; extending the cache to the pre-pass
-    # outputs preserves the contract.
+    # Editor mode v1 contract reminder: scanners observe the bytes that were on disk at scan time, NOT the
+    # in-flight buffer. Edits to a file that itself declares synthetic methods (or `pre_eval:`-listed patches)
+    # are NOT visible until the owner invalidates the scan — typically via `workspace/didChangeWatchedFiles`.
+    # This is the same trade-off the LSP made when slice 7 cached only the `Environment`; extending the cache
+    # to the pre-pass outputs preserves the contract.
     ProjectScan = Data.define(
       :plugin_registry,
       :dependency_source_index,

data/lib/rigor/analysis/result.rb

@@ -5,11 +5,9 @@ module Rigor
     class Result
       attr_reader :diagnostics, :stats
 
-      # @param stats [Rigor::Analysis::RunStats, nil] end-of-run
-      #   telemetry (target file count, RBS class breakdown,
-      #   wall + RSS) collected by the Runner. Nil when stats
-      #   collection wasn't requested or wasn't applicable
-      #   (early-exit paths like `validate_target_ruby` failure).
+      # @param stats [Rigor::Analysis::RunStats, nil] end-of-run telemetry (target file count, RBS class
+      #   breakdown, wall + RSS) collected by the Runner. Nil when stats collection wasn't requested or wasn't
+      #   applicable (early-exit paths like `validate_target_ruby` failure).
       def initialize(diagnostics: [], stats: nil)
         @diagnostics = diagnostics
         @stats = stats