rubocop 1.84.2 → 1.88.1

data/lib/rubocop/formatter/disabled_config_formatter.rb

@@ -91,12 +91,9 @@ module RuboCop
         command = 'rubocop --auto-gen-config'
 
         command += ' --auto-gen-only-exclude' if @options[:auto_gen_only_exclude]
-
-        if no_exclude_limit?
-          command += ' --no-exclude-limit'
-        elsif @exclude_limit_option
-          command += format(' --exclude-limit %<limit>d', limit: Integer(@exclude_limit_option))
-        end
+        command += ' --disable-pending-cops' if @options[:disable_pending_cops]
+        command += ' --enable-pending-cops' if @options[:enable_pending_cops]
+        command += exclude_limit_option
         command += ' --no-offense-counts' unless show_offense_counts?
 
         command += ' --no-auto-gen-timestamp' unless show_timestamp?
@@ -106,6 +103,16 @@ module RuboCop
         command
       end
 
+      def exclude_limit_option
+        if no_exclude_limit?
+          ' --no-exclude-limit'
+        elsif @exclude_limit_option
+          format(' --exclude-limit %<limit>d', limit: Integer(@exclude_limit_option))
+        else
+          ''
+        end
+      end
+
       def timestamp
         show_timestamp? ? "on #{Time.now.utc} " : ''
       end
@@ -131,6 +138,9 @@ module RuboCop
       end
 
       def set_max(cfg, cop_name)
+        exclude_limits = RuboCop::ExcludeLimit.read_limits(cop_name)
+        cfg[:exclude_limit] = exclude_limits unless exclude_limits.empty?
+
         return unless cfg[:exclude_limit]
 
         cfg.merge!(cfg[:exclude_limit]) if should_set_max?(cop_name)
@@ -155,7 +165,7 @@ module RuboCop
         output_buffer.puts "# Offense count: #{offense_count}" if show_offense_counts?
 
         cop_class = Cop::Registry.global.find_by_cop_name(cop_name)
-        default_cfg = default_config(cop_name)
+        default_cfg = default_config(cop_name) || @config_for_pwd[cop_name]
 
         if supports_safe_autocorrect?(cop_class, default_cfg)
           output_buffer.puts '# This cop supports safe autocorrection (--autocorrect).'
@@ -192,7 +202,7 @@ module RuboCop
           next unless value.is_a?(Array)
           next if value.empty?
 
-          value.map! { |v| v.nil? ? '~' : v } # Change nil back to ~ as in the YAML file.
+          value = value.map { |v| v.nil? ? '~' : v } # Change nil back to ~ as in the YAML file.
           output_buffer.puts "# #{param}: #{value.uniq.join(', ')}"
         end
       end
@@ -233,7 +243,7 @@ module RuboCop
 
       def output_exclude_list(output_buffer, offending_files, cop_name)
         require 'pathname'
-        parent = Pathname.new(Dir.pwd)
+        parent = Pathname.new(PathUtil.pwd)
 
         output_buffer.puts '  Exclude:'
         excludes(offending_files, cop_name, parent).each do |exclude_path|

data/lib/rubocop/formatter/formatter_set.rb

@@ -57,7 +57,7 @@ module RuboCop
         if output_path
           dir_path = File.dirname(output_path)
           FileUtils.mkdir_p(dir_path)
-          output = File.open(output_path, 'w')
+          output = File.open(output_path, 'w') # rubocop:disable Style/FileOpen
         else
           output = $stdout
         end

data/lib/rubocop/formatter/junit_formatter.rb

@@ -93,7 +93,7 @@ module RuboCop
 
       def classname_attribute_value(file)
         @classname_attribute_value_cache ||= Hash.new do |hash, key|
-          hash[key] = key.delete_suffix('.rb').gsub("#{Dir.pwd}/", '').tr('/', '.')
+          hash[key] = key.delete_suffix('.rb').gsub("#{PathUtil.pwd}/", '').tr('/', '.')
         end
         @classname_attribute_value_cache[file]
       end

data/lib/rubocop/formatter/simple_text_formatter.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative 'colorizable'
-
 module RuboCop
   module Formatter
     # A basic formatter that displays only files with offenses.

data/lib/rubocop/formatter/worst_offenders_formatter.rb

@@ -24,7 +24,7 @@ module RuboCop
       def file_finished(file, offenses)
         return if offenses.empty?
 
-        path = Pathname.new(file).relative_path_from(Pathname.new(Dir.pwd))
+        path = Pathname.new(file).relative_path_from(Pathname.new(PathUtil.pwd))
         @offense_counts[path] = offenses.size
       end
 

data/lib/rubocop/formatter.rb

@@ -3,32 +3,33 @@
 module RuboCop
   # The bootstrap module for formatter.
   module Formatter
-    require_relative 'formatter/text_util'
+    autoload :Colorizable, 'rubocop/formatter/colorizable'
+    autoload :TextUtil, 'rubocop/formatter/text_util'
 
-    require_relative 'formatter/base_formatter'
-    require_relative 'formatter/simple_text_formatter'
+    autoload :BaseFormatter, 'rubocop/formatter/base_formatter'
+    autoload :SimpleTextFormatter, 'rubocop/formatter/simple_text_formatter'
 
     # relies on simple text
-    require_relative 'formatter/clang_style_formatter'
-    require_relative 'formatter/disabled_config_formatter'
-    require_relative 'formatter/emacs_style_formatter'
-    require_relative 'formatter/file_list_formatter'
-    require_relative 'formatter/fuubar_style_formatter'
-    require_relative 'formatter/github_actions_formatter'
-    require_relative 'formatter/html_formatter'
-    require_relative 'formatter/json_formatter'
-    require_relative 'formatter/junit_formatter'
-    require_relative 'formatter/markdown_formatter'
-    require_relative 'formatter/offense_count_formatter'
-    require_relative 'formatter/pacman_formatter'
-    require_relative 'formatter/progress_formatter'
-    require_relative 'formatter/quiet_formatter'
-    require_relative 'formatter/tap_formatter'
-    require_relative 'formatter/worst_offenders_formatter'
+    autoload :ClangStyleFormatter, 'rubocop/formatter/clang_style_formatter'
+    autoload :DisabledConfigFormatter, 'rubocop/formatter/disabled_config_formatter'
+    autoload :EmacsStyleFormatter, 'rubocop/formatter/emacs_style_formatter'
+    autoload :FileListFormatter, 'rubocop/formatter/file_list_formatter'
+    autoload :FuubarStyleFormatter, 'rubocop/formatter/fuubar_style_formatter'
+    autoload :GitHubActionsFormatter, 'rubocop/formatter/github_actions_formatter'
+    autoload :HTMLFormatter, 'rubocop/formatter/html_formatter'
+    autoload :JSONFormatter, 'rubocop/formatter/json_formatter'
+    autoload :JUnitFormatter, 'rubocop/formatter/junit_formatter'
+    autoload :MarkdownFormatter, 'rubocop/formatter/markdown_formatter'
+    autoload :OffenseCountFormatter, 'rubocop/formatter/offense_count_formatter'
+    autoload :PacmanFormatter, 'rubocop/formatter/pacman_formatter'
+    autoload :ProgressFormatter, 'rubocop/formatter/progress_formatter'
+    autoload :QuietFormatter, 'rubocop/formatter/quiet_formatter'
+    autoload :TapFormatter, 'rubocop/formatter/tap_formatter'
+    autoload :WorstOffendersFormatter, 'rubocop/formatter/worst_offenders_formatter'
 
     # relies on progress formatter
-    require_relative 'formatter/auto_gen_config_formatter'
+    autoload :AutoGenConfigFormatter, 'rubocop/formatter/auto_gen_config_formatter'
 
-    require_relative 'formatter/formatter_set'
+    autoload :FormatterSet, 'rubocop/formatter/formatter_set'
   end
 end

data/lib/rubocop/lsp/diagnostic.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'language_server-protocol'
 require_relative 'disable_comment_edits'
 require_relative 'severity'
 

data/lib/rubocop/lsp/routes.rb

@@ -61,9 +61,16 @@ module RuboCop
 
       handle 'initialized' do |_request|
         version = RuboCop::Version::STRING
-        yjit = Object.const_defined?('RubyVM::YJIT') && RubyVM::YJIT.enabled? ? ' +YJIT' : ''
-
-        Logger.log("RuboCop #{version} language server#{yjit} initialized, PID #{Process.pid}")
+        # Only one JIT can be enabled at the same time, since YJIT and ZJIT are mutually exclusive.
+        jit = if Object.const_defined?('RubyVM::YJIT') && RubyVM::YJIT.enabled?
+                '+YJIT'
+              elsif Object.const_defined?('RubyVM::ZJIT') && RubyVM::ZJIT.enabled?
+                '+ZJIT'
+              else
+                ''
+              end
+
+        Logger.log("RuboCop #{version} language server#{jit} initialized, PID #{Process.pid}")
       end
 
       handle 'shutdown' do |request|

data/lib/rubocop/lsp/runtime.rb

@@ -23,7 +23,6 @@ module RuboCop
         RuboCop::LSP.enable
 
         @runner = RuboCop::Lsp::StdinRunner.new(config_store)
-        @cop_registry = RuboCop::Cop::Registry.global.to_h
 
         @safe_autocorrect = true
         @lint_mode = false
@@ -63,7 +62,7 @@ module RuboCop
           document_encoding,
           offense,
           path,
-          @cop_registry[offense.cop_name]&.first,
+          RuboCop::Cop::Registry.global.find_by_cop_name(offense.cop_name),
           processed_source
         ).to_lsp_diagnostic(config)
       end

data/lib/rubocop/mcp/server.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+begin
+  require 'mcp'
+
+  required_mcp_version = '0.6.0'
+
+  if Gem::Version.new(required_mcp_version) > Gem::Version.new(MCP::VERSION)
+    # While `mcp` is not a runtime dependency, users may have an outdated version installed.
+    warn <<~MESSAGE
+      Error: `mcp` gem version #{MCP::VERSION} was loaded, but `rubocop --mcp` requires #{required_mcp_version}.
+      - If you're using Bundler and don't yet have `gem 'mcp'` as a dependency, add it now.
+      - If you're using Bundler and already have `gem 'mcp'` as a dependency, update it to the most recent version.
+      - If you don't use Bundler, run `gem update mcp`.
+    MESSAGE
+    exit!
+  end
+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`.
+  MESSAGE
+
+  exit!
+end
+
+require_relative '../lsp'
+require_relative '../lsp/runtime'
+
+module RuboCop
+  module MCP
+    # RuboCop MCP Server.
+    # @api private
+    class Server
+      def initialize(config_store)
+        @config_store = config_store
+        @runtime = RuboCop::LSP::Runtime.new(@config_store)
+        @options = {}
+      end
+
+      def start
+        # No `protocol_version` is specified because draft feature by default can be used.
+        server = ::MCP::Server.new(
+          name: 'rubocop_mcp_server',
+          version: RuboCop::Version::STRING,
+          tools: [inspection_tool, autocorrection_tool]
+        )
+
+        ::MCP::Server::Transports::StdioTransport.new(server).open
+      end
+
+      private
+
+      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.',
+          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)
+        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.',
+          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)
+        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 }
+          end
+        end
+      end
+
+      def run_autocorrection(path, source_code, safety)
+        command = safety ? 'rubocop.formatAutocorrects' : 'rubocop.formatAutocorrectsAll'
+
+        if source_code
+          @runtime.format(path || 'example.rb', source_code, command: command).tap do |corrected|
+            write_file(path, corrected) if path
+          end
+        else
+          process_files(path) do |file, source|
+            @runtime.format(file, source, command: command).then do |corrected|
+              write_file(file, corrected)
+
+              { path: PathUtil.relative_path(file), corrected: source != corrected }
+            end
+          end
+        end
+      end
+
+      def process_files(path, filter_empty: false)
+        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
+
+        { files: files, summary: build_summary(target_files, all_files) }.to_json
+      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}"
+      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}"
+      end
+
+      # NOTE: It is useful for RuboCop's result summary to be shown in the LLM's responses
+      # during interactions, so the summary is returned in a form that is easy for the LLM
+      # 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
+      end
+
+      # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
+      def build_tool(
+        name:, description:,
+        title:, destructive_hint:, idempotent_hint:, read_only_hint:, safety_required:
+      )
+        if safety_required
+          safety_property = { safety: { type: 'boolean' } }
+          required = ['safety']
+        else
+          safety_property = {}
+          required = nil
+        end
+
+        ::MCP::Tool.define(
+          name: name,
+          description: description,
+          input_schema: {
+            properties: {
+              path: { type: 'string' },
+              source_code: { type: 'string' }
+            }.merge(safety_property),
+            required: required
+          }.compact,
+          annotations: {
+            title: title,
+            destructive_hint: destructive_hint,
+            idempotent_hint: idempotent_hint,
+            open_world_hint: false,
+            read_only_hint: read_only_hint
+          }
+        ) do |path: nil, source_code: nil, safety: true|
+          result = yield(path, source_code, safety)
+
+          ::MCP::Tool::Response.new([{ type: 'text', text: result }])
+        rescue RuboCop::Error => e
+          ::MCP::Tool::Response.new([{ type: 'text', text: e.message }], error: true)
+        end
+      end
+      # rubocop:enable Metrics/MethodLength, Metrics/ParameterLists
+    end
+  end
+end

data/lib/rubocop/options.rb

@@ -16,7 +16,9 @@ module RuboCop
                       'root of the project. RuboCop will use this path to determine which ' \
                       '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 show_docs_url lsp].freeze
+    EXITING_OPTIONS = %i[
+      version verbose_version show_cops list_enabled_cops_for show_docs_url lsp mcp
+    ].freeze
     DEFAULT_MAXIMUM_EXCLUSION_ITEMS = 15
 
     def initialize
@@ -57,6 +59,7 @@ module RuboCop
         add_check_options(opts)
         add_cache_options(opts)
         add_lsp_option(opts)
+        add_mcp_option(opts)
         add_server_options(opts)
         add_output_options(opts)
         add_autocorrection_options(opts)
@@ -88,6 +91,8 @@ module RuboCop
         option(opts, '-F', '--fail-fast')
         option(opts, '--disable-pending-cops')
         option(opts, '--enable-pending-cops')
+        option(opts, '--disable-all-cops')
+        option(opts, '--enable-all-cops')
         option(opts, '--ignore-disable-comments')
         option(opts, '--force-exclusion')
         option(opts, '--only-recognized-file-types')
@@ -215,6 +220,12 @@ module RuboCop
       end
     end
 
+    def add_mcp_option(opts)
+      section(opts, 'MCP Option') do
+        option(opts, '--mcp')
+      end
+    end
+
     def add_server_options(opts)
       section(opts, 'Server Options') do
         option(opts, '--[no-]server')
@@ -229,6 +240,7 @@ module RuboCop
     def add_additional_modes(opts)
       section(opts, 'Additional Modes') do
         option(opts, '-L', '--list-target-files')
+        option(opts, '--list-enabled-cops-for PATH')
         option(opts, '--show-cops [COP1,COP2,...]') do |list|
           @options[:show_cops] = list.nil? ? [] : list.split(',')
         end
@@ -386,6 +398,7 @@ module RuboCop
       validate_display_only_failed_and_display_only_correctable
       validate_display_only_correctable_and_autocorrect
       validate_lsp_and_editor_mode
+      validate_enable_all_cops_and_disable_all_cops
       disable_parallel_when_invalid_option_combo
 
       return if incompatible_options.size <= 1
@@ -439,6 +452,13 @@ module RuboCop
       raise OptionArgumentError, 'Do not specify `--editor-mode` as it is redundant in `--lsp`.'
     end
 
+    def validate_enable_all_cops_and_disable_all_cops
+      return if !@options.key?(:enable_all_cops) || !@options.key?(:disable_all_cops)
+
+      raise OptionArgumentError,
+            '--enable-all-cops cannot be used together with --disable-all-cops.'
+    end
+
     def validate_autocorrect
       if @options.key?(:safe_autocorrect) && @options.key?(:autocorrect_all)
         message = Rainbow(<<~MESSAGE).red
@@ -467,8 +487,7 @@ module RuboCop
     end
 
     def invalid_arguments_for_parallel
-      [('--auto-gen-config' if @options.key?(:auto_gen_config)),
-       ('-F/--fail-fast'    if @options.key?(:fail_fast)),
+      [('-F/--fail-fast'    if @options.key?(:fail_fast)),
        ('--profile'         if @options[:profile]),
        ('--memory'          if @options[:memory]),
        ('--cache false'     if @options > { cache: 'false' })].compact
@@ -592,7 +611,7 @@ module RuboCop
       display_only_correctable:         ['Only output correctable offense messages.'],
       display_only_safe_correctable:    ['Only output safe-correctable offense messages',
                                          'when combined with --display-only-correctable.'],
-      show_cops:                        ['Shows the given cops, or all cops by',
+      show_cops:                        ['Show the given cops, or all cops by',
                                          'default, and their configurations for the',
                                          'current directory.',
                                          'You can use `*` as a wildcard.'],
@@ -612,8 +631,16 @@ module RuboCop
       display_cop_names:                ['Display cop names in offense messages.',
                                          'Default is true.'],
       disable_pending_cops:             'Run without pending cops.',
+      disable_all_cops:                 ['Run with all cops disabled by default,',
+                                         'except `Lint/Syntax`. Overrides',
+                                         '`AllCops/EnabledByDefault` and',
+                                         '`AllCops/DisabledByDefault` in config files.'],
       display_style_guide:              'Display style guide URLs in offense messages.',
       enable_pending_cops:              'Run with pending cops.',
+      enable_all_cops:                  ['Run with all cops enabled, including those',
+                                         'disabled by default. Overrides',
+                                         '`AllCops/EnabledByDefault` and',
+                                         '`AllCops/DisabledByDefault` in config files.'],
       extra_details:                    'Display extra details in offense messages.',
       lint:                             'Run only lint cops.',
       safe:                             'Run only safe cops.',
@@ -621,6 +648,8 @@ module RuboCop
                                          'autocorrected source. This is especially useful',
                                          'when combined with --autocorrect and --stdin.'],
       list_target_files:                'List all files RuboCop will inspect.',
+      list_enabled_cops_for:            ['List which cops will inspect a given file or',
+                                         'directory.'],
       autocorrect:                      'Autocorrect offenses (only when it\'s safe).',
       auto_correct:                     '(same, deprecated)',
       safe_auto_correct:                '(same, deprecated)',
@@ -651,6 +680,8 @@ module RuboCop
       server_status:                    'Show server status.',
       no_detach:                        'Run the server process in the foreground.',
       lsp:                              'Start a language server listening on STDIN.',
+      mcp:                              ['Start an MCP (Model Context Protocol) server that',
+                                         'communicates over stdio.'],
       raise_cop_error:                  ['Raise cop-related errors with cause and location.',
                                          'This is used to prevent cops from failing silently.',
                                          'Default is false.'],

data/lib/rubocop/path_util.rb

@@ -10,7 +10,19 @@ module RuboCop
 
     module_function
 
-    def relative_path(path, base_dir = Dir.pwd)
+    # Returns the current working directory, cached for the duration of a run.
+    # Dir.pwd is a syscall; caching it avoids repeated overhead since RuboCop
+    # never changes the working directory during a run.
+    def pwd
+      @pwd ||= Dir.pwd
+    end
+
+    # Reset the cached pwd. Only needed in tests that use Dir.chdir.
+    def reset_pwd
+      @pwd = nil
+    end
+
+    def relative_path(path, base_dir = PathUtil.pwd)
       PathUtil.relative_paths_cache[base_dir][path] ||=
         # Optimization for the common case where path begins with the base
         # dir. Just cut off the first part.
@@ -41,7 +53,7 @@ module RuboCop
           path.uri.to_s
         else
           # Ideally, we calculate this relative to the project root.
-          base_dir = Dir.pwd
+          base_dir = PathUtil.pwd
 
           if path.start_with? base_dir
             relative_path(path, base_dir)

data/lib/rubocop/plugin/loader.rb

@@ -84,7 +84,7 @@ module RuboCop
         end
 
         def require_plugin(require_path)
-          FeatureLoader.load(config_directory_path: Dir.pwd, feature: require_path)
+          FeatureLoader.load(config_directory_path: PathUtil.pwd, feature: require_path)
         end
 
         def constantize_plugin_from_gemspec_metadata(plugin_name)

data/lib/rubocop/project_index_loader.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module RuboCop
+  # Defensive loader for the optional `rubydex` gem.
+  #
+  # When `AllCops/UseProjectIndex` is enabled in the user's configuration, RuboCop builds
+  # a project-wide index using `Rubydex::Graph` and exposes it to cops that opt in.
+  # The gem is intentionally not a runtime dependency; if it is not installed,
+  # or if the running Ruby is older than what `rubydex` supports, RuboCop falls back to
+  # its standard file-local behavior.
+  module ProjectIndexLoader
+    MINIMUM_RUBY_VERSION = '3.2'
+
+    module_function
+
+    # Returns whether the `rubydex` gem can be loaded. The result is memoized
+    # for the lifetime of the process.
+    def available?
+      return @available if defined?(@available)
+
+      @available = supported_ruby? && try_require
+    end
+
+    def supported_ruby?
+      RUBY_VERSION >= MINIMUM_RUBY_VERSION
+    end
+
+    def warn_unavailable
+      return if @warned
+
+      @warned = true
+
+      if supported_ruby?
+        warn Rainbow(<<~MSG).yellow
+          `AllCops/UseProjectIndex` is enabled but the `rubydex` gem is not installed.
+          Analyses that use the project index will be skipped. Add `gem 'rubydex'` to your Gemfile.
+        MSG
+      else
+        warn Rainbow(<<~MSG).yellow
+          `AllCops/UseProjectIndex` is enabled but `rubydex` requires Ruby #{MINIMUM_RUBY_VERSION} or later (current: #{RUBY_VERSION}).
+          Analyses that use the project index will be skipped.
+        MSG
+      end
+    end
+
+    def try_require
+      require 'rubydex'
+      true
+    rescue LoadError
+      false
+    end
+
+    # Builds and resolves a `Rubydex::Graph` for the given file paths. Returns the resolved graph,
+    # or `nil` if the build fails. This is the only place in RuboCop that depends on the concrete
+    # `Rubydex::Graph` API, so callers (e.g. `Runner`) do not need to know which Rubydex classes
+    # or methods are involved.
+    def build_index(paths)
+      graph = Rubydex::Graph.new
+      graph.index_all(paths.map(&:to_s))
+      graph.resolve
+      graph
+    rescue StandardError => e
+      warn Rainbow("rubydex index build failed: #{e.message}. Continuing without it.").yellow
+    end
+  end
+end