rigortype 0.3.8 → 0.4.0

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../check_rules/rule_ids"
 require_relative "../crash_signature"
 require_relative "../diagnostic"
 require_relative "../severity_stamp"
@@ -22,36 +23,39 @@ module Rigor
       # end-of-pass snapshots) is read through injected reader procs so this collaborator never calls back
       # into the {Runner} and the read happens at the exact point in the run the original inline read did.
       class DiagnosticAggregator # rubocop:disable Metrics/ClassLength
-        # @param configuration [Rigor::Configuration]
-        # @param rbs_extended_reporter [RbsExtended::Reporter]
-        # @param boundary_cross_reporter [DependencySourceInference::BoundaryCrossReporter]
-        # @param source_rbs_synthesis_reporter [Plugin::SourceRbsSynthesisReporter]
-        # @param plugin_registry [#call] reader returning the current {Plugin::Registry} (varies per run).
-        # @param dependency_source_index [#call] reader returning the current
+        # @param plugin_registry — reader returning the current {Plugin::Registry} (varies per run).
+        # @param dependency_source_index — reader returning the current
         #   {DependencySourceInference::Index}.
-        # @param pool_mode [#call] reader returning the pool-mode flag.
-        # @param cached_plugin_prepare_diagnostics [#call] reader returning the prepare-diagnostic snapshot.
-        # @param pre_eval_diagnostics_from_scanner [#call] reader returning the pre-eval scanner diagnostics.
-        # @param synthesized_namespaces_snapshot [#call] reader.
-        # @param quarantined_signatures_snapshot [#call] reader returning the `signature_paths:` files skipped
+        # @param pool_mode — reader returning the pool-mode flag.
+        # @param cached_plugin_prepare_diagnostics — reader returning the prepare-diagnostic snapshot.
+        # @param pre_eval_diagnostics_from_scanner — reader returning the pre-eval scanner diagnostics.
+        # @param synthesized_namespaces_snapshot — reader.
+        # @param quarantined_signatures_snapshot — reader returning the `signature_paths:` files skipped
         #   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
+        # @param signature_standdowns_snapshot — reader returning the plugin-contributed signature files
+        #   that stood down against a colliding generic arity (#610), as
+        #   `[path, class_name, existing_arity, incoming_arity, existing_file]` tuples. Defaults to none so
+        #   a caller that snapshots nothing of the kind need not say so.
+        # @param env_build_failure_snapshot — 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
+        # @param definition_build_failures_snapshot — 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 hkt_scan_failure_snapshot [#call] issue #784 — reader returning the `[error_class_name,
+        #   conflicting_buffer_names, unresolved_type_name_detail]` tuples (issue #997 added the fifth
+        #   element — `[token, location, refinement_hint]`, `nil` unless `error_class` is
+        #   `RBS::NoTypeFoundError`). Empty for a healthy sig set.
+        # @param hkt_scan_failure_snapshot — issue #784 — reader returning the `[error_class_name,
         #   first_message_line, raw_frame_or_nil, stage]` tuple whichever stage of the HKT-registry build
         #   raised, or nil when both built (or were never demanded). `stage` is `:scan` (the RBS `type`-alias
         #   scan) or `:overlay` (the plugin-manifest aggregation, #791), and picks the row's wording.
-        # @param conformance_results_snapshot [#call] reader.
+        # @param conformance_results_snapshot — 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:,
                        definition_build_failures_snapshot:, hkt_scan_failure_snapshot:,
-                       conformance_results_snapshot:)
+                       conformance_results_snapshot:, signature_standdowns_snapshot: -> { [] },
+                       pooled_run_disclosures: -> { [] })
           @configuration = configuration
           @rbs_extended_reporter = rbs_extended_reporter
           @boundary_cross_reporter = boundary_cross_reporter
@@ -63,10 +67,14 @@ module Rigor
           @pre_eval_diagnostics_from_scanner_reader = pre_eval_diagnostics_from_scanner
           @synthesized_namespaces_snapshot_reader = synthesized_namespaces_snapshot
           @quarantined_signatures_snapshot_reader = quarantined_signatures_snapshot
+          @signature_standdowns_snapshot_reader = signature_standdowns_snapshot
           @env_build_failure_snapshot_reader = env_build_failure_snapshot
           @definition_build_failures_snapshot_reader = definition_build_failures_snapshot
           @hkt_scan_failure_snapshot_reader = hkt_scan_failure_snapshot
           @conformance_results_snapshot_reader = conformance_results_snapshot
+          # Issue #1051 — reader for the pool coordinator's de-duplicated run-scoped disclosure table.
+          # Empty on a sequential run, where `plugin_registry`'s own instances are the ones that registered.
+          @pooled_run_disclosures_reader = pooled_run_disclosures
         end
 
         # Pre-file diagnostic streams that fire once per run rather than per analyzed file: plugin load /
@@ -416,12 +424,33 @@ module Rigor
           [build_rbs_synthesized_namespace_diagnostic(synthesized)]
         end
 
+        # Issue #610 — the outcome that AVOIDED `rbs.coverage.definition-build-failed`'s rung: a signature
+        # file a loaded plugin contributes re-declared a class another loaded source (typically an `rbs
+        # collection install`) already declares at a DIFFERENT generic arity, so the plugin's file stood
+        # down rather than fail the class's definition build. One `:info` per file: the user is told what
+        # typing they are not getting and why, and — unlike the quarantine row this file used to be
+        # misreported as — is not sent to remove a declaration the plugin owns.
+        def rbs_plugin_signature_stood_down_diagnostics
+          standdowns = signature_standdowns_snapshot
+          return [] if standdowns.nil? || standdowns.empty?
+
+          standdowns.map { |entry| build_rbs_plugin_signature_stood_down_diagnostic(entry) }
+        end
+
+        # The two `:info` notices that close the `rbs.coverage.*` ladder, in this order: the namespace
+        # synthesis first, then the stand-down (#610) — the outcome that AVOIDED a definition-build failure
+        # and so the quietest row on it. One method so the runner's assembly reads them as one slot.
+        def rbs_coverage_notice_diagnostics
+          rbs_synthesized_namespace_diagnostics + rbs_plugin_signature_stood_down_diagnostics
+        end
+
         # Maps the per-run `rigor:v1:conforms-to` scan results into diagnostics (spec: `rbs-extended.md` §
         # "Explicit conformance directive"). A class that declares `conforms-to _Interface` but is missing
         # a required interface method surfaces as `rbs_extended.unsatisfied-conformance`; an unresolvable
         # interface name surfaces as `dynamic.rbs-extended.unresolved` `:info` (the same fail-soft channel
-        # the other directive parsers use). Empty for a project with no directive, a well-formed
-        # conformance, or a non-sequential pool run (the snapshot mirrors `synthesized_namespaces`).
+        # the other directive parsers use). Empty for a project with no directive or a well-formed
+        # conformance; every analysis path, pooled or degraded, takes the snapshot `synthesized_namespaces`
+        # comes from.
         def conforms_to_diagnostics
           results = conformance_results_snapshot
           return [] if results.nil? || results.empty?
@@ -436,16 +465,28 @@ module Rigor
           when RbsExtended::ConformanceChecker::IncompatibleSignature
             build_incompatible_signature_diagnostic(record)
           else # UnresolvedInterface
-            build_reporter_diagnostic(
-              record.location,
-              rule: "dynamic.rbs-extended.unresolved",
-              message: "`#{record.class_name}` declares `conforms-to #{record.interface_name}` but " \
-                       "interface `#{record.interface_name}` is not loaded. Check for a typo or add " \
-                       "the `sig`/library that declares it to the RBS load path."
-            )
+            build_unresolved_conformance_diagnostic(record)
           end
         end
 
+        # Issue #928 — `:warning`, not the `:info` the other `dynamic.rbs-extended.unresolved` producers
+        # stamp. Those report that an inference fell back; this one reports that an assertion the author
+        # deliberately wrote is checking NOTHING, and the whole point of `conforms-to` is to be checked. It
+        # is not unsolicited either: only a project that wrote the directive can see it. Now that the
+        # capability-role catalog ships, the remaining way to reach this row is a name that does not exist.
+        def build_unresolved_conformance_diagnostic(record)
+          path, line, column = location_fields(record.location)
+          Diagnostic.new(
+            path: path, line: line, column: column,
+            message: "`#{record.class_name}` declares `conforms-to #{record.interface_name}` but " \
+                     "interface `#{record.interface_name}` is not loaded. Check for a typo or add " \
+                     "the `sig`/library that declares it to the RBS load path.",
+            severity: :warning,
+            rule: "dynamic.rbs-extended.unresolved",
+            source_family: :builtin
+          )
+        end
+
         def build_unsatisfied_conformance_diagnostic(record)
           path, line, column = location_fields(record.location)
           Diagnostic.new(
@@ -544,17 +585,58 @@ module Rigor
                      "#{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.",
+                     "than it should be rather than cleaner. #{definition_build_advice(failures.first)}",
             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.
+        # The closing advice follows the FIRST failure's error class: `GenericParameterMismatchError` is two
+        # declarations of one CLASS at different generic arity (#610); `NoTypeFoundError` (issue #997) is
+        # ONE declaration naming a type that does not exist, which "remove the duplicate declaration" sends
+        # its reader after a duplicate that is not there — the fifth tuple element
+        # ({RbsLoader#unresolved_type_name_detail}) is non-nil for exactly that case. Every other error class
+        # (the two duplicated-definition errors, `RecursiveAncestorError`, …) keeps the duplicate-declaration
+        # wording, which is accurate for them.
+        def definition_build_advice(failure)
+          _, error_class, _member, _buffers, unresolved = failure
+          if error_class.to_s.end_with?("GenericParameterMismatchError")
+            "Two signature sources declare the class with a different number of type parameters; make " \
+              "the declarations agree (`rbs validate`) to restore type coverage."
+          elsif unresolved
+            unresolved_type_name_advice(unresolved)
+          else
+            "Two signature sources declare the same member; remove the duplicate declaration " \
+              "(`rbs validate`) to restore type coverage."
+          end
+        end
+
+        # Issue #997 — `unresolved` is {RbsLoader#unresolved_type_name_detail}'s `[token, location,
+        # refinement_hint]`. `refinement_hint` turns the message into a fix: the token is not a typo to
+        # chase down but the start of a Rigor refinement name that is not valid in an RBS type position, and
+        # the reader is told the spelling that IS valid today. Without a hint, the token is named with its
+        # position and the reader is left with the same "not a duplicate" correction plus a typo/missing-load
+        # check — still narrower than the duplicate-declaration wording it replaces.
+        def unresolved_type_name_advice(unresolved)
+          token, location, refinement_hint = unresolved
+          position = location ? " at `#{location}`" : ""
+          if refinement_hint
+            "`#{token}`#{position} does not name a type RBS can resolve; it is the start of the Rigor " \
+              "refinement `#{refinement_hint}`, which is not valid in an RBS type position. Write it as " \
+              "an `%a{rigor:v1:param: name is #{refinement_hint}}` (or `return:` / `assert`) annotation " \
+              "alongside the plain RBS type instead — see docs/manual/16-rbs-extended-annotations.md — " \
+              "to restore type coverage."
+          else
+            "One signature source names `#{token}`#{position}, which is not a type RBS can resolve; fix " \
+              "the typo, or if it names a class, confirm it is loaded (`rbs validate`) to restore type " \
+              "coverage."
+          end
+        end
+
+        # `[class_name, error_class, member, buffers, unresolved_type_name_detail]`. 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?
@@ -665,6 +747,42 @@ module Rigor
           )
         end
 
+        def build_rbs_plugin_signature_stood_down_diagnostic(entry)
+          path, class_name, existing_arity, incoming_arity, existing_file = entry
+          displaced_by = displacing_source_phrase(existing_file)
+          Diagnostic.new(
+            path: ".rigor.yml",
+            line: 1,
+            column: 1,
+            message: "`#{relative_signature_path(path.to_s)}` (a signature file a plugin contributes) declares " \
+                     "`#{class_name.to_s.delete_prefix('::')}` with #{type_parameter_phrase(incoming_arity)}, " \
+                     "but #{displaced_by} already declares it with #{type_parameter_phrase(existing_arity)}. " \
+                     "Two declarations of one class at different generic arity fail its definition build, so " \
+                     "the plugin's file stood down: calls into the class resolve against the other " \
+                     "declaration, and the plugin's element typing for it is unavailable while both are " \
+                     "loaded. Expected when a bundled plugin and an `rbs collection install` both declare " \
+                     "the class; nothing to fix unless you want the plugin's typing back, which needs the " \
+                     "other source to stop declaring the class.",
+            severity: :info,
+            rule: "rbs.coverage.plugin-signature-stood-down",
+            source_family: :builtin
+          )
+        end
+
+        def displacing_source_phrase(existing_file)
+          return "another loaded signature source" if existing_file.nil?
+
+          "`#{relative_signature_path(existing_file.to_s)}`"
+        end
+
+        def type_parameter_phrase(arity)
+          case arity
+          when nil, 0 then "no type parameters"
+          when 1 then "1 type parameter"
+          else "#{arity} type parameters"
+          end
+        end
+
         def build_rbs_coverage_missing_diagnostic(missing)
           sample_size = 5
           sample = missing.first(sample_size).map(&:gem_name)
@@ -722,7 +840,22 @@ module Rigor
             )
           end
 
-          unresolved + lossy + hkt_directive_diagnostics
+          unresolved + lossy + hkt_directive_diagnostics + deprecated_form_diagnostics
+        end
+
+        # ADR-109 WD3 — one row per annotation still written in a spelling the grammar accepts but no
+        # longer displays. The row names the replacement because the deprecation window exists for exactly
+        # this edit, and it stays `:info`: the annotation resolved, the run is as green as it was.
+        def deprecated_form_diagnostics
+          @rbs_extended_reporter.deprecated_forms.map do |entry|
+            build_positioned_reporter_diagnostic(
+              entry,
+              rule: "dynamic.rbs-extended.deprecated-form",
+              message: "`#{entry.payload}` is a deprecated spelling; write `#{entry.replacement}`. The " \
+                       "angle-bracket integer range is accepted for one deprecation window and removed " \
+                       "at the next compatibility break (ADR-109)."
+            )
+          end
         end
 
         # Issue #785 — one row per declined HKT directive. The consequence sentence is the point: the parser
@@ -752,10 +885,29 @@ module Rigor
           return [] if @source_rbs_synthesis_reporter.empty?
 
           @source_rbs_synthesis_reporter.entries.map do |entry|
-            entry.kind == :not_honoured ? not_honoured_diagnostic(entry) : synthesis_failed_diagnostic(entry)
+            case entry.kind
+            when :not_honoured then not_honoured_diagnostic(entry)
+            when :contradiction then contradicting_signature_diagnostic(entry)
+            else synthesis_failed_diagnostic(entry)
+            end
           end
         end
 
+        # ADR-112 WD5 / issue #1075 — a member whose two declarations contradict, or whose refinement is
+        # outside its own declared type. An error in every profile: the false-positive discipline is carried
+        # by the rule's narrow definition of a contradiction, never by the severity (ADR-112 WD5). The message
+        # is composed where the record is read ({Environment.record_member_consistency}), since only there
+        # are both sources' paths at hand.
+        def contradicting_signature_diagnostic(entry)
+          Diagnostic.new(
+            path: entry.path, line: entry.line || 1, column: 1,
+            message: entry.message,
+            severity: :error,
+            rule: CheckRules::RULE_CONTRADICTING_SIGNATURE,
+            source_family: :builtin
+          )
+        end
+
         def synthesis_failed_diagnostic(entry)
           Diagnostic.new(
             path: entry.path, line: 1, column: 1,
@@ -811,6 +963,153 @@ module Rigor
           end
         end
 
+        # Issue #959 — surfaces the {Plugin::IoBoundary} refusal history each loaded plugin accumulated over
+        # the whole run (prepare AND every per-file call: `#io_boundary` is memoised per plugin instance, so
+        # one boundary sees both). `TrustPolicy#allow_read?` stays `File.expand_path`-only per ADR-2 — a
+        # project rooted under a symlink (macOS' `/tmp` → `/private/tmp` is the common case) can have every
+        # plugin read fall outside its own read roots with nothing said about it. One `:info` row per plugin
+        # that hit this, never one per path, naming the count and the first path so the row stays legible on
+        # a plugin that walked a whole out-of-scope subtree.
+        #
+        # Positioned here, in `#pre_file_diagnostics`'s post-analysis sibling list (called from
+        # `Runner#assemble_run_diagnostics`, which only runs on an ADR-45 cache MISS): the refusal history is
+        # a function of the plugin code and the resolved paths for THIS configuration, so it is deterministic
+        # across runs of the same inputs and the row that lands in a miss's cached diagnostics blob is the
+        # row a later warm HIT correctly re-serves — the same regeneration contract every other stream
+        # aggregated in `#pre_file_diagnostics` / `#assemble_run_diagnostics` already relies on (see
+        # `docs/type-specification/diagnostic-policy.md` § "Run-level rows and the record-and-validate
+        # cache"). It is also never routed through `IncrementalSession`'s per-file cache (`#788`): that cache
+        # holds only `Runner#per_file_diagnostics`, and this row is not part of that stream.
+        #
+        # Scope: `plugin_registry` here is the coordinator-side registry, which only actually RUNS `#prepare`
+        # / per-file analysis in sequential mode (`--workers` unset, the default) — a pooled run (`--workers
+        # N`) prepares and analyses on per-worker `WorkerSession` registries this reader never sees, so a
+        # refusal confined to a pooled worker's slice is not reported. Left out deliberately: draining it
+        # needs a fourth marshalled channel beside `drain_reporters` / `drain_dependencies` / `drain_effects`
+        # in `Runner::PoolCoordinator`, and the default (unpooled) path already covers the reported bug.
+        def plugin_trust_refusal_diagnostics
+          return [] if plugin_registry.empty?
+
+          plugin_registry.plugins.filter_map { |plugin| plugin_trust_refusal_diagnostic(plugin) }
+        end
+
+        # Issue #1051 — the run-scoped plugin disclosures ({Plugin::Base#disclose_once}), the run's
+        # project-global notices about its own inputs. Two sources feed one table:
+        #
+        # - the coordinator-side registry, which is where a SEQUENTIAL run's `#prepare` and per-file hooks
+        #   ran; and
+        # - `pooled_run_disclosures`, the pool coordinator's already-de-duplicated collection from the
+        #   pre-fork parent session and every worker payload.
+        #
+        # Both are keyed `[plugin id, key]` and the first registration of a pair wins, so a run emits one
+        # row per pair no matter how many plugin instances (workers) reached it — the #1051 bug, where a
+        # per-instance `@emitted` flag produced one row per WORKER.
+        #
+        # The emitted order is `(registry position, key)`, NOT registration order: a worker's slice
+        # determines which instance registers a key first, so registration order is a function of
+        # `--workers N` and would make a pooled run's stream differ from a sequential one's even with the
+        # duplicates gone. Registry position is the plugin load order (topological by `consumes:`), which
+        # both modes share.
+        #
+        # Position is `.rigor.yml:1:1` for every row; see {Plugin::Base#disclose_once} for why that and not
+        # the first analysed file. A positioned batch ({Plugin::Base#emit_once}) shares the table but not
+        # this stream — see {#plugin_run_emission_diagnostics}.
+        def plugin_run_disclosure_diagnostics
+          ordered_run_disclosure_records
+            .reject { |record| record.key?(:diagnostics) }
+            .map { |record| run_disclosure_diagnostic(record) }
+        end
+
+        # Issue #1060 — the positioned batches ({Plugin::Base#emit_once}) from the same table, de-duplicated
+        # by the same `[plugin id, key]` identity over the same sources, so the first registration of a key
+        # wins whole and a batch is never merged row by row across workers. Unlike a disclosure, every row
+        # keeps the position the plugin gave it; the engine only stamps `source_family: "plugin.<id>"`, the
+        # same stamp a `#diagnostics_for_file` row gets, so a baseline keyed to the row's own file and
+        # qualified rule matches it before and after a plugin moves onto this channel.
+        #
+        # Order is `(registry position, key)` and then the batch's own row order — the same
+        # `--workers`-independent order the disclosure stream uses. The runner appends this stream right
+        # after the per-file stream rather than into the run-level block: these rows are about files, and
+        # the files they name are usually not among the analysed targets (a view template), so there is no
+        # file slot to splice them into.
+        def plugin_run_emission_diagnostics
+          ordered_run_disclosure_records
+            .select { |record| record.key?(:diagnostics) }
+            .flat_map { |record| record[:diagnostics].map { |row| run_emission_diagnostic(row, record[:plugin_id]) } }
+        end
+
+        def ordered_run_disclosure_records
+          registry = plugin_registry
+          return [] if registry.empty?
+
+          positions = {}
+          registry.plugins.each_with_index { |plugin, index| positions[disclosure_plugin_id(plugin)] ||= index }
+          collect_run_disclosure_records(registry)
+            .sort_by { |record| [positions.fetch(record[:plugin_id], positions.size), record[:key].to_s] }
+        end
+
+        def collect_run_disclosure_records(registry)
+          records = {}
+          Array(pooled_run_disclosures).each do |record|
+            records[[record[:plugin_id], record[:key]]] ||= record
+          end
+          registry.plugins.each do |plugin|
+            plugin_id = disclosure_plugin_id(plugin)
+            Array(plugin.run_disclosure_records).each do |record|
+              records[[plugin_id, record[:key]]] ||= record.merge(plugin_id: plugin_id)
+            end
+          rescue StandardError
+            next
+          end
+          records.values
+        end
+
+        def run_disclosure_diagnostic(record)
+          Diagnostic.new(
+            path: ".rigor.yml", line: 1, column: 1,
+            message: record.fetch(:message),
+            severity: record.fetch(:severity),
+            rule: record.fetch(:rule),
+            source_family: "plugin.#{record[:plugin_id]}"
+          )
+        end
+
+        def run_emission_diagnostic(row, plugin_id)
+          Diagnostic.new(
+            path: row.path, line: row.line, column: row.column,
+            message: row.message,
+            severity: row.severity,
+            rule: row.rule,
+            source_family: "plugin.#{plugin_id}"
+          )
+        end
+
+        def disclosure_plugin_id(plugin)
+          plugin.manifest.id
+        rescue StandardError
+          plugin.class.to_s
+        end
+
+        def plugin_trust_refusal_diagnostic(plugin)
+          summary = plugin.io_boundary.refusal_summary
+          return nil if summary.nil?
+
+          plugin_id = plugin.manifest.id
+          Diagnostic.new(
+            path: ".rigor.yml", line: 1, column: 1,
+            message: "plugin #{plugin_id.inspect} had #{summary[:count]} read(s) refused by the trust " \
+                     "policy; first refused path: #{summary[:first_path].inspect}, outside read root " \
+                     "#{summary[:nearest_root].inspect}. Spell the path the way that read root spells it " \
+                     "(a symlink alias such as macOS' /tmp does not match its real path), or add a " \
+                     "`plugins_io.allowed_paths:` entry in .rigor.yml covering the path.",
+            severity: :info,
+            rule: "plugin_trust.read-refused",
+            source_family: :builtin
+          )
+        rescue StandardError
+          nil
+        end
+
         def build_reporter_diagnostic(source_location, rule:, message:)
           path, line, column = location_fields(source_location)
           Diagnostic.new(
@@ -877,6 +1176,10 @@ module Rigor
           @cached_plugin_prepare_diagnostics_reader.call
         end
 
+        def pooled_run_disclosures
+          @pooled_run_disclosures_reader.call
+        end
+
         def pre_eval_diagnostics_from_scanner
           @pre_eval_diagnostics_from_scanner_reader.call
         end
@@ -889,6 +1192,10 @@ module Rigor
           @quarantined_signatures_snapshot_reader.call
         end
 
+        def signature_standdowns_snapshot
+          @signature_standdowns_snapshot_reader.call
+        end
+
         def env_build_failure_snapshot
           @env_build_failure_snapshot_reader.call
         end

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

@@ -58,8 +58,7 @@ module Rigor
                   "every run of the project."
         private_constant :MESSAGE
 
-        # @param configuration [Rigor::Configuration]
-        # @param virtual_rbs [Array<Array(String, String)>, nil] `[buffer name, RBS source]` pairs the
+        # @param virtual_rbs — `[buffer name, RBS source]` pairs the
         #   run ALREADY resolved; never a loader built for this pass. Empty / nil simply drops the
         #   virtual-RBS stratum.
         def initialize(configuration:, virtual_rbs: nil)
@@ -67,7 +66,7 @@ module Rigor
           @virtual_rbs = virtual_rbs
         end
 
-        # @return [Array<Diagnostic>] zero or one.
+        # @return zero or one.
         def diagnostics
           return NO_DIAGNOSTICS if @configuration.effects_enabled?
           return NO_DIAGNOSTICS if @configuration.disabled_rules.include?(RULE)

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

@@ -78,22 +78,21 @@ module Rigor
         LABELS_CONSEQUENCE = "the label is not registered"
         private_constant :LABELS_CONSEQUENCE
 
-        # @param configuration [Rigor::Configuration]
-        # @param rbs_loader [Rigor::Environment::RbsLoader, nil] the run's loader; nil disables the pass.
-        # @param effect_table [Rigor::Effects::EffectTable] the propagated graph.
-        # @param discovery [#call] forces and returns the cross-file discovery tables as
+        # @param rbs_loader — the run's loader; nil disables the pass.
+        # @param effect_table — the propagated graph.
+        # @param discovery — forces and returns the cross-file discovery tables as
         #   `[def_sources, singleton_def_sources, class_sources]`. Called only when a finding needs a
         #   position — a judged-clean envelope never forces it.
-        # @param sources [Hash{String => String}] in-memory sources, for the buffer-backed run path.
-        # @param unit_sources [Hash{String => Array<String>}] `Runner#effect_sources` — where each effect
+        # @param sources — in-memory sources, for the buffer-backed run path.
+        # @param unit_sources — `Runner#effect_sources` — where each effect
         #   unit is defined, which is what an `effects.envelopes[].match:` path glob selects on. Its paths
         #   are relativised against the working directory, which is the project root for every run that
         #   reaches here (the same assumption `Snapshot.build` makes about `reach:`).
-        # @param ancestry [#call, nil] returns the run's as-written superclass table
+        # @param ancestry — returns the run's as-written superclass table
         #   (`FileCollection#superclasses`) — the nominal relation `effect.liskov-widened` reads. A
         #   lambda, and called only once an envelope exists, because merging the run's collections is
-        #   not free.
-        # @param apply_tolerated [Boolean] false runs the judgment with an empty tolerated set
+        #   not free. nil leaves that relation empty.
+        # @param apply_tolerated — false runs the judgment with an empty tolerated set
         #   (`--no-tolerated-effects`).
         def initialize(configuration:, rbs_loader:, effect_table:, discovery:, # rubocop:disable Metrics/ParameterLists
                        sources: nil, unit_sources: nil, ancestry: nil, apply_tolerated: true,
@@ -109,7 +108,7 @@ module Rigor
           @apply_tolerated = apply_tolerated
         end
 
-        # @return [Array<Diagnostic>] one per (method, exceeding label) plus one per unrecognised
+        # @return one per (method, exceeding label) plus one per unrecognised
         #   label, suppression already applied.
         def diagnostics
           return NO_DIAGNOSTICS unless @configuration.effects_check?
@@ -251,9 +250,7 @@ module Rigor
           )
         end
 
-        def table_class_names
-          @effect_table.keys.filter_map { |key| Effects::MethodKey.owner(key) }.uniq
-        end
+        def table_class_names = @effect_table.keys.filter_map { |k| Effects::MethodKey.envelope_owner(k) }.uniq
 
         def judge(scan)
           Effects::EnvelopeCheck.run(
@@ -302,7 +299,7 @@ module Rigor
 
         def build_diagnostic(finding)
           Diagnostic.new(
-            path: finding.path || ".rigor.yml",
+            path: finding.path || unit_source_path(finding.key) || ".rigor.yml",
             line: finding.line,
             column: 1,
             message: message_for(finding),
@@ -313,6 +310,13 @@ module Rigor
           )
         end
 
+        # #393 — a template unit has no `def` for {Effects::EnvelopeCheck::Positions} to find, so a view
+        # finding would land on `.rigor.yml` — the config file, not the template the reviewer has to open.
+        # `Runner#effect_sources` already records the file every unit key came from; the line stays at the
+        # finding's own (1 for a whole-file unit), because the bound is exceeded by the unit, not by one
+        # line of it, and the explanation chain names the origin site.
+        def unit_source_path(key) = Effects::MethodKey.template_unit?(key) ? @unit_sources[key.to_s]&.first : nil
+
         def message_for(finding)
           EnvelopeMessages.exceeded(finding)
         end