rubocop 0.46.0 → 0.47.0

data/config/disabled.yml

@@ -69,6 +69,11 @@ Style/InlineComment:
   Description: 'Avoid trailing inline comments.'
   Enabled: false
 
+Style/MethodCallWithArgsParentheses:
+  Description: 'Use parentheses for method calls with arguments.'
+  StyleGuide: '#method-invocation-parens'
+  Enabled: false
+
 Style/MethodCalledOnDoEndBlock:
   Description: 'Avoid chaining a method call on a do...end block.'
   StyleGuide: '#single-line-blocks'
@@ -113,3 +118,7 @@ Style/SymbolArray:
   Description: 'Use %i or %I for arrays of symbols.'
   StyleGuide: '#percent-i'
   Enabled: false
+
+Style/SingleLineBlockParams:
+  Description: 'Enforces the names of some block params.'
+  Enabled: false

data/config/enabled.yml

@@ -404,7 +404,7 @@ Style/LineEndConcatenation:
                  line end.
   Enabled: true
 
-Style/MethodCallParentheses:
+Style/MethodCallWithoutArgsParentheses:
   Description: 'Do not use parentheses for method calls with no arguments.'
   StyleGuide: '#method-invocation-parens'
   Enabled: true
@@ -710,10 +710,6 @@ Style/SignalException:
   StyleGuide: '#prefer-raise-over-fail'
   Enabled: true
 
-Style/SingleLineBlockParams:
-  Description: 'Enforces the names of some block params.'
-  Enabled: true
-
 Style/SingleLineMethods:
   Description: 'Avoid single-line methods.'
   StyleGuide: '#no-single-line-methods'
@@ -1120,10 +1116,6 @@ Lint/EnsureReturn:
   StyleGuide: '#no-return-ensure'
   Enabled: true
 
-Lint/Eval:
-  Description: 'The use of eval represents a serious security risk.'
-  Enabled: true
-
 Lint/FloatOutOfRange:
   Description: >-
                  Catches floating-point literals too large or small for Ruby to
@@ -1176,6 +1168,10 @@ Lint/Loop:
   StyleGuide: '#loop-with-break'
   Enabled: true
 
+Lint/MultipleCompare:
+  Description: "Use `&&` operator to compare multiple value."
+  Enabled: true
+
 Lint/NestedMethodDefinition:
   Description: 'Do not use nested method definitions.'
   StyleGuide: '#no-nested-methods'
@@ -1225,6 +1221,10 @@ Lint/RescueException:
   StyleGuide: '#no-blind-rescues'
   Enabled: true
 
+Lint/SafeNavigationChain:
+  Description: 'Do not chain ordinary method call after safe navigation operator.'
+  Enabled: true
+
 Lint/ShadowedException:
   Description: >-
                   Avoid rescuing a higher level exception
@@ -1279,6 +1279,7 @@ Lint/UselessAccessModifier:
   Description: 'Checks for useless access modifiers.'
   Enabled: true
   ContextCreatingMethods: []
+  MethodCreatingMethods: []
 
 Lint/UselessAssignment:
   Description: 'Checks for useless assignment to a local variable.'
@@ -1408,6 +1409,10 @@ Performance/RedundantSortBy:
   Description: 'Use `sort` instead of `sort_by { |x| x }`.'
   Enabled: true
 
+Performance/RegexpMatch:
+  Description: 'Use `match?` instead of `Regexp#match`, `String#match`, `Symbol#match`, `Regexp#===` or `=~` when `MatchData` is not used.'
+  Enabled: true
+
 Performance/ReverseEach:
   Description: 'Use `reverse_each` instead of `reverse.each`.'
   Reference: 'https://github.com/JuanitoFatas/fast-ruby#enumerablereverseeach-vs-enumerablereverse_each-code'
@@ -1488,6 +1493,10 @@ Rails/Exit:
                   exits during unit testing or running in production.
   Enabled: true
 
+Rails/FilePath:
+  Description: 'Use `Rails.root.join` for file path joining.'
+  Enabled: true
+
 Rails/FindBy:
   Description: 'Prefer find_by over where.first.'
   StyleGuide: 'https://github.com/bbatsov/rails-style-guide#find_by'
@@ -1537,6 +1546,12 @@ Rails/RequestReferer:
   Description: 'Use consistent syntax for request.referer.'
   Enabled: true
 
+Rails/ReversibleMigration:
+  Description: 'Checks whether the change method of the migration file is reversible.'
+  StyleGuide: 'https://github.com/bbatsov/rails-style-guide#reversible-migration'
+  Reference: 'http://api.rubyonrails.org/classes/ActiveRecord/Migration/CommandRecorder.html'
+  Enabled: true
+
 Rails/SafeNavigation:
   Description: "Use Ruby's safe navigation operator (`&.`) instead of `try!`"
   Enabled: true
@@ -1555,10 +1570,21 @@ Rails/UniqBeforePluck:
   Description: 'Prefer the use of uniq or distinct before pluck.'
   Enabled: true
 
+Rails/SkipsModelValidations:
+  Description: >-
+                 Use methods that skips model validations with caution.
+                 See reference for more information.
+  Reference: 'http://guides.rubyonrails.org/active_record_validations.html#skipping-validations'
+  Enabled: true
+
 Rails/Validation:
   Description: 'Use validates :attribute, hash of validations.'
   Enabled: true
 
+Security/Eval:
+  Description: 'The use of eval represents a serious security risk.'
+  Enabled: true
+
 Security/JSONLoad:
   Description: >-
                  Prefer usage of `JSON.parse` over `JSON.load` due to potential
@@ -1569,6 +1595,20 @@ Security/JSONLoad:
   # on the value of the argument.
   AutoCorrect: false
 
+Security/MarshalLoad:
+  Description: >-
+                 Avoid using of `Marshal.load` or `Marshal.restore` due to potential
+                 security issues. See reference for more information.
+  Reference: 'http://ruby-doc.org/core-2.3.3/Marshal.html#module-Marshal-label-Security+considerations'
+  Enabled: true
+
+Security/YAMLLoad:
+  Description: >-
+                 Prefer usage of `YAML.safe_load` over `YAML.load` due to potential
+                 security issues. See reference for more information.
+  Reference: 'https://ruby-doc.org/stdlib-2.3.3/libdoc/yaml/rdoc/YAML.html#module-YAML-label-Security'
+  Enabled: true
+
 ##################### Bundler #############################
 
 Bundler/DuplicatedGem:

data/lib/rubocop.rb

@@ -19,17 +19,33 @@ require 'rubocop/string_util'
 require 'rubocop/name_similarity'
 require 'rubocop/node_pattern'
 require 'rubocop/string_interpreter'
-require 'rubocop/ast_node/sexp'
-require 'rubocop/ast_node'
-require 'rubocop/ast_node/builder'
-require 'rubocop/ast_node/traversal'
+require 'rubocop/ast/sexp'
+require 'rubocop/ast/node'
+require 'rubocop/ast/node/mixin/conditional_node'
+require 'rubocop/ast/node/mixin/hash_element_node'
+require 'rubocop/ast/node/mixin/modifier_node'
+require 'rubocop/ast/node/array_node'
+require 'rubocop/ast/node/case_node'
+require 'rubocop/ast/node/for_node'
+require 'rubocop/ast/node/hash_node'
+require 'rubocop/ast/node/if_node'
+require 'rubocop/ast/node/keyword_splat_node'
+require 'rubocop/ast/node/pair_node'
+require 'rubocop/ast/node/until_node'
+require 'rubocop/ast/node/when_node'
+require 'rubocop/ast/node/while_node'
+require 'rubocop/ast/builder'
+require 'rubocop/ast/traversal'
 require 'rubocop/error'
 require 'rubocop/warning'
 
 require 'rubocop/cop/util'
 require 'rubocop/cop/offense'
+require 'rubocop/cop/message_annotator'
 require 'rubocop/cop/ignored_node'
 require 'rubocop/cop/autocorrect_logic'
+require 'rubocop/cop/badge'
+require 'rubocop/cop/registry'
 require 'rubocop/cop/cop'
 require 'rubocop/cop/commissioner'
 require 'rubocop/cop/corrector'
@@ -54,16 +70,17 @@ require 'rubocop/cop/mixin/configurable_max'
 require 'rubocop/cop/mixin/code_length' # relies on configurable_max
 require 'rubocop/cop/mixin/classish_length' # relies on code_length
 require 'rubocop/cop/mixin/configurable_enforced_style'
+require 'rubocop/cop/mixin/configurable_formatting'
 require 'rubocop/cop/mixin/configurable_naming'
 require 'rubocop/cop/mixin/configurable_numbering'
 require 'rubocop/cop/mixin/def_node'
 require 'rubocop/cop/mixin/documentation_comment'
+require 'rubocop/cop/mixin/duplication'
 require 'rubocop/cop/mixin/empty_lines_around_body'
 require 'rubocop/cop/mixin/end_keyword_alignment'
 require 'rubocop/cop/mixin/first_element_line_break'
 require 'rubocop/cop/mixin/frozen_string_literal'
-require 'rubocop/cop/mixin/hash_node'
-require 'rubocop/cop/mixin/if_node'
+require 'rubocop/cop/mixin/hash_alignment'
 require 'rubocop/cop/mixin/integer_node'
 require 'rubocop/cop/mixin/on_method_def'
 require 'rubocop/cop/mixin/match_range'
@@ -87,6 +104,7 @@ require 'rubocop/cop/mixin/space_inside' # relies on surrounding_space
 require 'rubocop/cop/mixin/statement_modifier'
 require 'rubocop/cop/mixin/string_help'
 require 'rubocop/cop/mixin/string_literals_help'
+require 'rubocop/cop/mixin/target_ruby_version'
 require 'rubocop/cop/mixin/too_many_lines'
 require 'rubocop/cop/mixin/trailing_comma'
 require 'rubocop/cop/mixin/unused_argument'
@@ -115,7 +133,6 @@ require 'rubocop/cop/lint/empty_when'
 require 'rubocop/cop/lint/end_alignment'
 require 'rubocop/cop/lint/end_in_method'
 require 'rubocop/cop/lint/ensure_return'
-require 'rubocop/cop/lint/eval'
 require 'rubocop/cop/lint/float_out_of_range'
 require 'rubocop/cop/lint/format_parameter_mismatch'
 require 'rubocop/cop/lint/handle_exceptions'
@@ -126,6 +143,7 @@ require 'rubocop/cop/lint/invalid_character_literal'
 require 'rubocop/cop/lint/literal_in_condition'
 require 'rubocop/cop/lint/literal_in_interpolation'
 require 'rubocop/cop/lint/loop'
+require 'rubocop/cop/lint/multiple_compare'
 require 'rubocop/cop/lint/nested_method_definition'
 require 'rubocop/cop/lint/next_without_accumulator'
 require 'rubocop/cop/lint/non_local_exit_from_iterator'
@@ -135,6 +153,7 @@ require 'rubocop/cop/lint/percent_symbol_array'
 require 'rubocop/cop/lint/rand_one'
 require 'rubocop/cop/lint/require_parentheses'
 require 'rubocop/cop/lint/rescue_exception'
+require 'rubocop/cop/lint/safe_navigation_chain'
 require 'rubocop/cop/lint/shadowed_exception'
 require 'rubocop/cop/lint/shadowing_outer_local_variable'
 require 'rubocop/cop/lint/string_conversion_in_interpolation'
@@ -179,6 +198,7 @@ require 'rubocop/cop/performance/redundant_block_call'
 require 'rubocop/cop/performance/redundant_match'
 require 'rubocop/cop/performance/redundant_merge'
 require 'rubocop/cop/performance/redundant_sort_by'
+require 'rubocop/cop/performance/regexp_match'
 require 'rubocop/cop/performance/reverse_each'
 require 'rubocop/cop/performance/sample'
 require 'rubocop/cop/performance/size'
@@ -278,7 +298,8 @@ require 'rubocop/cop/style/lambda'
 require 'rubocop/cop/style/lambda_call'
 require 'rubocop/cop/style/leading_comment_space'
 require 'rubocop/cop/style/line_end_concatenation'
-require 'rubocop/cop/style/method_call_parentheses'
+require 'rubocop/cop/style/method_call_without_args_parentheses'
+require 'rubocop/cop/style/method_call_with_args_parentheses'
 require 'rubocop/cop/style/method_called_on_do_end_block'
 require 'rubocop/cop/style/method_def_parentheses'
 require 'rubocop/cop/style/method_name'
@@ -399,6 +420,7 @@ require 'rubocop/cop/rails/delegate'
 require 'rubocop/cop/rails/delegate_allow_blank'
 require 'rubocop/cop/rails/enum_uniqueness'
 require 'rubocop/cop/rails/exit'
+require 'rubocop/cop/rails/file_path'
 require 'rubocop/cop/rails/find_by'
 require 'rubocop/cop/rails/find_each'
 require 'rubocop/cop/rails/has_and_belongs_to_many'
@@ -409,14 +431,19 @@ require 'rubocop/cop/rails/output'
 require 'rubocop/cop/rails/pluralization_grammar'
 require 'rubocop/cop/rails/read_write_attribute'
 require 'rubocop/cop/rails/request_referer'
+require 'rubocop/cop/rails/reversible_migration'
 require 'rubocop/cop/rails/safe_navigation'
 require 'rubocop/cop/rails/save_bang'
 require 'rubocop/cop/rails/scope_args'
+require 'rubocop/cop/rails/skips_model_validations'
 require 'rubocop/cop/rails/time_zone'
 require 'rubocop/cop/rails/uniq_before_pluck'
 require 'rubocop/cop/rails/validation'
 
+require 'rubocop/cop/security/eval'
 require 'rubocop/cop/security/json_load'
+require 'rubocop/cop/security/marshal_load'
+require 'rubocop/cop/security/yaml_load'
 
 require 'rubocop/cop/team'
 
@@ -444,6 +471,7 @@ require 'rubocop/config_store'
 require 'rubocop/target_finder'
 require 'rubocop/token'
 require 'rubocop/comment_config'
+require 'rubocop/magic_comment'
 require 'rubocop/processed_source'
 require 'rubocop/result_cache'
 require 'rubocop/runner'

data/lib/rubocop/ast/builder.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module AST
+    # `RuboCop::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::Builder.new
+    #   parser = Parser::CurrentRuby.new(builder)
+    #   root_node = parser.parse(buffer)
+    class Builder < Parser::Builders::Default
+      NODE_MAP = {
+        ArrayNode        => [:array],
+        CaseNode         => [:case],
+        ForNode          => [:for],
+        HashNode         => [:hash],
+        IfNode           => [:if],
+        KeywordSplatNode => [:kwsplat],
+        PairNode         => [:pair],
+        UntilNode        => [:until, :until_post],
+        WhenNode         => [:when],
+        WhileNode        => [:while, :while_post]
+      }.freeze
+
+      # Generates {Node} from the given information.
+      #
+      # @return [Node] the generated node
+      def n(type, children, source_map)
+        node_klass(type).new(type, children, location: source_map)
+      end
+
+      # TODO: Figure out what to do about literal encoding handling...
+      # More details here https://github.com/whitequark/parser/issues/283
+      def string_value(token)
+        value(token)
+      end
+
+      private
+
+      def node_klass(type)
+        node_map[type] || Node
+      end
+
+      # Take the human readable constant and generate a hash map where each
+      # (mapped) node type is a key with its constant as the value.
+      def node_map
+        @node_map ||= begin
+          NODE_MAP.each_pair.each_with_object({}) do |(klass, types), map|
+            types.each { |type| map[type] = klass }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/ast/node.rb

@@ -0,0 +1,607 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module AST
+    # `RuboCop::AST::Node` is a subclass of `Parser::AST::Node`. It provides
+    # access to parent nodes and an object-oriented way to traverse an AST with
+    # the power of `Enumerable`.
+    #
+    # It has predicate methods for every node type, like this:
+    #
+    # @example
+    #   node.send_type?    # Equivalent to: `node.type == :send`
+    #   node.op_asgn_type? # Equivalent to: `node.type == :op_asgn`
+    #
+    #   # Non-word characters (other than a-zA-Z0-9_) in type names are omitted.
+    #   node.defined_type? # Equivalent to: `node.type == :defined?`
+    #
+    #   # Find the first lvar node under the receiver node.
+    #   lvar_node = node.each_descendant.find(&:lvar_type?)
+    #
+    class Node < Parser::AST::Node # rubocop:disable Metrics/ClassLength
+      include RuboCop::AST::Sexp
+
+      COMPARISON_OPERATORS = [:!, :==, :===, :!=, :<=, :>=, :>, :<, :<=>].freeze
+
+      TRUTHY_LITERALS = [:str, :dstr, :xstr, :int, :float, :sym, :dsym, :array,
+                         :hash, :regexp, :true, :irange, :erange, :complex,
+                         :rational, :regopt].freeze
+      FALSEY_LITERALS = [:false, :nil].freeze
+      LITERALS = (TRUTHY_LITERALS + FALSEY_LITERALS).freeze
+      COMPOSITE_LITERALS = [:dstr, :xstr, :dsym, :array, :hash, :irange,
+                            :erange, :regexp].freeze
+      BASIC_LITERALS = (LITERALS - COMPOSITE_LITERALS).freeze
+      MUTABLE_LITERALS = [:str, :dstr, :xstr, :array, :hash].freeze
+      IMMUTABLE_LITERALS = (LITERALS - MUTABLE_LITERALS).freeze
+
+      VARIABLES = [:ivar, :gvar, :cvar, :lvar].freeze
+      REFERENCES = [:nth_ref, :back_ref].freeze
+      KEYWORDS = [:alias, :and, :break, :case, :class, :def, :defs, :defined?,
+                  :kwbegin, :do, :else, :ensure, :for, :if, :module, :next,
+                  :not, :or, :postexe, :redo, :rescue, :retry, :return, :self,
+                  :super, :zsuper, :then, :undef, :until, :when, :while,
+                  :yield].freeze
+      OPERATOR_KEYWORDS = [:and, :or].freeze
+      SPECIAL_KEYWORDS = %w(__FILE__ __LINE__ __ENCODING__).freeze
+
+      # def_matcher can be used to define a pattern-matching method on Node
+      class << self
+        def def_matcher(method_name, pattern_str)
+          compiler = RuboCop::NodePattern::Compiler.new(pattern_str, 'self')
+          src = "def #{method_name}(" \
+                "#{compiler.emit_param_list});" \
+                "#{compiler.emit_method_code};end"
+
+          file, lineno = *caller.first.split(':')
+          class_eval(src, file, lineno.to_i)
+        end
+      end
+
+      # @see http://rubydoc.info/gems/ast/AST/Node:initialize
+      def initialize(type, children = [], properties = {})
+        @mutable_attributes = {}
+
+        # ::AST::Node#initialize freezes itself.
+        super
+
+        # #parent= may be invoked multiple times for a node because there are
+        # pending nodes while constructing AST and they are replaced later.
+        # For example, `lvar` and `send` type nodes are initially created as an
+        # `ident` type node and fixed to the appropriate type later.
+        # So, the #parent attribute needs to be mutable.
+        each_child_node do |child_node|
+          child_node.parent = self unless child_node.complete?
+        end
+      end
+
+      Parser::Meta::NODE_TYPES.each do |node_type|
+        method_name = "#{node_type.to_s.gsub(/\W/, '')}_type?"
+        define_method(method_name) do
+          type == node_type
+        end
+      end
+
+      # Returns the parent node, or `nil` if the receiver is a root node.
+      #
+      # @return [Node, nil] the parent node or `nil`
+      def parent
+        @mutable_attributes[:parent]
+      end
+
+      def parent=(node)
+        @mutable_attributes[:parent] = node
+      end
+
+      def complete!
+        @mutable_attributes.freeze
+        each_child_node(&:complete!)
+      end
+
+      def complete?
+        @mutable_attributes.frozen?
+      end
+
+      protected :parent=
+
+      # Override `AST::Node#updated` so that `AST::Processor` does not try to
+      # mutate our ASTs. Since we keep references from children to parents and
+      # not just the other way around, we cannot update an AST and share
+      # identical subtrees. Rather, the entire AST must be copied any time any
+      # part of it is changed.
+      def updated(type = nil, children = nil, properties = {})
+        properties[:location] ||= @location
+        Node.new(type || @type, children || @children, properties)
+      end
+
+      # Returns the index of the receiver node in its siblings. (Sibling index
+      # uses zero based numbering.)
+      #
+      # @return [Integer] the index of the receiver node in its siblings
+      def sibling_index
+        parent.children.index { |sibling| sibling.equal?(self) }
+      end
+
+      # Calls the given block for each ancestor node from parent to root.
+      # If no block is given, an `Enumerator` is returned.
+      #
+      # @overload each_ancestor
+      #   Yield all nodes.
+      # @overload each_ancestor(type)
+      #   Yield only nodes matching the type.
+      #   @param [Symbol] type a node type
+      # @overload each_ancestor(type_a, type_b, ...)
+      #   Yield only nodes matching any of the types.
+      #   @param [Symbol] type_a a node type
+      #   @param [Symbol] type_b a node type
+      # @overload each_ancestor(types)
+      #   Yield only nodes matching any of types in the array.
+      #   @param [Array<Symbol>] types an array containing node types
+      # @yieldparam [Node] node each ancestor node
+      # @return [self] if a block is given
+      # @return [Enumerator] if no block is given
+      def each_ancestor(*types, &block)
+        return to_enum(__method__, *types) unless block_given?
+
+        visit_ancestors(types, &block)
+
+        self
+      end
+
+      # Returns an array of ancestor nodes.
+      # This is a shorthand for `node.each_ancestor.to_a`.
+      #
+      # @return [Array<Node>] an array of ancestor nodes
+      def ancestors
+        each_ancestor.to_a
+      end
+
+      # Calls the given block for each child node.
+      # If no block is given, an `Enumerator` is returned.
+      #
+      # Note that this is different from `node.children.each { |child| ... }`
+      # which yields all children including non-node elements.
+      #
+      # @overload each_child_node
+      #   Yield all nodes.
+      # @overload each_child_node(type)
+      #   Yield only nodes matching the type.
+      #   @param [Symbol] type a node type
+      # @overload each_child_node(type_a, type_b, ...)
+      #   Yield only nodes matching any of the types.
+      #   @param [Symbol] type_a a node type
+      #   @param [Symbol] type_b a node type
+      # @overload each_child_node(types)
+      #   Yield only nodes matching any of types in the array.
+      #   @param [Array<Symbol>] types an array containing node types
+      # @yieldparam [Node] node each child node
+      # @return [self] if a block is given
+      # @return [Enumerator] if no block is given
+      def each_child_node(*types)
+        return to_enum(__method__, *types) unless block_given?
+
+        children.each do |child|
+          next unless child.is_a?(Node)
+          yield child if types.empty? || types.include?(child.type)
+        end
+
+        self
+      end
+
+      # Returns an array of child nodes.
+      # This is a shorthand for `node.each_child_node.to_a`.
+      #
+      # @return [Array<Node>] an array of child nodes
+      def child_nodes
+        each_child_node.to_a
+      end
+
+      # Calls the given block for each descendant node with depth first order.
+      # If no block is given, an `Enumerator` is returned.
+      #
+      # @overload each_descendant
+      #   Yield all nodes.
+      # @overload each_descendant(type)
+      #   Yield only nodes matching the type.
+      #   @param [Symbol] type a node type
+      # @overload each_descendant(type_a, type_b, ...)
+      #   Yield only nodes matching any of the types.
+      #   @param [Symbol] type_a a node type
+      #   @param [Symbol] type_b a node type
+      # @overload each_descendant(types)
+      #   Yield only nodes matching any of types in the array.
+      #   @param [Array<Symbol>] types an array containing node types
+      # @yieldparam [Node] node each descendant node
+      # @return [self] if a block is given
+      # @return [Enumerator] if no block is given
+      def each_descendant(*types, &block)
+        return to_enum(__method__, *types) unless block_given?
+
+        visit_descendants(types, &block)
+
+        self
+      end
+
+      # Returns an array of descendant nodes.
+      # This is a shorthand for `node.each_descendant.to_a`.
+      #
+      # @return [Array<Node>] an array of descendant nodes
+      def descendants
+        each_descendant.to_a
+      end
+
+      # Calls the given block for the receiver and each descendant node in
+      # depth-first order.
+      # If no block is given, an `Enumerator` is returned.
+      #
+      # This method would be useful when you treat the receiver node as the root
+      # of a tree and want to iterate over all nodes in the tree.
+      #
+      # @overload each_node
+      #   Yield all nodes.
+      # @overload each_node(type)
+      #   Yield only nodes matching the type.
+      #   @param [Symbol] type a node type
+      # @overload each_node(type_a, type_b, ...)
+      #   Yield only nodes matching any of the types.
+      #   @param [Symbol] type_a a node type
+      #   @param [Symbol] type_b a node type
+      # @overload each_node(types)
+      #   Yield only nodes matching any of types in the array.
+      #   @param [Array<Symbol>] types an array containing node types
+      # @yieldparam [Node] node each node
+      # @return [self] if a block is given
+      # @return [Enumerator] if no block is given
+      def each_node(*types, &block)
+        return to_enum(__method__, *types) unless block_given?
+
+        yield self if types.empty? || types.include?(type)
+
+        visit_descendants(types, &block)
+
+        self
+      end
+
+      def source
+        loc.expression.source
+      end
+
+      def source_range
+        loc.expression
+      end
+
+      ## Destructuring
+
+      def_matcher :receiver,    '{(send $_ ...) (block (send $_ ...) ...)}'
+      def_matcher :method_name, '{(send _ $_ ...) (block (send _ $_ ...) ...)}'
+      def_matcher :method_args, '{(send _ _ $...) (block (send _ _ $...) ...)}'
+      # Note: for masgn, #asgn_rhs will be an array node
+      def_matcher :asgn_rhs, '[assignment? (... $_)]'
+      def_matcher :str_content, '(str $_)'
+
+      def const_name
+        return unless const_type?
+        namespace, name = *self
+        if namespace && !namespace.cbase_type?
+          "#{namespace.const_name}::#{name}"
+        else
+          name.to_s
+        end
+      end
+
+      def_matcher :defined_module0, <<-PATTERN
+        {(class (const $_ $_) ...)
+         (module (const $_ $_) ...)
+         (casgn $_ $_        (send (const nil {:Class :Module}) :new ...))
+         (casgn $_ $_ (block (send (const nil {:Class :Module}) :new ...) ...))}
+      PATTERN
+      private :defined_module0
+
+      def defined_module
+        namespace, name = *defined_module0
+        s(:const, namespace, name) if name
+      end
+
+      def defined_module_name
+        (const = defined_module) && const.const_name
+      end
+
+      ## Searching the AST
+
+      def parent_module_name
+        # what class or module is this method/constant/etc definition in?
+        # returns nil if answer cannot be determined
+        ancestors = each_ancestor(:class, :module, :sclass, :casgn, :block)
+        result    = ancestors.map do |ancestor|
+          parent_module_name_part(ancestor) { |full_name| return full_name }
+        end.compact.reverse.join('::')
+        result.empty? ? 'Object' : result
+      end
+
+      ## Predicates
+
+      def multiline?
+        source_range && (source_range.first_line != source_range.last_line)
+      end
+
+      def single_line?
+        !multiline?
+      end
+
+      def asgn_method_call?
+        !COMPARISON_OPERATORS.include?(method_name) &&
+          method_name.to_s.end_with?('='.freeze)
+      end
+
+      def_matcher :equals_asgn?, '{lvasgn ivasgn cvasgn gvasgn casgn masgn}'
+      def_matcher :shorthand_asgn?, '{op_asgn or_asgn and_asgn}'
+      def_matcher :assignment?,
+                  '{equals_asgn? shorthand_asgn? asgn_method_call?}'
+
+      def literal?
+        LITERALS.include?(type)
+      end
+
+      def basic_literal?
+        BASIC_LITERALS.include?(type)
+      end
+
+      def truthy_literal?
+        TRUTHY_LITERALS.include?(type)
+      end
+
+      def falsey_literal?
+        FALSEY_LITERALS.include?(type)
+      end
+
+      def mutable_literal?
+        MUTABLE_LITERALS.include?(type)
+      end
+
+      def immutable_literal?
+        IMMUTABLE_LITERALS.include?(type)
+      end
+
+      [:literal, :basic_literal].each do |kind|
+        recursive_kind = :"recursive_#{kind}?"
+        kind_filter = :"#{kind}?"
+        define_method(recursive_kind) do
+          case type
+          when :send
+            receiver, method_name, *args = *self
+            COMPARISON_OPERATORS.include?(method_name) &&
+              receiver.send(recursive_kind) &&
+              args.all?(&recursive_kind)
+          when :begin, :pair, *OPERATOR_KEYWORDS, *COMPOSITE_LITERALS
+            children.all?(&recursive_kind)
+          else
+            send(kind_filter)
+          end
+        end
+      end
+
+      def variable?
+        VARIABLES.include?(type)
+      end
+
+      def reference?
+        REFERENCES.include?(type)
+      end
+
+      def keyword?
+        return true if special_keyword? || keyword_not?
+        return false unless KEYWORDS.include?(type)
+
+        !OPERATOR_KEYWORDS.include?(type) || loc.operator.is?(type.to_s)
+      end
+
+      def special_keyword?
+        SPECIAL_KEYWORDS.include?(source)
+      end
+
+      def keyword_not?
+        _receiver, method_name, *args = *self
+        args.empty? && method_name == :! && loc.selector.is?('not'.freeze)
+      end
+
+      def keyword_bang?
+        _receiver, method_name, *args = *self
+        args.empty? && method_name == :! && loc.selector.is?('!'.freeze)
+      end
+
+      def unary_operation?
+        return false unless loc.respond_to?(:selector) && loc.selector
+        Cop::Util.operator?(loc.selector.source.to_sym) &&
+          source_range.begin_pos == loc.selector.begin_pos
+      end
+
+      def binary_operation?
+        return false unless loc.respond_to?(:selector) && loc.selector
+        Cop::Util.operator?(method_name) &&
+          source_range.begin_pos != loc.selector.begin_pos
+      end
+
+      def chained?
+        return false unless argument?
+
+        receiver, _method_name, *_args = *parent
+        equal?(receiver)
+      end
+
+      def argument?
+        parent && parent.send_type?
+      end
+
+      def numeric_type?
+        int_type? || float_type?
+      end
+
+      def_matcher :guard_clause?, <<-PATTERN
+        [{(send nil {:raise :fail} ...) return break next} single_line?]
+      PATTERN
+
+      def_matcher :command?, '(send nil %1 ...)'
+      def_matcher :lambda?,  '(block (send nil :lambda) ...)'
+      def_matcher :proc?, <<-PATTERN
+        {(block (send nil :proc) ...)
+         (block (send (const nil :Proc) :new) ...)
+         (send (const nil :Proc) :new)}
+      PATTERN
+      def_matcher :lambda_or_proc?, '{lambda? proc?}'
+
+      def_matcher :class_constructor?, <<-PATTERN
+        {       (send (const nil {:Class :Module}) :new ...)
+         (block (send (const nil {:Class :Module}) :new ...) ...)}
+      PATTERN
+
+      def_matcher :module_definition?, <<-PATTERN
+        {class module (casgn _ _ class_constructor?)}
+      PATTERN
+
+      # Some expressions are evaluated for their value, some for their side
+      # effects, and some for both
+      # If we know that an expression is useful only for its side effects, that
+      # means we can transform it in ways which preserve the side effects, but
+      # change the return value
+      # So, does the return value of this node matter? If we changed it to
+      # `(...; nil)`, might that affect anything?
+      #
+      # rubocop:disable Metrics/MethodLength
+      def value_used?
+        # Be conservative and return true if we're not sure.
+        return false if parent.nil?
+
+        case parent.type
+        when :array, :defined?, :dstr, :dsym, :eflipflop, :erange, :float,
+             :hash, :iflipflop, :irange, :not, :pair, :regexp, :str, :sym,
+             :when, :xstr
+          parent.value_used?
+        when :begin, :kwbegin
+          begin_value_used?
+        when :for
+          for_value_used?
+        when :case, :if
+          case_if_value_used?
+        when :while, :until, :while_post, :until_post
+          while_until_value_used?
+        else
+          true
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Some expressions are evaluated for their value, some for their side
+      # effects, and some for both.
+      # If we know that expressions are useful only for their return values,
+      # and have no side effects, that means we can reorder them, change the
+      # number of times they are evaluated, or replace them with other
+      # expressions which are equivalent in value.
+      # So, is evaluation of this node free of side effects?
+      #
+      def pure?
+        # Be conservative and return false if we're not sure
+        case type
+        when :__FILE__, :__LINE__, :const, :cvar, :defined?, :false, :float,
+             :gvar, :int, :ivar, :lvar, :nil, :str, :sym, :true, :regopt
+          true
+        when :and, :array, :begin, :case, :dstr, :dsym, :eflipflop, :ensure,
+             :erange, :for, :hash, :if, :iflipflop, :irange, :kwbegin, :not,
+             :or, :pair, :regexp, :until, :until_post, :when, :while,
+             :while_post
+          child_nodes.all?(&:pure?)
+        else
+          false
+        end
+      end
+
+      protected
+
+      def visit_descendants(types, &block)
+        each_child_node do |child|
+          yield child if types.empty? || types.include?(child.type)
+          child.visit_descendants(types, &block)
+        end
+      end
+
+      private
+
+      def visit_ancestors(types)
+        last_node = self
+
+        while (current_node = last_node.parent)
+          yield current_node if types.empty? ||
+                                types.include?(current_node.type)
+          last_node = current_node
+        end
+      end
+
+      def begin_value_used?
+        # the last child node determines the value of the parent
+        sibling_index == parent.children.size - 1 ? parent.value_used? : false
+      end
+
+      def for_value_used?
+        # `for var in enum; body; end`
+        # (for <var> <enum> <body>)
+        sibling_index == 2 ? parent.value_used? : true
+      end
+
+      def case_if_value_used?
+        # (case <condition> <when...>)
+        # (if <condition> <truebranch> <falsebranch>)
+        sibling_index.zero? ? true : parent.value_used?
+      end
+
+      def while_until_value_used?
+        # (while <condition> <body>) -> always evaluates to `nil`
+        sibling_index.zero?
+      end
+
+      def parent_module_name_part(node)
+        case node.type
+        when :class, :module, :casgn
+          # TODO: if constant name has cbase (leading ::), then we don't need
+          # to keep traversing up through nested classes/modules
+          node.defined_module_name
+        when :sclass
+          yield parent_module_name_for_sclass(node)
+        else # block
+          parent_module_name_for_block(node) { yield nil }
+        end
+      end
+
+      def parent_module_name_for_sclass(sclass_node)
+        # TODO: look for constant definition and see if it is nested
+        # inside a class or module
+        subject = sclass_node.children[0]
+
+        if subject.const_type?
+          "#<Class:#{subject.const_name}>"
+        elsif subject.self_type?
+          "#<Class:#{sclass_node.parent_module_name}>"
+        end
+      end
+
+      def parent_module_name_for_block(ancestor)
+        if ancestor.method_name == :class_eval
+          # `class_eval` with no receiver applies to whatever module or class
+          # we are currently in
+          return unless (receiver = ancestor.receiver)
+          yield unless receiver.const_type?
+          receiver.const_name
+        elsif !new_class_or_module_block?(ancestor)
+          yield
+        end
+      end
+
+      def new_class_or_module_block?(block_node)
+        receiver = block_node.receiver
+
+        block_node.method_name == :new &&
+          receiver && receiver.const_type? &&
+          (receiver.const_name == 'Class' || receiver.const_name == 'Module') &&
+          block_node.parent &&
+          block_node.parent.casgn_type?
+      end
+    end
+  end
+end