rigortype 0.3.8 → 0.3.9

data/lib/rigor/cli.rb

@@ -12,6 +12,7 @@ require_relative "analysis/result"
 require_relative "cli/options"
 require_relative "cli/diagnostic_formats"
 require_relative "ci_detector"
+require_relative "analysis/check_rules/rule_ids"
 
 module Rigor
   # The CLI class is a dispatcher: each `run_*` method delegates to a command-specific class once the command grows
@@ -20,6 +21,21 @@ module Rigor
   class CLI # rubocop:disable Metrics/ClassLength
     EXIT_USAGE = 64
 
+    # Issue [#609](https://github.com/rigortype/rigor/issues/609) — a run the analyzer could not finish.
+    # Distinct from `1` (the analysis ran and reported diagnostics) so a CI step can tell "your code has
+    # findings" from "Rigor died and this report is not an account of anything".
+    EXIT_INTERNAL_ERROR = 70
+
+    # The exceptions that mean "the process is out of a resource, and the backtrace names nothing
+    # actionable": `SystemStackError` from an ancestry walk that never terminates, `NoMemoryError` from a
+    # runaway allocation. Neither is a `StandardError`, so every rescue between here and the raise site
+    # declines them by design — the whole point of those rescues is to convert a per-file or per-plugin
+    # failure into a diagnostic, and a process running out of stack is not per-file. Left uncaught they
+    # abort with Ruby's own ~40-frame dump, which is non-zero (so a CI gate does catch it) but says
+    # neither that Rigor is at fault nor that the report on disk is empty. `Interrupt`, `SignalException`
+    # and `SystemExit` stay out: those are the user's answer, not a failure.
+    FATAL_ERRORS = [SystemStackError, NoMemoryError].freeze
+
     # The published location of `schemas/rigor-config.schema.json`, written into the `.rigor.yml` that
     # `rigor init` generates so an editor validates the file as the user types.
     #
@@ -95,10 +111,28 @@ module Rigor
       # register presets have loaded) would each need their own rescue at their own point.
       @err.puts("rigor: #{e.message}")
       EXIT_USAGE
+    rescue *FATAL_ERRORS => e
+      report_fatal_error(e)
+      EXIT_INTERNAL_ERROR
     end
 
     private
 
+    # One `rigor:` line naming the failure, then the innermost frames — enough to route a bug report,
+    # without the full dump the raise would otherwise print. The "no report" sentence is the part a user
+    # acts on: the crash usually happens with a redirect in place, so the artifact a CI step goes on to
+    # read is an empty file rather than a missing one.
+    def report_fatal_error(error)
+      @err.puts("rigor: analysis aborted: #{error.class}: #{error.message}")
+      Array(error.backtrace).first(FATAL_BACKTRACE_FRAMES).each { |frame| @err.puts("  from #{frame}") }
+      @err.puts("  Rigor could not finish this run, so its report is EMPTY rather than clean — do not")
+      @err.puts("  read this exit status as a passing check.")
+      @err.puts("  This is a defect in Rigor; please report it at https://github.com/rigortype/rigor/issues.")
+    end
+
+    FATAL_BACKTRACE_FRAMES = 5
+    private_constant :FATAL_BACKTRACE_FRAMES
+
     def dispatch(command)
       handler = HANDLERS[command]
       return arm_jit_deadline { send(handler) } if handler
@@ -169,6 +203,30 @@ module Rigor
       @out.puts "  3. Run `rigor check` to analyse your code."
     end
 
+    # Word-wraps `CheckRules::ALL_RULES` into a comma-separated, `#`-commented block for `init_template`, so the
+    # listed rule ids cannot drift from the catalogue the way a hand-picked subset did (#920) — every rule and only
+    # a rule actually in `ALL_RULES` gets named here.
+    def rule_ids_comment
+      prefix = "#                "
+      max_width = 78 - prefix.length
+      ids = Analysis::CheckRules::ALL_RULES
+      lines = []
+      current = +""
+      ids.each_with_index do |id, index|
+        token = "#{id}#{index == ids.length - 1 ? '.' : ','}"
+        if current.empty?
+          current = token
+        elsif current.length + 1 + token.length <= max_width
+          current << " " << token
+        else
+          lines << current
+          current = token
+        end
+      end
+      lines << current unless current.empty?
+      lines.map { |line| "#{prefix}#{line}" }.join("\n")
+    end
+
     # Renders the starter `.rigor.yml` body. The template serialises `Configuration::DEFAULTS` (so the on-disk file
     # round-trips through `Configuration.load`) and prepends a short header that points the user at the keys they are
     # most likely to want to edit.
@@ -187,11 +245,10 @@ module Rigor
         #                See https://github.com/rigortype/rigor/tree/master/plugins
         #                for production plugins (rigor-activerecord, rigor-sorbet, …).
         # - disable:     list of `rigor check` rule identifiers to
-        #                silence project-wide. The shipped rules are
-        #                call.undefined-method, call.wrong-arity,
-        #                call.argument-type-mismatch,
-        #                call.possible-nil-receiver, dump.type,
-        #                assert.type-mismatch, flow.always-raises.
+        #                silence project-wide. Every rule id Rigor
+        #                ships (run `rigor explain <rule>` for what
+        #                each one catches):
+        #{rule_ids_comment}
         #                A bare family token (`call`, `flow`,
         #                `assert`, `dump`, `def`) wildcards every
         #                rule under that prefix. Legacy unprefixed
@@ -320,7 +377,10 @@ module Rigor
         @err.puts "Install it with: gem install rigor-playground"
         return EXIT_USAGE
       end
-      Rigor::CLI::PlaygroundCommand.new(@argv[1..], @out, @err).run
+      # `run` shifts the verb off `@argv` before dispatching, so the handler receives the arguments
+      # already. Slicing here dropped the first one — `rigor playground --port=4000` served the
+      # default port, and a bare `rigor playground` passed `nil` into a command that iterates it.
+      Rigor::CLI::PlaygroundCommand.new(@argv, @out, @err).run
     end
 
     def run_skill
@@ -383,11 +443,13 @@ module Rigor
                      (opt-in; effects update/check/diff/explain)
           explain    Print the description of one or all CheckRules
           diff       Compare current diagnostics to a saved baseline JSON
+          baseline   Manage the baseline file (baseline generate/regenerate/dump/drift/prune)
           sig-gen    Emit RBS skeletons inferred from .rb sources
           lsp        Run the Rigor Language Server (LSP) over stdio
           mcp        Run the Rigor MCP server over stdio
           triage     Summarise diagnostics: distribution, hotspots, hints
           coverage   Report type-precision coverage (precise vs Dynamic ratio)
+          unused     Report unreferenced classes, modules and constants as removal candidates
           plugins    Report activation status of every configured plugin
           plugin     Browse bundled plugin source as worked examples (list/path/print/root)
           playground Start the browser playground (requires rigor-playground gem)

data/lib/rigor/config_audit.rb

@@ -18,6 +18,11 @@ module Rigor
   # never written. This module surfaces each such entry up front so the cause is visible
   # instead of inferred.
   #
+  # {.bundled_plugin_signature_path_warnings} widens that by one step, to a value that
+  # resolves to *part* of what it looks like. It belongs here because the symptom is the
+  # same one — a cluster of `call.undefined-method` on working code, traceable to a config
+  # line nothing in the output names.
+  #
   # Every check is held to the same bar that {SignaturePathAudit} set: it mirrors the
   # loader's own acceptance test, so a warning means the loader really did load nothing, and
   # it never fires on a setup that works. In particular the rule-token check only flags a
@@ -27,8 +32,8 @@ module Rigor
   # a typo.
   module ConfigAudit
     # One config-level finding. `kind` discriminates the source key (`:signature_path`,
-    # `:library`, `:disabled_rule`, `:severity_override`, `:bundler_bundle_path`,
-    # `:bundler_lockfile`, `:rbs_collection_lockfile`); `fields` carries the kind-specific
+    # `:bundled_plugin_signature_path`, `:library`, `:disabled_rule`, `:severity_override`,
+    # `:bundler_bundle_path`, `:bundler_lockfile`, `:rbs_collection_lockfile`); `fields` carries the kind-specific
     # structured data merged into {#to_h} for JSON consumers.
     Warning = Data.define(:kind, :message, :fields) do
       def to_h
@@ -36,13 +41,12 @@ module Rigor
       end
     end
 
-    # @param configuration [Rigor::Configuration]
-    # @param project_root [String] the directory the run's relative bundler / collection
+    # @param project_root — the directory the run's relative bundler / collection
     #   paths resolve against (the CLI's CWD), used only by the explicit-path checks.
-    # @return [Array<Warning>]
     def self.warnings(configuration, project_root: Dir.pwd)
       unknown_key_warnings(configuration) +
         signature_path_warnings(configuration) +
+        bundled_plugin_signature_path_warnings(configuration) +
         library_warnings(configuration) +
         rule_token_warnings(configuration) +
         explicit_path_warnings(configuration, project_root)
@@ -100,6 +104,27 @@ module Rigor
       end
     end
 
+    # The one member of this module whose subject is a configured value that resolves to
+    # *something*: a `signature_paths:` entry loading a bundled plugin's own `sig/` while
+    # `plugins:` never names that plugin (issue #697). The RBS arrives, its manifest does not,
+    # and the declarations that manifest marks deliberately partial (ADR-26 `open_receivers:`)
+    # are then read as complete — so the symptom is this module's usual one, a cluster of
+    # high-confidence `call.undefined-method` firings on code that runs, with nothing pointing
+    # at the config line that caused them.
+    #
+    # It is a warning and not a fix on purpose. Teaching the check rules to recognise this
+    # route would be a fourth way for a class to be open-receiver protected, and settling
+    # where that membership belongs is [#660](https://github.com/rigortype/rigor/issues/660)'s
+    # question; until it is answered, the honest move is to make the misconfiguration loud
+    # rather than to grow the mechanism. The false positive itself still fires.
+    def self.bundled_plugin_signature_path_warnings(configuration)
+      routes = SignaturePathAudit.bundled_plugin_routes(configuration.signature_paths, configuration.plugins)
+      routes.map do |route|
+        Warning.new(kind: :bundled_plugin_signature_path, message: route.message,
+                    fields: { "path" => route.path, "gem" => route.gem })
+      end
+    end
+
     # `libraries:` entries RBS does not recognise. Uses the same
     # `RBS::EnvironmentLoader#has_library?` guard the loader filters through
     # ({Environment::RbsLoader} `build_env_for`), so a flagged name is exactly one the loader

data/lib/rigor/configuration/severity_profile.rb

@@ -167,20 +167,20 @@ module Rigor
       # Resolves the configured severity for a diagnostic given the active profile and any per-rule
       # overrides.
       #
-      # @param rule [String, nil] canonical rule id (`call.undefined-method`).
-      # @param authored_severity [Symbol] severity the rule emitted the diagnostic with (`:error`, `:warning`,
+      # @param rule — canonical rule id (`call.undefined-method`).
+      # @param authored_severity — severity the rule emitted the diagnostic with (`:error`, `:warning`,
       #   `:info`).
-      # @param profile [Symbol] one of {VALID_PROFILES}; falls back to {DEFAULT_PROFILE} for unknown values.
-      # @param overrides [Hash{String => Symbol}] per-rule severity overrides from `.rigor.yml`'s
+      # @param profile — one of {VALID_PROFILES}; falls back to {DEFAULT_PROFILE} for unknown values.
+      # @param overrides — per-rule severity overrides from `.rigor.yml`'s
       #   `severity_overrides:` map. Keys are canonical rule ids; values are {VALID_SEVERITIES} symbols.
       #   Family-wildcard keys (`call`) match every rule under that prefix.
-      # @param bleeding_edge_overrides [Hash{String => Symbol}] the severity map imposed by the active ADR-50
+      # @param bleeding_edge_overrides — the severity map imposed by the active ADR-50
       #   § WD2 bleeding-edge features ({Rigor::BleedingEdge.severity_overrides_for}). Consulted *below* the
       #   user's own `overrides` (so an explicit `severity_overrides:` entry, exact or family wildcard,
       #   always wins) and *above* the profile table. Exact rule ids only — the overlay never carries family
       #   wildcards. Empty while the overlay is unpopulated, so the default leaves resolution bit-for-bit
       #   unchanged.
-      # @return [Symbol] the resolved severity. Returns `:off` to mean "drop the diagnostic entirely".
+      # @return the resolved severity. Returns `:off` to mean "drop the diagnostic entirely".
       def resolve(rule:, authored_severity:, profile: DEFAULT_PROFILE, overrides: {}, bleeding_edge_overrides: {})
         return authored_severity if rule.nil?
 

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)