rigortype 0.4.6 → 0.4.8

data/lib/rigor/cli.rb

@@ -10,6 +10,9 @@ require_relative "version"
 require_relative "analysis/diagnostic"
 require_relative "analysis/result"
 require_relative "cli/options"
+require "did_you_mean"
+
+require_relative "cli/catalogue"
 require_relative "cli/diagnostic_formats"
 require_relative "ci_detector"
 require_relative "analysis/check_rules/rule_ids"
@@ -30,8 +33,11 @@ module Rigor
     # 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
+    # failure into a diagnostic. Since #2455 the per-file phases (`Runner#analyze_file_body`, the worker session,
+    # the discovery loops) do contain a `SystemStackError` raised from Ruby code, as that file's own crash row;
+    # what still reaches here is one raised from C (`Prism.parse` of a source nested near Prism's cap, which has
+    # no backtrace and leaves no stack to recover on), one outside a per-file phase, and `NoMemoryError`. 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
@@ -46,6 +52,17 @@ module Rigor
     # 2026-07-17 and nothing noticed. See `docs/internal-spec/config.md`.
     CONFIG_SCHEMA_URL = "https://github.com/rigortype/rigor/raw/master/schemas/rigor-config.schema.json"
 
+    # The comment `rigor init` writes under `plugins: []` when Gemfile.lock names a gem a bundled plugin models. The
+    # plugins are suggested, not enabled: ADR-96 Criterion 2 keeps a lockfile's presence from opting a project into a
+    # plugin's code, so the user uncomments the ones they want (#2536).
+    DETECTED_PLUGINS_HEADER = [
+      "# Detected from Gemfile.lock (suggested, not enabled). To load them, delete the `[]` above, uncomment the",
+      "# entries you want, then run `rigor plugins --strict`."
+    ].freeze
+
+    # The file whose presence marks a Rails application for `rigor init`'s `paths:` suggestion (#2560).
+    RAILS_APPLICATION_FILE = "config/application.rb"
+
     HANDLERS = {
       "check" => :run_check,
       "init" => :run_init,
@@ -79,6 +96,26 @@ module Rigor
       new(argv.dup, out: out, err: err).run
     end
 
+    # The parser `rigor init` parses with, built without parsing anything (the catalogue reads it, ADR-126 WD3).
+    def self.init_option_parser(options = {})
+      OptionParser.new do |opts|
+        opts.banner = "Usage: rigor init [options]"
+        opts.on("--force", "Overwrite an existing configuration file") { options[:force] = true }
+        opts.on("--path=PATH", "Configuration file path") { |value| options[:path] = value }
+        opts.on("--no-plugins", "Write no commented plugin suggestions from Gemfile.lock") do
+          options[:plugins] = false
+        end
+      end
+    end
+
+    # The parser `rigor help` parses with, built without parsing anything (the catalogue reads it, ADR-126 WD3).
+    def self.help_option_parser(options = {})
+      OptionParser.new do |opts|
+        opts.banner = "Usage: rigor help [--format=text|json] [<command>]"
+        Options.add_format(opts, options, "Output format: text (default) or json")
+      end
+    end
+
     def initialize(argv = ARGV.dup, out: $stdout, err: $stderr)
       @argv = argv
       @out = out
@@ -89,12 +126,14 @@ module Rigor
       command = @argv.shift
 
       case command
-      when nil, "help", "-h", "--help"
+      when nil, "-h", "--help"
         @out.puts(help)
         0
+      when "help"
+        run_help
       when "version", "-v", "--version"
-        @out.puts("rigor #{Rigor::VERSION}")
-        0
+        run_version
+
       else
         dispatch(command)
       end
@@ -139,6 +178,8 @@ module Rigor
       return arm_jit_deadline { send(handler) } if handler
 
       @err.puts("Unknown command: #{command}")
+      nearest = ::DidYouMean::SpellChecker.new(dictionary: Catalogue.names).correct(command).first
+      @err.puts("Did you mean `rigor #{nearest}`?") if nearest
       @err.puts(help)
       EXIT_USAGE
     end
@@ -156,6 +197,16 @@ module Rigor
       yield
     end
 
+    # `rigor version` and `-v`/`--version` print the version; `rigor version --help` prints the usage instead.
+    def run_version
+      if @argv.intersect?(%w[-h --help])
+        @out.puts("Usage: rigor version")
+      else
+        @out.puts("rigor #{Rigor::VERSION}")
+      end
+      0
+    end
+
     def run_check
       require_relative "cli/check_command"
 
@@ -168,15 +219,11 @@ module Rigor
       # present; no implicit merge).
       options = {
         force: false,
-        path: ".rigor.dist.yml"
+        path: ".rigor.dist.yml",
+        plugins: true
       }
 
-      parser = OptionParser.new do |opts|
-        opts.banner = "Usage: rigor init [options]"
-        opts.on("--force", "Overwrite an existing configuration file") { options[:force] = true }
-        opts.on("--path=PATH", "Configuration file path") { |value| options[:path] = value }
-      end
-      parser.parse!(@argv)
+      self.class.init_option_parser(options).parse!(@argv)
 
       path = options.fetch(:path)
       if File.exist?(path) && !options.fetch(:force)
@@ -184,24 +231,57 @@ module Rigor
         return 1
       end
 
-      File.write(path, init_template(path))
+      plugins = options.fetch(:plugins) ? detected_plugins : []
+      paths_suggestion = detected_paths
+      begin
+        File.write(path, init_template(path, plugins: plugins, paths_suggestion: paths_suggestion))
+      rescue SystemCallError => e
+        # A destination whose directory is missing or not writable is a bad path argument, the same usage error
+        # `--config=PATH` gives for a file that does not exist (exit 64, docs/manual/02-cli-reference.md). The bare
+        # Errno::ENOENT backtrace read as an internal crash.
+        reason = e.message.sub(/ @ .*\z/m, "")
+        @err.puts("rigor init: cannot write #{path}: #{reason}")
+        return EXIT_USAGE
+      end
       @out.puts("Created #{path}")
-      print_init_next_steps(path)
+      print_init_next_steps(path, plugins, paths_suggestion)
       0
     end
 
-    # `rigor init`'s template ships empty `plugins:` so a fresh init has nothing to validate — but the moment the user
-    # adds any plugin entry, the activation-failure surfaces enumerated in `rigor plugins`'s docstring become real.
+    # The bundled plugins whose target gems the project's `Gemfile.lock` declares: the read `rigor doctor` makes,
+    # through {PluginGapAdvisory}, so the two cannot disagree about what the project depends on. Empty without a
+    # lockfile, which leaves the template as it was before detection existed. The advisory is required lazily:
+    # it loads every bundled plugin's entry file, a cost a plain `rigor init` in a directory with no lockfile never
+    # pays.
+    def detected_plugins
+      require_relative "plugin_gap_advisory"
+
+      PluginGapAdvisory.gaps(project_root: Dir.pwd, plugins: []).map(&:plugin_gem)
+    end
+
+    # `rigor init`'s template lists the plugins Gemfile.lock detected, or ships empty `plugins:` so a fresh init has
+    # nothing to validate — but the moment the user adds any plugin entry, the activation-failure surfaces enumerated
+    # in `rigor plugins`'s docstring become real.
     # Point them at the verification command + the canonical readiness flow so silent failures (the cwd / Gemfile /
     # signature_paths mismatches that surfaced during the Mastodon trial) get caught the first time the user wires a
     # plugin, not the first time `rigor check` reports false positives that should have been covered.
-    def print_init_next_steps(path)
+    def print_init_next_steps(path, plugins = [], paths_suggestion = nil)
       @out.puts ""
       @out.puts "Next steps:"
-      @out.puts "  1. Edit #{path} — add the `plugins:` your project needs."
+      if plugins.empty?
+        @out.puts "  1. Edit #{path} — add the `plugins:` your project needs."
+      else
+        @out.puts "  1. Edit #{path} — to load a detected plugin, delete the `[]` on the `plugins:` line and"
+        @out.puts "     uncomment the entries you want:"
+        plugins.each { |gem| @out.puts "       #{gem}" }
+      end
       @out.puts "  2. Run `rigor plugins` to verify every configured plugin loads."
       @out.puts "     (`--strict` exits 1 on failure; ideal CI gate.)"
       @out.puts "  3. Run `rigor check` to analyse your code."
+      return if paths_suggestion.nil?
+
+      @out.puts "     `rigor check` analyses only `lib` until you edit `paths:` in #{path}. " \
+                "The suggestion is commented beneath it."
     end
 
     # Word-wraps `CheckRules::ALL_RULES` into a comma-separated, `#`-commented block for `init_template`, so the
@@ -230,8 +310,9 @@ module Rigor
 
     # 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.
-    def init_template(path = ".rigor.dist.yml")
+    # most likely to want to edit. `plugins:` stays the empty list the defaults ship; detected gems appear beneath it as
+    # comments, so a project with no lockfile gets the template it always did.
+    def init_template(path = ".rigor.dist.yml", plugins: [], paths_suggestion: nil)
       <<~YAML
         # yaml-language-server: $schema=#{CONFIG_SCHEMA_URL}
         # Rigor configuration. The full key reference is
@@ -287,10 +368,49 @@ module Rigor
         # `target_ruby` is left commented: the default only picks the syntax Rigor parses. Set it to the lowest
         # Ruby your project runs on, and Rigor also reports what that Ruby deprecates.
         # target_ruby: #{Configuration::DEFAULTS.fetch('target_ruby').dump}
-        #{YAML.dump(init_settings(path)).sub(/\A---\n/, '')}
+        #{settings_yaml(path, plugins, paths_suggestion)}
       YAML
     end
 
+    # The serialised settings. `plugins: []` stays valid YAML and schema-clean; when `Gemfile.lock` named a modelled
+    # gem, the suggestion block sits under it as comments, so nothing loads until the user uncomments a line. The
+    # `paths:` suggestion sits under the active `paths:` list the same way, and the active list stays `lib`.
+    def settings_yaml(path, plugins, paths_suggestion = nil)
+      yaml = YAML.dump(init_settings(path)).sub(/\A---\n/, "")
+      yaml = yaml.sub(/^plugins: \[\]\n/) { "plugins: []\n#{detected_plugins_block(plugins)}" } unless plugins.empty?
+      return yaml if paths_suggestion.nil?
+
+      yaml.sub(/^paths:\n(?:- .*\n)+/) { |active| active + paths_suggestion_block(paths_suggestion, path) }
+    end
+
+    # The commented `paths:` suggestion: one line naming what was detected and why, then the value to uncomment, written
+    # relative to the config file's directory like the active list (#1399).
+    def paths_suggestion_block(suggestion, path)
+      named = suggestion.fetch(:dirs).join(", ")
+      written = roots_relative_to(suggestion.fetch(:dirs), config_dir_of(path)).join(", ")
+      pronoun = suggestion.fetch(:dirs).one? ? "it" : "them"
+      "# #{suggestion.fetch(:reason)}: #{named}. To scan #{pronoun}, delete the `paths:` list above and " \
+        "uncomment the line below:\n# paths: [#{written}]\n"
+    end
+
+    # The source directories `rigor init` suggests for `paths:`, read from the project root (the cwd, like the plugin
+    # detection). A Rails application (config/application.rb) has app/ and lib/, each listed only if it exists. Any
+    # other layout gets no suggestion: the template's `lib` already covers it, and no other directory is guessed
+    # (#2560). Nil when there is nothing to add to today's `paths: [lib]`.
+    def detected_paths
+      return nil unless File.file?(RAILS_APPLICATION_FILE)
+
+      dirs = %w[app lib].select { |dir| File.directory?(dir) }
+      return nil if dirs.empty? || dirs == ["lib"]
+
+      { dirs: dirs, reason: "Detected a Rails app (#{RAILS_APPLICATION_FILE})" }
+    end
+
+    def detected_plugins_block(plugins)
+      lines = DETECTED_PLUGINS_HEADER + plugins.map { |gem| "#   - #{gem}" }
+      lines.map { |line| "#{line}\n" }.join
+    end
+
     # The settings `rigor init` writes: the defaults, with `test_paths:` spelled out as the test roots found now, so
     # the project's config says where its tests are rather than leaving it to auto-detection. The roots are written
     # relative to the config file's directory, which is what {Configuration.load} resolves them against. `paths:`
@@ -320,7 +440,7 @@ module Rigor
 
     # Each root is resolved against the physical cwd (where `rigor` reads it from), then written relative to the config
     # dir. With the config at the project root, both sides are the same physical directory, so the roots come out as
-    # they are spelled from it (`lib`, `spec`), which is master's output for the default config.
+    # they are spelled from it (`lib`, `spec`).
     def roots_relative_to(roots, config_dir)
       roots.map { |root| Pathname(File.absolute_path(root)).relative_path_from(config_dir).to_s }
     end
@@ -445,11 +565,18 @@ module Rigor
     # Surfaced because a bare `rigor describe` is the intuitive guess (the onboarding field trial saw it tried and met
     # "Unknown command").
     def run_describe
+      return print_describe_usage if @argv.intersect?(%w[-h --help])
+
       require_relative "cli/skill_command"
 
       CLI::SkillCommand.new(argv: ["describe", *@argv], out: @out, err: @err).run
     end
 
+    def print_describe_usage
+      @out.puts("Usage: rigor describe [--deep]")
+      0
+    end
+
     def run_docs
       require_relative "cli/docs_command"
 
@@ -480,41 +607,72 @@ module Rigor
       CLI::UpgradeCommand.new(argv: @argv, out: @out, err: @err).run
     end
 
+    # The text help is rendered from {Catalogue}, so the command list cannot drift from the dispatch table.
     def help
-      <<~HELP
-        Usage: rigor <command> [options]
-
-        Commands:
-          check      Analyze Ruby source files
-          init       Create a starter .rigor.yml
-          annotate   Print FILE with each line's last-expression type
-          type-of    Print inferred types at FILE:LINE[:COL] positions
-          lens       Map a file's declarations with their types and provenance (experimental)
-          trace      Replay how the engine typed FILE as a terminal animation
-          type-scan  Report Scope#type_of coverage across PATHs
-          effects    Report each method's effect labels, and the committed effect snapshot
-                     (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)
-          describe   Recommend the next skill for this project (alias for `skill describe`)
-          skill      Recommend the next skill + list/print bundled Agent Skills (skill describe, skill <name>)
-          docs       Print the bundled docs offline (docs <name>, docs --list)
-          show-bleedingedge  Show the bleeding-edge overlay + what your config adopts
-          doctor     Classify setup problems vs clean run with routed next actions
-          upgrade    Migration command skeleton (queued)
-          version    Print the Rigor version
-          help       Print this help
-      HELP
+      Catalogue.help_text
+    end
+
+    # `rigor help [--format=text|json] [<command>]`. `help <command>` behaves as `rigor <command> --help`;
+    # `--format=json` prints the whole {Catalogue} document.
+    def run_help
+      return print_command_list if @argv.intersect?(%w[-h --help])
+
+      options = parse_help_options
+      topics = @argv
+      return run_help_json(topics) if options[:format] == "json"
+
+      topic = topics.first
+      return run_help_topic(topic, topics.drop(1)) if topic
+
+      print_command_list
+    end
+
+    def print_command_list
+      @out.puts(help)
+      0
+    end
+
+    def parse_help_options
+      options = Hash.new("text")
+      # `order!` stops at the first positional, so the flags of the command being asked about are never parsed here.
+      self.class.help_option_parser(options).order!(@argv)
+      options
+    end
+
+    def run_help_json(topics)
+      if topics.any?
+        @err.puts("rigor help --format=json takes no command; it prints every command")
+        return EXIT_USAGE
+      end
+
+      @out.puts(JSON.pretty_generate(Catalogue.document))
+      0
+    end
+
+    def run_help_topic(topic, rest)
+      # Flags after the command name (`help type-of --workers=2`) are not parsed; a second word is not a subcommand's
+      # help, so it is refused rather than answered with the parent's.
+      extra = rest.reject { |word| word.start_with?("-") }
+      unless extra.empty?
+        @err.puts("rigor help takes one command, got: #{[topic, *extra].join(' ')}")
+        return EXIT_USAGE
+      end
+
+      case topic
+      when "help"
+        @out.puts(self.class.help_option_parser.help)
+        0
+      when "version"
+        @out.puts("Usage: rigor version")
+        0
+      when *HANDLERS.keys
+        @argv = ["--help"]
+        dispatch(topic)
+      else
+        @err.puts("Unknown command: #{topic}")
+        @err.puts(help)
+        EXIT_USAGE
+      end
     end
   end
 end

data/lib/rigor/config_audit.rb

@@ -3,7 +3,10 @@
 require "did_you_mean"
 
 require_relative "config_path"
+require_relative "environment/bundle_sig_discovery"
+require_relative "environment/rbs_collection_discovery"
 require_relative "flow_contribution/conflict"
+require_relative "library_probe"
 require_relative "signature_path_audit"
 # ADR-87 WD4 — only the pure rule-id table (`ALL_RULES` / `RULE_FAMILIES`) is needed, so require the light
 # `rule_ids.rb` rather than the engine-pulling `check_rules.rb`; keeps `config_audit` (loaded by every check)
@@ -35,10 +38,10 @@ module Rigor
   # (`rbs_extended.*`, `rbs.*`, `dynamic.*`) is left alone, since the engine emits those ids
   # outside the catalogue.
   module ConfigAudit
-    # One config-level finding. `kind` discriminates the source key (`:signature_path`,
+    # One config-level finding. `kind` discriminates the source key (`:unknown_key`, `:signature_path`,
     # `: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.
+    # `:bundler_bundle_path`, `:bundler_lockfile`, `:rbs_collection_lockfile`, `:rbs_collection_library`); `fields`
+    # carries the kind-specific structured data merged into {#to_h} for JSON consumers.
     Warning = Data.define(:kind, :message, :fields) do
       def to_h
         { "kind" => kind.to_s, "message" => message }.merge(fields)
@@ -51,7 +54,7 @@ module Rigor
       unknown_key_warnings(configuration) +
         signature_path_warnings(configuration) +
         bundled_plugin_signature_path_warnings(configuration) +
-        library_warnings(configuration) +
+        library_warnings(configuration, project_root) +
         rule_token_warnings(configuration) +
         explicit_path_warnings(configuration, project_root)
     end
@@ -129,21 +132,32 @@ module Rigor
       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
-    # skipped. Fails soft: if RBS itself raises, no warning rather than a crash.
-    def self.library_warnings(configuration)
-      configured = Array(configuration.libraries)
-      return [] if configured.empty?
-
-      loader = ::RBS::EnvironmentLoader.new
-      configured.reject { |lib| loader.has_library?(library: lib.to_s, version: nil) }.map do |lib|
-        Warning.new(
-          kind: :library,
-          message: "libraries: #{lib.to_s.inspect} is not an available RBS library (no signatures loaded from it)",
-          fields: { "name" => lib.to_s }
-        )
+    # `libraries:` entries RBS does not recognise, and — issue #2946 — `source: { type: stdlib }` entries of
+    # the run's `rbs_collection.lock.yaml`, which load as libraries too ({Environment::BaseLibraries.resolve}). Uses the
+    # same `RBS::EnvironmentLoader#has_library?` answer the loader filters through
+    # ({Environment::RbsLoader} `library_loader`), so a flagged name is one the loader skipped. A
+    # {Environment::RequiredFeatures::VENDORED_DIRS} name (`prime`) under `libraries:` is not audited: the
+    # configuration turns it into a vendored feature token the loader never asks `has_library?` about. A
+    # lockfile entry of that name is not a token, so it is still audited. The `rbs` CLI warns on the same
+    # lockfile entry (`Collection::Sources::Stdlib#manifest_of`).
+    # Fails soft: if RBS itself raises, no warning rather than a crash.
+    def self.library_warnings(configuration, project_root = Dir.pwd)
+      lock = { lockfile_path: configuration.rbs_collection_lockfile, project_root: project_root,
+               auto_detect: configuration.rbs_collection_auto_detect }
+      lockfile = Environment::RbsCollectionDiscovery.stdlib_library_names(**lock)
+      # Issue #2971 — a `libraries:` name the collection lockfile provides loads from the collection, not as an
+      # RBS library, so it is not an unknown library.
+      provided = Environment::RbsCollectionDiscovery.collection_gem_names(**lock)
+      named = (LibraryProbe.auditable(configuration.libraries) - provided).map { |lib| [:library, "libraries:", lib] } +
+              lockfile.map { |name| [:rbs_collection_library, "rbs_collection.lock.yaml: stdlib entry", name] }
+      return [] if named.empty?
+
+      unavailable = LibraryProbe.predicate.then { |has| named.reject { |_, _, lib| has.call(lib) } }
+      # Issue #2987 — nor is a name whose own `sig/` the bundle loaded; read only once a name is unavailable.
+      bundled = unavailable.empty? ? [] : Environment::BundleSigDiscovery.loaded_names(configuration, project_root)
+      unavailable.reject { |kind, _, lib| kind == :library && bundled.include?(lib) }.map do |kind, source, lib|
+        Warning.new(kind: kind, fields: { "name" => lib },
+                    message: "#{source} #{lib.inspect} is not an available RBS library (no signatures loaded from it)")
       end
     rescue StandardError
       []

data/lib/rigor/configuration/severity_profile.rb

@@ -15,12 +15,12 @@ module Rigor
     #   rules `:warning`.
     # - `strict`: Every rule is `:error`. CI-friendly.
     #
-    # The profile resolution order:
+    # The resolution order, first match wins:
     #
-    # 1. Profile-specific entry for the canonical rule id.
-    # 2. The diagnostic's own authored severity (the rule's default).
-    # 3. `:error` (catch-all so an unrecognised rule still emits visibly — the public-API drift spec catches
-    #    the bookkeeping gap separately).
+    # 1. An explicit `severity_overrides:` entry for the row (`resolve`'s `overrides:`).
+    # 2. A bleeding-edge severity override.
+    # 3. The profile's entry for the canonical rule id.
+    # 4. The diagnostic's own authored severity (the rule's default); an unrecognised rule keeps it.
     module SeverityProfile
       VALID_PROFILES = %i[lenient balanced strict].freeze
       VALID_SEVERITIES = %i[error warning info off].freeze
@@ -86,6 +86,7 @@ module Rigor
           # a config edit the author may deliberately not want.
           "effect.annotations-unchecked" => :info,
           "static.value-use.void" => :off,
+          "plugin.api-surface" => :off,
           # Opt-in author assertion: you only see it if you wrote a
           # `conforms-to` directive, so it stays a :warning even in
           # lenient — it is never unsolicited noise.
@@ -131,6 +132,7 @@ module Rigor
           "suppression.empty" => :warning,
           "suppression.unknown-marker" => :warning,
           "static.value-use.void" => :off,
+          "plugin.api-surface" => :off,
           "effect.envelope-exceeded" => :warning,
           "effect.liskov-widened" => :warning,
           "effect.unknown-label" => :info,
@@ -173,6 +175,7 @@ module Rigor
           "suppression.unknown-marker" => :warning,
           # `:off` even under strict: the gate is `bleeding_edge:`, not the profile (ADR-50 WD1 / ADR-100).
           "static.value-use.void" => :off,
+          "plugin.api-surface" => :off,
           "effect.envelope-exceeded" => :error,
           "effect.liskov-widened" => :error,
           "effect.unknown-label" => :warning,
@@ -234,11 +237,17 @@ module Rigor
 
       private_class_method :row_override
 
+      # Rule ids a dot-free family key does not reach. `plugin.api-surface` is the one built-in id under `plugin.`,
+      # the prefix of plugin rows, so a `plugin` key must not turn the bleeding-edge rule on (#2822); `disable:
+      # [plugin]` does not reach it either. A key naming the id itself still does, in either direction.
+      FAMILY_FALLBACK_EXEMPT = ["plugin.api-surface"].freeze
+
       # A family name has no `.` in it, so only a dot-free key can match one. `resolve` runs for every
       # diagnostic in a run's stream, and most configurations carry no such key (usually no overrides at all),
       # so the split below is skipped for them rather than allocating a name that nothing can match.
       def family_override(rule, overrides)
         return nil unless overrides.any? { |key, _| !key.to_s.include?(".") }
+        return nil if FAMILY_FALLBACK_EXEMPT.include?(rule)
 
         family = rule.split(".").first
         return nil if family.nil?