yardstick 0.9.6 → 0.9.7

data/config/rubocop.yml

@@ -0,0 +1,49 @@
+AllCops:
+  Includes:
+    - '**/*.rake'
+    - 'Gemfile'
+    - 'Gemfile.devtools'
+  Excludes:
+    - '**/vendor/**'
+
+# Avoid parameter lists longer than five parameters.
+ParameterLists:
+  Max: 3
+  CountKeywordArgs: true
+
+# Avoid more than `Max` levels of nesting.
+BlockNesting:
+  Max: 3
+
+# Align with the style guide.
+CollectionMethods:
+  PreferredMethods:
+    collect:  'map'
+    inject:   'reduce'
+    find:     'detect'
+    find_all: 'select'
+
+# Do not force public/protected/private keyword to be indented at the same
+# level as the def keyword. My personal preference is to outdent these keywords
+# because I think when scanning code it makes it easier to identify the
+# sections of code and visually separate them. When the keyword is at the same
+# level I think it sort of blends in with the def keywords and makes it harder
+# to scan the code and see where the sections are.
+AccessControl:
+  Enabled: false
+
+# Limit line length
+LineLength:
+  Max: 146  # TODO: lower to 79
+
+# Disable documentation checking until a class needs to be documented once
+Documentation:
+  Enabled: false
+
+# Do not favor modifier if/unless usage when you have a single-line body
+IfUnlessModifier:
+  Enabled: false
+
+# Do not use sprintf instead of String#%.
+FavorSprintf:
+  Enabled: false

data/config/yardstick.yml

@@ -1,2 +1,33 @@
 ---
 threshold: 100
+rules:
+  ApiTag::Presence:
+    enabled: true
+    exclude: []
+  ApiTag::Inclusion:
+    enabled: true
+    exclude: []
+  ApiTag::ProtectedMethod:
+    enabled: true
+    exclude: []
+  ApiTag::PrivateMethod:
+    enabled: true
+    exclude: []
+  ExampleTag:
+    enabled: true
+    exclude: []
+  ReturnTag:
+    enabled: true
+    exclude: []
+  Summary::Presence:
+    enabled: true
+    exclude: []
+  Summary::Length:
+    enabled: true
+    exclude: []
+  Summary::Delimiter:
+    enabled: true
+    exclude: []
+  Summary::SingleLine:
+    enabled: true
+    exclude: []

data/lib/yardstick.rb

@@ -1,21 +1,29 @@
 # encoding: utf-8
 
 require 'pathname'
-require 'rational'
+require 'delegate'
 
 require 'backports'
 require 'yard'
 
 require 'yardstick/ordered_set'
-require 'yardstick/rule_set'
 require 'yardstick/measurement'
 
-require 'yardstick/measurement_set'
-require 'yardstick/processor'
+require 'yardstick/config'
+require 'yardstick/report_output'
+require 'yardstick/document'
+
 require 'yardstick/rule'
+require 'yardstick/rule_config'
+require 'yardstick/rules/api_tag'
+require 'yardstick/rules/example_tag'
+require 'yardstick/rules/summary'
+require 'yardstick/rules/return_tag'
 
-require 'yardstick/measurable'
-require 'yardstick/method'
+require 'yardstick/measurement_set'
+require 'yardstick/document_set'
+require 'yardstick/processor'
+require 'yardstick/parser'
 
 require 'yardstick/yard_ext'
 
@@ -27,19 +35,18 @@ module Yardstick
   # Measure a list of files
   #
   # @example
-  #   Yardstick.measure('article.rb')  # => [ Measurement ]
+  #   config = Yardstick::Config.coerce(path: 'article.rb')
+  #   Yardstick.measure(config)  # => [ MeasurementSet ]
   #
-  # @param [Array<#to_s>, #to_s] path
-  #   optional list of paths to measure
-  # @param [Hash] options
+  # @param [Config] config
   #   optional configuration
   #
   # @return [Yardstick::MeasurementSet]
   #   the measurements for each file
   #
   # @api public
-  def self.measure(path = 'lib/**/*.rb', options = {})
-    Processor.process_path(path)
+  def self.measure(config = Config.new)
+    Processor.new(config).process
   end
 
   # Measure a string of code and YARD documentation
@@ -51,15 +58,28 @@ module Yardstick
   #
   # @param [#to_str] string
   #   the string to measure
-  # @param [Hash] options
+  # @param [Config] config
   #   optional configuration
   #
   # @return [Yardstick::MeasurementSet]
   #   the measurements for the string
   #
   # @api public
-  def self.measure_string(string, options = {})
-    Processor.process_string(string)
+  def self.measure_string(string, config = Config.new)
+    Processor.new(config).process_string(string)
+  end
+
+  # Round percentage to 1/10th of a percent
+  #
+  # @param [Float] percentage
+  #   the percentage to round
+  #
+  # @return [Float]
+  #   the rounded percentage
+  #
+  # @api private
+  def self.round_percentage(percentage)
+    (percentage * 10).floor / 10.0
   end
 
 end # module Yardstick

data/lib/yardstick/cli.rb

@@ -20,7 +20,7 @@ module Yardstick
     #
     # @api public
     def self.run(*args)
-      measurements = Yardstick.measure(*parse_options(args))
+      measurements = Yardstick.measure(parse_config(args))
       measurements.puts
       measurements
     end
@@ -30,29 +30,29 @@ module Yardstick
     # @param [Array<String>] args
     #   the command-line options
     #
-    # @return [Array(Array<String>, Hash)]
+    # @return [Config]
     #   the list of files, and options parsed from the command-line
     #
     # @api private
-    def self.parse_options(args)
+    def self.parse_config(args)
       args << '--help' if args.empty?
       options = {}
       option_parser(options).parse!(args)
-      [ args, options ]
+      Config.new(options.merge(path: args))
     rescue OptionParser::InvalidOption => error
       display_exit(error.message)
     end
 
     # Return an OptionParser instance for the command-line app
     #
-    # @param [Hash] options
+    # @param [Hash] _options
     #   the options to set when parsing the command-line arguments
     #
     # @return [Yardstick::OptionParser]
     #   the option parser instance
     #
     # @api private
-    def self.option_parser(options)
+    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.to_s) }
@@ -73,7 +73,7 @@ module Yardstick
     end
 
     class << self
-      private :option_parser, :parse_options, :display_exit
+      private :option_parser, :parse_config, :display_exit
     end
 
   end # module CLI

data/lib/yardstick/config.rb

@@ -0,0 +1,176 @@
+# encoding: utf-8
+
+module Yardstick
+  # Handles Yardstick configuration
+  #
+  class Config
+    InvalidRule = Class.new(StandardError)
+
+    NAMESPACE_PREFIX = 'Yardstick::Rules::'.freeze
+
+    # Set the threshold
+    #
+    # @return [undefined]
+    #
+    # @api public
+    attr_writer :threshold
+
+    # Threshold value
+    #
+    # @return [Integer]
+    #
+    # @api private
+    attr_reader :threshold
+
+    # Specify if the threshold should match the coverage
+    #
+    # @return [undefined]
+    #
+    # @api public
+    attr_writer :require_exact_threshold
+
+    # List of paths to measure
+    #
+    # @return [undefined]
+    #
+    # @api public
+    attr_writer :path
+
+    # List of paths to measure
+    #
+    # @return [String]
+    #
+    # @api private
+    attr_reader :path
+
+    # Specify if the coverage summary should be displayed
+    #
+    # @return [undefined]
+    #
+    # @api public
+    attr_writer :verbose
+
+    # The path to the file where the measurements will be written
+    #
+    # @return [Yardstick::ReportOutput]
+    #
+    # @api private
+    attr_reader :output
+
+    # Coerces hash into a config object
+    #
+    # @param [Hash] hash
+    #
+    # @yieldparam [Yardstick::Config] config
+    #   the config object
+    #
+    # @return [Config]
+    #
+    # @api private
+    def self.coerce(hash, &block)
+      new(normalize_hash(hash), &block)
+    end
+
+    # Converts string keys into symbol keys
+    #
+    # @param [Hash] hash
+    #
+    # @return [Hash]
+    #   normalized hash
+    #
+    # @api private
+    def self.normalize_hash(hash)
+      hash.each_with_object({}) do |(key, value), normalized_hash|
+        normalized_value = value.is_a?(Hash) ? normalize_hash(value) : value
+        normalized_hash[key.to_sym] = normalized_value
+      end
+    end
+
+    # Initializes new config
+    #
+    # @param [Hash] options
+    #   optional configuration
+    #
+    # @yieldparam [Yardstick::Config] config
+    #   the config object
+    #
+    # @return [Yardstick::Config]
+    #
+    # @api private
+    def initialize(options = {}, &block)
+      set_defaults(options)
+
+      yield(self) if block_given?
+    end
+
+    # Return config for given rule
+    #
+    # @param [Class] rule_class
+    #
+    # @return [RuleConfig]
+    #
+    # @api private
+    def for_rule(rule_class)
+      key = rule_class.to_s[NAMESPACE_PREFIX.length..-1]
+
+      if key
+        RuleConfig.new(@rules.fetch(key.to_sym, {}))
+      else
+        raise InvalidRule, "every rule must begin with #{NAMESPACE_PREFIX}"
+      end
+    end
+
+    # Specify if the coverage summary should be displayed
+    #
+    # @return [Boolean]
+    #
+    # @api private
+    def verbose?
+      @verbose
+    end
+
+    # Return if the threshold should match the coverage
+    #
+    # @return [Boolean]
+    #
+    # @api private
+    def require_exact_threshold?
+      @require_exact_threshold
+    end
+
+    # 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 = ReportOutput.coerce(output)
+    end
+
+    private
+
+    # Sets default options
+    #
+    # @param [Hash] options
+    #   optional configuration
+    #
+    # @return [undefined]
+    #
+    # @api private
+    def set_defaults(options)
+      @threshold               = options.fetch(:threshold, 100)
+      @verbose                 = options.fetch(:verbose, true)
+      @path                    = options.fetch(:path, 'lib/**/*.rb')
+      @require_exact_threshold = options.fetch(:require_exact_threshold, true)
+      @rules                   = options.fetch(:rules, {})
+      self.output              = 'measurements/report.txt'
+    end
+
+    class << self
+      private :normalize_hash
+    end
+  end
+end

data/lib/yardstick/document.rb

@@ -0,0 +1,215 @@
+# encoding: utf-8
+
+module Yardstick
+
+  # Wraps a yard docstring to make a nicer interface
+  class Document
+    @registered_rules = Set.new
+
+    class << self
+      # Shows currently registered rules
+      #
+      # @return [Array<Class>]
+      #
+      # @api private
+      attr_reader :registered_rules
+    end
+
+    # Register rule with document
+    #
+    # @param [Class] rule_class
+    #   subclass of Yardstick::Rule
+    #
+    # @return [undefined]
+    #
+    # @api private
+    def self.register_rule(rule_class)
+      registered_rules << rule_class
+    end
+
+    # Measures docstring against enabled rules
+    #
+    # @param [Yardstring::Document] document
+    #   document that will be measured
+    # @param [Yardstick::Config] config
+    #   a configuration
+    #
+    # @return [MeasurementSet]
+    #
+    # @api private
+    def self.measure(document, config)
+      MeasurementSet.new(
+        registered_rules.map do |rule_class|
+          Measurement.new(rule_class.coerce(document, config))
+        end
+      )
+    end
+
+    # Return document yard docstring
+    #
+    # @return [YARD::Docstring]
+    #
+    # @api private
+    attr_reader :docstring
+
+    # Initializes Document object with docstring
+    #
+    # @param [Yard::Docstring]
+    #
+    # @return [undefined]
+    #
+    # @api private
+    def initialize(docstring)
+      @docstring = docstring
+    end
+
+    # The raw text for the summary
+    #
+    # @return [String]
+    #   the summary text
+    #
+    # @api private
+    def summary_text
+      @docstring.split(/\r?\n\r?\n/).first.to_s
+    end
+
+    # Tests if document has a tag
+    #
+    # @param [String] name
+    #   the name of the tag
+    #
+    # @return [Boolean]
+    #   true if tag exists
+    #
+    # @api private
+    def has_tag?(name)
+      @docstring.has_tag?(name)
+    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
+    end
+
+    # The types for a specified tag
+    #
+    # @param [String] tag_name
+    #   the name of the tag
+    #
+    # @return [Array<String>]
+    #   a collection of tag types
+    #
+    # @api private
+    def tag_types(tag_name)
+      tag(tag_name).types
+    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
+
+    # The filename for the code
+    #
+    # @return [Pathname]
+    #   the filename
+    #
+    # @api private
+    def file
+      Pathname(object.file)
+    end
+
+    # The line number for the code
+    #
+    # @return [Integer]
+    #   the line number
+    #
+    # @api private
+    def line
+      object.line
+    end
+
+    # The class and method name for the code
+    #
+    # @return [String]
+    #   the class and method name
+    #
+    # @api private
+    def path
+      object.path
+    end
+
+    private
+
+    # The code object for the docstring
+    #
+    # @return [YARD::CodeObjects::Base]
+    #   the code object
+    #
+    # @api private
+    def object
+      @docstring.object
+    end
+
+    # Finds tag by tag name
+    #
+    # @param [String] name
+    #   the name of the tag
+    #
+    # @return [YARD::Tags::Tag, NullTag]
+    #
+    # @api private
+    def tag(name)
+      @docstring.tag(name) || NullTag.new
+    end
+
+    # Null object for YARD::Tags::Tag
+    #
+    class NullTag
+      # Empty text
+      #
+      # @return [nil]
+      #
+      # @api private
+      def text
+        nil
+      end
+
+      # Empty list of types
+      #
+      # @return [Array]
+      #   an empty array
+      #
+      # @api private
+      def types
+        []
+      end
+    end
+  end
+end