callback_hell 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1e3c885812a73a0a4fd89036e2d1897b64a467130924de668bdfb7dd4c90091b
+  data.tar.gz: 55d44b2e7296574ec3657b9e4d44ea4dfc5b68b9510f87853ff33e41fc40ad9c
+SHA512:
+  metadata.gz: a43af18de970ceab56f70a67cbe08c7348b3ff69a5acdbeba4dbdb395173bcfe96c40bc9a1f441074512d42a142e58183c43bcb415c875fdbb93d3e7753b15b7
+  data.tar.gz: 7f51fd27e54b2ee70cf3927d716f3d5c95bfb1d14f240deadd0806ccd9200e480644240c24db0ea045dfb735786519ef844c83794955de24d2c78ae03f3f9bdf

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Change log
+
+## 0.2.0
+
+- Initial public release. ([@yaroslav][])
+
+- Make the default namespace-level rake task to run the full report (callbacks and validations). ([@yaroslav][])
+
+## 0.1.1
+
+- Migrated from `terminal-table` to `table_tennis`. ([@palkan][])
+
+- Added `mode=default | full` parameter to hide Rails internal callbacks/validations by default. ([@palkan][])
+
+## 0.1.0
+
+- Initial version. See `README.md` for details. ([@yaroslav][])
+
+[@palkan]: https://github.com/palkan
+[@yaroslav]: https://github.com/yaroslav

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2024 Yaroslav Markin, Vladimir Dementyev
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,174 @@
+[![Gem Version](https://badge.fury.io/rb/callback_hell.svg)](https://rubygems.org/gems/callback_hell) [![Build](https://github.com/evilmartians/callback_hell/workflows/Build/badge.svg)](https://github.com/evilmartians/callback_hell/actions)
+
+# Callback Hell
+
+> You live in it.
+
+Callback Hell is a Ruby gem for use with Ruby on Rails applications.
+
+It analyzes your Rails application models and provides actionable insights on callbacks and validations. Use it to identify models that might benefit from refactoring, spot callback pollution from gems and associations, and keep your models clean and maintainable.
+
+<a href="https://evilmartians.com/?utm_source=callback_hell">
+<img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54">
+</a>
+
+## Why bother?
+
+As Rails applications grow, callbacks can quickly spiral out of control. Callback Hell helps you:
+
+- **Visualize callback complexity** across your entire application
+- **Identify callback hotspots** that need refactoring attention
+- **Track callback origins**: distinguish your code from Rails internals and gem callbacks
+- **Spot inheritance issues** and understand callback propagation
+- **Audit conditional callbacks** that might be hiding bugs
+
+## Quick start
+
+Add to your Rails application's `Gemfile`:
+
+```ruby
+gem "callback_hell", group: :development
+```
+
+And then:
+
+```bash
+bundle install
+```
+
+### Basic usage
+
+Generate a complete analysis report (callbacks _and_ validations):
+
+```bash
+bin/rails ch
+```
+
+Sample output:
+
+<img src="https://raw.githubusercontent.com/evilmartians/callback_hell/refs/heads/main/assets/report.png" width="758" height="767" alt="Callback Hell sample output">
+
+Or run specific reports:
+
+```bash
+# Just callbacks
+bin/rails ch:callbacks
+
+# Just validations
+bin/rails ch:validations
+```
+
+### Requirements
+
+We support Ruby 3.0+ and Rails 7.0+.
+
+## Usage
+
+**Note:** you can use both `rake` or `bin/rails` as you wish.
+
+### Command line options
+
+All rake tasks support the following options:
+
+#### Output formats
+
+```bash
+# Table format (default)
+bin/rails callback_hell:callbacks format=table
+
+# Line format: detailed per-callback breakdown, useful for debugging
+bin/rails callback_hell:callbacks format=line
+
+# GitHub Actions format for CI/CD
+bin/rails callback_hell:callbacks format=github
+```
+
+#### Model filtering
+
+```bash
+# Analyze specific model by class name
+bin/rails ch model=User
+
+# Or by file path
+bin/rails ch model=admin/user
+
+# Works with namespaced models too
+bin/rails ch model=Admin::User
+```
+
+#### Sorting
+
+```bash
+# Sort by callback count (default)
+bin/rails ch sort=size:desc
+
+# Sort alphabetically
+bin/rails ch sort=name:asc
+```
+
+#### Analysis modes
+
+```bash
+# Default mode - your callbacks only
+bin/rails ch mode=default
+
+# Full mode - includes Rails internals and associations
+bin/rails ch mode=full
+```
+
+#### Custom model paths
+
+```bash
+# Include models from engines or non-standard locations
+bin/rails ch path=engines/admin/app/models,lib/models
+```
+
+### Understanding the output
+
+#### Callback origins
+
+- **Own**: Callbacks defined in your application code
+- **Rails**: Built-in Rails framework callbacks
+- **Gems**: Callbacks from external gems
+- **Inherited**: Callbacks inherited from parent classes or modules
+
+#### Special Categories
+
+- **Conditional**: Callbacks with `:if` or `:unless` conditions
+- **Associations**: Auto-generated by Rails associations (`has_many`, `belongs_to`, etc.)
+- **Attributes**: Generated by Rails attribute features (encryption, normalization, etc.)
+
+### Integration with CI/CD
+
+You can try the GitHub Actions format to integrate with your CI pipeline:
+
+```yaml
+# .github/workflows/callback_analysis.yml
+name: Callback Analysis
+on: [push, pull_request]
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+      - name: Analyze callbacks
+        run: bin/rails ch format=github
+```
+
+## Credits and acknowledgements
+
+Callback Hell is a spiritual successor of the [arca](https://github.com/jonmagic/arca) gem by [Jonathan Hoyt](https://github.com/jonmagic).
+
+The entire idea and a detailed specification for the gem was done by [Vladimir Dementyev](https://github.com/palkan) who initially offered it as a test task for [Evil Martians](https://evilmartians.com/?utm_source=callback_hell) Ruby developer take-home task.
+
+## Contributing
+
+Bug reports and pull requests are welcome at [https://github.com/evilmartians/callback_hell](https://github.com/evilmartians/callback_hell).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/file_id.diz

@@ -0,0 +1,19 @@
+   ..                           ..
+  .GP                           YH.
+ GP^Y$b.dBBBBBBBBBBBBBBBBBBBb.d$Y^YD          .dBBBBBBBBBBBBBBBBBBBb.
+     Y$$$$$$$$$$$$$$$$$$$$$$$$$Y            dSSSSSSSSSSSSSSSSSSSSSSSSSb
+    d$$$$$$$$$$$$$$$$$$$$$$$$$$$b          dSYSSSYYSSSYYSSSYYSSSYYSSSYSb
+    M$$$$$$$$$$$$$$$$$$$$$$$$$$$M          MS.`Y´.L`Y´.L`Y´.L`Y´.L`Y´.SM
+    M$$$$$$$$$$$$$$$$$$$$$$$$$$$M          MSSb.dSSb.dSSb.dSSb.dSSb.dSSM
+    M$$$$$$P^^^Y$$$$$P^^^Y$$$$$$M          MSSSSSSP^^^YSSSSSP^^^YSSSSSSM
+    M$$$$$´.qop.`$$$´.qop.`$$$$$M       .qGSSSSSS´.qop.`SSS´.qop.`SSSSSSDp.
+    M$$$$$ G( )D $$$ G( )D $$$$$M       GY´MSSSSS G( )D SSS G( )D SSSSSM`YD
+    M$$$$$.`YPP´.$$$.`YPP´.$$$$$M       Gb.MSSSSS.`YPP´.SSS.`YPP´.SSSSSM.dD
+    M$$$$$$bwwwd$$$$$bwwwd$$$$$$M       `YGSSSSSSSbwwwdSSSSSbwwwdSSSSSSSDY´
+    M$$$$$$$$$$$$$$$$$$$$$$$$$$$M          MSSSSSSSSSSSSSSSSSSSSSSSSSSSM
+    M$$$$$$$$$$$$$$$$$$$$$$$$$$$M          MSSSSSSSSSSSSSSSSSSSSSSSSSSSM
+    MBBBBBBBBBBBBBBBBBBBBBBBBBBBM          MBBBBBBBBBBBBBBBBBBBBBBBBBBBM
+
+    twitter.com/evilmartians  github.com/evilmartians  jobs: evl.ms/jobs
+
+                                 since 2006

data/lib/callback_hell/analyzers/callback_analyzer.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module CallbackHell
+  module Analyzers
+    class CallbackAnalyzer
+      RAILS_GEMS = %w[
+        actioncable actionmailbox actionmailer actionpack actiontext
+        actionview activejob activemodel activerecord activestorage
+        activesupport railties
+      ].freeze
+
+      RAILS_ATTRIBUTE_OWNERS = [
+        defined?(ActiveRecord::Normalization) ? ActiveRecord::Normalization : ActiveModel::Attributes::Normalization,
+        ActiveRecord::Encryption::EncryptableRecord
+      ].freeze
+
+      def initialize(callback, model, defining_class)
+        @callback = callback
+        @model = model
+        @defining_class = defining_class
+        @filter = callback.filter
+      end
+
+      def origin
+        if rails_callback?
+          :rails
+        elsif external_class?
+          :gems
+        elsif !@filter.is_a?(Symbol)
+          :own
+        else
+          external_method?(callback_method) ? :gems : :own
+        end
+      end
+
+      def inherited?
+        @model != @defining_class
+      end
+
+      def conditional?
+        [@callback.instance_variable_get(:@if),
+          @callback.instance_variable_get(:@unless)].any? do |condition|
+          next false if condition.nil?
+          [*condition].any? { |c| c.is_a?(Symbol) || c.is_a?(Proc) }
+        end
+      end
+
+      def association_generated?
+        generated_by_module?("GeneratedAssociationMethods") ||
+          from_rails_path?(%r{/active_record/(autosave_association\.rb|associations/builder)}) ||
+          ValidationAnalyzer.belongs_to_validator?(@filter, @model)
+      end
+
+      def attribute_generated?
+        generated_by_module?("GeneratedAttributeMethods") ||
+          generated_by_rails_attributes? ||
+          from_rails_path?("active_record/attribute_methods/")
+      end
+
+      private
+
+      def rails_callback?
+        ValidationAnalyzer.belongs_to_validator?(@filter, @model) || standard_rails_callback?
+      end
+
+      def standard_rails_callback?
+        case @filter
+        when Symbol, Proc then from_rails_path?
+        else @defining_class == ApplicationRecord
+        end
+      end
+
+      def callback_owner
+        @callback_owner ||= determine_owner
+      end
+
+      def determine_owner
+        case @filter
+        when Symbol then callback_method&.owner
+        when Proc then nil
+        when ActiveModel::Validator, ActiveModel::EachValidator then @defining_class
+        else @filter.class
+        end
+      end
+
+      def callback_method
+        return nil unless @filter.is_a?(Symbol) || @filter.is_a?(String)
+
+        @callback_method ||= begin
+          @model.instance_method(@filter)
+        rescue
+          nil
+        end
+      end
+
+      def source_location
+        @source_location ||= case @filter
+        when Symbol, String then callback_method&.source_location&.first
+        when Proc then @filter.source_location&.first
+        end.to_s
+      end
+
+      def external_class?
+        @defining_class != @model && !@model.ancestors.include?(@defining_class)
+      end
+
+      def external_method?(method)
+        return false unless method
+
+        source = method.source_location&.first.to_s
+        !from_app_path?(source)
+      end
+
+      def from_app_path?(path)
+        path.start_with?(Rails.root.to_s) &&
+          !path.start_with?(Rails.root.join("vendor").to_s)
+      end
+
+      def generated_by_module?(suffix)
+        callback_method&.owner&.name&.end_with?("::" + suffix) || false
+      end
+
+      def generated_by_rails_attributes?
+        method = callback_method
+        return false unless method
+
+        RAILS_ATTRIBUTE_OWNERS.include?(method.owner)
+      end
+
+      def from_rails_path?(subpath = nil)
+        return false if source_location.empty?
+
+        rails_paths.any? do |rails_path|
+          case subpath
+          when String
+            source_location.include?("/#{subpath}")
+          when Regexp
+            source_location.match?(subpath)
+          else
+            source_location.include?(rails_path)
+          end
+        end
+      end
+
+      def rails_paths
+        @rails_paths ||= RAILS_GEMS.map { |name| Gem::Specification.find_by_name(name).full_gem_path }
+      end
+
+      def rails_module?(mod)
+        mod.name&.start_with?("ActiveRecord::", "ActiveModel::")
+      end
+
+      def validator?(obj)
+        obj.is_a?(ActiveModel::Validator)
+      end
+    end
+  end
+end

data/lib/callback_hell/analyzers/validation_analyzer.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module CallbackHell
+  module Analyzers
+    class ValidationAnalyzer
+      STANDARD_VALIDATIONS = %w[
+        presence uniqueness format length inclusion exclusion
+        numericality acceptance confirmation
+      ].freeze
+
+      STANDARD_VALIDATION_PATTERN = /^validates?_(#{STANDARD_VALIDATIONS.join("|")})(?:_of)?$/
+
+      class << self
+        def belongs_to_validator?(filter, model)
+          presence_validator?(filter) &&
+            association_attribute?(filter.attributes.first, model, :belongs_to)
+        end
+
+        def detect_type(filter, model)
+          return nil unless filter
+
+          if belongs_to_validator?(filter, model)
+            "associated"
+          elsif validator?(filter)
+            validator_type(filter)
+          else
+            normalize_validation_name(filter.to_s)
+          end
+        end
+
+        def human_method_name(filter)
+          case filter
+          when Proc then format_proc_location(filter)
+          when Class, ActiveModel::Validator then format_validator(filter)
+          else filter.to_s
+          end
+        end
+
+        private
+
+        def presence_validator?(filter)
+          filter.is_a?(ActiveRecord::Validations::PresenceValidator)
+        end
+
+        def association_attribute?(attribute, model, macro)
+          model.reflect_on_association(attribute)&.macro == macro
+        end
+
+        def validator?(obj)
+          obj.class <= ActiveModel::EachValidator
+        end
+
+        def validator_type(validator)
+          validator.class.name.demodulize.sub("Validator", "").underscore
+        end
+
+        def normalize_validation_name(name)
+          case name
+          when STANDARD_VALIDATION_PATTERN, /^validate_(#{STANDARD_VALIDATIONS.join("|")})$/
+            $1
+          when /associated_records_for_/
+            "associated"
+          else
+            "custom"
+          end
+        end
+
+        def format_proc_location(proc)
+          location = proc.source_location
+          return "Proc (unknown location)" unless location
+
+          file = location.first.split("/").last(2).join("/")
+          "Proc (#{file}:#{location.last})"
+        end
+
+        def format_validator(validator)
+          "#{validator.class.name.split("::").last} (#{validator.attributes.join(", ")})"
+        end
+      end
+    end
+  end
+end

data/lib/callback_hell/callback.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module CallbackHell
+  class Callback
+    attr_reader :model, :method_name, :conditional, :origin, :inherited, :kind,
+      :association_generated, :attribute_generated, :callback, :defining_class,
+      :fingerprint
+
+    def initialize(model:, rails_callback:, name:, defining_class:)
+      @model = model
+      @callback = rails_callback
+      @name = name
+      @defining_class = defining_class
+
+      analyzer = Analyzers::CallbackAnalyzer.new(@callback, model, defining_class)
+
+      @kind = @callback.kind
+      @method_name = @callback.filter
+      @conditional = analyzer.conditional?
+      @origin = analyzer.origin
+      @inherited = analyzer.inherited?
+      @association_generated = analyzer.association_generated?
+      @attribute_generated = analyzer.attribute_generated?
+      # fingerprint allows us to de-duplicate callbacks/validations;
+      # in most cases, it's just an object_id, but for named validations/callbacks,
+      # it's a combination of the name, kind and the method_name.
+      # The "0" and "1" prefixes define how to handle duplicates (1 means last write wins, 0 means first write wins)
+      @fingerprint = (@method_name.is_a?(Symbol) && @origin != :rails) ? ["1", @name, @kind, @method_name].join("-") : "0-#{@callback.object_id}"
+    end
+
+    def callback_group
+      @name.to_s
+    end
+
+    def validation_type
+      return nil unless callback_group == "validate"
+      Analyzers::ValidationAnalyzer.detect_type(@callback.filter, model)
+    end
+
+    def human_method_name
+      Analyzers::ValidationAnalyzer.human_method_name(@callback.filter)
+    end
+
+    def to_s
+      [
+        "#{model.name}: #{human_method_name}",
+        "kind=#{kind}_#{callback_group}",
+        "origin=#{origin}",
+        inherited ? "inherited=true" : nil,
+        conditional ? "conditional=true" : nil,
+        association_generated ? "association=true" : nil,
+        attribute_generated ? "attribute=true" : nil
+      ].compact.join(" ")
+    end
+  end
+end

data/lib/callback_hell/collector.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "set"
+
+module CallbackHell
+  class Collector
+    attr_reader :models
+
+    def initialize(models = nil, paths: nil, kind: :callbacks, mode: :default)
+      @paths = paths
+      @kind = kind
+      @mode = mode
+
+      eager_load!
+      @models = Set.new(models ? [*models] : ApplicationRecord.descendants)
+    end
+
+    def collect(select_models = models)
+      select_models.flat_map { |model| collect_for_model(model) }
+    end
+
+    private
+
+    def eager_load!
+      Rails.application.eager_load!
+      load_additional_paths
+    end
+
+    def collect_for_model(model)
+      model.ancestors.select { |ancestor| ancestor < ActiveRecord::Base }
+        # collect from parent to child to correctly handle inheritance
+        .reverse
+        .flat_map { |ancestor| collect_callbacks_for_class(model, ancestor) }
+        .group_by(&:fingerprint)
+        # merge groups
+        .transform_values do |callbacks|
+          probe = callbacks.first
+          if probe.fingerprint.start_with?("1")
+            # we must keep the last non-matching callback (i.e., if all callbacks are the same,
+            # we must keep the first one)
+            callbacks.each do |clbk|
+              if clbk.callback != probe.callback
+                probe = clbk
+              end
+            end
+          end
+          probe
+        end
+        .values
+    end
+
+    def collect_callbacks_for_class(model, klass)
+      callbacks = klass.__callbacks
+      callbacks = callbacks.slice(:validate) if @kind == :validations
+
+      callbacks.flat_map do |kind, chain|
+        chain.map { |callback| build_callback(model, callback, kind, klass) }
+      end.then do |collected|
+        next collected if @mode == :full
+
+        collected.reject do |c|
+          c.association_generated || c.attribute_generated || (
+            @kind != :validations && c.callback_group == "validate"
+          )
+        end
+      end
+    end
+
+    def build_callback(model, callback, kind, klass)
+      Callback.new(
+        model: model,
+        rails_callback: callback,
+        name: kind,
+        defining_class: klass
+      )
+    end
+
+    def load_additional_paths
+      model_paths.each do |path|
+        Dir[File.join(path, "**", "*.rb")].sort.each { |file| require_dependency file }
+      end
+    end
+
+    def model_paths
+      @model_paths ||= begin
+        paths = engine_paths
+        paths += [@paths] if @paths
+        paths.select(&:exist?)
+      end
+    end
+
+    def engine_paths
+      @engine_paths ||= Rails::Engine.subclasses.map { |engine| engine.root.join("app/models") }
+    end
+  end
+end

data/lib/callback_hell/railtie.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module CallbackHell
+  class Railtie < ::Rails::Railtie
+    load "tasks/callback_hell.rake"
+  end
+end

data/lib/callback_hell/reports/base.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module CallbackHell
+  module Reports
+    class Base
+      attr_reader :callbacks, :stats
+
+      def initialize(callbacks, **opts)
+        @callbacks = callbacks
+        @stats = Stats.new(callbacks, **opts)
+      end
+
+      def generate
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/callback_hell/reports/callbacks/github.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module CallbackHell
+  module Reports
+    module Callbacks
+      class Github < GithubBase
+        private
+
+        def report_title
+          "Callback Hell callbacks report"
+        end
+
+        def format_group_name(callback)
+          "#{timing_symbol(callback.kind)}/#{callback.callback_group}"
+        end
+
+        def timing_symbol(timing)
+          case timing
+          when :before, "before" then "⇥"
+          when :after, "after" then "↦"
+          when :around, "around" then "↔"
+          else
+            "  "
+          end
+        end
+      end
+    end
+  end
+end