rigortype 0.4.5 → 0.4.7

data/lib/rigor/environment/reflection.rb

@@ -2,21 +2,21 @@
 
 module Rigor
   class Environment
-    # Frozen, `Ractor.shareable?` read-only RBS query facade.
+    # Frozen read-only RBS query facade.
     # [ADR-15](../../../docs/adr/15-ractor-concurrency.md) Phase 2b extracts the read-only surface of
     # {RbsLoader} into this carrier so future Ractor-isolated workers can share one Reflection across the
     # pool while keeping the per-Ractor mutable accelerator state (per-process memo Hashes) where it belongs.
     #
     # Backing tables (all frozen at construction):
     #
-    # - `known_class_names` — `Set<String>` of every class / module / alias name in the loaded RBS
-    #   environment. Top-level prefixed (`"::Hash"`); plain queries normalise via {#normalise}.
-    # - `instance_definitions` — `Hash<String, RBS::Definition>` keyed on `RBS::TypeName#to_s` (top-level
+    # - `known_class_names` — every class / module / alias name in the loaded RBS environment.
+    #   Top-level prefixed (`"::Hash"`); the query methods accept either form.
+    # - `instance_definitions` — `RBS::Definition` per class, keyed on `RBS::TypeName#to_s` (top-level
     #   prefixed).
     # - `singleton_definitions` — same shape, singleton side.
-    # - `type_param_names` — `Hash<String, Array<Symbol>>` of declared type parameters per class.
-    # - `constant_types` — `Hash<String, Rigor::Type>` of translated constant declarations.
-    # - `ancestor_names` — `Hash<String, Array<String>>` of normalised ancestor chains per class.
+    # - `type_param_names` — declared type parameters per class.
+    # - `constant_types` — translated constant declarations.
+    # - `ancestor_names` — normalised ancestor chains per class.
     #
     # Each `Reflection` instance is `frozen?` at construction — every cached table is frozen, `self` is
     # frozen. **NOT** `Ractor.shareable?`: the `instance_definitions` / `singleton_definitions` tables hold

data/lib/rigor/environment/required_features.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../analysis/path_expansion"
+require_relative "../rooted_glob"
 
 module Rigor
   class Environment
@@ -42,6 +43,36 @@ module Rigor
       # anything.
       PATTERN = /(?:(?<![\w.$@])|(?<=Kernel\.))require[ \t]*\(?[ \t]*(["'])(#{FEATURE_ALTERNATION})\1/
 
+      # Issue #2174 — the gems Ruby 4.0 bundles (its `gems/bundled_gems` list, which an installation does not
+      # keep): installed beside the interpreter, but loaded only by an explicit `require`. Gems installed later
+      # into the same directory are deliberately not read from it.
+      BUNDLED_GEMS = %w[
+        abbrev base64 benchmark bigdecimal csv debug drb fiddle getoptlong irb logger matrix minitest mutex_m
+        net-ftp net-imap net-pop net-smtp nkf observer ostruct power_assert prime pstore racc rake rbs rdoc readline
+        reline repl_type_completor resolv-replace rexml rinda rss syslog test-unit typeprof win32ole
+      ].freeze
+
+      # Issue #2174 — the first path segments of the features Ruby ships: the `.rb` files and directories of the
+      # interpreter's library directory, the extensions and directories of its architecture directory, and the
+      # bundled gems' names (`net-ftp` → `net`). Read once, at load time and on the main Ractor, since
+      # `RbConfig::CONFIG` is not shareable; empty when the directories cannot be read.
+      SHIPPED_SEGMENTS = begin
+        require "rbconfig"
+        segments = Set.new
+        [RbConfig::CONFIG["rubylibdir"], RbConfig::CONFIG["archdir"]].compact.each do |dir|
+          next unless File.directory?(dir)
+
+          Dir.children(dir).each { |entry| segments << entry.sub(/\.(?:rb|so|bundle|dll)\z/, "") }
+        end
+        BUNDLED_GEMS.each { |name| segments << name.split("-").first }
+        segments.to_set(&:freeze).freeze
+      rescue StandardError
+        Set.new.freeze
+      end
+
+      # A `require` of any literal feature, read as {PATTERN} reads one; {.features_of} keeps those Ruby ships.
+      ANY_FEATURE = %r{(?:(?<![\w.$@])|(?<=Kernel\.))require[ \t]*\(?[ \t]*(["'])([\w-]+(?:/[\w-]+)*)\1}
+
       module_function
 
       # The features a run over `configuration` requires: every file under the configured paths, plus
@@ -53,37 +84,51 @@ module Rigor
       def for_configuration(configuration, extra_files = [], sources: {})
         files = Analysis::PathExpansion.ruby_files(configuration.paths, configuration.exclude_patterns,
                                                    base: configuration.exclude_base)
-        scan(files + Array(extra_files).map(&:to_s), sources: sources)
+        scan(files + Array(extra_files).map(&:to_s), sources: sources,
+                                                     sig_paths: configured_sig_paths(configuration))
       rescue StandardError
         []
       end
 
+      # The project signature roots the environment loads: the configured `signature_paths:`, else `./sig` when it
+      # exists (`Environment.project_signature_roots`, which this leaf file does not load).
+      def configured_sig_paths(configuration)
+        configured = configuration.signature_paths
+        return Array(configured).map(&:to_s) if configured
+
+        File.directory?("sig") ? ["sig"] : []
+      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: {})
+      # @param sig_paths — the project's signature roots, whose `.rbs` declaration headers count as the project's
+      #   own names ({.relevant}).
+      # @return the sorted, frozen features some file requires, a shipped one kept only when {.relevant}.
+      def scan(files, sources: {}, sig_paths: [])
         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
+        names = 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))
+          features, declared = sources.key?(path) ? scan_source(sources[path]) : memoized_scan_in(path)
+          found.merge(features)
+          names.merge(declared)
         end
         prune_memo(paths)
-        found.to_a.sort.freeze
+        relevant(found, names.merge(sig_names(sig_paths))).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.
+      # @return path (absolute) => `[features, declared names]` ({.scan_source}) for every file under the
+      #   configured paths that has either. A long-lived reader (the language server) keeps this, overlays its open
+      #   buffers and passes the union to {.relevant}.
       def feature_files(configuration)
         listed = Analysis::PathExpansion.ruby_files(configuration.paths, configuration.exclude_patterns,
                                                     base: configuration.exclude_base)
         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?
+          scanned = memoized_scan_in(path)
+          acc[path] = scanned unless scanned.all?(&:empty?)
         end
         prune_memo(files)
         result
@@ -91,6 +136,42 @@ module Rigor
         {}
       end
 
+      # Issue #2174 — `features` with each shipped feature kept only when one of `names` (constant names the
+      # project's source or signatures declare a class or module under) is a root the feature's library declares
+      # ({RubyLibraryRoots}). Only such a feature can open a class (`RbsLoader#ruby_library_reopen?` asks it of a
+      # class every declaration of which is the project's), so dropping the rest changes no diagnostic, and keeps a
+      # `require "json"` edit in a project that reopens no library class out of the incremental snapshot's
+      # fingerprint and the language server's environment key. The listed features ({VENDORED_DIRS}) are kept.
+      def relevant(features, names)
+        return features.to_a if features.all? { |feature| VENDORED_DIRS.key?(feature) }
+
+        segments = names.empty? ? EMPTY_SEGMENTS : library_segments(names)
+        features.select { |feature| VENDORED_DIRS.key?(feature) || segments.include?(feature.split("/").first) }
+      end
+
+      # The feature segments of the libraries that declare one of `names` as a root. Loaded lazily: the roots read
+      # the `rbs` stdlib tree, which a run with no shipped `require` never needs.
+      def library_segments(names)
+        require_relative "ruby_library_roots"
+        roots = RubyLibraryRoots.shared
+        names.each_with_object(Set.new) { |name, acc| acc.merge(roots.fetch(name, EMPTY_SEGMENTS)) }
+      end
+
+      EMPTY_SEGMENTS = [].freeze
+
+      # The constant names the `.rbs` files under `sig_paths` declare a class or module under.
+      def sig_names(sig_paths)
+        Array(sig_paths).each_with_object(Set.new) do |root, acc|
+          next unless File.directory?(root.to_s)
+
+          RootedGlob.glob(root.to_s, "**/*.rbs").each do |path|
+            acc.merge(declared_names(File.binread(path)))
+          rescue SystemCallError, IOError
+            next
+          end
+        end
+      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.
@@ -114,8 +195,8 @@ module Rigor
       # 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
+      def memoized_scan_in(path)
+        return scan_in(path) unless Ractor.current == Ractor.main
 
         stat = File.stat(path)
         stamp = [stat.mtime.to_r, stat.ctime.to_r, stat.size, stat.ino]
@@ -123,13 +204,15 @@ module Rigor
         cached = memo[path]
         return cached.last if cached && cached.first == stamp
 
-        features = features_in(path)
-        memo[path] = [stamp, features]
-        features
+        scanned = scan_in(path)
+        memo[path] = [stamp, scanned]
+        scanned
       rescue SystemCallError
-        []
+        NOTHING
       end
 
+      NOTHING = [[].freeze, [].freeze].freeze
+
       # 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)
@@ -139,28 +222,51 @@ module Rigor
         @memo.select! { |path, _| keep.include?(path) }
       end
 
-      # @return the features one file requires.
-      def features_in(path)
-        features_of(File.binread(path))
+      # @return `[features, declared names]` for one file ({.scan_source}).
+      def scan_in(path)
+        scan_source(File.binread(path))
       rescue SystemCallError, IOError
-        []
+        NOTHING
+      end
+
+      # @return `[features, declared names]`: what {.features_of} reads, and the constant names a `class` or
+      # `module` header in `source` spells, each segment on its own (`class Net::SMTP` gives `Net` and `SMTP`).
+      def scan_source(source)
+        [features_of(source), declared_names(source)].freeze
+      end
+
+      # A header on a line of its own, or inside a comment (an rbs-inline `# @rbs!` block declares
+      # `#   class Matrix`). Over-matching a comment only keeps more features.
+      HEADER = /^[ \t]*(?:#[ \t]*)?(?:class|module)[ \t]+(?:::)?([A-Z]\w*(?:::[A-Z]\w*)*)/
+
+      def declared_names(source)
+        bytes = source.b
+        return [] unless bytes.include?("class") || bytes.include?("module")
+
+        bytes.scan(HEADER).flat_map { |(name)| name.split("::") }
+             .uniq.map { |name| name.dup.force_encoding(Encoding::UTF_8).freeze }.freeze
       end
 
-      # @return the features `source` requires.
+      # @return the features `source` requires: the listed ones ({VENDORED_DIRS}), and, for issue #2174, every
+      # feature Ruby ships ({SHIPPED_SEGMENTS}), which `RbsLoader#ruby_library_reopen?` reads to tell a reopened
+      # library class from a project class of the same name. Only the listed ones become library tokens.
       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) }
+        # A plain substring test first: a file with no `require` at all is the common case, and it is far cheaper
+        # than the regexp on a file that has none.
+        return [] unless source.include?("require")
 
         bytes = source.b
         named = []
         position = 0
-        while (match = PATTERN.match(bytes, position))
+        while (match = ANY_FEATURE.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) }
+        # The table's own frozen keys, and frozen copies of the rest, so the result is shareable across Ractors
+        # whatever the source's encoding.
+        listed = VENDORED_DIRS.each_key.select { |feature| named.include?(feature) }
+        shipped = named.select { |feature| SHIPPED_SEGMENTS.include?(feature.split("/").first) }
+        (listed + shipped.map { |feature| feature.dup.force_encoding(Encoding::UTF_8).freeze }).uniq
       end
 
       # Whether the match at `offset` sits on a line whose first non-blank character is `#`: a whole-line comment.
@@ -176,7 +282,8 @@ module Rigor
       # 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) }
+        listed = Array(features).select { |feature| VENDORED_DIRS.key?(feature) }
+        (listed | configured).sort.map { |feature| token(feature) }
       end
 
       def token(feature)
@@ -189,17 +296,14 @@ module Rigor
         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

data/lib/rigor/environment/ruby_library_roots.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "rbs"
+require "rbconfig"
+require_relative "missing_gem_constant_index"
+require_relative "required_features"
+require_relative "../rooted_glob"
+
+module Rigor
+  class Environment
+    # Issue #2174 — which library Ruby ships declares each root constant name. Three sources are read, and no others:
+    #
+    # - every library of the `rbs` gem's `stdlib/` tree, loaded into this run or not, read from its `.rbs` files
+    #   (`net-http` declares `Net`);
+    # - every top-level `.rb` file of the interpreter's library directory (`RbConfig::CONFIG["rubylibdir"]`), the
+    #   default gems' and the standard library's entry files, read from their top-level declarations;
+    # - the entry file of each gem Ruby bundles ({RequiredFeatures::BUNDLED_GEMS}), found under the interpreter's
+    #   gem directory. A gem installed there later is not one of them and is not read.
+    #
+    # Each root maps to the first path segments of the features that load it (`Matrix` → `matrix`, `Net` → `net`),
+    # which {RbsLoader#ruby_library_reopen?} intersects with the features the project's source requires
+    # ({RequiredFeatures.features_of}).
+    #
+    # Ownership is read, never guessed by camelizing a library name, for the reason {MissingGemConstantIndex}
+    # gives; that module's reader parses the `.rb` entry files. No library code runs. Everything fails open to
+    # "no library", which keeps the pre-#2174 reading. Core names (`Array`, `Kernel`) appear too, harmlessly:
+    # core signatures always load, so no project-only class carries one.
+    #
+    # The directories are resolved at load time, on the main Ractor: `RbConfig::CONFIG` and `Gem.default_dir`
+    # read non-shareable constants and raise `Ractor::IsolationError` inside a pool worker. The scan itself runs
+    # lazily (about 0.1 s), memoised per process, and only for a class about to be reported.
+    module RubyLibraryRoots
+      STDLIB_ROOT = begin
+        ::RBS::Repository::DEFAULT_STDLIB_ROOT.to_s.dup.freeze
+      rescue StandardError
+        nil
+      end
+
+      RUBY_LIB_DIR = begin
+        RbConfig::CONFIG["rubylibdir"].to_s.dup.freeze
+      rescue StandardError
+        nil
+      end
+
+      RUBY_GEMS_DIR = begin
+        File.join(Gem.default_dir, "gems").freeze
+      rescue StandardError
+        nil
+      end
+
+      module_function
+
+      # {.build}, built once per process on the main Ractor, where the language server and the incremental
+      # snapshot fingerprint ask it repeatedly; a non-main Ractor may not keep module state and builds its own.
+      def shared
+        return build unless Ractor.current == Ractor.main
+
+        @shared ||= build
+      end
+
+      # The frozen map of root constant name to the frozen set of feature segments that load it.
+      def build
+        roots = Hash.new { |hash, key| hash[key] = Set.new }
+        stdlib_roots(roots)
+        ruby_lib_roots(roots)
+        bundled_gem_roots(roots)
+        roots.each_value(&:freeze)
+        roots.default_proc = nil
+        roots.freeze
+      end
+
+      def stdlib_roots(roots)
+        return if STDLIB_ROOT.nil? || !File.directory?(STDLIB_ROOT)
+
+        Dir.children(STDLIB_ROOT).each do |library|
+          segment = library.split("-").first
+          RootedGlob.glob(File.join(STDLIB_ROOT, library), "*/**/*.rbs").each do |path|
+            stdlib_file_roots(path).each { |root| roots[root] << segment }
+          end
+        end
+      end
+
+      def stdlib_file_roots(path)
+        _, _, decls = ::RBS::Parser.parse_signature(File.read(path))
+        decls.filter_map { |decl| root_of(decl) if named_declaration?(decl) }
+      rescue StandardError
+        []
+      end
+
+      def ruby_lib_roots(roots)
+        return if RUBY_LIB_DIR.nil? || !File.directory?(RUBY_LIB_DIR)
+
+        RootedGlob.glob(RUBY_LIB_DIR, "*.rb").each do |path|
+          segment = File.basename(path, ".rb")
+          MissingGemConstantIndex.top_level_root_constants(path).each { |root| roots[root] << segment }
+        end
+      end
+
+      def bundled_gem_roots(roots)
+        return if RUBY_GEMS_DIR.nil? || !File.directory?(RUBY_GEMS_DIR)
+
+        Dir.children(RUBY_GEMS_DIR).each do |basename|
+          gem_name = basename[/\A(.+?)-\d/, 1]
+          next if gem_name.nil? || !RequiredFeatures::BUNDLED_GEMS.include?(gem_name)
+
+          segment = gem_name.split("-").first
+          MissingGemConstantIndex.entry_files(File.join(RUBY_GEMS_DIR, basename), gem_name).each do |path|
+            MissingGemConstantIndex.top_level_root_constants(path).each { |root| roots[root] << segment }
+          end
+        end
+      end
+
+      def named_declaration?(decl)
+        decl.is_a?(::RBS::AST::Declarations::Class) || decl.is_a?(::RBS::AST::Declarations::Module)
+      end
+
+      def root_of(decl)
+        decl.name.to_s.delete_prefix("::").split("::").first
+      end
+    end
+  end
+end

data/lib/rigor/environment/vendored_signature_plan.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "rbs"
+require_relative "../rooted_glob"
+require_relative "gated_signature_plan"
+
+module Rigor
+  class Environment
+    # Issue #2470 — a `data/vendored_gem_sigs/<gem>/` member another signature source also declares stands down,
+    # so the other source's declaration binds instead of the two failing the class's definition build.
+    #
+    # The vendored directories load on `RBS::EnvironmentLoader`'s batch path, ahead of the project's
+    # `signature_paths:` (its own `sig/`, an `rbs collection install`, a gem's `sig/`). A file there that reopens
+    # a vendored class and declares one of its methods again — the activerecord 8.1 collection's `patch.rbs`
+    # writes `def async_exec` on `PG::Connection`, where the vendored `pg.rbs` has `alias async_exec exec` — made
+    # `RBS::DefinitionBuilder` raise `DuplicatedMethodDefinitionError` for the class, which Rigor keeps known, so
+    # every call into it read `Dynamic[top]`.
+    #
+    # {.build} is the #1713 member rule ({GatedSignaturePlan}) applied to the ungated directories, planned from
+    # the signature files themselves rather than from a trial build: the vendored copy is Rigor's guess at a gem's
+    # surface, and the project chose the other source, so the other source wins (`RbsLoader.build_env_for`'s
+    # stated precedence). Only a directory with a member to leave out is planned; the rest stay on the batch path.
+    # An overload continuation (`def m: ... | ...`) declares nothing of its own and keeps the vendored base.
+    #
+    # The plan is a pure function of the vendored files and the signature files, both of which the env-cache key
+    # digests, so a cold and a warm run build the same environment.
+    module VendoredSignaturePlan
+      # `dirs` — the vendored directories (Pathnames) to keep off the batch path; `sources` — their files as
+      # `[buffer, directives, decls]`, the taken members left out, to add right after the batch; `takers` — the
+      # signature files a member stood down to. A member stands down only to a file that stays in the env: the
+      # caller re-plans without each taker the build quarantined (`RbsLoader.build_env_attempt`), or the method
+      # would have no declaration at all.
+      Plan = Data.define(:dirs, :sources, :takers)
+      EMPTY = Plan.new(dirs: [].freeze, sources: [].freeze, takers: Set.new.freeze)
+
+      # A `class` / `module` header, after any `%a{...}` / `%a(...)` / `%a[...]` annotations on the same line.
+      ANNOTATED_HEADER = /^\s*(?:%a(?:\{[^}]*\}|\([^)]*\)|\[[^\]]*\])\s*)*(?:class|module)\s+(?:::)?/
+
+      module_function
+
+      # @param roots — the ungated vendored directories this build loads.
+      # @param signature_files — the absolute paths of the signature files that outrank them.
+      # @param excluded — signature files to plan without: takers a previous build of this env quarantined.
+      def build(roots, signature_files, excluded = Set.new)
+        files = signature_files.reject { |file| excluded.include?(file) }
+        return EMPTY if roots.empty? || files.empty?
+
+        parsed = roots.to_h { |root| [root, parsed_sources(root)] }
+        taken = taken_keys(files, header_pattern(parsed.values.flatten(1)))
+        return EMPTY if taken.empty?
+
+        takers = Set.new
+        planned = parsed.filter_map do |root, sources|
+          kept = plan_sources(sources, taken, takers)
+          [root, kept] if kept
+        end
+        return EMPTY if planned.empty?
+
+        Plan.new(dirs: planned.map(&:first), sources: planned.flat_map(&:last), takers: takers.freeze)
+      end
+
+      # A vendored directory's files, parsed, under the Pathname buffer names the loader's batch path gives them,
+      # in the set `RBS::EnvironmentLoader#add(path:)` reads: every `.rbs` under it.
+      def parsed_sources(root)
+        RootedGlob.glob(root, "**/*.rbs").sort.filter_map { |file| RbsLoader.parse_signature_file(Pathname(file)) }
+      end
+
+      # `sources` with the taken members left out, or nil when nothing is taken from any of them.
+      def plan_sources(sources, taken, takers)
+        kept = sources.map do |buffer, directives, decls|
+          [buffer, directives, plan_decls(decls, nil, taken, takers)]
+        end
+        kept unless kept.zip(sources).all? { |(_, _, after), (_, _, before)| unchanged?(after, before) }
+      end
+
+      # A header naming one of the vendored top-level types, which every declaration of a vendored type (nested or
+      # `A::B`-qualified) starts from. A pre-filter only: the matches are parsed.
+      def header_pattern(parsed)
+        heads = parsed.flat_map do |_buffer, _directives, decls|
+          decls.filter_map { |decl| GatedSignaturePlan.type_declaration?(decl) && decl.name.to_s.delete_prefix("::") }
+        end
+        segments = heads.map { |name| Regexp.escape(name.split("::").first) }.uniq
+        return nil if segments.empty?
+
+        /#{ANNOTATED_HEADER}(?:#{segments.join('|')})\b/
+      end
+
+      # `{type name => {[method, kind] => Set[file]}}` over the signature files that declare a vendored top-level
+      # type.
+      def taken_keys(signature_files, pattern)
+        taken = Hash.new { |hash, name| hash[name] = Hash.new { |keys, key| keys[key] = Set.new } }
+        return taken if pattern.nil?
+
+        signature_files.sort.each do |file|
+          text = RbsLoader.read_signature_text(file)
+          next if text.nil? || !text.match?(pattern)
+
+          decls = RbsLoader.parse_signature_source(file, text)
+          collect_keys(decls, nil, taken, file) if decls
+        end
+        taken
+      end
+
+      def collect_keys(decls, namespace, taken, file)
+        decls.each do |decl|
+          next unless GatedSignaturePlan.type_declaration?(decl)
+
+          name = GatedSignaturePlan.qualify(namespace, decl.name)
+          decl.members.each do |member|
+            RbsLoader.member_method_keys(member).each { |key| taken[name][key] << file }
+          end
+          collect_keys(decl.members, name, taken, file)
+        end
+      end
+
+      # `decls` with every member `taken` declares for its type left out, nested types planned the same way, and
+      # the files each left-out member stood down to added to `takers`. A declaration nothing is taken from is
+      # returned as itself, which is how {.build} tells a directory unchanged.
+      def plan_decls(decls, namespace, taken, takers)
+        decls.map do |decl|
+          next decl unless GatedSignaturePlan.type_declaration?(decl)
+
+          plan_type(decl, GatedSignaturePlan.qualify(namespace, decl.name), taken, takers)
+        end
+      end
+
+      def unchanged?(after, before)
+        after.size == before.size && after.zip(before).all? { |a, b| a.equal?(b) }
+      end
+
+      def plan_type(decl, name, taken, takers)
+        keys = taken.fetch(name, nil)
+        members = decl.members.filter_map do |member|
+          if GatedSignaturePlan.type_declaration?(member)
+            plan_type(member, GatedSignaturePlan.qualify(name, member.name), taken, takers)
+          elsif keys
+            plan_member(member, keys, takers)
+          else
+            member
+          end
+        end
+        return decl if unchanged?(members, decl.members)
+
+        GatedSignaturePlan.rebuild(decl, members: members)
+      end
+
+      def plan_member(member, keys, takers)
+        RbsLoader.member_method_keys(member).each { |key| takers.merge(keys[key]) if keys.key?(key) }
+        GatedSignaturePlan.untaken(member, keys)
+      end
+    end
+  end
+end