RuboCop::SortedMethodsByCall

Repobeats CI Gem Version

Enforces “waterfall” method ordering: define methods after any method that calls them within the same scope.

Features

  • Waterfall ordering enforcement: Caller methods must be defined before their callees;

  • Smart visibility handling: Respects private/protected/public sections;

  • Safe mutual recursion: Handles recursive method calls gracefully;

  • Autocorrection support: Automatically reorders methods (opt-in with -A);

  • Full RuboCop integration: Works seamlessly with modern RuboCop plugin system;

  • Comprehensive scope support: Classes, modules, singleton classes, and top-level;

Installation

Add this line to your application’s Gemfile:

gem 'rubocop-sorted_methods_by_call'

And then execute:

bundle install

Or install it yourself:

gem install rubocop-sorted_methods_by_call

Configuration

Basic Setup

Add to your .rubocop.yml:

plugins:
  - rubocop-sorted_methods_by_call

SortedMethodsByCall/Waterfall:
  Enabled: true

Configuration Options

SortedMethodsByCall/Waterfall:
  Enabled: true
  SafeAutoCorrect: false          # Autocorrection requires -A flag
  AllowedRecursion: true          # Allow mutual recursion (default: true)

Usage Examples

Good Code (waterfall order)

In waterfall ordering, callers come before callees. This creates a top-down reading flow where main logic appears before implementation details.


class Service
  def call
    foo
    bar
  end

  private

  def bar
    method123
  end

  def method123
    foo
  end

  def foo
    123
  end
end

Bad Code (violates waterfall order)


class Service
  def call
    foo
    bar
  end

  private

  def foo # ❌ Offense: Define #foo after its caller #method123
    123
  end

  def bar
    method123
  end

  def method123
    foo
  end
end

Autocorrection

Run with unsafe autocorrection to automatically fix violations:

bundle exec rubocop -A

This will reorder the methods while preserving comments and visibility modifiers.

Testing

Run the test suite:

bundle exec rspec

Run RuboCop on the gem itself:

bundle exec rubocop
bundle exec rubocop --config test_project/.rubocop.test.yml lib/ -A

Development

After checking out the repo, run:

bin/setup

This will install dependencies and start an interactive console.

Available Commands

  • bin/console - Interactive development console

  • bin/setup - Install dependencies and build gem

  • bundle exec rake - Run tests and linting

Release Process

  1. Update version in lib/rubocop/sorted_methods_by_call/version.rb

  2. Create and push a git tag: git tag v0.1.0 && git push origin v0.1.0

  3. GitHub Actions will automatically:

    • Build the gem

    • Publish to RubyGems.org

    • Create a GitHub release

Requirements

  • Ruby: >= 2.7

  • RuboCop: >= 1.72.0 (required for plugin system)

Contributing

Bug reports and pull requests are welcome! Please follow these guidelines:

  1. Fork the repository

  2. Create your feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -am 'Add amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a pull request

Please ensure your code passes all tests and follows the existing style.

Documentation

Code is covered with YARD docs, you can access online docs at unurgunite.github.io/rubocop-sorted_methods_by_call_docs/

License

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

Code of Conduct

Everyone interacting with this project is expected to follow the Code of Conduct.

Note: This gem implements true waterfall ordering that considers the complete call graph across all methods in a scope. Methods are ordered so that every callee appears after all of its callers, creating a natural top-down reading flow.