rigortype 0.4.1 → 0.4.3

data/lib/rigor/analysis/reachability/scan_cache.rb

@@ -48,11 +48,13 @@ module Rigor
         # @param cache_path — the configuration's cache root; nil or empty is an inert
         #   cache (every fetch computes, nothing persists).
         # @param target_ruby — parse-affecting configuration, part of the identity.
-        def self.open(cache_path, target_ruby: nil)
+        # `root` names the project and working directory a run reads roles and spellings from (#1760): a
+        # scan cached by a run from another directory carries another role, so it is never served here.
+        def self.open(cache_path, target_ruby: nil, root: nil)
           return new(path: nil, header: nil) if cache_path.nil? || cache_path.to_s.empty?
 
           new(path: File.join(cache_path.to_s, FILE_NAME),
-              header: "#{SCHEMA}:#{Rigor::VERSION}:#{target_ruby}:#{source_digest}")
+              header: "#{SCHEMA}:#{Rigor::VERSION}:#{target_ruby}:#{source_digest}:#{root}")
         end
 
         def self.source_digest

data/lib/rigor/analysis/rule_catalog.rb

@@ -292,6 +292,38 @@ module Rigor
           since: "0.0.1"
         ),
 
+        CheckRules::RULE_DEPRECATED_RUBY2_KEYWORDS => Entry.new(
+          id: CheckRules::RULE_DEPRECATED_RUBY2_KEYWORDS,
+          summary: "A call to the ruby2_keywords family Ruby 4.1 deprecates, under an explicit target_ruby >= 4.1.",
+          fires_when: [
+            "`.rigor.yml` sets `target_ruby` explicitly to \"4.1\" or later.",
+            "The call reaches `Module#ruby2_keywords` (no receiver or `self` in a class / module body, a " \
+            "`class << self` body or a singleton method), top-level `ruby2_keywords` (at the top level, outside " \
+            "any block), or `Proc#ruby2_keywords` (a receiver typed `Proc`): removed in Ruby 4.4.",
+            "The call reaches `Hash.ruby2_keywords_hash?` or `Hash.ruby2_keywords_hash` (on `Hash` or a subclass " \
+            "RBS knows): removed in Ruby 4.5.",
+            "The same names through `send` / `__send__` with a literal Symbol."
+          ],
+          does_not_fire_when: [
+            "`target_ruby` is absent, is the default, is below 4.1, or is \"latest\" (which names a parser, " \
+            "not a runtime).",
+            "A project or `pre_eval:` file defines a method by the same name anywhere.",
+            "The call sits in a block at the top level, in an `instance_eval` / `instance_exec` block, in an " \
+            "instance method of a class or module, or on an explicit receiver that is not `Proc` / `Hash`.",
+            "The call sits in a version-guard arm that cannot run on the stated Ruby, under a guard on " \
+            "`RUBY_VERSION` that cannot be decided, or after a guard that returns or raises."
+          ],
+          suppression: "`# rigor:disable call.deprecated-ruby2-keywords` on the call line. To fix it instead, " \
+                       "rewrite the delegation the flag serves to `(...)` or `(*args, **kwargs, &block)` first, then " \
+                       "drop the `ruby2_keywords` call: removing it alone breaks keyword pass-through.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :info, balanced: :warning, strict: :error },
+          # Each call names a known core method on a receiver whose class the syntax or the scope fixes, and a
+          # project definition of the name silences it. A file loaded only on an older Ruby is the residual.
+          evidence_tier: :high,
+          since: "0.4.2"
+        ),
+
         CheckRules::RULE_ALWAYS_RAISES => Entry.new(
           id: CheckRules::RULE_ALWAYS_RAISES,
           summary: "Call provably raises (today: Integer division-by-zero).",
@@ -552,6 +584,9 @@ module Rigor
           ],
           does_not_fire_when: [
             "Override raises or preserves visibility (only reductions break substitutability).",
+            "The method is one Ruby makes private wherever it is defined (`initialize`, " \
+            "`initialize_copy` / `_dup` / `_clone`, `respond_to_missing?`), so its section is not its " \
+            "runtime visibility (ADR-35 WD10).",
             "The shadowed method lives on an RBS-known / third-party ancestor (RBS models only " \
             "public/private; RBS-parent visibility is a deferred follow-on).",
             "`def self.foo` singleton methods (visibility is instance-side only).",
@@ -578,6 +613,9 @@ module Rigor
           does_not_fire_when: [
             "Either side lacks an authored RBS signature (WD1 both-sides-authored gate).",
             "The override narrows or preserves the return (covariant-safe).",
+            "`initialize` and the `initialize_copy` / `_dup` / `_clone` hooks: `Class#new` / `dup` / " \
+            "`clone` reach them on the receiver's own class and discard their return, outside " \
+            "substitutability (ADR-35 WD10).",
             "The ancestor's return is `untyped` / `self` / an unbound generic (degrades to " \
             "`Dynamic[Top]`, which accepts everything — FP-safe).",
             "The subtype relationship between the two return types is not resolvable from loaded " \
@@ -609,6 +647,9 @@ module Rigor
           does_not_fire_when: [
             "Either side lacks an authored RBS signature (WD1 both-sides-authored gate).",
             "The override widens or preserves the parameter (contravariant-safe).",
+            "`initialize` and the `initialize_copy` / `_dup` / `_clone` hooks: `Class#new` / `dup` / " \
+            "`clone` reach them only on the receiver's own class, so no parent-typed caller passes the " \
+            "parent's arguments (ADR-35 WD10).",
             "Either side is overloaded (more than one method type — arm mapping is ambiguous).",
             "The ancestor's parameter is `untyped` / an unbound generic / an interface (degrades " \
             "to `Dynamic[Top]`, which is passable to anything — FP-safe).",
@@ -640,6 +681,8 @@ module Rigor
           ],
           does_not_fire_when: [
             "Later write is `nil` — the `@cache = nil` clear-idiom is allowlisted.",
+            "The class's RBS declares the ivar (`@var: T`, or the slot an `attr_*` member implies, own or " \
+            "inherited) and that type accepts both the first write and the later one.",
             "Either side is Union / Dynamic / IntegerRange / a shape-varied carrier.",
             "Writes live in different classes that happen to share an ivar name.",
             "Writes are in a singleton body — `def self.foo` or a `class << self` def — those track " \

data/lib/rigor/analysis/run_cache_key.rb

@@ -21,6 +21,9 @@ require_relative "../environment/default_libraries"
 # lockfile paths without loading `rigor/environment` or the RBS machinery.
 require_relative "../environment/lockfile_resolver"
 require_relative "../environment/rbs_collection_discovery"
+# A leaf file (it loads only the cache descriptor), unlike `dependency_source_inference`, whose walker loads the
+# inference engine the boot-slimming probe exists to avoid.
+require_relative "dependency_source_inference/gem_resolver"
 require_relative "shadow_harness"
 
 module Rigor
@@ -93,6 +96,7 @@ module Rigor
       def descriptor(configuration:, files:, explain:, rbs_config_entries:, template_units_digest: nil)
         Cache::Descriptor.new(
           gems: [Cache::RbsDescriptor.rbs_gem_entry],
+          dependencies: dependency_source_entries(configuration),
           configs: rbs_config_entries + engine_source_entries + lockfile_entries(configuration) +
                    template_unit_entries(template_units_digest) + shadow_harness_entries + [
                      config_entry("configuration", Marshal.dump(configuration.to_h)),
@@ -151,6 +155,14 @@ module Rigor
         [lockfile_entry("bundler.lockfile", bundler), lockfile_entry("rbs_collection.lockfile", collection)]
       end
 
+      # ADR-10 slice 3, issue #1814 — the `dependencies.source_inference` gems' `(name, version, mode)` rows, which the
+      # walker's output depends on and no lockfile digest covers when the project has none or the gem sits beside the
+      # bundle. Shared by this key and by {Cache::IncrementalSnapshot.fingerprint}, as the lockfiles are. A project
+      # that lists no gem adds no row, so its key is what it was.
+      def dependency_source_entries(configuration)
+        DependencySourceInference::GemResolver.dependency_entries(configuration.dependencies)
+      end
+
       # The one resolution of the two dependency lockfiles — `[bundler, rbs_collection]`, each a Pathname or nil
       # — shared by this key and by {Cache::IncrementalSnapshot.fingerprint} so the two caches identify the gem
       # set by the same files (issue #1532): `bundler.lockfile:` / `rbs_collection.lockfile:` and auto-detection.
@@ -180,7 +192,10 @@ module Rigor
 
       # The `rbs.libraries` config slot reconstructed from configuration alone — byte-identical to the
       # loader's `RbsDescriptor.libraries_entry(loader.libraries)` because `Environment.for_project` merges
-      # exactly `DEFAULT_LIBRARIES + config.libraries` (uniq) into `loader.libraries`.
+      # exactly `DEFAULT_LIBRARIES + config.libraries` (uniq) into `loader.libraries`, plus the
+      # `Environment::RequiredFeatures` tokens the run's source activates (issue #1700). Those are left out
+      # here: reading every source file would cost the boot-slimming probe the time it exists to save, and a
+      # project that requires a gated feature then only misses this probe, never hits a wrong slot.
       def libraries_config_entries(configuration)
         merged = (Environment::DEFAULT_LIBRARIES + configuration.libraries.map(&:to_s)).uniq
         [Cache::RbsDescriptor.libraries_entry(merged)]

data/lib/rigor/analysis/run_cache_probe.rb

@@ -64,7 +64,7 @@ module Rigor
       #   the caller loads the engine and runs the full path. Any failure declines rather than raising: the
       #   probe must never turn a servable run into a crash.
       def serve(paths)
-        files = PathExpansion.ruby_files(paths, @configuration.exclude_patterns)
+        files = PathExpansion.ruby_files(paths, @configuration.exclude_patterns, base: @configuration.exclude_base)
         key = RunCacheKey.descriptor(
           configuration: @configuration, files: files, explain: @explain,
           rbs_config_entries: RunCacheKey.libraries_config_entries(@configuration)

data/lib/rigor/analysis/run_stats.rb

@@ -24,18 +24,31 @@ module Rigor
     # `class_decl_paths` (a frozen `Hash<String, String>` populated once per environment by the RBS loader;
     # ~1000-2000 entries × one `String#start_with?`).
     class RunStats
-      attr_reader :wall_seconds, :peak_rss_bytes,
+      attr_reader :wall_seconds,
                   :target_files,
                   :rbs_classes_total, :rbs_classes_project_sig, :rbs_classes_bundled,
                   :gem_walk_classes, :gem_walk_gems, :rbs_attribution_available
 
-      def initialize(wall_seconds:, peak_rss_bytes:, # rubocop:disable Metrics/ParameterLists
+      # The live probe a run's summary uses: reads this process's RSS when first asked. The probe is a constant
+      # lambda, so the RunStats it rides on never captures the Runner (and its analysis state) through `Result`.
+      CURRENT_PROCESS_PEAK_RSS = Ractor.make_shareable(-> { RunStats.peak_rss_bytes })
+
+      # Issue #1529 — the peak RSS is read on the first {#peak_rss_bytes} call, not when the summary is built. A run
+      # that prints no summary (`--incremental` recheck, `--no-stats`) therefore never forks `ps` or reads `/proc`.
+      # The read stays in this process: the summary is built and printed by the process that ran the analysis.
+      #
+      # @param peak_rss_bytes — a value to report directly (specs, or a caller that already read it). Ignored when
+      #   `peak_rss_probe:` is given.
+      # @param peak_rss_probe — a zero-argument callable returning the RSS in bytes, called at most once, lazily.
+      def initialize(wall_seconds:, # rubocop:disable Metrics/ParameterLists
                      target_files:,
                      rbs_classes_total:, rbs_classes_project_sig:, rbs_classes_bundled:,
                      gem_walk_classes:, gem_walk_gems:,
-                     rbs_attribution_available: true)
+                     rbs_attribution_available: true, peak_rss_bytes: nil, peak_rss_probe: nil)
         @wall_seconds = wall_seconds
-        @peak_rss_bytes = peak_rss_bytes
+        @peak_rss_probe = peak_rss_probe || -> { peak_rss_bytes }
+        # A frozen RunStats cannot memoise into an ivar, so the first read lands in this (unfrozen) Hash.
+        @peak_rss_memo = {}
         @target_files = target_files
         @rbs_classes_total = rbs_classes_total
         @rbs_classes_project_sig = rbs_classes_project_sig
@@ -46,6 +59,15 @@ module Rigor
         freeze
       end
 
+      # The peak RSS in bytes, read once on first call and memoised (nil when no route answers). The check command
+      # forces the first call straight after the analysis (#1529), before `--coverage` or any output, so the figure
+      # covers the analysis alone. On Linux it is the kernel's VmHWM high-water mark, so a later read is never below
+      # the run-end value. On macOS it is `ps`'s current RSS, so the reading is the process as it stood at that
+      # first call, not a high-water mark.
+      def peak_rss_bytes
+        @peak_rss_memo.fetch(:value) { @peak_rss_memo[:value] = @peak_rss_probe.call }
+      end
+
       # Reports the process's resident set size in bytes. Source ordering: `/proc/self/status` (Linux — reads
       # `VmHWM:`, the peak RSS the kernel records) first; otherwise `ps -o rss= -p <pid>` (macOS / BSD —
       # reports CURRENT RSS, the closest universally-available proxy). Returns nil when neither route works
@@ -146,7 +168,7 @@ module Rigor
         end
         out.puts("#{prefix}Process")
         out.puts("#{prefix}  Wall time:   #{Kernel.format('%.2fs', @wall_seconds)}")
-        out.puts("#{prefix}  Memory peak: #{format_bytes(@peak_rss_bytes)}")
+        out.puts("#{prefix}  Memory peak: #{format_bytes(peak_rss_bytes)}")
       end
 
       def to_h
@@ -159,7 +181,7 @@ module Rigor
           gem_walk_classes: @gem_walk_classes,
           gem_walk_gems: @gem_walk_gems,
           wall_seconds: @wall_seconds,
-          peak_rss_bytes: @peak_rss_bytes
+          peak_rss_bytes: peak_rss_bytes
         }
       end
 

data/lib/rigor/analysis/runner/diagnostic_aggregator.rb

@@ -36,6 +36,8 @@ module Rigor
         #   that stood down against a colliding generic arity (#610), as
         #   `[path, class_name, existing_arity, incoming_arity, existing_file]` tuples. Defaults to none so
         #   a caller that snapshots nothing of the kind need not say so.
+        # @param vendored_standdowns_snapshot — issue #1713 — reader returning what each required-feature-gated
+        #   vendored directory left out (`Environment::RbsLoader#vendored_standdowns`). Defaults to none.
         # @param env_build_failure_snapshot — reader returning the total RBS env-build failure tuple
         #   (`[error_class, first_error_line, conflicting_buffer_names]`) or nil when the env built.
         # @param definition_build_failures_snapshot — issue #696 — reader returning the per-class
@@ -55,7 +57,7 @@ module Rigor
                        quarantined_signatures_snapshot:, env_build_failure_snapshot:,
                        definition_build_failures_snapshot:, hkt_scan_failure_snapshot:,
                        conformance_results_snapshot:, signature_standdowns_snapshot: -> { [] },
-                       pooled_run_disclosures: -> { [] })
+                       vendored_standdowns_snapshot: -> { [] }, pooled_run_disclosures: -> { [] })
           @configuration = configuration
           @rbs_extended_reporter = rbs_extended_reporter
           @boundary_cross_reporter = boundary_cross_reporter
@@ -68,6 +70,7 @@ module Rigor
           @synthesized_namespaces_snapshot_reader = synthesized_namespaces_snapshot
           @quarantined_signatures_snapshot_reader = quarantined_signatures_snapshot
           @signature_standdowns_snapshot_reader = signature_standdowns_snapshot
+          @vendored_standdowns_snapshot_reader = vendored_standdowns_snapshot
           @env_build_failure_snapshot_reader = env_build_failure_snapshot
           @definition_build_failures_snapshot_reader = definition_build_failures_snapshot
           @hkt_scan_failure_snapshot_reader = hkt_scan_failure_snapshot
@@ -125,7 +128,32 @@ module Rigor
               source_family: :builtin
             )
           end
-          not_found + Array(pre_eval_diagnostics_from_scanner).map { |hash| diagnostic_from_hash(hash) }
+          scanned = Array(pre_eval_diagnostics_from_scanner).map { |hash| diagnostic_from_hash(hash) }
+          suppress_pre_eval(not_found + scanned)
+        end
+
+        # The ordinary suppression pipeline for the `pre-eval.*` rows: the `# rigor:disable` /
+        # `# rigor:disable-file` comments of the file a row is positioned in (a `pre_eval:` file need not be
+        # under `paths:`, so its comments are read here rather than by per-file analysis) and the project's
+        # `disable:` list. A row positioned at `.rigor.yml` has no Ruby comments (`.yml` is skipped) and answers to
+        # `disable:` only.
+        # Stream order is the output contract, so survivors are picked out of the original sequence.
+        def suppress_pre_eval(diagnostics)
+          kept = diagnostics.group_by(&:path).flat_map do |path, group|
+            CheckRules.filter_suppressed(
+              group, comments: pre_eval_comments(path), disabled_rules: @configuration.disabled_rules
+            )
+          end
+          kept_ids = kept.to_set(&:object_id)
+          diagnostics.select { |diagnostic| kept_ids.include?(diagnostic.object_id) }
+        end
+
+        def pre_eval_comments(path)
+          return [].freeze unless File.file?(path) && !path.end_with?(".rbs", ".yml", ".yaml")
+
+          Prism.parse_file(path).comments
+        rescue StandardError
+          [].freeze
         end
 
         def diagnostic_from_hash(hash)
@@ -437,11 +465,23 @@ module Rigor
           standdowns.map { |entry| build_rbs_plugin_signature_stood_down_diagnostic(entry) }
         end
 
-        # The two `:info` notices that close the `rbs.coverage.*` ladder, in this order: the namespace
-        # synthesis first, then the stand-down (#610) — the outcome that AVOIDED a definition-build failure
-        # and so the quietest row on it. One method so the runner's assembly reads them as one slot.
+        # Issue #1713 — the other outcome that avoided a definition-build failure: a required-feature-gated
+        # vendored directory (`data/vendored_gem_sigs/prime/`) left out what another signature source already
+        # declares — a member, a whole type, or, when nothing narrower built, the directory. One `:info` per
+        # directory, naming the declarations that stood down and the files that displaced them.
+        def rbs_vendored_signature_stood_down_diagnostics
+          standdowns = vendored_standdowns_snapshot
+          return [] if standdowns.nil? || standdowns.empty?
+
+          standdowns.map { |entry| build_rbs_vendored_signature_stood_down_diagnostic(entry) }
+        end
+
+        # The `:info` notices that close the `rbs.coverage.*` ladder, in this order: the namespace synthesis
+        # first, then the stand-downs (#610, #1713) — the outcomes that AVOIDED a definition-build failure and so
+        # the quietest rows on it. One method so the runner's assembly reads them as one slot.
         def rbs_coverage_notice_diagnostics
-          rbs_synthesized_namespace_diagnostics + rbs_plugin_signature_stood_down_diagnostics
+          rbs_synthesized_namespace_diagnostics + rbs_plugin_signature_stood_down_diagnostics +
+            rbs_vendored_signature_stood_down_diagnostics
         end
 
         # Maps the per-run `rigor:v1:conforms-to` scan results into diagnostics (spec: `rbs-extended.md` §
@@ -769,6 +809,69 @@ module Rigor
           )
         end
 
+        def build_rbs_vendored_signature_stood_down_diagnostic(entry)
+          dir, declarations, whole = entry
+          Diagnostic.new(
+            path: ".rigor.yml",
+            line: 1,
+            column: 1,
+            message: vendored_standdown_message(dir, declarations, whole),
+            severity: :info,
+            rule: "rbs.coverage.vendored-signature-stood-down",
+            source_family: :builtin
+          )
+        end
+
+        def vendored_standdown_message(dir, declarations, whole)
+          subject = "Rigor's vendored `#{dir}` signatures (loaded because the project requires `#{dir}` or lists " \
+                    "it under `libraries:`)"
+          return vendored_whole_standdown_message(subject, dir, declarations) if whole
+
+          vendored_partial_standdown_message(subject, declarations)
+        end
+
+        # One sentence per kind of stand-down present ({Environment::GatedSignaturePlan.standdowns}' reasons).
+        VENDORED_STANDDOWN_SENTENCES = {
+          "member" => "left out %<count>d method declaration(s) another signature source also makes, since two " \
+                      "declarations of one method fail the class's definition build, and uses the other " \
+                      "source's: %<list>s.",
+          "type" => "stood %<count>d type(s) down whole, keeping only the types nested in them, because another " \
+                    "source declares each with a different kind (class or module) or generic arity, or the type " \
+                    "failed to build beside that source's declaration: %<list>s.",
+          "open" => "kept %<count>d type(s) without their superclass, because each failed to build beside the " \
+                    "other signatures although no other source declares it; calls they no longer answer read " \
+                    "untyped rather than undefined: %<list>s."
+        }.freeze
+        private_constant :VENDORED_STANDDOWN_SENTENCES
+
+        def vendored_partial_standdown_message(subject, declarations)
+          sentences = VENDORED_STANDDOWN_SENTENCES.filter_map do |reason, template|
+            group = declarations.select { |entry| (entry[2] || "member") == reason }
+            next if group.empty?
+
+            format(template, count: group.size, list: sampled(vendored_standdown_labels(group), 5))
+          end
+          "#{subject} loaded without some of their declarations. Rigor #{sentences.join(' Rigor ')} The rest of the " \
+            "vendored signatures still load. Nothing to fix unless the other declaration is an outdated copy; " \
+            "removing it brings the vendored one back."
+        end
+
+        def vendored_whole_standdown_message(subject, dir, declarations)
+          labels = vendored_standdown_labels(declarations)
+          clashes = labels.empty? ? "" : " Declarations it clashed with: #{sampled(labels, 5)}."
+          "#{subject} stood down " \
+            "entirely: a type they declare failed to build beside the other signature sources even with the " \
+            "clashing declarations left out, so calls into `#{dir}`'s API resolve only against what those " \
+            "sources declare.#{clashes}"
+        end
+
+        def vendored_standdown_labels(declarations)
+          declarations.map do |declaration, cause_file|
+            cause = cause_file.nil? ? "" : " (#{relative_signature_path(cause_file.to_s)})"
+            "`#{declaration}`#{cause}"
+          end
+        end
+
         def displacing_source_phrase(existing_file)
           return "another loaded signature source" if existing_file.nil?
 
@@ -1196,6 +1299,10 @@ module Rigor
           @signature_standdowns_snapshot_reader.call
         end
 
+        def vendored_standdowns_snapshot
+          @vendored_standdowns_snapshot_reader.call
+        end
+
         def env_build_failure_snapshot
           @env_build_failure_snapshot_reader.call
         end

data/lib/rigor/analysis/runner/pool_coordinator.rb

@@ -45,7 +45,8 @@ module Rigor
                        snapshots:, plugin_registry:, dependency_source_index:,
                        synthetic_method_index:, project_patched_methods:,
                        analyze_file:, project_scope_seed: -> { {} }, record_dependencies: false,
-                       restored_run_level_rows: nil, template_units: -> { TemplateUnits.empty })
+                       restored_run_level_rows: nil, template_units: -> { TemplateUnits.empty },
+                       feature_sources: -> { {} }, plugin_prepare: -> { [[], []] })
           @configuration = configuration
           @cache_store = cache_store
           @explain = explain
@@ -67,6 +68,7 @@ module Rigor
           @collected_run_disclosures = {}
           @collect_stats = collect_stats
           @buffer = buffer
+          @feature_sources = feature_sources
           @environment_override = environment_override
           @rbs_extended_reporter = rbs_extended_reporter
           @boundary_cross_reporter = boundary_cross_reporter
@@ -82,6 +84,10 @@ module Rigor
           # inherits the same compiled bytes.
           @template_units_reader = template_units
           @analyze_file = analyze_file
+          # Issue #1541 — `() -> [rows, disclosure records]`, a `#prepare` run on a throwaway registry. Read
+          # only by {#serve_empty_closure}: a pooled run's `#prepare` happens inside its workers, and an
+          # empty closure dispatches none.
+          @plugin_prepare = plugin_prepare
           # Issues #796 / #794 — the previous full run's run-level rows, handed down by
           # {Analysis::IncrementalSession} on a NARROWED run only (a recheck's closure, a
           # `--verify-incremental` partition). A full run leaves this nil and derives everything itself.
@@ -144,10 +150,8 @@ module Rigor
         #   (`expansion.fetch(:files)`), independent of any `analyze_only` narrowing of `files`; see
         #   {#serve_empty_closure} for what an empty `files` does with it.
         def analyze_files(files, environment: nil, project_files: nil)
-          if files.empty?
-            serve_empty_closure(environment, project_files)
-            return []
-          end
+          return serve_empty_closure(environment, project_files) if files.empty?
+
           # Issue #784 / #793 — `files` is what this run ANALYSES; `source_files` is what its environment
           # is BUILT over, and the two are the same only on a full run. A narrowed run (`analyze_only`: an
           # incremental closure, a `--verify-incremental` partition) used to build its environment over the
@@ -197,7 +201,16 @@ module Rigor
         #   whether anyone could have demanded anything at all: with no files, nobody could have, and an
         #   empty project keeps paying no env build. Keyed on the project's files rather than on
         #   `analyze_only`, because a recheck over an EMPTY project narrows to `Set[]`, which is non-nil.
+        #
+        # Issue #1541 — and, in pool mode, its `prepare` rows. A pooled run's `#prepare` happens inside the
+        # workers and its rows reach the stream through their first payload, so the coordinator-side
+        # pre-pass skips it ({ProjectPrePasses#run}) and {DiagnosticAggregator#pre_file_diagnostics} omits
+        # the cached rows; with no worker dispatched the row appeared nowhere, and a plugin whose `#prepare`
+        # raises turned a red project green on a nothing-changed `--incremental --workers N` recheck. They
+        # are returned as the run's per-file stream head, where the pool path puts them (`.rigor.yml`).
+        # Sequential, whose pre-pass already ran `#prepare`, returns no rows here.
         def serve_empty_closure(environment, project_files)
+          prepare_rows = pool_mode? ? pooled_prepare_rows : []
           env = environment || @environment_override
           # Resolved over the project's OWN file list — not `[]`, which would drop every plugin-synthesized
           # virtual RBS (`Environment.collect_virtual_rbs` short-circuits on an empty list) and scan a
@@ -208,23 +221,40 @@ module Rigor
 
             env = resolve_sequential_environment(source_files: project_files)
           end
-          snapshot_project_signature_state(signature_state_environment(resolve))
+          snapshot_project_signature_state(signature_state_environment(resolve, project_files))
           snapshot_effect_annotation_carrier(
             annotation_carrier_environment(resolve, in_hand: !env.nil?)&.rbs_loader
           )
           # `env` rather than `resolve.call`: read the demand the snapshots above just made when they built
           # an environment, and force nothing when they did not.
           record_definition_build_failures(env&.rbs_loader&.definition_build_failures)
-          return if replayed_restored_run_level_rows?
+          record_hkt_scan_failure(hkt_scan_outcome(resolve.call)) unless replayed_restored_run_level_rows?
+          prepare_rows
+        end
+
+        # Issue #1541 — the pooled empty closure's `#prepare`: the rows go to the caller, the run-scoped
+        # registrations into the table the workers' payloads would have filled.
+        def pooled_prepare_rows
+          rows, records = @plugin_prepare.call
+          merge_run_disclosures(records)
+          Array(rows)
+        end
 
-          record_hkt_scan_failure(hkt_scan_outcome(resolve.call))
+        # Issue #794 — the signature-state snapshot's own gates, asked BEFORE an environment exists. Every
+        # answer is loader-free (the configuration, the plugin registry and, issue #1713, the required-feature
+        # scan), and with no gate open {#snapshot_project_signature_state} writes the same empty state a nil
+        # environment gives it.
+        def signature_state_environment(resolve, project_files)
+          gated = plugin_signature_paths? || project_signature_paths? || vendored_features_requested?(project_files)
+          gated ? resolve.call : nil
         end
 
-        # Issue #794 — the signature-state snapshot's own gates, asked BEFORE an environment exists. Both
-        # answers are loader-free (the configuration and the plugin registry), and with neither gate open
-        # {#snapshot_project_signature_state} writes the same empty state a nil environment gives it.
-        def signature_state_environment(resolve)
-          plugin_signature_paths? || project_signature_paths? ? resolve.call : nil
+        # Issue #1713 — whether this run activates a required-feature-gated vendored directory, whose stand-down
+        # {#snapshot_project_signature_state} reports: the scan every build of this run gates on, or the
+        # feature named under `libraries:`.
+        def vendored_features_requested?(project_files)
+          features = project_files.nil? || project_files.empty? ? [] : required_features_for(project_files)
+          !Environment::RequiredFeatures.tokens(features, @configuration.libraries).empty?
         end
 
         # Issue #794 — the same, for the #441 carrier. The carrier is a filter over the loader's
@@ -344,6 +374,10 @@ module Rigor
           # no such plugin reads nothing off its loader here, as before.
           @snapshots.signature_standdowns =
             plugin_signature_paths? ? signature_standdowns_for(environment&.rbs_loader) : []
+          # Issue #1713 — NOT behind the `signature_paths:` gate either: what displaces a vendored declaration may
+          # be a gem's or a collection's copy. The loader answers without building its env when no gated
+          # directory is active.
+          @snapshots.vendored_standdowns = vendored_standdowns_for(environment&.rbs_loader)
           unless project_signature_paths?
             @snapshots.synthesized_namespaces = []
             @snapshots.quarantined_signatures = []
@@ -459,7 +493,22 @@ module Rigor
             **ProjectEnvironment.dependency_discovery_options(@configuration),
             synthetic_method_index: synthetic_method_index,
             project_patched_methods: project_patched_methods,
-            source_files: source_files
+            source_files: source_files,
+            required_features: required_features_for(source_files)
+          )
+        end
+
+        # Issue #1700 — the {Environment::RequiredFeatures} this run's environments gate on: the configured paths
+        # plus `source_files`, whichever files the run checks, with an editor buffer or an in-memory source read
+        # in place of its file. Taken once per file list and handed to every build (the sequential one, the
+        # pool's prewarm and each worker), so they agree and a pool does not re-read the project per worker.
+        def required_features_for(source_files)
+          key = source_files.map(&:to_s)
+          return @required_features if @required_features_key == key
+
+          @required_features_key = key
+          @required_features = Ractor.make_shareable(
+            Environment::RequiredFeatures.for_configuration(@configuration, key, sources: @feature_sources.call)
           )
         end
 
@@ -575,9 +624,10 @@ module Rigor
           # a frozen Array<String>; cheaply shareable. Issue #793 — it IS the full project now
           # (`source_files`), not the analyzed subset this comment always described.
           shareable_source_files = source_files.map { |path| path.to_s.dup.freeze }.freeze
+          features = required_features_for(source_files)
 
           pool = Array.new(@workers) do
-            Ractor.new(configuration, cache_root, blueprints, explain, shareable_source_files, locked_gems) do |configuration, cache_root, blueprints, explain, shareable_source_files, locked_gems| # rubocop:disable Layout/LineLength
+            Ractor.new(configuration, cache_root, blueprints, explain, shareable_source_files, locked_gems, features) do |configuration, cache_root, blueprints, explain, shareable_source_files, locked_gems, features| # rubocop:disable Layout/LineLength
               cache_store = cache_root ? Rigor::Cache::Store.new(root: cache_root) : nil
               session = Rigor::Analysis::WorkerSession.new(
                 configuration: configuration,
@@ -585,7 +635,8 @@ module Rigor
                 plugin_blueprints: blueprints,
                 explain: explain,
                 source_files: shareable_source_files,
-                locked_gems: locked_gems
+                locked_gems: locked_gems,
+                required_features: features
               )
               main = Ractor.main
               main.send([:prepare, session.prepare_diagnostics])
@@ -667,8 +718,9 @@ module Rigor
         # Issue #1051, known exception: run-scoped disclosures a plugin registered from `#prepare` are NOT
         # recovered here — nor, since #1060, a positioned `#emit_once` batch registered there, which rides
         # the same table. There is no session to drain — this backend builds none on the coordinator — and
-        # `#prepare` deliberately does not run on the coordinator-side registry under pool mode, so a
-        # prepare-time disclosure lives only inside the Ractor that died with it. A disclosure registered
+        # `#prepare` does not run on the coordinator-side registry under pool mode (only an empty closure
+        # runs it, on a throwaway registry; see {#serve_empty_closure}), so a prepare-time disclosure lives
+        # only inside the Ractor that died with it. A disclosure registered
         # from `#diagnostics_for_file` IS recovered, because the re-analysis below runs the coordinator-side
         # plugin instances that {DiagnosticAggregator#plugin_run_disclosure_diagnostics} reads directly.
         # Left as is: recovering the rest means running `#prepare` on the coordinator registry, which would
@@ -713,7 +765,8 @@ module Rigor
             project_scope_seed: project_scope_seed,
             source_files: source_files,
             record_dependencies: @record_dependencies,
-            template_units: template_units
+            template_units: template_units,
+            required_features: required_features_for(source_files)
           )
           # Force the full RBS load on the parent so children copy-on-write inherit a warm Environment
           # rather than each rebuilding it after the fork.
@@ -890,6 +943,7 @@ module Rigor
             plugin_registry: plugin_registry,
             source_files: source_files,
             locked_gems: locked_gems,
+            required_features: required_features_for(source_files),
             **ProjectEnvironment.dependency_discovery_options(@configuration)
           )
           warm_env.rbs_loader&.prewarm
@@ -1094,6 +1148,10 @@ module Rigor
           loader.signature_standdowns
         end
 
+        def vendored_standdowns_for(loader)
+          loader.respond_to?(:vendored_standdowns) ? loader.vendored_standdowns : []
+        end
+
         def plugin_registry
           @plugin_registry_reader.call
         end

data/lib/rigor/analysis/runner/project_pre_passes.rb

@@ -59,7 +59,7 @@ module Rigor
           :unpositioned_mixins, :discovered_class_sources, :constant_values, :constant_sources, :constant_writes,
           :discovered_method_visibilities, :discovered_methods, :discovered_parameter_envelopes, :data_member_layouts,
           :struct_member_layouts, :discovered_deferred_ranges, :discovered_refinements, :siblings,
-          :discovered_global_write_census
+          :discovered_global_write_census, :singleton_class_sources
         )
 
         # Internal: drives every EAGER project-wide pre-pass — the ones whose products feed the RBS
@@ -175,6 +175,8 @@ module Rigor
             # object's `extend`s reach `Narrowing` from a sibling file the way its `include`s already do.
             discovered_extends: def_index.fetch(:extends), unpositioned_mixins: def_index.fetch(:unpositioned_mixins),
             discovered_class_sources: def_index.fetch(:class_sources),
+            # Issue #1752 — the files opening `class << Const`, for the class-declaration diff alone.
+            singleton_class_sources: def_index.fetch(:singleton_class_sources, {}),
             # Issue #644 — the cross-file value-constant publication table and its write attribution.
             constant_values: def_index.fetch(:constant_values), constant_sources: def_index.fetch(:constant_sources),
             constant_writes: def_index.fetch(:constant_writes),
@@ -251,6 +253,24 @@ module Rigor
           registry
         end
 
+        # Issue #1541 — what a pooled run's workers would have produced from `#prepare`, for the coordinator's
+        # empty-closure branch, which dispatches none: the `#prepare` error rows and the run-scoped
+        # registrations (`#disclose_once` / `#emit_once`) made there. It runs on a THROWAWAY registry, so
+        # nothing `#prepare` records on a plugin instance (a trust refusal, say) reaches the coordinator-side
+        # instances {DiagnosticAggregator} reads — a pooled cold run never shows those either.
+        # Returns the rows first, then the disclosure records.
+        def prepare_throwaway_registry
+          registry = load_plugins
+          rows = plugin_prepare_diagnostics(registry)
+          records = registry.plugins.flat_map do |plugin|
+            plugin_id = safe_plugin_id(plugin)
+            Array(plugin.run_disclosure_records).map { |record| record.merge(plugin_id: plugin_id) }
+          rescue StandardError
+            []
+          end
+          [rows, records]
+        end
+
         # Returns the per-run shared `Plugin::FactStore` instance. All loaded plugins share this store
         # through their respective `Plugin::Services` (the same instance is threaded by
         # `Plugin::Loader.load`). Returns `nil` when no plugins are loaded.