rubocop-callback_checker 0.1.0

data/lib/callback_checker/prism_analyzer.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require 'prism'
+
+module CallbackChecker
+  class PrismAnalyzer < Prism::Visitor
+    attr_reader :offenses
+
+    SIDE_EFFECT_SENSITIVE_CALLBACKS = %i[
+      before_validation before_save after_save
+      before_create after_create
+      before_update after_update
+      before_destroy after_destroy
+      around_save around_create around_update around_destroy
+    ].freeze
+
+    SAFE_CALLBACKS = %i[
+      after_commit after_create_commit after_update_commit
+      after_destroy_commit after_save_commit after_rollback
+    ].freeze
+
+    SUSPICIOUS_CONSTANTS = %w[
+      RestClient Faraday HTTParty Net Sidekiq ActionCable
+    ].freeze
+
+    SIDE_EFFECT_METHODS = %i[
+      deliver_later deliver_now perform_later broadcast_later
+      save save! update update! destroy destroy! create create!
+      delete delete_all destroy_all update_all update_columns touch
+    ].freeze
+
+    def initialize(source)
+      @source = source
+      @offenses = []
+      @current_class = nil
+      @callback_methods = {}
+      @current_callback_type = nil
+    end
+
+    def visit_class_node(node)
+      previous_class = @current_class
+      previous_methods = @callback_methods.dup
+
+      @current_class = node
+      @callback_methods = {}
+
+      # First pass: collect all method definitions
+      collect_methods(node)
+
+      # Second pass: check callbacks
+      super
+
+      @current_class = previous_class
+      @callback_methods = previous_methods
+    end
+
+    def visit_call_node(node)
+      if callback_declaration?(node)
+        check_callback(node)
+      elsif @current_callback_type && side_effect_call?(node)
+        add_offense(node, @current_callback_type)
+      end
+
+      super
+    end
+
+    def visit_if_node(node)
+      # Make sure we visit all branches of conditionals
+      super
+    end
+
+    def visit_unless_node(node)
+      # Make sure we visit all branches of unless statements
+      super
+    end
+
+    private
+
+    def collect_methods(class_node)
+      class_node.body&.body&.each do |statement|
+        if statement.is_a?(Prism::DefNode)
+          @callback_methods[statement.name] = statement
+        end
+      end
+    end
+
+    def callback_declaration?(node)
+      return false unless node.receiver.nil?
+      return false unless node.name
+
+      callback_name = node.name
+      SIDE_EFFECT_SENSITIVE_CALLBACKS.include?(callback_name) ||
+        SAFE_CALLBACKS.include?(callback_name)
+    end
+
+    def check_callback(node)
+      callback_name = node.name
+
+      # Skip safe callbacks
+      return if SAFE_CALLBACKS.include?(callback_name)
+
+      if node.block
+        # Block form: before_save do ... end
+        check_block_callback(node, callback_name)
+      elsif node.arguments
+        # Symbol form: before_save :method_name
+        check_symbol_callback(node, callback_name)
+      end
+    end
+
+    def check_block_callback(node, callback_name)
+      previous_callback = @current_callback_type
+      @current_callback_type = callback_name
+
+      visit(node.block)
+
+      @current_callback_type = previous_callback
+    end
+
+    def check_symbol_callback(node, callback_name)
+      return unless node.arguments&.arguments
+
+      node.arguments.arguments.each do |arg|
+        next unless arg.is_a?(Prism::SymbolNode)
+
+        method_name = arg.value
+        method_def = @callback_methods[method_name.to_sym]
+
+        next unless method_def
+
+        check_method_for_side_effects(method_def, callback_name)
+      end
+    end
+
+    def check_method_for_side_effects(method_node, callback_name)
+      previous_callback = @current_callback_type
+      @current_callback_type = callback_name
+
+      visit(method_node.body) if method_node.body
+
+      @current_callback_type = previous_callback
+    end
+
+    def side_effect_call?(node)
+      return false unless node.is_a?(Prism::CallNode)
+
+      # Check for suspicious constant calls (RestClient.get, etc.)
+      if node.receiver.is_a?(Prism::ConstantReadNode)
+        constant_name = node.receiver.name.to_s
+        return true if SUSPICIOUS_CONSTANTS.include?(constant_name)
+        
+        # Check for any constant that isn't a known safe pattern
+        # This catches things like NewsletterSDK, CustomAPI, etc.
+        return true if constant_appears_to_be_external_service?(constant_name)
+      end
+
+      # Check for side effect methods
+      method_name = node.name
+      return true if SIDE_EFFECT_METHODS.include?(method_name)
+
+      # Check for mailer patterns (anything ending with Mailer)
+      if node.receiver.is_a?(Prism::ConstantReadNode)
+        constant_name = node.receiver.name.to_s
+        return true if constant_name.end_with?('Mailer')
+      end
+
+      # Check for method chains that end with deliver_now
+      if method_name == :deliver_now && node.receiver.is_a?(Prism::CallNode)
+        return true
+      end
+
+      # Check for calls on associations or other objects (not self)
+      if node.receiver && !self_reference?(node.receiver)
+        return true if persistence_method?(method_name)
+      end
+
+      # Check for save/update on self or implicit self
+      if node.receiver.nil? || self_reference?(node.receiver)
+        return true if %i[save save! update update!].include?(method_name)
+      end
+
+      false
+    end
+
+    def constant_appears_to_be_external_service?(constant_name)
+      # Heuristic: if it's all caps or ends with SDK, API, Client, Service
+      # it's probably an external service
+      return true if constant_name.end_with?('SDK', 'API', 'Client', 'Service')
+      return true if constant_name == constant_name.upcase && constant_name.length > 1
+      
+      false
+    end
+
+    def self_reference?(node)
+      node.is_a?(Prism::SelfNode)
+    end
+
+    def persistence_method?(method_name)
+      %i[
+        save save! update update! destroy destroy! create create!
+        delete delete_all destroy_all update_all update_columns touch
+      ].include?(method_name)
+    end
+
+    def add_offense(node, callback_type)
+      location = node.location
+      start_line = location.start_line
+      start_column = location.start_column
+      end_line = location.end_line
+      end_column = location.end_column
+
+      # Extract the source code for this node
+      source_range = location.start_offset...location.end_offset
+      code = @source[source_range]
+
+      @offenses << {
+        message: "Avoid side effects (API calls, mailers, background jobs, or modifying other records) in #{callback_type}. Use `after_commit` instead.",
+        location: {
+          start_line: start_line,
+          start_column: start_column,
+          end_line: end_line,
+          end_column: end_column
+        },
+        code: code,
+        callback_type: callback_type
+      }
+    end
+
+    class << self
+      def analyze_file(path)
+        source = File.read(path)
+        analyze_source(source, path)
+      end
+
+      def analyze_source(source, path = nil)
+        result = Prism.parse(source)
+
+        if result.errors.any?
+          warn "Parse errors in #{path}:" if path
+          result.errors.each do |error|
+            warn "  #{error.message}"
+          end
+          return []
+        end
+
+        analyzer = new(source)
+        analyzer.visit(result.value)
+        analyzer.offenses
+      end
+    end
+  end
+end

data/lib/rubocop/callback_checker/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Rubocop
+  module CallbackChecker
+    VERSION = "0.1.0"
+  end
+end

data/lib/rubocop/callback_checker.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "callback_checker/version"
+require "pathname"
+require "yaml"
+
+# Load all the cops
+Dir[Pathname.new(__dir__).join("cop", "callback_checker", "**", "*.rb")].each { |file| require file }
+
+module Rubocop
+  module CallbackChecker
+    class Error < StandardError; end
+
+    PROJECT_ROOT = Pathname.new(__dir__).parent.parent.freeze
+    CONFIG_DEFAULT = PROJECT_ROOT.join("config", "default.yml").freeze
+
+    def self.version
+      VERSION
+    end
+  end
+end

data/lib/rubocop/cop/callback_checker/attribute_assignment_only.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module CallbackChecker
+      # This cop checks for persistence method calls on self within before_* callbacks
+      # (before_save, before_validation, before_create, before_update).
+      # It suggests using attribute assignment instead, since the object will be
+      # automatically persisted after the callback completes.
+      #
+      # @example
+      #   # bad
+      #   class User < ApplicationRecord
+      #     before_save :normalize_data
+      #
+      #     def normalize_data
+      #       update(name: name.strip)
+      #     end
+      #   end
+      #
+      #   # good
+      #   class User < ApplicationRecord
+      #     before_save :normalize_data
+      #
+      #     def normalize_data
+      #       self.name = name.strip
+      #     end
+      #   end
+      class AttributeAssignmentOnly < Base
+        MSG = 'Use attribute assignment (`self.%<attribute>s = value`) instead of `%<method>s` in `%<callback>s`. ' \
+              'The object will be persisted automatically after the callback completes.'
+
+        PERSISTENCE_METHODS = %i[
+          update
+          update!
+          update_columns
+          update_column
+          update_attribute
+          update_attributes
+          update_attributes!
+        ].freeze
+
+        BEFORE_CALLBACKS = %i[
+          before_save
+          before_validation
+          before_create
+          before_update
+        ].freeze
+
+        def_node_matcher :callback_method?, <<~PATTERN
+          (send nil? {#{BEFORE_CALLBACKS.map(&:inspect).join(' ')}} ...)
+        PATTERN
+
+        def_node_matcher :persistence_call?, <<~PATTERN
+          (send {nil? (self)} {#{PERSISTENCE_METHODS.map(&:inspect).join(' ')}} ...)
+        PATTERN
+
+        def_node_matcher :hash_argument?, <<~PATTERN
+          (send {nil? (self)} _ (hash ...))
+        PATTERN
+
+        def_node_matcher :first_hash_key, <<~PATTERN
+          (send {nil? (self)} _ (hash (pair (sym $_) _) ...))
+        PATTERN
+
+        def_node_matcher :first_symbol_arg, <<~PATTERN
+          (send {nil? (self)} _ (sym $_) ...)
+        PATTERN
+
+        def on_class(node)
+          @current_callbacks = {}
+          
+          node.each_descendant(:send) do |send_node|
+            next unless callback_method?(send_node)
+            
+            callback_name = send_node.method_name
+            callback_args = send_node.arguments
+            
+            callback_args.each do |arg|
+              if arg.sym_type?
+                method_name = arg.value
+                @current_callbacks[method_name] = callback_name
+              elsif arg.block_type? || arg.numblock_type?
+                check_block_for_persistence(arg, callback_name)
+              end
+            end
+            
+            if send_node.block_node
+              check_block_for_persistence(send_node.block_node, callback_name)
+            end
+          end
+          
+          node.each_descendant(:def) do |def_node|
+            method_name = def_node.method_name
+            callback_name = @current_callbacks[method_name]
+            
+            next unless callback_name
+            
+            check_method_for_persistence(def_node, callback_name)
+          end
+        end
+
+        private
+
+        def check_block_for_persistence(block_node, callback_name)
+          block_node.each_descendant(:send) do |send_node|
+            next unless persistence_call?(send_node)
+            
+            add_offense_for_node(send_node, callback_name)
+          end
+        end
+
+        def check_method_for_persistence(method_node, callback_name)
+          method_node.each_descendant(:send) do |send_node|
+            next unless persistence_call?(send_node)
+            
+            add_offense_for_node(send_node, callback_name)
+          end
+        end
+
+        def add_offense_for_node(node, callback_name)
+          method_name = node.method_name
+          attribute = extract_attribute_name(node)
+          
+          message = format(
+            MSG,
+            attribute: attribute,
+            method: method_name,
+            callback: callback_name
+          )
+          
+          add_offense(node, message: message)
+        end
+
+        def extract_attribute_name(node)
+          # Try to extract from hash argument (e.g., update(name: 'foo'))
+          if hash_argument?(node)
+            key = first_hash_key(node)
+            return key.to_s if key
+          end
+          
+          # Try to extract from symbol argument (e.g., update_column(:name, 'foo'))
+          symbol_arg = first_symbol_arg(node)
+          return symbol_arg.to_s if symbol_arg
+          
+          'attribute'
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/callback_checker/avoid_self_persistence.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module CallbackChecker
+      # This cop checks for persistence method calls on self within Active Record callbacks.
+      # Calling .save, .update, .toggle!, etc. on self inside a callback can trigger
+      # infinite loops or run the entire callback chain multiple times.
+      #
+      # @example
+      #   # bad
+      #   after_save :activate_user
+      #   def activate_user
+      #     self.save
+      #   end
+      #
+      #   # bad
+      #   before_validation { update(status: 'active') }
+      #
+      #   # good
+      #   after_save :activate_user
+      #   def activate_user
+      #     self.status = 'active'
+      #   end
+      class AvoidSelfPersistence < Base
+        MSG = "Avoid calling `%<method>s` on self within `%<callback>s`. " \
+              "This can trigger infinite loops or run callbacks multiple times. " \
+              "Assign attributes directly instead: `self.attribute = value`."
+
+        CALLBACK_METHODS = %i[
+          before_validation after_validation
+          before_save after_save around_save
+          before_create after_create around_create
+          before_update after_update around_update
+          before_destroy after_destroy around_destroy
+          after_touch
+        ].freeze
+
+        SAFE_CALLBACKS = %i[
+          after_commit after_rollback
+          after_create_commit after_update_commit after_destroy_commit
+          after_save_commit
+        ].freeze
+
+        PERSISTENCE_METHODS = %i[
+          save save! update update! update_attribute update_attributes
+          update_attributes! update_column update_columns
+          toggle! increment! decrement! touch
+        ].freeze
+
+        def on_send(node)
+          return unless callback_method?(node)
+          return if safe_callback?(node)
+
+          check_callback_block(node) if node.block_node
+          check_callback_arguments(node)
+        end
+
+        private
+
+        def callback_method?(node)
+          CALLBACK_METHODS.include?(node.method_name)
+        end
+
+        def safe_callback?(node)
+          SAFE_CALLBACKS.include?(node.method_name)
+        end
+
+        def check_callback_block(node)
+          return unless node.block_node&.body
+
+          check_block_for_persistence(node.block_node.body, node.method_name)
+        end
+
+        def check_callback_arguments(node)
+          node.arguments.each do |arg|
+            process_callback_argument(node, arg)
+          end
+        end
+
+        def process_callback_argument(node, arg)
+          if arg.sym_type?
+            check_symbol_callback(node, arg.value)
+          elsif arg.block_pass_type?
+            # Handle block pass like: after_save &:method_name
+            # We can't easily analyze these, so skip
+            return
+          elsif arg.lambda_or_proc?
+            check_proc_callback(arg, node.method_name)
+          end
+        end
+
+        def check_proc_callback(arg, callback_name)
+          return unless arg.body
+
+          check_block_for_persistence(arg.body, callback_name)
+        end
+
+        def check_symbol_callback(node, method_name)
+          scope = node.each_ancestor(:class, :module).first
+          return unless scope
+
+          method_def = scope.each_descendant(:def).find { |d| d.method_name == method_name }
+          return unless method_def
+          return unless method_def.body
+
+          check_block_for_persistence(method_def.body, node.method_name)
+        end
+
+        def check_block_for_persistence(node, callback_name)
+          node.each_node(:send) do |send_node|
+            check_for_self_persistence(send_node, callback_name)
+          end
+        end
+
+        def check_for_self_persistence(send_node, callback_name)
+          return unless PERSISTENCE_METHODS.include?(send_node.method_name)
+          return unless called_on_self?(send_node)
+
+          add_offense(
+            send_node,
+            message: format(MSG, method: send_node.method_name, callback: callback_name)
+          )
+        end
+
+        def called_on_self?(send_node)
+          # No receiver means implicit self
+          return true if send_node.receiver.nil?
+
+          # Explicit self reference
+          send_node.receiver.self_type?
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/callback_checker/callback_method_length.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module CallbackChecker
+      # This cop enforces that callback methods should be short and simple.
+      # Long callback methods indicate that business logic is leaking into the model
+      # and should be extracted to a service object.
+      #
+      # @example Max: 5 (default)
+      #   # bad
+      #   class User < ApplicationRecord
+      #     before_save :complex_setup
+      #
+      #     def complex_setup
+      #       self.name = name.strip
+      #       self.email = email.downcase
+      #       self.token = generate_secure_token
+      #       self.status = calculate_status
+      #       self.score = compute_score
+      #       self.metadata = build_metadata
+      #       self.tags = process_tags
+      #     end
+      #   end
+      #
+      #   # good
+      #   class User < ApplicationRecord
+      #     before_save :normalize_fields
+      #
+      #     def normalize_fields
+      #       self.name = name.strip
+      #       self.email = email.downcase
+      #     end
+      #   end
+      #
+      #   # better - extract to service
+      #   class User < ApplicationRecord
+      #     # No callback, call UserRegistrationService.new(user).call from controller
+      #   end
+      class CallbackMethodLength < Base
+        MSG = "Callback method `%<method>s` is too long (%<length>d lines). " \
+              "Max allowed: %<max>d lines. Extract complex logic to a service object."
+
+        CALLBACK_METHODS = %i[
+          before_validation after_validation
+          before_save after_save around_save
+          before_create after_create around_create
+          before_update after_update around_update
+          before_destroy after_destroy around_destroy
+          after_commit after_rollback
+          after_touch
+          after_create_commit after_update_commit after_destroy_commit after_save_commit
+        ].freeze
+
+        def on_send(node)
+          return unless callback_method?(node)
+          
+          # Only check symbol arguments (method name references)
+          node.arguments.each do |arg|
+            check_callback_argument(node, arg) if arg.sym_type?
+          end
+        end
+
+        private
+
+        def callback_method?(node)
+          CALLBACK_METHODS.include?(node.method_name)
+        end
+
+        def check_callback_argument(callback_node, arg)
+          method_name = arg.value
+          scope = callback_node.each_ancestor(:class, :module).first
+          return unless scope
+
+          method_def = find_method_definition(scope, method_name)
+          return unless method_def
+
+          check_method_length(method_def, method_name)
+        end
+
+        def find_method_definition(scope, method_name)
+          scope.each_descendant(:def).find { |def_node| def_node.method_name == method_name }
+        end
+
+        def check_method_length(method_node, method_name)
+          return unless method_node.body
+
+          length = method_body_length(method_node)
+          max_length = cop_config['Max'] || 5
+
+          return if length <= max_length
+
+          add_offense(
+            method_node,
+            message: format(MSG, method: method_name, length: length, max: max_length)
+          )
+        end
+
+        def method_body_length(method_node)
+          return 0 unless method_node.body
+
+          body = method_node.body
+          
+          # Calculate line count
+          first_line = body.first_line
+          last_line = body.last_line
+          
+          # Count non-empty lines
+          (first_line..last_line).count do |line_number|
+            line = processed_source.lines[line_number - 1]
+            line && !line.strip.empty?
+          end
+        end
+      end
+    end
+  end
+end