rigortype 0.4.1 → 0.4.2

data/lib/rigor/inference/in_effect_refinements.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../source/constant_path"
+require_relative "../source/node_children"
+require_relative "refine_census"
+require_relative "refine_self"
+require_relative "in_effect_refinements/proc_literals"
+require_relative "in_effect_refinements/scope_reads"
+require_relative "in_effect_refinements/refine_defs"
+require_relative "in_effect_refinements/walk"
+
+module Rigor
+  module Inference
+    # ADR-121 WD1 (issue #1673) — the in-effect refinements of one file: at each program point, the ORDERED list of
+    # refining modules whose refinements Ruby applies there (`CONTEXT.md` § in-effect refinements). A later entry
+    # wins over an earlier one. The check rules ({Analysis::CheckRules::LexicalMethodSites}) and the typer
+    # ({Scope#in_effect_refinements}) both read the one `Inference::ScopeIndexer` stamps for the file, so a call
+    # cannot be silenced as refined and typed as unrefined.
+    #
+    # The list is built from activations, each in effect over a span of the file and placed by its activation
+    # offset:
+    #
+    # - **Lexical `using M`**, from the end of the call to the end of the body that holds it: the file's top level
+    #   or a `class` / `module` / `class << …` body, including everything nested in it. An outer body's `using`s
+    #   precede an inner body's, and a body's own `using`s keep their textual order. A `using` inside a `def`
+    #   raises in Ruby and activates nothing. `M` is resolved lexically: each name its spelling can denote sits at
+    #   the `using`'s position, innermost LAST, so where several are declared the one Ruby's lookup finds wins.
+    #   The caller's expansion block puts `M`'s included modules ahead of `M` and its prepended modules after it
+    #   (issue #1671), as CRuby activates them.
+    # - **A `refine X do … end` block**, over the block: its own refining module, after the enclosing `using`s.
+    #   The module is named where the block's `self` is: the innermost `module` / `class` body, the constant a
+    #   `M = Module.new do … end` write names, or a module's own singleton method (`def self.x`, a `def` in its
+    #   `class << self`, issue #1749), where `self` is the module once the method is called. Anywhere else (another
+    #   block, an instance `def`, `class << …`, the top level) the module is not named, and the block contributes
+    #   {UNKNOWN}. Where the `refine`'s `self` is known to be a class — directly in a `class` or `class << …` body,
+    #   or in the block of a `Class.new` / `Struct.new` / `Data.define` call — it is not `Module#refine` (`Class`
+    #   undefines it), so it activates nothing and its block is an ordinary one (issue #1689; {#class_body_refine?}).
+    # - **A `using` whose argument is not a constant** (`using Module.new { … }`) names no module. It contributes
+    #   {UNKNOWN} throughout its file, which is broader than Ruby's scoping and the declining direction.
+    # - **Block sources** (ADR-121 WD1's third and fourth). A Proc literal that is directly the receiver of
+    #   `Proc#refined` (#1666) — a lambda literal, or the literal block of a bare `proc` / `lambda` call or of
+    #   `Proc.new` — puts each `.refined` argument in effect over the literal's body, after the literal's lexical
+    #   list and in call order along a `.refined(A).refined(B)` chain (CRuby duplicates the block's cref and appends).
+    #   Nested blocks and literals inherit it, being inside the span. An argument that is not a constant names no
+    #   module and contributes {UNKNOWN} over that literal's body only. A plugin-declared refined block (#1667) is
+    #   typing-time knowledge, so its declared modules arrive as the `declared` argument of {#at} and {#for_node} and
+    #   are appended after the block site's lexical list. Both expand through includes as a `using` does.
+    #
+    # Activating a module that is already listed changes nothing: it keeps its first position
+    # (`rb_using_refinement` returns early, CRuby `eval.c`; `using A; using B; using A` answers B's method).
+    #
+    # Built lazily: the walk runs the first time a consumer asks, so a file nobody asks about pays one small object.
+    class InEffectRefinements
+      # The marker an activation contributes when it may put any refinement in effect: a non-constant `using`, a
+      # `using` whose include expansion is unknown, or a `refine` block whose module this walk cannot name. A list
+      # that carries it answers "any refinement may be in effect"; its position carries no meaning.
+      UNKNOWN = :unknown_refinement
+      EMPTY = [].freeze
+      # ADR-121 WD7 (A1) — what a caller's expansion block answers for a name nothing declares: such a candidate of a
+      # `using`'s spelling is not the module Ruby's lookup finds, so it leaves the list. Never itself a list entry.
+      UNDECLARED = :undeclared_module
+
+      # One activation: in effect over `[start, stop)`, ordered by `order`. `names` is the module names (several
+      # when a lexical spelling can denote several), or nil for {UNKNOWN}; `expand` says whether the caller's
+      # include expansion applies (a `using`'s, not a `refine` block's own module).
+      Activation = Data.define(:order, :start, :stop, :names, :expand, :refine_block) do
+        def covers?(offset) = offset >= start && offset < stop
+      end
+      private_constant :Activation
+
+      extend ScopeReads
+      include Walk
+
+      def initialize(root)
+        @root = root
+        @built = false
+      end
+
+      # The in-effect refinements at `offset` of this file, ordered so a later activation comes later, each module
+      # once at its first position, then `declared` (a block source's modules) on the same terms. The block, when
+      # given, answers the modules `using name` puts in effect, in CRuby's activation order, or nil when it cannot
+      # tell, which contributes {UNKNOWN}; without it a `using` contributes its own name.
+      # The caller vouches that `offset` is in this file; {#for_node} checks.
+      def at(offset, declared = EMPTY, &expand)
+        build
+        return EMPTY if @activations.empty? && declared.empty?
+
+        list = []
+        @activations.each do |activation|
+          append_activation(list, activation, expand) if activation.covers?(offset)
+        end
+        declared.each { |name| append_expanded(list, name, expand) }
+        list.empty? ? EMPTY : list.freeze
+      end
+
+      # {#at} for a node, or only `declared` when `node` is not this file's: a callee body another file wrote,
+      # typed under this file's scope, finds no lexical refinement here. Its own file's are not consulted.
+      def for_node(node, declared = EMPTY, &)
+        return at(EMPTY_OFFSET, declared, &) unless member?(node)
+
+        at(node.location.start_offset, declared, &)
+      end
+
+      # Issue #1120 — is a refinement from one of `modules` (refining-module names) in effect at `offset`, with
+      # `declared` (a plugin-declared refined block's modules, issue #1667) appended as {#at} appends them? The
+      # silencing answer is broader than the list in two places, both the declining direction: a {UNKNOWN} entry
+      # counts as every module, and inside a `refine` block every module counts, not only the block's own.
+      def refinement_active?(offset, modules, declared = EMPTY, &)
+        build
+        return true if @unresolved_using
+        return true if @activations.any? { |activation| activation.refine_block && activation.covers?(offset) }
+
+        at(offset, declared, &).any? { |name| name == UNKNOWN || modules.include?(name) }
+      end
+
+      # Does the file activate no refinement anywhere? A consumer asks first, so a file without one pays no list.
+      def empty?
+        build
+        @activations.empty?
+      end
+
+      # Issue #1664 — the `Prism::DefNode` a `refine class_name do … end` body in this file defines `method_name` with,
+      # for the refining module `module_name`, or nil. The last such `def` wins, as Ruby's method table keeps it. The
+      # refined class is matched by any name its spelling can denote, as the refinement table records it. A name whose
+      # last definer has no body answers `RefineDefs::BODILESS` (ADR-121 WD7).
+      def refinement_def(module_name, class_name, method_name)
+        build
+        @refine_defs&.lookup(module_name, class_name, method_name)
+      end
+
+      # `{refine-body DefNode => Module.nesting where it is written}` for the defs {#refinement_def} answers, which a
+      # body re-typed from another file's parse reads its constants by (`DefNodeResolver.refinement_query`).
+      def refine_def_nestings
+        build
+        @refine_defs ? @refine_defs.nestings : {}
+      end
+
+      # Issue #1689 — is `call_node` an implicit- or `self`-receiver `refine` call with a literal block
+      # ({ScopeIndexer.refine_call?}, whatever its argument) whose `self` this walk knows to be a class? `Class`
+      # undefines `refine`, so such a call is the class's own method (a DSL a base class defines), not
+      # `Module#refine`: its block is an ordinary block, and its `def`s refine nothing. Every walk that recognises a
+      # refine body asks this, so they agree on which calls are refine bodies. A node another file's parse made
+      # answers false.
+      def class_body_refine?(call_node)
+        build
+        offsets = @class_body_refines
+        !offsets.nil? && member?(call_node) && offsets.include?(call_node.block.location.start_offset)
+      end
+
+      # ADR-121 WD7 — the `RefineSelf::Context` of the `self` the `refine`-shaped `node` (a `refine` call, a `:refine`
+      # literal, a String naming `refine` passed to an eval, `send` or method-naming call) runs on, as this walk worked
+      # it out, or nil for a node it did not record (another file's, or no such node). The census charges what this
+      # answers, so the table and the activations agree.
+      def refine_context(node)
+        build
+        @refine_contexts[node.location.start_offset] if member?(node)
+      end
+
+      # Is this the query over `root`'s tree?
+      def over?(root) = @root.equal?(root)
+
+      # Issue #1367 — is any refinement in effect at `offset`?
+      def any_at?(offset) = !at(offset).empty?
+
+      # Is `def_node` one of the defs a `refine X do … end` body defines on X? Such a def redefines X's method by
+      # design, so X's declared signature for the name is not its contract (issue #1120, maintainer ruling a′).
+      def refinement_def?(def_node)
+        build
+        @refinement_defs.include?(def_node.location.start_offset)
+      end
+
+      private
+
+      EMPTY_OFFSET = -1
+      EMPTY_SET = Set.new.freeze
+      NO_CONTEXTS = {}.freeze
+      private_constant :EMPTY_OFFSET, :EMPTY_SET, :NO_CONTEXTS
+
+      # A spelling's candidates are alternatives, innermost first; Ruby's lexical lookup finds the innermost one
+      # that exists, so it goes last and wins where several are declared. ADR-121 WD7 (A1): every declared candidate
+      # stays, because which one Ruby finds can depend on load order; one nothing declares
+      # ({UNDECLARED}) leaves; and when none is declared, the spelling enters alone, a module no table declares,
+      # which the readers treat as opaque (`using` of a gem's module, issue #1796).
+      def append_activation(list, activation, expand)
+        names = activation.names
+        if names.nil?
+          list << UNKNOWN unless list.include?(UNKNOWN)
+          return
+        end
+        unless activation.expand && expand
+          names.reverse_each { |name| list << name unless list.include?(name) }
+          return
+        end
+
+        declared = false
+        names.reverse_each do |name|
+          expanded = expand.call(name)
+          next if expanded == UNDECLARED
+
+          declared = true
+          append_entries(list, expanded)
+        end
+        list << names.last unless declared || list.include?(names.last)
+      end
+
+      # A block source's declared module (#1667), listed as declared. One nothing declares refines nothing Rigor can
+      # see, so it matches no row; the readers never treat a declared module as opaque.
+      def append_expanded(list, name, expand)
+        expanded = expand ? expand.call(name) : [name]
+        append_entries(list, expanded == UNDECLARED ? [name] : expanded)
+      end
+
+      def append_entries(list, expanded)
+        if expanded.nil?
+          list << UNKNOWN unless list.include?(UNKNOWN)
+        else
+          expanded.each { |entry| list << entry unless list.include?(entry) }
+        end
+      end
+
+      # Is `node` one this file's parse holds? Prism gives every node of one parse the same `Prism::Source`, so a
+      # node another file's parse made answers false in O(1); a node synthesised over this parse's source counts.
+      def member?(node)
+        node.send(:source).equal?(@root.send(:source))
+      end
+
+      def build
+        return if @built
+
+        @built = true
+        @activations = EMPTY
+        @refinement_defs = EMPTY_SET
+        @refine_defs = nil
+        @chained_refined_calls = nil
+        @class_body_refines = nil
+        @refine_contexts = NO_CONTEXTS
+        @literal_bindings = nil
+        @refine_offsets = nil
+        @unresolved_using = false
+        return if @root.nil? || !mentions_refinements?
+
+        @activations = []
+        @refinement_defs = Set.new
+        @refine_defs = RefineDefs.new
+        @refine_contexts = {}
+        @nesting = EMPTY
+        location = @root.location
+        walk(@root, [], [location.start_offset, location.end_offset], false, RefineSelf.top)
+        sort_activations
+        @activations.freeze
+      end
+    end
+  end
+end

data/lib/rigor/inference/key_presence_guard/scan.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  module Inference
+    module KeyPresenceGuard
+      # Issue #1703 — the syntax scans {KeyPresenceGuard} decides with: whether a guard may be relied on at all
+      # ({.eligible?}), whether the source between a guard and its read may have broken it ({.intervening?}), and
+      # whether one call or write breaks it ({.breaks?}, {.aliases_guard?}). Every answer errs towards breaking.
+      module Scan
+        # Blockless calls on a guarded receiver that cannot remove a key or rebind a slot, and do not answer the
+        # receiver itself (so `x = h.itself` or `x = h.to_h` is a hand-on, not a read). Any other call on it, and any
+        # call with a block, may break the guard (`h.delete(k)`, `h.send(:delete, k)`, `h.each { … h.clear }`).
+        READ_ONLY_RECEIVER_CALLS = %i[
+          [] key? has_key? include? member? fetch dig values_at fetch_values size length count empty? any? none?
+          keys values to_a dup clone frozen? hash == != eql? equal? inspect to_s is_a? kind_of? instance_of? nil?
+          respond_to?
+        ].to_set.freeze
+
+        # The nodes whose `value` a write stores: storing the receiver or the key's root somewhere else aliases it.
+        WRITE_NODES = [
+          Prism::LocalVariableWriteNode, Prism::InstanceVariableWriteNode, Prism::ClassVariableWriteNode,
+          Prism::GlobalVariableWriteNode, Prism::ConstantWriteNode, Prism::ConstantPathWriteNode, Prism::MultiWriteNode,
+          Prism::LocalVariableOrWriteNode, Prism::LocalVariableAndWriteNode, Prism::LocalVariableOperatorWriteNode,
+          Prism::InstanceVariableOrWriteNode, Prism::InstanceVariableAndWriteNode,
+          Prism::InstanceVariableOperatorWriteNode, Prism::IndexOrWriteNode, Prism::IndexAndWriteNode,
+          Prism::IndexOperatorWriteNode, Prism::CallOrWriteNode, Prism::CallAndWriteNode, Prism::CallOperatorWriteNode
+        ].to_set.freeze
+
+        # The nodes that bind a local by name (a write, or a target of a multiple assignment, `for`, `rescue => e`, a
+        # pattern or a named capture) and an instance variable by name.
+        LOCAL_BINDERS = [
+          Prism::LocalVariableWriteNode, Prism::LocalVariableOrWriteNode, Prism::LocalVariableAndWriteNode,
+          Prism::LocalVariableOperatorWriteNode, Prism::LocalVariableTargetNode
+        ].to_set.freeze
+
+        IVAR_BINDERS = [
+          Prism::InstanceVariableWriteNode, Prism::InstanceVariableOrWriteNode, Prism::InstanceVariableAndWriteNode,
+          Prism::InstanceVariableOperatorWriteNode, Prism::InstanceVariableTargetNode
+        ].to_set.freeze
+
+        CLOSURE_NODES = [Prism::BlockNode, Prism::LambdaNode].to_set.freeze
+
+        private_constant :LOCAL_BINDERS, :IVAR_BINDERS, :CLOSURE_NODES
+
+        module_function
+
+        # A guard is relied on only when nothing in reach can change what it proved:
+        # - a local receiver is never handed on in its method body — as an argument, a written value, inside a block, or
+        #   as the receiver of anything but a blockless read ({.mentions?}) — before the guard or after it;
+        # - an instance-variable receiver is never handed on anywhere in the file;
+        # - a constant receiver is assigned once in the file, a frozen hash literal (`MAP = { … }.freeze`), and is never
+        #   handed on in the file;
+        # - a local key root is bound nowhere in its method body after the guard, never stored elsewhere (`j = k`) and
+        #   never read inside a block; an instance-variable key root is bound nowhere in the file.
+        def eligible?(walk, call_node, guard)
+          kind, name, key = guard
+          body = walk.enclosing_def(call_node) || walk.root
+          receiver_eligible?(walk, body, kind, name) && key_root_eligible?(walk, body, key, call_node)
+        end
+
+        # Memoised per receiver and, for a local, per method body: the answer depends on neither the guard nor its key.
+        def receiver_eligible?(walk, body, kind, name)
+          memo_key = [:receiver, kind, name, kind == :local ? body.location.start_offset : nil]
+          return walk.memo[memo_key] if walk.memo.key?(memo_key)
+
+          walk.memo[memo_key] = scan_receiver_eligible?(walk, body, kind, name)
+        end
+
+        def scan_receiver_eligible?(walk, body, kind, name)
+          case kind
+          when :local then !mentions?(body, [kind, name])
+          when :ivar then !mentions?(walk.root, [kind, name])
+          when :const then frozen_constant?(walk, name) && !mentions?(walk.root, [kind, name])
+          else false
+          end
+        end
+
+        def frozen_constant?(walk, name)
+          walk.frozen_constants ||= frozen_constant_names(walk.root)
+          walk.frozen_constants.include?(name)
+        end
+
+        # The constants the file assigns exactly once, to a frozen hash literal.
+        def frozen_constant_names(root)
+          writes = Hash.new { |table, key| table[key] = [] }
+          collect_constant_writes(root, writes)
+          writes.filter_map { |name, values| name if values.size == 1 && frozen_hash_literal?(values.first) }.to_set
+        end
+
+        def collect_constant_writes(node, writes)
+          writes[node.name] << node.value if node.is_a?(Prism::ConstantWriteNode)
+          writes[node.name] << nil if node.is_a?(Prism::ConstantOrWriteNode) || node.is_a?(Prism::ConstantTargetNode)
+          node.compact_child_nodes.each { |child| collect_constant_writes(child, writes) }
+        end
+
+        def frozen_hash_literal?(value)
+          value.is_a?(Prism::CallNode) && value.name == :freeze && value.arguments.nil? && value.block.nil? &&
+            value.receiver.is_a?(Prism::HashNode)
+        end
+
+        def key_root_eligible?(walk, body, key, guard_node)
+          root_ref = key.root
+          kind, name = root_ref
+          if kind == :ivar
+            memo_key = [:ivar_key_root, name]
+            return walk.memo[memo_key] if walk.memo.key?(memo_key)
+
+            walk.memo[memo_key] = !binds?(walk.root, IVAR_BINDERS, name, -1) && !closure_reads?(walk.root, root_ref)
+          else
+            !binds?(body, LOCAL_BINDERS, name, guard_node.location.start_offset) &&
+              !aliases?(body, key) && !closure_reads?(body, root_ref)
+          end
+        end
+
+        # Whether a binder of `name` starts after `offset` within `node`.
+        def binds?(node, binders, name, offset)
+          return true if binders.include?(node.class) && node.name == name && node.location.start_offset > offset
+
+          node.compact_child_nodes.any? { |child| binds?(child, binders, name, offset) }
+        end
+
+        # Whether a write stores the key's value or something a call on it answers (`j = k`, `s = k.itself`,
+        # `s = prop.column_type.to_s`): its value is the key's root read, or a receiver chain that starts with the
+        # whole key chain. Such a copy may be the key object itself, and mutating it changes the key.
+        def aliases?(node, key)
+          return true if WRITE_NODES.include?(node.class) && derived_from_key?(node.value, key)
+
+          node.compact_child_nodes.any? { |child| aliases?(child, key) }
+        end
+
+        def derived_from_key?(value, key)
+          path = receiver_path(value)
+          !path.nil? && path.first(key.path.size) == key.path
+        end
+
+        # `[[root_kind, root_name], method, …]` for a local / ivar read or a receiver chain rooted at one, or nil.
+        def receiver_path(node)
+          names = []
+          while node.is_a?(Prism::CallNode) && node.receiver
+            names.unshift(node.name)
+            node = node.receiver
+          end
+          root = chain_root(node)
+          root && [root, *names]
+        end
+
+        # Whether a block or lambda body reads `ref` at all.
+        def closure_reads?(node, ref)
+          return reads?(node, ref) if CLOSURE_NODES.include?(node.class)
+
+          node.compact_child_nodes.any? { |child| closure_reads?(child, ref) }
+        end
+
+        def reads?(node, ref)
+          receiver_ref(node) == ref || node.compact_child_nodes.any? { |child| reads?(child, ref) }
+        end
+
+        # Whether the source between the guard and the read holds anything that may break the guard, read in source
+        # order so a later operand of the guard's own condition counts (`h.key?(k) && purge(h, k)`). A read before its
+        # guard (a loop back-edge) is taken to intervene.
+        def intervening?(walk, guard, read_node)
+          start = walk.guard_ends[guard]
+          stop = read_node.location.start_offset
+          return true if start.nil? || start > stop
+
+          body = walk.enclosing_def(read_node) || walk.root
+          breaks_in_region?(body, guard, start, stop)
+        end
+
+        def breaks_in_region?(node, guard, start, stop)
+          location = node.location
+          return false if location.end_offset <= start || location.start_offset >= stop
+
+          return true if location.start_offset >= start && location.end_offset <= stop && node_breaks?(node, guard)
+
+          node.compact_child_nodes.any? { |child| breaks_in_region?(child, guard, start, stop) }
+        end
+
+        def node_breaks?(node, guard)
+          (node.is_a?(Prism::CallNode) && breaks?(node, guard)) ||
+            (WRITE_NODES.include?(node.class) && aliases_guard?(node, guard)) ||
+            rebinds_guard?(node, guard) ||
+            (CLOSURE_NODES.include?(node.class) && closure_breaks?(node, guard))
+        end
+
+        def aliases_guard?(node, guard)
+          kind, name, key = guard
+          mentions?(node.value, [kind, name]) || mentions?(node.value, key.root)
+        end
+
+        def rebinds_guard?(node, guard)
+          kind, name, key = guard
+          [[kind, name], key.root].any? do |ref_kind, ref_name|
+            binders = { local: LOCAL_BINDERS, ivar: IVAR_BINDERS }[ref_kind]
+            binders&.include?(node.class) && node.name == ref_name
+          end
+        end
+
+        def closure_breaks?(node, guard)
+          kind, name, key = guard
+          reads?(node, [kind, name]) || reads?(node, key.root)
+        end
+
+        # Whether `call_node` may break the guard `[receiver_kind, receiver_name, key]`:
+        # - it passes the receiver as an argument (or `self`, when an instance variable is involved), or its block
+        #   mentions the receiver or the key's root;
+        # - it is a call on the receiver other than a blockless read ({READ_ONLY_RECEIVER_CALLS});
+        # - it is rooted at the key's variable and does not re-read the key chain (`prop.reload`, `prop.x = 1`);
+        # - it is a call on `self` and the receiver or the key is an instance variable.
+        # Passing the key's root as an argument (`overridden?(prop)`) does not break it, as it does not end a
+        # method-chain narrowing.
+        def breaks?(call_node, guard)
+          kind, name, key = guard
+          receiver_ref = [kind, name]
+          return true if escapes_through_operands?(call_node, receiver_ref, key.root)
+
+          receiver = call_node.receiver
+          return kind == :ivar || key.root.first == :ivar if receiver.nil? || receiver.is_a?(Prism::SelfNode)
+          return true if receiver_ref(receiver) == receiver_ref && !read_only_call?(call_node)
+
+          touches_key_root?(call_node, key)
+        end
+
+        def escapes_through_operands?(call_node, receiver_ref, key_root)
+          args = call_node.arguments
+          return true if args && mentions?(args, receiver_ref)
+          # `other.mutate_owner(self)` hands on every instance variable.
+          return true if args && (receiver_ref.first == :ivar || key_root.first == :ivar) && mentions_self?(args)
+
+          block = call_node.block
+          return false if block.nil?
+
+          mentions?(block, receiver_ref) || (block.is_a?(Prism::BlockNode) && reads?(block, key_root))
+        end
+
+        def read_only_call?(call_node) = call_node.block.nil? && READ_ONLY_RECEIVER_CALLS.include?(call_node.name)
+
+        def touches_key_root?(call_node, key)
+          return false unless chain_root(call_node.receiver) == key.root
+
+          own = key_expr(call_node)
+          own.nil? || !key.prefixed_by?(own)
+        end
+
+        # The `[kind, name]` of the local / ivar a receiver chain (`a.b.c`, `a[0].b`) starts from, or nil.
+        def chain_root(node)
+          node = node.receiver while node.is_a?(Prism::CallNode) && node.receiver
+          case node
+          when Prism::LocalVariableReadNode then [:local, node.name]
+          when Prism::InstanceVariableReadNode then [:ivar, node.name]
+          end
+        end
+
+        def mentions_self?(node)
+          node.is_a?(Prism::SelfNode) || node.compact_child_nodes.any? { |child| mentions_self?(child) }
+        end
+
+        # Whether `node` holds a read of the variable `ref` in a position that may hand it on: anywhere but as the
+        # receiver of a blockless read ({READ_ONLY_RECEIVER_CALLS}), so `h[k]` and `MAP.key?(x)` do not count while
+        # `zap(h)`, `[h]`, `g = h` and `h.delete(k)` do.
+        def mentions?(node, ref)
+          return false if node.nil?
+
+          own = receiver_ref(node)
+          return own == ref if own
+
+          if node.is_a?(Prism::CallNode) && receiver_ref(node.receiver) == ref && read_only_call?(node)
+            return [node.arguments, node.block].any? { |part| mentions?(part, ref) }
+          end
+
+          node.compact_child_nodes.any? { |child| mentions?(child, ref) }
+        end
+
+        def receiver_ref(node) = KeyPresenceGuard.receiver_ref(node)
+        def key_expr(node) = KeyPresenceGuard.key_expr(node)
+      end
+    end
+  end
+end