mattknox / metric_fu forked from jscruggs/metric_fu

Version 0.9.0
http://github.com/jscruggs/metric_fu

Metric_fu began its life as a plugin for Rails that generated code metrics reports.  As of version 0.7.0, metric_fu is a 
gem owing to the excellent work done by Sean Soper.  

Metric_fu is a set of rake tasks that make it easy to generate metrics reports.  It uses Saikuro, Flog, Rcov, and Rails' 
built-in stats task to create a series of reports.  It's designed to integrate easily with CruiseControl.rb by placing 
files in the Custom Build Artifacts folder.

****Installation****
sudo gem install jscruggs-metric_fu -s http://gems.github.com

Then in your Rakefile:
require 'metric_fu'

If you like to vendor gems, you can unpack metric_fu into vendor/gems and require it like so:
require 'vendor/gems/jscruggs-metric_fu-0.9.0/lib/metric_fu'

then you don't have to install it on every box you run it on.

Important note:
You must have Rcov and Flog installed to get coverage and flog reports.  Metric_fu requires both of these gems so they 
will be installed when you install the metric_fu gem.


****Usage****

Out of the box metrics provides these tasks:
rake metrics:all                  # Generate coverage, cyclomatic complexity, flog, flay, railroad and churn reports
rake metrics:churn                # Which files change the most
rake metrics:coverage             # Generate and open coverage report
rake metrics:coverage:clean       # Delete aggregate coverage data.
rake metrics:coverage:clobber_do  # Remove rcov products for do
rake metrics:coverage:do          # RCov task to generate report
rake metrics:flay                 # Generate code duplication report with flay
rake metrics:flog:all             # Generate and open flog report
rake metrics:flog:clean           # Delete aggregate flog data.
rake metrics:flog:controllers     # Flog code in app/controllers
rake metrics:flog:custom          # Generate a flog report from specified directories
rake metrics:flog:helpers         # Flog code in app/helpers
rake metrics:flog:lib             # Flog code in lib
rake metrics:flog:models          # Flog code in app/models
rake metrics:reek                 # A code smell report using Reek
rake metrics:saikuro              # A cyclomatic complexity report using Saikuro

Rails projects also have the following tasks:

rake metrics:stats                 # A stats report

See below for more detail on the individual tasks.  It's recommended to use CruiseControl.rb to set up a metrics build.  
See the CruiseControl.rb online docs for more info on how to set up cc.rb and, once you've got that figured out, change 
the cruise_config.rb file inside your project to have these lines:

project.rake_task = 'metrics:all_with_migrate'
project.scheduler.polling_interval = 24.hours

Which will check for updates every 24 hours and run all the metrics rake tasks (migrating your test db first).  The 
output will be visible from an individual build's detail page.


****Notes on configuration****

Metric_fu can be customized to your liking by adding the following to your Rakefile

MetricFu::Configuration.run do |config|
  #define which metrics you want to use
  config.metrics          = [:coverage, :flog]
  config.churn    = { :start_date => lambda{ 3.months.ago } }  
  config.coverage = { :test_files => ['test/**/test_*.rb'] }
  config.flog     = { :dirs_to_flog => ['cms/app', 'cms/lib']  }
  config.flay     = { :dirs_to_flay => ['cms/app', 'cms/lib']  }  
  config.saikuro  = { "--warn_cyclo" => "3", "--error_cyclo" => "4" }
end


****Notes on metrics:coverage****

When creating a coverage report, metric_fu runs all the tests in the test folder and specs in spec folder using Rcov.
You can configure the coverage test files pattern:
  config.coverage[:test_files] = ['test/**/test_*.rb']

The default value is ['test/**/*_test.rb', 'spec/**/*_spec.rb']

You may also configure Rcov options:
  config.coverage = { :test_files => ['test/**/*_test.rb'],
                :rcov_opts => ["--exclude /gems/,/Library/"] }
                
The default value is  { :test_files => ['test/**/*_test.rb', 'spec/**/*_spec.rb'],
                        :rcov_opts => ["--sort coverage", "--html", "--rails", "--exclude /gems/,/Library/,spec"] }


****Notes on metrics:saikuro****

Saikuro is bundled with metric_fu so you don't have to install it.  Look at the SAIKURO_README (or the internet) for 
more documentation on Saikuro.  If you wish to change the options Saikuro is run with, then set this constant in your 
configuration:

  config.saikuro = { "--warn_cyclo" => "3", "--error_cyclo" => "4" }

config.saikuro is a hash that gets merged with the default options hash.  The above example will set the warn_cyclo to 3 
and the error_cyclo to 4 (which is way too low -- it's just an example) instructing Saikuro to flag methods with a 
higher cyclomatic complexity in it's report.

If you want to have Saikuro look at multiple folders you can put something like this in your configuration:

  config.saikuro = {"--input_directory" => '"cms/app | cms/lib"'}


****Notes on metrics:flay****

Flay analyzes ruby code for structural similarities. 
You can configure which directories need to be flayed.
The defaults are 'lib' for non Rails projects and ['app', 'lib'] for Rails projects.

  config.flay[:dirs_to_flay] = ['cms/app', 'cms/lib']


****Notes on metrics:flog****

Flog is another way of measuring complexity (or tortured code as the Flog authors like to put it).  You should check out 
the awesome, and a little scary, Flog website for more info.
'rake metrics:flog:custom' allows you to specify a custom set of directories to Flog (in your configuration).
The defaults are 'lib' for non Rails projects and ['app', 'lib'] for Rails projects.

  config.flog[:dirs_to_flog] = ['cms/app', 'cms/lib']


****Notes on metrics:reek****

Reek detects common code smells in ruby code.
You can configure which directories need to be checked.
The defaults are 'lib' for non Rails projects and ['app', 'lib'] for Rails projects.

  config.reek[:dirs_to_reek] = ['cms/app', 'cms/lib']


****Notes on metrics:roodi****

Roodi parses your Ruby code and warns you about design issues you have based on the checks that is has configured.
You can configure which directories need to be checked.
The defaults are 'lib' for non Rails projects and ['app', 'lib'] for Rails projects.

    config.roodi[:dirs_to_roodi] = ['cms/app', 'cms/lib']

****Notes on metrics:stats****

This is just 'rake stats' for Rails put into a file.  On my projects I like to be able to look at CruiseControl and get 
stats about the app at different points in time.


****Notes on metrics:churn****

Files that change a lot in your project may be bad a sign.  This task uses "svn log" to identify those files and put 
them in a report.  The default is to start counting changes from the beginning of your project, which might be too far 
back so you can change like so:

  config.churn = { :start_date => lambda{ 3.months.ago } }

The Proc is there because '3.months.ago' only works when after the Rails Environment is loaded (and Rails extends 
Fixnum) which I didn't want to do every time you run a rake task.

You can also change the minimum churn count like so:

  config.churn = { :minimum_churn_count => 3 }


****Thanks****

I'd like to thank the authors of Saikuro, Flog, Rcov, CruiseControl.rb, Flay, Reek, Roodi and Rails for creating such 
excellent open source products.  Also Andre Arko, Petrik de Heus, Sean Soper, Erik St Martin, Andy Gregorowicz, Bastien, 
Michael Schubert, Kurtis Seebaldt, Toby Tripp, Paul Gross, and Chirdeep Shetty for their help and advice.