rigortype 0.3.7 → 0.3.9

data/lib/rigor/configuration.rb

@@ -117,6 +117,16 @@ module Rigor
         # `"stat"` (or `RIGOR_CI_DETECT=0`).
         "validation" => "auto"
       },
+      # ADR-39 slice 5 / #911 — the plugin-isolation strategy for target-library invocation. `nil` (the
+      # default) names nothing, leaving the choice to `RIGOR_PLUGIN_ISOLATION` and then to
+      # `Plugin::Isolation::DEFAULT`. The environment variable WINS over this key: it is the
+      # one-invocation operator override (`RIGOR_PLUGIN_ISOLATION=none rigor check` on a platform where
+      # the fork worker misbehaves), and an override a committed file can veto is not an override.
+      # Only `none` and `process` are selectable here — `ruby_box` needs `RUBY_BOX=1` set before Ruby
+      # boots, which is what `exe/rigor` re-execs for, and the launcher deliberately does not parse YAML
+      # before that re-exec (ADR-87 / ADR-104 boot-slim), so naming it here raises instead of silently
+      # resolving to a different strategy.
+      "plugins_isolation" => nil,
       "plugins_io" => {
         "network" => "disabled",
         "allowed_paths" => [],
@@ -212,6 +222,10 @@ module Rigor
     # reservation FINDABLE by the next person adding config validation (#166 is exactly that), and to
     # give the schema-parity spec something to key on: a reserved namespace is by definition absent
     # from DEFAULTS, so the DEFAULTS-driven schema gate can never see it.
+    # The isolation strategies a `.rigor.yml` may name (ADR-39 slice 5 / #911). `ruby_box` is
+    # deliberately absent: it is a boot-time decision the config file is read too late to make.
+    CONFIGURABLE_PLUGIN_ISOLATIONS = %w[none process].freeze
+
     RESERVED_NAMESPACES = %w[rigor_rs].freeze
 
     # Every top-level key a conforming `.rigor.yml` may carry: the keys this implementation owns, plus
@@ -238,6 +252,7 @@ module Rigor
     attr_reader :target_ruby, :paths, :exclude_patterns, :plugins, :cache_path, :cache_max_bytes,
                 :cache_validation, :disabled_rules,
                 :libraries, :signature_paths, :fold_platform_specific_paths, :parameter_inference,
+                :plugins_isolation,
                 :plugins_io_network, :plugins_io_allowed_paths,
                 :plugins_io_allowed_url_hosts,
                 :severity_profile, :severity_overrides,
@@ -466,7 +481,7 @@ module Rigor
 
     # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
     #
-    # @param effects_key_present [Boolean] ADR-103 WD15 — whether the file this `data` came from carried an
+    # @param effects_key_present — ADR-103 WD15 — whether the file this `data` came from carried an
     #   `effects:` key at all, independent of its value. Defaults to `data.key?("effects")`, which is the
     #   right answer for a caller that passes a raw (non-`DEFAULTS`-merged) hash directly — the common shape
     #   in specs — but is always `true` once `data` has been through `DEFAULTS.merge`, because `DEFAULTS`
@@ -520,6 +535,9 @@ module Rigor
       raw_max = cache.fetch("max_bytes")
       @cache_max_bytes = raw_max.nil? ? nil : Integer(raw_max)
       @cache_validation = coerce_cache_validation(cache.fetch("validation", "auto"))
+      @plugins_isolation = coerce_plugins_isolation(
+        data.fetch("plugins_isolation", DEFAULTS.fetch("plugins_isolation"))
+      )
       @plugins_io_network = coerce_network_policy(plugins_io.fetch("network"))
       @plugins_io_allowed_paths = Array(plugins_io.fetch("allowed_paths")).map(&:to_s).freeze
       @plugins_io_allowed_url_hosts = Array(plugins_io.fetch("allowed_url_hosts")).map(&:to_s).freeze
@@ -583,6 +601,7 @@ module Rigor
           "max_bytes" => cache_max_bytes,
           "validation" => cache_validation
         },
+        "plugins_isolation" => plugins_isolation,
         "plugins_io" => {
           "network" => plugins_io_network.to_s,
           "allowed_paths" => plugins_io_allowed_paths,
@@ -626,9 +645,8 @@ module Rigor
     #   the same checkout: a typo is a bug, and reading it as `false` would ship the feature permanently off
     #   with no signal.
     #
-    # @param id [String] a feature id from {BleedingEdge::FEATURES} or {BleedingEdge::GRADUATED}.
-    # @return [Boolean]
-    # @raise [ArgumentError] if `id` names no known feature.
+    # @param id — a feature id from {BleedingEdge::FEATURES} or {BleedingEdge::GRADUATED}.
+    # @raise ArgumentError — if `id` names no known feature.
     def bleeding_edge_active?(id)
       return true if BleedingEdge.graduated?(id)
       unless BleedingEdge.known_id?(id)
@@ -967,6 +985,27 @@ module Rigor
       VALID_CACHE_VALIDATIONS.include?(str) ? str : "auto"
     end
 
+    # Rejects rather than fails soft — a strategy that silently resolves to a different one is exactly
+    # the failure #911 exists to close, and the run's isolation is not a detail the user can be assumed
+    # not to have meant.
+    def coerce_plugins_isolation(value)
+      return nil if value.nil?
+
+      str = value.to_s
+      return str if CONFIGURABLE_PLUGIN_ISOLATIONS.include?(str)
+
+      if str == "ruby_box"
+        raise ConfigurationError,
+              "plugins_isolation: ruby_box cannot be selected from the configuration file — `Ruby::Box` " \
+              "must be active before Ruby boots. Run rigor with RIGOR_PLUGIN_ISOLATION=ruby_box instead " \
+              "(the launcher re-execs itself with RUBY_BOX=1 set)."
+      end
+
+      raise ConfigurationError,
+            "plugins_isolation must be one of #{CONFIGURABLE_PLUGIN_ISOLATIONS.inspect} " \
+            "(`ruby_box` is environment-only), got #{value.inspect}"
+    end
+
     def coerce_network_policy(value)
       sym = value.to_sym
       unless VALID_NETWORK_POLICIES.include?(sym)

data/lib/rigor/effects/attribution.rb

@@ -30,7 +30,7 @@ module Rigor
         @empty ||= new({})
       end
 
-      # @param table [Hash{String => Array<String>}] `Configuration#effects_attribution` — method key to
+      # @param table — `Configuration#effects_attribution` — method key to
       #   label list, both already shape-validated at load (tier 2).
       def self.build(table)
         return empty if table.nil? || table.empty?
@@ -49,8 +49,6 @@ module Rigor
 
       # The labels attributed to a method key (`Net::HTTP.get`), or nil when the table says nothing about
       # it. The key is spelled by the caller, which already builds the same string for the catalogue.
-      #
-      # @return [LabelSet, nil]
       def [](key)
         @rows[key]
       end

data/lib/rigor/effects/config_envelopes.rb

@@ -69,9 +69,8 @@ module Rigor
 
       # Resolves `Configuration#effects_envelopes` against a registry.
       #
-      # @param entries [Array<Hash>] the loaded, shape-validated entries
-      # @param registry [Registry] the vocabulary, project extensions included
-      # @return [Array<Entry>]
+      # @param entries — the loaded, shape-validated entries
+      # @param registry — the vocabulary, project extensions included
       def build(entries:, registry:)
         entries.each_with_index.map do |entry, index|
           labels = Array(entry["effect"]).map(&:to_s)
@@ -86,11 +85,10 @@ module Rigor
 
       # The class-level envelopes the entries put on a project.
       #
-      # @param entries [Array<Entry>]
-      # @param class_names [Enumerable<String>] every class the run collected units for
-      # @param sources [Hash{String => Array<String>}] `Runner#effect_sources` — `{method key => [path]}`
-      # @param project_root [String] what `sources` paths are relativised against
-      # @return [Hash{String => Envelope}] one envelope per selected class, keyed by class name
+      # @param class_names — every class the run collected units for
+      # @param sources — `Runner#effect_sources` — `{method key => [path]}`
+      # @param project_root — what `sources` paths are relativised against
+      # @return one envelope per selected class, keyed by class name
       def for_classes(entries:, class_names:, sources: {}, project_root: Dir.pwd)
         return NO_ENVELOPES if entries.empty?
 

data/lib/rigor/effects/definition_lines.rb

@@ -3,6 +3,7 @@
 require "prism"
 
 require_relative "method_key"
+require_relative "../source/constant_path"
 
 module Rigor
   module Effects
@@ -30,9 +31,9 @@ module Rigor
       NO_LINES = {}.freeze
       private_constant :NO_LINES
 
-      # @param key [String] an effect unit key — `Tracer::Loud#emit`, `Net::HTTP.get`.
-      # @param path [String] the file the key was traced to.
-      # @return [Integer, nil] the `def`'s line, or nil when this file does not spell that key with a
+      # @param key — an effect unit key — `Tracer::Loud#emit`, `Net::HTTP.get`.
+      # @param path — the file the key was traced to.
+      # @return the `def`'s line, or nil when this file does not spell that key with a
       #   `def` — an unreadable file, a syntax error, and a synthesized method all land here.
       def for(key:, path:)
         index_for(path)[key]
@@ -62,10 +63,10 @@ module Rigor
       def walk(node, nesting, singleton:, index:)
         case node
         when Prism::ModuleNode, Prism::ClassNode
-          name = constant_name(node.constant_path)
-          return if name.nil?
+          inner = header_nesting(nesting, node.constant_path)
+          return if inner.nil?
 
-          walk_children(node.body, nesting + [name], singleton: false, index: index)
+          walk_children(node.body, inner, singleton: false, index: index)
         when Prism::SingletonClassNode
           walk_children(node.body, nesting, singleton: true, index: index)
         when Prism::DefNode
@@ -76,6 +77,24 @@ module Rigor
         end
       end
 
+      # A ROOTED header is the one case that needs no resolution to place: `::` re-anchors the declaration at
+      # the top level wherever it is written, exactly as `Source::ConstantPath.declaration_prefix` reads it
+      # for the engine's own walks. Prism's `full_name` KEEPS the `::`, so `class ::Rooted` inside
+      # `module Outer` was indexed under `Outer::::Rooted#m` — a key no caller spells, which cost the row
+      # its line while every unrooted sibling in the same file kept one
+      # ([#722](https://github.com/rigortype/rigor/issues/722) residue 4).
+      #
+      # nil propagates the refusal {#constant_name} makes, so a header naming no constant leaves the subtree
+      # unindexed rather than under a guessed name.
+      def header_nesting(nesting, constant_path)
+        name = constant_name(constant_path)
+        return nil if name.nil?
+
+        return nesting + [name] unless Source::ConstantPath.rooted?(constant_path)
+
+        [name.delete_prefix("::")]
+      end
+
       def walk_children(node, nesting, singleton:, index:)
         node&.compact_child_nodes&.each { |child| walk(child, nesting, singleton: singleton, index: index) }
       end

data/lib/rigor/effects/effect_table.rb

@@ -61,7 +61,6 @@ module Rigor
         @empty ||= new(EMPTY_ENTRIES)
       end
 
-      # @param entries [Hash{String => Entry}]
       def initialize(entries)
         @entries = entries.sort_by { |key, _| key }.to_h.freeze
         freeze

data/lib/rigor/effects/entry_points.rb

@@ -117,8 +117,6 @@ module Rigor
         # one message: the unregistered-preset error (#433) and the note `rigor effects update` prints
         # when `reach:` is empty (#436) have to give the same answer, and neither can hard-code a list
         # that moves with `plugins:`.
-        #
-        # @return [String]
         def availability
           if @presets.empty?
             return "no plugin in this project registers an entry-point preset — a preset is named by the " \

data/lib/rigor/effects/envelope_check.rb

@@ -61,7 +61,7 @@ module Rigor
         # It lives on the value rather than in {EnvelopeCheck} because {LiskovCheck} positions its
         # findings identically, and two spellings of "where the fix goes" would eventually disagree.
         #
-        # @return [Array(String, Integer)] `[path, line]`; `[nil, 1]` for a key with no owner.
+        # @return `[path, line]`; `[nil, 1]` for a key with no owner.
         def for(key)
           class_name, separator, selector = MethodKey.split(key)
           return [nil, 1] if class_name.nil?
@@ -103,17 +103,17 @@ module Rigor
 
       module_function
 
-      # @param table [EffectTable] the run's propagated graph.
-      # @param method_envelopes [Hash{String => Envelope}] per-method envelopes, as written.
-      # @param class_envelopes [Hash{String => Envelope}] class- / module-level envelopes, to distribute.
-      # @param config_envelopes [Hash{String => Envelope}] `effects.envelopes:` entries already resolved
+      # @param table — the run's propagated graph.
+      # @param method_envelopes — per-method envelopes, as written.
+      # @param class_envelopes — class- / module-level envelopes, to distribute.
+      # @param config_envelopes — `effects.envelopes:` entries already resolved
       #   to the classes they select ({ConfigEnvelopes.for_classes}), to distribute at the lowest precedence.
-      # @param positions [Positions, DeferredPositions] the discovery tables a finding's `def`
+      # @param positions — the discovery tables a finding's `def`
       #   position is read from — consulted only when a finding is built, so a deferred value's
       #   discovery force is reached exactly as often as a finding exists.
-      # @param apply_tolerated [Boolean] false judges against the undischarged-by-policy `proven` lane —
+      # @param apply_tolerated — false judges against the undischarged-by-policy `proven` lane —
       #   the `--no-tolerated-effects` audit switch.
-      # @return [Array<Finding>] sorted by position then key then label, so a run explains identically twice.
+      # @return sorted by position then key then label, so a run explains identically twice.
       def run(table:, method_envelopes:, class_envelopes:, config_envelopes: {},
               positions: Positions.empty, apply_tolerated: true)
         envelopes = distribute(table, method_envelopes, class_envelopes, config_envelopes)

data/lib/rigor/effects/envelope_index.rb

@@ -56,15 +56,13 @@ module Rigor
 
       # Reads every stratum this index serves, once per process.
       #
-      # @param configuration [Rigor::Configuration]
-      # @param plugin_facts [Rigor::Effects::PluginFacts, nil] the loaded plugins' effect contributions
+      # @param plugin_facts — the loaded plugins' effect contributions
       #   (#387); their `effect_labels:` join the vocabulary an annotation is read against, so a gem's
       #   `%a{rigor:v1:effect rails.activejob.enqueue}` resolves rather than reading as unknown.
-      # @param environment [Rigor::Environment, nil] the run's environment. Its loader supplies the
+      # @param environment — the run's environment. Its loader supplies the
       #   rbs-inline / plugin `virtual_rbs` buffers and the built RBS environment the accepted stratum is
       #   read from; without one, both are simply absent (the fail-quiet direction — a missing `≤` bound
       #   costs precision, never a finding).
-      # @return [EnvelopeIndex]
       def self.build(configuration:, environment: nil, plugin_facts: nil)
         # Required here rather than at the top of the file: the reader pulls in the whole
         # `RbsExtended` surface, and this build runs only under an `effects:` block.
@@ -122,10 +120,9 @@ module Rigor
 
       # The envelope bounding `owner`'s `selector`, or nil.
       #
-      # @param owner [String] the receiver's static class name, as the typer projected it
-      # @param singleton [Boolean] whether the call is `Owner.selector` rather than `Owner#selector`
-      # @param selector [String]
-      # @return [Envelope, nil] never a ⊤ envelope: a bound that bounds nothing is not a bound, and
+      # @param owner — the receiver's static class name, as the typer projected it
+      # @param singleton — whether the call is `Owner.selector` rather than `Owner#selector`
+      # @return never a ⊤ envelope: a bound that bounds nothing is not a bound, and
       #   importing it would both add nothing and discharge a taint on the strength of a typo.
       def [](owner, singleton, selector)
         return nil if owner.nil? || empty?

data/lib/rigor/effects/framework_units.rb

@@ -76,13 +76,11 @@ module Rigor
 
       # Every synthetic unit `class_name` earns, as `[key, Summary, edges]` triples.
       #
-      # @param class_name [String]
-      # @param instance_methods [Array<String>] the instance methods the class body defines, in source order
-      # @param macros [Hash{String=>Array<String>}] receiver-less class-body calls to their literal symbol
+      # @param instance_methods — the instance methods the class body defines, in source order
+      # @param macros — receiver-less class-body calls to their literal symbol
       #   arguments, as the scanner harvested them
-      # @param uniqueness [Boolean] whether the class body declares a uniqueness validator
-      # @param plugin_facts [PluginFacts]
-      # @param own_units [Hash{String=>Boolean}] the units the class body itself defines, keyed by the
+      # @param uniqueness — whether the class body declares a uniqueness validator
+      # @param own_units — the units the class body itself defines, keyed by the
       #   suffix a synthetic key carries (`"#save"`, `".create"`), each mapped to whether that body
       #   reaches `super`. Read by {.framework_row} and by nothing else.
       def synthesize(class_name:, instance_methods:, macros:, uniqueness:, plugin_facts:, own_units: {})

data/lib/rigor/effects/identity.rb

@@ -45,10 +45,9 @@ module Rigor
       # The effects identity as a hex digest — the form a store with no descriptor of its own (the ADR-46
       # incremental snapshot) carries alongside its payload, and compares verbatim on restore.
       #
-      # @param configuration [Rigor::Configuration]
-      # @param registry [Registry] the vocabulary whose version participates
-      # @param catalog [Catalog] the catalogue whose identity participates
-      # @return [String] hex SHA-256
+      # @param registry — the vocabulary whose version participates
+      # @param catalog — the catalogue whose identity participates
+      # @return hex SHA-256
       def digest(configuration:, registry: Registry.default, catalog: Catalog.default, plugin_facts: nil)
         Digest::SHA256.hexdigest(
           [
@@ -66,8 +65,7 @@ module Rigor
       # the analyzed-path set — for free, so "the effects identity is the diagnostics identity plus three
       # things" is a property of the code rather than a claim about it.
       #
-      # @param base [Cache::Descriptor] the run's diagnostics key descriptor
-      # @return [Cache::Descriptor]
+      # @param base — the run's diagnostics key descriptor
       def descriptor(base:, configuration:, registry: Registry.default, catalog: Catalog.default,
                      plugin_facts: nil)
         Cache::Descriptor.compose(

data/lib/rigor/effects/inline_anchor.rb

@@ -49,9 +49,9 @@ module Rigor
       SPELLING_PATTERN = /%a\{[^}]*\}/
       private_constant :SPELLING_PATTERN
 
-      # @param path [String] the buffer's readable path, as {SignatureSources.source_path} renders it.
-      # @param buffer [String] the synthesized RBS the position was read out of.
-      # @return [InlineAnchor, nil] nil when `path` is not a Ruby file — a real `.rbs` needs no mapping,
+      # @param path — the buffer's readable path, as {SignatureSources.source_path} renders it.
+      # @param buffer — the synthesized RBS the position was read out of.
+      # @return nil when `path` is not a Ruby file — a real `.rbs` needs no mapping,
       #   and its own line numbers are already the ones a reader can open.
       def self.for(path:, buffer:)
         return nil unless path.to_s.end_with?(RUBY_EXTENSION)
@@ -61,7 +61,7 @@ module Rigor
 
       # One-shot form, for a caller that holds a `[path, buffer, line]` triple and no anchor.
       #
-      # @return [Integer] the `.rb` line, or `buffer_line` unchanged when there is nothing to map.
+      # @return the `.rb` line, or `buffer_line` unchanged when there is nothing to map.
       def self.ruby_line(path:, buffer:, buffer_line:, spelling: nil)
         anchor = self.for(path: path, buffer: buffer)
         return buffer_line if anchor.nil?
@@ -75,10 +75,10 @@ module Rigor
         @ruby_lines = nil
       end
 
-      # @param buffer_line [Integer] 1-based, counting into the synthesized buffer.
-      # @param spelling [String, nil] the annotation's own text (`"%a{pure}"`); read off the buffer line
+      # @param buffer_line — 1-based, counting into the synthesized buffer.
+      # @param spelling — the annotation's own text (`"%a{pure}"`); read off the buffer line
       #   when the caller does not already hold it.
-      # @return [Integer] the 1-based line of the same annotation in the Ruby file.
+      # @return the 1-based line of the same annotation in the Ruby file.
       def line_for(buffer_line, spelling: nil)
         spelling = normalize(spelling) || spelling_at(buffer_line)
         return buffer_line if spelling.nil?

data/lib/rigor/effects/label_intent.rb

@@ -37,11 +37,10 @@ module Rigor
 
       # Whether reporting `token` as an unknown label is justified.
       #
-      # @param token [String] the spelling as written.
-      # @param registry [Rigor::Effects::Registry, nil] the vocabulary AFTER plugin load; `nil` (no
+      # @param token — the spelling as written.
+      # @param registry — the vocabulary AFTER plugin load; `nil` (no
       #   vocabulary at all) makes every token unjudgeable and therefore silent.
-      # @param siblings [Array<String>] the other tokens of the same list / the same config value.
-      # @return [Boolean]
+      # @param siblings — the other tokens of the same list / the same config value.
       def evident?(token, registry, siblings: [])
         return false if registry.nil?
         return false unless Label.valid?(token)

data/lib/rigor/effects/liskov_check.rb

@@ -56,16 +56,16 @@ module Rigor
 
       module_function
 
-      # @param table [EffectTable] the run's propagated graph.
-      # @param superclasses [Hash{String => Array<String>}] the collector's as-written superclass
+      # @param table — the run's propagated graph.
+      # @param superclasses — the collector's as-written superclass
       #   candidate lists (`FileCollection#superclasses`).
-      # @param method_envelopes [Hash{String => Envelope}] per-method envelopes, as written.
-      # @param class_envelopes [Hash{String => Envelope}] class- / module-level envelopes, to distribute.
-      # @param config_envelopes [Hash{String => Envelope}] `effects.envelopes:` entries already resolved
+      # @param method_envelopes — per-method envelopes, as written.
+      # @param class_envelopes — class- / module-level envelopes, to distribute.
+      # @param config_envelopes — `effects.envelopes:` entries already resolved
       #   to the classes they select.
-      # @param positions [EnvelopeCheck::Positions] where the override's `def` is.
-      # @param apply_tolerated [Boolean] false judges against `proven` — `--no-tolerated-effects`.
-      # @return [Array<Finding>] sorted by position then key then label.
+      # @param positions — where the override's `def` is.
+      # @param apply_tolerated — false judges against `proven` — `--no-tolerated-effects`.
+      # @return sorted by position then key then label.
       def run(table:, superclasses:, method_envelopes:, class_envelopes:, config_envelopes: {},
               positions: EnvelopeCheck::Positions.empty, apply_tolerated: true)
         # The distributed strata, over a base of the raw per-method annotations: a base class whose method

data/lib/rigor/effects/method_key.rb

@@ -14,7 +14,7 @@ module Rigor
     module MethodKey
       module_function
 
-      # @return [Array(String, String, String), nil] `[owner, separator, selector]`, or nil when `key` is
+      # @return `[owner, separator, selector]`, or nil when `key` is
       #   not a method key at all.
       def split(key)
         text = key.to_s

data/lib/rigor/effects/plugin_facts.rb

@@ -77,11 +77,10 @@ module Rigor
         @empty ||= new(contributions: [], superclasses: NO_ROWS, includes: NO_ROWS)
       end
 
-      # @param plugin_registry [Rigor::Plugin::Registry, nil]
-      # @param superclasses [Hash{String=>String,Array<String>}] the project's as-written superclass table
+      # @param superclasses — the project's as-written superclass table
       #   (`Scope::DiscoveryIndex#discovered_superclasses`). Empty is legal and simply means no row matches
       #   through inheritance.
-      # @param includes [Hash{String=>Array<String>}] the project's as-written include / prepend table
+      # @param includes — the project's as-written include / prepend table
       #   (`Scope::DiscoveryIndex#discovered_includes`), for the frameworks whose contract is a module
       #   rather than a base class (#456).
       def self.build(plugin_registry, superclasses: NO_ROWS, includes: NO_ROWS)
@@ -144,9 +143,8 @@ module Rigor
 
       # The row colouring `owner`'s `selector`, found on `owner` itself or on a project ancestor of it.
       #
-      # @param owner [String, nil] the receiver's class name as the syntax or the typer named it
-      # @param singleton [Boolean] whether the call is `Owner.selector`
-      # @return [Row, nil]
+      # @param owner — the receiver's class name as the syntax or the typer named it
+      # @param singleton — whether the call is `Owner.selector`
       def class_row(owner, singleton, selector)
         return nil if owner.nil? || @class_rows.empty?
 

data/lib/rigor/effects/propagator.rb

@@ -45,10 +45,9 @@ module Rigor
 
       module_function
 
-      # @param collection [FileCollection] the run's merged per-file collections
-      # @param discharge [Discharge] the `effects.tolerated:` policy the undischarged lane is computed
+      # @param collection — the run's merged per-file collections
+      # @param discharge — the `effects.tolerated:` policy the undischarged lane is computed
       #   under; {Discharge.none} makes the two lanes equal.
-      # @return [EffectTable]
       def propagate(collection, discharge: Discharge.none)
         return EffectTable.empty if collection.summaries.empty?
 

data/lib/rigor/effects/scanner.rb

@@ -184,7 +184,7 @@ module Rigor
       # per unit (ADR-103 WD13): a unit the scanner cannot finish is recorded as non-exhaustive with
       # `collector-error` and its siblings are unaffected.
       #
-      # @return [UnitScan, nil] the finished scan, or nil when the unit failed soft
+      # @return the finished scan, or nil when the unit failed soft
       def add_unit(class_name, method_name, singleton, body, parameters)
         key = "#{class_name}#{singleton ? '.' : '#'}#{method_name}"
         names = parameter_names(parameters)

data/lib/rigor/effects/signature_sources.rb

@@ -52,9 +52,8 @@ module Rigor
         stripped.start_with?(root) ? stripped[root.length..] : stripped
       end
 
-      # @param signature_paths [Array<String>, nil] the configured roots; empty / nil takes the default.
-      # @param virtual_rbs [Array<Array(String, String)>, nil] the loader's virtual entries.
-      # @return [Array<Array(String, String)>]
+      # @param signature_paths — the configured roots; empty / nil takes the default.
+      # @param virtual_rbs — the loader's virtual entries.
       def collect(signature_paths:, virtual_rbs: nil)
         files = roots(signature_paths).flat_map { |root| Dir.glob(File.join(root.to_s, "**", "*.rbs")).sort }
         sources = files.filter_map do |path|
@@ -76,8 +75,7 @@ module Rigor
       # residual reports one annotation per run, so the carrier a run holds past the environment's own
       # lifetime is a single synthesized buffer rather than the project's whole virtual tree.
       #
-      # @param virtual_rbs [Array<Array(String, String)>, nil]
-      # @return [Array<Array(String, String)>] zero or one pair.
+      # @return zero or one pair.
       def annotated_carrier(virtual_rbs)
         Array(virtual_rbs).each do |name, content|
           return [[name.to_s, content.to_s]] if ANNOTATION_HINT.match?(content)

data/lib/rigor/effects/snapshot.rb

@@ -117,12 +117,12 @@ module Rigor
       class << self
         # Builds the snapshot a run's effect table describes.
         #
-        # @param table [EffectTable] the propagated graph
-        # @param configuration [Rigor::Configuration] supplies the reach globs and the digested block
-        # @param sources [Hash{String=>Array<String>}] `Runner#effect_sources` — where each unit is defined
-        # @param full [Boolean] keep the rows {#omit?} drops
-        # @param registry [Registry] the vocabulary whose version the header carries
-        # @param project_root [String] what `sources` paths are relativised against for glob matching
+        # @param table — the propagated graph
+        # @param configuration — supplies the reach globs and the digested block
+        # @param sources — `Runner#effect_sources` — where each unit is defined
+        # @param full — keep the rows {#omit?} drops
+        # @param registry — the vocabulary whose version the header carries
+        # @param project_root — what `sources` paths are relativised against for glob matching
         def build(table:, configuration:, sources: {}, full: false, registry: Registry.default,
                   project_root: Dir.pwd)
           globs = expand_reach(configuration.effects_snapshot_reach)
@@ -146,10 +146,10 @@ module Rigor
         # It is built beside the snapshot and never inside it: the file stays flat and undischarged, and
         # this index exists only for the duration of one comparison ({SnapshotDiff}).
         #
-        # @param snapshot [Snapshot] the current side, already built
-        # @param table [EffectTable] the run that produced it
-        # @param discharge [Discharge] the policy
-        # @return [Hash, nil] nil when the policy discharges nothing, which is the common case
+        # @param snapshot — the current side, already built
+        # @param table — the run that produced it
+        # @param discharge — the policy
+        # @return nil when the policy discharges nothing, which is the common case
         def undischarged_index(snapshot:, table:, discharge:)
           return nil if discharge.inert?
 

data/lib/rigor/effects/snapshot_diff.rb

@@ -86,7 +86,7 @@ module Rigor
       # Compares `current` against `recorded`. `recorded` may be nil — no snapshot on disk at all, which
       # is drift with a routed message rather than an error.
       #
-      # @param undischarged [Hash] `{table name => {symbol => [label]}}` — the current side's labels that
+      # @param undischarged — `{table name => {symbol => [label]}}` — the current side's labels that
       #   survive per-origin discharge ({Snapshot.undischarged_index}). Optional; omitting it judges every
       #   event by label.
       def self.compare(recorded:, current:, tolerated: [], gate: :symmetric, strict_tolerated: false,

data/lib/rigor/effects/unit_scan.rb

@@ -87,7 +87,7 @@ module Rigor
       # the enclosing method contains. A non-literal name has no key to file the block under, so it stays
       # contained in the enclosing method and this returns nil.
       #
-      # @return [Array, nil] `[name, singleton, body, parameters]`
+      # @return `[name, singleton, body, parameters]`
       def self.define_method_unit(node)
         return nil unless node.name == :define_method && node.receiver.nil?
 
@@ -100,17 +100,17 @@ module Rigor
         [first.unescaped, false, block.body, block.parameters]
       end
 
-      # @param singleton [Boolean] whether the unit's `self` is the class object (`def self.x`,
+      # @param singleton — whether the unit's `self` is the class object (`def self.x`,
       #   `class << self`) — the axis that separates `mutate.self` from `mutate.static` on an ivar write
-      # @param block_parameter [String, nil] the unit's `&blk` parameter name, if any; a call on it is
+      # @param block_parameter — the unit's `&blk` parameter name, if any; a call on it is
       #   forwarding, not an opaque callable
-      # @param calls [Hash] node-identity table of {Collector::CallRecord}s
-      # @param attribution [Attribution] the project's `effects.attribution:` table
-      # @param envelopes [EnvelopeIndex] the envelopes a call site may import as a `≤` bound (#386)
-      # @param plugin_facts [PluginFacts] the loaded plugins' `effect_attributions:` (#387)
-      # @param owner_class [String, nil] the class this unit is defined on — the carrier an
+      # @param calls — node-identity table of {Collector::CallRecord}s
+      # @param attribution — the project's `effects.attribution:` table
+      # @param envelopes — the envelopes a call site may import as a `≤` bound (#386)
+      # @param plugin_facts — the loaded plugins' `effect_attributions:` (#387)
+      # @param owner_class — the class this unit is defined on — the carrier an
       #   implicit-self call's envelope is looked up under, since the syntax spells `Kernel#name`
-      # @param method_name [String, nil] this unit's own selector — what a `super` in its body names as
+      # @param method_name — this unit's own selector — what a `super` in its body names as
       #   the target the propagator resolves above `owner_class` (#446). With no name to state, a `super`
       #   taints instead.
       def initialize(singleton:, parameters:, block_parameter:, owned_locals:, calls:, # rubocop:disable Metrics/ParameterLists
@@ -283,7 +283,7 @@ module Rigor
       # Three receiver shapes, tried nearest-syntax first — a written receiver path (`Rails.cache.read`),
       # a receiver rooted at implicit self inside a framework class (`session[:x] = 1`), and the receiver's
       # class through the project's inheritance chain (`user.save`).
-      # @return [PluginFacts::Row, nil] the row that claimed this call, for {#visit_call} to read as a bound
+      # @return the row that claimed this call, for {#visit_call} to read as a bound
       def attribute_plugin(node, record)
         return nil unless @plugin_facts.attributions?
 

data/lib/rigor/effects/unknown_label_check.rb

@@ -30,10 +30,6 @@ module Rigor
 
       module_function
 
-      # @param method_envelopes [Hash{String => Envelope}]
-      # @param class_envelopes [Hash{String => Envelope}]
-      # @param registry [Rigor::Effects::Registry]
-      # @return [Array<Finding>]
       def for_envelopes(method_envelopes:, class_envelopes:, registry:)
         seen = {}
         declarations(method_envelopes, class_envelopes).each do |envelope|
@@ -49,10 +45,9 @@ module Rigor
         seen.values
       end
 
-      # @param labels [Array<String>] the list as written, in source order.
-      # @param key_path [String] the `.rigor.yml` key, for the message (`effects.tolerated`).
-      # @param consequence [String] what the degradation cost, for the message.
-      # @return [Array<Finding>]
+      # @param labels — the list as written, in source order.
+      # @param key_path — the `.rigor.yml` key, for the message (`effects.tolerated`).
+      # @param consequence — what the degradation cost, for the message.
       def for_config(labels:, key_path:, consequence:, registry:)
         tokens = Array(labels).map(&:to_s)
         tokens.filter_map do |token|