Turbulence visualizes churn vs complexity for your Ruby codebase, helping you identify files that are both highly complex and frequently changed - prime candidates for refactoring.
Based on Michael Feathers' work on getting empirical about refactoring.
The scatter plot places each file according to its churn (x-axis) and complexity (y-axis):
| Quadrant | Location | What it means |
|---|---|---|
| Danger Zone | Upper right | High complexity + high churn. These files change often and are hard to work with. Prime refactoring candidates! |
| Healthy Closure | Lower left | Low complexity + low churn. Stable, well-factored code. Leave it alone. |
| Cowboy Code | Upper left | High complexity + low churn. Complex code that sprang from someone's head fully formed. May need attention if it starts changing. |
| Fertile Ground | Lower right | Low complexity + high churn. Often configuration or incubators for new abstractions. Code grows here, then gets extracted. |
- Ruby 3.0 or later
- Git or Perforce
gem install turbulenceIn your project directory, run:
buleThis generates and opens turbulence/turbulence.html with an interactive scatter plot.
bule [options] [directory]
Options:
--scm p4|git SCM to use (default: git)
--churn-range A..B Commit range to compute file churn
--churn-mean Calculate mean churn instead of cumulative
--exclude PATTERN Exclude files matching pattern
--treemap Output treemap graph instead of scatter plot
--no-open Skip opening the report in a browser
--output DIR Output directory for reports (default: ./turbulence)# Analyze current directory
bule
# Analyze a specific directory
bule path/to/project
# Use Perforce instead of Git
bule --scm p4
# Analyze only recent changes
bule --churn-range HEAD~100..HEAD
# Generate report without opening browser (useful for CI)
bule --no-open
# Output to a custom directory
bule --output spec/reports/turbulence
# Exclude test files
bule --exclude specFor Perforce, set the P4CLIENT environment variable to your client workspace name:
export P4CLIENT=my-workspace
bule --scm p4Turbulence generates a JavaScript file containing your file paths and names. If these are sensitive, be careful where you put the generated files and who you share them with.
Bug reports and pull requests are welcome on GitHub.