syntax_tree 5.3.0 → 6.0.0

data/lib/syntax_tree/translation/rubocop_ast.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module SyntaxTree
+  module Translation
+    # This visitor is responsible for converting the syntax tree produced by
+    # Syntax Tree into the syntax tree produced by the rubocop/rubocop-ast gem.
+    class RuboCopAST < Parser
+      private
+
+      # This method is effectively the same thing as the parser gem except that
+      # it uses the rubocop-ast specializations of the nodes.
+      def s(type, children, location)
+        ::RuboCop::AST::Builder::NODE_MAP.fetch(type, ::RuboCop::AST::Node).new(
+          type,
+          children,
+          location: location
+        )
+      end
+    end
+  end
+end

data/lib/syntax_tree/translation.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module SyntaxTree
+  # This module is responsible for translating the Syntax Tree syntax tree into
+  # other representations.
+  module Translation
+    # This method translates the given node into the representation defined by
+    # the whitequark/parser gem. We don't explicitly list it as a dependency
+    # because it's not required for the core functionality of Syntax Tree.
+    def self.to_parser(node, buffer)
+      require "parser"
+      require_relative "translation/parser"
+
+      node.accept(Parser.new(buffer))
+    end
+
+    # This method translates the given node into the representation defined by
+    # the rubocop/rubocop-ast gem. We don't explicitly list it as a dependency
+    # because it's not required for the core functionality of Syntax Tree.
+    def self.to_rubocop_ast(node, buffer)
+      require "rubocop/ast"
+      require_relative "translation/parser"
+      require_relative "translation/rubocop_ast"
+
+      node.accept(RuboCopAST.new(buffer))
+    end
+  end
+end

data/lib/syntax_tree/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SyntaxTree
-  VERSION = "5.3.0"
+  VERSION = "6.0.0"
 end

data/lib/syntax_tree/with_scope.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+module SyntaxTree
+  # WithScope is a module intended to be included in classes inheriting from
+  # Visitor. The module overrides a few visit methods to automatically keep
+  # track of local variables and arguments defined in the current scope.
+  # Example usage:
+  #
+  #     class MyVisitor < Visitor
+  #       include WithScope
+  #
+  #       def visit_ident(node)
+  #         # Check if we're visiting an identifier for an argument, a local
+  #         # variable or something else
+  #         local = current_scope.find_local(node)
+  #
+  #         if local.type == :argument
+  #           # handle identifiers for arguments
+  #         elsif local.type == :variable
+  #           # handle identifiers for variables
+  #         else
+  #           # handle other identifiers, such as method names
+  #         end
+  #       end
+  #     end
+  #
+  module WithScope
+    # The scope class is used to keep track of local variables and arguments
+    # inside a particular scope.
+    class Scope
+      # This class tracks the occurrences of a local variable or argument.
+      class Local
+        # [Symbol] The type of the local (e.g. :argument, :variable)
+        attr_reader :type
+
+        # [Array[Location]] The locations of all definitions and assignments of
+        # this local
+        attr_reader :definitions
+
+        # [Array[Location]] The locations of all usages of this local
+        attr_reader :usages
+
+        def initialize(type)
+          @type = type
+          @definitions = []
+          @usages = []
+        end
+
+        def add_definition(location)
+          @definitions << location
+        end
+
+        def add_usage(location)
+          @usages << location
+        end
+      end
+
+      # [Integer] a unique identifier for this scope
+      attr_reader :id
+
+      # [scope | nil] The parent scope
+      attr_reader :parent
+
+      # [Hash[String, Local]] The local variables and arguments defined in this
+      # scope
+      attr_reader :locals
+
+      def initialize(id, parent = nil)
+        @id = id
+        @parent = parent
+        @locals = {}
+      end
+
+      # Adding a local definition will either insert a new entry in the locals
+      # hash or append a new definition location to an existing local. Notice
+      # that it's not possible to change the type of a local after it has been
+      # registered.
+      def add_local_definition(identifier, type)
+        name = identifier.value.delete_suffix(":")
+
+        local =
+          if type == :argument
+            locals[name] ||= Local.new(type)
+          else
+            resolve_local(name, type)
+          end
+
+        local.add_definition(identifier.location)
+      end
+
+      # Adding a local usage will either insert a new entry in the locals
+      # hash or append a new usage location to an existing local. Notice that
+      # it's not possible to change the type of a local after it has been
+      # registered.
+      def add_local_usage(identifier, type)
+        name = identifier.value.delete_suffix(":")
+        resolve_local(name, type).add_usage(identifier.location)
+      end
+
+      # Try to find the local given its name in this scope or any of its
+      # parents.
+      def find_local(name)
+        locals[name] || parent&.find_local(name)
+      end
+
+      private
+
+      def resolve_local(name, type)
+        local = find_local(name)
+
+        unless local
+          local = Local.new(type)
+          locals[name] = local
+        end
+
+        local
+      end
+    end
+
+    attr_reader :current_scope
+
+    def initialize(*args, **kwargs, &block)
+      super
+
+      @current_scope = Scope.new(0)
+      @next_scope_id = 0
+    end
+
+    # Visits for nodes that create new scopes, such as classes, modules
+    # and method definitions.
+    def visit_class(node)
+      with_scope { super }
+    end
+
+    def visit_module(node)
+      with_scope { super }
+    end
+
+    # When we find a method invocation with a block, only the code that happens
+    # inside of the block needs a fresh scope. The method invocation
+    # itself happens in the same scope.
+    def visit_method_add_block(node)
+      visit(node.call)
+      with_scope(current_scope) { visit(node.block) }
+    end
+
+    def visit_def(node)
+      with_scope { super }
+    end
+
+    # Visit for keeping track of local arguments, such as method and block
+    # arguments.
+    def visit_params(node)
+      add_argument_definitions(node.requireds)
+
+      node.posts.each do |param|
+        current_scope.add_local_definition(param, :argument)
+      end
+
+      node.keywords.each do |param|
+        current_scope.add_local_definition(param.first, :argument)
+      end
+
+      node.optionals.each do |param|
+        current_scope.add_local_definition(param.first, :argument)
+      end
+
+      super
+    end
+
+    def visit_rest_param(node)
+      name = node.name
+      current_scope.add_local_definition(name, :argument) if name
+
+      super
+    end
+
+    def visit_kwrest_param(node)
+      name = node.name
+      current_scope.add_local_definition(name, :argument) if name
+
+      super
+    end
+
+    def visit_blockarg(node)
+      name = node.name
+      current_scope.add_local_definition(name, :argument) if name
+
+      super
+    end
+
+    # Visit for keeping track of local variable definitions
+    def visit_var_field(node)
+      value = node.value
+      current_scope.add_local_definition(value, :variable) if value.is_a?(Ident)
+
+      super
+    end
+
+    # Visit for keeping track of local variable definitions
+    def visit_pinned_var_ref(node)
+      value = node.value
+      current_scope.add_local_usage(value, :variable) if value.is_a?(Ident)
+
+      super
+    end
+
+    # Visits for keeping track of variable and argument usages
+    def visit_var_ref(node)
+      value = node.value
+
+      if value.is_a?(Ident)
+        definition = current_scope.find_local(value.value)
+        current_scope.add_local_usage(value, definition.type) if definition
+      end
+
+      super
+    end
+
+    private
+
+    def add_argument_definitions(list)
+      list.each do |param|
+        if param.is_a?(SyntaxTree::MLHSParen)
+          add_argument_definitions(param.contents.parts)
+        else
+          current_scope.add_local_definition(param, :argument)
+        end
+      end
+    end
+
+    def next_scope_id
+      @next_scope_id += 1
+    end
+
+    def with_scope(parent_scope = nil)
+      previous_scope = @current_scope
+      @current_scope = Scope.new(next_scope_id, parent_scope)
+      yield
+    ensure
+      @current_scope = previous_scope
+    end
+  end
+end

data/lib/syntax_tree/yarv/basic_block.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module SyntaxTree
+  module YARV
+    # This object represents a single basic block, wherein all contained
+    # instructions do not branch except for the last one.
+    class BasicBlock
+      # This is the unique identifier for this basic block.
+      attr_reader :id
+
+      # This is the index into the list of instructions where this block starts.
+      attr_reader :block_start
+
+      # This is the set of instructions that this block contains.
+      attr_reader :insns
+
+      # This is an array of basic blocks that lead into this block.
+      attr_reader :incoming_blocks
+
+      # This is an array of basic blocks that this block leads into.
+      attr_reader :outgoing_blocks
+
+      def initialize(block_start, insns)
+        @id = "block_#{block_start}"
+
+        @block_start = block_start
+        @insns = insns
+
+        @incoming_blocks = []
+        @outgoing_blocks = []
+      end
+
+      # Yield each instruction in this basic block along with its index from the
+      # original instruction sequence.
+      def each_with_length
+        return enum_for(:each_with_length) unless block_given?
+
+        length = block_start
+        insns.each do |insn|
+          yield insn, length
+          length += insn.length
+        end
+      end
+
+      # This method is used to verify that the basic block is well formed. It
+      # checks that the only instruction in this basic block that branches is
+      # the last instruction.
+      def verify
+        insns[0...-1].each { |insn| raise unless insn.branch_targets.empty? }
+      end
+    end
+  end
+end

data/lib/syntax_tree/yarv/calldata.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module SyntaxTree
+  module YARV
+    # This is an operand to various YARV instructions that represents the
+    # information about a specific call site.
+    class CallData
+      CALL_ARGS_SPLAT = 1 << 0
+      CALL_ARGS_BLOCKARG = 1 << 1
+      CALL_FCALL = 1 << 2
+      CALL_VCALL = 1 << 3
+      CALL_ARGS_SIMPLE = 1 << 4
+      CALL_BLOCKISEQ = 1 << 5
+      CALL_KWARG = 1 << 6
+      CALL_KW_SPLAT = 1 << 7
+      CALL_TAILCALL = 1 << 8
+      CALL_SUPER = 1 << 9
+      CALL_ZSUPER = 1 << 10
+      CALL_OPT_SEND = 1 << 11
+      CALL_KW_SPLAT_MUT = 1 << 12
+
+      attr_reader :method, :argc, :flags, :kw_arg
+
+      def initialize(
+        method,
+        argc = 0,
+        flags = CallData::CALL_ARGS_SIMPLE,
+        kw_arg = nil
+      )
+        @method = method
+        @argc = argc
+        @flags = flags
+        @kw_arg = kw_arg
+      end
+
+      def flag?(mask)
+        (flags & mask) > 0
+      end
+
+      def to_h
+        result = { mid: method, flag: flags, orig_argc: argc }
+        result[:kw_arg] = kw_arg if kw_arg
+        result
+      end
+
+      def inspect
+        names = []
+        names << :ARGS_SPLAT if flag?(CALL_ARGS_SPLAT)
+        names << :ARGS_BLOCKARG if flag?(CALL_ARGS_BLOCKARG)
+        names << :FCALL if flag?(CALL_FCALL)
+        names << :VCALL if flag?(CALL_VCALL)
+        names << :ARGS_SIMPLE if flag?(CALL_ARGS_SIMPLE)
+        names << :BLOCKISEQ if flag?(CALL_BLOCKISEQ)
+        names << :KWARG if flag?(CALL_KWARG)
+        names << :KW_SPLAT if flag?(CALL_KW_SPLAT)
+        names << :TAILCALL if flag?(CALL_TAILCALL)
+        names << :SUPER if flag?(CALL_SUPER)
+        names << :ZSUPER if flag?(CALL_ZSUPER)
+        names << :OPT_SEND if flag?(CALL_OPT_SEND)
+        names << :KW_SPLAT_MUT if flag?(CALL_KW_SPLAT_MUT)
+
+        parts = []
+        parts << "mid:#{method}" if method
+        parts << "argc:#{argc}"
+        parts << "kw:[#{kw_arg.join(", ")}]" if kw_arg
+        parts << names.join("|") if names.any?
+
+        "<calldata!#{parts.join(", ")}>"
+      end
+
+      def self.from(serialized)
+        new(
+          serialized[:mid],
+          serialized[:orig_argc],
+          serialized[:flag],
+          serialized[:kw_arg]
+        )
+      end
+    end
+
+    # A convenience method for creating a CallData object.
+    def self.calldata(
+      method,
+      argc = 0,
+      flags = CallData::CALL_ARGS_SIMPLE,
+      kw_arg = nil
+    )
+      CallData.new(method, argc, flags, kw_arg)
+    end
+  end
+end

data/lib/syntax_tree/yarv/compiler.rb

@@ -8,7 +8,7 @@ module SyntaxTree
     #
     # You use this as with any other visitor. First you parse code into a tree,
     # then you visit it with this compiler. Visiting the root node of the tree
-    # will return a SyntaxTree::Visitor::Compiler::InstructionSequence object.
+    # will return a SyntaxTree::YARV::Compiler::InstructionSequence object.
     # With that object you can call #to_a on it, which will return a serialized
     # form of the instruction sequence as an array. This array _should_ mirror
     # the array given by RubyVM::InstructionSequence#to_a.
@@ -124,76 +124,122 @@ module SyntaxTree
         rescue CompilationError
         end
 
-        def visit_array(node)
-          node.contents ? visit_all(node.contents.parts) : []
-        end
+        visit_methods do
+          def visit_array(node)
+            node.contents ? visit_all(node.contents.parts) : []
+          end
 
-        def visit_bare_assoc_hash(node)
-          node.assocs.to_h do |assoc|
-            # We can only convert regular key-value pairs. A double splat **
-            # operator means it has to be converted at run-time.
-            raise CompilationError unless assoc.is_a?(Assoc)
-            [visit(assoc.key), visit(assoc.value)]
+          def visit_bare_assoc_hash(node)
+            node.assocs.to_h do |assoc|
+              # We can only convert regular key-value pairs. A double splat **
+              # operator means it has to be converted at run-time.
+              raise CompilationError unless assoc.is_a?(Assoc)
+              [visit(assoc.key), visit(assoc.value)]
+            end
           end
-        end
 
-        def visit_float(node)
-          node.value.to_f
-        end
+          def visit_float(node)
+            node.value.to_f
+          end
 
-        alias visit_hash visit_bare_assoc_hash
+          alias visit_hash visit_bare_assoc_hash
 
-        def visit_imaginary(node)
-          node.value.to_c
-        end
+          def visit_imaginary(node)
+            node.value.to_c
+          end
 
-        def visit_int(node)
-          case (value = node.value)
-          when /^0b/
-            value[2..].to_i(2)
-          when /^0o/
-            value[2..].to_i(8)
-          when /^0d/
-            value[2..].to_i
-          when /^0x/
-            value[2..].to_i(16)
-          else
-            value.to_i
+          def visit_int(node)
+            case (value = node.value)
+            when /^0b/
+              value[2..].to_i(2)
+            when /^0o/
+              value[2..].to_i(8)
+            when /^0d/
+              value[2..].to_i
+            when /^0x/
+              value[2..].to_i(16)
+            else
+              value.to_i
+            end
           end
-        end
 
-        def visit_label(node)
-          node.value.chomp(":").to_sym
-        end
+          def visit_label(node)
+            node.value.chomp(":").to_sym
+          end
 
-        def visit_mrhs(node)
-          visit_all(node.parts)
-        end
+          def visit_mrhs(node)
+            visit_all(node.parts)
+          end
 
-        def visit_qsymbols(node)
-          node.elements.map { |element| visit(element).to_sym }
-        end
+          def visit_qsymbols(node)
+            node.elements.map { |element| visit(element).to_sym }
+          end
 
-        def visit_qwords(node)
-          visit_all(node.elements)
-        end
+          def visit_qwords(node)
+            visit_all(node.elements)
+          end
 
-        def visit_range(node)
-          left, right = [visit(node.left), visit(node.right)]
-          node.operator.value === ".." ? left..right : left...right
-        end
+          def visit_range(node)
+            left, right = [visit(node.left), visit(node.right)]
+            node.operator.value === ".." ? left..right : left...right
+          end
 
-        def visit_rational(node)
-          node.value.to_r
-        end
+          def visit_rational(node)
+            node.value.to_r
+          end
 
-        def visit_regexp_literal(node)
-          if node.parts.length == 1 && node.parts.first.is_a?(TStringContent)
-            Regexp.new(node.parts.first.value, visit_regexp_literal_flags(node))
-          else
-            # Any interpolation of expressions or variables will result in the
-            # regular expression being constructed at run-time.
-            raise CompilationError
+          def visit_regexp_literal(node)
+            if node.parts.length == 1 && node.parts.first.is_a?(TStringContent)
+              Regexp.new(
+                node.parts.first.value,
+                visit_regexp_literal_flags(node)
+              )
+            else
+              # Any interpolation of expressions or variables will result in the
+              # regular expression being constructed at run-time.
+              raise CompilationError
+            end
+          end
+
+          def visit_symbol_literal(node)
+            node.value.value.to_sym
+          end
+
+          def visit_symbols(node)
+            node.elements.map { |element| visit(element).to_sym }
+          end
+
+          def visit_tstring_content(node)
+            node.value
+          end
+
+          def visit_var_ref(node)
+            raise CompilationError unless node.value.is_a?(Kw)
+
+            case node.value.value
+            when "nil"
+              nil
+            when "true"
+              true
+            when "false"
+              false
+            else
+              raise CompilationError
+            end
+          end
+
+          def visit_word(node)
+            if node.parts.length == 1 && node.parts.first.is_a?(TStringContent)
+              node.parts.first.value
+            else
+              # Any interpolation of expressions or variables will result in the
+              # string being constructed at run-time.
+              raise CompilationError
+            end
+          end
+
+          def visit_words(node)
+            visit_all(node.elements)
           end
         end
 
@@ -219,47 +265,6 @@ module SyntaxTree
             end
         end
 
-        def visit_symbol_literal(node)
-          node.value.value.to_sym
-        end
-
-        def visit_symbols(node)
-          node.elements.map { |element| visit(element).to_sym }
-        end
-
-        def visit_tstring_content(node)
-          node.value
-        end
-
-        def visit_var_ref(node)
-          raise CompilationError unless node.value.is_a?(Kw)
-
-          case node.value.value
-          when "nil"
-            nil
-          when "true"
-            true
-          when "false"
-            false
-          else
-            raise CompilationError
-          end
-        end
-
-        def visit_word(node)
-          if node.parts.length == 1 && node.parts.first.is_a?(TStringContent)
-            node.parts.first.value
-          else
-            # Any interpolation of expressions or variables will result in the
-            # string being constructed at run-time.
-            raise CompilationError
-          end
-        end
-
-        def visit_words(node)
-          visit_all(node.elements)
-        end
-
         def visit_unsupported(_node)
           raise CompilationError
         end
@@ -1050,11 +1055,16 @@ module SyntaxTree
         visit_if(
           IfNode.new(
             predicate: node.predicate,
-            statements: node.truthy,
+            statements:
+              Statements.new(body: [node.truthy], location: Location.default),
             consequent:
               Else.new(
                 keyword: Kw.new(value: "else", location: Location.default),
-                statements: node.falsy,
+                statements:
+                  Statements.new(
+                    body: [node.falsy],
+                    location: Location.default
+                  ),
                 location: Location.default
               ),
             location: Location.default