rubocop 1.90.0 → 1.92.0

data/lib/rubocop/mcp/server.rb

@@ -19,7 +19,7 @@ rescue LoadError => e
   raise unless e.path == 'mcp'
 
   warn <<~MESSAGE
-    Error: Unable to load `mcp` gem. Add `gem 'mcp', '~> 0.6'` to your Gemfile, or run `gem install mcp`.
+    Error: Unable to load `mcp` gem. Add `gem 'mcp'` to your Gemfile, or run `gem install mcp`.
   MESSAGE
 
   exit!
@@ -27,16 +27,59 @@ end
 
 require_relative '../lsp'
 require_relative '../lsp/runtime'
+require_relative 'autocorrection_request'
+require_relative 'explain_tool'
+require_relative 'scope'
+require_relative 'source_files'
 
 module RuboCop
   module MCP
     # RuboCop MCP Server.
     # @api private
     class Server
+      INSPECTION_DESCRIPTION =
+        'Inspect Ruby code for offenses. ' \
+        'Provide `source_code` to check inline code or `path` to check files. ' \
+        'Either way the result lists offenses per file, with a summary, and the ' \
+        'offenses use the `rubocop --format json` format, with 1-based lines. ' \
+        '`correctable` says whether `rubocop_autocorrection` fixes an offense, ' \
+        'and one whose `correction` is not `safe` needs `safety` set to false. ' \
+        'One with a `correction` that is not `correctable` is held back while code is ' \
+        'being written, and only fixed with `contextual` set to true. ' \
+        '`max_offenses_per_cop` caps what each cop reports, and the ' \
+        'summary\'s `unreported_offenses` counts what was left out. ' \
+        'A cop that crashes is listed in its file\'s `errors`; the rest still report.'
+
+      AUTOCORRECTION_DESCRIPTION =
+        'Autocorrect RuboCop offenses in Ruby code. ' \
+        'Provide `source_code` to correct inline code, which comes back corrected as ' \
+        'plain text, or `path` to correct files. ' \
+        'Set `safety` to false to include unsafe corrections, and `contextual` to true ' \
+        'to include the ones held back while code is being written, such as removing ' \
+        'an unused variable. ' \
+        'Set `dry_run` to true to preview: nothing is written, and each corrected file ' \
+        'comes with its `diff`. ' \
+        'For files, the result lists each file that was corrected or still has offenses, ' \
+        'with the offenses left in the `rubocop_inspection` format, located in the ' \
+        'corrected file. One whose `correction` is not `safe` needs `safety` set to false, ' \
+        'and one with a `correction` that is not `correctable` needs `contextual` set to ' \
+        'true. Each cop lists at most `max_offenses_per_cop` of them, 5 unless ' \
+        'set, and the summary\'s `unreported_offenses` counts the rest. ' \
+        'A cop that crashes is listed in its file\'s `errors`, and a file whose ' \
+        'corrections loop is left unchanged.'
+
       def initialize(config_store)
         @config_store = config_store
-        @runtime = RuboCop::LSP::Runtime.new(@config_store)
+        # An agent isn't an editor, so offenses are located and worded the way
+        # the command line does it. Only contextual corrections are held back.
+        @runtime = RuboCop::LSP::Runtime.new(@config_store, lsp_mode: false)
+        # One cop crashing on one file should not cost an agent everything else
+        # in the request, so cop errors are collected and reported per file.
+        @runtime.raise_cop_error = false
         @options = {}
+        # Offenses are reported the way `--format json` reports them, so an agent
+        # sees the same 1-based locations and correction data either way.
+        @json_formatter = RuboCop::Formatter::JSONFormatter.new(nil)
       end
 
       def start
@@ -44,7 +87,7 @@ module RuboCop
         server = ::MCP::Server.new(
           name: 'rubocop_mcp_server',
           version: RuboCop::Version::STRING,
-          tools: [inspection_tool, autocorrection_tool]
+          tools: [inspection_tool, autocorrection_tool, ExplainTool.new(@config_store).to_tool]
         )
 
         ::MCP::Server::Transports::StdioTransport.new(server).open
@@ -55,91 +98,158 @@ module RuboCop
       def inspection_tool
         build_tool(
           name: 'rubocop_inspection',
-          description: 'Inspect Ruby code for offenses. ' \
-                       'Provide `source_code` to check inline code or `path` to check files.',
+          description: INSPECTION_DESCRIPTION,
           title: "RuboCop's inspection",
           destructive_hint: false,
           idempotent_hint: true,
           read_only_hint: true,
-          safety_required: false
-        ) do |path, source_code|
-          run_inspection(path, source_code)
+          properties: { max_offenses_per_cop: { type: 'integer', minimum: 1 } }
+        ) do |scope:, path: nil, source_code: nil, max_offenses_per_cop: nil|
+          run_inspection(path, source_code, max_offenses_per_cop, scope)
         end
       end
 
       def autocorrection_tool
         build_tool(
           name: 'rubocop_autocorrection',
-          description: 'Autocorrect RuboCop offenses in Ruby code. ' \
-                       'Provide `source_code` to correct inline code or `path` to correct files. ' \
-                       'Set `safety` to false to include unsafe corrections.',
+          description: AUTOCORRECTION_DESCRIPTION,
           title: "RuboCop's autocorrection",
           destructive_hint: true,
           idempotent_hint: false,
           read_only_hint: false,
-          safety_required: true
-        ) do |path, source_code, safety|
-          run_autocorrection(path, source_code, safety)
+          properties: AutocorrectionRequest::PROPERTIES,
+          required: ['safety']
+        ) do |scope:, path: nil, source_code: nil, **arguments|
+          run_autocorrection(path, source_code, AutocorrectionRequest.new(scope, **arguments))
         end
       end
 
-      def run_inspection(path, source_code)
-        if source_code
-          offenses = @runtime.offenses(path || 'example.rb', source_code, source_code.encoding)
-          offenses.to_json
-        else
-          process_files(path, filter_empty: true) do |file, source|
-            offenses = @runtime.offenses(file, source, source.encoding)
-
-            { path: PathUtil.relative_path(file), offenses: offenses }
+      # A limit counts across the files of one request, so every request starts
+      # from zero.
+      def run_inspection(path, source_code, max_offenses_per_cop, scope)
+        limit = OffenseLimit.new(max_offenses_per_cop) if max_offenses_per_cop
+        result =
+          if source_code
+            file = path || 'example.rb'
+            build_result([file], [inspect_source(file, source_code, limit, scope)])
+          else
+            process_files(path, scope) { |file, src| inspect_source(file, src, limit, scope) }
           end
+        result_json(result, limit)
+      end
+
+      def inspect_source(file, source, limit, scope)
+        options = { **scope.cop_options, editing: true }
+        offenses = @runtime.raw_offenses(file, source, options: options)
+        offense_entry(file, offenses, limit).merge(problems_of_last_run(file))
+      end
+
+      # The offenses of a file the way `--format json` lists them, capped across
+      # the files of a request.
+      def offense_entry(file, offenses, limit)
+        offenses = limit.filter(offenses) if limit
+        @json_formatter.hash_for_file(file, offenses)
+      end
+
+      def run_autocorrection(path, source_code, request)
+        return correct_inline(path, source_code, request) if source_code
+
+        result = process_files(path, request.scope) do |file, source|
+          correct_file(file, source, request)
         end
+        result[:summary][:corrected_file_count] = result[:files].count { |file| file[:corrected] }
+        result_json(result, request.limit)
       end
 
-      def run_autocorrection(path, source_code, safety)
-        command = safety ? 'rubocop.formatAutocorrects' : 'rubocop.formatAutocorrectsAll'
+      # The agent never sees stderr, so the summary says what the limit left out.
+      def result_json(result, limit)
+        unreported = limit&.elided_per_cop
+        result[:summary][:unreported_offenses] = unreported if unreported&.any?
+        result.to_json
+      end
 
-        if source_code
-          @runtime.format(path || 'example.rb', source_code, command: command).tap do |corrected|
-            write_file(path, corrected) if path
-          end
+      # Cops that keep undoing each other's corrections leave the file half
+      # corrected, so it is left alone and the loop is reported instead. A file
+      # with nothing to correct is left alone too, so its modification time
+      # doesn't tell editors and agents it changed. The offenses left over are
+      # the ones an agent has to fix itself, which saves it inspecting again.
+      def correct_file(file, source, request)
+        corrected = @runtime.format(file, source, **request.format_options)
+        problems = problems_of_last_run(file)
+        looped = @runtime.errors.any?(Runner::InfiniteCorrectionLoop)
+        changed = !looped && source != corrected
+        leftovers = leftover_offenses(file, source, corrected, changed, request)
+        entry = offense_entry(file, leftovers, request.limit)
+        diff = write_or_diff(file, entry[:path], source, corrected, request) if changed
+
+        { path: entry[:path], corrected: changed, diff: diff, **entry, **problems }.compact
+      end
+
+      # A dry run writes nothing and returns the diff a real run would have
+      # applied, line endings included.
+      def write_or_diff(file, path, source, corrected, request)
+        if request.dry_run?
+          UnifiedDiff.new(path, source, Util.emulate_write_read_cycle(corrected)).to_s
         else
-          process_files(path) do |file, source|
-            @runtime.format(file, source, command: command).then do |corrected|
-              write_file(file, corrected)
+          SourceFiles.write(file, corrected)
+          nil
+        end
+      end
 
-              { path: PathUtil.relative_path(file), corrected: source != corrected }
-            end
-          end
+      # What's left is in the file as written, or as a dry run would have
+      # written it, or as it was when its corrections loop. The runner checks
+      # corrected code with LF line endings, which writing turns into CRLF on
+      # Windows, so there the file is checked again as written.
+      def leftover_offenses(file, source, corrected, changed, request)
+        on_disk = changed ? Util.emulate_write_read_cycle(corrected) : source
+        return @runtime.uncorrected_offenses if on_disk == corrected
+
+        @runtime.raw_offenses(file, on_disk, options: request.runtime_options)
+      end
+
+      # Corrected inline code comes back as plain text with nowhere to mention
+      # a cop that crashed, so a crash fails the call instead of going unseen.
+      def correct_inline(path, source_code, request)
+        file = path || 'example.rb'
+        corrected = @runtime.format(file, source_code, **request.format_options)
+        errors = problems_of_last_run(file)[:errors]
+        raise RuboCop::Error, errors.join("\n") if errors
+
+        SourceFiles.write(path, corrected) if path && !request.dry_run?
+        corrected
+      end
+
+      # Collapsed the way `--format json` collapses them, which also folds the
+      # repeats from each autocorrection pass a crashing cop fails on.
+      def problems_of_last_run(file)
+        errors, warnings = [@runtime.errors, @runtime.warnings].map do |problems|
+          problems.map { |problem| Rainbow::StringUtils.uncolor(problem.to_s) }
         end
+        @json_formatter.hash_for_problems(file, errors, warnings)
       end
 
-      def process_files(path, filter_empty: false)
+      def process_files(path, scope)
         target_finder = RuboCop::TargetFinder.new(@config_store, @options)
-        target_files = target_finder.find(path ? [path] : [], :only_recognized_file_types)
-        all_files = target_files.map { |file| yield(file, read_file(file)) }
-        files = filter_empty ? all_files.reject { |f| f[:offenses]&.empty? } : all_files
+        target_files = scope.select_files(
+          target_finder.find(path ? [path] : [], :only_recognized_file_types)
+        )
+        all_files = target_files.map do |file|
+          yield(file, SourceFiles.read(file, @config_store.for_file(file)))
+        end
 
-        { files: files, summary: build_summary(target_files, all_files) }.to_json
+        build_result(target_files, all_files)
       end
 
-      def read_file(file)
-        config = @config_store.for_file(file)
-        RuboCop::ProcessedSource.from_file(
-          file, config.target_ruby_version, parser_engine: config.parser_engine
-        ).raw_source
-      rescue Errno::ENOENT
-        raise RuboCop::Error, "No such file or directory: #{file}"
+      # Inline code is reported as a single file, so an agent reads one shape
+      # whichever way it asked. Files with nothing to report are only counted.
+      def build_result(target_files, all_files)
+        files = all_files.reject { |f| nothing_to_report?(f) }
+
+        { files: files, summary: build_summary(target_files, all_files) }
       end
 
-      def write_file(file, content)
-        File.write(file, content)
-      rescue Errno::EACCES
-        raise RuboCop::Error, "Permission denied: #{file}"
-      rescue Errno::ENOSPC
-        raise RuboCop::Error, "No space left on device: #{file}"
-      rescue Errno::EROFS
-        raise RuboCop::Error, "Read-only file system: #{file}"
+      def nothing_to_report?(file)
+        file[:offenses].empty? && !file[:corrected] && !file[:errors] && !file[:warnings]
       end
 
       # NOTE: It is useful for RuboCop's result summary to be shown in the LLM's responses
@@ -147,28 +257,16 @@ module RuboCop
       # to reason about. Since LLM execution is non-deterministic, it is also sensible to
       # compute the summary deterministically at this stage.
       def build_summary(target_files, files)
-        summary = { target_file_count: target_files.count }
-        if files.first&.key?(:offenses)
-          summary[:offense_count] = files.sum { |f| f[:offenses].size }
-        else
-          summary[:corrected_file_count] = files.count { |f| f[:corrected] }
-        end
-        summary
+        offense_count = files.sum { |f| f[:offenses].size }
+        { target_file_count: target_files.count, offense_count: offense_count }
+          .merge(@json_formatter.problem_counts(files))
       end
 
       # rubocop:disable-next Metrics/MethodLength, Metrics/ParameterLists
       def build_tool(
         name:, description:,
-        title:, destructive_hint:, idempotent_hint:, read_only_hint:, safety_required:
+        title:, destructive_hint:, idempotent_hint:, read_only_hint:, properties:, required: nil
       )
-        if safety_required
-          safety_property = { safety: { type: 'boolean' } }
-          required = ['safety']
-        else
-          safety_property = {}
-          required = nil
-        end
-
         ::MCP::Tool.define(
           name: name,
           description: description,
@@ -176,8 +274,11 @@ module RuboCop
             properties: {
               path: { type: 'string' },
               source_code: { type: 'string' }
-            }.merge(safety_property),
-            required: required
+            }.merge(properties, Scope::PROPERTIES),
+            required: required,
+            # The gem checks arguments against the schema, so one the tool
+            # doesn't take is refused by name rather than failing the call.
+            additionalProperties: false
           }.compact,
           annotations: {
             title: title,
@@ -186,11 +287,18 @@ module RuboCop
             open_world_hint: false,
             read_only_hint: read_only_hint
           }
-        ) do |path: nil, source_code: nil, safety: true|
-          result = yield(path, source_code, safety)
+        ) do |**arguments|
+          # Taking any keywords makes the gem pass a `server_context` as well.
+          # Each tool's own block names the arguments it accepts.
+          arguments.delete(:server_context)
+          selection = Scope::PROPERTIES.keys.to_h { |key| [key, arguments.delete(key)] }
+          scope = Scope.new(inline: !arguments[:source_code].nil?, **selection)
+          result = yield(**arguments, scope: scope)
 
           ::MCP::Tool::Response.new([{ type: 'text', text: result }])
-        rescue RuboCop::Error => e
+        rescue RuboCop::Error, IncorrectCopNameError => e
+          # The runner raises `IncorrectCopNameError` for a name in `only` or
+          # `except` that it does not know, with suggestions.
           ::MCP::Tool::Response.new([{ type: 'text', text: e.message }], error: true)
         end
       end

data/lib/rubocop/mcp/source_files.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module MCP
+    # Reads and writes the files the tools work on. A file that can't be read
+    # or written fails the request with an error the agent can act on.
+    # @api private
+    module SourceFiles
+      module_function
+
+      def read(file, config)
+        RuboCop::ProcessedSource.from_file(
+          file, config.target_ruby_version, parser_engine: config.parser_engine
+        ).raw_source
+      rescue Errno::ENOENT
+        raise RuboCop::Error, "No such file or directory: #{file}"
+      end
+
+      # Writing what a file already holds would only bump its modification time.
+      def write(file, content)
+        return if File.file?(file) && File.binread(file) == content.b
+
+        Util.replace_file_contents(file, content)
+      rescue Errno::EACCES
+        raise RuboCop::Error, "Permission denied: #{file}"
+      rescue Errno::EPERM
+        raise RuboCop::Error, "Operation not permitted: #{file}"
+      rescue Errno::ENOSPC
+        raise RuboCop::Error, "No space left on device: #{file}"
+      rescue Errno::EROFS
+        raise RuboCop::Error, "Read-only file system: #{file}"
+      end
+    end
+  end
+end

data/lib/rubocop/offense_limit.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module RuboCop
+  # Caps how many offenses each cop gets to report.
+  #
+  # Counted across a whole run rather than per file, since a cop that fires a
+  # handful of times in every file is exactly the one worth capping. Offenses
+  # have to be offered in a stable order (files in the order they are
+  # reported) for the same ones to survive every time.
+  # @api private
+  class OffenseLimit
+    attr_reader :max
+
+    def initialize(max)
+      @max = max
+      @offered = Hash.new(0)
+    end
+
+    # @return [Array<Cop::Offense>] the offenses still within their cop's limit
+    def filter(offenses)
+      offenses.select { |offense| (@offered[offense.cop_name] += 1) <= @max }
+    end
+
+    # @return [Hash{String => Integer}] how many offenses each cop had left out,
+    #   sorted by cop name
+    def elided_per_cop
+      @offered.filter_map { |cop, count| [cop, count - @max] if count > @max }.sort.to_h
+    end
+  end
+end

data/lib/rubocop/options.rb

@@ -17,7 +17,7 @@ module RuboCop
                       'cops are enabled (via eg. Include/Exclude), and so that certain cops ' \
                       'like Naming/FileName can be checked.'
     EXITING_OPTIONS = %i[
-      version verbose_version show_cops list_enabled_cops_for show_docs_url lsp mcp
+      version verbose_version show_cops list_enabled_cops_for show_docs_url explain lsp mcp
     ].freeze
     DEFAULT_MAXIMUM_EXCLUSION_ITEMS = 15
 
@@ -33,6 +33,9 @@ module RuboCop
 
       define_options.parse!(args)
 
+      return_path_given_to_changed(args)
+      imply_autocorrect_for_diff
+
       @validator.validate_compatibility
 
       if @options[:stdin]
@@ -51,6 +54,21 @@ module RuboCop
 
     private
 
+    # `--changed lib` hands the path to `--changed` as its optional argument,
+    # so it goes back among the paths to inspect.
+    def return_path_given_to_changed(args)
+      args.unshift(@path_given_to_changed) if @path_given_to_changed
+    end
+
+    # `--diff` is a dry run of autocorrection, so it turns autocorrection on
+    # unless the user already picked a mode with `-a`, `-A` or `-x`.
+    def imply_autocorrect_for_diff
+      return unless @options[:diff] && !@options[:autocorrect]
+
+      @options[:safe_autocorrect] = true
+      @options[:autocorrect] = true
+    end
+
     # rubocop:disable-next Metrics/AbcSize
     def define_options
       OptionParser.new do |opts|
@@ -92,12 +110,20 @@ module RuboCop
         option(opts, '--enable-pending-cops')
         option(opts, '--disable-all-cops')
         option(opts, '--enable-all-cops')
+        option(opts, '--[no-]preview')
         option(opts, '--ignore-disable-comments')
         option(opts, '--force-exclusion')
         option(opts, '--only-recognized-file-types')
         option(opts, '--ignore-parent-exclusion')
         option(opts, '--ignore-unrecognized-cops')
         option(opts, '--force-default-config')
+        option(opts, '--changed [REVISION]') do |revision|
+          if @validator.path_given_to_changed?(revision)
+            @path_given_to_changed = revision
+            revision = nil
+          end
+          @options[:changed] = revision || ChangedFiles::DEFAULT_REVISION
+        end
         option(opts, '-s', '--stdin FILE')
         option(opts, '--editor-mode')
         option(opts, '-P', '--[no-]parallel')
@@ -132,10 +158,13 @@ module RuboCop
         option(opts, '--display-only-correctable')
         option(opts, '--display-only-safe-correctable')
         option(opts, '--display-suppressed')
+        option(opts, '--max-offenses-per-cop COUNT') do
+          @validator.validate_max_offenses_per_cop_option
+        end
       end
     end
 
-    # rubocop:todo Naming/InclusiveLanguage
+    # rubocop:todo Naming/InclusiveLanguage -- `--auto-correct` is the deprecated flag name
     # the autocorrect command-line arguments map to the autocorrect @options values like so:
     #                            :fix_layout  :autocorrect  :safe_autocorrect  :autocorrect_all
     # -x, --fix-layout           true         true          -                  -
@@ -161,6 +190,8 @@ module RuboCop
         end
 
         option(opts, '--disable-uncorrectable')
+
+        option(opts, '--diff')
       end
     end
     # rubocop:enable Naming/InclusiveLanguage
@@ -249,6 +280,9 @@ module RuboCop
         option(opts, '--show-docs-url [COP1,COP2,...]') do |list|
           @options[:show_docs_url] = list.nil? ? [] : list.split(',')
         end
+        option(opts, '--explain COP1,COP2,...') do |list|
+          @options[:explain] = list.split(',')
+        end
       end
     end
 
@@ -400,6 +434,8 @@ module RuboCop
       validate_display_only_failed_and_display_only_correctable
       validate_display_only_correctable_and_autocorrect
       validate_lsp_and_editor_mode
+      validate_diff
+      validate_changed_and_stdin
       validate_enable_all_cops_and_disable_all_cops
       disable_parallel_when_invalid_option_combo
 
@@ -447,6 +483,20 @@ module RuboCop
             '--display-only-failed cannot be used together with other display options.'
     end
 
+    # `--diff` promises not to write anything, and `--auto-gen-config` exists to
+    # write a file.
+    def validate_diff
+      return unless @options.key?(:diff) && @options.key?(:auto_gen_config)
+
+      raise OptionArgumentError, '--diff cannot be used with --auto-gen-config.'
+    end
+
+    def validate_changed_and_stdin
+      return unless @options.key?(:changed) && @options.key?(:stdin)
+
+      raise OptionArgumentError, '--changed cannot be used with --stdin.'
+    end
+
     def validate_lsp_and_editor_mode
       return if !@options.key?(:lsp) || !@options.key?(:editor_mode)
 
@@ -475,7 +525,7 @@ module RuboCop
     end
 
     def disable_parallel_when_invalid_option_combo
-      return unless @options.key?(:parallel)
+      return unless @options[:parallel]
 
       invalid_flags = invalid_arguments_for_parallel
 
@@ -483,7 +533,9 @@ module RuboCop
 
       @options.delete(:parallel)
 
-      puts '-P/--parallel is being ignored because ' \
+      # On stderr, so that it can't end up in the middle of a formatter's
+      # output, such as `--format json`.
+      warn '-P/--parallel is being ignored because ' \
            "it is not compatible with #{invalid_flags.join(', ')}."
     end
 
@@ -511,6 +563,25 @@ module RuboCop
       @incompatible_options ||= @options.keys & Options::EXITING_OPTIONS
     end
 
+    # OptionParser hands `--changed lib/` the path as the revision, which is a
+    # natural thing to type, so an argument that names an existing path is
+    # taken as one. When it also names a revision there is no telling which
+    # was meant, and git itself refuses such an argument as ambiguous.
+    def path_given_to_changed?(revision)
+      return false unless revision && File.exist?(revision)
+      return true unless ChangedFiles.revision?(revision)
+
+      raise OptionArgumentError,
+            "--changed got `#{revision}`, which is both a path and a git revision. Write " \
+            "`./#{revision}` for the path, or `--changed=#{revision}^0` for the revision."
+    end
+
+    def validate_max_offenses_per_cop_option
+      return if /^[1-9]\d*$/.match?(@options[:max_offenses_per_cop])
+
+      raise OptionParser::InvalidArgument, '--max-offenses-per-cop must be a positive integer'
+    end
+
     def validate_exclude_limit_option
       return if /^\d+$/.match?(@options[:exclude_limit])
 
@@ -566,12 +637,21 @@ module RuboCop
                                          'when running --auto-gen-config, except if the',
                                          'number of files with offenses is bigger than',
                                          'exclude-limit. Default is false.'],
+      max_offenses_per_cop:             ['Report at most COUNT offenses per cop across the',
+                                         'whole run, so a single noisy cop cannot bury the',
+                                         'rest. Offenses beyond the limit are not reported',
+                                         'and do not count towards the totals, the same way',
+                                         'the other display filters work.'],
       exclude_limit:                    ['Set the limit for how many files to explicitly exclude.',
                                          'If there are more files than the limit, the cop will',
                                          "be disabled instead. Default is #{MAX_EXCL}."],
       disable_uncorrectable:            ['Used with --autocorrect to annotate any',
                                          'offenses that do not support autocorrect',
                                          'with `rubocop:todo` comments.'],
+      diff:                             ['Print a unified diff of what autocorrection',
+                                         'would change, without writing any files.',
+                                         'Turns on safe autocorrection unless a mode',
+                                         'was already given with -a, -A or -x.'],
       no_exclude_limit:                 ['Do not set the limit for how many files to exclude.'],
       force_exclusion:                  ['Any files excluded by `Exclude` in configuration',
                                          'files will be excluded, even if given explicitly',
@@ -584,6 +664,10 @@ module RuboCop
       ignore_parent_exclusion:          ['Prevent from inheriting `AllCops/Exclude` from',
                                          'parent folders.'],
       ignore_unrecognized_cops:         ['Ignore unrecognized cops or departments in the config.'],
+      changed:                          ['Inspect only the files that differ from a git',
+                                         'revision, defaulting to HEAD. Untracked files',
+                                         'count as changed. Pass a revision with',
+                                         '`--changed=REVISION`.'],
       force_default_config:             ['Use default configuration even if configuration',
                                          'files are present in the directory tree.'],
       format:                           ['Choose an output formatter. This option',
@@ -598,6 +682,7 @@ module RuboCop
                                          'specified --format, or the default format',
                                          'if no format is specified.'],
       fail_level:                       ['Minimum severity for exit with error code.',
+                                         'Overrides `AllCops: FailLevel` in the configuration.',
                                          '  [A] autocorrect',
                                          '  [I] info',
                                          '  [R] refactor',
@@ -620,6 +705,10 @@ module RuboCop
                                          'default, and their configurations for the',
                                          'current directory.',
                                          'You can use `*` as a wildcard.'],
+      explain:                          ['Explain what the given cops do: their',
+                                         'description, configuration, whether they',
+                                         'correct, and the examples from their own',
+                                         'documentation.'],
       show_docs_url:                    ['Display url to documentation for the given',
                                          'cops, or base url by default.'],
       fail_fast:                        ['Inspect files in order of modification',
@@ -642,6 +731,10 @@ module RuboCop
                                          '`AllCops/DisabledByDefault` in config files.'],
       display_style_guide:              'Display style guide URLs in offense messages.',
       enable_pending_cops:              'Run with pending cops.',
+      preview:                          ['Opt in to unstable behavior: cops that are',
+                                         '`Enabled: preview`, and changes to existing',
+                                         'cops that are not the default yet.',
+                                         'Overrides `AllCops: Preview`.'],
       enable_all_cops:                  ['Run with all cops enabled, including those',
                                          'disabled by default. Overrides',
                                          '`AllCops/EnabledByDefault` and',

data/lib/rubocop/path_util.rb

@@ -44,7 +44,7 @@ module RuboCop
       uri.start_with?('http://', 'https://')
     end
 
-    SMART_PATH_CACHE = {} # rubocop:disable Style/MutableConstant
+    SMART_PATH_CACHE = {} # rubocop:disable Style/MutableConstant -- a cache, written to at runtime
     private_constant :SMART_PATH_CACHE
 
     def smart_path(path)