rigortype 0.3.8 → 0.3.9

data/lib/rigor/sig_gen/observation_collector.rb

@@ -3,8 +3,10 @@
 require "prism"
 
 require_relative "../environment"
+require_relative "../project_environment"
 require_relative "../scope"
 require_relative "../type"
+require_relative "../source/constant_path"
 require_relative "../source/literals"
 require_relative "../source/node_children"
 require_relative "../inference/scope_indexer"
@@ -18,7 +20,7 @@ module Rigor
     # for every `Prism::CallNode` whose receiver types as a `Type::Nominal`. The {Generator} consumes the
     # resulting map to render `--params=observed` RBS:
     #
-    # @return [Hash{[class_name, method_name] => Array<Array<Rigor::Type>>}]
+    # @return => Array<Array<Rigor::Type>>}]
     #
     # ADR-5 clause 2 compliance: the observed union is the MOST PERMISSIVE parameter contract the existing
     # callers prove sufficient — by construction it accepts every type any caller has already passed. The
@@ -32,10 +34,9 @@ module Rigor
     #   the collector cannot attribute them to a specific class.
     # - Zero-argument calls give no observation; methods are matched by `(class_name, method_name)` only.
     class ObservationCollector # rubocop:disable Metrics/ClassLength
-      # @param configuration [Rigor::Configuration]
-      # @param paths [Array<String>] observe paths (files /
+      # @param paths — observe paths (files /
       #   directories).
-      # @param source_paths [Array<String>] source-tree paths
+      # @param source_paths — source-tree paths
       #   (defaults to `configuration.paths`) pre-walked to
       #   register every project-defined class so that calls
       #   like `Foo.new.bar(x)` in the observe tree resolve
@@ -51,10 +52,11 @@ module Rigor
       def collect
         return {} if @paths.empty?
 
-        environment = build_environment
+        resolved = resolve_paths(@paths)
+        environment = build_environment(resolved)
         discovered_classes = preindex_source_classes
         observations = Hash.new { |h, k| h[k] = [] }
-        resolve_paths(@paths).each do |path|
+        resolved.each do |path|
           collect_from_file(path, environment, discovered_classes, observations)
         end
         observations.transform_values(&:freeze).freeze
@@ -62,11 +64,11 @@ module Rigor
 
       private
 
-      def build_environment
-        Environment.for_project(
-          libraries: @configuration.libraries,
-          signature_paths: @configuration.signature_paths
-        )
+      # Issue #821 — same universe as the generator and as `rigor check`; see
+      # {Generator#build_environment}. An observation collected against a narrower environment types its
+      # argument differently from the run that will consume it.
+      def build_environment(source_files = [])
+        ProjectEnvironment.build(configuration: @configuration, source_files: source_files)
       end
 
       def resolve_paths(args)
@@ -118,11 +120,11 @@ module Rigor
         return unless node.is_a?(Prism::Node)
 
         if node.is_a?(Prism::ClassNode) || node.is_a?(Prism::ModuleNode)
-          name = qualified_constant_path(node.constant_path)
-          if name
-            full = (prefix + [name]).join("::")
+          child_prefix = Source::ConstantPath.declaration_prefix(prefix, node.constant_path)
+          if child_prefix
+            full = child_prefix.join("::")
             accumulator[full] = Type::Combinator.singleton_of(full)
-            walk_class_decls(node.body, prefix + [name], accumulator) if node.body
+            walk_class_decls(node.body, child_prefix, accumulator) if node.body
             return
           end
         end

data/lib/rigor/sig_gen/path_mapper.rb

@@ -21,9 +21,8 @@ module Rigor
     # When the source path is not under any configured source root (e.g. files supplied directly on the CLI
     # from outside `lib/`), the full relative path is preserved under the sig root.
     class PathMapper
-      # @param configuration [Rigor::Configuration]
-      # @param project_root [String, Pathname] (defaults to `Dir.pwd`)
-      # @param layout_index [LayoutIndex, nil] optional class
+      # @param project_root — (defaults to `Dir.pwd`)
+      # @param layout_index — optional class
       #   → existing sig file index; routes the target to the
       #   consolidated file when the class is already declared.
       def initialize(configuration:, project_root: Dir.pwd, layout_index: nil)
@@ -32,12 +31,11 @@ module Rigor
         @layout_index = layout_index
       end
 
-      # @param source_path [String]
-      # @param class_name [String, nil] fully-qualified Ruby
+      # @param class_name — fully-qualified Ruby
       #   class name. When supplied and matched by the
       #   `LayoutIndex`, the consolidated sig file's path is
       #   returned instead of the 1:1 mirror.
-      # @return [Pathname] absolute path of the target `.rbs`
+      # @return absolute path of the target `.rbs`
       #   file for the candidate.
       def target_for(source_path, class_name: nil)
         existing = existing_target_for(class_name)

data/lib/rigor/sig_gen/rbs_validity.rb

@@ -23,16 +23,16 @@ module Rigor
 
       module_function
 
-      # @param line [String] a rendered RBS method line, e.g. `def self.parse: (String) -> Integer`.
-      # @return [String, nil] the parse error's first line, or nil when the line is valid.
+      # @param line — a rendered RBS method line, e.g. `def self.parse: (String) -> Integer`.
+      # @return the parse error's first line, or nil when the line is valid.
       def method_line_error(line)
         return nil if line.nil?
 
         source_error("class #{PROBE_CLASS}\n  #{line}\nend\n")
       end
 
-      # @param source [String] a complete `.rbs` file's text.
-      # @return [String, nil] the parse error's first line, or nil when the file is valid.
+      # @param source — a complete `.rbs` file's text.
+      # @return the parse error's first line, or nil when the file is valid.
       def source_error(source)
         ::RBS::Parser.parse_signature(::RBS::Buffer.new(name: "(rigor sig-gen)", content: source))
         nil

data/lib/rigor/sig_gen/renderer.rb

@@ -3,6 +3,7 @@
 require "json"
 
 require_relative "classification"
+require_relative "superclass_spelling"
 
 module Rigor
   module SigGen
@@ -21,10 +22,8 @@ module Rigor
         @out = out
       end
 
-      # @param candidates [Array<MethodCandidate>]
-      # @param mode [:print, :diff]
-      # @param format [String] "text" or "json"
-      # @param selection [Array<Symbol>] subset of
+      # @param format — "text" or "json"
+      # @param selection — subset of
       #   {Classification} constants to include; an empty
       #   array means "all emittable classifications".
       def render(candidates:, mode:, format:, selection:)
@@ -91,7 +90,7 @@ module Rigor
         return "module #{class_name}" if candidate.namespace_kinds[class_name] == :module
 
         superclass = candidate.class_superclasses[class_name]
-        superclass ? "class #{class_name} < #{superclass}" : "class #{class_name}"
+        superclass ? "class #{class_name} < #{SuperclassSpelling.absolute(superclass)}" : "class #{class_name}"
       end
 
       def render_diff(candidates)

data/lib/rigor/sig_gen/skip_reason_catalog.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative "classification"
+
+module Rigor
+  module SigGen
+    # Answers for the `sig.skipped.*` identifiers `rigor sig-gen` prints when it declines to emit a
+    # signature for a method.
+    #
+    # ADR-108 WD4 — a skip id is an ANSWER ("Rigor cannot prove a type here"), and the command that exists
+    # to answer identifiers must be able to answer it. `rigor explain` resolves against
+    # {Analysis::RuleCatalog}, which carries diagnostic rules only, so `rigor explain
+    # sig.skipped.untyped-return` used to reply `Unknown rule` for an id Rigor had just printed. This is the
+    # second catalogue `explain` consults; it is deliberately separate from the rule catalog because a skip
+    # reason has no severity, no profile mapping and no suppression, and forcing it into {RuleCatalog::Entry}
+    # would mean inventing four fields that do not apply.
+    #
+    # Every id in {Classification::SKIP_DIAGNOSTIC_IDS} MUST have an entry here; the gate is
+    # `spec/rigor/sig_gen/skip_reason_catalog_spec.rb`.
+    module SkipReasonCatalog
+      class Entry < Data.define(:id, :summary, :explanation, :next_step)
+        # Hash-shaped form for `rigor explain --format=json`. String keys, and `kind` distinguishes a skip
+        # reason from a rule entry in a stream a consumer may receive either from.
+        def to_h
+          {
+            "id" => id,
+            "kind" => "sig_skip_reason",
+            "summary" => summary,
+            "explanation" => explanation,
+            "next_step" => next_step
+          }
+        end
+      end
+
+      ENTRIES = {
+        "sig.skipped.untyped-return" => Entry.new(
+          id: "sig.skipped.untyped-return",
+          summary: "The method's return types as Dynamic[top], so no signature was written.",
+          explanation: "Rigor inferred the body but the value it returns has no proven type — the last " \
+                       "expression widened to Dynamic[top] somewhere up its chain. Emitting `untyped` here " \
+                       "would record noise as a contract: the file would gain a signature that says nothing " \
+                       "and stops a later, better inference from being noticed. This is the commonest skip " \
+                       "reason on a project whose dependencies have no RBS.",
+          next_step: "Do not write the return type by hand — the skip is the finding. Trace the returned " \
+                     "expression back to where it became dynamic (`rigor annotate PATH` reads the `#=>` " \
+                     "column, `rigor trace --format=json --line=N` for one line) and close THAT: install or " \
+                     "write RBS for the dependency, enable the plugin for the framework, or report an " \
+                     "engine gap."
+        ),
+        "sig.skipped.user-authored" => Entry.new(
+          id: "sig.skipped.user-authored",
+          summary: "An RBS declaration for this method already exists and was left alone.",
+          explanation: "Not a gap. The project already states a type for this member, and sig-gen does not " \
+                       "overwrite a hand-authored contract without being told to. Where `sig/` and an inline " \
+                       "annotation both declare the member, `sig/` wins.",
+          next_step: "Read the existing declaration. If it disagrees with what Rigor infers, raise the " \
+                     "disagreement rather than silently retyping it; pass `--overwrite` only once you have " \
+                     "decided the generated type is the better contract."
+        ),
+        "sig.skipped.unrenderable-rbs" => Entry.new(
+          id: "sig.skipped.unrenderable-rbs",
+          summary: "Rigor rendered a line that `rbs` itself rejects, so the method was dropped.",
+          explanation: "A defect in Rigor's renderer, not in your code. The method is skipped rather than " \
+                       "written so one pathological signature cannot make the whole generated file " \
+                       "unparseable, and the count is reported so the defect is not silent.",
+          next_step: "Report it, with the method and the file. `rigor sig-gen --print PATH` shows what was " \
+                     "generated for the rest of the file and is the useful attachment."
+        ),
+        "sig.skipped.complex-shape" => Entry.new(
+          id: "sig.skipped.complex-shape",
+          summary: "Reserved for a shape too complex to render; no code path produces it today.",
+          explanation: "The identifier is part of the reserved `sig.skipped.*` family and is carried so the " \
+                       "family stays stable, but no generator path emits it.",
+          next_step: "If you have actually seen this id in output, that is itself worth reporting — it means " \
+                     "a path exists that this catalogue does not describe."
+        ),
+        "sig.skipped.unresolvable-superclass" => Entry.new(
+          id: "sig.skipped.unresolvable-superclass",
+          summary: "The class's superclass chain does not end in a class the RBS environment knows.",
+          explanation: "Writing the declaration would make things worse rather than better: RBS would read " \
+                       "the class as rooted at an unknown parent and collapse it on the next run, losing the " \
+                       "members it can resolve today.",
+          next_step: "Give the environment the missing ancestor — install or write RBS for the gem that " \
+                     "defines it, or add the project file that declares it to the analysed paths — then " \
+                     "re-run `rigor sig-gen`."
+        ),
+        "sig.skipped.overridden-by-unsigned-subclass" => Entry.new(
+          id: "sig.skipped.overridden-by-unsigned-subclass",
+          summary: "A subclass overrides this method and its override was not itself emitted.",
+          explanation: "A declaration on the parent is inherited by every subclass that does not redeclare " \
+                       "the member. Emitting it here would hand the subclass a type describing the parent's " \
+                       "body, not the override the subclass actually runs.",
+          next_step: "Generate signatures for the overriding subclass too — widen the `sig-gen` path set to " \
+                     "cover it — and the parent's declaration becomes safe to emit."
+        )
+      }.freeze
+
+      module_function
+
+      # @param token — a `sig.skipped.*` identifier.
+      # @return the matching entry, or nil when the token is not a known skip reason.
+      def resolve(token)
+        ENTRIES[token.to_s]
+      end
+
+      def all
+        ENTRIES.values
+      end
+    end
+  end
+end

data/lib/rigor/sig_gen/superclass_spelling.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Rigor
+  module SigGen
+    # Renders a recorded superclass token into the spelling that goes on an emitted `class` header.
+    #
+    # Issue [#609](https://github.com/rigortype/rigor/issues/609): every token that survives
+    # {Generator#demote_unresolvable_superclasses} names a class the RBS environment or this run declares at an
+    # ABSOLUTE position — both guards ask `Reflection.rbs_class_known?` and the emitted-name set, and both are
+    # keyed by fully qualified name. The writer then emitted that token bare inside a nested `module` tree, where
+    # RBS resolves its first segment relatively against the enclosing namespaces, so `class Show < Help::Show`
+    # written under `module Views; module Help` re-points at `::Views::Help::Show` — the class being declared.
+    # The self-referential ancestry is what made `AncestorBuilder#singleton_ancestors` recurse until the stack
+    # was exhausted on the reporter's project, and what `RBS::RecursiveAncestorError` collapses the class over on
+    # a smaller one. Anchoring the token with `::` says the name the guards already checked.
+    module SuperclassSpelling
+      module_function
+
+      # @param token — a recorded superclass token, possibly carrying type arguments (`Foo::Bar[untyped]`).
+      def absolute(token)
+        return token if token.nil? || token.start_with?("::")
+
+        "::#{token}"
+      end
+    end
+  end
+end

data/lib/rigor/sig_gen/type_elaborator.rb

@@ -20,9 +20,7 @@ module Rigor
     # The module is sig-gen-local; the broader question of whether the inference engine itself should always
     # construct generics with explicit type_args is queued as an ADR-14 follow-up.
     module TypeElaborator
-      # @param type [Rigor::Type]
-      # @param environment [Rigor::Environment]
-      # @return [Rigor::Type] same shape with bare generic
+      # @return same shape with bare generic
       #   nominals filled in.
       def self.elaborate(type, environment:)
         arity_cache = {}

data/lib/rigor/sig_gen/writer.rb

@@ -4,6 +4,7 @@ require "fileutils"
 require "rbs"
 
 require_relative "classification"
+require_relative "superclass_spelling"
 require_relative "write_result"
 
 module Rigor
@@ -50,8 +51,7 @@ module Rigor
       # ADR-14 follow-up: this is the consolidated-layout entry point. The legacy `write(source_path,
       # candidates)` below assumes all candidates share a target and remains for spec convenience.
       #
-      # @param candidates [Array<MethodCandidate>]
-      # @return [Array<WriteResult>] one per target sig file.
+      # @return one per target sig file.
       def write_all(candidates)
         emittable = candidates.select { |c| EMITTABLE.include?(c.classification) }
         return [] if emittable.empty?
@@ -62,12 +62,10 @@ module Rigor
                  .map { |target, group| write_target(target, group) }
       end
 
-      # @param source_path [String]
-      # @param candidates [Array<MethodCandidate>] only
+      # @param candidates — only
       #   emittable classifications (new-method /
       #   tighter-return) are honoured; the caller is
       #   responsible for filtering.
-      # @return [WriteResult]
       def write(source_path, candidates)
         emittable = candidates.select { |c| EMITTABLE.include?(c.classification) }
         return WriteResult.new(source_path: source_path, target_path: nil, action: :noop) if emittable.empty?
@@ -261,7 +259,7 @@ module Rigor
         return "" unless keyword == :class
 
         superclass = supers[qualified]
-        superclass ? " < #{superclass}" : ""
+        superclass ? " < #{SuperclassSpelling.absolute(superclass)}" : ""
       end
 
       # Per ADR-14 gap-#3 (a) the keyword for a segment comes from `namespace_kinds` when known. The default for
@@ -660,6 +658,8 @@ module Rigor
       end
 
       def eligible_for_replacement?(candidate, decl, source)
+        return false if replaces_declared_void?(candidate, decl)
+
         case candidate.classification
         when Classification::TIGHTER_RETURN then true
         when Classification::NEW_METHOD then tightens_untyped?(candidate, decl, source)
@@ -667,6 +667,23 @@ module Rigor
         end
       end
 
+      # Issue #836 — `--overwrite` never turns a declared `-> void` into a value return. The generator no
+      # longer proposes one (`Generator#declares_void?` classifies the method `equivalent`), but the writer
+      # reaches the same member through case 2 above whenever the RBS environment did not resolve the `def` to
+      # this declaration: an observed-parameter upgrade of `(untyped m) -> void` to `(Module m) -> Registry`
+      # counts one `untyped` fewer and would be applied, erasing the author's statement that the return is not
+      # part of the contract. A candidate that keeps `void` is still eligible, which is what case 2 is for —
+      # the `initialize` stub is always spelled `-> void`.
+      def replaces_declared_void?(candidate, decl)
+        member = find_method_member(decl, candidate.method_name, candidate.kind)
+        return false if member.nil?
+
+        declared_void = member.overloads.any? do |overload|
+          overload.method_type.type.return_type.is_a?(RBS::Types::Bases::Void)
+        end
+        declared_void && !candidate.rbs.to_s.end_with?(" -> void")
+      end
+
       # Compares the existing member's source-side RBS text against the candidate's proposed RBS text. Returns
       # true when the new spelling has STRICTLY FEWER bare `untyped` tokens than the existing one — i.e. at
       # least one `untyped` slot becomes a concrete type AND no concrete slot becomes `untyped`. Word-boundary

data/lib/rigor/signature_path_audit.rb

@@ -16,7 +16,24 @@ module Rigor
   # The audit deliberately mirrors the loader's own acceptance test (`path.directory?` + a
   # recursive `**/*.rbs` glob) so a `:ok` verdict means the loader did load from it and a
   # warning means it did not.
+  #
+  # {.bundled_plugin_routes} answers the mirror-image question — an entry that loads too
+  # *little of the plugin*, rather than nothing at all. See its own comment.
   module SignaturePathAudit
+    # The `plugins/` tree of the engine running this code, anchored from THIS file
+    # (`<root>/lib/rigor/signature_path_audit.rb`) so a git checkout and an installed
+    # `rigortype` gem answer identically — the anchor {Plugin::Loader::ENGINE_ROOT} uses, for
+    # the reason it documents.
+    #
+    # Deliberately re-derived rather than read off `Plugin::Loader`: ADR-87 WD4 keeps this
+    # file, which every `rigor check` loads before the cache probe, off the plugin
+    # subsystem's require graph — and that graph is order-dependent (`plugin/registry.rb`
+    # resolves `NodeRuleWalk` at load, which only `rigor/plugin.rb` has required by then), so
+    # requiring the loader from here fails outright. `signature_path_audit_spec` pins the two
+    # anchors equal, and pins this discovery against `Loader.bundled_plugin_sig_path`, so the
+    # duplication cannot drift unnoticed.
+    BUNDLED_PLUGINS_ROOT = File.expand_path("../../plugins", __dir__)
+
     # One configured `signature_paths:` entry's resolution status.
     #
     # `status` is one of:
@@ -60,17 +77,11 @@ module Rigor
     # `nil` — the unset default, where Rigor auto-detects `<root>/sig` — to get an empty
     # result: an absent auto-detected `sig/` is a normal setup, not a misconfiguration, so it
     # is never audited.
-    #
-    # @param signature_paths [Array<String, Pathname>, nil]
-    # @return [Array<Entry>]
     def self.audit(signature_paths)
       Array(signature_paths).map { |path| classify(path.to_s) }
     end
 
     # The subset of {audit} that resolved to nothing — the entries worth warning about.
-    #
-    # @param signature_paths [Array<String, Pathname>, nil]
-    # @return [Array<Entry>]
     def self.warnings(signature_paths)
       audit(signature_paths).select(&:warning?)
     end
@@ -82,5 +93,141 @@ module Rigor
       count = Dir.glob(File.join(path, "**", "*.rbs")).size
       Entry.new(path: path, status: count.zero? ? :empty : :ok, rbs_file_count: count)
     end
+
+    # One configured entry that reaches the `sig/` of a plugin THIS engine bundles, while
+    # `plugins:` never names that plugin (issue #697).
+    BundledPluginRoute = Data.define(:path, :gem) do
+      # Names the plugin and the one edit that fixes it. The consequence is spelled out
+      # because the symptom the user actually sees is `call.undefined-method` on code that
+      # runs — nothing in that row points back at the `signature_paths:` line.
+      def message
+        "signature_paths: #{path.inspect} loads the signatures of the bundled plugin #{gem.inspect}, " \
+          "which `plugins:` does not name — so the plugin's manifest never loads, and the classes it " \
+          "declares only partially on purpose (ADR-26 `open_receivers:`) are read as complete, which " \
+          "reports methods your code really defines as undefined. " \
+          "Add #{gem.inspect} to `plugins:` instead of naming its `sig/` in `signature_paths:`."
+      end
+
+      def to_h
+        { "path" => path, "gem" => gem, "message" => message }
+      end
+    end
+
+    # The mirror image of {.warnings}: an entry the loader reads perfectly well, which
+    # nevertheless leaves the user worse off than not configuring it.
+    #
+    # A bundled plugin ships two halves that only work together — the RBS under its `sig/`,
+    # and the manifest that says which of those declarations are deliberately partial
+    # (ADR-26 `open_receivers:`). `plugins:` loads both; `signature_paths:` loads only the
+    # first, and the partial declarations then read as complete, so a scope the application
+    # really defines draws `call.undefined-method`. This is a configuration mistake with no
+    # visible cause, so it is reported here rather than fixed by teaching the check rules yet
+    # another route to the same protection — which is [#660](https://github.com/rigortype/rigor/issues/660)'s
+    # question to settle, not this warning's.
+    #
+    # **What it asks is what the entry LOADS, not what it looks like**, exactly as
+    # `Environment::RbsLoader.bundled_overlay_twin_signatures_loaded?` does for the overlay
+    # stand-down: both sides are `File.realpath`'d and matched against the plugin's actual
+    # `.rbs` files, so a symlink or a case-variant spelling answers the same as the directory
+    # itself, and an entry naming a file (or a directory that does not exist) — which the
+    # loader reads nothing from — matches nothing. The two are not single-homed because the
+    # overlay-side predicate lives on the RBS loader, and ADR-87 WD4 keeps this file, which
+    # every `rigor check` loads before the cache probe, off the engine's require graph.
+    #
+    # @param signature_paths — {Configuration#signature_paths}; `nil` (the unset default,
+    #   where Rigor auto-detects `<root>/sig`) is never audited.
+    # @param plugins — the raw {Configuration#plugins} list.
+    def self.bundled_plugin_routes(signature_paths, plugins = [])
+      entries = resolved_entries(signature_paths)
+      return [] if entries.empty?
+
+      root = canonical_path(BUNDLED_PLUGINS_ROOT)
+      return [] if root.nil? || entries.none? { |(_, dir)| overlapping?(dir, root) }
+
+      listed = listed_plugin_names(plugins)
+      bundled_plugin_sig_dirs.reject { |gem, _| listed?(gem, listed) }.flat_map do |gem, sig_dir|
+        files = canonical_rbs_files(sig_dir)
+        next [] if files.empty?
+
+        entries.filter_map do |(entry, dir)|
+          BundledPluginRoute.new(path: entry, gem: gem) if files.any? { |file| under?(file, dir) }
+        end
+      end
+    end
+
+    # `[entry as configured, canonical directory]` for every entry the loader would read from.
+    def self.resolved_entries(signature_paths)
+      Array(signature_paths).filter_map do |entry|
+        dir = canonical_path(entry.to_s)
+        [entry.to_s, dir] if dir && File.directory?(dir)
+      end
+    end
+    private_class_method :resolved_entries
+
+    # Gem name of every plugin the engine bundles that ships signatures, to its `sig/`.
+    # Derived from the `plugins/` tree rather than listed, for {Plugin::FirstParty}'s reason:
+    # a list would be a second source of truth, and its first drift would silently stop
+    # warning about the plugin that drifted.
+    def self.bundled_plugin_sig_dirs
+      return {} unless File.directory?(BUNDLED_PLUGINS_ROOT)
+
+      Dir.children(BUNDLED_PLUGINS_ROOT).sort.filter_map do |gem|
+        sig = File.join(BUNDLED_PLUGINS_ROOT, gem, "sig")
+        [gem, sig] if File.directory?(sig)
+      end.to_h
+    end
+
+    # Every name a `plugins:` entry puts on the record, in both the bare-string and the
+    # `gem:` / `id:` hash forms. An `enabled: false` entry counts as named even though it
+    # loads nothing: the user has demonstrably found the plugin, and telling them to add what
+    # is already there would be worse than staying quiet. Under-warning is this module's
+    # standing FP-safe direction.
+    def self.listed_plugin_names(plugins)
+      Array(plugins).flat_map do |raw|
+        case raw
+        when String then [raw]
+        when Hash
+          keyed = raw.to_h { |key, value| [key.to_s, value] }
+          [keyed["gem"], keyed["id"]].compact.map(&:to_s)
+        else []
+        end
+      end.to_set
+    end
+    private_class_method :listed_plugin_names
+
+    # A bundled plugin's manifest id is its gem name minus the `rigor-` prefix, and `plugins:`
+    # accepts either spelling as `id:`, so both count as naming it.
+    def self.listed?(gem, listed)
+      require_relative "plugin/first_party"
+      listed.include?(gem) || listed.include?(gem.delete_prefix(Plugin::FirstParty::GEM_PREFIX))
+    end
+    private_class_method :listed?
+
+    def self.canonical_rbs_files(dir)
+      Dir.glob(File.join(dir, "**", "*.rbs")).filter_map { |file| canonical_path(file) }
+    end
+    private_class_method :canonical_rbs_files
+
+    # `File.realpath`, not `File.expand_path`: it resolves symlinks and, on a case-folding
+    # filesystem, the on-disk spelling. It raises for a path that does not exist, which is
+    # the answer wanted here — a path the loader cannot read is not a route to anything.
+    def self.canonical_path(path)
+      File.realpath(path.to_s)
+    rescue SystemCallError
+      nil
+    end
+    private_class_method :canonical_path
+
+    def self.under?(path, dir)
+      path.start_with?("#{dir}#{File::SEPARATOR}")
+    end
+    private_class_method :under?
+
+    # Whether the two directories could possibly share a file. The cheap prune that keeps the
+    # per-plugin globs off every run whose `signature_paths:` point at the project's own tree.
+    def self.overlapping?(one, other)
+      one == other || under?(one, other) || under?(other, one)
+    end
+    private_class_method :overlapping?
   end
 end

data/lib/rigor/source/literals.rb

@@ -31,9 +31,6 @@ module Rigor
 
       # The Symbol a literal `Prism::SymbolNode` / `Prism::StringNode` names, or `nil` for any other node
       # (including `nil`).
-      #
-      # @param node [Prism::Node, nil]
-      # @return [Symbol, nil]
       def symbol_or_string(node)
         return nil unless node.is_a?(Prism::SymbolNode) || node.is_a?(Prism::StringNode)
 
@@ -44,9 +41,6 @@ module Rigor
       # (including `nil`). The String-returning sibling of {.symbol_or_string} — for callers that key on the
       # raw name rather than the interned Symbol (route helpers, factory names, filter targets).
       # `#unescaped` round-trips an interpolation-free `:foo` / `"foo"` to `"foo"` for both kinds.
-      #
-      # @param node [Prism::Node, nil]
-      # @return [String, nil]
       def symbol_or_string_name(node)
         return nil unless node.is_a?(Prism::SymbolNode) || node.is_a?(Prism::StringNode)
 
@@ -56,9 +50,6 @@ module Rigor
       # The Symbol a literal `Prism::SymbolNode` names, or `nil` for any other node (including a
       # `Prism::StringNode` and `nil`). Stricter than {.symbol_or_string}: a DSL that accepts only `:draft`
       # and not `"draft"` keeps that distinction by reaching for this rather than the Symbol-or-String form.
-      #
-      # @param node [Prism::Node, nil]
-      # @return [Symbol, nil]
       def symbol(node)
         return nil unless node.is_a?(Prism::SymbolNode)
 
@@ -68,9 +59,6 @@ module Rigor
       # The String a literal `Prism::SymbolNode` names, or `nil` for any other node (including a
       # `Prism::StringNode` and `nil`). The String-returning sibling of {.symbol} — SymbolNode-only, but the
       # caller wants the raw name rather than the interned Symbol.
-      #
-      # @param node [Prism::Node, nil]
-      # @return [String, nil]
       def symbol_name(node)
         return nil unless node.is_a?(Prism::SymbolNode)
 
@@ -79,9 +67,6 @@ module Rigor
 
       # Every literal Symbol/String positional argument of a call, in source order. Non-literal arguments
       # are dropped. Returns `[]` when the call has no argument list.
-      #
-      # @param call_node [Prism::CallNode, nil]
-      # @return [Array<Symbol>]
       def symbol_arguments(call_node)
         args = call_node&.arguments&.arguments
         return [] if args.nil?
@@ -93,20 +78,12 @@ module Rigor
       # {.symbol_name} — for callers that need a predicate rather than an extraction (hash-key matching in
       # keyword or assoc argument positions, e.g. `el.is_a?(AssocNode) && symbol_named?(el.key, "required")`).
       # Uses `#unescaped` (not `#value`) for round-trip consistency.
-      #
-      # @param node [Prism::Node, nil]
-      # @param name [String]
-      # @return [Boolean]
       def symbol_named?(node, name)
         node.is_a?(Prism::SymbolNode) && node.unescaped == name
       end
 
       # The literal Symbol/String at positional `index`, or `nil` when the call has no argument list, the
       # index is out of range, or the argument there is not a literal Symbol/String.
-      #
-      # @param call_node [Prism::CallNode, nil]
-      # @param index [Integer]
-      # @return [Symbol, nil]
       def symbol_arg(call_node, index)
         args = call_node&.arguments&.arguments
         return nil if args.nil?

data/lib/rigor/source/node_children.rb

@@ -106,8 +106,6 @@ module Rigor
       # e.g. `node.body`). Pure and re-entrant; `break` / `next` / `return` in the block behave exactly as they
       # would with `compact_child_nodes.each`. Walkers holding a known `Prism::Node` call `#rigor_each_child`
       # directly; this wrapper is the nil-tolerant entry.
-      #
-      # @yieldparam child [Prism::Node]
       def each_child(node, &)
         node.rigor_each_child(&) if node.is_a?(Prism::Node)
       end