Initial commit

This includes basic support for Git repositories.

.gitignore

@@ -0,0 +1,4 @@
+.bundle/
+.yardoc/
+doc/
+pkg/

.yardopts

@@ -0,0 +1 @@
+--files Changelog.md,LICENSE

Changelog.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## `master` branch
+
+ * Basic stats support for Git repositories

Gemfile

@@ -0,0 +1,7 @@
+source :rubygems
+
+gem 'grit', '~> 2.4.0'
+
+group :development do
+  gem 'yard'
+end

Gemfile.lock

@@ -0,0 +1,16 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.2)
+    grit (2.4.1)
+      diff-lcs (~> 1.1)
+      mime-types (~> 1.15)
+    mime-types (1.16)
+    yard (0.6.5)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  grit (~> 2.4.0)
+  yard

LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2011, Sebastian Staudt
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+* Neither the name of the author nor the names of its contributors
+  may be used to endorse or promote products derived from this software
+  without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,76 @@
+Metior
+======
+
+Metior is a source code history analyzer API that provides various statistics
+about a source code repository and its change over time.
+
+Currently Metior provides basic support for Git repositories.
+
+If you're interested in Metior, feel free to join the discussion on Convore in
+[Metior's group](https://convore.com/metior).
+
+## Examples
+
+### One-liner for some basic statistics
+
+    Metior.simple_stats :git, '~/open-source/metior'
+
+### More fine-grained access to repository statistics
+
+    repo = Metior::Git::Repository '~/open-source/metior'
+    repo.commits 'development'         # Get all commits in development
+    repo.top_committers 'master', 5    # Get the top 5 committers in master
+
+## Requirements
+
+* Grit — a Ruby API for Git
+* [Git](http://git-scm.com) >= 1.6
+
+## Documentation
+
+The documentation of the Ruby API can be seen at [RubyDoc.info][1]. The API
+documentation of the current development version is also available [there][5].
+
+## Future plans
+
+* More statistics and analyses
+* More supported VCSs, like Subversion or Mercurial
+* Support for creating graphs
+* Console and web application to accompany this API
+* Code analysis to show programming languages, effective lines of code, etc.
+
+## Contribute
+
+Metior is a open-source project. Therefore you are free to help improving it.
+There are several ways of contributing to Metior's development:
+
+* Build apps using it and spread the word.
+* Report problems and request features using the [issue tracker][2].
+* Write patches yourself to fix bugs and implement new functionality.
+* Create a Metior fork on [GitHub][1] and start hacking. Extra points for using
+  Metior pull requests and feature branches.
+
+## License
+
+This code is free software; you can redistribute it and/or modify it under the
+terms of the new BSD License. A copy of this license can be found in the
+LICENSE file.
+
+## Credits
+
+* Sebastian Staudt – koraktor(at)gmail.com
+
+## See Also
+
+* [API documentation][1]
+* [Metior's homepage][2]
+* [GitHub project page][3]
+* [GitHub issue tracker][4]
+
+Follow Metior on Twitter [@metiorstats](http://twitter.com/metiorstats).
+
+ [1]: http://rubydoc.info/gems/metior/frames
+ [2]: http://koraktor.de/metior
+ [3]: http://github.com/koraktor/metior
+ [4]: http://github.com/koraktor/metior/issues
+ [5]: http://rubydoc.info/github/koraktor/metior/master/frames

Rakefile

@@ -0,0 +1,46 @@
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
+#
+# Copyright (c) 2011, Sebastian Staudt
+
+require 'rake/gempackagetask'
+require 'rake/testtask'
+
+task :default => :test
+
+# Rake tasks for building the gem
+spec = Gem::Specification.load('metior.gemspec')
+Rake::GemPackageTask.new(spec) do |pkg|
+end
+
+# Rake task for running the test suite
+Rake::TestTask.new do |t|
+  t.libs << 'lib' << 'test'
+  t.pattern = 'test/**/test_*.rb'
+  t.verbose = true
+end
+
+# Check if YARD is installed
+begin
+  require 'yard'
+
+  # Create a rake task +:doc+ to build the documentation using YARD
+  YARD::Rake::YardocTask.new do |yardoc|
+    yardoc.name    = 'doc'
+    yardoc.files   = [ 'lib/**/*.rb', 'LICENSE', 'README.md' ]
+    yardoc.options = [ '--private', '--title', 'Metior — API Documentation' ]
+  end
+rescue LoadError
+  # Create a rake task +:doc+ to show that YARD is not installed
+  desc 'Generate YARD Documentation (not available)'
+  task :doc do
+    $stderr.puts 'You need YARD to build the documentation. Install it using `gem install yard`.'
+  end
+end
+
+# Task for cleaning documentation and package directories
+desc 'Clean documentation and package directories'
+task :clean do
+  FileUtils.rm_rf 'doc'
+  FileUtils.rm_rf 'pkg'
+end

lib/metior.rb

@@ -0,0 +1,40 @@
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
+#
+# Copyright (c) 2011, Sebastian Staudt
+
+libdir = File.dirname(__FILE__)
+$LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
+
+require 'rubygems'
+require 'bundler'
+Bundler.setup :default
+
+require 'metior/git'
+
+# Metior is a source code history analyzer that provides various statistics
+# about a source code repository and its change over time.
+#
+# @author Sebastian Staudt
+module Metior
+
+  # Calculates simplistic stats for the given repository and branch
+  #
+  # @param [Symbol] type The type of the repository, e.g. +:git+
+  # @param [String] path The file system path of the repository
+  # @param [String] branch The repository's 'branch to analyze. +nil+ will use
+  #        the VCS's default branch
+  # @return [Hash] The calculated stats for the given repository and branch
+  def self.simple_stats(type, path, branch = nil)
+    vcs = vcs(type)
+    repo = vcs::Repository.new path
+    branch ||= vcs::DEFAULT_BRANCH
+
+    {
+      :authors        => repo.authors(branch).values,
+      :commit_count   => repo.commits(branch).size,
+      :top_committers => repo.top_contributors(branch, 3)
+    }
+  end
+
+end

lib/metior/actor.rb

@@ -0,0 +1,67 @@
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
+#
+# Copyright (c) 2011, Sebastian Staudt
+
+module Metior
+
+  # Represents an actor in a source code repository
+  #
+  # Depending on the repository's VCS this may be for example an author or
+  # committer.
+  #
+  # @abstract It has to be subclassed to implement a actor representation for a
+  #           specific VCS.
+  # @author Sebastian Staudt
+  class Actor
+
+    # @return [Array<Commit>] The list of commits this actor has contributed to
+    #         the source code repository
+    attr_reader :commits
+
+    # @return [String] The full name of the actor
+    attr_reader :name
+
+    # @return [String] A unqiue identifier for the actor
+    attr_reader :id
+
+    # Extracts a unique identifier from the given, VCS dependent actor object
+    #
+    # @abstract Different VCSs use different identifiers for users, so this
+    #           method must be implemented for each supported VCS.
+    # @param [Object] actor The actor object retrieved from the VCS
+    # @return [String] A unique identifier for the given actor
+    def self.id_for(actor)
+    end
+
+    # Creates a new actor linked to the given source code repository
+    #
+    # @param [Repository] repo The repository this actor belongs to
+    def initialize(repo)
+      @commits = []
+      @repo    = repo
+    end
+
+    # Adds a new commit to the list of commits this actor has contributed to
+    # the analyzed source code repository
+    #
+    # @param [Commit] commit The commit to add to the list
+    def add_commit(commit)
+      @commits << commit
+    end
+
+    # Creates a string representation for this actor without recursing into
+    # commit and repository details
+    #
+    # @return [String] A minimal string representation for this actor
+    def inspect
+      '<#%s:0x%x: @commits=%d @id="%s" @name="%s" @repo=<#%s:0x%x ...>>' %
+        [
+          self.class.name, __id__ * 2, @commits.size, @id, @name,
+          @repo.class.name, @repo.__id__ * 2
+        ]
+    end
+
+  end
+
+end

lib/metior/commit.rb

@@ -0,0 +1,51 @@
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
+#
+# Copyright (c) 2011, Sebastian Staudt
+
+
+module Metior
+
+  # This class represents a commit in a source code repository
+  #
+  # Although not all VCSs distinguish authors from committers this
+  # implementation forces a differentiation between the both.
+  #
+  # @abstract It has to be subclassed to implement a commit representation for
+  #           a specific VCS.
+  # @author Sebastian Staudt
+  class Commit
+
+    # @return [Actor] This commit's author
+    attr_reader :author
+
+    # @return [Time] The date this commit has been authored
+    attr_reader :authored_date
+
+    # @return [String] The branch this commit belongs to
+    attr_reader :branch
+
+    # @return [Time] The date this commit has been committed
+    attr_reader :committed_date
+
+    # @return [Actor] This commit's committer
+    attr_reader :committer
+
+    # @return [String] The commit message of this commit
+    attr_reader :message
+
+    # @return [Repository] The repository this commit belongs to
+    attr_reader :repo
+
+    # Creates a new commit instance linked to the given repository and branch
+    #
+    # @param [Repository] repo The repository this commit belongs to
+    # @param [String] branch The branch this commit belongs to
+    def initialize(repo, branch)
+      @repo   = repo
+      @branch = branch
+    end
+
+  end
+
+end

lib/metior/git.rb

@@ -0,0 +1,29 @@
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
+#
+# Copyright (c) 2011, Sebastian Staudt
+
+require 'metior/vcs'
+
+module Metior
+
+  # The Metior implementation for Git
+  #
+  # @author Sebastian Staudt
+  module Git
+
+    # Git will be registered as +:git+
+    NAME = :git
+
+    include Metior::VCS
+
+    # Git's default branch is _master_
+    DEFAULT_BRANCH = 'master'
+
+  end
+
+end
+
+require 'metior/git/actor'
+require 'metior/git/commit'
+require 'metior/git/repository'