rigortype 0.3.2 → 0.3.4

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

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

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

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

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