rigortype 0.2.9 → 0.3.1

data/lib/rigor/analysis/path_expansion.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Analysis
+    # ADR-87 WD4 — project file-set expansion shared by the {Analysis::Runner} (miss path) and the
+    # boot-slimming {RunCacheProbe}, so both resolve the IDENTICAL analyzed-path SET that feeds the run cache
+    # key's `paths` slot. A directory argument globs `**/*.rb` and drops excluded paths; a `.rb` file argument
+    # 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).
+    module PathExpansion
+      RUBY_GLOB = "**/*.rb"
+
+      module_function
+
+      # The `.rb` files an ordinary (non-buffer) check over `paths` would analyze.
+      def ruby_files(paths, exclude_patterns)
+        Array(paths).flat_map do |path|
+          if File.directory?(path)
+            directory_files(path, exclude_patterns)
+          elsif File.file?(path) && path.end_with?(".rb")
+            [path]
+          else
+            []
+          end
+        end
+      end
+
+      def directory_files(dir, exclude_patterns)
+        reject_excluded(Dir.glob(File.join(dir, RUBY_GLOB)), exclude_patterns)
+      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.
+      def reject_excluded(file_list, exclude_patterns)
+        return file_list if exclude_patterns.empty?
+
+        file_list.reject { |path| exclude_patterns.any? { |pattern| File.fnmatch?(pattern, path) } }
+      end
+    end
+  end
+end

data/lib/rigor/analysis/plugin_fact_fingerprint.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "runner"
+
+module Rigor
+  module Analysis
+    # ADR-88 WD1 — a stable fingerprint of the plugin FACT SURFACE for an incremental run: the plugin-computed
+    # values a cached per-file diagnostic can depend on but that the snapshot's global fingerprint (config /
+    # gems / RBS env / `signature_paths:`) does NOT capture.
+    #
+    # The gap: a plugin like `rigor-sorbet` reads `.rb` / `.rbi` sig files under its own `paths:` / `rbi_paths:`
+    # (outside `signature_paths:`), builds a catalog, and contributes `dynamic_return` types at call sites in
+    # OTHER files. An edit to such a sig file changes the types those call sites resolve WITHOUT moving any
+    # analyzed file's content — so `IncrementalSnapshot.fingerprint` stays fresh, the recheck sees an empty
+    # changed set, and it serves the stale cached diagnostics. Nothing in the ADR-46 dependency graph records
+    # the cross-file plugin read (the catalog is plugin-internal, not a `Scope` table).
+    #
+    # This class digests three fact-surface channels after plugin `#prepare`:
+    #   (a) every ADR-9 fact-store publication `(plugin_id, name) -> value` (a producer/consumer fact such as
+    #       `activerecord :model_index`, `dry-types :dry_type_aliases`),
+    #   (b) every declared ADR-60 producer's computed value (`sorbet :catalog`, `actionpack :controller_index`),
+    #   (c) each plugin's optional {Plugin::Base#incremental_state_fingerprint} — a hook for internal catalog
+    #       state that lives in neither (a) nor (b).
+    #
+    # The digest rides the {Cache::IncrementalSnapshot} (schema 9); a warm recheck compares it and, on a
+    # mismatch, invalidates the snapshot and runs a full analysis (the conservative, sound direction).
+    #
+    # OPAQUE plugins: a plugin that CONTRIBUTES per-call types (`dynamic_return` / `narrowing_facts`) but
+    # declares NONE of (a)/(b)/(c) has stale-able state the fingerprint cannot see. Rather than silently risk a
+    # stale reuse, such a plugin makes the snapshot un-reusable (a full analysis every run) and is named in a
+    # one-line note. The bundled contributing plugins all declare a surface (producers, facts, or the hook), so
+    # the bundled set stays incremental-capable; a third-party plugin that contributes types must do the same.
+    #
+    # The probe is ALWAYS sequential and independent of the analysis's pool mode, so the invalidation decision
+    # is identical whether the recheck ran pooled or sequential (the pooled-vs-sequential parity requirement).
+    class PluginFactFingerprint
+      # `digest` is nil when no plugins are loaded — the fast path (nothing to fingerprint), which reuses
+      # freely. `opaque_plugin_ids` names contributing-but-surfaceless plugins (see the class doc); when
+      # non-empty the snapshot is never reused.
+      Result = Data.define(:digest, :opaque_plugin_ids) do
+        def opaque?
+          !opaque_plugin_ids.empty?
+        end
+
+        # A warm recheck may reuse the snapshot only when this run is not opaque and its fact-surface digest
+        # matches the one the snapshot stored. A nil `stored` (a pre-schema-9 snapshot, or a snapshot written
+        # before any plugin existed) never matches a computed digest — the conservative full-run direction —
+        # while a nil==nil (plugin-free project both times) reuses.
+        def reusable_against?(stored)
+          !opaque? && digest == stored
+        end
+      end
+
+      # The SEQUENTIAL probe: load the plugins and run `#prepare` fresh, then fingerprint. Pool-independent
+      # (its prepare pass is always sequential), so it is the pooled-mode path and the reference the parity
+      # spec asserts against.
+      def self.compute(configuration:, cache_store:, plugin_requirer: nil)
+        new.digest_registry(
+          prepared_registry(configuration: configuration, cache_store: cache_store, plugin_requirer: plugin_requirer)
+        )
+      end
+
+      # ADR-88 WD1 — the CHEAP post-hoc path: fingerprint a registry the analysis runner ALREADY prepared
+      # (sequential runs run `#prepare` and consult the producers during analysis, so producer values are
+      # memoised and their cache entries current). Avoids a second `#prepare` pass and a second producer
+      # validation. Used only when the runner's main-process registry is prepared (sequential); the pooled path
+      # (whose main process skips `#prepare`) falls back to {.compute}. Both compute the identical digest for a
+      # given fact surface, so the reuse decision is pool-independent.
+      def self.from_registry(registry)
+        new.digest_registry(registry)
+      end
+
+      # Loads the plugins and runs every `#prepare` hook sequentially, returning the prepared registry (nil on
+      # any failure → the caller treats it as "no fact surface").
+      def self.prepared_registry(configuration:, cache_store:, plugin_requirer:)
+        Runner::ProjectPrePasses.new(
+          configuration: configuration, cache_store: cache_store, buffer: nil,
+          plugin_requirer: plugin_requirer, pool_mode: -> { false }
+        ).prepared_registry
+      rescue StandardError
+        nil
+      end
+
+      def digest_registry(registry)
+        return Result.new(digest: nil, opaque_plugin_ids: [].freeze) if registry.nil? || registry.empty?
+
+        facts_by_plugin = facts_by_plugin(registry.plugins.first&.services&.fact_store)
+        parts = fact_parts(facts_by_plugin)
+        opaque = []
+        registry.plugins.each { |plugin| collect_plugin_parts(plugin, facts_by_plugin, parts, opaque) }
+        # Sort the parts so the digest is independent of plugin registration / iteration order.
+        Result.new(
+          digest: Digest::SHA256.hexdigest(parts.sort.join("\x00")),
+          opaque_plugin_ids: opaque.uniq.freeze
+        )
+      end
+
+      private
+
+      # Channel (a) parts: one `fact\x1f<plugin>\x1f<name=digest,...>` string per publishing plugin.
+      def fact_parts(facts_by_plugin)
+        facts_by_plugin.map { |plugin_id, entries| "fact\x1f#{plugin_id}\x1f#{entries.sort.join("\x1e")}" }
+      end
+
+      # Appends one plugin's producer / hook parts to `parts` and marks it opaque when it contributes a type
+      # (`dynamic_return` / `narrowing_facts`) yet declares NONE of (a)/(b)/(c).
+      def collect_plugin_parts(plugin, facts_by_plugin, parts, opaque)
+        id = safe_id(plugin)
+        has_facts = facts_by_plugin.key?(id)
+        has_producers = collect_producer_parts(plugin, id, parts, opaque)
+        has_hook = collect_hook_part(plugin, id, parts, opaque)
+        surface = has_facts || has_producers || has_hook
+        opaque << id if !surface && contributes_types?(plugin)
+      end
+
+      # `{ plugin_id => ["name=digest", ...] }` for every ADR-9 published fact (channel a). A plugin that
+      # published nothing does not appear.
+      def facts_by_plugin(fact_store)
+        result = Hash.new { |hash, key| hash[key] = [] }
+        return result if fact_store.nil?
+
+        fact_store.each_fact do |fact|
+          result[fact.plugin_id.to_s] << "#{fact.name}=#{digest_value(fact.value)}"
+        end
+        result
+      rescue StandardError
+        # An unreadable fact store contributes nothing; opacity for contributing plugins is decided below.
+        Hash.new { |hash, key| hash[key] = [] }
+      end
+
+      # Channel (b): a stable signature of every declared producer's VALUE — a digest of the producer's own
+      # value, NOT its cache entry blob. The distinction is load-bearing: the blob also carries the dependency
+      # descriptor (the input files' digests), so it changes on ANY input edit — including a value-PRESERVING
+      # one (editing a controller's body without adding an action leaves `controller_index` identical but
+      # rewrites its blob). Digesting the value invalidates the snapshot only when a producer's contributed
+      # value actually moves (a new action, a changed sig), which is what a cached diagnostic can depend on;
+      # a value-preserving edit keeps the recheck incremental. Returns true when the plugin declared at least
+      # one producer (a surface); a producer whose value cannot be digested marks the plugin opaque.
+      # rubocop:disable Naming/PredicateMethod -- reports has-surface AND appends parts (a side-effecting builder)
+      def collect_producer_parts(plugin, id, parts, opaque)
+        producer_ids = plugin.class.producers.keys
+        return false if producer_ids.empty?
+
+        producer_ids.sort.each do |producer_id|
+          parts << "prod\x1f#{id}\x1f#{producer_id}\x1f#{digest_value(plugin.producer_value(producer_id))}"
+        rescue StandardError
+          opaque << id
+        end
+        true
+      end
+      # rubocop:enable Naming/PredicateMethod
+
+      # Channel (c): the optional {Plugin::Base#incremental_state_fingerprint} hook. Returns true when the
+      # plugin defines it (it has a surface).
+      def collect_hook_part(plugin, id, parts, opaque)
+        return false unless plugin.respond_to?(:incremental_state_fingerprint)
+
+        parts << "hook\x1f#{id}\x1f#{digest_value(plugin.incremental_state_fingerprint)}"
+        true
+      rescue StandardError
+        opaque << id
+        true
+      end
+
+      # A stable content digest of an arbitrary fact / producer value. Producer values are Marshal-clean by
+      # contract (the ADR-45 disk cache serialises them the same way), so this is the same round-trip the cache
+      # already relies on. A Marshal failure raises to the caller, which marks the plugin opaque (never a
+      # silent wrong-value digest).
+      def digest_value(value)
+        Digest::SHA256.hexdigest(Marshal.dump(value))
+      end
+
+      def contributes_types?(plugin)
+        klass = plugin.class
+        klass.dynamic_returns.any? || klass.narrowing_facts_rules.any?
+      rescue StandardError
+        false
+      end
+
+      def safe_id(plugin)
+        plugin.manifest.id.to_s
+      rescue StandardError
+        plugin.class.name.to_s
+      end
+    end
+  end
+end

data/lib/rigor/analysis/rule_catalog.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "check_rules"
+require_relative "check_rules/rule_ids"
 
 module Rigor
   module Analysis
@@ -215,6 +215,40 @@ module Rigor
           since: "0.0.2"
         ),
 
+        CheckRules::RULE_RAISE_NON_EXCEPTION => Entry.new(
+          id: CheckRules::RULE_RAISE_NON_EXCEPTION,
+          summary: "`raise` / `fail` operand provably cannot be raised (TypeError at runtime).",
+          fires_when: [
+            "The call is an implicit-self `raise x` / `fail x` (Kernel#raise) with a plain first " \
+            "positional argument.",
+            "The argument's inferred type is concrete and provably NOT a legal raise operand: not an " \
+            "Exception class, not an Exception instance, not a String, and its class defines no " \
+            "`#exception` (e.g. `raise 42`, `raise :sym`, `raise [1, 2]`, `raise nil` — an explicit " \
+            "nil argument is a TypeError, unlike bare `raise`).",
+            "A Class-object operand fires only when the class is RBS-known and its ancestry provably " \
+            "excludes Exception (including a concretely-resolved bare Module).",
+            "A union argument fires only when EVERY arm is independently illegal."
+          ],
+          does_not_fire_when: [
+            "The argument is `Dynamic[T]` / untyped / unresolved, or a union with any legal or unknown arm.",
+            "The call has an explicit receiver (`obj.raise(...)` is a user method, not Kernel#raise).",
+            "The project redefines `raise` / `fail` anywhere the call could resolve (toplevel def, " \
+            "Object/Kernel monkey-patch, or a def on the enclosing class — in source or `pre_eval:`).",
+            "The argument's class defines `#exception` (RBS-declared or project-defined) — the duck " \
+            "protocol `raise` consults at runtime.",
+            "The instance operand's nominal class subsumes exceptions (`Object`, `Class`, `Module`, a " \
+            "module type) — the runtime value may still be a legal operand.",
+            "The operand's class is declared in the analyzed source — a project `sig/` that omits the " \
+            "superclass would misread the ancestry as non-Exception, so source-declared classes stay silent.",
+            "Bare `raise` (re-raises `$!`), or a splat / keyword / forwarded first argument."
+          ],
+          suppression: "`# rigor:disable call.raise-non-exception`.",
+          severity_authored: :error,
+          severity_by_profile: { lenient: :warning, balanced: :error, strict: :error },
+          evidence_tier: :high,
+          since: "0.3.0"
+        ),
+
         CheckRules::RULE_DUMP_TYPE => Entry.new(
           id: CheckRules::RULE_DUMP_TYPE,
           summary: "`dump_type(expr)` from Rigor::Testing — informational type print.",
@@ -346,6 +380,63 @@ module Rigor
           since: "0.1.17"
         ),
 
+        CheckRules::RULE_RETURN_IN_ENSURE => Entry.new(
+          id: CheckRules::RULE_RETURN_IN_ENSURE,
+          summary: "Explicit `return` inside an `ensure` clause swallows in-flight exceptions.",
+          fires_when: [
+            "An explicit `return` sits lexically inside the `ensure` clause of a `begin` / `def` / class " \
+            "body (`ensure` always runs, so its `return` overrides the method's in-flight return value " \
+            "AND silently discards any exception being raised).",
+            "The `return` is inside a plain block (`each do ... return ... end`) within the ensure body — " \
+            "a `return` there still exits the enclosing method."
+          ],
+          does_not_fire_when: [
+            "The `return` is inside a nested `def`, a lambda (`->` / `lambda`), or a `define_method` " \
+            "block within the ensure body — it exits that inner frame, not the one the `ensure` guards.",
+            "The `ensure` body contains no explicit `return` (implicit last-expression values in `ensure` " \
+            "are discarded harmlessly and do not swallow exceptions)."
+          ],
+          suppression: "`# rigor:disable flow.return-in-ensure` on the `return` line.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :info, balanced: :warning, strict: :error },
+          # Purely syntactic proof with a frame-aware envelope — Ruby's `ensure` semantics make every
+          # firing a real control-flow hazard (RuboCop `Lint/EnsureReturn` precedent, low-FP).
+          evidence_tier: :high,
+          since: "0.3.0"
+        ),
+
+        CheckRules::RULE_SHADOWED_RESCUE_CLAUSE => Entry.new(
+          id: CheckRules::RULE_SHADOWED_RESCUE_CLAUSE,
+          summary: "A `rescue` clause an earlier clause of the same chain already fully catches.",
+          fires_when: [
+            "An earlier `rescue` clause in the same `begin` / `def` rescue chain names a superclass (or " \
+            "the same class) of EVERY exception class the later clause names — `rescue StandardError` " \
+            "followed by `rescue ArgumentError` leaves the ArgumentError arm dead.",
+            "A bare `rescue` / `rescue => e` counts as the implicit `StandardError` on either side.",
+            "Every exception reference in both clauses is a constant path resolving (against its lexical " \
+            "namespace) to a CLASS with known ancestry — RBS / registry core classes, or a project class " \
+            "whose `class Foo < Bar` superclass chain is discovered.",
+            "A multi-class arm (`rescue A, B`) fires only when every class it names is covered by earlier " \
+            "clauses."
+          ],
+          does_not_fire_when: [
+            "Any exception reference in either clause is an unresolved constant, a dynamic expression " \
+            "(`rescue klass_var`), or a splat (`rescue *ERRORS`) — the comparisons involving that clause " \
+            "stay silent.",
+            "A resolved constant is a MODULE (the `rescue MyGem::Error` module-tag mixin pattern — module " \
+            "`===` semantics are custom), or a project constant the discovery cannot certify as a class.",
+            "The later clause names a SUPERCLASS of an earlier one — the normal narrow-to-wide rescue order.",
+            "The clauses belong to different (nested) `begin` nodes — only clauses of the same chain compare."
+          ],
+          suppression: "`# rigor:disable shadowed-rescue-clause` on the shadowed `rescue` line.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :info, balanced: :warning, strict: :error },
+          # Purely syntactic + class-ancestry proof: both sides must resolve to concrete classes with known
+          # ancestry before a comparison happens, so a firing has no flow / mutation FP envelope.
+          evidence_tier: :high,
+          since: "0.3.0"
+        ),
+
         CheckRules::RULE_DEAD_ASSIGNMENT => Entry.new(
           id: CheckRules::RULE_DEAD_ASSIGNMENT,
           summary: "Local variable assigned in a method body but never read.",
@@ -370,6 +461,33 @@ module Rigor
           since: "0.1.2"
         ),
 
+        CheckRules::RULE_DUPLICATE_HASH_KEY => Entry.new(
+          id: CheckRules::RULE_DUPLICATE_HASH_KEY,
+          summary: "Duplicate literal key within a single Hash literal (the last entry wins silently at runtime).",
+          fires_when: [
+            "Two entries of one Hash literal — braced (`{ a: 1, a: 2 }`) or bare keyword arguments " \
+            "(`m(a: 1, a: 2)`) — carry the same value-pinned literal key: a symbol (the `key:` shorthand " \
+            "and `:key =>` spell the same symbol), a plain non-interpolated string, an integer, a float, " \
+            "or `true` / `false` / `nil`.",
+            "A `**splat` between two identical literal keys does not rescue the pair — the later literal " \
+            "entry still overwrites the earlier one regardless of what the splat contributes."
+          ],
+          does_not_fire_when: [
+            "Either key is not value-pinned at parse time: interpolated strings / symbols, constants, " \
+            "method calls, locals, and `**splat` entries are never compared.",
+            "The keys live in different literal kinds — `:a` vs `\"a\"`, and `1` vs `1.0` (`1.eql?(1.0)` " \
+            "is false, so Hash treats them as distinct keys) never collide.",
+            "The repeated keys sit in different Hash literals (nested literals are each their own scope)."
+          ],
+          suppression: "`# rigor:disable duplicate-hash-key` on the later occurrence's line.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :info, balanced: :warning, strict: :error },
+          # Purely syntactic value-pinned comparison with no metaprogramming escape: when it fires, the
+          # runtime overwrite is certain (Ruby itself warns under `-w`).
+          evidence_tier: :high,
+          since: "0.3.0"
+        ),
+
         CheckRules::RULE_RETURN_TYPE => Entry.new(
           id: CheckRules::RULE_RETURN_TYPE,
           summary: "Method body's last-expression type is incompatible with the declared return type.",
@@ -526,6 +644,113 @@ module Rigor
           # escapes are excluded.
           evidence_tier: :high,
           since: "0.1.2"
+        ),
+
+        CheckRules::RULE_SUPPRESSION_UNKNOWN_RULE => Entry.new(
+          id: CheckRules::RULE_SUPPRESSION_UNKNOWN_RULE,
+          summary: "A `# rigor:disable[-file]` comment names a rule that does not exist.",
+          fires_when: [
+            "A `# rigor:disable` / `# rigor:disable-file` marker carries a token that is not a canonical " \
+            "rule id, a legacy alias, `all`, or a family wildcard (`call` / `flow` / ...).",
+            "The token is also not a known non-catalogue engine diagnostic (`rbs_extended.*`, `dynamic.*`, " \
+            "`rbs.*`, `pre-eval.*`, or a bare engine id such as `load-error`).",
+            "Typically a typo — `call.undefined-metod` — leaving the suppression silently ineffective."
+          ],
+          does_not_fire_when: [
+            "The token resolves (canonical id, legacy alias, `all`, family wildcard, known engine id).",
+            "The token starts with `plugin.` — plugins load dynamically, so their rule vocabulary cannot " \
+            "be enumerated statically and under-warning is the FP-safe direction.",
+            "The comment merely mentions the marker followed by non-token text (documentation prose " \
+            "like \"`# rigor:disable <rule>` comments\") — that is not parsed as a suppression either."
+          ],
+          suppression: "Fix or remove the dead token; `# rigor:disable suppression.unknown-rule` on the " \
+                       "same line, or `disable: [\"suppression.unknown-rule\"]` in `.rigor.yml`.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :warning, balanced: :warning, strict: :warning },
+          # Pure token-table membership over the same tables the suppression matcher uses — no inference
+          # uncertainty; the plugin/prose escapes above are excluded before firing.
+          evidence_tier: :high,
+          since: "0.3.0"
+        ),
+
+        CheckRules::RULE_SUPPRESSION_EMPTY => Entry.new(
+          id: CheckRules::RULE_SUPPRESSION_EMPTY,
+          summary: "A `# rigor:disable[-file]` comment lists no rules.",
+          fires_when: [
+            "A comment is exactly the bare marker (`# rigor:disable` / `# rigor:disable-file`) with " \
+            "nothing but whitespace or commas after it.",
+            "Such a marker suppresses nothing — the author almost certainly meant to name rules or `all`."
+          ],
+          does_not_fire_when: [
+            "At least one token follows the marker (each token is then checked by " \
+            "`suppression.unknown-rule` instead).",
+            "Non-token text follows the marker (documentation prose mentioning the syntax)."
+          ],
+          suppression: "Complete the marker (`# rigor:disable <rule>` / `all`) or delete it; " \
+                       "`disable: [\"suppression.empty\"]` in `.rigor.yml`.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :warning, balanced: :warning, strict: :warning },
+          # Syntactic: the marker word is present and the token list is provably empty.
+          evidence_tier: :high,
+          since: "0.3.0"
+        ),
+
+        CheckRules::RULE_VALUE_USE_VOID => Entry.new(
+          id: CheckRules::RULE_VALUE_USE_VOID,
+          summary: "A value recovered from an author-declared `-> void` return is used in value context.",
+          fires_when: [
+            "A call resolves through direct RBS dispatch (the receiver's own resolvable class) to a method " \
+            "whose selected overload declares a `-> void` return.",
+            "That call node sits in a value position: an assignment right-hand side (`x = obj.log(...)`), a " \
+            "call's explicit receiver (`obj.log(...).inspect`), or a call's positional argument.",
+            "The `use-of-void-value` bleeding-edge feature is enabled (the rule resolves `:off` otherwise)."
+          ],
+          does_not_fire_when: [
+            "The void call is a bare statement (statement context) — a `void` result is accepted there.",
+            "The value is a legitimate `top` (an author-declared `-> top` return) or any non-void type — " \
+            "only an author-declared `-> void` is recorded, so a real `top` never fires.",
+            "The `-> void` return was resolved through the Object / user-class ancestor fallback rather than " \
+            "direct dispatch (the transitive / ancestor case is deferred, ADR-100 WD4).",
+            "The `use-of-void-value` bleeding-edge feature is not enabled (the default)."
+          ],
+          suppression: "`# rigor:disable static.value-use.void` on the call line, or " \
+                       "`disable: [\"static.value-use.void\"]` in `.rigor.yml`.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :off, balanced: :off, strict: :off },
+          # Recorded only for an author-written `-> void` on the direct-dispatch path — the strongest
+          # possible "do not rely on this return" signal — so a firing is a concrete misuse, not an
+          # inference guess. It ships `:off` behind `bleeding_edge:` per ADR-50 WD1 (a new required
+          # diagnostic is a compatibility change), not for lack of confidence.
+          evidence_tier: :high,
+          since: "0.3.0"
+        ),
+
+        CheckRules::RULE_SUPPRESSION_UNKNOWN_MARKER => Entry.new(
+          id: CheckRules::RULE_SUPPRESSION_UNKNOWN_MARKER,
+          summary: "A comment uses a suppression marker Rigor does not recognise " \
+                   "(`rigor:disable-next-line`, `rigor:enable`, ...).",
+          fires_when: [
+            "A comment carries `rigor:disable-<suffix>` with a suffix other than `file`, or " \
+            "`rigor:enable[-<suffix>]` — typically the RuboCop reflex `# rigor:disable-next-line " \
+            "<rule>` — followed by nothing or a rule-list-shaped remainder.",
+            "Such a marker is invisible to the whole suppression grammar, so it silently suppresses " \
+            "nothing; Rigor's only markers are `# rigor:disable <rules>` (same line) and " \
+            "`# rigor:disable-file <rules>`."
+          ],
+          does_not_fire_when: [
+            "The marker is one of the two recognised forms (their tokens are then checked by " \
+            "`suppression.unknown-rule` / `suppression.empty` instead).",
+            "Non-token text follows the marker (documentation prose mentioning the spelling)."
+          ],
+          suppression: "Rewrite as `# rigor:disable <rules>` on the offending line (Rigor has no " \
+                       "next-line or enable form) or delete the comment; " \
+                       "`disable: [\"suppression.unknown-marker\"]` in `.rigor.yml`.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :warning, balanced: :warning, strict: :warning },
+          # Syntactic: the marker word is present and provably outside the suppression grammar; the
+          # prose escape is excluded before firing.
+          evidence_tier: :high,
+          since: "0.3.0"
         )
       }.freeze
 

data/lib/rigor/analysis/run_cache_key.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "digest"
+# ADR-87 WD4 — the `rbs` gem's version feeds the cache key's `gems` slot (`RbsDescriptor.rbs_gem_entry`).
+# Load only its version constant (not the full RBS parser / env) so the boot-slimming probe can build the key
+# without paying for — or `$LOADED_FEATURES`-touching — the RBS machinery. Falls back to the full gem only if
+# this build of `rbs` has no standalone version file.
+begin
+  require "rbs/version"
+rescue LoadError
+  require "rbs"
+end
+
+require_relative "../version"
+require_relative "../cache/descriptor"
+require_relative "../cache/rbs_descriptor"
+require_relative "../environment/default_libraries"
+
+module Rigor
+  module Analysis
+    # ADR-45 / ADR-87 WD4 — the stable run-result cache KEY, built in ONE place so the miss path (the
+    # {Analysis::Runner}) and the boot-slimming hit path (the {RunCacheProbe}) can never drift out of key
+    # agreement. The key reads the stable inputs known before analysis: the `rbs` gem version, the resolved
+    # RBS library list, a digest of the whole resolved configuration, the engine + schema + `--explain`
+    # triple, and the analyzed-path SET.
+    #
+    # The ONLY difference between the two callers is the `rbs_config_entries` slot: the Runner passes the
+    # loader's `RbsDescriptor.config_entries` (which include a `rbs.virtual_rbs` entry when a plugin's
+    # `source_rbs_synthesizer` contributed one), while the probe passes {#libraries_config_entries} —
+    # reconstructed from config alone, WITHOUT building the RBS environment or loading any plugin. A project
+    # whose plugins DO synthesise virtual RBS therefore produces a probe key that omits that entry, so the
+    # probe simply misses and the full path takes over (sound: never a wrong hit, only a forgone fast lane).
+    # Slot order is irrelevant — {Cache::Descriptor#to_canonical_hash} sorts configs by key.
+    module RunCacheKey
+      module_function
+
+      RUN_DIAGNOSTICS_PRODUCER_ID = "analysis.run-diagnostics"
+
+      # The run-result producer's declared compaction budget (`Cache::Store#evict!` pass 2). Whole-project,
+      # but unlike the `rbs.*` producers several generations can be live at once: the `paths` key slot means
+      # one entry per analyzed-path SET, so `rigor check` over the whole project, over `lib`, and over a
+      # single file are three separate live generations. 16 is a judgement call sized for that churn; it is
+      # a cap on GENERATIONS, not on correctness — over-evicting here costs a recompute, never a wrong
+      # answer. Measured 2026-07-25 against a real project's `.rigor/cache`: the cap does bind (60 distinct
+      # path-set generations observed, differing in the `paths` slot alone), with no evidence yet on how
+      # often an evicted generation is asked for again — see issue #151.
+      GENERATION_CAP = 16
+
+      # @param rbs_config_entries [Array<Cache::Descriptor::ConfigEntry>] 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(
+          gems: [Cache::RbsDescriptor.rbs_gem_entry],
+          configs: rbs_config_entries + [
+            config_entry("configuration", Marshal.dump(configuration.to_h)),
+            config_entry("engine",
+                         "#{Rigor::VERSION}:#{Cache::Descriptor::SCHEMA_VERSION}:#{explain}"),
+            config_entry("paths", files.sort.join("\n"))
+          ]
+        )
+      rescue StandardError
+        nil
+      end
+
+      def config_entry(key, payload)
+        Cache::Descriptor::ConfigEntry.new(key: key, value_hash: Digest::SHA256.hexdigest(payload))
+      end
+
+      # The `rbs.libraries` config slot reconstructed from configuration alone — byte-identical to the
+      # loader's `RbsDescriptor.libraries_entry(loader.libraries)` because `Environment.for_project` merges
+      # exactly `DEFAULT_LIBRARIES + config.libraries` (uniq) into `loader.libraries`.
+      def libraries_config_entries(configuration)
+        merged = (Environment::DEFAULT_LIBRARIES + configuration.libraries.map(&:to_s)).uniq
+        [Cache::RbsDescriptor.libraries_entry(merged)]
+      end
+    end
+  end
+end

data/lib/rigor/analysis/run_cache_probe.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "result"
+require_relative "run_cache_key"
+require_relative "path_expansion"
+require_relative "severity_stamp"
+require_relative "../cache/store"
+require_relative "../cache/file_digest"
+
+module Rigor
+  module Analysis
+    # ADR-87 WD4 — the boot-slimming run-cache hit probe. Serves an ordinary `rigor check`'s diagnostics
+    # straight from the ADR-45 `analysis.run-diagnostics` cache WITHOUT loading the inference engine, its
+    # plugin gems, or building the RBS environment: a warm HIT boots only CLI + config + cache + digest code
+    # (the recon's `$LOADED_FEATURES` never gains a `rigor/inference` entry). The full plugin/prepass +
+    # env-build tax (~0.8s on a gitlab null) is paid ONLY on a miss.
+    #
+    # Soundness is inherited wholesale from ADR-45: the stored dependency descriptor records every file the
+    # prior run read — analyzed sources, the RBS signature tree, AND every file each plugin read mid-analysis
+    # (the Pundit-policy case) — and {Cache::Store#peek_validated} re-checks all of it against the live tree
+    # (ADR-87 `:stat`-validated). A hit therefore means every input the prior run observed is unchanged, so
+    # its cached diagnostics are exactly what a fresh full run would produce; skipping the plugin prepasses is
+    # sound because their inputs are in that same validated set. The key is built through the shared
+    # {RunCacheKey} — a project whose plugins synthesise virtual RBS produces a probe key that omits that
+    # entry, so it simply misses and the full path takes over (never a wrong hit).
+    class RunCacheProbe
+      # @param configuration [Rigor::Configuration]
+      # @param cache_root [String]
+      # @param explain [Boolean] 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
+      #   (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.
+      def serve(paths)
+        files = PathExpansion.ruby_files(paths, @configuration.exclude_patterns)
+        key = RunCacheKey.descriptor(
+          configuration: @configuration, files: files, explain: @explain,
+          rbs_config_entries: RunCacheKey.libraries_config_entries(@configuration)
+        )
+        return nil if key.nil?
+
+        diagnostics = validated_diagnostics(key)
+        return nil if diagnostics.nil?
+
+        Result.new(diagnostics: SeverityStamp.apply(diagnostics, @configuration), stats: nil)
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def validated_diagnostics(key)
+        store = Cache::Store.new(root: @cache_root, max_bytes: @configuration.cache_max_bytes)
+        # The digest fallback + `cache.validation` / RIGOR_STRICT_VALIDATION escape hatch route through the
+        # same per-run FileDigest scope the full run uses.
+        strict = @configuration.cache_validation_strict?
+        Cache::FileDigest.with_run(strict: strict) do
+          store.peek_validated(
+            producer_id: RunCacheKey::RUN_DIAGNOSTICS_PRODUCER_ID, key_descriptor: key
+          )
+        end
+      end
+    end
+  end
+end