prism 1.9.0 → 2.0.0.rc2

data/lib/prism/node_find.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+# :markup: markdown
+#--
+# rbs_inline: enabled
+
+module Prism
+  # Finds the Prism AST node corresponding to a given Method, UnboundMethod,
+  # Proc, or Thread::Backtrace::Location. On CRuby, uses node_id from the
+  # instruction sequence for an exact match. On other implementations, falls
+  # back to best-effort matching by source location line number.
+  #
+  # This module is autoloaded so that programs that don't use Prism.find don't
+  # pay for its definition.
+  module NodeFind # :nodoc:
+    # Find the node for the given callable or backtrace location.
+    #
+    #: (Method | UnboundMethod | Proc | Thread::Backtrace::Location callable) -> Node?
+    def self.find(callable)
+      if callable.respond_to?(:source_range) && !defined?(::RubyVM)
+        return SourceRangeFind.new.find(callable)
+      end
+
+      case callable
+      when Proc
+        if defined?(::RubyVM)
+          RubyVMCallableFind.new.find(callable)
+        elsif callable.lambda?
+          LineLambdaFind.new.find(callable)
+        else
+          LineProcFind.new.find(callable)
+        end
+      when Method, UnboundMethod
+        if defined?(::RubyVM)
+          RubyVMCallableFind.new.find(callable)
+        else
+          LineMethodFind.new.find(callable)
+        end
+      when Thread::Backtrace::Location
+        if defined?(::RubyVM)
+          RubyVMBacktraceLocationFind.new.find(callable)
+        else
+          LineBacktraceLocationFind.new.find(callable)
+        end
+      else
+        raise ArgumentError, "Expected a Method, UnboundMethod, Proc, or Thread::Backtrace::Location, got #{callable.class}"
+      end
+    end
+
+    # Base class that handles parsing a file.
+    class Find
+      private
+
+      # Parse the given file path, returning a ParseResult or nil.
+      #
+      #: (String? file) -> ParseResult?
+      def parse_file(file)
+        return unless file && File.readable?(file)
+        result = Prism.parse_file(file)
+        result if result.success?
+      end
+    end
+
+    # Finds the AST node for a Method, UnboundMethod, Proc or Thread::Backtrace::Location
+    # using the #source_range
+    class SourceRangeFind < Find
+      # Find the node for the given callable using the #source_range.
+      #
+      #: (Method | UnboundMethod | Proc | Thread::Backtrace::Location callable) -> Node?
+      def find(callable)
+        begin
+          range = callable.source_range
+        rescue ArgumentError # eval
+          return
+        end
+        return unless range
+        return unless (result = parse_file(range.absolute_path))
+
+        start_offset = result.source.byte_offset(range.start_line, range.start_column)
+        end_offset = result.source.byte_offset(range.end_line, range.end_column)
+        result.value.tunnel(range.start_line, range.start_column).reverse_each do |node|
+          if node.start_offset == start_offset && node.end_offset == end_offset
+            return node
+          end
+        end
+        nil
+      end
+    end
+
+    # Finds the AST node for a Method, UnboundMethod, or Proc using the node_id
+    # from the instruction sequence.
+    class RubyVMCallableFind < Find
+      # Find the node for the given callable using the ISeq node_id.
+      #
+      #: (Method | UnboundMethod | Proc callable) -> Node?
+      def find(callable)
+        return unless (source_location = callable.source_location)
+        return unless (result = parse_file(source_location[0]))
+        return unless (iseq = RubyVM::InstructionSequence.of(callable))
+
+        header = iseq.to_a[4]
+        return unless header[:parser] == :prism
+
+        result.value.find { |node| node.node_id == header[:node_id] }
+      end
+    end
+
+    # Finds the AST node for a Thread::Backtrace::Location using the node_id
+    # from the backtrace location.
+    class RubyVMBacktraceLocationFind < Find
+      # Find the node for the given backtrace location using node_id.
+      #
+      #: (Thread::Backtrace::Location location) -> Node?
+      def find(location)
+        file = location.absolute_path || location.path
+        return unless (result = parse_file(file))
+        return unless RubyVM::AbstractSyntaxTree.respond_to?(:node_id_for_backtrace_location)
+
+        node_id = RubyVM::AbstractSyntaxTree.node_id_for_backtrace_location(location)
+
+        result.value.find { |node| node.node_id == node_id }
+      end
+    end
+
+    # Finds the AST node for a Method or UnboundMethod using best-effort line
+    # matching. Used on non-CRuby implementations.
+    class LineMethodFind < Find
+      # Find the node for the given method by matching on name and line.
+      #
+      #: (Method | UnboundMethod callable) -> Node?
+      def find(callable)
+        return unless (source_location = callable.source_location)
+        return unless (result = parse_file(source_location[0]))
+
+        name = callable.name
+        start_line = source_location[1]
+
+        result.value.find do |node|
+          case node
+          when DefNode
+            node.name == name && node.location.start_line == start_line
+          when CallNode
+            node.block.is_a?(BlockNode) && node.location.start_line == start_line
+          else
+            false
+          end
+        end
+      end
+    end
+
+    # Finds the AST node for a lambda using best-effort line matching. Used
+    # on non-CRuby implementations.
+    class LineLambdaFind < Find
+      # Find the node for the given lambda by matching on line.
+      #
+      #: (Proc callable) -> Node?
+      def find(callable)
+        return unless (source_location = callable.source_location)
+        return unless (result = parse_file(source_location[0]))
+
+        start_line = source_location[1]
+
+        result.value.find do |node|
+          case node
+          when LambdaNode
+            node.location.start_line == start_line
+          when CallNode
+            node.block.is_a?(BlockNode) && node.location.start_line == start_line
+          else
+            false
+          end
+        end
+      end
+    end
+
+    # Finds the AST node for a non-lambda Proc using best-effort line
+    # matching. Used on non-CRuby implementations.
+    class LineProcFind < Find
+      # Find the node for the given proc by matching on line.
+      #
+      #: (Proc callable) -> Node?
+      def find(callable)
+        return unless (source_location = callable.source_location)
+        return unless (result = parse_file(source_location[0]))
+
+        start_line = source_location[1]
+
+        result.value.find do |node|
+          case node
+          when ForNode
+            node.location.start_line == start_line
+          when CallNode
+            node.block.is_a?(BlockNode) && node.location.start_line == start_line
+          else
+            false
+          end
+        end
+      end
+    end
+
+    # Finds the AST node for a Thread::Backtrace::Location using best-effort
+    # line matching. Used on non-CRuby implementations.
+    class LineBacktraceLocationFind < Find
+      # Find the node for the given backtrace location by matching on line.
+      #
+      #: (Thread::Backtrace::Location location) -> Node?
+      def find(location)
+        file = location.absolute_path || location.path
+        return unless (result = parse_file(file))
+
+        start_line = location.lineno
+        result.value.find { |node| node.location.start_line == start_line }
+      end
+    end
+  end
+end

data/lib/prism/parse_result/errors.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 # :markup: markdown
+#--
+# rbs_inline: enabled
 
 require "stringio"
 
@@ -9,14 +11,18 @@ module Prism
     # can be used to format the errors in a human-readable way.
     class Errors
       # The parse result that contains the errors.
-      attr_reader :parse_result
+      attr_reader :parse_result #: ParseResult
 
       # Initialize a new set of errors from the given parse result.
+      #
+      #: (ParseResult parse_result) -> void
       def initialize(parse_result)
         @parse_result = parse_result
       end
 
       # Formats the errors in a human-readable way and return them as a string.
+      #
+      #: () -> String
       def format
         error_lines = {} #: Hash[Integer, Array[ParseError]]
         parse_result.errors.each do |error|

data/lib/prism/parse_result/newlines.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 # :markup: markdown
+#--
+# rbs_inline: enabled
 
 module Prism
   class ParseResult < Result
@@ -24,13 +26,20 @@ module Prism
     # that case. We do that to avoid storing the extra `@newline` instance
     # variable on every node if we don't need it.
     class Newlines < Visitor
+      # The map of lines indices to whether or not they have been marked as
+      # emitting a newline event.
+      # @rbs @lines: Array[bool]
+
       # Create a new Newlines visitor with the given newline offsets.
+      #
+      #: (Integer lines) -> void
       def initialize(lines)
-        # @type var lines: Integer
         @lines = Array.new(1 + lines, false)
       end
 
-      # Permit block/lambda nodes to mark newlines within themselves.
+      # Permit block nodes to mark newlines within themselves.
+      #
+      #: (BlockNode node) -> void
       def visit_block_node(node)
         old_lines = @lines
         @lines = Array.new(old_lines.size, false)
@@ -42,17 +51,150 @@ module Prism
         end
       end
 
-      alias_method :visit_lambda_node, :visit_block_node
+      # Permit lambda nodes to mark newlines within themselves.
+      #
+      #: (LambdaNode node) -> void
+      def visit_lambda_node(node)
+        old_lines = @lines
+        @lines = Array.new(old_lines.size, false)
+
+        begin
+          super(node)
+        ensure
+          @lines = old_lines
+        end
+      end
+
+      # Permit def nodes to mark newlines within themselves. The body of an
+      # endless method definition never emits newline events, so in that case
+      # mark every line as already seen while visiting it instead. Nested
+      # scopes (blocks, lambdas, etc.) reset the lines and emit events again.
+      #
+      #: (DefNode node) -> void
+      def visit_def_node(node)
+        old_lines = @lines
+        @lines = Array.new(old_lines.size, !node.equal_loc.nil?)
+
+        begin
+          super(node)
+        ensure
+          @lines = old_lines
+        end
+      end
+
+      # Permit class nodes to mark newlines within themselves.
+      #
+      #: (ClassNode node) -> void
+      def visit_class_node(node)
+        old_lines = @lines
+        @lines = Array.new(old_lines.size, false)
+
+        begin
+          super(node)
+        ensure
+          @lines = old_lines
+        end
+      end
+
+      # Permit module nodes to mark newlines within themselves.
+      #
+      #: (ModuleNode node) -> void
+      def visit_module_node(node)
+        old_lines = @lines
+        @lines = Array.new(old_lines.size, false)
+
+        begin
+          super(node)
+        ensure
+          @lines = old_lines
+        end
+      end
+
+      # Permit singleton class nodes to mark newlines within themselves.
+      #
+      #: (SingletonClassNode node) -> void
+      def visit_singleton_class_node(node)
+        old_lines = @lines
+        @lines = Array.new(old_lines.size, false)
+
+        begin
+          super(node)
+        ensure
+          @lines = old_lines
+        end
+      end
+
+      # Statements inside string interpolation do not emit newline events, so
+      # mark every line as already seen while visiting them. Nested scopes
+      # (blocks, lambdas, defs, etc.) reset the lines and emit events again.
+      #
+      #: (EmbeddedStatementsNode node) -> void
+      def visit_embedded_statements_node(node)
+        old_lines = @lines
+        @lines = Array.new(old_lines.size, true)
+
+        begin
+          super(node)
+        ensure
+          @lines = old_lines
+        end
+      end
+
+      # The predicate of a while loop is compiled at the end of the loop,
+      # after the body, so any statements it contains (from parentheses)
+      # emit their line events again even if the lines were already seen.
+      #
+      #: (WhileNode node) -> void
+      def visit_while_node(node)
+        old_lines = @lines
+        @lines = Array.new(old_lines.size, false)
+
+        begin
+          visit(node.predicate)
+        ensure
+          @lines = old_lines
+        end
+
+        visit(node.statements)
+      end
+
+      # The predicate of an until loop is compiled at the end of the loop,
+      # after the body, so any statements it contains (from parentheses)
+      # emit their line events again even if the lines were already seen.
+      #
+      #: (UntilNode node) -> void
+      def visit_until_node(node)
+        old_lines = @lines
+        @lines = Array.new(old_lines.size, false)
 
-      # Mark if/unless nodes as newlines.
+        begin
+          visit(node.predicate)
+        ensure
+          @lines = old_lines
+        end
+
+        visit(node.statements)
+      end
+
+      # Mark if nodes as newlines.
+      #
+      #: (IfNode node) -> void
       def visit_if_node(node)
         node.newline_flag!(@lines)
         super(node)
       end
 
-      alias_method :visit_unless_node, :visit_if_node
+      # Mark unless nodes as newlines.
+      #
+      #: (UnlessNode node) -> void
+      def visit_unless_node(node)
+        node.newline_flag!(@lines)
+        super(node)
+      end
 
       # Permit statements lists to mark newlines within themselves.
+      #
+      #: (StatementsNode node) -> void
       def visit_statements_node(node)
         node.body.each do |child|
           child.newline_flag!(@lines)
@@ -63,10 +205,16 @@ module Prism
   end
 
   class Node
+    # Tracks whether or not this node should emit a newline event when the
+    # instructions that it represents are executed.
+    # @rbs @newline_flag: bool
+
+    #: () -> bool
     def newline_flag? # :nodoc:
       !!defined?(@newline_flag)
     end
 
+    #: (Array[bool] lines) -> void
     def newline_flag!(lines) # :nodoc:
       line = location.start_line
       unless lines[line]
@@ -77,48 +225,160 @@ module Prism
   end
 
   class BeginNode < Node
+    #: (Array[bool] lines) -> void
     def newline_flag!(lines) # :nodoc:
       # Never mark BeginNode with a newline flag, mark children instead.
     end
   end
 
   class ParenthesesNode < Node
+    #: (Array[bool] lines) -> void
     def newline_flag!(lines) # :nodoc:
       # Never mark ParenthesesNode with a newline flag, mark children instead.
     end
   end
 
   class IfNode < Node
+    #: (Array[bool] lines) -> void
     def newline_flag!(lines) # :nodoc:
       predicate.newline_flag!(lines)
     end
   end
 
   class UnlessNode < Node
+    #: (Array[bool] lines) -> void
     def newline_flag!(lines) # :nodoc:
       predicate.newline_flag!(lines)
     end
   end
 
   class UntilNode < Node
+    #: (Array[bool] lines) -> void
     def newline_flag!(lines) # :nodoc:
-      predicate.newline_flag!(lines)
+      if location.start_offset == keyword_loc.start_offset && predicate.is_a?(ParenthesesNode)
+        # A parenthesized predicate emits its own line event when it is
+        # compiled at the end of the loop, in addition to this one.
+        super
+      else
+        predicate.newline_flag!(lines)
+      end
     end
   end
 
   class WhileNode < Node
+    #: (Array[bool] lines) -> void
     def newline_flag!(lines) # :nodoc:
-      predicate.newline_flag!(lines)
+      if location.start_offset == keyword_loc.start_offset && predicate.is_a?(ParenthesesNode)
+        # A parenthesized predicate emits its own line event when it is
+        # compiled at the end of the loop, in addition to this one.
+        super
+      else
+        predicate.newline_flag!(lines)
+      end
     end
   end
 
   class RescueModifierNode < Node
+    #: (Array[bool] lines) -> void
     def newline_flag!(lines) # :nodoc:
       expression.newline_flag!(lines)
     end
   end
 
+  # The line event for a statement is emitted where its first instruction is
+  # compiled, so nodes whose first instruction comes from a sub-expression
+  # delegate their newline flag to that sub-expression: assignments to their
+  # value, calls to their receiver, and array, hash, and interpolated string
+  # literals to their first element. Static literals are the exception: they
+  # are compiled to a single instruction on the first line of the literal, so
+  # they do not delegate.
+
+  class LocalVariableWriteNode < Node
+    #: (Array[bool] lines) -> void
+    def newline_flag!(lines) # :nodoc:
+      value.newline_flag!(lines)
+    end
+  end
+
+  class InstanceVariableWriteNode < Node
+    #: (Array[bool] lines) -> void
+    def newline_flag!(lines) # :nodoc:
+      value.newline_flag!(lines)
+    end
+  end
+
+  class ClassVariableWriteNode < Node
+    #: (Array[bool] lines) -> void
+    def newline_flag!(lines) # :nodoc:
+      value.newline_flag!(lines)
+    end
+  end
+
+  class GlobalVariableWriteNode < Node
+    #: (Array[bool] lines) -> void
+    def newline_flag!(lines) # :nodoc:
+      value.newline_flag!(lines)
+    end
+  end
+
+  class ConstantWriteNode < Node
+    #: (Array[bool] lines) -> void
+    def newline_flag!(lines) # :nodoc:
+      value.newline_flag!(lines)
+    end
+  end
+
+  class ConstantPathWriteNode < Node
+    #: (Array[bool] lines) -> void
+    def newline_flag!(lines) # :nodoc:
+      value.newline_flag!(lines)
+    end
+  end
+
+  class MultiWriteNode < Node
+    #: (Array[bool] lines) -> void
+    def newline_flag!(lines) # :nodoc:
+      value.newline_flag!(lines)
+    end
+  end
+
+  class CallNode < Node
+    #: (Array[bool] lines) -> void
+    def newline_flag!(lines) # :nodoc:
+      if (receiver = self.receiver)
+        receiver.newline_flag!(lines)
+      else
+        super
+      end
+    end
+  end
+
+  class ArrayNode < Node
+    #: (Array[bool] lines) -> void
+    def newline_flag!(lines) # :nodoc:
+      first = elements.first
+      if first && !static_literal?
+        first.newline_flag!(lines)
+      else
+        super
+      end
+    end
+  end
+
+  class HashNode < Node
+    #: (Array[bool] lines) -> void
+    def newline_flag!(lines) # :nodoc:
+      first = elements.first
+      if first && !static_literal?
+        first.newline_flag!(lines)
+      else
+        super
+      end
+    end
+  end
+
   class InterpolatedMatchLastLineNode < Node
+    #: (Array[bool] lines) -> void
     def newline_flag!(lines) # :nodoc:
       first = parts.first
       first.newline_flag!(lines) if first
@@ -126,6 +386,7 @@ module Prism
   end
 
   class InterpolatedRegularExpressionNode < Node
+    #: (Array[bool] lines) -> void
     def newline_flag!(lines) # :nodoc:
       first = parts.first
       first.newline_flag!(lines) if first
@@ -133,13 +394,19 @@ module Prism
   end
 
   class InterpolatedStringNode < Node
+    #: (Array[bool] lines) -> void
     def newline_flag!(lines) # :nodoc:
       first = parts.first
-      first.newline_flag!(lines) if first
+      if first && !static_literal?
+        first.newline_flag!(lines)
+      else
+        super
+      end
     end
   end
 
   class InterpolatedSymbolNode < Node
+    #: (Array[bool] lines) -> void
     def newline_flag!(lines) # :nodoc:
       first = parts.first
       first.newline_flag!(lines) if first
@@ -147,6 +414,7 @@ module Prism
   end
 
   class InterpolatedXStringNode < Node
+    #: (Array[bool] lines) -> void
     def newline_flag!(lines) # :nodoc:
       first = parts.first
       first.newline_flag!(lines) if first