rigortype 0.3.4 → 0.3.5

data/docs/manual/ci-templates/README.md

@@ -26,6 +26,15 @@ comments (it works the same way against GitLab, Gerrit, Bitbucket, and Gitea
 — see the [`rigor-ci-setup`](../../../skills/rigor-ci-setup/SKILL.md) skill).
 All run Rigor the same way — only the output format and publish step differ.
 
+Every template ends with a **commented-out `rigor effects check` step**.
+Uncomment it once the project has an `effects:` block and a committed
+`.rigor-effects.yml`, and CI will fail when a branch changes what the code
+*does* — a job that starts talking to the network, a presenter that starts
+querying. It ships commented because `effects check` exits `1` when the
+snapshot file is absent, which is exactly what you want on a project that
+has one and pure noise on a project that does not. The workflow around it
+is [chapter 19, "Effect labels"](../19-effect-labels.md).
+
 ## Other runners (generic recipe)
 
 On any CI system, the four steps are: provision Ruby 4.0, install

data/lib/rigor/analysis/rule_catalog.rb

@@ -36,9 +36,16 @@ module Rigor
     module RuleCatalog # rubocop:disable Metrics/ModuleLength
       # Stable documentation home for a built-in rule. `documentation_url` appends a per-rule fragment that
       # resolves to the rule's anchor in the published diagnostics catalogue; the page itself points at
-      # `rigor explain <rule>` as the authoritative per-rule reference. Mirrors the gemspec
-      # `documentation_uri` URL scheme (`…/tree/main`).
-      DOCUMENTATION_BASE = "https://github.com/rigortype/rigor/blob/main/docs/manual/04-diagnostics.md"
+      # `rigor explain <rule>` as the authoritative per-rule reference.
+      #
+      # The canonical docs host, deliberately NOT a `github.com/…/blob/<ref>/…` path (ADR-65 amendment,
+      # #438): a git ref inside a frozen public contract is a mutable component, and the one that was
+      # baked in here — `main`, a branch this repository has never had — made every emitted URL 404 from
+      # the day the field shipped. A branch name rots on a rename and a tag only resolves once that tag
+      # is pushed (so every unreleased build would emit 404s); the published site carries no ref at all.
+      # The site renders `docs/manual/04-diagnostics.md` verbatim, `<a id="rule-…">` anchors included, so
+      # the fragment half of the contract is unchanged.
+      DOCUMENTATION_BASE = "https://rigor.typedduck.fail/manual/04-diagnostics/"
 
       class Entry < Data.define(:id, :summary, :fires_when, :does_not_fire_when,
                                 :suppression, :severity_authored, :severity_by_profile,

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

@@ -10,17 +10,19 @@ module Rigor
       # 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"
-        RUBY_EXTENSION = ".rb"
-        private_constant :RUBY_EXTENSION
 
         module_function
 
-        # @param finding [#location, #spelling]
-        # @param sources [Hash{String => String}] in-memory sources, for the buffer-backed run path
+        # @param finding [#location]
         # @return [Array(String, Integer)] `[path, line]`
-        def of(finding, sources: {})
+        def of(finding)
           location = finding.location
           return [CONFIG_PATH, 1] if location.nil?
 
@@ -28,25 +30,7 @@ module Rigor
           return [CONFIG_PATH, 1] if path.empty?
 
           line = raw_line.to_i
-          line = 1 unless line.positive?
-          return [path, line] unless path.end_with?(RUBY_EXTENSION)
-
-          [path, inline_line(path, finding.spelling, sources) || line]
-        end
-
-        # rbs-inline's writer re-emits the author's own comment block ABOVE the annotation it generates,
-        # so a line number read out of the synthesized buffer drifts from the `.rb` line the author
-        # actually wrote — by the length of every method body above it. The annotation's own text is
-        # unique enough to find again, so the Ruby file is what answers. One read, and only when a
-        # finding already exists.
-        def inline_line(path, spelling, sources)
-          return nil if spelling.nil?
-
-          source = sources[path] || File.read(path)
-          source.each_line.with_index(1) { |line, number| return number if line.include?(spelling) }
-          nil
-        rescue StandardError
-          nil
+          [path, line.positive? ? line : 1]
         end
       end
     end

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

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
 require_relative "../diagnostic"
-require_relative "../check_rules"
+# 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
@@ -25,9 +30,15 @@ module Rigor
       #   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 an inline-only annotation is reported when the run happens to have a
-      #   loader at hand and not otherwise. Under-reporting is the fail-quiet direction; the check
-      #   itself never depends on this pass.
+      #   `: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
@@ -38,9 +49,6 @@ module Rigor
 
         RULE = CheckRules::RULE_EFFECT_ANNOTATIONS_UNCHECKED
 
-        RUBY_EXTENSION = ".rb"
-        private_constant :RUBY_EXTENSION
-
         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 " \
@@ -51,11 +59,12 @@ module Rigor
         private_constant :MESSAGE
 
         # @param configuration [Rigor::Configuration]
-        # @param rbs_loader [Rigor::Environment::RbsLoader, nil] a loader the run ALREADY has; never
-        #   one built for this pass. `nil` simply drops the virtual-RBS stratum.
-        def initialize(configuration:, rbs_loader: nil)
+        # @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
-          @rbs_loader = rbs_loader
+          @virtual_rbs = virtual_rbs
         end
 
         # @return [Array<Diagnostic>] zero or one.
@@ -64,7 +73,7 @@ module Rigor
           return NO_DIAGNOSTICS if @configuration.disabled_rules.include?(RULE)
 
           sources = Effects::SignatureSources.collect(
-            signature_paths: @configuration.signature_paths, virtual_rbs: @rbs_loader&.virtual_rbs
+            signature_paths: @configuration.signature_paths, virtual_rbs: @virtual_rbs
           )
           return NO_DIAGNOSTICS if sources.empty?
 
@@ -80,28 +89,19 @@ module Rigor
         # 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)
-          line = inline_line(path, content, line) if path.end_with?(RUBY_EXTENSION)
           Diagnostic.new(
-            path: path, line: line, column: 1, message: MESSAGE,
-            severity: :info, rule: RULE, source_family: :builtin
+            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
-
-        # A `virtual:` buffer's line numbers are the synthesized RBS's, not the `.rb`'s — rbs-inline
-        # re-emits the author's comment block above each generated member, so the two drift apart by
-        # the length of every body above. Find the annotation's own text in the Ruby file instead.
-        def inline_line(path, content, line)
-          spelling = content.each_line.to_a[line - 1].to_s[/%a\{[^}]*\}/]
-          return line if spelling.nil?
-
-          File.foreach(path).with_index(1) { |source_line, number| return number if source_line.include?(spelling) }
-          line
-        rescue StandardError
-          line
-        end
       end
     end
   end

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

@@ -220,7 +220,7 @@ module Rigor
         end
 
         def position_of(finding)
-          DeclarationPosition.of(finding, sources: @sources)
+          DeclarationPosition.of(finding)
         end
 
         # The vocabulary an unknown label is judged against: the shipped registry plus whatever

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

@@ -6,6 +6,7 @@ require_relative "../../environment"
 require_relative "../diagnostic"
 require_relative "../worker_session"
 require_relative "../run_stats"
+require_relative "../../effects/signature_sources"
 require_relative "../../rbs_extended/conformance_checker"
 require_relative "../../runtime/jit"
 
@@ -123,6 +124,7 @@ module Rigor
 
         def analyze_files_sequentially(files, environment)
           snapshot_project_signature_state(environment)
+          snapshot_effect_annotation_carrier(environment&.rbs_loader)
           result = files.flat_map { |path| @analyze_file.call(path, environment) }
           if @collect_stats
             loader = environment.rbs_loader
@@ -157,6 +159,27 @@ module Rigor
           @snapshots.conformance_results = RbsExtended::ConformanceChecker.scan(loader)
         end
 
+        # #441 — the inline stratum of `effect.annotations-unchecked`, carried out of the analysis path as
+        # small plain data, for the same reason the block above is: the environment stays a LOCAL so it goes
+        # GC-eligible when the path returns, and the residual pass runs after it.
+        #
+        # {Runner#effect_annotation_residual_diagnostics} used to read the loader off `@run_environment`,
+        # which only the ADR-45 result-cacheable path ever assigns — so a `--no-cache`, `--workers N` or
+        # `--incremental` run reported a `.rbs` annotation and stayed silent about the identical one written
+        # as an rbs-inline comment, while a default run reported both. The environment was there either way;
+        # nothing was carrying it. {Effects::SignatureSources.annotated_carrier} reduces it to at most ONE
+        # synthesized buffer, which is all a one-`:info`-per-run pass can spend.
+        #
+        # Skipped when collection is on — then {Runner::EffectEnvelopePass} reads the loader directly and
+        # this pass is gated off — so a collecting run pays nothing, and a project with no synthesizing
+        # plugin answers with an empty array and no regex at all.
+        def snapshot_effect_annotation_carrier(loader)
+          virtual = @record_effects ? nil : loader&.virtual_rbs
+          @snapshots.effect_annotation_carrier = Effects::SignatureSources.annotated_carrier(virtual)
+        rescue StandardError
+          @snapshots.effect_annotation_carrier = [].freeze
+        end
+
         # Sequential-mode environment resolver. Returns the supplied `environment:` override (with the
         # runner's fresh per-run reporter pair attached so dispatcher events route to THIS runner's
         # diagnostics) when present; otherwise builds a fresh Environment per-call via
@@ -408,6 +431,7 @@ module Rigor
           # Force the full RBS load on the parent so children copy-on-write inherit a warm Environment
           # rather than each rebuilding it after the fork.
           session.environment.rbs_loader&.prewarm
+          snapshot_effect_annotation_carrier(session.environment.rbs_loader)
           snapshot_fork_pool_stats(session) if @collect_stats
 
           worker_count = [@workers, files.size].min
@@ -540,6 +564,7 @@ module Rigor
         # per-file analysis runs on the coordinator, identical to the default sequential path.
         def analyze_files_sequentially_fallback(files, reason:)
           environment = build_runner_environment
+          snapshot_effect_annotation_carrier(environment.rbs_loader)
           diagnostics = files.flat_map { |path| @analyze_file.call(path, environment) }
           loader = environment.rbs_loader
           @snapshots.class_decl_paths = loader&.class_decl_paths || {}.freeze

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

@@ -3,10 +3,11 @@
 module Rigor
   module Analysis
     class Runner
-      # Mutable per-run holder for the four end-of-pass snapshots that the analysis paths compute as a side
+      # Mutable per-run holder for the end-of-pass snapshots that the analysis paths compute as a side
       # effect and the rest of the run reads back: the RBS `class_decl_paths` / `signature_paths` tables
-      # (consumed by {RunStats}), the synthesized-namespace name list, and the `conforms-to` scan results
-      # (consumed by the diagnostic aggregator).
+      # (consumed by {RunStats}), the synthesized-namespace name list, the `conforms-to` scan results
+      # (consumed by the diagnostic aggregator), and the effect-annotation carrier (#441 — consumed by
+      # {EffectAnnotationResidualPass} on the runs that never store the environment).
       #
       # The snapshots are written by whichever analysis path ran ({PoolCoordinator} sequential / fork-pool /
       # fallback) and read by the {Runner} and {DiagnosticAggregator}. A shared mutable holder keeps the
@@ -16,7 +17,7 @@ module Rigor
       class RunSnapshots
         attr_accessor :class_decl_paths, :signature_paths,
                       :synthesized_namespaces, :quarantined_signatures, :conformance_results,
-                      :env_build_failure
+                      :env_build_failure, :effect_annotation_carrier
 
         # Constructor defaults match the {Runner} constructor: the pre-seed values `build_run_stats` /
         # `pre_file_diagnostics` read before the first analysis path runs are frozen empties. The
@@ -29,6 +30,7 @@ module Rigor
           @quarantined_signatures = [].freeze
           @conformance_results = [].freeze
           @env_build_failure = nil
+          @effect_annotation_carrier = [].freeze
         end
 
         # Per-`#run` reset. Mirrors the original `#run` body, which reset these to NON-frozen empties (distinct
@@ -40,6 +42,7 @@ module Rigor
           @quarantined_signatures = []
           @conformance_results = []
           @env_build_failure = nil
+          @effect_annotation_carrier = [].freeze
         end
       end
     end

data/lib/rigor/analysis/runner.rb

@@ -108,7 +108,9 @@ module Rigor
         return @effect_plugin_facts if @effect_plugin_facts && @effect_plugin_facts_ancestry.equal?(table)
 
         @effect_plugin_facts_ancestry = table
-        @effect_plugin_facts = Effects::PluginFacts.build(@plugin_registry, superclasses: table)
+        @effect_plugin_facts = Effects::PluginFacts.build(
+          @plugin_registry, superclasses: table, includes: @project_discovered_includes
+        )
       end
 
       # The merged per-file collections behind {#effect_table} — the *direct* summaries, before the graph
@@ -751,13 +753,20 @@ module Rigor
         ).diagnostics
       end
 
-      # The residual takes the loader the run ALREADY resolved — never `envelope_rbs_loader`, which
+      # The residual takes the virtual RBS the run ALREADY resolved — never `envelope_rbs_loader`, which
       # builds one on demand. This runs on the effects-off path, where an environment build is a cost
       # the project did not ask for; the `signature_paths:` `.rbs` stratum is always read, and the
       # rbs-inline stratum rides whatever the run happened to have.
+      #
+      # #441 — two sources, because two shapes of run resolve an environment and only one of them keeps
+      # it: `@run_environment` is assigned solely by the ADR-45 result-cacheable path, while every
+      # ANALYZING run (`--no-cache`, `--workers N`, `--incremental`, an editor buffer) builds one inside
+      # {PoolCoordinator} and lets it go. The snapshot is that run's carrier, and taking it second
+      # preserves the cacheable path's byte-identical behaviour.
       def effect_annotation_residual_diagnostics
         EffectAnnotationResidualPass.new(
-          configuration: @configuration, rbs_loader: @run_environment&.rbs_loader
+          configuration: @configuration,
+          virtual_rbs: @run_environment&.rbs_loader&.virtual_rbs || @snapshots.effect_annotation_carrier
         ).diagnostics
       end
 

data/lib/rigor/analysis/worker_session.rb

@@ -187,7 +187,9 @@ module Rigor
       # the same project ancestry the parent would have walked.
       def effect_plugin_facts
         @effect_plugin_facts ||= Effects::PluginFacts.build(
-          @plugin_registry, superclasses: @project_scope_seed[:discovered_superclasses] || {}
+          @plugin_registry,
+          superclasses: @project_scope_seed[:discovered_superclasses] || {},
+          includes: @project_scope_seed[:discovered_includes] || {}
         )
       end
       private :effect_plugin_facts

data/lib/rigor/cli/effects_command.rb

@@ -4,6 +4,9 @@ require "optionparser"
 
 require_relative "../configuration"
 require_relative "../analysis/runner"
+require_relative "../effects/plugin_facts"
+require_relative "../effects/registry"
+require_relative "../plugin/loader"
 require_relative "../cache/store"
 require_relative "command"
 require_relative "effects_renderer"
@@ -61,7 +64,17 @@ module Rigor
           #{USAGE}
 
           With no subcommand, prints one line per method: its proven effect labels and whether that
-          list is exhaustive.
+          list is exhaustive. A PATH selects which methods are printed, never which are analysed.
+
+          Options:
+            --config=PATH        Path to the Rigor configuration file
+            --format=FORMAT      Output format: text (default) or json
+            --full               List every method, including the ones with nothing to say
+            --label=LABEL        Only methods carrying LABEL (or a label under it), in either lane
+            --pure               Only methods proven to do nothing beyond mutate.local
+            --limit=N            Print at most N methods
+            --why                Expand each method's unresolved reasons and declared-lane sources
+            --list-labels        Print the effect vocabulary this project can name, and exit
 
           Subcommands (the committed effect snapshot, ADR-103 WD7):
             update      Write the snapshot to effects.snapshot.path. Commit it; review its diff.
@@ -78,24 +91,69 @@ module Rigor
         return usage_error("unsupported format: #{options.fetch(:format)}") unless FORMATS.include?(options[:format])
 
         configuration = Configuration.load(options.fetch(:config)).with_effects_enabled
-        table = analyze(configuration)
-        report = EffectsReport.build(table, full: options.fetch(:full))
-        EffectsRenderer.new(out: @out).render(report, format: options.fetch(:format))
+        return list_labels(configuration) if options.fetch(:list_labels)
+
+        scope = @argv.dup
+        table, sources = analyze(configuration, scope)
+        report = EffectsReport.build(
+          table, full: options.fetch(:full), sources: sources, scope: scope,
+                 label: options.fetch(:label), pure: options.fetch(:pure), limit: options.fetch(:limit)
+        )
+        note_scope(scope, report, table)
+        EffectsRenderer.new(out: @out, why: options.fetch(:why)).render(report, format: options.fetch(:format))
         0
       end
 
+      # A path argument is a **view**, and the note says so (#439).
+      #
+      # It used to narrow the analysed set, and effect labels are transitive over whatever was analysed —
+      # so `rigor effects app/controllers/issues_controller.rb` reported `IssuesController#create: [] …?`
+      # where the whole-project run reported four labels and a declared lane. The weakened answer was
+      # indistinguishable from a genuinely effect-free method, and a path argument is the only tractability
+      # lever the report has, so it was the thing an adopter reached for first.
+      #
+      # The note goes to stderr rather than into the report: it is about the invocation, not about the
+      # code, and `--format json` and `rigor effects … > report.txt` both stay exactly what they were.
+      def note_scope(scope, report, table)
+        return if scope.empty?
+
+        if report.empty?
+          @err.puts("rigor: no effect unit is defined in #{scope.join(', ')} " \
+                    "(a path selects what is printed, not what is analysed)")
+          return
+        end
+
+        @err.puts("rigor: showing #{report.rows.length} of #{table.size} units, selected by " \
+                  "#{scope.join(', ')}; a path narrows the printing and not the analysis, so every " \
+                  "label is the one the whole-project run reports")
+      end
+
       FORMATS = %w[text json].freeze
       private_constant :FORMATS
 
       def parse_options
-        options = { config: nil, format: "text", full: false, no_tolerated: false }
+        options = { config: nil, format: "text", full: false, no_tolerated: false, label: [], pure: false,
+                    limit: nil, why: false, list_labels: false }
         OptionParser.new do |opts|
           opts.banner = USAGE
           Options.add_config(opts, options)
           opts.on("--format=FORMAT", "Output format: text (default) or json") { |value| options[:format] = value }
-          opts.on("--full", "List every method, including exhaustive ones with no effects beyond mutate.local") do
+          opts.on("--full", "List every method, including the ones with nothing to say") do
             options[:full] = true
           end
+          opts.on("--label=LABEL", "Only methods carrying LABEL (or a label under it), in either lane") do |value|
+            options[:label].concat(value.split(",").map(&:strip).reject(&:empty?))
+          end
+          opts.on("--pure", "Only methods proven to do nothing beyond mutate.local — the %a{pure} set") do
+            options[:pure] = true
+          end
+          opts.on("--limit=N", Integer, "Print at most N methods") { |value| options[:limit] = value }
+          opts.on("--why", "Expand each method's unresolved reasons and declared-lane sources") do
+            options[:why] = true
+          end
+          opts.on("--list-labels", "Print the effect vocabulary this project can name, and exit") do
+            options[:list_labels] = true
+          end
           # Accepted here and deliberately inert, exactly as it is on `update`: the report is an
           # observation, and observations are undischarged. Only a JUDGMENT reads `effects.tolerated:` —
           # `rigor effects check` / `diff`, and `rigor check`'s envelope contract.
@@ -116,15 +174,71 @@ module Rigor
       # the diagnostics entry serves the run and the #382 effects sidecar serves the collections, leaving
       # only the fixpoint. Sequential is not a cache decision — the run-result cache declines pool mode —
       # but a collecting run is pinned to the fork backend anyway, so `workers: 0` costs nothing here.
-      def analyze(configuration)
+      # #429 — the vocabulary, from the product rather than from a document the gem does not ship.
+      #
+      # Four configuration keys and two annotation forms all require typing an effect label, and until
+      # this there was no way to find out what the labels are: the manual's pointers resolve into
+      # `docs/type-specification/`, which `rigortype.gemspec` does not package. The registry is shipped
+      # data and already knows the answer; nothing surfaced it.
+      #
+      # It loads plugins but never analyses, because a plugin is where `rails.flash.write` comes from and
+      # a reader deciding what to write in `effects.envelopes:` needs to see it. A plugin that fails to
+      # load costs its labels and nothing else — `rigor plugins` is where that failure is reported.
+      def list_labels(configuration)
+        registry = project_registry(configuration)
+        @out.puts("Effect vocabulary — #{registry.labels.length} labels (vocabulary #{registry.vocabulary_version})")
+        registry.roots.each do |root|
+          @out.puts
+          @out.puts(root_heading(root, registry))
+          in_root = registry.labels.select { |label| Effects::Label.root(label) == root }
+          in_root.each_slice(4) { |slice| @out.puts("  #{slice.join(', ')}") }
+        end
+        @out.puts
+        @out.puts("A bound naming a label admits everything under it and nothing above it: `io` covers " \
+                  "`io.db.read`, `io.db.read` does not cover `io`.")
+        0
+      end
+
+      # A shipped root carries the registry's own one-liner; a root a plugin or this project opened
+      # carries where it came from instead, which is the more useful thing to say about it.
+      def root_heading(root, registry)
+        description = registry.descriptions[root]
+        return "#{root} — #{description}" if description
+
+        "#{root} — opened by a plugin or by this project's `effects.labels:`"
+      end
+
+      def project_registry(configuration)
+        services = Plugin::Services.new(reflection: Reflection, type: Type::Combinator,
+                                        configuration: configuration, cache_store: nil)
+        plugins = Plugin::Loader.load(configuration: configuration, services: services)
+        Effects::Registry.for_configuration(configuration, plugin_facts: Effects::PluginFacts.build(plugins))
+      rescue StandardError
+        Effects::Registry.for_configuration(configuration)
+      end
+
+      # The analysed set is the configured `paths:` **plus** whatever the arguments name — never the
+      # arguments alone (#439). An effect summary is transitive over whatever was analysed, so analysing
+      # less does not filter the report, it lowers every answer in it: `rigor effects
+      # app/controllers/issues_controller.rb` used to report `IssuesController#create: [] …?` where the
+      # whole-project run reported four labels and a declared lane, with nothing marking the difference.
+      #
+      # The union rather than the configured paths alone, so that pointing the command at a tree the
+      # configuration does not cover — which is what every `rigor effects PATH` invocation from outside a
+      # project does — still analyses it. Inside a project the argument is already under `paths:` and the
+      # union is the configured set unchanged.
+      #
+      # @return [Array(Rigor::Effects::EffectTable, Hash{String=>Array<String>})] the table, and which
+      #   file each unit was defined in — the map {EffectsReport} needs to answer a path argument.
+      def analyze(configuration, scope)
         runner = Analysis::Runner.new(
           configuration: configuration,
           cache_store: Cache::Store.new(root: configuration.cache_path),
           collect_stats: false,
           workers: 0
         )
-        runner.run(@argv.empty? ? configuration.paths : @argv)
-        runner.effect_table
+        runner.run((configuration.paths + scope).uniq)
+        [runner.effect_table, runner.effect_sources]
       end
     end
   end

data/lib/rigor/cli/effects_diff_renderer.rb

@@ -35,7 +35,11 @@ module Rigor
 
       HEDGED_REMOVAL = "-? %<label>s (current summary is not exhaustive)"
 
-      CLOSING_LINE = "Run `rigor effects update` and commit the result if this change is intended."
+      # Both commands, because they answer the two questions a drift report raises and a reader almost
+      # always asks them in this order (#435). `explain` is the one the manual's own narrative reaches for
+      # first, and the footer used to name only the one that makes the report go away.
+      CLOSING_LINE = "Run `rigor effects explain` to see what caused this, and `rigor effects update` to " \
+                     "accept it."
 
       def initialize(out:, path:)
         @out = out