nielsm-metric_fu 0.9.0

data/HISTORY

@@ -0,0 +1,98 @@
+=== MetricFu 0.9.0 / 2009-1-25
+
+* Adding line numbers to the views so that people viewing it on cc.rb can figure out where the problems are
+* Merging in changes from Jay Zeschin having to do with the railroad task -- I still have no idea how to use it (lemme know if you figure it out)
+* Added totals to Flog results
+* Moved rcov options to configuration
+
+=== MetricFu 0.8.9 / 2009-1-20
+
+* Thanks to Andre Arko and Petrik de Heus for adding the following features:
+* The source control type is auto-detected for Churn
+* Moved all presentation to templates
+* Wrote specs for all classes
+* Added flay, Reek and Roodi metrics
+* There's now a configuration class (see README for details)
+* Unification of metrics reports
+* Metrics can be generated using one command
+* Adding new metrics reports has been standardized
+
+=== MetricFu 0.8.0 / 2008-10-06
+
+* Source Control Churn now supports git (thanks to Erik St Martin)
+* Flog Results are sorted by Highest Flog Score
+* Fix for a bunch of 'already initialized constant' warnings that metric_fu caused
+* Fixing bug so the flog reporter can handle methods with digits in the name (thanks to Andy Gregorowicz)
+* Internal Rake task now allows metric_fu to flog/churn itself
+
+=== MetricFu 0.7.6 / 2008-09-15
+
+* CHURN_OPTIONS has become MetricFu::CHURN_OPTIONS
+* SAIKURO_OPTIONS has become MetricFu::SAIKURO_OPTIONS
+* Rcov now looks at test and specs
+* Exclude gems and Library ruby code from rcov
+* Fixed bug with churn start_date functionality (bad path)
+
+=== MetricFu 0.7.5 / 2008-09-12
+
+* Flog can now flog any set of directories you like (see README).
+* Saikuro can now look at any set of directories you like (see README).
+
+=== MetricFu 0.7.1 / 2008-09-12
+
+* Fixed filename bugs pointed out by Bastien
+
+=== MetricFu 0.7.0 / 2008-09-11
+
+* Merged in Sean Soper's changes to metric_fu.  
+* Metric_fu is now a gem.
+* Flogging now uses a MD5 hash to figure out if it should re-flog a file (if it's changed)
+* Flogging also has a cool new output screen(s)
+* Thanks Sean!
+
+    === Metricks 0.4.2 / 2008-07-01
+
+    * Changed rcov output directory so that it is no longer 'coverage/unit' but just 'coverage' for better integration with CC.rb
+
+    === Metricks 0.4.1 / 2008-06-13
+
+    * Rcov tests now extend beyond one level depth directory by using RcovTask instead of the shell
+
+    === Metricks 0.4.0 / 2008-06-13
+
+    * Implementing functionality for use as a gem
+    * Added Rakefile to facilitate testing
+
+    === Metricks 0.3.0 / 2008-06-11
+
+    * Generated reports now open on darwin automatically
+    * Generated reports reside under tmp/metricks unless otherwise specified by ENV['CC_BUILD_ARTIFACTS']
+    * MD5Tracker works with Flog reports for speed optimization
+
+    === Metricks 0.2.0 / 2008-06-11
+
+    * Integrated use of base directory constant
+    * Have all reports automatically open in a browser if platform is darwin
+    * Namespaced under Metricks
+    * Dropped use of shell md5 command in favor of Ruby's Digest::MD5 libraries
+
+    === Metricks 0.1.0 / 2008-06-10
+
+    * Initial integration of metric_fu and my enhancements to flog
+    * Metrics are generated but are all over the place  
+
+=== MetricFu 0.6.0 / 2008-05-11
+
+* Add source control churn report
+
+=== MetricFu 0.5.1 / 2008-04-25
+
+* Fixed bug with Saikuro report generation
+
+=== MetricFu 0.5.0 / 2008-04-25
+
+* create MetricFu as a Rails Plugin
+* Add Flog Report
+* Add Coverage Report
+* Add Saikuro Report
+* Add Stats Report

data/MIT-LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2008,2009 Jake Scruggs
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,25 @@
+History.txt
+Manifest.txt
+metric_fu-0.7.gem
+metric_fu.gemspec
+MIT-LICENSE
+Rakefile
+README
+TODO.txt
+lib/metric_fu.rb
+lib/metric_fu/base.rb
+lib/metric_fu/churn.rb
+lib/metric_fu/flay_reporter.rb
+lib/metric_fu/flog_reporter.rb
+lib/metric_fu/md5_tracker.rb
+lib/metric_fu/saikuro/saikuro.rb
+lib/metric_fu/saikuro/SAIKURO_README
+lib/tasks/churn.rake
+lib/tasks/coverage.rake
+lib/tasks/flog.rake
+lib/tasks/metric_fu.rake
+lib/tasks/metric_fu.rb
+lib/tasks/saikuro.rake
+lib/tasks/stats.rake
+test/test_helper.rb
+test/test_md5_tracker.rb

data/README

@@ -0,0 +1,154 @@
+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.

data/Rakefile

@@ -0,0 +1,11 @@
+require 'rake'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+require File.join(File.dirname(__FILE__), 'lib', 'metric_fu')
+
+desc "Run all specs in spec directory"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+task :default => [:"metrics:all"]

data/TODO

@@ -0,0 +1,13 @@
+== TODO list
+
+* Color code flog results with scale from: http://jakescruggs.blogspot.com/2008/08/whats-good-flog-score.html
+* Extract functionality from rake files and put under test
+* Integrate Flog, Saikuro, and Coverage into one report so you can see methods that have high complexity and low coverage (this is a big one)
+* Integrate MD5 hashing with remainder of reports
+* Move HTML out of code and into templates/
+* Replace #generate_report with #new on each metric class
+* Make each class descend from MetricFu::CodeMetric
+* Generate metrics:* rake tasks for each of CodeMetric's descendants
+* Update flog specs so that they actually run flog
+* Add flay specs that run flay
+* Convert readme to markdown and rename to README.mkdn so github will render it

data/lib/metric_fu.rb

@@ -0,0 +1,3 @@
+require File.join(File.dirname(__FILE__), 'metric_fu', 'base') #require first because of dependecies
+require File.join(File.dirname(__FILE__), 'tasks', 'metric_fu')
+Dir[File.join(File.dirname(__FILE__), 'metric_fu/*.rb')].each{|l| require l }

data/lib/metric_fu/base.rb

@@ -0,0 +1,160 @@
+require 'erb'
+module MetricFu
+
+  TEMPLATE_DIR = File.join(File.dirname(__FILE__), '..', 'templates')
+  BASE_DIRECTORY = ENV['CC_BUILD_ARTIFACTS'] || 'tmp/metric_fu'
+  RAILS = File.exist?("config/environment.rb")
+
+  if RAILS
+    CODE_DIRS = ['app', 'lib']
+    DEFAULT_METRICS = [:coverage, :churn, :flog, :flay, :reek, :roodi, :stats, :saikuro ]
+  else
+    CODE_DIRS = ['lib']
+    DEFAULT_METRICS = [:coverage, :churn, :flog, :flay, :reek, :roodi, :saikuro ]
+  end 
+
+  module Base
+    
+    ######################################################################
+    # Base class for report Generators
+    #
+    class Generator
+
+      def initialize(options={})
+        @base_dir = self.class.metric_dir
+      end
+
+      def self.metric_dir
+        File.join(BASE_DIRECTORY, template_name)        
+      end
+      
+      def self.template_name
+        self.to_s.split('::').last.downcase
+      end      
+
+      def self.generate_report(options={})
+        FileUtils.mkdir_p(metric_dir, :verbose => false) unless File.directory?(metric_dir)
+        self.new(options).generate_report
+      end
+
+      def save_html(content, file='index.html')
+        open("#{@base_dir}/#{file}", "w") do |f|
+          f.puts content
+        end
+      end
+
+      def generate_report
+        save_html(generate_html)
+      end
+
+      def generate_html
+        analyze
+        html = ERB.new(File.read(template_file)).result(binding)
+      end
+      
+      def template_name
+        self.class.template_name
+      end
+
+      def template_file
+        File.join(MetricFu::TEMPLATE_DIR, "#{template_name}.html.erb")
+      end      
+      
+      ########################
+      # Template methods
+      
+      def inline_css(css)
+	      open(File.join(MetricFu::TEMPLATE_DIR, css)) { |f| f.read }      
+      end
+      
+      def link_to_filename(name, line = nil)
+        filename = File.expand_path(name)
+        if PLATFORM['darwin']
+          %{<a href="txmt://open/?url=file://#{filename}&line=#{line}">#{name}:#{line}</a>}
+        else
+          %{<a href="file://#{filename}">#{name}:#{line}</a>}
+        end
+      end
+      
+      def cycle(first_value, second_value, iteration)
+        return first_value if iteration % 2 == 0
+        return second_value
+      end      
+    end
+  end
+  
+  class << self
+    # The Configuration instance used to configure the Rails environment
+    def configuration
+      @@configuration ||= Configuration.new
+    end
+
+    def churn
+      configuration.churn
+    end
+
+    def coverage
+      configuration.coverage
+    end
+
+    def flay
+      configuration.flay
+    end
+
+    def flog
+      configuration.flog
+    end
+
+    def metrics
+      configuration.metrics
+    end
+
+    def open_in_browser?
+      PLATFORM['darwin'] && !ENV['CC_BUILD_ARTIFACTS']
+    end
+    
+    def saikuro
+      configuration.saikuro
+    end
+
+    def reek
+      configuration.reek
+    end    
+
+    def roodi
+      configuration.roodi
+    end
+
+  end
+  
+  class Configuration
+    attr_accessor :churn, :coverage, :flay, :flog, :metrics, :reek, :roodi, :saikuro
+    def initialize
+      raise "Use config.churn instead of MetricFu::CHURN_OPTIONS" if defined? ::MetricFu::CHURN_OPTIONS
+      raise "Use config.flog[:dirs_to_flog] instead of MetricFu::DIRECTORIES_TO_FLOG" if defined? ::MetricFu::DIRECTORIES_TO_FLOG
+      raise "Use config.saikuro instead of MetricFu::SAIKURO_OPTIONS" if defined? ::MetricFu::SAIKURO_OPTIONS      
+      reset      
+    end
+    
+    def self.run()  
+      yield MetricFu.configuration
+    end
+    
+    def reset
+      @churn    =  {}
+      @coverage = { :test_files => ['test/**/*_test.rb', 'spec/**/*_spec.rb'],
+                    :rcov_opts => ["--sort coverage", "--html", "--rails", "--exclude /gems/,/Library/,spec"] }
+      @flay     = { :dirs_to_flay => CODE_DIRS}
+      @flog     = { :dirs_to_flog => CODE_DIRS}
+      @reek     = { :dirs_to_reek => CODE_DIRS}
+      @roodi    = { :dirs_to_roodi => CODE_DIRS}
+      @metrics          = DEFAULT_METRICS
+      @saikuro  = {}
+    end
+    
+    def saikuro=(options)
+      raise "saikuro need to be a Hash" unless options.is_a?(Hash)
+      @saikuro = options
+    end
+  end
+end