rubocop-ast 1.29.0 → 1.46.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b08ce67ff41a6d40d8385735fe36ebe6fd90513f3cbafbd21afa4f9393a66f9a
-  data.tar.gz: 24e6a84531e66531bcf5c358cfbed40815d1fd3f1d91e598a5b884a1971bb3c7
+  metadata.gz: 2b94b9545a7aceaf8b52e8e6b8713df63fe1113c4040fd5f92563438c0307d21
+  data.tar.gz: 6db23c373003f60f0faf0f48ff1a4cb7d086f36820e7f5e732a147eea0d22f98
 SHA512:
-  metadata.gz: 20a8ea979cb2335691b7b39c9986962edc2fe61667e712187e3904e2a984fc3327b38034eca64028a362724964e982d053a093432d3f7994edae592cd8f6fb83
-  data.tar.gz: 59ab4c65c59d3407224147391e8b253c930da8add826c50553b433039057865aa1211d13e90061bb4e3a40ebb97184ea8d5698f3b4f5d0ff7c3c343d14a566bd
+  metadata.gz: 3a0fb03bcb60b82177efefcf2146d1512c50f9791f094769d64ae7c87899e9984ce41eebdb1fc8f6d8c40b287e42621f6d4bd9fdde23fe9884ebc0dd2202b5ae
+  data.tar.gz: 8fd5e39ac28109336a207edfedf5fc6b782ede8da4594cfdd1faf41e8e9df4d59a17716e1ea55121c575514d17fce9e0b3071ab98ecc54b007f66af8f002f560

data/README.md

@@ -1,7 +1,7 @@
 # RuboCop AST
 
 [![Gem Version](https://badge.fury.io/rb/rubocop-ast.svg)](https://badge.fury.io/rb/rubocop-ast)
-[![CI](https://github.com/rubocop/rubocop-ast/workflows/CI/badge.svg)](https://github.com/rubocop/rubocop-ast/actions?query=workflow%3ACI)
+[![CI](https://github.com/rubocop/rubocop-ast/actions/workflows/rubocop.yml/badge.svg)](https://github.com/rubocop/rubocop-ast/actions/workflows/rubocop.yml)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/a29666e6373bc41bc0a9/test_coverage)](https://codeclimate.com/github/rubocop/rubocop-ast/test_coverage)
 [![Maintainability](https://api.codeclimate.com/v1/badges/a29666e6373bc41bc0a9/maintainability)](https://codeclimate.com/github/rubocop/rubocop-ast/maintainability)
 

data/lib/rubocop/ast/builder.rb

@@ -2,20 +2,13 @@
 
 module RuboCop
   module AST
-    # `RuboCop::AST::Builder` is an AST builder that is utilized to let `Parser`
-    # generate ASTs with {RuboCop::AST::Node}.
-    #
-    # @example
-    #   buffer = Parser::Source::Buffer.new('(string)')
-    #   buffer.source = 'puts :foo'
-    #
-    #   builder = RuboCop::AST::Builder.new
-    #   require 'parser/ruby25'
-    #   parser = Parser::Ruby25.new(builder)
-    #   root_node = parser.parse(buffer)
-    class Builder < Parser::Builders::Default
-      self.emit_forward_arg = true if respond_to?(:emit_forward_arg=)
-      self.emit_match_pattern = true if respond_to?(:emit_match_pattern=)
+    # Common functionality between the parser and prism builder
+    # @api private
+    module BuilderExtensions
+      def self.included(base)
+        base.emit_forward_arg = true
+        base.emit_match_pattern = true
+      end
 
       # @api private
       NODE_MAP = {
@@ -39,11 +32,13 @@ module RuboCop
         gvasgn:              AsgnNode,
         block:               BlockNode,
         numblock:            BlockNode,
+        itblock:             BlockNode,
         break:               BreakNode,
         case_match:          CaseMatchNode,
         casgn:               CasgnNode,
         case:                CaseNode,
         class:               ClassNode,
+        complex:             ComplexNode,
         const:               ConstNode,
         def:                 DefNode,
         defined?:            DefinedNode,
@@ -63,8 +58,11 @@ module RuboCop
         irange:              RangeNode,
         erange:              RangeNode,
         kwargs:              HashNode,
+        kwbegin:             KeywordBeginNode,
         kwsplat:             KeywordSplatNode,
         lambda:              LambdaNode,
+        masgn:               MasgnNode,
+        mlhs:                MlhsNode,
         module:              ModuleNode,
         next:                NextNode,
         op_asgn:             OpAsgnNode,
@@ -72,6 +70,7 @@ module RuboCop
         or:                  OrNode,
         pair:                PairNode,
         procarg0:            Procarg0Node,
+        rational:            RationalNode,
         regexp:              RegexpNode,
         rescue:              RescueNode,
         resbody:             ResbodyNode,
@@ -86,6 +85,10 @@ module RuboCop
         sym:                 SymbolNode,
         until:               UntilNode,
         until_post:          UntilNode,
+        lvar:                VarNode,
+        ivar:                VarNode,
+        cvar:                VarNode,
+        gvar:                VarNode,
         when:                WhenNode,
         while:               WhileNode,
         while_post:          WhileNode,
@@ -99,7 +102,7 @@ module RuboCop
         node_klass(type).new(type, children, location: source_map)
       end
 
-      # TODO: Figure out what to do about literal encoding handling...
+      # Overwrite the base method to allow strings with invalid encoding
       # More details here https://github.com/whitequark/parser/issues/283
       def string_value(token)
         value(token)
@@ -111,5 +114,20 @@ module RuboCop
         NODE_MAP[type] || Node
       end
     end
+
+    # `RuboCop::AST::Builder` is an AST builder that is utilized to let `Parser`
+    # generate ASTs with {RuboCop::AST::Node}.
+    #
+    # @example
+    #   buffer = Parser::Source::Buffer.new('(string)')
+    #   buffer.source = 'puts :foo'
+    #
+    #   builder = RuboCop::AST::Builder.new
+    #   require 'parser/ruby25'
+    #   parser = Parser::Ruby25.new(builder)
+    #   root_node = parser.parse(buffer)
+    class Builder < Parser::Builders::Default
+      include BuilderExtensions
+    end
   end
 end

data/lib/rubocop/ast/builder_prism.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module AST
+    # A parser builder, based on the one provided by prism,
+    # which is capable of emitting AST for more recent Rubies.
+    class BuilderPrism < Prism::Translation::Parser::Builder
+      include BuilderExtensions
+    end
+  end
+end

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

@@ -32,7 +32,7 @@ module RuboCop
       #
       # @return [Array<Node>] array of argument nodes.
       def argument_list
-        each_descendant(*ARGUMENT_TYPES).to_a.freeze
+        each_descendant(:argument).to_a.freeze
       end
     end
   end

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

@@ -7,8 +7,8 @@ module RuboCop
     # to all `array` nodes within RuboCop.
     class ArrayNode < Node
       PERCENT_LITERAL_TYPES = {
-        string: /^%[wW]/,
-        symbol: /^%[iI]/
+        string: /\A%[wW]/,
+        symbol: /\A%[iI]/
       }.freeze
       private_constant :PERCENT_LITERAL_TYPES
 
@@ -17,7 +17,11 @@ module RuboCop
       # @return [Array<Node>] an array of value nodes
       alias values children
 
-      # @deprecated Use `values.each` (a.k.a. `children.each`)
+      # Calls the given block for each `value` node in the `array` literal.
+      # 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_value(&block)
         return to_enum(__method__) unless block
 
@@ -30,7 +34,7 @@ module RuboCop
       #
       # @return [Boolean] whether the array is enclosed in square brackets
       def square_brackets?
-        loc.begin&.is?('[')
+        loc_is?(:begin, '[')
       end
 
       # Checks whether the `array` literal is delimited by percent brackets.
@@ -46,7 +50,7 @@ module RuboCop
       # @return [Boolean] whether the array is enclosed in percent brackets
       def percent_literal?(type = nil)
         if type
-          loc.begin && loc.begin.source =~ PERCENT_LITERAL_TYPES[type]
+          loc.begin&.source&.match?(PERCENT_LITERAL_TYPES.fetch(type))
         else
           loc.begin&.source&.start_with?('%')
         end

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

@@ -12,6 +12,7 @@ module RuboCop
       def name
         node_parts[0]
       end
+      alias lhs name
 
       # The expression being assigned to the variable.
       #
@@ -19,6 +20,7 @@ module RuboCop
       def expression
         node_parts[1]
       end
+      alias rhs expression
     end
   end
 end

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

@@ -11,6 +11,8 @@ module RuboCop
     class BlockNode < Node
       include MethodIdentifierPredicates
 
+      IT_BLOCK_ARGUMENT = [ArgNode.new(:arg, [:it])].freeze
+      private_constant :IT_BLOCK_ARGUMENT
       VOID_CONTEXT_METHODS = %i[each tap].freeze
       private_constant :VOID_CONTEXT_METHODS
 
@@ -21,6 +23,24 @@ module RuboCop
         node_parts[0]
       end
 
+      # A shorthand for getting the first argument of this block.
+      # Equivalent to `arguments.first`.
+      #
+      # @return [Node, nil] the first argument of this block,
+      #                     or `nil` if there are no arguments
+      def first_argument
+        arguments[0]
+      end
+
+      # A shorthand for getting the last argument of this block.
+      # Equivalent to `arguments.last`.
+      #
+      # @return [Node, nil] the last argument of this block,
+      #                     or `nil` if there are no arguments
+      def last_argument
+        arguments[-1]
+      end
+
       # The arguments of this block.
       # Note that if the block has destructured arguments, `arguments` will
       # return a `mlhs` node, whereas `argument_list` will return only
@@ -28,10 +48,10 @@ module RuboCop
       #
       # @return [Array<Node>]
       def arguments
-        if numblock_type?
-          [].freeze # Numbered parameters have no block arguments.
-        else
+        if block_type?
           node_parts[1]
+        else
+          [].freeze # Numblocks and itblocks have no explicit block arguments.
         end
       end
 
@@ -42,6 +62,8 @@ module RuboCop
       def argument_list
         if numblock_type?
           numbered_arguments
+        elsif itblock_type?
+          IT_BLOCK_ARGUMENT
         else
           arguments.argument_list
         end
@@ -72,14 +94,14 @@ module RuboCop
       #
       # @return [Boolean] whether the `block` literal is enclosed in braces
       def braces?
-        loc.end&.is?('}')
+        loc.end.is?('}')
       end
 
       # Checks whether the `block` literal is delimited by `do`-`end` keywords.
       #
       # @return [Boolean] whether the `block` literal is enclosed in `do`-`end`
       def keywords?
-        loc.end&.is?('end')
+        loc.end.is?('end')
       end
 
       # The delimiters for this `block` literal.
@@ -135,10 +157,7 @@ module RuboCop
 
       private
 
-      # Numbered arguments of this `numblock`.
       def numbered_arguments
-        return [].freeze unless numblock_type?
-
         max_param = children[1]
         1.upto(max_param).map do |i|
           ArgNode.new(:arg, [:"_#{i}"])

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

@@ -6,19 +6,10 @@ module RuboCop
     # This will be used in place of a plain node when the builder constructs
     # the AST, making its methods available to all assignment nodes within RuboCop.
     class CasgnNode < Node
-      # The namespace of the constant being assigned.
-      #
-      # @return [Node, nil] the node associated with the scope (e.g. cbase, const, ...)
-      def namespace
-        node_parts[0]
-      end
+      include ConstantNode
 
-      # The name of the variable being assigned as a symbol.
-      #
-      # @return [Symbol] the name of the variable being assigned
-      def name
-        node_parts[1]
-      end
+      alias name short_name
+      alias lhs short_name
 
       # The expression being assigned to the variable.
       #
@@ -26,6 +17,7 @@ module RuboCop
       def expression
         node_parts[2]
       end
+      alias rhs expression
     end
   end
 end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module AST
+    # A node extension for `complex` nodes. This will be used in place of a plain
+    # node when the builder constructs the AST, making its methods available to
+    # all `complex` nodes within RuboCop.
+    class ComplexNode < Node
+      include BasicLiteralNode
+      include NumericNode
+    end
+  end
+end

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

@@ -4,58 +4,7 @@ module RuboCop
   module AST
     # A node extension for `const` nodes.
     class ConstNode < Node
-      # @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
-
-      # @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
-
-        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
+      include ConstantNode
     end
   end
 end

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

@@ -13,7 +13,7 @@ module RuboCop
       #
       # @return [Boolean] whether the `def` node body is a void context
       def void_context?
-        method?(:initialize) || assignment_method?
+        (def_type? && method?(:initialize)) || assignment_method?
       end
 
       # Checks whether this method definition node forwards its arguments

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

@@ -6,12 +6,48 @@ module RuboCop
     # node when the builder constructs the AST, making its methods available
     # to all `ensure` nodes within RuboCop.
     class EnsureNode < Node
+      DEPRECATION_WARNING_LOCATION_CACHE = [] # rubocop:disable Style/MutableConstant
+      private_constant :DEPRECATION_WARNING_LOCATION_CACHE
+
       # Returns the body of the `ensure` clause.
       #
       # @return [Node, nil] The body of the `ensure`.
+      # @deprecated Use `EnsureNode#branch`
       def body
+        first_caller = caller(1..1).first
+
+        unless DEPRECATION_WARNING_LOCATION_CACHE.include?(first_caller)
+          warn '`EnsureNode#body` is deprecated and will be changed in the next major version of ' \
+               'rubocop-ast. Use `EnsureNode#branch` instead to get the body of the `ensure` branch.'
+          warn "Called from:\n#{caller.join("\n")}\n\n"
+
+          DEPRECATION_WARNING_LOCATION_CACHE << first_caller
+        end
+
+        branch
+      end
+
+      # Returns an the ensure branch in the exception handling statement.
+      #
+      # @return [Node, nil] the body of the ensure branch.
+      def branch
         node_parts[1]
       end
+
+      # Returns the `rescue` node of the `ensure`, if present.
+      #
+      # @return [Node, nil] The `rescue` node.
+      def rescue_node
+        node_parts[0] if node_parts[0].rescue_type?
+      end
+
+      # Checks whether this node body is a void context.
+      # Always `true` for `ensure`.
+      #
+      # @return [true] whether the `ensure` node body is a void context
+      def void_context?
+        true
+      end
     end
   end
 end

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

@@ -17,7 +17,7 @@ module RuboCop
       #
       # @return [Boolean] whether the `for` node has a `do` keyword
       def do?
-        loc.begin&.is?('do')
+        loc_is?(:begin, 'do')
       end
 
       # Checks whether this node body is a void context.

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

@@ -115,7 +115,7 @@ module RuboCop
       #
       # @return [Boolean] whether the `hash` literal is enclosed in braces
       def braces?
-        loc.end&.is?('}')
+        loc_is?(:end, '}')
       end
     end
   end

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

@@ -25,6 +25,13 @@ module RuboCop
         keyword == 'unless'
       end
 
+      # Checks whether the `if` node has an `then` clause.
+      #
+      # @return [Boolean] whether the node has an `then` clause
+      def then?
+        loc_is?(:begin, 'then')
+      end
+
       # Checks whether the `if` is an `elsif`. Parser handles these by nesting
       # `if` nodes in the `else` branch.
       #
@@ -40,14 +47,14 @@ module RuboCop
       #
       # @return [Boolean] whether the node has an `else` clause
       def else?
-        loc.respond_to?(:else) && loc.else
+        loc?(:else)
       end
 
       # Checks whether the `if` node is a ternary operator.
       #
       # @return [Boolean] whether the `if` node is a ternary operator
       def ternary?
-        loc.respond_to?(:question)
+        loc?(:question)
       end
 
       # Returns the keyword of the `if` statement as a string. Returns an empty
@@ -81,7 +88,7 @@ module RuboCop
         (if? || unless?) && super
       end
 
-      # Chacks whether the `if` node has nested `if` nodes in any of its
+      # Checks whether the `if` node has nested `if` nodes in any of its
       # branches.
       #
       # @note This performs a shallow search.
@@ -102,7 +109,7 @@ module RuboCop
       #
       # @return [Boolean] whether the `if` node has at least one `elsif` branch
       def elsif_conditional?
-        else_branch&.if_type? && else_branch&.elsif?
+        else_branch&.if_type? && else_branch.elsif?
       end
 
       # Returns the branch of the `if` node that gets evaluated when its

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

@@ -24,7 +24,7 @@ module RuboCop
       #
       # @return [Boolean] whether the `in` node has a `then` keyword
       def then?
-        loc.begin&.is?('then')
+        loc_is?(:begin, 'then')
       end
 
       # Returns the body of the `in` node.

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module AST
+    # A node extension for `kwbegin` nodes. This will be used in place of a plain
+    # node when the builder constructs the AST, making its methods available
+    # to all `kwbegin` nodes within RuboCop.
+    class KeywordBeginNode < Node
+      # Returns the body of the `kwbegin` block. Returns `self` if the `kwbegin` contains
+      # multiple nodes.
+      #
+      # @return [Node, nil] The body of the `kwbegin`.
+      def body
+        return unless node_parts.any?
+
+        if rescue_node
+          rescue_node.body
+        elsif ensure_node
+          ensure_node.node_parts[0]
+        elsif node_parts.one?
+          node_parts[0]
+        else
+          self
+        end
+      end
+
+      # Returns the `rescue` node of the `kwbegin` block, if one is present.
+      #
+      # @return [Node, nil] The `rescue` node within `kwbegin`.
+      def ensure_node
+        node_parts[0] if node_parts[0]&.ensure_type?
+      end
+
+      # Returns the `rescue` node of the `kwbegin` block, if one is present.
+      #
+      # @return [Node, nil] The `rescue` node within `kwbegin`.
+      def rescue_node
+        return ensure_node&.rescue_node if ensure_node&.rescue_node
+
+        node_parts[0] if node_parts[0]&.rescue_type?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module AST
+    # A node extension for `masgn` nodes.
+    # This will be used in place of a plain node when the builder constructs
+    # the AST, making its methods available to all assignment nodes within RuboCop.
+    class MasgnNode < Node
+      # @return [MlhsNode] the `mlhs` node
+      def lhs
+        # The first child is a `mlhs` node
+        node_parts[0]
+      end
+
+      # @return [Array<Node>] the assignment nodes of the multiple assignment
+      def assignments
+        lhs.assignments
+      end
+
+      # @return [Array<Symbol>] names of all the variables being assigned
+      def names
+        assignments.map do |assignment|
+          if assignment.type?(:send, :indexasgn)
+            assignment.method_name
+          else
+            assignment.name
+          end
+        end
+      end
+
+      # The RHS (right hand side) of the multiple assignment. This returns
+      # the nodes as parsed: either a single node if the RHS has a single value,
+      # or an `array` node containing multiple nodes.
+      #
+      # NOTE: Due to how parsing works, `expression` will return the same for
+      # `a, b = x, y` and `a, b = [x, y]`.
+      #
+      # @return [Node] the right hand side of a multiple assignment.
+      def expression
+        node_parts[1]
+      end
+      alias rhs expression
+
+      # In contrast to `expression`, `values` always returns a Ruby array
+      # containing all the nodes being assigned on the RHS.
+      #
+      # Literal arrays are considered a singular value; but unlike `expression`,
+      # implied `array` nodes from assigning multiple values on the RHS are treated
+      # as separate.
+      #
+      # @return [Array<Node>] individual values being assigned on the RHS of the multiple assignment
+      def values
+        multiple_rhs? ? expression.children : [expression]
+      end
+
+      private
+
+      def multiple_rhs?
+        expression.array_type? && !expression.bracketed?
+      end
+    end
+  end
+end

data/lib/rubocop/ast/node/mixin/basic_literal_node.rb

@@ -3,7 +3,7 @@
 module RuboCop
   module AST
     # Common functionality for primitive literal nodes: `sym`, `str`,
-    # `int`, `float`, ...
+    # `int`, `float`, `rational`, `complex`...
     module BasicLiteralNode
       # Returns the value of the literal.
       #

data/lib/rubocop/ast/node/mixin/collection_node.rb

@@ -4,7 +4,7 @@ module RuboCop
   module AST
     # A mixin that helps give collection nodes array polymorphism.
     module CollectionNode
-      extend Forwardable
+      extend SimpleForwardable
 
       ARRAY_METHODS =
         (Array.instance_methods - Object.instance_methods - [:to_a]).freeze