rigortype 0.3.9 → 0.4.0

data/lib/rigor/inference/external_ancestor_resolution.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require_relative "../analysis/dependency_recorder"
+require_relative "../reflection"
+
+module Rigor
+  module Inference
+    # Issue #527 slice 0 — the single owner of one question: which RBS declaration answers
+    # `method_name` on `class_name` through an ancestor the PROJECT does not declare?
+    #
+    # A project class is usually absent from the RBS environment, so the declaration that decides the
+    # question is written about an ancestor the project does not declare — the `< StandardError`
+    # superclass, the `include Comparable` mixin, `< ::StringScanner`. `Scope#external_ancestor_name_candidates`
+    # gathers those as-written names breadth-first over the project ancestry; this module resolves each
+    # group against the RBS environment and reports WHICH declaration answered, not merely that one did.
+    #
+    # The logic existed twice before: `ExpressionTyper#rbs_ancestor_answers?` asked it as a boolean (the
+    # implicit-self binding veto of issue #633 / ADR-110), and the dispatch side of #527 needs the same
+    # walk but wants the definition and its owner so it can dispatch there. Two copies of an MRO cut-off
+    # rule is one copy too many, so the boolean is now `!resolve(...).nil?`.
+    #
+    # The one thing the consumers do NOT share is the ADR-46 cross-file edge, and that is
+    # `record_dependencies:`. The implicit-self veto genuinely READ the ancestor's declaration sites to
+    # decide a binding, so its walk records them. A dispatch lookup asking "does some ancestor happen to
+    # declare this?" did not, and filing an edge for it would mislabel the lookup as an ancestry edge —
+    # which is why `RbsDispatch.each_source_ancestor_candidate` read the raw discovery tables instead of
+    # this walk. The suppression is #992's {Analysis::DependencyRecorder.withhold} around the walk, NOT
+    # a flag threaded into `Scope`: an ADR-2 plugin-facing bypass of dependency recording would produce
+    # a silently stale warm cache that no diagnostic diff can show.
+    #
+    # There is deliberately NO memo here. The dispatch consumer this module is being extracted FOR does
+    # not exist yet, and a memo keyed on the tables this slice happens to name would be keyed on less
+    # than the walk reads — `Scope#resolve_ancestor_class_name` consults `discovered_def_nodes` and
+    # `discovered_methods` through `known_user_class?`, and `ancestor_name_candidates` reads
+    # `discovered_header_nestings`. The slice that brings the hot path brings the memo, keyed on what
+    # that consumer actually reads.
+    module ExternalAncestorResolution
+      # The owner a name must PRECEDE for its declaration to win an MRO. See {declared_before_object?}.
+      OBJECT_OWNER = "Object"
+      private_constant :OBJECT_OWNER
+
+      module_function
+
+      # Resolves `method_name` on `class_name` against the RBS environment, through the project's
+      # ancestry where `class_name` itself is absent from RBS.
+      #
+      # Returns `[definition, owner_name]` — the `RBS::Definition::Method` and the name of the class the
+      # walk asked it of (NOT `definition.defined_in`, which may be further up that class's own RBS
+      # ancestry) — or `nil` when no ancestor answers.
+      #
+      # The cut-off is `::Object`, not the own class: a top-level `def` IS a private `Object` instance
+      # method, the last link of every MRO, so any declared owner that comes before `::Object` wins at
+      # runtime (`Exception#message`, `Array#first`, `Comparable#clamp`) while a name owned by `Object`
+      # or `Kernel` themselves sits at or after that rung and contributes no evidence (#316 / #319).
+      #
+      # `kind` is `:instance` today. The singleton side of the walk (a module's `def self.` reached
+      # through a discovered `include`, #527 slice 6) is not implemented, and declines rather than
+      # guessing — which is what the engine answers there now.
+      #
+      # `record_dependencies: false` runs the ancestry walk under {Analysis::DependencyRecorder.withhold}
+      # so its reads reach no consumer. Only the WALK is withheld: the `Reflection` lookups around it
+      # read the RBS environment, which files no cross-file edge, so this suppresses exactly the intended
+      # one. `withhold` is a `[yield, nil]` fast path when nothing is recording, which is every ordinary
+      # run.
+      #
+      # `mixins: false` narrows the walk to the SUPERCLASS chain. #527 slice 1 lands `< Hash` before
+      # `include Enumerable` so that slice 2's measurement stays its own, and the narrowing belongs to
+      # the CALLER rather than to this module: the implicit-self veto must keep walking both edges,
+      # because Ruby reaches an included module's methods too.
+      # rubocop:disable-next Metrics/ParameterLists
+      def resolve(class_name, method_name, kind = :instance, scope:, environment: nil, name_memo: nil,
+                  record_dependencies: true, mixins: true)
+        return nil if class_name.nil? || scope.nil?
+        return nil unless kind == :instance
+
+        compute(class_name, method_name, scope, environment, name_memo, record_dependencies, mixins)
+      end
+
+      # The RBS method definition for `class_name`, or nil for a class the environment does not know, a
+      # name it does not declare, or a signature it cannot build. The single owner of the `rescue` —
+      # a malformed third-party signature is a gap, never an exception escaping into inference.
+      def method_definition(class_name, method_name, kind, scope: nil, environment: nil)
+        if kind == :singleton
+          Rigor::Reflection.singleton_method_definition(class_name, method_name, scope: scope,
+                                                                                 environment: environment)
+        else
+          Rigor::Reflection.instance_method_definition(class_name, method_name, scope: scope,
+                                                                                environment: environment)
+        end
+      rescue StandardError
+        nil
+      end
+
+      # True when the RBS declaration found for the name sits on `class_name` itself rather than on an
+      # ancestor; mirrors `CheckRules#defined_on?` and `SigGen::Generator#declared_on_class_itself?`.
+      def declared_on_class?(definition, class_name)
+        return false if definition.nil?
+        return false unless definition.respond_to?(:defined_in)
+
+        defined_in = definition.defined_in
+        return false if defined_in.nil?
+
+        defined_in.to_s.delete_prefix("::") == class_name.to_s.delete_prefix("::")
+      end
+
+      # Issue #633 — true when the declaration's owner sits strictly before `::Object` in `class_name`'s
+      # instance MRO, i.e. Ruby dispatches to it ahead of a top-level `def` (which is `Object`'s own
+      # private instance method). The own class trivially qualifies. An owner absent from the ancestor
+      # list, an unbuildable class, and an ancestry that does not reach `Object` (a `BasicObject`
+      # descendant) all answer false, leaving the historical top-level binding untouched.
+      def declared_before_object?(definition, class_name, scope: nil, environment: nil)
+        return true if declared_on_class?(definition, class_name)
+        return false if definition.nil? || !definition.respond_to?(:defined_in)
+
+        owner = definition.defined_in
+        return false if owner.nil?
+
+        ancestors = instance_ancestor_names(class_name, scope: scope, environment: environment)
+        object_index = ancestors.index(OBJECT_OWNER)
+        owner_index = ancestors.index(owner.to_s.delete_prefix("::"))
+        !object_index.nil? && !owner_index.nil? && owner_index < object_index
+      end
+
+      # The class's instance-side ancestors in MRO order, `::`-stripped, or `[]` for a class the RBS
+      # environment does not know or cannot build. Read through the loader's accessor rather than
+      # `instance_definition(...).ancestors` because that is the one wired to the ancestor-name cache and
+      # marked as RIGOR'S OWN demand — ordering two ancestors is not the analysis asking whether either
+      # one's methods resolve, and the `rbs.coverage` bookkeeping must not record it as such.
+      def instance_ancestor_names(class_name, scope: nil, environment: nil)
+        loader = rbs_loader_for(scope, environment)
+        loader ? loader.ancestor_names_for(class_name.to_s) : []
+      rescue StandardError
+        []
+      end
+
+      def compute(class_name, method_name, scope, environment, name_memo, record_dependencies, mixins)
+        kind = :instance
+        own = method_definition(class_name, method_name, kind, scope: scope, environment: environment)
+        if own
+          own_ancestors = instance_ancestor_names(class_name, scope: scope, environment: environment)
+          if declared_before_object?(own, class_name, scope: scope, environment: environment) ||
+             owned_within_candidate_chain?(own, own_ancestors)
+            return [own, class_name.to_s].freeze
+          end
+        end
+
+        groups = ancestor_candidate_groups(scope, class_name, name_memo, record_dependencies, mixins)
+        farther_ancestors = {}
+        groups.each_with_index do |candidates, index|
+          answer = first_known_candidate_answer(candidates, method_name, kind, scope, environment)
+          next if answer.nil?
+          next if resited_member?(answer, groups, index, farther_ancestors, scope, environment)
+
+          return answer
+        end
+        nil
+      end
+      private_class_method :compute
+
+      # The first candidate spelling the RBS environment knows is the ancestor Ruby resolves; a name it
+      # knows nothing about contributes no evidence either way, and a known one that does NOT answer
+      # ends this group rather than falling through to a less-qualified spelling of the same name.
+      def first_known_candidate_answer(candidates, method_name, kind, scope, environment)
+        candidates.each do |candidate|
+          ancestors = instance_ancestor_names(candidate, scope: scope, environment: environment)
+          next if ancestors.empty?
+
+          definition = method_definition(candidate, method_name, kind, scope: scope,
+                                                                       environment: environment)
+          return nil unless declared_before_object?(definition, candidate,
+                                                    scope: scope, environment: environment) ||
+                            owned_within_candidate_chain?(definition, ancestors)
+
+          return [definition, candidate].freeze
+        end
+        nil
+      end
+      private_class_method :first_known_candidate_answer
+
+      # The module-candidate half of the answering test (#1173 review). A module's RBS ancestry is
+      # `[itself, its own includes…]` and never reaches `Object`, so {declared_before_object?} — whose
+      # cut-off exists to keep an Object- / Kernel-owned declaration from outranking a top-level `def`
+      # — always answers false for it: the cut-off has nothing to cut. What decides instead is that
+      # the declaration came from the candidate's OWN chain: when the candidate sits in the receiver's
+      # MRO, Ruby dispatches the name through exactly those ancestors, so a `defined_in` anywhere in
+      # the list is the method that runs. Without this, a nearer RBS module that inherits the name
+      # from its own RBS `include` read as a dead group and a FARTHER ancestor's declaration was
+      # adopted in its place — `class C; include A; include B` where `B`'s RBS includes `N` answering
+      # A's declaration rather than N's. The gate keeps the Object cut-off's reach: a chain that DOES
+      # contain `Object` (every ordinary class candidate) is untouched.
+      def owned_within_candidate_chain?(definition, ancestors)
+        return false if ancestors.include?(OBJECT_OWNER)
+        return false if definition.nil? || !definition.respond_to?(:defined_in)
+
+        owner = definition.defined_in
+        !owner.nil? && ancestors.include?(owner.to_s.delete_prefix("::"))
+      end
+      private_class_method :owned_within_candidate_chain?
+
+      # The re-siting guard (#1173 review, second pass). Ruby's `include` is a no-op for a module
+      # already in the ancestry, so a member's real position is set by the EARLIEST source statement
+      # that pulled it in — which is the FARTHEST group in this search-order walk that carries it.
+      # Adopting group `index`'s answer claims the owner (and the declaration's `defined_in`) sit
+      # inside this group's segment; when either name also appears in a farther group's RBS chain,
+      # the runtime actually sites it there and everything between can shadow it —
+      # `class C < Array; include M` where `M`'s RBS includes `Enumerable` must not adopt
+      # `Enumerable#first` through `M` while `Array#first` intervenes. Skipping the answer is not a
+      # decline of the method: the farther group that truly carries the member resolves it at its
+      # real position (or nothing does, and the honest `Dynamic[top]` stands).
+      #
+      # `farther_ancestors` memoizes each farther group's resolved ancestor list — the first
+      # candidate spelling the RBS environment knows, the same spelling rule
+      # {first_known_candidate_answer} applies. A group whose names all stay project- or
+      # unresolved-side has no visible chain to compare. The deferral can trade precision for
+      # safety: when the farther carrier resolves the member without type-argument bindings the
+      # answer degrades to `Dynamic[top]` where the skipped group carried one — the intended
+      # direction, and in the pinned shapes the runtime-correct answer anyway.
+      def resited_member?(answer, groups, index, farther_ancestors, scope, environment)
+        definition, owner = answer
+        members = [owner.to_s.delete_prefix("::")]
+        defined_in = definition.defined_in if definition.respond_to?(:defined_in)
+        members << defined_in.to_s.delete_prefix("::") if defined_in
+
+        ((index + 1)...groups.size).any? do |j|
+          ancestors = farther_ancestors.fetch(j) do
+            farther_ancestors[j] = resolved_group_ancestors(groups[j], scope, environment)
+          end
+          ancestors&.any? { |name| members.include?(name) }
+        end
+      end
+      private_class_method :resited_member?
+
+      # The ancestor list of the first candidate spelling the RBS environment knows — nil when no
+      # spelling resolves, which is what the walk emitted the group for in the first place.
+      def resolved_group_ancestors(candidates, scope, environment)
+        candidates.each do |candidate|
+          ancestors = instance_ancestor_names(candidate, scope: scope, environment: environment)
+          return ancestors unless ancestors.empty?
+        end
+        nil
+      end
+      private_class_method :resolved_group_ancestors
+
+      # The walk, with its ADR-46 reads attached or detached. `withhold` returns `[result, read_set]`
+      # and the read set is dropped: a caller that suppresses is saying these reads are not a dependency
+      # of its answer, not that they should be replayed somewhere else.
+      def ancestor_candidate_groups(scope, class_name, name_memo, record_dependencies, mixins)
+        memo = name_memo || {}
+        if record_dependencies
+          return scope.external_ancestor_name_candidates(class_name, name_memo: memo, mixins: mixins)
+        end
+
+        Analysis::DependencyRecorder.withhold do
+          scope.external_ancestor_name_candidates(class_name, name_memo: memo, mixins: mixins)
+        end.first
+      end
+      private_class_method :ancestor_candidate_groups
+
+      def rbs_loader_for(scope, environment)
+        (environment || scope&.environment)&.rbs_loader
+      rescue StandardError
+        nil
+      end
+      private_class_method :rbs_loader_for
+    end
+  end
+end

data/lib/rigor/inference/fresh_frame_blocks.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../source/node_children"
+require_relative "../type"
+require_relative "stored_block_call"
+
+module Rigor
+  module Inference
+    # Issue #1361 — the blocks whose body does not read the narrowing of the frame-local special variables (the regex
+    # match globals, and `$_` since issue #1359) where it is written ({.fresh_entry?}, {.entry}):
+    #
+    # - a root block: the block of `Thread.new` / `Thread.start` / `Thread.fork`, `Fiber.new` or `Ractor.new` on the
+    #   core class ({.root_call?}). It runs as the root of a new thread, fiber or ractor, and Ruby keeps that
+    #   execution context's own special-variable slot (`ec->root_svar`) for every piece of code whose local frame is
+    #   the block's, the block and each block nested in it included. So the block reads `$1` nil whatever the
+    #   creator matched, and a match it runs never rebinds the creator's `$~`. A `&expr` block argument's
+    #   expression still runs in the creator's frame, before the thread starts;
+    # - a definer block: the block of `define_method` / `define_singleton_method`, on any receiver. It runs as a
+    #   method body whenever the method is called, and reads the defining frame's slot as it is at that time, which
+    #   each call's own matches write too, so the narrowing where the method is defined neither proves nor refutes
+    #   what it reads. Unlike a root block it shares that slot, so a match in it still rebinds the definer's `$~`.
+    #
+    # `Enumerator.new` is neither: its block runs on an internal fiber whose root is not the block, so it reads and
+    # rebinds the creator's slot like any other block.
+    #
+    # The receiver of a root call must be the literal constant, and must resolve to the core class where a scope is
+    # at hand, so a project's own `Thread` (`module Pool; class Thread; …`) keeps the ordinary block rules.
+    module FreshFrameBlocks
+      ROOT_CONSTRUCTORS = {
+        Thread: %i[new start fork].freeze, Fiber: %i[new].freeze, Ractor: %i[new].freeze
+      }.freeze
+      DEFINERS = Set[:define_method, :define_singleton_method].freeze
+      private_constant :ROOT_CONSTRUCTORS, :DEFINERS
+
+      module_function
+
+      # True when `node` is a call whose block (a literal or a `&expr` argument) runs as the root of a new thread,
+      # fiber or ractor. `scope` resolves the receiver; without one the literal constant is taken at its word.
+      def root_call?(node, scope = nil)
+        return false unless node.is_a?(Prism::CallNode) && !node.block.nil?
+
+        constant = StoredBlockCall.root_constant_name(node.receiver)
+        return false unless ROOT_CONSTRUCTORS[constant]&.include?(node.name)
+
+        scope.nil? || core_class?(node.receiver, constant, scope)
+      end
+
+      # The block of `node` when {.root_call?} holds, else nil.
+      def root_block(node, scope = nil)
+        root_call?(node, scope) ? node.block : nil
+      end
+
+      # True when the block answers true for a child of `node` that runs in the frame `node` runs in: any child but
+      # a root block ({.root_block}), which runs with a slot of its own. Every {MatchRebinding} reading of what
+      # running code may match walks through here. A root `&expr` block argument's own children are asked in its
+      # place, since Ruby evaluates `expr` in this frame before the thread starts
+      # (`Thread.new(&HANDLERS.fetch(name.sub(re, "")))` rebinds the creator's `$~`). `into_root` asks a root block's
+      # children too, for a reading of what the code makes rather than what it runs: a closure made in a root block
+      # may be handed back to this frame's thread. Stops at the first true answer, without a `return` out of the
+      # walk's block.
+      def any_frame_child?(node, scope, into_root: false)
+        root = root_block(node, scope)
+        found = false
+        node.rigor_each_child do |child|
+          if !child.equal?(root)
+            found ||= yield(child)
+          elsif into_root || child.is_a?(Prism::BlockArgumentNode)
+            child.rigor_each_child { |inner| found ||= yield(inner) }
+          end
+        end
+        found
+      end
+
+      # True when the block of `call_node` does not read the narrowing where it is written: a root block, or a
+      # definer block. {.entry} gives the scope it enters with.
+      def fresh_entry?(call_node, scope = nil)
+        return false unless call_node.is_a?(Prism::CallNode)
+
+        DEFINERS.include?(call_node.name) || root_call?(call_node, scope)
+      end
+
+      # The scope the block of `call_node`, which {.fresh_entry?} names, enters with. A root block reads a slot of its
+      # own, so the match globals are unbound there, and `k = $1; k.upcase` in an entered `Thread.new { … }` block is
+      # a true positive. A definer body reads the definer's slot whenever the method is called, which the analyzer
+      # does not follow, so a global narrowed where it is written reads `Dynamic[top]` there, neither narrowed nor
+      # flagged: the dynamic-finder idiom defines `find_by_email` in a `method_missing` guard whose `$1` its body
+      # reads. This is the one place the specials are reset at such an entry: the match globals, `$_` (#1359), and
+      # `$!`, `$@` and `$?` (#1360).
+      #
+      # A root block runs in an execution context of its own, so it reads `$!` and `$@` as `nil` even where it is
+      # written in a rescue clause ({ErrorInfo}). `$?` is the thread's, so a thread's or a ractor's root block starts
+      # without one, while a fiber shares the thread's. A definer body reads all three as they are when the method is
+      # called.
+      def entry(scope, call_node)
+        if DEFINERS.include?(call_node.name)
+          scope.untyped_match_globals.untyped_last_line.untyped_error_info.untyped_last_status
+        else
+          fresh = scope.forget_match_globals.forget_last_line.forget_error_info
+          StoredBlockCall.root_constant_name(call_node.receiver) == :Fiber ? fresh : fresh.forget_last_status
+        end
+      end
+
+      # Issue #1360 — the scope a closure's body enters with: a lambda literal's (`block_node` a `Prism::LambdaNode`),
+      # or the block of a call that keeps it to run later ({StoredBlockCall.stores_block?}: `lambda`, `proc`,
+      # `Proc.new`, `Enumerator.new`, `Hash.new`). The body runs whenever the closure is called, which is usually after
+      # the rescue clause it is written in has exited (`f = -> { $! }` in a clause reads `nil` once called past the
+      # `begin`), and may be on another thread (`Thread.new(&f)`), so `$!`, `$@` and `$?` are unbound there. A root or
+      # definer block enters as {.entry} gives; every other block reads them where it is written.
+      def closure_entry(scope, block_node, call_node)
+        return scope unless block_node.is_a?(Prism::LambdaNode) ||
+                            (call_node.is_a?(Prism::CallNode) && StoredBlockCall.stores_block?(call_node))
+
+        scope.forget_error_info.forget_last_status
+      end
+
+      def core_class?(receiver, constant, scope)
+        type = scope.type_of(receiver)
+        type.is_a?(Type::Singleton) && type.class_name == constant.name
+      rescue StandardError
+        false
+      end
+      private_class_method :core_class?
+    end
+  end
+end

data/lib/rigor/inference/global_write_census.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../source/constant_path"
+require_relative "../source/node_children"
+
+module Rigor
+  module Inference
+    # Issue #1367 — the program facts the `global.*` write rules read, gathered syntactically over every file:
+    #
+    # - `[:alias, name]` — a global variable name an `alias $new $old` statement names, on either side. After it,
+    #   `$new` is `$old`'s variable, setter included, so both rules exempt the name.
+    # - `[:defines, name]` — a method named after one of {ANSWER_NAMES} is defined somewhere, in any spelling and on
+    #   any receiver: `def`, `def obj.m`, a `class << obj` body, `define_method`, `define_singleton_method`,
+    #   `alias`, `alias_method`, `attr_*`, a delegation macro, or the same call through `send`. The
+    #   type check does not ask where it lands: an object can reach any of them (`class << nil`, `K = Integer;
+    #   class K`, `[Integer].each { |k| k.define_method(:write) }`), so a literal of any class declines.
+    # - {DEFINES_ANY} — a definition whose name no literal spells: a computed `define_method` name, a `send` whose
+    #   method name is computed, a string `eval` / `class_eval` whose code is interpolated or not a literal, a name
+    #   literal whose bytes are not valid in its encoding, or a top-level mixin of a non-constant. A node the
+    #   collector fails to read records it too ({Collector#visit}).
+    # - `[:refines, name]` / {REFINES_ANY} — the same, inside a `refine` block. A refinement changes what
+    #   `respond_to?(:write)` answers where a `using` is in effect, and nothing else the setters consult: an
+    #   implicit conversion and a refined `respond_to?` / `respond_to_missing?` ignore it, so these entries are
+    #   kept apart from `[:defines, …]`.
+    # - `[:main_mixin, name]` — a module a top-level `include`, `prepend` or `extend` mixes into `Object` (or
+    #   `main`), as written. A module RBS does not know may carry any method, so it reaches every class.
+    #
+    # The census is a `Set` of those frozen entries, merged by union across files, the project pre-pass and the
+    # `pre_eval:` files. It is recorded inside descents that already visit every node ({Collector#visit}), never
+    # by a walk of its own, except for a `pre_eval:` file ({.scan}).
+    module GlobalWriteCensus
+      # The methods whose presence lets an object answer a setter: the one it asks `respond_to?` about (`write`),
+      # the implicit conversions (`to_str`, `to_int`), and the escape hatches both consult.
+      ANSWER_NAMES = %i[write to_str to_int method_missing respond_to_missing? respond_to?].to_set.freeze
+
+      DEFINES_ANY = [:defines_any].freeze
+      REFINES_ANY = [:refines_any].freeze
+
+      # `define_method`-family calls whose first argument names the method they define.
+      NAMING_CALLS = %i[define_method define_singleton_method alias_method].to_set.freeze
+      # Calls every literal argument of which may name a method they define.
+      ATTRIBUTE_CALLS = %i[attr attr_reader attr_writer attr_accessor].to_set.freeze
+      DELEGATION_CALLS = %i[
+        def_delegator def_delegators def_instance_delegator def_instance_delegators def_single_delegator
+        def_single_delegators delegate instance_delegate single_delegate
+      ].to_set.freeze
+      # `delegate_missing_to` defines `method_missing` and `respond_to_missing?` whatever it is handed.
+      MISSING_DELEGATION_CALLS = %i[delegate_missing_to].to_set.freeze
+      SEND_CALLS = %i[send __send__ public_send].to_set.freeze
+      EVAL_CALLS = %i[eval class_eval module_eval instance_eval].to_set.freeze
+      MIXIN_CALLS = %i[include prepend extend].to_set.freeze
+      DEFINING_CALLS =
+        (NAMING_CALLS | ATTRIBUTE_CALLS | DELEGATION_CALLS | MISSING_DELEGATION_CALLS | EVAL_CALLS).freeze
+      # Every call name {Collector#visit} reads; any other call is skipped at once.
+      VISITED_CALLS = (DEFINING_CALLS | SEND_CALLS | MIXIN_CALLS | %i[import_methods]).freeze
+      NO_ARGUMENTS = [].freeze
+      NAME_PATTERN = /(?<![\w@$])(?:write|to_str|to_int|method_missing|respond_to_missing\?|respond_to\?)(?![\w?!=])/
+      private_constant :NAMING_CALLS, :ATTRIBUTE_CALLS, :DELEGATION_CALLS, :MISSING_DELEGATION_CALLS,
+                       :SEND_CALLS, :EVAL_CALLS, :MIXIN_CALLS, :DEFINING_CALLS, :VISITED_CALLS, :NO_ARGUMENTS,
+                       :NAME_PATTERN
+
+      EMPTY = Set.new.freeze
+
+      module_function
+
+      def alias_entry(name) = [:alias, name].freeze
+
+      def aliased?(census, name) = census.include?([:alias, name])
+
+      # Whether the program may define one of `names` somewhere, outside a refinement.
+      def defines_any_of?(census, names)
+        census.include?(DEFINES_ANY) || names.any? { |name| census.include?([:defines, name]) }
+      end
+
+      # Whether some refinement may add `write`.
+      def refines_write?(census) = census.include?(REFINES_ANY) || census.include?(%i[refines write])
+
+      # The module names the top-level mixins spell.
+      def main_mixins(census) = census.filter_map { |entry| entry[1] if entry[0] == :main_mixin }
+
+      # A standalone walk, for a file no existing descent visits (a `pre_eval:` entry).
+      def scan(root)
+        collector = Collector.new
+        walk(root, collector, true)
+        collector.census.freeze
+      end
+
+      def walk(node, collector, top_level)
+        return unless node.is_a?(Prism::Node)
+
+        collector.visit(node, top_level: top_level)
+        inner = top_level && !(node.is_a?(Prism::ClassNode) || node.is_a?(Prism::ModuleNode))
+        node.rigor_each_child { |child| walk(child, collector, inner) }
+      end
+      private_class_method :walk
+
+      # Accumulates one file's census, fed each node of a pre-order descent. `top_level` says whether the node sits
+      # outside every `class` / `module` body; it is the host walk's to track. `refine` blocks are remembered by
+      # offset as they are met, so a node inside one is known without the host walk tracking it.
+      class Collector
+        attr_reader :census
+
+        def initialize
+          @census = Set.new
+          @refine_ranges = []
+        end
+
+        # A node the collector cannot read must not fail the analysis of its file, nor of every file the pre-pass
+        # feeds: the census then counts it as a definition of every name, which only declines a report.
+        def visit(node, top_level:)
+          case node
+          when Prism::AliasGlobalVariableNode then visit_global_alias(node)
+          when Prism::DefNode then record(node, node.name)
+          when Prism::AliasMethodNode then record_argument(node, node.new_name)
+          when Prism::CallNode then visit_call(node, top_level)
+          end
+        rescue StandardError
+          @census << DEFINES_ANY
+        end
+
+        private
+
+        def visit_global_alias(node)
+          [node.new_name, node.old_name].each do |side|
+            @census << GlobalWriteCensus.alias_entry(side.name) if side.is_a?(Prism::GlobalVariableReadNode)
+          end
+        end
+
+        def visit_call(node, top_level)
+          remember_refine(node)
+          name = node.name
+          return unless VISITED_CALLS.include?(name)
+
+          arguments = node.arguments&.arguments || NO_ARGUMENTS
+          if SEND_CALLS.include?(name)
+            return if arguments.empty?
+
+            # A method name no literal spells (computed, or with bytes invalid in its encoding) may be any of them. A
+            # literal one is read as that call written directly: `send(:include, M)` at the top level is a mixin, and
+            # `send(:size)` defines nothing.
+            first = literal_name(arguments.first)
+            return @census << any_entry(node) if first.nil?
+
+            name = first
+            arguments = arguments.drop(1)
+          end
+          visit_defining_call(node, name, arguments)
+          visit_main_mixin(node, arguments) if top_level && MIXIN_CALLS.include?(name) && self_receiver?(node)
+        end
+
+        def visit_defining_call(node, name, arguments)
+          if NAMING_CALLS.include?(name)
+            record_argument(node, arguments.first)
+          elsif ATTRIBUTE_CALLS.include?(name) || DELEGATION_CALLS.include?(name)
+            arguments.each { |argument| record_every_literal(node, argument) }
+          elsif MISSING_DELEGATION_CALLS.include?(name)
+            record(node, :method_missing)
+            record(node, :respond_to_missing?)
+          elsif EVAL_CALLS.include?(name)
+            # Only the first argument is code; the rest are a binding, a file name and a line number.
+            record_eval_text(node, arguments.first) unless arguments.empty?
+          elsif name == :import_methods && inside_refine?(node)
+            @census << REFINES_ANY
+          end
+        end
+
+        # A top-level `include M` / `prepend M` / `extend M` mixes M into `Object` (or `main`).
+        def visit_main_mixin(node, arguments)
+          arguments.each do |argument|
+            constant = Source::ConstantPath.qualified_name(argument) if constant_node?(argument)
+            @census << (constant ? [:main_mixin, constant.delete_prefix("::").freeze].freeze : any_entry(node))
+          end
+        end
+
+        def record(node, name)
+          return unless ANSWER_NAMES.include?(name)
+
+          @census << [inside_refine?(node) ? :refines : :defines, name].freeze
+        end
+
+        # A literal method name, or any name when the argument spells none.
+        def record_argument(node, argument)
+          name = literal_name(argument)
+          name ? record(node, name) : @census << any_entry(node)
+        end
+
+        def record_every_literal(node, argument)
+          case argument
+          when Prism::SymbolNode, Prism::StringNode then record_argument(node, argument)
+          when Prism::ArrayNode then argument.elements.each { |element| record_every_literal(node, element) }
+          when Prism::KeywordHashNode, Prism::HashNode
+            argument.elements.each { |pair| record_every_literal(node, pair) }
+          when Prism::AssocNode
+            record_every_literal(node, argument.key)
+            record_every_literal(node, argument.value)
+          else @census << any_entry(node)
+          end
+        end
+
+        def record_eval_text(node, argument)
+          if argument.is_a?(Prism::StringNode) && argument.unescaped.valid_encoding?
+            argument.unescaped.scan(NAME_PATTERN) { |name| record(node, name.to_sym) }
+          else
+            @census << any_entry(node)
+          end
+        end
+
+        def any_entry(node) = inside_refine?(node) ? REFINES_ANY : DEFINES_ANY
+
+        # The name a Symbol or String literal spells, or nil for any other node and for a literal whose bytes are
+        # not valid in its encoding, which names no method Ruby can define.
+        def literal_name(argument)
+          return unless argument.is_a?(Prism::SymbolNode) || argument.is_a?(Prism::StringNode)
+
+          text = argument.unescaped
+          text.to_sym if text.valid_encoding?
+        end
+
+        def constant_node?(node) = node.is_a?(Prism::ConstantReadNode) || node.is_a?(Prism::ConstantPathNode)
+
+        def self_receiver?(node) = node.receiver.nil? || node.receiver.is_a?(Prism::SelfNode)
+
+        def remember_refine(node)
+          return unless node.name == :refine && self_receiver?(node) && node.block.is_a?(Prism::BlockNode)
+
+          location = node.block.location
+          @refine_ranges << (location.start_offset...location.end_offset)
+        end
+
+        def inside_refine?(node)
+          offset = node.location.start_offset
+          @refine_ranges.any? { |range| range.cover?(offset) }
+        end
+      end
+    end
+  end
+end