rubocop-ast 1.1.1 → 1.49.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec19a654b5c38c2a70e811bd7c16a86473bd9fec2444774e9d8ef3cfa9d9de58
-  data.tar.gz: 6a0ef9e9d121c5ba9991bb7cd534f8e180d84718ef093fc0be8099175bf027b4
+  metadata.gz: aad4bf15828f1db50f117c1a983e1f4c7f0cff233878a7f1a1686416ab21feff
+  data.tar.gz: 8ac8ad74b061c5fcd733e21420068edc69d0a9bfba532dc766e01dbb80be5c40
 SHA512:
-  metadata.gz: a720f20464156e92dddd9979ae2dff71a7a5deca84b2e8c717b9165fa9e831b4c15c5f7cba3c33cd8986a2618822ee0e82386e58d1586b1ebefbb5a74f9972b6
-  data.tar.gz: bf26e4aa780bf56d029ca9272825a4a91d8c76f87d88e7c43de8167e06d8e2687d2d450e28f989b77c3d61169a0d91866bfe1504f2069aee3d0d2e16e2ce4444
+  metadata.gz: 75f3882c819f2e10f7ef893481fbe9feddedfcdc91678c1c695d6ef36d94798dedf5667427cbfc6c022494e7e0c9581f54b4e1dcc9f05f2aea677668fe645b04
+  data.tar.gz: 94b37b0490cbf1ab81ab0c4c98a5bd8e6037b6ae5210af6ba2cbd23d4a263a3e4cfccad3f99fe621a6ab62d8356fc007fd066adb2d2379e02f5b07580ef2b2d4

data/README.md

@@ -1,11 +1,9 @@
 # RuboCop AST
 
 [![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)
+[![CI](https://github.com/rubocop/rubocop-ast/actions/workflows/rubocop.yml/badge.svg)](https://github.com/rubocop/rubocop-ast/actions/workflows/rubocop.yml)
 
-Contains the classes needed by [RuboCop](https://github.com/rubocop-hq/rubocop) to deal with Ruby's AST, in particular:
+Contains the classes needed by [RuboCop](https://github.com/rubocop/rubocop) to deal with Ruby's AST, in particular:
 
 * `RuboCop::AST::Node` ([doc](docs/modules/ROOT/pages/node_types.adoc))
 * `RuboCop::AST::NodePattern` ([doc](docs/modules/ROOT/pages/node_pattern.adoc))
@@ -35,7 +33,9 @@ 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`.
+This gem, by default, uses most [legacy AST output from parser](https://github.com/whitequark/parser/#usage), except for the following which are set to `true`:
+* `emit_forward_arg`
+* `emit_match_pattern`
 
 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`:

data/lib/rubocop/ast/builder.rb

@@ -2,72 +2,97 @@
 
 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
+    # 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 = {
-        and:          AndNode,
-        alias:        AliasNode,
-        args:         ArgsNode,
-        array:        ArrayNode,
-        block:        BlockNode,
-        numblock:     BlockNode,
-        break:        BreakNode,
-        case_match:   CaseMatchNode,
-        case:         CaseNode,
-        class:        ClassNode,
-        const:        ConstNode,
-        def:          DefNode,
-        defined?:     DefinedNode,
-        defs:         DefNode,
-        ensure:       EnsureNode,
-        for:          ForNode,
-        forward_args: ForwardArgsNode,
-        float:        FloatNode,
-        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,
-        return:       ReturnNode,
-        csend:        SendNode,
-        send:         SendNode,
-        str:          StrNode,
-        dstr:         StrNode,
-        xstr:         StrNode,
-        sclass:       SelfClassNode,
-        super:        SuperNode,
-        zsuper:       SuperNode,
-        sym:          SymbolNode,
-        until:        UntilNode,
-        until_post:   UntilNode,
-        when:         WhenNode,
-        while:        WhileNode,
-        while_post:   WhileNode,
-        yield:        YieldNode
+        and:                 AndNode,
+        and_asgn:            AndAsgnNode,
+        alias:               AliasNode,
+        arg:                 ArgNode,
+        blockarg:            ArgNode,
+        forward_arg:         ArgNode,
+        kwarg:               ArgNode,
+        kwoptarg:            ArgNode,
+        kwrestarg:           ArgNode,
+        optarg:              ArgNode,
+        restarg:             ArgNode,
+        shadowarg:           ArgNode,
+        args:                ArgsNode,
+        array:               ArrayNode,
+        lvasgn:              AsgnNode,
+        ivasgn:              AsgnNode,
+        cvasgn:              AsgnNode,
+        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,
+        defs:                DefNode,
+        dstr:                DstrNode,
+        ensure:              EnsureNode,
+        for:                 ForNode,
+        forward_args:        ForwardArgsNode,
+        forwarded_kwrestarg: KeywordSplatNode,
+        float:               FloatNode,
+        hash:                HashNode,
+        if:                  IfNode,
+        in_pattern:          InPatternNode,
+        int:                 IntNode,
+        index:               IndexNode,
+        indexasgn:           IndexasgnNode,
+        irange:              RangeNode,
+        erange:              RangeNode,
+        kwargs:              HashNode,
+        kwbegin:             KeywordBeginNode,
+        kwsplat:             KeywordSplatNode,
+        lambda:              LambdaNode,
+        masgn:               MasgnNode,
+        mlhs:                MlhsNode,
+        module:              ModuleNode,
+        next:                NextNode,
+        op_asgn:             OpAsgnNode,
+        or_asgn:             OrAsgnNode,
+        or:                  OrNode,
+        pair:                PairNode,
+        procarg0:            Procarg0Node,
+        rational:            RationalNode,
+        regexp:              RegexpNode,
+        rescue:              RescueNode,
+        resbody:             ResbodyNode,
+        return:              ReturnNode,
+        csend:               CsendNode,
+        send:                SendNode,
+        str:                 StrNode,
+        xstr:                StrNode,
+        sclass:              SelfClassNode,
+        super:               SuperNode,
+        zsuper:              SuperNode,
+        sym:                 SymbolNode,
+        until:               UntilNode,
+        until_post:          UntilNode,
+        lvar:                VarNode,
+        ivar:                VarNode,
+        cvar:                VarNode,
+        gvar:                VarNode,
+        when:                WhenNode,
+        while:               WhileNode,
+        while_post:          WhileNode,
+        yield:               YieldNode
       }.freeze
 
       # Generates {Node} from the given information.
@@ -77,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)
@@ -89,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/ext/range.rb

@@ -15,8 +15,8 @@ module RuboCop
         #     :bar
         #   ]
         #
-        #   node.loc.begin.line_span                         # => 1..1
-        #   node.loc.expression.line_span(exclude_end: true) # => 1...4
+        #   node.loc.begin.line_span                       # => 1..1
+        #   node.source_range.line_span(exclude_end: true) # => 1...4
         def line_span(exclude_end: false)
           ::Range.new(first_line, last_line, exclude_end)
         end
@@ -25,4 +25,4 @@ module RuboCop
   end
 end
 
-::Parser::Source::Range.include ::RuboCop::AST::Ext::Range
+Parser::Source::Range.include RuboCop::AST::Ext::Range

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module AST
+    # A node extension for `op_asgn` 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 AndAsgnNode < OpAsgnNode
+      # The operator being used for assignment as a symbol.
+      #
+      # @return [Symbol] the assignment operator
+      def operator
+        :'&&'
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module AST
+    # A node extension for `arg`, `optarg`, `restarg`, `kwarg`, `kwoptarg`,
+    # `kwrestarg`, `blockarg`, `shadowarg` and `forward_arg` nodes.
+    # This will be used in place of a plain node when the builder constructs
+    # the AST, making its methods available to all `arg` nodes within RuboCop.
+    class ArgNode < Node
+      # Returns the name of an argument.
+      #
+      # @return [Symbol, nil] the name of the argument
+      def name
+        node_parts[0]
+      end
+
+      # Returns the default value of the argument, if any.
+      #
+      # @return [Node, nil] the default value of the argument
+      def default_value
+        return unless default?
+
+        node_parts[1]
+      end
+
+      # Checks whether the argument has a default value
+      #
+      # @return [Boolean] whether the argument has a default value
+      def default?
+        optarg_type? || kwoptarg_type?
+      end
+    end
+  end
+end

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

@@ -24,6 +24,16 @@ module RuboCop
       def empty_and_without_delimiters?
         loc.expression.nil?
       end
+
+      # Yield each argument from the collection.
+      # Arguments can be inside `mlhs` nodes in the case of destructuring, so this
+      # flattens the collection to just `arg`, `optarg`, `restarg`, `kwarg`,
+      # `kwoptarg`, `kwrestarg`, `blockarg`, `forward_arg` and `shadowarg`.
+      #
+      # @return [Array<Node>] array of argument nodes.
+      def argument_list
+        each_descendant(:argument).to_a.freeze
+      end
     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,9 +17,13 @@ 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_given?
+        return to_enum(__method__) unless block
 
         values.each(&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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module AST
+    # A node extension for `lvasgn`, `ivasgn`, `cvasgn`, and `gvasgn` 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 AsgnNode < Node
+      # The name of the variable being assigned as a symbol.
+      #
+      # @return [Symbol] the name of the variable being assigned
+      def name
+        node_parts[0]
+      end
+      alias lhs name
+
+      # The expression being assigned to the variable.
+      #
+      # @return [Node] the expression being assigned.
+      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,14 +23,49 @@ 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
+      # actual argument nodes.
       #
       # @return [Array<Node>]
       def arguments
+        if block_type?
+          node_parts[1]
+        else
+          [].freeze # Numblocks and itblocks have no explicit block arguments.
+        end
+      end
+
+      # Returns a collection of all descendants of this node that are
+      # argument type nodes. See `ArgsNode#argument_list` for details.
+      #
+      # @return [Array<Node>]
+      def argument_list
         if numblock_type?
-          [].freeze # Numbered parameters have no block arguments.
+          numbered_arguments
+        elsif itblock_type?
+          IT_BLOCK_ARGUMENT
         else
-          node_parts[1]
+          arguments.argument_list
         end
       end
 
@@ -57,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.
@@ -117,6 +154,15 @@ module RuboCop
       def void_context?
         VOID_CONTEXT_METHODS.include?(method_name)
       end
+
+      private
+
+      def numbered_arguments
+        max_param = children[1]
+        1.upto(max_param).map do |i|
+          ArgNode.new(:arg, [:"_#{i}"])
+        end.freeze
+      end
     end
   end
 end

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

@@ -17,23 +17,37 @@ module RuboCop
 
       # @deprecated Use `in_pattern_branches.each`
       def each_in_pattern(&block)
-        return in_pattern_branches.to_enum(__method__) unless block_given?
+        return in_pattern_branches.to_enum(__method__) unless block
 
         in_pattern_branches.each(&block)
 
         self
       end
 
-      # Returns an array of all the when branches in the `case` statement.
+      # Returns an array of all the `in` pattern branches in the `case` statement.
       #
-      # @return [Array<Node>] an array of `in_pattern` nodes
+      # @return [Array<InPatternNode>] an array of `in_pattern` nodes
       def in_pattern_branches
         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 `in` branches
+      # and the `else` (if any). Note that these bodies could be nil.
+      def branches
+        bodies = in_pattern_branches.map(&:body)
+        if else?
+          # `empty-else` node sets nil because it has no body.
+          else_branch.empty_else_type? ? bodies.push(nil) : bodies.push(else_branch)
+        end
+        bodies
+      end
+
       # Returns the else branch of the `case` statement, if any.
       #
       # @return [Node] the else branch node of the `case` statement
+      # @return [EmptyElse] the empty else branch node of the `case` statement
       # @return [nil] if the case statement does not have an else branch.
       def else_branch
         node_parts[-1]

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

@@ -17,7 +17,7 @@ module RuboCop
 
       # @deprecated Use `when_branches.each`
       def each_when(&block)
-        return when_branches.to_enum(__method__) unless block_given?
+        return when_branches.to_enum(__method__) unless block
 
         when_branches.each(&block)
 

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module AST
+    # A node extension for `casgn` 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 CasgnNode < Node
+      include ConstantNode
+
+      alias name short_name
+      alias lhs short_name
+
+      # The expression being assigned to the variable.
+      #
+      # @return [Node] the expression being assigned.
+      def expression
+        node_parts[2]
+      end
+      alias rhs expression
+    end
+  end
+end

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

@@ -6,9 +6,9 @@ module RuboCop
     # node when the builder constructs the AST, making its methods available
     # to all `class` nodes within RuboCop.
     class ClassNode < Node
-      # The identifer for this `class` node.
+      # The identifier for this `class` node.
       #
-      # @return [Node] the identifer of the class
+      # @return [Node] the identifier of the class
       def identifier
         node_parts[0]
       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,62 +4,7 @@ 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
+      include ConstantNode
     end
   end
 end