rubocop 1.71.1 → 1.92.0

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

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Style
+      # Checks for directive scopes that can be expressed with the tighter
+      # next-statement forms: a `disable`/`enable` pair, an
+      # `enable`/`disable` pair, or a `push`/`pop` with signed arguments
+      # wrapping exactly one statement. A statement-scoped directive cannot
+      # drift as the surrounding code changes and needs no closing boundary.
+      #
+      # @safety
+      #   The autocorrection is unsafe because the suppression scope shrinks
+      #   from the whole region to the statement: offenses of the suppressed
+      #   cops located on the directive lines themselves resurface.
+      #
+      # @example
+      #   # bad
+      #   # rubocop:disable Metrics/AbcSize
+      #   def foo
+      #   end
+      #   # rubocop:enable Metrics/AbcSize
+      #
+      #   # good
+      #   # rubocop:disable-next Metrics/AbcSize
+      #   def foo
+      #   end
+      #
+      #   # bad
+      #   # rubocop:push -Metrics/AbcSize
+      #   def foo
+      #   end
+      #   # rubocop:pop
+      #
+      #   # good
+      #   # rubocop:disable-next Metrics/AbcSize
+      #   def foo
+      #   end
+      #
+      #   # bad
+      #   # rubocop:disable Metrics/AbcSize
+      #   # rubocop:push +Metrics/AbcSize
+      #   def foo
+      #   end
+      #   # rubocop:pop
+      #   # rubocop:enable Metrics/AbcSize
+      #
+      #   # good
+      #   # rubocop:disable Metrics/AbcSize
+      #   # rubocop:enable-next Metrics/AbcSize
+      #   def foo
+      #   end
+      #   # rubocop:enable Metrics/AbcSize
+      #
+      #   # good - the region spans more than one statement
+      #   # rubocop:disable Metrics/AbcSize
+      #   def foo
+      #   end
+      #
+      #   def bar
+      #   end
+      #   # rubocop:enable Metrics/AbcSize
+      #
+      class DirectiveScope < Base
+        include RangeHelp
+        extend AutoCorrector
+
+        MSG_PAIR = 'Use `%<mode>s-next` instead of a `%<mode>s`/`enable` pair ' \
+                   'around a single statement.'
+        MSG_ENABLE_PAIR = 'Use `enable-next` instead of an `enable`/`disable` pair ' \
+                          'around a single statement.'
+        MSG_PUSH_POP = 'Use `%<replacement>s` instead of `push`/`pop` around a single statement.'
+
+        def on_new_investigation
+          processed_source.comments.each do |comment|
+            directive = DirectiveComment.new(comment)
+            next unless comment_config.comment_only_line?(directive.line_number)
+
+            if plain_disable?(directive)
+              check_pair(directive)
+            elsif signed_push?(directive)
+              check_push_pop(directive)
+            elsif plain_enable?(directive)
+              check_enable_pair(directive)
+            end
+          end
+        end
+
+        private
+
+        def comment_config
+          processed_source.comment_config
+        end
+
+        def plain_disable?(directive)
+          directive.disabled? && !directive.disable_next?
+        end
+
+        def plain_enable?(directive)
+          directive.enabled? && !directive.enable_next? && !directive.all_cops?
+        end
+
+        def signed_push?(directive)
+          directive.push? && !directive.signed_args.empty?
+        end
+
+        def check_pair(directive)
+          enable = single_statement_closing_directive(directive)
+          return unless enable&.enabled?
+          return unless enable.raw_cop_names.sort == directive.raw_cop_names.sort
+
+          message = format(MSG_PAIR, mode: directive.mode)
+          add_offense(directive.comment, message: message) do |corrector|
+            convert_pair(corrector, directive, enable)
+          end
+        end
+
+        def convert_pair(corrector, directive, enable)
+          replacement = directive.comment.text.sub(/\b#{directive.mode}\b/,
+                                                   "#{directive.mode}-next")
+          corrector.replace(directive.comment, replacement)
+          remove_line(corrector, enable.comment)
+        end
+
+        def check_push_pop(directive)
+          pop_line = balancing_pop_line(directive)
+          return unless pop_line && comment_config.comment_only_line?(pop_line)
+          return unless wraps_single_statement?(directive, pop_line)
+
+          pop_comment = processed_source.comment_at_line(pop_line)
+          replacement = push_replacement(directive)
+          message = format(MSG_PUSH_POP, replacement: replacement_mode(directive))
+          add_offense(directive.comment, message: message) do |corrector|
+            corrector.replace(directive.comment, replacement)
+            remove_line(corrector, pop_comment)
+          end
+        end
+
+        # The line of the `pop` balancing this `push`, taking nesting into
+        # account, or `nil` when the push is never popped.
+        def balancing_pop_line(push_directive)
+          depth = 0
+          each_directive_after(push_directive) do |directive|
+            if directive.push?
+              depth += 1
+            elsif directive.pop?
+              return directive.line_number if depth.zero?
+
+              depth -= 1
+            end
+          end
+          nil
+        end
+
+        def each_directive_after(reference)
+          processed_source.comments.each do |comment|
+            directive = DirectiveComment.new(comment)
+            next unless directive.cop_names || directive.push? || directive.pop?
+
+            yield directive if directive.line_number > reference.line_number
+          end
+        end
+
+        def replacement_mode(directive)
+          ops = directive.signed_args.keys.sort
+          if ops == ['-']
+            'disable-next'
+          elsif ops == ['+']
+            'enable-next'
+          else
+            'next'
+          end
+        end
+
+        def push_replacement(directive)
+          text = case replacement_mode(directive)
+                 when 'disable-next'
+                   "# rubocop:disable-next #{directive.signed_args['-'].join(', ')}"
+                 when 'enable-next'
+                   "# rubocop:enable-next #{directive.signed_args['+'].join(', ')}"
+                 else
+                   "# rubocop:next #{directive.cops}"
+                 end
+          reason = directive.reason
+          reason ? "#{text} -- #{reason}" : text
+        end
+
+        # An `enable`/`disable` pair around one statement inside a disabled
+        # region re-enables the cops for just that statement - `enable-next`
+        # says the same without the closing boundary. The pair only counts
+        # when the `enable` really closed open disables (otherwise the
+        # trailing `disable` opens a new region and the conversion would
+        # change what is covered).
+        def check_enable_pair(directive)
+          closing = enable_pair_closing(directive)
+          return unless closing
+
+          add_offense(directive.comment, message: MSG_ENABLE_PAIR) do |corrector|
+            corrector.replace(directive.comment,
+                              directive.comment.text.sub(/\benable\b/, 'enable-next'))
+            remove_line(corrector, closing.comment)
+          end
+        end
+
+        def enable_pair_closing(directive)
+          scope = comment_config.statement_scope_after(directive.line_number)
+          return nil unless scope && scope.begin == directive.line_number + 1
+
+          closing = re_disable_below(directive, scope.end + 1)
+          closing if closing && closed_open_disables?(directive, closing)
+        end
+
+        def re_disable_below(directive, line)
+          return nil unless comment_config.comment_only_line?(line)
+
+          comment = processed_source.comment_at_line(line)
+          return nil unless comment
+
+          closing = DirectiveComment.new(comment)
+          return nil unless closing.disabled? && !closing.disable_next?
+          return nil unless closing.raw_cop_names.sort == directive.raw_cop_names.sort
+
+          closing
+        end
+
+        # Every cop of the pair must have a range the `enable` closed and a
+        # range the trailing `disable` reopened - otherwise the `enable` was
+        # not inside a disabled region and the conversion would change what
+        # is covered.
+        def closed_open_disables?(directive, closing)
+          directive.cop_names.all? do |cop|
+            ranges = comment_config.cop_disabled_line_ranges[qualified_name(cop)]
+            ranges && closed_at?(ranges, directive.line_number) && reopened_by?(ranges, closing)
+          end
+        end
+
+        def closed_at?(ranges, line)
+          ranges.any? { |range| range.end == line }
+        end
+
+        def reopened_by?(ranges, closing)
+          ranges.any? do |range|
+            range.respond_to?(:directive) && range.directive.comment.equal?(closing.comment)
+          end
+        end
+
+        def qualified_name(cop_name)
+          Registry.qualified_cop_name(cop_name.strip, processed_source.file_path,
+                                      correct_namespace: false)
+        end
+
+        # The directive closing this one's scope, when that scope wraps
+        # exactly one statement - `nil` otherwise.
+        def single_statement_closing_directive(directive)
+          closing_line = single_closing_line(directive)
+          return nil unless closing_line
+
+          closing_comment = processed_source.comment_at_line(closing_line)
+          return nil unless closing_comment
+          return nil unless wraps_single_statement?(directive, closing_line)
+
+          DirectiveComment.new(closing_comment)
+        end
+
+        # The single line on which every disabled range opened by this
+        # directive ends, or `nil` when the ranges disagree or never close.
+        # For a `disable` that is the `enable` line; for a `push` it is the
+        # line before the `pop`.
+        def single_closing_line(directive)
+          ranges = ranges_opened_by(directive)
+          return nil if ranges.empty?
+
+          ends = ranges.map(&:end).uniq
+          return nil unless ends.size == 1 && ends.first.to_f.finite?
+
+          ends.first
+        end
+
+        def ranges_opened_by(directive)
+          comment_config.cop_disabled_line_ranges.each_value.flat_map do |ranges|
+            ranges.select do |range|
+              range.respond_to?(:directive) && range.directive.comment.equal?(directive.comment)
+            end
+          end
+        end
+
+        # The region wraps a single statement only when the directive sits
+        # immediately above it and the closing directive immediately below -
+        # any other line inside the region (a comment, a blank line) may
+        # carry offenses of the suppressed cops that the tighter scope
+        # would no longer cover.
+        def wraps_single_statement?(directive, closing_line)
+          scope = comment_config.statement_scope_after(directive.line_number)
+
+          !scope.nil? && scope.begin == directive.line_number + 1 && scope.end + 1 == closing_line
+        end
+
+        def remove_line(corrector, comment)
+          corrector.remove(range_by_whole_lines(comment.source_range, include_final_newline: true))
+        end
+      end
+    end
+  end
+end

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

@@ -1,17 +1,45 @@
 # 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. Offenses in this mode are not autocorrected,
+      # since only a human can supply the missing justification.
+      #
+      # 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,57 +58,193 @@ 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
+          @matching_pops = nil
+
           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?
 
-            register_offense(comment, directive_cops, disallowed_cops)
+            register_offense(directive, directive_cops, disallowed_cops)
           end
         end
 
         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|
-            replacement = ''
+        def register_offense(directive, directive_cops, disallowed_cops)
+          comment = directive.comment
 
-            if directive_cops.length != disallowed_cops.length
-              replacement = comment.text.sub(/#{Regexp.union(disallowed_cops)},?\s*/, '')
-                                   .sub(/,\s*$/, '')
+          add_offense(comment, message: offense_message(disallowed_cops)) do |corrector|
+            # The remedy in `AllowWithReason` mode is to write the missing `--` justification,
+            # which cannot be autocorrected. Removing the directive would also unsuppress
+            # the disabled cops and let their autocorrections rewrite the annotated code.
+            next if allow_with_reason?
+
+            if directive_cops.length == disallowed_cops.length
+              remove_directive(corrector, directive)
+            elsif signed_args?(directive)
+              remove_signed_args(corrector, directive, disallowed_cops)
+            else
+              remove_cops(corrector, comment, disallowed_cops)
             end
+          end
+        end
 
-            corrector.replace(comment, replacement)
+        # A `push` without its `pop` leaves an orphan `pop` behind, so the pair goes together.
+        def remove_directive(corrector, directive)
+          corrector.replace(directive.comment, '')
+          return unless directive.push? && (pop = matching_pop(directive.comment))
+
+          corrector.replace(pop, '')
+        end
+
+        def matching_pop(push_comment)
+          @matching_pops ||= pair_pushes_with_pops
+          @matching_pops[push_comment]
+        end
+
+        def pair_pushes_with_pops
+          pushes = []
+          processed_source.comments.each_with_object({}) do |comment, pairs|
+            directive = DirectiveComment.new(comment)
+            if directive.push?
+              pushes.push(comment)
+            elsif directive.pop? && (push = pushes.pop)
+              pairs[push] = comment
+            end
           end
         end
 
-        def directive_cops(comment)
-          match_captures = DirectiveComment.new(comment).match_captures
+        def remove_signed_args(corrector, directive, disallowed_cops)
+          range = directive.range
+          names = Regexp.union(disallowed_cops)
+          corrector.replace(range, range.source.gsub(/\s+[+-]#{names}(?!\S)/, ''))
+        end
+
+        def remove_cops(corrector, comment, disallowed_cops)
+          corrector.replace(comment, comment.text.sub(/#{Regexp.union(disallowed_cops)},?\s*/, '')
+                                                 .sub(/,\s*$/, ''))
+        end
+
+        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)
+          return directive.signed_args.values.flatten if signed_args?(directive)
+
+          match_captures = directive.match_captures
           match_captures && match_captures[1] ? match_captures[1].split(',').map(&:strip) : []
         end
 
+        def signed_args?(directive)
+          directive.push? || directive.next?
+        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?
+          # TODO: The obsolete `AllowTrailingComment` is honored for backward compatibility
+          # and will be removed in RuboCop 2.0.
+          allow_trailing_comment = cop_config['AllowTrailingComment'] # rubocop:disable InternalAffairs/UndefinedConfig -- obsolete key, gone from default.yml on purpose
+          return allow_trailing_comment unless allow_trailing_comment.nil?
+
+          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))