chad/turbulence

Hopefully-meaningful metrics

Hopefully-meaningful Metrics

Based on Michael Feathers' recent work in project churn and complexity.

Here is how to read the graph (extracted from the above article):

• The upper right quadrant is particularly important. These files have a high degree of complexity, and they change quite frequently. There are a number of reasons why this can happen. The one to look out for, though, is something I call runaway conditionals. Sometimes a class becomes so complex that refactoring seems too difficult. Developers hack if-then-elses into if-then-elses, and the rat’s nest grows. These classes are particularly ripe for a refactoring investment.

• The lower left quadrant. is the healthy closure region. Abstractions here have low complexity and don't change much.

• The upper left is what I call the cowboy region. This is complex code that sprang from someone's head and didn't seem to grow incrementally.

• The bottom right is very interesting. I call it the fertile ground. It can consist of files that are somewhat configurational, but often there are also files that act as incubators for new abstractions. People add code, it grows, and then they factor outward, extracting new classes. The files churn frequently, but their complexity remains low.

Installation

$ gem install turbulence

Usage

In your project directory, run:

$ bule

and it will generate (and open) turbulence/turbulence.html

Supported SCM systems

Currently, bule defaults to using git. If you are using Perforce, call it like so:

$ bule --scm p4

You need to have an environment variable P4CLIENT set to the name of your client workspace.

WARNING

When you run bule, it creates a JavaScript file which contains your file paths and names. If those are sensitive, be careful where you put these generated files and who you share them with.

turbulence's Issues

Select calculators from command line

If we have multiple Calculators, what would it be like if we ran all the numbers and let end users select which metrics to graph against each other in the report's UI?

Allow setting the path of the turbulence output directory

Ideally, I'd like to have my turbulence charts generated in (for example, a rails project) spec/reports/turbulence. For now I am cd spec/reports and then bule $APP_PATH but it would be preferable to be able to specify this as an option.

Thanks for the great gem!

Add travis to main gem repo

Nice to have, should only take a few minutes.

Finish writing documentation

I added the --treemap option but didn't write up the documentation like I said I would. I was thinking that the README could use a refresh, along with screenshots of the output.

Consider using churn gem

Consider @danmayer's churn gem. One less thing to maintain :)

• https://github.com/danmayer/churn
• https://github.com/danmayer/churn

Update to latest Google Charts

https://developers.google.com/chart/interactive/docs/gallery/treemap

I like the click-through ability and the tooltips, especially.

What's the OSS license for turbulence?

I don't see a LICENSE file or a reference in the README.

Wrong home directory on Windows

On Windows, the home directory is mangled. Bule wants to open

file://C/Users/...

instead of

file://C:/Users/...

(comma missing). This appeared after updating turbulence.

Restrict files included in output

I'm using this on a repo with a huge number of targets, and it makes the resulting graphs tough to navigate. I wonder if restricting the number of files included in the output analysis would be useful. I could see restricting to only the worst N offenders, or only the files that are in the "upper right" quadrant, or the "worst 50% of files".. or all three. This would require running a full analysis, then processing the result set before beginning graphing. Would also need to add CLI options supporting this.

Add --include flag to filter only matching a regex

An --include flag would be helpful to find well-namespaced files in a large monolith.

Command line error

Hi guys, I would like to generate the Javascript files and html file to be published to an HTML report in Jenkins. However, I keep getting a command line error because it tries to trigger a browser launch through Launchy. Is there any way that I can disable this trigger?

Release 1.2.1

I bumped the gem version to reflect the windows support, might as well officially release it.

Getting `stack level too deep (SystemStackError)`

I'm currently unable to run the latest version of this gem, 1.2.2. The 1.2.0 version does work though.

The Ruby version doesn't seem to matter, as I tested this in both 1.9.3 and 2.1.1.

Unfortunately, the stack trace from running bule is incredibly unhelpful:

/usr/local/rvm/gems/ruby-2.1.1/bin/ruby_executable_hooks:15: stack level too deep (SystemStackError)

I'd love to know of a way to improve this stack trace.

Add cyclometric complexity calculator

I love flog, but if we're opening up the calculator system to be more extensible, shipping with a cyclometric complexity calculator would be a useful.

Refactoring to Instances

I'd like to convert the calculators to instances, allowing configuration to be applied on a per instance (rather than per class) basis. My thinking is that this will allow different SCM handlers and calculators to be implemented more cleanly. This would be a fairly large change, so I wanted to make sure this doesn't fly in the face of an existing design philosophy.

Specs are leaking state

Steps to reproduce:

1. Update rspec dependency to a version that supports the "--order random" command line flag. (I used "~> 2.14.0".)
2. Run rspec --order random a few times.
   3a) Note that not all runs have the same pass/fail status.
   3b) Note that different runs output "sh: git: No such file or directory" a varying number of times. (I haven't tracked this one down yet, so it may only occur on my machine.)

Upgrade/improve treemap output

The D3 library offers a much more visual pleasing treemap, along with more interaction options. One example might be to be able to view not just a treemap of the files, but view the treemap distribution by directory, and allow you to click through each folder to see the tree map of its contents, until you reach a specific file, and then you get a treemap of its methods sized according to flog score?