metior 0.1.1

data/.gitignore

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

data/.travis.yml

@@ -0,0 +1,7 @@
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - jruby
+  - rbx
+  - ree
+  - ruby-head

data/.yardopts

@@ -0,0 +1,4 @@
+--files Changelog.md,LICENSE
+--markup markdown
+--private
+--protected

data/Changelog.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## Version 0.1.1
+
+ **June 8<sup>th</sup>, 2011**
+
+ * Fixed gem dependencies
+
+ See the
+ [Git history](https://github.com/koraktor/metior/compare/0.1.0...0.1.1) for
+ version 0.1.1
+
+## Version 0.1.0
+
+ **June 8<sup>th</sup>, 2011**
+
+ * Support for Git and GitHub repositories
+ * Basic loading of commits, authors and committers
+ * Simple statistics
+
+ See the [Git history](https://github.com/koraktor/metior/commits/0.1.0) for
+ version 0.1.0

data/Gemfile

@@ -0,0 +1,21 @@
+source :rubygems
+
+gem 'bundler', '~> 1.0.14'
+
+group :git do
+  gem 'grit', '~> 2.4.1'
+end
+
+group :github do
+  gem 'octokit', '~> 0.6.3'
+end
+
+group :development do
+  gem 'rake', '~> 0.9.1'
+  gem 'yard', '~> 0.7.1'
+end
+
+group :test do
+  gem 'mocha', '~> 0.9.12'
+  gem 'shoulda', '~> 2.11.3'
+end

data/Gemfile.lock

@@ -0,0 +1,44 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    addressable (2.2.6)
+    diff-lcs (1.1.2)
+    faraday (0.6.1)
+      addressable (~> 2.2.4)
+      multipart-post (~> 1.1.0)
+      rack (< 2, >= 1.1.0)
+    faraday_middleware (0.6.3)
+      faraday (~> 0.6.0)
+    grit (2.4.1)
+      diff-lcs (~> 1.1)
+      mime-types (~> 1.15)
+    hashie (1.0.0)
+    mime-types (1.16)
+    mocha (0.9.12)
+    multi_json (1.0.2)
+    multipart-post (1.1.1)
+    octokit (0.6.3)
+      addressable (~> 2.2.4)
+      faraday (~> 0.6.0)
+      faraday_middleware (~> 0.6.0)
+      hashie (~> 1.0.0)
+      multi_json (~> 1.0.0)
+      rash (~> 0.3.0)
+    rack (1.2.2)
+    rake (0.9.1)
+    rash (0.3.0)
+      hashie (~> 1.0.0)
+    shoulda (2.11.3)
+    yard (0.7.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.14)
+  grit (~> 2.4.1)
+  mocha (~> 0.9.12)
+  octokit (~> 0.6.3)
+  rake (~> 0.9.1)
+  shoulda (~> 2.11.3)
+  yard (~> 0.7.1)

data/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.

data/README.md

@@ -0,0 +1,117 @@
+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.new '~/open-source/metior'
+    repo.commits 'development'         # Get all commits in development
+    repo.file_stats                    # Basic statistics about the files
+                                       # contained in a repository
+    repo.line_history                  # Quick access to lines added and
+                                       # removed in each commit
+    repo.significant_authors           # Get up to 3 of the most important
+                                       # authors
+    repo.significant_commits, 20       # Get up to 20 of the commits changing
+                                       # the most lines
+    repo.top_authors 'master', 5       # Get the top 5 authors in master
+
+### Get statistics about a set of commits
+
+    Metior::Commit.activity repo.commits
+    Metior::Commit.activity repo.authors[author_id].commits
+
+## Advanced usage
+
+### Specifying commit ranges
+
+Sometimes it's more useful to not analyze the whole history of a repository's
+branch. For example when analyzing the changes from one branch to another, or
+from the last released version to the latest code. In that case you will have
+to specify a commit range. Specifying a commit range works just like in Git:
+
+    'master..development'
+    'master'..'development'
+    'master..HEAD'
+    'master'..'HEAD'
+    'deadbeef..HEAD'
+
+Given that your currently checked out branch is `development` and `master`
+points to commit `deadbeef`, the above statements are equal. Please also note
+the different syntaxes: The first, third and fifth example are standards string
+which will be parsed by Metior. The second and fourth example are Ruby `Range`
+objects which can be used by Metior right away.
+
+## Requirements
+
+* Grit — a Ruby API for Git
+  * [Git](http://git-scm.com) >= 1.6
+* Octokit — a Ruby wrapper for the GitHub API
+
+## 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
+* Generation of reports in HTML or other formats
+* Support for creating graphs
+* Console and web application to accompany this API
+* More supported VCSs, like Subversion or Mercurial
+* 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.
+
+## About the name
+
+The latin word "metior" means "I measure". That's just what Metior does –
+measuring source code histories.
+
+## 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

data/Rakefile

@@ -0,0 +1,48 @@
+# -*- encoding: utf-8 -*-
+
+# 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/testtask'
+require 'rubygems/package_task'
+
+task :default => :test
+
+# Rake tasks for building the gem
+spec = Gem::Specification.load('metior.gemspec')
+Gem::PackageTask.new(spec) do |pkg|
+end
+
+# Rake task for running the test suite
+Rake::TestTask.new do |t|
+  t.libs << 'lib' << 'test'
+  t.test_files = FileList['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

data/lib/core_ext/object.rb

@@ -0,0 +1,25 @@
+# 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
+
+unless Object.method_defined? :singleton_class
+
+  # Provides the `singleton_class` method for Ruby implementations not
+  # supporting it
+  #
+  # @author Sebastian Staudt
+  class Object
+
+    # Returns the singleton class (also known as eigenclass) of this object
+    #
+    # @return [Class] The singleton class of this object
+    def singleton_class
+      class << self
+         self
+      end
+    end
+
+  end
+
+end

data/lib/metior.rb

@@ -0,0 +1,50 @@
+# 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 'bundler'
+
+require 'core_ext/object'
+require 'metior/git'
+require 'metior/github'
+require 'metior/version'
+
+# 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
+
+  # Creates a new repository for the given repository type and path
+  #
+  # @param [Symbol] type The type of the repository, e.g. `:git`
+  # @param [Array<Object>] options The options to use for creating the new
+  #        repository, e.g. a file system path
+  # @return [Repository] A VCS specific `Repository` instance
+  def self.repository(type, *options)
+    vcs(type)::Repository.new *options
+  end
+
+  # 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)
+    repo = repository type, 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

data/lib/metior/actor.rb

@@ -0,0 +1,85 @@
+# 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 [Fixnum] The lines of code that have been added by this actor
+    attr_reader :additions
+
+    # @return [Array<Commit>] The list of commits this actor has contributed to
+    #         the source code repository
+    attr_reader :commits
+
+    # @return [Fixnum] The lines of code that have been deleted by this actor
+    attr_reader :deletions
+
+    # @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)
+      raise NotImplementedError
+    end
+
+    # Creates a new actor linked to the given source code repository
+    #
+    # @param [Repository] repo The repository this actor belongs to
+    def initialize(repo)
+      @additions = 0
+      @commits   = []
+      @deletions = 0
+      @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)
+      @additions += commit.additions
+      @commits << commit
+      @deletions += commit.deletions
+    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
+
+    # Returns the total of changed lines in all commits of this actor
+    #
+    # @return [Fixnum] The total number of changed lines
+    def modifications
+      additions + deletions
+    end
+
+  end
+
+end