rubocop 1.88.2 → 1.89.0

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

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Lint
+      # Checks for calls to methods and references to constants that are documented
+      # as deprecated with a YARD `@deprecated` tag.
+      #
+      # The check is powered by the project-wide index, so it only runs when
+      # `AllCops/UseProjectIndex` is enabled and the `rubydex` gem is installed.
+      # Without the index the cop does nothing.
+      #
+      # Only references that can be resolved without type inference are checked:
+      # constants, method calls without an explicit receiver (or with `self`),
+      # which are looked up in the enclosing class or module and its ancestry,
+      # and calls whose receiver is a constant, which are looked up in that
+      # namespace's singleton class. Calls on arbitrary objects are not checked.
+      #
+      # References made from a definition that is itself deprecated are allowed,
+      # so deprecated implementations can keep calling each other.
+      #
+      # @example
+      #   # Given a deprecated method and constant:
+      #   #
+      #   #   class Api
+      #   #     # @deprecated Use `#new_method` instead.
+      #   #     def old_method
+      #   #     end
+      #   #
+      #   #     # @deprecated
+      #   #     OLD_TIMEOUT = 10
+      #   #   end
+      #
+      #   # bad
+      #   class Client < Api
+      #     def call
+      #       old_method
+      #     end
+      #
+      #     def timeout
+      #       OLD_TIMEOUT
+      #     end
+      #   end
+      #
+      #   # good
+      #   class Client < Api
+      #     def call
+      #       new_method
+      #     end
+      #
+      #     def timeout
+      #       NEW_TIMEOUT
+      #     end
+      #   end
+      #
+      class DeprecatedReference < Base
+        include ProjectIndexHelp
+
+        METHOD_MSG = 'Method `%<name>s` is deprecated%<detail>s'
+        CONSTANT_MSG = 'Constant `%<name>s` is deprecated%<detail>s'
+
+        DEPRECATED_TAG = '@deprecated'
+        DEPRECATION_DETAIL = /#{DEPRECATED_TAG}\s+(.+)/.freeze
+
+        def on_new_investigation
+          @namespace_cache = {}
+          super
+        end
+
+        def on_send(node)
+          return unless project_index
+
+          declaration = method_declaration_for(node)
+          return unless declaration && deprecated?(declaration)
+          return if within_deprecated_definition?(node)
+
+          message = format(METHOD_MSG, name: node.method_name, detail: detail_for(declaration))
+          add_offense(node.loc.selector, message: message)
+        end
+        alias on_csend on_send
+
+        def on_const(node)
+          return unless project_index
+          return if node.parent&.defined_module
+
+          declaration = resolve_constant_in_index(node)
+          return unless declaration && deprecated?(declaration)
+          return if within_deprecated_definition?(node)
+
+          message = format(CONSTANT_MSG, name: node.const_name, detail: detail_for(declaration))
+          add_offense(node, message: message)
+        end
+
+        private
+
+        def method_declaration_for(node)
+          receiver = node.receiver
+
+          if receiver.nil? || receiver.self_type?
+            implicit_receiver_declaration(node)
+          elsif receiver.const_type?
+            const_receiver_declaration(node, receiver)
+          end
+        end
+
+        def implicit_receiver_declaration(node)
+          namespace = enclosing_namespace(node)
+          return nil unless namespace.is_a?(Rubydex::Namespace)
+
+          if singleton_context?(node)
+            indexed_singleton_member(namespace, "#{node.method_name}()")
+          else
+            namespace.find_member("#{node.method_name}()")
+          end
+        end
+
+        def const_receiver_declaration(node, receiver)
+          namespace = resolve_constant_in_index(receiver)
+          return nil unless namespace.is_a?(Rubydex::Namespace)
+
+          indexed_singleton_member(namespace, "#{node.method_name}()")
+        end
+
+        def enclosing_namespace(node)
+          namespace_node = node.each_ancestor(:class, :module).first
+          return project_index['Object'] unless namespace_node
+
+          @namespace_cache.fetch(namespace_node) do
+            @namespace_cache[namespace_node] = resolve_constant_in_index(namespace_node.identifier)
+          end
+        end
+
+        # Whether an implicit-receiver call runs with the class or module itself
+        # as `self` (directly in a namespace body, in a singleton method, or
+        # inside `class << self`) rather than inside an instance method.
+        def singleton_context?(node)
+          instance_def_seen = false
+
+          node.each_ancestor do |ancestor|
+            case ancestor.type
+            when :defs, :sclass
+              return true
+            when :def
+              instance_def_seen = true
+            when :class, :module
+              return !instance_def_seen
+            end
+          end
+
+          false
+        end
+
+        def deprecated?(declaration)
+          definitions = declaration.definitions.to_a
+
+          definitions.any? && definitions.all?(&:deprecated?)
+        end
+
+        # References from a definition that is itself documented as deprecated
+        # are allowed.
+        def within_deprecated_definition?(node)
+          node.each_ancestor(:any_def, :class, :module).any? do |ancestor|
+            comments = processed_source.ast_with_comments[ancestor]
+            comments.any? { |comment| comment.text.include?(DEPRECATED_TAG) }
+          end
+        end
+
+        def detail_for(declaration)
+          text = deprecation_text(declaration)
+          return '.' if text.nil? || text.empty?
+
+          text.end_with?('.') ? ": #{text}" : ": #{text}."
+        end
+
+        def deprecation_text(declaration)
+          tag_comment = declaration.definitions.to_a.filter_map do |definition|
+            definition.comments.to_a.map(&:string).find { |string| string.include?(DEPRECATED_TAG) }
+          end.first
+
+          tag_comment && tag_comment[DEPRECATION_DETAIL, 1]&.strip
+        end
+      end
+    end
+  end
+end

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

@@ -10,6 +10,17 @@ module RuboCop
       # the developer intends to suppress Ruby's method redefinition warnings.
       # See https://bugs.ruby-lang.org/issues/13574.
       #
+      # By default the cop can only detect duplicates within a single file.
+      # When `AllCops/UseProjectIndex` is enabled and the `rubydex` gem is installed,
+      # the cop additionally consults the project-wide index and reports methods
+      # whose duplicate definition lives in another file.
+      #
+      # NOTE: The project index does not record whether a definition in another
+      # file is wrapped in a conditional, so a platform-specific redefinition in
+      # another file may still be reported. Aliasing the method to itself (see above)
+      # before redefining marks the redefinition as intentional and is respected
+      # across files.
+      #
       # @example
       #
       #   # bad
@@ -118,16 +129,45 @@ module RuboCop
       #     delegate :foo, to: :bar
       #   end
       #
+      # @example DelegatingMethods: ['delegate', 'expose'] (default: ['delegate'])
+      #   # A project's own `delegate`-shaped macros can be registered so the
+      #   # methods they define are recognized (with
+      #   # `AllCops/ActiveSupportExtensionsEnabled: true`).
+      #
+      #   # bad
+      #   def foo
+      #     1
+      #   end
+      #
+      #   expose :foo, to: :bar
+      #
       class DuplicateMethods < Base # rubocop:disable Metrics/ClassLength
+        include ProjectIndexHelp
+
         MSG = 'Method `%<method>s` is defined at both %<defined>s and %<current>s.'
-        RESTRICT_ON_SEND = %i[alias_method attr_reader attr_writer attr_accessor attr
-                              delegate def_delegator def_instance_delegator def_delegators
-                              def_instance_delegators].freeze
+
+        # Method names the cop registers that can be looked up in the project index:
+        # a fully qualified namespace followed by `#` (instance) or `.` (singleton)
+        # and the method name.
+        INDEXABLE_METHOD_NAME =
+          /\A(?<owner>[A-Z]\w*(?:::[A-Z]\w*)*)(?<separator>[#.])(?<name>[^#.]+)\z/.freeze
+        # No `RESTRICT_ON_SEND`: the delegating method names are configurable
+        # (`DelegatingMethods`), so `on_send` must see every call. The handler
+        # returns quickly for calls that are not method definitions, and
+        # benchmarks show no measurable cost over the previous fixed list.
 
         def initialize(config = nil, options = nil)
           super
           @definitions = {}
           @scopes = Hash.new { |hash, key| hash[key] = [] }
+          @self_aliased = Set.new
+        end
+
+        def on_new_investigation
+          # The self-alias trick declares an intentional redefinition only within
+          # the file that uses it, so the tracked names do not carry over.
+          @self_aliased = Set.new
+          super
         end
 
         def on_def(node)
@@ -157,7 +197,11 @@ module RuboCop
         def on_alias(node)
           name, original_name = method_alias?(node)
           return unless name && original_name
-          return if name == original_name
+
+          if name == original_name
+            track_self_alias(node, name)
+            return
+          end
           return if node.ancestors.any?(&:if_type?)
 
           found_instance_method(node, name)
@@ -168,9 +212,12 @@ module RuboCop
           (send nil? :alias_method (sym $_name) (sym $_original_name))
         PATTERN
 
-        # @!method delegate_method?(node)
-        def_node_matcher :delegate_method?, <<~PATTERN
-          (send nil? :delegate
+        # Matches the argument shape of an Active Support `delegate` call
+        # (`delegate :a, :b, to: :target`), regardless of the method name; the
+        # name is checked separately against `DelegatingMethods`.
+        # @!method delegate_args(node)
+        def_node_matcher :delegate_args, <<~PATTERN
+          (send nil? _
             ({sym str} $_)+
             (hash <(pair (sym :to) {sym str}) ...>)
           )
@@ -204,17 +251,27 @@ module RuboCop
             ...)
         PATTERN
 
+        # @!method class_new_block?(node)
+        def_node_matcher :class_new_block?, <<~PATTERN
+          (block
+            (send (const _ :Class) :new ...)
+            ...)
+        PATTERN
+
         def on_send(node) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
           name, original_name = alias_method?(node)
 
           if name && original_name
-            return if name == original_name
+            if name == original_name
+              track_self_alias(node, name)
+              return
+            end
             return if inside_condition?(node)
 
             found_instance_method(node, name)
           elsif (attr = node.attribute_accessor?)
             on_attr(node, *attr)
-          elsif active_support_extensions_enabled? && (names = delegate_method?(node))
+          elsif delegating_method?(node) && (names = delegate_args(node))
             return if inside_condition?(node)
 
             on_delegate(node, names)
@@ -257,6 +314,19 @@ module RuboCop
                       current: source_location(node))
         end
 
+        # Recognizing a delegating call as a method definition is Active
+        # Support behavior, so it stays gated on `ActiveSupportExtensionsEnabled`
+        # as it was when only `delegate` was supported. `DelegatingMethods` lets
+        # a project register its own `delegate`-shaped macros.
+        def delegating_method?(node)
+          active_support_extensions_enabled? &&
+            delegating_methods.include?(node.method_name.to_s)
+        end
+
+        def delegating_methods
+          cop_config.fetch('DelegatingMethods', ['delegate'])
+        end
+
         def on_delegate(node, method_names)
           name_prefix = delegate_prefix(node)
 
@@ -318,13 +388,27 @@ module RuboCop
           parent = anon_block.parent
           return unless parent&.type?(:any_block, :begin, :call, :casgn, :any_def)
 
-          if (receiver = named_receiver(parent))
+          if (receiver = scope_receiver(parent, anon_block))
             "#{receiver.source}.#{parent.method_name}"
           elsif !parent.begin_type? || parent.parent&.any_block_type?
-            source_location(anon_block)
+            anon_block_identity(anon_block)
           end
         end
 
+        # When a Class.new block is passed as an argument to a named-receiver
+        # method call (e.g. T.cast(Class.new(Base) do ... end, ...)), the
+        # receiver-based scope id (e.g. "T.cast") is the same for every call,
+        # causing false positives for methods defined in distinct anonymous
+        # classes. Return nil so the block falls through to the unique
+        # source-location-based scope id.
+        # Module.new blocks are excluded because they may be intentionally
+        # mixed into the same target via prepend/include/extend.
+        def scope_receiver(parent, anon_block)
+          return if class_new_block?(anon_block) && parent.call_type?
+
+          named_receiver(parent)
+        end
+
         def named_receiver(node)
           receiver = node.receiver
           receiver unless class_or_module_new_block?(receiver)
@@ -340,27 +424,45 @@ module RuboCop
           found_method(node, "#{singleton_receiver_node.method_name}.#{name}")
         end
 
-        # rubocop:disable Metrics/AbcSize
         def found_method(node, method_name, scope_id: nil)
           key = method_key(node, method_name)
           key = "#{key}@#{scope_id}" if scope_id
           scope = node.each_ancestor(:rescue, :ensure).first&.type
 
           if @definitions.key?(key)
-            if scope && !@scopes[scope].include?(key)
-              @definitions[key] = node
-              @scopes[scope] << key
-              return
-            end
-
-            message = message_for_dup(node, method_name, key)
-
-            add_offense(location(node), message: message)
+            found_redefinition(node, method_name, key, scope)
           else
             @definitions[key] = node
+            check_cross_file_duplicate(node, method_name) if scope_id.nil? && scope.nil?
+          end
+        end
+
+        def found_redefinition(node, method_name, key, scope)
+          if scope && !@scopes[scope].include?(key)
+            @definitions[key] = node
+            @scopes[scope] << key
+          elsif intentional_cross_file_redefinition?(node, method_name, key)
+            @definitions[key] = node
+          else
+            add_offense(location(node), message: message_for_dup(node, method_name, key))
           end
         end
-        # rubocop:enable Metrics/AbcSize
+
+        # The self-alias trick (`alias foo foo` or `alias_method :foo, :foo` right before
+        # a `def`) suppresses Ruby's method redefinition warning, signaling an intentional
+        # redefinition of a method defined in another file.
+        def intentional_cross_file_redefinition?(node, method_name, key)
+          @self_aliased.include?(method_name) &&
+            @definitions[key].source_range.source_buffer.name !=
+              node.source_range.source_buffer.name
+        end
+
+        def track_self_alias(node, name)
+          scope = node.parent_module_name
+          return unless scope
+
+          @self_aliased << "#{humanize_scope(scope)}#{name}"
+        end
 
         def method_key(node, method_name)
           if (ancestor_def = node.each_ancestor(:any_def).first)
@@ -439,6 +541,84 @@ module RuboCop
           path = smart_path(range.source_buffer.name)
           "#{path}:#{range.line}"
         end
+
+        def check_cross_file_duplicate(node, method_name)
+          return unless project_index
+          return if @self_aliased.include?(method_name)
+          return if node.each_ancestor(:any_def).any?
+          return unless (prior = cross_file_prior_definition(method_name))
+
+          message = format(MSG, method: method_name,
+                                defined: index_source_location(prior),
+                                current: source_location(node))
+          add_offense(location(node), message: message)
+        end
+
+        def cross_file_prior_definition(method_name)
+          return unless (match = INDEXABLE_METHOD_NAME.match(method_name))
+
+          definitions = definitions_in_other_files(
+            indexed_definitions(match[:owner], match[:separator], match[:name])
+          )
+          return if definitions.empty? || cross_file_self_alias_trick?(definitions)
+
+          first_indexed_definition(definitions)
+        end
+
+        def indexed_definitions(owner, separator, name)
+          namespace = separator == '.' ? "#{owner}::<#{owner.split('::').last}>" : owner
+
+          if name.match?(/\A\w+=\z/)
+            # Rubydex indexes `attr_writer :foo` under `foo` rather than `foo=`, so
+            # writer definitions come from both the `foo=` and the `foo` declarations.
+            indexed_declaration_definitions(namespace, name) +
+              indexed_declaration_definitions(namespace, name.delete_suffix('='))
+              .select { |definition| writer_attr_definition?(definition) }
+          else
+            indexed_declaration_definitions(namespace, name).grep_v(Rubydex::AttrWriterDefinition)
+          end
+        end
+
+        def indexed_declaration_definitions(namespace, name)
+          project_index["#{namespace}##{name}()"]&.definitions.to_a
+        end
+
+        def writer_attr_definition?(definition)
+          definition.is_a?(Rubydex::AttrWriterDefinition) ||
+            definition.is_a?(Rubydex::AttrAccessorDefinition)
+        end
+
+        # An alias of the method alongside one of its definitions in another file may be
+        # the self-alias trick marking an intentional redefinition there, so no offense
+        # is registered. A genuine `alias` duplicate is still reported when the alias
+        # itself is inspected.
+        def cross_file_self_alias_trick?(definitions)
+          aliases, others = definitions.partition do |definition|
+            definition.is_a?(Rubydex::MethodAliasDefinition)
+          end
+          alias_paths = aliases.map { |definition| definition.location.to_file_path }
+
+          others.any? { |definition| alias_paths.include?(definition.location.to_file_path) }
+        end
+
+        def first_indexed_definition(definitions)
+          definitions.find { |definition| !definition.is_a?(Rubydex::MethodAliasDefinition) }
+        end
+
+        def index_source_location(definition)
+          location = definition.location
+          "#{smart_path(location.to_file_path)}:#{location.to_display.start_line}"
+        end
+
+        # Internal identity for an anonymous block, used as a scope key.
+        # Includes the source range's begin position to distinguish blocks
+        # that share the same line (e.g. two Class.new calls separated by `;`).
+        # The user-facing offense message still uses `source_location`, which
+        # shows only `path:line`.
+        def anon_block_identity(anon_block)
+          range = anon_block.source_range
+          "#{smart_path(range.source_buffer.name)}:#{range.line}:#{range.begin_pos}"
+        end
       end
     end
   end

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

@@ -12,6 +12,11 @@ module RuboCop
       #   exception class handle `StandardError` and its subclasses,
       #   but not `Exception` and its subclasses.
       #
+      # When `AllCops/UseProjectIndex` is enabled and the `rubydex` gem is
+      # installed, indirect inheritance is also detected: a class whose parent
+      # (defined anywhere in the project) ultimately inherits from `Exception`
+      # is reported, without autocorrection.
+      #
       # @example EnforcedStyle: standard_error (default)
       #   # bad
       #
@@ -39,9 +44,11 @@ module RuboCop
       #   C = Class.new(RuntimeError)
       class InheritException < Base
         include ConfigurableEnforcedStyle
+        include ProjectIndexHelp
         extend AutoCorrector
 
         MSG = 'Inherit from `%<prefer>s` instead of `Exception`.'
+        INDIRECT_MSG = 'Inherit from `%<prefer>s` instead of `Exception` (inherited via `%<via>s`).'
         PREFERRED_BASE_CLASS = {
           runtime_error: 'RuntimeError',
           standard_error: 'StandardError'
@@ -57,13 +64,20 @@ module RuboCop
         PATTERN
 
         def on_class(node)
-          return unless node.parent_class && exception_class?(node.parent_class)
-          return if inherit_exception_class_with_omitted_namespace?(node)
-
-          message = message(node.parent_class)
-
-          add_offense(node.parent_class, message: message) do |corrector|
-            corrector.replace(node.parent_class, preferred_base_class)
+          parent_class = node.parent_class
+          return unless parent_class
+
+          if exception_class?(parent_class)
+            return if inherit_exception_class_with_omitted_namespace?(node)
+
+            add_offense(parent_class, message: message(parent_class)) do |corrector|
+              corrector.replace(parent_class, preferred_base_class)
+            end
+          elsif (via = inherits_exception_via(parent_class))
+            # No autocorrection: the `Exception` inheritance lives at another
+            # class' definition site, possibly in another file.
+            message = format(INDIRECT_MSG, prefer: preferred_base_class, via: via)
+            add_offense(parent_class, message: message)
           end
         end
 
@@ -88,6 +102,38 @@ module RuboCop
           class_node.const_name == 'Exception'
         end
 
+        # When `AllCops/UseProjectIndex` is enabled, indirect inheritance is
+        # detected by walking the parent's indexed ancestry: `Exception` itself
+        # is not indexed, so a chain ending in it shows up as an ancestor whose
+        # superclass reference is unresolved and literally named `Exception`.
+        # Returns the name of that ancestor, or `nil`.
+        def inherits_exception_via(parent_class)
+          return nil unless project_index && parent_class.const_type?
+
+          declaration = resolve_constant_in_index(parent_class)
+          return nil unless declaration.is_a?(Rubydex::Class)
+
+          exception_ancestor(declaration)&.name
+        rescue StandardError
+          nil
+        end
+
+        def exception_ancestor(declaration)
+          declaration.ancestors.find do |ancestor|
+            ancestor.is_a?(Rubydex::Class) && exception_superclass_reference?(ancestor)
+          end
+        end
+
+        def exception_superclass_reference?(ancestor)
+          ancestor.definitions.any? do |definition|
+            next false unless definition.is_a?(Rubydex::ClassDefinition)
+
+            superclass = definition.superclass
+            superclass.is_a?(Rubydex::UnresolvedConstantReference) &&
+              superclass.name.delete_prefix('::') == 'Exception'
+          end
+        end
+
         def inherit_exception_class_with_omitted_namespace?(class_node)
           return false if class_node.parent_class.namespace&.cbase_type?
 

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

@@ -254,6 +254,11 @@ module RuboCop
         def correct_if_node(node, cond)
           result = condition_evaluation?(node, cond)
 
+          # When the branch that survives the literal condition is missing,
+          # there is no meaningful correction, so no offense is registered.
+          surviving_branch = result ? node.if_branch : node.else_branch
+          return if surviving_branch.nil? && (node.elsif? || node.else?)
+
           new_node = if node.elsif? && result
                        "else\n  #{range_with_comments(node.if_branch).source}"
                      elsif node.elsif? && !result

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

@@ -163,7 +163,7 @@ module RuboCop
           when :float
             node.children.last.to_f.to_s
           when :str
-            "\\\"#{node.value.to_s.gsub('"') { '\\\\\"' }}\\\""
+            escape_string_content(node.value.inspect)
           when :sym
             autocorrected_value_in_hash_for_symbol(node)
           when :array

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