rubocop-ast 0.0.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4c380d9edb3f0bdbdb8d7d9822b25cd96f9d23b7428bf8e8c56e4e19cf5628b
-  data.tar.gz: 3568dc3fabb7c2d6b0575c9dc07341b4bb0b5daf6d65e284fdd524000a7de019
+  metadata.gz: 918c6017183db74497fc68166973904312bac7583f7752c2e55d1829574cb248
+  data.tar.gz: 1d04eb24fcbaec96b4bf0f17694018c31034fce4b3d81a9446ca98b3085e05a4
 SHA512:
-  metadata.gz: 228b11a44b85a2bb3467afad8d28aadd65d7864ee7a5639773b007bcb2b9eef37ef2daff14d923730ec1b50cf3b7bfd96556ba3573e179615b9c7aba7d787480
-  data.tar.gz: 061d70e99b00be1f84ab91d18cab96a97829e1ee5a62ef615013eae5994b72f67aa0b6101b64bf0715de6b863ebf60022849b1930ed7e306ff841d86bff39d60
+  metadata.gz: 54f6882ebf057c76a9c97212a62b295d03baea85ec7c44e606b412e74edce01b6c4bba93dfafa341756009a8bfa2352c4b2b3b22bdbf689dac08ddd9395a9aff
+  data.tar.gz: '08e60b802e83dba688bf1a31be417f9880b640194cf3b966849dd2c211de5a1f3797c8a37be3f2d3aa466d6c994b10c31277b0ed3dc708b12fe1c2f7a0f15552'

data/README.md

@@ -1,11 +1,17 @@
 # RuboCop AST
 
 [![Gem Version](https://badge.fury.io/rb/rubocop-ast.svg)](https://badge.fury.io/rb/rubocop-ast)
-[![CircleCI](https://circleci.com/gh/rubocop-hq/rubocop-ast.svg?style=svg)](https://circleci.com/gh/rubocop-hq/rubocop-ast)
+[![CI](https://github.com/rubocop-hq/rubocop-ast/workflows/CI/badge.svg)](https://github.com/rubocop-hq/rubocop-ast/actions?query=workflow%3ACI)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/a29666e6373bc41bc0a9/test_coverage)](https://codeclimate.com/github/rubocop-hq/rubocop-ast/test_coverage)
+[![Maintainability](https://api.codeclimate.com/v1/badges/a29666e6373bc41bc0a9/maintainability)](https://codeclimate.com/github/rubocop-hq/rubocop-ast/maintainability)
 
 Contains the classes needed by [RuboCop](https://github.com/rubocop-hq/rubocop) to deal with Ruby's AST, in particular:
-* `RuboCop::AST::Node`
-* `RuboCop::NodePattern`
+
+* `RuboCop::AST::Node` ([doc](docs/modules/ROOT/pages/node_types.adoc))
+* `RuboCop::AST::NodePattern` ([doc](docs/modules/ROOT/pages/node_pattern.adoc))
+
+This gem may be used independently from the main RuboCop gem. It was extracted from RuboCop in version 0.84 and its only
+dependency is the [parser](https://github.com/whitequark/parser) gem, which `rubocop-ast` extends.
 
 ## Installation
 
@@ -23,7 +29,20 @@ gem 'rubocop-ast'
 
 ## Usage
 
-Refer to the documentation of `RuboCop::AST::Node` and [`RuboCop::NodePattern`](manual/node_pattern.md)
+Refer to the documentation of [`RuboCop::AST::Node`](docs/modules/ROOT/pages/node_types.adoc) and [`RuboCop::AST::NodePattern`](docs/modules/ROOT/pages/node_pattern.adoc)
+
+See the [docs site](https://docs.rubocop.org/rubocop-ast) for more details.
+
+### Parser compatibility switches
+
+This gem, by default, uses most [legacy AST output from parser](https://github.com/whitequark/parser/#usage), except for `emit_forward_arg` which is set to `true`.
+
+The main `RuboCop` gem uses these defaults (and is currently only compatible with these), but this gem can be used separately from `RuboCop` and is meant to be compatible with all settings. For example, to have `-> { ... }` emitted
+as `LambdaNode` instead of `SendNode`:
+
+```ruby
+RuboCop::AST::Builder.emit_lambda = true
+```
 
 ## Contributing
 

data/lib/rubocop/ast.rb

@@ -2,10 +2,10 @@
 
 require 'parser'
 require 'forwardable'
+require 'set'
 
-require_relative 'error'
-require_relative 'node_pattern'
-
+require_relative 'ast/ext/range'
+require_relative 'ast/node_pattern'
 require_relative 'ast/sexp'
 require_relative 'ast/node'
 require_relative 'ast/node/mixin/method_identifier_predicates'
@@ -36,15 +36,18 @@ require_relative 'ast/node/forward_args_node'
 require_relative 'ast/node/float_node'
 require_relative 'ast/node/hash_node'
 require_relative 'ast/node/if_node'
+require_relative 'ast/node/index_node'
+require_relative 'ast/node/indexasgn_node'
 require_relative 'ast/node/int_node'
 require_relative 'ast/node/keyword_splat_node'
+require_relative 'ast/node/lambda_node'
 require_relative 'ast/node/module_node'
+require_relative 'ast/node/next_node'
 require_relative 'ast/node/or_node'
 require_relative 'ast/node/pair_node'
 require_relative 'ast/node/range_node'
 require_relative 'ast/node/regexp_node'
 require_relative 'ast/node/resbody_node'
-require_relative 'ast/node/retry_node'
 require_relative 'ast/node/return_node'
 require_relative 'ast/node/self_class_node'
 require_relative 'ast/node/send_node'
@@ -56,7 +59,7 @@ require_relative 'ast/node/when_node'
 require_relative 'ast/node/while_node'
 require_relative 'ast/node/yield_node'
 require_relative 'ast/builder'
+require_relative 'ast/processed_source'
+require_relative 'ast/token'
 require_relative 'ast/traversal'
-
-require_relative 'token'
-require_relative 'processed_source'
+require_relative 'ast/version'

data/lib/rubocop/ast/builder.rb

@@ -14,6 +14,8 @@ module RuboCop
     #   parser = Parser::Ruby25.new(builder)
     #   root_node = parser.parse(buffer)
     class Builder < Parser::Builders::Default
+      self.emit_forward_arg = true
+
       NODE_MAP = {
         and:          AndNode,
         alias:        AliasNode,
@@ -35,15 +37,18 @@ module RuboCop
         hash:         HashNode,
         if:           IfNode,
         int:          IntNode,
+        index:        IndexNode,
+        indexasgn:    IndexasgnNode,
         irange:       RangeNode,
         erange:       RangeNode,
         kwsplat:      KeywordSplatNode,
+        lambda:       LambdaNode,
         module:       ModuleNode,
+        next:         NextNode,
         or:           OrNode,
         pair:         PairNode,
         regexp:       RegexpNode,
         resbody:      ResbodyNode,
-        retry:        RetryNode,
         return:       ReturnNode,
         csend:        SendNode,
         send:         SendNode,

data/lib/rubocop/ast/ext/range.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module AST
+    module Ext
+      # Extensions to Parser::AST::Range
+      module Range
+        # @return [Range] the range of line numbers for the node
+        # If `exclude_end` is `true`, then the range will be exclusive.
+        #
+        # Assume that `node` corresponds to the following array literal:
+        #
+        #   [
+        #     :foo,
+        #     :bar
+        #   ]
+        #
+        #   node.loc.begin.line_span                         # => 1..1
+        #   node.loc.expression.line_span(exclude_end: true) # => 1...4
+        def line_span(exclude_end: false)
+          ::Range.new(first_line, last_line, exclude_end)
+        end
+      end
+    end
+  end
+end
+
+::Parser::Source::Range.include ::RuboCop::AST::Ext::Range

data/lib/rubocop/ast/node.rb

@@ -44,6 +44,8 @@ module RuboCop
 
       BASIC_CONDITIONALS = %i[if while until].freeze
       CONDITIONALS = [*BASIC_CONDITIONALS, :case].freeze
+      POST_CONDITION_LOOP_TYPES = %i[while_post until_post].freeze
+      LOOP_TYPES = (POST_CONDITION_LOOP_TYPES + %i[while until for]).freeze
       VARIABLES = %i[ivar gvar cvar lvar].freeze
       REFERENCES = %i[nth_ref back_ref].freeze
       KEYWORDS = %i[alias and break case class def defs defined?
@@ -53,6 +55,7 @@ module RuboCop
                     yield].freeze
       OPERATOR_KEYWORDS = %i[and or].freeze
       SPECIAL_KEYWORDS = %w[__FILE__ __LINE__ __ENCODING__].freeze
+      ARGUMENT_TYPES = %i[arg optarg restarg kwarg kwoptarg kwrestarg blockarg].freeze
 
       # @see https://www.rubydoc.info/gems/ast/AST/Node:initialize
       def initialize(type, children = [], properties = {})
@@ -310,8 +313,8 @@ module RuboCop
       def_node_matcher :defined_module0, <<~PATTERN
         {(class (const $_ $_) ...)
          (module (const $_ $_) ...)
-         (casgn $_ $_        (send (const nil? {:Class :Module}) :new ...))
-         (casgn $_ $_ (block (send (const nil? {:Class :Module}) :new ...) ...))}
+         (casgn $_ $_        (send #global_const?({:Class :Module}) :new ...))
+         (casgn $_ $_ (block (send #global_const?({:Class :Module}) :new ...) ...))}
       PATTERN
 
       private :defined_module0
@@ -425,6 +428,15 @@ module RuboCop
         CONDITIONALS.include?(type)
       end
 
+      def post_condition_loop?
+        POST_CONDITION_LOOP_TYPES.include?(type)
+      end
+
+      # Note: `loop { }` is a normal method call and thus not a loop keyword.
+      def loop_keyword?
+        LOOP_TYPES.include?(type)
+      end
+
       def keyword?
         return true if special_keyword? || send_type? && prefix_not?
         return false unless KEYWORDS.include?(type)
@@ -456,6 +468,10 @@ module RuboCop
         parent&.send_type? && parent.arguments.include?(self)
       end
 
+      def argument_type?
+        ARGUMENT_TYPES.include?(type)
+      end
+
       def boolean_type?
         true_type? || false_type?
       end
@@ -480,16 +496,33 @@ module RuboCop
 
       def_node_matcher :proc?, <<~PATTERN
         {(block (send nil? :proc) ...)
-         (block (send (const nil? :Proc) :new) ...)
-         (send (const nil? :Proc) :new)}
+         (block (send #global_const?(:Proc) :new) ...)
+         (send #global_const?(:Proc) :new)}
       PATTERN
 
       def_node_matcher :lambda?, '({block numblock} (send nil? :lambda) ...)'
       def_node_matcher :lambda_or_proc?, '{lambda? proc?}'
 
+      def_node_matcher :global_const?, '(const {nil? cbase} %1)'
+
       def_node_matcher :class_constructor?, <<~PATTERN
-        {       (send (const nil? {:Class :Module}) :new ...)
-         (block (send (const nil? {:Class :Module}) :new ...) ...)}
+        {       (send #global_const?({:Class :Module}) :new ...)
+         (block (send #global_const?({:Class :Module}) :new ...) ...)}
+      PATTERN
+
+      def_node_matcher :struct_constructor?, <<~PATTERN
+        (block (send #global_const?(:Struct) :new ...) _ $_)
+      PATTERN
+
+      def_node_matcher :class_definition?, <<~PATTERN
+        {(class _ _ $_)
+         (sclass _ $_)
+         (block (send #global_const?({:Struct :Class}) :new ...) _ $_)}
+      PATTERN
+
+      def_node_matcher :module_definition?, <<~PATTERN
+        {(module _ $_)
+         (block (send #global_const?(:Module) :new ...) _ $_)}
       PATTERN
 
       # Some expressions are evaluated for their value, some for their side
@@ -500,7 +533,7 @@ module RuboCop
       # So, does the return value of this node matter? If we changed it to
       # `(...; nil)`, might that affect anything?
       #
-      # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
+      # rubocop:disable Metrics/MethodLength
       def value_used?
         # Be conservative and return true if we're not sure.
         return false if parent.nil?
@@ -522,7 +555,7 @@ module RuboCop
           true
         end
       end
-      # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity
+      # rubocop:enable Metrics/MethodLength
 
       # Some expressions are evaluated for their value, some for their side
       # effects, and some for both.

data/lib/rubocop/ast/node/array_node.rb

@@ -14,15 +14,9 @@ module RuboCop
       # Returns an array of all value nodes in the `array` literal.
       #
       # @return [Array<Node>] an array of value nodes
-      def values
-        each_child_node.to_a
-      end
+      alias values children
 
-      # Calls the given block for all values in the `array` literal.
-      #
-      # @yieldparam [Node] node each node
-      # @return [self] if a block is given
-      # @return [Enumerator] if no block is given
+      # @deprecated Use `values.each` (a.k.a. `children.each`)
       def each_value(&block)
         return to_enum(__method__) unless block_given?
 

data/lib/rubocop/ast/node/break_node.rb

@@ -6,12 +6,7 @@ module RuboCop
     # plain node when the builder constructs the AST, making its methods
     # available to all `break` nodes within RuboCop.
     class BreakNode < Node
-      include MethodDispatchNode
-      include ParameterizedNode
-
-      def arguments
-        []
-      end
+      include ParameterizedNode::WrappedArguments
     end
   end
 end

data/lib/rubocop/ast/node/case_match_node.rb

@@ -15,17 +15,11 @@ module RuboCop
         'case'
       end
 
-      # Calls the given block for each `in_pattern` node in the `in` statement.
-      # If no block is given, an `Enumerator` is returned.
-      #
-      # @return [self] if a block is given
-      # @return [Enumerator] if no block is given
-      def each_in_pattern
+      # @deprecated Use `in_pattern_branches.each`
+      def each_in_pattern(&block)
         return in_pattern_branches.to_enum(__method__) unless block_given?
 
-        in_pattern_branches.each do |condition|
-          yield condition
-        end
+        in_pattern_branches.each(&block)
 
         self
       end

data/lib/rubocop/ast/node/case_node.rb

@@ -15,17 +15,11 @@ module RuboCop
         'case'
       end
 
-      # Calls the given block for each `when` node in the `case` statement.
-      # If no block is given, an `Enumerator` is returned.
-      #
-      # @return [self] if a block is given
-      # @return [Enumerator] if no block is given
-      def each_when
+      # @deprecated Use `when_branches.each`
+      def each_when(&block)
         return when_branches.to_enum(__method__) unless block_given?
 
-        when_branches.each do |condition|
-          yield condition
-        end
+        when_branches.each(&block)
 
         self
       end
@@ -37,6 +31,16 @@ module RuboCop
         node_parts[1...-1]
       end
 
+      # Returns an array of all the when branches in the `case` statement.
+      #
+      # @return [Array<Node, nil>] an array of the bodies of the when branches
+      # and the else (if any). Note that these bodies could be nil.
+      def branches
+        bodies = when_branches.map(&:body)
+        bodies.push(else_branch) if else?
+        bodies
+      end
+
       # Returns the else branch of the `case` statement, if any.
       #
       # @return [Node] the else branch node of the `case` statement

data/lib/rubocop/ast/node/def_node.rb

@@ -24,21 +24,21 @@ module RuboCop
       #
       # @return [Boolean] whether the `def` node uses argument forwarding
       def argument_forwarding?
-        arguments.any?(&:forward_args_type?)
+        arguments.any?(&:forward_args_type?) || arguments.any?(&:forward_arg_type?)
       end
 
       # The name of the defined method as a symbol.
       #
       # @return [Symbol] the name of the defined method
       def method_name
-        node_parts[2]
+        children[-3]
       end
 
       # An array containing the arguments of the method definition.
       #
       # @return [Array<Node>] the arguments of the method definition
       def arguments
-        node_parts[1]
+        children[-2]
       end
 
       # The body of the method definition.
@@ -49,33 +49,14 @@ module RuboCop
       #
       # @return [Node] the body of the method definition
       def body
-        node_parts[0]
+        children[-1]
       end
 
       # The receiver of the method definition, if any.
       #
       # @return [Node, nil] the receiver of the method definition, or `nil`.
       def receiver
-        node_parts[3]
-      end
-
-      # Custom destructuring method. This can be used to normalize
-      # destructuring for different variations of the node.
-      #
-      # In this case, the `def` node destructures into:
-      #
-      #   `method_name, arguments, body`
-      #
-      # while the `defs` node destructures into:
-      #
-      #   `receiver, method_name, arguments, body`
-      #
-      # so we reverse the destructured array to get the optional receiver
-      # at the end, where it can be discarded.
-      #
-      # @return [Array] the different parts of the `def` or `defs` node
-      def node_parts
-        to_a.reverse
+        children[-4]
       end
     end
   end

data/lib/rubocop/ast/node/defined_node.rb

@@ -12,6 +12,8 @@ module RuboCop
       def node_parts
         [nil, :defined?, *to_a]
       end
+
+      alias arguments children
     end
   end
 end

data/lib/rubocop/ast/node/float_node.rb

@@ -6,6 +6,7 @@ module RuboCop
     # node when the builder constructs the AST, making its methods available to
     # all `float` nodes within RuboCop.
     class FloatNode < Node
+      include BasicLiteralNode
       include NumericNode
     end
   end

data/lib/rubocop/ast/node/forward_args_node.rb

@@ -5,6 +5,21 @@ module RuboCop
     # A node extension for `forward-args` nodes. This will be used in place
     # of a plain node when the builder constructs the AST, making its methods
     # available to all `forward-args` nodes within RuboCop.
+    #
+    # Not used with modern emitters:
+    #
+    #   $ ruby-parse -e "def foo(...); end"
+    #   (def :foo
+    #     (args
+    #       (forward-arg)) nil)
+    #   $ ruby-parse --legacy -e "->(foo) { bar }"
+    #   (def :foo
+    #     (forward-args) nil)
+    #
+    # Note the extra 's' with legacy form.
+    #
+    # The main RuboCop runs in legacy mode; this node is only used
+    # if user `AST::Builder.modernize` or `AST::Builder.emit_lambda=true`
     class ForwardArgsNode < Node
       include CollectionNode