ryac 0.2.0

data/lib/ryac/analysis/type_oracle.rb

@@ -0,0 +1,386 @@
+# frozen_string_literal: true
+
+require 'typeprof'
+
+module Ryac
+  # The one place allowed to talk to TypeProf.
+  #
+  # Everything the renamer needs from type analysis is phrased as a handful
+  # of questions — which methods a call can reach, who calls a method, what
+  # a receiver is, what a constant resolves to, what a class inherits. The
+  # collections compute every lexical fact themselves on the Prism tree and
+  # come here only for those questions, so a change in TypeProf's internals
+  # breaks this file and nothing else.
+  #
+  # Answers refer to source positions (location keys) or plain values, never
+  # to TypeProf objects.
+  class TypeOracle
+    # Boots TypeProf over the program and its RBS. This owns the two
+    # internals the boot requires — the Service construction and the
+    # private @rb_text_nodes table behind update_rb_file — so an upstream
+    # change to either breaks here and nowhere else.
+    def self.boot(content, rbs_files)
+      path = '(minify_concat)'
+      service = TypeProf::Core::Service.new({})
+      rbs_files.each do |rbs_path, rbs_content|
+        service.update_rbs_file(rbs_path, rbs_content)
+      end
+      service.update_rb_file(path, content)
+      new(service.genv, service.instance_variable_get(:@rb_text_nodes)[path])
+    end
+
+    # TypeProf keeps the backing Prism node private because an editor has no
+    # reason to ask; the coordinate join (tp_key below) asks constantly,
+    # since Prism is where the syntax being rewritten lives.
+    def self.raw_prism_node(node)
+      node.instance_variable_get(:@raw_node)
+    end
+
+    def initialize(genv, tp_root)
+      @genv = genv
+      @tp_root = tp_root
+    end
+
+    # Yields every ancestor cpath of the class, including its own.
+    # Unresolvable classes yield nothing.
+    def each_ancestor_cpath(cpath, singleton, &block)
+      @ancestor_cpaths ||= {} #: Hash[MethodRenameMapping::class_key, Array[Array[Symbol]]]
+      cached = @ancestor_cpaths[[cpath, singleton]] ||= begin
+        list = [] #: Array[Array[Symbol]]
+        mod = @genv.resolve_cpath(cpath) rescue nil
+        if mod
+          @genv.each_superclass(mod, singleton) do |ancestor_mod, _singleton|
+            list << ancestor_mod.cpath
+          end
+        end
+        list
+      end
+      cached.each(&block)
+    end
+
+    # Yields [ancestor_cpath, singleton, method_names] along the ancestor
+    # chain, own class first — the namespace a new method name must not
+    # collide with.
+    def each_ancestor_methods(cpath, singleton)
+      mod = @genv.resolve_cpath(cpath) rescue nil
+      return unless mod
+
+      @genv.each_superclass(mod, singleton) do |ancestor_mod, s|
+        names = [] #: Array[String]
+        ancestor_mod.methods[s]&.each_key { |mid| names << mid.to_s }
+        yield ancestor_mod.cpath, s, names
+      end
+    end
+
+    # True when type analysis has any record of the method at all.
+    def method_known?(cpath, singleton, mid)
+      !resolve_method(cpath, singleton, mid).nil?
+    end
+
+    # True when the method has at least one definition in the analyzed source.
+    def method_defined?(cpath, singleton, mid)
+      entity = resolve_method(cpath, singleton, mid)
+      !entity.nil? && entity.defs.size > 0
+    end
+
+    def method_call_count(cpath, singleton, mid)
+      entity = resolve_method(cpath, singleton, mid)
+      entity ? entity.method_call_boxes.size : 0
+    end
+
+    # Location keys of every call site that dispatches to the method.
+    def each_call_site_key(cpath, singleton, mid)
+      entity = resolve_method(cpath, singleton, mid)
+      return unless entity
+
+      entity.method_call_boxes.each do |call_box|
+        yield tp_key(call_box.node)
+      end
+    end
+
+    # Location keys of the method's definition sites.
+    def method_definition_keys(cpath, singleton, mid)
+      entity = resolve_method(cpath, singleton, mid)
+      return [] unless entity
+
+      entity.defs.to_a.map { |d| tp_key(d.node) }
+    end
+
+    # One record per call site that dispatches to the method, as plain data:
+    #
+    #   prism_node       the call in the syntax tree (nil for a super with no
+    #                    syntactic call node of its own, and for a dispatch
+    #                    synthesized inside an RBS declaration)
+    #   super            true for `super` — dispatch from a subclass override
+    #   caller_cpath     the class nesting the call sits in
+    #   receiver         whether the call is written with an explicit receiver
+    #   keyword_entries  [[symbol_node, value_node], ...] for literal keyword
+    #                    arguments, nil when the call passes none
+    #   keyword_splat    true when keywords arrive via **splat
+    CallerInfo = Struct.new(:prism_node, :super, :caller_cpath, :receiver,
+                            :keyword_entries, :keyword_splat, keyword_init: true)
+
+    def each_caller(cpath, singleton, mid)
+      entity = resolve_method(cpath, singleton, mid)
+      return unless entity
+
+      entity.method_call_boxes.each do |call_box|
+        node = call_box.node
+
+        if node.is_a?(TypeProf::Core::AST::SuperNode) ||
+           node.is_a?(TypeProf::Core::AST::ForwardingSuperNode)
+          yield CallerInfo.new(prism_node: TypeOracle.raw_prism_node(node), super: true,
+                               caller_cpath: node.lenv.cref.cpath, receiver: false,
+                               keyword_entries: nil, keyword_splat: false)
+          next
+        end
+
+        # A box whose node is not a syntactic call names no site in the
+        # program — e.g. one synthesized while TypeProf evaluated an RBS
+        # declaration: `[x].map(&:foo)` dispatches to foo from Array#map's
+        # declared signature. Nothing in the source can be rewritten to
+        # follow a rename, so the record carries only the fact that an
+        # unrewritable caller exists.
+        unless node.is_a?(TypeProf::Core::AST::CallBaseNode)
+          yield CallerInfo.new(prism_node: nil, super: false, caller_cpath: nil,
+                               receiver: false, keyword_entries: nil, keyword_splat: false)
+          next
+        end
+
+        entries = nil
+        splat = false
+        kw = node.respond_to?(:keyword_args) ? node.keyword_args : nil
+        if kw.is_a?(TypeProf::Core::AST::HashNode)
+          splat = kw.keys.any?(&:nil?)
+          entries = kw.keys.zip(kw.vals).filter_map do |sym_node, val_node|
+            # @type var val_node: TypeProf::Core::AST::Node
+            next unless sym_node.is_a?(TypeProf::Core::AST::SymbolNode)
+            [TypeOracle.raw_prism_node(sym_node), TypeOracle.raw_prism_node(val_node)] #: [Prism::Node, Prism::Node]
+          end
+        end
+
+        yield CallerInfo.new(prism_node: TypeOracle.raw_prism_node(node), super: false,
+                             caller_cpath: nil, receiver: !node.recv.nil?,
+                             keyword_entries: entries, keyword_splat: splat)
+      end
+    end
+
+    # The method keys a call could dispatch to, per type inference. nil when
+    # inference has no answer at all — distinct from an empty list.
+    def resolved_targets(prism_call_node, mid)
+      tp_node = tp_call_for(prism_call_node, mid)
+      return nil unless tp_node
+
+      keys = [] #: Array[method_key]
+      tp_node.boxes(:mcall) do |box|
+        box.resolve(@genv, nil) do |entity, ty, _mid, _orig_ty|
+          next unless entity
+          singleton = ty.is_a?(TypeProf::Core::Type::Singleton)
+          keys << [ty.mod.cpath, singleton, mid]
+        end
+      end
+      keys.any? ? keys : nil
+    end
+
+    # Symbol values inference assigns to the call's first positional argument
+    # — how `method(:foo)`-style dynamic references name their target.
+    def first_argument_symbols(prism_call_node)
+      tp_node = tp_call_for(prism_call_node, prism_call_node.name)
+      return [] unless tp_node
+
+      sym_arg = tp_node.positional_args&.first #: TypeProf::Core::AST::Node
+      ret = sym_arg.ret rescue nil
+      return [] unless ret
+
+      ret.types.each_key.filter_map do |ty|
+        ty.sym if ty.is_a?(TypeProf::Core::Type::Symbol)
+      end
+    end
+
+    # True when every inferred type of the call's receiver responds to mid —
+    # the safety condition for rewriting the call to a stdlib alias.
+    def receiver_responds_to?(prism_call_node, mid)
+      every_receiver_base_type(prism_call_node) do |base|
+        singleton = base.is_a?(TypeProf::Core::Type::Singleton)
+        type_responds_to?(base.mod, singleton, mid)
+      end
+    end
+
+    # Resolves a constant reference to its fully-qualified path, using type
+    # analysis to see through lexical-scope lookup and value constants.
+    # nil when the reference is not statically resolvable. Memoized — the
+    # counting, external-reference, and precompute passes each ask about the
+    # same nodes.
+    def resolve_constant_read(prism_node)
+      @const_resolution_cache ||= {} #: Hash[location_key, Array[Symbol]?]
+      key = AstUtils.location_key(prism_node)
+      return @const_resolution_cache[key] if @const_resolution_cache.key?(key)
+
+      tp_node = tp_const_for(prism_node)
+      @const_resolution_cache[key] = tp_node ? resolve_tp_const(tp_node) : nil
+    end
+
+    # How many read sites type analysis records for the constant. Can exceed
+    # the syntactic count when reads reach it through resolution the text
+    # does not show.
+    def constant_read_count(cpath)
+      # @type var entity: untyped
+      entity = begin
+        @genv.resolve_const(cpath)
+      rescue StandardError
+        nil
+      end
+      entity.respond_to?(:read_boxes) ? entity.read_boxes.size : 0
+    end
+
+    # True when every inferred type of the call's receiver is type_name or a
+    # subclass — the safety condition for type-specific rewrites like
+    # `.empty?` → `=={}` on a Hash.
+    def receiver_within_type?(prism_call_node, type_name)
+      target_mod = @genv.resolve_cpath([type_name])
+      return false unless target_mod
+
+      every_receiver_base_type(prism_call_node) do |base|
+        mod_is_or_inherits?(base.mod, target_mod)
+      end
+    end
+
+    private
+
+    # Location key of a TypeProf node, via the Prism node it was built from.
+    # TypeProf models source it cannot point back at — a node may carry no
+    # @raw_node at all, or an RBS node instead of a Prism one on sig-built
+    # nodes. Either way a node we cannot locate is one we cannot rename, so
+    # this raises rather than inventing a key that could never match. The
+    # conversion stays inside the oracle: everything outside it holds Prism
+    # nodes, and AstUtils keys those.
+    def tp_key(node)
+      prism_node = TypeOracle.raw_prism_node(node)
+      raise ArgumentError, "no source location behind #{node.class}" unless prism_node.is_a?(Prism::Node)
+
+      AstUtils.location_key(prism_node)
+    end
+
+    def resolve_method(cpath, singleton, mid)
+      @method_cache ||= {} #: Hash[method_key, TypeProf::Core::MethodEntity?]
+      key = [cpath, singleton, mid] #: method_key
+      return @method_cache[key] if @method_cache.key?(key)
+
+      @method_cache[key] = begin
+        @genv.resolve_method(cpath, singleton, mid)
+      rescue StandardError
+        nil
+      end
+    end
+
+    # The shared scaffold of the receiver-safety questions: false unless the
+    # receiver has inferred types at all, then the block must hold for every
+    # type's base.
+    def every_receiver_base_type(prism_call_node)
+      recv = tp_call_for(prism_call_node, prism_call_node.name)&.recv #: untyped
+      return false unless recv.respond_to?(:ret) && recv.ret
+
+      types = recv.ret.types
+      return false if types.empty?
+
+      types.all? do |ty, _|
+        base = ty.base_type(@genv)
+        next false unless base.respond_to?(:mod)
+        yield base
+      end
+    end
+
+    def type_responds_to?(mod, singleton, mid)
+      @genv.each_superclass(mod, singleton) do |ancestor_mod, s|
+        entity = ancestor_mod.methods[s]&.[](mid)
+        return true if entity && (entity.exist? || entity.aliases.any?)
+      end
+      false
+    end
+
+    def mod_is_or_inherits?(mod, target)
+      return true if mod == target
+      @genv.each_superclass(mod, false) do |ancestor, _|
+        return true if ancestor == target
+      end
+      false
+    end
+
+    TP_CALL_NODES = [
+      TypeProf::Core::AST::CallNode,
+      TypeProf::Core::AST::CallReadNode,
+      TypeProf::Core::AST::CallWriteNode
+    ].freeze
+
+    # TypeProf's node for a call at a given source position. TypeProf answers
+    # type questions per node in its own tree; this index is how a question
+    # about a Prism node finds its counterpart.
+    #
+    # Indexed by position *and* method name: a compound write like
+    # `self.count += 1` is one position but two TypeProf nodes — a read of
+    # `count` and a write of `count=` — and a question about either name has
+    # to reach its own node.
+    def tp_call_for(prism_node, mid)
+      build_tp_indexes
+      @tp_calls_by_loc[AstUtils.location_key(prism_node)]&.[](mid)
+    end
+
+    # TypeProf's constant-read node at a given source position. Covers plain
+    # reads, every level of a qualified chain, and the read half of compound
+    # writes (`X ||= 1` reads at the whole expression's position).
+    def tp_const_for(prism_node)
+      build_tp_indexes
+      @tp_consts_by_loc[AstUtils.location_key(prism_node)]
+    end
+
+    # Both position indexes come from the same walk; a real run always needs
+    # both, so one traversal fills them together.
+    def build_tp_indexes
+      return if @tp_calls_by_loc
+
+      calls = {} #: Hash[location_key, Hash[Symbol, TypeProf::Core::AST::CallBaseNode]]
+      consts = {} #: Hash[location_key, TypeProf::Core::AST::ConstantReadNode]
+      @tp_root.traverse do |event, node|
+        next unless event == :enter
+        case node
+        when *TP_CALL_NODES
+          # @type var node: TypeProf::Core::AST::CallBaseNode
+          (calls[tp_key(node)] ||= {})[node.mid] = node
+        when TypeProf::Core::AST::ConstantReadNode
+          consts[tp_key(node)] = node
+        end
+      end
+      @tp_calls_by_loc = calls
+      @tp_consts_by_loc = consts
+    end
+
+    # A class/module reference resolves through its own analysis result; a
+    # value constant through its definition's location; a qualified chain
+    # (Foo::CONST) through its prefix, recursively.
+    def resolve_tp_const(node)
+      return nil unless node.is_a?(TypeProf::Core::AST::ConstantReadNode)
+
+      static_ret = begin
+        node.static_ret
+      rescue StandardError
+        nil
+      end
+      return nil unless static_ret.respond_to?(:cpath)
+      return static_ret.cpath if static_ret.cpath
+
+      cdef = static_ret.respond_to?(:cdef) ? static_ret.cdef : nil #: untyped
+      if cdef.respond_to?(:defs)
+        cdef.defs.each do |d|
+          return d.static_cpath if d.respond_to?(:static_cpath) && d.static_cpath
+        end
+      end
+
+      if node.cbase
+        base_cpath = resolve_tp_const(node.cbase)
+        return base_cpath + [node.cname] if base_cpath
+      end
+
+      nil
+    end
+  end
+end

data/lib/ryac/ast_utils.rb

@@ -0,0 +1,321 @@
+# frozen_string_literal: true
+
+module Ryac
+  module AstUtils
+    module_function
+
+    # The plain-symbol arguments of a call, as symbols — how attr_*,
+    # private_constant and friends name their subjects.
+    def symbol_arguments(call_node)
+      call_node.arguments&.arguments&.filter_map { |arg|
+        arg.unescaped.to_sym if arg.is_a?(Prism::SymbolNode)
+      } || []
+    end
+
+    def unwrap_statements(node)
+      return node unless node
+      node = node.body if node.is_a?(Prism::ParenthesesNode)
+      if node.is_a?(Prism::StatementsNode) && node.body.size == 1
+        node.body.first
+      else
+        node
+      end
+    end
+
+    MIDDLE_METHODS = %i[+ - * / ** % ^ > < <= >= <=> == === != & | << >> =~ !~].freeze
+
+    def middle_method?(method)
+      MIDDLE_METHODS.include?(method)
+    end
+
+    def logical_op?(node)
+      node.is_a?(Prism::OrNode) || node.is_a?(Prism::AndNode)
+    end
+
+    def has_block?(node)
+      node.block != nil
+    end
+
+    def single_statement_body?(body)
+      return false if body.nil?
+      return body.body.size == 1 if body.is_a?(Prism::StatementsNode)
+      true
+    end
+
+    def setter_def_name?(name)
+      s = name.to_s
+      s.end_with?('=') && !%w[== != <= >= ===].include?(s)
+    end
+
+    def simple_negatable?(node)
+      inner = unwrap_statements(node)
+      return false if logical_op?(inner)
+
+      inner.is_a?(Prism::CallNode) ? !middle_method?(inner.name) : true
+    end
+
+    def first_arg_starts_with_brace?(arg)
+      inner = unwrap_statements(arg)
+      return true if inner.is_a?(Prism::HashNode)
+      return first_arg_starts_with_brace?(inner.receiver) if inner.is_a?(Prism::CallNode) && inner.receiver
+
+      false
+    end
+
+    # Does this node's string representation end with a character
+    # that could form `name!` or `name?` if `!` or `?` is appended?
+    # Used for spacing before `!~` operator and ternary `?`/`:`.
+    # Recursively follows rightmost sub-expressions for compound nodes.
+    def ends_with_name_char?(node)
+      inner = unwrap_statements(node)
+      case inner
+      # Empty parens unwrap to nothing; the rendered `()` ends with ')'.
+      when nil
+        false
+      # nil renders as `()` — ends with ')', not a name char.
+      when Prism::NilNode
+        false
+      # Terminals: definitely safe (end with delimiter/sigil/literal)
+      when Prism::ParenthesesNode,
+           Prism::StringNode, Prism::InterpolatedStringNode,
+           Prism::InterpolatedSymbolNode,
+           Prism::RegularExpressionNode, Prism::InterpolatedRegularExpressionNode,
+           Prism::ArrayNode, Prism::HashNode, Prism::LambdaNode,
+           Prism::InstanceVariableReadNode, Prism::ClassVariableReadNode,
+           Prism::GlobalVariableReadNode,
+           Prism::IntegerNode, Prism::FloatNode, Prism::RationalNode, Prism::ImaginaryNode,
+           Prism::DefinedNode, Prism::RescueModifierNode
+        false
+      # Bare symbol :name ends with name char; quoted :"name" ends with delimiter
+      when Prism::SymbolNode
+        !inner.closing_loc
+      # Compound: follow rightmost sub-expression
+      when Prism::OrNode, Prism::AndNode
+        ends_with_name_char?(inner.right)
+      when Prism::RangeNode
+        inner.right ? ends_with_name_char?(inner.right) : false
+      when Prism::CallNode
+        return false if inner.block
+        if middle_method?(inner.name)
+          # Binary op: a+b → ends with right operand
+          arg = inner.arguments&.arguments&.first
+          arg ? ends_with_name_char?(arg) : true
+        elsif inner.name == :[]=
+          # Index assignment: recv[k]=val → ends with value
+          last_arg = inner.arguments&.arguments&.last
+          last_arg ? ends_with_name_char?(last_arg) : false
+        elsif inner.receiver && !inner.arguments && (inner.name == :! || inner.name == :~)
+          # Unary prefix operators: !x, ~x → output ends with operand
+          ends_with_name_char?(inner.receiver)
+        elsif inner.opening_loc
+          false # foo(args) → ends with )
+        elsif inner.name.to_s.end_with?('?', '!')
+          false
+        else
+          true # bare method: foo.bar → ends with ident char
+        end
+      when Prism::YieldNode, Prism::SuperNode
+        inner.arguments.nil?
+      # Assignment: var=value → ends with value
+      when Prism::LocalVariableWriteNode, Prism::InstanceVariableWriteNode,
+           Prism::ClassVariableWriteNode, Prism::GlobalVariableWriteNode,
+           Prism::ConstantWriteNode, Prism::ConstantPathWriteNode
+        ends_with_name_char?(inner.value)
+      when Prism::LocalVariableOrWriteNode, Prism::LocalVariableAndWriteNode,
+           Prism::InstanceVariableOrWriteNode, Prism::InstanceVariableAndWriteNode,
+           Prism::ClassVariableOrWriteNode, Prism::ClassVariableAndWriteNode,
+           Prism::GlobalVariableOrWriteNode, Prism::GlobalVariableAndWriteNode,
+           Prism::ConstantOrWriteNode, Prism::ConstantAndWriteNode
+        ends_with_name_char?(inner.value)
+      else
+        true # conservative: local var, const, nil, true, false, self, etc.
+      end
+    end
+
+    # Does this node's output end with ? or ! method suffix?
+    # Recursively follows rightmost sub-expressions.
+    def ends_with_method_suffix?(node)
+      inner = unwrap_statements(node)
+      case inner
+      when Prism::OrNode, Prism::AndNode
+        ends_with_method_suffix?(inner.right)
+      when Prism::CallNode
+        return false if inner.block
+        return false if inner.opening_loc && inner.name != :[]=
+        if middle_method?(inner.name)
+          arg = inner.arguments&.arguments&.first
+          arg ? ends_with_method_suffix?(arg) : false
+        elsif inner.name == :[]=
+          last_arg = inner.arguments&.arguments&.last
+          last_arg ? ends_with_method_suffix?(last_arg) : false
+        elsif inner.receiver && !inner.arguments && (inner.name == :! || inner.name == :~)
+          # Unary prefix operators (!x, ~x) — output ends with operand, not suffix
+          ends_with_method_suffix?(inner.receiver)
+        else
+          inner.name.to_s.end_with?('?', '!')
+        end
+      when Prism::SymbolNode
+        !inner.closing_loc && inner.value.to_s.end_with?('?', '!')
+      when Prism::LocalVariableWriteNode, Prism::InstanceVariableWriteNode,
+           Prism::ClassVariableWriteNode, Prism::GlobalVariableWriteNode,
+           Prism::ConstantWriteNode, Prism::ConstantPathWriteNode,
+           Prism::LocalVariableOrWriteNode, Prism::LocalVariableAndWriteNode,
+           Prism::InstanceVariableOrWriteNode, Prism::InstanceVariableAndWriteNode,
+           Prism::ClassVariableOrWriteNode, Prism::ClassVariableAndWriteNode,
+           Prism::GlobalVariableOrWriteNode, Prism::GlobalVariableAndWriteNode,
+           Prism::ConstantOrWriteNode, Prism::ConstantAndWriteNode
+        ends_with_method_suffix?(inner.value)
+      else
+        false
+      end
+    end
+
+    # Needs space before ternary `?`?
+    # True when condition ends with: name char, `?`, `!`, or digit.
+    def needs_ternary_q_space?(node)
+      ends_with_name_char?(node) || ends_with_method_suffix?(node)
+    end
+
+    def modifier_control_flow?(node)
+      modifier_conditional?(node) || modifier_loop?(node)
+    end
+
+    def modifier_conditional?(node)
+      case node
+      when Prism::IfNode then node.if_keyword_loc && !node.end_keyword_loc
+      when Prism::UnlessNode then node.keyword_loc && !node.end_keyword_loc
+      else false
+      end
+    end
+
+    def modifier_loop?(node)
+      case node
+      when Prism::WhileNode, Prism::UntilNode then !node.closing_loc
+      else false
+      end
+    end
+
+    # Bytes before which a ternary does NOT need wrapping parens
+    TERNARY_SAFE_PREV = [';'.ord, "\n".ord, "\r".ord, '('.ord, '['.ord, '{'.ord].freeze
+    COMPARISON_PREV   = ['<'.ord, '>'.ord, '!'.ord, '='.ord].freeze
+    PIPE_BREAK_BYTES  = [';'.ord, "\n".ord, '{'.ord].freeze
+
+    def ternary_needs_parens?(node, source)
+      start = node.location.start_offset
+      return false if start == 0
+      prev = source.getbyte(start - 1)
+      return false if TERNARY_SAFE_PREV.include?(prev)
+      if prev == '='.ord
+        return false if start < 2
+        prev2 = source.getbyte(start - 2)
+        return COMPARISON_PREV.include?(prev2)
+      end
+      if prev == '|'.ord
+        return true if start < 3
+        return true if source.getbyte(start - 2) == '|'.ord
+        pos = start - 2
+        while pos >= 0
+          byte = source.getbyte(pos)
+          if byte == '|'.ord
+            return !(pos > 0 && source.getbyte(pos - 1) == '{'.ord)
+          end
+          break if PIPE_BREAK_BYTES.include?(byte)
+          pos -= 1
+        end
+        return true
+      end
+      true
+    end
+
+    def can_omit_parens?(node, method_name = nil)
+      return false if has_block?(node)
+      # `.()` proc-call sugar has no message; its parens ARE the call.
+      return false if node.message_loc.nil?
+      raw_args = node.arguments&.arguments || []
+      positional_args = raw_args.reject { |a| a.is_a?(Prism::KeywordHashNode) }
+      return false if positional_args.empty?
+      return false if raw_args.any? { |a| a.is_a?(Prism::ForwardingArgumentsNode) }
+      return false if node.name == :[] || node.name == :[]=
+      name_to_check = method_name || node.name.to_s
+      return false if name_to_check.end_with?('?')
+      return false if first_arg_starts_with_brace?(positional_args.first)
+      return false if first_arg_is_regex?(positional_args.first)
+      return false if raw_args.any? { |a| contains_bare_block?(a) }
+
+      true
+    end
+
+    def first_arg_is_regex?(arg)
+      arg.is_a?(Prism::RegularExpressionNode) || arg.is_a?(Prism::InterpolatedRegularExpressionNode)
+    end
+
+    def contains_bare_block?(node)
+      case node
+      when Prism::CallNode
+        return true if node.block.is_a?(Prism::BlockNode)
+        return true if node.receiver && contains_bare_block?(node.receiver)
+        return false if node.opening_loc
+        node.arguments&.arguments&.any? { |a| contains_bare_block?(a) } || false
+      when Prism::ParenthesesNode, Prism::ArrayNode, Prism::HashNode, Prism::LambdaNode
+        false
+      when Prism::KeywordHashNode
+        node.elements.any? { |e| e.is_a?(Prism::AssocNode) && contains_bare_block?(e.value) }
+      when Prism::SplatNode
+        contains_bare_block?(node.expression)
+      else
+        false
+      end
+    end
+
+    # Depth-first over every node. The shared primitive for analyses that
+    # need the whole tree without caring about scope or nesting context.
+    def self.each_node(node, &block)
+      return unless node.is_a?(Prism::Node)
+      yield node
+      node.compact_child_nodes.each { |child| each_node(child, &block) }
+    end
+
+    # Expressions that rebind to the surrounding statement when their parens
+    # are stripped: `def f =expr in pat` parses as `(def f =expr) in pat`.
+    # Every "needs parens" list must include these.
+    MATCH_REBIND_NODES = [Prism::MatchPredicateNode, Prism::MatchRequiredNode].freeze
+
+    def self.match_rebind?(node)
+      MATCH_REBIND_NODES.any? { |t| node.is_a?(t) }
+    end
+
+    # The shorthand-pun values of a hash-ish node: implicit assoc values that
+    # are NOT plain local reads (`{ label: }` calling method label). The one
+    # definition of "pun" shared by the keyword and method exclusion passes.
+    def self.shorthand_pun_values(node)
+      return [] unless node.is_a?(Prism::KeywordHashNode) || node.is_a?(Prism::HashNode)
+
+      node.elements.filter_map do |el|
+        next unless el.is_a?(Prism::AssocNode) && el.value.is_a?(Prism::ImplicitNode)
+
+        inner = el.value.value
+        inner unless inner.is_a?(Prism::LocalVariableReadNode)
+      end
+    end
+
+    # The single place the analysis and the patchers agree on what "the same
+    # piece of source" is: every map between phases is keyed by this. Prism
+    # nodes only — TypeOracle converts its own tree's nodes before keying,
+    # so the seam between the two trees stays inside the oracle.
+    #
+    # Byte offsets, because that is the coordinate system patches are applied
+    # in — deriving a separate line/column space for the join only gave the two
+    # sides a way to disagree.
+    def self.location_key(node)
+      loc = node.location
+      [loc.start_offset, loc.end_offset]
+    end
+
+    # The line/column coordinate space (syntax_data and friends) — kept
+    # separate from byte-offset location_key on purpose.
+    def self.line_col_key(node)
+      loc = node.location
+      [loc.start_line, loc.start_column]
+    end
+  end
+end