edouard-metric_fu 1.0.3.2 → 1.0.3.3

data/lib/base/base_template.rb

@@ -0,0 +1,134 @@
+module MetricFu
+
+  # The Template class is intended as an abstract class for concrete
+  # template classes to subclass.  It provides a variety of utility
+  # methods to make templating a bit easier.  However, classes do not
+  # have to inherit from here in order to provide a template.  The only
+  # requirement for a template class is that it provides a #write method
+  # to actually write out the template.  See StandardTemplate for an
+  # example.
+  class Template
+    attr_accessor :report
+    
+    private
+    # Creates a new erb evaluated result from the passed in section.
+    #
+    # @param section String
+    #   The section name of 
+    #
+    # @return String
+    #   The erb evaluated string
+    def erbify(section)
+      require 'erb'
+      erb_doc = File.read(template(section))
+      ERB.new(erb_doc).result(binding)
+    end
+
+    # Determines whether a template file exists for a given section
+    # of the full template.
+    #
+    # @param section String
+    #   The section of the template to check against
+    #
+    # @return Boolean
+    #   Does a template file exist for this section or not?
+    def template_exists?(section)
+      File.exist?(template(section))
+    end
+    
+    # Copies an instance variable mimicing the name of the section
+    # we are trying to render, with a value equal to the passed in 
+    # constant.  Allows the concrete template classes to refer to 
+    # that instance variable from their ERB rendering
+    #
+    # @param section String
+    #  The name of the instance variable to create
+    #
+    # @param contents Object
+    #   The value to set as the value of the created instance
+    #   variable
+    def create_instance_var(section, contents)
+      instance_variable_set("@#{section}", contents)        
+    end
+
+    # Generates the filename of the template file to load and 
+    # evaluate.  In this case, the path to the template directory +
+    # the section name + .html.erb
+    #
+    # @param section String
+    #   A section of the template to render
+    #
+    # @return String
+    #   A file path
+    def template(section)
+      File.join(this_directory,  section.to_s + ".html.erb")
+    end
+
+    # Returns the filename that the template will render into for
+    # a given section.  In this case, the section name + '.html'
+    #
+    # @param section String
+    #   A section of the template to render
+    #
+    # @return String
+    #   The output filename
+    def output_filename(section)
+      section.to_s + ".html"
+    end
+
+    # Returns the contents of a given css file in order to 
+    # render it inline into a template.
+    #
+    # @param css String
+    #   The name of a css file to open
+    #
+    # @return String
+    #   The contents of the css file
+    def inline_css(css)
+      open(File.join(this_directory, css)) { |f| f.read }      
+    end
+  
+    # Provides a link to open a file through the textmate protocol
+    # on Darwin, or otherwise, a simple file link.
+    #
+    # @param name String
+    #   
+    # @param line Integer
+    #   The line number to link to, if textmate is available.  Defaults
+    #   to nil
+    #
+    # @return String
+    #   An anchor link to a textmate reference or a file reference
+    def link_to_filename(name, line = nil)
+      filename = File.expand_path(name)
+      if MetricFu.configuration.platform.include?('darwin')
+        "<a href='txmt://open/?url=file://" \
+        +"#{filename}&line=#{line}'>#{name}:#{line}</a>"
+      else 
+       "<a href='file://#{filename}'>#{name}:#{line}</a>"
+      end
+    end
+  
+
+    # Provides a brain dead way to cycle between two values during
+    # an iteration of some sort.  Pass in the first_value, the second_value,
+    # and the cardinality of the iteration.
+    #
+    # @param first_value Object
+    #
+    # @param second_value Object
+    #
+    # @param iteration Integer
+    #   The number of times through the iteration.
+    #
+    # @return Object
+    #   The first_value if iteration is even.  The second_value if
+    #   iteration is odd.
+    def cycle(first_value, second_value, iteration)
+      return first_value if iteration % 2 == 0
+      return second_value
+    end      
+    
+
+  end
+end

data/lib/base/configuration.rb

@@ -0,0 +1,187 @@
+module MetricFu
+
+  # A list of metrics which are available in the MetricFu system.
+  #
+  # These are metrics which have been developed for the system.  Of
+  # course, in order to use these metrics, their respective gems must
+  # be installed on the system.
+  AVAILABLE_METRICS = [:churn, :flog, :flay, :reek, 
+                       :roodi, :saikuro, :rcov]
+
+
+  # The @@configuration class variable holds a global type configuration
+  # object for any parts of the system to use.
+  def self.configuration
+    @@configuration ||= Configuration.new
+  end
+
+  # = Configuration
+  #
+  # The Configuration class, as it sounds, provides methods for
+  # configuring the behaviour of MetricFu.
+  #
+  # == Customization for Rails
+  #
+  # The Configuration class checks for the presence of a
+  # 'config/environment.rb' file.  If the file is present, it assumes
+  # it is running in a Rails project.  If it is, it will:
+  #
+  # * Add 'app' to the @code_dirs directory to include the
+  #   code in the app directory in the processing
+  # * Add :stats to the list of metrics to run to get the Rails stats
+  #   task
+  #
+  # == Customization for CruiseControl.rb
+  #
+  # The Configuration class checks for the presence of a 
+  # 'CC_BUILD_ARTIFACTS' environment variable.  If it's found
+  # it will change the default output directory from the default
+  # "tmp/metric_fu to the directory represented by 'CC_BUILD_ARTIFACTS'
+  #
+  # == Deprications
+  #
+  # The Configuration class checks for several deprecated constants
+  # that were previously used to configure MetricFu.  These include
+  # CHURN_OPTIONS, DIRECTORIES_TO_FLOG, SAIKURO_OPTIONS, 
+  # and MetricFu::SAIKURO_OPTIONS.
+  #
+  # These have been replaced by config.churn, config.flog and
+  # config.saikuro respectively.
+  class Configuration
+
+    def initialize #:nodoc:#
+      warn_about_deprecated_config_options
+      reset
+      add_attr_accessors_to_self
+      add_class_methods_to_metric_fu
+    end
+  
+    # Searches through the instance variables of the class and
+    # creates a class method on the MetricFu module to read the value
+    # of the instance variable from the Configuration class.
+    def add_class_methods_to_metric_fu
+      instance_variables.each do |name|
+        method_name = name[1..-1].to_sym
+        method = <<-EOF
+                  def self.#{method_name}
+                    configuration.send(:#{method_name})
+                  end
+        EOF
+        MetricFu.module_eval(method)
+      end
+    end
+   
+    # Searches through the instance variables of the class and creates
+    # an attribute accessor on this instance of the Configuration 
+    # class for each instance variable.
+    def add_attr_accessors_to_self
+      instance_variables.each do |name|
+        method_name = name[1..-1].to_sym
+        MetricFu::Configuration.send(:attr_accessor, method_name)
+      end
+    end
+
+    # Check if certain constants that are deprecated have been
+    # assigned.  If so, warn the user about them, and the 
+    # fact that they will have no effect.
+    def warn_about_deprecated_config_options
+      if defined?(::MetricFu::CHURN_OPTIONS)
+        raise("Use config.churn instead of MetricFu::CHURN_OPTIONS")
+      end
+      if defined?(::MetricFu::DIRECTORIES_TO_FLOG)
+        raise("Use config.flog[:dirs_to_flog] "+
+              "instead of MetricFu::DIRECTORIES_TO_FLOG") 
+      end
+      if defined?(::MetricFu::SAIKURO_OPTIONS)
+        raise("Use config.saikuro instead of MetricFu::SAIKURO_OPTIONS")
+      end
+      if defined?(SAIKURO_OPTIONS)
+        raise("Use config.saikuro instead of SAIKURO_OPTIONS")
+      end
+    end
+
+    # This allows us to have a nice syntax like:
+    #
+    #   MetricFu.run do |config|
+    #     config.base_directory = 'tmp/metric_fu'
+    #   end
+    #
+    # See the README for more information on configuration options.
+    def self.run
+      yield MetricFu.configuration
+    end
+   
+    # This does the real work of the Configuration class, by setting
+    # up a bunch of instance variables to represent the configuration
+    # of the MetricFu app.
+    def reset
+      @base_directory = ENV['CC_BUILD_ARTIFACTS'] || 'tmp/metric_fu'
+      @scratch_directory = File.join(@base_directory, 'scratch')
+      @output_directory = File.join(@base_directory, 'output')
+      @metric_fu_root_directory = File.join(File.dirname(__FILE__), 
+                                                        '..', '..')
+      @template_directory =  File.join(@metric_fu_root_directory, 
+                                       'lib', 'templates') 
+      @template_class = StandardTemplate
+      set_metrics
+      set_code_dirs
+      @flay     = { :dirs_to_flay => @code_dirs  } 
+      @flog     = { :dirs_to_flog => @code_dirs  }
+      @reek     = { :dirs_to_reek => @code_dirs  }
+      @roodi    = { :dirs_to_roodi => @code_dirs }
+      @saikuro  = { :output_directory => @scratch_directory + '/saikuro', 
+                    :input_directory => @code_dirs,
+                    :cyclo => "",
+                    :filter_cyclo => "0",
+                    :warn_cyclo => "5",
+                    :error_cyclo => "7",
+                    :formater => "text"}
+      @churn    = {}
+      @stats    = {}
+      @rcov     = { :test_files => ['test/**/*_test.rb', 
+                                    'spec/**/*_spec.rb'],
+                    :rcov_opts => ["--sort coverage", 
+                                   "--no-html", 
+                                   "--text-coverage",
+                                   "--no-color",
+                                   "--profile",
+                                   "--rails",
+                                   "--exclude /gems/,/Library/,/usr/,spec"]}
+    end
+
+    # Perform a simple check to try and guess if we're running
+    # against a rails app.
+    #
+    # @todo  This should probably be made a bit more robust.
+    def rails?
+      @rails = File.exist?("config/environment.rb")
+    end
+
+    # Add the :stats task to the AVAILABLE_METRICS constant if we're
+    # running within rails.
+    def set_metrics
+      if rails?
+        @metrics = MetricFu::AVAILABLE_METRICS + [:stats]
+      else
+        @metrics = MetricFu::AVAILABLE_METRICS
+      end 
+    end
+
+    # Add the 'app' directory if we're running within rails.
+    def set_code_dirs
+      if rails?
+        @code_dirs = ['app', 'lib']
+      else
+        @code_dirs = ['lib']
+      end
+    end
+    
+    def platform #:nodoc:
+      return PLATFORM
+    end
+    
+    def is_cruise_control_rb?
+      !!ENV['CC_BUILD_ARTIFACTS']
+    end
+  end
+end

data/lib/base/generator.rb

@@ -0,0 +1,147 @@
+module MetricFu
+
+  # = Generator
+  #
+  # The Generator class is an abstract class that provides the 
+  # skeleton for producing different types of metrics.
+  #
+  # It drives the production of the metrics through a template 
+  # method - #generate_report(options={}).  This method calls
+  # #emit, #analyze and #to_h in order to produce the metrics.
+  #
+  # To implement a concrete class to generate a metric, therefore,
+  # the class must implement those three methods. 
+  #
+  # * #emit should take care of running the metric tool and 
+  #   gathering its output.  
+  # * #analyze should take care of manipulating the output from
+  #   #emit and making it possible to store it in a programmatic way.
+  # * #to_h should provide a hash representation of the output from
+  #   #analyze ready to be serialized into yaml at some point.
+  #
+  # == Pre-conditions
+  #
+  # Based on the class name of the concrete class implementing a
+  # Generator, the Generator class will create a 'metric_directory'
+  # named after the class under the MetricFu.scratch_directory, where
+  # any output from the #emit method should go.
+  #
+  # It will also create the MetricFu.output_directory if neccessary, and
+  # in general setup the directory structure that the MetricFu system
+  # expects.
+  class Generator
+    attr_reader :report, :template
+
+    def initialize(options={})
+      create_metric_dir_if_missing
+      create_output_dir_if_missing
+    end
+    
+    # Creates a new generator and returns the output of the 
+    # #generate_report method.  This is the typical way to 
+    # generate a new MetricFu report. For more information see
+    # the #generate_report instance method.
+    #
+    # @params options Hash
+    #   A currently unused hash to configure the Generator
+    #
+    # @see generate_report
+    def self.generate_report(options={})
+      generator = self.new(options)
+      generator.generate_report
+    end
+
+    # Provides the unqualified class name of an implemented concrete
+    # class, as a string.  For example:
+    #
+    #   class Flay < Generator; end
+    #   klass = Flay.new
+    #   klass.class_name
+    #   > "flay"
+    #
+    # @return String
+    #   The unqualified class name of this concrete class, returned
+    #   as a string.
+    def self.class_name
+      self.to_s.split('::').last.downcase
+    end
+   
+    # Returns the directory where the Generator will write any output
+    def self.metric_directory
+      File.join(MetricFu.scratch_directory, class_name) 
+    end
+
+    def create_metric_dir_if_missing #:nodoc:
+      unless File.directory?(metric_directory)
+        FileUtils.mkdir_p(metric_directory, :verbose => false) 
+      end
+    end
+    
+    def create_output_dir_if_missing #:nodoc:
+      unless File.directory?(MetricFu.output_directory)
+        FileUtils.mkdir_p(MetricFu.output_directory, :verbose => false) 
+      end
+    end
+
+    # @return String
+    #   The path of the metric directory this class is using.
+    def metric_directory
+      self.class.metric_directory
+    end
+
+   
+    # Defines some hook methods for the concrete classes to hook into.
+    %w[emit analyze].each do |meth|
+      define_method("before_#{meth}".to_sym) {}
+      define_method("after_#{meth}".to_sym) {}
+    end
+    define_method("before_to_h".to_sym) {}
+
+    # Provides a template method to drive the production of a metric
+    # from a concrete implementation of this class.  Each concrete
+    # class must implement the three methods that this template method
+    # calls: #emit, #analyze and #to_h.  For more details, see the
+    # class documentation.
+    #
+    # This template method also calls before_emit, after_emit... etc.
+    # methods to allow extra hooks into the processing methods, and help
+    # to keep the logic of your Generators clean.
+    def generate_report
+      %w[emit analyze].each do |meth|
+        send("before_#{meth}".to_sym)
+        send("#{meth}".to_sym)
+        send("after_#{meth}".to_sym)
+      end
+      before_to_h()
+      to_h()
+    end
+
+    def round_to_tenths(decimal)
+      (decimal * 10).round / 10.0 
+    end
+
+    def emit #:nodoc:
+      raise <<-EOF
+        This method must be implemented by a concrete class descending
+        from Generator.  See generator class documentation for more 
+        information.
+      EOF
+    end
+
+    def analyze #:nodoc:
+      raise <<-EOF
+        This method must be implemented by a concrete class descending
+        from Generator.  See generator class documentation for more 
+        information.
+      EOF
+    end
+
+    def to_h #:nodoc:
+      raise <<-EOF
+        This method must be implemented by a concrete class descending
+        from Generator.  See generator class documentation for more 
+        information.
+      EOF
+    end
+  end
+end

data/lib/base/md5_tracker.rb

@@ -0,0 +1,52 @@
+require 'digest/md5'
+require 'fileutils'
+
+module MetricFu
+  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/base/report.rb

@@ -0,0 +1,100 @@
+module MetricFu
+
+  # MetricFu.report memoizes access to a Report object, that will be
+  # used throughout the lifecycle of the MetricFu app.
+  def self.report
+    @report ||= Report.new
+  end
+
+  # = Report
+  #
+  # The Report class is responsible two things:
+  #
+  # It adds information to the yaml report, produced by the system 
+  # as a whole, for each of the generators used in this test run.
+  #
+  # It also handles passing the information from each generator used
+  # in this test run out to the template class set in 
+  # MetricFu::Configuration.
+  class Report
+    
+    # Renders the result of the report_hash into a yaml serialization
+    # ready for writing out to a file.
+    #
+    # @return YAML
+    #   A YAML object containing the results of the report generation 
+    #   process
+    def to_yaml
+      report_hash.to_yaml
+    end
+
+    
+    def report_hash #:nodoc:
+      @report_hash ||= {}
+    end
+
+    # Instantiates a new template class based on the configuration set
+    # in MetricFu::Configuration, or through the MetricFu.config block
+    # in your rake file (defaults to the included StandardTemplate) and
+    # assigns the report_hash to the report_hash to the template and
+    # asks itself to write itself out.
+    def save_templatized_report
+      @template = MetricFu.template_class.new
+      @template.report = report_hash
+      @template.write
+    end
+   
+    # Adds a hash from a passed report, produced by one of the Generator
+    # classes to the aggregate report_hash managed by this hash.
+    #
+    # @param report_type Hash
+    #   The hash to add to the aggregate report_hash
+    def add(report_type)
+      clazz = MetricFu.const_get(report_type.to_s.capitalize)
+      report_hash.merge!(clazz.generate_report)
+    end
+
+    # Saves the passed in content to the passed in directory.  If
+    # a filename is passed in it will be used as the name of the 
+    # file, otherwise it will default to 'index.html'
+    #
+    # @param content String
+    #   A string containing the content (usually html) to be written
+    #   to the file.
+    #
+    # @param dir String
+    #   A dir containing the path to the directory to write the file in.
+    #
+    # @param file String
+    #   A filename to save the path as.  Defaults to 'index.html'.
+    #
+    def save_output(content, dir, file='index.html')
+      open("#{dir}/#{file}", "w") do |f|
+        f.puts content
+      end
+    end
+
+    # Checks to discover whether we should try and open the results
+    # of the report in the browser on this system.  We only try and open
+    # in the browser if we're on OS X and we're not running in a 
+    # CruiseControl.rb environment.  See MetricFu.configuration for more
+    # details about how we make those guesses.
+    #
+    # @return Boolean
+    #   Should we open in the browser or not?
+    def open_in_browser?
+      MetricFu.configuration.platform.include?('darwin') &&
+      ! MetricFu.configuration.is_cruise_control_rb?
+    end
+
+    # Shows 'index.html' from the passed directory in the browser
+    # if we're able to open the browser on this platform.
+    #
+    # @param dir String
+    #   The directory path where the 'index.html' we want to open is  
+    #   stored
+    def show_in_browser(dir)
+      system("open #{dir}/index.html") if open_in_browser?
+    end
+  end
+end

data/lib/generators/churn.rb

@@ -0,0 +1,86 @@
+require 'chronic'
+require 'generator'
+module MetricFu
+  
+  class Churn < Generator
+
+    def initialize(options={})
+      super
+      if File.exist?(".git")
+        @source_control = Git.new(MetricFu.churn[:start_date])
+      elsif File.exist?(".svn")
+        @source_control = Svn.new(MetricFu.churn[:start_date])
+      else
+        raise "Churning requires a subversion or git repo"
+      end
+      @minimum_churn_count = MetricFu.churn[:minimum_churn_count] || 5
+    end
+
+    def emit
+      @changes = parse_log_for_changes.reject {|file, change_count| change_count < @minimum_churn_count}
+    end
+
+    def analyze
+      @changes = @changes.to_a.sort {|x,y| y[1] <=> x[1]}
+      @changes = @changes.map {|change| {:file_path => change[0], :times_changed => change[1] }}
+    end
+
+    def to_h
+      {:churn => {:changes => @changes}}
+    end
+
+    private
+
+    def parse_log_for_changes
+      changes = {}
+
+      logs = @source_control.get_logs
+      logs.each do |line|
+        changes[line] ? changes[line] += 1 : changes[line] = 1
+      end
+      changes
+    end
+
+
+    class SourceControl
+      def initialize(start_date=nil)
+        @start_date = start_date
+      end
+    end
+
+    class Git < SourceControl
+      def get_logs
+        `git log #{date_range} --name-only --pretty=format:`.split(/\n/).reject{|line| line == ""}
+      end
+
+      private
+      def date_range
+        if @start_date
+          date = Chronic.parse(@start_date)
+          "--after=#{date.strftime('%Y-%m-%d')}"
+        end
+      end
+
+    end
+
+    class Svn < SourceControl
+      def get_logs
+        `svn log #{date_range} --verbose`.split(/\n/).map { |line| clean_up_svn_line(line) }.compact
+      end
+
+      private
+      def date_range
+        if @start_date
+          date = Chronic.parse(@start_date)
+          "--revision {#{date.strftime('%Y-%m-%d')}}:{#{Time.now.strftime('%Y-%m-%d')}}"
+        end
+      end
+
+      def clean_up_svn_line(line)
+        m = line.match(/\W*[A,M]\W+(\/.*)\b/)
+        m ? m[1] : nil
+      end
+    end
+
+  end
+end