rubocop 1.88.2 → 1.90.0

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

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Lint
+      # Checks for private instance methods that are not referenced anywhere
+      # in the project.
+      #
+      # 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.
+      #
+      # A method counts as referenced when a call with its name appears anywhere
+      # in the indexed project (regardless of the receiver), when it is the source
+      # of an `alias`, or when its name appears in the same file as a symbol or
+      # inside a string literal (covering `send(:name)` and declarative DSLs like
+      # `before_action :name`). An interpolated symbol or string with a literal
+      # prefix (e.g. `send(:"format_#{type}")`) counts as a reference to every
+      # method whose name starts with that prefix; fully dynamic names cannot
+      # be detected. Methods defined in classes or modules with descendants are
+      # not checked, since they may be invoked through `super` or inherited
+      # dispatch.
+      #
+      # Methods whose names are composed by a framework (e.g. Rails
+      # `attribute_method_suffix` generating `attribute?` methods) can be
+      # excluded from the check with `AllowedNames` (exact names) or
+      # `AllowedPatterns` (regular expressions).
+      #
+      # The cop is disabled by default because symbol-based references from
+      # *other* files (e.g. a Rails callback declared in a concern) cannot be
+      # detected and would be reported as false positives. It is best suited
+      # for occasional dead-code sweeps rather than permanent enforcement.
+      #
+      # @example
+      #   # bad - `helper` is never referenced anywhere in the project
+      #   class Service
+      #     def call
+      #       do_something
+      #     end
+      #
+      #     private
+      #
+      #     def helper
+      #     end
+      #   end
+      #
+      #   # good
+      #   class Service
+      #     def call
+      #       do_something(helper)
+      #     end
+      #
+      #     private
+      #
+      #     def helper
+      #     end
+      #   end
+      #
+      # @example AllowedNames: ['attribute?']
+      #   # good - the name is explicitly allowed
+      #   class Contact
+      #     private
+      #
+      #     def attribute?
+      #     end
+      #   end
+      #
+      # @example AllowedPatterns: ['_hook\z']
+      #   # good - the name matches an allowed pattern
+      #   class Service
+      #     private
+      #
+      #     def before_save_hook
+      #     end
+      #   end
+      #
+      class UnusedPrivateMethod < Base
+        include AllowedPattern
+        include ProjectIndexHelp
+
+        MSG = 'Private method `%<method>s` appears to be unused.'
+
+        IDENTIFIER_PATTERN = /[a-zA-Z_]\w*[?!=]?/.freeze
+        NAME_PREFIX_PATTERN = /[a-zA-Z_]\w*\z/.freeze
+
+        # Methods invoked implicitly by the Ruby runtime.
+        IMPLICITLY_INVOKED_METHODS = %i[
+          initialize initialize_copy initialize_clone initialize_dup
+          method_missing respond_to_missing? marshal_dump marshal_load
+          coerce instance_variables_to_inspect
+          inherited included extended prepended
+          append_features extend_object prepend_features
+          const_missing const_added
+          method_added method_removed method_undefined
+          singleton_method_added singleton_method_removed singleton_method_undefined
+        ].to_set.freeze
+
+        class << self
+          # The reference-name set is a property of the index, not of the cop
+          # instance, so all per-file instances share one computation. A
+          # single-entry cache (instead of a hash keyed by index) avoids
+          # retaining stale graphs in long-lived processes.
+          attr_accessor :cached_reference_names
+        end
+
+        def on_new_investigation
+          @literal_names = nil
+          @literal_name_prefixes = nil
+          super
+        end
+
+        def on_def(node)
+          return unless project_index
+
+          declaration = checkable_declaration(node)
+          return unless declaration
+          return if referenced?(node.method_name)
+          return if owner_with_descendants?(declaration) || override?(declaration, node.method_name)
+
+          message = format(MSG, method: node.method_name)
+          add_offense(node.loc.keyword.join(node.loc.name), message: message)
+        end
+
+        private
+
+        def checkable_declaration(node)
+          return nil if IMPLICITLY_INVOKED_METHODS.include?(node.method_name)
+          return nil if allowed_name?(node.method_name)
+          return nil if node.each_ancestor(:any_def, :any_block, :sclass).any?
+          return nil unless (namespace_node = node.each_ancestor(:class, :module).first)
+
+          declaration = method_declaration(node, namespace_node)
+          declaration if declaration&.private?
+        end
+
+        def allowed_name?(method_name)
+          name = method_name.to_s
+
+          cop_config.fetch('AllowedNames', []).include?(name) || matches_allowed_pattern?(name)
+        end
+
+        def method_declaration(node, namespace_node)
+          namespace = resolve_constant_in_index(namespace_node.identifier)
+          return nil unless namespace.is_a?(Rubydex::Namespace)
+
+          namespace.member("#{node.method_name}()")
+        end
+
+        def referenced?(method_name)
+          name = method_name.to_s
+
+          referenced_names.include?(name) || literal_names.include?(name) ||
+            literal_name_prefixes.any? { |prefix| name.start_with?(prefix) }
+        end
+
+        def referenced_names
+          index, names = self.class.cached_reference_names
+          return names if index.equal?(project_index)
+
+          compute_referenced_names.tap do |computed|
+            self.class.cached_reference_names = [project_index, computed]
+          end
+        end
+
+        def compute_referenced_names
+          project_index.method_references
+                       .to_set { |reference| reference.name.delete_suffix('()') }
+        end
+
+        # Symbol literals and identifier-like tokens inside string literals in the
+        # current file, covering `send(:name)`, declarative DSLs like
+        # `before_action :name` and names embedded in strings (e.g. node-pattern
+        # `#helper` references).
+        def literal_names
+          @literal_names ||=
+            processed_source.ast.each_descendant(:sym, :str)
+                            .with_object(Set.new) do |literal, names|
+              if literal.sym_type?
+                names << literal.value.to_s
+              else
+                # `scan` raises on binary string literals with invalid byte sequences.
+                value = literal.value
+                value = value.scrub unless value.valid_encoding?
+                value.scan(IDENTIFIER_PATTERN) { |token| names << token }
+              end
+            end
+        end
+
+        # The leading literal fragment of an interpolated symbol or string acts
+        # as a method-name prefix: `send(:"format_#{type}")` may invoke any
+        # method whose name starts with `format_`. Only the leading fragment
+        # qualifies (a mid-string fragment is not a name prefix), and a fully
+        # dynamic name contributes nothing.
+        def literal_name_prefixes
+          @literal_name_prefixes ||=
+            processed_source.ast.each_descendant(:dsym, :dstr)
+                            .with_object(Set.new) do |literal, prefixes|
+              prefix = interpolation_prefix(literal)
+              prefixes << prefix if prefix
+            end
+        end
+
+        def interpolation_prefix(node)
+          return nil if node.children.all?(&:str_type?)
+
+          leading_fragment = node.children.first
+          return nil unless leading_fragment&.str_type?
+
+          leading_fragment.value[NAME_PREFIX_PATTERN]
+        end
+
+        # A method defined in a class or module with descendants may be invoked
+        # through `super` or inherited dispatch, which the index does not track.
+        def owner_with_descendants?(declaration)
+          owner = declaration.owner
+          return false unless owner.is_a?(Rubydex::Namespace)
+
+          owner.descendants.any? { |descendant| descendant.name != owner.name }
+        end
+
+        # An override of an inherited method may be invoked polymorphically
+        # (e.g. a framework hook), even when no direct reference exists.
+        def override?(declaration, method_name)
+          owner = declaration.owner
+          return false unless owner.is_a?(Rubydex::Namespace)
+
+          owner.ancestors.any? do |ancestor|
+            ancestor.name != owner.name && ancestor.member("#{method_name}()")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -210,7 +210,7 @@ module RuboCop
           end
         end
 
-        # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         def check_child_nodes(node, unused, cur_vis)
           node.child_nodes.each do |child|
             if child.send_type? && access_modifier?(child)
@@ -228,7 +228,6 @@ module RuboCop
 
           [cur_vis, unused]
         end
-        # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
         def check_send_node(node, cur_vis, unused)
           if node.bare_access_modifier?

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

@@ -173,7 +173,7 @@ module RuboCop
           node.receiver.nil? && !node.arguments?
         end
 
-        # rubocop:disable Metrics/AbcSize
+        # rubocop:disable-next Metrics/AbcSize
         def autocorrect(corrector, assignment)
           if assignment.exception_assignment?
             remove_exception_assignment_part(corrector, assignment.node)
@@ -189,7 +189,6 @@ module RuboCop
             remove_local_variable_assignment_part(corrector, assignment.node)
           end
         end
-        # rubocop:enable Metrics/AbcSize
 
         def remove_exception_assignment_part(corrector, node)
           range = node.parent.children.first&.source_range || node.parent.location.keyword

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

@@ -10,6 +10,11 @@ module RuboCop
       # It does not support autocorrection due to behavior change and multiple ways to fix it.
       # Or a public constant may be intended.
       #
+      # Constant assignments that define classes or modules via `Class.new`, `Module.new`,
+      # `Struct.new`, or `Data.define` are allowed. Those forms are class and module definitions
+      # written with assignment syntax, and match the common practice of placing nested
+      # `class` / `module` bodies after `private` without intending private constant visibility.
+      #
       # @example
       #
       #   # bad
@@ -29,6 +34,19 @@ module RuboCop
       #     PUBLIC_CONST = 42 # If private scope is not intended.
       #   end
       #
+      #   # good - class/module definitions via assignment, same as nested `class`/`module`
+      #   class Foo
+      #     private
+      #
+      #     def some_private_method
+      #     end
+      #
+      #     MyClass = Class.new
+      #     MyModule = Module.new
+      #     MyStruct = Struct.new(:name)
+      #     MyData = Data.define(:name)
+      #   end
+      #
       class UselessConstantScoping < Base
         MSG = 'Useless `private` access modifier for constant scope.'
 
@@ -37,9 +55,27 @@ module RuboCop
           (send nil? :private_constant $...)
         PATTERN
 
+        # Matches class/module-like constant assignments. Nested `class` / `module`
+        # keyword definitions are not visited by this cop; these assignment forms are
+        # the equivalent syntax and should be treated the same way.
+        # @!method class_or_module_definition_assignment?(node)
+        def_node_matcher :class_or_module_definition_assignment?, <<~PATTERN
+          {
+            (send (const {nil? cbase} {:Class :Module :Struct}) :new ...)
+            (send (const {nil? cbase} :Data) :define ...)
+            (any_block
+              {
+                (send (const {nil? cbase} {:Class :Module :Struct}) :new ...)
+                (send (const {nil? cbase} :Data) :define ...)
+              }
+              ...)
+          }
+        PATTERN
+
         def on_casgn(node)
           return unless after_private_modifier?(node.left_siblings)
           return if private_constantize?(node.right_siblings, node.name)
+          return if class_or_module_definition_assignment?(node.expression)
 
           add_offense(node)
         end

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

@@ -59,7 +59,7 @@ module RuboCop
         end
 
         def use_rest_or_optional_args?(node)
-          node.arguments.any? { |arg| arg.type?(:restarg, :optarg, :kwoptarg) }
+          node.arguments.any? { |arg| arg.type?(:restarg, :optarg, :kwoptarg, :kwrestarg) }
         end
 
         def delegating?(node, def_node)

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

@@ -56,7 +56,7 @@ module RuboCop
 
         private
 
-        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
+        # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity
         def only_reraising?(resbody_node)
           return false if use_exception_variable_in_ensure?(resbody_node)
 
@@ -70,7 +70,6 @@ module RuboCop
 
           exception_objects(resbody_node).include?(exception_name)
         end
-        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity
 
         def use_exception_variable_in_ensure?(resbody_node)
           return false unless (exception_variable = resbody_node.exception_variable)

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

@@ -116,6 +116,8 @@ module RuboCop
             # so stop searching once a class/module boundary is crossed without a match.
             return nil if ancestor.type?(:class, :module, :sclass)
           end
+
+          nil
         end
 
         # `ruby2_keywords` is only allowed if there's a `restarg` and no keyword arguments

data/lib/rubocop/cop/lint/utils/nil_receiver_checker.rb

@@ -12,6 +12,8 @@ module RuboCop
             @receiver = receiver
             @additional_nil_methods = additional_nil_methods
             @checked_nodes = {}.compare_by_identity
+            @receiver_binding_name = binding_name(receiver)
+            @receiver_binding_scope = binding_scope(receiver) if @receiver_binding_name
           end
 
           def cant_be_nil?
@@ -20,7 +22,7 @@ module RuboCop
 
           private
 
-          # rubocop:disable Metrics
+          # rubocop:disable-next Metrics
           def _cant_be_nil?(node, receiver)
             return false unless node
 
@@ -34,7 +36,9 @@ module RuboCop
             when :def, :defs, :class, :module, :sclass
               return false
             when :send
-              return non_nil_method?(node.method_name) if node.receiver == receiver
+              if node.receiver == receiver && same_binding_as_receiver?(node.receiver)
+                return non_nil_method?(node.method_name)
+              end
 
               node.arguments.each do |argument|
                 return true if _cant_be_nil?(argument, receiver)
@@ -74,13 +78,12 @@ module RuboCop
               false
             end
           end
-          # rubocop:enable Metrics
 
           def non_nil_method?(method_name)
             !NIL_METHODS.include?(method_name) && !@additional_nil_methods.include?(method_name)
           end
 
-          # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+          # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
           def sole_condition_of_parent_if?(node)
             child = node
             parent = node.parent
@@ -104,12 +107,63 @@ module RuboCop
 
             false
           end
-          # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
           def non_nil_condition?(condition, node)
-            return true if condition == node
+            return true if condition == node && same_binding_as_receiver?(condition)
+            return false unless condition.csend_type?
+
+            root_receiver = csend_root_receiver(condition)
+
+            root_receiver == node && same_binding_as_receiver?(root_receiver)
+          end
+
+          # Structurally equal occurrences can be different variables: `it` binds to
+          # its innermost block, and a block parameter can shadow an outer variable of
+          # the same name. Evidence about such a receiver only holds when both occurrences
+          # resolve to the same binding.
+          def same_binding_as_receiver?(occurrence)
+            return true unless @receiver_binding_name
+
+            binding_scope(occurrence).equal?(@receiver_binding_scope)
+          end
+
+          # The name whose binding can differ between structurally equal occurrences:
+          # a local variable (block parameters included), or a bare `it` call, which is
+          # how `it` parses when the target Ruby version is below 3.4 even though the code
+          # may run on 3.4+ where `it` is the implicit block parameter.
+          def binding_name(node)
+            if node.lvar_type?
+              node.children.first
+            elsif node.send_type? && !node.receiver && node.method?(:it) && node.arguments.empty?
+              :it
+            end
+          end
+
+          def binding_scope(occurrence)
+            node = occurrence
+
+            while (parent = node.parent)
+              case parent.type
+              when :block, :numblock, :itblock
+                # Only the body is inside the block's scope; the send node and the arguments of
+                # the block node evaluate in the outer scope.
+                return parent if parent.body.equal?(node) && block_binds_name?(parent)
+              when :def, :defs, :class, :module, :sclass
+                return parent
+              end
+
+              node = parent
+            end
+
+            nil
+          end
+
+          def block_binds_name?(block_node)
+            name = @receiver_binding_name
+
+            return true if block_node.argument_list.any? { |argument| argument.name == name }
 
-            condition.csend_type? && csend_root_receiver(condition) == node
+            name == :it && block_node.arguments.empty?
           end
 
           # Whether control reaches `node` by falling through its left siblings rather than by

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

@@ -16,11 +16,14 @@ module RuboCop
       # enumerator.each { |item| item >= 2 } #=> [2, 3]
       # ----
       #
-      # NOTE: Return values in assignment method definitions such as `def foo=(arg)` are
-      # detected because they are in a void context. However, autocorrection does not remove
-      # the return value, as that would change behavior. In such cases, whether to remove
-      # the return value or rename the method to something more appropriate should be left to
-      # the user.
+      # NOTE: The last expression in an assignment method definition such as `def foo=(arg)`
+      # is not flagged. Ruby discards it (the method returns its argument), but the method can
+      # still be called directly and its return value relied upon, so flagging it would be a
+      # false positive for this lint.
+      #
+      # NOTE: A constant used in a void context is flagged but not autocorrected, since
+      # referencing a constant can trigger autoloading side effects (e.g. forcing a file to
+      # load before a monkey-patch), so removing it may change behavior.
       #
       # @example CheckForMethodsWithNoSideEffects: false (default)
       #   # bad
@@ -109,7 +112,7 @@ module RuboCop
         def check_begin(node)
           expressions = *node
           inside_each_block = node.each_ancestor(:any_block).first&.method?(:each)
-          expressions.pop if !in_void_context?(node) || inside_each_block
+          expressions.pop if !in_void_context?(node) || inside_each_block || setter_method?(node)
           expressions.each do |expr|
             check_void_op(expr) { inside_each_block }
             check_expression(expr)
@@ -150,7 +153,7 @@ module RuboCop
           check_expression(case_node.else_branch) if case_node.else_branch
         end
 
-        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         def check_void_op(node, &block)
           node = node.children.first while node&.begin_type?
           return unless node&.call_type? && OPERATORS.include?(node.method_name)
@@ -165,7 +168,6 @@ module RuboCop
             autocorrect_void_op(corrector, node)
           end
         end
-        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
         def check_var(node)
           return unless node.variable? || node.const_type?
@@ -244,6 +246,10 @@ module RuboCop
           parent.respond_to?(:void_context?) && parent.void_context?
         end
 
+        def setter_method?(node)
+          node.parent&.any_def_type? && node.parent.assignment_method?
+        end
+
         def autocorrect_void_op(corrector, node)
           if node.arguments.empty?
             corrector.replace(node, node.receiver.source)
@@ -258,6 +264,10 @@ module RuboCop
         end
 
         def autocorrect_void_expression(corrector, node)
+          # Referencing a constant can trigger autoloading side effects (e.g. forcing a file
+          # to load before a monkey-patch), so removing it may change behavior. Flag but don't
+          # autocorrect, leaving it to the user.
+          return if node.const_type? && !node.special_keyword?
           return if node.parent.type?(:if, :case, :when, :case_match, :in_pattern)
           return if (def_node = node.each_ancestor(:any_def).first) && def_node.assignment_method?