Many authors (Michael Feathers, Sandi Metz) have shown that an evaluation of churn vs complexity of files in software projects provide a valuable metric towards code quality. This is another take on the matter, for ruby code, using the
Here's an article on medium explaining the approach in greater detail.
Attractor's installation is standard for a Ruby gem:
gem install attractor
You'll also want to install some plugins to go along with the main gem:
You will most likely want to install Attractor using Bundler:
And then execute:
To create a HTML report in
If you'd like to specify a directory, use the file prefix option:
attractor report --file_prefix app/models
attractor report -p app/models
Watch for file changes:
attractor report -p app/models --watch
attractor serve -p app/models
attractor serve -p app/models --watch
Make sure you prefix these commands with
bundle exec if you are using Bundler.
If you have guard-livereload (or a similar service) running on your project, you can leverage the hot reloading functionality by specifying
--watch|-w. Attractor will then live-reload the browser window when a file watched by
To use this CLI in a CI environment, use the
--ci option, which will suppress automatic opening of a browser window.
There is a dedicated Github Action that will compile Attractor's output.
You can quickly integrate it into your action's workflow by grabbing it on the Marketplace.
The simplest use case is to store the
attractor_output directory as an artifact.
attractor: stage: your-stage-label image: ruby:latest script: - gem install attractor - attractor report --ci artifacts: when: on_success paths: - attractor_output
Print a simple output to console:
attractor calc --file_prefix|-p app/models --type|-t rb|js --watch|-w --start_ago|-s (e.g. 5y, 3m, 7w) --minimum_churn|-c (minimum times a file must have changed to be processed)
Generate a full report
attractor report --file_prefix|-p app/models --type|-t rb|js --watch|-w --no-open-browser|--ci --start_ago|-s (e.g. 5y, 3m, 7w) --minimum_churn|-c (minimum times a file must have changed to be processed)
Serve the output on
attractor serve --file_prefix|-p app/models --watch|-w --no-open-browser|--ci --start_ago|-s (e.g. 5y, 3m, 7w) --minimum_churn|-c (minimum times a file must have changed to be processed)
After checking out the repo, run
bin/setup to install dependencies. You can also run
bin/console for an interactive prompt that will allow you to experiment.
To run all tests, run
bin/test. You can run the specs by themselves with
bundle exec rspec, and the cucumber features with
bundle exec cucumber.
To install this gem onto your local machine, run
bundle exec rake install. To release a new version, update the version number in
version.rb, and then run
bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the
.gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub.
Thanks goes to these wonderful people (emoji key):
💻 👀 📖
This project follows the all-contributors specification. Contributions of any kind welcome!