rigortype 0.4.5 → 0.4.7

data/lib/rigor/cli/type_scan_renderer.rb

@@ -4,6 +4,7 @@ require "json"
 require "optionparser"
 
 require_relative "renderable"
+require_relative "json_document"
 
 module Rigor
   class CLI
@@ -100,7 +101,7 @@ module Rigor
       end
 
       def render_json(report)
-        @out.puts(JSON.pretty_generate(json_payload(report)))
+        @out.puts(JSON.pretty_generate(JsonDocument.stamp(json_payload(report))))
       end
 
       def json_payload(report)

data/lib/rigor/cli/unused_command.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "optionparser"
+require_relative "json_document"
 require "json"
 
 require_relative "../configuration"
@@ -67,6 +68,23 @@ module Rigor
         0
       end
 
+      # The parser this command parses with, built without parsing anything: the catalogue reads the
+      # flags and formats from it (ADR-126 WD3). `options` is only written by the switches' blocks.
+      def option_parser(options = {})
+        OptionParser.new do |opts|
+          opts.banner = USAGE
+          Options.add_config(opts, options)
+          Options.add_format(opts, options, "Output format: text (default) or json")
+          opts.on("--entry-point=GLOB", "Treat declarations in files matching GLOB as roots (repeatable)") do |v|
+            options[:entry_points] << v
+          end
+          opts.on("--limit=N", Integer, "Print at most N candidates (default: all)") { |v| options[:limit] = v }
+          # WD5 — refuse rather than silently absorb. A reachability answer is sound only over a full run, and a
+          # user who asked for the fast path must not silently get the slow one.
+          opts.on("--incremental", "(unsupported)") { options[:incremental] = true }
+        end
+      end
+
       private
 
       # A scan's role and the spelling it records depend on the root and the working directory (#1760): a role
@@ -120,20 +138,8 @@ module Rigor
 
       def parse_options
         options = { config: nil, format: "text", entry_points: [], limit: nil }
-        parser = OptionParser.new do |opts|
-          opts.banner = USAGE
-          Options.add_config(opts, options)
-          opts.on("--format=FORMAT", "Output format: text (default) or json") { |v| options[:format] = v }
-          opts.on("--entry-point=GLOB", "Treat declarations in files matching GLOB as roots (repeatable)") do |v|
-            options[:entry_points] << v
-          end
-          opts.on("--limit=N", Integer, "Print at most N candidates (default: all)") { |v| options[:limit] = v }
-          # WD5 — refuse rather than silently absorb. A reachability answer is sound only over a full run, and a
-          # user who asked for the fast path must not silently get the slow one.
-          opts.on("--incremental", "(unsupported)") { options[:incremental] = true }
-        end
-        parser.parse!(@argv)
-        return usage_error(parser) if options[:incremental]
+        option_parser(options).parse!(@argv)
+        return usage_error if options[:incremental]
 
         options
       rescue OptionParser::ParseError => e
@@ -141,7 +147,7 @@ module Rigor
         :usage_error
       end
 
-      def usage_error(_parser)
+      def usage_error
         @err.puts("rigor unused does not support --incremental: reachability is only sound over a whole-project " \
                   "run, so an incremental pass would report constants as unused merely because the files that " \
                   "reference them were served from cache. Re-run without --incremental.")
@@ -379,6 +385,9 @@ module Rigor
                                       required_features: ProjectEnvironment.required_features(configuration),
                                       **ProjectEnvironment.dependency_discovery_options(configuration))
         ->(fqn) { !env.singleton_for_name(fqn).nil? }
+      rescue Environment::CoreRootError
+        # Issue #2517 — answering "unknown" for every name would report against no core at all.
+        raise
       rescue StandardError
         ->(_fqn) { false }
       end
@@ -413,7 +422,7 @@ module Rigor
       end
 
       def json(report, options, supply)
-        JSON.pretty_generate(
+        payload = {
           declared: report.declared, reachable: report.reachable, roots: report.roots, edges: report.edges,
           namespaces: report.namespaces,
           plugin_roots: supply.supplied, plugin_roots_unmatched: supply.unmatched,
@@ -421,7 +430,8 @@ module Rigor
           undecidable: limited(report.undecidable, options).map do |u|
             { name: u.fqn, path: u.path, line: u.line, reason: u.reason }
           end
-        )
+        }
+        JSON.pretty_generate(JsonDocument.stamp(payload))
       end
 
       def rows_json(rows, options)

data/lib/rigor/cli/upgrade_command.rb

@@ -15,6 +15,11 @@ module Rigor
 
       # @return CLI exit status.
       def run
+        if @argv.intersect?(%w[-h --help])
+          @out.puts(USAGE)
+          return 0
+        end
+
         @out.puts("rigor upgrade: No migration target available yet (ADR-50 WD7, queued).")
         @out.puts("Current version: #{Rigor::VERSION}")
         0

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"
@@ -46,6 +49,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 +93,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 +123,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 +175,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 +194,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 +216,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 +228,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 +307,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 +365,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 +437,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 +562,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 +604,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

@@ -35,7 +35,7 @@ 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.
@@ -156,9 +156,8 @@ module Rigor
       disable = Array(configuration.disabled_rules).filter_map do |token|
         disable_token_warning(token.to_s, plugin_ids)
       end
-      overrides = configuration.severity_overrides.keys.filter_map do |key|
-        override_key_warning(key.to_s, plugin_ids)
-      end
+      keys = configuration.severity_overrides.keys.map(&:to_s)
+      overrides = keys.filter_map { |key| override_key_warning(key, plugin_ids, keys) }
       disable + overrides
     end
 
@@ -172,14 +171,26 @@ module Rigor
     # `plugin.`-qualified key naming an unconfigured plugin, and any key outside the built-in vocabulary that is
     # not a qualified plugin id (a plugin's bare rule included), is inert. A reserved run-level row is the home of
     # this map, so naming one is never flagged; `all` is not a family wildcard here, so it is.
-    def self.override_key_warning(key, plugin_ids)
-      reason = override_key_problem(key, plugin_ids)
+    def self.override_key_warning(key, plugin_ids, present = [])
+      reason = legacy_alias_problem(key, present) || override_key_problem(key, plugin_ids)
       return nil if reason.nil?
 
       Warning.new(kind: :severity_override, message: "severity_overrides: #{key.inspect} #{reason}",
                   fields: { "token" => key })
     end
 
+    # #2005 — `disable:` expands a legacy alias to its canonical id, but the severity resolver matches canonical ids
+    # only, so an alias key reaches no row. Name the canonical id rather than accept the key. `present` holds the
+    # keys the map already has: when the canonical id is one of them, the advice to write it is already followed.
+    def self.legacy_alias_problem(key, present)
+      canonical = Analysis::CheckRules::LEGACY_RULE_ALIASES[key]
+      return nil if canonical.nil?
+
+      reason = "is a legacy alias of `#{canonical}`; the override has no effect"
+      present.include?(canonical) ? reason : "#{reason}, so write `#{canonical}`"
+    end
+    private_class_method :legacy_alias_problem
+
     def self.override_key_problem(key, plugin_ids)
       return "is not a recognized rule id; the override has no effect" if key == "all"
       return nil unless Array(Analysis::CheckRules.resolve_rule_token(key)).empty?

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