rubocop 1.71.1 → 1.92.0

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]
@@ -44,7 +49,7 @@ module RuboCop
       #      - private_methods
       # ----
       #
-      # Instead of putting all literals in the expected order, is also
+      # Instead of putting all literals in the expected order, it is also
       # possible to group categories of macros. Visibility levels are handled
       # automatically.
       #
@@ -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
@@ -153,42 +188,75 @@ module RuboCop
 
         MSG = '`%<category>s` is supposed to appear before `%<previous>s`.'
 
+        # A moved element is inserted before the line break that precedes its anchor.
+        # When the anchor follows a blank line, `Layout/EmptyLines`,
+        # `Layout/EmptyLinesAroundAccessModifier` or `Layout/EmptyLinesAroundClassBody`
+        # may remove that line break in the same pass.
+        def self.autocorrect_incompatible_with
+          [Layout::EmptyLines, Layout::EmptyLinesAroundAccessModifier, Layout::EmptyLinesAroundClassBody]
+        end
+
         # 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}
         # @param node to be analysed
         # @return String when the node type is a `:block` then
         #   {classify} recursively with the first children
-        # @return String when the node type is a `:send` then {find_category}
+        # @return String when the node type is a `:send` then {find_send_node_category}
         #   by method name
         # @return String otherwise trying to {humanize_node} of the current node
         def classify(node)
@@ -198,9 +266,10 @@ module RuboCop
           when :block
             classify(node.send_node)
           when :send
-            find_category(node)
+            find_send_node_category(node)
           else
-            humanize_node(node)
+            name = humanize_node(node)
+            find_category(name) || name
           end.to_s
         end
 
@@ -209,19 +278,25 @@ module RuboCop
         # also its visibility.
         # @param node to be analysed.
         # @return [String] with the key category or the `method_name` as string
-        def find_category(node)
+        def find_send_node_category(node)
           name = node.method_name.to_s
-          category, = categories.find { |_, names| names.include?(name) }
+          category = find_category(name)
           key = category || name
           visibility_key =
             if node.def_modifier?
-              "#{name}_methods"
+              name.end_with?('_class_method') ? "#{name}s" : "#{name}_methods"
             else
               "#{node_visibility(node)}_#{key}"
             end
           expected_order.include?(visibility_key) ? visibility_key : key
         end
 
+        def find_category(name)
+          name = name.to_s
+          category, = categories.find { |_, names| names.include?(name) }
+          category
+        end
+
         def walk_over_nested_class_definition(class_node)
           class_elements(class_node).each do |node|
             classification = classify(node)
@@ -236,10 +311,14 @@ module RuboCop
 
           return [] unless class_def
 
-          if class_def.type?(:def, :send)
-            [class_def]
+          # Only a multi-statement body (`begin`/`kwbegin`) wraps several elements; any
+          # single statement (`def`, `send`, `csend`, `if`, ...) is itself the sole element.
+          # Exploding such a node into its children would yield non-node values (e.g. a
+          # method-name `Symbol` from a `csend`) and crash later checks.
+          if class_def.type?(:begin, :kwbegin)
+            flatten_class_elements(class_def)
           else
-            class_def.children.compact
+            [class_def]
           end
         end
 
@@ -250,13 +329,10 @@ module RuboCop
             private_constant?(node)
         end
 
-        def ignore_for_autocorrect?(node, sibling)
-          classification = classify(node)
-          sibling_class = classify(sibling)
-
-          ignore?(sibling, sibling_class) ||
-            classification == sibling_class ||
-            dynamic_constant?(node)
+        def flatten_class_elements(node)
+          node.children.compact.flat_map do |child|
+            child.kwbegin_type? ? flatten_class_elements(child) : [child]
+          end
         end
 
         def humanize_node(node)
@@ -276,6 +352,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)
@@ -295,7 +431,7 @@ module RuboCop
         def end_position_for(node)
           if node.casgn_type?
             heredoc = find_heredoc(node)
-            return heredoc.location.heredoc_end.end_pos + 1 if heredoc
+            return heredoc.location.heredoc_end.end_pos if heredoc
           end
 
           end_line = buffer.line_for_position(node.source_range.end_pos)
@@ -322,7 +458,7 @@ module RuboCop
         end
 
         def find_heredoc(node)
-          node.each_node(:str, :dstr, :xstr).find(&:heredoc?)
+          node.each_node(:any_str).find(&:heredoc?)
         end
 
         def buffer

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

@@ -155,13 +155,13 @@ module RuboCop
         end
 
         def all_elements_aligned?(elements)
-          elements.flat_map do |e|
-            if e.hash_type?
-              e.each_child_node.map { |child| child.loc.column }
-            else
+          if elements.first.hash_type?
+            elements.first.each_child_node.map { |child| child.loc.column }
+          else
+            elements.flat_map do |e|
               e.loc.column
             end
-          end.uniq.count == 1
+          end.uniq.one?
         end
 
         def first_argument_line(elements)

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)
@@ -155,8 +158,15 @@ module RuboCop
 
         def less_indented?(line)
           rule = config.for_cop('Layout/AccessModifierIndentation')['EnforcedStyle'] == 'outdent'
-          access_modifier = 'private|protected|public'
-          /\A\s*(end\b|[)}\]])/.match?(line) || (rule && /\A\s*(#{access_modifier})\b/.match?(line))
+          /\A\s*(end\b|[)}\]])/.match?(line) || (rule && bare_access_modifier?(line))
+        end
+
+        # Only a bare access modifier (the keyword alone on its line) is outdented by
+        # `Layout/AccessModifierIndentation`. An inline modifier such as `private def foo`
+        # keeps the regular method indentation, so a comment above it must not be pushed
+        # one level deeper.
+        def bare_access_modifier?(line)
+          /\A\s*(private|protected|public)\s*(#.*)?\z/.match?(line)
         end
 
         def two_alternatives?(line)

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

@@ -44,16 +44,26 @@ module RuboCop
           message = message(condition)
 
           add_offense(condition, message: message) do |corrector|
-            range = range_by_whole_lines(condition.source_range, include_final_newline: true)
-
             corrector.insert_after(condition.parent.loc.keyword, " #{condition.source}")
-            corrector.remove(range)
+            corrector.remove(removal_range(node, condition))
           end
         end
 
         def message(condition)
           format(MSG, keyword: condition.parent.keyword)
         end
+
+        # When a body statement shares the condition's line (e.g. `while\n cond; body\nend`),
+        # removing the whole line would delete the body too. In that case only remove the
+        # condition and its trailing separator, preserving the body statement.
+        def removal_range(node, condition)
+          body = node.body
+          if body && body.source_range.line == condition.source_range.last_line
+            range_between(condition.source_range.begin_pos, body.source_range.begin_pos)
+          else
+            range_by_whole_lines(condition.source_range, include_final_newline: true)
+          end
+        end
       end
     end
   end

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

@@ -48,7 +48,11 @@ module RuboCop
         def on_send(node)
           return unless node.def_modifier?
 
-          method_def = node.each_descendant(:def, :defs).first
+          method_def = node.each_descendant(:any_def).first
+          # A single-line `def` has nothing to align, even when a line
+          # continuation puts it on a later line than the modifier.
+          return if method_def.single_line?
+
           expr = node.source_range
 
           line_start = range_between(expr.begin_pos, method_def.loc.keyword.end_pos)

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

@@ -112,7 +112,7 @@ module RuboCop
         end
 
         def last_heredoc_line(node)
-          if node.send_type?
+          if node.call_type?
             node.arguments.select { |arg| heredoc?(arg) }.map { |arg| arg.loc.heredoc_end.line }.max
           elsif heredoc?(node)
             node.loc.heredoc_end.line
@@ -120,7 +120,7 @@ module RuboCop
         end
 
         def heredoc?(node)
-          node.type?(:str, :dstr) && node.heredoc?
+          node.any_str_type? && node.heredoc?
         end
 
         def end_range(node)

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

@@ -49,7 +49,7 @@ module RuboCop
         end
 
         def on_rescue(node)
-          return unless node.loc.respond_to?(:else) && node.loc.else
+          return unless node.loc?(:else)
 
           check_alignment(base_range_of_rescue(node), node.loc.else)
         end
@@ -92,13 +92,8 @@ module RuboCop
           case parent.type
           when :def, :defs then base_for_method_definition(parent)
           when :kwbegin then parent.loc.begin
-          when :block
-            assignment_node = assignment_node(parent)
-            if same_line?(parent, assignment_node)
-              assignment_node.source_range
-            else
-              parent.send_node.source_range
-            end
+          when :block, :numblock, :itblock then start_line_range(parent)
+          when :class, :module, :sclass then parent.loc.keyword
           else node.loc.keyword
           end
         end
@@ -143,13 +138,6 @@ module RuboCop
             autocorrect(corrector, else_range)
           end
         end
-
-        def assignment_node(node)
-          assignment_node = node.ancestors.first
-          return unless assignment_node&.assignment?
-
-          assignment_node
-        end
       end
     end
   end

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

@@ -95,8 +95,7 @@ module RuboCop
         end
 
         def autocorrect(corrector, node)
-          previous_token = previous_token(node)
-          range = if previous_token && same_line?(node, previous_token)
+          range = if inline_comment?(node)
                     range_with_surrounding_space(node.source_range, newlines: false)
                   else
                     range_by_whole_lines(node.source_range, include_final_newline: true)
@@ -138,14 +137,13 @@ module RuboCop
           cop_config['AllowMarginComment']
         end
 
-        def current_token(comment)
-          processed_source.tokens.find { |token| token.pos == comment.source_range }
-        end
-
-        def previous_token(node)
-          current_token = current_token(node)
-          index = processed_source.tokens.index(current_token)
-          index.zero? ? nil : processed_source.tokens[index - 1]
+        # A comment is inline when code precedes it on the same line. Detecting this
+        # from the source (rather than the token stream) is required because, for a
+        # comment trailing a heredoc opener, the preceding token is the heredoc end on
+        # a later line, which would wrongly trigger whole-line removal of the opener.
+        def inline_comment?(comment)
+          preceding_source = processed_source.lines[comment.loc.line - 1][0...comment.loc.column]
+          !preceding_source.strip.empty?
         end
       end
     end

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

@@ -5,8 +5,10 @@ module RuboCop
     module Layout
       # Enforces empty line after guard clause.
       #
-      # This cop allows `# :nocov:` directive after guard clause because
-      # SimpleCov excludes code from the coverage report by wrapping it in `# :nocov:`:
+      # This cop allows a SimpleCov directive comment after guard clause because
+      # SimpleCov excludes code from the coverage report by wrapping it in such directives.
+      # Both the legacy `# :nocov:` comment and the newer `# simplecov:disable` /
+      # `# simplecov:enable` comments are recognized:
       #
       # [source,ruby]
       # ----
@@ -16,6 +18,13 @@ module RuboCop
       #   # :nocov:
       #   bar
       # end
+      #
+      # def foo
+      #   # simplecov:disable
+      #   return if condition
+      #   # simplecov:enable
+      #   bar
+      # end
       # ----
       #
       # Refer to SimpleCov's documentation for more details:
@@ -58,7 +67,12 @@ module RuboCop
 
         MSG = 'Add empty line after guard clause.'
         END_OF_HEREDOC_LINE = 1
-        SIMPLE_DIRECTIVE_COMMENT_PATTERN = /\A# *:nocov:\z/.freeze
+        SIMPLECOV_COMMENT_PATTERN = /\A#\s*(?::nocov:|simplecov\s*:\s*(?:disable|enable)\b)/.freeze
+
+        # @!method guard_clause_branch?(node)
+        def_node_matcher :guard_clause_branch?, <<~PATTERN
+          {(send nil? {:raise :fail} ...) return break next}
+        PATTERN
 
         def on_if(node)
           return if correct_style?(node)
@@ -97,14 +111,16 @@ module RuboCop
         end
 
         def correct_style?(node)
-          !contains_guard_clause?(node) ||
+          !node.if_branch&.guard_clause? ||
             next_line_rescue_or_ensure?(node) ||
             next_sibling_parent_empty_or_else?(node) ||
             next_sibling_empty_or_guard_clause?(node)
         end
 
         def contains_guard_clause?(node)
-          node.if_branch&.guard_clause?
+          return false unless (branch = node.if_branch)
+
+          branch.guard_clause? || guard_clause_branch?(branch)
         end
 
         def next_line_empty_or_allowed_directive_comment?(line)
@@ -131,7 +147,7 @@ module RuboCop
 
         def next_sibling_parent_empty_or_else?(node)
           next_sibling = node.right_sibling
-          return true if next_sibling.nil?
+          return true unless next_sibling.is_a?(AST::Node)
 
           parent = next_sibling.parent
 
@@ -145,8 +161,10 @@ module RuboCop
           next_sibling.if_type? && contains_guard_clause?(next_sibling)
         end
 
+        # 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?
 
           return n if heredoc?(n)
           return unless n.respond_to?(:arguments)
@@ -189,7 +207,7 @@ module RuboCop
         end
 
         def offense_location(node)
-          if node.loc.respond_to?(:end) && node.loc.end
+          if node.loc?(:end)
             node.loc.end
           else
             node
@@ -203,10 +221,10 @@ module RuboCop
           parent.begin_type? && same_line?(node, node.right_sibling)
         end
 
-        # SimpleCov excludes code from the coverage report by wrapping it in `# :nocov:`:
+        # SimpleCov excludes code from the coverage report by wrapping it in directive comments:
         # https://github.com/simplecov-ruby/simplecov#ignoringskipping-code
         def simplecov_directive_comment?(comment)
-          SIMPLE_DIRECTIVE_COMMENT_PATTERN.match?(comment.text)
+          SIMPLECOV_COMMENT_PATTERN.match?(comment.text)
         end
       end
     end