rigortype 0.4.5 → 0.4.7

data/lib/rigor/analysis/incremental_session.rb

@@ -5,6 +5,7 @@ require_relative "incremental"
 require_relative "incremental_run_slot"
 require_relative "incremental_run_slot/write_guard"
 require_relative "plugin_fact_fingerprint"
+require_relative "run_disclosure_ledger"
 require_relative "source_rbs_gate"
 require_relative "../cache/file_digest"
 require_relative "../cache/incremental_snapshot"
@@ -26,10 +27,8 @@ module Rigor
     #
     # The invariant the verify harness (and the spec) assert: `#recheck`'s merged diagnostics are
     # byte-identical to a full `--no-cache` re-analysis of the edited tree, in the same order (#1524; the gate
-    # itself compares sorted sets). 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).
+    # itself compares sorted sets). The `--verify-incremental` gate runs this engine; `#run_incremental` adds the
+    # snapshot persistence that `--incremental` uses.
     # The class-length budget is relaxed: this is one cohesive orchestrator of the incremental state
     # (per-file diagnostics cache, the file-level / symbol-level / negative dependency graphs, and the ADR-85
     # seed bundles), clearer read together than split across micro-classes that would all share the same ivars.
@@ -100,8 +99,8 @@ module Rigor
         # ADR-85 WD2 — per-file discovery seed bundles keyed by logical path. A cold baseline builds them; a
         # warm recheck folds them (re-walking only changed files) and refreshes the set. Ride the snapshot.
         @seed_bundles = {}
-        @cache = {}              # analyzed path => [Diagnostic]
-        @sources = {}            # analyzed path => Set<source path it read from>
+        @cache = {}              # analyzed path => its diagnostics
+        @sources = {}            # analyzed path => the source paths it read from
         @digests = {}            # analyzed path => ADR-87 packed stat-digest entry at last analysis
         # Issue #1583 — discovered-not-analysed path => the same packed entry, for a run over path arguments that
         # #684 widened to the configured `paths:`. Empty on every run over the configured paths.
@@ -109,18 +108,18 @@ module Rigor
         @analyzed = []           # the project files analyzed last round
         @dependents = {}         # inverted @sources (file-level)
         # ADR-46 slice 4 — symbol-granularity tracking.
-        @symbol_sources = {}     # consumer => { source_path => Set<"ClassName#method"> }
-        @ancestry_sources = {}   # consumer => Set<source_path> (class-ancestry deps)
+        @symbol_sources = {}     # consumer => { source_path => the "ClassName#method" symbols it read }
+        @ancestry_sources = {}   # consumer => source paths (class-ancestry deps)
         @symbol_fingerprints = {}  # path => { "ClassName#method" => sha256_hex }
-        @symbol_dependents = {}    # [source, symbol] => Set<consumer>
-        @ancestry_dependents = {}  # source => Set<consumer> (inverted ancestry_sources)
+        @symbol_dependents = {}    # [source, symbol] => consumers
+        @ancestry_dependents = {}  # source => consumers (inverted ancestry_sources)
         # ADR-46 slice 3 — negative (missing) dependencies: a consumer that
         # looked up a name and resolved nothing must be re-checked when that
         # name later appears (e.g. a `call.unresolved-toplevel` whose target
         # is defined by a later edit).
-        @missing = {}              # consumer => Set<"kind:name"> it looked up and missed
-        @negative_dependents = {}  # "kind:name" => Set<consumer> (inverted @missing)
-        @class_decls = {}          # path => Set<qualified class name declared in the file>
+        @missing = {}              # consumer => the "kind:name" keys it looked up and missed
+        @negative_dependents = {}  # "kind:name" => consumers (inverted @missing)
+        @class_decls = {}          # path => qualified class names declared in the file
         # Issue #644 — the value-constant twin: path => { qualified constant name => publication descriptor }.
         # Diffed on a recheck to find every constant whose PUBLISHED answer could have moved, which satisfies
         # the `constant:` edges a reader records at every reference, resolved or not.
@@ -139,6 +138,9 @@ module Rigor
         # the frozen `Cache::Descriptor::FileEntry` / `GlobEntry` rows, as each read observed its input. A recheck
         # re-analyses every file one of whose rows no longer validates ({#plugin_read_affected}).
         @plugin_reads = {}
+        # Issue #2020 — the run-scoped plugin rows each analysed file registered, and the reads that make one stale.
+        @plugin_disclosures = RunDisclosureLedger.new
+        @stale_disclosures = Set.new
         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
@@ -269,8 +271,10 @@ module Rigor
         @effect_collections = runner.effect_collections_by_path
         @effects_identity = current_effects_identity
         @effect_plugin_digest = effect_plugin_digest_of(runner)
+        @synthetic_surface_digest = synthetic_surface_digest_of(runner)
         @cache = per_file(runner.per_file_diagnostics)
         @plugin_reads = plugin_reads_of(runner, @analyzed)
+        @plugin_disclosures = RunDisclosureLedger.from(runner.analysis_disclosures.slice(*@analyzed))
         record_baseline_digests
         @run_level_rows = runner.run_level_rows
         diagnostics
@@ -294,16 +298,11 @@ module Rigor
         fresh_params = fresh_param_table(current, changed, added, removed)
         param_files, param_pairs = param_seed_invalidation(fresh_params)
         affected = affected_closure(changed, added, removed, param_files, param_pairs)
-        forced, analyze_set = forced_analyze_set(affected, current)
-        reused = (current & previous) - analyze_set.to_a
-        # 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). The reused files' cached rows
-        # go in too, so the runner lists them in the full run's file order (#1524).
-        runner = build_runner(analyze_only: analyze_set, record_dependencies: true,
-                              param_inferred_types: fresh_params, **forced_target_options(forced),
-                              restored_run_level_rows: @run_level_rows, **served_state(reused))
-        merged = run_runner(runner).diagnostics
-        return rebaseline_recheck(changed, added, removed) if served_effects_stale?(runner, reused)
+        affected, analyze_set, runner, merged, reused =
+          run_settled_closure(affected, [current, previous, removed], fresh_params)
+        if served_effects_stale?(runner, reused) || synthetic_surface_moved?(runner, reused)
+          return rebaseline_recheck(changed, added, removed)
+        end
 
         absorb(runner, current, analyze_set, removed)
         @param_table = fresh_params
@@ -311,6 +310,36 @@ module Rigor
                                                           stale_readers: @stale_plugin_readers)
       end
 
+      # {#recheck}'s narrowed run. Issue #2020 — a stale run-scoped key whose chosen refresher registered nothing (a
+      # parse error, a plugin that raised, an edit that took the notice out of its text) is decided by its other
+      # holders, so they join the closure and it runs again. Returns `[affected, analyze_set, runner, merged, reused]`.
+      def run_settled_closure(affected, (current, previous, removed), fresh_params)
+        forced, analyze_set = forced_analyze_set(affected, current)
+        runner, merged, reused = run_closure(analyze_set, current, previous, forced, fresh_params)
+        fallback = @plugin_disclosures.unresolved_holders(runner.analysis_disclosures, analyze_set, @stale_disclosures,
+                                                          removed.to_set)
+        return [affected, analyze_set, runner, merged, reused] if fallback.empty?
+
+        affected = (affected | fallback).freeze
+        @stale_plugin_readers |= fallback
+        forced, analyze_set = forced_analyze_set(affected, current)
+        [affected, analyze_set, *run_closure(analyze_set, current, previous, forced, fresh_params)]
+      end
+      private :run_settled_closure
+
+      # One narrowed run of {#recheck}'s closure: the runner, its merged rows, and the files it served. 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). The reused files' cached rows go in too, so the runner lists them
+      # in the full run's file order (#1524).
+      def run_closure(analyze_set, current, previous, forced, fresh_params)
+        reused = (current & previous) - analyze_set.to_a
+        runner = build_runner(analyze_only: analyze_set, record_dependencies: true,
+                              param_inferred_types: fresh_params, **forced_target_options(forced),
+                              restored_run_level_rows: @run_level_rows, **served_state(reused))
+        [runner, run_runner(runner).diagnostics, reused]
+      end
+      private :run_closure
+
       # Editor mode option B (#146) — a whole-project recheck with the editor's buffer substituted for one
       # file, for the CLI's `--incremental --tmp-file=X --instead-of=Y`. Returns the {Recheck} when the
       # snapshot could be reused, or nil when it could not — the caller then falls back to option A
@@ -361,7 +390,7 @@ module Rigor
       # records none at all), so no dependent set can bound who read it. An edit that moved it re-analyses the
       # whole project — what a `sig/` edit already costs through the snapshot fingerprint.
       def affected_closure(changed, added, removed, param_files = Set.new, param_pairs = Set.new)
-        @stale_plugin_readers = plugin_read_affected
+        @stale_plugin_readers = plugin_read_affected | disclosure_refreshers(removed)
         return whole_project_closure(changed, added) if source_rbs_gate.moved?(@seed_bundles, changed, added, removed)
 
         (gated_closure(changed, added, removed, param_files, param_pairs) | @stale_plugin_readers).freeze
@@ -471,8 +500,8 @@ module Rigor
       # exempts such a write is a fact of the whole program — an alias, or a `write` / `to_str` / `to_int` / hatch
       # defined in any spelling on any receiver, a rewritten ancestor, a mixin — which no name-keyed edge can
       # follow, so a stale report would outlive the edit that exempts it. Such files are rare, so this costs little.
-      # A file the census silenced is not re-checked when the exemption goes away: that stale answer misses a
-      # report, it never makes one.
+      # A file the census silenced is re-checked through the `global_census:` keys its rule recorded
+      # ({#global_census_affected}, issue #2158).
       def global_write_reporters
         @cache.each_with_object(Set.new) do |(path, diagnostics), reporters|
           reporters << path if diagnostics.any? { |diagnostic| diagnostic.rule.to_s.start_with?("global.") }
@@ -602,9 +631,21 @@ module Rigor
         runner = build_runner
         files = @paths ? runner.analysis_file_set(@paths) : runner.analysis_file_set
         rebind_buffer(files)
-        files
+        admit_new_buffer(files)
       end
 
+      # Issue #2233 — a buffer for a file that is not on disk (a new file) is in no expansion, so the set above never
+      # names it: the recheck neither analyses it nor sees its declarations, and the run answers "re-analysed 0 file(s)"
+      # with no diagnostics for the buffer. Option A (single-file scope) analyses the logical path whether or not it
+      # exists; option B joins it to the set the same way, as an added file, so the closure analyses it like any new
+      # file. A buffer already matched by {#rebind_buffer} is in `files` and is returned as it is.
+      def admit_new_buffer(files)
+        return files if @buffer.nil? || files.include?(@buffer.logical_path)
+
+        files + [@buffer.logical_path]
+      end
+      private :admit_new_buffer
+
       # 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
@@ -620,6 +661,32 @@ module Rigor
         run_runner(runner).diagnostics
       end
 
+      # Issue #1967 — the edit replay of `--verify-incremental-edits`: a warm recheck of this session's baseline with
+      # `buffer` standing in for one file, the way editor mode option B (#146) rechecks an unsaved edit. The baseline is
+      # handed over as a Marshal copy of the snapshot a `--incremental` run would save, through a fresh session that
+      # never persists, so this session's own state is untouched and each replay starts from the same baseline. Unlike
+      # {#reanalyze_subset}, whose tree is the baseline's, the edit moves what the served files' rows were computed
+      # from, so a dependent the recheck fails to re-analyse is served stale and the comparison sees it. Returns the
+      # {Recheck}, or nil when the recheck declined as option B does (the plugin fact surface moved, an unverified
+      # source-RBS gate, a re-baseline), where the answer would be a full analysis and there is nothing to compare.
+      def replay_edit(buffer)
+        adopt_plugin_fact_fingerprint if @plugin_fact_reusable.nil?
+        replay = IncrementalSession.new(
+          configuration: @configuration, paths: @paths, environment: @environment, cache_store: @cache_store,
+          plugin_requirer: @plugin_requirer, buffer: buffer, explain: @explain
+        )
+        replay.run_buffer_recheck(snapshot: ReplaySnapshot.new(blob: Marshal.dump(to_payload)), fingerprint: :replay)
+      end
+
+      # The in-memory stand-in for {Cache::IncrementalSnapshot} {#replay_edit} hands its replay session: every load is a
+      # fresh copy, as a load from disk is.
+      ReplaySnapshot = Data.define(:blob) do
+        def load(fingerprint:) # rubocop:disable Lint/UnusedMethodArgument
+          Marshal.load(blob) # rubocop:disable Security/MarshalLoad
+        end
+      end
+      private_constant :ReplaySnapshot
+
       # 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,
@@ -991,7 +1058,7 @@ 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.
-        @plugin_reads      = payload.plugin_reads # Issue #1553 — `{}` in a payload built without it.
+        restore_plugin_records(payload)
         # 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
@@ -1007,6 +1074,14 @@ module Rigor
         @negative_dependents = Incremental.invert(@missing)
       end
 
+      # Issue #1553 — the plugin reads each file's last analysis made, and (#2020) the run-scoped plugin rows it
+      # registered; `{}` in a payload built without them. Extracted to keep {#restore} under its ABC budget.
+      def restore_plugin_records(payload)
+        @plugin_reads = payload.plugin_reads
+        @plugin_disclosures = RunDisclosureLedger.load(payload.plugin_disclosures)
+        @synthetic_surface_digest = payload.synthetic_surface_digest # the plugin-built ADR-16 index (PR #2286 M1)
+      end
+
       # ADR-46 slice 3 / issue #644 — the structural tier's negative-edge state: the per-consumer missed
       # lookups plus the two per-file DECLARATION sets (`class_decls`, `constant_decls`) whose diff says what
       # APPEARED in an edit. Absent in an older snapshot → empty, which only loses the appeared-symbol
@@ -1032,7 +1107,9 @@ module Rigor
           effects_identity: @effects_identity,
           run_level_rows: @run_level_rows,
           effect_plugin_digest: @effect_plugin_digest,
+          synthetic_surface_digest: @synthetic_surface_digest,
           plugin_reads: @plugin_reads,
+          plugin_disclosures: @plugin_disclosures.to_h,
           discovery_digests: @discovery_digests
         )
       end
@@ -1152,11 +1229,13 @@ module Rigor
           @digests[path] = pack_digest(path)
           fresh_reads.key?(path) ? @plugin_reads[path] = fresh_reads[path] : @plugin_reads.delete(path)
         end
+        absorb_disclosures(runner, analyze_set)
         forget_unbound_digests
         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
+        @synthetic_surface_digest = synthetic_surface_digest_of(runner)
         refresh_return_summaries(runner, analyze_set)
         refresh_effect_collections(runner, analyze_set)
       end
@@ -1200,6 +1279,7 @@ module Rigor
         @digests.delete(path)
         @sources.delete(path)
         @plugin_reads.delete(path)
+        @plugin_disclosures.forget(path) # Unpinned hygiene: a removed file is never served, so never replayed.
         @symbol_sources.delete(path)
         @ancestry_sources.delete(path)
         @missing.delete(path)
@@ -1271,7 +1351,8 @@ module Rigor
       # top-level def, `method:C#m` otherwise), then unions the recorded negative-dependents of those keys.
       # Issue #1120 — plus the consumers of any refinement name the edit moved ({#refinement_affected}). Issue #1367 —
       # and every file whose last result holds a `global.*` diagnostic ({#global_write_reporters}). Issue #1459 — and
-      # the consumers of any method name a file started or stopped defining ({#defined_name_affected}).
+      # the consumers of any method name a file started or stopped defining ({#defined_name_affected}). Issue #2134 —
+      # and the consumers of any visibility slot a file moved ({#visibility_name_affected}).
       def negative_affected(changed, removed, new_fingerprints, new_class_decls, new_constant_decls, summary = nil)
         appeared_methods = Incremental.appeared_symbols(changed, @symbol_fingerprints, new_fingerprints)
         # Issue #639 — a class DISAPPEARING satisfies the `class:` kind too, now that a resolved bare
@@ -1288,11 +1369,18 @@ module Rigor
         keys = appeared_methods.map { |symbol| negative_key_for(symbol) }
         keys.concat(class_move_keys(moved_classes))
         keys.concat(moved_constants.map { |name| "constant:#{name.split('::').last}" })
-        Incremental.negative_closure(keys, @negative_dependents) | refinement_affected(changed + removed, summary) |
-          defined_name_affected(changed + removed, summary) | mark_affected(changed + removed, summary) |
+        Incremental.negative_closure(keys, @negative_dependents) | table_diff_affected(changed + removed, summary) |
           global_write_reporters
       end
 
+      # The consumers of the name-keyed edges whose producers diff a per-file table between each file's seed bundle
+      # and the scan.
+      def table_diff_affected(paths, summary)
+        refinement_affected(paths, summary) | defined_name_affected(paths, summary) |
+          visibility_name_affected(paths, summary) | mark_affected(paths, summary) |
+          global_census_affected(paths, summary) | ivar_set_affected(paths, summary)
+      end
+
       # Issue #1833 — the consumers whose answer read a class mark that moved in this edit. A reader of a class's
       # envelope bucket records `mark:<last segment>` (`Scope#parameter_envelopes_of`), whichever way it answered, so
       # a file that adds or drops only a mark (`x.singleton_class.prepend(Comparable)`, `o.extend(Helper)` in a
@@ -1319,7 +1407,8 @@ module Rigor
         keys = moved.map { |(class_name, _mark)| "mark:#{class_name.split('::').last}" }.uniq
         keys.concat(mixin_keys(tainted))
         extended = Scope::DiscoveryIndex::ENVELOPE_OBJECT_EXTENDED_MARK
-        keys << "mark:*" if moved.any? { |(_class_name, mark)| mark == extended }
+        meta = Scope::DiscoveryIndex::ENVELOPE_META_SUPERCLASS_MARK
+        keys << "mark:*" if moved.any? { |(_class_name, mark)| mark == extended || mark == meta }
         Incremental.negative_closure(keys, @negative_dependents)
       end
 
@@ -1379,8 +1468,55 @@ module Rigor
         Incremental.negative_closure(names.map { |name| "defines:#{name}" }, @negative_dependents)
       end
 
+      # Issue #2158 — the consumers whose `global.*` write rule read a census entry that a file in `paths` started or
+      # stopped writing. The before-state is each file's seed bundle, the after-state the scan's per-file census. The
+      # write the census silenced reports nothing, so {#global_write_reporters} does not reach it.
+      def global_census_affected(paths, summary)
+        after = (summary && summary[:global_write_census]) || {}
+        before = paths.to_h { |path| [path, @seed_bundles.dig(path, :global_write_census)] }
+        keys = Incremental.changed_global_census_keys(paths, before, after)
+        return Set.new if keys.empty?
+
+        Incremental.negative_closure(keys, @negative_dependents)
+      end
+
+      # Issue #1154 — the consumers whose declared-parameter ivar credit read an ivar writer entry a file in `paths`
+      # started or stopped recording ({GlobalWriteCensus.ivar_key}: `ivar_set:@x`, `ivar_set_class:K`,
+      # `own_write:K#@x`). The before-state is each file's seed bundle, the after-state the scan's per-file census. The
+      # write sits in a method body, so neither the declaration signature nor the symbol fingerprints move with it.
+      def ivar_set_affected(paths, summary)
+        after = (summary && summary[:global_write_census]) || {}
+        keys = Set.new
+        paths.each do |path|
+          census = @seed_bundles.dig(path, :global_write_census) || Inference::GlobalWriteCensus::EMPTY
+          before = Inference::GlobalWriteCensus.ivar_set_entries(census)
+          now = Inference::GlobalWriteCensus.ivar_set_entries(after[path] || Inference::GlobalWriteCensus::EMPTY)
+          (before ^ now).each { |entry| keys << Inference::GlobalWriteCensus.ivar_key(entry) }
+        end
+        return Set.new if keys.empty?
+
+        Incremental.negative_closure(keys.to_a, @negative_dependents)
+      end
+
+      # Issue #2134 — the consumers whose answer read a class's visibility slot for a method, or its contest, for each
+      # slot whose entries a file in `paths` added, dropped or changed (`Scope#discovered_method_visibility`). The
+      # before-state is each file's seed bundle, the after-state the scan's per-file entries. A `private :foo` in a
+      # reopening or a `class_eval` block moves no `def`, so neither the symbol fingerprints nor the defined-name diff
+      # sees it.
+      def visibility_name_affected(paths, summary)
+        after = (summary && summary[:visibility_entries]) || {}
+        before = paths.to_h do |path|
+          bundle = @seed_bundles[path]
+          [path, bundle && Inference::ScopeIndexer.visibility_entries(bundle)]
+        end
+        slots = Incremental.changed_visibility_slots(paths, before, after)
+        return Set.new if slots.empty?
+
+        Incremental.negative_closure(slots.map { |slot| "visibility:#{slot}" }, @negative_dependents)
+      end
+
       # The qualified class/module names declared in the pre-parsed `index` (shared with
-      # {#symbol_fingerprints_from_index}, so the changed set is parsed once). `{ path => Set<class name> }`.
+      # {#symbol_fingerprints_from_index}, so the changed set is parsed once), keyed by path.
       def class_declarations_from_index(index)
         return {} if index.nil?
 
@@ -1541,7 +1677,22 @@ module Rigor
       # and (#1898) their effect collections, so the run closes its effect graph over the whole project.
       def served_state(reused)
         { served_per_file_diagnostics: @cache.slice(*reused),
-          served_effect_collections: @effect_collections.slice(*reused) }
+          served_effect_collections: @effect_collections.slice(*reused),
+          served_run_disclosures: @plugin_disclosures.served(reused, @stale_disclosures) }
+      end
+
+      # Issue #2020 — folds the run's run-scoped registrations into the ledger, refreshing the keys this recheck found
+      # stale. Extracted to keep {#absorb} under its ABC budget.
+      def absorb_disclosures(runner, analyze_set)
+        @plugin_disclosures.absorb(runner.analysis_disclosures, analyze_set, @stale_disclosures)
+        @stale_disclosures = Set.new
+      end
+
+      # Issue #2020 — the run-scoped plugin rows whose reads went stale ({RunDisclosureLedger}): one registering file
+      # each joins the closure, and their replays are withheld until {#absorb} refreshes them from that file.
+      def disclosure_refreshers(removed)
+        @stale_disclosures = @plugin_disclosures.stale_identities { |row| plugin_read_fresh?(row) }
+        @plugin_disclosures.refreshers(@stale_disclosures, removed.to_set)
       end
 
       # Issue #1898 — the plugin effect-fact digest a run's collections were stamped under. A plugin writes its
@@ -1560,6 +1711,21 @@ module Rigor
         effect_plugin_digest_of(runner) != @effect_plugin_digest
       end
 
+      # PR #2286 review M1 — whether the ADR-16 synthetic-method index `runner` built differs from the one the
+      # served files were analysed under. The index comes from class-body DSL calls (`devise :confirmable`,
+      # a Tier C `attribute`), which no declaration signature records and no dependency edge names, so a file
+      # that dispatched through a synthesised member is not in the closure of the edit that removed it. The
+      # comparison waits for the run because the index is built by its pre-pass; a move re-analyses the project.
+      def synthetic_surface_moved?(runner, reused)
+        return false if reused.empty?
+
+        synthetic_surface_digest_of(runner) != @synthetic_surface_digest
+      end
+
+      def synthetic_surface_digest_of(runner)
+        runner.synthetic_method_index&.surface_digest
+      end
+
       # The answer {#recheck} gives when {#served_effects_stale?}: a full baseline, reported as a recheck that
       # re-analysed every file. {#run_incremental} reads `rebaselined` so it neither runs a second baseline
       # nor reports the run as warm.
@@ -1644,19 +1810,12 @@ module Rigor
       def rebind_buffer(files)
         return if @buffer.nil? || files.include?(@buffer.logical_path)
 
-        target = real_path(@buffer.logical_path)
-        return if target.nil?
+        target = BufferBinding.real_path(@buffer.logical_path)
 
-        match = files.find { |path| real_path(path) == target }
+        match = files.find { |path| BufferBinding.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.

data/lib/rigor/analysis/path_expansion.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../rooted_glob"
+require_relative "diagnostic"
 
 module Rigor
   module Analysis
@@ -10,8 +11,13 @@ module Rigor
     # is taken verbatim; anything else contributes no files here (the Runner layers its own path-error
     # diagnostics and buffer / in-memory handling on top — none of which add or remove files for an ordinary
     # on-disk check, so the two file sets agree).
+    #
+    # #1991 — also the one place a path that names neither a directory nor a `.rb` file is worded and
+    # severity-graded, so `rigor check` and `rigor sig-gen` report the same path error the same way.
     module PathExpansion
       RUBY_GLOB = "**/*.rb"
+      NO_SUCH_PATH = "no such file or directory"
+      NOT_A_RUBY_FILE = "not a Ruby file (expected `.rb` or a directory)"
 
       module_function
 
@@ -28,10 +34,45 @@ module Rigor
         end
       end
 
+      # The `[path, message]` pairs for each of `paths` that names neither a directory nor a `.rb` file,
+      # worded as `rigor check` words them.
+      def unusable(paths)
+        Array(paths).each_with_object([]) do |path, bad|
+          next if File.directory?(path) || (File.file?(path) && path.end_with?(".rb"))
+
+          bad << [path, unusable_message(path)]
+        end
+      end
+
+      def unusable_message(path)
+        File.exist?(path) ? NOT_A_RUBY_FILE : NO_SUCH_PATH
+      end
+
+      # The error diagnostics for `bad` (from {unusable}). A bad path among valid ones is a warning that it was
+      # skipped; a bad path that leaves nothing to analyse is an error, so a lone typo is not masked.
+      def diagnostics(bad, any_files:)
+        severity = any_files ? :warning : :error
+        suffix = any_files ? " (skipped)" : ""
+        bad.map do |path, message|
+          Diagnostic.new(path: path, line: 1, column: 1, message: "#{message}#{suffix}", severity: severity)
+        end
+      end
+
       def directory_files(dir, exclude_patterns, base: Dir.pwd)
         reject_excluded(RootedGlob.glob(dir, RUBY_GLOB), exclude_patterns, base: base)
       end
 
+      # The configured project files, expanded as `rigor check` expands its configured paths: a directory globs,
+      # any other entry (a file, or a path that does not exist) is kept verbatim and left to the reader to skip.
+      # The file list a cross-file discovery seed is folded over ({Protection::DiscoverySeed}).
+      def configured_files(configuration)
+        Array(configuration.paths).flat_map do |path|
+          next [path] unless File.directory?(path)
+
+          directory_files(path, configuration.exclude_patterns, base: configuration.exclude_base)
+        end
+      end
+
       # `exclude_patterns` are matched with `File.fnmatch?` WITHOUT `FNM_PATHNAME`, so `**`/`*` span separators
       # (the patterns behave like substring globs) — the exact semantics the Runner's directory glob applies.
       #

data/lib/rigor/analysis/require_relative_closure.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  module Analysis
+    # Issue #2021 — the files a run analyses outside the configured `paths:` load through `require_relative`.
+    #
+    # A run over path arguments widens its discovery to the configured paths (#684), which is the whole project for
+    # a file inside them. A file outside them has no such project: `rigor check plugins/x/lib/rigor/plugin/x.rb`
+    # in a repository whose `paths:` is `lib` discovered `x.rb` and `lib` alone. The plugin's nested `Effects`,
+    # declared in the sibling `x/effects.rb`, was then invisible, the lexical lookup fell through to the
+    # project's `Rigor::Effects`, and every call on it drew a false `call.undefined-method` that checking the
+    # plugin's `lib` did not.
+    #
+    # The file names its siblings itself: Ruby loads what it `require_relative`s before any of its code runs, so
+    # those declarations are in scope at runtime. {.closure} follows that graph from the out-of-paths files,
+    # through each target that is itself outside the configured paths. A target under a configured path is
+    # already discovered and stops the walk there, so the files inside `paths:` are discovered exactly as a run
+    # over the configured paths discovers them. Only a string literal counts (`require_relative "a/b"`, with or
+    # without the `.rb`); a computed name, `require`, `load` and `autoload` are not followed, so a gem's own
+    # files and a Zeitwerk-loaded tree are not reached this way.
+    #
+    # The walk sees one entry point's load graph, and a file it does not reach may redefine what a walked file
+    # defines. The runner therefore discovers the walked files as uncertain: their declarations resolve constants
+    # and their methods exist, but no return type, arity or visibility is read from them.
+    module RequireRelativeClosure
+      # The walk's answer: the existing targets it reached, and the targets it named that are not files (each an
+      # input of the answer too, since one appearing would join the discovery).
+      Result = Data.define(:found, :missing)
+
+      module_function
+
+      # @param seeds — the analysed files outside the configured paths, as spelled by the run.
+      # @param covered — `->(real_path) { Boolean }`, whether a target lies under a configured path, where discovery
+      #   holds it already. The walk neither adds nor follows such a target. Paths are compared as real paths, so a
+      #   symlinked spelling of a configured file is covered too.
+      # @param read — `->(path) { String }`, the source of a file (an editor buffer's bytes for its file).
+      # @return a {Result}; `found` holds absolute paths in walk order, each file once, and never a seed.
+      def closure(seeds, covered:, read:)
+        seen = seeds.to_set { |path| real_path(path) }
+        queue = seeds.dup
+        found = []
+        missing = []
+        until queue.empty?
+          targets_of(queue.shift, read).each do |target|
+            next missing << target unless File.file?(target)
+
+            real = real_path(target)
+            next if covered.call(real) || !seen.add?(real)
+
+            found << target
+            queue << target
+          end
+        end
+        Result.new(found: found, missing: missing.uniq)
+      end
+
+      def real_path(path)
+        File.realpath(path)
+      rescue SystemCallError
+        File.absolute_path(path)
+      end
+
+      # The `.rb` paths `path` names with a literal `require_relative`, absolute, whether or not they exist.
+      def targets_of(path, read)
+        source = read.call(path)
+        return [] if source.nil?
+
+        base = File.dirname(File.absolute_path(path))
+        literal_features(Prism.parse(source).value).map do |feature|
+          File.expand_path(feature.end_with?(".rb") ? feature : "#{feature}.rb", base)
+        end
+      rescue StandardError
+        []
+      end
+
+      # In source order, so discovery meets the targets in the order Ruby loads them.
+      def literal_features(root)
+        calls = []
+        stack = [root]
+        until stack.empty?
+          node = stack.pop
+          calls << node if literal_feature(node)
+          stack.concat(node.compact_child_nodes)
+        end
+        calls.sort_by { |call| call.location.start_offset }.filter_map { |call| literal_feature(call) }
+      end
+
+      def literal_feature(node)
+        return nil unless node.is_a?(Prism::CallNode) && node.name == :require_relative && node.receiver.nil?
+
+        arguments = node.arguments&.arguments
+        return nil unless arguments&.size == 1 && arguments.first.is_a?(Prism::StringNode)
+
+        arguments.first.unescaped
+      end
+    end
+  end
+end

data/lib/rigor/analysis/rule_catalog.rb

@@ -25,7 +25,7 @@ module Rigor
     #   profile, taken from `Configuration::SeverityProfile::PROFILES`.
     # - `evidence_tier` — `:high` / `:medium` / `:low` (or `nil` for informational helpers), Rigor's own
     #   confidence that a firing is a true positive, derived from the rule's firing gates. `:high` rules
-    #   fire only on a concrete, statically- known type with no metaprogramming escape (Rigor's
+    #   fire only on a concrete, statically-known type with no metaprogramming escape (Rigor's
     #   false-positive discipline has already filtered the uncertain cases); `:medium` rules rest on flow /
     #   inference proofs that inherit a documented FP envelope (loop / mutation / RBS-strictness modelling
     #   gaps); `:low` rules are resolution- or coverage-gap signals where a firing often reflects missing
@@ -706,7 +706,11 @@ module Rigor
             "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."
+            "`Module.new`, `Struct.new`, `Data.define`): that body defines another class.",
+            "The class descends from a plugin-declared per-invocation class (ADR-125; rigor-actionpack declares " \
+            "`ActionController::Base` / `ActionController::API`, rigor-actionmailer `ActionMailer::Base`), and the " \
+            "write and every conflicting write sit in different actions: public methods no callback macro or " \
+            "`helper_method` names. One action runs per instance."
           ],
           suppression: "`# rigor:disable ivar-write-mismatch` on the offending write.",
           severity_authored: :error,
@@ -1116,7 +1120,7 @@ module Rigor
 
       module_function
 
-      # Looks up a rule by canonical id, legacy alias, or family wildcard. Returns an Array<Entry>:
+      # Looks up a rule by canonical id, legacy alias, or family wildcard. Returns the matching entries:
       #
       # - canonical id → 1-element array,
       # - legacy alias → 1-element array (resolved to canonical),