rubocop 1.71.1 → 1.73.1

data/lib/rubocop/cop/style/single_line_methods.rb

@@ -8,9 +8,9 @@ module RuboCop
       #
       # Endless methods added in Ruby 3.0 are also accepted by this cop.
       #
-      # If `Style/EndlessMethod` is enabled with `EnforcedStyle: allow_single_line` or
-      # `allow_always`, single-line methods will be autocorrected to endless
-      # methods if there is only one statement in the body.
+      # If `Style/EndlessMethod` is enabled with `EnforcedStyle: allow_single_line`, `allow_always`,
+      # `require_single_line`, or `require_always`, single-line methods will be autocorrected
+      # to endless methods if there is only one statement in the body.
       #
       # @example
       #   # bad

data/lib/rubocop/cop/style/string_concatenation.rb

@@ -128,7 +128,7 @@ module RuboCop
         end
 
         def uncorrectable?(part)
-          part.multiline? || heredoc?(part) || part.each_descendant(:block).any?
+          part.multiline? || heredoc?(part) || part.each_descendant(:any_block).any?
         end
 
         def heredoc?(node)

data/lib/rubocop/cop/style/trailing_comma_in_array_literal.rb

@@ -6,12 +6,13 @@ module RuboCop
       # Checks for trailing comma in array literals.
       # The configuration options are:
       #
-      # * `consistent_comma`: Requires a comma after the
-      # last item of all non-empty, multiline array literals.
-      # * `comma`: Requires a comma after last item in an array,
-      # but only when each item is on its own line.
-      # * `no_comma`: Does not require a comma after the
-      # last item in an array
+      # * `consistent_comma`: Requires a comma after the last item of all non-empty, multiline array
+      # literals.
+      # * `comma`: Requires a comma after the last item in an array, but only when each item is on
+      # its own line.
+      # * `diff_comma`: Requires a comma after the last item in an array, but only when that item is
+      # followed by an immediate newline.
+      # * `no_comma`: Does not require a comma after the last item in an array
       #
       # @example EnforcedStyleForMultiline: consistent_comma
       #   # bad
@@ -37,6 +38,14 @@ module RuboCop
       #     2,
       #   ]
       #
+      #   # bad
+      #   a = [1, 2,
+      #        3, 4]
+      #
+      #   # good
+      #   a = [1, 2,
+      #        3, 4,]
+      #
       # @example EnforcedStyleForMultiline: comma
       #   # bad
       #   a = [1, 2,]
@@ -72,6 +81,38 @@ module RuboCop
       #     2,
       #   ]
       #
+      # @example EnforcedStyleForMultiline: diff_comma
+      #   # bad
+      #   a = [1, 2,]
+      #
+      #   # good
+      #   a = [1, 2]
+      #
+      #   # good
+      #   a = [
+      #     1, 2,
+      #     3,
+      #   ]
+      #
+      #   # good
+      #   a = [
+      #     1, 2, 3,
+      #   ]
+      #
+      #   # good
+      #   a = [
+      #     1,
+      #     2,
+      #   ]
+      #
+      #   # bad
+      #   a = [1, 2,
+      #        3, 4,]
+      #
+      #   # good
+      #   a = [1, 2,
+      #        3, 4]
+      #
       # @example EnforcedStyleForMultiline: no_comma (default)
       #   # bad
       #   a = [1, 2,]

data/lib/rubocop/cop/style/trailing_comma_in_hash_literal.rb

@@ -6,12 +6,13 @@ module RuboCop
       # Checks for trailing comma in hash literals.
       # The configuration options are:
       #
-      # * `consistent_comma`: Requires a comma after the
-      # last item of all non-empty, multiline hash literals.
-      # * `comma`: Requires a comma after the last item in a hash,
-      # but only when each item is on its own line.
-      # * `no_comma`: Does not require a comma after the
-      # last item in a hash
+      # * `consistent_comma`: Requires a comma after the last item of all non-empty, multiline hash
+      # literals.
+      # * `comma`: Requires a comma after the last item in a hash, but only when each item is on its
+      # own line.
+      # * `diff_comma`: Requires a comma after the last item in a hash, but only when that item is
+      # followed by an immediate newline.
+      # * `no_comma`: Does not require a comma after the last item in a hash
       #
       # @example EnforcedStyleForMultiline: consistent_comma
       #
@@ -38,6 +39,14 @@ module RuboCop
       #     bar: 2,
       #   }
       #
+      #   # bad
+      #   a = { foo: 1, bar: 2,
+      #         baz: 3, qux: 4 }
+      #
+      #   # good
+      #   a = { foo: 1, bar: 2,
+      #         baz: 3, qux: 4, }
+      #
       # @example EnforcedStyleForMultiline: comma
       #
       #   # bad
@@ -74,6 +83,39 @@ module RuboCop
       #     bar: 2,
       #   }
       #
+      # @example EnforcedStyleForMultiline: diff_comma
+      #
+      #   # bad
+      #   a = { foo: 1, bar: 2, }
+      #
+      #   # good
+      #   a = { foo: 1, bar: 2 }
+      #
+      #   # good
+      #   a = {
+      #     foo: 1, bar: 2,
+      #     qux: 3,
+      #   }
+      #
+      #   # good
+      #   a = {
+      #     foo: 1, bar: 2, qux: 3,
+      #   }
+      #
+      #   # good
+      #   a = {
+      #     foo: 1,
+      #     bar: 2,
+      #   }
+      #
+      #   # bad
+      #   a = { foo: 1, bar: 2,
+      #         baz: 3, qux: 4, }
+      #
+      #   # good
+      #   a = { foo: 1, bar: 2,
+      #         baz: 3, qux: 4 }
+      #
       # @example EnforcedStyleForMultiline: no_comma (default)
       #
       #   # bad

data/lib/rubocop/cop/style/trivial_accessors.rb

@@ -113,7 +113,7 @@ module RuboCop
         private
 
         def in_module_or_instance_eval?(node)
-          node.each_ancestor(:block, :class, :sclass, :module).each do |pnode|
+          node.each_ancestor(:any_block, :class, :sclass, :module).each do |pnode|
             case pnode.type
             when :class, :sclass
               return false

data/lib/rubocop/cop/style/while_until_modifier.rb

@@ -24,7 +24,6 @@ module RuboCop
       #   # good
       #   x += 1 until x > 10
       #
-      # @example
       #   # bad
       #   x += 100 while x < 500 # a long comment that makes code too long if it were a single line
       #

data/lib/rubocop/cop/util.rb

@@ -32,7 +32,7 @@ module RuboCop
       end
 
       def parentheses?(node)
-        node.loc.respond_to?(:end) && node.loc.end&.is?(')')
+        node.loc_is?(:end, ')')
       end
 
       # rubocop:disable Metrics/AbcSize, Metrics/MethodLength

data/lib/rubocop/cop/utils/format_string.rb

@@ -5,15 +5,16 @@ module RuboCop
     module Utils
       # Parses {Kernel#sprintf} format strings.
       class FormatString
-        DIGIT_DOLLAR  = /(\d+)\$/.freeze
+        DIGIT_DOLLAR  = /(?<arg_number>\d+)\$/.freeze
+        INTERPOLATION = /#\{.*?\}/.freeze
         FLAG          = /[ #0+-]|#{DIGIT_DOLLAR}/.freeze
         NUMBER_ARG    = /\*#{DIGIT_DOLLAR}?/.freeze
-        NUMBER        = /\d+|#{NUMBER_ARG}/.freeze
+        NUMBER        = /\d+|#{NUMBER_ARG}|#{INTERPOLATION}/.freeze
         WIDTH         = /(?<width>#{NUMBER})/.freeze
-        PRECISION     = /\.(?<precision>#{NUMBER})/.freeze
+        PRECISION     = /\.(?<precision>#{NUMBER}?)/.freeze
         TYPE          = /(?<type>[bBdiouxXeEfgGaAcps])/.freeze
         NAME          = /<(?<name>\w+)>/.freeze
-        TEMPLATE_NAME = /\{(?<name>\w+)\}/.freeze
+        TEMPLATE_NAME = /(?<!#)\{(?<name>\w+)\}/.freeze
 
         SEQUENCE = /
             % (?<type>%)
@@ -41,7 +42,7 @@ module RuboCop
         #
         # @see https://ruby-doc.org/core-2.6.3/Kernel.html#method-i-format
         class FormatSequence
-          attr_reader :begin_pos, :end_pos, :flags, :width, :precision, :name, :type
+          attr_reader :begin_pos, :end_pos, :flags, :width, :precision, :name, :type, :arg_number
 
           def initialize(match)
             @source = match[0]
@@ -52,6 +53,7 @@ module RuboCop
             @precision = match[:precision]
             @name = match[:name]
             @type = match[:type]
+            @arg_number = match[:arg_number]
           end
 
           def percent?

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

@@ -6,6 +6,8 @@ module RuboCop
       # A Variable represents existence of a local variable.
       # This holds a variable declaration node and some states of the variable.
       class Variable
+        extend NodePattern::Macros
+
         VARIABLE_DECLARATION_TYPES = (VARIABLE_ASSIGNMENT_TYPES + ARGUMENT_DECLARATION_TYPES).freeze
 
         attr_reader :name, :declaration_node, :scope, :assignments, :references, :captured_by_block
@@ -31,11 +33,21 @@ module RuboCop
         def assign(node)
           assignment = Assignment.new(node, self)
 
-          @assignments.last&.reassigned! unless captured_by_block?
+          mark_last_as_reassigned!(assignment)
 
           @assignments << assignment
         end
 
+        def mark_last_as_reassigned!(assignment)
+          return if captured_by_block?
+          return if candidate_condition?(assignment.node.parent)
+
+          @assignments.last&.reassigned!
+        end
+
+        # @!method candidate_condition?(node)
+        def_node_matcher :candidate_condition?, '[{if case case_match when}]'
+
         def referenced?
           !@references.empty?
         end

data/lib/rubocop/cops_documentation_generator.rb

@@ -28,6 +28,12 @@ class CopsDocumentationGenerator # rubocop:disable Metrics/ClassLength
   #
   #   CopsDocumentationGenerator.new(departments: ['Lint']).call
   #
+  # For plugin extensions, specify `:plugin_name` keyword as follows:
+  #
+  #   CopsDocumentationGenerator.new(
+  #     departments: ['Performance'], plugin_name: 'rubocop-performance'
+  #   ).call
+  #
   # You can append additional information:
   #
   #   callback = ->(data) { required_rails_version(data.cop) }
@@ -36,11 +42,16 @@ class CopsDocumentationGenerator # rubocop:disable Metrics/ClassLength
   # This will insert the string returned from the lambda _after_ the section from RuboCop itself.
   # See `CopsDocumentationGenerator::STRUCTURE` for available sections.
   #
-  def initialize(departments: [], extra_info: {}, base_dir: Dir.pwd)
+  def initialize(departments: [], extra_info: {}, base_dir: Dir.pwd, plugin_name: nil)
     @departments = departments.map(&:to_sym).sort!
     @extra_info = extra_info
     @cops = RuboCop::Cop::Registry.global
     @config = RuboCop::ConfigLoader.default_configuration
+    # NOTE: For example, this prevents excessive plugin loading before another task executes,
+    # in cases where plugins are already loaded by `internal_investigation`.
+    if plugin_name && @config.loaded_plugins.none? { |plugin| plugin.about.name == plugin_name }
+      RuboCop::Plugin.integrate_plugins(RuboCop::Config.new, [plugin_name])
+    end
     @base_dir = base_dir
     @docs_path = "#{base_dir}/docs/modules/ROOT"
     FileUtils.mkdir_p("#{@docs_path}/pages")

data/lib/rubocop/directive_comment.rb

@@ -18,10 +18,24 @@ module RuboCop
     # @api private
     COPS_PATTERN = "(all|#{COP_NAMES_PATTERN})"
     # @api private
+    AVAILABLE_MODES = %w[disable enable todo].freeze
+    # @api private
+    DIRECTIVE_MARKER_PATTERN = '# rubocop : '
+    # @api private
+    DIRECTIVE_MARKER_REGEXP = Regexp.new(DIRECTIVE_MARKER_PATTERN.gsub(' ', '\s*'))
+    # @api private
+    DIRECTIVE_HEADER_PATTERN = "#{DIRECTIVE_MARKER_PATTERN}((?:#{AVAILABLE_MODES.join('|')}))\\b"
+    # @api private
     DIRECTIVE_COMMENT_REGEXP = Regexp.new(
-      "# rubocop : ((?:disable|enable|todo))\\b #{COPS_PATTERN}"
+      "#{DIRECTIVE_HEADER_PATTERN} #{COPS_PATTERN}"
         .gsub(' ', '\s*')
     )
+    # @api private
+    TRAILING_COMMENT_MARKER = '--'
+    # @api private
+    MALFORMED_DIRECTIVE_WITHOUT_COP_NAME_REGEXP = Regexp.new(
+      "\\A#{DIRECTIVE_HEADER_PATTERN}\\s*\\z".gsub(' ', '\s*')
+    )
 
     def self.before_comment(line)
       line.split(DIRECTIVE_COMMENT_REGEXP).first
@@ -32,9 +46,28 @@ module RuboCop
     def initialize(comment, cop_registry = Cop::Registry.global)
       @comment = comment
       @cop_registry = cop_registry
+      @match_data = comment.text.match(DIRECTIVE_COMMENT_REGEXP)
       @mode, @cops = match_captures
     end
 
+    # Checks if the comment starts with `# rubocop:` marker
+    def start_with_marker?
+      comment.text.start_with?(DIRECTIVE_MARKER_REGEXP)
+    end
+
+    # Checks if the comment is malformed as a `# rubocop:` directive
+    def malformed?
+      return true if !start_with_marker? || @match_data.nil?
+
+      tail = @match_data.post_match.lstrip
+      !(tail.empty? || tail.start_with?(TRAILING_COMMENT_MARKER))
+    end
+
+    # Checks if the directive comment is missing a cop name
+    def missing_cop_name?
+      MALFORMED_DIRECTIVE_WITHOUT_COP_NAME_REGEXP.match?(comment.text)
+    end
+
     # Checks if this directive relates to single line
     def single_line?
       !comment.text.start_with?(DIRECTIVE_COMMENT_REGEXP)
@@ -55,7 +88,7 @@ module RuboCop
 
     # Returns match captures to directive comment pattern
     def match_captures
-      @match_captures ||= comment.text.match(DIRECTIVE_COMMENT_REGEXP)&.captures
+      @match_captures ||= @match_data&.captures
     end
 
     # Checks if this directive disables cops

data/lib/rubocop/lsp/runtime.rb

@@ -20,6 +20,8 @@ module RuboCop
       attr_writer :safe_autocorrect, :lint_mode, :layout_mode
 
       def initialize(config_store)
+        RuboCop::LSP.enable
+
         @runner = RuboCop::Lsp::StdinRunner.new(config_store)
         @cop_registry = RuboCop::Cop::Registry.global.to_h
 

data/lib/rubocop/lsp/server.rb

@@ -22,8 +22,6 @@ module RuboCop
       def initialize(config_store)
         $PROGRAM_NAME = "rubocop --lsp #{ConfigFinder.project_root}"
 
-        RuboCop::LSP.enable
-
         @reader = LanguageServer::Protocol::Transport::Io::Reader.new($stdin)
         @writer = LanguageServer::Protocol::Transport::Io::Writer.new($stdout)
         @runtime = RuboCop::LSP::Runtime.new(config_store)

data/lib/rubocop/options.rb

@@ -243,6 +243,7 @@ module RuboCop
         option(opts, '--init')
         option(opts, '-c', '--config FILE')
         option(opts, '-d', '--debug')
+        option(opts, '--plugin FILE') { |f| plugin_feature(f) }
         option(opts, '-r', '--require FILE') { |f| require_feature(f) }
         option(opts, '--[no-]color')
         option(opts, '-v', '--version')
@@ -299,11 +300,25 @@ module RuboCop
       long_opt[2..].sub('[no-]', '').sub(/ .*/, '').tr('-', '_').gsub(/[\[\]]/, '').to_sym
     end
 
-    def require_feature(file)
-      # If any features were added on the CLI from `--require`,
+    def plugin_feature(file)
+      # If any features were added on the CLI from `--plugin`,
       # add them to the config.
-      ConfigLoader.add_loaded_features(file)
-      require file
+      ConfigLoaderResolver.new.resolve_plugins(Config.new, file)
+    end
+
+    def require_feature(file)
+      if Plugin.plugin_capable?(file)
+        # NOTE: Compatibility for before plugins style.
+        warn Rainbow(<<~MESSAGE).yellow
+          #{file} gem supports plugin, use `--plugin` instead of `--require`.
+        MESSAGE
+        plugin_feature(file)
+      else
+        # If any features were added on the CLI from `--require`,
+        # add them to the config.
+        require file
+        ConfigLoader.add_loaded_features(file)
+      end
     end
   end
 
@@ -397,7 +412,7 @@ module RuboCop
       return if @options[:format] == 'junit'
 
       raise OptionArgumentError,
-            format('--display-only-failed can only be used together with --format junit.')
+            '--display-only-failed can only be used together with --format junit.'
     end
 
     def validate_display_only_correctable_and_autocorrect
@@ -415,14 +430,13 @@ module RuboCop
                 !@options.key?(:display_only_safe_correctable)
 
       raise OptionArgumentError,
-            format('--display-only-failed cannot be used together with other display options.')
+            '--display-only-failed cannot be used together with other display options.'
     end
 
     def validate_lsp_and_editor_mode
       return if !@options.key?(:lsp) || !@options.key?(:editor_mode)
 
-      raise OptionArgumentError,
-            format('Do not specify `--editor-mode` as it is redundant in `--lsp`.')
+      raise OptionArgumentError, 'Do not specify `--editor-mode` as it is redundant in `--lsp`.'
     end
 
     def validate_autocorrect
@@ -436,7 +450,7 @@ module RuboCop
       return unless @options.key?(:disable_uncorrectable)
 
       raise OptionArgumentError,
-            format('--disable-uncorrectable can only be used together with --autocorrect.')
+            '--disable-uncorrectable can only be used together with --autocorrect.'
     end
 
     def disable_parallel_when_invalid_option_combo
@@ -504,6 +518,7 @@ module RuboCop
       only_guide_cops:                  ['Run only cops for rules that link to a',
                                          'style guide.'],
       except:                           'Exclude the given cop(s).',
+      plugin:                           'Load a RuboCop plugin.',
       require:                          'Require Ruby file.',
       config:                           'Specify configuration file.',
       auto_gen_config:                  ['Generate a configuration file acting as a',
@@ -542,8 +557,8 @@ module RuboCop
       only_recognized_file_types:       ['Inspect files given on the command line only if',
                                          'they are listed in `AllCops/Include` parameters',
                                          'of user configuration or default configuration.'],
-      ignore_disable_comments:          ['Run cops even when they are disabled locally',
-                                         'by a `rubocop:disable` directive.'],
+      ignore_disable_comments:          ['Report offenses even if they have been manually disabled',
+                                         'with a `rubocop:disable` or `rubocop:todo` directive.'],
       ignore_parent_exclusion:          ['Prevent from inheriting `AllCops/Exclude` from',
                                          'parent folders.'],
       ignore_unrecognized_cops:         ['Ignore unrecognized cops or departments in the config.'],

data/lib/rubocop/path_util.rb

@@ -28,6 +28,10 @@ module RuboCop
         end
     end
 
+    def remote_file?(uri)
+      uri.start_with?('http://', 'https://')
+    end
+
     SMART_PATH_CACHE = {} # rubocop:disable Style/MutableConstant
     private_constant :SMART_PATH_CACHE
 

data/lib/rubocop/plugin/configuration_integrator.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'lint_roller/context'
+require_relative 'not_supported_error'
+
+module RuboCop
+  module Plugin
+    # A class for integrating plugin configurations into RuboCop.
+    # Handles configuration merging, validation, and compatibility for plugins.
+    # @api private
+    class ConfigurationIntegrator
+      class << self
+        def integrate_plugins_into_rubocop_config(rubocop_config, plugins)
+          default_config = ConfigLoader.default_configuration
+          runner_context = create_context(rubocop_config)
+
+          validate_plugins!(plugins, runner_context)
+
+          plugin_config = combine_rubocop_configs(default_config, runner_context, plugins).to_h
+
+          merge_plugin_config_into_all_cops!(default_config, plugin_config)
+          merge_plugin_config_into_default_config!(default_config, plugin_config)
+        end
+
+        private
+
+        def create_context(rubocop_config)
+          LintRoller::Context.new(
+            runner: :rubocop,
+            runner_version: Version.version,
+            engine: :rubocop,
+            engine_version: Version.version,
+            target_ruby_version: rubocop_config.target_ruby_version
+          )
+        end
+
+        def validate_plugins!(plugins, runner_context)
+          unsupported_plugins = plugins.reject { |plugin| plugin.supported?(runner_context) }
+          return if unsupported_plugins.none?
+
+          raise Plugin::NotSupportedError, unsupported_plugins
+        end
+
+        def combine_rubocop_configs(default_config, runner_context, plugins)
+          fake_out_rubocop_default_configuration(default_config) do |fake_config|
+            all_cop_keys_configured_by_plugins = []
+
+            plugins.reduce(fake_config) do |combined_config, plugin|
+              RuboCop::ConfigLoader.instance_variable_set(:@default_configuration, combined_config)
+
+              print 'Plugin ' if ConfigLoader.debug
+
+              plugin_config, plugin_config_path = load_plugin_rubocop_config(plugin, runner_context)
+
+              plugin_config['AllCops'], all_cop_keys_configured_by_plugins = merge_all_cop_settings(
+                combined_config['AllCops'], plugin_config['AllCops'],
+                all_cop_keys_configured_by_plugins
+              )
+
+              plugin_config.make_excludes_absolute
+
+              ConfigLoader.merge_with_default(plugin_config, plugin_config_path)
+            end
+          end
+        end
+
+        def merge_plugin_config_into_all_cops!(rubocop_config, plugin_config)
+          rubocop_config['AllCops'].merge!(plugin_config['AllCops'])
+        end
+
+        def merge_plugin_config_into_default_config!(default_config, plugin_config)
+          plugin_config.each do |key, value|
+            default_config[key] = if default_config[key].is_a?(Hash)
+                                    resolver.merge(default_config[key], value)
+                                  else
+                                    value
+                                  end
+          end
+        end
+
+        def fake_out_rubocop_default_configuration(default_config)
+          orig_default_config = ConfigLoader.instance_variable_get(:@default_configuration)
+
+          result = yield default_config
+
+          ConfigLoader.instance_variable_set(:@default_configuration, orig_default_config)
+
+          result
+        end
+
+        # rubocop:disable Metrics/AbcSize
+        def load_plugin_rubocop_config(plugin, runner_context)
+          rules = plugin.rules(runner_context)
+
+          case rules.type
+          when :path
+            [ConfigLoader.load_file(rules.value, check: false), rules.value]
+          when :object
+            path = plugin.method(:rules).source_location[0]
+            [Config.create(rules.value, path, check: true), path]
+          when :error
+            plugin_name = plugin.about&.name || plugin.inspect
+            error_message = rules.value.respond_to?(:message) ? rules.value.message : rules.value
+
+            raise "Plugin `#{plugin_name}' failed to load with error: #{error_message}"
+          end
+        end
+        # rubocop:enable Metrics/AbcSize
+
+        # This is how we ensure "first-in wins": plugins can override AllCops settings that are
+        # set by RuboCop's default configuration, but once a plugin sets an AllCop setting, they
+        # have exclusive first-in-wins rights to that setting.
+        #
+        # The one exception to this are array fields, because we don't want to
+        # overwrite the AllCops defaults but rather munge the arrays (`existing |
+        # new`) to allow plugins to add to the array, for example Include and
+        # Exclude paths and patterns.
+        def merge_all_cop_settings(existing_all_cops, new_all_cops, already_configured_keys)
+          return [existing_all_cops, already_configured_keys] unless new_all_cops.is_a?(Hash)
+
+          combined_all_cops = existing_all_cops.dup
+          combined_configured_keys = already_configured_keys.dup
+
+          new_all_cops.each do |key, value|
+            if combined_all_cops[key].is_a?(Array) && value.is_a?(Array)
+              combined_all_cops[key] |= value
+              combined_configured_keys |= [key]
+            elsif !combined_configured_keys.include?(key)
+              combined_all_cops[key] = value
+              combined_configured_keys << key
+            end
+          end
+
+          [combined_all_cops, combined_configured_keys]
+        end
+
+        def resolver
+          @resolver ||= ConfigLoaderResolver.new
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/plugin/load_error.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Plugin
+    # An exception raised when a plugin fails to load.
+    # @api private
+    class LoadError < Error
+      def initialize(plugin_name)
+        super
+
+        @plugin_name = plugin_name
+      end
+
+      def message
+        <<~MESSAGE
+          Failed to load plugin `#{@plugin_name}` because the corresponding plugin class could not be determined for instantiation.
+          Try upgrading it first (e.g., `bundle update #{@plugin_name}`).
+          If `#{@plugin_name}` is not yet a plugin, use `require: #{@plugin_name}` instead of `plugins: #{@plugin_name}` in your configuration.
+
+          For further assistance, check with the developer regarding the following points:
+          https://docs.rubocop.org/rubocop/plugin_migration_guide.html
+        MESSAGE
+      end
+    end
+  end
+end