dkubb-yardstick 0.0.1 → 0.1.0

data/.document

@@ -1,4 +1,4 @@
-README.rdoc
+README.markdown
 lib/**/*.rb
 bin/*
 features/**/*.feature

data/.gitignore

@@ -2,6 +2,7 @@
 .DS_Store
 .yardoc
 coverage
+profiling
 rdoc
 doc
 pkg

data/README.markdown

@@ -0,0 +1,69 @@
+Yardstick 0.0.1
+===============
+
+Synopsis
+--------
+
+Yardstick is a tool that verifies YARD coverage of ruby code.
+
+It will measure the source and provide feedback on what is missing from
+the documentation and what can be improved.
+
+Installation
+------------
+
+From Gem:
+
+    $ sudo gem install dkubb-yardstick --source http://gems.github.com/
+
+With a local working copy:
+
+    $ git clone git://github.com/dkubb/yardstick.git
+    $ cd yardstick
+    $ rake build && sudo rake install
+
+Usage
+-----
+
+Yardstick may be used two ways:
+
+**1. yardstick Command-line Tool**
+
+This is the simplest way to run yardstick.  Provide it a list of files
+and it will measure all of them and output suggestions for improvement,
+eg:
+
+    $ yardstick lib/**/*.rb
+
+**2. Yardstick Libraries**
+
+Yardstick comes with several libraries that will allow you to process
+lists of files, or String code fragments, eg:
+
+    # measure a list of file paths
+    measurements = Yardstick.measure(paths)
+
+    # measure a code fragment
+    measurements = Yardstick.measure_string <<-RUBY
+      # Displays the message provided to stdout
+      #
+      # @param [#to_str] message
+      #   the message to display
+      #
+      # @return [undefined]
+      #
+      # @api public
+      def display(message)
+        puts message.to_str
+      end
+    RUBY
+
+TODO
+----
+
+- Add more measurements, especially for @param, @yield and type
+  validation
+- Create a Rake task to allow integration of Yardstick into build
+  processes more easily
+
+Copyright (c) 2009 Dan Kubb. See LICENSE for details.

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.1.0

data/lib/yardstick.rb

@@ -2,7 +2,7 @@ require 'pathname'
 require 'yard'
 
 module Yardstick
-  VERSION = '0.0.1'.freeze
+  VERSION = '0.1.0'.freeze
   ROOT    = Pathname(__FILE__).dirname.parent.expand_path.freeze
 
   # Measure a list of files
@@ -10,17 +10,17 @@ module Yardstick
   # @example
   #   Yardstick.measure('article.rb')  # => [ Measurement ]
   #
-  # @param [Array<#to_str>, #to_str] files
+  # @param [Array<#to_s>, #to_s] path
   #   optional list of paths to measure
   # @param [Hash] options
   #   optional configuration
   #
-  # @return [Array<Measurement>]
+  # @return [MeasurementSet]
   #   the measurements for each file
   #
   # @api public
-  def self.measure(files = 'lib/**/*.rb', options = {})
-    Yardstick::Processor.process_files(files)
+  def self.measure(path = 'lib/**/*.rb', options = {})
+    Yardstick::Processor.process_path(path)
   end
 
   # Measure a string of code and YARD documentation
@@ -35,7 +35,7 @@ module Yardstick
   # @param [Hash] options
   #   optional configuration
   #
-  # @return [Array<Measurement>]
+  # @return [MeasurementSet]
   #   the measurements for the string
   #
   # @api public
@@ -45,7 +45,7 @@ module Yardstick
 
 end # module Yardstick
 
-$LOAD_PATH << Yardstick::ROOT + 'lib'
+$LOAD_PATH.unshift(Yardstick::ROOT + 'lib')
 
 require 'yardstick/core_ext/object'
 require 'yardstick/yard_ext'

data/lib/yardstick/autoload.rb

@@ -1,7 +1,11 @@
 module Yardstick
-  autoload :CLI,         'yardstick/cli'
-  autoload :Measurable,  'yardstick/measurable'
-  autoload :Measurement, 'yardstick/measurement'
-  autoload :Method,      'yardstick/method'
-  autoload :Processor,   'yardstick/processor'
+  autoload :CLI,            'yardstick/cli'
+  autoload :Measurable,     'yardstick/measurable'
+  autoload :Measurement,    'yardstick/measurement'
+  autoload :MeasurementSet, 'yardstick/measurement_set'
+  autoload :Method,         'yardstick/method'
+  autoload :OrderedSet,     'yardstick/ordered_set'
+  autoload :Processor,      'yardstick/processor'
+  autoload :Rule,           'yardstick/rule'
+  autoload :RuleSet,        'yardstick/rule_set'
 end # module Yardstick

data/lib/yardstick/cli.rb

@@ -11,14 +11,14 @@ module Yardstick
     # @param [Array] *args
     #   arguments passed in from the command line
     #
-    # @return [Array(Measurement)]
+    # @return [MeasurementSet]
     #   the measurement for each file
     #
-    # @api private
+    # @api public
     def self.run(*args)
-      Yardstick.measure(*parse_options(args)).each do |measurement|
-        measurement.warn
-      end
+      measurements = Yardstick.measure(*parse_options(args))
+      measurements.warn
+      measurements
     end
 
     # Parse the options provided from the command-line
@@ -36,7 +36,7 @@ module Yardstick
       option_parser(options).parse!(args)
       [ args, options ]
     rescue OptionParser::InvalidOption => error
-      display_exit(error.message << "\n" << args.inspect)
+      display_exit(error.message)
     end
 
     # Return an OptionParser instance for the command-line app
@@ -51,7 +51,7 @@ module Yardstick
     def self.option_parser(options)
       opts = OptionParser.new
       opts.on_tail('-v', '--version', 'print version information and exit') { display_exit("#{opts.program_name} #{Yardstick::VERSION}") }
-      opts.on_tail('-h', '--help',    'display this help and exit')         { display_exit(opts) }
+      opts.on_tail('-h', '--help',    'display this help and exit')         { display_exit(opts.to_s) }
       opts
     end
 
@@ -69,9 +69,7 @@ module Yardstick
     end
 
     class << self
-      private :option_parser
-      private :parse_options
-      private :display_exit
+      private :option_parser, :parse_options, :display_exit
     end
 
   end # module CLI

data/lib/yardstick/measurable.rb

@@ -4,23 +4,23 @@ module Yardstick
 
     module ClassMethods
 
-      # List of measurement types for this class
+      # List of rules for this class
       #
-      # @return [Array<Array(String, Symbol)>]
-      #   the measurements for this class
+      # @return [RuleSet<Rule>]
+      #   the rules for this class
       #
       # @api private
-      def measurements
-        @measurements ||= []
+      def rules
+        @rules ||= RuleSet.new
       end
 
-      # Set the description for the measurement
+      # Set the description for the rule
       #
       # @param [#to_str] description
-      #   the measurement description
+      #   the rule description
       #
       # @yield []
-      #   the measurement to perform
+      #   the rule to perform
       #
       # @yieldreturn [Boolean]
       #   return true if successful, false if not
@@ -28,8 +28,8 @@ module Yardstick
       # @return [undefined]
       #
       # @api private
-      def measurement(description, &block)
-        measurements << [ description, block ]
+      def rule(description, &block)
+        rules << Rule.new(description, &block)
       end
 
     private
@@ -43,8 +43,7 @@ module Yardstick
       #
       # @api private
       def included(mod)
-        mod.extend(ClassMethods)
-        copy_measurements(mod)
+        mod.extend(ClassMethods).rules.merge(rules)
       end
 
       # Extend the docstring meta class with measurable class methods
@@ -56,21 +55,7 @@ module Yardstick
       #
       # @api private
       def extended(docstring)
-        meta_class = docstring.meta_class
-        meta_class.extend(ClassMethods)
-        copy_measurements(meta_class)
-      end
-
-      # Copy measurements from the ancestor to the descendant
-      #
-      # @param [Module] descendant
-      #   the descendant module or class
-      #
-      # @return [undefined]
-      #
-      # @api private
-      def copy_measurements(descendant)
-        descendant.measurements.concat(measurements).uniq!
+        included(docstring.meta_class)
       end
     end # module ClassMethods
 
@@ -81,14 +66,12 @@ module Yardstick
     # @example
     #   docstring.measure  # => [ Measurement ]
     #
-    # @return [Array<Measurement>]
+    # @return [MeasurementSet]
     #   a collection of measurements
     #
     # @api public
     def measure
-      meta_class.measurements.map do |(description, block)|
-        Measurement.new(description, self, &block)
-      end
+      meta_class.rules.measure(self)
     end
 
   end # module Measurable

data/lib/yardstick/measurement.rb

@@ -1,6 +1,17 @@
 module Yardstick
   class Measurement
 
+    # Return the Measurement description
+    #
+    # @example
+    #   measurement.description  # => "The description"
+    #
+    # @return [String]
+    #   the description
+    #
+    # @api public
+    attr_reader :description
+
     # Return a Measurement instance
     #
     # @example
@@ -87,6 +98,33 @@ module Yardstick
       end
     end
 
+    # Test if Measurement is equal to another measurement
+    #
+    # @example
+    #   measurement == equal_measurement  # => true
+    #
+    # @param [Measurement] other
+    #   the other Measurement
+    #
+    # @return [Boolean]
+    #   true if the Measurement is equal to the other, false if not
+    #
+    # @api semipublic
+    def eql?(other)
+      @description.eql?(other.instance_variable_get(:@description)) &&
+      @docstring.eql?(other.instance_variable_get(:@docstring))
+    end
+
+    # Return hash identifier for the Measurement
+    #
+    # @return [Integer]
+    #   the hash identifier
+    #
+    # @api private
+    def hash
+      [ @description, @docstring ].hash
+    end
+
   private
 
     # Measure the docstring using the method provided to the constructor

data/lib/yardstick/measurement_set.rb

@@ -0,0 +1,123 @@
+require 'rational'
+
+module Yardstick
+  class MeasurementSet < OrderedSet
+
+    # The total number of measurements
+    #
+    # @example
+    #   measurements.total  # => 570
+    #
+    # @return [Integer]
+    #   total measurements
+    #
+    # @api public
+    def total
+      length
+    end
+
+    # The number of successful measurements
+    #
+    # @example
+    #   measurements.successful  # => 561
+    #
+    # @return [Integer]
+    #   successful measurements
+    #
+    # @api public
+    def successful
+      select { |measurement| measurement.ok? }.length
+    end
+
+    # The number of failed measurements
+    #
+    # @example
+    #   measurements.failed  # => 9
+    #
+    # @return [Integer]
+    #   failed measurements
+    #
+    # @api public
+    def failed
+      total - successful
+    end
+
+    # The percentage of successful measurements
+    #
+    # @example
+    #   measurements.coverage  # => Rational(561, 570).to_f  # => 98.4%
+    #
+    # @return [Integer, Rational]
+    #   the coverage percentage
+    #
+    # @api public
+    def coverage
+      empty? ? 0 : Rational(successful, total)
+    end
+
+    # Warn the unsuccessful measurements and a summary
+    #
+    # @example
+    #   measurements.warn  # (outputs measurements results and summary)
+    #
+    # @return [undefined]
+    #
+    # @api public
+    def warn
+      each { |measurement| measurement.warn }
+      warn_summary
+    end
+
+  private
+
+    # Warn the summary of all measurements
+    #
+    # @return [undefined]
+    #
+    # @api private
+    def warn_summary
+      Kernel.warn("\n#{[ coverage_text, successful_text, failed_text, total_text ].join('  ')}")
+    end
+
+    # The text for the coverage percentage to include in the summary
+    #
+    # @return [String]
+    #   the coverage text
+    #
+    # @api private
+    def coverage_text
+      'Coverage: %.1f%%' % (coverage * 100)
+    end
+
+    # The text for the successful measurements to include in the summary
+    #
+    # @return [String]
+    #   the successful text
+    #
+    # @api private
+    def successful_text
+      'Success: %d' % successful
+    end
+
+    # The text for the failed measurements to include in the summary
+    #
+    # @return [String]
+    #   the failed text
+    #
+    # @api private
+    def failed_text
+      'Failed: %d' % failed
+    end
+
+    # The text for the total measurements to include in the summary
+    #
+    # @return [String]
+    #   the total text
+    #
+    # @api private
+    def total_text
+      'Total: %d' % total
+    end
+
+  end # class MeasurementSet
+end # module Yardstick