rigortype 0.4.4 → 0.4.6

data/lib/rigor/cli/options.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../analysis/buffer_binding"
+require_relative "../configuration_error"
 
 module Rigor
   class CLI
@@ -10,15 +11,31 @@ module Rigor
     # `--instead-of` flag pair and the buffer-binding resolution that validates it. That resolution used to be copied
     # verbatim into both `Rigor::CLI` and `TypeOfCommand`, so a fix to one (the paired-flag check, the readability
     # check, the error wording) could silently miss the other. Centralising it keeps the two editor-mode entry points in
-    # lockstep.
+    # lockstep. It also owns the `--config` check (#1992), so every command and the MCP tools that pass `--config`
+    # read the same rule.
     module Options
       module_function
 
       # Defines the standard `--config=PATH` flag on `parser`, writing the path into `options[:config]`. Used by every
       # subcommand that loads a `.rigor.yml`; the few whose `--config` help text is intentionally bespoke (`diff`,
-      # `mcp`, `show-bleedingedge`) keep their own `parser.on` rather than this shared wording.
+      # `mcp`, `show-bleedingedge`) keep their own `parser.on` and call {.config_path} for the same check.
       def add_config(parser, options)
-        parser.on("--config=PATH", "Path to the Rigor configuration file") { |value| options[:config] = value }
+        parser.on("--config=PATH", "Path to the Rigor configuration file") do |value|
+          options[:config] = config_path(value)
+        end
+      end
+
+      # The `--config` value, checked where the flag is read (#1992). A named file that is not there is an error, not
+      # a request for the defaults: the run would otherwise analyse under a configuration the caller did not ask for,
+      # and an MCP caller would get a result for it with no sign anything was missing. Auto-discovery, with no
+      # `--config` given, is not affected.
+      def config_path(value)
+        raise ConfigurationError, "empty config path" if value.strip.empty?
+        raise ConfigurationError, "config path is a directory: #{value}" if File.directory?(value)
+        raise ConfigurationError, "config file not found: #{value}" unless File.exist?(value)
+        raise ConfigurationError, "config file not readable: #{value}" unless File.readable?(value)
+
+        value
       end
 
       # Defines the `--tmp-file` / `--instead-of` editor-mode flag pair on `parser`, writing into `options`.

data/lib/rigor/cli/plugin_command.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "command"
+require_relative "../rooted_glob"
 
 module Rigor
   class CLI
@@ -204,7 +205,7 @@ module Rigor
         candidate = File.join(dir, "lib", "#{plugin.fetch(:name)}.rb")
         return candidate if File.file?(candidate)
 
-        Dir.glob(File.join(dir, "lib", "*.rb")).min
+        RootedGlob.glob(dir, "lib/*.rb").min
       end
 
       def docker_note

data/lib/rigor/cli/plugins_command.rb

@@ -13,6 +13,7 @@ require_relative "../reflection"
 require_relative "../type/combinator"
 require_relative "plugins_renderer"
 require_relative "command"
+require_relative "../rooted_glob"
 
 module Rigor
   class CLI
@@ -232,6 +233,8 @@ module Rigor
           signature_paths: signature_path_rows(plugin),
           open_receivers: manifest.open_receivers.dup,
           owns_receivers: manifest.owns_receivers.dup,
+          per_invocation_classes: manifest.per_invocation_classes.dup,
+          per_invocation_non_action_macros: manifest.per_invocation_non_action_macros.map(&:to_s),
           produces: manifest.produces.map(&:to_s),
           consumes: manifest.consumes.map { |c| "#{c.plugin_id}/#{c.name}#{'?' if c.optional}" },
           source_rbs_synthesizer: !manifest.source_rbs_synthesizer.nil?
@@ -264,6 +267,8 @@ module Rigor
           signature_paths: [],
           open_receivers: [],
           owns_receivers: [],
+          per_invocation_classes: [],
+          per_invocation_non_action_macros: [],
           produces: [],
           consumes: [],
           block_as_methods: 0,
@@ -297,7 +302,7 @@ module Rigor
       def rbs_file_count(dir)
         return 0 unless File.directory?(dir)
 
-        Dir.glob(File.join(dir, "**", "*.rbs")).size
+        RootedGlob.glob(dir, "**/*.rbs").size
       end
 
       def entry_gem_name(entry)
@@ -344,6 +349,7 @@ module Rigor
             config: {},
             signature_paths: [],
             open_receivers: [], owns_receivers: [], produces: [], consumes: [],
+            per_invocation_classes: [], per_invocation_non_action_macros: [],
             block_as_methods: 0, heredoc_templates: 0, trait_registries: 0,
             type_node_resolvers: 0,
             hkt_registrations: 0, hkt_definitions: 0,

data/lib/rigor/cli/plugins_renderer.rb

@@ -185,12 +185,26 @@ module Rigor
         lines = []
         lines << "        open_receivers: #{row[:open_receivers].join(', ')}" if row[:open_receivers].any?
         lines << "        owns_receivers: #{row[:owns_receivers].join(', ')}" if row[:owns_receivers].any?
+        lines.concat(per_invocation_lines(row))
         lines << "        produces: #{row[:produces].join(', ')}" if row[:produces].any?
         lines << "        consumes: #{row[:consumes].join(', ')}" if row[:consumes].any?
         lines.concat(narrow_protocol_lines(row))
         lines
       end
 
+      # ADR-125 — the per-invocation classes a plugin vouches for, and the macros whose arguments name a method that is
+      # not one of their actions.
+      def per_invocation_lines(row)
+        lines = []
+        if row[:per_invocation_classes].any?
+          lines << "        per_invocation_classes: #{row[:per_invocation_classes].join(', ')}"
+        end
+        if row[:per_invocation_non_action_macros].any?
+          lines << "        per_invocation_non_action_macros: #{row[:per_invocation_non_action_macros].join(', ')}"
+        end
+        lines
+      end
+
       # ADR-37 narrow extension protocols (node_rule / dynamic_return / narrowing_facts). Surfaced in the full report
       # alongside the declarative surfaces; `--capabilities` is the focused view.
       def narrow_protocol_lines(row)
@@ -249,8 +263,6 @@ module Rigor
           "signature_paths" => row[:signature_paths].map do |sp|
             { "path" => sp[:path], "exists" => sp[:exists], "rbs_files" => sp[:rbs_files] }
           end,
-          "open_receivers" => row[:open_receivers],
-          "owns_receivers" => row[:owns_receivers],
           "produces" => row[:produces],
           "consumes" => row[:consumes],
           "block_as_methods" => row[:block_as_methods],
@@ -265,6 +277,16 @@ module Rigor
           "dynamic_return_receivers" => row[:dynamic_return_receivers],
           "narrowing_facts_methods" => row[:narrowing_facts_methods],
           "load_error" => row[:load_error]
+        }.merge(receiver_json(row))
+      end
+
+      # ADR-125 — the per-invocation keys are additive; an empty array when the plugin declares none.
+      def receiver_json(row)
+        {
+          "open_receivers" => row[:open_receivers],
+          "owns_receivers" => row[:owns_receivers],
+          "per_invocation_classes" => row[:per_invocation_classes],
+          "per_invocation_non_action_macros" => row[:per_invocation_non_action_macros]
         }
       end
 

data/lib/rigor/cli/show_bleedingedge_command.rb

@@ -6,6 +6,7 @@ require "optionparser"
 require_relative "../bleeding_edge"
 require_relative "../configuration"
 require_relative "command"
+require_relative "options"
 
 module Rigor
   class CLI
@@ -44,7 +45,7 @@ module Rigor
             options[:format] = fmt
           end
           opt.on("--config=PATH", "Path to a .rigor.yml (default: auto-discovery).") do |path|
-            options[:config] = path
+            options[:config] = Options.config_path(path)
           end
         end.parse!(@argv)
         options

data/lib/rigor/cli/sig_gen_command.rb

@@ -3,6 +3,7 @@
 require "optionparser"
 
 require_relative "../configuration"
+require_relative "../analysis/path_expansion"
 require_relative "../effects/config_envelopes"
 require_relative "../effects/registry"
 require_relative "options"
@@ -55,7 +56,11 @@ module Rigor
         configuration = Configuration.load(options.fetch(:config))
         paths = @argv.empty? ? configuration.paths : @argv
 
-        observations = collect_observations(configuration, options)
+        path_errors = path_diagnostics(paths, configuration)
+        report_path_errors(path_errors, options)
+
+        observation_roots = observation_roots(configuration, options)
+        observations = collect_observations(configuration, options, observation_roots, paths)
         generator = SigGen::Generator.new(configuration: configuration, paths: paths,
                                           observations: observations,
                                           include_private: options.fetch(:include_private),
@@ -68,15 +73,20 @@ module Rigor
                  when :write then dispatch_write(candidates, configuration, options)
                  when :check then dispatch_check(candidates, configuration, options)
                  else
-                   dispatch_print_or_diff(candidates, mode, options)
+                   dispatch_print_or_diff(candidates, mode, options, observation_roots, path_errors)
                    0
                  end
+        status = 1 if path_errors.any?(&:error?)
+        report_run_notes(candidates, generator, options)
+        status
+      end
+
+      def report_run_notes(candidates, generator, options)
         report_skipped(candidates, options)
         report_inline_declared(candidates, options)
         report_withheld_annotations(candidates, options)
         report_unrenderable(generator.unrenderable)
         report_unresolvable_superclasses(generator.unresolvable_superclasses)
-        status
       end
 
       private
@@ -219,12 +229,38 @@ module Rigor
         unresolvable.sort.each { |class_name, superclass| @err.puts("  #{class_name} < #{superclass}") }
       end
 
-      def dispatch_print_or_diff(candidates, mode, options)
+      # #1991 — the path errors `rigor check` reports for the arguments: a path that is neither a directory nor a
+      # `.rb` file. Warned about beside files that will be read, an error when nothing will be, as `check` grades it.
+      def path_diagnostics(paths, configuration)
+        bad = Analysis::PathExpansion.unusable(paths)
+        return [] if bad.empty?
+
+        any_files = !Analysis::PathExpansion.ruby_files(paths, configuration.exclude_patterns,
+                                                        base: configuration.exclude_base).empty?
+        Analysis::PathExpansion.diagnostics(bad, any_files: any_files)
+      end
+
+      # Without this a missing path was read as empty, so the run said "No candidates" and exited 0 (#1991). JSON
+      # print/diff carries the errors in its payload (see {#path_errors_in_payload?}); every other form says them on
+      # stderr, as `rigor check` does.
+      def report_path_errors(path_errors, options)
+        return if path_errors_in_payload?(options)
+
+        path_errors.each { |diagnostic| @err.puts(diagnostic.to_s) }
+      end
+
+      def path_errors_in_payload?(options)
+        options.fetch(:format) == "json" && %w[print diff].include?(options.fetch(:mode))
+      end
+
+      def dispatch_print_or_diff(candidates, mode, options, observation_roots, path_errors)
         SigGen::Renderer.new(out: @out).render(
           candidates: candidates,
           mode: mode,
           format: options.fetch(:format),
-          selection: options.fetch(:selection)
+          selection: options.fetch(:selection),
+          observation: observation_report(observation_roots, options),
+          diagnostics: path_errors_in_payload?(options) ? path_errors : []
         )
       end
 
@@ -289,28 +325,52 @@ module Rigor
       # specified, observe the project's test roots: `test_paths:`, or whichever of `spec/` and `test/` exist. With no
       # root at all the run still succeeds, but says so — otherwise every parameter stays `untyped` with nothing
       # naming the reason.
-      def collect_observations(configuration, options)
+      #
+      # The collector pre-indexes the classes of the paths the run generates for as well as the configured ones, so
+      # a call site on a class named only on the command line (`sig-gen ../lib` from a subdirectory, where no
+      # config file is discovered and the default `paths:` resolve under the subdirectory) attaches (#2078).
+      def collect_observations(configuration, options, observe_paths, paths)
         return {} if options.fetch(:params) != "observed"
 
-        observe_paths = options.fetch(:observe)
-        observe_paths = configuration.resolved_test_paths if observe_paths.empty?
         if observe_paths.empty?
           warn_no_test_roots(configuration)
         else
           warn_missing_test_roots(observe_paths)
         end
-        SigGen::ObservationCollector.new(configuration: configuration, paths: observe_paths).collect
+        SigGen::ObservationCollector.new(configuration: configuration, paths: observe_paths,
+                                         source_paths: (configuration.paths + paths).uniq).collect
+      end
+
+      # The roots `--params=observed` reads: `--observe=PATH...` when given, else the project's test roots.
+      def observation_roots(configuration, options)
+        return [] if options.fetch(:params) != "observed"
+
+        observe_paths = options.fetch(:observe)
+        observe_paths.empty? ? configuration.resolved_test_paths : observe_paths
+      end
+
+      # #1398 — the same fact the stderr notes carry, as data for `--format=json` (and the MCP tool, whose
+      # stderr nobody reads). Absent under `--params=untyped`, where no root is read. Paths are spelled as
+      # {#observation_roots} yields them: `--observe=PATH` as typed, `test_paths:` as the configuration
+      # resolved them, an auto-detected `spec/` / `test/` absolute.
+      def observation_report(observe_paths, options)
+        return nil if options.fetch(:params) != "observed"
+
+        present, missing = observe_paths.uniq.partition { |path| SigGen::ObservationCollector.readable_root?(path) }
+        { paths: present, missing: missing }
       end
 
-      # A declared root that does not exist is read as empty, so name it: `sig-gen` is the only command that reads
-      # the test roots, and without this the run looks exactly like one whose tests pass no typed arguments.
+      # A declared root that does not exist (or is not a directory or `.rb` file) is read as empty, so name it:
+      # `sig-gen` is the only command that reads the test roots, and without this the run looks exactly like one
+      # whose tests pass no typed arguments.
       def warn_missing_test_roots(observe_paths)
-        missing = observe_paths.reject { |path| File.exist?(path) }
+        missing = observe_paths.reject { |path| SigGen::ObservationCollector.readable_root?(path) }
         return if missing.empty?
 
         consequence = missing.size == observe_paths.size ? "; every parameter stays untyped" : ""
         @err.puts("rigor sig-gen: no call sites are observed from #{missing.map(&:inspect).join(', ')}, " \
-                  "which does not exist#{consequence}. Check `test_paths:` or --observe=PATH.")
+                  "which does not exist or is not a directory or `.rb` file#{consequence}. " \
+                  "Check `test_paths:` or --observe=PATH.")
       end
 
       def warn_no_test_roots(configuration)

data/lib/rigor/cli/skill_command.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "command"
+require_relative "../rooted_glob"
 
 module Rigor
   class CLI
@@ -227,7 +228,7 @@ module Rigor
         return [] unless File.directory?(dir)
 
         # `Dir.glob` returns lexicographically sorted paths (Ruby 3.0+), so the `NN-` prefixes already drive read order.
-        Dir.glob(File.join(dir, "*.md"))
+        RootedGlob.glob(dir, "*.md")
       end
 
       def name_error(name)

data/lib/rigor/cli/skill_describe.rb

@@ -3,6 +3,7 @@
 require "yaml"
 
 require_relative "../plugin_gap_advisory"
+require_relative "../rooted_glob"
 
 module Rigor
   class CLI
@@ -78,7 +79,7 @@ module Rigor
         vscode = File.join(@root, ".vscode")
         return :none unless File.directory?(vscode)
 
-        files = Dir.glob(File.join(vscode, "*.json"))
+        files = RootedGlob.glob(vscode, "*.json")
         return :unwired if files.empty?
 
         files.any? { |path| file_mentions_rigor?(path) } ? :wired : :unwired
@@ -103,7 +104,7 @@ module Rigor
       end
 
       def ci_config_files
-        files = Dir.glob(File.join(@root, ".github", "workflows", "*.{yml,yaml}"))
+        files = RootedGlob.glob(@root, ".github/workflows/*.{yml,yaml}")
         gitlab = File.join(@root, ".gitlab-ci.yml")
         files << gitlab if File.file?(gitlab)
         files

data/lib/rigor/cli/type_of_command.rb

@@ -17,6 +17,7 @@ require_relative "type_of_template_probe"
 require_relative "command"
 require_relative "options"
 require_relative "../project_environment"
+require_relative "type_of_project_scope"
 
 module Rigor
   class CLI
@@ -88,7 +89,7 @@ module Rigor
       def execute(targets:, options:, buffer: nil)
         configuration = Configuration.load(options.fetch(:config))
         environment = project_environment(targets.map(&:file).uniq, configuration, buffer)
-        base_scope = Scope.empty(environment: environment)
+        base_scope = TypeOfProjectScope.build(environment: environment, configuration: configuration, buffer: buffer)
 
         results_by_target = Array.new(targets.length)
         targets.each_with_index.group_by { |target, _index| target.file }.each do |file, indexed_targets|

data/lib/rigor/cli/type_of_project_scope.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "../scope"
+require_relative "../protection/discovery_seed"
+
+module Rigor
+  class CLI
+    # Issue #512 — the scope `rigor type-of` probes with: single-file, plus the cross-file tables a prior
+    # `rigor check --incremental` left in the snapshot ({Protection::DiscoverySeed.from_snapshot}) when there are
+    # any. A probe never re-parses the project for its seed, so without a reusable snapshot this is the bare
+    # `Scope.empty` it always was.
+    #
+    # The seed is the full {Inference::ProjectSeedTables} fold, so a `contested_*` sibling travels with the member
+    # it qualifies (ADR-119): this is a recorded whole-index consumer in `admission_census.yml`.
+    module TypeOfProjectScope
+      module_function
+
+      def build(environment:, configuration:, buffer: nil)
+        base = Scope.empty(environment: environment)
+        seed = Protection::DiscoverySeed.from_snapshot(configuration: configuration, buffer: buffer)
+        return base if seed.nil? || seed.empty?
+
+        base.with_discovery(base.discovery.with(**seed))
+      end
+    end
+  end
+end

data/lib/rigor/cli/unused_command.rb

@@ -15,6 +15,7 @@ require_relative "../cache/store"
 require_relative "options"
 require_relative "command"
 require_relative "../project_environment"
+require_relative "../rooted_glob"
 
 module Rigor
   class CLI
@@ -51,7 +52,7 @@ module Rigor
         paths = @argv.empty? ? configuration.paths : @argv
         establish_root(configuration)
         scan_cache = open_scan_cache(configuration)
-        declarations, references, dynamic_uses, shadows = scan(paths, configuration, scan_cache)
+        declarations, references, dynamic_uses, shadows, ancestries = scan(paths, configuration, scan_cache)
         references.concat(signature_references(configuration))
         dynamic_uses.concat(template_mentions(declarations, scan_cache))
 
@@ -60,7 +61,7 @@ module Rigor
         references.concat(plugin_references(contribution.references))
         graph = build_graph(configuration, options, contribution,
                             declarations: declarations, references: references, dynamic_uses: dynamic_uses,
-                            shadows: shadows)
+                            shadows: shadows, ancestries: ancestries)
         emit(graph.report, options, supply: root_supply(contribution.roots, declarations))
         scan_cache.save
         0
@@ -109,9 +110,9 @@ module Rigor
         cwd == @root || inside?(cwd, @root) ? [@root] : [@root, cwd]
       end
 
-      def build_graph(configuration, options, contribution, declarations:, references:, dynamic_uses:, shadows:)
+      def build_graph(configuration, options, contribution, declarations:, **scanned)
         Analysis::Reachability::Graph.new(
-          declarations: declarations, references: references, dynamic_uses: dynamic_uses, shadows: shadows,
+          declarations: declarations, **scanned,
           root_fqns: root_fqns(declarations, options.fetch(:entry_points)) + contribution.roots,
           foreign: foreign_predicate(configuration)
         )
@@ -160,16 +161,18 @@ module Rigor
       # is the one the report prints; any other spelling's declarations are shadows, as a wider-corpus
       # file's are (#1732).
       def scan(paths, configuration, cache)
-        out = { declarations: [], references: [], dynamic_uses: [], shadows: [] }
+        out = { declarations: [], references: [], dynamic_uses: [], shadows: [], ancestries: [] }
         file_spellings(paths, configuration).sort.each do |real, list|
           primary, analysed = list.find { |_, declared| declared } || list.first
           result = cache.serve(:scan, primary) { read_and_scan(primary, real, configuration) }
           next if result.nil?
 
           out[analysed ? :declarations : :shadows].concat(result.declarations)
+          # An ancestry edge is a fact about the program, not about the file's role, so one spelling carries it.
+          out[:ancestries].concat(result.ancestries)
           list.map(&:first).each { |file| add_spelling(out, result, file, real, primary) }
         end
-        out.values_at(:declarations, :references, :dynamic_uses, :shadows)
+        out.values_at(:declarations, :references, :dynamic_uses, :shadows, :ancestries)
       end
 
       def add_spelling(out, result, file, real, primary)
@@ -289,7 +292,7 @@ module Rigor
         Array(configuration.signature_paths).flat_map do |dir|
           next [] unless File.directory?(dir)
 
-          Dir.glob(File.join(dir, "**/*.rbs")).flat_map { |file| Analysis::Reachability::SignatureScan.call(file) }
+          RootedGlob.glob(dir, "**/*.rbs").flat_map { |file| Analysis::Reachability::SignatureScan.call(file) }
         end
       end
 

data/lib/rigor/cli.rb

@@ -250,8 +250,9 @@ module 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
+        #                A bare family token (`call`, `flow`, `def`,
+        #                `assert`, `dump`, `global`, `suppression`,
+        #                `static`, `effect`, `pre-eval`) wildcards every
         #                rule under that prefix. Legacy unprefixed
         #                names (`undefined-method`, …) still
         #                resolve. In-source

data/lib/rigor/config_audit.rb

@@ -3,6 +3,7 @@
 require "did_you_mean"
 
 require_relative "config_path"
+require_relative "flow_contribution/conflict"
 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)
@@ -26,12 +27,13 @@ module Rigor
   #
   # 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 `severity_overrides:` check only
-  # flags a key under a built-in family (`call`, `flow`, …) — a plugin- or `rbs_extended.*`
-  # rule id (whose family Rigor cannot statically enumerate, since a `node_rule` block emits
-  # any `rule:` string it likes) is left alone. The `disable:` check goes further because the
-  # list's reach is enumerable (issue #1953): a plugin's row answers only to its qualified
-  # `plugin.<id>.<rule>` id, so a bare plugin rule there is inert (see {.disable_token_warning}).
+  # it never fires on a setup that works. The rule-token checks lean on the reach of `disable:`
+  # and `severity_overrides:` being enumerable (issues #1953, #1985): a plugin's row answers only
+  # to its qualified `plugin.<id>.<rule>` id (or `plugin.<id>`), so a bare plugin rule there is
+  # inert (see {.disable_token_warning}, {.override_key_warning}). A `plugin.`-qualified token is
+  # checked only against `plugins:`, and a token under a non-check engine family
+  # (`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`,
     # `:bundled_plugin_signature_path`, `:library`, `:disabled_rule`, `:severity_override`,
@@ -148,24 +150,65 @@ module Rigor
     end
 
     # `disable:` tokens that reach no row ({.disable_token_warning}) and `severity_overrides:` keys
-    # that name no rule. An override key is flagged only under a built-in family, so a plugin
-    # rule id is never mis-flagged (see the module docstring).
+    # that reach none ({.override_key_warning}).
     def self.rule_token_warnings(configuration)
       plugin_ids = configured_plugin_ids(configuration.plugins)
       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|
-        next unless inert_builtin_token?(key.to_s)
+      keys = configuration.severity_overrides.keys.map(&:to_s)
+      overrides = keys.filter_map { |key| override_key_warning(key, plugin_ids, keys) }
+      disable + overrides
+    end
 
-        Warning.new(
-          kind: :severity_override,
-          message: "severity_overrides: #{key.to_s.inspect} is not a recognized rule id; the override has no effect",
-          fields: { "token" => key.to_s }
-        )
+    # Issue #1985 — the plugin loader's own rows, which a `severity_overrides:` key names by their qualified
+    # id; they also answer to the bare `load-error` / `runtime-error`.
+    PLUGIN_LOADER_ROWS = %w[plugin_loader.load-error plugin_loader.runtime-error].freeze
+    private_constant :PLUGIN_LOADER_ROWS
+
+    # A warning for a `severity_overrides:` key that can reach no row, or nil. Mirrors {.disable_token_warning}
+    # (issue #1985): a plugin's row answers only to its qualified `plugin.<id>.<rule>` or `plugin.<id>`, so a
+    # `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, 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?
+
+      if key.start_with?(Analysis::CheckRules::PLUGIN_FAMILY_PREFIX)
+        return nil if plugin_ids.nil? || plausible_plugin_token?(key, plugin_ids)
+
+        "names no plugin `plugins:` configures; the override has no effect"
+      elsif key.start_with?("plugin_loader.")
+        "is not a recognized rule id; the override has no effect" unless PLUGIN_LOADER_ROWS.include?(key)
+      elsif inert_builtin_token?(key)
+        "is not a recognized rule id; the override has no effect"
+      elsif !non_check_engine_token?(key) && !severity_only_id?(key)
+        "is not a recognized rule id; the override has no effect " \
+          "(if this is a plugin's rule, write it as `plugin.<id>.<rule>`)"
       end
-      disable + overrides
     end
+    private_class_method :override_key_problem
 
     # Issue #1953 — the run-level rows the diagnostic policy keeps on `severity_overrides:` and the
     # baseline. `disable:` does not reach them by any spelling, so naming one there is inert.
@@ -224,6 +267,19 @@ module Rigor
     end
     private_class_method :reserved_run_level_token?
 
+    # Bare ids that a `severity_overrides:` key re-stamps but a marker or `disable:` cannot suppress: the `--explain`
+    # `fallback` row and the `contribution_merge` conflict reasons (`FlowContribution::CONFLICT_VALID_REASONS`,
+    # kebab-cased). They are not in `CheckRules::NON_CHECK_DIAGNOSTIC_IDS`, which would silence the warnings for a
+    # `disable:` token or marker naming them. `spec/rigor/config_audit_spec.rb` pins this list's completeness.
+    CONFLICT_IDS = FlowContribution::CONFLICT_VALID_REASONS.map { |reason| reason.to_s.tr("_", "-").freeze }.freeze
+    SEVERITY_ONLY_IDS = (%w[fallback] + CONFLICT_IDS).freeze
+    private_constant :CONFLICT_IDS, :SEVERITY_ONLY_IDS
+
+    def self.severity_only_id?(key)
+      SEVERITY_ONLY_IDS.include?(key)
+    end
+    private_class_method :severity_only_id?
+
     def self.non_check_engine_token?(token)
       Analysis::CheckRules::NON_CHECK_DIAGNOSTIC_IDS.include?(token) ||
         Analysis::CheckRules::NON_CHECK_DIAGNOSTIC_FAMILIES.include?(token.split(".").first)

data/lib/rigor/configuration/severity_profile.rb

@@ -202,11 +202,17 @@ module Rigor
       #   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.
+      # @param qualified_rule — the row's `<source_family>.<rule>` id (`plugin_loader.load-error`); equal to `rule`
+      #   for a built-in row. Issue #1985 — an override key may spell it.
+      # @param plugin_family — `plugin.<id>` for a row a plugin emitted, nil for every other row. Such a row answers
+      #   to an override only by its `qualified_rule` or this whole-plugin key, never by its bare `rule` or a family
+      #   wildcard: plugins share bare rules (`load-error`), and a bare key would re-stamp them all.
       # @return the resolved severity. Returns `:off` to mean "drop the diagnostic entirely".
-      def resolve(rule:, authored_severity:, profile: DEFAULT_PROFILE, overrides: {}, bleeding_edge_overrides: {})
+      def resolve(rule:, authored_severity:, profile: DEFAULT_PROFILE, overrides: {}, bleeding_edge_overrides: {},
+                  qualified_rule: rule, plugin_family: nil)
         return authored_severity if rule.nil?
 
-        override = overrides[rule] || family_override(rule, overrides)
+        override = row_override(rule, qualified_rule, plugin_family, overrides)
         return override.to_sym if override
 
         bleeding = bleeding_edge_overrides[rule]
@@ -216,6 +222,18 @@ module Rigor
         profile_table.fetch(rule, authored_severity)
       end
 
+      # Issue #1985 — the `severity_overrides:` entry a row answers to, or nil. A plugin's row: its qualified id, then
+      # its `plugin.<id>`. Any other row: its qualified id (the plugin loader's
+      # `plugin_loader.load-error`), then its bare rule, then a family wildcard. The qualified key is the more specific
+      # one, so it wins over the bare key, as it does for a plugin's row.
+      def row_override(rule, qualified_rule, plugin_family, overrides)
+        return overrides[qualified_rule] || overrides[plugin_family] unless plugin_family.nil?
+
+        overrides[qualified_rule] || overrides[rule] || family_override(rule, overrides)
+      end
+
+      private_class_method :row_override
+
       # 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.