codefumes 0.1.0

data/History.txt

@@ -0,0 +1,4 @@
+== 0.0.1 2009-04-24
+
+* 1 major enhancement:
+  * Initial release

data/Manifest.txt

@@ -0,0 +1,24 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+config/website.yml.sample
+lib/codefumes.rb
+lib/codefumes/api.rb
+lib/codefumes/commit.rb
+lib/codefumes/config_file.rb
+lib/codefumes/payload.rb
+lib/codefumes/project.rb
+spec/codefumes/api_spec.rb
+spec/codefumes/commit_spec.rb
+spec/codefumes/config_file_spec.rb
+spec/codefumes/payload_spec.rb
+spec/codefumes/project_spec.rb
+spec/spec.opts
+spec/spec_helper.rb
+tasks/rspec.rake
+website/index.html
+website/index.txt
+website/javascripts/rounded_corners_lite.inc.js
+website/stylesheets/screen.css
+website/template.html.erb

data/README.txt

@@ -0,0 +1,102 @@
+= codefumes
+
+http://www.codefumes.com
+
+== DESCRIPTION:
+
+CodeFumes.com[http://codefumes.com] is a service intended to help people
+involved with software projects who are interested in tracking, sharing,
+and reviewing metrics/information about a project in relation to the
+commits of said project's repository.  The site supports a small set of
+'standard' metrics, but also provides a simple method of supplying
+and retrieving custom metrics, allowing users to gather any metric they
+are interested in tracking.
+
+The 'codefumes' gem is an implementation of the
+CodeFumes.com[http://codefumes.com] API. The intention of the
+gem is to simplify integration with CodeFumes.com for developers of
+other libraries & and applications.
+
+For an example of another library using the current features of this
+gem, you can refer to the
+'codefumes_harvester[http://codefumes.rubyforge.org/codefumes_harvester]'  gem.
+
+== FEATURES/PROBLEMS:
+
+=== Features
+* Saving, finding, marshalling, and destroying CodeFumes
+  projects
+* Associating and retrieving a repository's history of commits for a
+  CodeFumes 'project'
+* Simple interface for accessing both CodeFumes's 'standard' commit
+  metrics, as well as custom commit attributes; simplifying
+  integration with other tools & libraries users may be interested in
+  using.
+* Interfaces with the CodeFumes config file (used to track projects a
+  user has created on the site)
+
+=== Problems / Things to Note
+
+* CodeFumes 'projects' are repository-specific, not branch-specific.
+
+== SYNOPSIS:
+
+  require 'codefumes'
+
+  # Creating & finding a CodeFumes project
+  p = Project.save  # optionally providing a custom public key: :public_key => 'Abc3'
+  found_p = Project.find(p.public_key)
+  p.pulic_key # => 'Abc3'
+  p.api_uri   # => 'http://codefumes.com/api/v1/xml/Abc3'
+
+  # Commits
+  c = Commit.find(<commit identifier>)
+  c.identifier    # => git commit SHA (svn support coming soon)
+  c.short_message # => commit message
+
+  # Custom attributes associated with a commit
+  c.custom_attributes[:coverage] # => "80"
+
+
+  # Payloads, used to break up large HTTP requests
+  content = Payload.prepare(payload_content)
+  content.each {|chunk| chunk.save}
+
+== REQUIREMENTS:
+
+* httparty (0.4.3)
+
+== INSTALL:
+
+From RubyForge:
+
+  sudo gem install codefumes
+
+Or, from Github:
+
+  sudo gem install cosyn-codefumes
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 Cosyn Technologies, Inc.
+
+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/Rakefile

@@ -0,0 +1,31 @@
+%w[hoe rake rake/clean fileutils rubigen hoe].each { |f| require f }
+
+require File.dirname(__FILE__) + '/lib/codefumes'
+
+begin
+  require "hanna/rdoctask"
+rescue LoadError
+  require 'rake/rdoctask'
+end
+
+# Load in the harvester ane metric_fu gems if available so we can collect metrics
+begin
+  require "metric_fu"
+  require "codefumes_harvester"
+rescue LoadError
+end
+
+$hoe = Hoe.spec('codefumes') do |p|
+  p.developer('Cosyn Technologies', 'devs@codefumes.com')
+  p.summary = "API gem for the CodeFumes website"
+  p.extra_deps      = [
+     ['httparty','>= 0.4.3']
+  ]
+  p.extra_dev_deps = [
+    ['jscruggs-metric_fu', ">= 1.1.5"],
+  ]
+end
+
+Dir['tasks/**/*.rake'].each { |t| load t}
+
+task :default => [:spec]

data/config/website.yml.sample

@@ -0,0 +1,2 @@
+host: unknown@rubyforge.org
+remote_dir: /var/www/gforge-projects/codefumes

data/lib/codefumes.rb

@@ -0,0 +1,11 @@
+require 'httparty'
+
+require 'codefumes/api'
+require 'codefumes/project'
+require 'codefumes/config_file'
+require 'codefumes/payload'
+require 'codefumes/commit'
+
+module CodeFumes
+  VERSION = '0.1.0'
+end

data/lib/codefumes/api.rb

@@ -0,0 +1,19 @@
+module CodeFumes
+  class API
+    include HTTParty
+    
+    format :xml
+    
+    BASE_URIS = {
+      :production => 'http://www.codefumes.com/api/v1/xml',
+      :test => 'http://test.codefumes.com/api/v1/xml'
+    }
+    
+    def self.mode(mode)
+      base_uri(BASE_URIS[mode]) if BASE_URIS[mode]
+    end
+    
+    mode(:production)
+
+  end
+end

data/lib/codefumes/commit.rb

@@ -0,0 +1,144 @@
+module CodeFumes
+  # Similar to a revision control system, a Commit encompasses a set of
+  # changes to a codebase, who made them, when said changes were applied
+  # to the previous revision of codebase, et cetera.
+  #
+  # A Commit has a concept of 'standard attributes' which will always be
+  # present in a response from CodeFumes.com[http://codefumes.com], such
+  # as the +identifier+, +author+, and +commit_message+ (see the list of
+  # attributes for a comprehensive listing).  In addition to this, users
+  # are able to associate 'custom attributes' to a Commit, allowing
+  # users to link any number of attributes with a commit identifier and
+  # easily retrieve them later.
+  #
+  # One thing to note about Commit objects is that they are read-only.
+  # To associate metrics with a Commit object, a Payload object should
+  # be created and saved.  Refer to the Payload documentation for more
+  # information.
+  class Commit < CodeFumes::API
+    attr_reader :identifier, :author_name, :author_email, :committer_name,
+                :committer_email, :short_message, :message,:committed_at,
+                :authored_at, :uploaded_at, :api_uri, :parent_identifiers,
+                :line_additions, :line_deletions, :line_total,
+                :affected_file_count, :custom_attributes
+
+    # Instantiates a new Commit object
+    #
+    # Accepts a Hash of options, including:
+    # * identifier
+    # * author_email
+    # * author_name
+    # * committer_email
+    # * committer_name
+    # * short_message
+    # * message
+    # * committed_at
+    # * authored_at
+    # * uploaded_at
+    # * api_uri
+    # * parent_identifiers
+    # * line_additions
+    # * line_deletions
+    # * line_total
+    # * affected_file_count
+    # * custom_attributes
+    #
+    # +custom_attributes+ should be a Hash of attribute_name/value
+    # pairs associated with the commit.  All other attributes are
+    # expected to be String values, other than +committed_at+ and
+    # +authored_at+, which are expected to be DateTime objects.
+    # Technically speaking, you could pass anything you wanted into
+    # the fields, but when using with the CodeFumes API, the attribute
+    # values will be of the type String, DateTime, or Hash.
+    def initialize(options)
+      @identifier          = options["identifier"]
+      @author_email        = options["author_email"]
+      @author_name         = options["author_name"]
+      @committer_email     = options["committer_email"]
+      @committer_name      = options["committer_name"]
+      @short_message       = options["short_message"]
+      @message             = options["message"]
+      @committed_at        = options["committed_at"]
+      @authored_at         = options["authored_at"]
+      @uploaded_at         = options["uploaded_at"]
+      @api_uri             = options["api_uri"]
+      @parent_identifiers  = options["parent_identifiers"]
+      @line_additions      = options["line_additions"]
+      @line_deletions      = options["line_deletions"]
+      @line_total          = options["line_total"]
+      @affected_file_count = options["affected_file_count"]
+      @custom_attributes   = options["custom_attributes"] || {}
+      convert_custom_attributes_keys_to_symbols
+    end
+
+    # Returns the name of the author and the email associated
+    # with the commit in a string formatted as:
+    #   "Name [email_address]"
+    #   (ie: "John Doe [jdoe@example.com]")
+    def author
+      "#{author_name} [#{author_email}]"
+    end
+
+    # Returns the name of the committer and the email associated
+    # with the commit in a string formatted as:
+    #   "Name [email_address]"
+    #   (ie: "John Doe [jdoe@example.com]")
+    def committer
+      "#{committer_name} [#{committer_email}]"
+    end
+
+    # Returns the Commit object associated with the supplied identifier.
+    # Returns nil if the identifier is not found.
+    def self.find(identifier)
+      response = get("/commits/#{identifier}")
+      case response.code
+      when 200
+        return nil if response["commit"].empty?
+        new(response["commit"])
+      else
+        nil
+      end
+    end
+
+    # Returns a collection of commits associated with the specified
+    # Project public key.
+    def self.all(project_public_key)
+      response = get("/projects/#{project_public_key}/commits")
+      case response.code
+      when 200
+        return [] if response["commits"].empty? || response["commits"]["commit"].nil?
+        response["commits"]["commit"].map do |commit_data|
+          new(commit_data)
+        end
+      else
+        nil
+      end
+    end
+
+    # Returns the most recent commit associated with the specified
+    # Project public key.
+    def self.latest(project_public_key)
+      response = get("/projects/#{project_public_key}/commits/latest")
+      case response.code
+      when 200
+        new(response["commit"])
+      else
+        nil
+      end
+    end
+
+    # Returns the commit identifier of the most recent commit of with
+    # the specified Project public key.
+    def self.latest_identifier(project_public_key)
+      latest_commit = latest(project_public_key)
+      latest_commit.nil? ? nil : latest_commit.identifier
+    end
+
+    private
+      def convert_custom_attributes_keys_to_symbols
+        @custom_attributes = @custom_attributes.inject({}) do |results, key_and_value|
+          results.merge! key_and_value.first.to_sym => key_and_value.last
+        end
+      end
+  end
+end

data/lib/codefumes/config_file.rb

@@ -0,0 +1,85 @@
+module CodeFumes
+  # CodeFumes uses a global (per-user) config file to store relevant
+  # information around a user's use of the service.  Doing so addresses
+  # the following goals:
+  # * A defined location for all tools to utilize which contains URI's
+  #   and and keys for all projects a user has set up on
+  #   CodeFumes.com[http://codefumes.com], simplifying integration.
+  # * Associating (or disassociating) a project to (or from) a CodeFumes
+  #   project does not require any modifications to said project's
+  #   repository.
+  # * Simplified the implementation of 'user-less' projects on the
+  #   website.
+  #
+  # This class wraps up reading and writing this config file so other
+  # developers should not have to concern themselves with how to
+  # serialize & write the data of a project into the appropriate format,
+  # output file, et cetera.
+  class ConfigFile
+    DEFAULT_FILE_STRUCTURE = {}
+    DEFAULT_PATH = File.expand_path('~/.codefumes_config')
+
+    class << self
+      # Returns the path to the CodeFumes global (per-user) config file.
+      # The default path is '~/.codefumes_config'.
+      def path
+        @path || ENV['CODEFUMES_CONFIG_FILE'] || DEFAULT_PATH.dup
+      end
+
+      # Sets the path which should be used for storing the configuration
+      # CodeFumes.com data.
+      def path=(custom_path)
+        @path = custom_path.nil? ? path : File.expand_path(custom_path)
+      end
+
+      # Store the supplied project into the CodeFumes config file.
+      def save_project(project)
+        config = serialized
+        if config[:projects]
+          config[:projects].merge!(project.to_config)
+        else
+          config[:projects] = project.to_config
+        end
+        write(config)
+      end
+
+      # Remove the supplied project from the CodeFumes config file.
+      def delete_project(project)
+        config = serialized
+        config[:projects] && config[:projects].delete(project.public_key.to_sym)
+        write(config)
+      end
+
+      # Returns a Hash representation of the CodeFumes config file
+      def serialized
+        empty? ? DEFAULT_FILE_STRUCTURE.dup : loaded
+      end
+
+      # Returns a Hash representation of a specific project contained in
+      # the CodeFumes config file.
+      def options_for_project(public_key)
+        config = serialized
+        public_key && config[:projects] && config[:projects][public_key.to_sym] || {}
+      end
+
+      private
+        def write(serializable_object)
+          File.open(path, 'w') do |f|
+            f.puts YAML::dump(serializable_object)
+          end
+        end
+
+        def exists?
+          File.exists?(path)
+        end
+
+        def empty?
+          !(exists? && loaded)
+        end
+
+        def loaded
+          YAML::load_file(path)
+        end
+    end
+  end
+end

data/lib/codefumes/payload.rb

@@ -0,0 +1,103 @@
+module CodeFumes
+  # Payloads are intended to simplify sending up large amounts of
+  # content at one time.  For example, when sending up the entire
+  # history of a repository, making a POST request for each commit would
+  # require a very large number of requests.  Using a Payload object
+  # allows larger amounts of content to be saved at one time,
+  # significantly reducing the number of requests made.
+  class Payload < CodeFumes::API
+    PAYLOAD_CHARACTER_LIMIT = 4000 #:nodoc:
+
+    attr_reader :project_public_key, :project_private_key, :created_at
+
+    # Accepts +:public_key+, +:private_key+, and :content keys.
+    # +:content+ should also contain a key named +:commits+, with a list
+    # of commits and associated data.  An example would be:
+    #
+    #   {:public_key => "abC3", :private_key => "some-private-key",
+    #   :content => {:commits => [{:identifier => "commit_identifer",
+    #   :files_affected => 3, :any_metric_you_want => "value"}]}}
+    def initialize(options = {})
+      @project_public_key = options[:public_key]
+      @project_private_key = options[:private_key]
+      @content = options[:content]
+    end
+
+    # Saves instance to CodeFumes.com. After a successful save, the
+    # +created_at+ attribute will be populated with the timestamp the
+    # Payload was created.
+    #
+    # Returns +true+ if the Payload does not contain any content to be
+    # saved or the request was successful.
+    #
+    # Returns +false+ if the request failed.
+    def save
+      return true if empty_payload?
+      response = self.class.post("/projects/#{@project_public_key}/payloads", :query => {:payload => @content}, :basic_auth => {:username => @project_public_key, :password => @project_private_key})
+
+      case response.code
+      when 201
+        @created_at = response['payload']['created_at']
+        true
+      else
+        false
+      end
+    end
+
+    # +save+ requests are made with a standard POST request (not a
+    # multi-part POST), so the request size is limited by the
+    # application server.  The current configuration on CodeFumes.com
+    # limits requests to approximately 8,000 bytes (a little over).  In
+    # order to simplify dealing with these constraints, without
+    # requiring a multi-part POST request, +prepare+ can be used to
+    # "chunk" up the data into Payloads which do not exceed this limit.
+    #
+    # Returns collection of payload objects which fall into the
+    # constraints of a individual payload (ie: length of raw request,
+    # et cetera).
+    #--
+    # TODO: Clean up how the size of the request is constrained, this
+    # is pretty hackish right now (basically guesses how many
+    # characters would be added when HTTParty wraps the content in XML.
+    def self.prepare(data = {})
+      return [] if data.nil? || data.empty?
+      raw_payload = data.dup
+
+      public_key = raw_payload.delete(:public_key)
+      raise ArgumentError, "No public key provided" if public_key.nil?
+      
+      private_key = raw_payload.delete(:private_key)
+
+      if raw_payload[:content].nil? || raw_payload[:content][:commits].nil?
+        raise ArgumentError, "No commits key provided"
+      end
+
+      content = raw_payload[:content][:commits]
+      initial_chunks = {:on_deck => [], :prepared => []}
+
+      # TODO: Clean this up
+      chunked = content.inject(initial_chunks) do |chunks, new_commit|
+        if chunks[:on_deck].to_s.length + new_commit.to_s.length >= PAYLOAD_CHARACTER_LIMIT
+          chunks[:prepared] << chunks[:on_deck]
+          chunks[:on_deck] = [new_commit]
+        elsif new_commit == content.last
+          chunks[:on_deck] << new_commit
+          chunks[:prepared] << chunks[:on_deck]
+          chunks[:on_deck] = []
+        else
+          chunks[:on_deck] << new_commit
+        end
+        chunks
+      end
+
+      chunked[:prepared].map do |raw_content|
+        Payload.new(:public_key => public_key, :private_key => private_key, :content => {:commits => raw_content})
+      end
+    end
+
+    private
+      def empty_payload?
+        @content.empty? || @content[:commits].nil? || @content[:commits].blank?
+      end
+  end
+end