rubocop 1.91.0 → 1.92.2

data/lib/rubocop/cop/variable_force/variable.rb

@@ -67,7 +67,8 @@ module RuboCop
 
             break if !assignment.branch || assignment.branch == reference.branch
 
-            unless assignment.branch.may_run_incompletely?
+            unless assignment.branch.may_run_incompletely? ||
+                   exception_may_reach?(assignment.branch, node)
               (consumed_branches ||= Set.new) << assignment.branch
             end
           end
@@ -83,6 +84,18 @@ module RuboCop
           covers?(conditional, reference_node) && !covers?(conditional.condition, reference_node)
         end
 
+        # A branch nested in the main body of `begin` can be cut short by an exception
+        # too. An earlier assignment in it is visible to a reference in the `rescue` or
+        # `ensure` clause, or after a `rescue` that handles the exception.
+        def exception_may_reach?(branch, reference_node)
+          branch.each_ancestor.any? do |ancestor|
+            next false unless ancestor.may_run_incompletely?
+            next false if covers?(ancestor.child_node, reference_node)
+
+            ancestor.control_node.rescue_type? || covers?(ancestor.control_node, reference_node)
+          end
+        end
+
         def modifier_conditional_of(node)
           node.each_ancestor(:if, :while, :until).find do |conditional|
             conditional.modifier_form? && covers?(conditional.condition, node)

data/lib/rubocop/formatter/base_formatter.rb

@@ -35,6 +35,7 @@ module RuboCop
     # * `#file_started`
     # * `#file_finished`
     # * `#file_started`
+    # * `#file_problems` (only when a cop crashed or warned on the file)
     # * `#file_finished`
     # * `#finished`
     #
@@ -88,6 +89,27 @@ module RuboCop
       # @return [void]
       def file_started(file, options); end
 
+      # @api public
+      #
+      # Invoked before `#file_finished` for a file that a cop crashed on or
+      # raised a warning for, or whose corrections went into an infinite loop.
+      # Optional: a formatter implementing the API by duck typing is skipped
+      # when it doesn't define it.
+      #
+      # @param file [String]
+      #   the file path
+      #
+      # @param errors [Array(String)]
+      #   the error messages as they're printed, without colors. A cop that
+      #   crashes on every node of a kind has a message for each, naming the
+      #   line and column.
+      #
+      # @param warnings [Array(String)]
+      #   the warning messages, in the same form
+      #
+      # @return [void]
+      def file_problems(file, errors, warnings); end
+
       # @api public
       #
       # Invoked at the end of inspecting each files.

data/lib/rubocop/formatter/formatter_set.rb

@@ -49,6 +49,10 @@ module RuboCop
         each { |f| f.file_started(file, options) }
       end
 
+      def file_problems(file, errors, warnings)
+        each { |f| f.file_problems(file, errors, warnings) if f.respond_to?(:file_problems) }
+      end
+
       def file_finished(file, offenses)
         each { |f| f.file_finished(file, offenses) }
         offenses

data/lib/rubocop/formatter/json_formatter.rb

@@ -13,19 +13,29 @@ module RuboCop
       def initialize(output, options = {})
         super
         @output_hash = { metadata: metadata_hash, files: [], summary: { offense_count: 0 } }
+        @problems = {}
       end
 
       def started(target_files)
         output_hash[:summary][:target_file_count] = target_files.count
       end
 
+      def file_problems(file, errors, warnings)
+        @problems[file] = hash_for_problems(file, errors, warnings)
+      end
+
       def file_finished(file, offenses)
-        output_hash[:files] << hash_for_file(file, offenses)
+        entry = hash_for_file(file, offenses)
+        problems = @problems.delete(file)
+        entry.merge!(problems) if problems
+
+        output_hash[:files] << entry
         output_hash[:summary][:offense_count] += offenses.count
       end
 
       def finished(inspected_files)
         output_hash[:summary][:inspected_file_count] = inspected_files.count
+        output_hash[:summary].merge!(problem_counts(output_hash[:files]))
         output.write output_hash.to_json
       end
 
@@ -46,6 +56,32 @@ module RuboCop
         }
       end
 
+      # A cop that crashes fails once per node it visits, so messages that
+      # differ only in their line and column are listed once, at the first place
+      # they happened. They name the file the way its entry does. The keys are
+      # absent when there's nothing to report, which keeps them additive for
+      # existing consumers.
+      def hash_for_problems(file, errors, warnings)
+        return {} if errors.empty? && warnings.empty?
+
+        path = smart_path(file)
+        location = /#{Regexp.escape(File.expand_path(file))}((?::\d+)*)/
+
+        { errors: errors, warnings: warnings }.filter_map do |key, messages|
+          next if messages.empty?
+
+          messages = messages.uniq { |message| message.gsub(location, '') }
+          [key, messages.map { |message| message.gsub(location) { path + Regexp.last_match(1) } }]
+        end.to_h
+      end
+
+      def problem_counts(files)
+        {
+          error_count: files.sum { |f| f[:errors]&.size.to_i },
+          warning_count: files.sum { |f| f[:warnings]&.size.to_i }
+        }.reject { |_, count| count.zero? }
+      end
+
       def hash_for_offense(offense)
         hash = {
           severity:    offense.severity.name,
@@ -63,9 +99,43 @@ module RuboCop
           hash[:justification] = offense.justification
         end
 
+        # The edits autocorrection would make, so a consumer can apply or review
+        # them without running autocorrection itself. Additive, and absent when
+        # the offense has no correction.
+        hash[:correction] = correction_for(offense) unless offense.corrections.empty?
+
         hash
       end
 
+      def correction_for(offense)
+        { safe: offense.correction_safe, edits: edits_for(offense) }
+      end
+
+      def edits_for(offense)
+        buffer = offense.location.source_buffer
+
+        offense.corrections.map do |correction|
+          # Built as a range so the columns follow the same 1-based convention
+          # as `hash_for_location`, end-exclusive column included.
+          range = ::Parser::Source::Range.new(buffer, correction.begin_pos, correction.end_pos)
+
+          hash_for_edit_range(range).merge!(
+            begin_pos: correction.begin_pos,
+            end_pos: correction.end_pos,
+            replacement: correction.replacement
+          )
+        end
+      end
+
+      def hash_for_edit_range(range)
+        {
+          start_line: range.line,
+          start_column: range.column + 1,
+          last_line: range.last_line,
+          last_column: range.last_column.zero? ? 1 : range.last_column
+        }
+      end
+
       def hash_for_location(offense)
         {
           start_line:   offense.line,

data/lib/rubocop/formatter/offense_count_formatter.rb

@@ -14,6 +14,8 @@ module RuboCop
     # --
     # 29  Total in 5 files
     class OffenseCountFormatter < BaseFormatter
+      include TextUtil
+
       attr_reader :offense_counts
 
       def started(target_files)
@@ -64,7 +66,7 @@ module RuboCop
           output.puts "#{count.to_s.ljust(column_width)}#{cop_information(cop_name)}"
         end
         output.puts '--'
-        output.puts "#{total_count}  Total in #{offending_files_count} files"
+        output.puts "#{total_count}  Total in #{pluralize(offending_files_count, 'file')}"
 
         output.puts
       end

data/lib/rubocop/formatter/pacman_formatter.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'io/console'
+
 module RuboCop
   module Formatter
     # This formatter prints a PACDOT per every file to be analyzed.
@@ -50,7 +52,7 @@ module RuboCop
 
       def cols
         @cols ||= begin
-          _height, width = $stdout.winsize
+          _height, width = output.winsize if output.tty?
           width.nil? || width.zero? ? FALLBACK_TERMINAL_WIDTH : width
         end
       end

data/lib/rubocop/formatter/sarif_formatter.rb

@@ -38,8 +38,9 @@ module RuboCop
       end
 
       def file_finished(file, offenses)
+        line_hash_counts = Hash.new(0)
         offenses.each do |offense|
-          @results << result_for(file, offense)
+          @results << result_for(file, offense, line_hash_counts)
         end
       end
 
@@ -67,14 +68,14 @@ module RuboCop
         }
       end
 
-      def result_for(file, offense)
+      def result_for(file, offense, line_hash_counts)
         result = {
           ruleId: offense.cop_name,
           ruleIndex: rule_index_for(file, offense),
           level: SEVERITY_LEVELS.fetch(offense.severity.name, 'warning'),
           message: { text: offense.message },
           locations: [location_for(file, offense)],
-          partialFingerprints: fingerprints_for(offense)
+          partialFingerprints: fingerprints_for(offense, line_hash_counts)
         }
 
         # Suppressed offenses are only reported under `--display-suppressed`.
@@ -110,9 +111,13 @@ module RuboCop
 
       # GitHub uses these to match an alert across runs. Without them it falls
       # back to the file path, which makes alerts churn whenever a file moves.
-      def fingerprints_for(offense)
-        source_line = offense.location.source_line
-        { primaryLocationLineHash: Digest::SHA256.hexdigest("#{offense.cop_name}#{source_line}") }
+      # Repeats of the same hash within a file get a `:N` suffix, like GitHub's
+      # own fingerprints, so two offenses on one line don't merge into one alert.
+      # The first occurrence keeps the bare hash to match earlier reports.
+      def fingerprints_for(offense, line_hash_counts)
+        line_hash = Digest::SHA256.hexdigest("#{offense.cop_name}#{offense.location.source_line}")
+        count = line_hash_counts[line_hash] += 1
+        { primaryLocationLineHash: count == 1 ? line_hash : "#{line_hash}:#{count}" }
       end
 
       def suppression_for(offense)
@@ -158,7 +163,7 @@ module RuboCop
 
       def default_level_for(file, offense, cop_class)
         severity = cop_config(file, offense)['Severity'] ||
-                   (cop_class&.lint? ? :warning : :convention)
+                   Cop::Base::DEPARTMENT_SEVERITIES.fetch(cop_class&.department, :convention)
 
         SEVERITY_LEVELS.fetch(severity.to_sym, 'warning')
       end

data/lib/rubocop/formatter/worst_offenders_formatter.rb

@@ -14,6 +14,8 @@ module RuboCop
     # --
     # 29  Total in 2 files
     class WorstOffendersFormatter < BaseFormatter
+      include TextUtil
+
       attr_reader :offense_counts
 
       def started(target_files)
@@ -46,7 +48,7 @@ module RuboCop
         end
 
         output.puts '--'
-        output.puts "#{total_count}  Total in #{file_count} files"
+        output.puts "#{total_count}  Total in #{pluralize(file_count, 'file')}"
 
         output.puts
       end

data/lib/rubocop/lsp/routes.rb

@@ -25,12 +25,6 @@ module RuboCop
       # via `executeCommandProvider` so it knows which commands it can invoke.
       EXECUTE_COMMANDS = %w[rubocop.formatAutocorrects rubocop.formatAutocorrectsAll].freeze
 
-      def self.handle(name, &block)
-        define_method(:"handle_#{name}", &block)
-      end
-
-      private_class_method :handle
-
       def initialize(server)
         @server = server
 
@@ -44,6 +38,29 @@ module RuboCop
         method(name)
       end
 
+      def handle_unsupported_method(request, method = request[:method])
+        @server.write(
+          id: request[:id],
+          error: LanguageServer::Protocol::Interface::ResponseError.new(
+            code: LanguageServer::Protocol::Constant::ErrorCodes::METHOD_NOT_FOUND,
+            message: "Unsupported Method: #{method}"
+          )
+        )
+        Logger.log("Unsupported Method: #{method}")
+      end
+
+      def handle_method_missing(request)
+        return unless request.key?(:id)
+
+        @server.write(id: request[:id], result: nil)
+      end
+
+      def self.handle(name, &block)
+        define_method(:"handle_#{name}", &block)
+      end
+
+      private_class_method :handle
+
       handle 'initialize' do |request|
         initialization_options = extract_initialization_options_from(request)
 
@@ -178,23 +195,6 @@ module RuboCop
         # No-op, we log everything
       end
 
-      def handle_unsupported_method(request, method = request[:method])
-        @server.write(
-          id: request[:id],
-          error: LanguageServer::Protocol::Interface::ResponseError.new(
-            code: LanguageServer::Protocol::Constant::ErrorCodes::METHOD_NOT_FOUND,
-            message: "Unsupported Method: #{method}"
-          )
-        )
-        Logger.log("Unsupported Method: #{method}")
-      end
-
-      def handle_method_missing(request)
-        return unless request.key?(:id)
-
-        @server.write(id: request[:id], result: nil)
-      end
-
       private
 
       def extract_initialization_options_from(request)

data/lib/rubocop/lsp/runtime.rb

@@ -17,27 +17,31 @@ module RuboCop
     # Runtime for Language Server Protocol of RuboCop.
     # @api private
     class Runtime
-      attr_writer :safe_autocorrect, :lint_mode, :layout_mode
+      attr_writer :safe_autocorrect, :lint_mode, :layout_mode, :raise_cop_error
 
-      def initialize(config_store)
-        RuboCop::LSP.enable
+      # Without `lsp_mode`, offenses keep the locations and messages the
+      # command line gives them, rather than the ones meant for an editor.
+      def initialize(config_store, lsp_mode: true)
+        RuboCop::LSP.enable if lsp_mode
 
         @runner = RuboCop::Lsp::StdinRunner.new(config_store)
 
         @safe_autocorrect = true
         @lint_mode = false
         @layout_mode = false
+        @raise_cop_error = true
       end
 
-      def format(path, text, command:, prism_result: nil)
+      def format(path, text, command:, prism_result: nil, options: {})
         safe_autocorrect = if command
                              command == 'rubocop.formatAutocorrects'
                            else
                              @safe_autocorrect
                            end
 
-        formatting_options = { autocorrect: true, safe_autocorrect: safe_autocorrect }
-        formatting_options[:only] = config_only_options if @lint_mode || @layout_mode
+        formatting_options = {
+          autocorrect: true, safe_autocorrect: safe_autocorrect, raise_cop_error: @raise_cop_error
+        }.merge(call_options(options))
 
         @runner.run(path, text, formatting_options, prism_result: prism_result)
         @runner.formatted_source
@@ -48,17 +52,39 @@ module RuboCop
       end
 
       def offenses(path, text, document_encoding = nil, prism_result: nil)
-        diagnostic_options = {}
-        diagnostic_options[:only] = config_only_options if @lint_mode || @layout_mode
-
-        @runner.run(path, text, diagnostic_options, prism_result: prism_result)
+        found = raw_offenses(path, text, prism_result: prism_result)
         processed_source = @runner.processed_source
         config = @runner.config_for_working_directory
-        @runner.offenses.map do |offense|
+        found.map do |offense|
           build_diagnostic(offense, path, document_encoding, processed_source, config)
         end
       end
 
+      # The offenses before they are converted to LSP diagnostics, for callers
+      # that do not speak LSP.
+      def raw_offenses(path, text, prism_result: nil, options: {})
+        diagnostic_options = { raise_cop_error: @raise_cop_error }.merge(call_options(options))
+
+        @runner.run(path, text, diagnostic_options, prism_result: prism_result)
+        @runner.offenses
+      end
+
+      # The offenses the last `format` found but didn't correct, located in the
+      # source it returned.
+      def uncorrected_offenses
+        @runner.offenses.reject(&:corrected?)
+      end
+
+      # What went wrong in the last run. Cop errors only end up here when
+      # `raise_cop_error` is off; otherwise they are raised.
+      def errors
+        @runner.errors
+      end
+
+      def warnings
+        @runner.warnings
+      end
+
       private
 
       def build_diagnostic(offense, path, document_encoding, processed_source, config)
@@ -71,6 +97,16 @@ module RuboCop
         ).to_lsp_diagnostic(config)
       end
 
+      # What a caller adds for one call, such as `only` and `except` to select
+      # the cops, or `editing` to hold back the corrections of cops with
+      # `AutoCorrect: contextual`, as LSP mode does. Without `only`, the cops
+      # are the departments a lint or layout mode limits the server to.
+      def call_options(options)
+        return options if options[:only] || !(@lint_mode || @layout_mode)
+
+        options.merge(only: config_only_options)
+      end
+
       def config_only_options
         only_options = []
         only_options << 'Lint' if @lint_mode

data/lib/rubocop/lsp/stdin_runner.rb

@@ -23,7 +23,6 @@ module RuboCop
         stderr: true,
         force_exclusion: true,
         formatters: ['RuboCop::Formatter::BaseFormatter'],
-        raise_cop_error: true,
         todo_file: nil,
         todo_ignore_files: []
       }.freeze
@@ -41,6 +40,13 @@ module RuboCop
       end
 
       def run(path, contents, options, prism_result: nil)
+        # The cops mobilized for a configuration are cached, which only holds while
+        # every run asks for the same ones.
+        selection = options.values_at(:only, :except)
+        unless selection == @cop_selection
+          forget_mobilized_cops
+          @cop_selection = selection
+        end
         @options = options.merge(DEFAULT_RUBOCOP_OPTIONS)
         @options[:stdin] = contents
 
@@ -86,10 +92,10 @@ module RuboCop
         @offenses = offenses
       end
 
-      def do_inspection_loop(file)
-        source, offenses = super
-        @processed_source = source
-        [source, offenses]
+      def do_inspection_loop(file, source = nil)
+        processed_source, offenses = super
+        @processed_source = processed_source
+        [processed_source, offenses]
       end
     end
   end

data/lib/rubocop/lsp.rb

@@ -26,8 +26,11 @@ module RuboCop
       if block
         original = @enabled
         @enabled = false
-        yield
-        @enabled = original
+        begin
+          yield
+        ensure
+          @enabled = original
+        end
       else
         @enabled = false
       end

data/lib/rubocop/mcp/autocorrection_request.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module MCP
+    # What an autocorrection request asks for, shared by every file it corrects.
+    # The keywords are the tool's arguments, so an unknown one is refused.
+    # @api private
+    class AutocorrectionRequest
+      PROPERTIES = {
+        safety: { type: 'boolean' },
+        contextual: { type: 'boolean' },
+        dry_run: { type: 'boolean' },
+        max_offenses_per_cop: { type: 'integer', minimum: 1 }
+      }.freeze
+
+      # The offenses left over come back after the files are written, so they're
+      # capped unless the agent asks otherwise: a result too big for the client
+      # would hide what was done.
+      DEFAULT_MAX_OFFENSES_PER_COP = 5
+
+      attr_reader :scope, :limit
+
+      def initialize(scope, safety: true, contextual: false, dry_run: false,
+                     max_offenses_per_cop: DEFAULT_MAX_OFFENSES_PER_COP)
+        @scope = scope
+        @safety = safety
+        @contextual = contextual
+        @dry_run = dry_run
+        @limit = OffenseLimit.new(max_offenses_per_cop)
+      end
+
+      def dry_run?
+        @dry_run
+      end
+
+      # The options `LSP::Runtime#format` takes to apply the corrections
+      # `safety` and `contextual` allow, from the cops the scope selects.
+      def format_options
+        command = @safety ? 'rubocop.formatAutocorrects' : 'rubocop.formatAutocorrectsAll'
+        { command: command, options: runtime_options }
+      end
+
+      # The options the LSP runtime takes for each call the request makes.
+      # Cops with `AutoCorrect: contextual` hold back corrections that get in
+      # the way of code still being written, such as removing a variable that
+      # is about to be used, so an agent that is done editing has to ask for them.
+      def runtime_options
+        { **@scope.cop_options, editing: !@contextual }
+      end
+    end
+  end
+end

data/lib/rubocop/mcp/explain_tool.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module MCP
+    # The `rubocop_explain` tool: what cops do, as `--explain` prints it.
+    # @api private
+    class ExplainTool
+      include RuboCop::CLI::Command::CopNames
+
+      DESCRIPTION =
+        'Explain what cops do: the problem each one targets, bad and good examples, ' \
+        'its configuration as this project resolves it, and whether it autocorrects. ' \
+        'Takes cop names as offenses report them, such as `Style/StringLiterals`. ' \
+        'Pass the `path` of a file to see the configuration that applies to it.'
+      INPUT_SCHEMA = {
+        properties: {
+          cop_names: { type: 'array', items: { type: 'string' }, minItems: 1 },
+          path: { type: 'string' }
+        },
+        required: ['cop_names'],
+        additionalProperties: false
+      }.freeze
+      ANNOTATIONS = {
+        title: "RuboCop's cop explanation", destructive_hint: false, idempotent_hint: true,
+        open_world_hint: false, read_only_hint: true
+      }.freeze
+
+      def initialize(config_store)
+        @config_store = config_store
+      end
+
+      # The tool's block does not run in this instance, so it reaches
+      # `explain` through a method object it closes over.
+      def to_tool
+        explain = method(:explain)
+
+        ::MCP::Tool.define(
+          name: 'rubocop_explain',
+          description: DESCRIPTION,
+          input_schema: INPUT_SCHEMA,
+          annotations: ANNOTATIONS
+        ) do |cop_names:, path: nil|
+          ::MCP::Tool::Response.new([{ type: 'text', text: explain.call(cop_names, path) }])
+        rescue RuboCop::Error => e
+          ::MCP::Tool::Response.new([{ type: 'text', text: e.message }], error: true)
+        end
+      end
+
+      private
+
+      # Explains the cops it recognizes and then names the ones it does not, as
+      # `--explain` does, so a typo does not cost the explanations asked for
+      # alongside it. The configuration is loaded first, since that is what
+      # registers the cops of any plugins it names.
+      def explain(cop_names, path)
+        config = path ? @config_store.for_file(path) : @config_store.for_pwd
+        explanations = known_cop_classes(cop_names).map do |cop_class|
+          Cop::CopExplanation.new(cop_class, config).to_s
+        end
+        validate_cop_names!(cop_names)
+
+        explanations.join("\n\n")
+      rescue IncorrectCopNameError => e
+        raise RuboCop::Error, [*explanations, e.message].join("\n\n")
+      end
+    end
+  end
+end