rubocop 1.52.1 → 1.79.2

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

@@ -0,0 +1,306 @@
+# 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: 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 confirm 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 AllowBangMethods: false (default)
+      #   # bad
+      #   def save!
+      #     true
+      #   end
+      #
+      # @example AllowBangMethods: true
+      #   # good
+      #   def save!
+      #     true
+      #   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)
+          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
+
+          last_value = last_value(node)
+          return_values << last_value if last_value
+
+          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 : 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,204 @@
+# 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` 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.
+      #
+      # @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 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)
+          predicate_prefixes.each do |prefix|
+            method_name = node.method_name.to_s
+
+            next if allowed_method_name?(method_name, prefix)
+            next if use_sorbet_sigs? && !sorbet_sig?(node, return_type: 'T::Boolean')
+
+            add_offense(
+              node.loc.name,
+              message: message(method_name, expected_name(method_name, prefix))
+            )
+          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
+      end
+    end
+  end
+end

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

@@ -109,35 +109,39 @@ module RuboCop
               variable_name_matches?(lvasgn_node, name)
             end
           else
-            node.children.first == name
+            node.name == name
           end
         end
 
+        # rubocop:disable 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
             end
           end
         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
         # 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 +154,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)

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,25 +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)
-          name, = *node
-          return unless name
+          return unless (name = node.name)
           return if allowed_identifier?(name)
 
-          check_name(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
@@ -57,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

@@ -113,10 +113,9 @@ module RuboCop
 
         def on_arg(node)
           @node = node
-          name, = *node
-          return if allowed_identifier?(name)
+          return if allowed_identifier?(node.name)
 
-          check_name(node, name, node.loc.name)
+          check_name(node, node.name, node.loc.name)
         end
         alias on_lvasgn on_arg
         alias on_ivasgn on_arg

data/lib/rubocop/cop/offense.rb

@@ -43,11 +43,10 @@ module RuboCop
       # @!attribute [r] cop_name
       #
       # @return [String]
-      #   a cop class name without department.
-      #   i.e. type of the violation.
+      #   the cop name as a String for which this offense is for.
       #
       # @example
-      #   'LineLength'
+      #   'Layout/LineLength'
       attr_reader :cop_name
 
       # @api private
@@ -97,8 +96,8 @@ module RuboCop
       # @!attribute [r] correctable?
       #
       # @return [Boolean]
-      #   whether this offense can be automatically corrected via
-      #   autocorrect or a todo.
+      #   whether this offense can be automatically corrected via autocorrect.
+      #   This includes todo comments, for example when requested with `--disable-uncorrectable`.
       def correctable?
         @status != :unsupported
       end