rigortype 0.4.3 → 0.4.5

data/lib/rigor/cache/descriptor.rb

@@ -4,6 +4,7 @@ require "digest"
 require "json"
 require_relative "../value_semantics"
 require_relative "file_digest"
+require_relative "../rooted_glob"
 
 module Rigor
   module Cache
@@ -82,7 +83,18 @@ module Rigor
       # an unchanged file would fold as "no possible fact" where a cold walk records one.
       # v18: ADR-119 WD3 — the visibility walk fills `contested_discovered_method_visibilities`; a pre-18 bundle
       # carries it empty, so an unchanged file's conditional visibility would fold as certain.
-      SCHEMA_VERSION = 18
+      # v19: #1555 / #1962 — the run-result dependency descriptor now carries a `:kind` row per analysis root,
+      # `pre_eval:` entry and project signature root (configured, or the auto-detected `sig`), so one that
+      # appears, vanishes or changes kind invalidates the warm entry. A
+      # pre-19 entry carries none of them and would validate fresh across exactly those edits, so cached
+      # entries must read as misses once and rebuild carrying the rows.
+      # v20: #1977 — the `--incremental` run-result slot records a `:kind` row, not an existence row, per analysis
+      # root, `pre_eval:` entry and project signature root. A pre-20 slot's existence row validates fresh across a
+      # directory replaced by a file of the same name, so it must read as a miss once and rebuild.
+      # v21: #1984 — the visibility walk records each class's singleton slots (`[:singleton, name]`) in the seed
+      # bundles' `method_visibilities`. A pre-21 bundle carries none for an unchanged file, so cached bundles must read
+      # as misses once and rebuild carrying them.
+      SCHEMA_VERSION = 21
 
       # Per-slot entry value objects. Constructors validate enums / required fields and freeze the resulting
       # struct so no caller can mutate after the entry is in a Descriptor.
@@ -96,7 +108,7 @@ module Rigor
         # It MUST NOT be placed in a descriptor used as a cache KEY (its value carries machine-local,
         # per-run-nondeterministic stat data); {RbsDescriptor.build}'s env-cache `files` therefore stay
         # `:digest`, while the {Runner} run-dependency descriptor and plugin {IoBoundary} reads use `:stat`.
-        VALID_COMPARATORS = %i[digest stat mtime exists].freeze
+        VALID_COMPARATORS = %i[digest stat mtime kind exists].freeze
 
         # The two `:exists` values — `File.exist?`'s answer rendered with `to_s`, which is what
         # {Descriptor#file_entry_fresh?} compares the live answer against.
@@ -163,6 +175,32 @@ module Rigor
           new(path: path, comparator: :exists, value: PRESENT)
         end
 
+        # The four `:kind` values, in the order {Analysis::Runner}'s path expansion asks: a directory, a regular
+        # file, something else that exists (a FIFO, a socket), nothing (a missing path or a dangling symlink).
+        # Each predicate follows symlinks, as the expansion's do.
+        KIND_DIRECTORY = "directory"
+        KIND_FILE = "file"
+        KIND_OTHER = "other"
+        KIND_ABSENT = "absent"
+
+        # #1962 — the kind row: fresh while `path` is still the same kind of thing, stale once it appears,
+        # vanishes, or a directory and a file trade places. It is the row for an analysis root, whose
+        # diagnostics (`no such file or directory`, `not a Ruby file`) answer to exactly that and to nothing
+        # else about the path, and for a `pre_eval:` entry and a signature root: an existence row would read a
+        # directory replaced by a file of the same name as fresh (ADR-45 WD1b's bound), and what the path holds
+        # has rows of its own (the analysed-file set the key carries, a signature root's `.rbs` rows).
+        def self.kind(path:)
+          new(path: path, comparator: :kind, value: kind_of(path))
+        end
+
+        def self.kind_of(path)
+          if File.directory?(path) then KIND_DIRECTORY
+          elsif File.file?(path) then KIND_FILE
+          elsif File.exist?(path) then KIND_OTHER
+          else KIND_ABSENT
+          end
+        end
+
         # @return whether this row records the path as absent (see {.absent}).
         def absent?
           comparator == :exists && value == ABSENT
@@ -294,7 +332,12 @@ module Rigor
         # tuple moves, so a `git checkout`, a `bundle install` or a CI cache restored over a fresh checkout
         # keeps the file rows fresh while it would move every glob signature, turning every such run into a
         # full re-analysis. `:names` also reads no stat at all, so it costs a `Dir.glob` and nothing else.
-        VALID_MODES = %i[stat names].freeze
+        #
+        # `:kinds` (#1959) is `:names` plus each match's `File.lstat` file type: the set moves it, and so does a
+        # path that keeps its name and changes kind (a file `gen` replaced by a directory `gen/`, a symlinked
+        # directory replaced by a real one). It reads one `lstat` per match and no content, so a `touch` or an
+        # edit leaves it fresh.
+        VALID_MODES = %i[stat names kinds].freeze
 
         attr_reader :root, :pattern, :value
 
@@ -326,13 +369,15 @@ module Rigor
         # The aggregate signature the entry's `value` carries: SHA-256 over the sorted per-file rows. In the
         # default (`:stat`) mode a row is the file's `(path, size, mtime_ns, ctime_ns, inode)` tuple — NO
         # content read; in strict mode a row is `(path, content-sha256)`, restoring the pre-ADR-87 authority.
-        # In `:names` mode a row is the path alone, stat-free, so only the matching SET moves the signature.
+        # In `:names` mode a row is the path alone, stat-free, so only the matching SET moves the signature; in
+        # `:kinds` mode it is the path and its {.lstat_kind}.
         # Per-file stat failures (a file vanishing between the glob and the stat) drop the row — same race
         # posture as {Descriptor#file_entry_fresh?}. `Dir.glob` returns sorted entries by default so the row
         # order — and therefore the signature — is stable.
         def self.signature_for(root:, pattern:, mode: :stat)
-          paths = Dir.glob(File.join(root, pattern))
+          paths = RootedGlob.glob(root, pattern)
           return Digest::SHA256.hexdigest(paths.map { |path| "#{path}#{ROW_SEPARATOR}" }.join) if mode == :names
+          return kinds_signature(paths) if mode == :kinds
 
           strict = FileDigest.strict_validation?
           rows = paths.filter_map do |path|
@@ -351,10 +396,29 @@ module Rigor
           Digest::SHA256.hexdigest(rows.join)
         end
 
+        # #1959 — what `path` itself is, a symlink not followed: `:file`, `:directory`, `:symlink` or `:other`, and
+        # `:absent` for a path that vanished between the glob and the `lstat`.
+        def self.lstat_kind(path)
+          case File.lstat(path).ftype
+          when "file" then :file
+          when "directory" then :directory
+          when "link" then :symlink
+          else :other
+          end
+        rescue SystemCallError
+          :absent
+        end
+
+        def self.kinds_signature(paths)
+          rows = paths.map { |path| "#{path}#{FIELD_SEPARATOR}#{lstat_kind(path)}#{ROW_SEPARATOR}" }
+          Digest::SHA256.hexdigest(rows.join)
+        end
+        private_class_method :kinds_signature
+
         # ADR-87 WD2 — fresh iff re-globbing + re-stat-ing reproduces the recorded signature. Zero file-content
-        # bytes are read in the default mode, and no stat at all in `:names`. Any failure reads as stale
-        # (recompute), never a crash. A stored signature recorded under the opposite validation mode simply
-        # mismatches and recomputes.
+        # bytes are read in the default mode, no stat at all in `:names`, and one `lstat` per match in `:kinds`.
+        # Any failure reads as stale (recompute), never a crash. A stored signature recorded under the opposite
+        # validation mode simply mismatches and recomputes.
         def self.fresh?(entry)
           signature_for(root: entry.root, pattern: entry.pattern, mode: entry.mode) == entry.value
         rescue StandardError
@@ -413,10 +477,11 @@ module Rigor
 
       # File-comparator strictness ordering. `:stat` is strictest (it carries the content digest AND a stat
       # tuple, so it validates content-authoritatively while short-circuiting on an unmoved stat); `:digest` is
-      # deterministic across machines; `:mtime` is cheaper but local; `:exists` is the weakest signal. Ranking
-      # `:stat` and `:digest` apart guarantees a path contributed under both never raises a value {Conflict}
-      # (their `value` strings differ by construction) — the stricter one wins and its value is used.
-      COMPARATOR_STRICTNESS = { stat: 3, digest: 2, mtime: 1, exists: 0 }.freeze
+      # deterministic across machines; `:mtime` is cheaper but local; `:kind` answers what the path is and
+      # `:exists` only whether it is there, the weakest signal. Ranking `:stat` and `:digest` apart guarantees a
+      # path contributed under both never raises a value {Conflict} (their `value` strings differ by
+      # construction) — the stricter one wins and its value is used.
+      COMPARATOR_STRICTNESS = { stat: 4, digest: 3, mtime: 2, kind: 1, exists: 0 }.freeze
       private_constant :COMPARATOR_STRICTNESS
 
       # Composes any number of descriptors into a single descriptor whose slots are the union of the inputs'
@@ -505,6 +570,8 @@ module Rigor
           FileDigest.stat_fresh?(entry.path, entry.value)
         when :mtime
           File.exist?(entry.path) && File.mtime(entry.path).to_i.to_s == entry.value
+        when :kind
+          FileEntry.kind_of(entry.path) == entry.value
         when :exists
           File.exist?(entry.path).to_s == entry.value
         else

data/lib/rigor/cache/engine_source.rb

@@ -4,6 +4,7 @@ require "digest"
 
 require_relative "../version"
 require_relative "descriptor"
+require_relative "../rooted_glob"
 
 module Rigor
   module Cache
@@ -195,8 +196,8 @@ module Rigor
       # Sorted, de-duplicated absolute paths of every engine `.rb` file and {DATA_GLOBS} data file, across
       # the directories that exist. `plugins/*/sig/**/*.rbs` overlaps nothing else but is de-duplicated anyway.
       def source_files(root)
-        sources = SOURCE_DIRECTORIES.flat_map { |relative| Dir.glob(File.join(root, relative, "**", "*.rb")) }
-        data = DATA_GLOBS.flat_map { |pattern| Dir.glob(File.join(root, pattern)) }
+        sources = SOURCE_DIRECTORIES.flat_map { |relative| RootedGlob.glob(root, File.join(relative, "**", "*.rb")) }
+        data = DATA_GLOBS.flat_map { |pattern| RootedGlob.glob(root, pattern) }
         (sources + data).uniq.sort
       end
     end

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
@@ -169,7 +170,19 @@ module Rigor
       # file's conditional `def` as certain and a warm run would answer a definer a cold run declines.
       # 37: ADR-119 WD3 — the visibility walk fills `contested_discovered_method_visibilities`, which a pre-37 bundle
       # carries empty.
-      SCHEMA = 37
+      # 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.
+      # 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.
@@ -224,11 +237,26 @@ 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
+      # compares this one after the recheck has loaded them.
       Payload = Data.define(:cache, :sources, :digests, :analyzed,
                             :symbol_sources, :ancestry_sources, :symbol_fingerprints,
                             :missing, :class_decls, :constant_decls, :seed_bundles, :plugin_fact_digest,
                             :return_summaries, :param_table,
-                            :effect_collections, :effects_identity, :run_level_rows)
+                            :effect_collections, :effects_identity, :run_level_rows,
+                            :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
 
       # Issues #796 / #794 — the two run-level rows the snapshot carries. `definition_build_failures` is the
       # reported per-class detail list ({Environment::RbsLoader#definition_build_failures}); `hkt_scan_failure`
@@ -353,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
@@ -434,7 +462,10 @@ module Rigor
           param_table: data[:param_table] || {},
           effect_collections: data[:effect_collections] || {},
           effects_identity: data[:effects_identity],
-          run_level_rows: data[:run_level_rows]
+          run_level_rows: data[:run_level_rows],
+          effect_plugin_digest: data[:effect_plugin_digest],
+          plugin_reads: data[:plugin_reads] || {},
+          discovery_digests: data.fetch(:discovery_digests, {})
         )
       end
       private :payload_from
@@ -459,7 +490,10 @@ module Rigor
           param_table: payload.param_table,
           effect_collections: payload.effect_collections,
           effects_identity: payload.effects_identity,
-          run_level_rows: payload.run_level_rows
+          run_level_rows: payload.run_level_rows,
+          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/mcp_command.rb

@@ -12,7 +12,7 @@ module Rigor
     # Starts a long-running MCP (Model Context Protocol) server over stdio. The server exposes Rigor's analysis tools as
     # MCP tool calls over a newline-delimited JSON-RPC 2.0 stream. See ADR-33.
     #
-    # Slice 1 ships the stdio transport with seven read-only tools: rigor_check, rigor_type_of, rigor_triage,
+    # The stdio transport serves eight read-only tools: rigor_check, rigor_type_of, rigor_triage, rigor_lens,
     # rigor_annotate, rigor_sig_gen, rigor_explain, rigor_coverage.
     class McpCommand < Command
       USAGE = "Usage: rigor mcp [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
@@ -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