rubocop 1.90.0 → 1.92.0

data/config/obsoletion.yml

@@ -80,6 +80,11 @@ removed:
       `Lint/BinaryOperatorWithIdenticalOperands`. Please use
       `Lint/BinaryOperatorWithIdenticalOperands` instead
   Style/BracesAroundHashParameters: true
+  Style/DoubleCopDisableDirective:
+    severity: warning
+    reason: >
+      it has been superseded by `Lint/CopDirectiveSyntax`. Please use
+      `Lint/CopDirectiveSyntax` instead
   Style/MethodMissingSuper:
     reason: >
       it has been superseded by `Lint/MissingSuper`. Please use
@@ -149,6 +154,10 @@ changed_parameters:
     parameters: IgnoreCopDirectives
     alternative: AllowCopDirectives
     severity: warning
+  - cops: Style/DisableCopsWithinSourceCodeDirective
+    parameters: AllowTrailingComment
+    alternative: AllowWithReason
+    severity: warning
   - cops:
       - Lint/BlockAlignment
       - Layout/BlockAlignment

data/lib/rubocop/cached_data.rb

@@ -35,16 +35,44 @@ module RuboCop
         cop_name: offense.cop_name,
         status:   status || offense.status
       }
-      # Only offenses suppressed by a directive can carry one, so keep the key out of the
-      # common case rather than writing a null for every cached offense.
-      hash[:justification] = offense.justification if offense.justification
+      add_justification(hash, offense)
+      add_corrections(hash, offense)
       hash
     end
 
     def message(offense)
-      # JSON.dump will fail if the offense message contains text which is not
-      # valid UTF-8
-      offense.message.dup.force_encoding(::Encoding::UTF_8).scrub
+      encode_to_utf8(offense.message)
+    end
+
+    def encode_to_utf8(value)
+      string = value.to_s
+
+      if string.encoding == ::Encoding::BINARY
+        string.dup.force_encoding(::Encoding::UTF_8).scrub
+      else
+        string.encode(::Encoding::UTF_8, invalid: :replace, undef: :replace)
+      end
+    end
+
+    # Only offenses suppressed by a directive can carry one, so keep the key out of the
+    # common case rather than writing a null for every cached offense.
+    def add_justification(hash, offense)
+      return unless offense.justification
+
+      hash[:justification] = encode_to_utf8(offense.justification)
+    end
+
+    # A corrector cannot be serialized, so the edits it would make are cached
+    # separately; without this a cache hit would report no corrections.
+    def add_corrections(hash, offense)
+      return if offense.corrections.empty?
+
+      hash[:corrections] = offense.corrections.map do |correction|
+        { begin_pos: correction.begin_pos,
+          end_pos: correction.end_pos,
+          replacement: encode_to_utf8(correction.replacement) }
+      end
+      hash[:correction_safe] = offense.correction_safe
     end
 
     # Restore an offense object loaded from a JSON file.
@@ -52,7 +80,19 @@ module RuboCop
       offenses.map! do |o|
         location = location_from_source_buffer(o)
         Cop::Offense.new(o['severity'], location, o['message'], o['cop_name'], o['status'].to_sym,
-                         justification: o['justification'])
+                         justification: o['justification'],
+                         corrections: corrections_from_cache(o),
+                         correction_safe: o.fetch('correction_safe', true))
+      end
+    end
+
+    def corrections_from_cache(offense)
+      cached = offense['corrections']
+      return [] unless cached
+
+      cached.map do |correction|
+        Cop::Offense::Correction.new(correction['begin_pos'], correction['end_pos'],
+                                     correction['replacement']).freeze
       end
     end
 

data/lib/rubocop/changed_files.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module RuboCop
+  # Lists the files that differ from a git revision, for `--changed`.
+  #
+  # Shelling out to `git` keeps RuboCop free of a version control dependency,
+  # and means the answer is exactly what git would give on the command line.
+  #
+  # @api private
+  class ChangedFiles
+    DEFAULT_REVISION = 'HEAD'
+    FILESYSTEM_ENCODING = Encoding.find('filesystem')
+
+    # Whether git can resolve `name` to a commit in the current repository.
+    def self.revision?(name)
+      _stdout, _stderr, status =
+        Open3.capture3('git', 'rev-parse', '--verify', '--quiet', "#{name}^{commit}")
+      status.success?
+    rescue Errno::ENOENT
+      false
+    end
+
+    def initialize(revision = nil)
+      @revision = revision || DEFAULT_REVISION
+    end
+
+    # Files that were added or modified since the revision, as absolute paths.
+    # Deleted files are left out - there is nothing left to inspect - and
+    # untracked files are included, since a file that is new to the working
+    # tree has changed as surely as one git already knows about.
+    #
+    # @return [Set<String>]
+    def paths
+      root = repository_root
+
+      (modified_paths + untracked_paths).to_set { |path| File.expand_path(path, root) }
+    end
+
+    # @return [Array<String>] the files among these that changed
+    def filter(files)
+      changed = paths
+      files.select { |file| changed.include?(file) }
+    end
+
+    private
+
+    def repository_root
+      filesystem_path(git('rev-parse', '--show-toplevel').b.chomp)
+    end
+
+    def modified_paths(revision = @revision)
+      # `diff.relative` would make git report paths relative to the current
+      # directory rather than to the repository root.
+      split_paths(
+        git('-c', 'diff.relative=false', 'diff', '--name-only', '--diff-filter=d', '-z', revision)
+      )
+    rescue Error
+      raise unless revision == DEFAULT_REVISION && unborn_head?
+
+      # A repository without commits has no `HEAD` to diff against, but files
+      # can already be staged in it. Against the empty tree every one of them
+      # counts as changed, which is what the caller wants to hear rather than
+      # an error about `HEAD` not resolving.
+      modified_paths(empty_tree)
+    end
+
+    def unborn_head?
+      !self.class.revision?(DEFAULT_REVISION)
+    end
+
+    # Hashed rather than hardcoded, since its id depends on the repository's
+    # object format (SHA-1 or SHA-256).
+    def empty_tree
+      git('hash-object', '-t', 'tree', '--stdin').chomp
+    end
+
+    def untracked_paths
+      # Unlike `git diff`, `ls-files` only looks under the current directory, so
+      # the `:/` pathspec widens it to the whole repository, and `--full-name`
+      # anchors the paths to the repository root the way `git diff` does.
+      split_paths(
+        git('ls-files', '--others', '--exclude-standard', '--full-name', '-z', '--', ':/')
+      )
+    end
+
+    # The `-z` above is what makes these usable: without it git wraps any path
+    # that is not plain ASCII in quotes and octal escapes, and those files drop
+    # out of the comparison without a word.
+    def split_paths(output)
+      output.b.split("\0").reject(&:empty?).map { |path| filesystem_path(path) }
+    end
+
+    # git hands back bytes, which Ruby tags with the encoding the process
+    # happens to have been started in - splitting those bytes as US-ASCII raises
+    # on any path that is not. They have to end up in the encoding `Dir.glob`
+    # uses, or a path with a non-ASCII character in it never matches the file
+    # list it is compared against.
+    #
+    # On POSIX those bytes are already the filesystem's own, so the encoding is
+    # simply corrected. Windows is the exception: git converts paths to UTF-8 on
+    # the way out, while Ruby reports file names in the local code page, so the
+    # two have to be reconciled.
+    def filesystem_path(path)
+      path = path.dup
+
+      return path.force_encoding(FILESYSTEM_ENCODING) unless Platform.windows?
+
+      path.force_encoding(Encoding::UTF_8).encode(FILESYSTEM_ENCODING)
+    rescue Encoding::UndefinedConversionError, Encoding::InvalidByteSequenceError
+      # A name the local code page cannot represent. Nothing good is left to do
+      # with it, and dropping it would be worse than reporting it as-is.
+      path.force_encoding(FILESYSTEM_ENCODING)
+    end
+
+    def git(*args)
+      stdout, stderr, status = Open3.capture3('git', *args)
+
+      raise Error, git_error_message(stderr) unless status.success?
+
+      stdout
+    rescue Errno::ENOENT
+      raise Error, '--changed requires git to be installed and on your PATH.'
+    end
+
+    def git_error_message(stderr)
+      message = stderr.strip
+      message = 'git failed with no output on standard error.' if message.empty?
+
+      "--changed could not ask git which files changed: #{message}"
+    end
+  end
+end

data/lib/rubocop/cli/command/cop_names.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RuboCop
+  class CLI
+    module Command
+      # Shared handling for commands that take a list of cop names.
+      #
+      # Validation happens here rather than during option parsing because the
+      # registry is not complete until the configuration has been loaded, which
+      # is also why `--only` and `--except` are validated from the runner.
+      # @api private
+      module CopNames
+        private
+
+        # The cops among `names` that exist, so a command can report on what it
+        # understood before {#validate_cop_names!} objects to the rest.
+        def known_cop_classes(names)
+          names.filter_map { |name| cop_class_for(name) }
+        end
+
+        # @raise [IncorrectCopNameError] if any name is not a cop
+        def validate_cop_names!(names)
+          unknown = names.reject { |name| cop_class_for(name) }
+          return if unknown.empty?
+
+          raise IncorrectCopNameError, unknown.map { |name| unknown_cop_message(name) }.join("\n")
+        end
+
+        # Not memoized: the MCP server lives long enough for a plugin to register
+        # a cop after a lookup has missed it.
+        def cop_class_for(name)
+          Cop::Registry.global.find_by_cop_name(name)
+        end
+
+        def unknown_cop_message(name)
+          return department_message(name) if department?(name)
+
+          message = "Unrecognized cop: #{name}."
+          similar = NameSimilarity.find_similar_names(name, Cop::Registry.global.names)
+          return message if similar.empty?
+
+          "#{message}\nDid you mean? #{similar.join(', ')}"
+        end
+
+        def department?(name)
+          Cop::Registry.global.departments.any? { |department| department.to_s == name }
+        end
+
+        def department_message(name)
+          example = Cop::Registry.global.names.find { |cop| cop.start_with?("#{name}/") }
+
+          "#{name} is a department, not a cop. Name one of its cops, such as #{example}."
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cli/command/execute_runner.rb

@@ -9,7 +9,7 @@ module RuboCop
         include Formatter::TextUtil
 
         # Combination of short and long formatter names.
-        INTEGRATION_FORMATTERS = %w[h html j json ju junit].freeze
+        INTEGRATION_FORMATTERS = %w[h html j json ju junit sa sarif].freeze
 
         self.command_name = :execute_runner
 
@@ -28,7 +28,16 @@ module RuboCop
             all_passed || @options[:auto_gen_config]
           end
 
-          maybe_print_corrected_source
+          if @options[:diff]
+            print_diffs(runner.diffs)
+          else
+            maybe_print_corrected_source
+          end
+
+          # A diff means autocorrectable offenses are still in the working
+          # tree, so the run has not passed even though they were "corrected"
+          # in memory.
+          all_pass_or_excluded &&= runner.diffs.empty?
 
           merge_todo_audit_status(runner_status(runner, all_pass_or_excluded))
         end
@@ -119,9 +128,20 @@ module RuboCop
           "#{Gem.loaded_specs['rubocop'].metadata['bug_tracker_uri']}\n"
         end
 
+        def print_diffs(diffs)
+          return if diffs.empty?
+          # Integration tools own stdout when they ask for a machine-readable
+          # format, so the diff would only corrupt their input.
+          return if INTEGRATION_FORMATTERS.include?(@options[:format])
+
+          output = @options[:stderr] ? $stderr : $stdout
+          output.puts
+          diffs.each { |diff| output.print(diff) }
+        end
+
         def maybe_print_corrected_source
           # Integration tools (like RubyMine) expect to have only the JSON result
-          # when specifying JSON format. Similar HTML and JUnit are targeted as well.
+          # when specifying JSON format. Similar HTML, JUnit and SARIF are targeted as well.
           # See: https://github.com/rubocop/rubocop/issues/8673
           return if INTEGRATION_FORMATTERS.include?(@options[:format])
 

data/lib/rubocop/cli/command/explain.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module RuboCop
+  class CLI
+    module Command
+      # Explains what cops do, as described by {Cop::CopExplanation}.
+      # @api private
+      class Explain < Base
+        include CopNames
+
+        self.command_name = :explain
+
+        def initialize(env)
+          super
+
+          @config = @config_store.for(PathUtil.pwd)
+        end
+
+        def run
+          names = @options[:explain]
+
+          known_cop_classes(names).each_with_index do |cop_class, index|
+            puts if index.positive?
+            puts Cop::CopExplanation.new(cop_class, @config)
+          end
+
+          # Checked after printing, so a typo in a list does not cost you the
+          # explanations you asked for alongside it.
+          validate_cop_names!(names)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cli/command/show_cops.rb

@@ -7,6 +7,8 @@ module RuboCop
       # for the current directory.
       # @api private
       class ShowCops < Base
+        include CopNames
+
         self.command_name = :show_cops
 
         ExactMatcher = Struct.new(:pattern) do
@@ -38,6 +40,10 @@ module RuboCop
 
         def run
           print_available_cops
+          # Checked after printing, so a typo alongside good names still shows
+          # what was asked for. Wildcards are patterns, not names, so a pattern
+          # that matches nothing is not an error.
+          validate_cop_names!(@options[:show_cops].grep_v(/\*/))
         end
 
         private

data/lib/rubocop/cli/command/show_docs_url.rb

@@ -7,6 +7,8 @@ module RuboCop
       # or documentation base url by default.
       # @api private
       class ShowDocsUrl < Base
+        include CopNames
+
         self.command_name = :show_docs_url
 
         def initialize(env)
@@ -17,6 +19,9 @@ module RuboCop
 
         def run
           print_documentation_url
+          # Checked after printing, so a typo alongside good names still gives
+          # you the urls you asked for.
+          validate_cop_names!(cops_array)
         end
 
         private
@@ -24,10 +29,7 @@ module RuboCop
         def print_documentation_url
           puts Cop::Documentation.default_base_url if cops_array.empty?
 
-          cops_array.each do |cop_name|
-            cop = Cop::Registry.global.find_by_cop_name(cop_name)
-            next unless cop
-
+          known_cop_classes(cops_array).each do |cop|
             url = Cop::Documentation.url_for(cop, @config)
             puts url if url
           end

data/lib/rubocop/cli.rb

@@ -13,7 +13,8 @@ module RuboCop
     DEFAULT_PARALLEL_OPTIONS = %i[
       color config debug display_style_guide display_time display_only_fail_level_offenses
       display_only_failed editor_mode except extra_details fail_level fix_layout format formatters
-      ignore_disable_comments lint only only_guide_cops out require safe
+      ignore_disable_comments lint max_offenses_per_cop only only_guide_cops out preview require
+      safe
       autocorrect safe_autocorrect autocorrect_all
     ].freeze
 
@@ -183,12 +184,18 @@ module RuboCop
 
     def set_options_to_config_loader
       ConfigLoader.debug = @options[:debug]
-      ConfigLoader.disable_pending_cops = @options[:disable_pending_cops]
-      ConfigLoader.enable_pending_cops = @options[:enable_pending_cops]
       ConfigLoader.ignore_parent_exclusion = @options[:ignore_parent_exclusion]
       ConfigLoader.ignore_unrecognized_cops = @options[:ignore_unrecognized_cops]
+      set_cop_selection_options_to_config_loader
+    end
+
+    # Options that decide which cops run, as opposed to how configuration is loaded.
+    def set_cop_selection_options_to_config_loader
+      ConfigLoader.disable_pending_cops = @options[:disable_pending_cops]
+      ConfigLoader.enable_pending_cops = @options[:enable_pending_cops]
       ConfigLoader.enabled_by_default = @options[:enable_all_cops]
       ConfigLoader.disabled_by_default = @options[:disable_all_cops]
+      ConfigLoader.preview = @options[:preview]
     end
 
     def set_options_to_pending_cops_reporter
@@ -204,7 +211,7 @@ module RuboCop
       return unless Options::EXITING_OPTIONS.any? { |o| @options.key? o }
 
       run_command(:version) if @options[:version] || @options[:verbose_version]
-      %i[show_cops list_enabled_cops_for show_docs_url lsp mcp].each do |name|
+      %i[show_cops list_enabled_cops_for show_docs_url explain lsp mcp].each do |name|
         run_command(name) if @options[name]
       end
       raise Finished

data/lib/rubocop/comment_config/directive_range.rb

@@ -22,8 +22,10 @@ module RuboCop
     CopAnalysis = Struct.new(:line_ranges, :start_line_number, :start_directive) do
       # The open range (if any) closed at the given line, appended to the
       # accumulated ranges, each remembering the directive that opened it.
+      # Closing above the opening line (e.g. a `pop` directly below a
+      # statement whose disable a `next +Cop` suspended) yields no range.
       def close(line)
-        return line_ranges unless start_line_number
+        return line_ranges if !start_line_number || line < start_line_number
 
         line_ranges + [DirectiveRange.new(start_line_number, line, start_directive)]
       end

data/lib/rubocop/comment_config/disable_next.rb

@@ -2,14 +2,15 @@
 
 module RuboCop
   class CommentConfig
-    # Handling of `disable-next` directives: computing the statement scope
-    # they apply to and tracking directives that attached to nothing.
+    # Handling of next-statement directives (`disable-next`, `todo-next` and
+    # `next`): computing the statement scope they apply to and tracking
+    # directives that attached to nothing.
     # The scope is the whole statement starting on the next line bearing
     # code. Comment-only lines between the directive and the code chain (so
     # several directives can stack), while a blank line breaks the attachment.
     # @api private
     module DisableNext
-      # `disable-next` directives that suppress nothing: nothing follows
+      # Next-statement directives that affect nothing: nothing follows
       # them, or they sit at the end of a code line.
       def detached_next_directives
         cop_disabled_line_ranges # ensure the analysis that collects them ran
@@ -48,6 +49,51 @@ module RuboCop
                                              analysis.start_line_number, analysis.start_directive)
       end
 
+      # Applies a `next` directive: `-` cops are disabled for the attached
+      # statement (exactly like `disable-next`), `+` cops have any open
+      # disable suspended for it. The `resolved_cops` come pre-expanded and
+      # qualified, mirroring `push`.
+      def apply_next_directive(analyses, resolved_cops, directive)
+        bounds = statement_scope_after(directive.line_number)
+        return @detached_next_directives << directive unless bounds
+
+        range = DirectiveRange.new(bounds.begin, bounds.end, directive)
+        resolved_cops.each do |op, cops|
+          cops.each do |cop|
+            if op == '-'
+              add_next_range(analyses, cop, range)
+            else
+              suspend_disable(analyses, cop, bounds)
+            end
+          end
+        end
+      end
+
+      # Applies an `enable-next` directive: every listed cop (departments
+      # and `all` included) has any open disable suspended for the attached
+      # statement.
+      def apply_enable_next(analyses, directive)
+        bounds = statement_scope_after(directive.line_number)
+        return @detached_next_directives << directive unless bounds
+
+        directive.cop_names.each do |cop_name|
+          suspend_disable(analyses, qualified_cop_name(cop_name), bounds)
+        end
+      end
+
+      # Punches a statement-sized hole into the currently open disable of the
+      # cop (whether opened by a directive or injected for a config-disabled
+      # cop): the open range closes just above the statement and reopens
+      # right below it, still attributed to its opening directive. Aligned
+      # with `push`, a `+` for a cop that is not disabled is a no-op.
+      def suspend_disable(analyses, cop, bounds)
+        analysis = analyses[cop]
+        return unless analysis.start_line_number
+
+        analyses[cop] = CopAnalysis.new(analysis.close(bounds.begin - 1),
+                                        bounds.end + 1, analysis.start_directive)
+      end
+
       def attached_code_line(directive_line)
         ((directive_line + 1)..processed_source.lines.size).each do |line|
           return line unless comment_only_line?(line)

data/lib/rubocop/comment_config/push_pop.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RuboCop
+  class CommentConfig
+    # Handling of `push`/`pop` directives and their signed cop arguments:
+    # saving and restoring the per-cop analysis state, and resolving the
+    # `+`/`-` argument lists (shared with the `next` directive).
+    # @api private
+    module PushPop
+      private
+
+      def resolve_push_cops(directive)
+        directive.push_args.transform_values do |names|
+          names.flat_map { |name| expand_cop_name(name) }
+        end
+      end
+
+      def expand_cop_name(name)
+        registry = Cop::Registry.global
+        cops = registry.department?(name) ? registry.names_for_department(name) : [name]
+        cops.map { |c| qualified_cop_name(c) }
+      end
+
+      def apply_push(analyses, resolved_cops, directive)
+        resolved_cops.each do |op, cops|
+          cops.each { |cop| apply_cop_op(analyses, op, cop, directive) }
+        end
+      end
+
+      def apply_cop_op(analyses, operation, cop, directive)
+        analysis = analyses[cop]
+        line = directive.line_number
+        if operation == '-' && !analysis.start_line_number
+          analyses[cop] = CopAnalysis.new(analysis.line_ranges, line, directive)
+        elsif operation == '+' && analysis.start_line_number
+          analyses[cop] = CopAnalysis.new(analysis.close(line), nil)
+        end
+      end
+
+      def pop_state(analyses, line)
+        restore_point = @stack.pop
+        (restore_point.keys | analyses.keys).each do |cop|
+          analyses[cop] = popped_analysis(analyses[cop], restore_point[cop], line)
+        end
+      end
+
+      def popped_analysis(current, restored, line)
+        ranges = current.close(line - 1)
+        return CopAnalysis.new(ranges, nil) unless restored&.start_line_number
+
+        CopAnalysis.new(ranges, line, restored.start_directive)
+      end
+    end
+  end
+end