rigortype 0.3.2 → 0.3.4

data/lib/rigor/analysis/reachability/scan.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../../source/constant_path"
+require_relative "../../source/node_children"
+
+module Rigor
+  module Analysis
+    module Reachability
+      # ADR-102 — the per-file half of the reference index: one Prism walk that records every constant
+      # DECLARATION and every constant REFERENCE, each with the lexical nesting in force at that point.
+      #
+      # This is deliberately NOT a hook on the typing path. `Reflection.resolve_constant_type` fires only where
+      # the engine needs a constant's *type*, so a constant that is read but never typed leaves no trace there —
+      # the #345 measurement found five distinct losses (cross-file value constants, parameter defaults,
+      # lambda-rvalue bodies, superclass positions, intermediate namespace segments) and produced 140 candidates
+      # of which zero were genuine. A reference index has to see every constant node regardless of whether a type
+      # was wanted, which is what this walk does.
+      #
+      # Names are recorded AS WRITTEN together with their nesting; resolution to a fully-qualified name happens
+      # in {Graph}, after every file has been scanned, because a bare `Foo` cannot be resolved until the whole
+      # declaration set is known.
+      module Scan
+        # A class / module declaration, or a constant assigned one of the meta-new forms. `nesting` is the
+        # enclosing declaration path at the declaration site, so `fqn` is exact.
+        Declaration = Data.define(:fqn, :path, :line, :superclass, :includes)
+
+        # One constant reference. `from` is the fully-qualified name of the innermost enclosing declaration, or
+        # nil for a reference written at file level — that is what makes the graph a reachability graph rather
+        # than a reference count (ADR-102 WD2). `role` is the referring FILE's role (WD8).
+        Reference = Data.define(:as_written, :nesting, :from, :role, :path, :line)
+
+        # ADR-102 WD4 — a site where a constant is reached by a mechanism the static reading cannot follow.
+        # `name` is the exact constant when the argument is a literal (`"Foo".constantize`), in which case this
+        # is as good as a reference. `prefix` is the namespace a dynamic construction can reach into
+        # (`"Foo::#{k}".constantize` → `"Foo"`, and `nil` when even that is unknown), which taints every
+        # declaration at or below it rather than proving any single one used.
+        DynamicUse = Data.define(:name, :prefix, :reason, :site, :path, :line)
+
+        Result = Data.define(:declarations, :references, :dynamic_uses)
+
+        # Roles a referring file can have (ADR-102 WD8). A reference edge carries its referrer's role so
+        # "used only by its own test" is a reportable category rather than a bucket boundary.
+        def self.role_for(path)
+          case path
+          when %r{(\A|/)(spec|test)/}, /_(spec|test)\.rb\z/ then :test
+          when /\.rake\z/, %r{(\A|/)(lib/)?tasks/} then :task
+          when %r{(\A|/)config/} then :config
+          else :production
+          end
+        end
+
+        # @param path [String] the file's path, as the report should render it.
+        # @param source [String] the file's bytes.
+        # @param target_ruby [String, nil] Prism version string, threaded from the project configuration.
+        # @return [Result, nil] nil when the file does not parse (a parse error is the analyzer's business, not
+        #   this scan's — it simply contributes nothing rather than half a file).
+        # A constant name is ASCII by construction, so a byte sequence that is not valid UTF-8 cannot be one.
+        # Dropping it is both correct and the only safe answer: carrying it forward crashed the whole run on
+        # the first `String#sub` downstream, which is how this surfaced — `rigor unused` on Rigor's own
+        # repository, which vendors a CRuby checkout containing deliberately ill-encoded encoding fixtures.
+        def self.usable_name(raw)
+          return nil if raw.nil?
+
+          name = raw.dup.force_encoding(Encoding::UTF_8)
+          name.valid_encoding? ? name : nil
+        end
+
+        def self.call(path:, source:, target_ruby: nil)
+          parsed = if target_ruby
+                     Prism.parse(source, filepath: path,
+                                         version: target_ruby)
+                   else
+                     Prism.parse(source, filepath: path)
+                   end
+          return nil unless parsed.success?
+
+          walker = Walker.new(path: path, role: role_for(path))
+          walker.walk(parsed.value, [])
+          Result.new(declarations: walker.declarations.freeze, references: walker.references.freeze,
+                     dynamic_uses: walker.dynamic_uses.freeze)
+        end
+
+        # Single-pass walker. Tracks `nesting` as the stack of enclosing declaration names.
+        class Walker
+          attr_reader :declarations, :references, :dynamic_uses
+
+          def initialize(path:, role:)
+            @path = path
+            @role = role
+            @declarations = []
+            @references = []
+            @dynamic_uses = []
+          end
+
+          def walk(node, nesting)
+            return unless node.is_a?(Prism::Node)
+
+            case node
+            when Prism::ClassNode  then return walk_declaration(node, nesting, superclass: node.superclass)
+            when Prism::ModuleNode then return walk_declaration(node, nesting, superclass: nil)
+            when Prism::ConstantReadNode, Prism::ConstantPathNode
+              record_reference(node, nesting)
+              # A constant path's segments are not separate references — `A::B::C` is one reference to the leaf,
+              # and descending would record `A` and `A::B` as references in their own right (22 spurious
+              # candidates on Rigor's own lib came from exactly that in the #345 probe).
+              return
+            when Prism::ConstantWriteNode
+              record_meta_new(node, nesting)
+              walk(node.value, nesting)
+              return
+            when Prism::CallNode
+              record_dynamic_use(node)
+            end
+
+            node.rigor_each_child { |child| walk(child, nesting) }
+          end
+
+          private
+
+          def walk_declaration(node, nesting, superclass:)
+            name = Source::ConstantPath.qualified_name(node.constant_path)
+            return node.rigor_each_child { |child| walk(child, nesting) } if name.nil?
+
+            fqn = (nesting + [name]).join("::")
+            # The superclass position IS a reference — `class Sub < Base` reads `Base` — and it resolves against
+            # the OUTER nesting, not inside the body being opened.
+            record_reference(superclass, nesting) if superclass
+            includes = node.body ? mixin_names(node.body) : []
+            @declarations << Declaration.new(fqn: fqn, path: @path, line: node.location.start_line,
+                                             superclass: superclass && Source::ConstantPath.qualified_name(superclass),
+                                             includes: includes.freeze)
+            walk(node.body, nesting + [name]) if node.body
+          end
+
+          # `Const = Class.new` / `Module.new` / `Data.define(...)` / `Struct.new(...)` declare a class under a
+          # constant, and `ScopeIndexer#record_class_new_constant_decl` already treats them as class declarations
+          # for cross-file resolution. The report must agree, or every such constant reads as an unreferenced
+          # value rather than a class.
+          META_NEW = { "Class" => :new, "Module" => :new, "Data" => :define, "Struct" => :new }.freeze
+          private_constant :META_NEW
+
+          def record_meta_new(node, nesting)
+            call = node.value
+            return unless call.is_a?(Prism::CallNode)
+
+            recv = call.receiver
+            return unless recv.is_a?(Prism::ConstantReadNode) && META_NEW[recv.name.to_s] == call.name
+
+            @declarations << Declaration.new(fqn: (nesting + [node.name.to_s]).join("::"), path: @path,
+                                             line: node.location.start_line, superclass: nil, includes: [].freeze)
+          end
+
+          # `include` / `prepend` / `extend` argument names written directly in the declaration body. Only the
+          # top level of the body is inspected: a mixin applied inside a conditional or a nested def is not a
+          # static ancestor edge.
+          def mixin_names(body)
+            body.child_nodes.filter_map do |stmt|
+              next unless stmt.is_a?(Prism::CallNode) && %i[include prepend extend].include?(stmt.name)
+              next if stmt.receiver
+
+              arg = stmt.arguments&.arguments&.first
+              arg && Source::ConstantPath.qualified_name_or_nil(arg)
+            end
+          end
+
+          # Names that turn a String into a constant. `constantize` / `safe_constantize` are ActiveSupport;
+          # `const_get` is core and may carry an explicit receiver (`Object.const_get`, `self.class.const_get`).
+          DYNAMIC_RESOLVERS = %i[constantize safe_constantize const_get].freeze
+          private_constant :DYNAMIC_RESOLVERS
+
+          SUBJECT_SHAPES = {
+            Prism::StringNode => "a literal string",
+            Prism::SymbolNode => "a literal symbol",
+            Prism::InterpolatedStringNode => "an interpolated string"
+          }.freeze
+          private_constant :SUBJECT_SHAPES
+
+          # Rigor knows the argument's shape, which is the whole reason this can be tiered rather than treated
+          # as a blanket namespace poison: a literal argument names the exact constant and is as good as a
+          # written reference, while an interpolated one can only bound the namespace it reaches into.
+          def record_dynamic_use(node)
+            return unless DYNAMIC_RESOLVERS.include?(node.name)
+
+            subject = node.name == :const_get ? node.arguments&.arguments&.first : node.receiver
+            return if subject.nil?
+
+            name, prefix = dynamic_target(subject)
+            # A literal whose bytes are not valid UTF-8 cannot name a constant; dropping it is the only safe
+            # answer, and carrying it forward crashed the whole run downstream.
+            return if subject.is_a?(Prism::StringNode) && name.nil?
+            return if subject.is_a?(Prism::SymbolNode) && name.nil?
+
+            @dynamic_uses << DynamicUse.new(
+              name: name, prefix: prefix, site: site(node), path: @path, line: node.location.start_line,
+              reason: "#{node.name} on #{SUBJECT_SHAPES.fetch(subject.class, 'a computed value')}"
+            )
+          end
+
+          # `[exact name, bounded namespace]` for a dynamic-resolution subject. A literal names its constant
+          # exactly; an interpolation can only bound the namespace its literal head names; anything else bounds
+          # nothing.
+          def dynamic_target(subject)
+            case subject
+            when Prism::StringNode, Prism::SymbolNode then [Scan.usable_name(subject.unescaped), nil]
+            when Prism::InterpolatedStringNode then [nil, literal_prefix(subject)]
+            else [nil, nil]
+            end
+          end
+
+          # The literal head of an interpolated name: `"Foo::Bar::#{k}"` bounds the reach to `Foo::Bar`. Returns
+          # nil when the interpolation starts the string, which bounds nothing.
+          def site(node)
+            "#{@path}:#{node.location.start_line}"
+          end
+
+          def literal_prefix(node)
+            head = node.parts.first
+            return nil unless head.is_a?(Prism::StringNode)
+
+            literal = Scan.usable_name(head.unescaped)
+            return nil if literal.nil?
+
+            trimmed = literal.sub(/::\z/, "")
+            trimmed.empty? ? nil : trimmed
+          end
+
+          def record_reference(node, nesting)
+            as_written = Source::ConstantPath.qualified_name_or_nil(node)
+            return if as_written.nil?
+
+            @references << Reference.new(as_written: as_written, nesting: nesting.dup.freeze,
+                                         from: nesting.empty? ? nil : nesting.join("::"),
+                                         role: @role, path: @path, line: node.location.start_line)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rigor/analysis/reachability/signature_scan.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "rbs"
+
+require_relative "scan"
+
+module Rigor
+  module Analysis
+    module Reachability
+      # ADR-102 WD7 / issue #363 — the RBS half of the reference corpus.
+      #
+      # A constant named only from the project's own `sig/` is genuinely referenced, which is why signatures
+      # are read at all: the #345 probe reported such constants as false candidates until an RBS-side hook was
+      # added. But a signature file also DECLARES, and the two must not be confused.
+      #
+      # The first implementation scanned each file for constant-shaped tokens, which cannot tell the
+      # difference. With `rbs-inline`-generated signatures — where every project class has a mirror
+      # declaration under `sig/` — that made a large fraction of the project unconditionally reachable: on one
+      # application 48 of 101 roots came from `sig/`, hiding seven candidates and ten test-only rows. Over-supply
+      # is the worse direction (an under-supplied root leaves a row where a human can see it; an over-supplied
+      # one removes it where nobody will), so this parses instead.
+      #
+      # The rule: a declaration's own name is a DECLARATION and contributes nothing. Every type name appearing
+      # in a POSITION — a superclass, a mixin argument, a parameter or return type, a constant's type, a type
+      # alias body, a generic argument — is a reference and counts.
+      module SignatureScan
+        module_function
+
+        # @param file [String] path to a `.rbs` file.
+        # @return [Array<Scan::Reference>] one file-level reference per distinct referenced name. Empty when the
+        #   file cannot be read or parsed — a broken signature is the analyzer's business, not this scan's.
+        def call(file)
+          _, _, decls = ::RBS::Parser.parse_signature(::RBS::Buffer.new(name: file, content: File.read(file)))
+          found = []
+          decls.each { |decl| walk(decl, [], found) }
+          found.uniq.map do |name, nesting|
+            Scan::Reference.new(as_written: name, nesting: nesting, from: nil, role: :config, path: file,
+                                line: 1)
+          end
+        rescue ::RBS::BaseError, SystemCallError, ArgumentError
+          []
+        end
+
+        # Walks a declaration, threading the lexical nesting so a name written relative to an enclosing module
+        # resolves the way the graph's own candidate walk expects. Without this, `module A; class B < C; end`
+        # would contribute a bare `C` that resolves against nothing.
+        def walk(node, nesting, out)
+          case node
+          when ::RBS::AST::Declarations::Class then walk_class(node, nesting, out)
+          when ::RBS::AST::Declarations::Module then walk_module(node, nesting, out)
+          when ::RBS::AST::Declarations::Interface
+            descend(node, nesting + segments(node.name), out)
+          when ::RBS::AST::Members::Include, ::RBS::AST::Members::Extend, ::RBS::AST::Members::Prepend
+            record(node.name, nesting, out)
+            node.args&.each { |arg| collect_types(arg, nesting, out) }
+          when ::RBS::AST::Members::MethodDefinition
+            node.overloads.each { |overload| collect_types(overload.method_type, nesting, out) }
+          when *TYPED_NODES
+            collect_types(node.type, nesting, out)
+          end
+        end
+
+        # Nodes whose whole contribution is the type they carry: a constant's or alias's right-hand side, and
+        # the attribute / variable families.
+        TYPED_NODES = [
+          ::RBS::AST::Declarations::Constant, ::RBS::AST::Declarations::TypeAlias,
+          ::RBS::AST::Members::AttrReader, ::RBS::AST::Members::AttrWriter,
+          ::RBS::AST::Members::AttrAccessor, ::RBS::AST::Members::InstanceVariable,
+          ::RBS::AST::Members::ClassInstanceVariable, ::RBS::AST::Members::ClassVariable
+        ].freeze
+
+        def walk_class(node, nesting, out)
+          record(node.super_class&.name, nesting, out)
+          node.super_class&.args&.each { |arg| collect_types(arg, nesting, out) }
+          descend(node, nesting + segments(node.name), out)
+        end
+
+        def walk_module(node, nesting, out)
+          node.self_types&.each { |self_type| record(self_type.name, nesting, out) }
+          descend(node, nesting + segments(node.name), out)
+        end
+
+        def descend(node, nesting, out)
+          node.members&.each { |member| walk(member, nesting, out) }
+        end
+
+        # Every `RBS::TypeName` reachable from a type, found reflectively. RBS's type zoo is wide (unions,
+        # intersections, tuples, records, optionals, procs, generics) and grows between releases; enumerating
+        # the classes would silently drop references the day a new one lands, and dropping a reference here
+        # manufactures a false candidate.
+        def collect_types(type, nesting, out)
+          return if type.nil?
+
+          record(type.name, nesting, out) if type.respond_to?(:name) && type.name.is_a?(::RBS::TypeName)
+          type.instance_variables.each do |ivar|
+            value = type.instance_variable_get(ivar)
+            case value
+            when ::RBS::TypeName then record(value, nesting, out)
+            when Array then value.each { |v| collect_types(v, nesting, out) }
+            when Hash then value.each_value { |v| collect_types(v, nesting, out) }
+            else collect_types(value, nesting, out) if value.respond_to?(:instance_variables)
+            end
+          end
+        end
+
+        # Records the name AS WRITTEN together with the nesting it was written under, and lets
+        # {Graph#resolve} do the lexical walk — the same walk it does for a name read out of Ruby source.
+        #
+        # An earlier version hand-built the qualified form instead (`"#{nesting}::#{bare}"`) on the reasoning
+        # that over-approximating which of absolute / relative / top-level a name is could only fail to remove
+        # a candidate. That was wrong, and it resurrected the very defect #363 fixed. `include Alba::Resource`
+        # inside `class SignageResource` produced `SignageResource::Alba::Resource`; the graph resolves a
+        # reference to a member as a reference to its owner, so it peeled that to `SignageResource::Alba` and
+        # then to `SignageResource` — a declaration. The reference is file-level, so the class rooted ITSELF,
+        # and three genuinely dead classes stayed out of the report on the project where this was found.
+        #
+        # Passing the real nesting cannot do that: the walk tries the qualified candidate, misses, and the peel
+        # then applies to the written name alone.
+        def record(type_name, nesting, out)
+          return if type_name.nil?
+
+          bare = type_name.to_s.delete_prefix("::")
+          return if bare.empty?
+
+          out << [bare, nesting.dup.freeze]
+        end
+
+        def segments(type_name)
+          type_name.to_s.delete_prefix("::").split("::")
+        end
+      end
+    end
+  end
+end

data/lib/rigor/analysis/rule_catalog.rb

@@ -660,6 +660,8 @@ module Rigor
             "The token resolves (canonical id, legacy alias, `all`, family wildcard, known engine id).",
             "The token starts with `plugin.` — plugins load dynamically, so their rule vocabulary cannot " \
             "be enumerated statically and under-warning is the FP-safe direction.",
+            "The marker does not open the comment (documentation prose quoting the syntax, a doubled " \
+            "`##` comment, or an `=begin` block) — that is not parsed as a suppression either.",
             "The comment merely mentions the marker followed by non-token text (documentation prose " \
             "like \"`# rigor:disable <rule>` comments\") — that is not parsed as a suppression either."
           ],
@@ -684,6 +686,7 @@ module Rigor
           does_not_fire_when: [
             "At least one token follows the marker (each token is then checked by " \
             "`suppression.unknown-rule` instead).",
+            "The marker does not open the comment (documentation prose quoting the syntax).",
             "Non-token text follows the marker (documentation prose mentioning the syntax)."
           ],
           suppression: "Complete the marker (`# rigor:disable <rule>` / `all`) or delete it; " \
@@ -725,12 +728,170 @@ 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 " \
                    "(`rigor:disable-next-line`, `rigor:enable`, ...).",
           fires_when: [
-            "A comment carries `rigor:disable-<suffix>` with a suffix other than `file`, or " \
+            "A comment OPENS with `rigor:disable-<suffix>` for a suffix other than `file`, or with " \
             "`rigor:enable[-<suffix>]` — typically the RuboCop reflex `# rigor:disable-next-line " \
             "<rule>` — followed by nothing or a rule-list-shaped remainder.",
             "Such a marker is invisible to the whole suppression grammar, so it silently suppresses " \
@@ -740,6 +901,7 @@ module Rigor
           does_not_fire_when: [
             "The marker is one of the two recognised forms (their tokens are then checked by " \
             "`suppression.unknown-rule` / `suppression.empty` instead).",
+            "The marker does not open the comment (documentation prose quoting the spelling).",
             "Non-token text follows the marker (documentation prose mentioning the spelling)."
           ],
           suppression: "Rewrite as `# rigor:disable <rules>` on the offending line (Rigor has no " \

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