rigortype 0.3.6 → 0.3.7

data/lib/rigor/analysis/crash_signature.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Analysis
+    # Issues #665 / #674 / #683 / #686 / #696 — the ONE definition of "an internal failure made this run
+    # report less than it should have".
+    #
+    # Every member of that family shares a defect: the run still exits 0 and its diagnostic list still
+    # looks like an answer, so an absence assertion (`not_to include(...)`, `be_empty`, `all(eq(...))`)
+    # holds on it and a comparison of two such runs (`baseline == mutant`, `recheck == full_run`) reports
+    # "no difference" — because both sides carry the same synthetic row, not because the code agreed. Four
+    # separate consumers needed to recognise these shapes, and before this module each recognised them by
+    # matching a diagnostic MESSAGE with its own string literal. A fourth copy is what this exists to stop:
+    # a reworded message silently disarms whichever copies were not updated, and nothing goes red.
+    #
+    # ## The three shapes
+    #
+    # - `:check_rule` — message begins `internal analyzer error`, `rule: nil`. Built by
+    #   `Runner#analyze_file_body` / `WorkerSession#analyze_body`'s `rescue StandardError`.
+    # - `:plugin` — `severity: :error`, `source_family: :plugin_loader`, `rule: "runtime-error"`. Built by
+    #   `Runner#collect_plugin_diagnostics` / `Runner::ProjectPrePasses#invoke_plugin_prepare`.
+    # - `:rbs_build` — `rule` in {RBS_BUILD_FAILURE_RULES}. Recorded by `Environment::RbsLoader`'s
+    #   env-build and definition-build rescues, surfaced by {Runner::DiagnosticAggregator}.
+    #
+    # The `:plugin` shape is keyed on the structured `(severity, source_family, rule)` triple rather than on
+    # the bare rule name: a plugin is free to define its OWN `"runtime-error"` (or `"load-error"`) under its
+    # own `source_family: "plugin.<id>"`, and several specs legitimately assert on one. Only the
+    # `:plugin_loader` family paired with `"runtime-error"` is the isolation envelope's own row.
+    #
+    # ## Only ONE shape discards a file's analysis
+    #
+    # {.discards_file_analysis?} answers true for `:check_rule` alone, and the distinction is not pedantry —
+    # it decides whether a consumer may still read the run's diagnostics.
+    #
+    # - `:check_rule` — `Runner#analyze_file_body` rescues around the WHOLE per-file body, so what comes
+    #   back is `[crash_row]` and every diagnostic that file would have produced is gone. Nothing is left to
+    #   read.
+    # - `:plugin` — `collect_plugin_diagnostics` replaces only the raising PLUGIN's contribution;
+    #   `CheckRules.diagnose` has already returned, and `invoke_plugin_prepare` adds one row at `.rigor.yml`
+    #   and lets the run proceed. The builtin rules ran, and their diagnostics are all still there. A
+    #   consumer that refuses the whole run over this throws away a real measurement — and because the
+    #   prepare row is appended to every sequential run, it would refuse every run for the life of the
+    #   process.
+    # - `:rbs_build` — the analysis ran to completion and every rule fired, over a type universe missing one
+    #   class (`rbs.coverage.definition-build-failed`) or all of them
+    #   (`rbs.coverage.environment-build-failed`). A degradation the user causes and the diagnostic itself
+    #   reports; a project can sit on it for a release while it fixes its `sig/`.
+    #
+    # The two consumer tiers therefore differ on purpose. The ADR-69 kill oracles arm `:check_rule` only:
+    # refusing a run they could still have measured is the same "manufactures work" error as scoring an
+    # unmeasured mutant a survivor, pointed the other way (issue #686 review). The spec harness additionally
+    # arms `:plugin`, which is suite POLICY rather than a claim about the diagnostics — no spec has a reason
+    # to want a plugin crashing under it, and `allow_plugin_crash:` is the opt-out for the handful whose
+    # subject IS the isolation envelope.
+    module CrashSignature
+      # The `rescue StandardError` in `Runner#analyze_file_body` / `WorkerSession#analyze_body` folds a
+      # raising check rule (or a plugin's node-rule contribution) into ONE diagnostic per file with this
+      # message prefix. Matched on the prefix alone, exactly as the pre-#696 guards did: adding a `rule.nil?`
+      # conjunct would NARROW the match, and the whole point of a guard against a bug is that it stays armed
+      # when the shape shifts.
+      CHECK_RULE_MESSAGE_PREFIX = "internal analyzer error"
+
+      PLUGIN_SOURCE_FAMILY = :plugin_loader
+      PLUGIN_RULE = "runtime-error"
+
+      # The `rbs.coverage.*` rules that mean declared types went missing from this run — an env-wide
+      # collapse and its per-class sibling (#696). Ordered widest consequence last, the way the two rows sit
+      # in `docs/type-specification/diagnostic-policy.md`.
+      RBS_BUILD_FAILURE_RULES = %w[
+        rbs.coverage.definition-build-failed
+        rbs.coverage.environment-build-failed
+      ].freeze
+
+      # The one reason that means a file's whole diagnostic list was replaced by a crash row. `:plugin` and
+      # `:rbs_build` both leave a readable run behind — see the class doc.
+      DISCARDS_FILE_ANALYSIS_REASON = :check_rule
+
+      module_function
+
+      # @param diagnostic [Rigor::Analysis::Diagnostic]
+      # @return [Symbol, nil] `:check_rule`, `:plugin`, `:rbs_build`, or nil for an ordinary diagnostic.
+      def reason(diagnostic)
+        return :check_rule if diagnostic.message.to_s.start_with?(CHECK_RULE_MESSAGE_PREFIX)
+        return :plugin if plugin_isolation_row?(diagnostic)
+        return :rbs_build if RBS_BUILD_FAILURE_RULES.include?(diagnostic.rule)
+
+        nil
+      end
+
+      # True when `diagnostic` is the rescue row that REPLACED a file's analysis — the only shape after which
+      # the run's diagnostics say nothing about the code. NOT a general "something went wrong" predicate; see
+      # the class doc for why `:plugin` and `:rbs_build` are excluded.
+      #
+      # @param diagnostic [Rigor::Analysis::Diagnostic]
+      def discards_file_analysis?(diagnostic)
+        reason(diagnostic) == DISCARDS_FILE_ANALYSIS_REASON
+      end
+
+      # A one-line "<reason> at <path>:<line>: <message>" for a failure message, so whoever reads the raise
+      # sees which shape fired and where without re-deriving it.
+      #
+      # @param diagnostic [Rigor::Analysis::Diagnostic]
+      # @return [String]
+      def describe(diagnostic)
+        "#{reason(diagnostic) || :unknown} at #{diagnostic.path}:#{diagnostic.line}: #{diagnostic.message}"
+      end
+
+      def plugin_isolation_row?(diagnostic)
+        diagnostic.severity == :error &&
+          diagnostic.source_family == PLUGIN_SOURCE_FAMILY &&
+          diagnostic.rule == PLUGIN_RULE
+      end
+      private_class_method :plugin_isolation_row?
+    end
+  end
+end

data/lib/rigor/analysis/dependency_recorder.rb

@@ -168,9 +168,17 @@ module Rigor
         accumulate_read(accumulator, path, symbol)
       end
 
-      # Records a cross-file lookup of `name` (kind `:method` / `:class` / `:const` / …) that resolved to
-      # nothing — a negative dependency.
-      def read_missing(kind, name)
+      # Records a NAME-KEYED cross-file dependency: this consumer's answer depends on what the project makes
+      # of `name` under `kind`, so a recheck must re-analyze it when that changes. The recorded key is
+      # inverted into `negative_dependents` and matched against the producer for its kind.
+      #
+      # For `:method` / `:class` / `:toplevel` this is recorded only on a MISS ({read_missing}) — a resolved
+      # method or class already carries a positive edge to its definition site, which covers every later
+      # change to it. Issue #644's `:constant` kind is recorded on a HIT as well, because a constant's
+      # published value is a function of the WHOLE project's write set for the name, not of the one file that
+      # currently wins: a second declarer appearing in a file the reader has no edge to must drop the name to
+      # `Dynamic` at that reader, and only a name-keyed edge can see it.
+      def read_name(kind, name)
         accumulator = Thread.current[KEY]
         return if accumulator.nil?
 
@@ -179,6 +187,13 @@ module Rigor
         accumulator.missing.add(entry)
       end
 
+      # The miss-only spelling of {read_name}: a cross-file lookup of `name` (kind `:method` / `:class` /
+      # `:toplevel` / …) that resolved to nothing. Kept as the name the internal spec's negative-edge
+      # contract uses.
+      def read_missing(kind, name)
+        read_name(kind, name)
+      end
+
       # The positive-edge aggregation shared by {read_site} and {replay}.
       def accumulate_read(accumulator, path, symbol)
         accumulator.sources << path

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

@@ -139,7 +139,8 @@ module Rigor
         def descend_class_or_module(node, qualified_prefix, in_singleton_class, accumulator, budget)
           name = Source::ConstantPath.qualified_name_or_nil(node.constant_path)
           if name && node.body
-            walk_node(node.body, qualified_prefix + [name], in_singleton_class, accumulator, budget)
+            child_prefix = Source::ConstantPath.declaration_prefix(qualified_prefix, node.constant_path)
+            walk_node(node.body, child_prefix, in_singleton_class, accumulator, budget)
           else
             walk_children(node, qualified_prefix, in_singleton_class, accumulator, budget)
           end

data/lib/rigor/analysis/incremental.rb

@@ -120,6 +120,34 @@ module Rigor
         appeared.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
+      # exists or does not, whereas a constant's published answer is a function of the whole project's write
+      # set for the name, so a *name* diff is the wrong question. All four ways the answer moves are a
+      # descriptor change and none of them is an appearance:
+      #
+      # - the value edited (`[50]` -> `[7]`),
+      # - the write becoming unpublishable or publishable again (`[50]` <-> `:unpublishable`),
+      # - a SECOND declarer appearing, which drops the name to `Dynamic` (`{}` -> `{NAME => …}` in that file),
+      # - a second declarer going away, which restores the precise answer.
+      #
+      # `paths` MUST therefore include removed files as well as changed and added ones; a removed file's
+      # after-state is simply absent, so its whole before-census counts as changed. Returns a frozen Set of
+      # qualified-name Strings. `before` / `after` map a path to `{name => descriptor}`.
+      def changed_constant_publications(paths, before, after)
+        moved = Set.new
+        paths.each do |path|
+          was = before[path] || {}
+          now = after[path]  || {}
+          # `eql?`, not `==`: `[1] == [1.0]` is TRUE, so `LIMIT = 1` becoming `LIMIT = 1.0` would move the
+          # published type (`Constant[1]` -> `Constant[1.0]`) while this diff called it unchanged. The
+          # declaration signature backstops that case today; the producer must not depend on it.
+          (was.keys | now.keys).each { |name| moved << name unless was[name].eql?(now[name]) }
+        end
+        moved.freeze
+      end
+
       # ADR-46 slice 3 — the consumers to re-check because a name they looked up and *missed* (a negative
       # dependency) now resolves. `keys` is the set of negative-dependency keys (`"toplevel:foo"` /
       # `"method:C#m"`) the appeared symbols would satisfy; `negative_dependents` maps each key to the Set of

data/lib/rigor/analysis/incremental_session.rb

@@ -98,6 +98,10 @@ module Rigor
         @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>
+        # 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.
+        @constant_decls = {}
         # ADR-89 WD2 — per-def observed-key return summaries: [path, symbol] => { keys:, returns:, effects: }.
         # Harvested from the ADR-84 return memo after each run; drives the behavioural-stability gate.
         @return_summaries = {}
@@ -259,6 +263,7 @@ module Rigor
         declaration_signatures = (summary && summary[:declaration_signatures]) || {}
         new_fps = symbol_fingerprints_from_index(scan_index)
         new_class_decls = class_declarations_from_index(scan_index)
+        new_constant_decls = constant_declarations_from_index(scan_index)
         changed_pairs = Incremental.changed_symbol_pairs(changed, @symbol_fingerprints, new_fps)
         # ADR-89 WD1 — a changed file whose DECLARATION signature (per-def parameter shape / visibility /
         # ancestry / member layout / def line, bodies excluded) is byte-identical to the snapshot is
@@ -275,7 +280,8 @@ module Rigor
         # minus those stable pairs, and only it (not `changed_pairs`) drives the symbol-dependent fan-out.
         symbol_pairs = behaviourally_unstable_pairs(changed_pairs, unstable, scan_index) | param_pairs
         base = dependents_base(unstable, symbol_pairs)
-        closure = base | changed.to_set | added.to_set | negative_affected(scan, new_fps, new_class_decls)
+        closure = base | changed.to_set | added.to_set |
+                  negative_affected(scan, removed, new_fps, new_class_decls, new_constant_decls)
         closure = param_seed_closure(closure, param_files)
         removed.each { |path| closure |= @dependents[path] || Set.new }
         closure.freeze
@@ -550,12 +556,7 @@ module Rigor
         @symbol_sources    = payload.symbol_sources    || {}
         @ancestry_sources  = payload.ancestry_sources  || {}
         @symbol_fingerprints = payload.symbol_fingerprints || {}
-        # ADR-46 slice 3 — restore negative edges if present (absent in pre-slice-3 snapshots → empty, which
-        # only loses the appeared-symbol re-check refinement; such a snapshot is never loaded by a slice-3+
-        # engine because the engine version + schema is part of the snapshot fingerprint, and
-        # `--verify-incremental` backstops any residual under-capture, so it is never unsound).
-        @missing           = payload.missing || {}
-        @class_decls       = payload.class_decls || {}
+        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.
         # ADR-103 WD13 / #382 — the effects sidecar rides its own identity, so a snapshot whose summaries
@@ -569,12 +570,24 @@ module Rigor
         @negative_dependents = Incremental.invert(@missing)
       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
+      # refinement; such a snapshot is never loaded by a newer engine (the version + SCHEMA are part of the
+      # fingerprint) and `--verify-incremental` backstops any residual under-capture. Extracted to keep
+      # {#restore} under its ABC budget.
+      def restore_structural_declarations(payload)
+        @missing        = payload.missing || {}
+        @class_decls    = payload.class_decls || {}
+        @constant_decls = payload.constant_decls || {}
+      end
+
       def to_payload
         Cache::IncrementalSnapshot::Payload.new(
           cache: @cache, sources: @sources, digests: @digests, analyzed: @analyzed,
           symbol_sources: @symbol_sources, ancestry_sources: @ancestry_sources,
           symbol_fingerprints: @symbol_fingerprints, missing: @missing,
-          class_decls: @class_decls, seed_bundles: @seed_bundles,
+          class_decls: @class_decls, constant_decls: @constant_decls, seed_bundles: @seed_bundles,
           plugin_fact_digest: @plugin_fact_digest,
           return_summaries: marshal_safe_return_summaries,
           param_table: marshal_safe_param_table,
@@ -754,6 +767,7 @@ module Rigor
         # Wholesale replace (the subset runner's pre-pass is complete): a file that lost its last class must
         # drop out of the map so a later re-add registers as an appearance.
         @class_decls = runner.class_declarations
+        @constant_decls = runner.constant_declarations
       end
 
       # Per-symbol body fingerprints from the pre-parsed `index` (the shared scan-summary def-index — Prism
@@ -792,11 +806,18 @@ module Rigor
       # a prior missed lookup. Maps each appeared `"ClassName#method"` to the negative-dependency key it
       # would satisfy (`toplevel:foo` for a top-level def, `method:C#m` otherwise), then unions the recorded
       # negative-dependents of those keys.
-      def negative_affected(changed, new_fingerprints, new_class_decls)
+      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 #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.
+        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_constants.map { |name| "constant:#{name.split('::').last}" })
         Incremental.negative_closure(keys, @negative_dependents)
       end
 
@@ -812,6 +833,20 @@ module Rigor
         result.transform_values(&:freeze).freeze
       end
 
+      # Issue #644 — the per-file PUBLICATION CENSUS of the pre-parsed `index`:
+      # `{ path => { constant name => descriptor } }`, the twin of {#class_declarations_from_index}. The
+      # descriptor is what the diff compares — see {Incremental.changed_constant_publications} for why a bare
+      # name set cannot answer the question.
+      def constant_declarations_from_index(index)
+        return {} if index.nil?
+
+        result = Hash.new { |hash, key| hash[key] = {} }
+        index[:constant_writes].each do |name, by_path|
+          by_path.each { |path, descriptor| result[path][name] = descriptor }
+        end
+        result.transform_values(&:freeze).freeze
+      end
+
       # ADR-89 WD2 — the (live, freshly parsed) def node for a `"Class#method"` / `"Class.method"` symbol in
       # the changed-set scan index, or nil. Instance methods live under `def_nodes`, singleton under
       # `singleton_def_nodes`, both keyed by class name then method Symbol.

data/lib/rigor/analysis/plugin_fact_fingerprint.rb

@@ -151,7 +151,7 @@ module Rigor
       # 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)
+      # rubocop:disable-next 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?
@@ -163,7 +163,6 @@ module Rigor
         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).

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

@@ -81,7 +81,8 @@ module Rigor
             next if use.name.nil?
 
             Scan::Reference.new(as_written: use.name.sub(/\A::/, ""), nesting: [].freeze, from: nil,
-                                role: :production, path: use.path, line: use.line)
+                                role: :production, path: use.path, line: use.line,
+                                rooted: use.name.start_with?("::"))
           end
         end
 
@@ -148,7 +149,7 @@ module Rigor
           @references.each do |ref|
             next unless yield(ref)
 
-            target = resolve(ref.as_written, ref.nesting)
+            target = resolve(ref.as_written, ref.nesting, rooted: ref.rooted)
             set << target if target && @owned.include?(target)
           end
           set
@@ -157,7 +158,7 @@ module Rigor
         # `[from_fqn_or_nil, to_fqn, role]` for every reference that resolves to an owned declaration.
         def resolved_edges
           @resolved_edges ||= @references.filter_map do |ref|
-            target = resolve(ref.as_written, ref.nesting)
+            target = resolve(ref.as_written, ref.nesting, rooted: ref.rooted)
             next unless target && @owned.include?(target)
             next if ref.from == target # a declaration referencing itself is not evidence of use
 
@@ -197,8 +198,16 @@ module Rigor
         end
 
         # Ruby's constant lookup at name granularity: `Module.nesting` innermost first, then the ancestors of
-        # the innermost cresting scope (#354), then the bare name.
-        def resolve(as_written, nesting)
+        # the innermost cresting scope (#354), then the bare name. When `rooted: true`, lexical nesting and
+        # ancestors are skipped, answering the top-level declaration directly (#625).
+        def resolve(as_written, nesting, rooted: false)
+          if rooted
+            return as_written if @by_fqn.key?(as_written)
+
+            idx = as_written.rindex("::")
+            return idx ? resolve(as_written[0, idx], nesting, rooted: true) : nil
+          end
+
           walker = nesting.dup
           until walker.empty?
             candidate = (walker + [as_written]).join("::")

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

@@ -28,8 +28,11 @@ module Rigor
 
         # One constant reference. `from` is the fully-qualified name of the innermost enclosing declaration, or
         # nil for a reference written at file level — that is what makes the graph a reachability graph rather
-        # than a reference count (ADR-102 WD2). `role` is the referring FILE's role (WD8).
-        Reference = Data.define(:as_written, :nesting, :from, :role, :path, :line)
+        # than a reference count (ADR-102 WD2). `role` is the referring FILE's role (WD8). `rooted` is true
+        # when the constant was written with a leading `::` (#625).
+        Reference = Data.define(:as_written, :nesting, :from, :role, :path, :line, :rooted) do
+          def initialize(rooted: false, **) = super
+        end
 
         # ADR-102 WD4 — a site where a constant is reached by a mechanism the static reading cannot follow.
         # `name` is the exact constant when the argument is a literal (`"Foo".constantize`), in which case this
@@ -248,7 +251,8 @@ module Rigor
 
             @references << Reference.new(as_written: as_written, nesting: nesting.dup.freeze,
                                          from: nesting.empty? ? nil : nesting.join("::"),
-                                         role: @role, path: @path, line: node.location.start_line)
+                                         role: @role, path: @path, line: node.location.start_line,
+                                         rooted: Source::ConstantPath.rooted?(node))
           end
         end
       end

data/lib/rigor/analysis/result.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "crash_signature"
+
 module Rigor
   module Analysis
     class Result
@@ -17,6 +19,36 @@ module Rigor
         diagnostics.none?(&:error?)
       end
 
+      # Issue #686 — true when a check rule (or a plugin's node-rule contribution) raised, so
+      # `Runner#analyze_file_body`'s rescue REPLACED the affected file's whole diagnostic list with one
+      # synthetic row. What comes back is then not a weaker account of the code; it is no account of it.
+      #
+      # Any consumer that compares two results, or reads an EMPTY result as "clean", has to ask this first.
+      # A crashed baseline and a crashed mutant carry the same synthetic row, so `==` reports agreement; an
+      # absence assertion holds on the one-diagnostic list the rescue leaves behind. That is how a kill
+      # oracle scored survivors it never measured (#686) and how 1,177 spec examples passed with every check
+      # rule crashing (#674).
+      #
+      # Narrower than "the run reported a failure", deliberately. A raising PLUGIN loses only that plugin's
+      # contribution and a failed RBS definition build loses only a type — in both cases every builtin rule
+      # still ran and its diagnostics are still here, so a consumer that refused those would be discarding a
+      # real measurement. {CrashSignature} carries the full table and the reasoning.
+      #
+      # `success?` is deliberately NOT this question: a crash makes `success?` false (the row is `:error`),
+      # which is why the CLI is loud and CI goes red. It is the callers that read the diagnostic LIST rather
+      # than the exit code which need the predicate.
+      def crashed?
+        diagnostics.any? { |diagnostic| CrashSignature.discards_file_analysis?(diagnostic) }
+      end
+
+      # 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
+
       def error_count
         diagnostics.count(&:error?)
       end

data/lib/rigor/analysis/run_cache_key.rb

@@ -14,8 +14,13 @@ end
 require_relative "../version"
 require_relative "../cache/descriptor"
 require_relative "../cache/engine_source"
+require_relative "../cache/file_digest"
 require_relative "../cache/rbs_descriptor"
 require_relative "../environment/default_libraries"
+# Both resolvers are leaf files (no requires beyond `yaml`), so the boot-slimming probe reaches the two
+# lockfile paths without loading `rigor/environment` or the RBS machinery.
+require_relative "../environment/lockfile_resolver"
+require_relative "../environment/rbs_collection_discovery"
 
 module Rigor
   module Analysis
@@ -80,7 +85,7 @@ module Rigor
       def descriptor(configuration:, files:, explain:, rbs_config_entries:)
         Cache::Descriptor.new(
           gems: [Cache::RbsDescriptor.rbs_gem_entry],
-          configs: rbs_config_entries + engine_source_entries + [
+          configs: rbs_config_entries + engine_source_entries + lockfile_entries(configuration) + [
             config_entry("configuration", Marshal.dump(configuration.to_h)),
             config_entry("engine",
                          "#{Rigor::VERSION}:#{Cache::Descriptor::SCHEMA_VERSION}:#{explain}"),
@@ -106,6 +111,41 @@ module Rigor
         [config_entry("engine-source", identity)]
       end
 
+      # Issue #564 — the two dependency lockfiles, BY CONTENT. Both are inputs to the run's diagnostics and
+      # neither was represented in the key: the locked gem set decides which bundle-shipped `sig/` dirs and
+      # which `rbs_collection` dirs load, which ADR-72 gem overlays apply, what the ADR-82 WD9 missing-gem
+      # constant index owns, and whether `rbs.coverage.missing-gem` fires at all. Editing a lockfile touches
+      # no analyzed source and no `.rbs` file, so the `paths` slot, the `configuration` slot (which carries
+      # the lockfile PATH, never its bytes) and the recorded dependency descriptor were all unchanged by a
+      # `bundle add` — and a warm run replayed the pre-edit diagnostics in BOTH directions: an
+      # `undefined-method` on `3.minutes` surviving the `bundle add activesupport` that licenses the overlay,
+      # and the same call staying silent after the `bundle remove` that revokes it.
+      #
+      # A KEY slot rather than a dependency entry, because a dependency descriptor can only say "a file I
+      # recorded changed": it cannot express a lockfile that did not exist when the entry was written and
+      # does now, which is the `bundle init` / first-`bundle install` case.
+      #
+      # Content-only — the resolved PATH is deliberately not in the payload, so a checkout that moves (a CI
+      # runner's workspace, a renamed directory) still hits with an identical lockfile.
+      def lockfile_entries(configuration)
+        bundler = Environment::LockfileResolver.resolve_lockfile_path(
+          lockfile_path: configuration.bundler_lockfile, auto_detect: configuration.bundler_auto_detect
+        )
+        collection = Environment::RbsCollectionDiscovery.resolve_lockfile_path(
+          lockfile_path: configuration.rbs_collection_lockfile,
+          auto_detect: configuration.rbs_collection_auto_detect
+        )
+        [lockfile_entry("bundler.lockfile", bundler), lockfile_entry("rbs_collection.lockfile", collection)]
+      end
+
+      # `nil` — no lockfile resolves — is itself part of the identity, so it carries its own sentinel rather
+      # than dropping the slot: "absent" and "present but empty" must not key the same.
+      ABSENT_LOCKFILE = "\0absent"
+
+      def lockfile_entry(key, path)
+        config_entry(key, path.nil? ? ABSENT_LOCKFILE : Cache::FileDigest.hexdigest(path.to_s))
+      end
+
       def config_entry(key, payload)
         Cache::Descriptor::ConfigEntry.new(key: key, value_hash: Digest::SHA256.hexdigest(payload))
       end

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

@@ -36,13 +36,16 @@ module Rigor
         #   because they do not parse (`[path, first_error_line]` pairs).
         # @param env_build_failure_snapshot [#call] reader returning the total RBS env-build failure tuple
         #   (`[error_class, first_error_line, conflicting_buffer_names]`) or nil when the env built.
+        # @param definition_build_failures_snapshot [#call] issue #696 — reader returning the per-class
+        #   `RBS::DefinitionBuilder` failures the run observed, as `[class_name, error_class, member,
+        #   conflicting_buffer_names]` tuples. Empty for a healthy sig set.
         # @param conformance_results_snapshot [#call] reader.
         def initialize(configuration:, rbs_extended_reporter:, boundary_cross_reporter:, # rubocop:disable Metrics/ParameterLists
                        source_rbs_synthesis_reporter:, plugin_registry:, dependency_source_index:,
                        pool_mode:, cached_plugin_prepare_diagnostics:,
                        pre_eval_diagnostics_from_scanner:, synthesized_namespaces_snapshot:,
                        quarantined_signatures_snapshot:, env_build_failure_snapshot:,
-                       conformance_results_snapshot:)
+                       definition_build_failures_snapshot:, conformance_results_snapshot:)
           @configuration = configuration
           @rbs_extended_reporter = rbs_extended_reporter
           @boundary_cross_reporter = boundary_cross_reporter
@@ -55,6 +58,7 @@ module Rigor
           @synthesized_namespaces_snapshot_reader = synthesized_namespaces_snapshot
           @quarantined_signatures_snapshot_reader = quarantined_signatures_snapshot
           @env_build_failure_snapshot_reader = env_build_failure_snapshot
+          @definition_build_failures_snapshot_reader = definition_build_failures_snapshot
           @conformance_results_snapshot_reader = conformance_results_snapshot
         end
 
@@ -351,6 +355,32 @@ module Rigor
           [build_rbs_environment_build_failed_diagnostic(failure)]
         end
 
+        # Issue #696 — the third rung of the same ladder, between its two neighbours by consequence: a
+        # QUARANTINED file removes what one FILE declared, this removes what one CLASS declared, an
+        # ENV-BUILD failure removes everything. `RBS::DefinitionBuilder` raising for a class (typically
+        # `DuplicatedMethodDefinitionError`: two signature sources declaring the same method, e.g. a project
+        # `sig/` carrying a vendored COPY of a bundled plugin's `.rbs`) leaves the class KNOWN but with no
+        # method surface, so every call on it — real methods and typos alike — reads `Dynamic[top]`. When
+        # the collision is on a class others inherit, the whole bundled type universe goes with it: the
+        # observed shape is thousands of stderr warnings, ZERO diagnostics, and exit 0.
+        #
+        # Not "drop the class to genuinely-unknown" instead. That also removes diagnostics, so it is not
+        # louder; it changes `Dynamic[top]` semantics for every rule that consults `class_known?`; and
+        # `class_known?` reads {Environment::RbsLoader#known_class_names_set}, a different table from the
+        # definition builder, so it would need a new "known but unbuildable" state regardless. The failure
+        # is made REPORTABLE; the class is not made invisible.
+        #
+        # Authored `:warning`, not `:error`, for the same reason as both neighbours: the collision is
+        # typically between the user's `sig/` and Rigor's OWN bundled RBS, so an `:error` default would let
+        # a Rigor release turn a green build red with no user change (ADR-5 / AGENTS.md § FP discipline).
+        # The `reject-unparseable-signatures` bleeding-edge feature promotes it to `:error`.
+        def rbs_definition_build_failed_diagnostics
+          failures = definition_build_failures_snapshot
+          return [] if failures.nil? || failures.empty?
+
+          [build_rbs_definition_build_failed_diagnostic(failures)]
+        end
+
         def rbs_synthesized_namespace_diagnostics
           synthesized = synthesized_namespaces_snapshot
           return [] if synthesized.nil? || synthesized.empty?
@@ -462,6 +492,64 @@ module Rigor
           )
         end
 
+        # Issue #696. One diagnostic per RUN, not per class: a collision on a widely-inherited class fails
+        # every descendant, and 2,709 rows saying the same thing about one `.rbs` line is noise, not
+        # visibility.
+        #
+        # The failed-class list alone is not actionable, and that is what the "First failure" clause is for.
+        # A duplicate on `::Object#blank?` fails `String`, `Integer`, `Array` and 1,333 more — every name in
+        # that list is a DESCENDANT, and none of them is where the fix goes. The member comes off the error
+        # object rather than out of its message ({RbsLoader#definition_build_member}), so it names the
+        # culprit and reads the same on a cache hit, where every `RBS::Location` has been dumped to a
+        # sentinel. The error class is attributed to that first failure explicitly rather than to all of
+        # them: the per-class memo keeps only the first reason, and one run can mix error classes.
+        def build_rbs_definition_build_failed_diagnostic(failures)
+          sample_size = 5
+          files = failures.flat_map { |failure| Array(failure[3]) }.uniq.map { |name| relative_signature_path(name) }
+          Diagnostic.new(
+            path: ".rigor.yml",
+            line: 1,
+            column: 1,
+            message: "#{failures.size} RBS class definition(s) failed to build: " \
+                     "#{sampled(failures.map(&:first), sample_size)}." \
+                     "#{first_failure_clause(failures.first)}#{conflicting_files_clause(files, sample_size)} " \
+                     "Rigor still treats each class as KNOWN, so calls into it — real methods and typos " \
+                     "alike — silently read `Dynamic[top]` instead of resolving, and this run is quieter " \
+                     "than it should be rather than cleaner. Two signature sources declare the same " \
+                     "member; remove the duplicate declaration (`rbs validate`) to restore type coverage.",
+            severity: :warning,
+            rule: "rbs.coverage.definition-build-failed",
+            source_family: :builtin
+          )
+        end
+
+        # `[class_name, error_class, member, buffers]`. The member is nil for the error classes that carry no
+        # name at all (`RecursiveAncestorError`), and the clause then names the error class alone rather than
+        # inventing a member.
+        def first_failure_clause(failure)
+          _, error_class, member, = failure
+          return " First failure: #{error_class}." if member.nil? || member.empty?
+
+          " First failure: #{error_class} on `#{member}`."
+        end
+
+        # Identical on a cache HIT: the ADR-54 env cache drops location POSITIONS but keeps each buffer's
+        # NAME, so a warm run names the same files a cold one does. Where a name is absent anyway, the
+        # reconstructed {RbsLoader::CACHED_LOCATION_BUFFER_NAME} sentinel is filtered out and the clause is
+        # omitted, rather than naming `<cached>` as if it were a path.
+        def conflicting_files_clause(files, sample_size)
+          return "" if files.empty?
+
+          " Conflicting signature file(s): #{sampled(files, sample_size)}."
+        end
+
+        # "a, b, c, and N more" — the sampling shape every `rbs.coverage.*` message above uses.
+        def sampled(names, sample_size)
+          sample = names.first(sample_size)
+          suffix = names.size > sample_size ? ", and #{names.size - sample_size} more" : ""
+          "#{sample.join(', ')}#{suffix}"
+        end
+
         # The absolute path is what the loader records; the user thinks in project-relative terms.
         def relative_signature_path(path)
           root = "#{Dir.pwd}#{File::SEPARATOR}"
@@ -684,6 +772,10 @@ module Rigor
           @env_build_failure_snapshot_reader.call
         end
 
+        def definition_build_failures_snapshot
+          @definition_build_failures_snapshot_reader.call
+        end
+
         def conformance_results_snapshot
           @conformance_results_snapshot_reader.call
         end