rigortype 0.3.4 → 0.3.6

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

@@ -30,11 +30,13 @@ module Rigor
       #
       # 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.
+      # 2. **Judge** ({Effects::EnvelopeCheck}). Cross-file discovery — the diagnostic is positioned
+      #    at the Ruby `def`, and the discovery tables are what map a method key to one — is forced
+      #    from inside the judgment, on the first finding built, so an envelope nothing exceeds costs
+      #    no discovery parse at all.
+      # 3. **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
@@ -80,7 +82,8 @@ module Rigor
         # @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.
+        #   `[def_sources, singleton_def_sources, class_sources]`. Called only when a finding needs a
+        #   position — a judged-clean envelope never forces it.
         # @param sources [Hash{String => String}] in-memory sources, for the buffer-backed run path.
         # @param unit_sources [Hash{String => Array<String>}] `Runner#effect_sources` — where each effect
         #   unit is defined, which is what an `effects.envelopes[].match:` path glob selects on. Its paths
@@ -220,7 +223,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
@@ -272,9 +275,12 @@ module Rigor
           )
         end
 
-        # The discovery tables both judgments position their findings from, forced once.
+        # The discovery tables both judgments position their findings from — behind a deferred value,
+        # forced at most once, on the first finding either judgment builds. A clean run (an envelope
+        # nothing exceeds — the common CI case) therefore never calls `@discovery` at all, which on a
+        # warm run is the difference between a no-op and a Prism parse of every project file.
         def positions
-          @positions ||= begin
+          @positions ||= Effects::EnvelopeCheck::DeferredPositions.new do
             def_sources, singleton_def_sources, class_sources = @discovery.call
             Effects::EnvelopeCheck::Positions.build(
               def_sources: def_sources, singleton_def_sources: singleton_def_sources,

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