rubocop 1.91.0 → 1.92.1

data/lib/rubocop/cop/base.rb

@@ -216,14 +216,8 @@ module RuboCop
         message = find_message(range_to_pass, message)
 
         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,
-                                        justification: justification)
+        current_offenses << new_offense(range, severity, message, status, corrector)
       end
 
       # This method should be overridden when a cop's behavior depends
@@ -271,10 +265,21 @@ module RuboCop
         @config.target_ruby_version
       end
 
-      # Returns a gems locked versions (i.e. from Gemfile.lock or gems.locked)
-      # @returns [Gem::Version | nil] The locked gem version, or nil if the gem is not present.
+      # Returns the version of a gem in the target, by default its locked version
+      # (i.e. from Gemfile.lock or gems.locked).
+      #
+      # The requirements declared with `requires_gem` are checked against the version
+      # this method returns, so an extension that lets users state the version of its
+      # gem in `AllCops` (e.g. `TargetFrameworkVersion`) can override it for that gem,
+      # returning a `Gem::Version`, and fall back to `super` for any other gem.
+      #
+      # @param [String] gem_name
+      # @return [Gem::Version, nil] The gem version, or nil if the gem is not present.
+      #
+      # @api public
       def target_gem_version(gem_name)
-        @config.gem_versions_in_target && @config.gem_versions_in_target[gem_name]
+        gem_versions = @config.gem_versions_in_target
+        gem_versions && gem_versions[gem_name]
       end
 
       def parser_engine
@@ -382,6 +387,12 @@ module RuboCop
         cop_config.fetch('AutoCorrect', 'always') == 'contextual'
       end
 
+      # @api private
+      def disabled_autocorrect?
+        # `false` is the same as `'disabled'` for backward compatibility.
+        ['disabled', false].include?(cop_config['AutoCorrect'])
+      end
+
       def inspect # :nodoc:
         "#<#{self.class.name}:#{object_id} @config=#{@config} @options=#{@options}>"
       end
@@ -394,6 +405,22 @@ module RuboCop
         @restrict_on_send ||= self::RESTRICT_ON_SEND.to_a.freeze
       end
 
+      # @return [Offense]
+      def new_offense(range, severity, message, status, corrector)
+        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.
+        # A cop configured with `AutoCorrect: false` reports no edits, since
+        # nothing that honors the configuration applies them. The corrector
+        # stays, so an editor can still offer it as a quick fix to choose.
+        corrections = [] if corrector && disabled_autocorrect?
+
+        Offense.new(severity, range_for_original(range), message, name, status, corrector,
+                    justification: justification, correction_safe: safe_autocorrect?,
+                    corrections: corrections)
+      end
+
       ### Reserved for Cop::Cop
 
       def callback_argument(range)
@@ -465,7 +492,8 @@ module RuboCop
           # 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?))
+        elsif corrector && (always_autocorrect? ||
+                            (contextual_autocorrect? && !contextual_autocorrect_held_back?))
           :uncorrected
         else
           :unsupported
@@ -601,17 +629,10 @@ module RuboCop
       end
 
       def target_satisfies_all_gem_version_requirements?
-        gem_requirements = self.class.gem_requirements
-        return true if gem_requirements.empty?
-
-        gem_requirements.all? do |gem_name, version_req|
-          all_gem_versions_in_target = @config.gem_versions_in_target
-          next false unless all_gem_versions_in_target
-
-          gem_version_in_target = all_gem_versions_in_target[gem_name]
-          next false unless gem_version_in_target
+        self.class.gem_requirements.all? do |gem_name, version_requirement|
+          gem_version = target_gem_version(gem_name)
 
-          version_req.satisfied_by?(gem_version_in_target)
+          gem_version && version_requirement.satisfied_by?(gem_version)
         end
       end
     end

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

@@ -81,7 +81,6 @@ module RuboCop
       #   gem 'bar', '< 2.1'
       #
       class GemComment < Base
-        include DefNode
         include GemDeclaration
 
         MSG = 'Missing gem description comment.'

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,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.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: 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?
 
@@ -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/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))

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/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/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