Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/julianrubisch/attractor

code complexity metrics visualization and exploration tool for ruby and javascript
https://github.com/julianrubisch/attractor

churn code-quality complexity es6 javascript ruby

Last synced: 5 days ago
JSON representation

code complexity metrics visualization and exploration tool for ruby and javascript

Host: GitHub
URL: https://github.com/julianrubisch/attractor
Owner: julianrubisch
License: mit
Created: 2019-08-21T12:31:07.000Z (over 5 years ago)
Default Branch: master
Last Pushed: 2024-01-27T13:08:56.000Z (11 months ago)
Last Synced: 2024-12-15T05:04:56.346Z (12 days ago)
Topics: churn, code-quality, complexity, es6, javascript, ruby
Language: JavaScript
Homepage:
Size: 8.14 MB
Stars: 357
Watchers: 4
Forks: 8
Open Issues: 13
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE

Awesome Lists containing this project

README

        

[forks-shield]: https://img.shields.io/github/forks/julianrubisch/attractor.svg?style=flat-square

[forks-url]: https://github.com/julianrubisch/attractor/network/members

[stars-shield]: https://img.shields.io/github/stars/julianrubisch/attractor.svg?style=flat-square

[stars-url]: https://github.com/julianrubisch/attractor/stargazers

[issues-shield]: https://img.shields.io/github/issues/julianrubisch/attractor.svg?style=flat-square

[issues-url]: https://github.com/julianrubisch/attractor/issues

[license-shield]: https://img.shields.io/github/license/julianrubisch/attractor.svg?style=flat-square

[license-url]: https://github.com/julianrubisch/attractor/blob/master/LICENSE

[twitter-url]: https://twitter.com/AttractorGem

[twitter-shield]: https://img.shields.io/twitter/follow/AttractorGem?style=social

[twitter-shield]: https://img.shields.io/twitter/follow/AttractorGem?style=social

[ruby-tests-action-shield]: https://github.com/julianrubisch/attractor/workflows/Ruby%20Tests/badge.svg

[demo-gif]: https://user-images.githubusercontent.com/4352208/67033292-b41e4280-f115-11e9-8c91-81b3bea4451c.gif

[logo-source]: https://thenounproject.com/term/black-hole/1043893

[medium-article]: https://medium.com/better-programming/why-i-made-my-own-code-quality-tool-c44b40ceaafd

[sandi-metz-article]: https://www.sandimetz.com/blog/2017/9/13/breaking-up-the-behemoth

[michael-feathers-article]: https://www.agileconnection.com/article/getting-empirical-about-refactoring

[bundler]: https://bundler.io

[rack-livereload]: https://github.com/johnbintz/rack-livereload

[guard-livereload]: https://github.com/guard/guard-livereload

[attractor-action]: https://github.com/julianrubisch/attractor-action

[attractor-action-marketplace]: https://github.com/marketplace/actions/attractor-action

[repo]: https://github.com/julianrubisch/attractor






  

    

  

  Attractor

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


---

![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]

[![Twitter follow][twitter-shield]][twitter-url]

[![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square)](#contributors-)

  



![attractor_v0 6 1][demo-gif]

**If you are looking for a managed solution to observe your code's quality, check out [UseAttractor](https://useattr.actor)**

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

Initialize the local cache:

```sh

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:

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

  --ignore|-i 'spec/*_spec.rb,db/schema.rb,tmp'

```

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)

  --ignore|-i 'spec/*_spec.rb,db/schema.rb,tmp'

```

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)

  --ignore|-i 'spec/*_spec.rb,db/schema.rb,tmp'

```

Clear the local cache:

```sh

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](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)):

  

    
_{Julian Rubisch}
💻 📖

    
_Olivier
🚧

    
_{Andrew Mason}
💻 👀 📖

    
_{Ernesto Tagwerker}
💻

    
_{Manuel Tancoigne}
💻

  

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!