https://github.com/evilmartians/callback_hell
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.
https://github.com/evilmartians/callback_hell
callbacks profiling refactoring ruby ruby-gem ruby-on-rails
Last synced: 3 months ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/evilmartians/callback_hell
- Owner: evilmartians
- License: mit
- Created: 2025-08-27T10:04:01.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-08-27T20:33:57.000Z (6 months ago)
- Last Synced: 2025-08-27T23:32:26.184Z (6 months ago)
- Topics: callbacks, profiling, refactoring, ruby, ruby-gem, ruby-on-rails
- Language: Ruby
- Homepage:
- Size: 141 KB
- Stars: 29
- Watchers: 1
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
[](https://rubygems.org/gems/callback_hell) [](https://github.com/evilmartians/callback_hell/actions)
# 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`:
```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:
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 either `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 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
```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=total
# Sort alphabetically
bin/rails ch sort=name
```
#### 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 supposed to be 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 were done by [Vladimir Dementyev](https://github.com/palkan) who initially offered it as a Ruby developer candidate take-home task for [Evil Martians](https://evilmartians.com/?utm_source=callback_hell).
Shout-out to [Adam Doppelt](https://github.com/gurgeous) for [table_tennis](https://github.com/gurgeous/table_tennis) that we use for formatting tables.
## 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).