# MetricFu [![Gem Version](https://badge.fury.io/rb/metric_fu.png)](http://badge.fury.io/rb/metric_fu) [![Build Status](https://travis-ci.org/metricfu/metric_fu.png?branch=master)](http://travis-ci.org/metricfu/metric_fu)

[![Code Climate](https://codeclimate.com/github/metricfu/metric_fu.png)](https://codeclimate.com/github/metricfu/metric_fu) [![Dependency Status](https://gemnasium.com/metricfu/metric_fu.png)](https://gemnasium.com/metricfu/metric_fu)

[Rdoc](http://rdoc.info/github/metricfu/metric_fu/)

## Installation

    gem install metric_fu

If you have trouble installing the gem
- try adding metric_fu to your Gemfile and bundling.
- file a ticket on the issues page.

MetricFu is cryptographically signed. To be sure the gem you install hasn't been tampered with:
- Add my public key (if you haven't already) as a trusted certificate `gem cert --add <(curl -Ls https://raw.github.com/metricfu/metric_fu/master/certs/bf4.pem)`
- `gem install metric_fu -P HighSecurity`
- This may cause installation to fail if non-signed dependent gems are also being installed.

## Usage

From your application root. Running via Rake is still supported.

```sh
metric_fu
```

See:
- `metric_fu --help` for more options
- the [.metrics file](https://github.com/metricfu/metric_fu/blob/master/.metrics)
- Documentation and Compatibility below
- There is also a [wiki page of user-maintained usage information](https://github.com/metricfu/metric_fu/wiki#usage)

## Contact

*Code and Bug Reports*

* [Issue Tracker](http://github.com/metricfu/metric_fu/issues)
  * See [CONTRIBUTING](https://github.com/metricfu/metric_fu/blob/master/CONTRIBUTING.md) for how to contribute

*Questions, Problems, Suggestions, etc.*

* [Google Group](https://groups.google.com/forum/#!forum/metric_fu)

## Documentation


## Formatters

### Built-in Formatters

By default, metric_fu will use the built-in html formatter to generate HTML reports for each metric with pretty graphs.

These reports are generated in metric_fu's output directory (```tmp/metric_fu/output```) by default. You can customize the output directory by specifying an out directory at the command line
using a relative path:

```sh
  metric_fu --out custom_directory    # outputs to tmp/metric_fu/custom_directory
```

or a full path:

```sh
  metric_fu --out /home/metrics      # outputs to /home/metrics
```

You can specify a different formatter at the command line by referencing a built-in formatter or providing the fully-qualified name of a custom formatter.


```sh
  metric_fu --format yaml --out custom_report.yml
```

or

```sh
  metric_fu --format MyCustomFormatter
```

### Custom Formatters

You can customize metric_fu's output format with a custom formatter.

To create a custom formatter, you simply need to create a class
that takes an options hash and responds to one or more notifications:

```ruby
 class MyCustomFormatter
   def initialize(opts={}); end    # metric_fu will pass in an output param if provided.

   # Should include one or more of...
   def start; end           # Sent before metric_fu starts metric measurements.
   def start_metric(metric); end   # Sent before individual metric is measured.
   def finish_metric(metric); end   # Sent after individual metric measurement is complete.
   def finish; end           # Sent after metric_fu has completed all measurements.
   def display_results; end     # Used to open results in browser, etc.
 end
```

See [lib/metric_fu/formatter/](lib/metric_fu/formatter/) for examples.

metric_fu will attempt to require a custom formatter by
fully qualified name based on ruby search path. So if you include a custom
formatter as a gem in your Gemfile, you should be able to use it out of the box.
But you may find in certain cases that you need to add a require to
your .metrics configuration file.

For instance, to require a formatter in your app's lib directory:

```ruby
require './lib/my_custom_formatter.rb'
```

### Using Coverage Metrics

in your .metrics file add the below to run pre-generated metrics

```ruby
    MetricFu::Configuration.run do |config|
      config.configure_metric(:rcov) do |rcov|
        rcov.enabled = true
        rcov.external = File.expand_path("coverage/rcov/rcov.txt", Dir.pwd)
        rcov.activate
      end
    end
```

If you want metric_fu to actually run rcov itself (1.8 only), don't specify an external file to read from

#### Rcov metrics with Ruby 1.8

To generate the same metrics metric_fu has been generating run from the root of your project before running metric_fu

```sh
    RAILS_ENV=test rcov $(ruby -e "puts Dir['{spec,test}/**/*_{spec,test}.rb'].join(' ')") --sort coverage --no-html --text-coverage --no-color --profile --exclude-only '.*' --include-file "\Aapp,\Alib" -Ispec > coverage/rcov/rcov.txt
```

#### Simplecov metrics with Ruby 1.9 and 2.0

Add to your Gemfile or otherwise install

```ruby
    gem 'simplecov'
    # https://github.com/kina/simplecov-rcov-text
    gem 'simplecov-rcov-text'
```

Modify your [spec_helper](https://github.com/metricfu/metric_fu/blob/master/spec/spec_helper.rb) as per the SimpleCov docs and run your tests before running metric_fu

```ruby
    #in your spec_helper
    require 'simplecov'
    require 'simplecov-rcov-text'
    SimpleCov.formatter = SimpleCov::Formatter::RcovTextFormatter
    # or
    SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter[
      SimpleCov::Formatter::HTMLFormatter,
      SimpleCov::Formatter::RcovTextFormatter
      ]
    SimpleCov.start
```

## Compatibility

* It is currently testing on MRI (>= 1.9.3), JRuby (19 mode), and Rubinius (19 mode). Ruby 1.8 is no longer supported.

* For 1.8.7 support, see version 3.0.0 for partial support, or 2.1.3.7.18.1 (where [Semantic Versioning](http://semver.org/) goes to die)

* MetricFu  no longer runs any of the analyzed code. For code coverage, You may still use rcov metrics as documented below

* The Cane, Flog, and Rails Best Practices metrics are disabled when Ripper is not available

### Historical

There is some useful-but-out-of-date documentation about configuring metric_fu at http://metricfu.github.io/metric_fu and a change log in the the HISTORY file.

## Resources:

This is the official repository for metric_fu.  The original repository by Jake Scruggs at [https://github.com/jscruggs/metric_fu](https://github.com/jscruggs/metric_fu) has been deprecated.

* [Official Repository](http://github.com/metricfu/metric_fu)
* [Outdated Homepage](http://metricfu.github.io/metric_fu/)
* [List of code tools](https://github.com/metricfu/metric_fu/wiki/Code-Tools)
* [Roadmap](https://github.com/metricfu/metric_fu/wiki/Roadmap)

### Metrics

* [Cane](https://rubygems.org/gems/cane), [Source](http://github.com/square/cane)
* [Churn](https://rubygems.org/gems/churn), [Source](http://github.com/danmayer/churn)
* [Flog](https://rubygems.org/gems/flog), [Source](https://github.com/seattlerb/flog)
* [Flay](https://rubygems.org/gems/flay), [Source](https://github.com/seattlerb/flay)
* [Reek](https://rubygems.org/gems/reek) [Source](https://github.com/troessner/reek)
* [Roodi](https://rubygems.org/gems/roodi), [Source](https://github.com/roodi/roodi)
* [Saikuro](https://rubygems.org/gems/metric_fu-Saikuro), [Source](https://github.com/metricfu/Saikuro)
  [Code Statistics](https://rubygems.org/gems/code_metrics), [Source](https://github.com/bf4/code_metrics) )
* Rails-only
  * [Rails Best Practices](https://rubygems.org/gems/rails_best_practices), [Source](https://github.com/railsbp/rails_best_practices)
* Test Coverage
  * 1.9: [SimpleCov](http://rubygems.org/gems/simplecov) and [SimpleCov-Rcov-Text](http://rubygems.org/gems/simplecov-rcov-text)
  * 1.8: [Rcov](http://rubygems.org/gems/rcov)
* Hotspots (a meta-metric of the above)


### Original Resources:

* Github: http://github.com/jscruggs/metric_fu
* Issue Tracker: http://github.com/jscruggs/metric_fu/issues
* Historical Homepage: http://metric-fu.rubyforge.org/
* Jake's Blog: http://jakescruggs.blogspot.com/
* Jake's Post about stepping down: http://jakescruggs.blogspot.com/2012/08/why-i-abandoned-metricfu.html