rubocop 1.89.0 → 1.91.0

data/lib/rubocop/cop/base.rb

@@ -49,7 +49,12 @@ module RuboCop
       InvestigationReport = Struct.new(:cop, :processed_source, :offenses, :corrector)
 
       # List of methods names to restrict calls for `on_send` / `on_csend`
-      RESTRICT_ON_SEND = Set[].freeze # rubocop:disable InternalAffairs/UselessRestrictOnSend
+      RESTRICT_ON_SEND = Set[].freeze # rubocop:disable InternalAffairs/UselessRestrictOnSend -- the base class default, which cops override
+
+      # Departments whose cops report above `convention` unless a cop says
+      # otherwise. The exceptions live in `config/default.yml` as an explicit
+      # `Severity`, such as the lint-like cops in `Bundler` and `Gemspec`.
+      DEPARTMENT_SEVERITIES = { Lint: :warning, Security: :warning, Metrics: :refactor }.freeze
 
       # List of cops that should not try to autocorrect at the same
       # time as this cop
@@ -127,6 +132,8 @@ module RuboCop
       # in the `on_new_investigation` callback.
       # If your cop does autocorrections, be aware that your instance may be called
       # multiple times with the same `processed_source.path` but different content.
+      # Note that under `--parallel` each worker process has its own cop
+      # instances, so state persists only within a worker's share of the files.
       def self.support_multiple_source?
         false
       end
@@ -208,13 +215,15 @@ module RuboCop
         severity = find_severity(range_to_pass, severity)
         message = find_message(range_to_pass, message)
 
-        status, corrector = enabled_line?(range.line) ? correct(range, &block) : :disabled
+        status, corrector = enabled_lines?(range) ? correct(range, &block) : :disabled
+        justification = suppression_reason(range) if status == :disabled
 
         # Since this range may be generated from Ruby code embedded in some
         # template file, we convert it to location info in the original file.
         range = range_for_original(range)
 
-        current_offenses << Offense.new(severity, range, message, name, status, corrector)
+        current_offenses << Offense.new(severity, range, message, name, status, corrector,
+                                        justification: justification)
       end
 
       # This method should be overridden when a cop's behavior depends
@@ -284,6 +293,13 @@ module RuboCop
         @config.string_literals_frozen_by_default?
       end
 
+      # Whether the user opted in to unstable behavior, with `--preview` or
+      # `AllCops: Preview`. Cops branch on this to ship a change that is not
+      # ready to be the default yet.
+      def preview?
+        @config.preview?(@options)
+      end
+
       def relevant_file?(file)
         return false unless target_satisfies_all_gem_version_requirements?
         return true unless @config.clusivity_config_for_badge?(self.class.badge)
@@ -322,7 +338,7 @@ module RuboCop
 
       ### Reserved for Commissioner
 
-      # rubocop:disable Layout/ClassStructure
+      # rubocop:disable Layout/ClassStructure -- grouped under the Commissioner heading above
       # @api private
       def callbacks_needed
         self.class.callbacks_needed
@@ -445,6 +461,10 @@ module RuboCop
       def use_corrector(range, corrector)
         if autocorrect?
           attempt_correction(range, corrector)
+        elsif skipped_unsafe_correction_with_disable_uncorrectable?
+          # The unsafe correction will not run, so the offense is
+          # uncorrectable for this run and gets a todo comment.
+          attempt_correction(range, nil)
         elsif corrector && (always_autocorrect? || (contextual_autocorrect? && !LSP.enabled?))
           :uncorrected
         else
@@ -524,12 +544,36 @@ module RuboCop
         @processed_source.comment_config.cop_enabled_at_line?(self, line_number)
       end
 
+      # A multi-line offense is suppressed by a directive on any line of its
+      # range, not only its first line, matching the intuition that the
+      # directive is attached to the offending code.
+      def enabled_lines?(range)
+        return true if @options[:ignore_disable_comments] || !@processed_source
+
+        comment_config = @processed_source.comment_config
+        comment_config.cop_enabled_at_lines?(self, range.first_line, range.last_line)
+      end
+
+      # The `--` reason on the directive that suppresses offenses on this
+      # range, or `nil` when the directive carries none.
+      def suppression_reason(range)
+        covering = covering_disabled_range(range)
+        covering.directive.reason if covering.respond_to?(:directive)
+      end
+
+      def covering_disabled_range(range)
+        disabled_ranges = @processed_source.comment_config.cop_disabled_line_ranges[cop_name]
+        disabled_ranges&.find do |disabled_range|
+          disabled_range.end >= range.first_line && disabled_range.begin <= range.last_line
+        end
+      end
+
       def find_severity(_range, severity)
         custom_severity || severity || default_severity
       end
 
       def default_severity
-        self.class.lint? ? :warning : :convention
+        DEPARTMENT_SEVERITIES.fetch(self.class.department, :convention)
       end
 
       def custom_severity

data/lib/rubocop/cop/corrector.rb

@@ -46,7 +46,7 @@ module RuboCop
 
       # Removes `size` characters prior to the source range.
       #
-      # @param [Parser::Source::Range, RuboCop::AST::Node] range or node
+      # @param [Parser::Source::Range, RuboCop::AST::Node] node_or_range
       # @param [Integer] size
       def remove_preceding(node_or_range, size)
         range = to_range(node_or_range)
@@ -58,7 +58,7 @@ module RuboCop
       # If `size` is greater than the size of `range`, the removed region can
       # overrun the end of `range`.
       #
-      # @param [Parser::Source::Range, RuboCop::AST::Node] range or node
+      # @param [Parser::Source::Range, RuboCop::AST::Node] node_or_range
       # @param [Integer] size
       def remove_leading(node_or_range, size)
         range = to_range(node_or_range)
@@ -70,7 +70,7 @@ module RuboCop
       # If `size` is greater than the size of `range`, the removed region can
       # overrun the beginning of `range`.
       #
-      # @param [Parser::Source::Range, RuboCop::AST::Node] range or node
+      # @param [Parser::Source::Range, RuboCop::AST::Node] node_or_range
       # @param [Integer] size
       def remove_trailing(node_or_range, size)
         range = to_range(node_or_range)

data/lib/rubocop/cop/correctors.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 module RuboCop
-  module Cop # rubocop:disable Style/Documentation
+  module Cop # rubocop:disable Style/Documentation -- a namespace that only autoloads the correctors below
     # Autoloads corrector classes used by cops. Classes are autoloaded to reduce the number of
     # required classes because they're referenced only when autocorrection is performed.
 
-    # rubocop:disable Layout/LineLength
+    # rubocop:disable Layout/LineLength -- the autoload paths do not wrap
     autoload :AlignmentCorrector, 'rubocop/cop/correctors/alignment_corrector'
     autoload :ConditionCorrector, 'rubocop/cop/correctors/condition_corrector'
     autoload :EachToForCorrector, 'rubocop/cop/correctors/each_to_for_corrector'

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

@@ -92,7 +92,7 @@ module RuboCop
           (str "true")
         PATTERN
 
-        def on_block(node) # rubocop:disable Metrics/MethodLength, InternalAffairs/NumblockHandler, InternalAffairs/ItblockHandler
+        def on_block(node) # rubocop:disable Metrics/MethodLength, InternalAffairs/NumblockHandler, InternalAffairs/ItblockHandler -- the gemspec block is matched by its named block variable
           gem_specification(node) do |block_var|
             metadata_value = metadata(node)
             mfa_value = mfa_value(metadata_value)

data/lib/rubocop/cop/generator.rb

@@ -147,7 +147,7 @@ module RuboCop
                                     badge: badge,
                                     version_added: version_added)
 
-        injector.inject do # rubocop:disable Lint/UnexpectedBlockArity
+        injector.inject do # rubocop:disable Lint/UnexpectedBlockArity -- this `inject` is the injector API, not `Enumerable#inject`
           output.puts(format(CONFIGURATION_ADDED_MESSAGE,
                              configuration_file_path: config_file_path))
         end

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

@@ -146,7 +146,7 @@ module RuboCop
           end
         end
 
-        # rubocop:disable Metrics/MethodLength
+        # rubocop:disable-next Metrics/MethodLength
         def formatted_message(offense_type, directive, actual_name, method_name)
           case offense_type
           when :wrong_name
@@ -166,7 +166,6 @@ module RuboCop
             format(MSG, method: method_name)
           end
         end
-        # rubocop:enable Metrics/MethodLength
 
         def remove_receiver(current)
           current.delete_prefix('self.')

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

@@ -3,7 +3,7 @@
 module RuboCop
   module Cop
     module InternalAffairs
-      # rubocop:disable InternalAffairs/RedundantSourceRange -- node here is a `NodePattern::Node`
+      # rubocop:disable-next InternalAffairs/RedundantSourceRange -- node here is a `NodePattern::Node`
       class NodePatternGroups
         # Walks an AST that has been processed by `InternalAffairs::NodePatternGroups::Processor`
         # in order to find `node_type` and `node_sequence` nodes that can be replaced with a node
@@ -125,7 +125,6 @@ module RuboCop
           end
         end
       end
-      # rubocop:enable InternalAffairs/RedundantSourceRange
     end
   end
 end

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

@@ -75,7 +75,7 @@ module RuboCop
           @on_csend_definition = node if node.new_identifier.value == :on_csend
         end
 
-        def on_send(node) # rubocop:disable InternalAffairs/OnSendWithoutOnCSend
+        def on_send(node) # rubocop:disable InternalAffairs/OnSendWithoutOnCSend -- this cop is what enforces the rule, and does not apply to itself
           return unless (new_identifier = node.first_argument)
           return unless new_identifier.basic_literal?
 

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

@@ -81,6 +81,8 @@ module RuboCop
           last_arg = node.last_argument
 
           if last_arg.hash_type? && !last_arg.braces?
+            return items if enforce_hash_argument_with_separator?
+
             items += last_arg.pairs
           else
             items << last_arg

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

@@ -281,7 +281,7 @@ module RuboCop
           end
         end
 
-        # rubocop:disable Metrics/AbcSize
+        # rubocop:disable-next Metrics/AbcSize
         def do_line_begins_inside_argument?(node, do_loc)
           line_begin_pos = do_loc.begin_pos - do_loc.column
           first_char_pos = line_begin_pos + (do_loc.source_line =~ /\S/)
@@ -292,7 +292,6 @@ module RuboCop
               first_char_pos < argument.source_range.end_pos
           end
         end
-        # rubocop:enable Metrics/AbcSize
 
         # The continuation line indentation is only an unmeaningful alignment target when
         # it is dictated by an opening delimiter, i.e. the line begins inside `(` or `[`.

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

@@ -190,33 +190,58 @@ module RuboCop
 
         # Validates code style on class declaration.
         # Add offense when find a node out of expected order.
+        # A node is out of order when its category is expected earlier than
+        # the highest-priority category seen so far, so that a low-priority element
+        # (even an unmovable one) cannot mask disorder among the elements that follow it.
+        # Consecutive elements of the same category are reported only once,
+        # on the first element of the group.
         def on_class(class_node)
-          previous = -1
-          walk_over_nested_class_definition(class_node) do |node, category|
-            index = expected_order.index(category)
-            if index < previous
-              message = format(MSG, category: category, previous: expected_order[previous])
-              add_offense(node, message: message) { |corrector| autocorrect(corrector, node) }
+          # Corrections are registered in reverse source order because an insertion at
+          # a given position lands before any insertion already made there;
+          # this keeps the source order of nodes moved before the same anchor.
+          out_of_order_elements(class_node).reverse_each do |node, category, previous|
+            message = format(MSG, category: category, previous: previous)
+
+            add_offense(node, message: message) do |corrector|
+              autocorrect(corrector, node)
             end
-            previous = index
           end
         end
         alias on_sclass on_class
 
         private
 
-        # Autocorrect by swapping between two nodes autocorrecting them
-        def autocorrect(corrector, node)
-          previous = node.left_siblings.reverse.find do |sibling|
-            !ignore_for_autocorrect?(node, sibling)
+        def out_of_order_elements(class_node)
+          out_of_order = []
+          max_index = -1
+          previous_category = nil
+          walk_over_nested_class_definition(class_node) do |node, category|
+            index = expected_order.index(category)
+            if index < max_index && category != previous_category
+              out_of_order << [node, category, expected_order[max_index]]
+            end
+            max_index = index if index > max_index
+            previous_category = category
           end
-          return unless previous
-
-          current_range = source_range_with_comment(node)
-          previous_range = source_range_with_comment(previous)
+          out_of_order
+        end
 
-          corrector.insert_before(previous_range, current_range.source)
-          corrector.remove(current_range)
+        # Autocorrect by moving the node, together with the contiguous group of
+        # same-category elements that follows it, to its expected position.
+        def autocorrect(corrector, node)
+          return if dynamic_constant?(node)
+
+          anchor = insertion_anchor(node)
+          return unless anchor
+
+          anchor_range = source_range_with_comment(anchor)
+          # Reversed for the same reason offenses are registered in reverse source order:
+          # the last insertion at a position comes first.
+          movable_group(node).reverse_each do |group_node|
+            current_range = source_range_with_comment(group_node)
+            corrector.insert_before(anchor_range, current_range.source)
+            corrector.remove(current_range)
+          end
         end
 
         # Classifies a node to match with something in the {expected_order}
@@ -302,15 +327,6 @@ module RuboCop
           end
         end
 
-        def ignore_for_autocorrect?(node, sibling)
-          classification = classify(node)
-          sibling_class = classify(sibling)
-
-          ignore?(sibling, sibling_class) ||
-            classification == sibling_class ||
-            dynamic_constant?(node)
-        end
-
         def humanize_node(node)
           if node.def_type?
             return :initializer if node.method?(:initialize)
@@ -328,6 +344,66 @@ module RuboCop
             !(expression.method?(:freeze) && expression.receiver&.recursive_basic_literal?)
         end
 
+        # The expected position of the node: the first left sibling within its movable span
+        # whose category is expected to appear after the node's.
+        # Requiring a strictly later category keeps the order of elements sharing a category stable.
+        def insertion_anchor(node)
+          index = expected_order.index(classify(node))
+
+          movable_span(node).find do |sibling|
+            classification = classify(sibling)
+
+            !ignore?(sibling, classification) && expected_order.index(classification) > index
+          end
+        end
+
+        # The node together with the contiguous same-category right siblings,
+        # so that the whole group moves in a single pass while the offense is
+        # reported only on its first element.
+        def movable_group(node)
+          classification = classify(node)
+          group = [node]
+
+          node.right_siblings.each do |sibling|
+            break unless classify(sibling) == classification
+            break if ignore?(sibling, classification) || dynamic_constant?(sibling)
+
+            group << sibling
+          end
+
+          group
+        end
+
+        # Left siblings the node may be reordered with: those after the last barrier.
+        # Ignored elements within the span are simply jumped over.
+        def movable_span(node)
+          left_siblings = node.left_siblings
+          barrier_index = left_siblings.rindex { |sibling| barrier?(node, sibling) }
+
+          barrier_index ? left_siblings[(barrier_index + 1)..] : left_siblings
+        end
+
+        # A dynamic constant blocks every element: the cop does not move such constants,
+        # and letting other elements jump over one would change execution order just the same.
+        # A bare visibility modifier blocks only the elements whose meaning depends on
+        # the visibility section they appear in.
+        def barrier?(node, sibling)
+          dynamic_constant?(sibling) || (visibility_dependent?(node) && visibility_block?(sibling))
+        end
+
+        # Whether moving the node across a bare visibility modifier would change its meaning.
+        # This is the case for `def` nodes and for macros whose category is classified by visibility
+        # (e.g. `attr_accessor` when the expected order lists `private_attribute_macros`).
+        # Inline visibility (`private def foo`, `def self.foo`) travels with the node.
+        def visibility_dependent?(node)
+          return true if node.def_type?
+          return false if !node.send_type? || node.def_modifier?
+
+          key = find_category(node.method_name) || node.method_name.to_s
+
+          VISIBILITY_SCOPES.any? { |visibility| expected_order.include?("#{visibility}_#{key}") }
+        end
+
         def private_constant?(node)
           return false unless node.casgn_type? && node.namespace.nil?
           return false unless (parent = node.parent)

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

@@ -64,10 +64,10 @@ module RuboCop
           autocorrect_one(corrector, comment)
         end
 
-        # Corrects all comment lines that occur immediately before the given
-        # comment and have the same indentation. This is to avoid a long chain
-        # of correcting, saving the file, parsing and inspecting again, and
-        # then correcting one more line, and so on.
+        # Corrects all preceding comment lines that have the same indentation
+        # and are separated from the given comment by nothing but blank lines.
+        # This is to avoid a long chain of correcting, saving the file, parsing
+        # and inspecting again, and then correcting one more line, and so on.
         def autocorrect_preceding_comments(corrector, comment)
           comments = processed_source.comments
           index = comments.index(comment)
@@ -82,7 +82,10 @@ module RuboCop
         def should_correct?(preceding_comment, reference_comment)
           loc = preceding_comment.loc
           ref_loc = reference_comment.loc
-          loc.line == ref_loc.line - 1 && loc.column == ref_loc.column
+          return false unless loc.column == ref_loc.column
+          return false unless own_line_comment?(preceding_comment)
+
+          ((loc.line + 1)...ref_loc.line).all? { |line| processed_source[line - 1].blank? }
         end
 
         def autocorrect_one(corrector, comment)

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

@@ -93,6 +93,7 @@ module RuboCop
           when :def, :defs then base_for_method_definition(parent)
           when :kwbegin then parent.loc.begin
           when :block, :numblock, :itblock then start_line_range(parent)
+          when :class, :module, :sclass then parent.loc.keyword
           else node.loc.keyword
           end
         end

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

@@ -161,7 +161,7 @@ module RuboCop
           next_sibling.if_type? && contains_guard_clause?(next_sibling)
         end
 
-        # rubocop:disable Metrics/CyclomaticComplexity
+        # rubocop:disable-next Metrics/CyclomaticComplexity
         def last_heredoc_argument(node)
           n = last_heredoc_argument_node(node)
           n = n.children.first while n.respond_to?(:begin_type?) && n.begin_type?
@@ -176,7 +176,6 @@ module RuboCop
 
           last_heredoc_argument(n.receiver) if n.respond_to?(:receiver)
         end
-        # rubocop:enable Metrics/CyclomaticComplexity
 
         def last_heredoc_argument_node(node)
           return node unless node.respond_to?(:if_branch)

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

@@ -5,6 +5,14 @@ module RuboCop
     module Layout
       # Checks for a newline after the final magic comment.
       #
+      # `NumberOfEmptyLines` configures the minimum number of empty lines required. Set it
+      # to `2` when using YARD, which otherwise treats the magic comments as documentation
+      # for the first module or class in the file.
+      #
+      # NOTE: `Layout/EmptyLines` has to be disabled for values greater than `1`, as it
+      # removes the extra empty lines this cop adds, and autocorrecting with both enabled
+      # loops between them.
+      #
       # @example
       #   # good
       #   # frozen_string_literal: true
@@ -20,30 +28,80 @@ module RuboCop
       #   class Person
       #     # Some code
       #   end
+      #
+      # @example NumberOfEmptyLines: 1 (default)
+      #   # good
+      #   # frozen_string_literal: true
+      #
+      #   class Person
+      #   end
+      #
+      # @example NumberOfEmptyLines: 2
+      #   # bad
+      #   # frozen_string_literal: true
+      #
+      #   class Person
+      #   end
+      #
+      #   # good
+      #   # frozen_string_literal: true
+      #
+      #
+      #   class Person
+      #   end
       class EmptyLineAfterMagicComment < Base
         include RangeHelp
         extend AutoCorrector
 
-        MSG = 'Add an empty line after magic comments.'
+        MSG = 'Expected at least %<expected>d empty %<lines>s after magic comments; found ' \
+              '%<actual>d.'
+
+        def validate_config
+          return if number_of_empty_lines.is_a?(Integer) && number_of_empty_lines.positive?
+
+          raise ValidationError,
+                'The `Layout/EmptyLineAfterMagicComment` cop only accepts a positive ' \
+                'integer for its `NumberOfEmptyLines` configuration parameter, but ' \
+                "`#{number_of_empty_lines.inspect}` was given."
+        end
 
         def on_new_investigation
           return unless (last_magic_comment = last_magic_comment(processed_source))
-          return unless (next_line = processed_source[last_magic_comment.loc.line])
-          return if next_line.strip.empty?
+
+          actual = empty_lines_after(last_magic_comment)
+          # Trailing empty lines are `Layout/TrailingEmptyLines`' responsibility.
+          return unless processed_source[last_magic_comment.loc.line + actual]
+          return if actual >= number_of_empty_lines
 
           offending_range = offending_range(last_magic_comment)
 
-          add_offense(offending_range) do |corrector|
-            corrector.insert_before(offending_range, "\n")
+          add_offense(offending_range, message: message(actual)) do |corrector|
+            corrector.insert_before(offending_range, "\n" * (number_of_empty_lines - actual))
           end
         end
 
         private
 
+        def message(actual)
+          format(MSG, expected: number_of_empty_lines, actual: actual,
+                      lines: number_of_empty_lines == 1 ? 'line' : 'lines')
+        end
+
+        def empty_lines_after(last_magic_comment)
+          first_line = last_magic_comment.loc.line
+          count = 0
+          count += 1 while (line = processed_source[first_line + count]) && line.strip.empty?
+          count
+        end
+
         def offending_range(last_magic_comment)
           source_range(processed_source.buffer, last_magic_comment.loc.line + 1, 0)
         end
 
+        def number_of_empty_lines
+          cop_config.fetch('NumberOfEmptyLines', 1)
+        end
+
         # Find the last magic comment in the source file.
         #
         # Take all comments that precede the first line of code (or just take

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

@@ -91,7 +91,7 @@ module RuboCop
         end
 
         def next_line_node(node)
-          return if node.parent.if_type?
+          return if node.parent.type?(:if, :rescue, :ensure)
 
           node.right_sibling
         end

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

@@ -123,7 +123,7 @@ module RuboCop
           AlignmentCorrector.align_end(corrector, processed_source, node, alignment_node(node))
         end
 
-        # rubocop:disable Metrics/CyclomaticComplexity
+        # rubocop:disable-next Metrics/CyclomaticComplexity
         def check_assignment(node, rhs)
           # If there are method calls chained to the right hand side of the
           # assignment, we let rhs be the receiver of those method calls before
@@ -139,7 +139,6 @@ module RuboCop
 
           check_asgn_alignment(node, rhs)
         end
-        # rubocop:enable Metrics/CyclomaticComplexity
 
         def check_asgn_alignment(outer_node, inner_node)
           align_with = {