dcov 0.1.0

data/History.txt

@@ -0,0 +1,15 @@
+== 0.0.1 2007-05-28
+
+* 1 major enhancement:
+  * Initial release
+
+== 0.0.2 2007-06-20
+
+* 3 major enhancements:
+  * Refactored generators out to separate classes
+  * Added rudimentary Ruport support
+  * Refactored analyzers out to separate classes to allow users to easily define custom analyzers
+
+== 0.1.0
+
+No serious enhancements other than a pretty major bug fix and a new version number. :)

data/License.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2007 Jeremy McAnally
+
+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,21 @@
+History.txt
+License.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/dcov
+lib/dcov.rb
+lib/dcov/analyzer.rb
+lib/dcov/version.rb
+lib/dcov/stats.rb
+lib/dcov/analyzed_token.rb
+lib/dcov/generators/html/generator.rb
+lib/dcov/analyzers/coverage_analyzer.rb
+setup.rb
+spec/dcov_spec.rb
+spec/spec_helper.rb
+spec/blank_code.rb
+spec/just_a_class.rb
+spec/just_a_method.rb
+spec/just_a_module.rb
+spec/mock_code.rb

data/README.txt

@@ -0,0 +1,12 @@
+dcov -- Your friendly neighborhood Ruby documentation analyzer
+==============================================================
+
+dcov is a tool to analyze your Ruby documentation.  At this time, it only checks for coverage and not quality (even though it will check for that one day...).
+
+To use dcov, you simply invoke the command from your terminal/command prompt, followed by a list of files to analyze:
+
+  dcov my_file.rb your_file.rb
+
+That will spit out a file named coverage.html in the current directory (more formats such as plaintext and PDF to come), which contains information about your documentation coverage.
+
+

data/Rakefile

@@ -0,0 +1,120 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/contrib/rubyforgepublisher'
+require 'fileutils'
+require 'hoe'
+begin
+  require 'spec/rake/spectask'
+rescue LoadError
+  puts 'To use rspec for testing you must install rspec gem:'
+  puts '$ sudo gem install rspec'
+  exit
+end
+
+include FileUtils
+require File.join(File.dirname(__FILE__), 'lib', 'dcov', 'version')
+
+AUTHOR = 'Jeremy McAnally'  # can also be an array of Authors
+EMAIL = "jeremymcanally@gmail.com"
+DESCRIPTION = "A documentation analysis tool for Ruby."
+GEM_NAME = 'dcov' # what ppl will type to install your gem
+
+@config_file = "~/.rubyforge/user-config.yml"
+@config = nil
+def rubyforge_username
+  unless @config
+    begin
+      @config = YAML.load(File.read(File.expand_path(@config_file)))
+    rescue
+      puts <<-EOS
+ERROR: No rubyforge config file found: #{@config_file}"
+Run 'rubyforge setup' to prepare your env for access to Rubyforge
+ - See http://newgem.rubyforge.org/rubyforge.html for more details
+      EOS
+      exit
+    end
+  end
+  @rubyforge_username ||= @config["username"]
+end
+
+RUBYFORGE_PROJECT = 'dcov' # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
+
+NAME = "dcov"
+REV = nil 
+# UNCOMMENT IF REQUIRED: 
+# REV = `svn info`.each {|line| if line =~ /^Revision:/ then k,v = line.split(': '); break v.chomp; else next; end} rescue nil
+VERS = Dcov::VERSION::STRING + (REV ? ".#{REV}" : "")
+CLEAN.include ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']
+RDOC_OPTS = ['--quiet', '--title', 'dcov documentation',
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "README",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps 
+    @extra_deps.reject { |x| Array(x).first == 'hoe' } 
+  end 
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.author = AUTHOR 
+  p.description = DESCRIPTION
+  p.email = EMAIL
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/test_*.rb"]
+  p.clean_globs = CLEAN  #An array of file patterns to delete on clean.
+  
+  # == Optional
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  p.extra_deps = [['ruport', '>= 0.0.1']]     # An array of rubygem dependencies [name, version], e.g. [ ['active_support', '>= 1.3.1'] ]
+  #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
+end
+
+CHANGES = hoe.paragraphs_of('History.txt', 0..1).join("\n\n")
+PATH    = (RUBYFORGE_PROJECT == GEM_NAME) ? RUBYFORGE_PROJECT : "#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
+hoe.remote_rdoc_dir = File.join(PATH.gsub(/^#{RUBYFORGE_PROJECT}\/?/,''), 'rdoc')
+
+desc 'Release the website and new gem version'
+task :deploy => [:check_version, :release] do
+  puts "Remember to create SVN tag:"
+  puts "svn copy svn+ssh://#{rubyforge_username}@rubyforge.org/var/svn/#{PATH}/trunk " +
+    "svn+ssh://#{rubyforge_username}@rubyforge.org/var/svn/#{PATH}/tags/REL-#{VERS} "
+  puts "Suggested comment:"
+  puts "Tagging release #{CHANGES}"
+end
+
+desc 'Runs tasks website_generate and install_gem as a local deployment of the gem'
+task :local_deploy => [:install_gem]
+
+task :check_version do
+  unless ENV['VERSION']
+    puts 'Must pass a VERSION=x.y.z release version'
+    exit
+  end
+  unless ENV['VERSION'] == VERS
+    puts "Please update your version.rb to match the release version, currently #{VERS}"
+    exit
+  end
+end
+
+desc "Run the specs under spec/models"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_opts = ['--color']
+  t.spec_files = FileList['spec/*_spec.rb']
+end
+
+desc "Default task is to run specs"
+task :default => :spec
+

data/bin/dcov

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+#
+#  Created by Jeremy McAnally on 2007-5-28.
+#  Copyright (c) 2007. All rights reserved.
+
+begin
+  require 'rubygems'
+rescue LoadError
+  # no rubygems to load, so we fail silently
+end
+
+require 'optparse'
+require File.dirname(__FILE__) + '/../lib/dcov'
+
+# NOTE: the option -p/--path= is given as an example, and should probably be replaced in your application.
+
+OPTIONS = {
+  :path     => Dir.getwd,
+  :output_format => 'html',
+  :files => ''
+}
+MANDATORY_OPTIONS = %w( )
+
+parser = OptionParser.new do |opts|
+  opts.banner = <<BANNER
+dcov - A documentation coverage and quality analyzer for Ruby
+
+Usage: #{File.basename($0)} [options]
+
+Options are:
+BANNER
+  opts.separator ""
+  opts.on("-p", "--path=PATH", String,
+          "The root path for selecting files",
+          "Default: current working directory") { |OPTIONS[:path]| }
+  opts.on("-f", "--output-format=FORMAT", String,
+          "The output format for the coverage report",
+          "Default: HTML") { |OPTIONS[:output_format]| }
+  opts.on("-h", "--help",
+          "Show this help message.") { puts opts; exit }
+  opts.parse!(ARGV)
+
+  if MANDATORY_OPTIONS && MANDATORY_OPTIONS.find { |option| OPTIONS[option.to_sym].nil? }
+    puts opts; exit
+  end
+end
+
+if (ARGV != [])
+  OPTIONS[:files] = ARGV
+  @coverage = Dcov::Analyzer.new(OPTIONS)
+else
+  raise "No files to analyze!"
+end

data/lib/dcov/analyzed_token.rb

@@ -0,0 +1,12 @@
+class AnalyzedToken
+  attr_accessor :name, :parent
+  
+  def initialize(name, parent)
+    @name = name
+    @parent = parent
+  end
+  
+  def ==(other)
+    (self.name == other.name) && (self.parent == other.parent) 
+  end
+end

data/lib/dcov/analyzer.rb

@@ -0,0 +1,163 @@
+require 'rdoc/rdoc'
+require 'dcov/analyzed_token.rb'
+require 'dcov/stats'
+
+# Makes +stats+ accessible to us so we can inject our own.
+# We also add a +classifier+ attribtue to the code object classes.
+module RDoc
+  class RDoc
+    attr_accessor :stats
+  end
+  
+  class AnyMethod
+    def classifier
+      :method
+    end
+  end
+  
+  class NormalClass
+    def classifier
+      :class
+    end
+  end
+  
+  class NormalModule
+    def classifier
+      :module
+    end
+  end
+end
+
+module Dcov
+  
+  # Mocked options object to feed to RDoc
+  class RDocOptionsMock
+    attr_accessor :files
+
+    def initialize(file_list)
+      @files = file_list
+    end
+
+    def method_missing(*args)
+      false
+    end
+  end
+  
+  # Main class
+  class Analyzer
+    attr_accessor :classes, :methods, :modules, :hierarchy, :stats
+    
+    # Grab the arguments from the DCov init script or
+    # another calling script and feed them to RDoc for
+    # parsing.
+    def initialize(options)
+      @options = options
+      
+      # Setup the analyzed tokens array so we can keep track of which methods we've already
+      # taken a look at...
+      @analyzed_tokens = []
+      
+      r = RDoc::RDoc.new
+      
+      # Instantiate our little hacked Stats class...
+      @stats = Dcov::Stats.new
+      r.stats = @stats
+      
+      # Get our analyzers together...
+      @analyzers = []
+      find_analyzers
+      
+      # Setup any options we need here...
+      Options.instance.parse(["--tab-width", 2], {})
+            
+      # We have to use #send because #parse_files is private
+      parsed_structure = r.send(:parse_files, RDocOptionsMock.new(options[:files]))
+      
+      # Analyze it, Spiderman!
+      analyze parsed_structure
+      
+      # Generate the report!
+      generate
+    end
+    
+    # Method to initialize analysis of the code; passes
+    # structure off to the process method which actually
+    # processes the tokens.
+    def analyze(hierarchy)
+      @hierarchy = hierarchy
+      process
+
+      @stats.print   
+    end
+    
+    # Method to start walking the hierarchy of tokens,
+    # separating them into covered/not covered (and 
+    # eventually lexing their comments for quality).
+    def process
+      @hierarchy.each do |hier| 
+        hier.classes.each do |cls| 
+          process_token cls
+        end
+        
+        hier.modules.each do |mod|
+          process_token mod
+        end
+      end
+    end
+    
+    # Method to process all the tokens for a token...recursion FTW! :)
+    def process_token(token)
+      analyzed_token = AnalyzedToken.new(token.name, token.parent)
+      unless @analyzed_tokens.include?(analyzed_token)
+        expose_to_analyzers(token)
+        @analyzed_tokens << analyzed_token
+                 
+        [:method_list, :classes, :modules].each do |meth, type|
+          token.send(meth).each do |item|
+            process_token item
+          end if token.respond_to?(meth)
+        end
+      end
+    end
+    
+    # Generate the output based on the format specified
+    # TODO: Have an argument sanity check at startup to make sure we actually have a generator for the format
+    def generate
+      print "Generating report..."
+      require File.dirname(__FILE__) + "/generators/#{@options[:output_format]}/generator.rb"
+      report = @stats.as(@options[:output_format].to_sym) 
+      print "done.\n"
+      
+      print "Writing report..."
+      if (!File.exists?("#{@options[:path]}/coverage.html")) || (File.writable?("#{@options[:path]}/coverage.html"))
+        output_file = File.open("#{@options[:path]}/coverage.html", "w")
+        output_file.write report
+        output_file.close
+        print "done.\n"
+      else
+        raise "Can't write to [#{@options[:path]}/coverage.html]."
+      end
+    end
+    
+    # Grok the analyzers directory and find all analyzers
+    def find_analyzers
+      Dir::entries(File.dirname(__FILE__) + "/analyzers").each do |analyzer|
+        next unless /(\w+)_analyzer.rb$/ =~ analyzer
+        type = $1
+
+        require File.dirname(__FILE__) + "/analyzers/#{analyzer}"
+        @analyzers << "#{type.capitalize}Analyzer".intern
+      end
+    end
+    
+    # Fire off the token to each analyzer, letting it have its way with
+    # the token and the Stats instance.
+    def expose_to_analyzers(token)
+      @analyzers.each do |analyzer|
+        classifier = token.classifier
+        
+        Dcov::Analyzers.const_get(analyzer).analyze(token, classifier, @stats)
+      end
+    end
+  end
+end   

data/lib/dcov/analyzers/coverage_analyzer.rb

@@ -0,0 +1,9 @@
+module Dcov
+  module Analyzers
+    class CoverageAnalyzer
+      def self.analyze(token, classifier, stats)
+        (token.comment.nil? || token.comment == '') ? stats.coverage[classifier][:not_covered] << token : stats.coverage[classifier][:covered] << token
+      end
+    end
+  end
+end

data/lib/dcov/generators/html/generator.rb

@@ -0,0 +1,39 @@
+module Dcov
+  # Generates HTML output
+  class Generator < Ruport::Formatter::HTML
+    renders :html, :for => StatsRenderer
+          
+    def build_stats_header 
+      output << "<html><head><title>dcov results</title>"+
+                "</head><body>\n<h1>dcov results</h1>\n\n"   
+    end
+
+    def build_stats_body
+      output << "<p>\n"
+      output << "Class coverage: <b>#{class_coverage}%</b><br>\n"
+      output << "Module coverage: <b>#{module_coverage}%</b><br>\n"
+      output << "Method coverage: <b>#{method_coverage}%</b><br>\n"
+      output << "</p>\n\n"
+      output << "<ul>\n" 
+
+      data[:structured].each do |key,value|
+        output << ((value[0].comment.nil? || value[0].comment == '') ? 
+                "\t<li><font color='#f00;'>#{key}</font>\n\t\t<ul>\n" : 
+                "\t<li> #{key}\n\t\t<ul>")
+
+        value[1].each do |itm|
+          output << ((itm.comment.nil? || itm.comment == '') ? 
+                "\t\t\t<li><font color='#f00;'>#{itm.name}</font></li>\n" : 
+                 "\t\t\t<li> #{itm.name}</li>\n")
+        end
+
+        output << "\t\t</ul>\n\t</li>\n\n"
+      end  
+    end
+
+    def build_stats_footer
+      output << "\n\n</body></html>"   
+    end
+
+  end
+end

data/lib/dcov/stats.rb

@@ -0,0 +1,106 @@
+require 'rubygems'
+require 'ruport'
+
+module Dcov
+  class StatsRenderer < Ruport::Renderer
+  
+    stage :stats_header, :stats_body, :stats_footer
+  
+    module Helpers
+     
+      def class_coverage
+         data[:coverage_rating][:class]
+      end
+
+      def module_coverage
+         data[:coverage_rating][:module]
+      end
+
+      def method_coverage
+         data[:coverage_rating][:method]
+      end
+
+    end
+  end
+  
+  class TopLevel
+    attr_accessor :comment
+  end
+  
+  # RDoc's Stats class with our own stats thrown in and our own custom
+  # print method.
+  class Stats
+    
+    attr_accessor :num_files, :num_classes, :num_modules, :num_methods, :coverage
+    
+    include Ruport::Renderer::Hooks
+    renders_with Dcov::StatsRenderer
+    
+    def initialize
+      @num_files = @num_classes = @num_modules = @num_methods = 0
+      @start = Time.now
+    
+      @coverage = { }
+
+      [:class, :method, :module].each do |type|
+        @coverage[type] = { :covered => [], :not_covered => [] }
+      end
+    end
+  
+    # Print out the coverage rating
+    def print
+      puts "\n\nFiles:   #{@num_files}"
+      puts "Total Classes: #{@num_classes}"
+      puts "Total Modules: #{@num_modules}"
+      puts "Total Methods: #{@num_methods}"
+      puts "\n\n\n"
+      puts "Class coverage: #{coverage_rating(:class)}%\n"
+      puts "\tNot covered: #{@coverage[:class][:not_covered].map{|itm| itm.name}.join(', ')}\n\n"
+
+      puts "Method coverage: #{coverage_rating(:method)}%\n"
+      puts "\tNot covered: #{@coverage[:method][:not_covered].map{|itm| itm.parent.name + "#" + itm.name}.join(', ')}\n\n"
+
+      puts "Module coverage: #{coverage_rating(:module)}%"
+      puts "\tNot covered: #{@coverage[:module][:not_covered].map{|itm| itm.name}.join(', ')}\n\n"
+    end
+  
+    # Get the coverage rating (e.g., 34%) for the tokens of the type specified
+    def coverage_rating(tokens)
+      rating = ((@coverage[tokens][:covered].size.to_f / (@coverage[tokens][:covered].size.to_f + @coverage[tokens][:not_covered].size.to_f)) * 100)
+      
+      # If it's NaN (for whatever reason, be it an irrational or irrationally small number), return 0
+      (rating.nan?) ? 0 : rating.to_i
+    end
+    
+    def renderable_data
+      data = {}
+      data[:coverage_rating] = {}
+      
+      [:class, :method, :module].each do |token|
+        data[:coverage_rating][token] = coverage_rating(token)
+      end
+      
+      classes = @coverage[:class][:not_covered] + @coverage[:class][:covered]
+      modules = @coverage[:module][:not_covered] + @coverage[:module][:covered]
+      methods = @coverage[:method][:not_covered] + @coverage[:method][:covered]
+      
+      # Create a properly nested structure
+      data[:structured] = {}
+      classes.each {|cls| data[:structured][cls.name] = [cls, []]}
+      modules.each {|mod| data[:structured][mod.name] = [mod, []]}
+      data[:structured]['[Toplevel]'] = [TopLevel.new, []]
+      
+      methods.each do |method|
+        if (data[:structured].has_key?(method.parent.name))
+          data[:structured][method.parent.name][1] << method
+        else
+          data[:structured]['[Toplevel]'][1] << method
+        end
+      end
+      
+      data[:analyzed] = @coverage
+      
+      data
+    end
+  end
+end

data/lib/dcov/version.rb

@@ -0,0 +1,9 @@
+module Dcov #:nodoc:
+  module VERSION #:nodoc:
+    MAJOR = 0
+    MINOR = 1
+    TINY  = 0
+
+    STRING = [MAJOR, MINOR, TINY].join('.')
+  end
+end

data/lib/dcov.rb

@@ -0,0 +1,5 @@
+module Dcov
+end
+
+require 'dcov/version.rb'
+require 'dcov/analyzer.rb'