rigortype 0.3.5 → 0.3.6

data/lib/rigor/cli/unused_command.rb

@@ -6,10 +6,12 @@ require "json"
 require_relative "../configuration"
 require_relative "../analysis/path_expansion"
 require_relative "../analysis/reachability/scan"
+require_relative "../analysis/reachability/scan_cache"
 require_relative "../analysis/reachability/graph"
 require_relative "../analysis/reachability/plugin_roots"
 require_relative "../analysis/reachability/signature_scan"
 require_relative "../analysis/reachability/project_files"
+require_relative "../cache/store"
 require_relative "options"
 require_relative "command"
 require_relative "probe_environment"
@@ -22,7 +24,11 @@ module Rigor
     # measured precision of this signal is 7.0% on an adjudicated corpus target
     # (`docs/notes/20260813-unused-constant-fp-baseline.md`), so its output is a review queue, not a defect
     # list, and it never enters `rigor check`'s stream at any severity (WD1). Exits 0 whatever it finds.
-    class UnusedCommand < Command
+    #
+    # Like {CheckCommand}, it aggregates one command's concerns — the two scans, the graph, and both
+    # render formats — that read clearer together than split across micro-classes, so it carries the
+    # same ClassLength exemption.
+    class UnusedCommand < Command # rubocop:disable Metrics/ClassLength
       USAGE = "Usage: rigor unused [options] [paths]"
 
       # WD7 — the REFERENCE corpus is wider than the ANALYSIS corpus. `.rake` files sit inside `paths:` and
@@ -43,23 +49,32 @@ module Rigor
 
         configuration = Configuration.load(options.fetch(:config))
         paths = @argv.empty? ? configuration.paths : @argv
-        declarations, references, dynamic_uses = scan(paths, configuration)
+        scan_cache = Analysis::Reachability::ScanCache.open(configuration.cache_path,
+                                                            target_ruby: configuration.target_ruby)
+        declarations, references, dynamic_uses = scan(paths, configuration, scan_cache)
         references.concat(signature_references(configuration))
-        dynamic_uses.concat(template_mentions(declarations))
+        dynamic_uses.concat(template_mentions(declarations, scan_cache))
 
-        contribution = Analysis::Reachability::PluginRoots.collect(configuration: configuration)
+        contribution = Analysis::Reachability::PluginRoots.collect(configuration: configuration,
+                                                                   cache_store: cache_store(configuration))
         references.concat(plugin_references(contribution.references))
-        graph = Analysis::Reachability::Graph.new(
-          declarations: declarations, references: references, dynamic_uses: dynamic_uses,
-          root_fqns: root_fqns(declarations, options.fetch(:entry_points)) + contribution.roots,
-          foreign: foreign_predicate(configuration)
-        )
+        graph = build_graph(configuration, options, contribution,
+                            declarations: declarations, references: references, dynamic_uses: dynamic_uses)
         emit(graph.report, options, supply: root_supply(contribution.roots, declarations))
+        scan_cache.save
         0
       end
 
       private
 
+      def build_graph(configuration, options, contribution, declarations:, references:, dynamic_uses:)
+        Analysis::Reachability::Graph.new(
+          declarations: declarations, references: references, dynamic_uses: dynamic_uses,
+          root_fqns: root_fqns(declarations, options.fetch(:entry_points)) + contribution.roots,
+          foreign: foreign_predicate(configuration)
+        )
+      end
+
       def parse_options
         options = { config: nil, format: "text", entry_points: [], limit: nil }
         parser = OptionParser.new do |opts|
@@ -91,13 +106,15 @@ module Rigor
       end
 
       # Declarations come from the analysed paths; references additionally from the wider corpus (WD7).
-      def scan(paths, configuration)
+      # Every file is consulted every run — an unchanged one contributes its cached scan, so the
+      # whole-project completeness the `--incremental` refusal protects is unaffected.
+      def scan(paths, configuration, cache)
         declaration_files = Analysis::PathExpansion.ruby_files(paths, configuration.exclude_patterns).to_set
         declarations = []
         references = []
         dynamic_uses = []
         (declaration_files + reference_files(paths, configuration)).sort.each do |file|
-          result = read_and_scan(file, configuration)
+          result = cache.serve(:scan, file) { read_and_scan(file, configuration) }
           next if result.nil?
 
           declarations.concat(result.declarations) if declaration_files.include?(file)
@@ -155,24 +172,38 @@ module Rigor
         end
       end
 
-      def template_mentions(declarations)
+      def template_mentions(declarations, cache)
         names = declarations.map(&:fqn)
         return [] if names.empty?
 
         Analysis::Reachability::ProjectFiles.own(Dir.glob(TEMPLATE_GLOB, base: Dir.pwd), Dir.pwd).flat_map do |rel|
-          text = File.read(File.expand_path(rel)).scrub
+          absolute = File.expand_path(rel)
+          haystack = cache.serve(:runs, absolute) { constant_bearing_text(File.read(absolute).scrub) }
           names.filter_map do |fqn|
-            next unless text.include?(fqn)
+            next unless haystack.include?(fqn)
 
             Analysis::Reachability::Scan::DynamicUse.new(name: nil, prefix: fqn, site: nil,
                                                          reason: "named as a string in #{rel}",
-                                                         path: rel, line: 1)
+                                                         path: rel, line: 1, scope: :exact)
           end
         rescue SystemCallError, ArgumentError
           []
         end
       end
 
+      # A maximal run of constant-path characters carrying at least one capital — the only substrings a
+      # declaration FQN can occur inside, since an FQN starts with a capital and uses this charset alone.
+      # An occurrence cannot cross a non-charset character, so `include?` over the de-duplicated runs
+      # (joined by a character outside the charset) answers exactly what `include?` over the whole text
+      # did, on a fraction of the bytes: a locale YAML or fixture JSON is almost entirely lowercase prose,
+      # and scanning 21 MB of it per declaration name was 81% of this command's wall time on mastodon.
+      CONSTANT_BEARING_RUN = /[A-Za-z0-9_:]*[A-Z][A-Za-z0-9_:]*/
+      private_constant :CONSTANT_BEARING_RUN
+
+      def constant_bearing_text(text)
+        text.scan(CONSTANT_BEARING_RUN).uniq.join("\n")
+      end
+
       def root_fqns(declarations, globs)
         return [] if globs.empty?
 
@@ -188,13 +219,31 @@ module Rigor
       # declaration, which produced three of redmine's artifacts from a single initializer. A name the bundled
       # (non-project) environment already knows is not ours to call unused. The project's own `sig/` is
       # deliberately excluded from this environment, so a project class that ships a signature stays owned.
+      #
+      # The cache store makes the environment a Marshal restore instead of a cold RBS build on every
+      # invocation — the same ADR-54 slot `rigor check` reads, keyed apart by this environment's own
+      # (sig-less) descriptor. The report only ever asks "is this name known", which the cached
+      # environment answers identically: the one thing the cache degrades is `RBS::Location`, and no
+      # location is read here.
       def foreign_predicate(configuration)
-        env = Environment.for_project(libraries: configuration.libraries, signature_paths: [])
+        env = Environment.for_project(libraries: configuration.libraries, signature_paths: [],
+                                      cache_store: cache_store(configuration))
         ->(fqn) { !env.singleton_for_name(fqn).nil? }
       rescue StandardError
         ->(_fqn) { false }
       end
 
+      # One store per run, shared by the environment build and the plugin-roots collection. Nil when the
+      # store cannot be opened — both consumers already treat a nil store as "recompute", which was this
+      # command's only mode before it had a cache at all.
+      def cache_store(configuration)
+        return @cache_store if defined?(@cache_store)
+
+        @cache_store = Cache::Store.new(root: configuration.cache_path)
+      rescue StandardError
+        @cache_store = nil
+      end
+
       # ADR-102 § Consequences — "a root source that OVER-supplies silently hides real dead code, which is
       # worse than one that under-supplies, so each plugin's contribution needs its own corpus check". A
       # supplied root naming a constant the project does not declare is inert in the graph, but it is the

data/lib/rigor/cli.rb

@@ -101,13 +101,26 @@ module Rigor
 
     def dispatch(command)
       handler = HANDLERS[command]
-      return send(handler) if handler
+      return arm_jit_deadline { send(handler) } if handler
 
       @err.puts("Unknown command: #{command}")
       @err.puts(help)
       EXIT_USAGE
     end
 
+    # Deferred YJIT for EVERY dispatched command, not just `check` / `coverage` where PR #75 first
+    # calibrated it. The deadline makes the decision command-independent: a run that finishes inside
+    # the window never pays JIT compile, and a run that outlasts it JITs its dominant tail — measured
+    # on `rigor effects` cold over Mastodon, which ran its whole 21 s interpreted while the same
+    # analysis under `check` took 14.8 s (forcing YJIT on the effects run: 15.9 s; disabling it on
+    # check: 21.1 s). `lsp` / `mcp` still call `Runtime::Jit.enable_now` at boot, which makes the
+    # deadline thread armed here a no-op when it later fires.
+    def arm_jit_deadline
+      require_relative "runtime/jit"
+      Runtime::Jit.enable_after(Runtime::Jit.deadline_seconds)
+      yield
+    end
+
     def run_check
       require_relative "cli/check_command"
 
@@ -367,13 +380,13 @@ module Rigor
           trace      Replay how the engine typed FILE as a terminal animation
           type-scan  Report Scope#type_of coverage across PATHs
           effects    Report each method's effect labels, and the committed effect snapshot
-                     (ADR-103, opt-in; effects update/check/diff/explain)
+                     (opt-in; effects update/check/diff/explain)
           explain    Print the description of one or all CheckRules
           diff       Compare current diagnostics to a saved baseline JSON
-          sig-gen    Emit RBS skeletons inferred from .rb sources (ADR-14)
+          sig-gen    Emit RBS skeletons inferred from .rb sources
           lsp        Run the Rigor Language Server (LSP) over stdio
-          mcp        Run the Rigor MCP server over stdio (ADR-33)
-          triage     Summarise diagnostics: distribution, hotspots, hints (ADR-23)
+          mcp        Run the Rigor MCP server over stdio
+          triage     Summarise diagnostics: distribution, hotspots, hints
           coverage   Report type-precision coverage (precise vs Dynamic ratio)
           plugins    Report activation status of every configured plugin
           plugin     Browse bundled plugin source as worked examples (list/path/print/root)
@@ -381,9 +394,9 @@ module Rigor
           describe   Recommend the next skill for this project (alias for `skill describe`)
           skill      Recommend the next skill + list/print bundled Agent Skills (skill describe, skill <name>)
           docs       Print the bundled docs offline (docs <name>, docs --list)
-          show-bleedingedge  Show the bleeding-edge overlay + what your config adopts (ADR-50)
-          doctor     Classify setup problems vs clean run with routed next actions (ADR-77)
-          upgrade    Migration command skeleton (ADR-50 WD7, queued)
+          show-bleedingedge  Show the bleeding-edge overlay + what your config adopts
+          doctor     Classify setup problems vs clean run with routed next actions
+          upgrade    Migration command skeleton (queued)
           version    Print the Rigor version
           help       Print this help
       HELP

data/lib/rigor/effects/definition_lines.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "method_key"
+
+module Rigor
+  module Effects
+    # Where a method key's `def` is written, resolved from the file the key was already traced to
+    # (#435).
+    #
+    # A drift row names the file out of `Runner#effect_sources`, which rides the cached summary entry
+    # and is therefore free. The **line** is not in any value the effects surfaces hold: the discovery
+    # tables {EnvelopeCheck::Positions} reads are built by one Prism parse of every project file, which
+    # is exactly what [ADR-104](../../../docs/adr/104-effects-boot-slim-probe.md) removed from this
+    # command — a warm `rigor effects check` is fast *because* it never parses the project.
+    #
+    # So this parses the drift's own files and nothing else: an index is built the first time a row asks
+    # about a path, and a report with no rows builds none. The cost is proportional to the drift, not to
+    # the project — the {EnvelopeCheck::DeferredPositions} shape (#479) applied one layer up, and the
+    # reason it can be one layer up is that the caller already knows the file.
+    #
+    # It is deliberately not a second discovery pass. It answers `def`s and only `def`s: a key whose
+    # method has no Ruby `def` at all — a synthesized accessor — keeps the file and loses the line,
+    # which is the same degradation `Positions` makes when it falls back to the class's own source.
+    class DefinitionLines
+      TOPLEVEL = "<toplevel>"
+      private_constant :TOPLEVEL
+
+      NO_LINES = {}.freeze
+      private_constant :NO_LINES
+
+      # @param key [String] an effect unit key — `Tracer::Loud#emit`, `Net::HTTP.get`.
+      # @param path [String] the file the key was traced to.
+      # @return [Integer, nil] the `def`'s line, or nil when this file does not spell that key with a
+      #   `def` — an unreadable file, a syntax error, and a synthesized method all land here.
+      def for(key:, path:)
+        index_for(path)[key]
+      end
+
+      private
+
+      def index_for(path)
+        @indexes ||= {}
+        @indexes[path] ||= build_index(path)
+      end
+
+      # First `def` wins: a file that reopens the same method twice has two lines and only one of them is
+      # where a reader starts.
+      def build_index(path)
+        result = Prism.parse_file(path.to_s)
+        return NO_LINES unless result.success?
+
+        {}.tap { |index| walk(result.value, [], singleton: false, index: index) }
+      rescue StandardError
+        NO_LINES
+      end
+
+      # The nesting is tracked, never resolved: `class Tracer::Loud` inside `module Tracer` spells a key
+      # this cannot see, and answering it would need the constant resolution an engine-free path does not
+      # have. A key it cannot spell keeps its file, which is what the row printed before this class existed.
+      def walk(node, nesting, singleton:, index:)
+        case node
+        when Prism::ModuleNode, Prism::ClassNode
+          name = constant_name(node.constant_path)
+          return if name.nil?
+
+          walk_children(node.body, nesting + [name], singleton: false, index: index)
+        when Prism::SingletonClassNode
+          walk_children(node.body, nesting, singleton: true, index: index)
+        when Prism::DefNode
+          record(node, nesting, singleton: singleton, index: index)
+          walk_children(node.body, nesting, singleton: singleton, index: index)
+        else
+          walk_children(node, nesting, singleton: singleton, index: index)
+        end
+      end
+
+      def walk_children(node, nesting, singleton:, index:)
+        node&.compact_child_nodes&.each { |child| walk(child, nesting, singleton: singleton, index: index) }
+      end
+
+      def record(node, nesting, singleton:, index:)
+        separator = singleton || node.receiver.is_a?(Prism::SelfNode) ? "." : "#"
+        owner = nesting.empty? ? TOPLEVEL : nesting.join("::")
+        key = "#{owner}#{separator}#{node.name}"
+        index[key] ||= node.location.start_line
+      end
+
+      def constant_name(node)
+        case node
+        when Prism::ConstantReadNode then node.name.to_s
+        when Prism::ConstantPathNode then node.full_name
+        end
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/rigor/effects/envelope_check.rb

@@ -83,6 +83,21 @@ module Rigor
         end
       end
 
+      # {Positions} behind a thunk: the discovery tables — one Prism parse of every project file —
+      # are built on the first `.for`, which both judgments reach only once a finding is being
+      # constructed. A clean judgment, the common CI case, therefore forces no discovery and parses
+      # nothing; that is the whole point of this class existing rather than the pass forcing the
+      # tables up front.
+      class DeferredPositions
+        def initialize(&build)
+          @build = build
+        end
+
+        def for(key)
+          (@positions ||= @build.call).for(key)
+        end
+      end
+
       NO_FINDINGS = [].freeze
       private_constant :NO_FINDINGS
 
@@ -93,7 +108,9 @@ module Rigor
       # @param class_envelopes [Hash{String => Envelope}] class- / module-level envelopes, to distribute.
       # @param config_envelopes [Hash{String => Envelope}] `effects.envelopes:` entries already resolved
       #   to the classes they select ({ConfigEnvelopes.for_classes}), to distribute at the lowest precedence.
-      # @param positions [Positions] the discovery tables a finding's `def` position is read from.
+      # @param positions [Positions, DeferredPositions] the discovery tables a finding's `def`
+      #   position is read from — consulted only when a finding is built, so a deferred value's
+      #   discovery force is reached exactly as often as a finding exists.
       # @param apply_tolerated [Boolean] false judges against the undischarged-by-policy `proven` lane —
       #   the `--no-tolerated-effects` audit switch.
       # @return [Array<Finding>] sorted by position then key then label, so a run explains identically twice.

data/lib/rigor/effects/liskov_check.rb

@@ -112,11 +112,13 @@ module Rigor
 
         inherited = envelopes.fetch(ancestor_key)
         own = envelopes[key]
-        position = positions.for(key)
+        # The position is read inside the two collectors, after they know a finding exists: `.for` is
+        # what forces a deferred position table, and an inherited envelope nothing widens must not
+        # cost a whole-project discovery parse.
         if own && !own.top?
-          collect_declared(findings, key, ancestor_key, inherited, own, position)
+          collect_declared(findings, key, ancestor_key, inherited, own, positions)
         else
-          collect_proven(findings, table, key, ancestor_key, inherited, position, apply_tolerated)
+          collect_proven(findings, table, key, ancestor_key, inherited, positions, apply_tolerated)
         end
       end
 
@@ -135,16 +137,19 @@ module Rigor
         nil
       end
 
-      def collect_proven(findings, table, key, ancestor_key, inherited, position, apply_tolerated)
+      def collect_proven(findings, table, key, ancestor_key, inherited, positions, apply_tolerated)
         entry = table[key]
         return if entry.nil?
 
         exceeding = inherited.exceeded_by(apply_tolerated ? entry.undischarged : entry.proven)
+        return if exceeding.empty?
+
+        path, line = positions.for(key)
         exceeding.each do |label|
           trail = PathFinder.shortest(table, symbol: key, label: label)
           findings << Finding.new(
             key: key, label: label, ancestor_key: ancestor_key, ancestor_envelope: inherited,
-            own_envelope: nil, path: position.first, line: position.last,
+            own_envelope: nil, path: path, line: line,
             chain: trail&.chain || [key].freeze, origin: trail&.origin
           )
         end
@@ -152,11 +157,15 @@ module Rigor
 
       # Two authored bounds, compared by subsumption alone. `mutate.local` is tolerated here as it is
       # everywhere, so declaring it under an inherited `%a{pure}` is not a widening.
-      def collect_declared(findings, key, ancestor_key, inherited, own, position)
-        own.bound.to_a.reject { |label| inherited.tolerates?(label) }.each do |label|
+      def collect_declared(findings, key, ancestor_key, inherited, own, positions)
+        widened = own.bound.to_a.reject { |label| inherited.tolerates?(label) }
+        return if widened.empty?
+
+        path, line = positions.for(key)
+        widened.each do |label|
           findings << Finding.new(
             key: key, label: label, ancestor_key: ancestor_key, ancestor_envelope: inherited,
-            own_envelope: own, path: position.first, line: position.last, chain: nil, origin: nil
+            own_envelope: own, path: path, line: line, chain: nil, origin: nil
           )
         end
       end

data/lib/rigor/effects/signature_sources.rb

@@ -21,10 +21,21 @@ module Rigor
       DEFAULT_ROOTS = ["sig"].freeze
 
       # A cheap text pre-filter for "does this source carry an effect annotation at all". It matches
-      # the two spellings the envelope reader honours and nothing else, so a signature tree with no
+      # the two payloads the envelope reader honours and nothing else, so a signature tree with no
       # effect annotation is answered by one regex per file and never parsed. It is a ROUTING test,
       # not the grammar — `RbsExtended.parse_effect_annotation` is still what decides meaning.
-      ANNOTATION_HINT = /%a\{\s*(?:pure\s*\}|rigor:v1:effect\b)/
+      #
+      # RBS accepts five bracket pairs for an annotation, and the reader sees only the text inside
+      # them, so the hint must accept all five too: routing on `%a{` alone made a `%a(pure)` project
+      # invisible to the run-cache probe, which then served the fast path while a bound existed —
+      # the silent-lane shape the #428 family is about. Over-matching (a mismatched closer) is safe:
+      # the cost is one declined fast path or one parsed file, never a missed bound.
+      ANNOTATION_BRACKETS = { "{" => "}", "(" => ")", "[" => "]", "|" => "|", "<" => ">" }.freeze
+      ANNOTATION_HINT = Regexp.union(
+        ANNOTATION_BRACKETS.map do |opener, closer|
+          /%a#{Regexp.escape(opener)}\s*(?:pure\s*#{Regexp.escape(closer)}|rigor:v1:effect\b)/
+        end
+      )
 
       # A `virtual:<plugin-id>:<source path>` buffer is rbs-inline's (or a plugin's) synthesized RBS for
       # a Ruby file the author actually wrote in. Naming that file is what a reader can act on, so the

data/lib/rigor/effects/snapshot.rb

@@ -38,7 +38,10 @@ module Rigor
     class Snapshot
       # Bumped when the file's shape changes in a way an older reader would misread. A bump makes every
       # existing file a regeneration event rather than a silent reinterpretation.
-      SCHEMA = 1
+      # 2 — `unresolved:` became a count (#434). A schema-1 file still loads, and its only reported
+      # difference is this field, so an existing project sees one regeneration line rather than a
+      # reinterpretation.
+      SCHEMA = 2
 
       HEADER = "# .rigor-effects.yml — generated by `rigor effects update`. Commit it; review its diff."
 
@@ -47,8 +50,16 @@ module Rigor
 
       # One row of either table.
       #
-      # `effects` and `declared` are sorted label arrays; `unresolved` is the sorted list of taint-cause
-      # renderings behind a false `exhaustive`, and is empty when the row is exhaustive.
+      # `effects` and `declared` are sorted label arrays; `unresolved` is HOW MANY taint causes sit behind
+      # a false `exhaustive`, and is zero when the row is exhaustive.
+      #
+      # A count rather than the causes themselves (#434). On redmine the cause renderings were 144,771 of
+      # the file's 293,276 bytes, on lines up to 821 characters — simultaneously the half a reviewer
+      # cannot read and the half that churns when an unrelated call moves. This file already makes that
+      # argument about origins ("a record keyed by them would churn on every refactor"); the causes are
+      # the same class of thing and were the one place it was not applied. What a reviewer needs from the
+      # record is the stable fact that the row is not exhaustive and by how much, which is what a count
+      # is; `rigor effects explain` names the causes on demand, against the live table.
       class Entry < Data.define(:key, :effects, :declared, :exhaustive, :unresolved)
         def exhaustive?
           exhaustive
@@ -61,7 +72,7 @@ module Rigor
           row = { "effects" => effects }
           row["declared"] = declared unless declared.empty?
           row["exhaustive"] = false unless exhaustive
-          row["unresolved"] = unresolved unless unresolved.empty?
+          row["unresolved"] = unresolved unless unresolved.zero?
           row
         end
 
@@ -73,10 +84,23 @@ module Rigor
             effects: string_list(row["effects"], key, "effects"),
             declared: string_list(row["declared"], key, "declared"),
             exhaustive: row.fetch("exhaustive", true) != false,
-            unresolved: string_list(row["unresolved"], key, "unresolved")
+            unresolved: unresolved_count(row["unresolved"], key)
           )
         end
 
+        # Tolerant of the schema-1 spelling, which was the list itself: the field's whole point now is a
+        # stable number, and a schema-1 file must LOAD so the header's own mismatch can be reported as
+        # the one regeneration event it is. Refusing to parse it would turn a migration into an error.
+        def self.unresolved_count(value, key)
+          case value
+          when nil then 0
+          when Integer then value
+          when Array then value.length
+          else raise ParseError, "#{key.inspect} unresolved: expected a count, got #{value.class}"
+          end
+        end
+        private_class_method :unresolved_count
+
         def self.string_list(value, key, field)
           return [].freeze if value.nil?
           raise ParseError, "#{key.inspect} #{field}: expected a list, got #{value.class}" unless value.is_a?(Array)
@@ -185,6 +209,29 @@ module Rigor
           parse(File.read(path, encoding: "UTF-8"))
         end
 
+        # A path as a reader sees it: project-relative when it is under the root, absolute when it is not.
+        #
+        # Public for the same reason {.render_causes} is — `reach:`'s entry-point globs and a drift row's
+        # source suffix (#435) must agree about what a project-relative path is, and a report that leaked
+        # `/private/tmp/nix-shell.../loud.rb` into a reviewer's terminal would be answering with this
+        # machine's layout rather than with the project's.
+        def relativize(path, project_root)
+          absolute = File.absolute_path(path.to_s)
+          root = "#{File.absolute_path(project_root.to_s).chomp('/')}/"
+          absolute.start_with?(root) ? absolute[root.length..] : absolute
+        end
+
+        # The taint causes as a reviewer reads them, from the closed enum of
+        # `docs/type-specification/effect-labels.md` — `dynamic-send`, `unresolved-self-call(save!)`.
+        #
+        # Public because two surfaces render the same causes and must not disagree about what one IS:
+        # a row's `unresolved:` count is the length of this list, and `rigor effects explain` prints the
+        # list itself for an `exhaustive → not` drift row (#434 / #435). One implementation, as WD3 asks.
+        def render_causes(causes)
+          causes.map { |cause, detail| detail.nil? || detail.empty? ? cause : "#{cause}(#{detail})" }
+                .uniq.sort.freeze
+        end
+
         private
 
         def parse_header(data)
@@ -241,12 +288,6 @@ module Rigor
           end
         end
 
-        def relativize(path, project_root)
-          absolute = File.absolute_path(path.to_s)
-          root = "#{File.absolute_path(project_root.to_s).chomp('/')}/"
-          absolute.start_with?(root) ? absolute[root.length..] : absolute
-        end
-
         # Each table takes the lanes at ITS own reading: `methods:` records the direct summary, so its
         # `declared:` is what this method's own body claims, and `reach:` records the transitive one, so
         # its `declared:` is the fixpoint's — a controller reaching an attributed gem call through two
@@ -261,19 +302,10 @@ module Rigor
             effects: proven.to_a,
             declared: declared.excluding_subsumed_by(proven).to_a,
             exhaustive: exhaustive,
-            unresolved: exhaustive ? [].freeze : render_causes(causes)
+            unresolved: exhaustive ? 0 : render_causes(causes).length
           )
         end
 
-        # `unresolved:` says why the row is not exhaustive, from the closed taint-cause enum of
-        # `docs/type-specification/effect-labels.md` — `dynamic-send`, `unresolved-self-call(save!)`. The
-        # design note sketched this field as "call names"; the collector keeps causes rather than names,
-        # and for the causes that have one the detail already IS the call name.
-        def render_causes(causes)
-          causes.map { |cause, detail| detail.nil? || detail.empty? ? cause : "#{cause}(#{detail})" }
-                .uniq.sort.freeze
-        end
-
         # A synthesised default summary — an `attr_*` writer's `mutate.self`, and the `Struct` / `Data`
         # accessors that join it when discovery synthesises them — carries no information a reviewer acts
         # on: it restates the `attr_accessor` line. Recognised by its origins being exactly the synthesised

data/lib/rigor/effects/snapshot_diff.rb

@@ -107,6 +107,7 @@ module Rigor
         @undischarged = undischarged
         @added_symbols = 0
         @removed_symbols = 0
+        @suppressed = 0
         @events = build_events.freeze
         freeze
       end
@@ -123,9 +124,16 @@ module Rigor
       end
 
       # Renames are a removal plus an addition and are never reported as a lost effect; the footer is
-      # where the reviewer sees that the two counts balance.
+      # where the reviewer sees that the two counts balance. `suppressed` is the per-symbol events a
+      # regeneration event withheld — zero on an ordinary comparison.
       def footer
-        { added_symbols: @added_symbols, removed_symbols: @removed_symbols }
+        { added_symbols: @added_symbols, removed_symbols: @removed_symbols, suppressed: @suppressed }
+      end
+
+      # Whether the two sides were computed under different rules (#434). The per-symbol comparison is
+      # then meaningless rather than merely noisy, which is why {#build_events} withholds it.
+      def regeneration?
+        @events.any? { |event| event.category == REGENERATION }
       end
 
       def events_for(table)
@@ -145,10 +153,25 @@ module Rigor
         ADDITIVE_CATEGORIES.include?(event.category)
       end
 
+      # A regeneration event withholds the per-symbol comparison rather than printing it (#434).
+      #
+      # The header says the record was written under different rules, so the two sides are not
+      # comparable — a claim this class already makes in its own documentation and then contradicted by
+      # emitting every row anyway. On redmine a moved `config_digest:` produced one regeneration line
+      # followed by 482 `-symbol` lines, none of which was a review signal: they say the recorded set was
+      # computed differently, which the header already said once.
+      #
+      # The table comparison still RUNS, because its per-symbol counters are what tell the reader the
+      # scale of what is withheld. Only the events are dropped.
       def build_events
         return [missing_snapshot_event] if @recorded.nil?
 
-        header_events + TABLES.flat_map { |table| table_events(table) }
+        header = header_events
+        table = TABLES.flat_map { |name| table_events(name) }
+        return table if header.empty?
+
+        @suppressed = table.length
+        header
       end
 
       def missing_snapshot_event

data/lib/rigor/inference/synthetic_method_scanner.rb

@@ -65,6 +65,13 @@ module Rigor
         registries = collect_trait_registries(plugin_registry)
         nested_templates = collect_nested_class_templates(plugin_registry)
         return SyntheticMethodIndex::EMPTY if templates.empty? && registries.empty? && nested_templates.empty?
+        # Tier B alone cannot emit without an environment: every trait entry — the direct route and the
+        # concern-re-targeted one — funnels through `module_instance_method_names`, whose first line
+        # answers `[]` for a nil environment. The production pre-pass passes `environment: nil` (#476),
+        # so a project whose only contributing plugin registers trait registries (rigor-devise on a
+        # Rails app) would otherwise pay a whole-project parse to build a provably empty index. This
+        # gate mirrors that nil guard and MUST be removed in the change that threads a real environment.
+        return SyntheticMethodIndex::EMPTY if environment.nil? && templates.empty? && nested_templates.empty?
 
         asts = parse_paths(paths, buffer: buffer)
         hierarchy = build_hierarchy(asts)

data/lib/rigor/rbs_extended/envelope_scanner.rb

@@ -2,6 +2,7 @@
 
 require "rbs"
 
+require_relative "../effects/signature_sources"
 require_relative "../rbs_extended"
 require_relative "reporter"
 
@@ -50,11 +51,19 @@ module Rigor
       #   `.rbs` files, plus the virtual entries rbs-inline and plugin `source_rbs` synthesis contribute.
       # @param registry [Rigor::Effects::Registry] the vocabulary an unknown label is judged against.
       # @return [Result]
+      #
+      # The `ANNOTATION_HINT` routing test runs here, before any parse: a source with no honoured
+      # payload can contribute neither an envelope nor an unresolved report, so a signature tree with
+      # no effect annotation is answered by one regex per file — which is what that hint's own
+      # documentation promises, and what every warm envelope-lane run was paying a full
+      # `RBS::Parser.parse_signature` per file for.
       def scan(sources:, registry:)
         reporter = Reporter.new
         methods = {}
         classes = {}
         sources.each do |name, content|
+          next unless Effects::SignatureSources::ANNOTATION_HINT.match?(content)
+
           declarations(name, content).each do |decl|
             walk(decl, [], methods, classes, registry, reporter)
           end