rubocop 1.71.1 → 1.92.0

data/lib/rubocop/cop/lint/misplaced_magic_comment.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Lint
+      # Checks for magic comments placed where Ruby silently ignores them.
+      #
+      # The `encoding` magic comment is only honored on the first line of a file,
+      # or on the second line when the first line is a shebang. Anywhere else it
+      # is silently ignored - even directly below another comment or a blank line.
+      #
+      # Other magic comments (such as `frozen_string_literal`) are honored
+      # anywhere before the first token of code, but are ignored after any code,
+      # with a warning emitted only when running Ruby with `-w`.
+      #
+      # A magic comment misplaced ahead of a shebang also renders the shebang
+      # ineffective, since a shebang is only recognized on the first line.
+      #
+      # NOTE: An `encoding` comment that is only preceded by other magic
+      # comments is not flagged by this cop; that case is handled by
+      # `Lint/OrderedMagicComments`. `shareable_constant_value` is never
+      # flagged, as Ruby intentionally allows it mid-file with block scoping.
+      #
+      # @safety
+      #   This cop's autocorrection is unsafe because moving the magic comment
+      #   to its effective position activates it, which changes runtime
+      #   behavior (e.g. the source encoding or string mutability).
+      #
+      # @example
+      #   # bad
+      #   # Documentation comment
+      #   # encoding: ascii-8bit
+      #   puts 'hello'
+      #
+      #   # good
+      #   # encoding: ascii-8bit
+      #   # Documentation comment
+      #   puts 'hello'
+      #
+      #   # bad
+      #   require 'foo'
+      #   # frozen_string_literal: true
+      #
+      #   # good
+      #   # frozen_string_literal: true
+      #   require 'foo'
+      #
+      #   # bad
+      #   # frozen_string_literal: true
+      #   #!/usr/bin/env ruby
+      #   puts 'hello'
+      #
+      #   # good
+      #   #!/usr/bin/env ruby
+      #   # frozen_string_literal: true
+      #   puts 'hello'
+      class MisplacedMagicComment < Base
+        include RangeHelp
+        extend AutoCorrector
+
+        MSG_ENCODING = 'The `encoding` magic comment is ignored unless placed on the first ' \
+                       'line (or below a shebang on the first line).'
+        MSG_AFTER_CODE = 'The `%<directive>s` magic comment is ignored after any code.'
+        MSG_ABOVE_SHEBANG = 'A magic comment above a shebang renders the shebang ineffective.'
+
+        def on_new_investigation
+          return if processed_source.buffer.source.empty?
+
+          check_magic_comment_above_shebang
+          processed_source.comments.each { |comment| check_comment(comment) }
+        end
+
+        private
+
+        def check_comment(comment)
+          return unless magic_comment_shaped?(comment.text)
+
+          magic_comment = MagicComment.parse(comment.text)
+          return unless magic_comment.valid?
+
+          if magic_comment.encoding_specified?
+            return unless known_encoding?(magic_comment.encoding)
+
+            check_encoding_comment(comment)
+          elsif magic_comment.frozen_string_literal_specified?
+            check_top_block_comment(comment, 'frozen_string_literal')
+          end
+        end
+
+        # The Emacs and Vim regexps in `MagicComment` match anywhere inside a
+        # comment, which would flag documentation that merely quotes a magic
+        # comment (e.g. `#   # -*- coding: UTF-8 -*-`). Require the magic
+        # comment to start right after the `#`.
+        def magic_comment_shaped?(text)
+          /\A#(?![^#]*#)/.match?(text)
+        end
+
+        # Prose that happens to open with `Encoding:` parses as an encoding
+        # comment (`# Encoding: force given encoding` yields `force`). Ruby
+        # ignores a misplaced encoding comment entirely, so a name no encoding
+        # answers to means the line is a comment, not a directive.
+        def known_encoding?(name)
+          Encoding.find(name)
+          true
+        rescue ArgumentError
+          false
+        end
+
+        def shebang?
+          processed_source.lines.first.to_s.start_with?('#!')
+        end
+
+        # First line that may carry an effective encoding comment.
+        def effective_encoding_line
+          shebang? ? 2 : 1
+        end
+
+        def first_code_token
+          processed_source.sorted_tokens.find { |token| !token.comment? }
+        end
+
+        def check_encoding_comment(comment)
+          return unless misplaced_encoding_position?(comment)
+
+          add_offense(comment, message: MSG_ENCODING) do |corrector|
+            correct_encoding_comment(corrector, comment)
+          end
+        end
+
+        def misplaced_encoding_position?(comment)
+          line = comment.source_range.line
+          return false if line == effective_encoding_line && comment_starts_line?(comment)
+
+          # Leave `# frozen_string_literal: true` + `# encoding: x` runs at the
+          # very top to Lint/OrderedMagicComments, which already reorders them.
+          !preceded_only_by_magic_comments?(comment)
+        end
+
+        # With an effective encoding comment already in place, moving another
+        # one in would override it. Drop an identical duplicate and leave a
+        # conflicting one for a human to resolve.
+        def correct_encoding_comment(corrector, comment)
+          effective_comment = effective_encoding_comment
+
+          if effective_comment.nil?
+            move_comment(corrector, comment, effective_encoding_line)
+          elsif comment_encoding(effective_comment) == comment_encoding(comment)
+            corrector.remove(comment_removal_range(comment))
+          end
+        end
+
+        def comment_encoding(comment)
+          Encoding.find(MagicComment.parse(comment.text).encoding)
+        rescue ArgumentError
+          nil
+        end
+
+        def check_top_block_comment(comment, directive)
+          return unless first_code_token
+          return unless comment.source_range.begin_pos > first_code_token.begin_pos
+
+          message = format(MSG_AFTER_CODE, directive: directive)
+          add_offense(comment, message: message) do |corrector|
+            # Both would be inserted at the top, in no reliable order. Leave
+            # this one to the next pass, once the encoding comment is in place.
+            next if encoding_comment_moving_in?
+
+            move_comment(corrector, comment, top_block_insertion_line)
+          end
+        end
+
+        def encoding_comment_moving_in?
+          return false if effective_encoding_comment
+
+          processed_source.comments.any? do |comment|
+            known_encoding_comment?(comment) && misplaced_encoding_position?(comment)
+          end
+        end
+
+        def effective_encoding_comment
+          processed_source.comments.find do |comment|
+            comment.source_range.line == effective_encoding_line &&
+              comment_starts_line?(comment) &&
+              MagicComment.parse(comment.text).encoding_specified?
+          end
+        end
+
+        def known_encoding_comment?(comment)
+          return false unless magic_comment_shaped?(comment.text)
+
+          magic_comment = MagicComment.parse(comment.text)
+          magic_comment.encoding_specified? && known_encoding?(magic_comment.encoding)
+        end
+
+        # Insert below an effective encoding comment rather than above it,
+        # which would push it off the only lines where Ruby honors it.
+        def top_block_insertion_line
+          effective_encoding_comment ? effective_encoding_line + 1 : effective_encoding_line
+        end
+
+        def check_magic_comment_above_shebang
+          shebang_comment = processed_source.comments.find do |comment|
+            comment.source_range.line > 1 && comment.text.start_with?('#!') &&
+              comment.source_range.column.zero?
+          end
+          return unless shebang_comment
+          # Only flag when what precedes the shebang is magic comments -
+          # a `#!` comment deep inside a file is not an intended shebang.
+          return unless preceded_only_by_magic_comments?(shebang_comment)
+
+          add_offense(shebang_comment, message: MSG_ABOVE_SHEBANG)
+        end
+
+        def preceded_only_by_magic_comments?(comment)
+          (1...comment.source_range.line).all? do |line_number|
+            text = processed_source.lines[line_number - 1]
+            (line_number == 1 && text.start_with?('#!')) || MagicComment.parse(text).valid?
+          end
+        end
+
+        def comment_starts_line?(comment)
+          processed_source.lines[comment.source_range.line - 1].lstrip.start_with?('#')
+        end
+
+        def move_comment(corrector, comment, target_line)
+          corrector.remove(comment_removal_range(comment))
+          target_range = processed_source.buffer.line_range(target_line)
+          if comment.source_range.line < target_line
+            corrector.insert_after(target_range, "\n#{comment.text}")
+          else
+            corrector.insert_before(target_range, "#{comment.text}\n")
+          end
+        end
+
+        def comment_removal_range(comment)
+          if comment_starts_line?(comment)
+            range_by_whole_lines(comment.source_range, include_final_newline: true)
+          else
+            range_with_surrounding_space(comment.source_range, side: :left)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/lint/missing_cop_enable_directive.rb

@@ -1,17 +1,29 @@
 # frozen_string_literal: true
 
-# rubocop:disable Lint/RedundantCopDisableDirective
+# rubocop:disable-next Lint/RedundantCopDisableDirective -- the examples below read as real directives
 module RuboCop
   module Cop
     module Lint
       # Checks that there is an `# rubocop:enable ...` statement
       # after a `# rubocop:disable ...` statement. This will prevent leaving
-      # cop disables on wide ranges of code, that latter contributors to
+      # cop disables on wide ranges of code, that later contributors to
       # a file wouldn't be aware of.
       #
-      # @example
-      #   # Lint/MissingCopEnableDirective:
-      #   #   MaximumRangeSize: .inf
+      # You can set `MaxRangeSize` to define the maximum number of
+      # consecutive lines a cop can be disabled for.
+      #
+      # - `.inf` any size (default)
+      # - `0` allows only single-line disables
+      # - `1` means the maximum allowed is as follows:
+      #
+      # [source,ruby]
+      # ----
+      # # rubocop:disable SomeCop
+      # a = 1
+      # # rubocop:enable SomeCop
+      # ----
+      #
+      # @example MaxRangeSize: .inf (default)
       #
       #   # good
       #   # rubocop:disable Layout/SpaceAroundOperators
@@ -25,9 +37,7 @@ module RuboCop
       #   x= 0
       #   # EOF
       #
-      # @example
-      #   # Lint/MissingCopEnableDirective:
-      #   #   MaximumRangeSize: 2
+      # @example MaxRangeSize: 2
       #
       #   # good
       #   # rubocop:disable Layout/SpaceAroundOperators
@@ -45,17 +55,16 @@ module RuboCop
       class MissingCopEnableDirective < Base
         include RangeHelp
 
-        MSG = 'Re-enable %<cop>s %<type>s with `# rubocop:enable` after disabling it.'
+        MSG = 'Re-enable %<cop>s %<type>s with `%<directive>s` after disabling it.'
         MSG_BOUND = 'Re-enable %<cop>s %<type>s within %<max_range>s lines after disabling it.'
 
         def on_new_investigation
           each_missing_enable do |cop, line_range|
             next if acceptable_range?(cop, line_range)
 
-            range = source_range(processed_source.buffer, line_range.min, (0..0))
-            comment = processed_source.comment_at_line(line_range.begin)
+            comment = opening_comment(line_range)
 
-            add_offense(range, message: message(cop, comment))
+            add_offense(comment, message: message(cop, comment))
           end
         end
 
@@ -63,39 +72,68 @@ module RuboCop
 
         def each_missing_enable
           processed_source.disabled_line_ranges.each do |cop, line_ranges|
-            line_ranges.each { |line_range| yield cop, line_range }
+            line_ranges.each do |line_range|
+              # A `disable-next` or `next` scope closes itself with its statement.
+              next if statement_scoped?(line_range)
+
+              yield cop, line_range
+            end
           end
         end
 
+        def statement_scoped?(line_range)
+          directive = line_range.respond_to?(:directive) && line_range.directive
+          directive && (directive.disable_next? || directive.next?)
+        end
+
+        # A disable suspended by `enable-next` or `next +Cop` reopens below the
+        # statement, on a code line, so the comment that opened it has to come
+        # from the range rather than from its first line.
+        def opening_comment(line_range)
+          directive = line_range.respond_to?(:directive) && line_range.directive
+          return directive.comment if directive
+
+          processed_source.comment_at_line(line_range.begin)
+        end
+
         def acceptable_range?(cop, line_range)
           # This has to remain a strict inequality to handle
           # the case when max_range is Float::INFINITY
           return true if line_range.max - line_range.min < max_range + 2
+          # A name that is not registered as written (e.g. a wrongly-namespaced
+          # cop) suppresses nothing; `Lint/RedundantCopDisableDirective` reports
+          # it, so demanding its re-enablement would only add noise.
+          return true unless Registry.global.names.include?(cop)
+
+          expected_open_range?(cop, line_range)
+        end
+
+        def expected_open_range?(cop, line_range)
           # This cop is disabled in the config, it is not expected to be re-enabled
           return true if line_range.min == CommentConfig::CONFIG_DISABLED_LINE_RANGE_MIN
 
-          cop_class = RuboCop::Cop::Registry.global.find_by_cop_name cop
-          if cop_class &&
+          cop_class = RuboCop::Cop::Registry.global.find_by_cop_name(cop)
+          !!(cop_class &&
              !processed_source.registry.enabled?(cop_class, config) &&
-             line_range.max == Float::INFINITY
-            return true
-          end
-
-          false
+             line_range.max == Float::INFINITY)
         end
 
         def max_range
-          @max_range ||= cop_config['MaximumRangeSize']
+          @max_range ||= cop_config['MaxRangeSize']
         end
 
         def message(cop, comment, type = 'cop')
+          directive = DirectiveComment.new(comment)
           if department_enabled?(cop, comment)
             type = 'department'
             cop = cop.split('/').first
           end
 
           if max_range == Float::INFINITY
-            format(MSG, cop: cop, type: type)
+            # A range opened by `rubocop:push` is closed by `rubocop:pop`,
+            # not by `rubocop:enable`.
+            enabling_directive = directive.push? ? '# rubocop:pop' : '# rubocop:enable'
+            format(MSG, cop: cop, type: type, directive: enabling_directive)
           else
             format(MSG_BOUND, cop: cop, type: type, max_range: max_range)
           end
@@ -108,4 +146,3 @@ module RuboCop
     end
   end
 end
-# rubocop:enable Lint/RedundantCopDisableDirective

data/lib/rubocop/cop/lint/missing_super.rb

@@ -21,6 +21,13 @@ module RuboCop
       # `AllowedParentClasses` option to specify which classes should be allowed
       # *in addition to* `Object` and `BasicObject`.
       #
+      # When `AllCops/UseProjectIndex` is enabled and the `rubydex` gem is installed,
+      # the constructor check additionally consults the project-wide index: if the
+      # class' entire ancestry is resolvable and no ancestor defines `initialize`,
+      # no offense is registered, since `super` would only reach the no-op
+      # `Object#initialize`. Classes whose ancestry contains an unresolvable
+      # superclass or mixin (e.g. one defined in a gem) are still reported.
+      #
       # @example
       #   # bad
       #   class Employee < Person
@@ -83,6 +90,8 @@ module RuboCop
       #   end
       #
       class MissingSuper < Base
+        include ProjectIndexHelp
+
         CONSTRUCTOR_MSG = 'Call `super` to initialize state of the parent class.'
         CALLBACK_MSG    = 'Call `super` to invoke callback defined in the parent class.'
 
@@ -140,7 +149,8 @@ module RuboCop
 
             !allowed_class?(super_class)
           elsif (class_node = node.each_ancestor(:class).first)
-            class_node.parent_class && !allowed_class?(class_node.parent_class)
+            class_node.parent_class && !allowed_class?(class_node.parent_class) &&
+              !index_verified_stateless_ancestry?(class_node)
           else
             false
           end
@@ -153,6 +163,26 @@ module RuboCop
         def allowed_classes
           @allowed_classes ||= STATELESS_CLASSES + cop_config.fetch('AllowedParentClasses', [])
         end
+
+        # With the project index, the offense is skipped when the class' whole ancestry
+        # is resolvable and none of the inherited ancestors defines `initialize` —
+        # `super` would only reach the no-op `Object#initialize`. An unresolvable
+        # superclass or mixin anywhere in the chain (e.g. a class from a gem) means
+        # the ancestry cannot be verified and the offense is kept.
+        def index_verified_stateless_ancestry?(class_node)
+          return false unless project_index
+
+          declaration = resolve_constant_in_index(class_node.identifier)
+          return false unless declaration.is_a?(Rubydex::Class)
+
+          ancestors = declaration.ancestors.to_a
+          inherited = ancestors.reject { |ancestor| ancestor.name == declaration.name }
+          return false if inherited.any? { |ancestor| ancestor.member('initialize()') }
+
+          # `extend` affects the singleton class and cannot introduce an
+          # inherited `initialize`, so unresolved extends are tolerated.
+          fully_resolved_index_ancestry?(declaration, ignore_extend: true)
+        end
       end
     end
   end

data/lib/rubocop/cop/lint/mixed_case_range.rb

@@ -79,7 +79,7 @@ module RuboCop
         end
 
         def range_pairs(expr)
-          RuboCop::Cop::Utils::RegexpRanges.new(expr).pairs
+          expr.expressions.filter_map { |e| [e.expressions[0], e.expressions[1]] if e.type == :set }
         end
 
         def unsafe_range?(range_start, range_end)
@@ -94,7 +94,7 @@ module RuboCop
 
         def skip_range?(range_start, range_end)
           [range_start, range_end].any? do |bound|
-            bound.type != :literal
+            bound&.type != :literal
           end
         end
 

data/lib/rubocop/cop/lint/multiple_comparison.rb

@@ -4,8 +4,8 @@ module RuboCop
   module Cop
     module Lint
       # In math and Python, we can use `x < y < z` style comparison to compare
-      # multiple value. However, we can't use the comparison in Ruby. However,
-      # the comparison is not syntax error. This cop checks the bad usage of
+      # multiple values. However, we can't use the comparison in Ruby. However,
+      # the comparison is not a syntax error. This cop checks the bad usage of
       # comparison operators.
       #
       # @example