Awesome Open Source
Awesome Open Source

Logo

Attractor

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


Build Status Ruby Tests Action Status Forks Stargazers Issues MIT License Twitter follow

All Contributors

Become a Patron!

attractor_v0 6 1

Table of Contents

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

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 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)

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

💻

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


Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
javascript (67,454) 
ruby (12,277) 
es6 (513) 
code-quality (78) 
complexity (17) 

Find Open Source By Browsing 7,000 Topics Across 59 Categories

Advertising 📦 10
All Projects
Application Programming Interfaces 📦 124
Applications 📦 192
Artificial Intelligence 📦 78
Blockchain 📦 73
Build Tools 📦 113
Cloud Computing 📦 80
Code Quality 📦 28
Collaboration 📦 32
Command Line Interface 📦 49
Community 📦 83
Companies 📦 60
Compilers 📦 63
Computer Science 📦 80
Configuration Management 📦 42
Content Management 📦 175
Control Flow 📦 213
Data Formats 📦 78
Data Processing 📦 276
Data Storage 📦 135
Economics 📦 64
Frameworks 📦 215
Games 📦 129
Graphics 📦 110
Hardware 📦 152
Integrated Development Environments 📦 49
Learning Resources 📦 166
Legal 📦 29
Libraries 📦 129
Lists Of Projects 📦 22
Machine Learning 📦 347
Mapping 📦 64
Marketing 📦 15
Mathematics 📦 55
Media 📦 239
Messaging 📦 98
Networking 📦 315
Operating Systems 📦 89
Operations 📦 121
Package Managers 📦 55
Programming Languages 📦 245
Runtime Environments 📦 100
Science 📦 42
Security 📦 396
Social Media 📦 27
Software Architecture 📦 72
Software Development 📦 72
Software Performance 📦 58
Software Quality 📦 133
Text Editors 📦 49
Text Processing 📦 136
User Interface 📦 330
User Interface Components 📦 514
Version Control 📦 30
Virtualization 📦 71
Web Browsers 📦 42
Web Servers 📦 26
Web User Interface 📦 210