augment 1.0.0

data/History.txt

@@ -0,0 +1,5 @@
+== 1.0.0 / 2007-10-27
+
+* Works with a minimal set of backends and frontends
+  * Birthday!
+

data/Manifest.txt

@@ -0,0 +1,27 @@
+COPYING
+TODO
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/augment
+lib/augment.rb
+lib/layer.rb
+lib/flet.rb
+lib/backends/backend.rb
+lib/backends/coloring_backend.rb
+lib/backends/test_unit_backend.rb
+lib/frontends/frontend.rb
+lib/frontends/ansi_color_frontend.rb
+lib/frontends/html_frontend.rb
+lib/frontends/augment.el
+spec/ansi_frontend_spec.rb
+spec/color_backend_spec.rb
+spec/emacs-frontend-test.el
+spec/html_frontend_spec.rb
+spec/spec_helper.rb
+spec/test_backend_spec.rb
+spec/fixtures/augment-output.txt
+spec/fixtures/layers.json
+spec/fixtures/drinks/lib/drink.rb
+spec/fixtures/drinks/test/test_drink.rb

data/README.txt

@@ -0,0 +1,103 @@
+augment
+    by Phil Hagelberg (c) 2007
+    http://augment.rubyforge.org
+
+== Description
+  
+Augment is a framework for gathering metadata from code and displaying
+it. This metadata would include test failures, test coverage levels,
+complexity metrics, and others. Display frontends will be pluggable so
+as to interface with many editors.
+
+== Usage
+
+The +augment+ executable gathers metadata in the form of layers for a
+given file via a backend. Some backends gather data for a file other
+than the original one passed in. (The test backend will store data for
+the test if you pass in the implementation.)
+
+Example:
+
+$ augment test lib/foo.rb # will store metadata for test/test_foo.rb
+
+The various frontends have their own executables that provide access
+to the layer metadata once it's stored. The simplest frontend is
++augment_color+ which outputs the layers via ANSI color codes to the
+shell:
+
+$ augment_color test/test_foo.rb
+
+Most other frontends are editor-specific.
+
+== Design
+
+Augment is designed to be generalized; if you want to collect
+different kinds of data you can just write a new backend. If you want
+to display the data in an unsupported editor or output format, you can
+write a new frontend.
+
+=== Backends
+
+Each backend takes a filename or glob and outputs the metadata about
+that file into the .augment directory, created in the project root.
+Metadata is stored as layer information in JSON. Each backend also
+needs an initiator command to kick off the process that gathers the
+metadata, with the exception of auto-initiating backends like autotest.
+
+=== Frontends
+
+Most frontends are implemented within an editor or IDE. They watch
+the .augment directory for changes and apply them to the open buffers
+when they happen.  The user can choose what augmentations he wants
+displayed either globally or on a per-file basis. He can also control
+when backend initiators should be started, though usually these will
+be kicked off automatically upon saving a file.
+
+=== Layers
+
+A layer consists of a single piece of metadata about a file. This is
+expressed in terms of the range it applies to in the file, its color,
+and the message associated with it.
+
+== Support
+
+Backends:
+
+* Tests (miniunit)
+* Rspec (planned)
+* Heckle (planned)
+* Rcov (planned)
+* Flog (planned)
+* Performance (planned)
+
+Frontends:
+
+* ANSI color codes (for shells)
+* Emacs (planned)
+* Vim (planned)
+* Textmate (planned)
+
+== Issues
+  
+* Not really, um, written yet.
+
+== License
+
+This is free software; you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free
+Software Foundation; either version 3, or (at your option) any later
+version.
+
+This file is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this software; see the file COPYING. If not, write to the
+Free Software Foundation at this address:
+
+  Free Software Foundation
+  51 Franklin Street, Fifth Floor
+  Boston, MA 02110-1301
+  USA

data/Rakefile

@@ -0,0 +1,26 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require 'spec/rake/spectask'
+require './lib/augment.rb'
+
+Hoe.new('augment', Augment::VERSION) do |p|
+  p.rubyforge_name = 'augment'
+  p.author = 'Phil Hagelberg'
+  p.email = 'technomancy@gmail.com'
+  p.summary = 'Augment is a system for collecting and displaying code metadata.'
+  p.description = p.paragraphs_of('README.txt', 2..5).join("\n\n")
+  p.url = p.paragraphs_of('README.txt', 0).first.split(/\n/)[1..-1]
+  p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
+  p.extra_deps << ['miniunit', '>= 1.0.1']
+  p.extra_deps << ['json', '>= 1.1.1']
+end
+
+task :publish_html do
+  system("scp -r html/* technomancy@rubyforge.org:/var/www/gforge-projects/augment/")
+end
+
+Spec::Rake::SpecTask.new
+
+# vim: syntax=Ruby

data/TODO

@@ -0,0 +1,5 @@
+= Backends
+== test/unit
+* Discover char range from exception
+
+* Report rubyforge bug when doing "rubyforge config" on project rinari

data/bin/augment

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+$LOAD_PATH << File.dirname(__FILE__) + '/../lib'
+
+require 'augment'
+
+if ARGV.first == '--interactive'
+  Augment.interactive
+  exit 0
+elsif ARGV.size != 2
+  puts "Usage: augment BACKEND/FRONTEND FILE"
+  puts "   or: augment --interactive"
+  puts "Output or store metadata regarding code."
+  exit 1
+end
+
+Augment.new Augment::BACKENDS[ARGV[0]] || Augment::FRONTENDS[ARGV[0]], ARGV[1]

data/lib/augment.rb

@@ -0,0 +1,41 @@
+$LOAD_PATH << File.dirname(__FILE__)
+$LOAD_PATH << File.dirname(__FILE__) + '/backends'
+$LOAD_PATH << File.dirname(__FILE__) + '/frontends'
+
+require 'rubygems'
+
+require 'layer'
+require 'flet'
+require 'backend'
+require 'frontend'
+
+class Augment
+  VERSION = '1.0.0'
+  BACKENDS = {}
+  FRONTENDS = {}
+  
+  def initialize(action, file)
+    raise "No backend or frontend with that name." if action.nil?
+    action.run(file)
+  end
+
+  class << self
+    def interactive(backend_names = 'test')
+      while true
+        begin
+          filename = STDIN.gets.chomp
+          backend_names.each { |backend| BACKENDS[backend].run(filename) }
+          puts "{\"#{filename}\" : #{File.read(augment_path(filename))} }"
+        rescue
+          puts "Error augmenting #{filename}."
+        end
+      end
+    end
+    
+    def augment_path(original)
+      "#{File.dirname(File.expand_path(original))}/.augment/#{File.basename(original)}"
+    end
+  end
+end
+
+Dir.glob(File.dirname(__FILE__) + '/*ends/*rb').each { |b| require b[0 .. -4] }

data/lib/backends/backend.rb

@@ -0,0 +1,14 @@
+require 'fileutils'
+
+class Backend
+  class << self
+    def write_layers
+      @layers.each do |file, layers|
+        FileUtils.mkpath(File.dirname(file) + '/.augment')
+        File.open(Augment.augment_path(file), 'w') do |f|
+          f.puts "[#{layers.map{ |l| l.to_json }.join(", \n")}]"
+        end
+      end
+    end
+  end
+end

data/lib/backends/coloring_backend.rb

@@ -0,0 +1,25 @@
+class ColoringBackend < Backend
+  COLORS = ['white', 'red', 'green', 'blue', 'black']
+  
+  class << self
+    attr_reader :layers
+    
+    def run(file)
+      @layers = {}
+      text = File.read(file)
+
+      COLORS.each do |color|
+        offset = 0
+        while occurance = text.index(color, offset) do
+          (@layers[file] ||= []) << Layer.new((occurance ... occurance + color.length),
+                                              color, "Found a #{color}", self)
+          offset += (occurance + 1)
+        end
+      end
+      
+      write_layers
+    end
+  end
+end
+
+Augment::BACKENDS['color'] = ColoringBackend

data/lib/backends/test_unit_backend.rb

@@ -0,0 +1,56 @@
+Object.flet(:at_exit => lambda {}) do
+  # keep miniunit's at_exit block from running
+  gem 'miniunit', ">= 1.0.1"
+  require 'test/unit'
+end
+
+module Test
+  def Unit.puke(*args) # pass on failure info
+    TestUnitBackend.record_failure(*args)
+  end
+
+  def Unit.puts(*args); end # muffle test output
+end
+
+class TestUnitBackend < Backend
+  class << self
+    def run(file)
+      @file = file
+      @layers = {}
+
+      load(find_test_for(file))
+      # this will call record_failure as needed
+      with_no_output { Test::Unit.autotest }
+      write_layers
+    end
+
+    def record_failure(klass, method, exception)
+      # FIXME: errors here could actually occur in impl rather than test file
+      (@layers[@file] ||= []) << Layer.from_failure(@file, klass, method, exception)
+    end
+
+    def find_test_for(file)
+      # TODO: return test for implementation if possible
+      file
+    end
+
+    def with_no_output
+      old_stdout = $stdout.clone
+      $stdout.reopen(File.new('/dev/null','w'))
+      yield
+      $stdout.reopen(old_stdout)
+    end
+  end
+end
+
+def Layer.from_failure(file, klass, method, exception)
+  color = Test::Assertion === exception ? 'red' : 'yellow'
+
+  trace = exception.backtrace.detect { |e| e =~ /test_drink/ }
+  line = trace.match(/:(\d*):/)[1]
+
+  range = Layer.line_to_char_range(file, line.to_i)
+  Layer.new(range, color, exception.message, TestUnitBackend)
+end
+
+Augment::BACKENDS['test'] = TestUnitBackend

data/lib/flet.rb

@@ -0,0 +1,26 @@
+def Object.flet(bindings, &block)
+  old_methods = {}
+
+  bindings.each do |the_method, body|
+    old_methods[the_method] = method(the_method)
+    define_method(the_method, body)
+  end
+  
+  begin
+    block.call
+  ensure
+    bindings.each do |the_method, body|
+      define_method(the_method) { |*args| old_methods[the_method].call(*args) }
+    end
+  end
+end
+
+if $0 == __FILE__
+  puts "foo" # should output "foo"
+  
+  Object.flet(:puts => lambda { |str| print "#{str.reverse}\n" }) do
+    puts "foo" # should output "oof"
+  end
+
+  puts "foo" # should output "foo"
+end

data/lib/frontends/ansi_color_frontend.rb

@@ -0,0 +1,38 @@
+class String
+  COLOR_LOOKUP = {'black' => 30,
+      'red' => 31,
+      'green' => 32,
+      'yellow' => 33,
+      'blue' => 34,
+      'magenta' => 35,
+      'cyan' => 36,
+      'white' => 37,
+    'default' => 38 }
+  
+  def colorize(color_code)
+    "\e[#{String.lookup_color_code(color_code)}m#{self}\e[0m"
+  end
+
+  def colorize_range(range, color)
+    "#{self[0 ... range.begin]}#{self[range].colorize(color)}#{self[range.end .. -1]}"
+  end
+  
+  def self.lookup_color_code(color, foreground = true)
+    return color if color.is_a? Fixnum
+    COLOR_LOOKUP[color.downcase]
+  end
+end
+
+class AnsiColorFrontend < Frontend
+  class << self
+    def run(file)
+      puts super(file)
+    end
+    
+    def process_layer(text, layer)
+      text.colorize_range(layer['range'], layer['color'])
+    end
+  end
+end
+
+Augment::FRONTENDS['ansi'] = AnsiColorFrontend

data/lib/frontends/augment.el

@@ -0,0 +1,148 @@
+;;; augment.el --- Display metadata about code
+
+;; Copyright (C) 2007 Phil Hagelberg
+
+;; Author: Phil Hagelberg <technomancy@gmail.com>
+;; Created: 16 Oct 2007
+;; Version: 0.1
+;; Keywords: augment testing metadata
+
+;; This file is NOT part of GNU Emacs.
+
+;; This is free software; you can redistribute it and/or modify it under
+;; the terms of the GNU General Public License as published by the Free
+;; Software Foundation; either version 3, or (at your option) any later
+;; version.
+
+;; This file is distributed in the hope that it will be useful, but
+;; WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+;; General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with Emacs; see the file COPYING, or type `C-h C-c'. If not,
+;; write to the Free Software Foundation at this address:
+
+;;   Free Software Foundation
+;;   51 Franklin Street, Fifth Floor
+;;   Boston, MA 02110-1301
+;;   USA
+
+;;; Commentary:
+
+;; augment.el is a frontend for augment, a system for gathering and
+;; displaying metadata about code. It's a minor mode for displaying
+;; data that's been gathered and for initiating new augmentations.
+
+;; Tests are present in spec/emacs-frontend-test.el
+
+;;; Installation:
+
+;; Put this file on your load-path and add "(require 'augment)" to
+;; your .emacs file.
+
+;;; Todo:
+
+;; * Support overlapping layers
+
+;;; Code:
+
+(require 'cl)
+(require 'json) ;; See hober's http://edward.oconnor.cx/2006/03/json.el
+
+(defstruct layer begin end color message backend)
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+(defun augment-layer-from-plist (plist)
+  "Make a layers struct from a plist."
+  (make-layer :begin (string-to-number (first (split-string (getf plist :range) "\\.")))
+	      :end (string-to-number (cadddr (split-string (getf plist :range) "\\.")))
+	      :color (getf plist :color)
+	      :message (getf plist :message)))
+
+(defun augment-render-layer (layer)
+  "Create an overlay for a layer." ;; needs to be reimplemented for xemacs
+  (overlay-put (make-overlay (layer-begin layer) (layer-end layer))
+	       'face (layer-face layer)))
+
+(defun layer-face (layer)
+  ;; could do some kind of transformation here for color themes.
+  (cons 'background-color (layer-color layer)))
+
+(defun augment-file-path (file)
+  (concat
+   (file-name-directory file) ".augment/"
+   (file-name-nondirectory file)))
+
+(defun augment-message-at-point (&optional point)
+  (interactive)
+  ;; find the first layer that the point is between begin and end
+  (layer-message (find (or point (point)) layers :test
+		       (lambda (p l) (and (> p (layer-begin l))
+				     (< p (layer-end l)))))))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+(define-minor-mode augment-mode
+  "Major mode for showing code metadata.
+
+\\{augment-mode-map}"
+
+  :keymap (setq augment-mode-map (make-sparse-keymap))
+
+  (define-key augment-mode-map (kbd "C-c C-s") 'augment-initiate)
+  (define-key augment-mode-map (kbd "C-c C-k") 'augment-clear)
+  (define-key augment-mode-map (kbd "C-c C-i") 'augment-message-at-point)
+  
+  (make-local-variable 'layers)
+
+  (make-local-variable 'after-save-hook)
+  (add-hook 'after-save-hook 'augment-initiate)
+
+  (augment-initiate (buffer-file-name)))
+
+(defun augment-initiate (&optional file)
+  (interactive)
+  (setq layers nil)
+  (augment-clear)
+  (augment-start-process)
+  (process-send-string "augment" (concat (or file (buffer-file-name)) "\n")))
+
+(defun augment-start-process ()
+  (unless (get-process "augment") ;; only one should be running at a time
+    (set-process-filter
+     (start-process "augment" "*augment-out*"
+		    "augment" "--interactive")
+     'augment-filter)))
+
+(defun augment-filter (process output)
+  (if (string-match "^Error augmenting \\(.*\\)\\." output)
+      (error "Error augmenting %s." (match-string 1 output))
+    ;; layers need to be cached in local var for messages
+    (let* ((json-object-type 'plist)
+	   (json-array-type 'list)
+	   (all-layers (json-read-from-string output)))
+      (while all-layers
+	;; gotta remove the colon from the plisted filename
+	(let ((filename (substring (symbol-name (pop all-layers)) 1 nil))
+	      (layer-plists (pop all-layers)))
+	  (with-current-buffer (file-name-nondirectory filename)
+	    (setq layers (mapcar #'augment-layer-from-plist layer-plists))
+	    (augment-buffer layers)))))))
+
+(defun augment-buffer (layers)
+  (dolist (layer layers)
+    (augment-render-layer layer)))
+
+(defun augment-clear ()
+  (interactive)
+  (remove-overlays))
+
+(defun augment-reset ()
+  (interactive)
+  (kill-process "augment")
+  (augment-clear))
+
+(provide 'augment)
+;;; augment.el ends here