rubocop 1.71.1 → 1.91.0

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

@@ -1,17 +1,44 @@
 # frozen_string_literal: true
 
-# rubocop:disable Lint/RedundantCopDisableDirective
+# rubocop:disable Lint/RedundantCopDisableDirective -- the examples below read as real directives
 
 module RuboCop
   module Cop
     module Style
       # Detects comments to enable/disable RuboCop.
-      # This is useful if want to make sure that every RuboCop error gets fixed
+      # This is useful if you want to make sure that every RuboCop error gets fixed
       # and not quickly disabled with a comment.
       #
       # Specific cops can be allowed with the `AllowedCops` configuration. Note that
       # if this configuration is set, `rubocop:disable all` is still disallowed.
       #
+      # `AllowedCops` and `DisallowedCops` accept cop names and department names
+      # alike. Listing a cop does not cover its whole department: a directive
+      # disabling `Metrics` is broader than one disabling `Metrics/AbcSize`.
+      #
+      # Alternatively, specific cops can be disallowed with the `DisallowedCops`
+      # configuration. When `DisallowedCops` is set, only directives for the listed
+      # cops (and `all`) will be flagged. This is useful when you want
+      # to protect a small set of critical cops from being disabled rather than
+      # allowlisting all other cops. `AllowedCops` and `DisallowedCops` should not
+      # both be set at the same time; if `DisallowedCops` is set, it takes precedence.
+      #
+      # `AllowedDirectives` names directive forms - `disable`, `todo`,
+      # `disable-next`, `todo-next`, `push`, `next` - and exempts them from the
+      # cop entirely. `rubocop:todo` is the usual candidate, since
+      # `--disable-uncorrectable` generates those and they record debt rather
+      # than a decision someone should be asked to justify.
+      #
+      # With `AllowWithReason` set to `true`, a disable directive carrying
+      # a `--` trailing justification comment is allowed, so a team can require
+      # every disable to be documented instead of banning them outright. Enable
+      # directives are not checked in this mode, since they end a suppression
+      # rather than start one.
+      #
+      # This cop cannot be disabled via directive comments when it is explicitly
+      # enabled with `Enabled: true`. This prevents users from bypassing the cop
+      # with `# rubocop:disable Style/DisableCopsWithinSourceCodeDirective`.
+      #
       # @example
       #   # bad
       #   # rubocop:disable Metrics/AbcSize
@@ -30,17 +57,54 @@ module RuboCop
       #   end
       #   # rubocop:enable Metrics/AbcSize
       #
+      # @example DisallowedCops: [Lint/Void]
+      #   # bad
+      #   # rubocop:disable Lint/Void
+      #   foo
+      #   # rubocop:enable Lint/Void
+      #
+      #   # good
+      #   # rubocop:disable Metrics/AbcSize
+      #   foo
+      #   # rubocop:enable Metrics/AbcSize
+      #
+      # @example AllowedDirectives: [todo]
+      #   # good - the cop does not look at `todo` directives at all
+      #   x = 0 # rubocop:todo Layout/SpaceAroundOperators
+      #
+      #   # bad
+      #   x = 0 # rubocop:disable Layout/SpaceAroundOperators
+      #
+      # @example AllowedCops: [Metrics]
+      #   # good - every cop the directive disables is in an exempt department
+      #   # rubocop:disable Metrics/AbcSize
+      #   def foo
+      #   end
+      #   # rubocop:enable Metrics/AbcSize
+      #
+      # @example AllowWithReason: true
+      #   # bad
+      #   x = 0 # rubocop:disable Layout/SpaceAroundOperators
+      #
+      #   # good
+      #   x = 0 # rubocop:disable Layout/SpaceAroundOperators -- would misalign the table
+      #
       class DisableCopsWithinSourceCodeDirective < Base
         extend AutoCorrector
 
         # rubocop:enable Lint/RedundantCopDisableDirective
         MSG = 'RuboCop disable/enable directives are not permitted.'
         MSG_FOR_COPS = 'RuboCop disable/enable directives for %<cops>s are not permitted.'
+        MSG_MISSING_REASON = 'RuboCop disable directives without a `--` justification ' \
+                             'comment are not permitted.'
 
         def on_new_investigation
           processed_source.comments.each do |comment|
-            directive_cops = directive_cops(comment)
-            disallowed_cops = directive_cops - allowed_cops
+            directive = DirectiveComment.new(comment)
+            next if ignored?(directive)
+
+            directive_cops = directive_cops(directive)
+            disallowed_cops = compute_disallowed_cops(directive_cops)
 
             next unless disallowed_cops.any?
 
@@ -50,14 +114,20 @@ module RuboCop
 
         private
 
-        def register_offense(comment, directive_cops, disallowed_cops)
-          message = if any_cops_allowed?
-                      format(MSG_FOR_COPS, cops: "`#{disallowed_cops.join('`, `')}`")
-                    else
-                      MSG
-                    end
+        def compute_disallowed_cops(directive_cops)
+          if disallowed_cops_config.any?
+            if directive_cops.include?('all')
+              directive_cops
+            else
+              directive_cops.uniq.select { |cop| listed?(disallowed_cops_config, cop) }
+            end
+          else
+            directive_cops.reject { |cop| cop != 'all' && listed?(allowed_cops, cop) }
+          end
+        end
 
-          add_offense(comment, message: message) do |corrector|
+        def register_offense(comment, directive_cops, disallowed_cops)
+          add_offense(comment, message: offense_message(disallowed_cops)) do |corrector|
             replacement = ''
 
             if directive_cops.length != disallowed_cops.length
@@ -69,18 +139,56 @@ module RuboCop
           end
         end
 
-        def directive_cops(comment)
-          match_captures = DirectiveComment.new(comment).match_captures
+        def offense_message(disallowed_cops)
+          if allow_with_reason?
+            MSG_MISSING_REASON
+          elsif any_cops_allowed? || disallowed_cops_config.any?
+            format(MSG_FOR_COPS, cops: "`#{disallowed_cops.join('`, `')}`")
+          else
+            MSG
+          end
+        end
+
+        def directive_cops(directive)
+          match_captures = directive.match_captures
           match_captures && match_captures[1] ? match_captures[1].split(',').map(&:strip) : []
         end
 
+        def ignored?(directive)
+          return true if exempt_mode?(directive)
+
+          allow_with_reason? && (directive.reason || directive.enabled?)
+        end
+
+        def exempt_mode?(directive)
+          allowed_directives.include?(directive.mode)
+        end
+
+        def allowed_directives
+          @allowed_directives ||= Array(cop_config['AllowedDirectives'])
+        end
+
+        def allow_with_reason?
+          cop_config['AllowWithReason']
+        end
+
         def allowed_cops
-          Array(cop_config['AllowedCops'])
+          @allowed_cops ||= Array(cop_config['AllowedCops']).to_set
+        end
+
+        # A name matches either outright or through its department, so
+        # `Metrics` covers `Metrics/AbcSize` but not the other way round.
+        def listed?(names, cop)
+          names.include?(cop) || names.include?(cop.split('/').first)
         end
 
         def any_cops_allowed?
           allowed_cops.any?
         end
+
+        def disallowed_cops_config
+          @disallowed_cops_config ||= Array(cop_config['DisallowedCops']).to_set
+        end
       end
     end
   end

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

@@ -161,7 +161,12 @@ module RuboCop
           source = source.gsub(COMMENT_REGEXP, '')
           return if source.blank?
 
-          /\s*#{Regexp.escape(source.strip)}/
+          # Treat `\#` (an escaped interpolation marker in the heredoc) as matching
+          # either `\#` or `#` in the comment, since the comment may show either
+          # the literal source form or the runtime appearance.
+          segments = source.strip.split('\\#', -1).map { |segment| Regexp.escape(segment) }
+
+          /\s*#{segments.join('\\\\?#')}/
         end
       end
     end

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

@@ -13,6 +13,11 @@ module RuboCop
       # a `#:nodoc:` comment next to it. Likewise, `#:nodoc: all` does the
       # same for all its children.
       #
+      # When `AllCops/UseProjectIndex` is enabled and the `rubydex` gem is
+      # installed, a reopened class or module is not reported when any of its
+      # other definition sites (in the same or another file) carries a
+      # documentation comment.
+      #
       # @example
       #   # bad
       #   class Person
@@ -62,19 +67,24 @@ module RuboCop
       #
       # @example AllowedConstants: ['ClassMethods']
       #
-      #    # good
-      #    module A
-      #      module ClassMethods
-      #        # ...
-      #      end
-      #    end
+      #   # good
+      #   module A
+      #     module ClassMethods
+      #       # ...
+      #     end
+      #   end
       #
       class Documentation < Base
         include DocumentationComment
+        include ProjectIndexHelp
         include RangeHelp
 
         MSG = 'Missing top-level documentation comment for `%<type>s %<identifier>s`.'
 
+        # Comments that configure tooling rather than document the code.
+        DIRECTIVE_COMMENT_REGEXP = /\A\#\s*(rubocop:|frozen_string_literal:|encoding:|
+                                            shareable_constant_value:|typed:|-\*-)/x.freeze
+
         # @!method constant_definition?(node)
         def_node_matcher :constant_definition?, '{class module casgn}'
 
@@ -109,12 +119,49 @@ module RuboCop
           return if constant_allowed?(node)
           return if nodoc_self_or_outer_module?(node)
           return if include_statement_only?(body)
+          return if documented_elsewhere?(node)
+
+          add_documentation_offense(node)
+        end
 
+        def add_documentation_offense(node)
           range = range_between(node.source_range.begin_pos, node.loc.name.end_pos)
           message = format(MSG, type: node.type, identifier: identifier(node))
           add_offense(range, message: message)
         end
 
+        # A reopened class or module is typically documented at a single
+        # definition site. When `AllCops/UseProjectIndex` is enabled, the
+        # documentation requirement is satisfied by a comment on any other
+        # definition of the same class or module.
+        def documented_elsewhere?(node)
+          return false unless project_index
+
+          declaration = resolve_constant_in_index(node.identifier)
+          return false unless declaration.is_a?(Rubydex::Namespace)
+
+          declaration.definitions.any? do |definition|
+            other_definition?(definition, node) && documenting_comments?(definition)
+          end
+        rescue StandardError
+          false
+        end
+
+        def other_definition?(definition, node)
+          location = definition.location
+          return false unless location.uri.start_with?(FILE_URI_PREFIX)
+
+          !same_file?(location.to_file_path, processed_source.file_path) ||
+            location.to_display.start_line != node.first_line
+        end
+
+        def documenting_comments?(definition)
+          definition.comments.to_a.any? do |comment|
+            text = comment.string.strip
+            !text.empty? && !DIRECTIVE_COMMENT_REGEXP.match?(text)
+          end
+        end
+
         def nodoc_self_or_outer_module?(node)
           nodoc_comment?(node) ||
             (compact_namespace?(node) && nodoc_comment?(outer_module(node).first))

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

@@ -97,14 +97,14 @@ module RuboCop
       #
       # @example AllowedMethods: ['method_missing', 'respond_to_missing?']
       #
-      #    # good
-      #    class Foo
-      #      def method_missing(name, *args)
-      #      end
+      #   # good
+      #   class Foo
+      #     def method_missing(name, *args)
+      #     end
       #
-      #      def respond_to_missing?(symbol, include_private)
-      #      end
-      #    end
+      #     def respond_to_missing?(symbol, include_private)
+      #     end
+      #   end
       #
       class DocumentationMethod < Base
         include DocumentationComment
@@ -119,6 +119,7 @@ module RuboCop
 
         def on_def(node)
           return if node.method?(:initialize)
+          return if allowed_methods.include?(node.method_name)
 
           parent = node.parent
           modifier_node?(parent) ? check(parent) : check(node)
@@ -130,7 +131,6 @@ module RuboCop
         def check(node)
           return if non_public?(node) && !require_for_non_public_methods?
           return if documentation_comment?(node)
-          return if method_allowed?(node)
 
           add_offense(node)
         end
@@ -139,10 +139,6 @@ module RuboCop
           cop_config['RequireForNonPublicMethods']
         end
 
-        def method_allowed?(node)
-          allowed_methods.include?(node.method_name)
-        end
-
         def allowed_methods
           @allowed_methods ||= cop_config.fetch('AllowedMethods', []).map(&:to_sym)
         end

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

@@ -96,20 +96,20 @@ module RuboCop
           elsif last_child.type?(:pair, :hash) || last_child.parent.array_type?
             false
           else
-            last_child.last_line <= node.last_line
+            last_child.first_line <= node.first_line
           end
         end
 
         def find_def_node_from_ascendant(node)
           return unless (parent = node.parent)
-          return parent if parent.type?(:def, :defs)
+          return parent if parent.any_def_type?
           return node.parent.child_nodes.first if define_method?(parent)
 
           find_def_node_from_ascendant(node.parent)
         end
 
         def define_method?(node)
-          return false unless node.block_type?
+          return false unless node.any_block_type?
 
           child = node.child_nodes.first
           return false unless child.send_type?

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

@@ -26,7 +26,7 @@ module RuboCop
 
         MSG = 'Use `Integer#times` for a simple loop which iterates a fixed number of times.'
 
-        def on_block(node) # rubocop:disable InternalAffairs/NumblockHandler
+        def on_block(node) # rubocop:disable InternalAffairs/NumblockHandler, InternalAffairs/ItblockHandler -- only matches blocks that take no parameters
           return unless offending?(node)
 
           send_node = node.send_node

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

@@ -40,6 +40,8 @@ module RuboCop
           end
         end
 
+        alias on_itblock on_block
+
         def on_numblock(node)
           each_with_object_numblock_candidate?(node) do |method, body|
             _, method_name, method_arg = *method
@@ -58,7 +60,7 @@ module RuboCop
 
         # @!method each_with_object_block_candidate?(node)
         def_node_matcher :each_with_object_block_candidate?, <<~PATTERN
-          (block $(call _ {:inject :reduce} _) $_ $_)
+          (block $(call _ {:inject :reduce} _) $(args _ _) $_)
         PATTERN
 
         # @!method each_with_object_numblock_candidate?(node)
@@ -71,8 +73,7 @@ module RuboCop
 
           first_arg, second_arg = *node.arguments
 
-          corrector.replace(first_arg, second_arg.source)
-          corrector.replace(second_arg, first_arg.source)
+          corrector.swap(first_arg, second_arg)
 
           if return_value_occupies_whole_line?(return_value)
             corrector.remove(whole_line_expression(return_value))

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

@@ -28,7 +28,7 @@ module RuboCop
 
         MSG = 'Omit pipes for the empty block parameters.'
 
-        def on_block(node) # rubocop:disable InternalAffairs/NumblockHandler
+        def on_block(node) # rubocop:disable InternalAffairs/NumblockHandler, InternalAffairs/ItblockHandler -- the offense is an empty `||`
           send_node = node.send_node
           check(node) unless send_node.send_type? && send_node.lambda_literal?
         end

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

@@ -40,9 +40,9 @@ module RuboCop
         extend AutoCorrector
 
         MSG = 'Do not use empty `case` condition, instead use an `if` expression.'
-        NOT_SUPPORTED_PARENT_TYPES = %i[return break next send csend].freeze
+        NOT_SUPPORTED_PARENT_TYPES = %i[return break next send csend yield super].freeze
 
-        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         def on_case(case_node)
           if case_node.condition || NOT_SUPPORTED_PARENT_TYPES.include?(case_node.parent&.type)
             return
@@ -56,7 +56,6 @@ module RuboCop
 
           add_offense(case_node.loc.keyword) { |corrector| autocorrect(corrector, case_node) }
         end
-        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
         private
 
@@ -90,7 +89,17 @@ module RuboCop
             range = range_between(conditions.first.source_range.begin_pos,
                                   conditions.last.source_range.end_pos)
 
-            corrector.replace(range, conditions.map(&:source).join(' || '))
+            corrector.replace(range, conditions.map { |c| parenthesize_condition(c) }.join(' || '))
+          end
+        end
+
+        # A condition that binds looser than `||` (e.g. a ternary, range, or
+        # assignment) must be parenthesized so the joined `||` keeps its meaning.
+        def parenthesize_condition(condition)
+          if condition.assignment? || condition.type?(:if, :and, :or, :range)
+            "(#{condition.source})"
+          else
+            condition.source
           end
         end
 

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Style
+      # Enforces consistent style for empty class definitions.
+      #
+      # This cop can enforce either a standard class definition or `Class.new`
+      # for classes with no body.
+      #
+      # The supported styles are:
+      #
+      # * class_keyword (default) - prefer standard class definition over `Class.new`
+      # * class_new - prefer `Class.new` over class definition
+      #
+      # One difference between the two styles is that the `Class.new` form does not make
+      # the subclass name available to the base class's `inherited` callback.
+      # For this reason, `EnforcedStyle: class_keyword` is set as the default style.
+      # Class definitions without a superclass, which are not involved in inheritance,
+      # are not detected. This ensures safe detection regardless of the applied style.
+      # This avoids overlapping responsibilities with the `Lint/EmptyClass` cop.
+      #
+      # Use `AllowedParentClasses` to permit both styles for specific parent classes.
+      # For example, adding `StandardError` allows both `Error = Class.new(StandardError)`
+      # and `class Error < StandardError; end` regardless of the enforced style.
+      #
+      # @example EnforcedStyle: class_keyword (default)
+      #   # bad
+      #   FooError = Class.new(StandardError)
+      #
+      #   # okish
+      #   class FooError < StandardError; end
+      #
+      #   # good
+      #   class FooError < StandardError
+      #   end
+      #
+      # @example EnforcedStyle: class_new
+      #   # bad
+      #   class FooError < StandardError
+      #   end
+      #
+      #   # bad
+      #   class FooError < StandardError; end
+      #
+      #   # good
+      #   FooError = Class.new(StandardError)
+      #
+      # @example AllowedParentClasses: ['StandardError']
+      #   # good - allowed regardless of EnforcedStyle
+      #   FooError = Class.new(StandardError)
+      #
+      #   # good - allowed regardless of EnforcedStyle
+      #   class FooError < StandardError
+      #   end
+      #
+      class EmptyClassDefinition < Base
+        include ConfigurableEnforcedStyle
+        extend AutoCorrector
+
+        MSG_CLASS_KEYWORD =
+          'Use the `class` keyword instead of `Class.new` to define an empty class.'
+        MSG_CLASS_NEW = 'Use `Class.new` instead of the `class` keyword to define an empty class.'
+
+        # @!method class_new_assignment(node)
+        def_node_matcher :class_new_assignment, <<~PATTERN
+          (casgn _ _ $(send (const _ :Class) :new _))
+        PATTERN
+
+        def on_casgn(node)
+          return unless %i[class_keyword class_definition].include?(style)
+          return unless (class_new_node = class_new_assignment(node))
+          return if (arg = class_new_node.first_argument) && !arg.const_type?
+          return if allowed_parent_class?(class_new_node.first_argument.source)
+
+          add_offense(node, message: MSG_CLASS_KEYWORD) do |corrector|
+            autocorrect_class_new(corrector, node, class_new_node)
+          end
+        end
+
+        def on_class(node)
+          return unless style == :class_new
+          return unless node.parent_class
+          return if (body = node.body) && !body.children.empty?
+          return if allowed_parent_class?(node.parent_class.source)
+
+          add_offense(node, message: MSG_CLASS_NEW) do |corrector|
+            autocorrect_class_definition(corrector, node)
+          end
+        end
+
+        private
+
+        def allowed_parent_class?(parent_class_name)
+          allowed_parent_classes.include?(parent_class_name)
+        end
+
+        def allowed_parent_classes
+          cop_config.fetch('AllowedParentClasses', [])
+        end
+
+        def autocorrect_class_new(corrector, node, class_new_node)
+          indent = ' ' * node.loc.column
+          class_name = constant_name(node)
+          parent_class_name = class_new_node.first_argument.source
+
+          corrector.replace(node, "class #{class_name} < #{parent_class_name}\n#{indent}end")
+        end
+
+        # Preserve any namespace on the assigned constant (e.g. `Foo::Bar`),
+        # which `node.name` drops.
+        def constant_name(node)
+          namespace = node.namespace
+          namespace ? "#{namespace.source}::#{node.name}" : node.name
+        end
+
+        def autocorrect_class_definition(corrector, node)
+          class_name = node.identifier.source
+          parent_class_name = node.parent_class.source
+
+          corrector.replace(node, "#{class_name} = Class.new(#{parent_class_name})")
+        end
+      end
+    end
+  end
+end

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

@@ -42,6 +42,10 @@ module RuboCop
         MSG = 'Use an empty string literal instead of heredoc.'
 
         def on_heredoc(node)
+          # A backtick heredoc (`<<~`CMD``) executes a command, so it cannot be
+          # replaced with an empty string literal.
+          return if node.xstr_type?
+
           heredoc_body = node.loc.heredoc_body
 
           return unless heredoc_body.source.empty?

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

@@ -23,7 +23,7 @@ module RuboCop
 
         MSG = 'Omit parentheses for the empty lambda parameters.'
 
-        def on_block(node) # rubocop:disable InternalAffairs/NumblockHandler
+        def on_block(node) # rubocop:disable InternalAffairs/NumblockHandler, InternalAffairs/ItblockHandler -- the offense is an empty `()`
           send_node = node.send_node
           return unless send_node.send_type?
 

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

@@ -6,6 +6,10 @@ module RuboCop
       # Checks for the use of a method, the result of which
       # would be a literal, like an empty array, hash, or string.
       #
+      # NOTE: When frozen string literals are enabled, `String.new`
+      # isn't corrected to an empty string since the former is
+      # mutable and the latter would be frozen.
+      #
       # @example
       #   # bad
       #   a = Array.new
@@ -40,13 +44,18 @@ module RuboCop
         def_node_matcher :str_node, '(send (const {nil? cbase} :String) :new)'
 
         # @!method array_with_block(node)
-        def_node_matcher :array_with_block, '(block (send (const {nil? cbase} :Array) :new) args _)'
+        def_node_matcher :array_with_block, <<~PATTERN
+          {
+            (block (send (const {nil? cbase} :Array) :new) args _)
+            ({numblock itblock} (send (const {nil? cbase} :Array) :new) ...)
+          }
+        PATTERN
 
         # @!method hash_with_block(node)
         def_node_matcher :hash_with_block, <<~PATTERN
           {
             (block (send (const {nil? cbase} :Hash) :new) args _)
-            (numblock (send (const {nil? cbase} :Hash) :new) ...)
+            ({numblock itblock} (send (const {nil? cbase} :Hash) :new) ...)
           }
         PATTERN