rubocop-ast 0.0.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0750c7434a863460f8b900080b40ed7515c6e1eb415d0b91ce612f6bcac7a67
-  data.tar.gz: 0b08bbe1e7ed4612351d4296264f18bbe0e3af5d069410d46e017f4826ac1bc9
+  metadata.gz: a691b22abba3de79be3aca5f66247b20b5bdd8fe0bcbe1403d5455c4da25fae9
+  data.tar.gz: d0984b47a3d0f683447361683acb58afa4fcfffb1597bed575cce1d34fafd90e
 SHA512:
-  metadata.gz: 7259c958f33d8a754275a5c25d8b6094f2f41be2a058935dca5d689903accd0bba77bff7ac440501c35274fb00f9a9c29c4c02f8e988e2a7bb0f3fc334773cab
-  data.tar.gz: e28f39434e75ad138bc49646e36d9bbb39fe25011d0bd41034c4da02d5bbb801b52e5caf06a05453e9ada004b158e1c573deb4749468f126fb4cbb88bebd3a74
+  metadata.gz: 165cfc53926eecd29099f29554dae5e751bb1bee7c4fc42f49abe93db18ea3dbf6589b7b57e6e16aaabf7e842ea253dd41609ab2af343c44db4181af4c815c79
+  data.tar.gz: f150ffa3ae23ae80f4e3572a529fd19d42509e025e013c02c52eb408c60f3feaf55ef1d53304c19586ad2bf3b3b0ca7aac18503bc45b56ed3ad534dc875d894f

data/README.md

@@ -2,12 +2,16 @@
 
 [![Gem Version](https://badge.fury.io/rb/rubocop-ast.svg)](https://badge.fury.io/rb/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` ([doc](manual/node_pattern.md))
 
-This gem may be used independently from the main RuboCop gem.
+* `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
 
@@ -25,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,11 @@
 
 require 'parser'
 require 'forwardable'
+require 'set'
 
-require_relative 'error'
-require_relative 'node_pattern'
-
+require_relative 'ast/ext/range'
+require_relative 'ast/ext/set'
+require_relative 'ast/node_pattern'
 require_relative 'ast/sexp'
 require_relative 'ast/node'
 require_relative 'ast/node/mixin/method_identifier_predicates'
@@ -28,6 +29,7 @@ require_relative 'ast/node/break_node'
 require_relative 'ast/node/case_match_node'
 require_relative 'ast/node/case_node'
 require_relative 'ast/node/class_node'
+require_relative 'ast/node/const_node'
 require_relative 'ast/node/def_node'
 require_relative 'ast/node/defined_node'
 require_relative 'ast/node/ensure_node'
@@ -36,15 +38,19 @@ 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/rescue_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,8 +62,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 'ast/version'
-
-require_relative 'token'
-require_relative 'processed_source'

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,
@@ -25,6 +27,7 @@ module RuboCop
         case_match:   CaseMatchNode,
         case:         CaseNode,
         class:        ClassNode,
+        const:        ConstNode,
         def:          DefNode,
         defined?:     DefinedNode,
         defs:         DefNode,
@@ -35,15 +38,19 @@ 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,
+        rescue:       RescueNode,
         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/ext/set.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+test = :foo
+case test
+when Set[:foo]
+  # ok, RUBY_VERSION > 2.4
+else
+  # Harmonize `Set#===`
+  class Set
+    alias === include?
+  end
+end

data/lib/rubocop/ast/node.rb

@@ -38,12 +38,14 @@ module RuboCop
       IMMUTABLE_LITERALS = (LITERALS - MUTABLE_LITERALS).freeze
 
       EQUALS_ASSIGNMENTS = %i[lvasgn ivasgn cvasgn gvasgn
-                              casgn masgn].freeze
+                              casgn masgn rasgn mrasgn].freeze
       SHORTHAND_ASSIGNMENTS = %i[op_asgn or_asgn and_asgn].freeze
       ASSIGNMENTS = (EQUALS_ASSIGNMENTS + SHORTHAND_ASSIGNMENTS).freeze
 
       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 = {})
@@ -113,12 +116,50 @@ module RuboCop
 
       # Returns the index of the receiver node in its siblings. (Sibling index
       # uses zero based numbering.)
+      # Use is discouraged, this is a potentially slow method.
       #
-      # @return [Integer] the index of the receiver node in its siblings
+      # @return [Integer, nil] the index of the receiver node in its siblings
       def sibling_index
         parent&.children&.index { |sibling| sibling.equal?(self) }
       end
 
+      # Use is discouraged, this is a potentially slow method and can lead
+      # to even slower algorithms
+      # @return [Node, nil] the right (aka next) sibling
+      def right_sibling
+        return unless parent
+
+        parent.children[sibling_index + 1].freeze
+      end
+
+      # Use is discouraged, this is a potentially slow method and can lead
+      # to even slower algorithms
+      # @return [Node, nil] the left (aka previous) sibling
+      def left_sibling
+        i = sibling_index
+        return if i.nil? || i.zero?
+
+        parent.children[i - 1].freeze
+      end
+
+      # Use is discouraged, this is a potentially slow method and can lead
+      # to even slower algorithms
+      # @return [Array<Node>] the left (aka previous) siblings
+      def left_siblings
+        return [].freeze unless parent
+
+        parent.children[0...sibling_index].freeze
+      end
+
+      # Use is discouraged, this is a potentially slow method and can lead
+      # to even slower algorithms
+      # @return [Array<Node>] the right (aka next) siblings
+      def right_siblings
+        return [].freeze unless parent
+
+        parent.children[sibling_index + 1..-1].freeze
+      end
+
       # Common destructuring method. This can be used to normalize
       # destructuring for different variations of the node.
       # Some node types override this with their own custom
@@ -310,8 +351,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 +466,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 +506,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 +534,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 +571,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 +593,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/block_node.rb

@@ -25,7 +25,7 @@ module RuboCop
       # @return [Array<Node>]
       def arguments
         if numblock_type?
-          [] # Numbered parameters have no block arguments.
+          [].freeze # Numbered parameters have no block arguments.
         else
           node_parts[1]
         end

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