revolutionhealth-metricks 0.4

data/History.txt

@@ -0,0 +1,22 @@
+=== 0.4.0 / 2008-06-13
+
+* Implementing functionality for use as a gem
+* Added Rakefile to facilitate testing
+
+=== 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
+
+=== 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
+
+=== 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  

data/MIT-LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2008 Sean Soper
+
+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,28 @@
+History.txt
+Manifest.txt
+metricks-0.4.gem
+metricks.gemspec
+MIT-LICENSE
+Rakefile
+README
+TODO.txt
+lib/metricks.rb
+lib/metricks/flog_reporter.rb
+lib/metricks/md5_tracker.rb
+lib/metricks/flog_reporter/base.rb
+lib/metricks/flog_reporter/flog_reporter.css
+lib/metricks/flog_reporter/generator.rb
+lib/metricks/flog_reporter/operator.rb
+lib/metricks/flog_reporter/page.rb
+lib/metricks/flog_reporter/scanned_method.rb
+lib/metricks/saikuro/saikuro.rb
+lib/metricks/saikuro/SAIKURO_README
+lib/tasks/churn.rake
+lib/tasks/coverage.rake
+lib/tasks/flog.rake
+lib/tasks/metricks.rake
+lib/tasks/metricks.rb
+lib/tasks/saikuro.rake
+lib/tasks/stats.rake
+test/test_helper.rb
+test/test_md5_tracker.rb

data/README

@@ -0,0 +1,98 @@
+Version 0.4.0
+http://github.com/revolutionhealth/metricks
+
+Metricks is a fork of the metric_fu project and 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 revolutionhealth-metricks -s http://gems.github.com
+
+Then in your Rakefile:
+require 'metricks'
+
+*Important note:
+You must have Rcov and Flog installed to get coverage and flog reports.  You can do this through ruby gems at the command line like so:
+sudo gem install rcov
+sudo gem install flog
+
+
+*Usage
+
+Out of the box metricks provides these tasks:
+rake metricks:all              
+rake metricks:all_with_migrate
+rake metricks:coverage
+rake metricks:saikuro
+rake metricks:flog
+rake metricks:stats
+rake metricks:churn
+
+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 = 'metricks:all_with_migrate'
+project.scheduler.polling_interval = 24.hours
+
+Which will check for updates every 24 hours and run all the metricks rake tasks (migrating your test db first).  The output will be visible from an individual build's detail page.
+
+
+*Notes on metricks:coverage
+
+When creating a coverage report, metricks runs all the tests in the test folder using Rcov.  If you use RSpec you can change the default by putting this in your Rakefile:
+
+namespace :metricks do
+  TEST_PATHS_FOR_RCOV = ['spec/**/*_spec.rb']
+end
+
+The namespace is only there for intentional purposes and isn't necessary.  If you have multiple paths to test, then you can do this:
+
+  TEST_PATHS_FOR_RCOV = ['spec/**/*_spec.rb', 'test/**/*_test.rb']
+
+The coverage task will iterate over all the paths and aggregate the results into one report. You'll see a coverage.data file in the root of your project.
+
+If you want to change the options that Rcov is run with, then set this constant in your Rakefile:
+
+  RCOV_OPTIONS =  { "--sort" => "loc" }
+
+It's a hash that gets merged with the default options.  This particular change will sort the coverage report by lines of code (loc).  Check out the Rcov documentation for more options.  If you want to see the default options metricks runs, open up the metricks.rake file in the plugin.
+
+
+*Notes on metricks:cyclomatic_complexity
+
+Saikuro is bundled with metricks 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 Rakefile:
+
+namespace :metricks do                   
+  SAIKURO_OPTIONS = { "--warn_cyclo" => "3", "--error_cyclo" => "4" }
+end
+
+Like RCOV_OPTIONS, SAIKURO_OPTIONS 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.
+
+
+*Notes on metricks:flog
+
+Flog is another way of measuring complexity (or tortured code as the Flog authors like to put it).  Metricksmetricks takes the output of Flog run on the 'app' folder, puts it in between some <pre> tags, calculates the average Flog score per method, and jams all that into an index.html file.  You should check out the awesome, and a little scary, Flog website for more info.
+
+
+*Notes on metricks:stats
+
+This is just 'rake stats' 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 metricks: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:
+metricks
+namespace :metricks do 
+  CHURN_OPTIONS = { :start_date => lambda{3.months.ago} }
+end
+
+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:
+
+namespace :metricks do
+  CHURN_OPTIONS = { :minimum_churn_count => 3 }
+end
+
+
+*Thanks
+
+I'd like to thank the authors of Saikuro, Flog, Rcov, CruiseControl.rb, and Rails for creating such excellent open source products.  Also Michael Schubert, Kurtis Seebaldt, Toby Tripp, Paul Gross, and Chirdeep Shetty for their help and advice.

data/TODO.txt

@@ -0,0 +1,4 @@
+== TODO list
+
+* Integrate MD5 hashing with remainder of reports
+* Update README to more accurately reflect current development

data/lib/metricks/flog_reporter/base.rb

@@ -0,0 +1,59 @@
+module Metricks::FlogReporter
+  
+  THRESHOLD = (ENV['FLOG_THRESHOLD'] || 120)
+  SCORE_FORMAT = "%0.2f"
+  
+  class InvalidFlog < RuntimeError
+  end
+  
+  class Base
+    MODULE_NAME = "([A-Z][a-z]+)+"
+    METHOD_NAME = "#([a-z]+_?)+"
+    SCORE = "\\d+\\.\\d+"
+
+    METHOD_NAME_RE = Regexp.new("#{MODULE_NAME}#{METHOD_NAME}")
+    SCORE_RE = Regexp.new(SCORE)
+  
+    METHOD_LINE_RE = Regexp.new("#{MODULE_NAME}#{METHOD_NAME}:\\s\\(#{SCORE}\\)")
+    OPERATOR_LINE_RE = Regexp.new("\\s+(#{SCORE}):\\s(.*)$")
+
+    class << self
+      def cycle(first_value, second_value, iteration)
+        return first_value if iteration % 2 == 0
+        return second_value
+      end
+
+      def load_css(css_file = nil)
+        filepath = css_file || File.join(File.dirname(__FILE__), 'flog_reporter.css')
+        css = ""
+        file = File.open(filepath, "r")
+        file.each_line { |line| css << line }
+        file.close
+        css
+      end
+
+      def parse(text)
+        score = text[/score = (\d+\.\d+)/, 1]
+        return nil unless score
+        page = Page.new(score)
+
+        text.each_line do |method_line|
+          if METHOD_LINE_RE =~ method_line and
+             method_name = method_line[METHOD_NAME_RE] and
+             score = method_line[SCORE_RE]
+             page.scanned_methods << ScannedMethod.new(method_name, score)
+          end
+
+          if OPERATOR_LINE_RE =~ method_line and
+             operator = method_line[OPERATOR_LINE_RE, 2] and
+             score = method_line[SCORE_RE]
+             raise InvalidFlog if page.scanned_methods.empty?
+             page.scanned_methods.last.operators << Operator.new(score, operator)
+          end
+        end
+      
+        page
+      end
+    end
+  end
+end

data/lib/metricks/flog_reporter/flog_reporter.css

@@ -0,0 +1,39 @@
+body { 
+	background-color: rgb(240, 240, 245);
+	font-family: verdana, arial, helvetica;
+}
+
+table {
+	border-collapse: collapse;
+}
+
+table.report {
+	width: 100%;
+}
+
+table th {
+	text-align: center;
+}
+
+table td.score {
+	text-align: right;
+}
+
+table th {
+	background: #dcecff;
+	border: #d0d0d0 1px solid;
+	font-weight: bold;
+}
+
+table td {
+	border: #d0d0d0 1px solid;
+}
+
+table tr.light {
+ background-color: rgb(240, 240, 245);
+}
+
+table tr.dark {
+ background-color: rgb(230, 230, 235);
+}
+

data/lib/metricks/flog_reporter/generator.rb

@@ -0,0 +1,71 @@
+module Metricks::FlogReporter
+  class Generator
+    class << self
+      def generate_report(base_dir)
+        flog_hashes = []
+        Dir.glob("#{base_dir}/**/*.txt").each do |filename|
+          content = ""
+          File.open(filename, "r").each_line do |file|
+            content << file
+          end
+
+          begin
+            page = Base.parse(content)
+          rescue InvalidFlog
+            puts "Invalid flog for #{filename}"
+            next
+          end
+
+          next unless page
+
+          if Metricks::MD5Tracker.file_already_counted?(filename)            
+            flog_hashes << {
+              :page => page,
+              :path => filename.sub('.txt', '.html').sub("#{base_dir}/", "")
+            }
+          else  
+            flog_hashes << generate_page(filename, page, base_dir)
+          end
+        end
+        
+        generate_index(flog_hashes, base_dir)
+      end
+
+      def generate_page(filename, page, base_dir)
+        html_file = File.new(filename.gsub(/\.txt/, '.html'), "w")
+        html_file.puts page.to_html
+        html_file.close
+        return { :path => html_file.path.sub("#{base_dir}/", ''),
+                 :page => page }
+      end
+
+      def generate_index(flog_hashes, base_dir)
+        html = "<html><head><title>Flog Reporter</title><style>"
+        html << Base.load_css
+        html << "</style></head><body>"
+        html << "<p><strong>Flogged files</strong></p>\n"
+        html << "<p>Generated on #{Time.now.localtime} with <a href='http://ruby.sadi.st/Flog.html'>flog</a></p>\n"
+        html << "<table class='report'>\n"
+        html << "<tr><th>File</th><th>Total score</th><th>Methods</th><th>Average score</th><th>Highest score</th></tr>"
+        count = 0
+        flog_hashes.each do |flog_hash|
+          html << <<-EOF
+                    <tr class='#{Base.cycle("light", "dark", count)}'>
+                      <td><a href='#{flog_hash[:path]}'>#{flog_hash[:path].sub('.html', '.rb')}</a></td>
+                      <td class='score'>#{sprintf(SCORE_FORMAT, flog_hash[:page].score)}</td>
+                      <td class='score'>#{flog_hash[:page].scanned_methods.length}</td>
+                      <td class='score'>#{sprintf(SCORE_FORMAT, flog_hash[:page].average_score)}</td>
+                      <td class='score'>#{sprintf(SCORE_FORMAT, flog_hash[:page].highest_score)}</td>
+                    </tr>
+                  EOF
+          count += 1
+        end
+        html << "</table>\n"
+        html << "</body></html>\n"
+        index = File.new("#{base_dir}/index.html", "w")
+        index.puts html
+        index.close
+      end
+    end
+  end
+end

data/lib/metricks/flog_reporter/operator.rb

@@ -0,0 +1,10 @@
+module Metricks::FlogReporter
+  class Operator
+    attr_accessor :score, :operator
+    
+    def initialize(score, operator)
+      @score = score.to_f
+      @operator = operator
+    end
+  end
+end

data/lib/metricks/flog_reporter/page.rb

@@ -0,0 +1,36 @@
+module Metricks::FlogReporter
+  class Page
+    attr_accessor :score, :scanned_methods
+    
+    def initialize(score, scanned_methods = [])
+      @score = score.to_f
+      @scanned_methods = scanned_methods
+    end
+    
+    def to_html
+      output = "<html><head><style>"
+      output << Base.load_css
+      output << "</style></head><body>"
+      output << "Score: #{score}\n"
+      scanned_methods.each do |sm|
+        output << sm.to_html
+      end
+      output << "</body></html>"
+      output
+    end
+    
+    def average_score
+      sum = 0
+      scanned_methods.each do |m|
+        sum += m.score
+      end
+      sum / scanned_methods.length
+    end
+    
+    def highest_score
+      scanned_methods.inject(0) do |highest, m|
+        m.score > highest ? m.score : highest
+      end
+    end
+  end
+end

data/lib/metricks/flog_reporter/scanned_method.rb

@@ -0,0 +1,28 @@
+module Metricks::FlogReporter
+  class ScannedMethod
+    attr_accessor :name, :score, :operators
+    
+    def initialize(name, score, operators = [])
+      @name = name
+      @score = score.to_f
+      @operators = operators
+    end
+    
+    def to_html
+      output = "<p><strong>#{name} (#{score})</strong></p>\n"
+      output << "<table>\n"
+      output << "<tr><th>Score</th><th>Operator</th></tr>\n"
+      count = 0
+      operators.each do |operator|
+        output << <<-EOF
+                    <tr class='#{Base.cycle("light", "dark", count)}'>
+                      <td class='score'>#{sprintf(SCORE_FORMAT, operator.score)}</td>
+                      <td class='score'>#{operator.operator}</td>
+                    </tr>
+                  EOF
+        count += 1
+      end
+      output << "</table>\n\n"
+    end
+  end
+end

data/lib/metricks/flog_reporter.rb

@@ -0,0 +1,5 @@
+require File.join(File.dirname(__FILE__), 'flog_reporter', 'base')
+require File.join(File.dirname(__FILE__), 'flog_reporter', 'page')
+require File.join(File.dirname(__FILE__), 'flog_reporter', 'scanned_method')
+require File.join(File.dirname(__FILE__), 'flog_reporter', 'operator')
+require File.join(File.dirname(__FILE__), 'flog_reporter', 'generator')

data/lib/metricks/md5_tracker.rb

@@ -0,0 +1,52 @@
+require 'digest/md5'
+require 'fileutils'
+
+module Metricks
+  class MD5Tracker
+
+    @@unchanged_md5s = []
+
+    class << self
+      def md5_dir(path_to_file, base_dir)
+        File.join(base_dir,
+                  path_to_file.split('/')[0..-2].join('/'))        
+      end
+
+      def md5_file(path_to_file, base_dir)
+        File.join(md5_dir(path_to_file, base_dir),    
+                  path_to_file.split('/').last.sub(/\.[a-z]+/, '.md5'))
+      end
+
+      def track(path_to_file, base_dir)
+        md5 = Digest::MD5.hexdigest(File.read(path_to_file))
+        FileUtils.mkdir_p(md5_dir(path_to_file, base_dir), :verbose => false)
+        f = File.new(md5_file(path_to_file, base_dir), "w")
+        f.puts(md5)
+        f.close
+        md5
+      end
+      
+      def file_changed?(path_to_file, base_dir)
+        orig_md5_file = md5_file(path_to_file, base_dir)
+        return track(path_to_file, base_dir) unless File.exist?(orig_md5_file)
+
+        current_md5 = ""
+        file = File.open(orig_md5_file, 'r')
+        file.each_line { |line| current_md5 << line }
+        file.close
+        current_md5.chomp!
+        
+        new_md5 = Digest::MD5.hexdigest(File.read(path_to_file))
+        new_md5.chomp!
+
+        @@unchanged_md5s << path_to_file if new_md5 == current_md5
+
+        return new_md5 != current_md5
+      end
+  
+      def file_already_counted?(path_to_file)
+        return @@unchanged_md5s.include?(path_to_file)
+      end
+    end
+  end
+end

data/lib/metricks/saikuro/SAIKURO_README

@@ -0,0 +1,142 @@
+Version 0.2
+
+Saikuro:
+Saikuro is a Ruby cyclomatic complexity analyzer.  When given Ruby
+source code Saikuro will generate a report listing the cyclomatic
+complexity of each method found.  In addition, Saikuro counts the
+number of lines per method and can generate a listing of the number of
+tokens on each line of code.
+
+License:
+Saikuro uses the BSD license.
+
+Installation:
+Option 1: Using setup.rb
+* login as root
+* run "ruby setup.rb all"
+
+Option 2: The manual way
+Saikuro is a single Ruby file that is executable.  You can run it where
+you unpacked it or you can move it your preferred location such as
+"/usr/local/bin" or "~/bin".
+
+Note:
+Ruby 1.8.5 has a bug in ri_options that will prevent Saikuro from
+running.  If you are using 1.8.5 please apply this patch :
+http://www.ruby-lang.org/cgi-bin/cvsweb.cgi/ruby/lib/rdoc/ri/ri_options.rb.diff?r1=1.2.2.13;r2=1.2.2.14
+
+
+Usage:
+Saikuro is a command line program.
+Running "saikuro -h" will output a usage statement describing all
+the various arguments you can pass to it.
+
+"saikuro -c -p tests/samples.rb"
+
+The above command is a simple example that generates a cyclomatic
+complexity report on the samples.rb file, using the default filter,
+warning and error settings. The report is saved in the current
+directory.
+
+
+A more detailed example is
+"saikuro -c -t -i tests -y 0 -w 11 -e 16 -o out/"
+
+This will analyze all Ruby files found in the "tests/" directory.
+Saikuro will generate a token count report and a cyclomatic complexity
+report in the "out" directory .  The "-y 0" command will turn off
+filtering and thus show the complexity of all methods.  The "-w 11"
+will mark all methods with a complexity of 11 or higher with a
+warning.  Finally, "-e 16" will flag all methods with a complexity of
+16 or higher with an error.
+
+
+About Cyclomatic Complexity:
+
+The following document provides a very good and detailed description
+by the author of cyclomatic complexity.
+
+NIST Special Publication 500-235
+Structured Testing: A Testing Methodology Using the Cyclomatic
+Complexity Metric
+
+By Arthur H. Watson and Thomas J. McCabe
+HTML
+http://hissa.nist.gov/HHRFdata/Artifacts/ITLdoc/235/title.htm
+PDF
+http://www.mccabe.com/iq_research_nist.htm
+
+
+How and what Saikuro counts to calculate the cyclomatic complexity:
+
+Saikuro uses the Simplified Complexity Calculation, which is just
+adding up the number of branch points in a method.
+
+Each method starts with a complexity of 1, because there is at least
+one path through the code.  Then each conditional or looping operator
+(if, unless, while, until, for, elsif, when) adds one point to the
+complexity. Each "when" in a case statement adds one point.  Also each
+"rescue" statement adds one.
+
+Saikuro also regards blocks as an addition to a method's complexity
+because in many cases a block does add a path that may be traversed.
+For example, invoking the "each" method of an array with a block would
+only traverse the give block if the array is not empty.  Thus if you
+want to find the basis set to get 100% coverage of your code then a
+block should add one point to the method's complexity.  It is not yet
+for sure however to what level the accuracy is decreased through this
+measurement, as normal Ruby code uses blocks quite heavily and new
+paths are not necessarily introduced by every block.
+
+In addition, the short-circuiting "and" operators (&& and "and")
+currently do not contribute to a method's complexity, although
+McCabe's paper listed above suggests doing so.
+
+
+#Example for "and" operator handling:
+
+ # Starting values for case 1 and 2
+ x = false
+ y = 15
+ r, q = nil
+
+ # case 1
+ puts "W" if ((r = x) && (q = y))
+ puts r # => false
+ puts q # => nil
+
+ # case 2
+ puts "W" if ((q = y) && (r = x))
+ puts r # => false
+ puts q # => 15
+
+Case 1 illustrates why "and" operators should add to a method's
+complexity, because the result of ( r = x ) is false the if statement
+stops and returns false without evaluating the ( q = y ) branch.  Thus
+if a total coverage of source code is desired, one point should be
+added to the method's complexity.
+
+So why is it not added?
+Mainly, because we have not gotten around to it.  We are wondering if
+this would increase the noise more than it should.
+
+
+Tests:
+In the test directory is a sample file that has examples of the
+various possible cases that we examined and documented the expected
+cyclomatic complexity result.  If you find mistakes or missing tests
+please report them.
+
+Contact:
+Saikuro is written by
+Zev Blut (zb at ubit dot com)
+
+Acknowledgments:
+Thanks to Elbert Corpuz for writing the CSS for the HTML output!
+
+Other metric tools for Ruby:
+Ryan Davis has an abc metric program as an example in his ParseTree
+product:  http://www.zenspider.com/ZSS/Products/ParseTree/
+
+The PMD project has a tool called CPD that can scan Ruby source code
+looking for source duplication:  http://pmd.sourceforge.net/