rubocop 1.71.1 → 1.91.0

data/lib/rubocop/cop/naming/predicate_method.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Naming
+      # Checks that predicate methods end with `?` and non-predicate methods do not.
+      #
+      # The names of predicate methods (methods that return a boolean value) should end
+      # in a question mark. Methods that don't return a boolean shouldn't
+      # end in a question mark.
+      #
+      # The cop assesses a predicate method as one that returns boolean values. Likewise,
+      # a method that only returns literal values is assessed as non-predicate. Other predicate
+      # method calls are assumed to return boolean values. The cop does not make an assessment
+      # if the return type is unknown (non-predicate method calls, variables, etc.).
+      #
+      # NOTE: The `initialize` method and operator methods (`def ==`, etc.) are ignored.
+      #
+      # By default, the cop runs in `conservative` mode, which allows a method to be named
+      # with a question mark as long as at least one return value is boolean. In `aggressive`
+      # mode, methods with a question mark will register an offense if any known non-boolean
+      # return values are detected.
+      #
+      # The cop also has `AllowedMethods` configuration in order to prevent the cop from
+      # registering an offense from a method name that does not conform to the naming
+      # guidelines. By default, `call` is allowed. The cop also has `AllowedPatterns`
+      # configuration to allow method names by regular expression.
+      #
+      # Although returning a call to another predicate method is treated as a boolean value,
+      # certain method names can be known to not return a boolean, despite ending in a `?`
+      # (for example, `Numeric#nonzero?` returns `self` or `nil`). These methods can be
+      # configured using `NonBooleanPredicates`.
+      #
+      # The cop can furthermore be configured to allow all bang methods (method names
+      # ending with `!`), with `AllowBangMethods: true` (default false).
+      #
+      # @example Mode: conservative (default)
+      #   # bad
+      #   def foo
+      #     bar == baz
+      #   end
+      #
+      #   # good
+      #   def foo?
+      #     bar == baz
+      #   end
+      #
+      #   # bad
+      #   def foo?
+      #     5
+      #   end
+      #
+      #   # good
+      #   def foo
+      #     5
+      #   end
+      #
+      #   # bad
+      #   def foo
+      #     x == y
+      #   end
+      #
+      #   # good
+      #   def foo?
+      #     x == y
+      #   end
+      #
+      #   # bad
+      #   def foo
+      #     !x
+      #   end
+      #
+      #   # good
+      #   def foo?
+      #     !x
+      #   end
+      #
+      #   # bad - returns the value of another predicate method
+      #   def foo
+      #     bar?
+      #   end
+      #
+      #   # good
+      #   def foo?
+      #     bar?
+      #   end
+      #
+      #   # good - operator method
+      #   def ==(other)
+      #     hash == other.hash
+      #   end
+      #
+      #   # good - at least one return value is boolean
+      #   def foo?
+      #     return unless bar?
+      #     true
+      #   end
+      #
+      #   # ok - return type is not known
+      #   def foo?
+      #     bar
+      #   end
+      #
+      #   # ok - return type is not known
+      #   def foo
+      #     bar?
+      #   end
+      #
+      # @example Mode: aggressive
+      #   # bad - the method returns nil in some cases
+      #   def foo?
+      #     return unless bar?
+      #     true
+      #   end
+      #
+      # @example AllowedMethods: [call] (default)
+      #   # good
+      #   def call
+      #     foo == bar
+      #   end
+      #
+      # @example AllowedPatterns: [\Afoo]
+      #   # good
+      #   def foo?
+      #     'foo'
+      #   end
+      #
+      # @example AllowBangMethods: false (default)
+      #   # bad
+      #   def save!
+      #     true
+      #   end
+      #
+      # @example AllowBangMethods: true
+      #   # good
+      #   def save!
+      #     true
+      #   end
+      #
+      # @example WaywardPredicates: ['infinite?', 'nonzero?'] (default)
+      #   # good
+      #   def non_predicate_method(num)
+      #     num.infinite?
+      #   end
+      #
+      #   # good
+      #   def non_predicate_method(num)
+      #     num.nonzero?
+      #   end
+      #
+      class PredicateMethod < Base
+        include AllowedMethods
+        include AllowedPattern
+
+        MSG_PREDICATE = 'Predicate method names should end with `?`.'
+        MSG_NON_PREDICATE = 'Non-predicate method names should not end with `?`.'
+
+        def on_def(node)
+          return if allowed?(node)
+
+          return_values = return_values(node.body)
+          return if acceptable?(return_values)
+
+          if node.predicate_method? && potential_non_predicate?(return_values)
+            add_offense(node.loc.name, message: MSG_NON_PREDICATE)
+          elsif !node.predicate_method? && all_return_values_boolean?(return_values)
+            add_offense(node.loc.name, message: MSG_PREDICATE)
+          end
+        end
+        alias on_defs on_def
+
+        private
+
+        def allowed?(node)
+          node.method?(:initialize) ||
+            allowed_method?(node.method_name) ||
+            matches_allowed_pattern?(node.method_name) ||
+            allowed_bang_method?(node) ||
+            node.operator_method? ||
+            node.body.nil?
+        end
+
+        def acceptable?(return_values)
+          # In `conservative` mode, if the method returns `super`, `zsuper`, or a
+          # non-comparison method call, the method name is acceptable.
+          return false unless conservative?
+
+          return_values.any? do |value|
+            value.type?(:super, :zsuper) || unknown_method_call?(value)
+          end
+        end
+
+        def unknown_method_call?(value)
+          return false unless value.call_type?
+
+          !method_returning_boolean?(value)
+        end
+
+        def return_values(node)
+          # Collect all the (implicit and explicit) return values of a node
+          return_values = Set.new(node.begin_type? ? [] : [extract_return_value(node)])
+
+          node.each_descendant(:return) do |return_node|
+            return_values << extract_return_value(return_node)
+          end
+
+          return_values << last_value(node)
+
+          process_return_values(return_values)
+        end
+
+        def all_return_values_boolean?(return_values)
+          values = return_values.reject { |value| value.type?(:super, :zsuper) }
+          return false if values.empty?
+
+          values.all? { |value| boolean_return?(value) }
+        end
+
+        def boolean_return?(value)
+          return true if value.boolean_type?
+
+          method_returning_boolean?(value)
+        end
+
+        def method_returning_boolean?(value)
+          return false unless value.call_type?
+          return false if wayward_predicate?(value.method_name)
+
+          value.comparison_method? || value.predicate_method? || value.negation_method?
+        end
+
+        def potential_non_predicate?(return_values)
+          # Assumes a method to be non-predicate if all return values are non-boolean literals.
+          #
+          # In `Mode: conservative`, if any of the return values is a boolean,
+          # the method name is acceptable.
+          # In `Mode: aggressive`, all return values must be booleans for a predicate
+          # method, or else an offense will be registered.
+          return false if conservative? && return_values.any? { |value| boolean_return?(value) }
+
+          return_values.any? do |value|
+            value.literal? && !value.boolean_type?
+          end
+        end
+
+        def extract_return_value(node)
+          return node unless node.return_type?
+
+          # `return` without a value is a `nil` return.
+          return s(:nil) if node.arguments.empty?
+
+          # When there's a multiple return, it cannot be a predicate
+          # so just return an `array` sexp for simplicity.
+          return s(:array) unless node.arguments.one?
+
+          node.first_argument
+        end
+
+        def last_value(node)
+          value = node.begin_type? ? node.children.last || s(:nil) : node
+
+          value.return_type? ? extract_return_value(value) : value
+        end
+
+        def process_return_values(return_values)
+          return_values.flat_map do |value|
+            if value.conditional?
+              process_return_values(extract_conditional_branches(value))
+            elsif and_or?(value)
+              process_return_values(extract_and_or_clauses(value))
+            else
+              value
+            end
+          end
+        end
+
+        def and_or?(node)
+          node.type?(:and, :or)
+        end
+
+        def extract_and_or_clauses(node)
+          # Recursively traverse an `and` or `or` node to collect all clauses within
+          return node unless and_or?(node)
+
+          [extract_and_or_clauses(node.lhs), extract_and_or_clauses(node.rhs)].flatten
+        end
+
+        def extract_conditional_branches(node)
+          return node unless node.conditional?
+
+          if node.type?(:while, :until)
+            # If there is no body, act as implicit `nil`.
+            node.body ? [last_value(node.body)] : [s(:nil)]
+          else
+            # Branches with no value act as an implicit `nil`.
+            branches = node.branches.map { |branch| branch ? last_value(branch) : s(:nil) }
+            # Missing else branches also act as an implicit `nil`.
+            branches.push(s(:nil)) unless node.else_branch
+            branches
+          end
+        end
+
+        def conservative?
+          cop_config.fetch('Mode', :conservative).to_sym == :conservative
+        end
+
+        def allowed_bang_method?(node)
+          return false unless allow_bang_methods?
+
+          node.bang_method?
+        end
+
+        def allow_bang_methods?
+          cop_config.fetch('AllowBangMethods', false)
+        end
+
+        # If a method ending in `?` is known to not return a boolean value,
+        # (for example, `Numeric#nonzero?`) it should be treated as a non-boolean
+        # value, despite the method naming.
+        def wayward_predicate?(name)
+          wayward_predicates.include?(name.to_s)
+        end
+
+        def wayward_predicates
+          Array(cop_config.fetch('WaywardPredicates', []))
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/naming/{predicate_name.rb → predicate_prefix.rb}

@@ -17,6 +17,15 @@ module RuboCop
       # they end with a `?`. These methods should be changed to remove the
       # prefix.
       #
+      # When `UseSorbetSigs` is set to true (optional), the cop will only report
+      # offenses if the method has a Sorbet `sig` with a return type of
+      # `T::Boolean`. Dynamic methods are not supported with this configuration.
+      #
+      # When `AllCops/UseProjectIndex` is enabled and the `rubydex` gem is
+      # installed, methods that override a method defined by an ancestor
+      # elsewhere in the project are not reported, since renaming an override
+      # breaks the inherited contract.
+      #
       # @example NamePrefix: ['is_', 'has_', 'have_'] (default)
       #   # bad
       #   def is_even(value)
@@ -58,6 +67,30 @@ module RuboCop
       #   def is_even?(value)
       #   end
       #
+      # @example UseSorbetSigs: false (default)
+      #   # bad
+      #   sig { returns(String) }
+      #   def is_this_thing_on
+      #     "yes"
+      #   end
+      #
+      #   # good - Sorbet signature is not evaluated
+      #   sig { returns(String) }
+      #   def is_this_thing_on?
+      #     "yes"
+      #   end
+      #
+      # @example UseSorbetSigs: true
+      #   # bad
+      #   sig { returns(T::Boolean) }
+      #   def odd(value)
+      #   end
+      #
+      #   # good
+      #   sig { returns(T::Boolean) }
+      #   def odd?(value)
+      #   end
+      #
       # @example MethodDefinitionMacros: ['define_method', 'define_singleton_method'] (default)
       #   # bad
       #   define_method(:is_even) { |value| }
@@ -72,12 +105,13 @@ module RuboCop
       #   # good
       #   def_node_matcher(:even?) { |value| }
       #
-      class PredicateName < Base
+      class PredicatePrefix < Base
+        include ProjectIndexHelp
         include AllowedMethods
 
         # @!method dynamic_method_define(node)
         def_node_matcher :dynamic_method_define, <<~PATTERN
-          (send nil? #method_definition_macros
+          (send nil? #method_definition_macro?
             (sym $_)
             ...)
         PATTERN
@@ -96,17 +130,24 @@ module RuboCop
         end
 
         def on_def(node)
-          predicate_prefixes.each do |prefix|
-            method_name = node.method_name.to_s
-
-            next if allowed_method_name?(method_name, prefix)
+          method_name = node.method_name.to_s
+          offending_prefixes = offending_prefixes_for(node, method_name)
+          return if offending_prefixes.empty? || overrides_inherited_method?(node)
 
+          offending_prefixes.each do |prefix|
             add_offense(
               node.loc.name,
               message: message(method_name, expected_name(method_name, prefix))
             )
           end
         end
+
+        def offending_prefixes_for(node, method_name)
+          predicate_prefixes.reject do |prefix|
+            allowed_method_name?(method_name, prefix) ||
+              (use_sorbet_sigs? && !sorbet_sig?(node, return_type: 'T::Boolean'))
+          end
+        end
         alias on_defs on_def
 
         def validate_config
@@ -114,13 +155,24 @@ module RuboCop
             next if predicate_prefixes.include?(forbidden_prefix)
 
             raise ValidationError, <<~MSG.chomp
-              The `Naming/PredicateName` cop is misconfigured. Prefix #{forbidden_prefix} must be included in NamePrefix because it is included in ForbiddenPrefixes.
+              The `Naming/PredicatePrefix` cop is misconfigured. Prefix #{forbidden_prefix} must be included in NamePrefix because it is included in ForbiddenPrefixes.
             MSG
           end
         end
 
         private
 
+        # @!method sorbet_return_type(node)
+        def_node_matcher :sorbet_return_type, <<~PATTERN
+          (block (send nil? :sig) args (send _ :returns $_type))
+        PATTERN
+
+        def sorbet_sig?(node, return_type: nil)
+          return false unless (type = sorbet_return_type(node.left_sibling))
+
+          type.source == return_type
+        end
+
         def allowed_method_name?(method_name, prefix)
           !(method_name.start_with?(prefix) && # cheap check to avoid allocating Regexp
               method_name.match?(/^#{prefix}[^0-9]/)) ||
@@ -151,9 +203,29 @@ module RuboCop
           cop_config['NamePrefix']
         end
 
-        def method_definition_macros(macro_name)
+        def use_sorbet_sigs?
+          cop_config['UseSorbetSigs']
+        end
+
+        def method_definition_macro?(macro_name)
           cop_config['MethodDefinitionMacros'].include?(macro_name.to_s)
         end
+
+        # When `AllCops/UseProjectIndex` is enabled, methods that override a
+        # method defined by an ancestor elsewhere in the project are not
+        # reported: renaming an override breaks the inherited contract.
+        def overrides_inherited_method?(node)
+          return false unless project_index
+          return false unless (namespace_node = node.each_ancestor(:class, :module).first)
+
+          declaration = resolve_constant_in_index(namespace_node.identifier)
+          return false unless declaration.is_a?(Rubydex::Namespace)
+
+          scope = node.defs_type? ? indexed_singleton_of(declaration) : declaration
+          !scope.nil? && inherited_index_member?(scope, "#{node.method_name}()")
+        rescue StandardError
+          false
+        end
       end
     end
   end

data/lib/rubocop/cop/naming/rescued_exceptions_variable_name.rb

@@ -3,7 +3,7 @@
 module RuboCop
   module Cop
     module Naming
-      # Makes sure that rescued exceptions variables are named as
+      # Makes sure that rescued exception variables are named as
       # expected.
       #
       # The `PreferredName` config option takes a `String`. It represents
@@ -95,11 +95,14 @@ module RuboCop
 
         def autocorrect(corrector, node, range, offending_name, preferred_name)
           corrector.replace(range, preferred_name)
-          correct_node(corrector, node.body, offending_name, preferred_name)
+          # Once the exception variable is reassigned, later references point to a
+          # different value, so stop correcting after the reassignment - both in the
+          # body and in the code following the `begin`/`rescue`.
+          return if correct_node(corrector, node.body, offending_name, preferred_name)
           return unless (kwbegin_node = node.parent.each_ancestor(:kwbegin).first)
 
           kwbegin_node.right_siblings.each do |child_node|
-            correct_node(corrector, child_node, offending_name, preferred_name)
+            break if correct_node(corrector, child_node, offending_name, preferred_name)
           end
         end
 
@@ -113,7 +116,9 @@ module RuboCop
           end
         end
 
-        # rubocop:disable Metrics/MethodLength
+        # Returns the reassignment node once the exception variable is reassigned (a truthy
+        # signal to stop correcting later references), or `nil` when no reassignment is found.
+        # rubocop:disable-next Metrics/MethodLength
         def correct_node(corrector, node, offending_name, preferred_name)
           return unless node
 
@@ -131,11 +136,11 @@ module RuboCop
 
             if child_node.type?(:masgn, :lvasgn)
               correct_reassignment(corrector, child_node, offending_name, preferred_name)
-              break
+              return child_node
             end
           end
+          nil
         end
-        # rubocop:enable Metrics/MethodLength
 
         # If the exception variable is reassigned, that assignment needs to be corrected.
         # Further `lvar` nodes will not be corrected though since they now refer to a

data/lib/rubocop/cop/naming/variable_name.rb

@@ -3,8 +3,15 @@
 module RuboCop
   module Cop
     module Naming
-      # Makes sure that all variables use the configured style,
-      # snake_case or camelCase, for their names.
+      # Checks that the configured style (snake_case or camelCase) is used for all variable names.
+      # This includes local variables, instance variables, class variables, method arguments
+      # (positional, keyword, rest or block), and block arguments.
+      #
+      # The cop can also be configured to forbid using specific names for variables, using
+      # `ForbiddenIdentifiers` or `ForbiddenPatterns`. In addition to the above, this applies
+      # to global variables as well.
+      #
+      # Method definitions and method calls are not affected by this cop.
       #
       # @example EnforcedStyle: snake_case (default)
       #   # bad
@@ -26,24 +33,45 @@ module RuboCop
       #
       # @example AllowedPatterns: ['_v\d+\z']
       #   # good (with EnforcedStyle: camelCase)
-      #   :release_v1
+      #   release_v1 = true
+      #
+      # @example ForbiddenIdentifiers: ['fooBar']
+      #   # bad (in all cases)
+      #   fooBar = 1
+      #   @fooBar = 1
+      #   @@fooBar = 1
+      #   $fooBar = 1
+      #
+      # @example ForbiddenPatterns: ['_v\d+\z']
+      #   # bad (in all cases)
+      #   release_v1 = true
+      #   @release_v1 = true
+      #   @@release_v1 = true
+      #   $release_v1 = true
       #
       class VariableName < Base
         include AllowedIdentifiers
         include ConfigurableNaming
         include AllowedPattern
+        include ForbiddenIdentifiers
+        include ForbiddenPattern
 
         MSG = 'Use %<style>s for variable names.'
+        MSG_FORBIDDEN = '`%<identifier>s` is forbidden, use another name instead.'
 
         def valid_name?(node, name, given_style = style)
           super || matches_allowed_pattern?(name)
         end
 
         def on_lvasgn(node)
-          return unless node.name
-          return if allowed_identifier?(node.name)
+          return unless (name = node.name)
+          return if allowed_identifier?(name)
 
-          check_name(node, node.name, node.loc.name)
+          if forbidden_name?(name)
+            register_forbidden_name(node)
+          else
+            check_name(node, name, node.loc.name)
+          end
         end
         alias on_ivasgn    on_lvasgn
         alias on_cvasgn    on_lvasgn
@@ -56,11 +84,28 @@ module RuboCop
         alias on_blockarg  on_lvasgn
         alias on_lvar      on_lvasgn
 
+        # Only forbidden names are checked for global variable assignment
+        def on_gvasgn(node)
+          return unless (name = node.name)
+          return unless forbidden_name?(name)
+
+          register_forbidden_name(node)
+        end
+
         private
 
+        def forbidden_name?(name)
+          forbidden_identifier?(name) || forbidden_pattern?(name)
+        end
+
         def message(style)
           format(MSG, style: style)
         end
+
+        def register_forbidden_name(node)
+          message = format(MSG_FORBIDDEN, identifier: node.name)
+          add_offense(node.loc.name, message: message)
+        end
       end
     end
   end

data/lib/rubocop/cop/naming/variable_number.rb

@@ -132,7 +132,9 @@ module RuboCop
 
         def on_sym(node)
           @node = node
-          return if allowed_identifier?(node.value)
+
+          # Prism parses a quoted empty hash key (`{ "": value }`) as an empty symbol node.
+          return if node.value.empty? || allowed_identifier?(node.value)
 
           check_name(node, node.value, node) if cop_config['CheckSymbols']
         end

data/lib/rubocop/cop/naming.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    # Cops for the `Naming` department. The department's cops are registered for lazy loading
+    # and their files are loaded on demand.
+    module Naming
+      extend LazyLoader
+
+      register_cop :AccessorMethodName, "#{__dir__}/naming/accessor_method_name"
+      register_cop :AsciiIdentifiers, "#{__dir__}/naming/ascii_identifiers"
+      register_cop :BlockForwarding, "#{__dir__}/naming/block_forwarding"
+      register_cop :BlockParameterName, "#{__dir__}/naming/block_parameter_name"
+      register_cop :ClassAndModuleCamelCase, "#{__dir__}/naming/class_and_module_camel_case"
+      register_cop :ConstantName, "#{__dir__}/naming/constant_name"
+      register_cop :FileName, "#{__dir__}/naming/file_name"
+      register_cop :HeredocDelimiterCase, "#{__dir__}/naming/heredoc_delimiter_case"
+      register_cop :HeredocDelimiterNaming, "#{__dir__}/naming/heredoc_delimiter_naming"
+      register_cop :InclusiveLanguage, "#{__dir__}/naming/inclusive_language"
+      register_cop :MemoizedInstanceVariableName, "#{__dir__}/naming/memoized_instance_variable_name"
+      register_cop :MethodName, "#{__dir__}/naming/method_name"
+      register_cop :MethodParameterName, "#{__dir__}/naming/method_parameter_name"
+      register_cop :BinaryOperatorParameterName, "#{__dir__}/naming/binary_operator_parameter_name"
+      register_cop :PredicateMethod, "#{__dir__}/naming/predicate_method"
+      register_cop :PredicatePrefix, "#{__dir__}/naming/predicate_prefix"
+      register_cop :RescuedExceptionsVariableName, "#{__dir__}/naming/rescued_exceptions_variable_name"
+      register_cop :VariableName, "#{__dir__}/naming/variable_name"
+      register_cop :VariableNumber, "#{__dir__}/naming/variable_number"
+    end
+  end
+end