rubocop 1.21.0 → 1.22.0

data/lib/rubocop/cop/lint/unexpected_block_arity.rb

@@ -13,14 +13,19 @@ module RuboCop
       # Keyword arguments (including `**kwargs`) do not get counted towards
       # this, as they are not used by the methods in question.
       #
-      # NOTE: This cop matches for method names only and hence cannot tell apart
-      # methods with same name in different classes.
-      #
       # Method names and their expected arity can be configured like this:
       #
+      # [source,yaml]
+      # ----
       # Methods:
       #   inject: 2
       #   reduce: 2
+      # ----
+      #
+      # @safety
+      #  This cop matches for method names only and hence cannot tell apart
+      #  methods with same name in different classes, which may lead to a
+      #  false positive.
       #
       # @example
       #   # bad

data/lib/rubocop/cop/lint/useless_method_definition.rb

@@ -6,8 +6,9 @@ module RuboCop
       # This cop checks for useless method definitions, specifically: empty constructors
       # and methods just delegating to `super`.
       #
-      # This cop is marked as unsafe as it can trigger false positives for cases when
-      # an empty constructor just overrides the parent constructor, which is bad anyway.
+      # @safety
+      #   This cop is unsafe as it can register false positives for cases when an empty
+      #   constructor just overrides the parent constructor, which is bad anyway.
       #
       # @example
       #   # bad

data/lib/rubocop/cop/lint/useless_setter_call.rb

@@ -5,11 +5,14 @@ module RuboCop
     module Lint
       # This cop checks for setter call to local variable as the final
       # expression of a function definition.
-      # Its auto-correction is marked as unsafe because return value will be changed.
       #
-      # NOTE: There are edge cases in which the local variable references a
-      # value that is also accessible outside the local scope. This is not
-      # detected by the cop, and it can yield a false positive.
+      # @safety
+      #   There are edge cases in which the local variable references a
+      #   value that is also accessible outside the local scope. This is not
+      #   detected by the cop, and it can yield a false positive.
+      #
+      #   As well, auto-correction is unsafe because the method's
+      #   return value will be changed.
       #
       # @example
       #

data/lib/rubocop/cop/lint/useless_times.rb

@@ -7,8 +7,9 @@ module RuboCop
       # (when the integer <= 0) or that will only ever yield once
       # (`1.times`).
       #
-      # This cop is marked as unsafe as `times` returns its receiver, which
-      # is *usually* OK, but might change behavior.
+      # @safety
+      #   This cop is unsafe as `times` returns its receiver, which is
+      #   *usually* OK, but might change behavior.
       #
       # @example
       #   # bad

data/lib/rubocop/cop/metrics/abc_size.rb

@@ -8,6 +8,12 @@ module RuboCop
       # (method calls), and conditions. See http://c2.com/cgi/wiki?AbcMetric
       # and https://en.wikipedia.org/wiki/ABC_Software_Metric.
       #
+      # Interpreting ABC size:
+      #
+      # * <= 17 satisfactory
+      # * 18..30 unsatisfactory
+      # * > 30 dangerous
+      #
       # You can have repeated "attributes" calls count as a single "branch".
       # For this purpose, attributes are any method with no argument; no attempt
       # is meant to distinguish actual `attr_reader` from other methods.

data/lib/rubocop/cop/mixin/frozen_string_literal.rb

@@ -20,7 +20,7 @@ module RuboCop
 
       def frozen_string_literal?(node)
         frozen_string = if target_ruby_version >= 3.0
-                          node.str_type? || frozen_heredoc?(node)
+                          uninterpolated_string?(node) || frozen_heredoc?(node)
                         else
                           FROZEN_STRING_LITERAL_TYPES_RUBY27.include?(node.type)
                         end
@@ -28,6 +28,10 @@ module RuboCop
         frozen_string && frozen_string_literals_enabled?
       end
 
+      def uninterpolated_string?(node)
+        node.str_type? || (node.dstr_type? && node.each_descendant(:begin).none?)
+      end
+
       def frozen_heredoc?(node)
         return false unless node.dstr_type? && node.heredoc?
 

data/lib/rubocop/cop/mixin/heredoc.rb

@@ -21,9 +21,7 @@ module RuboCop
       private
 
       def indent_level(str)
-        indentations = str.lines
-                          .map { |line| line[/^\s*/] }
-                          .reject { |line| line.end_with?("\n") }
+        indentations = str.lines.map { |line| line[/^\s*/] }.reject { |line| line.end_with?("\n") }
         indentations.empty? ? 0 : indentations.min_by(&:size).size
       end
 

data/lib/rubocop/cop/mixin/ordered_gem_node.rb

@@ -35,7 +35,15 @@ module RuboCop
           previous: gem_name(current),
           current: gem_name(previous)
         )
-        add_offense(current, message: message)
+
+        add_offense(current, message: message) do |corrector|
+          OrderedGemCorrector.correct(
+            processed_source,
+            current,
+            previous_declaration(current),
+            treat_comments_as_separators
+          ).call(corrector)
+        end
       end
 
       def gem_name(declaration_node)

data/lib/rubocop/cop/mixin/percent_array.rb

@@ -36,7 +36,12 @@ module RuboCop
       def check_percent_array(node)
         array_style_detected(:percent, node.values.size)
 
-        return unless style == :brackets || invalid_percent_array_contents?(node)
+        brackets_required = invalid_percent_array_contents?(node)
+        return unless style == :brackets || brackets_required
+
+        # If in percent style but brackets are required due to
+        # string content, the file should be excluded in auto-gen-config
+        no_acceptable_style! if brackets_required
 
         bracketed_array = build_bracketed_array(node)
         message = format(self.class::ARRAY_MSG, prefer: bracketed_array)

data/lib/rubocop/cop/naming/block_parameter_name.rb

@@ -24,7 +24,7 @@ module RuboCop
       #   # With `AllowNamesEndingInNumbers` set to false
       #   foo { |num1, num2| num1 * num2 }
       #
-      #   # With `MinParamNameLength` set to number greater than 1
+      #   # With `MinNameLength` set to number greater than 1
       #   baz { |a, b, c| do_stuff(a, b, c) }
       #
       #   # good

data/lib/rubocop/cop/naming/memoized_instance_variable_name.rb

@@ -14,6 +14,11 @@ module RuboCop
       # convention that is used to implicitly indicate that an ivar should not
       # be set or referenced outside of the memoization method.
       #
+      # @safety
+      #   This cop relies on the pattern `@instance_var ||= ...`,
+      #   but this is sometimes used for other purposes than memoization
+      #   so this cop is considered unsafe.
+      #
       # @example EnforcedStyleForLeadingUnderscores: disallowed (default)
       #   # bad
       #   # Method foo is memoized using an instance variable that is
@@ -139,10 +144,6 @@ module RuboCop
       #   define_method(:foo) do
       #     @_foo ||= calculate_expensive_thing
       #   end
-      #
-      # This cop relies on the pattern `@instance_var ||= ...`,
-      # but this is sometimes used for other purposes than memoization
-      # so this cop is considered unsafe.
       class MemoizedInstanceVariableName < Base
         include ConfigurableEnforcedStyle
 

data/lib/rubocop/cop/naming/rescued_exceptions_variable_name.rb

@@ -75,6 +75,9 @@ module RuboCop
           preferred_name = preferred_name(offending_name)
           return if preferred_name.to_sym == offending_name
 
+          # check variable shadowing for exception variable
+          return if shadowed_variable_name?(node)
+
           range = offense_range(node)
           message = message(node)
 
@@ -150,6 +153,10 @@ module RuboCop
           preferred_name = preferred_name(offending_name)
           format(MSG, preferred: preferred_name, bad: offending_name)
         end
+
+        def shadowed_variable_name?(node)
+          node.each_descendant(:lvar).any? { |n| n.children.first.to_s == preferred_name(n) }
+        end
       end
     end
   end

data/lib/rubocop/cop/security/io_methods.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Security
+      # Checks for the first argument to `IO.read`, `IO.binread`, `IO.write`, `IO.binwrite`,
+      # `IO.foreach`, and `IO.readlines`.
+      #
+      # If argument starts with a pipe character (`'|'`) and the receiver is the `IO` class,
+      # a subprocess is created in the same way as `Kernel#open`, and its output is returned.
+      # `Kernel#open` may allow unintentional command injection, which is the reason these
+      # `IO` methods are a security risk.
+      # Consider to use `File.read` to disable the behavior of subprocess invocation.
+      #
+      # @safety
+      #   This cop is unsafe because false positive will occur if the variable passed as
+      #   the first argument is a command that is not a file path.
+      #
+      # @example
+      #
+      #   # bad
+      #   IO.read(path)
+      #   IO.read('path')
+      #
+      #   # good
+      #   File.read(path)
+      #   File.read('path')
+      #   IO.read('| command') # Allow intentional command invocation.
+      #
+      class IoMethods < Base
+        extend AutoCorrector
+
+        MSG = '`File.%<method_name>s` is safer than `IO.%<method_name>s`.'
+        RESTRICT_ON_SEND = %i[read binread write binwrite foreach readlines].freeze
+
+        def on_send(node)
+          return unless (receiver = node.receiver) && receiver.source == 'IO'
+
+          argument = node.first_argument
+          return if argument.respond_to?(:value) && argument.value.strip.start_with?('|')
+
+          add_offense(node, message: format(MSG, method_name: node.method_name)) do |corrector|
+            corrector.replace(receiver, 'File')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/security/json_load.rb

@@ -6,13 +6,14 @@ module RuboCop
       # This cop checks for the use of JSON class methods which have potential
       # security issues.
       #
-      # Autocorrect is disabled by default because it's potentially dangerous.
-      # If using a stream, like `JSON.load(open('file'))`, it will need to call
-      # `#read` manually, like `JSON.parse(open('file').read)`.
-      # If reading single values (rather than proper JSON objects), like
-      # `JSON.load('false')`, it will need to pass the `quirks_mode: true`
-      # option, like `JSON.parse('false', quirks_mode: true)`.
-      # Other similar issues may apply.
+      # @safety
+      #   Autocorrect is disabled by default because it's potentially dangerous.
+      #   If using a stream, like `JSON.load(open('file'))`, it will need to call
+      #   `#read` manually, like `JSON.parse(open('file').read)`.
+      #   If reading single values (rather than proper JSON objects), like
+      #   `JSON.load('false')`, it will need to pass the `quirks_mode: true`
+      #   option, like `JSON.parse('false', quirks_mode: true)`.
+      #   Other similar issues may apply.
       #
       # @example
       #   # bad

data/lib/rubocop/cop/security/open.rb

@@ -11,6 +11,10 @@ module RuboCop
       # the argument of `Kernel#open` and `URI.open`. It would be better to use
       # `File.open`, `IO.popen` or `URI.parse#open` explicitly.
       #
+      # @safety
+      #   This cop could register false positives if `open` is redefined
+      #   in a class and then used without a receiver in that class.
+      #
       # @example
       #   # bad
       #   open(something)

data/lib/rubocop/cop/security/yaml_load.rb

@@ -7,6 +7,10 @@ module RuboCop
       # potential security issues leading to remote code execution when
       # loading from an untrusted source.
       #
+      # @safety
+      #   The behaviour of the code might change depending on what was
+      #   in the YAML payload, since `YAML.safe_load` is more restrictive.
+      #
       # @example
       #   # bad
       #   YAML.load("--- foo")

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

@@ -7,9 +7,10 @@ module RuboCop
       # `||` instead. It can be configured to check only in conditions or in
       # all contexts.
       #
-      # It is marked as unsafe auto-correction because it may change the
-      # operator precedence between logical operators (`&&` and `||`) and
-      # semantic operators (`and` and `or`).
+      # @safety
+      #   Auto-correction is unsafe because there is a different operator precedence
+      #   between logical operators (`&&` and `||`) and semantic operators (`and` and `or`),
+      #   and that might change the behaviour.
       #
       # @example EnforcedStyle: always
       #   # bad

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

@@ -30,6 +30,10 @@ module RuboCop
       #     bar(*args)
       #   end
       #
+      #   def foo(**kwargs)
+      #     bar(**kwargs)
+      #   end
+      #
       # @example AllowOnlyRestArgument: false
       #   # bad
       #   # The following code can replace the arguments with `...`,
@@ -38,6 +42,10 @@ module RuboCop
       #     bar(*args)
       #   end
       #
+      #   def foo(**kwargs)
+      #     bar(**kwargs)
+      #   end
+      #
       class ArgumentsForwarding < Base
         include RangeHelp
         extend AutoCorrector
@@ -49,12 +57,15 @@ module RuboCop
 
         # @!method use_rest_arguments?(node)
         def_node_matcher :use_rest_arguments?, <<~PATTERN
-          (args (restarg $_) $...)
+          (args ({restarg kwrestarg} $_) $...)
         PATTERN
 
         # @!method only_rest_arguments?(node, name)
         def_node_matcher :only_rest_arguments?, <<~PATTERN
-          (send _ _ (splat (lvar %1)))
+          {
+            (send _ _ (splat (lvar %1)))
+            (send _ _ (hash (kwsplat (lvar %1))))
+          }
         PATTERN
 
         # @!method forwarding_method_arguments?(node, rest_name, block_name, kwargs_name)

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/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!

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/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/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/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

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 }

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

@@ -8,12 +8,10 @@ module RuboCop
       # transforming the keys of a hash, and tries to use a simpler & faster
       # call to `transform_keys` instead.
       #
-      # This can produce false positives if we are transforming an enumerable
-      # of key-value-like pairs that isn't actually a hash, e.g.:
-      # `[[k1, v1], [k2, v2], ...]`
-      #
-      # This cop should only be enabled on Ruby version 2.5 or newer
-      # (`transform_keys` was added in Ruby 2.5.)
+      # @safety
+      #   This cop is unsafe, as it can produce false positives if we are
+      #   transforming an enumerable of key-value-like pairs that isn't actually
+      #   a hash, e.g.: `[[k1, v1], [k2, v2], ...]`
       #
       # @example
       #   # bad

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

@@ -8,12 +8,10 @@ module RuboCop
       # transforming the values of a hash, and tries to use a simpler & faster
       # call to `transform_values` instead.
       #
-      # This can produce false positives if we are transforming an enumerable
-      # of key-value-like pairs that isn't actually a hash, e.g.:
-      # `[[k1, v1], [k2, v2], ...]`
-      #
-      # This cop should only be enabled on Ruby version 2.4 or newer
-      # (`transform_values` was added in Ruby 2.4.)
+      # @safety
+      #   This cop is unsafe, as it can produce false positives if we are
+      #   transforming an enumerable of key-value-like pairs that isn't actually
+      #   a hash, e.g.: `[[k1, v1], [k2, v2], ...]`
       #
       # @example
       #   # bad