rubocop 1.53.0 → 1.90.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_prefix.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Naming
+      # Checks that predicate method names end with a question mark and
+      # do not start with a forbidden prefix.
+      #
+      # A method is determined to be a predicate method if its name starts with
+      # one of the prefixes listed in the `NamePrefix` configuration. The list
+      # defaults to `is_`, `has_`, and `have_` but may be overridden.
+      #
+      # Predicate methods must end with a question mark.
+      #
+      # When `ForbiddenPrefixes` is also set (as it is by default), predicate
+      # methods which begin with a forbidden prefix are not allowed, even if
+      # 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)
+      #   end
+      #
+      #   # When ForbiddenPrefixes: ['is_', 'has_', 'have_'] (default)
+      #   # good
+      #   def even?(value)
+      #   end
+      #
+      #   # When ForbiddenPrefixes: []
+      #   # good
+      #   def is_even?(value)
+      #   end
+      #
+      # @example NamePrefix: ['seems_to_be_']
+      #   # bad
+      #   def seems_to_be_even(value)
+      #   end
+      #
+      #   # When ForbiddenPrefixes: ['seems_to_be_']
+      #   # good
+      #   def even?(value)
+      #   end
+      #
+      #   # When ForbiddenPrefixes: []
+      #   # good
+      #   def seems_to_be_even?(value)
+      #   end
+      #
+      # @example AllowedMethods: ['is_a?'] (default)
+      #   # Despite starting with the `is_` prefix, this method is allowed
+      #   # good
+      #   def is_a?(value)
+      #   end
+      #
+      # @example AllowedMethods: ['is_even?']
+      #   # good
+      #   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| }
+      #
+      #   # good
+      #   define_method(:even?) { |value| }
+      #
+      # @example MethodDefinitionMacros: ['def_node_matcher']
+      #   # bad
+      #   def_node_matcher(:is_even) { |value| }
+      #
+      #   # good
+      #   def_node_matcher(:even?) { |value| }
+      #
+      class PredicatePrefix < Base
+        include ProjectIndexHelp
+        include AllowedMethods
+
+        # @!method dynamic_method_define(node)
+        def_node_matcher :dynamic_method_define, <<~PATTERN
+          (send nil? #method_definition_macro?
+            (sym $_)
+            ...)
+        PATTERN
+
+        def on_send(node)
+          dynamic_method_define(node) do |method_name|
+            predicate_prefixes.each do |prefix|
+              next if allowed_method_name?(method_name.to_s, prefix)
+
+              add_offense(
+                node.first_argument,
+                message: message(method_name, expected_name(method_name.to_s, prefix))
+              )
+            end
+          end
+        end
+
+        def on_def(node)
+          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
+          forbidden_prefixes.each do |forbidden_prefix|
+            next if predicate_prefixes.include?(forbidden_prefix)
+
+            raise ValidationError, <<~MSG.chomp
+              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]/)) ||
+            method_name == expected_name(method_name, prefix) ||
+            method_name.end_with?('=') ||
+            allowed_method?(method_name)
+        end
+
+        def expected_name(method_name, prefix)
+          new_name = if forbidden_prefixes.include?(prefix)
+                       method_name.sub(prefix, '')
+                     else
+                       method_name.dup
+                     end
+          new_name << '?' unless method_name.end_with?('?')
+          new_name
+        end
+
+        def message(method_name, new_name)
+          "Rename `#{method_name}` to `#{new_name}`."
+        end
+
+        def forbidden_prefixes
+          cop_config['ForbiddenPrefixes']
+        end
+
+        def predicate_prefixes
+          cop_config['NamePrefix']
+        end
+
+        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
+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
 
@@ -109,35 +112,41 @@ module RuboCop
               variable_name_matches?(lvasgn_node, name)
             end
           else
-            node.children.first == name
+            node.name == name
           end
         end
 
+        # 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
 
           node.each_node(:lvar, :lvasgn, :masgn) do |child_node|
             next unless variable_name_matches?(child_node, offending_name)
 
-            corrector.replace(child_node, preferred_name) if child_node.lvar_type?
+            if child_node.lvar_type?
+              parent_node = child_node.parent
+              if parent_node.respond_to?(:value_omission?) && parent_node.value_omission?
+                corrector.insert_after(parent_node.loc.operator, " #{preferred_name}")
+              else
+                corrector.replace(child_node, preferred_name)
+              end
+            end
 
-            if child_node.masgn_type? || child_node.lvasgn_type?
+            if child_node.type?(:masgn, :lvasgn)
               correct_reassignment(corrector, child_node, offending_name, preferred_name)
-              break
+              return child_node
             end
           end
+          nil
         end
 
         # 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
         # different variable.
         def correct_reassignment(corrector, node, offending_name, preferred_name)
-          if node.lvasgn_type?
-            correct_node(corrector, node.child_nodes.first, offending_name, preferred_name)
-          elsif node.masgn_type?
-            # With multiple assign, the assignments are in an array as the last child
-            correct_node(corrector, node.children.last, offending_name, preferred_name)
-          end
+          correct_node(corrector, node.rhs, offending_name, preferred_name)
         end
 
         def preferred_name(variable_name)
@@ -150,10 +159,7 @@ module RuboCop
         end
 
         def variable_name(node)
-          asgn_node = node.exception_variable
-          return unless asgn_node
-
-          asgn_node.children.last
+          node.exception_variable.name if node.exception_variable.respond_to?(:name)
         end
 
         def message(node)