rigortype 0.4.1 → 0.4.2

data/lib/rigor/environment/rbs_loader.rb

@@ -7,6 +7,9 @@ require_relative "../inference/rbs_type_translator"
 require_relative "../builtins/imported_refinements"
 require_relative "rbs_hierarchy"
 require_relative "member_consistency"
+require_relative "required_features"
+require_relative "gated_signature_guard"
+require_relative "gated_signature_plan"
 
 module Rigor
   class Environment
@@ -83,28 +86,100 @@ module Rigor
         # per-gem RBS bundled with Rigor itself is in scope for every analysis run. The gem stubs are
         # intentionally read-only and appended LAST so user-supplied `signature_paths` win on name conflicts.
         def build_env_for(libraries:, signature_paths:, virtual_rbs: [], deferred_signature_paths: [])
-          rbs_loader = RBS::EnvironmentLoader.new
-          libraries = libraries_without_shadowed_bigdecimal_math(libraries)
-          loaded_libraries = libraries.select do |library|
-            rbs_loader.has_library?(library: library, version: nil)
-          end
-          loaded_libraries.each do |library|
-            rbs_loader.add(library: library, version: nil)
+          inputs = [signature_paths, virtual_rbs, deferred_signature_paths]
+          env, gated_dirs = whole_gated_attempt(libraries, inputs)
+          return env if gated_dirs.empty?
+
+          # Issue #1700 — a {RequiredFeatures}-gated directory joined; keep it whole only if it does not cost the
+          # environment anything ({.gated_failures}).
+          failed, quarantined = env ? gated_failures(env, gated_dirs, signature_paths, virtual_rbs) : [[], 1]
+          return env if failed.empty? && quarantined.zero?
+
+          tokens = gated_dirs.map { |dir| RequiredFeatures.token(RequiredFeatures.feature_for_dir(dir)) }
+          fallback, = build_env_attempt(libraries.reject { |library| tokens.include?(library.to_s) }, *inputs)
+          partial = partial_gated_env(libraries, inputs, gated_dirs, fallback, failed)
+          return partial if partial
+
+          trouble = failed.size + quarantined
+          return fallback if env.nil?
+
+          gated_trouble(fallback, gated_dirs, signature_paths, virtual_rbs) < trouble ? fallback : env
+        end
+
+        # The first attempt, with every activated gated directory whole. rbs 3.x validates a class's generic
+        # parameters and kind as each declaration is inserted, so a project `class Prime[T]` or `module Prime`
+        # raises out of this build where rbs 4.x lets the trial find it; with a gated directory active that is
+        # the directory's cost, not the environment's, and the build answers nil for the planned builds to
+        # replace. Without one the error is the environment's own and propagates as before.
+        def whole_gated_attempt(libraries, inputs)
+          build_env_attempt(libraries, *inputs)
+        rescue ::RBS::BaseError
+          gated_dirs = loadable_gated_dirs(libraries, library_loader(libraries).last)
+          raise if gated_dirs.empty?
+
+          [nil, gated_dirs]
+        end
+
+        # Issue #1713 — the directory less what clashes ({GatedSignaturePlan}), planned against `fallback`, the
+        # environment without it. A plan whose trial build still fails for some gated type is re-planned once
+        # with each such type shelled — standing down as a whole — and nil is returned when that fails too, so the
+        # caller falls back to the whole directory standing down. Every input is one the env-cache key covers.
+        #
+        # @param failed — the gated types the whole directory failed to build for.
+        def partial_gated_env(libraries, inputs, gated_dirs, fallback, failed)
+          roots = gated_dirs.map { |dir| gated_dir_root(dir) }
+          plan = GatedSignaturePlan.build(roots, fallback)
+          if plan.changed
+            env = gated_plan_attempt(libraries, inputs, plan)
+            failed, quarantined = env ? gated_failures(env, gated_dirs, inputs[0], inputs[1]) : [failed, 0]
+            return env if env && failed.empty? && quarantined.zero?
           end
+          return nil if failed.empty?
+
+          plan = GatedSignaturePlan.build(roots, fallback, failed.to_set { |name| name.to_s.delete_prefix("::") })
+          env = gated_plan_attempt(libraries, inputs, plan)
+          return nil if env.nil?
+
+          failed, quarantined = gated_failures(env, gated_dirs, inputs[0], inputs[1])
+          env if failed.empty? && quarantined.zero?
+        end
+
+        # A planned build is a candidate, never a requirement: one that raises leaves the caller's fallback.
+        def gated_plan_attempt(libraries, inputs, plan)
+          build_env_attempt(libraries, *inputs, gated_plan: plan).first
+        rescue ::RBS::BaseError
+          nil
+        end
+
+        def gated_dir_root(dir)
+          Pathname(File.join(VENDORED_GEM_SIGS_ROOT, dir))
+        end
+
+        # One environment build ({.build_env_for}'s body before the issue #1700 trial). Returns the environment
+        # and the gated vendored directories it loaded.
+        #
+        # @param gated_plan — issue #1713 — a {GatedSignaturePlan} loaded in place of the gated directories: its
+        #   kept declarations where the directories would have loaded, its shells after the project's signatures.
+        def build_env_attempt(libraries, signature_paths, virtual_rbs, deferred_signature_paths, gated_plan: nil)
+          libraries = libraries_without_shadowed_bigdecimal_math(libraries)
+          rbs_loader, loaded_libraries = library_loader(libraries)
+          gated_dirs = loadable_gated_dirs(libraries, loaded_libraries)
           # Project `signature_paths:` are loaded per-file by {.add_project_signatures} AFTER `from_loader`,
           # NOT added to the loader here: `RBS::Environment.from_loader` parses every added file all-or-nothing,
           # so one unparseable user `.rbs` raises `RBS::ParsingError` and collapses the WHOLE env to nil (every
           # type-of query then degrades to `Dynamic[top]` — the "sig looks harmful" failure of the 2026-07-06
           # mastodon coverage note). Per-file loading quarantines the broken file instead. Vendored / core-overlay
           # sigs are Rigor-shipped and trusted, so they stay on the loader's fast batch path.
-          add_bundled_signatures(rbs_loader, loaded_libraries.to_set(&:to_s))
+          add_bundled_signatures(rbs_loader, loaded_libraries.to_set(&:to_s), gated_plan ? [] : gated_dirs)
           env = unload_upstream_core_shims(RBS::Environment.from_loader(rbs_loader), rbs_loader)
+          gated_plan&.leading&.each { |source| add_parsed_decls(env, *source) }
           project_files = project_sig_files(signature_paths)
           # Issue #1075 — decided from the inputs before either side enters `env`: the consistency rule may
           # stand the `.rbs` member down, and that has to happen before its file is added.
           consistency = member_consistency_for(project_files, virtual_rbs)
           add_project_signatures(env, signature_paths, deferred_signature_paths,
                                  standdowns: consistency.signature_standdowns)
+          gated_plan&.shells&.each { |source| add_parsed_decls(env, *source) }
           # Issue #928 — the capability-role catalog goes in AFTER the project's own signatures, per
           # declaration, so a project that already declares one of these interface names keeps its own
           # (`add_capability_role_signatures`). The rest of the bundled RBS cannot be ordered that way (it
@@ -119,7 +194,86 @@ module Rigor
           # Issue #777 — resolve-time backstop: also unload colliding PROJECT buffers (class-vs-module /
           # constant redeclarations against bundled RBS). Virtual culprits are preferred when both appear.
           env, resolved = resolve_quarantining_virtual_collisions(env, virtual_rbs, project_files: project_files)
-          stub_missing_referenced_types(env, resolved, project_files)
+          [stub_missing_referenced_types(env, resolved, project_files), gated_dirs]
+        end
+
+        # An `RBS::EnvironmentLoader` with every library of `libraries` that resolves added, and those libraries.
+        def library_loader(libraries)
+          rbs_loader = RBS::EnvironmentLoader.new
+          # Issue #1700 — a `RequiredFeatures` token names a gated vendored directory, never an RBS library.
+          loaded_libraries = libraries.select do |library|
+            next false if RequiredFeatures.feature_of_token(library)
+
+            rbs_loader.has_library?(library: library, version: nil)
+          end
+          loaded_libraries.each do |library|
+            rbs_loader.add(library: library, version: nil)
+          end
+          [rbs_loader, loaded_libraries]
+        end
+
+        # Issue #1700 — what loading the gated vendored `dirs` costs `env`: each type they declare whose instance
+        # or singleton definition fails to build, plus each project signature file or inline-synthesized RBS
+        # buffer quarantined for a duplicate declaration. A vendored copy joins signatures the project chose — its
+        # own `sig/`, a `signature_paths:` entry, a gem's `sig/`, an `rbs collection` copy, plugin signatures,
+        # inline RBS — and any clash with them (a member both declare, a class one side declares as a module,
+        # a different superclass or generic arity) surfaces here as a failed definition or a quarantine, and
+        # degrades the whole class to `Dynamic[top]` or drops the project's file. A trial build is the oracle
+        # rather than a comparison of declarations because it answers exactly what RBS itself decides — an
+        # overload continuation (`| ...`), a superclass written relative or absolute, a type parameter — with no
+        # second reading of the rules to drift. It runs only when a gated directory joined, on an env-cache miss.
+        def gated_trouble(env, dirs, signature_paths, virtual_rbs)
+          failed, quarantined = gated_failures(env, dirs, signature_paths, virtual_rbs)
+          failed.size + quarantined
+        end
+
+        # {.gated_trouble} split in two: the gated type names whose definitions fail, and the number of quarantined
+        # signature sources that declare one. Issue #1713 re-plans against the first.
+        def gated_failures(env, dirs, signature_paths, virtual_rbs)
+          type_names = gated_type_names(dirs)
+          builder = RBS::DefinitionBuilder.new(env: env)
+          failed = type_names.select do |type_name|
+            entry = env.class_decls[type_name]
+            next false if entry.nil?
+
+            # rbs 4 validates the declarations' type parameters here (`GenericParameterMismatchError`), which
+            # the definition builds below do not reach on their own.
+            entry.type_params if entry.respond_to?(:type_params)
+            builder.build_instance(type_name)
+            builder.build_singleton(type_name)
+            false
+          rescue StandardError
+            true
+          end
+          declares = gated_declaration_pattern(type_names)
+          quarantined = collision_quarantined_project_signatures(env, signature_paths).count do |file, _note|
+            File.read(file).match?(declares)
+          rescue SystemCallError, IOError, ArgumentError
+            false
+          end
+          [failed, quarantined + quarantined_virtual_count(env, virtual_rbs, declares)]
+        end
+
+        # A `class` / `module` line declaring one of the gated types, by its last name segment. A quarantine is
+        # counted only for a file that declares one, so a project whose other signature files were already
+        # quarantined (a duplicated gem `sig/`) does not read every gated directory as costly and pay a second
+        # build on each env-cache miss.
+        def gated_declaration_pattern(type_names)
+          segments = type_names.map { |name| Regexp.escape(name.name.to_s) }.uniq.join("|")
+          /^\s*(?:class|module)\s+(?:::)?(?:[\w:]*::)?(?:#{segments})\b/
+        end
+
+        def gated_type_names(dirs)
+          roots = dirs.map { |dir| gated_dir_root(dir) }
+          names = roots.flat_map { |root| GatedSignatureGuard.type_names(root) }
+          names.uniq.map { |name| ::RBS::TypeName.parse("::#{name}") }
+        end
+
+        def quarantined_virtual_count(env, virtual_rbs, declares)
+          present = env.buffers.to_set(&:name)
+          virtual_rbs.count do |name, content|
+            !content.empty? && !present.include?(name) && content.match?(declares) && parseable_rbs?(content)
+          end
         end
 
         # rbs ships `stdlib/bigdecimal/` and `stdlib/bigdecimal-math/` as two libraries, so
@@ -1228,6 +1382,7 @@ module Rigor
         # Keyed by `data/vendored_gem_sigs/` directory basename.
         LIBRARY_SUPPLEMENT_VENDORED_DIRS = {
           "cgi" => "cgi",
+          "prime" => "singleton",
           "prism" => "prism"
         }.freeze
         private_constant :LIBRARY_SUPPLEMENT_VENDORED_DIRS
@@ -1258,13 +1413,13 @@ module Rigor
         # overlay is added per-file, not per-directory, because the `LIBRARY_SUPPLEMENT_CORE_OVERLAYS` and
         # `RBS_LINE_CORE_OVERLAYS` files must be gated individually.
         #
+        # A directory {RequiredFeatures} gates loads only when the library list activated it (issue #1700).
+        #
         # @param loaded_library_names — libraries that actually resolved on this loader.
-        def add_bundled_signatures(rbs_loader, loaded_library_names)
+        # @param gated_dirs — the {RequiredFeatures}-gated directory basenames this library list activates.
+        def add_bundled_signatures(rbs_loader, loaded_library_names, gated_dirs = [])
           vendored_gem_sig_paths.each do |path|
-            next unless path.directory?
-            next unless supplement_dependency_loaded?(LIBRARY_SUPPLEMENT_VENDORED_DIRS, path, loaded_library_names)
-
-            rbs_loader.add(path: path)
+            rbs_loader.add(path: path) if vendored_dir_loads?(path, loaded_library_names, gated_dirs)
           end
           core_overlay_sig_paths.each do |dir|
             next unless dir.directory?
@@ -1279,6 +1434,31 @@ module Rigor
           end
         end
 
+        # Issue #1700 — the {RequiredFeatures}-gated directories `libraries` activates, less one whose feature
+        # resolved as an RBS library here (`libraries: [prime]` on a host whose `prime` gem ships its `sig/`),
+        # whose own copy is then already loaded. {.build_env_for} then keeps a directory that joined only if the
+        # trial build finds it costs nothing ({.gated_trouble}). Both decisions are made inside the build, against
+        # what the environment holds, so the env-cache producer — which rebuilds through it from the same inputs
+        # — decides the same way.
+        def loadable_gated_dirs(libraries, loaded_libraries)
+          resolved = loaded_libraries.to_set(&:to_s)
+          RequiredFeatures.active_dirs(libraries.map(&:to_s)).reject do |dir|
+            resolved.include?(RequiredFeatures.feature_for_dir(dir))
+          end
+        end
+
+        # @param path — a `data/vendored_gem_sigs/<gem>/` entry.
+        # @return true when the directory exists, its supplemented library (if any) loaded, and — for a
+        #   {RequiredFeatures}-gated directory — the library list activated it.
+        def vendored_dir_loads?(path, loaded_library_names, gated_dirs)
+          return false unless path.directory?
+          return false unless supplement_dependency_loaded?(LIBRARY_SUPPLEMENT_VENDORED_DIRS, path,
+                                                            loaded_library_names)
+
+          basename = path.basename.to_s
+          !RequiredFeatures.gated_dir?(basename) || gated_dirs.include?(basename)
+        end
+
         # @param supplements — basename → gating library map.
         # @param path — the vendored directory or overlay file to test.
         # @param loaded_library_names — libraries that actually resolved on this loader.
@@ -1537,6 +1717,32 @@ module Rigor
         @state[:signature_standdowns] ||= self.class.deferred_standdowns(env, @deferred_signature_paths).freeze
       end
 
+      # Issue #1713 — what stood down from each {RequiredFeatures}-gated vendored directory this loader's library
+      # list activated, as {GatedSignaturePlan.standdowns} reports it: `[dir, [[declaration, cause_file, reason],
+      # ...], whole]`. Derived from the final env, so a cache HIT reports what the cold build decided. Empty, without
+      # building the env, when no gated directory is active; empty too for a directory whose feature resolved as
+      # an RBS library, which the build never loads ({.loadable_gated_dirs}).
+      def vendored_standdowns
+        @state[:vendored_standdowns] ||= derive_vendored_standdowns.freeze
+      end
+
+      def derive_vendored_standdowns
+        names = @libraries.map(&:to_s)
+        roots = RequiredFeatures.active_dirs(names).uniq.each_with_object({}) do |dir, acc|
+          acc[dir] = self.class.gated_dir_root(dir) unless gated_feature_resolved?(dir, names)
+        end
+        return [] if roots.empty?
+
+        GatedSignaturePlan.standdowns(env, roots, self.class.project_sig_files(@signature_paths))
+      end
+      private :derive_vendored_standdowns
+
+      def gated_feature_resolved?(dir, library_names)
+        feature = RequiredFeatures.feature_for_dir(dir)
+        library_names.include?(feature) && RBS::EnvironmentLoader.new.has_library?(library: feature, version: nil)
+      end
+      private :gated_feature_resolved?
+
       # Issue #735 — the class / module names whose PRIMARY declaration lives under the project's own
       # `signature_paths:`, top-level prefix stripped ("::Admin::Widget" reads back as "Admin::Widget").
       #
@@ -1807,6 +2013,69 @@ module Rigor
         false
       end
 
+      # Issue #1698 — the modules and classes `name`'s RBS declarations place in its ancestry, read from the
+      # declarations themselves rather than through the definition builder, so a declaration whose definition
+      # fails to build (a missing mixin, a superclass mismatch) still yields what it declares: each declaration's
+      # `include` / `prepend` members and a class's superclass, followed through the other RBS-declared modules
+      # and classes they name, `::`-stripped and without `name` itself. `[names, complete]`: `complete` is false
+      # when a name on the way is not an RBS class or module (an alias, an undeclared mixin), when the walk
+      # passes 64 names, or when the environment is unavailable; `names` is then what was read so far. Interface
+      # includes own no constants and are skipped. Memoised per loader.
+      def declared_ancestry(name)
+        memo = (@state[:declared_ancestry] ||= {})
+        key = name.to_s.delete_prefix("::")
+        memo[key] ||= build_declared_ancestry(key).freeze
+      end
+
+      def build_declared_ancestry(key)
+        environment = env
+        return [[].freeze, false] if environment.nil?
+
+        names = []
+        complete = true
+        pending = [key]
+        until pending.empty?
+          current = pending.shift
+          entry = environment.class_decls[parse_type_name(current)]
+          if entry.nil?
+            complete = false
+            next
+          end
+          declared_parents(entry).each do |parent|
+            next if parent == key || names.include?(parent)
+
+            names << parent
+            pending << parent
+          end
+          next unless names.size > 64
+
+          complete = false
+          break
+        end
+        [names.freeze, complete]
+      rescue ::RBS::BaseError
+        [[].freeze, false]
+      end
+      private :build_declared_ancestry
+
+      def declared_parents(entry)
+        self.class.entry_declarations(entry).flat_map do |decl|
+          parents = decl.respond_to?(:members) ? decl.members.filter_map { |member| mixin_parent(member) } : []
+          superclass = decl.respond_to?(:super_class) ? decl.super_class : nil
+          parents << superclass.name.to_s.delete_prefix("::") if superclass
+          parents
+        end
+      end
+      private :declared_parents
+
+      def mixin_parent(member)
+        return nil unless member.is_a?(::RBS::AST::Members::Include) || member.is_a?(::RBS::AST::Members::Prepend)
+        return nil if member.name.interface?
+
+        member.name.to_s.delete_prefix("::")
+      end
+      private :mixin_parent
+
       # Yields every known class / module / alias name (top-level prefixed) currently loaded into the
       # environment. The cache producer that materialises the known-name set uses this so it never recurses
       # back through {#class_known?}.

data/lib/rigor/environment/required_features.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require_relative "../analysis/path_expansion"
+
+module Rigor
+  class Environment
+    # Issue #1700 — vendored signatures that load only when the project's own source requires the feature. A
+    # `data/vendored_gem_sigs/` directory loads for every project, which is safe for a gem that owns its
+    # namespace (`PG::Connection`) and unsafe for one that reopens core classes or claims a short top-level name.
+    # `prime` does both: it declares `class Prime` and adds `Integer#prime?`, and with it loaded unconditionally a
+    # project's own `class Prime` with a zero-argument `prime?` drew a false `call.wrong-arity` against the gem's
+    # `(Integer, ?generator)`. Such a directory is listed in {VENDORED_DIRS} and loads only when some project
+    # source file requires the feature ({PATTERN}), or the configuration lists it under `libraries:`.
+    #
+    # The decision travels as a library token ({token}) inside the environment's library list, so every
+    # consumer that already keys on that list sees it without plumbing of its own: the RBS environment cache
+    # key (`Cache::RbsDescriptor.libraries_entry`), the env-cache producer that rebuilds from
+    # `RbsLoader#libraries`, and the run-result key built from the loader's descriptor. The ADR-87 boot-slimming
+    # probe reconstructs the list from configuration alone and so never carries a token: for a project that
+    # requires a listed feature it misses and the full path serves the run, which forgoes the fast lane and
+    # never serves a wrong answer. Whether a token's directory then loads is `RbsLoader`'s decision, made
+    # against what the environment actually holds (`RbsLoader.gated_dir_loads?`).
+    #
+    # A leaf file (no engine requires), for the reason `default_libraries.rb` is one: the incremental snapshot
+    # fingerprint reads it without building an environment.
+    module RequiredFeatures
+      # Required feature => `data/vendored_gem_sigs/` directory basename.
+      VENDORED_DIRS = { "prime" => "prime" }.freeze
+
+      TOKEN_PREFIX = "rigor-vendored:"
+
+      FEATURE_ALTERNATION = VENDORED_DIRS.keys.map { |feature| Regexp.escape(feature) }.join("|").freeze
+      private_constant :FEATURE_ALTERNATION
+
+      # A `require` call naming a listed feature as a string literal, with or without parentheses: the bare call
+      # and `Kernel.require` count, a `require` that follows any other `.` (`obj.require`) or is part of a longer
+      # word (`require_relative`) does not, and a computed name never does; nor do `require(` with the name on
+      # the next line or `send(:require, "prime")`. A match on a whole-line comment ({#commented?}) does not
+      # count, so commenting a require out changes nothing. Otherwise the match is textual and leans toward
+      # loading: a `require "prime"` in a trailing comment, a heredoc or an `=begin` block counts. That direction
+      # only loads the gem's own signatures, and `RbsLoader` still drops them when they cost the environment
+      # anything.
+      PATTERN = /(?:(?<![\w.$@])|(?<=Kernel\.))require[ \t]*\(?[ \t]*(["'])(#{FEATURE_ALTERNATION})\1/
+
+      module_function
+
+      # The features a run over `configuration` requires: every file under the configured paths, plus
+      # `extra_files` (a run's own targets or a probe's file, which may lie outside them). The scan does not
+      # depend on which files a run checks, so `rigor check lib/a.rb`, a probe on `lib/a.rb` and the language
+      # server all see a `require "prime"` in `lib/b.rb`. Fails soft to no features.
+      #
+      # @param sources — path => source text, read in place of that path's file (an editor buffer).
+      def for_configuration(configuration, extra_files = [], sources: {})
+        files = Analysis::PathExpansion.ruby_files(configuration.paths, configuration.exclude_patterns)
+        scan(files + Array(extra_files).map(&:to_s), sources: sources)
+      rescue StandardError
+        []
+      end
+
+      # @param files — source paths (Strings or Pathnames); an unreadable one contributes nothing.
+      # @param sources — path => source text, scanned instead of the file; its paths are scanned even when
+      #   `files` does not list them.
+      # @return the sorted, frozen features some file requires.
+      def scan(files, sources: {})
+        sources = sources.to_h { |path, text| [File.expand_path(path.to_s), text] }
+        paths = (Array(files).map { |path| source_key(File.expand_path(path.to_s), sources) } + sources.keys).uniq
+        found = Set.new
+        paths.each do |path|
+          break if found.size == VENDORED_DIRS.size
+
+          found.merge(sources.key?(path) ? features_of(sources[path]) : memoized_features_in(path))
+        end
+        prune_memo(paths)
+        found.to_a.sort.freeze
+      end
+
+      # @return path (absolute) => the features that file requires, for every file under the configured paths
+      #   that requires any. A long-lived reader (the language server) keeps this and overlays its open buffers.
+      def feature_files(configuration)
+        listed = Analysis::PathExpansion.ruby_files(configuration.paths, configuration.exclude_patterns)
+        files = listed.map { |path| File.expand_path(path.to_s) }
+        result = files.each_with_object({}) do |path, acc|
+          features = memoized_features_in(path)
+          acc[path] = features unless features.empty?
+        end
+        prune_memo(files)
+        result
+      rescue StandardError
+        {}
+      end
+
+      # Paths are compared expanded, so a relative `--instead-of=lib/a.rb` replaces the configured
+      # `/project/lib/a.rb`; a source whose real path matches (a symlinked directory) replaces it too. The real
+      # path is asked only for a file that shares a source's basename, so a scan does not resolve every path.
+      def source_key(path, sources)
+        return path if sources.empty? || sources.key?(path)
+
+        candidates = sources.keys.select { |key| File.basename(key) == File.basename(path) }
+        return path if candidates.empty?
+
+        real = real_path(path)
+        candidates.find { |key| real_path(key) == real } || path
+      end
+
+      def real_path(path)
+        File.realpath(path)
+      rescue SystemCallError
+        path
+      end
+
+      # One run scans the same files more than once (the incremental snapshot fingerprint, then the environment
+      # build; a long-lived language server on every rebuild), so on the main Ractor each file's answer is kept
+      # against its stat and the file is re-read only when the stat moved. A non-main Ractor may not touch the
+      # module's state and reads the file every time.
+      def memoized_features_in(path)
+        return features_in(path) unless Ractor.current == Ractor.main
+
+        stat = File.stat(path)
+        stamp = [stat.mtime.to_r, stat.ctime.to_r, stat.size, stat.ino]
+        memo = (@memo ||= {})
+        cached = memo[path]
+        return cached.last if cached && cached.first == stamp
+
+        features = features_in(path)
+        memo[path] = [stamp, features]
+        features
+      rescue SystemCallError
+        []
+      end
+
+      # Keeps the memo to the files the latest scan was asked about, so a long-lived language server holds one
+      # entry per project file rather than one per file it ever saw.
+      def prune_memo(paths)
+        return unless Ractor.current == Ractor.main && @memo && @memo.size > paths.size
+
+        keep = paths.to_set
+        @memo.select! { |path, _| keep.include?(path) }
+      end
+
+      # @return the features one file requires.
+      def features_in(path)
+        features_of(File.binread(path))
+      rescue SystemCallError, IOError
+        []
+      end
+
+      # @return the features `source` requires.
+      def features_of(source)
+        # A plain substring test first: almost no file mentions any listed feature, and it is far cheaper than
+        # the regexp on a file that does not.
+        return [] unless VENDORED_DIRS.each_key.any? { |feature| source.include?(feature) }
+
+        bytes = source.b
+        named = []
+        position = 0
+        while (match = PATTERN.match(bytes, position))
+          named << match[2] unless commented?(bytes, match.begin(0))
+          position = match.end(0)
+        end
+        # The table's own frozen keys, so the result is shareable across Ractors whatever the source's encoding.
+        VENDORED_DIRS.each_key.select { |feature| named.include?(feature) }
+      end
+
+      # Whether the match at `offset` sits on a line whose first non-blank character is `#`: a whole-line comment.
+      # Deliberately narrower than "after a `#`": a `#` later on a line may be inside `?#`, `%q(#)`, `%w[a#b]`,
+      # a regexp or a string continued from an earlier line, and reading it as a comment would drop a real
+      # require — a false `call.undefined-method` on every call into the feature. A trailing comment
+      # (`p 1 # require "prime"`) therefore still counts, which only loads the gem's own signatures.
+      def commented?(bytes, offset)
+        line_start = offset.zero? ? 0 : (bytes.rindex("\n", offset - 1) || -1) + 1
+        bytes.byteslice(line_start, offset - line_start).lstrip.start_with?("#")
+      end
+
+      # The library tokens for `features` and for any listed feature the configuration's `libraries:` names.
+      def tokens(features, configured_libraries)
+        configured = Array(configured_libraries).map(&:to_s).select { |name| VENDORED_DIRS.key?(name) }
+        (Array(features) | configured).sort.map { |feature| token(feature) }
+      end
+
+      def token(feature)
+        "#{TOKEN_PREFIX}#{feature}"
+      end
+
+      # The feature a library token names, or nil for an ordinary library name.
+      def feature_of_token(name)
+        name = name.to_s
+        name.start_with?(TOKEN_PREFIX) ? name.delete_prefix(TOKEN_PREFIX) : nil
+      end
+
+      # The vendored directory basenames a library list activates.
+      def active_dirs(library_names)
+        library_names.filter_map { |name| VENDORED_DIRS[feature_of_token(name)] }
+      end
+
+      # Whether `dir_basename` is one of the gated directories.
+      def gated_dir?(dir_basename)
+        VENDORED_DIRS.value?(dir_basename)
+      end
+
+      # The feature a gated directory loads for.
+      def feature_for_dir(dir_basename)
+        VENDORED_DIRS.key(dir_basename)
+      end
+    end
+  end
+end

data/lib/rigor/environment.rb

@@ -3,6 +3,7 @@
 require "digest"
 
 require_relative "environment/default_libraries"
+require_relative "environment/required_features"
 require_relative "environment/class_registry"
 require_relative "environment/rbs_loader"
 require_relative "environment/reflection"
@@ -275,7 +276,7 @@ module Rigor
                       bundler_lockfile: nil,
                       rbs_collection_lockfile: nil, rbs_collection_auto_detect: false,
                       synthetic_method_index: nil, project_patched_methods: nil,
-                      source_files: [], locked_gems: nil)
+                      source_files: [], locked_gems: nil, required_features: nil)
         resolved_paths = project_signature_roots(signature_paths, root: root)
         # O4 MVP — append per-gem `sig/` directories discovered under the target project's bundler install
         # root. Empty array when neither an explicit path nor auto-detection finds a bundle. Order: user
@@ -314,8 +315,10 @@ module Rigor
         # and the `data/vendored_gem_sigs/` bundle (`redis`, `nokogiri`, `pg`, …). `skip_gem_names:` passes
         # both sets so the collection copy doesn't double-declare against rigor's bundled RBS (the
         # `RBS::DuplicatedDeclarationError` hazard).
-        merged_libraries = (DEFAULT_LIBRARIES + libraries.map(&:to_s)).uniq
-        skip_gem_names = merged_libraries + RbsLoader.vendored_gem_names
+        # Issue #1700 — plus the gated vendored directories this run's source activates ({#feature_tokens}).
+        merged_libraries = (DEFAULT_LIBRARIES + libraries.map(&:to_s) +
+                            feature_tokens(required_features, source_files, libraries)).uniq
+        skip_gem_names = collection_skip_gem_names(merged_libraries)
         collection_paths = RbsCollectionDiscovery.discover(
           lockfile_path: rbs_collection_lockfile,
           project_root: root,
@@ -400,6 +403,21 @@ module Rigor
 
       private
 
+      # Issue #1700 — the `RequiredFeatures` library tokens for the gated vendored directories this run asks for:
+      # each feature its source requires and each one the configuration's `libraries:` names. `required_features`
+      # is the scan a caller already took; nil scans `source_files`. Whether a directory then loads is decided
+      # by `RbsLoader.build_env_for` against the environment it builds.
+      def feature_tokens(required_features, source_files, libraries)
+        RequiredFeatures.tokens(required_features || RequiredFeatures.scan(source_files), libraries)
+      end
+
+      # The gem names an `rbs collection` copy must not double-declare against: the library list and every
+      # vendored directory except a `RequiredFeatures`-gated one. A gated directory stands down for any other
+      # copy of its declarations (`GatedSignatureGuard`), so the collection's copy is kept and wins.
+      def collection_skip_gem_names(library_names)
+        library_names + RbsLoader.vendored_gem_names.reject { |name| RequiredFeatures.gated_dir?(name) }
+      end
+
       def default_signature_paths(root)
         sig = Pathname(root) / DEFAULT_PROJECT_SIG_DIR
         sig.directory? ? [sig] : []