rigortype 0.3.3 → 0.3.4

data/lib/rigor/analysis/rule_catalog.rb

@@ -728,6 +728,164 @@ module Rigor
           since: "0.3.0"
         ),
 
+        CheckRules::RULE_EFFECT_ENVELOPE_EXCEEDED => Entry.new(
+          id: CheckRules::RULE_EFFECT_ENVELOPE_EXCEEDED,
+          summary: "A method performs an effect its declared envelope does not admit.",
+          fires_when: [
+            "The project's `.rigor.yml` carries an `effects:` block and `effects.check` is on (it " \
+            "defaults to on when the block is present).",
+            "The method's RBS carries an envelope — `%a{pure}` (the empty bound) or " \
+            "`%a{rigor:v1:effect <labels>}` — written on the method, or on its class / module and " \
+            "distributed to it.",
+            "The method's PROVEN effect labels — its own body plus the transitive closure over the " \
+            "project methods it calls — include a label no member of the bound subsumes."
+          ],
+          does_not_fire_when: [
+            "No `effects:` block is configured, or `effects.check: false` is set — an annotation " \
+            "alone never turns the check on.",
+            "The exceeding label is `mutate.local`: mutating what the frame itself allocated and " \
+            "never let escape is tolerated by every envelope, `%a{pure}` included.",
+            "The label is only suspected rather than proven — an unresolved or dynamic call taints " \
+            "the summary's exhaustiveness bit and contributes nothing to the proven lane, so " \
+            "\"possibly more\" never produces a finding.",
+            "The envelope names a label the effect registry does not recognise (a typo, a retired " \
+            "spelling): the whole tag then reads as unbounded, which suppresses findings rather " \
+            "than inventing them.",
+            "The envelope was written on a supertype rather than on this class — the inherited-bound " \
+            "(Liskov) reading is `effect.liskov-widened`.",
+            "The envelope was written outside the project's own `signature_paths:` RBS (core, a " \
+            "gem's shipped RBS): only project-authored envelopes are checked. Such an envelope is " \
+            "still imported as a `≤` bound at calls INTO it, which produces no finding."
+          ],
+          suppression: "`# rigor:disable effect.envelope-exceeded` on the Ruby `def` line (the " \
+                       "diagnostic is positioned there, not on the `.rbs` line), or " \
+                       "`disable: [\"effect.envelope-exceeded\"]` in `.rigor.yml`. Widening or " \
+                       "removing the envelope is the real fix.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :warning, balanced: :warning, strict: :error },
+          # FP-safe by two accepted constructions at once: opt-in by author directive (the envelope IS
+          # the directive, so a firing is never unsolicited — the `conforms-to` construction) and
+          # as-strict-as-proven (the proven lane only; taint never fires). What it costs to be wrong is
+          # bounded by the author having asked the question.
+          evidence_tier: :high,
+          since: "0.3.4"
+        ),
+
+        CheckRules::RULE_EFFECT_LISKOV_WIDENED => Entry.new(
+          id: CheckRules::RULE_EFFECT_LISKOV_WIDENED,
+          summary: "An override performs or declares an effect the envelope it inherits does not admit.",
+          fires_when: [
+            "The project's `.rigor.yml` carries an `effects:` block and `effects.check` is on (it " \
+            "defaults to on when the block is present).",
+            "A method the project defines redefines a method of a SUPERCLASS, and that ancestor's " \
+            "definition carries an envelope — written on it, distributed from its class, or put " \
+            "there by an `effects.envelopes:` convention. The nearest enveloped ancestor wins.",
+            "The override declares NO envelope of its own and its PROVEN effect labels — its body " \
+            "plus the transitive closure over the project methods it calls — include a label the " \
+            "inherited bound does not admit.",
+            "Or the override declares its OWN envelope and that bound is wider than the inherited " \
+            "one. This half is proven-independent: two authored bounds, compared by subsumption."
+          ],
+          does_not_fire_when: [
+            "No `effects:` block is configured, or `effects.check: false` is set.",
+            "Nobody wrote an envelope on the overridden method. The check is both-sides-authored: " \
+            "an override alone can never produce it.",
+            "The override is purer than the bound it inherits — that is the whole point of an upper " \
+            "bound, and a narrower envelope on an override is correct by construction.",
+            "The relation is a module include rather than a subclass. An includer's own `def` sits " \
+            "AHEAD of the module's in Ruby's ancestry rather than under it, so the substitutability " \
+            "argument that licenses this check does not apply.",
+            "The exceeding label is `mutate.local`, or the label is only suspected rather than " \
+            "proven: an unresolved or dynamic call taints exhaustiveness and contributes nothing to " \
+            "the proven lane.",
+            "The ancestor's envelope names a label the registry does not recognise: the whole tag " \
+            "reads as unbounded, which suppresses findings rather than inventing them."
+          ],
+          suppression: "`# rigor:disable effect.liskov-widened` on the override's Ruby `def` line, or " \
+                       "`disable: [\"effect.liskov-widened\"]` in `.rigor.yml`. Widening the " \
+                       "ancestor's envelope — or moving the effect out of the override — is the real " \
+                       "fix.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :warning, balanced: :warning, strict: :error },
+          # Both-sides-authored in the ADR-35 sense — an envelope on the ancestor is the directive, and
+          # the override is a `def` the project wrote — and as strict as proven on the half that reads a
+          # body at all. The other half compares two authored bounds and reads nothing inferred.
+          evidence_tier: :high,
+          since: "0.3.4"
+        ),
+
+        CheckRules::RULE_EFFECT_UNKNOWN_LABEL => Entry.new(
+          id: CheckRules::RULE_EFFECT_UNKNOWN_LABEL,
+          summary: "An effect declaration names a label the registry does not recognise, so it " \
+                   "bounds nothing.",
+          fires_when: [
+            "The project's `.rigor.yml` carries an `effects:` block and `effects.check` is on — the " \
+            "same gate as `effect.envelope-exceeded`, because opting into envelope enforcement is " \
+            "what turns on the diagnostic that says an envelope stopped enforcing.",
+            "A `%a{rigor:v1:effect <labels>}` envelope — in `.rbs`, or written as an rbs-inline " \
+            "`# @rbs %a{…}` comment — names a token the effect registry does not know after plugin " \
+            "load, which makes the WHOLE tag read as unbounded (⊤), or an `effects.tolerated:` " \
+            "entry names one, which then tolerates nothing.",
+            "Label intent is evident from one of four signals: the spelling is within two edits of " \
+            "a known label, another member of the same list is known, the token carries two or " \
+            "more dot-separated segments, or the registry's retired table names it."
+          ],
+          does_not_fire_when: [
+            "No `effects:` block is configured, or `effects.check: false` is set.",
+            "The unrecognised token is a lone far-off word (`database`): a vocabulary is open by " \
+            "design, so a bare word nothing resembles is as likely to be a label this project has " \
+            "not registered as it is a typo. The tag still reads ⊤ — silence here is about the " \
+            "diagnostic, never about the reading.",
+            "The tag is malformed rather than unrecognised (`io/db`, an empty list): a grammar " \
+            "violation is a different condition, reported through the `RBS::Extended` conflict " \
+            "channel.",
+            "The label is registered — by the shared registry, by `effects.labels:`, or by a " \
+            "plugin that owns its root."
+          ],
+          suppression: "`disable: [\"effect.unknown-label\"]` in `.rigor.yml`, or a baseline entry. " \
+                       "A `# rigor:disable` comment works only where the diagnostic lands in a " \
+                       "`.rb` file (an rbs-inline annotation); Rigor does not read suppression " \
+                       "comments out of `.rbs` or `.rigor.yml`. Fixing the spelling is the real fix.",
+          severity_authored: :info,
+          severity_by_profile: { lenient: :info, balanced: :info, strict: :warning },
+          # Syntactic and author-directed at once: the token is provably outside the vocabulary, and
+          # the author wrote the declaration that names it. The intent gate is what keeps an open
+          # vocabulary from turning into noise.
+          evidence_tier: :high,
+          since: "0.3.4"
+        ),
+
+        CheckRules::RULE_EFFECT_ANNOTATIONS_UNCHECKED => Entry.new(
+          id: CheckRules::RULE_EFFECT_ANNOTATIONS_UNCHECKED,
+          summary: "Effect annotations are present, but no `effects:` block enables anything that " \
+                   "reads them.",
+          fires_when: [
+            "The project's own `signature_paths:` RBS carries a `%a{pure}` or " \
+            "`%a{rigor:v1:effect …}` annotation.",
+            "`.rigor.yml` carries no `effects:` block, so effect collection never runs and nothing " \
+            "checks those annotations. One diagnostic per run, positioned at the first such " \
+            "annotation."
+          ],
+          does_not_fire_when: [
+            "An `effects:` block is present — including `effects: {}` and `effects: {check: false}`, " \
+            "both of which are deliberate answers to the question this asks.",
+            "No project-authored effect annotation exists.",
+            "The annotation is written only as an rbs-inline `# @rbs %a{…}` comment and this run " \
+            "did not already have an RBS environment at hand: detecting it would mean building one " \
+            "on a surface that must stay free, so the residual stays quiet rather than paying for " \
+            "an `:info`."
+          ],
+          suppression: "Add an `effects:` block (`effects: {}` enables collection), or " \
+                       "`disable: [\"effect.annotations-unchecked\"]` in `.rigor.yml` to keep the " \
+                       "annotations documentary.",
+          severity_authored: :info,
+          severity_by_profile: { lenient: :info, balanced: :info, strict: :info },
+          # Purely a presence report about the project's own files — nothing is inferred, so there is
+          # no proof to be wrong about.
+          evidence_tier: nil,
+          since: "0.3.4"
+        ),
+
         CheckRules::RULE_SUPPRESSION_UNKNOWN_MARKER => Entry.new(
           id: CheckRules::RULE_SUPPRESSION_UNKNOWN_MARKER,
           summary: "A comment uses a suppression marker Rigor does not recognise " \

data/lib/rigor/analysis/run_cache_key.rb

@@ -37,6 +37,17 @@ module Rigor
 
       RUN_DIAGNOSTICS_PRODUCER_ID = "analysis.run-diagnostics"
 
+      # ADR-103 WD13 / issue #382 — the whole-run **effects sidecar**: the run's per-file effect
+      # collections, keyed by {Effects::Identity.descriptor} (this key descriptor plus the vocabulary
+      # version, the catalogue identity and the `effects:` digest) rather than by the descriptor above.
+      #
+      # A separate producer id, not a second section of the diagnostics entry, and that is the whole of
+      # "the diagnostics slot is never invalidated by effects": the two slots cannot share a fate when they
+      # do not share a file. It also keeps the ADR-87 boot-slim probe reading exactly the bytes it reads
+      # today — it peeks `analysis.run-diagnostics` and finds a plain diagnostics array, whatever a
+      # collecting run wrote elsewhere.
+      RUN_EFFECTS_PRODUCER_ID = "analysis.run-effects"
+
       # The run-result producer's declared compaction budget (`Cache::Store#evict!` pass 2). Whole-project,
       # but unlike the `rbs.*` producers several generations can be live at once: the `paths` key slot means
       # one entry per analyzed-path SET, so `rigor check` over the whole project, over `lib`, and over a
@@ -47,6 +58,11 @@ module Rigor
       # often an evicted generation is asked for again — see issue #151.
       GENERATION_CAP = 16
 
+      # The effects sidecar's own compaction budget. One generation per (path set × effects identity), and
+      # only a project that opted in writes any at all, so it is sized as the diagnostics cap's shadow: a
+      # collecting project's path-set churn is the same churn, and over-evicting costs one recompute.
+      EFFECTS_GENERATION_CAP = GENERATION_CAP
+
       # @param rbs_config_entries [Array<Cache::Descriptor::ConfigEntry>] the RBS-derived config slots
       #   (`rbs.libraries` [+ `rbs.virtual_rbs`]). nil on any failure so a malformed key disables the cache.
       def descriptor(configuration:, files:, explain:, rbs_config_entries:)

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Analysis
+    class Runner
+      # Where an `effect.unknown-label` finding is positioned (ADR-103 WD14; #384).
+      #
+      # The declaration, not the method: this is a fact about what the author wrote, and the fix is on
+      # that line. A `.rbs` position is the right answer here even though its sibling deliberately avoids
+      # one (the `rbs_extended.unsatisfied-conformance` precedent) — there is no Ruby `def` that could
+      # carry the typo. A value written in configuration has no location at all and lands at
+      # `.rigor.yml:1`, the `rbs.coverage.quarantined-signature` precedent.
+      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
+        # @return [Array(String, Integer)] `[path, line]`
+        def of(finding, sources: {})
+          location = finding.location
+          return [CONFIG_PATH, 1] if location.nil?
+
+          path, _, raw_line = location.rpartition(":")
+          return [CONFIG_PATH, 1] if path.empty?
+
+          line = raw_line.to_i
+          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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative "../diagnostic"
+require_relative "../check_rules"
+require_relative "../../effects/signature_sources"
+
+module Rigor
+  module Analysis
+    class Runner
+      # `effect.annotations-unchecked` — the ADR-103 WD13 commitment-1 residual (#384).
+      #
+      # WD13 fixes two rules that pull against each other: an annotation **must not** turn effect
+      # collection on (a `%a{pure}` written for Steep's benefit would otherwise impose a project-wide
+      # cost cliff on every run of every project that has one), and an annotation **must not** be
+      # silently inert either. One `:info` per run is the whole reconciliation: the declarations are
+      # there, nothing reads them, and `effects: {}` is the one-line answer.
+      #
+      # ## What it is allowed to cost
+      #
+      # This runs on the surface that is meant to be free — a project with no `effects:` block, which
+      # is every project by default — so the budget is a glob and a regex:
+      #
+      # - It reads the project's own `signature_paths:` `.rbs` tree (the same stratum the envelope
+      #   check reads) and matches {Effects::SignatureSources::ANNOTATION_HINT} line by line. No RBS
+      #   parse, no analysis, no environment build, and nothing at all when the tree does not exist.
+      # - It consults the run's virtual RBS — rbs-inline's `# @rbs %a{…}` — only when the run ALREADY
+      #   resolved an environment. Building one here to find an `:info` would cost more than the
+      #   `:info` is worth, so 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.
+      #
+      # It is computed OUTSIDE the cached run assembly for the same reason `EffectEnvelopePass` is:
+      # the `effects:` block is deliberately absent from the diagnostics cache identity, so a residual
+      # baked into that entry would survive the very edit that answers it.
+      class EffectAnnotationResidualPass
+        NO_DIAGNOSTICS = [].freeze
+        private_constant :NO_DIAGNOSTICS
+
+        RULE = CheckRules::RULE_EFFECT_ANNOTATIONS_UNCHECKED
+
+        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 " \
+                  "contract. Add `effects: {}` to have Rigor prove what your methods do and check " \
+                  "these bounds against it (ADR-103); an annotation alone never turns collection " \
+                  "on, because that would make one line in one signature file more expensive for " \
+                  "every run of the project."
+        private_constant :MESSAGE
+
+        # @param configuration [Rigor::Configuration]
+        # @param 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)
+          @configuration = configuration
+          @rbs_loader = rbs_loader
+        end
+
+        # @return [Array<Diagnostic>] zero or one.
+        def diagnostics
+          return NO_DIAGNOSTICS if @configuration.effects_enabled?
+          return NO_DIAGNOSTICS if @configuration.disabled_rules.include?(RULE)
+
+          sources = Effects::SignatureSources.collect(
+            signature_paths: @configuration.signature_paths, virtual_rbs: @rbs_loader&.virtual_rbs
+          )
+          return NO_DIAGNOSTICS if sources.empty?
+
+          found = Effects::SignatureSources.first_annotated(sources)
+          found.nil? ? NO_DIAGNOSTICS : [build_diagnostic(found)]
+        rescue StandardError
+          # Fail-soft, like every other effects surface: an advisory `:info` must never fail a run.
+          NO_DIAGNOSTICS
+        end
+
+        private
+
+        # Positioned at the first annotation itself rather than at `.rigor.yml:1`: the fix is a config
+        # edit, but the thing being reported is something the author wrote, and pointing at it is what
+        # tells them WHICH declaration is inert.
+        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
+          )
+        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
+end