Callback Hell

You live in it.

Callback Hell is a Ruby gem that analyzes your Ruby on 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.

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:

gem "callback_hell", group: :development

And then:

bundle install

Basic usage

Generate a complete analysis report (callbacks and validations):

bin/rails ch

Sample output:

Or run specific reports:

# 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 either rake or bin/rails as you wish.

Command line options

All rake tasks support the following options:

Output formats

# Table format (default)
bin/rails ch:callbacks format=table

# Line format: detailed per-callback breakdown
bin/rails ch:callbacks format=line

# GitHub Actions format for CI/CD
bin/rails ch:callbacks format=github

Model filtering

# 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

# Sort by callback count (default)
bin/rails ch sort=total

# Sort alphabetically
bin/rails ch sort=name

Analysis modes

# 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

# 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:

# .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 supposed to be a spiritual successor of the arca gem by Jonathan Hoyt.

The entire idea and a detailed specification for the gem were done by Vladimir Dementyev who initially offered it as a Ruby developer candidate take-home task for Evil Martians.

Shout-out to Adam Doppelt for table_tennis that we use for formatting tables.

Contributing

Bug reports and pull requests are welcome at https://github.com/evilmartians/callback_hell.

License

The gem is available as open source under the terms of the MIT License.