rubocop 1.81.7 → 1.92.1

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

@@ -4,8 +4,11 @@ module RuboCop
   module Cop
     module Style
       # Checks for non-ascii (non-English) characters
-      # in comments. You could set an array of allowed non-ascii chars in
-      # `AllowedChars` attribute (copyright notice "©" by default).
+      # in comments. Non-ascii characters can cause issues with
+      # portability and encoding across different environments
+      # and editors. You could set an array of allowed non-ascii
+      # chars in `AllowedChars` attribute (copyright notice "©"
+      # by default).
       #
       # @example
       #   # bad
@@ -49,7 +52,7 @@ module RuboCop
         end
 
         def allowed_non_ascii_chars
-          cop_config['AllowedChars'] || []
+          @allowed_non_ascii_chars ||= (cop_config['AllowedChars'] || []).freeze
         end
       end
     end

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

@@ -3,10 +3,13 @@
 module RuboCop
   module Cop
     module Style
-      # Checks for uses of Module#attr.
+      # Checks for uses of `Module#attr`. The `attr` method has confusing
+      # behavior: with a single argument it creates a reader (like `attr_reader`),
+      # but with a second boolean argument it creates an accessor (deprecated in
+      # Ruby 1.9). Use `attr_reader` or `attr_accessor` to make intent explicit.
       #
       # @example
-      #   # bad - creates a single attribute accessor (deprecated in Ruby 1.9)
+      #   # bad
       #   attr :something, true
       #   attr :one, :two, :three # behaves as attr_reader
       #
@@ -47,10 +50,9 @@ module RuboCop
         def autocorrect(corrector, node)
           attr_name, setter = *node.arguments
 
-          node_expr = node.source_range
-          attr_expr = attr_name.source_range
-
-          remove = range_between(attr_expr.end_pos, node_expr.end_pos) if setter&.boolean_type?
+          if setter&.boolean_type?
+            remove = range_between(attr_name.source_range.end_pos, setter.source_range.end_pos)
+          end
 
           corrector.replace(node.loc.selector, replacement_method(node))
           corrector.remove(remove) if remove

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

@@ -3,7 +3,9 @@
 module RuboCop
   module Cop
     module Style
-      # Checks if usage of %() or %Q() matches configuration.
+      # Checks if usage of `%()` or `%Q()` matches configuration.
+      # Consistent use of one style makes the codebase easier
+      # to read.
       #
       # @example EnforcedStyle: bare_percent (default)
       #   # bad
@@ -41,8 +43,7 @@ module RuboCop
 
         def check(node)
           return if node.heredoc?
-          return unless node.loc.respond_to?(:begin)
-          return unless node.loc.begin
+          return unless node.loc?(:begin)
 
           source = node.loc.begin.source
           if requires_percent_q?(source)

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

@@ -3,7 +3,9 @@
 module RuboCop
   module Cop
     module Style
-      # Checks for BEGIN blocks.
+      # Checks for `BEGIN` blocks. They are Perl-style constructs that execute
+      # code before the rest of the file is parsed, making the control flow
+      # harder to follow and reason about.
       #
       # @example
       #   # bad

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

@@ -66,16 +66,18 @@ module RuboCop
 
         # @!method bit_operation?(node)
         def_node_matcher :bit_operation?, <<~PATTERN
-          (begin
-            (send _ :& _))
+          {
+            (begin (send _ :& _))
+            (send _ :& _)
+          }
         PATTERN
 
-        # rubocop:disable Metrics/AbcSize
+        # rubocop:disable-next Metrics/AbcSize
         def on_send(node)
-          return unless node.receiver&.begin_type?
+          return unless bit_operation?(node.receiver)
           return unless (preferred_method = preferred_method(node))
 
-          bit_operation = node.receiver.children.first
+          bit_operation = node.receiver.begin_type? ? node.receiver.children.first : node.receiver
           lhs, _operator, rhs = *bit_operation
 
           preferred = if preferred_method == 'allbits?' && lhs.source == node.first_argument.source
@@ -88,7 +90,6 @@ module RuboCop
             corrector.replace(node, preferred)
           end
         end
-        # rubocop:enable Metrics/AbcSize
 
         private
 

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# rubocop:disable Metrics/ClassLength
+# rubocop:disable-next Metrics/ClassLength
 module RuboCop
   module Cop
     module Style
@@ -177,7 +177,7 @@ module RuboCop
         BRACES_REQUIRED_MESSAGE = "Brace delimiters `{...}` required for '%<method_name>s' method."
 
         def self.autocorrect_incompatible_with
-          [Style::RedundantBegin]
+          [Layout::SpaceBeforeBlockBraces, Style::MethodCallWithArgsParentheses, Style::RedundantBegin]
         end
 
         def on_send(node)
@@ -196,14 +196,17 @@ module RuboCop
           end
         end
         alias on_csend on_send
+        alias on_super on_send
+        alias on_yield on_send
 
         def on_block(node)
-          return if ignored_node?(node)
+          return if part_of_ignored_node?(node)
           return if proper_block_style?(node)
 
           message = message(node)
           add_offense(node.loc.begin, message: message) do |corrector|
             autocorrect(corrector, node)
+            ignore_node(node)
           end
         end
 
@@ -231,9 +234,7 @@ module RuboCop
         end
 
         def semantic_message(node)
-          block_begin = node.loc.begin.source
-
-          if block_begin == '{'
+          if node.braces?
             'Prefer `do...end` over `{...}` for procedural blocks.'
           else
             'Prefer `{...}` over `do...end` for functional blocks.'
@@ -293,7 +294,7 @@ module RuboCop
           corrector.replace(b, '{')
           corrector.replace(e, '}')
 
-          corrector.wrap(node.body, "begin\n", "\nend") if begin_required?(node)
+          wrap_body_with_begin(corrector, node.body) if begin_required?(node)
         end
 
         def whitespace_before?(range)
@@ -305,6 +306,8 @@ module RuboCop
         end
 
         def move_comment_before_block(corrector, comment, block_node, closing_brace)
+          return if directive_comment?(comment)
+
           range = block_node.chained? ? end_of_chain(block_node.parent).source_range : closing_brace
 
           # It is possible that there is code between the block and the comment
@@ -318,6 +321,10 @@ module RuboCop
           corrector.insert_before(block_node, "#{comment.text}\n")
         end
 
+        def directive_comment?(comment)
+          comment.text.match?(DirectiveComment::DIRECTIVE_COMMENT_REGEXP)
+        end
+
         def source_range_before_comment(range, comment)
           range = range.end.join(comment.source_range.begin)
 
@@ -345,7 +352,7 @@ module RuboCop
           node.respond_to?(:block_node) && node.block_node
         end
 
-        # rubocop:disable Metrics/CyclomaticComplexity
+        # rubocop:disable-next Metrics/CyclomaticComplexity
         def get_blocks(node, &block)
           case node.type
           when :block, :numblock, :itblock
@@ -369,38 +376,47 @@ module RuboCop
             node.each_child_node { |child| get_blocks(child, &block) }
           end
         end
-        # rubocop:enable Metrics/CyclomaticComplexity
 
+        # rubocop:disable-next Metrics/CyclomaticComplexity -- inlined special_method checks to avoid double evaluation
         def proper_block_style?(node)
           return true if require_do_end?(node)
-          return special_method_proper_block_style?(node) if special_method?(node.method_name)
+          return true if collection_of_for_loop?(node)
+
+          method_name = node.method_name
+          return true if allowed_method?(method_name) || matches_allowed_pattern?(method_name)
+          return node.braces? if braces_required_method?(method_name)
 
           case style
           when :line_count_based    then line_count_based_block_style?(node)
           when :semantic            then semantic_block_style?(node)
           when :braces_for_chaining then braces_for_chaining_style?(node)
-          when :always_braces       then braces_style?(node)
+          when :always_braces       then node.braces?
           end
         end
 
         def require_do_end?(node)
           return false if node.braces? || node.multiline?
-          return false unless (resbody = node.each_descendant(:resbody).first)
 
-          resbody.children.first&.array_type?
+          body = node.body
+          return false unless body
+          # `ensure` and a block-level `rescue` are illegal inside `{ }`; only a
+          # bare modifier rescue (`expr rescue expr`) can be written with braces.
+          return true if body.ensure_type?
+          return false unless body.rescue_type?
+
+          !modifier_rescue?(body)
         end
 
-        def special_method?(method_name)
-          allowed_method?(method_name) ||
-            matches_allowed_pattern?(method_name) ||
-            braces_required_method?(method_name)
+        def collection_of_for_loop?(node)
+          node.parent&.for_type? && node.parent.collection == node
         end
 
-        def special_method_proper_block_style?(node)
-          method_name = node.method_name
-          return true if allowed_method?(method_name) || matches_allowed_pattern?(method_name)
+        def modifier_rescue?(rescue_node)
+          return false if rescue_node.body.nil? || rescue_node.else_branch
+          return false unless rescue_node.resbody_branches.one?
 
-          node.braces? if braces_required_method?(method_name)
+          resbody = rescue_node.resbody_branches.first
+          resbody.exceptions.empty? && resbody.exception_variable.nil?
         end
 
         def braces_required_method?(method_name)
@@ -420,34 +436,41 @@ module RuboCop
 
           if node.braces?
             functional_method?(method_name) || functional_block?(node) ||
-              (procedural_oneliners_may_have_braces? && !node.multiline?)
+              (procedural_oneliners_may_have_braces? && node.single_line?)
           else
             procedural_method?(method_name) || !return_value_used?(node)
           end
         end
 
         def braces_for_chaining_style?(node)
-          block_begin = node.loc.begin.source
-
-          block_begin == if node.multiline?
-                           (node.chained? ? '{' : 'do')
-                         else
-                           '{'
-                         end
-        end
-
-        def braces_style?(node)
-          node.loc.begin.source == '{'
+          if node.multiline?
+            node.chained? ? node.braces? : !node.braces?
+          else
+            node.braces?
+          end
         end
 
         def correction_would_break_code?(node)
-          return false unless node.keywords?
+          return loop_condition?(node) if node.braces?
 
           node.send_node.arguments? && !node.send_node.parenthesized?
         end
 
+        # A `do` in the condition of `while` or `until` is taken as the start of
+        # the loop body. Inside the body of another block it is unambiguous again.
+        def loop_condition?(node)
+          ancestors = node.each_ancestor.take_while { |ancestor| !ancestor.any_block_type? }
+          [node, *ancestors].each_cons(2).any? do |child, parent|
+            parent.type?(:while, :until) && parent.condition.equal?(child)
+          end
+        end
+
         def functional_method?(method_name)
-          cop_config['FunctionalMethods'].map(&:to_sym).include?(method_name)
+          functional_methods.include?(method_name)
+        end
+
+        def functional_methods
+          @functional_methods ||= cop_config['FunctionalMethods'].to_set(&:to_sym).freeze
         end
 
         def functional_block?(node)
@@ -459,7 +482,11 @@ module RuboCop
         end
 
         def procedural_method?(method_name)
-          cop_config['ProceduralMethods'].map(&:to_sym).include?(method_name)
+          procedural_methods.include?(method_name)
+        end
+
+        def procedural_methods
+          @procedural_methods ||= cop_config['ProceduralMethods'].to_set(&:to_sym).freeze
         end
 
         def return_value_used?(node)
@@ -485,10 +512,20 @@ module RuboCop
           node.type?(:array, :range)
         end
 
+        def wrap_body_with_begin(corrector, body)
+          heredoc_ends = body.each_node(:any_str).select(&:heredoc?).map do |str|
+            str.loc.heredoc_end
+          end
+          body_end = [body.source_range, *heredoc_ends].max_by(&:end_pos)
+
+          corrector.insert_before(body, "begin\n")
+          corrector.insert_after(body_end, "\nend")
+        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?
+          block_node.each_child_node(:rescue, :ensure).any? && block_node.multiline?
         end
 
         def single_argument_operator_method?(node)
@@ -500,4 +537,3 @@ module RuboCop
     end
   end
 end
-# rubocop:enable Metrics/ClassLength

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

@@ -3,31 +3,40 @@
 module RuboCop
   module Cop
     module Style
-      # Checks for uses of the case equality operator(===).
+      # Checks for uses of the case equality operator (`===`).
+      # The `===` operator has different behavior depending on the
+      # receiver and its use outside of `case`/`when` is confusing.
+      # Prefer more explicit alternatives like `is_a?`, `include?`,
+      # or `match?`.
       #
       # If `AllowOnConstant` option is enabled, the cop will ignore violations when the receiver of
       # the case equality operator is a constant.
-
+      #
       # If `AllowOnSelfClass` option is enabled, the cop will ignore violations when the receiver of
       # the case equality operator is `self.class`. Note intermediate variables are not accepted.
       #
+      # NOTE: Regexp case equality (`/regexp/ === var`) is allowed because changing it to
+      # `/regexp/.match?(var)` needs to take into account `Regexp.last_match?`, `$~`, `$1`, etc.
+      # This potentially incompatible transformation is handled by `Performance/RegexpMatch` cop.
+      #
       # @example
       #   # bad
       #   (1..100) === 7
-      #   /something/ === some_string
       #
       #   # good
-      #   something.is_a?(Array)
       #   (1..100).include?(7)
-      #   /something/.match?(some_string)
       #
       # @example AllowOnConstant: false (default)
       #   # bad
       #   Array === something
       #
+      #   # good
+      #   something.is_a?(Array)
+      #
       # @example AllowOnConstant: true
       #   # good
       #   Array === something
+      #   something.is_a?(Array)
       #
       # @example AllowOnSelfClass: false (default)
       #   # bad
@@ -51,7 +60,7 @@ module RuboCop
 
         def on_send(node)
           case_equality?(node) do |lhs, rhs|
-            return if lhs.const_type? && !lhs.module_name?
+            return if lhs.regexp_type? || (lhs.const_type? && !lhs.module_name?)
 
             add_offense(node.loc.selector) do |corrector|
               replacement = replacement(lhs, rhs)
@@ -71,13 +80,6 @@ module RuboCop
 
         def replacement(lhs, rhs)
           case lhs.type
-          when :regexp
-            # The automatic correction from `a === b` to `a.match?(b)` needs to
-            # consider `Regexp.last_match?`, `$~`, `$1`, and etc.
-            # This correction is expected to be supported by `Performance/Regexp` cop.
-            # See: https://github.com/rubocop/rubocop-performance/issues/152
-            #
-            # So here is noop.
           when :begin
             begin_replacement(lhs, rhs)
           when :const
@@ -94,13 +96,25 @@ module RuboCop
         end
 
         def const_replacement(lhs, rhs)
-          "#{rhs.source}.is_a?(#{lhs.source})"
+          "#{parenthesize_if_needed(rhs)}.is_a?(#{lhs.source})"
         end
 
         def send_replacement(lhs, rhs)
           return unless self_class?(lhs)
 
-          "#{rhs.source}.is_a?(#{lhs.source})"
+          "#{parenthesize_if_needed(rhs)}.is_a?(#{lhs.source})"
+        end
+
+        # `Array === a + b` must become `(a + b).is_a?(Array)`, not
+        # `a + b.is_a?(Array)` (which parses as `a + (b.is_a?(Array))`).
+        def parenthesize_if_needed(node)
+          requires_parentheses?(node) ? "(#{node.source})" : node.source
+        end
+
+        def requires_parentheses?(node)
+          return true if node.type?(:and, :or, :if, :range) || node.assignment?
+
+          node.send_type? && (node.operator_method? || node.unary_operation?)
         end
       end
     end

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

@@ -54,6 +54,10 @@ module RuboCop
 
         MSG = 'Convert `if-elsif` to `case-when`.'
 
+        def self.autocorrect_incompatible_with
+          [Style::IfInsideElse]
+        end
+
         def on_if(node)
           return unless should_check?(node)
 
@@ -98,7 +102,7 @@ module RuboCop
             node.elsif_conditional? && min_branches_count?(node)
         end
 
-        # rubocop:disable Metrics/MethodLength
+        # rubocop:disable-next Metrics/MethodLength
         def find_target(node)
           case node.type
           when :begin
@@ -106,7 +110,7 @@ module RuboCop
           when :or
             find_target(node.lhs)
           when :match_with_lvasgn
-            lhs, rhs = *node # rubocop:disable InternalAffairs/NodeDestructuring
+            lhs, rhs = *node # rubocop:disable InternalAffairs/NodeDestructuring -- `match_with_lvasgn` has no named operand accessors
             if lhs.regexp_type?
               rhs
             elsif rhs.regexp_type?
@@ -116,7 +120,6 @@ module RuboCop
             find_target_in_send_node(node)
           end
         end
-        # rubocop:enable Metrics/MethodLength
 
         def find_target_in_send_node(node)
           case node.method_name
@@ -172,7 +175,7 @@ module RuboCop
               return collect_conditions(node.lhs, target, conditions) &&
                      collect_conditions(node.rhs, target, conditions)
             when :match_with_lvasgn
-              lhs, rhs = *node # rubocop:disable InternalAffairs/NodeDestructuring
+              lhs, rhs = *node # rubocop:disable InternalAffairs/NodeDestructuring -- `match_with_lvasgn` has no named operand accessors
               condition_from_binary_op(lhs, rhs, target)
             when :send
               condition_from_send_node(node, target)
@@ -181,7 +184,7 @@ module RuboCop
           conditions << condition if condition
         end
 
-        # rubocop:disable Metrics/CyclomaticComplexity
+        # rubocop:disable-next Metrics/CyclomaticComplexity
         def condition_from_send_node(node, target)
           case node.method_name
           when :is_a?
@@ -196,7 +199,6 @@ module RuboCop
             condition_from_include_or_cover_node(node, target)
           end
         end
-        # rubocop:enable Metrics/CyclomaticComplexity
 
         def condition_from_equality_node(node, target)
           condition = condition_from_binary_op(node.receiver, node.first_argument, target)
@@ -226,10 +228,9 @@ module RuboCop
         end
 
         def branch_conditions(node)
-          conditions = []
-          while node&.if_type? && !node.ternary?
+          conditions = [node.condition]
+          while (node = node.else_branch)&.if_type? && node.elsif?
             conditions << node.condition
-            node = node.else_branch
           end
           conditions
         end
@@ -260,7 +261,7 @@ module RuboCop
         def regexp_with_working_captures?(node)
           case node.type
           when :match_with_lvasgn
-            lhs, _rhs = *node # rubocop:disable InternalAffairs/NodeDestructuring
+            lhs, _rhs = *node # rubocop:disable InternalAffairs/NodeDestructuring -- `match_with_lvasgn` has no named operand accessors
             node.loc.selector.source == '=~' && regexp_with_named_captures?(lhs)
           when :send
             node.method?(:match) &&

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

@@ -8,8 +8,8 @@ module RuboCop
       # essentially one-character strings, so this syntax
       # is mostly redundant at this point.
       #
-      # ? character literal can be used to express meta and control character.
-      # That's a good use case of ? literal so it doesn't count it as an offense.
+      # A `?` character literal can be used to express meta and control characters.
+      # That's a good use case of a `?` literal so it doesn't count as an offense.
       #
       # @example
       #   # bad