piggly 1.2.0

data/README.markdown

@@ -0,0 +1,84 @@
+# Piggly - PostgreSQL PL/pgSQL stored procedure code coverage
+
+## What's Piggly?
+Piggly is like [RCov] [1] for PostgreSQL's PL/pgSQL stored procedures. It reports on code
+coverage to help you identify untested parts of your code.
+
+## Features
+* Branch, block, and loop coverage analysis
+* Instrumenting source-to-source compiler
+* Low test execution overhead
+* Reduced compilation times by use of disk caching
+* Readable and easily navigable reports (see example/piggly/reports/index.html)
+* Able to aggregate coverage across multiple runs
+* Test::Unit and RSpec compatible
+
+## Limitations
+* Cannot parse aggregate definitions (but helper functions are fine)
+* Cannot parse nested dollar-quoted strings, eg $A$ ... $B$ ... $B$ ... $A$
+* Report generation is resource intensive and slow
+
+## Requirements
+* [Treetop] [2]
+* Stored procedures stored on the filesystem, defined with "CREATE OR REPLACE FUNCTION ..."
+* The [ruby-pg driver] [3], and for the time being, ActiveRecord (some workaround should be possible)
+
+## Usage
+Assume your stored procedures are in proc/, and the tests that should be exercising your
+stored procedures are in spec/.
+
+    $ cd piggly/example/
+    $ ../bin/piggly -s 'proc/*.sql' 'spec/**/*_spec.rb'
+    Loading 1 test files
+     > Completed in 0.30 seconds
+    Compiling 1 files
+    Compiling /home/kputnam/wd/piggly/example/proc/iterate.sql
+     > Completed in 0.09 seconds
+    Installing 1 proc files
+     > Completed in 0.02 seconds
+    Clearing previous run's profile
+     > Completed in 0.00 seconds
+    ...........
+
+    Finished in 0.025061 seconds
+
+    11 examples, 0 failures
+    Storing coverage profile
+     > Completed in 0.00 seconds
+    Removing trace code
+     > Completed in 0.00 seconds
+    Creating index
+     > Completed in 0.00 seconds
+    Creating reports
+     > Completed in 0.02 seconds
+     > Completed in 0.65 seconds
+
+    $ ls -alh piggly/reports/index.html
+    -rw-r--r-- 1 kputnam kputnam 1.3K 2010-04-19 14:25 piggly/reports/index.html
+
+Note the compilation can be slow on the first run, but on subsequent runs it shouldn't need
+to be compiled again. If a file is added or changed (based on mtime), it will be recompiled.
+
+Piggly can also be run from Rake, with a task like:
+
+    namespace :spec do
+      Piggly::Task.new(:piggly => 'db:test:prepare') do |t|
+        t.libs.push 'spec'
+
+        t.test_files = FileList['spec/**/*_spec.rb']
+        t.proc_files = FileList['procs/*.sql']
+
+        # this can be used if piggly is frozen in a Rails application
+        t.libs.concat Dir['vendor/gems/*/lib/'].sort.reverse
+        t.piggly_path = Dir['vendor/gems/piggly-*/bin/piggly'].sort.last
+      end
+    end
+
+    $ rake spec:piggly
+
+## Author
+* Kyle Putnam <putnam.kyle@gmail.com>
+
+  [1]: http://github.com/relevance/rcov/
+  [2]: http://github.com/nathansobo/treetop
+  [3]: http://bitbucket.org/ged/ruby-pg/

data/Rakefile

@@ -0,0 +1,19 @@
+dir = File.dirname(__FILE__)
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'spec/rake/spectask'
+  Spec::Rake::SpecTask.new do |t|
+    t.pattern = 'spec/**/*_spec.rb'
+  end
+  task :default => :spec
+rescue Exception
+end
+
+require 'rake/gempackagetask'
+load './piggly.gemspec'
+Rake::GemPackageTask.new(Piggly.gemspec) do |pkg|
+  pkg.need_tar = false
+  pkg.need_zip = false
+end

data/bin/piggly

@@ -0,0 +1,245 @@
+#!/usr/bin/env ruby
+require 'optparse'
+require 'rubygems'
+$:.push File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'piggly'
+
+# Number of children to fork for parallel tasks
+Piggly::Queue.children = 2
+
+STDOUT.sync = true
+
+module Piggly
+  module Command
+    class << self
+
+      def main
+        benchmark do
+          sources, tests = parse_options
+          load_tests(tests)
+          connect_to_database
+          compile_procs(sources)
+          install_procs(sources)
+          clear_coverage
+          execute_tests
+          store_coverage
+          uninstall_procs(sources)
+          create_index(sources)
+          create_reports(sources)
+        end
+      end
+
+    private
+
+      def benchmark
+        start = Time.now
+        yield
+        puts " > Completed in #{'%0.2f' % (Time.now - start)} seconds"
+      end
+
+      def parse_options
+        proc_paths = []
+
+        opts = OptionParser.new do |opts|
+          opts.on("-I", "--include PATHS", "Prepend paths to $: (colon separated list)") do |paths|
+            $:.concat paths.split(':')
+          end
+
+          opts.on("-o", "--output PATH", "Report output directory") do |dir|
+            Piggly::Config.report_root = dir
+          end
+
+          opts.on("-c", "--cache-root PATH", "Compiler cache directory") do |dir|
+            Piggly::Config.cache_root = dir
+          end
+
+          opts.on("-s", "--proc-files PATH", "Stored procedures file list (may be specified many times)") do |dir|
+            proc_paths << dir
+          end
+
+        # opts.on("-T", "--trace-prefix PATH", "Trace prefix") do |str|
+        #   Piggly::Config.trace_prefix = str
+        # end
+          
+          opts.on("-a", "--aggregate", "Aggregate data from the previous run") do
+            Piggly::Config.aggregate = true
+          end
+
+          opts.on("--version", "Show version") do
+            puts "piggly #{Piggly::VERSION::STRING} #{Piggly::VERSION::RELEASE_DATE}"
+            exit
+          end
+
+          opts.on("-h", "--help", "Show this message") do
+            puts opts
+            exit 0
+          end
+        end
+
+        if index = ARGV.index('--')
+          extra = ARGV.slice!(index..-1).slice(1..-1)
+        else
+          extra = []
+        end
+
+        begin
+          opts.parse! ARGV
+          raise OptionParser::MissingArgument, "no tests specified" if ARGV.empty?
+        rescue OptionParser::InvalidOption, OptionParser::InvalidArgument, OptionParser::MissingArgument
+          puts opts
+          puts
+          puts $!.message
+          exit -1
+        end
+
+        proc_paths = proc_paths.map{|p| Dir[p] }.flatten.sort
+        test_paths = ARGV.map{|p| Dir[p] }.flatten.sort
+
+        ARGV.clear
+
+        return proc_paths, test_paths
+      end
+
+      def load_tests(tests)
+        puts "Loading #{tests.size} test files"
+
+        benchmark { tests.each{|file| load file } }
+
+      # # TODO: this doesn't seem right, but workaround RSpec executing each spec twice
+      # if defined? Spec::Runner::ExampleGroupRunner
+      #   Spec::Runner::ExampleGroupRunner.send(:define_method, :load_files) do |*args|
+      #     # don't do anything, we already loaded the files
+      #   end
+      # end
+      end
+
+      def connect_to_database
+        ActiveRecord::Base.connection.active?
+      rescue
+        ActiveRecord::Base.establish_connection
+      end
+
+      def compile_procs(sources)
+        stale = sources.select{|f| Piggly::TraceCompiler.stale?(f) }
+
+        # build the parser if needed
+        Piggly::Parser.parser
+
+        puts "Compiling #{stale.size} files"
+        benchmark do
+          stale.each do |file|
+            Piggly::Queue.child do
+              begin
+                Piggly::TraceCompiler.cache(file)
+            # rescue Errno::ENOENT, Piggly::Parser::Failure
+            #   puts "! #{File.basename file}"
+              rescue
+                puts
+                puts "#{$!.class}: #{$!.message}"
+                puts $!.backtrace.join("\n")
+              end
+            end
+          end
+          Piggly::Queue.start
+        end
+      end
+
+      def install_procs(sources)
+        puts "Installing #{sources.size} proc files"
+
+        benchmark do
+          sources.each do |file|
+            begin
+              Piggly::Installer.trace_proc(file)
+            rescue Errno::ENOENT, Piggly::Parser::Failure
+            # puts "! #{File.basename file}"
+            rescue
+              puts
+              puts "#{$!.class}: #{$!.message}"
+              puts $!.backtrace.join("\n")
+            end
+          end
+
+          Piggly::Installer.install_trace
+        end
+      end
+
+      def clear_coverage
+        unless Piggly::Config.aggregate
+          puts "Clearing previous run's profile"
+          benchmark { Piggly::Profile.clear }
+        end
+      end
+
+      def execute_tests
+        if defined? Spec::Runner
+          Spec::Runner.run
+        else
+          Test::Unit::AutoRunner.run
+        end
+      end
+
+      def store_coverage
+        puts "Storing coverage profile"
+        benchmark { Piggly::Profile.store }
+      end
+
+      def uninstall_procs(sources)
+        puts "Removing trace code"
+        benchmark do
+          sources.each do |file|
+            begin
+              Piggly::Installer.untrace_proc(file)
+            rescue Errno::ENOENT, Piggly::Parser::Failure
+            # puts "! #{File.basename file}"
+            rescue
+              puts
+              puts "#{$!.class}: #{$!.message}"
+              puts $!.backtrace.join("\n")
+            end
+          end
+
+          Piggly::Installer.uninstall_trace
+        end
+      end
+
+      def create_index(sources)
+        puts "Creating index"
+        benchmark do
+          Piggly::Reporter.install('piggly.css', 'sortable.js')
+          Piggly::HtmlReporter::Index.output(sources)
+        end
+      end
+
+      def create_reports(sources)
+        puts "Creating reports"
+        summary = Hash.new{|h,k| h[k] = Hash.new[:count => 0, :percent => 0]}
+
+        benchmark do
+          sources.each do |file|
+            Piggly::Queue.child do
+              begin
+                summary = Piggly::Profile.summary(file)
+                pretty  = Piggly::PrettyCompiler.compile(file, Piggly::Profile)
+
+                Piggly::HtmlReporter.output(file, pretty, summary)
+              rescue Errno::ENOENT, Piggly::Parser::Failure
+              # puts "! #{File.basename file}"
+              rescue
+                puts "#{$!.class}: #{$!.message}"
+                puts $!.backtrace.join("\n")
+              end
+            end
+          end
+
+          Piggly::Queue.start
+        end
+      end
+
+    end
+  end
+end
+
+if __FILE__ == $0
+  Piggly::Command.main
+end

data/lib/piggly/compiler/cache.rb

@@ -0,0 +1,151 @@
+module Piggly
+  module CompilerCache
+    def self.included(subclass)
+      subclass.extend(ClassMethods)
+    end
+
+    #
+    # Each cache unit (any group of data that should be expired and created
+    # together) can be broken apart, to prevent unmarshaling a huge block of
+    # data all at once.
+    #
+    # The interface works like a Hash, so the compile method should return a
+    # hash of objects. Each object is writen to a different file (named by the
+    # hash key) within the same directory. String objects are (usually) read
+    # and written directly to disk, while all other objects are (un-)Marshal'd
+    #
+    # Cache invalidation is done by comparing mtime timestamps on the cached
+    # object's file to all the "source" files (ruby libs, input files, etc)
+    # required to regenerate the data.
+    #
+    class FileCache
+      # Non-printable ASCII char indicates data should be Marshal'd
+      HINT = /[\000-\010\016-\037\177-\300]/
+
+      class << self
+        def lookup(cachedir, data={})
+          store[cachedir] ||= new(cachedir, data)
+        end
+
+        def dump(cachedir, hash)
+          FileUtils.mkdir(cachedir) unless File.exists?(cachedir)
+          FileUtils.touch(cachedir)
+
+          for key, data in hash
+            File.open(File.join(cachedir, key.to_s), 'wb') do |f|
+              if data.is_a?(String) and data[0,2] !~ HINT
+                # even Strings will be Marshal'd if the first two bytes contain non-ASCII
+                f.write data
+              else
+                Marshal.dump(data, f)
+              end
+            end
+          end
+
+          return hash
+        end
+
+        def load(cachedir, key)
+          File.open(File.join(cachedir, key.to_s)) do |io|
+            # detect Marshal'd data
+            if io.read(2) !~ HINT
+              io.rewind
+              io.read
+            else
+              io.rewind
+              Marshal.load(io)
+            end
+          end
+        end
+
+        # Creates cachedir (if missing) and destroys its contents
+        def clean(cachedir)
+          FileUtils.mkdir(cachedir) unless File.exists?(cachedir)
+          FileUtils.touch(cachedir)
+          FileUtils.rm(Dir["#{cachedir}/*"])
+        end
+
+        def store
+          @store ||= {}
+        end
+      end
+
+      # Destroys any existing cached data and write the given data to disk if data is not empty
+      def initialize(cachedir, data={})
+        @dir  = cachedir
+        @data = {}
+        replace(data) unless data.empty?
+      end
+
+      # Load +key+ from file system if needed
+      def [](key)
+        @data[key.to_s] ||= self.class.load(@dir, key)
+      end
+
+      # Writes through to file system
+      def []=(key, value)
+        @data[key.to_s] = value
+        self.class.dump(@dir, key.to_s => value)
+      end
+
+      # Writes through to file system
+      def update(hash)
+        hash.each do |key,value|
+          self[key] = value
+        end
+      end
+
+      def keys
+        Dir[@dir + '/*'].map{|e| File.basename(e) } | @data.keys
+      end
+
+      private
+
+      # Clears entire cache and replaces contents
+      def replace(data)
+        self.class.clean(@dir)
+        self.class.dump(@dir, data)
+
+        for key, value in data
+          # stringify keys
+          @data[key.to_s] = data
+        end
+      end
+    end
+
+    #
+    # Base class should define self.compiler_path and self.compile(tree, ...)
+    #
+    module ClassMethods
+      def cache_sources
+        [compiler_path, Parser.grammar_path, Parser.parser_path, Parser.nodes_path]
+      end
+
+      def stale?(source)
+        File.stale?(cache_path(source), source, *cache_sources)
+      end
+
+      # returns FileCache instance 
+      def cache(source, args={}, &block)
+        Parser.parser # load libraries
+        cachedir = cache_path(source)
+
+        if stale?(source)
+          begin
+            tree = Parser.cache(source)
+            data = compile(tree, args.update(:path => source), &block)
+            
+            # replaces old cached data with new data
+            FileCache.lookup(cachedir, data)
+          rescue Piggly::Parser::Failure
+            FileCache.clean(cachedir)
+            raise
+          end
+        else
+          FileCache.lookup(cachedir)
+        end
+      end
+    end
+
+  end
+end

data/lib/piggly/compiler/pretty.rb

@@ -0,0 +1,67 @@
+require File.join(File.dirname(__FILE__), *%w(.. reporter))
+
+module Piggly
+
+  #
+  # Produces HTML output to report coverage of tagged nodes in the tree
+  #
+  class PrettyCompiler
+    include Piggly::HtmlTag
+
+    def self.compile(path, profile)
+      new(profile).send(:compile, path)
+    end
+
+    def initialize(profile)
+      @profile = profile
+    end
+
+  private
+
+    def compile(path)
+      lines = File.read(path).count("\n") + 1
+
+      # recompile (should be cache hit) to identify tagged nodes
+      data = TraceCompiler.cache(path)
+      html = traverse(data['tree'])
+
+      return 'html'  => html,
+             'lines' => 1..lines,
+             'tags'  => data['tags']
+    end
+
+    def traverse(node, string='')
+      if node.terminal?
+        # terminals (leaves) are never tagged
+        if node.style
+          string << '<span class="' << node.style << '">' << e(node.text_value) << '</span>'
+        else
+          string << e(node.text_value)
+        end
+      else
+        # non-terminals never write their text_value
+        node.elements.each do |child|
+          if child.tagged?
+
+            # retreive the profiled tag
+            tag = @profile.by_id[child.tag_id]
+
+            if tag.complete?
+              string << '<span class="' << tag.style << '" id="T' << tag.id << '">'
+            else
+              string << '<span class="' << tag.style << '" id="T' << tag.id << '" title="' << tag.description << '">'
+            end
+
+            traverse(child, string)
+            string << '</span>'
+          else
+            traverse(child, string)
+          end
+        end
+      end
+
+      string
+    end
+
+  end
+end

data/lib/piggly/compiler/queue.rb

@@ -0,0 +1,46 @@
+module Piggly
+
+  #
+  # Executes blocks in parallel subprocesses
+  #
+  class Queue
+
+    def self.children=(value)
+      @children = value
+    end
+
+    # add a compile job to the queue
+    def self.queue(&block)
+      (@queue ||= []) << block
+    end
+
+    def self.child
+      queue { yield }
+    end
+
+    # start scheduler thread
+    def self.start
+      @active     = 0
+      @children ||= 1
+      @queue    ||= []
+
+      while block = @queue.shift
+        if @active >= @children
+          pid = Process.wait
+          @active -= 1
+        end
+
+        # enable enterprise ruby feature
+        GC.copy_on_write_friendly = true if GC.respond_to?(:copy_on_write_friendly=)
+
+        # use exit! to avoid auto-running any test suites
+        pid = Process.fork{ block.call; exit! 0 }
+
+        @active += 1
+      end
+
+      Process.waitall
+    end
+
+  end
+end