Stellwerk

Stellwerk is a Ruby gem that helps you enforce architectural rules in your Ruby on Rails application. It analyzes your codebase and identifies violations of architectural constraints you specify.

Name

The name "Stellwerk" is derived from the German word for "signal station" in a railway context. It keeps your Rails on track!

Installation

Install the gem and add to the application's Gemfile by executing:

bundle add stellwerk

If bundler is not being used to manage dependencies, install the gem by executing:

gem install stellwerk

Usage

Create a stellwerk.yml in the root of your Rails application that defines at least one rule.

Run the check task in your Rails app:

bin/rails stellwerk:check

Run a simpler check without booting :environment (uses statically defined Zeitwerk loaders for app/* and lib) and will probably miss stuff in more complex Rails apps:

bin/rails stellwerk:check_simple

Rules

Rules are defined in the stellwerk.yml file.

Layered Architecture

The Layered Architecture rule enforces that files in one layer do not reference files in a layer that is "above" it.

Example configuration with three layers:

rules:
  layers:
    - app/controllers
    - [ app/jobs, app/models ]
    - lib

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

Publishing to RubyGems

Update the version in lib/stellwerk/version.rb. Push / merge to main.
rake release

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/exterm/stellwerk. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

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

Code of Conduct

Everyone interacting in the Stellwerk project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.