rigortype 0.4.2 → 0.4.3

data/lib/rigor/analysis/incremental_session.rb

@@ -38,7 +38,7 @@ module Rigor
       # gate) can report what was re-analyzed versus served from cache. `added` / `removed` carry the
       # structural delta so {#run_incremental} (ADR-87 WD3) can recognise a zero-change recheck and skip the
       # unconditional snapshot rewrite.
-      Recheck = Data.define(:diagnostics, :changed, :added, :removed, :affected, :reused) do
+      Recheck = Data.define(:diagnostics, :changed, :added, :removed, :affected, :reused, :templates) do
         # A recheck that changed, added, and removed nothing — the session state is byte-equivalent to the
         # snapshot that was restored, so persisting it again would only rewrite identical bytes.
         def no_change?
@@ -68,9 +68,14 @@ module Rigor
       #   `--verify-incremental` gate use) keeps the sequential recording path bit-for-bit unchanged. The fork
       #   pool records each worker's cross-file reads and marshals them back (PoolCoordinator), so the
       #   dependency graph a pooled recheck rebuilds equals the sequential one.
-      def initialize(configuration:, paths: nil, environment: nil, cache_store: nil, plugin_requirer: nil,
-                     workers: 0, buffer: nil)
+      def initialize(configuration:, paths: nil, environment: nil, cache_store: nil, plugin_requirer: nil, # rubocop:disable Metrics/ParameterLists,Metrics/AbcSize,Metrics/MethodLength
+                     workers: 0, buffer: nil, explain: false, on_file_indexed: nil)
         @configuration = configuration
+        # ADR-113 WD2 — `rigor lens`: {#force_targets=} names files a {#recheck} analyses whether or not they changed,
+        # in this process, so `on_file_indexed` (see {Runner}) sees their seeded index. Neither moves a diagnostic:
+        # a forced file re-analyses under the same seeds its cached rows were computed with.
+        @force_targets = Set.new
+        @on_file_indexed = on_file_indexed
         @paths = paths
         # Editor mode option B (#146) — the in-flight buffer, threaded into every internal Runner so the
         # pre-passes and the closure re-analysis read the editor's bytes at the logical path. A session
@@ -81,6 +86,7 @@ module Rigor
         @cache_store = cache_store
         @plugin_requirer = plugin_requirer
         @workers = workers
+        @explain = explain # #1533: threaded into every Runner; keys the snapshot, and no slot is written
         # 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 = {}
@@ -122,12 +128,31 @@ module Rigor
         # banner + `--cache-stats`) reads after `#run_incremental`. `@last_runner` is the analysis runner the
         # post-hoc fingerprint reads from; `@plugin_fact_reusable` is the computed decision object.
         @plugin_fact_digest = nil
-        @opaque_plugin_ids = [].freeze
+        @opaque_reasons = {}.freeze
+        @fact_store_unreadable = false
         @fact_surface_invalidated = false
         @last_runner = nil
         @plugin_fact_reusable = nil
       end
 
+      # ADR-113 WD2 — the paths (as {#project_files} spells them) every later {#recheck} analyses in this process.
+      def force_targets=(paths)
+        @force_targets = paths.to_set
+      end
+
+      # The project files a run of this session analyses, as the runner expands the configured paths.
+      def project_files
+        current_files
+      end
+
+      # The per-file discovery bundles of the last run, keyed by path (ADR-85 WD2).
+      attr_reader :seed_bundles
+
+      # The project files `path`'s analysis read from at the last run that analysed it (ADR-46 slice 1).
+      def dependency_sources(path)
+        @sources.fetch(path, Set.new)
+      end
+
       # The project files analyzed at the last baseline / recheck — the set a verify pass partitions and the
       # merge subtracts the affected closure from.
       def analyzed_files
@@ -206,13 +231,13 @@ 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)
-        analyze_set = affected & current
-        reused = (current & previous) - affected.to_a
+        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,
+                              param_inferred_types: fresh_params, **forced_target_options(forced),
                               restored_run_level_rows: @run_level_rows,
                               served_per_file_diagnostics: @cache.slice(*reused))
         merged = run_runner(runner).diagnostics
@@ -220,7 +245,8 @@ module Rigor
         absorb(runner, current, analyze_set, removed)
         @param_table = fresh_params
         Recheck.new(diagnostics: merged, changed: changed.to_set, added: added.to_set,
-                    removed: removed.to_set, affected: affected, reused: reused.to_set)
+                    removed: removed.to_set, affected: affected, reused: reused.to_set,
+                    templates: runner.template_unit_paths.size)
       end
 
       # Editor mode option B (#146) — a whole-project recheck with the editor's buffer substituted for one
@@ -480,6 +506,7 @@ module Rigor
       # to. Every soundness gate below — the fingerprint, the ADR-88 fact surface — is unchanged, so the
       # decision to reuse is made identically whether or not the result is saved.
       def run_incremental(snapshot:, fingerprint:, persist: true)
+        @last_recheck = nil # #1526 — set only by a warm recheck, see {#last_recheck}
         # ADR-87 WD1 — install the per-run digest table + recording instant + strict flag for the whole
         # invocation so change-detection's stat-then-digest freshness (`#pack_digest` / `#stat_fresh?`) honours
         # `cache.validation: digest` (and `RIGOR_STRICT_VALIDATION`, which the env-only path already sees) and
@@ -508,7 +535,7 @@ module Rigor
             adopt_plugin_fact_fingerprint
             fact_reusable = @plugin_fact_reusable.reusable_against?(restored.plugin_fact_digest)
             if fact_reusable && effects_reusable && !source_rbs_unverified?(result)
-              diagnostics = result.diagnostics
+              diagnostics = keep_recheck(result)
               warm = true
               # ADR-87 WD3 — a warm recheck that changed nothing leaves the session state byte-equivalent to the
               # snapshot it restored, so skip the unconditional rewrite (209ms + 2 MB on gitlab per null recheck).
@@ -539,9 +566,36 @@ module Rigor
 
       # ADR-88 WD1 — reporting hooks the CLI reads after {#run_incremental}. `fact_surface_invalidated?` is true
       # when a valid snapshot was dropped for a fact-surface reason (a plugin sig/catalog edit, or an opaque
-      # plugin) rather than a cold miss. `opaque_plugin_ids` names the contributing-but-surfaceless plugins that
-      # force a full run every invocation.
-      attr_reader :opaque_plugin_ids
+      # plugin) rather than a cold miss. `opaque_reasons` maps each plugin that forces a full run every invocation
+      # to its {PluginFactFingerprint::OpaqueReason}.
+      attr_reader :opaque_reasons
+
+      # #1526 — the {Recheck} of the last {#run_incremental}, or nil unless that run answered warm. A baseline
+      # (cold, or a re-baseline after a fact-surface, effects or source-RBS reason) has no recheck to report.
+      # The diagnostics are not kept: a long-lived session (the LSP) would otherwise retain every merged list.
+      attr_reader :last_recheck
+
+      # Records the warm recheck's sets for {#last_recheck} and hands back its diagnostics.
+      def keep_recheck(result)
+        @last_recheck = result.with(diagnostics: [])
+        result.diagnostics
+      end
+      private :keep_recheck
+
+      # The opaque plugin ids, sorted (the keys of {#opaque_reasons}).
+      def opaque_plugin_ids
+        @opaque_reasons.keys
+      end
+
+      # True when the fact store could not be read, so no single plugin is named (see {PluginFactFingerprint::Result}).
+      def fact_store_unreadable?
+        @fact_store_unreadable
+      end
+
+      # True when the fact surface forces a full run: some plugin is opaque, or the fact store is unreadable.
+      def opaque_fact_surface?
+        !@opaque_reasons.empty? || @fact_store_unreadable
+      end
 
       def fact_surface_invalidated?
         @fact_surface_invalidated
@@ -566,7 +620,8 @@ module Rigor
         registry = prepared_plugin_registry
         fact = compute_plugin_fact_fingerprint(registry)
         @plugin_fact_digest = fact.digest
-        @opaque_plugin_ids = fact.opaque_plugin_ids
+        @opaque_reasons = fact.opaque_reasons
+        @fact_store_unreadable = fact.fact_store_unreadable
         @plugin_fact_reusable = fact
         @seed_bundles = source_rbs_gate.verify(registry, @seed_bundles)
       end
@@ -596,10 +651,10 @@ module Rigor
 
       # ADR-88 WD1 — the plugin fact-surface fingerprint for this invocation. For a SEQUENTIAL run it is read
       # post-hoc from the analysis runner's already-prepared registry (no second `#prepare`, producers already
-      # validated during analysis). A POOLED run's main process skips `#prepare`, so its registry carries no
-      # published facts — there it falls back to the always-sequential probe. Both paths compute the identical
-      # digest for a given fact surface, so the reuse decision is worker-count-independent (the parity spec
-      # asserts this).
+      # validated during analysis). A POOLED run's main process does not run `#prepare` on it (its workers do),
+      # so its registry carries no published facts — there it falls back to the always-sequential probe. Both
+      # paths compute the identical digest for a given fact surface, so the reuse decision is worker-count-independent
+      # (the parity spec asserts this).
       def compute_plugin_fact_fingerprint(registry = prepared_plugin_registry)
         PluginFactFingerprint.from_registry(registry)
       end
@@ -710,7 +765,8 @@ module Rigor
         return nil if fingerprint.nil? || @cache_store.nil? || @cache_store.read_only? || !@buffer.nil?
         # Known before the run: none of these can be written afterwards, so the stamp and the recomputed
         # fingerprint would be spent for nothing.
-        return nil unless @workers.zero? && !@configuration.effects_enabled?
+        # `WriteGuard.start` would also refuse (it recomputes the fingerprint without `explain:`); say so here.
+        return nil unless @workers.zero? && !@configuration.effects_enabled? && !@explain
 
         IncrementalRunSlot::WriteGuard.start(
           configuration: @configuration, roots: @paths || @configuration.paths, cache_root: @cache_store.root,
@@ -724,7 +780,7 @@ module Rigor
       # cold, not the warm run the probe stands in for.
       def run_slot_writable?
         !@cache_store.nil? && !@cache_store.read_only? && @buffer.nil? && @workers.zero? &&
-          !@configuration.effects_enabled? && @opaque_plugin_ids.empty? && !@last_runner.nil?
+          !@configuration.effects_enabled? && !@explain && !opaque_fact_surface? && !@last_runner.nil?
       end
 
       def start_chain(rows)
@@ -1127,8 +1183,8 @@ module Rigor
         return {} if index.nil?
 
         result = Hash.new { |hash, key| hash[key] = Set.new }
-        index[:class_sources].each do |class_name, files|
-          files.each { |file| result[file] << class_name }
+        [index[:class_sources], index[:singleton_class_sources] || {}].each do |sources|
+          sources.each { |class_name, files| files.each { |file| result[file] << class_name } }
         end
         Incremental.add_superclass_edges(result, index[:class_sources], index[:superclasses])
         result.transform_values(&:freeze).freeze
@@ -1269,10 +1325,21 @@ module Rigor
         Runner.new(
           configuration: @configuration, cache_store: @cache_store, environment: @environment,
           plugin_requirer: @plugin_requirer, seed_bundles: @seed_bundles, collect_seed_bundles: true,
-          workers: @workers, buffer: @buffer, **
+          workers: @workers, buffer: @buffer, explain: @explain, on_file_indexed: @on_file_indexed, **
         )
       end
 
+      # The forced targets present in `current`, and the recheck's analyse set with them joined to the closure.
+      def forced_analyze_set(affected, current)
+        forced = @force_targets & current.to_set
+        [forced, (affected | forced) & current]
+      end
+
+      # A recheck that forces targets analyses in this process, so the index callback reaches them.
+      def forced_target_options(forced)
+        forced.empty? ? {} : { workers: 0 }
+      end
+
       # Run the runner over the session's explicit paths (or, when none were given, the configuration's
       # `paths:` via `Runner#run`'s default).
       def run_runner(runner)

data/lib/rigor/analysis/path_expansion.rb

@@ -14,10 +14,10 @@ module Rigor
       module_function
 
       # The `.rb` files an ordinary (non-buffer) check over `paths` would analyze.
-      def ruby_files(paths, exclude_patterns)
+      def ruby_files(paths, exclude_patterns, base: Dir.pwd)
         Array(paths).flat_map do |path|
           if File.directory?(path)
-            directory_files(path, exclude_patterns)
+            directory_files(path, exclude_patterns, base: base)
           elsif File.file?(path) && path.end_with?(".rb")
             [path]
           else
@@ -26,16 +26,72 @@ module Rigor
         end
       end
 
-      def directory_files(dir, exclude_patterns)
-        reject_excluded(Dir.glob(File.join(dir, RUBY_GLOB)), exclude_patterns)
+      def directory_files(dir, exclude_patterns, base: Dir.pwd)
+        reject_excluded(Dir.glob(File.join(dir, RUBY_GLOB)), exclude_patterns, base: base)
       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)
+      #
+      # #1576 — a RELATIVE pattern (a leading `./` is ignored) is matched against the file's path relative to
+      # `base` (the config file's directory, or the working directory with no config), so the same file is
+      # excluded whether `paths:` (absolute) or an argument (relative) named it.
+      #
+      # Two spellings are tried. The LOGICAL one (the path as given, against the logical base) counts only when
+      # the file lies inside the base; it is what lets a symlinked `lib` match `lib/gen/**`. The REALPATH one
+      # (realpath of the file against realpath of the base) is the only one used for a file outside the base, and
+      # it also catches a base or file spelled through a different symlink root (macOS `/tmp` vs `/private/tmp`).
+      # Neither shows a directory name above the base: a file outside it comes out as `../…`, so `**/tmp/**`
+      # cannot exclude a project merely located under a `tmp/`, while `**/vendor/bundle/**` still reaches
+      # `../other/vendor/bundle/x.rb`. The pattern is also tried against `/<relative>`, because without
+      # `FNM_PATHNAME` the unanchored `**/tmp/**` needs a leading `/` to match a top-level `tmp/x.rb` (and `*`
+      # never matches a leading `.`, as in `../other`). A pattern starting with `.` therefore also matches files
+      # outside the base. An ABSOLUTE pattern is matched only against the absolute path (logical, then real).
+      def reject_excluded(file_list, exclude_patterns, base: Dir.pwd)
         return file_list if exclude_patterns.empty?
 
-        file_list.reject { |path| exclude_patterns.any? { |pattern| File.fnmatch?(pattern, path) } }
+        absolute_patterns, relative_patterns = exclude_patterns.partition { |pattern| pattern.start_with?("/") }
+        relative_patterns = relative_patterns.map { |pattern| pattern.sub(%r{\A(?:\./+)+}, "") }
+        logical_base = File.absolute_path(base)
+        context = { cwd: Dir.pwd, base: logical_base, real_base: real_directory(logical_base), real_dirs: {} }
+        file_list.reject { |path| excluded?(path, absolute_patterns, relative_patterns, context) }
+      end
+
+      def excluded?(path, absolute_patterns, relative_patterns, context)
+        logical = File.absolute_path(path, context.fetch(:cwd))
+        base = context.fetch(:base)
+        inside = logical.start_with?("#{base}/")
+        return true if inside && matches_relative?(relative_patterns, logical.byteslice((base.bytesize + 1)..))
+        return true if absolute_patterns.any? { |pattern| File.fnmatch?(pattern, logical) }
+
+        real = real_file(logical, context.fetch(:real_dirs))
+        return false if real == logical && inside && context.fetch(:real_base) == base
+
+        matches_relative?(relative_patterns, relative_path(real, context.fetch(:real_base))) ||
+          (real != logical && absolute_patterns.any? { |pattern| File.fnmatch?(pattern, real) })
+      end
+
+      def relative_path(absolute, base)
+        return absolute.byteslice((base.bytesize + 1)..) if absolute.start_with?("#{base}/")
+
+        Pathname.new(absolute).relative_path_from(Pathname.new(base)).to_s
+      end
+
+      def matches_relative?(patterns, relative)
+        candidates = [relative, "/#{relative}"]
+        patterns.any? { |pattern| candidates.any? { |candidate| File.fnmatch?(pattern, candidate) } }
+      end
+
+      def real_directory(dir)
+        File.realpath(dir)
+      rescue SystemCallError
+        File.absolute_path(dir)
+      end
+
+      def real_file(absolute, real_dirs)
+        dir = File.dirname(absolute)
+        real_dir = real_dirs[dir] ||= real_directory(dir)
+        File.join(real_dir, File.basename(absolute))
       end
     end
   end

data/lib/rigor/analysis/plugin_fact_fingerprint.rb

@@ -36,12 +36,55 @@ module Rigor
     # 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
+      # Why one plugin is opaque to the fingerprint. `kind` is one of:
+      #   :no_surface    the plugin contributes types and declares no fact, producer or hook;
+      #   :undigestible  a value it declares or publishes cannot be digested (a Proc, an IO, ...);
+      #   :raised        the hook or a producer raised while its value was being read.
+      # `input` names the input: `"producer worker_index"`, `"fact callback"`, `"hook incremental_state_fingerprint"`.
+      # `class_name` is the class of the value that could not be digested, or of the exception raised; an anonymous
+      # class reads "anonymous Class", and nil means the class itself could not be read.
+      OpaqueReason = Data.define(:kind, :input, :class_name) do
+        # The clause a note states about plugin `id`. The note groups :no_surface plugins itself, so this is only
+        # called for :undigestible and :raised reasons.
+        def describe(id)
+          return "plugin #{id}'s #{input} raised #{class_name}" if kind == :raised
+
+          "plugin #{id}'s #{input} has a value the incremental fingerprint cannot digest#{parenthesised_class}"
+        end
+
+        # The same verdict without the plugin id, for a `--cache-stats` line that already names it.
+        def summary
+          return "no incremental fingerprint surface" if kind == :no_surface
+          return "#{input} raised #{class_name}" if kind == :raised
+
+          "#{input} has a value the incremental fingerprint cannot digest#{parenthesised_class}"
+        end
+
+        private
+
+        def parenthesised_class
+          return "" if class_name.nil?
+
+          " (#{article(class_name)} #{class_name})"
+        end
+
+        def article(word)
+          word.match?(/\A[aeiou]/i) ? "an" : "a"
+        end
+      end
+
+      # `digest` is nil when no plugins are loaded — the fast path (nothing to fingerprint), which reuses freely.
+      # `opaque_reasons` maps each opaque plugin id to its {OpaqueReason}, sorted by id. `fact_store_unreadable` is
+      # true when the fact store could not be read at all: no single plugin is to blame, so no reason names one.
+      # Either makes the snapshot un-reusable.
+      Result = Data.define(:digest, :opaque_reasons, :fact_store_unreadable) do
+        # The opaque plugin ids, sorted (the keys of {#opaque_reasons}).
+        def opaque_plugin_ids
+          opaque_reasons.keys
+        end
+
         def opaque?
-          !opaque_plugin_ids.empty?
+          fact_store_unreadable || !opaque_reasons.empty?
         end
 
         # A warm recheck may reuse the snapshot only when this run is not opaque and its fact-surface digest
@@ -97,16 +140,20 @@ module Rigor
       end
 
       def digest_registry(registry)
-        return Result.new(digest: nil, opaque_plugin_ids: [].freeze) if registry.nil? || registry.empty?
+        empty = registry.nil? || registry.empty?
+        return Result.new(digest: nil, opaque_reasons: {}.freeze, fact_store_unreadable: false) if empty
 
-        opaque = []
-        facts_by_plugin = facts_by_plugin(registry, opaque)
-        parts = fact_parts(facts_by_plugin)
-        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.
+        reasons = {}
+        facts, store_unreadable = facts_by_plugin(registry, reasons)
+        parts = fact_parts(facts)
+        registry.plugins.each { |plugin| collect_plugin_parts(plugin, facts, parts, reasons) }
+        # Sort the parts so the digest is independent of plugin registration / iteration order. An unreadable
+        # store names no plugin: the snapshot is opaque as a whole, and per-plugin reasons would blame plugins
+        # whose facts were simply not read.
         Result.new(
           digest: Digest::SHA256.hexdigest(parts.sort.join("\x00")),
-          opaque_plugin_ids: opaque.uniq.freeze
+          opaque_reasons: (store_unreadable ? {} : reasons.sort.to_h).freeze,
+          fact_store_unreadable: store_unreadable
         )
       end
 
@@ -119,23 +166,25 @@ module Rigor
 
       # 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)
+      def collect_plugin_parts(plugin, facts_by_plugin, parts, reasons)
         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)
+        has_producers = collect_producer_parts(plugin, id, parts, reasons)
+        has_hook = collect_hook_part(plugin, id, parts, reasons)
         surface = has_facts || has_producers || has_hook
-        opaque << id if !surface && contributes_types?(plugin)
+        return if surface || !contributes_types?(plugin)
+
+        mark_opaque(reasons, id, OpaqueReason.new(kind: :no_surface, input: nil, class_name: nil))
       end
 
-      # `{ plugin_id => ["name=digest", ...] }` for every ADR-9 published fact (channel a). A plugin that
-      # published nothing does not appear.
+      # `[{ plugin_id => ["name=digest", ...] }, unreadable]` for every ADR-9 published fact (channel a). A plugin
+      # that published nothing does not appear.
       #
-      # A fact the fingerprint cannot digest is an input it cannot see, so its publisher is opaque, whether or
-      # not the publisher contributes a type itself: other plugins read its facts. A fact store that cannot be
-      # read at all makes every plugin opaque. Both force the full run; dropping the facts instead would let a
-      # plugin with another surface reuse a snapshot its facts no longer match.
-      def facts_by_plugin(registry, opaque)
+      # A fact the fingerprint cannot digest is an input it cannot see, so its publisher is opaque, whether or not
+      # the publisher contributes a type itself: other plugins read its facts. A fact store that cannot be read at
+      # all makes the whole surface opaque. Both force the full run; dropping the facts instead would let a plugin
+      # with another surface reuse a snapshot its facts no longer match.
+      def facts_by_plugin(registry, reasons)
         result = Hash.new { |hash, key| hash[key] = [] }
         fact_store = registry.plugins.first&.services&.fact_store
         fact_store&.each_fact do |fact|
@@ -143,13 +192,12 @@ module Rigor
           begin
             result[plugin_id] << "#{fact.name}=#{digest_value(fact.value)}"
           rescue StandardError
-            opaque << plugin_id
+            mark_opaque(reasons, plugin_id, undigestible("fact #{fact.name}", fact.value))
           end
         end
-        result
+        [result, false]
       rescue StandardError
-        registry.plugins.each { |plugin| opaque << safe_id(plugin) }
-        Hash.new { |hash, key| hash[key] = [] }
+        [Hash.new { |hash, key| hash[key] = [] }, true]
       end
 
       # Channel (b): a stable signature of every declared producer's VALUE — a digest of the producer's own
@@ -161,28 +209,67 @@ module Rigor
       # 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-next Naming/PredicateMethod -- reports has-surface AND appends parts (a side-effecting builder)
-      def collect_producer_parts(plugin, id, parts, opaque)
+      def collect_producer_parts(plugin, id, parts, reasons)
         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
+          input = "producer #{producer_id}"
+          begin
+            value = plugin.producer_value(producer_id)
+          rescue StandardError => e
+            mark_opaque(reasons, id, raised(input, e))
+            next
+          end
+          digest_part(parts, reasons, id, input, "prod\x1f#{id}\x1f#{producer_id}", value)
         end
         true
       end
 
-      # 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)
+      # Channel (c): the optional {Plugin::Base#incremental_state_fingerprint} hook. Returns true when the plugin
+      # defines it (it has a surface).
+      # rubocop:disable-next Naming/PredicateMethod -- reports has-surface AND appends parts (a side-effecting builder)
+      def collect_hook_part(plugin, id, parts, reasons)
         return false unless plugin.respond_to?(:incremental_state_fingerprint)
 
-        parts << "hook\x1f#{id}\x1f#{digest_value(plugin.incremental_state_fingerprint)}"
+        input = "hook incremental_state_fingerprint"
+        begin
+          value = plugin.incremental_state_fingerprint
+        rescue StandardError => e
+          mark_opaque(reasons, id, raised(input, e))
+          return true
+        end
+        digest_part(parts, reasons, id, input, "hook\x1f#{id}", value)
         true
+      end
+
+      # Appends `prefix\x1f<digest of value>` to `parts`, or marks the plugin opaque when the value cannot be digested.
+      def digest_part(parts, reasons, id, input, prefix, value)
+        parts << "#{prefix}\x1f#{digest_value(value)}"
       rescue StandardError
-        opaque << id
-        true
+        mark_opaque(reasons, id, undigestible(input, value))
+      end
+
+      # The first reason a plugin is found opaque wins: one reason per plugin id, as {Result#opaque_reasons} states.
+      def mark_opaque(reasons, id, reason)
+        reasons[id] ||= reason
+      end
+
+      def undigestible(input, value)
+        OpaqueReason.new(kind: :undigestible, input: input, class_name: class_name_of(value))
+      end
+
+      def raised(input, error)
+        OpaqueReason.new(kind: :raised, input: input, class_name: class_name_of(error))
+      end
+
+      # The name of `object`'s class, "anonymous Class" for an anonymous one, or nil when even the class is unreadable
+      # (a BasicObject has no `#class`).
+      def class_name_of(object)
+        klass = object.class
+        klass.name || "anonymous Class"
+      rescue StandardError
+        nil
       end
 
       # A digest of a fact / producer / hook value that depends on the value alone (issue #1574). A producer's