rigortype 0.4.4 → 0.4.5

data/lib/rigor/cache/incremental_snapshot.rb

@@ -10,6 +10,7 @@ require_relative "../analysis/shadow_harness"
 require_relative "../analysis/run_cache_key"
 require_relative "../environment"
 require_relative "../analysis/path_expansion"
+require_relative "../rooted_glob"
 
 module Rigor
   module Cache
@@ -172,7 +173,16 @@ module Rigor
       # 38: issue #1898 — the payload gains `effect_plugin_digest`, the plugin effect-fact digest the collections were
       # stamped under, which a recheck now checks before its served collections reach the envelope pass. A pre-38
       # blob carries none, so the gate rejects it and the next run is cold.
-      SCHEMA = 38
+      # 39: issue #1984 — the visibility walk records the singleton slots (`[:singleton, name]`) and contests the ones
+      # two files disagree on, which a pre-39 bundle carries none of, so a warm run would answer a singleton call a
+      # cold run reports.
+      # 40: issue #1553 — the payload gains `plugin_reads`, the plugin reads each analysed file's last analysis made,
+      # which a recheck validates to put a reader of a changed input into the closure. A pre-40 blob carries none,
+      # so its readers would be served stale; the gate rejects it and the next run is cold.
+      # 41: issue #1583 — the payload gains `discovery_digests`, the packed digest of each file a run over path
+      # arguments discovered without analysing, which a recheck compares to re-baseline when one moved. A pre-41
+      # blob carries none; the gate rejects it and the next run is cold.
+      SCHEMA = 41
 
       # The persisted per-file state.
       # `cache` maps an analyzed file to its diagnostics.
@@ -227,6 +237,9 @@ module Rigor
       # Issues #796 / #794 — the run-level rows a narrowed run replays instead of re-deriving; see
       # docs/internal-spec/cache.md § "Run-level rows the snapshot carries" for why exactly these two are
       # fresh under the fingerprint and why no other `.rigor.yml`-level row may join them.
+      # Issue #1583 — `discovery_digests` maps each file a run over path arguments discovered but did not analyse
+      # (#684's widening to the configured `paths:`) to its ADR-87 packed stat-digest entry; `{}` on a run over
+      # the configured paths. A recheck that finds one moved, or the set changed, re-baselines.
       # Issue #1898 — `effect_plugin_digest` is {Rigor::Effects::PluginFacts#digest} at the run that collected
       # `effect_collections` (nil when collection was off). A plugin stamps its attributions and edges into a file's
       # collection, and `effects_identity` is plugin-blind (it is compared before any plugin loads), so the session
@@ -236,10 +249,11 @@ module Rigor
                             :missing, :class_decls, :constant_decls, :seed_bundles, :plugin_fact_digest,
                             :return_summaries, :param_table,
                             :effect_collections, :effects_identity, :run_level_rows,
-                            :effect_plugin_digest) do
-        # Defaults to nil so a payload built without it (an older caller, a spec fixture) reads as "unknown",
-        # which the session treats as moved.
-        def initialize(effect_plugin_digest: nil, **rest)
+                            :effect_plugin_digest, :plugin_reads, :discovery_digests) do
+        # `effect_plugin_digest` defaults to nil so a payload built without it (an older caller, a spec fixture)
+        # reads as "unknown", which the session treats as moved. `plugin_reads` defaults to no reads, and
+        # `discovery_digests` to no discovery-only files.
+        def initialize(effect_plugin_digest: nil, plugin_reads: {}, discovery_digests: {}, **rest)
           super
         end
       end
@@ -367,7 +381,7 @@ module Rigor
       # checkouts.
       def self.digest_signature_paths(signature_paths)
         globbed = Array(signature_paths).flat_map do |entry|
-          File.directory?(entry) ? Dir.glob(File.join(entry, "**", "*.rbs")) : [entry]
+          File.directory?(entry) ? RootedGlob.glob(entry, "**/*.rbs") : [entry]
         end
         files = globbed.select { |path| File.file?(path) }.sort
         digest = Digest::SHA256.new
@@ -449,7 +463,9 @@ module Rigor
           effect_collections: data[:effect_collections] || {},
           effects_identity: data[:effects_identity],
           run_level_rows: data[:run_level_rows],
-          effect_plugin_digest: data[:effect_plugin_digest]
+          effect_plugin_digest: data[:effect_plugin_digest],
+          plugin_reads: data[:plugin_reads] || {},
+          discovery_digests: data.fetch(:discovery_digests, {})
         )
       end
       private :payload_from
@@ -475,7 +491,9 @@ module Rigor
           effect_collections: payload.effect_collections,
           effects_identity: payload.effects_identity,
           run_level_rows: payload.run_level_rows,
-          effect_plugin_digest: payload.effect_plugin_digest
+          effect_plugin_digest: payload.effect_plugin_digest,
+          plugin_reads: payload.plugin_reads,
+          discovery_digests: payload.discovery_digests
         )
         # #1507 — every `--incremental` run that analysed anything rewrites this whole blob, so its deflate is
         # on the edit path; see {Store::DEFLATE_LEVEL}.

data/lib/rigor/cache/rbs_descriptor.rb

@@ -5,6 +5,7 @@ require "digest"
 require_relative "descriptor"
 require_relative "engine_source"
 require_relative "file_digest"
+require_relative "../rooted_glob"
 
 module Rigor
   module Cache
@@ -110,7 +111,7 @@ module Rigor
         roots.flat_map do |root|
           next [] unless root.directory?
 
-          Dir.glob(root.join("**", "*.rbs")).map do |path|
+          RootedGlob.glob(root, "**/*.rbs").map do |path|
             digest = FileDigest.hexdigest(path)
             if comparator == :stat
               Descriptor::FileEntry.stat(path: path, digest: digest)

data/lib/rigor/cache/store.rb

@@ -9,6 +9,7 @@ require "zlib"
 
 require_relative "../version"
 require_relative "descriptor"
+require_relative "../rooted_glob"
 
 module Rigor
   module Cache
@@ -176,7 +177,7 @@ module Rigor
           subdir = File.join(root, child)
           next nil unless File.directory?(subdir)
 
-          entries = Dir.glob(File.join(subdir, "**", "*.entry"))
+          entries = RootedGlob.glob(subdir, "**/*.entry")
           next nil if entries.empty?
 
           { id: child, entries: entries.size, bytes: entries.sum { |e| File.size(e) } }
@@ -709,7 +710,7 @@ module Rigor
 
       def cleanup_stale_temp_files
         cutoff = Time.now - STALE_TEMP_FILE_AGE_SECONDS
-        Dir.glob(File.join(@root, "**", "*.tmp.*")).each do |path|
+        RootedGlob.glob(@root, "**/*.tmp.*").each do |path|
           next unless File.file?(path)
           next if File.mtime(path) > cutoff
 
@@ -771,7 +772,7 @@ module Rigor
       # Returns an array of `{ path:, producer:, mtime:, bytes: }` hashes for every `.entry` file under the
       # cache root, skipping unreadable entries.
       def collect_entry_stats
-        Dir.glob(File.join(@root, "**", "*.entry")).filter_map do |path|
+        RootedGlob.glob(@root, "**/*.entry").filter_map do |path|
           stat = File.stat(path)
           producer = producer_id_for_entry(path)
           next nil if producer.nil?

data/lib/rigor/cli/command.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../rooted_glob"
+
 module Rigor
   class CLI
     # Base class for the `rigor <subcommand>` command objects.
@@ -26,7 +28,7 @@ module Rigor
         paths = []
         args.each do |arg|
           if File.directory?(arg)
-            paths.concat(Dir.glob(File.join(arg, "**/*.rb")))
+            paths.concat(RootedGlob.glob(arg, "**/*.rb"))
           elsif File.file?(arg)
             paths << arg
           else

data/lib/rigor/cli/docs_command.rb

@@ -2,6 +2,7 @@
 
 require_relative "command"
 require_relative "doc_links"
+require_relative "../rooted_glob"
 
 module Rigor
   class CLI
@@ -186,8 +187,8 @@ module Rigor
       # `install.md` sits at the docs root (category `guide`); the rest are manual / handbook chapters.
       def discover_docs
         paths = [File.join(DOCS_ROOT, "install.md")]
-        paths += Dir.glob(File.join(MANUAL_ROOT, "**", "*.md")) # Dir.glob is already sorted
-        paths += Dir.glob(File.join(HANDBOOK_ROOT, "**", "*.md"))
+        paths += RootedGlob.glob(MANUAL_ROOT, "**/*.md") # Dir.glob is already sorted
+        paths += RootedGlob.glob(HANDBOOK_ROOT, "**/*.md")
         paths.select { |path| File.file?(path) }.map { |path| doc_entry(path) }
       end
 

data/lib/rigor/cli/doctor_command.rb

@@ -364,7 +364,7 @@ module Rigor
           status: :warn,
           message: "#{gap.locked_gems.join(', ')} #{gap.locked_gems.one? ? 'is a dependency' : 'are dependencies'} " \
                    "of this project and #{gap.plugin_gem} models it, but it is not enabled",
-          hint: "Add `#{gap.plugin_gem}` to `.rigor.yml` `plugins:`, or leave it out deliberately."
+          hint: "Add `#{gap.plugin_gem}` to `.rigor.yml` `plugins:`, or decline it with an `enabled: false` entry."
         }
       end
 

data/lib/rigor/cli/explain_command.rb

@@ -10,7 +10,7 @@ require_relative "command"
 module Rigor
   class CLI
     # Executes `rigor explain <rule>`. Prints the catalog entry for one canonical rule id, a legacy alias, or a family
-    # wildcard (`call`, `flow`, `assert`, `dump`, `def`).
+    # wildcard (`call`, `flow`, `def`, `assert`, `dump`, `global`, `suppression`, `static`, `effect`).
     #
     # Without arguments lists every rule's id and one-line summary.
     #
@@ -74,7 +74,8 @@ module Rigor
         end
         @out.puts("")
         @out.puts("Run `rigor explain <rule>` for the full description.")
-        @out.puts("Family wildcards (`call`, `flow`, `assert`, `dump`, `def`) print every rule under that prefix.")
+        @out.puts("Family wildcards (#{Analysis::CheckRules::RULE_FAMILIES.map { |f| "`#{f}`" }.join(', ')}) " \
+                  "print every rule under that prefix.")
         @out.puts("")
         @out.puts("`rigor sig-gen` skip reasons:")
         @out.puts("")

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
@@ -297,7 +298,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)

data/lib/rigor/cli/sig_gen_command.rb

@@ -55,7 +55,8 @@ module Rigor
         configuration = Configuration.load(options.fetch(:config))
         paths = @argv.empty? ? configuration.paths : @argv
 
-        observations = collect_observations(configuration, options)
+        observation_roots = observation_roots(configuration, options)
+        observations = collect_observations(configuration, options, observation_roots)
         generator = SigGen::Generator.new(configuration: configuration, paths: paths,
                                           observations: observations,
                                           include_private: options.fetch(:include_private),
@@ -68,7 +69,7 @@ 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)
                    0
                  end
         report_skipped(candidates, options)
@@ -219,12 +220,13 @@ module Rigor
         unresolvable.sort.each { |class_name, superclass| @err.puts("  #{class_name} < #{superclass}") }
       end
 
-      def dispatch_print_or_diff(candidates, mode, options)
+      def dispatch_print_or_diff(candidates, mode, options, observation_roots)
         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)
         )
       end
 
@@ -289,11 +291,9 @@ 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)
+      def collect_observations(configuration, options, observe_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
@@ -302,15 +302,36 @@ module Rigor
         SigGen::ObservationCollector.new(configuration: configuration, paths: observe_paths).collect
       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.
+      # 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 (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/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,25 +150,55 @@ 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)
-
-        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 }
-        )
+        override_key_warning(key.to_s, plugin_ids)
       end
       disable + overrides
     end
 
+    # 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)
+      reason = 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
+
+    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
+    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.
     RESERVED_RUN_LEVEL_FAMILIES = %w[plugin_loader plugin_trust rbs.coverage dynamic.dependency-source].freeze
@@ -224,6 +256,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.

data/lib/rigor/configuration.rb

@@ -8,6 +8,7 @@ require_relative "configuration/dependencies"
 require_relative "configuration/severity_profile"
 require_relative "config_path"
 require_relative "configuration_error"
+require_relative "rooted_glob"
 require_relative "effects/entry_points"
 require_relative "effects/label"
 require_relative "effects/method_key"
@@ -995,9 +996,34 @@ module Rigor
     # this entry" so a templated `**` pattern in a fresh project doesn't generate an error per match-less
     # pattern.
     def expand_pre_eval_entries(entries)
-      entries.flat_map do |entry|
-        glob_pattern?(entry) ? Dir.glob(entry, sort: true) : [entry]
-      end.uniq.freeze
+      entries.flat_map { |entry| expand_pre_eval_entry(entry) }.uniq.freeze
+    end
+
+    # #1956 — a relative entry arrives joined onto the config file's directory, so the metacharacters the
+    # check above sees may be that directory's own (`ds [x]/`). The leading run of segments that name existing
+    # directories is read literally and only the rest is globbed under it: a literal entry under such a
+    # directory stays a literal path, and a pattern matches what it matches under a plain directory.
+    def expand_pre_eval_entry(entry)
+      return [entry] unless glob_pattern?(entry)
+
+      base, pattern = literal_directory_prefix(entry)
+      return [entry] unless glob_pattern?(pattern)
+
+      base ? RootedGlob.glob(base, pattern) : Dir.glob(entry, sort: true)
+    end
+
+    def literal_directory_prefix(entry)
+      segments = entry.split("/")
+      count = (1...segments.size).take_while { |n| File.directory?(join_segments(segments.take(n))) }.size
+      return [nil, entry] if count.zero?
+
+      [join_segments(segments.take(count)), segments.drop(count).join("/")]
+    end
+
+    # `"/a".split("/")` leads with an empty segment, which spells the filesystem root.
+    def join_segments(segments)
+      path = segments.join("/")
+      path.empty? ? "/" : path
     end
 
     def glob_pattern?(path)