rigortype 0.4.7 → 0.4.8

data/lib/rigor/sig_gen/generator.rb

@@ -17,6 +17,7 @@ require_relative "../inference/def_return_typer"
 require_relative "../inference/scope_indexer"
 require_relative "../inference/project_seed_tables"
 require_relative "../inference/module_function_state"
+require_relative "bot_proposal_guard"
 require_relative "../inference/rbs_type_translator"
 require_relative "alias_index"
 require_relative "meta_class_shape"
@@ -27,6 +28,7 @@ require_relative "declaration_equivalence"
 require_relative "inline_declarations"
 require_relative "layout_index"
 require_relative "method_candidate"
+require_relative "platform_guarded_files"
 require_relative "type_name_qualification"
 require_relative "writer"
 require_relative "../rooted_glob"
@@ -164,6 +166,11 @@ module Rigor
       def run
         resolved = resolve_paths(@paths)
         @resolved_paths = resolved
+        # Issue #3035 — the scanned files Ruby loads only through a platform-conditional require; their
+        # candidates are demoted in {#demote_platform_guarded}.
+        @platform_guarded_files = PlatformGuardedFiles.call(
+          resolved, ruby_version: @configuration.target_ruby
+        )
         @environment = build_environment(resolved)
         # ADR-84 WD2, as `Runner#run_analysis` mints it for `check` (#2300): one return-memo bucket for the whole
         # run. Without it the memo keys on each file's merged `discovered_def_nodes`, a new table per file, so a
@@ -176,10 +183,21 @@ module Rigor
         @file_base_scope = nil
         # #2461 — which `sig/` targets the writer will write to, read from the files as they are now.
         @writable_targets = {}
-        candidates = resolved.flat_map { |path| analyse_file(path, @environment) }
-        demoted = demote_overridden_base_methods(
-          demote_unresolvable_superclasses(
-            demote_generic_reopenings(demote_inline_generic_classes(resolve_superclass_spellings(candidates)))
+        # ADR-130 WD5 — with interface dispatch off, so a return read through a `Rigor::Plugin` interface member
+        # (`_FactStore#publish: ... -> nil`) is not written into RBS a plugin author never wrote against the
+        # interface: the output is the output of erasure.
+        candidates = Inference::MethodDispatcher::RbsDispatch.without_interface_dispatch do
+          resolved.flat_map { |path| analyse_file(path, @environment) }
+        end
+        demoted = shelter_withheld_classes(
+          demote_platform_guarded(
+            demote_overridden_base_methods(
+              demote_bot_proposals(
+                demote_unresolvable_superclasses(
+                  demote_generic_reopenings(demote_inline_generic_classes(resolve_superclass_spellings(candidates)))
+                )
+              )
+            )
           )
         )
         # Again after the override demotion: a demoted method can leave its file with nothing to write, and a class
@@ -390,6 +408,82 @@ module Rigor
         end
       end
 
+      # Issue #3029 — an emittable `-> bot` proposal for an overridden, abstract or template method is skipped
+      # ({BotProposalGuard}). It runs before {#demote_overridden_base_methods}, so a subclass's `bot` override this
+      # skips counts there as an override that is not emitted, and its parent's declaration is held back too.
+      def demote_bot_proposals(candidates)
+        guard = nil
+        candidates.map do |candidate|
+          next candidate unless Classification::EMITTABLE.include?(candidate.classification)
+          next candidate if candidate.classification == Classification::INLINE_OVERWRITE
+          next candidate unless candidate.inferred_return.is_a?(Type::Bot)
+
+          guard ||= BotProposalGuard.new(project_tables)
+          reason = guard.reason_for(candidate)
+          reason ? demoted_candidate(candidate, reason) : candidate
+        end
+      end
+
+      # The reasons that withhold a member because of what its class's subclasses or callees do, not because the class
+      # itself cannot be declared. `:platform_guarded` counts too (#3035): a class whose every proposal the guard
+      # withheld — the raising-stub shape — still needs its shell on a subclass's file, or the subclass's own
+      # declaration reads `unresolvable-superclass` against a class this platform does load.
+      WITHHELD_FOR_OVERRIDES = %i[overridden_bot abstract_method template_method overridden_by_unsigned_subclass
+                                  platform_guarded].freeze
+      private_constant :WITHHELD_FOR_OVERRIDES
+
+      # Issue #3029 — a class whose members {#demote_bot_proposals} or {#demote_overridden_base_methods} withheld,
+      # leaving it nothing to emit, is still declared, as a class shell, so its subclasses keep their proposals.
+      # Without it an all-abstract base has nothing to write, {#demote_unresolvable_superclasses} finds no
+      # declaration for it, and every subclass proposal is skipped as `unresolvable-superclass`. The shell rides on
+      # each file that declares one of its subclasses, so it reaches disk wherever a subclass's members do. The writer
+      # spells its header with the run's recorded superclass and namespace kinds. A class the file already declares
+      # makes the shell a no-op, and one the loaded RBS declares gets none ({#wholly_withheld_classes}). A class whose
+      # own superclass chain is unresolvable is already skipped as `unresolvable-superclass` when this pass runs, so
+      # it is never withheld here and gets no shell.
+      def shelter_withheld_classes(candidates)
+        withheld = wholly_withheld_classes(candidates)
+        return candidates if withheld.empty?
+
+        shells_by_path = withheld_shell_paths(candidates, withheld)
+        candidates.map do |candidate|
+          extra = shells_by_path.fetch(candidate.path, nil)
+          next candidate if extra.nil?
+
+          shells = (candidate.class_shells + extra.to_a).uniq
+          shells.size == candidate.class_shells.size ? candidate : candidate.with_class_shells(shells)
+        end
+      end
+
+      # The classes to shelter: a withheld member and nothing to emit, and no declaration in the loaded RBS (`sig/`,
+      # the collection, gems). A declared class needs no shell for its subclasses' headers to resolve, and a shell
+      # spelling the source's superclass could contradict the declaration's (`RBS::SuperclassMismatchError`).
+      def wholly_withheld_classes(candidates)
+        by_class = candidates.select(&:class_name).group_by(&:class_name)
+        by_class.each_with_object(Set.new) do |(name, rows), acc|
+          next unless rows.any? { |c| WITHHELD_FOR_OVERRIDES.include?(c.skip_reason) }
+          next if rows.any? { |c| Classification::EMITTABLE.include?(c.classification) }
+          next if class_known?(name)
+
+          acc << name
+        end
+      end
+
+      # `{ path => Set[class name] }`: the files each withheld class's shell rides on, which are the files of every
+      # candidate whose class descends from it, however far down.
+      def withheld_shell_paths(candidates, withheld)
+        superclasses = candidates.each_with_object({}) do |candidate, acc|
+          (candidate.class_superclasses || {}).each { |name, sup| acc[name] = bare_superclass_name(sup) }
+        end
+        candidates.each_with_object(Hash.new { |h, k| h[k] = Set.new }) do |candidate, acc|
+          next if candidate.class_name.nil?
+
+          each_ancestor(candidate.class_name, superclasses) do |ancestor|
+            acc[candidate.path] << ancestor if withheld.include?(ancestor)
+          end
+        end
+      end
+
       # `[class name, method name]` pairs an UNSIGNED override shadows: for every candidate that will not
       # be emitted, every ancestor of its class paired with its method name.
       def unsigned_override_ancestors(candidates, superclasses)
@@ -421,6 +515,54 @@ module Rigor
         )
       end
 
+      # Issue #3035 — a file Ruby loads only under a `RUBY_ENGINE` / `RUBY_PLATFORM` / `defined?(…)`
+      # require guard is not an ordinary definition for the platform sig-gen cannot pick:
+      # `stackprof/truffleruby.rb`'s raising `StackProf.run` stub proposed `-> bot` against the C
+      # extension's real signature. {PlatformGuardedFiles} names those files; a candidate from one is
+      # demoted when another file also provides the method — the guarded proposal would compete with
+      # or duplicate the definition this platform actually loads — or when its inferred return is
+      # `bot`, the shape a raising stub takes and never a contract worth writing from a file the
+      # current engine may never read. It runs after every demotion — LAST of them — so an earlier
+      # pass still sees the guarded candidate as emittable: a platform-conditional override is no
+      # "unsigned subclass" ({#demote_overridden_base_methods}), {BotProposalGuard} still reads its
+      # `bot` on the discovery tables, and demoting the base for a file this platform never loads
+      # would withhold a declaration the guarded file cannot shadow here. It runs BEFORE
+      # {#shelter_withheld_classes}, which must see the final emittable set: a class left with
+      # nothing to emit only because this pass withheld its last member still needs its shell.
+      def demote_platform_guarded(candidates)
+        guarded = @platform_guarded_files
+        return candidates if guarded.nil? || guarded.empty?
+
+        providers = method_providers(candidates)
+        candidates.map do |candidate|
+          next candidate unless platform_guarded_demote?(candidate, guarded, providers)
+
+          demoted_candidate(candidate, :platform_guarded)
+        end
+      end
+
+      # `[class_name, kind, method_name]` → the expanded paths of every candidate providing it, the
+      # guarded file's own included — "another definition also provides" is the `!= own` test.
+      def method_providers(candidates)
+        candidates.each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |candidate, acc|
+          next if candidate.class_name.nil?
+
+          acc[[candidate.class_name, candidate.kind, candidate.method_name]] <<
+            File.expand_path(candidate.path)
+        end
+      end
+
+      def platform_guarded_demote?(candidate, guarded, providers)
+        return false unless Classification::EMITTABLE.include?(candidate.classification)
+        return false if candidate.class_name.nil?
+
+        own = File.expand_path(candidate.path)
+        return false unless guarded.include?(own)
+
+        slot = [candidate.class_name, candidate.kind, candidate.method_name]
+        candidate.inferred_return&.erase_to_rbs == "bot" || providers[slot].any? { |path| path != own }
+      end
+
       # Issue #722 — resolves each recorded superclass token to the class Ruby means by it, and rewrites the
       # emitted spelling when the two differ.
       #
@@ -537,11 +679,30 @@ module Rigor
           unresolvable = found
           current = candidates.map do |candidate|
             owner = unresolvable_for(candidate.class_name, unresolvable)
-            owner ? record_unresolvable_superclass(candidate, owner) : candidate
+            candidate = record_unresolvable_superclass(candidate, owner) if owner
+            drop_unresolvable_shells(candidate, unresolvable)
           end
         end
       end
 
+      # Issue #2715 — a nested declaration's class shell rides on a surviving sibling's candidate (`class QueryColumn`
+      # beside `class Query < BaseRecord` wrapping `class QueryError`), so demoting the container's own candidates
+      # leaves the shell, and the writer renders the container around it with the unresolvable superclass: the next
+      # `check` fails `RBS::NoSuperclassFoundError`. A shell inside a demoted class goes with it, like a demoted
+      # class's own members, and a demoted candidate sheds them too: a shell left on one would still count as emitted
+      # ({#declared_by_run}), so a written subclass of the dropped nested class would fail its build.
+      # Writing the container bare instead would make it RBS-known without its ancestry, which
+      # a later run (or a path-subset run) would take for a resolvable superclass of its subclasses.
+      def drop_unresolvable_shells(candidate, unresolvable)
+        shells = (candidate.class_shells || []).to_a
+        kept = shells.reject do |name|
+          owner = unresolvable_for(name, unresolvable)
+          @unresolvable_superclasses[owner.first] ||= owner.last if owner
+          owner
+        end
+        kept.size == shells.size ? candidate : candidate.with_class_shells(kept)
+      end
+
       def unresolvable_superclass_roots(superclasses, emitted)
         superclasses.each_with_object({}) do |(name, _sup), acc|
           root = unresolved_superclass_root(name, superclasses, emitted)
@@ -683,6 +844,8 @@ module Rigor
       end
 
       # #1406 — sig-gen keeps the census's own answer: a declared ivar type read back would echo the declaration.
+      # #2489 — `base_scope` names the file, so the class-ivar census joins the writes another file's reopening and
+      # the class's ancestors make ({Inference::ScopeIndexer::IvarContributions}), as `rigor check`'s does.
       def index_file(root, base_scope)
         Inference::ScopeIndexer.index(
           root, default_scope: base_scope, ivar_writer_scope: ivar_writer_scope(base_scope), declared_ivar_types: false
@@ -706,7 +869,7 @@ module Rigor
         parse_result = Prism.parse(source, filepath: path, version: @configuration.target_ruby)
         return [] if parse_result.errors.any?
 
-        scope_index = index_file(parse_result.value, file_base_scope(environment))
+        scope_index = index_file(parse_result.value, file_base_scope(environment).with_source_path(path))
 
         reset_file_maps
         @meta_layouts = collect_meta_layouts(scope_index)
@@ -859,6 +1022,8 @@ module Rigor
         @in_effect_refinements = nil
         out = []
         @block_depth = 0
+        @hook_blocks = {}.compare_by_identity
+        @hook_block_prefixes = []
         @certain_bodies = Set.new.compare_by_identity
         @certain_definers = Set.new.compare_by_identity
         mark_certain_body(root.statements)
@@ -873,7 +1038,9 @@ module Rigor
         when Prism::ClassNode, Prism::ModuleNode
           return if descend_into_namespace?(node, prefix, out)
         when Prism::SingletonClassNode
-          if node.expression.is_a?(Prism::SelfNode) && node.body
+          # `class << M` inside `module M` opens the same singleton as `class << self` (#3155).
+          if node.body && (node.expression.is_a?(Prism::SelfNode) ||
+                           Inference::ScopeIndexer.def_receiver_targets_lexical_self?(node.expression, prefix))
             mark_certain_body(node.body)
             walk_defs(node.body, prefix, true, false, out)
             return
@@ -908,12 +1075,30 @@ module Rigor
         in_block = node.is_a?(Prism::BlockNode) || node.is_a?(Prism::LambdaNode) ||
                    node.is_a?(Prism::SingletonClassNode)
         @block_depth += 1 if in_block
+        hook_block = @hook_blocks.key?(node)
+        @hook_block_prefixes.push(prefix) if hook_block
         node.rigor_each_child do |child|
           walk_defs(child, prefix, in_singleton_class, module_function_active, out)
         end
+        @hook_block_prefixes.pop if hook_block
         @block_depth -= 1 if in_block
       end
 
+      # Issue #3015 — the `included do … end` / `prepended do … end` statements of a body that runs `extend
+      # ActiveSupport::Concern`: Ruby runs the block in the includer's class body, so a `def self.x` or `class << self`
+      # def there is the includer's singleton method, not the module's, and {#collect_def_node} leaves it out.
+      def mark_hook_blocks(namespace_node, prefix)
+        body = namespace_node.body
+        return unless namespace_node.is_a?(Prism::ModuleNode) && Inference::ScopeIndexer.concern_body?(body, prefix)
+
+        body.body.each do |statement|
+          next unless statement.is_a?(Prism::CallNode) && statement.receiver.nil? &&
+                      %i[included prepended].include?(statement.name) && statement.block.is_a?(Prism::BlockNode)
+
+          @hook_blocks[statement] = true
+        end
+      end
+
       # [#722](https://github.com/rigortype/rigor/issues/722) residue 3 — the qualified name is built by
       # `Source::ConstantPath.declaration_prefix`, the same reader the engine's declaration walks use, so a
       # ROOTED header re-anchors here too. Appending the rendered name to the enclosing prefix wrote
@@ -1113,6 +1298,7 @@ module Rigor
         return if namespace_node.body.nil?
 
         mark_certain_body(namespace_node.body)
+        mark_hook_blocks(namespace_node, prefix)
         walk_defs(namespace_node.body, prefix, false, false, out)
       end
 
@@ -1151,7 +1337,12 @@ module Rigor
           return
         end
 
-        kind = node.receiver.is_a?(Prism::SelfNode) || in_singleton_class ? :singleton : :instance
+        # `def Foo.x` inside `module Foo` is `def self.x` (#2950), and a def on another object's singleton is no method
+        # of this class (#3155); the rule is the one check indexes defs by.
+        kind = Inference::ScopeIndexer.def_side(node, prefix, in_singleton_class)
+        return if kind.nil?
+        return if kind == :singleton && @hook_block_prefixes.last == prefix
+
         class_name = prefix.join("::")
         if Inference::ModuleFunctionState.sig_gen_module_function?(module_function_active, kind)
           @module_function_methods << node
@@ -1771,7 +1962,7 @@ module Rigor
           return equivalent(path, def_node, class_name, kind, inferred, declared_rbs)
         end
 
-        unless tighter?(declared, inferred) && !literal_decline?(inferred, def_node)
+        unless tighter?(declared, inferred) && !literal_decline?(inferred, def_node, declared)
           return equivalent(path, def_node, class_name, kind, inferred, declared_rbs)
         end
 
@@ -2060,11 +2251,24 @@ module Rigor
 
       def structurally_covers?(inferred_member, declared_member)
         return true if inferred_member == declared_member
+        return true if nominal_subclass_of?(inferred_member, declared_member)
 
         result = inferred_member.accepts(declared_member)
         result.respond_to?(:yes?) && result.yes?
       end
 
+      # Issue #2914 — a proposed member that is a subclass of the declared one keeps that member: declared
+      # `Prism::Node?` against an inferred `Prism::DefNode?` narrows what a caller receives without dropping a
+      # branch the caller could observe, unlike a lost `nil` or a lost alternate. Only a bare nominal pair whose
+      # ordering the analyzer's class data decides (`Environment#class_ordering`, RBS hierarchy included) is
+      # read this way; a generic pair or an `:unknown` ordering stays uncovered, so the guard still declines.
+      def nominal_subclass_of?(inferred_member, declared_member)
+        return false unless inferred_member.is_a?(Type::Nominal) && declared_member.is_a?(Type::Nominal)
+        return false unless inferred_member.type_args.empty? && declared_member.type_args.empty?
+
+        @environment&.class_ordering(inferred_member.class_name, declared_member.class_name) == :subclass
+      end
+
       GENERIC_COLLECTION_CLASSES = %w[
         Array Hash Set Range Enumerable Enumerator Enumerator::Lazy
       ].freeze
@@ -2080,8 +2284,8 @@ module Rigor
       # The two reasons a `Type::Constant` the body proves is not the method's contract. Both say the same
       # thing from opposite ends: the precision is real about this body and says nothing about the promise
       # the method makes to its callers.
-      def literal_decline?(inferred, def_node)
-        computed_literal_tightening?(inferred, def_node) || pins_literal_over_declaration?(inferred)
+      def literal_decline?(inferred, def_node, declared)
+        computed_literal_tightening?(inferred, def_node) || pins_literal_over_declaration?(inferred, declared)
       end
 
       # Issue #837 — a proposal that erases to an RBS LITERAL type never tightens an existing declaration.
@@ -2106,9 +2310,14 @@ module Rigor
       # is refused when ANY member is a literal: a mixed `("a" | Float)` pins `"a"` just as a bare one does.
       # A literal nested inside a shape carrier (`[1, 2]`, a `HashShape` value) is a different question,
       # already answered for the collection declarations that matter by {#narrows_collection_to_shape?}.
-      def pins_literal_over_declaration?(inferred)
+      #
+      # A literal the declaration itself spells is not pinned over it (#2914): declared `Prism::Node?` against
+      # a proposed `Prism::DefNode?` carries the same `nil` member the author wrote, so only the narrowed
+      # nominal arm is new. A literal the declaration does not spell is refused as before.
+      def pins_literal_over_declaration?(inferred, declared)
         members = inferred.is_a?(Type::Union) ? inferred.members : [inferred]
-        members.any? { |member| rbs_literal?(member) }
+        declared_members = declared.is_a?(Type::Union) ? declared.members : [declared]
+        members.any? { |member| rbs_literal?(member) && !declared_members.include?(member) }
       end
 
       # `Type::Constant#erase_to_rbs` spells the values RBS writes as literal types (`true` / `false` /

data/lib/rigor/sig_gen/method_candidate.rb

@@ -108,6 +108,20 @@ module Rigor
         )
       end
 
+      # A copy carrying more class shells: a class whose every member a later pass withheld still has to be
+      # declared for its subclasses' headers (#3029).
+      def with_class_shells(class_shells)
+        self.class.new(
+          path: @path, class_name: @class_name, method_name: @method_name, kind: @kind,
+          classification: @classification, inferred_return: @inferred_return,
+          declared_return_rbs: @declared_return_rbs, rbs: @rbs, skip_reason: @skip_reason,
+          namespace_kinds: @namespace_kinds, class_shells: class_shells,
+          class_superclasses: @class_superclasses, annotations: @annotations, effect_reason: @effect_reason,
+          declared_rbs: @declared_rbs, declared_annotations: @declared_annotations,
+          class_type_params: @class_type_params
+        )
+      end
+
       def to_h
         {
           file: path,

data/lib/rigor/sig_gen/observation_collector.rb

@@ -4,6 +4,7 @@ require "prism"
 
 require_relative "../environment"
 require_relative "../project_environment"
+require_relative "../run_scoped_slots"
 require_relative "../scope"
 require_relative "../type"
 require_relative "../source/constant_path"
@@ -56,10 +57,18 @@ module Rigor
         environment = build_environment(resolved)
         discovered_classes = preindex_source_classes
         observations = Hash.new { |h, k| h[k] = [] }
-        resolved.each do |path|
-          collect_from_file(path, environment, discovered_classes, observations)
+        # ADR-130 WD5 — with interface dispatch off, as {Generator#run} analyses: an argument read through a
+        # `Rigor::Plugin` interface member is not written into a parameter type either.
+        Inference::MethodDispatcher::RbsDispatch.without_interface_dispatch do
+          resolved.each do |path|
+            collect_from_file(path, environment, discovered_classes, observations)
+          end
         end
         observations.transform_values(&:freeze).freeze
+      ensure
+        # Issue #2869 — release this analysis's run-scoped slots, as every other entry point that runs one does, so
+        # a later run (the generator's, under its own interface-dispatch install) starts from none of them.
+        RunScopedSlots.release
       end
 
       # Whether `arg` names something {#collect} reads: a directory, or a `.rb` file. The CLI's

data/lib/rigor/sig_gen/platform_guarded_files.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../source/node_children"
+
+module Rigor
+  module SigGen
+    # Issue #3035 — the files a sig-gen run must not read as ordinary definitions: every scanned `.rb`
+    # file Ruby loads ONLY through a platform-conditional `require` / `require_relative`.
+    #
+    # `stackprof.rb` opens with `if RUBY_ENGINE == 'truffleruby'` → `require "stackprof/truffleruby"`,
+    # and `truffleruby.rb` re-implements `StackProf.run` / `.results` as raising stubs — on MRI the C
+    # extension defines them. Scanning every `.rb` under `lib/` reads that stub file as an ordinary
+    # definition and proposes `StackProf.run -> bot` against a method whose real signature returns
+    # `Hash[Symbol, untyped]`.
+    #
+    # {.call} answers the guarded set from the resolved file list alone: it parses each file once,
+    # collects the literal `require` / `require_relative` sites, marks a site guarded when it sits
+    # inside a conditional whose predicate reads `RUBY_ENGINE`, `RUBY_PLATFORM` or `defined?(…)`,
+    # resolves each feature against the scanned set (`require_relative` against the file's own
+    # directory; `require` against the file's ancestor directories — the load-path approximation a
+    # gem's `lib/` root satisfies), and keeps the files whose EVERY incoming edge is guarded —
+    # directly, or through a file already known guarded (a helper `truffleruby.rb` requires
+    # unconditionally is still truffleruby-only). A file with no scanned require site is never
+    # guarded: an entry point, an autoload target or a `load`ed file cannot be told apart from a
+    # guarded one, and the unguarded reading is the one that emits.
+    #
+    # Limits, deliberately: require sites in files OUTSIDE the scanned set are invisible (a sibling
+    # the run did not read may require the file unguarded); `load`, `autoload` and computed features
+    # are not edges; a `require` sitting in the guard's own predicate — an `&&` / `||` operand, say —
+    # inherits the branch's guarded mark without the walk checking whether Ruby reaches it before the
+    # platform test decides; the `begin … rescue LoadError` fallback (`require "json"` else
+    # `require "json/pure"`) is not a platform guard, so both of its edges read unguarded; and a file
+    # that fails to parse poisons the whole answer — its require edges are unknowable, so {.call}
+    # returns an empty set rather than risk a false guarded verdict.
+    module PlatformGuardedFiles
+      # The constants a conditional predicate may read to make a require platform-dependent.
+      GUARD_CONSTANTS = %i[RUBY_ENGINE RUBY_PLATFORM].freeze
+      private_constant :GUARD_CONSTANTS
+
+      # The conditional forms whose whole subtree a platform predicate guards — `if` / `unless` in
+      # statement, modifier and ternary spelling, `case` and `case/in` on a guarded subject. Both
+      # branches count: `else` of `RUBY_ENGINE == 'x'` is `RUBY_ENGINE != 'x'`, still conditional.
+      CONDITIONALS = [Prism::IfNode, Prism::UnlessNode, Prism::CaseNode, Prism::CaseMatchNode].freeze
+      private_constant :CONDITIONALS
+
+      REQUIRE_CALLS = %i[require require_relative].freeze
+      private_constant :REQUIRE_CALLS
+
+      module_function
+
+      # @param paths — the `.rb` files the run will analyse, as spelled by the run.
+      # @param ruby_version — the Prism version to parse with (the configuration's `target_ruby`).
+      # @return a Set of `File.expand_path`'d paths that are required only under platform guards.
+      def call(paths, ruby_version: nil)
+        files = paths.map { |path| File.expand_path(path) }.uniq
+        known = files.to_set
+        edges = Hash.new { |hash, key| hash[key] = [] }
+        files.each do |file|
+          sites = require_sites(file, ruby_version, known)
+          return Set.new if sites.nil?
+
+          sites.each { |target, guarded| edges[target] << { from: file, guarded: guarded } }
+        end
+        guarded_closure(files, edges)
+      end
+
+      # Every `[target, guarded]` pair `file`'s literal require sites resolve to inside `known`;
+      # `nil` when the file does not parse (see the class comment for why that voids the answer).
+      def require_sites(file, ruby_version, known)
+        result = Prism.parse(File.read(file), filepath: file, version: ruby_version)
+        return nil if result.errors.any?
+
+        sites = []
+        walk_require_sites(result.value) do |node, guarded|
+          target = require_target(file, node, known)
+          sites << [target, guarded] if target
+        end
+        sites
+      end
+
+      # An explicit stack, not recursion: a require site deep in a generated file must not exhaust it.
+      def walk_require_sites(root, &block)
+        stack = [[root, false]]
+        until stack.empty?
+          node, guarded = stack.pop
+          next unless node.is_a?(Prism::Node)
+
+          block.call(node, guarded) if require_call?(node)
+          child_guarded = guarded || platform_conditional?(node)
+          node.rigor_each_child { |child| stack << [child, child_guarded] }
+        end
+      end
+
+      # A `require "feature"` / `require_relative "feature"` with one string literal and no receiver —
+      # the same strictness {Analysis::RequireRelativeClosure} reads `require_relative` with.
+      def require_call?(node)
+        return false unless node.is_a?(Prism::CallNode) && node.receiver.nil?
+        return false unless REQUIRE_CALLS.include?(node.name)
+
+        arguments = node.arguments&.arguments
+        arguments&.size == 1 && arguments.first.is_a?(Prism::StringNode)
+      end
+
+      # Whether `node` is a conditional whose predicate makes what it guards platform-dependent: a
+      # `RUBY_ENGINE` / `RUBY_PLATFORM` read or a `defined?(…)` anywhere in it.
+      def platform_conditional?(node)
+        return false unless CONDITIONALS.any? { |klass| node.is_a?(klass) }
+
+        predicate = node.predicate
+        !predicate.nil? && platform_expression?(predicate)
+      end
+
+      # Iterative like {#walk_require_sites}: a predicate can chain thousands of `||` operands. A hit is
+      # the only answer — a constant that is NOT a guard (`RUBY_VERSION`, `ENV`, a namespaced path) does
+      # not end the walk, or `RUBY_ENGINE == "x" && RUBY_VERSION >= "y"` would read unguarded on the
+      # strength of which operand the stack pops first.
+      def platform_expression?(root)
+        stack = [root]
+        until stack.empty?
+          node = stack.pop
+          next unless node.is_a?(Prism::Node)
+          return true if node.is_a?(Prism::DefinedNode)
+          return true if node.is_a?(Prism::ConstantReadNode) && GUARD_CONSTANTS.include?(node.name)
+          # `::RUBY_ENGINE` names the same constant; `Foo::RUBY_ENGINE` is a different one.
+          return true if node.is_a?(Prism::ConstantPathNode) && node.parent.nil? &&
+                         GUARD_CONSTANTS.include?(node.name)
+
+          node.rigor_each_child { |child| stack << child }
+        end
+        false
+      end
+
+      # The scanned file `node`'s feature resolves to, or nil when it names nothing the run reads
+      # (a gem, a `.so`, a computed path's sibling).
+      def require_target(site_file, node, known)
+        feature = node.arguments.arguments.first.unescaped
+        feature += ".rb" unless feature.end_with?(".rb")
+        if node.name == :require_relative
+          candidate = File.expand_path(feature, File.dirname(site_file))
+          return candidate if known.include?(candidate)
+
+          return nil
+        end
+
+        # `require` resolves through the load path; the file's own directory upward is the
+        # approximation that finds `lib/stackprof/truffleruby.rb` for `require "stackprof/truffleruby"`
+        # in `lib/stackprof.rb`, nearest ancestor first.
+        dir = File.dirname(site_file)
+        loop do
+          candidate = File.expand_path(feature, dir)
+          return candidate if known.include?(candidate)
+
+          parent = File.dirname(dir)
+          return nil if parent == dir
+
+          dir = parent
+        end
+      end
+
+      # The fixpoint: a file is guarded-only when it has at least one scanned require edge and every
+      # edge reaching it is either syntactically guarded or issued from a file already guarded-only.
+      def guarded_closure(files, edges)
+        guarded = Set.new
+        loop do
+          added = false
+          files.each do |file|
+            next if guarded.include?(file)
+
+            incoming = edges[file]
+            next if incoming.empty?
+            next unless incoming.all? { |edge| edge[:guarded] || guarded.include?(edge[:from]) }
+
+            guarded << file
+            added = true
+          end
+          break unless added
+        end
+        guarded
+      end
+    end
+  end
+end