rubocop 1.75.7 → 1.76.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef87f85272e845ecc9477a7c890be9f5d8daa78ef1c9625c3252ca8bee58ee40
-  data.tar.gz: aeb5a1576ba984944521e10cd92933cbf37080d492a25ed8e51bf46926dc0c4a
+  metadata.gz: 236bdf0fa5879274099388142e17b886fc852cdc1e762d50c74a31254c7c6136
+  data.tar.gz: 03011b196c686aa5ce1cc617d56c19041dbdc76ba237626316048be9e75dc62c
 SHA512:
-  metadata.gz: 7f668097cd95658c24f521bed8e11b43c3b5ff01bdb49bc2e1cc5a71af630cb751a402bf8026f90cb95907fea56ff2cabe5ea0139329fa3e7fc31a46ca615fc4
-  data.tar.gz: cb542cf88e2de605a086e69009dcb8ae2afa4d0b7a713671e6c134cf8b77e5ccd4f6e408c6566be62d57809552e7ef0de30b849b619b0192c358a1441d4060a8
+  metadata.gz: 91eb23282705c816206704923efdea2cb45ad09677a5d72a8741a565d9ed96146ad688aa54c1dc5be7f6d83c6e4d099605bdd91cb941d0d2b1fb36ace05b02a8
+  data.tar.gz: 6ff783d52e62e4dda5cae1c78f8648ef8af4078c5f052134a23c9229018e33d29a21d3ecaa80bfdc74d382b73a1a666f67d9e1b3436b1dfb5745a96861cf92ec

data/README.md

@@ -36,10 +36,11 @@ Working on RuboCop is often fun, but it also requires a great deal of time and e
 **RuboCop**'s installation is pretty standard:
 
 ```sh
-$ gem install rubocop
+gem install rubocop
 ```
 
-If you'd rather install RuboCop using `bundler`, add a line for it in your `Gemfile` (but set the `require` option to `false`, as it is a standalone tool):
+If you'd rather install RuboCop using `bundler`, add a line for it in your
+`Gemfile` (but set the `require` option to `false`, as it is a standalone tool):
 
 ```rb
 gem 'rubocop', require: false
@@ -52,7 +53,7 @@ To prevent an unwanted RuboCop update you might want to use a conservative versi
 in your `Gemfile`:
 
 ```rb
-gem 'rubocop', '~> 1.75', require: false
+gem 'rubocop', '~> 1.76', require: false
 ```
 
 See [our versioning policy](https://docs.rubocop.org/rubocop/versioning.html) for further details.
@@ -61,12 +62,15 @@ See [our versioning policy](https://docs.rubocop.org/rubocop/versioning.html) fo
 
 Just type `rubocop` in a Ruby project's folder and watch the magic happen.
 
-```
-$ cd my/cool/ruby/project
-$ rubocop
+```sh
+cd my/cool/ruby/project
+rubocop
 ```
 
-You can also use this magic in your favorite editor with RuboCop's [built-in LSP server](https://docs.rubocop.org/rubocop/usage/lsp.html).
+> [!TIP]
+>
+> You can also use this magic in your favorite editor with RuboCop's
+> [built-in LSP server](https://docs.rubocop.org/rubocop/usage/lsp.html).
 
 ## Documentation
 
@@ -79,7 +83,7 @@ RuboCop officially supports the following runtime Ruby implementations:
 * MRI 2.7+
 * JRuby 9.4+
 
-Targets Ruby 2.0+ code analysis.
+It targets Ruby 2.0+ for code analysis.
 
 See the [compatibility documentation](https://docs.rubocop.org/rubocop/compatibility.html) for further details.
 
@@ -91,7 +95,6 @@ If you use RuboCop in your project, you can include one of these badges in your
 
 [![Ruby Style Guide](https://img.shields.io/badge/code_style-community-brightgreen.svg)](https://rubystyle.guide)
 
-
 Here are the Markdown snippets for the two badges:
 
 ``` markdown
@@ -157,8 +160,8 @@ wide array of funding channels to account for your preferences
 currently [Open Collective](https://opencollective.com/rubocop) is our
 preferred funding platform).
 
-**If you're working in a company that's making significant use of RuboCop we'd appreciate it if you suggest to your company
-to become a RuboCop sponsor.**
+**If you're working in a company that's making significant use of RuboCop we'd
+appreciate it if you suggest to your company to become a RuboCop sponsor.**
 
 You can support the development of RuboCop via
 [GitHub Sponsors](https://github.com/sponsors/bbatsov),
@@ -168,8 +171,11 @@ You can support the development of RuboCop via
 and [Tidelift](https://tidelift.com/subscription/pkg/rubygems-rubocop?utm_source=rubygems-rubocop&utm_medium=referral&utm_campaign=readme)
 .
 
-**Note:** If doing a sponsorship in the form of donation is problematic for your company from an accounting standpoint, we'd recommend
-the use of Tidelift, where you can get a support-like subscription instead.
+> [!NOTE]
+>
+> If doing a sponsorship in the form of donation is problematic for your company
+> from an accounting standpoint, we'd recommend the use of Tidelift, where you
+> can get a support-like subscription instead.
 
 ### Open Collective for Individuals
 

data/config/default.yml

@@ -1923,7 +1923,7 @@ Lint/EmptyInterpolation:
   Enabled: true
   AutoCorrect: contextual
   VersionAdded: '0.20'
-  VersionChanged: '1.61'
+  VersionChanged: '1.76'
 
 Lint/EmptyWhen:
   Description: 'Checks for `when` branches with empty bodies.'
@@ -2423,8 +2423,9 @@ Lint/ShadowingOuterLocalVariable:
   Description: >-
                  Do not use the same name as outer local variable
                  for block arguments or block local variables.
-  Enabled: true
+  Enabled: false
   VersionAdded: '0.9'
+  VersionChanged: '1.76'
 
 Lint/SharedMutableDefault:
   Description: 'Checks for mutable literals used as default arguments during Hash initialization.'
@@ -2612,6 +2613,13 @@ Lint/UselessConstantScoping:
   Enabled: pending
   VersionAdded: '1.72'
 
+Lint/UselessDefaultValueArgument:
+  Description: 'Checks for usage of `fetch` or `Array.new` with default value argument and block.'
+  Enabled: pending
+  VersionAdded: '1.76'
+  Safe: false
+  AllowedReceivers: []
+
 Lint/UselessDefined:
   Description: 'Checks for calls to `defined?` with strings and symbols. The result of such a call will always be truthy.'
   Enabled: pending
@@ -2636,6 +2644,11 @@ Lint/UselessNumericOperation:
   Enabled: pending
   VersionAdded: '1.66'
 
+Lint/UselessOr:
+  Description: 'Checks for useless OR expressions.'
+  Enabled: pending
+  VersionAdded: '1.76'
+
 Lint/UselessRescue:
   Description: 'Checks for useless `rescue`s.'
   Enabled: pending
@@ -3046,8 +3059,20 @@ Naming/MethodParameterName:
   # Forbidden names that will register an offense
   ForbiddenNames: []
 
-Naming/PredicateName:
-  Description: 'Check the names of predicate methods.'
+Naming/PredicateMethod:
+  Description: 'Checks that predicate methods end with `?` and non-predicate methods do not.'
+  Enabled: pending
+  VersionAdded: '1.76'
+  # In `aggressive` mode, the cop will register an offense for predicate methods that
+  #   may return a non-boolean value.
+  # In `conservative` mode, the cop will *not* register an offense for predicate methods
+  #   that may return a non-boolean value.
+  Mode: conservative
+  AllowedMethods:
+    - call
+
+Naming/PredicatePrefix:
+  Description: 'Predicate method names should not be prefixed and end with a `?`.'
   StyleGuide: '#bool-methods-qmark'
   Enabled: true
   VersionAdded: '0.50'
@@ -3939,6 +3964,16 @@ Style/EmptyMethod:
     - compact
     - expanded
 
+Style/EmptyStringInsideInterpolation:
+  Description: 'Checks for empty strings being assigned inside string interpolation.'
+  StyleGuide: '#empty-strings-in-interpolation'
+  Enabled: pending
+  EnforcedStyle: trailing_conditional
+  SupportedStyles:
+    - trailing_conditional
+    - ternary
+  VersionAdded: '1.76'
+
 Style/Encoding:
   Description: 'Use UTF-8 as the source file encoding.'
   StyleGuide: '#utf-8'
@@ -4433,12 +4468,14 @@ Style/ItAssignment:
 Style/ItBlockParameter:
   Description: 'Checks for blocks with one argument where `it` block parameter can be used.'
   Enabled: pending
-  EnforcedStyle: only_numbered_parameters
+  EnforcedStyle: allow_single_line
   SupportedStyles:
+    - allow_single_line
     - only_numbered_parameters
     - always
     - disallow
   VersionAdded: '1.75'
+  VersionChanged: '1.76'
 
 Style/KeywordArgumentsMerging:
   Description: >-
@@ -5151,6 +5188,12 @@ Style/RedundantArrayConstructor:
   Enabled: pending
   VersionAdded: '1.52'
 
+Style/RedundantArrayFlatten:
+  Description: 'Checks for redundant calls of `Array#flatten`.'
+  Enabled: pending
+  Safe: false
+  VersionAdded: '1.76'
+
 Style/RedundantAssignment:
   Description: 'Checks for redundant assignment before returning.'
   Enabled: true

data/config/obsoletion.yml

@@ -31,6 +31,9 @@ renamed:
   Lint/UnneededRequireStatement: Lint/RedundantRequireStatement
   Lint/UnneededSplatExpansion: Lint/RedundantSplatExpansion
   Metrics/LineLength: Layout/LineLength
+  Naming/PredicateName:
+    new_name: Naming/PredicatePrefix
+    severity: warning
   Naming/UncommunicativeBlockParamName: Naming/BlockParameterName
   Naming/UncommunicativeMethodParamName: Naming/MethodParameterName
   Style/AccessorMethodName: Naming/AccessorMethodName
@@ -44,7 +47,7 @@ renamed:
   Style/MethodName: Naming/MethodName
   Style/OpMethod: Naming/BinaryOperatorParameterName
   Style/PredicateName:
-    new_name: Naming/PredicateName
+    new_name: Naming/PredicatePrefix
     severity: warning
   Style/SingleSpaceBeforeFirstArg: Layout/SpaceBeforeFirstArg
   Style/UnneededCapitalW: Style/RedundantCapitalW
@@ -179,10 +182,10 @@ changed_parameters:
   - cops: Naming/HeredocDelimiterNaming
     parameters: Blacklist
     alternative: ForbiddenDelimiters
-  - cops: Naming/PredicateName
+  - cops: Naming/PredicatePrefix
     parameters: NamePrefixBlacklist
     alternative: ForbiddenPrefixes
-  - cops: Naming/PredicateName
+  - cops: Naming/PredicatePrefix
     parameters: NameWhitelist
     alternative: AllowedMethods
   - cops:

data/lib/rubocop/cop/autocorrect_logic.rb

@@ -50,7 +50,7 @@ module RuboCop
 
       def disable_offense(offense_range)
         unbreakable_range = multiline_ranges(offense_range)&.find do |range|
-          range_overlaps_offense?(offense_range, range)
+          eol_comment_would_be_inside_literal?(offense_range, range)
         end
 
         if unbreakable_range
@@ -75,18 +75,22 @@ module RuboCop
       end
 
       def disable_offense_with_eol_or_surround_comment(range)
-        eol_comment = " # rubocop:todo #{cop_name}"
-        needed_line_length = (range.source_line + eol_comment).length
-
-        if needed_line_length <= max_line_length
-          disable_offense_at_end_of_line(range_of_first_line(range), eol_comment)
-        else
+        if line_with_eol_comment_too_long?(range)
           disable_offense_before_and_after(range_by_lines(range))
+        else
+          disable_offense_at_end_of_line(range_of_first_line(range))
         end
       end
 
-      def range_overlaps_offense?(offense_range, range)
-        offense_range.begin_pos > range.begin_pos && range.overlaps?(offense_range)
+      def eol_comment_would_be_inside_literal?(offense_range, literal_range)
+        return true if line_with_eol_comment_too_long?(offense_range)
+
+        offense_line = offense_range.line
+        offense_line >= literal_range.first_line && offense_line < literal_range.last_line
+      end
+
+      def line_with_eol_comment_too_long?(range)
+        (range.source_line + eol_comment).length > max_line_length
       end
 
       def surrounding_heredoc?(node)
@@ -132,10 +136,14 @@ module RuboCop
         config.for_cop('Layout/LineLength')['Max'] || 120
       end
 
-      def disable_offense_at_end_of_line(range, eol_comment)
+      def disable_offense_at_end_of_line(range)
         Corrector.new(range).insert_after(range, eol_comment)
       end
 
+      def eol_comment
+        " # rubocop:todo #{cop_name}"
+      end
+
       def disable_offense_before_and_after(range_by_lines)
         range_with_newline = range_by_lines.resize(range_by_lines.size + 1)
         leading_whitespace = range_by_lines.source_line[/^\s*/]

data/lib/rubocop/cop/bundler/ordered_gems.rb

@@ -45,7 +45,7 @@ module RuboCop
 
           gem_declarations(processed_source.ast)
             .each_cons(2) do |previous, current|
-            next unless consecutive_lines(previous, current)
+            next unless consecutive_lines?(previous, current)
             next unless case_insensitive_out_of_order?(gem_name(current), gem_name(previous))
 
             register_offense(previous, current)

data/lib/rubocop/cop/gemspec/duplicated_assignment.rb

@@ -57,13 +57,13 @@ module RuboCop
         # @!method assignment_method_declarations(node)
         def_node_search :assignment_method_declarations, <<~PATTERN
           (send
-            (lvar #match_block_variable_name?) _ ...)
+            (lvar {#match_block_variable_name? :_1 :it}) _ ...)
         PATTERN
 
         # @!method indexed_assignment_method_declarations(node)
         def_node_search :indexed_assignment_method_declarations, <<~PATTERN
           (send
-            (send (lvar #match_block_variable_name?) _)
+            (send (lvar {#match_block_variable_name? :_1 :it}) _)
             :[]=
             literal?
             _

data/lib/rubocop/cop/gemspec/ordered_dependencies.rb

@@ -71,7 +71,7 @@ module RuboCop
 
           dependency_declarations(processed_source.ast)
             .each_cons(2) do |previous, current|
-            next unless consecutive_lines(previous, current)
+            next unless consecutive_lines?(previous, current)
             next unless case_insensitive_out_of_order?(gem_name(current), gem_name(previous))
             next unless get_dependency_name(previous) == get_dependency_name(current)
 

data/lib/rubocop/cop/internal_affairs/node_pattern_groups.rb

@@ -29,6 +29,7 @@ module RuboCop
         NODE_GROUPS = {
           any_block: %i[block numblock itblock],
           any_def: %i[def defs],
+          any_match_pattern: %i[match_pattern match_pattern_p],
           argument: %i[arg optarg restarg kwarg kwoptarg kwrestarg blockarg forward_arg shadowarg],
           boolean: %i[true false],
           call: %i[send csend],

data/lib/rubocop/cop/layout/class_structure.rb

@@ -22,6 +22,11 @@ module RuboCop
       # * Private attribute macros (`attr_accessor`, `attr_writer`, `attr_reader`)
       # * Private instance methods
       #
+      # NOTE: Simply enabling the cop with `Enabled: true` will not use
+      # the example order shown below.
+      # To enforce the order of macros like `attr_reader`,
+      # you must define both `ExpectedOrder` *and* `Categories`.
+      #
       # You can configure the following order:
       #
       # [source,yaml]
@@ -68,6 +73,36 @@ module RuboCop
       #        - extend
       # ----
       #
+      # If you only set `ExpectedOrder`
+      # without defining `Categories`,
+      # macros such as `attr_reader` or `has_many`
+      # will not be recognized as part of a category, and their order will not be validated.
+      # For example, the following will NOT raise any offenses, even if the order is incorrect:
+      #
+      # [source,yaml]
+      # ----
+      # Layout/ClassStructure:
+      #   Enabled: true
+      #   ExpectedOrder:
+      #     - public_attribute_macros
+      #     - initializer
+      # ----
+      #
+      # To make it work as expected, you must also specify `Categories` like this:
+      #
+      # [source,yaml]
+      # ----
+      # Layout/ClassStructure:
+      #   ExpectedOrder:
+      #     - public_attribute_macros
+      #     - initializer
+      #   Categories:
+      #     attribute_macros:
+      #       - attr_reader
+      #       - attr_writer
+      #       - attr_accessor
+      # ----
+      #
       # @safety
       #   Autocorrection is unsafe because class methods and module inclusion
       #   can behave differently, based on which methods or constants have

data/lib/rubocop/cop/layout/empty_lines_around_access_modifier.rb

@@ -116,7 +116,7 @@ module RuboCop
         def allowed_only_before_style?(node)
           if node.special_modifier?
             return true if processed_source[node.last_line] == 'end'
-            return false if next_line_empty?(node.last_line)
+            return false if next_line_empty_and_exists?(node.last_line)
           end
 
           previous_line_empty?(node.first_line)
@@ -129,7 +129,7 @@ module RuboCop
           when :around
             corrector.insert_after(line, "\n") unless next_line_empty?(node.last_line)
           when :only_before
-            if next_line_empty?(node.last_line)
+            if next_line_empty_and_exists?(node.last_line)
               range = next_empty_line_range(node)
 
               corrector.remove(range)
@@ -154,6 +154,10 @@ module RuboCop
           body_end?(last_send_line) || next_line.blank?
         end
 
+        def next_line_empty_and_exists?(last_send_line)
+          next_line_empty?(last_send_line) && last_send_line.next != processed_source.lines.size
+        end
+
         def empty_lines_around?(node)
           previous_line_empty?(node.first_line) && next_line_empty?(node.last_line)
         end

data/lib/rubocop/cop/layout/first_argument_indentation.rb

@@ -155,7 +155,7 @@ module RuboCop
         def on_send(node)
           return unless should_check?(node)
           return if same_line?(node, node.first_argument)
-          return if style != :consistent && enforce_first_argument_with_fixed_indentation? &&
+          return if enforce_first_argument_with_fixed_indentation? &&
                     !enable_layout_first_method_argument_line_break?
 
           indent = base_indentation(node) + configured_indentation_width

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

@@ -132,7 +132,7 @@ module RuboCop
         def_node_matcher :delegate_method?, <<~PATTERN
           (send nil? :delegate
             ({sym str} $_)+
-            (hash <(pair (sym :to) _) ...>)
+            (hash <(pair (sym :to) {sym str}) ...>)
           )
         PATTERN
 

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

@@ -19,7 +19,9 @@ module RuboCop
         MSG = 'Empty interpolation detected.'
 
         def on_interpolation(begin_node)
-          return unless begin_node.children.empty?
+          node_children = begin_node.children.dup
+          node_children.delete_if { |e| e&.nil_type? || (e&.basic_literal? && e&.value&.empty?) }
+          return unless node_children.empty?
 
           add_offense(begin_node) { |corrector| corrector.remove(begin_node) }
         end

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

@@ -15,6 +15,14 @@ module RuboCop
       #   x == 0.1
       #   x != 0.1
       #
+      #   # bad
+      #   case value
+      #   when 1.0
+      #     foo
+      #   when 2.0
+      #     bar
+      #   end
+      #
       #   # good - using BigDecimal
       #   x.to_d == 0.1.to_d
       #
@@ -32,12 +40,21 @@ module RuboCop
       #   # good - comparing against nil
       #   Float(x, exception: false) == nil
       #
+      #   # good - using epsilon comparison in case expression
+      #   case
+      #   when (value - 1.0).abs < Float::EPSILON
+      #     foo
+      #   when (value - 2.0).abs < Float::EPSILON
+      #     bar
+      #   end
+      #
       #   # Or some other epsilon based type of comparison:
       #   # https://www.embeddeduse.com/2019/08/26/qt-compare-two-floats/
       #
       class FloatComparison < Base
         MSG_EQUALITY = 'Avoid equality comparisons of floats as they are unreliable.'
         MSG_INEQUALITY = 'Avoid inequality comparisons of floats as they are unreliable.'
+        MSG_CASE = 'Avoid float literal comparisons in case statements as they are unreliable.'
 
         EQUALITY_METHODS = %i[== != eql? equal?].freeze
         FLOAT_RETURNING_METHODS = %i[to_f Float fdiv].freeze
@@ -58,6 +75,16 @@ module RuboCop
         end
         alias on_csend on_send
 
+        def on_case(node)
+          node.when_branches.each do |when_branch|
+            when_branch.each_condition do |condition|
+              next if !float?(condition) || literal_safe?(condition)
+
+              add_offense(condition, message: MSG_CASE)
+            end
+          end
+        end
+
         private
 
         def float?(node)

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

@@ -11,39 +11,43 @@ module RuboCop
       # @example
       #   # bad
       #   foo.object_id == bar.object_id
+      #   foo.object_id != baz.object_id
       #
       #   # good
       #   foo.equal?(bar)
+      #   !foo.equal?(baz)
       #
       class IdentityComparison < Base
         extend AutoCorrector
 
-        MSG = 'Use `equal?` instead `==` when comparing `object_id`.'
-        RESTRICT_ON_SEND = %i[==].freeze
+        MSG = 'Use `%<bang>sequal?` instead of `%<comparison_method>s` when comparing `object_id`.'
+        RESTRICT_ON_SEND = %i[== !=].freeze
+
+        # @!method object_id_comparison(node)
+        def_node_matcher :object_id_comparison, <<~PATTERN
+          (send
+            (send
+              _lhs_receiver :object_id) ${:== :!=}
+            (send
+              _rhs_receiver :object_id))
+        PATTERN
 
         def on_send(node)
-          return unless compare_between_object_id_by_double_equal?(node)
+          return unless (comparison_method = object_id_comparison(node))
 
-          add_offense(node) do |corrector|
+          bang = comparison_method == :== ? '' : '!'
+          add_offense(node,
+                      message: format(MSG, comparison_method: comparison_method,
+                                           bang: bang)) do |corrector|
             receiver = node.receiver.receiver
             argument = node.first_argument.receiver
             return unless receiver && argument
 
-            replacement = "#{receiver.source}.equal?(#{argument.source})"
+            replacement = "#{bang}#{receiver.source}.equal?(#{argument.source})"
 
             corrector.replace(node, replacement)
           end
         end
-
-        private
-
-        def compare_between_object_id_by_double_equal?(node)
-          object_id_method?(node.receiver) && object_id_method?(node.first_argument)
-        end
-
-        def object_id_method?(node)
-          node.send_type? && node.method?(:object_id)
-        end
       end
     end
   end

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

@@ -240,30 +240,22 @@ module RuboCop
         def correct_if_node(node, cond)
           result = condition_evaluation(node, cond)
 
-          if node.elsif? && result
-            add_offense(cond) do |corrector|
-              corrector.replace(node, "else\n  #{node.if_branch.source}")
-            end
-          elsif node.elsif? && !result
-            add_offense(cond) do |corrector|
-              corrector.replace(node, "else\n  #{node.else_branch.source}")
-            end
-          elsif node.if_branch && result
-            add_offense(cond) do |corrector|
-              corrector.replace(node, node.if_branch.source)
-            end
-          elsif node.elsif_conditional?
-            add_offense(cond) do |corrector|
-              corrector.replace(node, "#{node.else_branch.source.sub('elsif', 'if')}\nend")
-            end
-          elsif node.else? || node.ternary?
-            add_offense(cond) do |corrector|
-              corrector.replace(node, node.else_branch.source)
-            end
-          else
-            add_offense(cond) do |corrector|
-              corrector.remove(node)
-            end
+          new_node = if node.elsif? && result
+                       "else\n  #{range_with_comments(node.if_branch).source}"
+                     elsif node.elsif? && !result
+                       "else\n  #{node.else_branch.source}"
+                     elsif node.if_branch && result
+                       node.if_branch.source
+                     elsif node.elsif_conditional?
+                       "#{node.else_branch.source.sub('elsif', 'if')}\nend"
+                     elsif node.else? || node.ternary?
+                       node.else_branch.source
+                     else
+                       '' # Equivalent to removing the node
+                     end
+
+          add_offense(cond) do |corrector|
+            corrector.replace(node, new_node)
           end
         end
         # rubocop:enable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity

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

@@ -8,6 +8,11 @@ module RuboCop
       # given by `ruby -cw` prior to Ruby 2.6:
       # "shadowing outer local variable - foo".
       #
+      # The cop is now disabled by default to match the upstream Ruby behavior.
+      # It's useful, however, if you'd like to avoid shadowing variables from outer
+      # scopes, which some people consider an anti-pattern that makes it harder
+      # to keep track of what's going on in a program.
+      #
       # NOTE: Shadowing of variables in block passed to `Ractor.new` is allowed
       # because `Ractor` should not access outer variables.
       # eg. following style is encouraged: