rubocop 1.81.7 → 1.92.1

data/lib/rubocop/cop/commissioner.rb

@@ -64,14 +64,16 @@ module RuboCop
         r = '#' unless RESTRICTED_CALLBACKS.include?(method_name) # has Restricted?
         c = '#' if NO_CHILD_NODES.include?(node_type) # has Children?
 
+        # The `after_` calls are guarded because barely any cop defines an `after_`
+        # callback, and the guard is cheaper than the method call it avoids.
         class_eval(<<~RUBY, __FILE__, __LINE__ + 1)
-                  def on_#{node_type}(node)                               # def on_send(node)
-                    trigger_responding_cops(:on_#{node_type}, node)       #   trigger_responding_cops(:on_send, node)
-              #{r}  trigger_restricted_cops(:on_#{node_type}, node)       #   trigger_restricted_cops(:on_send, node)
-          #{c}      super(node)                                           #   super(node)
-          #{c}      trigger_responding_cops(:after_#{node_type}, node)    #   trigger_responding_cops(:after_send, node)
-          #{c}#{r}  trigger_restricted_cops(:after_#{node_type}, node)    #   trigger_restricted_cops(:after_send, node)
-                  end                                                     # end
+                  def on_#{node_type}(node)                                                                                # def on_send(node)
+                    trigger_responding_cops(:on_#{node_type}, node)                                                        #   trigger_responding_cops(:on_send, node)
+              #{r}  trigger_restricted_cops(:on_#{node_type}, node)                                                        #   trigger_restricted_cops(:on_send, node)
+          #{c}      super(node)                                                                                            #   super(node)
+          #{c}      trigger_responding_cops(:after_#{node_type}, node) if @callbacks[:after_#{node_type}]                  #   trigger_responding_cops(:after_send, node) if @callbacks[:after_send]
+          #{c}#{r}  trigger_restricted_cops(:after_#{node_type}, node) unless @restricted_map[:after_#{node_type}].empty?  #   trigger_restricted_cops(:after_send, node) unless @restricted_map[:after_send].empty?
+                  end                                                                                                      # end
         RUBY
       end
 
@@ -81,13 +83,13 @@ module RuboCop
 
         begin_investigation(processed_source, offset: offset, original: original)
         if processed_source.valid_syntax?
-          invoke(:on_new_investigation, @cops)
+          invoke(:on_new_investigation, @callbacks[:on_new_investigation])
           invoke_with_argument(:investigate, @forces, processed_source)
 
           walk(processed_source.ast) unless @cops.empty?
-          invoke(:on_investigation_end, @cops)
+          invoke(:on_investigation_end, @callbacks[:on_investigation_end])
         else
-          invoke(:on_other_file, @cops)
+          invoke(:on_other_file, @callbacks[:on_other_file])
         end
         reports = @cops.map { |cop| cop.send(:complete_investigation) }
         InvestigationReport.new(processed_source, reports, @errors)
@@ -157,7 +159,7 @@ module RuboCop
       end
 
       def invoke(callback, cops)
-        cops.each { |cop| with_cop_error_handling(cop) { cop.send(callback) } }
+        cops&.each { |cop| with_cop_error_handling(cop) { cop.send(callback) } }
       end
 
       def invoke_with_argument(callback, cops, arg)

data/lib/rubocop/cop/cop_documentation.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    # Reads the documentation comment a cop carries above its class definition
+    # and splits it into the sections worth showing on their own.
+    #
+    # YARD is a development dependency, so the comment is read straight from the
+    # source rather than through a doclet.
+    # @api private
+    class CopDocumentation
+      TAG = /^@(\w+)\s*(.*)$/.freeze
+
+      def initialize(cop_class)
+        @cop_class = cop_class
+      end
+
+      # @return [Array<Array(String, Array<String>)>] title and body per section
+      def sections
+        comment = comment_lines
+        return [] if comment.empty?
+
+        prose, tagged = split_on_first_tag(comment)
+
+        [['Details', strip_blank(prose)], *tagged_sections(tagged)].reject { |_, b| b.empty? }
+      end
+
+      private
+
+      def comment_lines
+        path, line = source_location
+        return [] unless path && File.file?(path)
+
+        lines = File.readlines(path, chomp: true)
+        collect_comment_above(lines, line - 2)
+      end
+
+      def source_location
+        name = @cop_class.name
+        return [] unless name
+
+        Module.const_source_location(name) || []
+      rescue NameError
+        []
+      end
+
+      # Walks up from the class definition for as long as the lines are comments.
+      def collect_comment_above(lines, index)
+        block = []
+        while index >= 0 && lines[index].match?(/^\s*#/)
+          block.unshift(lines[index].sub(/^\s*# ?/, ''))
+          index -= 1
+        end
+        block
+      end
+
+      def split_on_first_tag(comment)
+        first_tag = comment.index { |line| line.match?(TAG) }
+        return [comment, []] unless first_tag
+
+        [comment[0...first_tag], comment[first_tag..]]
+      end
+
+      def tagged_sections(lines)
+        lines.slice_before { |line| line.match?(TAG) }.map do |(head, *body)|
+          tag, argument = head.match(TAG).captures
+          [section_title(tag, argument), strip_blank(body)]
+        end
+      end
+
+      def section_title(tag, argument)
+        title = tag.capitalize
+        argument.empty? ? title : "#{title}: #{argument}"
+      end
+
+      def strip_blank(lines)
+        lines.drop_while(&:empty?).reverse.drop_while(&:empty?).reverse
+      end
+    end
+  end
+end

data/lib/rubocop/cop/cop_explanation.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    # Explains what a single cop does: its description, how it is configured,
+    # whether it corrects, and the examples from its own documentation.
+    #
+    # Rendered as plain text, which is what `--explain` prints and what the MCP
+    # server hands to an agent.
+    # @api private
+    class CopExplanation
+      # Keys that describe the cop to RuboCop itself rather than something a
+      # user would set, so they are reported in their own section or not at all.
+      METADATA_KEYS = %w[
+        Description StyleGuide Reference References Enabled Safe SafeAutoCorrect
+        AutoCorrect VersionAdded VersionChanged Include Exclude Details Preview
+      ].freeze
+
+      def initialize(cop_class, config)
+        @cop_class = cop_class
+        @config = config
+        @cop_config = config.for_cop(cop_class.cop_name)
+      end
+
+      def to_s
+        lines.join("\n")
+      end
+
+      private
+
+      def lines
+        description = description_lines
+
+        [
+          @cop_class.cop_name,
+          *section(nil, description),
+          *section('Properties', property_lines),
+          *documentation_sections(description).flat_map { |title, body| section(title, body) },
+          *section('Configuration', configuration_lines),
+          *section('References', reference_lines)
+        ]
+      end
+
+      def section(title, body)
+        return [] if body.empty?
+
+        heading = title ? [title, ''] : []
+        ['', *heading, *body.map { |line| line.empty? ? '' : "  #{line}" }]
+      end
+
+      def description_lines
+        Array(@cop_config['Description']).flat_map { |line| line.split("\n") }
+      end
+
+      def property_lines
+        [
+          "Enabled:     #{@cop_config.fetch('Enabled', true)}",
+          "Safe:        #{@cop_config.fetch('Safe', true)}",
+          "Autocorrect: #{autocorrect_description}",
+          *version_lines,
+          *scope_lines
+        ]
+      end
+
+      # Which files the cop looks at. A cop that only runs on Gemfiles
+      # explains an absent offense better than anything else here does.
+      def scope_lines
+        [
+          *patterns_line('Applies to:  ', @cop_config['Include']),
+          *patterns_line('Excludes:    ', @cop_config['Exclude'])
+        ]
+      end
+
+      def patterns_line(label, patterns)
+        patterns = Array(patterns).compact
+        return [] if patterns.empty?
+
+        ["#{label}#{patterns.map { |pattern| readable_pattern(pattern) }.join(', ')}"]
+      end
+
+      # `Exclude` patterns are absolutized against the config that set them,
+      # which makes for a wall of identical prefixes. A user config can also
+      # hold a regexp rather than a glob.
+      def readable_pattern(pattern)
+        pattern.is_a?(String) ? PathUtil.smart_path(pattern) : pattern.inspect
+      end
+
+      def autocorrect_description
+        return 'not supported' unless @cop_class.support_autocorrect?
+
+        # Asks the cop, so `AutoCorrect` is read the way the cop reads it.
+        cop = @cop_class.new(@config)
+        return 'disabled' unless cop.always_autocorrect? || cop.contextual_autocorrect?
+
+        description = cop.safe_autocorrect? ? 'safe, applied by -a' : 'unsafe, applied by -A only'
+        # Contextual corrections wait until the code is finished, which an
+        # editor or an agent mid-edit cannot promise, so they have to ask.
+        description += ', but through LSP or MCP only on request' if cop.contextual_autocorrect?
+        description
+      end
+
+      def version_lines
+        lines = []
+        lines << "Added:       #{@cop_config['VersionAdded']}" if @cop_config['VersionAdded']
+        lines << "Changed:     #{@cop_config['VersionChanged']}" if @cop_config['VersionChanged']
+        lines
+      end
+
+      def configuration_lines
+        (@cop_config.keys - METADATA_KEYS).sort.map do |key|
+          "#{key}: #{format_value(@cop_config[key])}"
+        end
+      end
+
+      def format_value(value)
+        value.is_a?(Array) ? value.join(', ') : value.to_s
+      end
+
+      def reference_lines
+        annotator = MessageAnnotator.new(@config, @cop_class.cop_name, @cop_config, {})
+
+        [*annotator.urls, Documentation.url_for(@cop_class, @config)].compact
+      end
+
+      # The comment above the class opens by restating the description, which
+      # is already printed above, so that opening is dropped.
+      def documentation_sections(description)
+        CopDocumentation.new(@cop_class).sections.filter_map do |title, body|
+          body -= description if title == 'Details'
+          body = strip_blank(body)
+          [title, body] unless body.empty?
+        end
+      end
+
+      def strip_blank(lines)
+        lines.drop_while(&:empty?).reverse.drop_while(&:empty?).reverse
+      end
+    end
+  end
+end

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)
@@ -103,7 +103,7 @@ module RuboCop
       # :nodoc:
       def to_range(node_or_range)
         range = case node_or_range
-                when ::RuboCop::AST::Node, ::Parser::Source::Comment
+                when RuboCop::AST::Node, ::Parser::Source::Comment
                   node_or_range.source_range
                 when ::Parser::Source::Range
                   node_or_range

data/lib/rubocop/cop/correctors/alignment_corrector.rb

@@ -12,17 +12,28 @@ module RuboCop
       class << self
         attr_reader :processed_source
 
-        def correct(corrector, processed_source, node, column_delta)
+        # `tab_indentation` may only be set by callers whose `column_delta` represents
+        # whole indentation levels (e.g. `Layout/IndentationWidth`).
+        # Alignment to an arbitrary column cannot be expressed with tabs, so those callers
+        # leave tab correction disabled to avoid producing a never-converging correction.
+        def correct(corrector, processed_source, node, column_delta, tab_indentation: false)
           return unless node
 
           @processed_source = processed_source
+
           expr = node.respond_to?(:loc) ? node.source_range : node
           return if block_comment_within?(expr)
 
           taboo_ranges = inside_string_ranges(node)
 
-          each_line(expr) do |line_begin_pos|
-            autocorrect_line(corrector, line_begin_pos, expr, column_delta, taboo_ranges)
+          if using_tabs?
+            return unless tab_indentation
+
+            correct_tab_indentation(corrector, expr, column_delta, taboo_ranges)
+          else
+            each_line(expr) do |line_begin_pos|
+              autocorrect_line(corrector, line_begin_pos, expr, column_delta, taboo_ranges)
+            end
           end
         end
 
@@ -30,11 +41,12 @@ module RuboCop
           @processed_source = processed_source
           whitespace = whitespace_range(node)
           column = alignment_column(align_to)
+          indentation = indentation_string(column)
 
           if whitespace.source.strip.empty?
-            corrector.replace(whitespace, ' ' * column)
+            corrector.replace(whitespace, indentation)
           else
-            corrector.insert_after(whitespace, "\n#{' ' * column}")
+            corrector.insert_after(whitespace, "\n#{indentation}")
           end
         end
 
@@ -54,9 +66,63 @@ module RuboCop
           end
         end
 
+        # Tab indentation is corrected by rewriting each line's leading whitespace to
+        # the target number of tabs. Working in whole tabs rather than applying a column delta
+        # keeps the result idempotent, which avoids the infinite loops that delta-based correction
+        # caused for tabs.
+        def correct_tab_indentation(corrector, expr, column_delta, taboo_ranges)
+          buffer = expr.source_buffer
+
+          each_line(expr) do |line_begin_pos|
+            line_range = buffer.line_range(buffer.line_for_position(line_begin_pos))
+            correct_tab_line(corrector, line_range, column_delta, taboo_ranges)
+          end
+        end
+
+        def correct_tab_line(corrector, line_range, column_delta, taboo_ranges)
+          leading = line_range.source[/\A[ \t]*/]
+          return if leading.length == line_range.source.length # blank line
+
+          leading_range = range_between(line_range.begin_pos, line_range.begin_pos + leading.length)
+          return if taboo_ranges.any? { |t| within?(leading_range, t) }
+
+          target = target_tab_indentation(leading, column_delta)
+          corrector.replace(leading_range, target) unless leading == target
+        end
+
+        def target_tab_indentation(leading, column_delta)
+          width = configured_indentation_width
+          return leading unless width.positive?
+
+          visual_width = leading.chars.sum { |char| char == "\t" ? width : 1 }
+
+          "\t" * ([visual_width + column_delta, 0].max / width)
+        end
+
+        # The number of columns a single tab spans. This must match the width
+        # `Layout/IndentationWidth` uses to compute `column_delta`, otherwise
+        # the division below would not land on a tab boundary. `Layout/IndentationStyle`
+        # has its own `IndentationWidth`, but that only governs how that cop replaces tabs
+        # with spaces, so it must not be consulted here.
+        def configured_indentation_width
+          processed_source.config.for_cop('Layout/IndentationWidth')['Width'] || 2
+        end
+
         def inside_string_ranges(node)
-          return [] unless node.is_a?(Parser::AST::Node)
+          return source_string_ranges unless node.is_a?(Parser::AST::Node)
+
+          string_ranges(node)
+        end
+
+        def source_string_ranges
+          return [] unless processed_source.ast
+          return @source_string_ranges if @source_string_ranges_source.equal?(processed_source)
+
+          @source_string_ranges_source = processed_source
+          @source_string_ranges = string_ranges(processed_source.ast)
+        end
 
+        def string_ranges(node)
           node.each_node(:any_str).filter_map { |n| inside_string_range(n) }
         end
 
@@ -76,9 +142,7 @@ module RuboCop
         #   nil.
         # - The source map of `__FILE__` responds to neither :begin nor :end.
         def delimited_string_literal?(node)
-          loc = node.location
-
-          loc.respond_to?(:begin) && loc.begin && loc.respond_to?(:end) && loc.end
+          node.loc?(:begin) && node.loc?(:end)
         end
 
         def block_comment_within?(expr)
@@ -122,6 +186,20 @@ module RuboCop
             align_to.column
           end
         end
+
+        def indentation_string(column)
+          if using_tabs?
+            "\t" * column
+          else
+            ' ' * column
+          end
+        end
+
+        def using_tabs?
+          config = processed_source.config
+          indentation_style = config.for_cop('Layout/IndentationStyle')['EnforcedStyle']
+          indentation_style == 'tabs'
+        end
       end
     end
   end

data/lib/rubocop/cop/correctors/condition_corrector.rb

@@ -16,7 +16,7 @@ module RuboCop
 
         def negated_condition(node)
           condition = node.condition
-          condition = condition.children.first while condition.begin_type?
+          condition = condition.children.last while condition.begin_type?
           condition
         end
       end

data/lib/rubocop/cop/correctors/each_to_for_corrector.rb

@@ -17,6 +17,7 @@ module RuboCop
 
       def call(corrector)
         corrector.replace(offending_range, correction)
+        corrector.replace(block_node.loc.end, closing_keyword) if block_node.braces?
       end
 
       private
@@ -24,13 +25,42 @@ module RuboCop
       attr_reader :block_node, :collection_node, :argument_node
 
       def correction
-        if block_node.arguments?
-          format(CORRECTION_WITH_ARGUMENTS,
-                 collection: collection_node.source,
-                 variables: argument_node.children.first.source)
-        else
-          format(CORRECTION_WITHOUT_ARGUMENTS, enumerable: collection_node.source)
-        end
+        keyword = if block_node.arguments?
+                    format(
+                      CORRECTION_WITH_ARGUMENTS,
+                      collection: collection_node.source,
+                      variables: loop_variables
+                    )
+                  else
+                    format(CORRECTION_WITHOUT_ARGUMENTS, enumerable: collection_node.source)
+                  end
+
+        padding_needed?(offending_range.end_pos) ? "#{keyword} " : keyword
+      end
+
+      def loop_variables
+        variables = argument_node.children.map { |argument| loop_variable(argument) }.join(', ')
+
+        argument_node.source.match?(/,\s*\|\z/) ? "#{variables}," : variables
+      end
+
+      def loop_variable(argument)
+        return argument.source unless argument.mlhs_type?
+
+        variables = argument.children.map { |child| loop_variable(child) }.join(', ')
+        lone_target = argument.children.one? && !argument.children.first.restarg_type?
+
+        lone_target ? "(#{variables},)" : "(#{variables})"
+      end
+
+      def closing_keyword
+        padding_needed?(block_node.loc.end.begin_pos - 1) ? ' end' : 'end'
+      end
+
+      def padding_needed?(position)
+        character = block_node.source_range.source_buffer.source[position]
+
+        !character.nil? && !character.match?(/\s/)
       end
 
       def offending_range

data/lib/rubocop/cop/correctors/empty_line_corrector.rb

@@ -12,7 +12,7 @@ module RuboCop
           when :no_empty_lines
             corrector.remove(range)
           when :empty_lines
-            corrector.insert_before(range, "\n")
+            corrector.insert_before(range.begin, "\n")
           end
         end
 

data/lib/rubocop/cop/correctors/lambda_literal_to_method_corrector.rb

@@ -29,6 +29,10 @@ module RuboCop
         insert_arguments(corrector)
       end
 
+      def replace_delimiters?
+        !block_node.braces? && arg_to_unparenthesized_call?
+      end
+
       private
 
       attr_reader :block_node, :method, :arguments
@@ -72,12 +76,12 @@ module RuboCop
       end
 
       def remove_trailing_whitespace(corrector)
-        size = block_begin.begin_pos - arguments.source_range.end_pos - 1
-        corrector.remove_preceding(block_begin, size) if size.positive?
+        whitespace = arguments.source_range.end.join(block_begin.begin)
+        corrector.replace(whitespace, ' ') if whitespace.size > 1
       end
 
       def replace_delimiters(corrector)
-        return if block_node.braces? || !arg_to_unparenthesized_call?
+        return unless replace_delimiters?
 
         corrector.insert_after(block_begin, ' ') unless separating_space?
 
@@ -86,7 +90,13 @@ module RuboCop
       end
 
       def lambda_arg_string
-        arguments.children.map(&:source).join(', ')
+        # Block-local (shadow) arguments are separated from regular arguments by a
+        # `;`; joining everything with `,` would turn them into extra parameters
+        # and change the lambda's arity.
+        regular, shadow = arguments.children.partition { |arg| !arg.shadowarg_type? }
+        arg_string = regular.map { |arg| argument_source(arg) }.join(', ')
+        arg_string += "; #{shadow.map(&:source).join(', ')}" unless shadow.empty?
+        arg_string
       end
 
       def needs_separating_space?
@@ -134,6 +144,23 @@ module RuboCop
       def separating_space?
         block_begin.source_buffer.source[block_begin.begin_pos + 2].match?(/\s/)
       end
+
+      def argument_source(argument)
+        return argument.source unless argument.type?(:optarg, :kwoptarg)
+        return argument.source unless operator_expression?(argument.default_value)
+
+        default_value = argument.default_value
+        name = argument.source_range.begin.join(default_value.source_range.begin).source
+
+        "#{name}(#{default_value.source})"
+      end
+
+      def operator_expression?(node)
+        return true if node.type?(:range, :if, :and, :or)
+        return false unless node.call_type?
+
+        node.operator_method? && !node.method?(:[])
+      end
     end
   end
 end

data/lib/rubocop/cop/correctors/multiline_literal_brace_corrector.rb

@@ -27,6 +27,7 @@ module RuboCop
           # corrected. The user must handle the delicate decision of where to
           # put the comment.
           return if new_line_needed_before_closing_brace?(node)
+          return if nested_closing_bracket_moved_before_comment?
 
           end_range = last_element_range_with_trailing_comma(node).end
 
@@ -43,6 +44,39 @@ module RuboCop
         corrector.insert_before(node.loc.end, "\n")
       end
 
+      def nested_closing_bracket_moved_before_comment?
+        last_element = children(node).last
+        return false unless (comment = processed_source.comment_at_line(last_element.last_line - 1))
+        return false unless (nested = nested_literal_with_closing_bracket_on_own_line(last_element))
+
+        own_line_comment?(comment) || !(nested.chained? || nested.argument?)
+      end
+
+      def nested_literal_with_closing_bracket_on_own_line(last_element)
+        last_line = last_element.last_line
+
+        last_element.each_node.find do |descendant|
+          same_kind_as_node?(descendant) && closing_bracket_on_own_line?(descendant, last_line)
+        end
+      end
+
+      def same_kind_as_node?(descendant)
+        descendant.type == node.type || (descendant.call_type? && node.call_type?)
+      end
+
+      def closing_bracket_on_own_line?(descendant, line)
+        return false unless descendant.loc?(:end) && descendant.loc.end.is?('}', ']', ')')
+
+        closing_bracket = descendant.loc.end
+        return false if closing_bracket.line != line
+
+        closing_bracket.source_line[0...closing_bracket.column].strip.empty?
+      end
+
+      def own_line_comment?(comment)
+        comment.source_range.source_line.lstrip.start_with?('#')
+      end
+
       def correct_next_line_brace(corrector, end_range)
         corrector.remove(range_with_surrounding_space(node.loc.end, side: :left))
         corrector.insert_before(end_range, content_if_comment_present(corrector, node))
@@ -59,11 +93,7 @@ module RuboCop
       end
 
       def content_if_comment_present(corrector, node)
-        range = range_with_surrounding_space(
-          children(node).last.source_range,
-          side: :right
-        ).end.resize(1)
-        if range.source == '#'
+        if processed_source.comment_at_line(children(node).last.last_line)
           select_content_to_be_inserted_after_last_element(corrector, node)
         else
           node.loc.end.source

data/lib/rubocop/cop/correctors/ordered_gem_corrector.rb

@@ -18,7 +18,14 @@ module RuboCop
           current_range = declaration_with_comment(node)
           previous_range = declaration_with_comment(previous_declaration)
 
-          ->(corrector) { corrector.swap(current_range, previous_range) }
+          lambda do |corrector|
+            if current_range.source.end_with?("\n")
+              corrector.swap(current_range, previous_range)
+            else
+              corrector.insert_before(previous_range, "#{current_range.source}\n")
+              corrector.remove(current_range)
+            end
+          end
         end
 
         private