Attractor
A code complexity metrics visualization and exploration tool for Ruby and JavaScript
---
![Build Status][build-status]
![Ruby Tests Action Status][ruby-tests-action-shield]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![MIT License][license-shield]][license-url]
[](#contributors-)
![attractor_v0 6 1][demo-gif]
## Table of Contents
- [Table of Contents](#table-of-contents)
- [Introduction](#introduction)
- [Installation](#installation)
- [Usage](#usage)
- [Live Reloading](#live-reloading)
- [CI Usage](#ci-usage)
- [Github Action](#github-action)
- [Gitlab Example](#gitlab-example)
- [CLI Commands and Options](#cli-commands-and-options)
- [Development](#development)
- [Contributing](#contributing)
- [Logo Attribution](#logo-attribution)
- [Contributors ✨](#contributors-%e2%9c%a8)
## Introduction
Many authors ([Michael Feathers][michael-feathers-article], [Sandi Metz][sandi-metz-article] 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][medium-article] explaining the approach in greater detail.
## Installation
Attractor's installation is standard for a Ruby gem:
```sh
gem install attractor
```
You'll also want to install some plugins to go along with the main gem:
```sh
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][bundler]:
```ruby
gem 'attractor'
gem 'attractor-ruby'
gem 'attractor-javascript'
```
And then execute:
```sh
bundle
```
## Usage
To create a HTML report in `attractor_output/index.html`:
```sh
attractor report
```
If you'd like to specify a directory, use the file prefix option:
```sh
attractor report --file_prefix app/models
```
Or shorter:
```sh
attractor report -p app/models
```
Check JavaScript:
```sh
attractor report -p app/javascript -t js
```
Watch for file changes:
```sh
attractor report -p app/models --watch
```
Serve at `http://localhost:7890`:
```sh
attractor serve -p app/models
```
Enable [rack-livereload][rack-livereload]:
```sh
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][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][attractor-action] that will compile Attractor's output.
You can quickly integrate it into your action's workflow by grabbing it on the [Marketplace][attractor-action-marketplace].
### Gitlab Example
The simplest use case is to store the `attractor_output` directory as an artifact.
```yml
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
Print a simple output to console:
```sh
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
```sh
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 `http://localhost:7890`
```sh
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)
```
## 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](https://rubygems.org).
## Contributing
Bug reports and pull requests are welcome on [GitHub][repo].
## Logo Attribution
[Black Hole by Eynav Raphael from the Noun Project][logo-source]
## Contributors ✨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
