rigortype 0.3.3 → 0.3.5

data/lib/rigor/analysis/run_cache_probe.rb

@@ -4,8 +4,10 @@ require_relative "result"
 require_relative "run_cache_key"
 require_relative "path_expansion"
 require_relative "severity_stamp"
+require_relative "runner/effect_annotation_residual_pass"
 require_relative "../cache/store"
 require_relative "../cache/file_digest"
+require_relative "../effects/signature_sources"
 
 module Rigor
   module Analysis
@@ -23,6 +25,31 @@ module Rigor
     # sound because their inputs are in that same validated set. The key is built through the shared
     # {RunCacheKey} — a project whose plugins synthesise virtual RBS produces a probe key that omits that
     # entry, so it simply misses and the full path takes over (never a wrong hit).
+    #
+    # ## What the slot does NOT contain (#428)
+    #
+    # ADR-103 puts the two effect diagnostics OUTSIDE the cached run assembly on purpose: the `effects:`
+    # block is deliberately absent from the diagnostics cache identity, so a finding written into that
+    # entry would outlive the configuration that produced it. `Runner#run_analysis` therefore appends them
+    # after `#compute_run_diagnostics` — which is exactly the code a served hit skips. Serving the slot
+    # verbatim silently dropped both of them on every warm run, and a check that only ever fires on a cold
+    # cache is worse than one that never fires at all.
+    #
+    # A probe that serves a slot has to answer for what the slot omits, so this one does, per pass:
+    #
+    # - `effect.annotations-unchecked` is **reproduced here**. It was built to be free (a glob and a regex
+    #   over the project's own signature tree — {Effects::SignatureSources}), so the probe simply runs it,
+    #   with no virtual RBS: the inline stratum is the documented fail-quiet direction of that pass, and it
+    #   is the stratum a run without an environment never had. #441 — that omission is unreachable rather
+    #   than merely tolerated, because a project whose plugins synthesise virtual RBS is exactly the one
+    #   whose probe key omits the `rbs.virtual_rbs` entry (§ above), so it misses here and the full path —
+    #   which carries the stratum in every run mode — answers instead.
+    # - `effect.envelope-exceeded` / `effect.liskov-widened` / `effect.unknown-label` cannot be: they read
+    #   the propagated effect graph and the cross-file discovery tables, i.e. the engine this path exists
+    #   to skip. So the probe **declines** for a project that could earn one ({#envelope_lane_live?}) and
+    #   the full path — which caches both halves in its own two slots, and re-judges them every run —
+    #   serves it instead. The decline is measured against the declarations alone, never against what they
+    #   would judge to, so it costs one glob and never a wrong answer.
     class RunCacheProbe
       # @param configuration [Rigor::Configuration]
       # @param cache_root [String]
@@ -48,14 +75,55 @@ module Rigor
 
         diagnostics = validated_diagnostics(key)
         return nil if diagnostics.nil?
+        # #428 — asked only after the peek, so a run that was going to miss anyway never pays the walk.
+        return nil if envelope_lane_live?
 
-        Result.new(diagnostics: SeverityStamp.apply(diagnostics, @configuration), stats: nil)
+        Result.new(
+          diagnostics: SeverityStamp.apply(diagnostics + residual_diagnostics, @configuration), stats: nil
+        )
       rescue StandardError
         nil
       end
 
       private
 
+      # #428 — whether this project could earn one of the three diagnostics {Runner::EffectEnvelopePass}
+      # produces, which are the ones no cached slot carries and no engine-free path can recompute.
+      #
+      # Read off the DECLARATIONS, because a declaration is the whole of what the engine-free side can
+      # see: the four `.rigor.yml` policy lists, and whether the project's own signature tree carries an
+      # effect annotation at all ({Effects::SignatureSources::ANNOTATION_HINT}, the same one-regex-per-file
+      # pre-filter the envelope reader routes on). Over-declining is free — it forgoes a fast lane for a
+      # run the full path still serves out of the same two warm slots — while under-declining is the bug
+      # this method exists for, so anything ambiguous answers true.
+      def envelope_lane_live?
+        return false unless @configuration.effects_check?
+
+        declared_in_config? || !Effects::SignatureSources.first_annotated(signature_sources).nil?
+      end
+
+      # The `effects:` policy surface an `effect.unknown-label` can be read off, plus the envelopes an
+      # `effect.envelope-exceeded` / `effect.liskov-widened` is judged against. A project that opted into
+      # effects and declared none of them has nothing for the pass to say.
+      def declared_in_config?
+        !@configuration.effects_envelopes.empty? || !@configuration.effects_tolerated.empty? ||
+          !@configuration.effects_labels.empty? || !@configuration.effects_attribution.empty?
+      end
+
+      # `effect.annotations-unchecked`, reproduced verbatim — the pass self-gates on `effects_enabled?`,
+      # so exactly one of it and {#envelope_lane_live?} is ever non-empty, as on the full path.
+      def residual_diagnostics
+        Runner::EffectAnnotationResidualPass.new(configuration: @configuration).diagnostics
+      end
+
+      # One walk, whichever of the two lanes asks: the residual pass collects its own (it is the one that
+      # runs when effects are off), so the memo only ever serves the envelope-lane decline.
+      def signature_sources
+        @signature_sources ||= Effects::SignatureSources.collect(
+          signature_paths: @configuration.signature_paths
+        )
+      end
+
       def validated_diagnostics(key)
         store = Cache::Store.new(root: @cache_root, max_bytes: @configuration.cache_max_bytes)
         # The digest fallback + `cache.validation` / RIGOR_STRICT_VALIDATION escape hatch route through the

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Analysis
+    class Runner
+      # Where an `effect.unknown-label` finding is positioned (ADR-103 WD14; #384).
+      #
+      # The declaration, not the method: this is a fact about what the author wrote, and the fix is on
+      # that line. A `.rbs` position is the right answer here even though its sibling deliberately avoids
+      # one (the `rbs_extended.unsatisfied-conformance` precedent) — there is no Ruby `def` that could
+      # carry the typo. A value written in configuration has no location at all and lands at
+      # `.rigor.yml:1`, the `rbs.coverage.quarantined-signature` precedent.
+      # A declaration's `location` is already the position a reader can open, `.rbs` and rbs-inline
+      # alike: the synthesized-buffer line is re-anchored onto the Ruby file where the envelope is
+      # built ({Rigor::Effects::InlineAnchor}, #432), so this module only has to split it. Doing the
+      # re-anchoring here as well used to be the fix, and it could not tell two identically-spelled
+      # annotations in one file apart — every finding in it landed on the first.
+      module DeclarationPosition
+        CONFIG_PATH = ".rigor.yml"
+
+        module_function
+
+        # @param finding [#location]
+        # @return [Array(String, Integer)] `[path, line]`
+        def of(finding)
+          location = finding.location
+          return [CONFIG_PATH, 1] if location.nil?
+
+          path, _, raw_line = location.rpartition(":")
+          return [CONFIG_PATH, 1] if path.empty?
+
+          line = raw_line.to_i
+          [path, line.positive? ? line : 1]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative "../diagnostic"
+# ADR-87 WD4 — the pure-data rule-id table, never the engine-heavy `check_rules.rb` that reopens the
+# same module. This pass is one of the two the boot-slimming {Analysis::RunCacheProbe} has to run for
+# itself on a cache hit (#428), and requiring the full rule set would put `rigor/inference` back into
+# a hit's `$LOADED_FEATURES`.
+require_relative "../check_rules/rule_ids"
+require_relative "../../effects/inline_anchor"
+require_relative "../../effects/signature_sources"
+
+module Rigor
+  module Analysis
+    class Runner
+      # `effect.annotations-unchecked` — the ADR-103 WD13 commitment-1 residual (#384).
+      #
+      # WD13 fixes two rules that pull against each other: an annotation **must not** turn effect
+      # collection on (a `%a{pure}` written for Steep's benefit would otherwise impose a project-wide
+      # cost cliff on every run of every project that has one), and an annotation **must not** be
+      # silently inert either. One `:info` per run is the whole reconciliation: the declarations are
+      # there, nothing reads them, and `effects: {}` is the one-line answer.
+      #
+      # ## What it is allowed to cost
+      #
+      # This runs on the surface that is meant to be free — a project with no `effects:` block, which
+      # is every project by default — so the budget is a glob and a regex:
+      #
+      # - It reads the project's own `signature_paths:` `.rbs` tree (the same stratum the envelope
+      #   check reads) and matches {Effects::SignatureSources::ANNOTATION_HINT} line by line. No RBS
+      #   parse, no analysis, no environment build, and nothing at all when the tree does not exist.
+      # - It consults the run's virtual RBS — rbs-inline's `# @rbs %a{…}` — only when the run ALREADY
+      #   resolved an environment. Building one here to find an `:info` would cost more than the
+      #   `:info` is worth, so the pass never reaches for a loader; every caller hands it what the run
+      #   had. #441 is why the caller side matters: an ANALYZING run always has an environment, so the
+      #   stratum is carried out of the analysis path as
+      #   {Runner::RunSnapshots#effect_annotation_carrier} whatever its mode, and the two lanes of
+      #   chapter 16 report the same annotation. The one shape that genuinely has no environment is a
+      #   warm ADR-87 WD4 cache hit served by {Analysis::RunCacheProbe} — an engine-free path whose
+      #   whole point is not building one — so there, and only there, an inline-only annotation goes
+      #   unreported. Under-reporting is the fail-quiet direction; the check itself never depends on
+      #   this pass.
+      #
+      # It is computed OUTSIDE the cached run assembly for the same reason `EffectEnvelopePass` is:
+      # the `effects:` block is deliberately absent from the diagnostics cache identity, so a residual
+      # baked into that entry would survive the very edit that answers it.
+      class EffectAnnotationResidualPass
+        NO_DIAGNOSTICS = [].freeze
+        private_constant :NO_DIAGNOSTICS
+
+        RULE = CheckRules::RULE_EFFECT_ANNOTATIONS_UNCHECKED
+
+        MESSAGE = "Effect annotations (`%a{pure}` / `%a{rigor:v1:effect …}`) are present in your " \
+                  "project's signatures, but `.rigor.yml` carries no `effects:` block, so effect " \
+                  "collection never runs and nothing checks them — they are documentation, not a " \
+                  "contract. Add `effects: {}` to have Rigor prove what your methods do and check " \
+                  "these bounds against it (ADR-103); an annotation alone never turns collection " \
+                  "on, because that would make one line in one signature file more expensive for " \
+                  "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
+        #   run ALREADY resolved; never a loader built for this pass. Empty / nil simply drops the
+        #   virtual-RBS stratum.
+        def initialize(configuration:, virtual_rbs: nil)
+          @configuration = configuration
+          @virtual_rbs = virtual_rbs
+        end
+
+        # @return [Array<Diagnostic>] zero or one.
+        def diagnostics
+          return NO_DIAGNOSTICS if @configuration.effects_enabled?
+          return NO_DIAGNOSTICS if @configuration.disabled_rules.include?(RULE)
+
+          sources = Effects::SignatureSources.collect(
+            signature_paths: @configuration.signature_paths, virtual_rbs: @virtual_rbs
+          )
+          return NO_DIAGNOSTICS if sources.empty?
+
+          found = Effects::SignatureSources.first_annotated(sources)
+          found.nil? ? NO_DIAGNOSTICS : [build_diagnostic(found)]
+        rescue StandardError
+          # Fail-soft, like every other effects surface: an advisory `:info` must never fail a run.
+          NO_DIAGNOSTICS
+        end
+
+        private
+
+        # Positioned at the first annotation itself rather than at `.rigor.yml:1`: the fix is a config
+        # edit, but the thing being reported is something the author wrote, and pointing at it is what
+        # tells them WHICH declaration is inert.
+        #
+        # A `virtual:` buffer's line numbers are the synthesized RBS's, not the `.rb`'s, so the position
+        # is re-anchored onto the Ruby file the same way the envelope reader anchors a declaration
+        # ({Effects::InlineAnchor}) — one mapping, so the advisory and the check can never name two
+        # different lines for one annotation.
+        def build_diagnostic(found)
+          name, content, line = found
+          path = Effects::SignatureSources.source_path(name)
+          Diagnostic.new(
+            path: path, line: Effects::InlineAnchor.ruby_line(path: path, buffer: content, buffer_line: line),
+            column: 1, message: MESSAGE, severity: :info, rule: RULE, source_family: :builtin
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,358 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../diagnostic"
+require_relative "../check_rules"
+require_relative "../../effects/config_envelopes"
+require_relative "../../effects/envelope_check"
+require_relative "../../effects/liskov_check"
+require_relative "../../effects/method_key"
+require_relative "../../effects/registry"
+require_relative "../../effects/signature_sources"
+require_relative "../../effects/unknown_label_check"
+require_relative "../../rbs_extended/envelope_scanner"
+require_relative "declaration_position"
+require_relative "envelope_messages"
+
+module Rigor
+  module Analysis
+    class Runner
+      # `effect.envelope-exceeded` and `effect.unknown-label`, end to end (ADR-103 WD1 / WD8 / WD12;
+      # #383 / #384).
+      #
+      # The two ride one gate and one walk on purpose. `effect.unknown-label` reports that an envelope
+      # STOPPED bounding — the fail-open degradation an unrecognised label causes — so opting into
+      # envelope enforcement is exactly what should turn it on, and reading it off any other pass
+      # would mean walking the project's signatures twice.
+      #
+      # Three steps, and the order is the cost model:
+      #
+      # 1. **Read the envelopes** off the project's own RBS ({RbsExtended::EnvelopeScanner}). A project
+      #    with `effects:` but no envelope pays this walk and stops here.
+      # 2. **Force cross-file discovery**, but only when step 1 found something — the diagnostic is
+      #    positioned at the Ruby `def`, and the discovery tables are what map a method key to one.
+      # 3. **Judge** ({Effects::EnvelopeCheck}) and render, then run the findings through the ordinary
+      #    suppression filter so `# rigor:disable effect.envelope-exceeded` on the `def` line and
+      #    `disable:` in `.rigor.yml` work exactly as they do for a per-file rule.
+      #
+      # **Why this is not part of the cached run assembly.** ADR-103 WD12 says envelope diagnostics are
+      # recomputed every run from the (possibly cached) summaries and never stored. The `effects:` block
+      # is deliberately absent from the diagnostics cache identity — that absence is what lets a project
+      # turn collection on without invalidating its check — so a finding baked into that entry would
+      # survive an `effects.check: false` edit. The pass therefore runs OUTSIDE
+      # `Runner#compute_run_diagnostics`, over whatever table the run ended up with, warm or cold.
+      class EffectEnvelopePass
+        NO_DIAGNOSTICS = [].freeze
+        private_constant :NO_DIAGNOSTICS
+
+        RULE = CheckRules::RULE_EFFECT_ENVELOPE_EXCEEDED
+        LISKOV_RULE = CheckRules::RULE_EFFECT_LISKOV_WIDENED
+        UNKNOWN_LABEL_RULE = CheckRules::RULE_EFFECT_UNKNOWN_LABEL
+
+        # Where a diagnostic about a configuration value is positioned when the loader cannot say
+        # which line the key was written on — the `rbs.coverage.quarantined-signature` precedent.
+        CONFIG_PATH = ".rigor.yml"
+        private_constant :CONFIG_PATH
+
+        RUBY_EXTENSION = ".rb"
+        private_constant :RUBY_EXTENSION
+
+        # What a `.rigor.yml` label list stops doing once one of its members is unrecognised.
+        TOLERATED_CONSEQUENCE = "the entry discharges nothing"
+        private_constant :TOLERATED_CONSEQUENCE
+
+        # An `envelopes[].effect` list degrades exactly as an annotation does: the whole tag reads ⊤.
+        ENVELOPE_CONSEQUENCE = "the entry now bounds nothing"
+        private_constant :ENVELOPE_CONSEQUENCE
+
+        # An attribution's labels are a *claim*, so an unrecognised member costs meaning rather than a
+        # bound: the labels are still attributed, and nothing in the vocabulary explains them.
+        ATTRIBUTION_CONSEQUENCE = "the attributed label means nothing to the vocabulary"
+        private_constant :ATTRIBUTION_CONSEQUENCE
+
+        # `effects.labels:` is the one list whose whole point is to introduce a spelling, so a member of
+        # it can only be unrecognised by being unregisterable — a root the loader dropped.
+        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
+        #   `[def_sources, singleton_def_sources, class_sources]`. Called only when an envelope exists.
+        # @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
+        #   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
+        #   (`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
+        #   (`--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,
+                       plugin_facts: nil)
+          @configuration = configuration
+          @plugin_facts = plugin_facts
+          @rbs_loader = rbs_loader
+          @effect_table = effect_table
+          @discovery = discovery
+          @sources = sources || {}
+          @unit_sources = unit_sources || {}
+          @ancestry_source = ancestry
+          @apply_tolerated = apply_tolerated
+        end
+
+        # @return [Array<Diagnostic>] one per (method, exceeding label) plus one per unrecognised
+        #   label, suppression already applied.
+        def diagnostics
+          return NO_DIAGNOSTICS unless @configuration.effects_check?
+
+          produced = config_label_diagnostics + config_envelope_diagnostics + declaration_diagnostics
+          return NO_DIAGNOSTICS if produced.empty?
+
+          suppress(produced)
+        rescue StandardError
+          # Fail-soft, like every other effects surface: an envelope Rigor cannot read must not fail a
+          # check that would otherwise pass.
+          NO_DIAGNOSTICS
+        end
+
+        private
+
+        # The envelopes, from both strata, and the judgment over them.
+        #
+        # The `.rbs` / rbs-inline walk is the expensive half and stays lazy: a project with `effects:` and
+        # no annotation pays it and stops. It is also **skipped entirely** when there is no loader — a
+        # project that writes no RBS at all still gets the configured envelopes judged, which is the whole
+        # point of the convention surface (design note § 6.2, "value on day one").
+        def declaration_diagnostics
+          scan = scan_declarations
+          return NO_DIAGNOSTICS if scan.nil? && config_envelopes.empty?
+
+          unknown_label_diagnostics(scan) + exceeded_diagnostics(scan)
+        end
+
+        def scan_declarations
+          return nil if @rbs_loader.nil?
+
+          scan = RbsExtended::EnvelopeScanner.scan(sources: signature_sources, registry: registry)
+          scan.empty? ? nil : scan
+        end
+
+        # The envelope contract itself. Needs the propagated graph and the discovery tables the `def`
+        # positions come from, so it is skipped when collection produced nothing — an unrecognised
+        # label is still reported in that case, because it is a fact about the declaration alone.
+        #
+        # The two contracts ride one resolution of the strata and one force of the discovery tables:
+        # `effect.envelope-exceeded` asks whether a method honours its OWN bound, `effect.liskov-widened`
+        # whether an override honours the one it inherits, and both read the same distributed table.
+        def exceeded_diagnostics(scan)
+          return NO_DIAGNOSTICS if @effect_table.empty?
+
+          judge(scan).map { |finding| build_diagnostic(finding) } +
+            judge_liskov(scan).map { |finding| build_liskov_diagnostic(finding) }
+        end
+
+        def unknown_label_diagnostics(scan)
+          return NO_DIAGNOSTICS if scan.nil?
+
+          findings = Effects::UnknownLabelCheck.for_envelopes(
+            method_envelopes: scan.method_envelopes, class_envelopes: scan.class_envelopes,
+            registry: registry
+          )
+          build_unknown_label_diagnostics(findings)
+        end
+
+        # The `.rigor.yml` label lists. Their SHAPE is already a tier-2 load error; this is the other
+        # half, a member the registry does not know after plugin load, which would otherwise fail
+        # silently — a `tolerated:` entry that discharges nothing, an envelope that reads ⊤, an
+        # attribution nothing can interpret.
+        def config_label_diagnostics
+          findings = config_label_findings("effects.tolerated", @configuration.effects_tolerated,
+                                           TOLERATED_CONSEQUENCE) +
+                     config_label_findings("effects.labels", @configuration.effects_labels,
+                                           LABELS_CONSEQUENCE) +
+                     attribution_findings
+          build_unknown_label_diagnostics(findings)
+        end
+
+        def config_label_findings(key_path, labels, consequence)
+          return [] if labels.empty?
+
+          Effects::UnknownLabelCheck.for_config(
+            labels: labels, key_path: key_path, consequence: consequence, registry: registry
+          )
+        end
+
+        def attribution_findings
+          @configuration.effects_attribution.flat_map do |key, labels|
+            config_label_findings("effects.attribution.#{key}", labels, ATTRIBUTION_CONSEQUENCE)
+          end
+        end
+
+        # `envelopes[].effect` — reported per entry, so the message names the stanza a reader has to edit
+        # rather than the label list it happens to share with another entry.
+        def config_envelope_diagnostics
+          findings = config_envelopes_entries.flat_map do |entry|
+            next [] if entry.unknown_labels.empty?
+
+            config_label_findings("effects.envelopes[#{entry.index}].effect", entry.labels,
+                                  ENVELOPE_CONSEQUENCE)
+          end
+          build_unknown_label_diagnostics(findings)
+        end
+
+        def build_unknown_label_diagnostics(findings)
+          findings.map { |finding| build_unknown_label_diagnostic(finding) }
+                  .sort_by { |diagnostic| [diagnostic.path, diagnostic.line, diagnostic.message] }
+        end
+
+        def build_unknown_label_diagnostic(finding)
+          path, line = position_of(finding)
+          Diagnostic.new(
+            path: path, line: line, column: 1, message: finding.message,
+            severity: :info, rule: UNKNOWN_LABEL_RULE, source_family: :builtin
+          )
+        end
+
+        def position_of(finding)
+          DeclarationPosition.of(finding)
+        end
+
+        # The vocabulary an unknown label is judged against: the shipped registry plus whatever
+        # `effects.labels:` opened, plus every loaded plugin's `effect_labels:` (#387). A project may open
+        # any root — the listing IS the vouching act — so nothing the project writes can raise on
+        # ownership; a plugin overreaching its root is refused inside {Effects::PluginFacts}, whose warning
+        # rides the report rather than this diagnostic stream.
+        def registry
+          @registry ||= Effects::Registry.for_configuration(@configuration, plugin_facts: @plugin_facts)
+        end
+
+        # `effects.envelopes:`, resolved against the vocabulary once per run.
+        def config_envelopes_entries
+          @config_envelopes_entries ||= Effects::ConfigEnvelopes.build(
+            entries: @configuration.effects_envelopes, registry: registry
+          )
+        end
+
+        # The classes those entries select, as class-keyed envelopes. Keyed off the effect table's own
+        # class names, so an entry naming a namespace or a path with no analysed unit behind it simply
+        # selects nothing.
+        def config_envelopes
+          @config_envelopes ||= Effects::ConfigEnvelopes.for_classes(
+            entries: config_envelopes_entries, class_names: table_class_names, sources: @unit_sources
+          )
+        end
+
+        def table_class_names
+          @effect_table.keys.filter_map { |key| Effects::MethodKey.owner(key) }.uniq
+        end
+
+        def judge(scan)
+          Effects::EnvelopeCheck.run(
+            table: @effect_table,
+            method_envelopes: scan&.method_envelopes || {}, class_envelopes: scan&.class_envelopes || {},
+            config_envelopes: config_envelopes,
+            positions: positions,
+            apply_tolerated: @apply_tolerated
+          )
+        end
+
+        def judge_liskov(scan)
+          Effects::LiskovCheck.run(
+            table: @effect_table, superclasses: ancestry,
+            method_envelopes: scan&.method_envelopes || {}, class_envelopes: scan&.class_envelopes || {},
+            config_envelopes: config_envelopes,
+            positions: positions,
+            apply_tolerated: @apply_tolerated
+          )
+        end
+
+        # The discovery tables both judgments position their findings from, forced once.
+        def positions
+          @positions ||= begin
+            def_sources, singleton_def_sources, class_sources = @discovery.call
+            Effects::EnvelopeCheck::Positions.build(
+              def_sources: def_sources, singleton_def_sources: singleton_def_sources,
+              class_sources: class_sources
+            )
+          end
+        end
+
+        def ancestry
+          @ancestry ||= @ancestry_source&.call || {}
+        end
+
+        # Everything an envelope may be written in — {Effects::SignatureSources} owns the stratum rule.
+        def signature_sources
+          Effects::SignatureSources.collect(
+            signature_paths: @configuration.signature_paths, virtual_rbs: @rbs_loader.virtual_rbs
+          )
+        end
+
+        def build_diagnostic(finding)
+          Diagnostic.new(
+            path: finding.path || ".rigor.yml",
+            line: finding.line,
+            column: 1,
+            message: message_for(finding),
+            severity: :warning,
+            rule: RULE,
+            source_family: :builtin,
+            method_name: method_name_of(finding.key)
+          )
+        end
+
+        def message_for(finding)
+          EnvelopeMessages.exceeded(finding)
+        end
+
+        def build_liskov_diagnostic(finding)
+          Diagnostic.new(
+            path: finding.path || CONFIG_PATH,
+            line: finding.line,
+            column: 1,
+            message: EnvelopeMessages.liskov(finding),
+            severity: :warning,
+            rule: LISKOV_RULE,
+            source_family: :builtin,
+            method_name: method_name_of(finding.key)
+          )
+        end
+
+        def method_name_of(key)
+          index = key.index("#") || key.index(".")
+          index.nil? ? nil : key[(index + 1)..]
+        end
+
+        # The ordinary suppression pipeline, per file: `# rigor:disable` / `# rigor:disable-file` comments
+        # from the Ruby file the diagnostic is positioned in, plus the project's `disable:` list. Reading
+        # the comments costs one parse per file that actually carries a finding.
+        def suppress(diagnostics)
+          diagnostics.group_by(&:path).flat_map do |path, group|
+            CheckRules.filter_suppressed(
+              group, comments: comments_for(path), disabled_rules: @configuration.disabled_rules
+            )
+          end
+        end
+
+        # Only a Ruby file has Ruby comments. An `effect.unknown-label` positioned in `.rbs` or at
+        # `.rigor.yml` is suppressible by the `disable:` list and by the baseline, never by an in-file
+        # comment — parsing YAML or RBS as Ruby to look for one would be a lie dressed as a feature.
+        def comments_for(path)
+          return [].freeze unless path.end_with?(RUBY_EXTENSION)
+
+          source = @sources[path]
+          result = source ? Prism.parse(source) : Prism.parse_file(path)
+          result.comments
+        rescue StandardError
+          [].freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Analysis
+    class Runner
+      # How an effect-envelope finding is worded (ADR-103 WD14; #383 / #386).
+      #
+      # One module for both contracts, because their messages are one sentence with a swapped middle:
+      # `effect.envelope-exceeded` names the bound the method carries, `effect.liskov-widened` names the
+      # bound it inherits, and both end by naming the label that escaped. Keeping the two here is what
+      # stops them drifting into two dialects of the same explanation — and what keeps
+      # {EffectEnvelopePass} about *when* a finding is produced rather than about how it reads.
+      #
+      # The shape a reviewer can act on without re-running anything: what the method does, the shortest
+      # route to whatever proves it, the author's own spelling of the bound quoted back, and where that
+      # bound was written.
+      module EnvelopeMessages
+        module_function
+
+        # `Effects::EnvelopeCheck::Finding` — a method against its own bound.
+        def exceeded(finding)
+          "Method #{finding.key} performs #{finding.label}#{explanation(finding)}, but is declared " \
+            "#{finding.envelope.spelling}#{declared_at(finding.envelope)}, so #{finding.label} exceeds " \
+            "the envelope."
+        end
+
+        # `Effects::LiskovCheck::Finding` — an override against the bound it inherits. Two variants of
+        # one sentence, and which one a reader gets says which comparison produced the finding: what the
+        # override *does* against the inherited bound, or what it *declares* against it. Both name the
+        # ancestor's declaration, because that is where the fix usually goes.
+        def liskov(finding)
+          "Method #{finding.key} #{liskov_subject(finding)}, but overrides #{finding.ancestor_key}, " \
+            "which is declared #{finding.ancestor_envelope.spelling}" \
+            "#{declared_at(finding.ancestor_envelope)}, so #{finding.label} exceeds the inherited envelope."
+        end
+
+        def liskov_subject(finding)
+          own = finding.own_envelope
+          return "is declared #{own.spelling}#{declared_at(own)}" if own
+
+          "performs #{finding.label}#{explanation(finding)}"
+        end
+
+        def explanation(finding)
+          hops = Array(finding.chain)[1..] || []
+          parts = [finding.origin, ("via #{hops.join(' → ')}" unless hops.empty?)].compact
+          parts.empty? ? "" : " (#{parts.join(' ')})"
+        end
+
+        # A distributed annotation names the class it came from; a configured envelope does not, because
+        # its `location` already names the stanza (`.rigor.yml effects.envelopes[2]`) and the method key
+        # at the head of the message already names the class.
+        def declared_at(envelope)
+          owner = envelope.source == :class_annotation ? " on #{envelope.owner_key.split(/[#.]/).first}" : ""
+          where = envelope.location ? " at #{envelope.location}" : ""
+          "#{owner}#{where}"
+        end
+      end
+    end
+  end
+end