rubocop-ast 0.0.3 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0c196be6c58699fcb84209860508c96e69e8122adb8e14d6641134009802712
-  data.tar.gz: a2d50c781f612349b4aa7e24a4ea4008c359ce766a6f5e0f7e925ac78d57dbb7
+  metadata.gz: 4bf5651a5da2be43d773d152c2f2260dfd1850ce1075aca7c4d21c08dd31a92a
+  data.tar.gz: c9addcd67e29e797109dc2f523c9c2094f94908b40c2e60c56061d6a8bf0e0f5
 SHA512:
-  metadata.gz: 2d263c6a0ab978cb1b81dde253ce752c2b64af9e94c59ac6a6a364aef3cec37c03028e4d7c00086c11b8b46abae9373edad636528782f84ad914ea527b644ec0
-  data.tar.gz: edeefb4a74f678920907e130ea6a7fea86b4c67cf9a9bbaefa21ef231738c0de541d61de5d9c234384e46b3243a74ffaac84288b2c68c49e3178cb39d2d96b37
+  metadata.gz: 1aa33edeacd95a65468093b80248a5908c69d30bf7d19afd6141044d00830f31c12aa489caf8ef705364d63771cade73651d9697635ab22941137df467ce4e92
+  data.tar.gz: fb820b52d69df72ab17a5ee06d06bdf7256b3318d8094b96467f79d314bad1b52bcb3938cb2ef98ca07b300f56132ac14921ef24aadf299d4c5754bb118b119f

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::AST::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::AST::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,7 +2,10 @@
 
 require 'parser'
 require 'forwardable'
+require 'set'
 
+require_relative 'ast/ext/range'
+require_relative 'ast/ext/set'
 require_relative 'ast/node_pattern'
 require_relative 'ast/sexp'
 require_relative 'ast/node'
@@ -26,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'
@@ -34,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'

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

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module AST
+    # A node extension for `const` nodes.
+    class ConstNode < Node
+      # The `send` node associated with this block.
+      #
+      # @return [Node, nil] the node associated with the scope (e.g. cbase, const, ...)
+      def namespace
+        children[0]
+      end
+
+      # @return [Symbol] the demodulized name of the constant: "::Foo::Bar" => :Bar
+      def short_name
+        children[1]
+      end
+
+      # The body of this block.
+      #
+      # @return [Boolean] if the constant is a Module / Class, according to the standard convention.
+      #                   Note: some classes might have uppercase in which case this method
+      #                         returns false
+      def module_name?
+        short_name.match?(/[[:lower:]]/)
+      end
+      alias class_name? module_name?
+
+      # @return [Boolean] if the constant starts with `::` (aka s(:cbase))
+      def absolute?
+        return false unless namespace
+
+        each_path.first.cbase_type?
+      end
+
+      # @return [Boolean] if the constant does not start with `::` (aka s(:cbase))
+      def relative?
+        !absolute?
+      end
+
+      # Yield nodes for the namespace
+      #
+      #   For `::Foo::Bar::BAZ` => yields:
+      #      s(:cbase), then
+      #      s(:const, :Foo), then
+      #      s(:const, s(:const, :Foo), :Bar)
+      def each_path(&block)
+        return to_enum(__method__) unless block_given?
+
+        descendants = []
+        last = self
+        loop do
+          last = last.children.first
+          break if last.nil?
+
+          descendants << last
+          break unless last.const_type?
+        end
+        descendants.reverse_each(&block)
+
+        self
+      end
+    end
+  end
+end