rigortype 0.3.8 → 0.3.9

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

@@ -25,7 +25,7 @@ module Rigor
           @mutex = Mutex.new
         end
 
-        # @return [Array<Entry>] frozen snapshot of the recorded boundary-cross events. Each entry is a Data
+        # @return 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

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

@@ -17,8 +17,6 @@ module Rigor
       module Builder
         module_function
 
-        # @param dependencies [Rigor::Configuration::Dependencies]
-        # @return [Index]
         def build(dependencies)
           return Index::EMPTY if dependencies.empty?
 

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

@@ -30,8 +30,6 @@ module Rigor
 
         module_function
 
-        # @param entry [Rigor::Configuration::Dependencies::Entry]
-        # @return [Resolved, Unresolvable]
         def resolve(entry)
           spec = locate_gem_spec(entry.gem)
           return Unresolvable.new(gem_name: entry.gem, reason: :not_in_bundle) if spec.nil?

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

@@ -13,19 +13,19 @@ module Rigor
         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
+        # @param method_catalog — => 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
+        # @param budget_exceeded — 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
+        # @param class_to_gem — 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 |
+        # @param gem_modes — 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`;
@@ -56,7 +56,7 @@ module Rigor
         end
         private :normalize_catalog
 
-        # @return [String, nil] the gem that owns `class_name` (first-write-wins); `nil` when the class isn't
+        # @return 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]

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

@@ -28,8 +28,7 @@ module Rigor
       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
+        # @return 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

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

@@ -55,12 +55,12 @@ module Rigor
 
         module_function
 
-        # @param gem_dir [String, Pathname] absolute path to the gem's installation directory.
-        # @param roots [Array<String>] subdirectory names within the gem to walk (defaults to `["lib"]` per
+        # @param gem_dir — absolute path to the gem's installation directory.
+        # @param roots — subdirectory names within the gem to walk (defaults to `["lib"]` per
         #   `Configuration::Dependencies::Entry`).
-        # @param budget [Integer, Float] per-gem catalog cap (method-definition count). When unset, defaults
+        # @param budget — per-gem catalog cap (method-definition count). When unset, defaults
         #   to `UNBOUNDED` for backwards-compatible test paths.
-        # @return [Outcome] frozen wrapper carrying the catalog (`Hash{[class_name, method_name] =>
+        # @return frozen wrapper carrying the catalog (`Hash{[class_name, method_name] =>
         #   :instance | :singleton}`) and a `truncated?` flag set when the walker stopped harvesting because
         #   the budget was reached. Methods of identical name on the same class with different kinds (rare;
         #   private API mostly) carry the kind that wins the per-class first walk.

data/lib/rigor/analysis/effects_cache_probe.rb

@@ -52,17 +52,16 @@ module Rigor
       # otherwise rebuild (the probe loaded the plugins to key the entry, so it already knows it).
       Served = Data.define(:table, :sources, :registry, :plugin_facts)
 
-      # @param configuration [Rigor::Configuration] with effects already enabled by the caller.
-      # @param cache_root [String, nil]
+      # @param configuration — with effects already enabled by the caller.
       def initialize(configuration:, cache_root:)
         @configuration = configuration
         @cache_root = cache_root
       end
 
-      # @param paths [Array<String>] the analysed set — `configuration.paths` unioned with any path
+      # @param paths — the analysed set — `configuration.paths` unioned with any path
       #   arguments, exactly what {CLI::EffectsCommand#analyze} hands the runner, because the analysed
       #   set is part of the diagnostics key.
-      # @return [Served, nil] nil to decline, on any failure whatsoever.
+      # @return nil to decline, on any failure whatsoever.
       def serve(paths)
         return nil if @cache_root.nil? || !@configuration.effects_check?
 

data/lib/rigor/analysis/erb_template_detector.rb

@@ -19,8 +19,7 @@ module Rigor
 
       module_function
 
-      # @param parse_result [Prism::ParseResult]
-      # @return [Boolean] true when the parsed source looks like an ERB template (parse errors expected;
+      # @return true when the parsed source looks like an ERB template (parse errors expected;
       #   analysis should skip).
       def template?(parse_result)
         source = parse_result.source.source

data/lib/rigor/analysis/fact_store.rb

@@ -18,9 +18,14 @@ module Rigor
       ].freeze
 
       class Target < Data.define(:kind, :name)
+        # #775 — a target is an immutable value keyed by its name, and the local target is built on every
+        # binding (`Scope#with_local` invalidates through it) and every local-fact read: ~350k times on
+        # the lib self-check for a few thousand distinct names. One shared instance per name.
         def self.local(name)
-          new(kind: :local, name: name.to_sym)
+          name = name.to_sym
+          @local_targets[name] ||= new(kind: :local, name: name)
         end
+        @local_targets = {}
 
         def initialize(kind:, name:)
           super(kind: kind.to_sym, name: name)

data/lib/rigor/analysis/incremental.rb

@@ -120,6 +120,22 @@ module Rigor
         appeared.freeze
       end
 
+      # Issue #639 — the SYMMETRIC reading of {appeared_classes}: the names whose declaration in a file
+      # appeared OR VANISHED. Appearance alone answered the miss side, which was the only side recording a
+      # `class:` edge; a bare reference that RESOLVED now records one too, and what invalidates it is the
+      # declaration going away. `paths` MUST therefore include REMOVED files — a removed file has no
+      # after-state, so its whole before-set vanished — which is the same reason
+      # {changed_constant_publications} diffs over `changed + removed`.
+      def changed_class_declarations(paths, decls_before, decls_after)
+        moved = Set.new
+        paths.each do |path|
+          before = decls_before[path] || Set.new
+          after  = decls_after[path]  || Set.new
+          moved.merge(after ^ before)
+        end
+        moved.freeze
+      end
+
       # Issue #644 — the qualified constant names whose PUBLICATION could have moved in this edit: the names
       # whose per-file census descriptor differs between the before- and after-state of any file in `paths`.
       # The value-constant twin of {appeared_classes}, and deliberately NOT its analogue — a class either

data/lib/rigor/analysis/incremental_session.rb

@@ -42,22 +42,22 @@ module Rigor
         end
       end
 
-      # @param paths [Array<String>, nil] explicit analysis roots; nil (the default) uses the configuration's
+      # @param paths — explicit analysis roots; nil (the default) uses the configuration's
       #   `paths:`.
-      # @param environment [Rigor::Environment, nil] optional shared environment to thread into each internal
+      # @param environment — 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 cache_store [Rigor::Cache::Store, nil] ADR-85 WD1 — the persistent cache each internal Runner
+      # @param cache_store — ADR-85 WD1 — the persistent cache each internal Runner
       #   exposes to the RBS-env and plugin-producer tiers. A cross-process `--incremental` recheck otherwise
       #   rebuilt a fresh runner with no store, so every plugin `#prepare` producer (the ADR-9/#74/ADR-60 WD3
       #   record-and-validate caches) recomputed per invocation — 86% of a Rails warm incremental. Threading
       #   the store lets those producers serve from disk. `nil` (the default) preserves the pre-#85 behaviour
       #   the specs assert; the whole-run ADR-45 result cache stays disabled on these runs
       #   (`Runner#run_result_cacheable?` excludes `record_dependencies` / `analyze_only`).
-      # @param plugin_requirer [#call, nil] optional gem-require hook threaded into each internal Runner
+      # @param plugin_requirer — optional gem-require hook threaded into each internal Runner
       #   (mirrors {Runner}'s parameter). nil (the default, and what the CLI passes) uses `Kernel.require`;
       #   embedders and specs inject a fake so a test plugin registers without touching the real load path.
-      # @param workers [Integer] ADR-46 — the resolved fork-pool worker count threaded into every internal
+      # @param workers — ADR-46 — the resolved fork-pool worker count threaded into every internal
       #   analyzer, so a `--incremental` recheck's closure re-analysis parallelises exactly like the standard
       #   `check` path (the recon's audit: `--workers` / `RIGOR_RACTOR_WORKERS` / `parallel.workers:` were
       #   silently ignored because `build_runner` passed no `workers:`). 0 (the default, and what the specs and
@@ -112,7 +112,7 @@ module Rigor
         # and a missing invalidation edge is impossible by construction — the reason this is a table diff
         # and not the caller→callee edge recording #204 first sketched.
         @param_table = {}
-        reset_effect_state
+        reset_carried_state
         # ADR-88 WD1 — the plugin fact-surface digest computed for THIS invocation (nil until a
         # `#run_incremental` pass runs / a plugin-free project) and the reporting flags a caller (the CLI
         # banner + `--cache-stats`) reads after `#run_incremental`. `@last_runner` is the analysis runner the
@@ -174,6 +174,7 @@ module Rigor
         @effects_identity = current_effects_identity
         @cache = per_file(runner.per_file_diagnostics)
         @digests = @analyzed.to_h { |path| [path, pack_digest(path)] }
+        @run_level_rows = runner.run_level_rows
         diagnostics
       end
 
@@ -197,7 +198,8 @@ module Rigor
         # The freshly collected table is handed to the runner so the run seeds from the SAME table the diff
         # was decided on (and the collector runs once per recheck, not twice).
         runner = build_runner(analyze_only: analyze_set, record_dependencies: true,
-                              param_inferred_types: fresh_params)
+                              param_inferred_types: fresh_params,
+                              restored_run_level_rows: @run_level_rows)
         fresh = run_runner(runner).diagnostics
         @last_runner = runner # ADR-88 WD1 — the post-hoc fact-surface fingerprint reads this prepared registry.
         reused = (current & previous) - affected.to_a
@@ -407,10 +409,13 @@ module Rigor
       end
 
       # The current project file set (cheap directory expansion, no analysis), used to detect files added /
-      # removed since the last run.
+      # removed since the last run. Also where an editor buffer's binding is re-spelled onto the set, since
+      # this is where the run first learns how it spells its own members.
       def current_files
         runner = build_runner
-        @paths ? runner.analysis_file_set(@paths) : runner.analysis_file_set
+        files = @paths ? runner.analysis_file_set(@paths) : runner.analysis_file_set
+        rebind_buffer(files)
+        files
       end
 
       # Verification engine (the `--verify-incremental` gate): with NO source edit, re-analyze `subset` fresh
@@ -422,7 +427,8 @@ module Rigor
         affected = subset.to_set
         # ADR-67 WD6c lift — seed the subset run from the baseline's own table so the verification engine
         # exercises the exact seeds the served cache entries were computed under (and skips a re-collect).
-        runner = build_runner(analyze_only: affected, param_inferred_types: @param_table)
+        runner = build_runner(analyze_only: affected, param_inferred_types: @param_table,
+                              restored_run_level_rows: @run_level_rows)
         fresh = run_runner(runner).diagnostics
         reused = @analyzed - affected.to_a
         fresh + reused.flat_map { |path| @cache[path] || [] }
@@ -559,6 +565,9 @@ module Rigor
         restore_structural_declarations(payload)
         @return_summaries  = payload.return_summaries || {}
         @param_table       = payload.param_table || {} # ADR-67 WD6c lift — the seeds the cache was built under.
+        # Issues #796 / #794 — absent (nil) in a snapshot written before schema 22 is impossible (the SCHEMA
+        # gate rejects one), so nil here means the writing run genuinely had nothing to say.
+        @run_level_rows    = payload.run_level_rows
         # ADR-103 WD13 / #382 — the effects sidecar rides its own identity, so a snapshot whose summaries
         # were collected under a different vocabulary / catalogue / `effects:` block restores as EMPTY
         # rather than as stale rows. {#run_incremental} turns that emptiness into a full baseline, because
@@ -592,7 +601,8 @@ module Rigor
           return_summaries: marshal_safe_return_summaries,
           param_table: marshal_safe_param_table,
           effect_collections: marshal_safe_effect_collections,
-          effects_identity: @effects_identity
+          effects_identity: @effects_identity,
+          run_level_rows: @run_level_rows
         )
       end
 
@@ -606,6 +616,15 @@ module Rigor
         @effects_identity = nil
       end
 
+      # The state this session carries ACROSS processes in the snapshot rather than deriving each run: the
+      # effects sidecar above, and (issues #796 / #794) the run-level rows the last FULL run answered — the
+      # `definition-build-failed` set and the HKT-scan outcome, nil until a full run has produced them, and
+      # handed to every narrowed run this session builds, none of which can derive them from its own files.
+      def reset_carried_state
+        reset_effect_state
+        @run_level_rows = nil
+      end
+
       # Whether the effects half of a restored snapshot permits reuse. Collection off is vacuously true —
       # the session keeps no collections, writes none, and the pre-#382 reuse decision stands unchanged.
       def effects_reuse_permitted?(payload)
@@ -696,6 +715,9 @@ module Rigor
           @digests[path] = pack_digest(path)
         end
         absorb_dependency_graph(runner)
+        # Issues #796 / #794 — the recheck's own snapshots already carry the replayed rows folded together
+        # with anything its closure demanded for itself, so this is the same union the next run replays.
+        @run_level_rows = runner.run_level_rows
         refresh_return_summaries(runner, analyze_set)
         refresh_effect_collections(runner, analyze_set)
       end
@@ -803,20 +825,24 @@ module Rigor
       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.
+      # a prior missed lookup, and (issue #639) because a class DECLARATION appeared or vanished. 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, removed, new_fingerprints, new_class_decls, new_constant_decls)
         appeared_methods = Incremental.appeared_symbols(changed, @symbol_fingerprints, new_fingerprints)
-        appeared_classes = Incremental.appeared_classes(changed, @class_decls, new_class_decls)
+        # Issue #639 — a class DISAPPEARING satisfies the `class:` kind too, now that a resolved bare
+        # reference records the edge and not only a failed one; removed files join the diff for it.
+        moved_classes = Incremental.changed_class_declarations(
+          changed + removed, @class_decls, new_class_decls
+        )
         # Issue #644 — a constant whose PUBLICATION moved satisfies the `constant:` kind, keyed on the same
-        # last segment the consumer recorded. REMOVED files join the diff here and nowhere else: deleting a
-        # second declarer restores the precise answer, and no other producer input can see that.
+        # last segment the consumer recorded. Removed files join this diff (as they do the class one above):
+        # deleting a second declarer restores the precise answer, and no other producer input can see that.
         moved_constants = Incremental.changed_constant_publications(
           changed + removed, @constant_decls, new_constant_decls
         )
         keys = appeared_methods.map { |symbol| negative_key_for(symbol) }
-        keys.concat(appeared_classes.map { |klass| "class:#{klass.split('::').last}" })
+        keys.concat(moved_classes.map { |klass| "class:#{klass.split('::').last}" })
         keys.concat(moved_constants.map { |name| "constant:#{name.split('::').last}" })
         Incremental.negative_closure(keys, @negative_dependents)
       end
@@ -1013,18 +1039,51 @@ module Rigor
         candidates.reject { |path| stat_fresh?(path) }
       end
 
-      # A bound buffer's logical path is never fresh: the bytes to analyse live in the editor's temp file, and
-      # the recorded entry describes the file on disk. Re-analysing it when the two happen to agree costs one
-      # file; trusting the stat tuple would serve the editor its own stale diagnostics.
       def buffer_path?(path)
         !@buffer.nil? && path == @buffer.logical_path
       end
 
+      # Editor mode (#146) — the bound buffer's logical path is fresh exactly when the EDITOR's bytes still
+      # hash to the digest the snapshot recorded for the file they stand in for. The recorded stat tuple
+      # describes the file on disk, which an edit in the editor never moves, so validating through it serves
+      # the editor its own pre-buffer answers (#960); hashing the buffer makes the substituted file changed
+      # whenever it differs, and keeps an untouched buffer out of the closure. Anything unreadable or
+      # unrecorded reads as changed, the conservative direction the rest of this tier takes.
+      def buffer_fresh?(path)
+        recorded = Cache::FileDigest.content_digest(@digests[path])
+        return false if recorded.nil?
+
+        Cache::FileDigest.hexdigest(@buffer.resolve(path)) == recorded
+      rescue StandardError
+        false
+      end
+
+      # Editor mode (#146 / #960) — `--instead-of` is spelled the way the editor spells it (absolute, or
+      # `./`-prefixed), while the analysed set is spelled the way the run's path arguments produce. A binding
+      # whose logical path matches no member of that set substitutes nothing at all: every reader keeps
+      # reading the file on disk and the run answers as if no buffer had been passed. Re-spell the binding
+      # onto the set's own member, identified by real path, once the set is known.
+      def rebind_buffer(files)
+        return if @buffer.nil? || files.include?(@buffer.logical_path)
+
+        target = real_path(@buffer.logical_path)
+        return if target.nil?
+
+        match = files.find { |path| real_path(path) == target }
+        @buffer = BufferBinding.new(logical_path: match, physical_path: @buffer.physical_path) if match
+      end
+
+      def real_path(path)
+        File.realpath(path)
+      rescue StandardError
+        nil
+      end
+
       # True when `path`'s recorded stat entry proves it unchanged since the last analysis. Any stat / parse
       # failure (missing entry, unreadable / vanished file) reads as NOT fresh (→ re-analyse), preserving the
       # prior `digest(path) != recorded` "changed" semantics for a file that cannot be validated.
       def stat_fresh?(path)
-        return false if buffer_path?(path)
+        return buffer_fresh?(path) if buffer_path?(path)
 
         entry = @digests[path]
         return false if entry.nil?

data/lib/rigor/analysis/plugin_fact_fingerprint.rb

@@ -79,7 +79,6 @@ module Rigor
       #
       # Keeping the opaque decision here, rather than at each cache's call site, means a new consumer cannot
       # key on `digest` while forgetting that an opaque surface makes it meaningless.
-      # @return [String, nil]
       def self.key_digest(registry)
         result = from_registry(registry)
         result.opaque? ? nil : result.digest.to_s

data/lib/rigor/analysis/reachability/graph.rb

@@ -29,13 +29,11 @@ module Rigor
         # bucket on trust.
         Undecidable = Data.define(:fqn, :path, :line, :reason)
 
-        # @param declarations [Array<Scan::Declaration>]
-        # @param references [Array<Scan::Reference>]
-        # @param root_fqns [Enumerable<String>] declarations that are entry points regardless of who references
+        # @param root_fqns — declarations that are entry points regardless of who references
         #   them (config-declared globs in this slice; plugin-supplied roots are #349).
-        # @param foreign [#call] predicate answering "is this FQN owned by something outside the project?" —
+        # @param foreign — predicate answering "is this FQN owned by something outside the project?" —
         #   a reopened gem or stdlib class must never be a candidate (WD6). Defaults to "nothing is foreign".
-        # @param dynamic_uses [Array<Scan::DynamicUse>] sites where a constant is reached by name at runtime.
+        # @param dynamic_uses — sites where a constant is reached by name at runtime.
         #   A literal-argument site contributes a real reference; a dynamic one taints a namespace (WD4).
         def initialize(declarations:, references:, root_fqns: [], dynamic_uses: [], foreign: ->(_fqn) { false })
           @declarations = declarations

data/lib/rigor/analysis/reachability/plugin_roots.rb

@@ -83,14 +83,15 @@ module Rigor
         # Loads the project's configured plugins, runs every `#prepare`, and returns the union of every
         # published `:reachability_roots` and `:reachability_references` fact.
         #
-        # @param configuration [Rigor::Configuration] the loaded project configuration.
-        # @param plugin_requirer [#call] how a plugin gem is brought into the process. The same seam
-        #   `Analysis::Runner` exposes, so a spec can register a plugin class without publishing a gem.
-        # @param cache_store [Rigor::Cache::Store, nil] when given, each plugin's `#prepare` producers read
+        # @param configuration — the loaded project configuration.
+        # @param plugin_requirer — how a plugin gem is brought into the process, called with the gem name. The
+        #   same seam `Analysis::Runner` exposes, so a spec can register a plugin class without publishing a
+        #   gem.
+        # @param cache_store — when given, each plugin's `#prepare` producers read
         #   and write the same ADR-60 record-and-validate slots they use under `rigor check`, instead of
         #   recomputing from scratch — a routes parse or a factory discovery is a validated cache read on
         #   every invocation after the first. Nil keeps the historical recompute-always behaviour.
-        # @return [Contribution] sorted and de-duplicated. Empty whenever the project declares no plugins, no
+        # @return sorted and de-duplicated. Empty whenever the project declares no plugins, no
         #   plugin contributes anything, or anything at all goes wrong.
         def collect(configuration:, plugin_requirer: ->(name) { require name }, cache_store: nil)
           return Contribution.empty if configuration.plugins.empty?

data/lib/rigor/analysis/reachability/project_files.rb

@@ -46,8 +46,8 @@ module Rigor
           File.fnmatch?(pattern, path, File::FNM_PATHNAME)
         end
 
-        # @param relative_paths [Array<String>] paths relative to `root`.
-        # @return [Array<String>] those that belong to the project itself.
+        # @param relative_paths — paths relative to `root`.
+        # @return those that belong to the project itself.
         def own(relative_paths, root)
           prefixes = submodule_prefixes(root)
           relative_paths.grep_v(VENDOR_DIRS).reject { |rel| prefixes.any? { |prefix| rel.start_with?(prefix) } }

data/lib/rigor/analysis/reachability/scan.rb

@@ -70,11 +70,6 @@ module Rigor
           end
         end
 
-        # @param path [String] the file's path, as the report should render it.
-        # @param source [String] the file's bytes.
-        # @param target_ruby [String, nil] Prism version string, threaded from the project configuration.
-        # @return [Result, nil] nil when the file does not parse (a parse error is the analyzer's business, not
-        #   this scan's — it simply contributes nothing rather than half a file).
         # A constant name is ASCII by construction, so a byte sequence that is not valid UTF-8 cannot be one.
         # Dropping it is both correct and the only safe answer: carrying it forward crashed the whole run on
         # the first `String#sub` downstream, which is how this surfaced — `rigor unused` on Rigor's own
@@ -86,6 +81,11 @@ module Rigor
           name.valid_encoding? ? name : nil
         end
 
+        # @param path — the file's path, as the report should render it.
+        # @param source — the file's bytes.
+        # @param target_ruby — Prism version string, threaded from the project configuration.
+        # @return nil when the file does not parse (a parse error is the analyzer's business, not
+        #   this scan's — it simply contributes nothing rather than half a file).
         def self.call(path:, source:, target_ruby: nil)
           parsed = if target_ruby
                      Prism.parse(source, filepath: path,

data/lib/rigor/analysis/reachability/scan_cache.rb

@@ -43,9 +43,9 @@ module Rigor
         RACY_WINDOW_NS = 2_000_000_000
         private_constant :RACY_WINDOW_NS
 
-        # @param cache_path [String, nil] the configuration's cache root; nil or empty is an inert
+        # @param cache_path — the configuration's cache root; nil or empty is an inert
         #   cache (every fetch computes, nothing persists).
-        # @param target_ruby [String, nil] parse-affecting configuration, part of the identity.
+        # @param target_ruby — parse-affecting configuration, part of the identity.
         def self.open(cache_path, target_ruby: nil)
           return new(path: nil, header: nil) if cache_path.nil? || cache_path.to_s.empty?
 

data/lib/rigor/analysis/reachability/signature_scan.rb

@@ -26,8 +26,8 @@ module Rigor
       module SignatureScan
         module_function
 
-        # @param file [String] path to a `.rbs` file.
-        # @return [Array<Scan::Reference>] one file-level reference per distinct referenced name. Empty when the
+        # @param file — path to a `.rbs` file.
+        # @return one file-level reference per distinct referenced name. Empty when the
         #   file cannot be read or parsed — a broken signature is the analyzer's business, not this scan's.
         def call(file)
           _, _, decls = ::RBS::Parser.parse_signature(::RBS::Buffer.new(name: file, content: File.read(file)))

data/lib/rigor/analysis/result.rb

@@ -7,7 +7,7 @@ module Rigor
     class Result
       attr_reader :diagnostics, :stats
 
-      # @param stats [Rigor::Analysis::RunStats, nil] end-of-run telemetry (target file count, RBS class
+      # @param stats — 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)
@@ -43,8 +43,6 @@ module Rigor
 
       # The diagnostics {#crashed?} answers true for, so a caller can name what it saw rather than only that
       # it saw something.
-      #
-      # @return [Array<Rigor::Analysis::Diagnostic>]
       def crash_diagnostics
         diagnostics.select { |diagnostic| CrashSignature.discards_file_analysis?(diagnostic) }
       end

data/lib/rigor/analysis/rule_catalog.rb

@@ -642,7 +642,10 @@ module Rigor
             "Later write is `nil` — the `@cache = nil` clear-idiom is allowlisted.",
             "Either side is Union / Dynamic / IntegerRange / a shape-varied carrier.",
             "Writes live in different classes that happen to share an ivar name.",
-            "Writes are in `def self.foo` (singleton) bodies — those track separately."
+            "Writes are in a singleton body — `def self.foo` or a `class << self` def — those track " \
+            "separately.",
+            "Writes are in a `def` inside an anonymous-class factory block (`Class.new do … end`, " \
+            "`Module.new`, `Struct.new`, `Data.define`): that body defines another class."
           ],
           suppression: "`# rigor:disable ivar-write-mismatch` on the offending write.",
           severity_authored: :error,

data/lib/rigor/analysis/run_cache_key.rb

@@ -80,7 +80,7 @@ module Rigor
       # collecting project's path-set churn is the same churn, and over-evicting costs one recompute.
       EFFECTS_GENERATION_CAP = GENERATION_CAP
 
-      # @param rbs_config_entries [Array<Cache::Descriptor::ConfigEntry>] the RBS-derived config slots
+      # @param rbs_config_entries — the RBS-derived config slots
       #   (`rbs.libraries` [+ `rbs.virtual_rbs`]). nil on any failure so a malformed key disables the cache.
       def descriptor(configuration:, files:, explain:, rbs_config_entries:)
         Cache::Descriptor.new(

data/lib/rigor/analysis/run_cache_probe.rb

@@ -51,17 +51,15 @@ module Rigor
     #   serves it instead. The decline is measured against the declarations alone, never against what they
     #   would judge to, so it costs one glob and never a wrong answer.
     class RunCacheProbe
-      # @param configuration [Rigor::Configuration]
-      # @param cache_root [String]
-      # @param explain [Boolean] the `--explain` flag (folded into the key, as the runner does).
+      # @param explain — the `--explain` flag (folded into the key, as the runner does).
       def initialize(configuration:, cache_root:, explain:)
         @configuration = configuration
         @cache_root = cache_root
         @explain = explain
       end
 
-      # @param paths [Array<String>] the analysis roots (`@argv` or `configuration.paths`).
-      # @return [Analysis::Result, nil] the cached run result with the severity profile applied and no stats
+      # @param paths — the analysis roots (`@argv` or `configuration.paths`).
+      # @return the cached run result with the severity profile applied and no stats
       #   (matching a cache-served `Runner#run`), or nil to DECLINE — a miss / stale / unavailable cache — so
       #   the caller loads the engine and runs the full path. Any failure declines rather than raising: the
       #   probe must never turn a servable run into a crash.

data/lib/rigor/analysis/runner/buffer_pool_dispatcher.rb

@@ -66,7 +66,7 @@ module Rigor
         # via `RIGOR_LSP_POOL_MIN_BATCH` (mirrors `RIGOR_RACTOR_WORKERS`'s override shape).
         DEFAULT_MIN_BATCH_SIZE = 16
 
-        # @return [Integer] `RIGOR_LSP_POOL_MIN_BATCH` when set to a non-empty value, else
+        # @return `RIGOR_LSP_POOL_MIN_BATCH` when set to a non-empty value, else
         #   {DEFAULT_MIN_BATCH_SIZE}.
         def self.resolve_min_batch_size
           env_value = ENV.fetch("RIGOR_LSP_POOL_MIN_BATCH", nil)
@@ -75,19 +75,17 @@ module Rigor
           Integer(env_value)
         end
 
-        # @param configuration [Rigor::Configuration]
-        # @param cache_store [Rigor::Cache::Store, nil]
-        # @param environment [Rigor::Environment] the warm, shared per-session Environment
+        # @param environment — the warm, shared per-session Environment
         #   (`ProjectContext#environment`) every job's Runner reuses instead of rebuilding.
-        # @param prebuilt [Rigor::Analysis::ProjectScan] the warm, shared pre-pass snapshot
+        # @param prebuilt — the warm, shared pre-pass snapshot
         #   (`ProjectContext#project_scan`) every job's Runner adopts instead of re-scanning.
-        # @param workers [Integer] pool size. `#analyze` degrades to sequential in-process execution — one
+        # @param workers — pool size. `#analyze` degrades to sequential in-process execution — one
         #   job at a time, no `fork` — when fewer than 2 bindings are submitted, fewer than `min_batch_size`
         #   bindings are submitted, `workers` is not positive, `fork` is unavailable on this platform, or
         #   `cache_store` is nil. The middle two are the fork-pool-is-not-worth-it-yet gate documented on
         #   {DEFAULT_MIN_BATCH_SIZE}; the last two mirror
         #   {PoolCoordinator#analyze_files_in_pool}'s own fork-pool preconditions.
-        # @param min_batch_size [Integer] see {DEFAULT_MIN_BATCH_SIZE}. Exposed as a constructor param
+        # @param min_batch_size — see {DEFAULT_MIN_BATCH_SIZE}. Exposed as a constructor param
         #   (rather than read from the env internally) purely for spec control; production callers get the
         #   resolved default.
         def initialize(configuration:, cache_store:, environment:, prebuilt:, workers:,
@@ -185,7 +183,7 @@ module Rigor
           degraded
         end
 
-        # @return [Hash, nil] the child's `{index => diagnostics}` payload, or nil when the child exited
+        # @return the child's `{index => diagnostics}` payload, or nil when the child exited
         #   abnormally or wrote no readable payload. `Marshal.load` is safe here: the blob was written by our
         #   own forked child to a temp file we created.
         def fork_worker_payload(status, out_path)

data/lib/rigor/analysis/runner/declaration_position.rb

@@ -20,8 +20,7 @@ module Rigor
 
         module_function
 
-        # @param finding [#location]
-        # @return [Array(String, Integer)] `[path, line]`
+        # @return `[path, line]`
         def of(finding)
           location = finding.location
           return [CONFIG_PATH, 1] if location.nil?