rubocop 1.81.7 → 1.92.1

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

@@ -7,16 +7,21 @@ module RuboCop
       # or documentation base url by default.
       # @api private
       class ShowDocsUrl < Base
+        include CopNames
+
         self.command_name = :show_docs_url
 
         def initialize(env)
           super
 
-          @config = @config_store.for(Dir.pwd)
+          @config = @config_store.for(PathUtil.pwd)
         end
 
         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,11 +29,8 @@ module RuboCop
         def print_documentation_url
           puts Cop::Documentation.default_base_url if cops_array.empty?
 
-          cops_array.each do |cop_name|
-            cop = registry_hash[cop_name]
-            next if cop.empty?
-
-            url = Cop::Documentation.url_for(cop.first, @config)
+          known_cop_classes(cops_array).each do |cop|
+            url = Cop::Documentation.url_for(cop, @config)
             puts url if url
           end
 
@@ -38,10 +40,6 @@ module RuboCop
         def cops_array
           @cops_array ||= @options[:show_docs_url]
         end
-
-        def registry_hash
-          @registry_hash ||= Cop::Registry.global.to_h
-        end
       end
     end
   end

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

@@ -60,7 +60,7 @@ module RuboCop
         def print_opt_out_instruction
           puts
           puts 'You can opt out of this message by adding the following to your config ' \
-               '(see https://docs.rubocop.org/rubocop/extensions.html#extension-suggestions ' \
+               '(see https://docs.rubocop.org/rubocop/plugins.html#plugin-suggestions ' \
                'for more options):'
           puts '  AllCops:'
           puts '    SuggestExtensions: false'

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 require safe
+      ignore_disable_comments lint max_offenses_per_cop only only_guide_cops out preview require
+      safe
       autocorrect safe_autocorrect autocorrect_all
     ].freeze
 
@@ -35,7 +36,7 @@ module RuboCop
     # @param args [Array<String>] command line arguments
     # @return [Integer] UNIX exit code
     #
-    # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+    # rubocop:disable-next Metrics/MethodLength, Metrics/AbcSize
     def run(args = ARGV)
       time_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
@@ -66,7 +67,7 @@ module RuboCop
       STATUS_INTERRUPTED
     rescue Finished
       STATUS_SUCCESS
-    rescue OptionParser::InvalidOption => e
+    rescue OptionParser::ParseError => e
       warn e.message
       warn 'For usage information, use --help'
       STATUS_ERROR
@@ -76,13 +77,14 @@ module RuboCop
       STATUS_ERROR
     ensure
       elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - time_start
-      puts "Finished in #{elapsed_time} seconds" if @options[:debug] || @options[:display_time]
+      if @options[:debug] || @options[:display_time]
+        puts "Finished in #{elapsed_time.round(5)} seconds"
+      end
     end
-    # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
 
     private
 
-    # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+    # rubocop:disable-next Metrics/MethodLength, Metrics/AbcSize
     def profile_if_needed
       return yield unless @options[:profile]
 
@@ -114,7 +116,6 @@ module RuboCop
       end
       status
     end
-    # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
 
     def require_gem(name)
       require name
@@ -165,6 +166,10 @@ module RuboCop
       handle_editor_mode
 
       @config_store.apply_options!(@options)
+      # Set cache root after apply_options! to ensure force_default_config is applied first.
+      early_cache_root = ConfigLoader.cache_root(@options[:cache_root])
+      ConfigLoader.cache_root = ResultCache.cache_root(@config_store, @options[:cache_root])
+      warn_if_cache_root_changed(early_cache_root, ConfigLoader.cache_root)
 
       handle_exiting_options
 
@@ -179,10 +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
@@ -194,17 +207,15 @@ module RuboCop
       RuboCop::LSP.enable if @options[:editor_mode]
     end
 
-    # rubocop:disable Metrics/CyclomaticComplexity
     def handle_exiting_options
       return unless Options::EXITING_OPTIONS.any? { |o| @options.key? o }
 
       run_command(:version) if @options[:version] || @options[:verbose_version]
-      run_command(:show_cops) if @options[:show_cops]
-      run_command(:show_docs_url) if @options[:show_docs_url]
-      run_command(:lsp) if @options[:lsp]
+      %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
     end
-    # rubocop:enable Metrics/CyclomaticComplexity
 
     def apply_default_formatter
       # This must be done after the options have already been processed,
@@ -223,5 +234,21 @@ module RuboCop
     def report_pending_cops
       PendingCopsReporter.warn_if_needed(@config_store.for_pwd)
     end
+
+    def warn_if_cache_root_changed(early, desired)
+      return if early == desired
+      # Normalize paths to avoid false positives from symlink resolution differences
+      if File.exist?(early) && File.exist?(desired) &&
+         File.realpath(early) == File.realpath(desired)
+        return
+      end
+
+      warn Rainbow(
+        "Warning: Remote configuration cache files were stored in `#{early}` " \
+        "because a desired cache root (`#{desired}`) was not set at the top level. " \
+        'Consider setting `AllCops: CacheRootDirectory` in your toplevel configuration file, ' \
+        'using the `RUBOCOP_CACHE_ROOT` environment variable, or using CLI options.'
+      ).yellow
+    end
   end
 end

data/lib/rubocop/comment_config/directive_range.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module RuboCop
+  class CommentConfig
+    # A disabled line range that remembers the directive comment that opened
+    # it. Value-equal to a plain `Range`, so consumers comparing or hashing
+    # ranges are unaffected.
+    # @api private
+    class DirectiveRange < Range
+      attr_reader :directive
+
+      def initialize(first_line, last_line, directive)
+        super(first_line, last_line)
+        @directive = directive
+      end
+    end
+
+    # The per-cop state accumulated while analyzing directives: the disabled
+    # ranges so far, plus the line and directive of the currently open
+    # disable, if any.
+    # @api private
+    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 if !start_line_number || line < start_line_number
+
+        line_ranges + [DirectiveRange.new(start_line_number, line, start_directive)]
+      end
+    end
+  end
+end

data/lib/rubocop/comment_config/disable_next.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module RuboCop
+  class CommentConfig
+    # 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
+      # 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
+        @detached_next_directives
+      end
+
+      # The line range of the statement a `disable-next` directive on the
+      # given line scopes to (or would scope to), or `nil` when no statement
+      # is attached. A directive is only honored on a comment-only line.
+      # Stacked directives share the target, so the computation is memoized.
+      # @api private
+      def statement_scope_after(line)
+        return nil unless comment_only_line?(line)
+
+        code_line = attached_code_line(line)
+        return nil unless code_line
+
+        (@statement_bounds ||= {})[code_line] ||= statement_bounds_at(code_line)
+      end
+
+      private
+
+      def apply_disable_next(analyses, directive)
+        bounds = statement_scope_after(directive.line_number)
+        return @detached_next_directives << directive unless bounds
+
+        range = DirectiveRange.new(bounds.begin, bounds.end, directive)
+        directive.cop_names.each do |cop_name|
+          add_next_range(analyses, qualified_cop_name(cop_name), range)
+        end
+      end
+
+      def add_next_range(analyses, cop_name, range)
+        analysis = analyses[cop_name]
+        analyses[cop_name] = CopAnalysis.new(analysis.line_ranges + [range],
+                                             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)
+          return nil if processed_source[line - 1].blank?
+        end
+
+        nil
+      end
+
+      def statement_bounds_at(line)
+        statement = statement_starting_at(line)
+        # A code line where no statement starts (e.g. a lone `end`) scopes
+        # the directive to that line alone.
+        return (line..line) unless statement
+
+        (line..statement_end_line(statement))
+      end
+
+      def statement_start_line?(node, line)
+        # Synthetic nodes (e.g. parentheses-less argument lists) have no
+        # source range. `begin` nodes are sequences of statements, not
+        # statements themselves - taking one would scope the directive to
+        # everything up to the last statement of the sequence.
+        node.source_range && node.first_line == line && !node.begin_type?
+      end
+
+      def statement_starting_at(line)
+        ast = processed_source.ast
+        return nil unless ast
+
+        ast.each_node.select { |node| statement_start_line?(node, line) }.max_by(&:last_line)
+      end
+
+      def statement_end_line(statement)
+        statement.each_node.filter_map do |node|
+          next unless node.source_range
+
+          heredoc?(node) ? node.loc.heredoc_end.line : node.last_line
+        end.max
+      end
+
+      def heredoc?(node)
+        node.respond_to?(:heredoc?) && node.heredoc?
+      end
+    end
+  end
+end

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

data/lib/rubocop/comment_config.rb

@@ -5,6 +5,8 @@ module RuboCop
   # and provides a way to check if each cop is enabled at arbitrary line.
   class CommentConfig
     extend SimpleForwardable
+    include DisableNext
+    include PushPop
 
     CONFIG_DISABLED_LINE_RANGE_MIN = -Float::INFINITY
 
@@ -25,8 +27,6 @@ module RuboCop
       end
     end
 
-    CopAnalysis = Struct.new(:line_ranges, :start_line_number)
-
     attr_reader :processed_source
 
     def_delegators :@processed_source, :config, :registry
@@ -34,14 +34,26 @@ module RuboCop
     def initialize(processed_source)
       @processed_source = processed_source
       @no_directives = !processed_source.raw_source.include?('rubocop')
+      @stack = []
+      @detached_next_directives = []
     end
 
     def cop_enabled_at_line?(cop, line_number)
+      cop_enabled_at_lines?(cop, line_number, line_number)
+    end
+
+    # Whether the cop is enabled for all of the given line span. The cop
+    # counts as disabled for the span when any of its disabled ranges
+    # overlaps it, so that a directive on any line of a multi-line offense
+    # suppresses the offense.
+    def cop_enabled_at_lines?(cop, first_line, last_line)
       cop = cop.cop_name if cop.respond_to?(:cop_name)
       disabled_line_ranges = cop_disabled_line_ranges[cop]
       return true unless disabled_line_ranges
 
-      disabled_line_ranges.none? { |range| range.include?(line_number) }
+      disabled_line_ranges.none? do |range|
+        range.end >= first_line && range.begin <= last_line
+      end
     end
 
     def cop_opted_in?(cop)
@@ -54,8 +66,8 @@ module RuboCop
 
     def extra_enabled_comments
       disable_count = Hash.new(0)
-      registry.disabled(config).each do |cop|
-        disable_count[cop.cop_name] += 1
+      registry.disabled_names(config).each do |cop_name|
+        disable_count[cop_name] += 1
       end
       extra_enabled_comments_with_names(extras: Hash.new { |h, k| h[k] = [] }, names: disable_count)
     end
@@ -64,11 +76,29 @@ module RuboCop
       non_comment_token_line_numbers.none?(line_number)
     end
 
+    # 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. 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 { |directive| cops.merge(opted_in_by(directive)) }
+        cops
+      end
+    end
+
     private
 
     def extra_enabled_comments_with_names(extras:, names:)
       each_directive do |directive|
         next unless comment_only_line?(directive.line_number)
+        next if self_closing_directive?(directive)
 
         if directive.enabled_all?
           handle_enable_all(directive, names, extras)
@@ -80,43 +110,59 @@ module RuboCop
       extras
     end
 
-    def opt_in_cops
-      @opt_in_cops ||= begin
-        cops = Set.new
-        each_directive do |directive|
-          next unless directive.enabled?
-          next if directive.all_cops?
-
-          cops.merge(directive.raw_cop_names)
-        end
-        cops
+    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
 
-    def analyze # rubocop:todo Metrics/AbcSize
+    # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+    def analyze
       return {} if @no_directives
 
       analyses = Hash.new { |hash, key| hash[key] = CopAnalysis.new([], nil) }
       inject_disabled_cops_directives(analyses)
 
       each_directive do |directive|
-        directive.cop_names.each do |cop_name|
-          cop_name = qualified_cop_name(cop_name)
-          analyses[cop_name] = analyze_cop(analyses[cop_name], directive)
+        if directive.push?
+          restore_point = analyses.transform_values(&:dup)
+          @stack.push(restore_point)
+          apply_push(analyses, resolve_push_cops(directive), directive)
+        elsif directive.pop?
+          pop_state(analyses, directive.line_number) if @stack.any?
+        elsif directive.disable_next?
+          apply_disable_next(analyses, directive)
+        elsif directive.next?
+          apply_next_directive(analyses, resolve_push_cops(directive), directive)
+        elsif directive.enable_next?
+          apply_enable_next(analyses, directive)
+        else
+          directive.cop_names.each do |cop_name|
+            cop_name = qualified_cop_name(cop_name)
+            analyses[cop_name] = analyze_cop(analyses[cop_name], directive)
+          end
         end
       end
 
       analyses.each_with_object({}) do |element, hash|
         cop_name, analysis = *element
+        next if prevent_directive_disabling?(cop_name)
+
         hash[cop_name] = cop_line_ranges(analysis)
       end
     end
 
     def inject_disabled_cops_directives(analyses)
-      registry.disabled(config).each do |cop|
-        analyses[cop.cop_name] = analyze_cop(
-          analyses[cop.cop_name],
-          DirectiveComment.new(ConfigDisabledCopDirectiveComment.new(cop.cop_name))
+      registry.disabled_names(config).each do |cop_name|
+        analyses[cop_name] = analyze_cop(
+          analyses[cop_name],
+          DirectiveComment.new(ConfigDisabledCopDirectiveComment.new(cop_name))
         )
       end
     end
@@ -136,35 +182,21 @@ module RuboCop
       return analysis unless directive.disabled?
 
       line = directive.line_number
-      start_line = analysis.start_line_number
-
-      CopAnalysis.new(analysis.line_ranges + [(line..line)], start_line)
+      range = DirectiveRange.new(line, line, directive)
+      CopAnalysis.new(analysis.line_ranges + [range], analysis.start_line_number,
+                      analysis.start_directive)
     end
 
     def analyze_disabled(analysis, directive)
-      line = directive.line_number
-      start_line = analysis.start_line_number
-
-      # Cop already disabled on this line, so we end the current disabled
-      # range before we start a new range.
-      return CopAnalysis.new(analysis.line_ranges + [start_line..line], line) if start_line
-
-      CopAnalysis.new(analysis.line_ranges, line)
+      CopAnalysis.new(analysis.close(directive.line_number), directive.line_number, directive)
     end
 
     def analyze_rest(analysis, directive)
-      line = directive.line_number
-      start_line = analysis.start_line_number
-
-      return CopAnalysis.new(analysis.line_ranges + [start_line..line], nil) if start_line
-
-      CopAnalysis.new(analysis.line_ranges, nil)
+      CopAnalysis.new(analysis.close(directive.line_number), nil)
     end
 
     def cop_line_ranges(analysis)
-      return analysis.line_ranges unless analysis.start_line_number
-
-      analysis.line_ranges + [(analysis.start_line_number..Float::INFINITY)]
+      analysis.close(Float::INFINITY)
     end
 
     def each_directive
@@ -176,8 +208,29 @@ module RuboCop
       end
     end
 
+    # Push/pop and next-statement directives close themselves, so they
+    # play no part in the disable/enable pairing.
+    def self_closing_directive?(directive)
+      directive.push? || directive.pop? || directive.disable_next? ||
+        directive.next? || directive.enable_next?
+    end
+
     def qualified_cop_name(cop_name)
-      Cop::Registry.qualified_cop_name(cop_name.strip, processed_source.file_path)
+      # A directive naming a cop under the wrong department is not honored -
+      # the mistake is surfaced by `Lint/RedundantCopDisableDirective` (with a
+      # did-you-mean hint) instead of a stderr warning that is easy to miss
+      # and disappears entirely on cached runs.
+      Cop::Registry.qualified_cop_name(cop_name.strip, processed_source.file_path,
+                                       correct_namespace: false)
+    end
+
+    # `Style/DisableCopsWithinSourceCodeDirective` cannot be disabled via
+    # directive comments when it is explicitly enabled with `Enabled: true`.
+    # This prevents users from bypassing the cop by writing a disable
+    # directive that targets this cop itself.
+    def prevent_directive_disabling?(cop_name)
+      cop_name == DirectiveComment::STYLE_DISABLE_COPS_DIRECTIVE_COP &&
+        config.dig(cop_name, 'Enabled') == true
     end
 
     def non_comment_token_line_numbers