yardstick 0.1.0

data/lib/yardstick/measurement_set.rb

@@ -0,0 +1,130 @@
+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
+    #   coverage = measurements.coverage  # => Rational(561, 570)
+    #   '%.1f%%' % (coverage * 100)       # => "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.puts  # (outputs measurements results and summary)
+    #
+    # @param [#puts] io
+    #   optional object to puts the summary
+    #
+    # @return [undefined]
+    #
+    # @api public
+    def puts(io = $stdout)
+      each { |measurement| measurement.puts(io) }
+      puts_summary(io)
+    end
+
+  private
+
+    # Warn the summary of all measurements
+    #
+    # @param [#puts] io
+    #   object to puts the summary
+    #
+    # @return [undefined]
+    #
+    # @api private
+    def puts_summary(io)
+      io.puts("\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

data/lib/yardstick/method.rb

@@ -0,0 +1,111 @@
+module Yardstick
+  module Method
+    include Measurable
+
+    rule 'The method summary should be specified' do
+      skip if has_tag?('see')
+      summary_text != ''
+    end
+
+    rule 'The method summary should be less than 80 characters in length' do
+      summary_text.split(//).length <= 80
+    end
+
+    rule 'The method summary should not end in a period' do
+      summary_text[-1, 1] != '.'
+    end
+
+    rule 'The method summary should be a single line' do
+      !summary_text.include?("\n")
+    end
+
+    rule 'The public/semipublic method should have an example specified' do
+      skip if api?(%w[ private ]) || tag_types('return') == %w[ undefined ]
+      has_tag?('example')
+    end
+
+    rule 'The @api tag should be specified' do
+      has_tag?('api')
+    end
+
+    rule 'The @api tag must be either public, semipublic or private' do
+      %w[ public semipublic private ].include?(tag_text('api'))
+    end
+
+    rule 'A method with protected visibility must have an @api tag of semipublic or private' do
+      skip unless visibility == :protected
+      api?(%w[ semipublic private ])
+    end
+
+    rule 'A method with private visibility must have an @api tag of private' do
+      skip unless visibility == :private
+      api?(%w[ private ])
+    end
+
+    rule 'The @return tag should be specified' do
+      has_tag?('return')
+    end
+
+  private
+
+    # The raw text for the summary
+    #
+    # @return [String]
+    #   the summary text
+    #
+    # @api private
+    def summary_text
+      split(/\r?\n\r?\n/).first || ''
+    end
+
+    # The text for a specified tag
+    #
+    # @param [String] tag_name
+    #   the name of the tag
+    #
+    # @return [String, nil]
+    #   the tag text if the tag exists
+    #
+    # @api private
+    def tag_text(tag_name)
+      tag(tag_name).text if has_tag?(tag_name)
+    end
+
+    # The types for a specified tag
+    #
+    # @param [String] tag_name
+    #   the name of the tag
+    #
+    # @return [Array<String>, nil]
+    #   a collection of tag types if the tag exists
+    #
+    # @api private
+    def tag_types(tag_name)
+      tag(tag_name).types if has_tag?(tag_name)
+    end
+
+    # The method visibility: public, protected or private
+    #
+    # @return [Symbol]
+    #   the visibility of the method
+    #
+    # @api private
+    def visibility
+      object.visibility
+    end
+
+    # Check if the method API type matches
+    #
+    # @param [Array<String>] types
+    #   a collection of API types
+    #
+    # @return [Boolean]
+    #   true if the API type matches
+    #
+    # @api private
+    def api?(types)
+      types.include?(tag_text('api'))
+    end
+
+  end # module Method
+end # module Yardstick

data/lib/yardstick/ordered_set.rb

@@ -0,0 +1,115 @@
+module Yardstick
+  class OrderedSet
+    include Enumerable
+
+    # Returns the OrderedSet instance
+    #
+    # @param [Array] entries
+    #   optional entries
+    #
+    # @return [OrderedSet]
+    #   the ordered set instance
+    #
+    # @api private
+    def initialize(entries = nil)
+      @entries = []
+      @index   = {}
+      merge(entries) if entries
+    end
+
+    # Append to the OrderedSet
+    #
+    # @param [Object] entry
+    #   the object to append
+    #
+    # @return [OrderedSet]
+    #   returns self
+    #
+    # @api private
+    def <<(entry)
+      unless include?(entry)
+        @index[entry] = @entries.length
+        @entries << entry
+      end
+      self
+    end
+
+    # Merge in another OrderedSet
+    #
+    # @param [#each] other
+    #   the other ordered set
+    #
+    # @return [OrderedSet]
+    #   returns self
+    #
+    # @api private
+    def merge(other)
+      other.each { |entry| self << entry }
+      self
+    end
+
+    # Iterate over each entry
+    #
+    # @yield [entry]
+    #   yield to the entry
+    #
+    # @yieldparam [Object] entry
+    #   an entry in the ordered set
+    #
+    # @return [OrderedSet]
+    #   returns self
+    #
+    # @api private
+    def each(&block)
+      @entries.each(&block)
+      self
+    end
+
+    # Check if there are any entries
+    #
+    # @return [Boolean]
+    #   true if there are no entries, false if there are
+    #
+    # @api private
+    def empty?
+      @entries.empty?
+    end
+
+    # The number of entries
+    #
+    # @return [Integer]
+    #   number of entries
+    #
+    # @api private
+    def length
+      @entries.length
+    end
+
+    # Check if the entry exists in the set
+    #
+    # @param [Object] entry
+    #   the entry to test for
+    #
+    # @return [Boolean]
+    #   true if the entry exists in the set, false if not
+    #
+    # @api private
+    def include?(entry)
+      @index.key?(entry)
+    end
+
+    # Return the index for the entry in the set
+    #
+    # @param [Object] entry
+    #   the entry to check the set for
+    #
+    # @return [Integer, nil]
+    #   the index for the entry, or nil if it does not exist
+    #
+    # @api private
+    def index(entry)
+      @index[entry]
+    end
+
+  end # class OrderedSet
+end # module Yardstick

data/lib/yardstick/processor.rb

@@ -0,0 +1,65 @@
+module Yardstick
+  class Processor
+
+    # Measure files provided
+    #
+    # @param [Array<#to_s>, #to_s] path
+    #   the files to measure
+    #
+    # @return [MeasurementSet]
+    #   a collection of measurements
+    #
+    # @api private
+    def self.process_path(path)
+      YARD.parse(Array(path).map { |file| file.to_s })
+      measurements
+    end
+
+    # Measure string provided
+    #
+    # @param [#to_str] string
+    #   the string to measure
+    #
+    # @return [MeasurementSet]
+    #   a collection of measurements
+    #
+    # @api private
+    def self.process_string(string)
+      YARD.parse_string(string.to_str)
+      measurements
+    end
+
+    # Measure method objects in YARD registry
+    #
+    # @return [MeasurementSet]
+    #   a collection of measurements
+    #
+    # @api private
+    def self.measurements
+      measurements = MeasurementSet.new
+      method_objects.each do |method_object|
+        measurements.merge(method_object.docstring.measure)
+      end
+      measurements
+    end
+
+    # Return method objects in YARD registry
+    #
+    # @return [Array<YARD::CodeObjects::MethodObject>]
+    #   a collection of method objects
+    #
+    # @api private
+    def self.method_objects
+      YARD::Registry.all(:method).sort_by do |method_object|
+        [ method_object.file, method_object.line ]
+      end
+    ensure
+      YARD::Registry.clear
+    end
+
+    class << self
+      private :measurements, :method_objects
+    end
+
+  end # class Processor
+end # module Yardstick

data/lib/yardstick/rake/measurement.rb

@@ -0,0 +1,101 @@
+require 'rake'
+require 'rake/tasklib'
+
+module Yardstick
+  module Rake
+    class Measurement < ::Rake::TaskLib
+
+      # List of paths to measure
+      #
+      # @param [Array<#to_s>, #to_s] path
+      #   optional list of paths to measure
+      #
+      # @return [undefined]
+      #
+      # @api public
+      attr_writer :path
+
+      # The path to the file where the measurements will be written
+      #
+      # @param [String, Pathname] output
+      #   optional output path for measurements
+      #
+      # @return [undefined]
+      #
+      # @api public
+      def output=(output)
+        @output = Pathname(output)
+      end
+
+      # Initializes a Measurement task
+      #
+      # @example
+      #   task = Yardstick::Rake::Measurement
+      #
+      # @param [Symbol] name
+      #   optional task name
+      #
+      # @yield [task]
+      #   yield to self
+      #
+      # @yieldparam [Yardstick::Rake::Measurement] task
+      #   the measurement task
+      #
+      # @return [Yardstick::Rake::Measurement]
+      #   the measurement task
+      #
+      # @api public
+      def initialize(name = :yardstick_measure)
+        @name = name
+        @path = 'lib/**/*.rb'
+
+        self.output = 'measurements/report.txt'
+
+        yield self if block_given?
+
+        define
+      end
+
+      # Measure the documentation
+      #
+      # @example
+      #   task.yardstick_measure  # (output measurement report)
+      #
+      # @return [undefined]
+      #
+      # @api public
+      def yardstick_measure
+        write_report { |io| Yardstick.measure(@path).puts(io) }
+      end
+
+    private
+
+      # Define the task
+      #
+      # @return [undefined]
+      #
+      # @api private
+      def define
+        desc "Measure docs in #{@path} with yardstick"
+        task(@name) { yardstick_measure }
+      end
+
+      # Open up a report for writing
+      #
+      # @yield [io]
+      #   yield to an object that responds to #puts
+      #
+      # @yieldparam [#puts] io
+      #   the object that responds to #puts
+      #
+      # @return [undefined]
+      #
+      # @api private
+      def write_report(&block)
+        @output.dirname.mkpath
+        @output.open('w', &block)
+      end
+
+    end # class Measurement
+  end # module Rake
+end # module Yardstick

data/lib/yardstick/rake/verify.rb

@@ -0,0 +1,179 @@
+require 'rake'
+require 'rake/tasklib'
+
+module Yardstick
+  module Rake
+    class Verify < ::Rake::TaskLib
+
+      # Set the threshold
+      #
+      # @param [Number] threshold
+      #   the threshold to set
+      #
+      # @return [undefined]
+      #
+      # @api public
+      attr_writer :threshold
+
+      # Specify if the threshold should match the coverage
+      #
+      # @param [Boolean] require_exact_threshold
+      #   true if the threshold should match the coverage, false if not
+      #
+      # @return [undefined]
+      #
+      # @api public
+      attr_writer :require_exact_threshold
+
+      # List of paths to measure
+      #
+      # @param [Array<#to_s>, #to_s] path
+      #   optional list of paths to measure
+      #
+      # @return [undefined]
+      #
+      # @api public
+      attr_writer :path
+
+      # Specify if the coverage summary should be displayed
+      #
+      # @param [Boolean] verbose
+      #   true if the coverage summary should be displayed, false if not
+      #
+      # @return [undefined]
+      #
+      # @api public
+      attr_writer :verbose
+
+      # Initialize a Verify task
+      #
+      # @example
+      #   task = Yardstick::Rake::Verify.new do |task|
+      #     task.threshold = 100
+      #   end
+      #
+      # @param [Symbol] name
+      #   optional task name
+      #
+      # @yield [task]
+      #   yield to self
+      #
+      # @yieldparam [Yardstick::Rake::Verify] task
+      #   the verification task
+      #
+      # @return [Yardstick::Rake::Verify] task
+      #   the verification task instance
+      #
+      # @api public
+      def initialize(name = :verify_measurements)
+        @name                    = name
+        @require_exact_threshold = true
+        @path                    = 'lib/**/*.rb'
+        @verbose                 = true
+
+        yield self
+
+        assert_threshold
+        define
+      end
+
+      # Verify the YARD coverage measurements
+      #
+      # @example
+      #   task.verify_measurements  # output coverage and threshold
+      #
+      # @return [undefined]
+      #
+      # @raise [RuntimeError]
+      #   raised if threshold is not met
+      # @raise [RuntimeError]
+      #   raised if threshold is not equal to the coverage
+      #
+      # @api public
+      def verify_measurements
+        puts "Coverage: #{total_coverage}% (threshold: #{@threshold}%)" if verbose
+        assert_meets_threshold
+        assert_matches_threshold
+      end
+
+    private
+
+      # Define the task
+      #
+      # @return [undefined]
+      #
+      # @api private
+      def define
+        desc "Verify that yardstick coverage is at least #{@threshold}%"
+        task(@name) { verify_measurements }
+      end
+
+      # The total YARD coverage
+      #
+      # @return [Float]
+      #   the total coverage
+      #
+      # @api private
+      def total_coverage
+        measurements = Yardstick.measure(@path)
+        round_percentage(measurements.coverage * 100)
+      end
+
+      # Round percentage to 1/10th of a percent
+      #
+      # @param [Float] percentage
+      #   the percentage to round
+      #
+      # @return [Float]
+      #   the rounded percentage
+      #
+      # @api private
+      def round_percentage(percentage)
+        (percentage * 10).ceil / 10.0
+      end
+
+      # Raise an exception if threshold is not set
+      #
+      # @return [undefined]
+      #
+      # @raise [RuntimeError]
+      #   raised if threshold is not set
+      #
+      # @api private
+      def assert_threshold
+        if @threshold.nil?
+          raise 'threshold must be set'
+        end
+      end
+
+      # Raise an exception if the threshold is not met
+      #
+      # @return [undefined]
+      #
+      # @raise [RuntimeError]
+      #   raised if threshold is not met
+      #
+      # @api private
+      def assert_meets_threshold
+        if total_coverage < @threshold
+          raise "Coverage must be at least #{@threshold}% but was #{total_coverage}%"
+        end
+      end
+
+      # Raise an exception if the threshold is not equal to the coverage
+      #
+      # @return [undefined]
+      #
+      # @raise [RuntimeError]
+      #   raised if threshold is not equal to the coverage
+      #
+      # @api private
+      def assert_matches_threshold
+        if @require_exact_threshold && total_coverage > @threshold
+          raise "Coverage has increased above the threshold of #{@threshold}% to #{total_coverage}%. You should update your threshold value."
+        end
+      end
+
+    end # class Verify
+  end # module Rake
+end # module Yardstick