README.md

Attractor

A code complexity metrics visualization and exploration tool for Ruby and JavaScript

---

If you are looking for a managed solution to observe your code's quality, check out UseAttractor

Table of Contents

• Table of Contents
• Introduction
• Installation
• Usage
  • Live Reloading
• CI Usage
  • Github Action
  • Gitlab Example
• CLI Commands and Options
• Development
• Contributing
• Logo Attribution
• Contributors ✨

Introduction

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 churn and flog projects.

Here's an article on medium explaining the approach in greater detail.

Installation

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:

gem install attractor-ruby # https://github.com/julianrubisch/attractor-ruby
gem install attractor-javascript # https://github.com/julianrubisch/attractor-javascript

You will most likely want to install Attractor using Bundler:

gem 'attractor'
gem 'attractor-ruby'
gem 'attractor-javascript'

And then execute:

bundle

Usage

To create a HTML report in attractor_output/index.html:

attractor report

If you'd like to specify a directory, use the file prefix option:

attractor report --file_prefix app/models

Or shorter:

attractor report -p app/models

Check JavaScript:

attractor report -p app/javascript -t js

Watch for file changes:

attractor report -p app/models --watch

Serve at http://localhost:7890:

attractor serve -p app/models

Enable rack-livereload:

attractor serve -p app/models --watch

Make sure you prefix these commands with bundle exec if you are using Bundler.

Live Reloading

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 guard-livereload changes.

CI Usage

To use this CLI in a CI environment, use the --ci option, which will suppress automatic opening of a browser window.

Github Action

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.

Gitlab Example

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

CLI Commands and Options

Initialize the local cache:

attractor init
  --file_prefix|-p app/models
  --type|-t rb|js
  --start_ago|-s  (e.g. 5y, 3m, 7w)
  --minimum_churn|-c (minimum times a file must have changed to be processed)
  --ignore|-i 'spec/*_spec.rb,db/schema.rb,tmp'

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)
  --ignore|-i 'spec/*_spec.rb,db/schema.rb,tmp'

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)
  --ignore|-i 'spec/*_spec.rb,db/schema.rb,tmp'

Serve the output on http://localhost:7890

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)
  --ignore|-i 'spec/*_spec.rb,db/schema.rb,tmp'

Clear the local cache:

attractor clean

Development

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.

Contributing

Bug reports and pull requests are welcome on GitHub.

Logo Attribution

Black Hole by Eynav Raphael from the Noun Project

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Julian Rubisch 💻 📖

Olivier 🚧

Andrew Mason 💻 👀 📖

Ernesto Tagwerker 💻

Manuel Tancoigne 💻

This project follows the all-contributors specification. Contributions of any kind welcome!