metior 0.1.4 → 0.2.0

data/.travis.yml

@@ -1,7 +1,9 @@
 rvm:
   - 1.8.7
   - 1.9.2
+  - 1.9.3
   - jruby
   - rbx
+  - rbx-2.0
   - ree
   - ruby-head

data/.yardopts

@@ -1,3 +1,4 @@
+lib/**/*.rb reports/**/*.rb
 --files Changelog.md,LICENSE
 --markup markdown
 --private

data/Changelog.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## Version 0.2.0
+
+ * Initial support for HTML reports
+ * Improved caching
+ * Collections can be used to easily query information
+ * Lazy load file and line stats for Git
+ * Lots of bugfixes
+
+ See the
+ [Git history](https://github.com/koraktor/metior/compare/0.1.4...0.2.0) for
+ version 0.2.0
+
+## Version 0.1.4
+
+ **June 16<sup>th</th>, 2011**
+
+ * Removed Bundler as a dependency loader
+ * Fixed GitHub::Commit not requiring 'time'
+
+ See the
+ [Git history](https://github.com/koraktor/metior/compare/0.1.3...0.1.4) for
+ version 0.1.4
+
 ## Version 0.1.3
 
  **June 13<sup>th</sup>, 2011**

data/Gemfile

@@ -1,19 +1,3 @@
 source :rubygems
 
-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
+gemspec

data/Gemfile.lock

@@ -1,43 +1,50 @@
+PATH
+  remote: .
+  specs:
+    metior (0.2.0)
+      grit (~> 2.4.1)
+      hashery (~> 1.4.0)
+      mustache (~> 0.99.4)
+      octokit (~> 0.6.4)
+
 GEM
   remote: http://rubygems.org/
   specs:
     addressable (2.2.6)
     diff-lcs (1.1.2)
-    faraday (0.6.1)
-      addressable (~> 2.2.4)
+    faraday (0.7.4)
+      addressable (~> 2.2.6)
       multipart-post (~> 1.1.0)
       rack (< 2, >= 1.1.0)
-    faraday_middleware (0.6.3)
-      faraday (~> 0.6.0)
+    faraday_middleware (0.7.0)
+      faraday (~> 0.7.3)
     grit (2.4.1)
       diff-lcs (~> 1.1)
       mime-types (~> 1.15)
+    hashery (1.4.0)
     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)
+    multi_json (1.0.3)
+    multipart-post (1.1.3)
+    mustache (0.99.4)
+    octokit (0.6.4)
+      addressable (~> 2.2.6)
+      faraday (~> 0.7.3)
+      faraday_middleware (~> 0.7.0.rc1)
       hashie (~> 1.0.0)
+      multi_json (~> 1.0.2)
+    rack (1.3.2)
+    rake (0.9.2)
     shoulda (2.11.3)
-    yard (0.7.1)
+    yard (0.7.2)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  grit (~> 2.4.1)
+  metior!
   mocha (~> 0.9.12)
-  octokit (~> 0.6.3)
-  rake (~> 0.9.1)
+  rake (~> 0.9.2)
   shoulda (~> 2.11.3)
-  yard (~> 0.7.1)
+  yard (~> 0.7.2)

data/README.md

@@ -4,61 +4,103 @@ 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.
+Currently Metior provides support for Git and GitHub repositories.
 
 If you're interested in Metior, feel free to join the discussion on Convore in
 [Metior's group](https://convore.com/metior).
 
-## Examples
+## Reports
+
+The most straightforward use of Metior is probably generating an out-of-the-box
+report that analyzes a repository and gives a user-friendly output of the
+gathered data.
+
+    Metior.report :git, '~/open-source/metior', './reports/metior'
+    Metior.report :github, 'koraktor/metior', './reports/metior'
+
+## API Examples
+
+If you want more sophisticated access to the available data, you can use the
+low-level API that provides stats for repositories and their individual commits
+and actors.
 
 ### One-liner for some basic statistics
 
     Metior.simple_stats :git, '~/open-source/metior'
-    Metior.simple_stats :github, 'koraktor', 'metior'
+    Metior.simple_stats :github, 'koraktor/metior'
 
 ### Create a repository object for different VCSs
 
-    repo = Metior::Git::Repository.new '~/open-source/metior'
-    repo = Metior::GitHub::Repository.new 'koraktor', 'metior'
+    repo = Metior.repository :git, '~/open-source/metior'
+    repo = Metior.repository :github, 'koraktor/metior'
 
 ### More fine-grained access to repository statistics
 
-    repo.commits 'development'         # Get all commits in development
+    repo.commits 'development'         # Get all commits in branch 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
+    repo.significant_commits           # Get up to 3 of the commits changing
                                        # the most lines
-    repo.top_authors 'master', 5       # Get the top 5 authors in master
+    repo.authors('master').top 5       # Get the top 5 authors in master
+
+### Query a collection of commits
+
+    repo.commits.activity
+    repo.commits.after '05/29/2010'
+    repo.commits.additions
+    repo.commits.authors
+    repo.commits.before '05/29/2010'
+    repo.commits.by 'koraktor'
+    repo.commits.changing 'lib/metior.rb'
+    repo.commits.deletions
+    repo.commits.modifications
+    repo.commits.most_significant 10
+    repo.commits.with_impact 100
+
+See documentation of {Metior::CommitCollection}
 
-### Get statistics about a set of commits
+### Query a collection of actors
 
-    Metior::Commit.activity repo.commits
-    Metior::Commit.activity repo.authors[author_id].commits
+    repo.authors.authored_commits
+    repo.authors.comitted_commits
+    repo.authors.most_significant 10
+    repo.authors.top 10
+
+See documentation of {Metior::ActorCollection}
 
 ## Advanced usage
 
+### Chain collection querys
+
+Querys on a collection of commits or actors can be easily chained to achieve
+complex filters on the available data.
+
+    repo.commits.by('koraktor').after('05/29/2010').with_impact 100
+    repo.authors.top(10).commits.changing 'lib/metior.rb'
+
 ### Specifying commit ranges
 
+Usually, when Metior queries a repository for its commits and authors it will
+use the default branch of the VCS, e.g. `master` for Git.
+
 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'
+    'master'..'development'
 
 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.
+the different syntaxes: The first two example are standard strings which
+will be parsed by Metior. The other one is a Ruby `Range` object which can be
+used by Metior right away.
 
 ## Requirements
 
@@ -73,8 +115,8 @@ 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
+* Provide more reports
+* Generation of reports in formats other than HTML
 * Support for creating graphs
 * Console and web application to accompany this API
 * More supported VCSs, like Subversion or Mercurial
@@ -89,7 +131,7 @@ There are several ways of contributing to Metior's development:
 * 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.
+  feature branches and GitHub's pull requests.
 
 ## About the name
 
@@ -105,6 +147,8 @@ LICENSE file.
 ## Credits
 
 * Sebastian Staudt – koraktor(at)gmail.com
+* Alex Manelis – amanelis(at)gmail.com
+* Michael Klishin – michaelklishin(at)me.com
 
 ## See Also
 
@@ -112,6 +156,7 @@ LICENSE file.
 * [Metior's homepage][2]
 * [GitHub project page][3]
 * [GitHub issue tracker][4]
+* [Continuous Integration at Travis CI][6]
 
 Follow Metior on Twitter [@metiorstats](http://twitter.com/metiorstats).
 
@@ -120,3 +165,4 @@ Follow Metior on Twitter [@metiorstats](http://twitter.com/metiorstats).
  [3]: http://github.com/koraktor/metior
  [4]: http://github.com/koraktor/metior/issues
  [5]: http://rubydoc.info/github/koraktor/metior/master/frames
+ [6]: http://travis-ci.org/koraktor/metior

data/lib/metior.rb

@@ -6,6 +6,7 @@
 require 'core_ext/object'
 require 'metior/git'
 require 'metior/github'
+require 'metior/report'
 require 'metior/version'
 
 # Metior is a source code history analyzer that provides various statistics
@@ -21,29 +22,44 @@ module Metior
   #        repository, e.g. a file system path
   # @return [Repository] A VCS specific `Repository` instance
   def self.repository(type, *options)
-    vcs(type)::Repository.new *options
+    vcs(type)::Repository.new(*options)
+  end
+
+  # Generates a report for the given repository
+  #
+  # @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
+  # @param [String] target_dir The target directory to save the report to
+  # @param [String, Range] range The commit range to analyze for the report
+  # @param [String] report The name of the report template to use
+  def self.report(type, repo_options, target_dir, range = nil, report = 'default')
+    repo = repository type, *repo_options
+    range ||= repo.vcs::DEFAULT_BRANCH
+    Report.create(report, repo, range).generate target_dir
   end
 
   # Calculates simplistic stats for the given repository and branch
   #
   # @param [Symbol] type The type of the repository, e.g. `:git`
-  # @param [Array<Object>] options The options for the repository
+  # @param [Object, Array<Object>] repo_options The options to supply to the
+  #        repository
   # @param [String, Range] range The range of commits for which the commits
   #        should be loaded. This may be given as a string
-  #        (`'master..development'`), a range (`'master'..'development'`)
-  #        or as a single ref (`'master'`). A single ref name means all
-  #        commits reachable from that ref.
-  # @return [Hash] The calculated stats for the given repository and branch
-  def self.simple_stats(type, *options)
-    arity  = vcs(type)::Repository.instance_method(:initialize).arity
-    branch = options.delete_at arity
-    branch = vcs(type)::DEFAULT_BRANCH if branch.nil?
-    repo   = repository type, *options
+  #        (`'master..development'`), a range (`'master'..'development'`) or as
+  #        a single ref (`'master'`). A single ref name means all commits
+  #        reachable from that ref.
+  # @return [Hash<Symbol, Object>] The calculated stats for the given
+  #         repository and branch
+  def self.simple_stats(type, repo_options, range = nil)
+    range = vcs(type)::DEFAULT_BRANCH if range.nil?
+    repo  = repository type, *repo_options
 
+    commits = repo.commits(range)
     {
-      :commit_count     => repo.commits(branch).size,
-      :top_contributors => repo.top_contributors(branch, 5),
-    }.merge Commit.activity(repo.commits(branch))
+      :commit_count     => commits.size,
+      :top_contributors => repo.top_contributors(range, 5),
+    }.merge commits.activity
   end
 
 end

data/lib/metior/actor.rb

@@ -3,6 +3,8 @@
 #
 # Copyright (c) 2011, Sebastian Staudt
 
+require 'metior/auto_include_vcs'
+
 module Metior
 
   # Represents an actor in a source code repository
@@ -15,15 +17,16 @@ module Metior
   # @author Sebastian Staudt
   class Actor
 
-    # @return [Fixnum] The lines of code that have been added by this actor
-    attr_reader :additions
+    include AutoIncludeVCS
 
-    # @return [Array<Commit>] The list of commits this actor has contributed to
-    #         the source code repository
-    attr_reader :commits
+    # @return [CommitCollection] The list of commits this actor has contributed
+    #         to the source code repository
+    attr_reader :authored_commits
+    alias_method :commits, :authored_commits
 
-    # @return [Fixnum] The lines of code that have been deleted by this actor
-    attr_reader :deletions
+    # @return [CommitCollection] The list of commits this actor has committed
+    #         to the source code repository
+    attr_reader :committed_commits
 
     # @return [String] The full name of the actor
     attr_reader :name
@@ -45,20 +48,23 @@ module Metior
     #
     # @param [Repository] repo The repository this actor belongs to
     def initialize(repo)
-      @additions = 0
-      @commits   = []
-      @deletions = 0
-      @repo      = repo
+      @authored_commits  = CommitCollection.new
+      @committed_commits = CommitCollection.new
+      @repo              = repo
+    end
+
+    # Returns the lines of code that have been added by this actor
+    #
+    # @return [Fixnum] The lines of code that have been added
+    def additions
+      @authored_commits.additions
     end
 
-    # Adds a new commit to the list of commits this actor has contributed to
-    # the analyzed source code repository
+    # Returns the lines of code that have been deleted by this actor
     #
-    # @param [Commit] commit The commit to add to the list
-    def add_commit(commit)
-      @additions += commit.additions
-      @commits << commit
-      @deletions += commit.deletions
+    # @return [Fixnum] The lines of code that have been deleted
+    def deletions
+      @authored_commits.deletions
     end
 
     # Creates a string representation for this actor without recursing into
@@ -66,10 +72,10 @@ module Metior
     #
     # @return [String] A minimal string representation for this actor
     def inspect
-      '<#%s:0x%x: @commits=%d @id="%s" @name="%s" @repo=<#%s:0x%x ...>>' %
+      '#<%s:0x%x: @commits=%d @id="%s" @name="%s" @repo="%s"' %
         [
-          self.class.name, __id__ * 2, @commits.size, @id, @name,
-          @repo.class.name, @repo.__id__ * 2
+          self.class.name, __id__ * 2, @authored_commits.size, @id, @name,
+          @repo.path
         ]
     end
 
@@ -77,7 +83,7 @@ module Metior
     #
     # @return [Fixnum] The total number of changed lines
     def modifications
-      additions + deletions
+      @authored_commits.modifications
     end
 
   end