rubocop-callbacksystems 0.1.0

data/lib/rubocop/cop/callbacksystems/prefer_it_block_parameter.rb

@@ -0,0 +1,156 @@
+# Detects single-line brace blocks with a single parameter that should use `it`
+# instead. Since Ruby 3.4 a block can read its one parameter as `it`, and on a
+# single line a name for it only repeats what the receiver already said.
+#
+# @example
+#   # bad
+#   items.map { |item| item.name }
+#   users.select { |user| user.active? }
+#   items.each { |item| process(item) }
+#   numbers.map { |n| n.to_s }
+#
+#   # good
+#   items.map { it.name }
+#   users.select { it.active? }
+#   items.each { process(it) }
+#   numbers.map { it.to_s }
+#
+#   # good - multi-line block
+#   items.map do |item|
+#     item.name
+#   end
+#
+#   # good - multiple parameters
+#   hash.each { |key, value| puts key }
+#
+#   # good - lambda or proc, where the parameter name documents the signature
+#   double = ->(number) { number * 2 }
+#   greet = proc { |name| puts name }
+#
+#   # good - define_method, where the block sets the defined method's signature
+#   define_method(:double) { |number| number * 2 }
+#
+class RuboCop::Cop::Callbacksystems::PreferItBlockParameter < RuboCop::Cop::Callbacksystems::Base
+  extend RuboCop::Cop::AutoCorrector
+
+  def on_block(node)
+    report NamedParameterBlock.new(node)
+  end
+
+  alias on_numblock on_block
+  alias on_itblock on_block
+
+  private
+    class NamedParameterBlock
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "Use `it` instead of explicit block parameter `|%<parameter>s|`."
+      METHOD_DEFINITIONS = %i[ define_method define_singleton_method ]
+
+      def initialize(node)
+        @node = node
+      end
+
+      def offense
+        offense_for_parameter if convertible?
+      end
+
+      private
+        attr_reader :node
+
+        def convertible?
+          single_line_braced? && single_replaceable_parameter? &&
+            !node.lambda_or_proc? && !method_definition? && !nested_in_convertible_block? &&
+            !read_inside_an_inner_block? && !it_has_an_existing_meaning?
+        end
+
+        def single_line_braced?
+          node.body && node.braces? && node.single_line?
+        end
+
+        def single_replaceable_parameter?
+          node.arguments.size == 1 && node.first_argument.arg_type? && !parameter_reassigned?
+        end
+
+        def parameter_reassigned?
+          nodes_in(node.body, :lvasgn, :match_var).any? { it.children.first == parameter_name }
+        end
+
+        def parameter_name
+          node.first_argument.name
+        end
+
+        def method_definition?
+          METHOD_DEFINITIONS.include?(node.method_name)
+        end
+
+        def nested_in_convertible_block?
+          node.each_ancestor(:any_block).any? { it.arguments.size == 1 && it.braces? && it.single_line? }
+        end
+
+        def read_inside_an_inner_block?
+          parameter_reads.any? { |read| read.each_ancestor(*BLOCK_NODE_TYPES).take_while { !it.equal?(node) }.any? }
+        end
+
+        def parameter_reads
+          @parameter_reads ||= reads_of(parameter_name, within: node.body)
+        end
+
+        def it_has_an_existing_meaning?
+          parameter_name != :it && (it_variable_nodes.any? || bare_it_calls.any?)
+        end
+
+        def it_variable_nodes
+          nodes_in(
+            node.body,
+            :lvar, :lvasgn, :match_var, :shadowarg, :arg, :optarg, :restarg, :kwarg, :kwoptarg, :kwrestarg, :blockarg
+          ).select { it.children.first == :it }
+        end
+
+        def bare_it_calls
+          nodes_in(node.body, :send).select { bare_send?(it) && it.method?(:it) }
+        end
+
+        def offense_for_parameter
+          if parameter_reads.empty?
+            RuboCop::Callbacksystems::Offense.new(node, message)
+          else
+            RuboCop::Callbacksystems::Offense.new(node, message) { correct(it) }
+          end
+        end
+
+        def message
+          format(MESSAGE, parameter: node.first_argument.source)
+        end
+
+        def correct(corrector)
+          Correction.new(corrector, node, reads: parameter_reads).apply
+        end
+    end
+
+    class Correction
+      include RuboCop::Callbacksystems::Helpers
+
+      def initialize(corrector, node, reads:)
+        @corrector = corrector
+        @node = node
+        @reads = reads
+      end
+
+      def apply
+        replace_parameter_reads
+        remove_parameters
+      end
+
+      private
+        attr_reader :corrector, :node, :reads
+
+        def replace_parameter_reads
+          reads.each { replace_expression(corrector, it, with: "it") }
+        end
+
+        def remove_parameters
+          corrector.remove(node.arguments.source_range.join(node.arguments.source_range.end.adjust(end_pos: 1)))
+        end
+    end
+end

data/lib/rubocop/cop/callbacksystems/prefer_many.rb

@@ -0,0 +1,57 @@
+# Detects `collection.size > 1` patterns that should use `many?`. The predicate
+# asks the question in one word, where the comparison makes the reader count.
+#
+# `size`, `length` and `count` answer for a String too, while `many?` comes from
+# `Enumerable` and a String is not one, so a receiver we can read as a String is
+# left alone. A receiver whose type the file does not show stays flagged: getting
+# it wrong raises on the first call rather than passing quietly.
+#
+# @example
+#   # bad
+#   users.size > 1
+#   users.length > 1
+#   users.count > 1
+#
+#   # good
+#   users.many?
+#
+#   # good - a String has no `many?`
+#   name.strip.length > 1
+#
+class RuboCop::Cop::Callbacksystems::PreferMany < RuboCop::Cop::Callbacksystems::Base
+  extend RuboCop::Cop::AutoCorrector
+
+  MESSAGE = "Use `many?` instead of `%<method>s > 1`."
+
+  # @!method size_greater_than_one?(node)
+  def_node_matcher :size_greater_than_one?, <<~PATTERN
+    (call $(call _ ${:size :length :count}) :> (int 1))
+  PATTERN
+
+  def on_send(node)
+    size_greater_than_one?(node) do |size_call, method|
+      next if string_receiver?(size_call.receiver)
+
+      add_many_offense(node, call: size_call, method:)
+    end
+  end
+
+  alias on_csend on_send
+
+  private
+    def string_receiver?(receiver)
+      reads_as_string?(receiver)
+    end
+
+    def add_many_offense(node, call:, method:)
+      if source_comments.any_within?(node)
+        add_offense(node, message: format(MESSAGE, method:))
+      else
+        add_offense(node, message: format(MESSAGE, method:)) { it.replace(node, replacement_for(call)) }
+      end
+    end
+
+    def replacement_for(call)
+      "#{call_prefix_of(call)}many?"
+    end
+end

data/lib/rubocop/cop/callbacksystems/prefer_method_over_lambda.rb

@@ -0,0 +1,211 @@
+# Detects a lambda or proc assigned to a local variable inside a method when
+# its body reads nothing from that method. A closure that closes over no
+# local and no parameter is a method in disguise: giving it a name of its own
+# lets it be read and tested alone, and keeps the enclosing method to its
+# job. Instance variables, methods on `self` and constants do not count as
+# captures, since a method reads those too, and neither do the closure's own
+# parameters and locals.
+#
+# A closure that reads or reassigns a local or a parameter of the method is
+# left alone, since that capture is the point of the closure. So is one that
+# yields to the method's block or calls `super`, one defined outside a method,
+# such as a scope or a callback, and one not held in a local, whose shape
+# other cops judge.
+#
+# @example
+#   # bad - the lambda reads nothing from `total`
+#   def total(orders)
+#     price_of = ->(order) { order.quantity * order.unit_price }
+#     orders.sum { price_of.call(it) }
+#   end
+#
+#   # good - a method of its own
+#   def total(orders)
+#     orders.sum { price_of(it) }
+#   end
+#
+#   def price_of(order)
+#     order.quantity * order.unit_price
+#   end
+#
+#   # good - the lambda closes over `rate`
+#   def total(orders, rate)
+#     price_of = ->(order) { order.quantity * rate }
+#     orders.sum { price_of.call(it) }
+#   end
+#
+class RuboCop::Cop::Callbacksystems::PreferMethodOverLambda < RuboCop::Cop::Callbacksystems::Base
+  def on_lvasgn(node)
+    node.each_ancestor(:any_def, :class, :module, :sclass).first&.then do |definition|
+      report HeldClosure.new(node, method_node: definition) if definition.any_def_type?
+    end
+  end
+
+  private
+    # A local assignment inside a method, read as a closure against the names that method binds around it.
+    class HeldClosure
+      extend RuboCop::AST::NodePattern::Macros
+      include RuboCop::Callbacksystems::Helpers
+
+      MESSAGE = "`%<name>s` captures nothing from `%<method>s`, so it can be a method of its own."
+
+      # @!method closure?(node)
+      def_node_matcher :closure?, <<~PATTERN
+        (any_block {(lambda) (send nil? {:lambda :proc}) (send (const {nil? cbase} :Proc) :new)} ...)
+      PATTERN
+
+      def initialize(node, method_node:)
+        @node = node
+        @method_node = method_node
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(node, message) if closure?(closure) && captures_nothing?
+      end
+
+      private
+        attr_reader :node, :method_node
+
+        def closure
+          node.expression
+        end
+
+        def captures_nothing?
+          captured_uses.none? && !depends_on_method_context?
+        end
+
+        def captured_uses
+          LocalVariables.used_in(closure).select do |use|
+            method_names.include?(use.name) && !bound_within_closure?(use)
+          end
+        end
+
+        # The closure's own name is left out so that a recursive call counts as no capture.
+        def method_names
+          @method_names ||= bindings_around_closure.filter_map(&:name).excluding(node.name)
+        end
+
+        def bindings_around_closure
+          LocalVariables.bound_in(method_node).select { binding_visible_around_closure?(it) }
+        end
+
+        def binding_visible_around_closure?(binding)
+          binding.node.source_range.begin_pos < closure.source_range.begin_pos &&
+            binding_scopes.include?(lexical_scope_of(binding.node))
+        end
+
+        def binding_scopes
+          @binding_scopes ||= closure.each_ancestor(:any_block, :any_def)
+            .take_while { !it.equal?(method_node) }
+            .push(method_node)
+        end
+
+        def lexical_scope_of(binding)
+          binding.each_ancestor(:any_def, :any_block, :class, :module, :sclass).first
+        end
+
+        def bound_within_closure?(use)
+          blocks_from(use).any? { block_binds?(it, use.name) }
+        end
+
+        def blocks_from(use)
+          use.node.each_ancestor(:any_block).take_while { !it.equal?(closure) }.push(closure)
+        end
+
+        def block_binds?(block, name)
+          block.argument_list.any? { it.name == name }
+        end
+
+        def depends_on_method_context?
+          nodes_in(closure, :yield, :super, :zsuper, :return, :break, :next, :redo, :retry).any? ||
+            nodes_in(closure, :send, :csend).any? { ContextualCall.new(it).contextual? }
+        end
+
+        def message
+          format(MESSAGE, name: node.name, method: method_node.method_name)
+        end
+
+        class ContextualCall
+          include RuboCop::Callbacksystems::Helpers
+
+          CONTEXTUAL_METHODS = %i[ binding block_given? __method__ __callee__ eval local_variables ]
+          REFLECTIVE_METHODS = %i[ send __send__ method ]
+          STRING_EVAL_METHODS = %i[ instance_eval class_eval module_eval ]
+
+          def initialize(node)
+            @node = node
+          end
+
+          def contextual?
+            direct? || reflective? || string_eval?
+          end
+
+          private
+            attr_reader :node
+
+            def direct?
+              contextual_receiver? && CONTEXTUAL_METHODS.include?(node.method_name)
+            end
+
+            def contextual_receiver?
+              call_on_self?(node) || (core_constant?(node.receiver) && node.receiver.short_name == :Kernel)
+            end
+
+            def reflective?
+              node.first_argument&.then do |argument|
+                REFLECTIVE_METHODS.include?(node.method_name) &&
+                  (!argument.type?(:sym, :str) || contextual_reflection?(argument.value.to_sym))
+              end
+            end
+
+            def contextual_reflection?(method_name)
+              STRING_EVAL_METHODS.include?(method_name) ||
+                (contextual_receiver? && CONTEXTUAL_METHODS.include?(method_name))
+            end
+
+            def string_eval?
+              STRING_EVAL_METHODS.include?(node.method_name) && node.arguments.any?
+            end
+        end
+
+        class LocalVariables
+          include RuboCop::Callbacksystems::Helpers
+
+          BINDING_TYPES = %i[ arg optarg restarg kwarg kwoptarg kwrestarg blockarg shadowarg lvasgn match_var ]
+          USE_TYPES = %i[ lvar lvasgn match_var ]
+          Occurrence = Data.define(:node, :name)
+
+          class << self
+            def bound_in(tree)
+              new(tree, types: BINDING_TYPES).to_a
+            end
+
+            def used_in(tree)
+              new(tree, types: USE_TYPES).to_a
+            end
+          end
+
+          def initialize(tree, types:)
+            @tree = tree
+            @types = types
+          end
+
+          def to_a
+            node_occurrences + regexp_occurrences
+          end
+
+          private
+            attr_reader :tree, :types
+
+            def node_occurrences
+              nodes_in(tree, *types).map { Occurrence.new(it, variable_name_of(it)) }
+            end
+
+            def regexp_occurrences
+              nodes_in(tree, :match_with_lvasgn).flat_map do |match|
+                match.children.first.to_regexp.named_captures.each_key.map { Occurrence.new(match, it.to_sym) }
+              end
+            end
+        end
+    end
+end

data/lib/rubocop/cop/callbacksystems/prefer_method_over_variable.rb

@@ -0,0 +1,172 @@
+# Detects local variable assignments that could be methods instead.
+# Assigning to a variable with the same name as the method being called
+# suggests the code would be more declarative with a method or delegate.
+#
+# @example
+#   # bad - variable name matches method call (simple receiver)
+#   account = user.account
+#   plan = @account.plan
+#
+#   # good - use delegate when method names match
+#   delegate :account, to: :user
+#   delegate :plan, to: :account
+#
+#   # good - or extract method
+#   def account
+#     user.account
+#   end
+#
+#   # bad - finder pattern
+#   user = find_user
+#   user = User.find(params[:id])
+#   order = Order.find_by(number: number)
+#
+#   # good - extract to method
+#   def user
+#     User.find(params[:id])
+#   end
+#
+#   # ok - assignment in conditional
+#   if user = find_user
+#     user.activate
+#   end
+#
+#   # ok - chain receiver (delegate doesn't apply)
+#   length = answer.value.to_s.length
+#
+#   # ok - receiver is a method parameter (delegate doesn't apply)
+#   def process(user)
+#     account = user.account  # user is a parameter, not a method
+#   end
+#
+#   # ok - different name indicates transformation
+#   formatted_date = date.strftime("%Y-%m-%d")
+#   active_users = users.select(&:active?)
+#
+class RuboCop::Cop::Callbacksystems::PreferMethodOverVariable < RuboCop::Cop::Callbacksystems::Base
+  def on_lvasgn(node)
+    report Assignment.new(node)
+  end
+
+  private
+    class Assignment
+      DELEGATE_MESSAGE = "Variable `%<variable>s` mirrors method call. Use `delegate :%<variable>s, " \
+        "to: :%<receiver>s` or extract a method."
+      FINDER_MESSAGE = "Variable `%<variable>s` assigned from finder. Consider extracting a `%<variable>s` method."
+      CONDITIONAL_TYPES = %i[ if while until while_post until_post case case_match ]
+
+      def initialize(node)
+        @node = node
+      end
+
+      def offense
+        RuboCop::Callbacksystems::Offense.new(node, message) if message
+      end
+
+      private
+        attr_reader :node
+
+        def message
+          @message ||= delegation_message || finder_message if assigns_a_call? && !inside_conditional?
+        end
+
+        def assigns_a_call?
+          node.expression&.send_type?
+        end
+
+        def inside_conditional?
+          node.each_ancestor(*CONDITIONAL_TYPES).any? { condition_holds_assignment?(it.condition) }
+        end
+
+        def condition_holds_assignment?(condition)
+          condition&.then { it.equal?(node) || it.source_range.contains?(node.source_range) }
+        end
+
+        def delegation_message
+          format(DELEGATE_MESSAGE, variable: variable_name, receiver: receiver.name) if same_name_with_simple_receiver?
+        end
+
+        def same_name_with_simple_receiver?
+          value_node.method?(variable_name) && delegatable_receiver?
+        end
+
+        def value_node
+          node.expression
+        end
+
+        def variable_name
+          node.name
+        end
+
+        # `delegate` needs a method or a reader to send to, which also keeps `now = Time.now` holding its one instant.
+        def delegatable_receiver?
+          value_node.receiver && !value_node.receiver.lvar_type? && !receiver.chained? && !receiver.name.nil?
+        end
+
+        def receiver
+          @receiver ||= Receiver.new(value_node)
+        end
+
+        def finder_message
+          format(FINDER_MESSAGE, variable: variable_name) if finder_call.finds_the_variable?
+        end
+
+        def finder_call
+          FinderCall.new(variable_name, value_node)
+        end
+    end
+
+    class Receiver
+      include RuboCop::Callbacksystems::Helpers
+
+      def initialize(value_node)
+        @value_node = value_node
+      end
+
+      def chained?
+        value_node.receiver.send_type? && value_node.receiver.receiver
+      end
+
+      def name
+        case value_node.receiver.type
+        when :send then value_node.receiver.method_name
+        when :ivar then name_without_sigil(value_node.receiver.name)
+        end
+      end
+
+      private
+        attr_reader :value_node
+    end
+
+    class FinderCall
+      FINDER_PREFIXES = %w[ find_ get_ fetch_ load_ ]
+      CLASS_FINDERS = %w[ find find_by find_by! ]
+
+      def initialize(variable_name, value_node)
+        @variable_name = variable_name
+        @value_node = value_node
+      end
+
+      def finds_the_variable?
+        (finder_method? || class_finder?) && !reads_a_local?
+      end
+
+      private
+        attr_reader :variable_name, :value_node
+
+        def finder_method?
+          FINDER_PREFIXES.any? { value_node.method_name.to_s == "#{it}#{variable_name}" }
+        end
+
+        def class_finder?
+          value_node.receiver&.const_type? &&
+            CLASS_FINDERS.include?(value_node.method_name.to_s) &&
+            variable_name.to_s == value_node.receiver.short_name.to_s.underscore
+        end
+
+        # A method extracted out of here could not read a local of the caller, so a finder given one stays a variable.
+        def reads_a_local?
+          value_node.each_node(:lvar).any?
+        end
+    end
+end