rubocop 1.91.0 → 1.92.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1d198a5503ecb56c2ee7fc8fc0a22f1bcf5b733cb2d1d22164fc3322da20390
-  data.tar.gz: d698c0ca090ee2dd64879448b9a1e5fc9f51cc2b1816385f60e5c90f490aad99
+  metadata.gz: 82ffd9b6c03e12d770357a074e5f04f30536c85ce4afb9eff74987f03951d756
+  data.tar.gz: f9032e319d69366079bd51472893ef0e780e8405b2d3892ccde21c23deaf3fe0
 SHA512:
-  metadata.gz: f31306b39a0d1daf1606fac0c7e812f04f9d0f50dacb37a22bcd31d3d848e1e66a33c8dc317f1d536c7a96cfb90a6736aacdb6aeacbc5670f9657eab390fe534
-  data.tar.gz: d576dfbeaa9e6eb91c162b8c210054f3b5764a02bf4d8f2bcb8cc01c65441847ed287a040cb28e1e440e74d36ea77bef48c428142f8c34bd5940bc500f9c515f
+  metadata.gz: c00f0dac21282c6d8727c74ef585bab1d21f2818e29003b99e05d740ab2a142160d8cbfc9030e0654dbc6d08f83e811333d02bf41d4ea7bca3a033f03783efcc
+  data.tar.gz: 88f197ff630a6531ac0f702c46f68ccbe3d78315aa3f4ec57d0155b854d421bd0ef0abed6dcc7835cd90a869da14909ca99c606dd8d463a641c901a223dc6092

data/README.md

@@ -51,7 +51,7 @@ To prevent an unwanted RuboCop update you might want to use a conservative versi
 in your `Gemfile`:
 
 ```rb
-gem 'rubocop', '~> 1.82', require: false
+gem 'rubocop', '~> 1.92', require: false
 ```
 
 See [our versioning policy](https://docs.rubocop.org/rubocop/versioning.html) for further details.

data/config/default.yml

@@ -4144,7 +4144,7 @@ Style/DisableCopsWithinSourceCodeDirective:
                  Forbids disabling/enabling cops within source code.
   Enabled: false
   VersionAdded: '0.82'
-  VersionChanged: '1.90'
+  VersionChanged: '1.92'
   # Cop or department names. A directive is exempt only when everything it
   # disables is listed here.
   AllowedCops: []
@@ -5231,7 +5231,9 @@ Style/NegativeArrayIndex:
     Also handles range patterns with length calculations. Recognizes preserving methods
     and their combinations, allowing safe replacement when the receiver matches.
   Enabled: pending
+  Safe: false
   VersionAdded: '1.84'
+  VersionChanged: '1.92'
 
 Style/NestedFileDirname:
   Description: 'Checks for nested `File.dirname`.'

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

@@ -13,6 +13,15 @@ module RuboCop
     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
@@ -29,38 +38,51 @@ module RuboCop
       (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
+    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)
+        git('-c', 'diff.relative=false', 'diff', '--name-only', '--diff-filter=d', '-z', revision)
       )
     rescue Error
-      raise unless unborn_head?
+      raise unless revision == DEFAULT_REVISION && unborn_head?
 
-      # A repository without commits has nothing to diff against, and
-      # everything in it is untracked - which is what the caller wants to hear
-      # rather than an error about `HEAD` not resolving.
-      []
+      # 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?
-      return false unless @revision == DEFAULT_REVISION
+      !self.class.revision?(DEFAULT_REVISION)
+    end
 
-      _stdout, _stderr, status = Open3.capture3('git', 'rev-parse', '--verify', '--quiet', 'HEAD')
-      !status.success?
+    # 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
-      # `--full-name` anchors the paths to the repository root, the way the
-      # paths from `git diff` already are.
-      split_paths(git('ls-files', '--others', '--exclude-standard', '--full-name', '-z'))
+      # 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

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
 
@@ -141,7 +141,7 @@ module RuboCop
 
         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 preview require safe
+      ignore_disable_comments lint max_offenses_per_cop only only_guide_cops out preview require
+      safe
       autocorrect safe_autocorrect autocorrect_all
     ].freeze
 
@@ -210,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.rb

@@ -78,20 +78,17 @@ module RuboCop
 
     # The names of the cops that are opted in by an `enable` comment directive
     # or a `+` argument of a `push`/`next` directive, used to mobilize cops
-    # disabled in the config on demand.
+    # disabled in the config on demand. Departments are expanded for the
+    # opt-in forms only: a plain `enable` naming a department usually just
+    # closes a `disable` of it, and expanding it would switch on every
+    # config-disabled cop of the department for the rest of the file.
     #
     # @api private
     # @return [Set<String>]
     def opt_in_cops
       @opt_in_cops ||= begin
         cops = Set.new
-        each_directive do |directive|
-          if directive.enabled?
-            cops.merge(directive.raw_cop_names) unless directive.all_cops?
-          elsif directive.push? || directive.next?
-            cops.merge(directive.signed_args.fetch('+', []))
-          end
-        end
+        each_directive { |directive| cops.merge(opted_in_by(directive)) }
         cops
       end
     end
@@ -113,6 +110,18 @@ module RuboCop
       extras
     end
 
+    def opted_in_by(directive)
+      if directive.push? || directive.next?
+        directive.signed_args.fetch('+', []).flat_map { |name| expand_cop_name(name) }
+      elsif !directive.enabled? || directive.all_cops?
+        []
+      elsif directive.enable_next?
+        directive.cop_names
+      else
+        directive.raw_cop_names
+      end
+    end
+
     # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
     def analyze
       return {} if @no_directives

data/lib/rubocop/config_loader.rb

@@ -173,7 +173,8 @@ module RuboCop
         hash = ConfigLoader.load_yaml_configuration(path)
         config = Config.new(hash, path).tap(&:make_excludes_absolute)
 
-        @default_configuration = ConfigLoader.merge_with_default(config, path)
+        @default_configuration =
+          ConfigLoader.merge_with_default(config, path, resolve_preview: false)
       end
 
       # Returns the path RuboCop inferred as the root of the project. No file
@@ -189,8 +190,10 @@ module RuboCop
       end
 
       # Merges the given configuration with the default one.
-      def merge_with_default(config, config_file, unset_nil: true)
-        resolver.merge_with_default(config, config_file, unset_nil: unset_nil)
+      def merge_with_default(config, config_file, unset_nil: true, resolve_preview: true)
+        resolver.merge_with_default(
+          config, config_file, unset_nil: unset_nil, resolve_preview: resolve_preview
+        )
       end
 
       # Applies CLI overrides for `AllCops/EnabledByDefault` and

data/lib/rubocop/config_loader_resolver.rb

@@ -37,8 +37,9 @@ module RuboCop
 
     def resolve_inheritance(path, hash, file, debug) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
       inherited_files = Array(hash['inherit_from'])
-      base_configs(path, inherited_files, file)
-        .each_with_index.reverse_each do |base_config, index|
+      base_configs = base_configs(path, inherited_files, file)
+      preview = inherited_preview?(hash, base_configs)
+      base_configs.each_with_index.reverse_each do |base_config, index|
         override_department_setting_for_cops(base_config, hash)
         override_enabled_for_disabled_departments(base_config, hash)
 
@@ -50,7 +51,7 @@ module RuboCop
             v = merge(v, hash[k],
                       cop_name: k, file: file, debug: debug,
                       inherited_file: inherited_files[index],
-                      inherit_mode: determine_inherit_mode(hash, k))
+                      inherit_mode: determine_inherit_mode(hash, k, preview))
           end
           hash[k] = v
           fix_include_paths(base_config.loaded_path, hash, path, k, v) if only_base_has_include
@@ -94,8 +95,13 @@ module RuboCop
     # only cops explicitly disabled in user configuration are disabled.
     # When the `--disable-all-cops` or `--enable-all-cops` CLI option is given,
     # it takes precedence over the configuration values.
-    def merge_with_default(config, config_file, unset_nil:)
-      base_defaults = apply_preview_defaults(ConfigLoader.default_configuration, preview?(config))
+    #
+    # With `resolve_preview: false` the `Preview` sections of the default
+    # configuration are left in place and preview is treated as off. That is
+    # what extending the default configuration itself needs: preview gets
+    # applied later, when a project configuration is resolved against it.
+    def merge_with_default(config, config_file, unset_nil:, resolve_preview: true)
+      base_defaults, preview = defaults_with_preview(config, resolve_preview)
       default_configuration = base_defaults
       disabled_by_default, enabled_by_default = resolve_default_overrides(config)
 
@@ -110,7 +116,7 @@ module RuboCop
       end
       override_enabled_for_disabled_departments(default_configuration, config)
 
-      opts = { inherit_mode: inherit_mode_for_default(config), unset_nil: unset_nil }
+      opts = { inherit_mode: inherit_mode_for_default(config, preview), unset_nil: unset_nil }
       Config.new(merge(default_configuration, config, **opts), config_file)
     end
 
@@ -185,16 +191,24 @@ module RuboCop
 
     private
 
-    def inherit_mode_for_default(config)
-      with_preview_exclude_merge(config['inherit_mode'] || {}, config)
+    def defaults_with_preview(config, resolve_preview)
+      defaults = ConfigLoader.default_configuration
+      return [defaults, false] unless resolve_preview
+
+      preview = preview?(config)
+      [apply_preview_defaults(defaults, preview), preview]
+    end
+
+    def inherit_mode_for_default(config, preview)
+      with_preview_exclude_merge(config['inherit_mode'] || {}, preview)
     end
 
     # Under `Preview`, `Exclude` is merged rather than replaced, so that excluding
     # one directory does not silently drop the excludes it would have inherited -
     # from the default configuration or from a file named in `inherit_from`. An
     # explicit `inherit_mode` still wins, in either direction.
-    def with_preview_exclude_merge(mode, config)
-      return mode unless preview?(config)
+    def with_preview_exclude_merge(mode, preview)
+      return mode unless preview
       return mode if Array(mode['override']).include?('Exclude')
       return mode if Array(mode['merge']).include?('Exclude')
 
@@ -249,10 +263,21 @@ module RuboCop
         "the same parameter in #{opts[:inherited_file]}"
     end
 
-    def determine_inherit_mode(hash, key)
+    # The `AllCops: Preview` in effect once inheritance is resolved: the file
+    # itself wins, then the files it inherits from, last one first. It has to be
+    # known before merging, since the keys are merged in whatever order they
+    # appear and `AllCops` may well come after the cops whose `Exclude` it affects.
+    def inherited_preview?(hash, base_configs)
+      all_cops = [hash, *base_configs.reverse].map { |config| config['AllCops'] }.find do |params|
+        params.is_a?(Hash) && params.key?('Preview')
+      end
+      preview?('AllCops' => all_cops)
+    end
+
+    def determine_inherit_mode(hash, key, preview)
       cop_cfg = hash[key]
       local_inherit = cop_cfg['inherit_mode'] if cop_cfg.is_a?(Hash)
-      with_preview_exclude_merge(local_inherit || hash['inherit_mode'] || {}, hash)
+      with_preview_exclude_merge(local_inherit || hash['inherit_mode'] || {}, preview)
     end
 
     def should_union?(derived_hash, base_hash, root_mode, key)

data/lib/rubocop/config_obsoletion/removed_cop.rb

@@ -20,7 +20,7 @@ module RuboCop
 
         if reason
           "#{base} since #{reason.chomp}."
-        elsif alternatives
+        elsif alternatives.any?
           "#{base}. Please use #{to_sentence(alternatives, connector: 'and/or')} instead."
         else
           "#{base}."

data/lib/rubocop/config_validator.rb

@@ -173,6 +173,7 @@ module RuboCop
     def validate_all_cops_parameters
       validate_new_cops_parameter
       validate_fail_level_parameter
+      validate_preview_parameter
     end
 
     def validate_fail_level_parameter
@@ -185,6 +186,16 @@ module RuboCop
       raise ValidationError, message
     end
 
+    def validate_preview_parameter
+      preview = @config.for_all_cops['Preview']
+      return if [nil, true, false].include?(preview)
+
+      message = "invalid #{preview} for `Preview` found in #{smart_loaded_path}\n" \
+                'Valid choices are: true, false'
+
+      raise ValidationError, message
+    end
+
     def validate_all_cops_new_cops_parameter
       new_cop_parameter = @config.for_all_cops['NewCops']
       return if new_cop_parameter.nil? || NEW_COPS_VALUES.include?(new_cop_parameter)

data/lib/rubocop/cop/autocorrect_logic.rb

@@ -40,12 +40,9 @@ module RuboCop
         # allow turning off autocorrect on a cop by cop basis
         return true unless cop_config
 
-        # `false` is the same as `disabled` for backward compatibility.
-        return false if ['disabled', false].include?(cop_config['AutoCorrect'])
+        return false if disabled_autocorrect?
 
-        # When LSP is enabled or the `--editor-mode` option is on, it is considered as editing
-        # source code, and autocorrection with `AutoCorrect: contextual` will not be performed.
-        return false if contextual_autocorrect? && LSP.enabled?
+        return false if contextual_autocorrect_held_back?
 
         # :safe_autocorrect is a derived option based on several command-line
         # arguments - see RuboCop::Options#add_autocorrection_options
@@ -56,6 +53,14 @@ module RuboCop
 
       private
 
+      # When LSP is enabled or the `--editor-mode` option is on, it is considered as editing
+      # source code, and autocorrection with `AutoCorrect: contextual` will not be performed.
+      # The `editing` option says the same without the rest of LSP mode, which
+      # is about showing offenses in an editor.
+      def contextual_autocorrect_held_back?
+        contextual_autocorrect? && (LSP.enabled? || @options.fetch(:editing, false))
+      end
+
       def disable_offense(offense_range)
         unbreakable_range = multiline_ranges(offense_range)&.find do |range|
           offense_range.overlaps?(range) &&