rubocop 1.19.1 → 1.22.1

data/lib/rubocop/cop/style/array_coercion.rb

@@ -5,9 +5,27 @@ module RuboCop
     module Style
       # This cop enforces the use of `Array()` instead of explicit `Array` check or `[*var]`.
       #
-      # This cop is disabled by default because false positive will occur if
-      # the argument of `Array()` is not an array (e.g. Hash, Set),
-      # an array will be returned as an incompatibility result.
+      # The cop is disabled by default due to safety concerns.
+      #
+      # @safety
+      #   This cop is unsafe because a false positive may occur if
+      #   the argument of `Array()` is (or could be) nil or depending
+      #   on how the argument is handled by `Array()` (which can be
+      #   different than just wrapping the argument in an array).
+      #
+      #   For example:
+      #
+      #   [source,ruby]
+      #   ----
+      #   [nil]             #=> [nil]
+      #   Array(nil)        #=> []
+      #
+      #   [{a: 'b'}]        #= [{a: 'b'}]
+      #   Array({a: 'b'})   #=> [[:a, 'b']]
+      #
+      #   [Time.now]        #=> [#<Time ...>]
+      #   Array(Time.now)   #=> [14, 16, 14, 16, 9, 2021, 4, 259, true, "EDT"]
+      #   ----
       #
       # @example
       #   # bad

data/lib/rubocop/cop/style/ascii_comments.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# rubocop:disable Style/AsciiComments
-
 module RuboCop
   module Cop
     module Style
@@ -57,4 +55,3 @@ module RuboCop
     end
   end
 end
-# rubocop:enable Style/AsciiComments

data/lib/rubocop/cop/style/block_delimiters.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# rubocop:disable Metrics/ClassLength
 module RuboCop
   module Cop
     module Style
@@ -191,7 +192,7 @@ module RuboCop
           if node.braces?
             replace_braces_with_do_end(corrector, node.loc)
           else
-            replace_do_end_with_braces(corrector, node.loc)
+            replace_do_end_with_braces(corrector, node)
           end
         end
 
@@ -256,7 +257,8 @@ module RuboCop
           corrector.replace(e, 'end')
         end
 
-        def replace_do_end_with_braces(corrector, loc)
+        def replace_do_end_with_braces(corrector, node)
+          loc = node.loc
           b = loc.begin
           e = loc.end
 
@@ -264,6 +266,8 @@ module RuboCop
 
           corrector.replace(b, '{')
           corrector.replace(e, '}')
+
+          corrector.wrap(node.body, "begin\n", "\nend") if begin_required?(node)
         end
 
         def whitespace_before?(range)
@@ -275,14 +279,20 @@ module RuboCop
         end
 
         def move_comment_before_block(corrector, comment, block_node, closing_brace)
-          range = range_between(closing_brace.end_pos, comment.loc.expression.end_pos)
-
-          corrector.remove(range_with_surrounding_space(range: range, side: :right))
-          corrector.insert_after(closing_brace, "\n")
+          range = block_node.chained? ? end_of_chain(block_node.parent).source_range : closing_brace
+          comment_range = range_between(range.end_pos, comment.loc.expression.end_pos)
+          corrector.remove(range_with_surrounding_space(range: comment_range, side: :right))
+          corrector.insert_after(range, "\n")
 
           corrector.insert_before(block_node, "#{comment.text}\n")
         end
 
+        def end_of_chain(node)
+          return node unless node.chained?
+
+          end_of_chain(node.parent)
+        end
+
         def get_blocks(node, &block)
           case node.type
           when :block
@@ -407,7 +417,14 @@ module RuboCop
         def array_or_range?(node)
           node.array_type? || node.range_type?
         end
+
+        def begin_required?(block_node)
+          # If the block contains `rescue` or `ensure`, it needs to be wrapped in
+          # `begin`...`end` when changing `do-end` to `{}`.
+          block_node.each_child_node(:rescue, :ensure).any? && !block_node.single_line?
+        end
       end
     end
   end
 end
+# rubocop:enable Metrics/ClassLength

data/lib/rubocop/cop/style/case_equality.rb

@@ -5,9 +5,11 @@ module RuboCop
     module Style
       # This cop checks for uses of the case equality operator(===).
       #
+      # If `AllowOnConstant` option is enabled, the cop will ignore violations when the receiver of
+      # the case equality operator is a constant.
+      #
       # @example
       #   # bad
-      #   Array === something
       #   (1..100) === 7
       #   /something/ === some_string
       #
@@ -16,18 +18,13 @@ module RuboCop
       #   (1..100).include?(7)
       #   /something/.match?(some_string)
       #
-      # @example AllowOnConstant
-      #   # Style/CaseEquality:
-      #   #   AllowOnConstant: true
-      #
+      # @example AllowOnConstant: false (default)
       #   # bad
-      #   (1..100) === 7
-      #   /something/ === some_string
+      #   Array === something
       #
+      # @example AllowOnConstant: true
       #   # good
       #   Array === something
-      #   (1..100).include?(7)
-      #   /something/.match?(some_string)
       #
       class CaseEquality < Base
         extend AutoCorrector

data/lib/rubocop/cop/style/case_like_if.rb

@@ -6,6 +6,11 @@ module RuboCop
       # This cop identifies places where `if-elsif` constructions
       # can be replaced with `case-when`.
       #
+      # @safety
+      #   This cop is unsafe. `case` statements use `===` for equality,
+      #   so if the original conditional used a different equality operator, the
+      #   behaviour may be different.
+      #
       # @example
       #   # bad
       #   if status == :active

data/lib/rubocop/cop/style/class_and_module_children.rb

@@ -6,6 +6,15 @@ module RuboCop
       # This cop checks the style of children definitions at classes and
       # modules. Basically there are two different styles:
       #
+      # @safety
+      #   Autocorrection is unsafe.
+      #
+      #   Moving from compact to nested children requires knowledge of whether the
+      #   outer parent is a module or a class. Moving from nested to compact requires
+      #   verification that the outer parent is defined elsewhere. Rubocop does not
+      #   have the knowledge to perform either operation safely and thus requires
+      #   manual oversight.
+      #
       # @example EnforcedStyle: nested (default)
       #   # good
       #   # have each child on its own line

data/lib/rubocop/cop/style/collection_compact.rb

@@ -6,11 +6,13 @@ module RuboCop
       # This cop checks for places where custom logic on rejection nils from arrays
       # and hashes can be replaced with `{Array,Hash}#{compact,compact!}`.
       #
-      # It is marked as unsafe by default because false positives may occur in the
-      # nil check of block arguments to the receiver object.
-      # For example, `[[1, 2], [3, nil]].reject { |first, second| second.nil? }`
-      # and `[[1, 2], [3, nil]].compact` are not compatible. This will work fine
-      # when the receiver is a hash object.
+      # @safety
+      #   It is unsafe by default because false positives may occur in the
+      #   `nil` check of block arguments to the receiver object.
+      #
+      #   For example, `[[1, 2], [3, nil]].reject { |first, second| second.nil? }`
+      #   and `[[1, 2], [3, nil]].compact` are not compatible. This will work fine
+      #   when the receiver is a hash object.
       #
       # @example
       #   # bad

data/lib/rubocop/cop/style/collection_methods.rb

@@ -6,10 +6,6 @@ module RuboCop
       # This cop enforces the use of consistent method names
       # from the Enumerable module.
       #
-      # Unfortunately we cannot actually know if a method is from
-      # Enumerable or not (static analysis limitation), so this cop
-      # can yield some false positives.
-      #
       # You can customize the mapping from undesired method to desired method.
       #
       # e.g. to use `detect` over `find`:
@@ -18,9 +14,14 @@ module RuboCop
       #     PreferredMethods:
       #       find: detect
       #
-      # The default mapping for `PreferredMethods` behaves as follows.
+      # @safety
+      #   This cop is unsafe because it finds methods by name, without actually
+      #   being able to determine if the receiver is an Enumerable or not, so
+      #   this cop may register false positives.
       #
       # @example
+      #   # These examples are based on the default mapping for `PreferredMethods`.
+      #
       #   # bad
       #   items.collect
       #   items.collect!
@@ -68,7 +69,8 @@ module RuboCop
           return false unless node.arguments.any?
 
           node.last_argument.block_pass_type? ||
-            node.last_argument.sym_type? && methods_accepting_symbol.include?(node.method_name.to_s)
+            (node.last_argument.sym_type? &&
+            methods_accepting_symbol.include?(node.method_name.to_s))
         end
 
         def message(node)

data/lib/rubocop/cop/style/combinable_loops.rb

@@ -7,8 +7,9 @@ module RuboCop
       # can be combined into a single loop. It is very likely that combining them
       # will make the code more efficient and more concise.
       #
-      # It is marked as unsafe, because the first loop might modify
-      # a state that the second loop depends on; these two aren't combinable.
+      # @safety
+      #   The cop is unsafe, because the first loop might modify state that the
+      #   second loop depends on; these two aren't combinable.
       #
       # @example
       #   # bad

data/lib/rubocop/cop/style/comment_annotation.rb

@@ -6,6 +6,9 @@ module RuboCop
       # This cop checks that comment annotation keywords are written according
       # to guidelines.
       #
+      # Annotation keywords can be specified by overriding the cop's `Keywords`
+      # configuration. Keywords are allowed to be single words or phrases.
+      #
       # NOTE: With a multiline comment block (where each line is only a
       # comment), only the first line will be able to register an offense, even
       # if an annotation keyword starts another line. This is done to prevent
@@ -56,7 +59,6 @@ module RuboCop
       #   # good
       #   # OPTIMIZE does not work
       class CommentAnnotation < Base
-        include AnnotationComment
         include RangeHelp
         extend AutoCorrector
 
@@ -73,27 +75,27 @@ module RuboCop
             next unless first_comment_line?(processed_source.comments, index) ||
                         inline_comment?(comment)
 
-            margin, first_word, colon, space, note = split_comment(comment)
-            next unless annotation?(comment) && !correct_annotation?(first_word, colon, space, note)
-
-            range = annotation_range(comment, margin, first_word, colon, space)
+            annotation = AnnotationComment.new(comment, keywords)
+            next unless annotation.annotation? && !annotation.correct?(colon: requires_colon?)
 
-            register_offense(range, note, first_word)
+            register_offense(annotation)
           end
         end
 
         private
 
-        def register_offense(range, note, first_word)
-          message = requires_colon? ? MSG_COLON_STYLE : MSG_SPACE_STYLE
+        def register_offense(annotation)
+          range = annotation_range(annotation)
+          message = if annotation.note
+                      requires_colon? ? MSG_COLON_STYLE : MSG_SPACE_STYLE
+                    else
+                      MISSING_NOTE
+                    end
 
-          add_offense(
-            range,
-            message: format(note ? message : MISSING_NOTE, keyword: first_word)
-          ) do |corrector|
-            next if note.nil?
+          add_offense(range, message: format(message, keyword: annotation.keyword)) do |corrector|
+            next if annotation.note.nil?
 
-            correct_offense(corrector, range, first_word)
+            correct_offense(corrector, range, annotation.keyword)
           end
         end
 
@@ -105,39 +107,23 @@ module RuboCop
           !comment_line?(comment.loc.expression.source_line)
         end
 
-        def annotation_range(comment, margin, first_word, colon, space)
-          start = comment.loc.expression.begin_pos + margin.length
-          length = concat_length(first_word, colon, space)
-          range_between(start, start + length)
-        end
-
-        def concat_length(*args)
-          args.reduce(0) { |acc, elem| acc + elem.to_s.length }
+        def annotation_range(annotation)
+          range_between(*annotation.bounds)
         end
 
-        def correct_annotation?(first_word, colon, space, note)
-          return correct_colon_annotation?(first_word, colon, space, note) if requires_colon?
+        def correct_offense(corrector, range, keyword)
+          return corrector.replace(range, "#{keyword.upcase}: ") if requires_colon?
 
-          correct_space_annotation?(first_word, colon, space, note)
-        end
-
-        def correct_colon_annotation?(first_word, colon, space, note)
-          keyword?(first_word) && (colon && space && note || !colon && !note)
-        end
-
-        def correct_space_annotation?(first_word, colon, space, note)
-          keyword?(first_word) && (!colon && space && note || !colon && !note)
-        end
-
-        def correct_offense(corrector, range, first_word)
-          return corrector.replace(range, "#{first_word.upcase}: ") if requires_colon?
-
-          corrector.replace(range, "#{first_word.upcase} ")
+          corrector.replace(range, "#{keyword.upcase} ")
         end
 
         def requires_colon?
           cop_config['RequireColon']
         end
+
+        def keywords
+          cop_config['Keywords']
+        end
       end
     end
   end

data/lib/rubocop/cop/style/commented_keyword.rb

@@ -12,7 +12,10 @@ module RuboCop
       #
       # Auto-correction removes comments from `end` keyword and keeps comments
       # for `class`, `module`, `def` and `begin` above the keyword.
-      # It is marked as unsafe auto-correction as it may remove meaningful comments.
+      #
+      # @safety
+      #   Auto-correction is unsafe because it may remove a comment that is
+      #   meaningful.
       #
       # @example
       #   # bad

data/lib/rubocop/cop/style/date_time.rb

@@ -9,6 +9,11 @@ module RuboCop
       # replaceable in certain situations when dealing with multiple timezones
       # and/or DST.
       #
+      # @safety
+      #   Autocorrection is not safe, because `DateTime` and `Time` do not have
+      #   exactly the same behaviour, although in most cases the autocorrection
+      #   will be fine.
+      #
       # @example
       #
       #   # bad - uses `DateTime` for current time

data/lib/rubocop/cop/style/document_dynamic_eval_definition.rb

@@ -86,7 +86,7 @@ module RuboCop
 
           return unless arg_node&.dstr_type? && interpolated?(arg_node)
           return if inline_comment_docs?(arg_node) ||
-                    arg_node.heredoc? && comment_block_docs?(arg_node)
+                    (arg_node.heredoc? && comment_block_docs?(arg_node))
 
           add_offense(node.loc.selector)
         end

data/lib/rubocop/cop/style/documentation.rb

@@ -71,8 +71,9 @@ module RuboCop
       #
       class Documentation < Base
         include DocumentationComment
+        include RangeHelp
 
-        MSG = 'Missing top-level %<type>s documentation comment.'
+        MSG = 'Missing top-level documentation comment for `%<type>s %<identifier>s`.'
 
         # @!method constant_definition?(node)
         def_node_matcher :constant_definition?, '{class module casgn}'
@@ -88,33 +89,35 @@ module RuboCop
         def on_class(node)
           return unless node.body
 
-          check(node, node.body, :class)
+          check(node, node.body)
         end
 
         def on_module(node)
-          check(node, node.body, :module)
+          check(node, node.body)
         end
 
         private
 
-        def check(node, body, type)
+        def check(node, body)
           return if namespace?(body)
           return if documentation_comment?(node)
           return if constant_allowed?(node)
           return if nodoc_self_or_outer_module?(node)
           return if macro_only?(body)
 
-          add_offense(node.loc.keyword, message: format(MSG, type: type))
+          range = range_between(node.loc.expression.begin_pos, node.loc.name.end_pos)
+          message = format(MSG, type: node.type, identifier: identifier(node))
+          add_offense(range, message: message)
         end
 
         def nodoc_self_or_outer_module?(node)
           nodoc_comment?(node) ||
-            compact_namespace?(node) && nodoc_comment?(outer_module(node).first)
+            (compact_namespace?(node) && nodoc_comment?(outer_module(node).first))
         end
 
         def macro_only?(body)
-          body.respond_to?(:macro?) && body.macro? ||
-            body.respond_to?(:children) && body.children&.all? { |child| macro_only?(child) }
+          (body.respond_to?(:macro?) && body.macro?) ||
+            (body.respond_to?(:children) && body.children&.all? { |child| macro_only?(child) })
         end
 
         def namespace?(node)
@@ -165,6 +168,18 @@ module RuboCop
         def allowed_constants
           @allowed_constants ||= cop_config.fetch('AllowedConstants', []).map(&:intern)
         end
+
+        def identifier(node)
+          # Get the fully qualified identifier for a class/module
+          nodes = [node, *node.each_ancestor(:class, :module)]
+          nodes.reverse_each.flat_map { |n| qualify_const(n.identifier) }.join('::')
+        end
+
+        def qualify_const(node)
+          return if node.nil?
+
+          [qualify_const(node.namespace), node.short_name].compact
+        end
       end
     end
   end

data/lib/rubocop/cop/style/double_negation.rb

@@ -9,6 +9,21 @@ module RuboCop
       # that use boolean as a return value. When using `EnforcedStyle: forbidden`, double negation
       # should be forbidden always.
       #
+      # NOTE: when `something` is a boolean value
+      # `!!something` and `!something.nil?` are not the same thing.
+      # As you're unlikely to write code that can accept values of any type
+      # this is rarely a problem in practice.
+      #
+      # @safety
+      #   Autocorrection is unsafe when the value is `false`, because the result
+      #   of the expression will change.
+      #
+      #   [source,ruby]
+      #   ----
+      #   !!false     #=> false
+      #   !false.nil? #=> true
+      #   ----
+      #
       # @example
       #   # bad
       #   !!something
@@ -27,11 +42,6 @@ module RuboCop
       #   def foo?
       #     !!return_value
       #   end
-      #
-      # Please, note that when something is a boolean value
-      # !!something and !something.nil? are not the same thing.
-      # As you're unlikely to write code that can accept values of any type
-      # this is rarely a problem in practice.
       class DoubleNegation < Base
         include ConfigurableEnforcedStyle
         extend AutoCorrector

data/lib/rubocop/cop/style/empty_method.rb

@@ -62,7 +62,7 @@ module RuboCop
         end
 
         def correct_style?(node)
-          compact_style? && compact?(node) || expanded_style? && expanded?(node)
+          (compact_style? && compact?(node)) || (expanded_style? && expanded?(node))
         end
 
         def corrected(node)

data/lib/rubocop/cop/style/explicit_block_argument.rb

@@ -67,17 +67,27 @@ module RuboCop
             # so this can cause crashes in haml_lint
             return unless def_node
 
+            block_name = extract_block_name(def_node)
+
             add_offense(block_node) do |corrector|
               corrector.remove(block_body_range(block_node, send_node))
 
-              add_block_argument(send_node, corrector)
-              add_block_argument(def_node, corrector) if @def_nodes.add?(def_node)
+              add_block_argument(send_node, corrector, block_name)
+              add_block_argument(def_node, corrector, block_name) if @def_nodes.add?(def_node)
             end
           end
         end
 
         private
 
+        def extract_block_name(def_node)
+          if def_node.block_argument?
+            def_node.arguments.last.name
+          else
+            'block'
+          end
+        end
+
         def yielding_arguments?(block_args, yield_args)
           yield_args = yield_args.dup.fill(
             nil,
@@ -91,15 +101,15 @@ module RuboCop
           end
         end
 
-        def add_block_argument(node, corrector)
+        def add_block_argument(node, corrector, block_name)
           if node.arguments?
-            insert_argument(node, corrector)
+            insert_argument(node, corrector, block_name)
           elsif empty_arguments?(node)
-            corrector.replace(node.arguments, '(&block)')
+            corrector.replace(node.arguments, "(&#{block_name})")
           elsif call_like?(node)
-            correct_call_node(node, corrector)
+            correct_call_node(node, corrector, block_name)
           else
-            corrector.insert_after(node.loc.name, '(&block)')
+            corrector.insert_after(node.loc.name, "(&#{block_name})")
           end
         end
 
@@ -112,16 +122,16 @@ module RuboCop
           node.call_type? || node.zsuper_type? || node.super_type?
         end
 
-        def insert_argument(node, corrector)
+        def insert_argument(node, corrector, block_name)
           last_arg = node.arguments.last
           arg_range = range_with_surrounding_comma(last_arg.source_range, :right)
-          replacement = ' &block'
+          replacement = " &#{block_name}"
           replacement = ",#{replacement}" unless arg_range.source.end_with?(',')
           corrector.insert_after(arg_range, replacement) unless last_arg.blockarg_type?
         end
 
-        def correct_call_node(node, corrector)
-          corrector.insert_after(node, '(&block)')
+        def correct_call_node(node, corrector, block_name)
+          corrector.insert_after(node, "(&#{block_name})")
           return unless node.parenthesized?
 
           args_begin = Util.args_begin(node)

data/lib/rubocop/cop/style/float_division.rb

@@ -7,8 +7,16 @@ module RuboCop
       # It is recommended to either always use `fdiv` or coerce one side only.
       # This cop also provides other options for code consistency.
       #
-      # This cop is marked as unsafe, because if operand variable is a string object
-      # then `.to_f` will be removed and an error will occur.
+      # @safety
+      #   This cop is unsafe, because if the operand variable is a string object
+      #   then `.to_f` will be removed and an error will occur.
+      #
+      #   [source,ruby]
+      #   ----
+      #   a = '1.2'
+      #   b = '3.4'
+      #   a.to_f / b.to_f # Both `to_f` calls are required here
+      #   ----
       #
       # @example EnforcedStyle: single_coerce (default)
       #   # bad

data/lib/rubocop/cop/style/frozen_string_literal_comment.rb

@@ -10,12 +10,17 @@ module RuboCop
       # default in future Ruby. The comment will be added below a shebang and
       # encoding comment.
       #
-      # Note that the cop will ignore files where the comment exists but is set
+      # Note that the cop will accept files where the comment exists but is set
       # to `false` instead of `true`.
       #
       # To require a blank line after this comment, please see
       # `Layout/EmptyLineAfterMagicComment` cop.
       #
+      # @safety
+      #  This cop's autocorrection is unsafe since any strings mutations will
+      #  change from being accepted to raising `FrozenError`, as all strings
+      #  will become frozen by default, and will need to be manually refactored.
+      #
       # @example EnforcedStyle: always (default)
       #   # The `always` style will always add the frozen string literal comment
       #   # to a file, regardless of the Ruby version or if `freeze` or `<<` are
@@ -141,7 +146,7 @@ module RuboCop
 
         def frozen_string_literal_comment(processed_source)
           processed_source.find_token do |token|
-            token.text.start_with?(FrozenStringLiteral::FROZEN_STRING_LITERAL)
+            token.text.start_with?(FROZEN_STRING_LITERAL)
           end
         end
 

data/lib/rubocop/cop/style/global_std_stream.rb

@@ -8,6 +8,10 @@ module RuboCop
       # reassign (possibly to redirect some stream) constants in Ruby, you'll get
       # an interpreter warning if you do so.
       #
+      # @safety
+      #   Autocorrection is unsafe because `STDOUT` and `$stdout` may point to different
+      #   objects, for example.
+      #
       # @example
       #   # bad
       #   STDOUT.puts('hello')

data/lib/rubocop/cop/style/hash_each_methods.rb

@@ -9,6 +9,11 @@ module RuboCop
       #   parentheses around the block arguments to indicate that you're not
       #   working with a hash, and suppress RuboCop offenses.
       #
+      # @safety
+      #   This cop is unsafe because it cannot be guaranteed that the receiver
+      #   is a `Hash`. The `AllowedReceivers` configuration can mitigate,
+      #   but not fully resolve, this safety issue.
+      #
       # @example
       #   # bad
       #   hash.keys.each { |k| p k }