rubocop 1.90.0 → 1.92.0

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

@@ -51,14 +51,6 @@ module RuboCop
           end
         end
 
-        private
-
-        def previous_declaration(node)
-          declarations = gem_declarations(processed_source.ast)
-          node_index = declarations.map(&:location).find_index(node.location)
-          declarations.to_a[node_index - 1]
-        end
-
         # @!method gem_declarations(node)
         def_node_search :gem_declarations, <<~PATTERN
           (:send nil? :gem str ...)

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/correctors/alignment_corrector.rb

@@ -109,8 +109,20 @@ module RuboCop
         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
 

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,27 @@ 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.map(&:source).join(', '))
-        else
-          format(CORRECTION_WITHOUT_ARGUMENTS, enumerable: collection_node.source)
-        end
+        keyword = if block_node.arguments?
+                    format(
+                      CORRECTION_WITH_ARGUMENTS,
+                      collection: collection_node.source,
+                      variables: argument_node.children.map(&:source).join(', ')
+                    )
+                  else
+                    format(CORRECTION_WITHOUT_ARGUMENTS, enumerable: collection_node.source)
+                  end
+
+        padding_needed?(offending_range.end_pos) ? "#{keyword} " : keyword
+      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
@@ -77,7 +81,7 @@ module RuboCop
       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?
 
@@ -90,7 +94,7 @@ module RuboCop
         # `;`; 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(&:source).join(', ')
+        arg_string = regular.map { |arg| argument_source(arg) }.join(', ')
         arg_string += "; #{shadow.map(&:source).join(', ')}" unless shadow.empty?
         arg_string
       end
@@ -140,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/parentheses_corrector.rb

@@ -21,14 +21,55 @@ module RuboCop
           corrector.insert_after(node.loc.end, ' ')
         end
 
+        def heredoc_strands_code_after_close_paren?(node)
+          return false unless heredoc_body_before_close_paren?(node)
+
+          after_paren = text_after_close_paren(node)
+
+          !after_paren.empty? && !after_paren.start_with?('.', '&.', ',')
+        end
+
         private
 
         # When the line above `)` ends with a comment and a chained call follows `)`,
         # crossing the newline would pull the chain into the comment. Preserve the newline.
+        # When a heredoc body comes before `)`, a chained call has to start on the line
+        # after the terminator instead, since the terminator must stay alone on its line.
         def remove_close_paren(corrector, node, buffer)
-          newlines = !comment_above_close_paren_swallows_chain?(node, buffer)
-          corrector.remove(range_with_surrounding_space(range: node.loc.end, buffer: buffer,
-                                                        side: :left, newlines: newlines))
+          if heredoc_above_close_paren_swallows_chain?(node)
+            range = range_with_surrounding_space(range: node.loc.end, buffer: buffer, side: :left)
+
+            corrector.replace(range, "\n")
+          else
+            newlines = !comment_above_close_paren_swallows_chain?(node, buffer)
+            range = range_with_surrounding_space(
+              range: node.loc.end, buffer: buffer, side: :left, newlines: newlines
+            )
+
+            corrector.remove(range)
+          end
+        end
+
+        def heredoc_above_close_paren_swallows_chain?(node)
+          return false unless heredoc_body_before_close_paren?(node)
+
+          text_after_close_paren(node).start_with?('.', '&.')
+        end
+
+        def heredoc_body_before_close_paren?(node)
+          return false unless (last_child = node.children.last)
+
+          close_paren_pos = node.loc.end.begin_pos
+
+          last_child.each_node(:any_str).any? do |str_node|
+            str_node.heredoc? && str_node.loc.heredoc_end.end_pos <= close_paren_pos
+          end
+        end
+
+        def text_after_close_paren(node)
+          close_paren = node.loc.end
+
+          close_paren.source_line[(close_paren.column + 1)..].to_s.lstrip
         end
 
         def comment_above_close_paren_swallows_chain?(node, buffer)
@@ -46,12 +87,8 @@ module RuboCop
         end
 
         def chained_after_close_paren?(node)
-          close_paren = node.loc.end
-          line_text = close_paren.source_line
-          after_paren = line_text[(close_paren.column + 1)..]
-          return false if after_paren.nil?
+          trimmed = text_after_close_paren(node)
 
-          trimmed = after_paren.lstrip
           !trimmed.empty? && !trimmed.start_with?('#')
         end
 

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/documentation.rb

@@ -14,7 +14,7 @@ module RuboCop
       # @api private
       def url_for(cop_class, config = nil)
         base = department_to_basename(cop_class.department)
-        fragment = cop_class.cop_name.downcase.gsub(/[^a-z]/, '')
+        fragment = cop_class.cop_name.downcase.delete('/')
         base_url = base_url_for(cop_class, config)
         extension = extension_for(cop_class, config)
 

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

@@ -109,12 +109,6 @@ module RuboCop
           end
         end
 
-        def match_block_variable_name?(receiver_name)
-          gem_specification(processed_source.ast) do |block_variable_name|
-            return block_variable_name == receiver_name
-          end
-        end
-
         def add_dependency_method?(method_name)
           ADD_DEPENDENCY_METHODS.include?(method_name)
         end

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

@@ -80,12 +80,6 @@ module RuboCop
 
         private
 
-        def previous_declaration(node)
-          declarations = dependency_declarations(processed_source.ast)
-          node_index = declarations.find_index(node)
-          declarations.to_a[node_index - 1]
-        end
-
         def get_dependency_name(node)
           node.method_name
         end

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

@@ -201,11 +201,8 @@ module RuboCop
         def add_newline?(node)
           # Determine if a blank line should be inserted before the new directive
           # in order to spread out pattern matchers
-          return false if node.sibling_index&.zero?
-          return false unless node.parent
-
-          prev_sibling = node.parent.child_nodes[node.sibling_index - 1]
-          return false unless prev_sibling && pattern_matcher?(prev_sibling)
+          prev_sibling = node.left_sibling
+          return false unless prev_sibling.is_a?(AST::Node) && pattern_matcher?(prev_sibling)
 
           node.loc.line == last_line(prev_sibling) + 1
         end

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

@@ -46,13 +46,6 @@ module RuboCop
 
         private
 
-        def arguments_range(node)
-          range_between(
-            node.first_argument.source_range.begin_pos,
-            node.last_argument.source_range.end_pos
-          )
-        end
-
         def group_satisfied?(group_types, symbol_args)
           group_types.all? { |type| symbol_args.any? { |arg| arg.value == type } }
         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/internal_affairs/redundant_context_config_parameter.rb

@@ -31,15 +31,9 @@ module RuboCop
             dup_arguments = arguments.dup
             dup_arguments.delete(config_node)
 
-            corrector.replace(offense_range(arguments), dup_arguments.map(&:source).join(', '))
+            corrector.replace(arguments_range(node), dup_arguments.map(&:source).join(', '))
           end
         end
-
-        private
-
-        def offense_range(arguments)
-          range_between(arguments.first.source_range.begin_pos, arguments.last.source_range.end_pos)
-        end
       end
     end
   end

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

@@ -109,7 +109,7 @@ module RuboCop
         end
 
         def on_if(node)
-          traverse_condition(node.condition) do |cond|
+          node.condition.each_node(:send) do |cond|
             add_offense(cond, message: MSG_FOR_CONDITIONAL_USE) if style_detected_api_used?(cond)
           end
         end
@@ -134,12 +134,6 @@ module RuboCop
             no_acceptable_style_check(node) ||
             style_detected_check(node)
         end
-
-        def traverse_condition(condition, &block)
-          yield condition if condition.send_type?
-
-          condition.each_child_node { |child| traverse_condition(child, &block) }
-        end
       end
     end
   end

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

@@ -68,6 +68,7 @@ module RuboCop
       #   end
       #
       class BlockAlignment < Base
+        include Alignment
         include ConfigurableEnforcedStyle
         include RangeHelp
         extend AutoCorrector
@@ -154,6 +155,32 @@ module RuboCop
                           else
                             start_for_line_node(node)
                           end
+
+          if using_tabs? && (indentation = anchor_indentation(ancestor_node, node))
+            replace_end_indentation(corrector, node, indentation)
+          else
+            shift_end_to_start_col(corrector, ancestor_node, node)
+          end
+        end
+
+        def anchor_indentation(ancestor_node, node)
+          if style == :start_of_block
+            do_line_anchor_loc(node, node.loc.begin).source_line[/\A\s*/]
+          else
+            anchor_loc = (ancestor_node || node).source_range
+            anchor_loc.source_line[/\A\s*/] if begins_its_line?(anchor_loc)
+          end
+        end
+
+        def replace_end_indentation(corrector, node, indentation)
+          loc_end = node.loc.end
+          whitespace = range_between(loc_end.begin_pos - loc_end.column, loc_end.begin_pos)
+          return if whitespace.source == indentation
+
+          corrector.replace(whitespace, indentation)
+        end
+
+        def shift_end_to_start_col(corrector, ancestor_node, node)
           start_col = compute_start_col(ancestor_node, node)
           loc_end = node.loc.end
           delta = start_col - loc_end.column