metior 0.1.4 → 0.2.0

data/lib/metior/report/view_helper.rb

@@ -0,0 +1,47 @@
+# 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
+
+class Metior::Report
+
+  # This helper module implements generic functionality that is included in all
+  # report views
+  #
+  # @author Sebastian Staudt
+  module ViewHelper
+
+    # Increases the counter by one and returns it
+    #
+    # This can, for example, be used to count the values in an array that is
+    # iterated in a view.
+    #
+    # @return [Fixnum] The current counter value
+    # @see #reset_count
+    def count
+      @count ||= 0
+      @count += 1
+    end
+
+    # Returns whether the current counter value is even or odd
+    #
+    # This is specifically useful for e.g. generating alternating colors of
+    # table rows in the output of the view.
+    #
+    # @return ['even', 'odd'] `'even'` if the current counter value is even,
+    #         `'odd'` otherwise.
+    # @see #reset_count
+    def even_odd
+      (count % 2 == 0) ? 'even' : 'odd'
+    end
+
+    # Resets the current counter to 0
+    #
+    # @see #count
+    def reset_count
+      @count = 0
+    end
+
+  end
+
+end

data/lib/metior/repository.rb

@@ -3,7 +3,9 @@
 #
 # Copyright (c) 2011, Sebastian Staudt
 
-require 'metior/actor'
+require 'metior/auto_include_vcs'
+require 'metior/collections/actor_collection'
+require 'metior/collections/commit_collection'
 
 module Metior
 
@@ -14,6 +16,8 @@ module Metior
   # @author Sebastian Staudt
   class Repository
 
+    include AutoIncludeVCS
+
     # @return [String] The file system path of this repository
     attr_reader :path
 
@@ -21,10 +25,26 @@ module Metior
     #
     # @param [String] path The file system path of the repository
     def initialize(path)
-      @authors    = {}
-      @commits    = {}
-      @committers = {}
-      @path       = path
+      @actors      = {}
+      @commits     = {}
+      @description = nil
+      @name        = nil
+      @path        = path
+      @refs        = {}
+    end
+
+    # Returns a single VCS specific actor object from the raw data of the actor
+    # provided by the VCS implementation
+    #
+    # The actor object is either created from the given raw data or retrieved
+    # from the cache using the VCS specific unique identifier of the actor.
+    #
+    # @param [Object] actor The raw data of the actor provided by the VCS
+    # @return [Actor] A object representing the actor
+    # @see Actor.id_for
+    def actor(actor)
+      id = self.class::Actor.id_for(actor)
+      @actors[id] ||= self.class::Actor.new(self, actor)
     end
 
     # Returns all authors from the given commit range in a hash where the IDs
@@ -38,15 +58,20 @@ module Metior
     #        (`'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<String, Actor>] All authors from the given commit range
+    # @return [ActorCollection] All authors from the given commit range
     # @see #commits
     def authors(range = self.class::DEFAULT_BRANCH)
-      range = parse_range range
-      commits(range) if @authors[range].nil?
-      @authors[range]
+      commits(range).authors
     end
     alias_method :contributors, :authors
 
+    # Returns the names of all branches of this repository
+    #
+    # @return [Array<String>] The names of all branches
+    def branches
+      load_branches.each { |name, id| @refs[name] = id }.keys.sort
+    end
+
     # Loads all commits including their committers and authors from the given
     # commit range
     #
@@ -55,22 +80,38 @@ module Metior
     #        (`'master..development'`), a range (`'master'..'development'`) or
     #        as a single ref (`'master'`). A single ref name means all commits
     #        reachable from that ref.
-    # @return [Array<Commit>] All commits from the given commit range
+    # @return [CommitCollection] All commits from the given commit range
     def commits(range = self.class::DEFAULT_BRANCH)
       range = parse_range range
-      if @commits[range].nil?
-        @authors[range]    = {}
-        @committers[range] = {}
-        @commits[range]    = []
-        load_commits(range).each do |commit|
-          commit = self.class::Commit.new(self, range, commit)
-          @commits[range] << commit
-          @authors[range][commit.author.id]       = commit.author
-          @committers[range][commit.committer.id] = commit.committer
+      commits = cached_commits range
+
+      if commits.empty?
+        base_commit, raw_commits = load_commits(range)
+        commits = commits + build_commits(raw_commits)
+        unless base_commit.nil?
+          base_commit = self.class::Commit.new(self, base_commit)
+          base_commit.add_child commits.last.id
+          @commits[base_commit.id] = base_commit
+        end
+      else
+        if range.first == ''
+          unless commits.last.parents.empty?
+            raw_commits = load_commits(''..commits.last.id).last
+            commits += build_commits raw_commits[0..-2]
+          end
+        else
+          if commits.first.id != range.last
+            raw_commits = load_commits(commits.first.id..range.last).last
+            commits = build_commits(raw_commits) + commits
+          end
+          unless commits.last.parents.include? range.first
+            raw_commits = load_commits(range.first..commits.last.id).last
+            commits += build_commits raw_commits
+          end
         end
       end
 
-      @commits[range]
+      CommitCollection.new commits
     end
 
     # Returns all committers from the given commit range in a hash where the
@@ -84,15 +125,25 @@ module Metior
     #        (`'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<String, Actor>] All committers from the given commit range
+    # @return [ActorCollection] All committers from the given commit range
     # @see #commits
     def committers(range = self.class::DEFAULT_BRANCH)
-      range = parse_range range
-      commits(range) if @committers[range].nil?
-      @committers[range]
+      commits(range).committers
     end
     alias_method :collaborators, :committers
 
+    # Returns the description of the project contained in the repository
+    #
+    # This will load the description through a VCS specific mechanism if
+    # required.
+    #
+    # @return [String] The description of the project in the repository
+    # @see #load_description
+    def description
+      load_description if @description.nil?
+      @description
+    end
+
     # This evaluates basic statistics about the files in a given commit range.
     #
     # @example
@@ -122,7 +173,7 @@ module Metior
       support! :line_stats
 
       stats = {}
-      commits(range).each do |commit|
+      commits(range).each_value do |commit|
         commit.added_files.each do |file|
           stats[file] = { :modifications => 0 } unless stats.key? file
           stats[file][:added_date] = commit.authored_date
@@ -160,18 +211,20 @@ module Metior
     # @return [Hash<Symbol, Array>] Added lines are returned in an `Array`
     #         assigned to key `:additions`, deleted lines are assigned to
     #         `:deletions`
-    # @see Commit#additions
-    # @see Commit#deletions
+    # @see CommitCollection#line_history
     def line_history(range = self.class::DEFAULT_BRANCH)
-      support! :line_stats
-
-      history = { :additions => [], :deletions => [] }
-      commits(range).reverse.each do |commit|
-        history[:additions] <<  commit.additions
-        history[:deletions] << -commit.deletions
-      end
+      commits(range).line_history
+    end
 
-      history
+    # Returns the name of the project contained in the repository
+    #
+    # This will load the name through a VCS specific mechanism if required.
+    #
+    # @return [String] The name of the project in the repository
+    # @see #load_name
+    def name
+      load_name if @name.nil?
+      @name
     end
 
     # Returns a list of authors with the biggest impact on the repository, i.e.
@@ -187,11 +240,7 @@ module Metior
     # @return [Array<Actor>] An array of the given number of the most
     #         significant authors in the given commit range
     def significant_authors(range = self.class::DEFAULT_BRANCH, count = 3)
-      support! :line_stats
-
-      authors = authors(range).values.sort_by { |author| author.modifications }
-      count = [count, authors.size].min
-      authors[-count..-1].reverse
+      authors(range).most_significant(count)
     end
     alias_method :significant_contributors, :significant_authors
 
@@ -208,11 +257,14 @@ module Metior
     # @return [Array<Actor>] An array of the given number of the most
     #         significant commits in the given commit range
     def significant_commits(range = self.class::DEFAULT_BRANCH, count = 10)
-      support! :line_stats
+      commits(range).most_significant(count)
+    end
 
-      commits = commits(range).sort_by { |commit| commit.modifications }
-      count = [count, commits.size].min
-      commits[-count..-1].reverse
+    # Returns the names of all tags of this repository
+    #
+    # @return [Array<String>] The names of all tags
+    def tags
+      load_tags.each { |name, id| @refs[name] = id }.keys.sort
     end
 
     # Returns a list of top contributors in the given commit range
@@ -230,17 +282,109 @@ module Metior
     #         in the given commit range
     # @see #authors
     def top_authors(range = self.class::DEFAULT_BRANCH, count = 3)
-      authors = authors(range).values.sort_by { |author| author.commits.size }
-      count = [count, authors.size].min
-      authors[-count..-1].reverse
+      authors(range).top(count)
     end
     alias_method :top_contributors, :top_authors
 
     private
 
+    # Builds VCS specific commit objects for each given commit's raw data that
+    # is provided by the VCS implementation
+    #
+    # The raw data will be transformed into commit objects that will also be
+    # saved into the commit cache. Authors and committers of the given commits
+    # will be created and stored into the cache or loaded from the cache if
+    # they already exist. Additionally this method will establish an
+    # association between the commits and their children.
+    #
+    # @param [Array<Object>] raw_commits The commits' raw data provided by the
+    #        VCS implementation
+    # @return [Array<Commit>] The commit objects representing the given commits
+    # @see Commit
+    # @see Commit#add_child
+    def build_commits(raw_commits)
+      child_commit_id = nil
+      raw_commits.map do |commit|
+        commit = self.class::Commit.new(self, commit)
+        commit.add_child child_commit_id unless child_commit_id.nil?
+        child_commit_id = commit.id
+        @commits[commit.id] = commit
+        @actors[commit.author.id] ||= commit.author
+        commit
+      end
+    end
+
+    # Tries to retrieve as many commits as possible in the given commit range
+    # from the commit cache
+    #
+    # This method calls itself recursively to walk the given commit range
+    # either from the start to the end or vice versa depending on which commit
+    # could be found in the cache.
+    #
+    # @param [Range] range The range of commits which should be retrieved from
+    #        the cache. This may be given a range of commit IDs
+    #        (`'master'..'development'`).
+    # @return [Array<Commit>] A list of commit objects that could be retrieved
+    #         from the cache
+    # @see Commit#children
+    def cached_commits(range)
+      commits = []
+
+      direction = nil
+      if @commits.key? range.last
+        current_commits = [@commits[range.last]]
+        direction = :parents
+      elsif @commits.key? range.first
+        current_commits = [@commits[range.first]]
+        direction = :children
+      end
+
+      unless direction.nil?
+        while !current_commits.empty? do
+          new_commits = []
+          current_commits.each do |commit|
+            new_commits += commit.send direction
+            commits << commit if commit.id != range.first
+            if direction == :parents && new_commits.include?(range.first)
+              new_commits = []
+              break
+            end
+          end
+          unless new_commits.include? range.first
+            current_commits = new_commits.uniq.map do |commit|
+              commit = @commits[commit]
+              commits.include?(commit) ? nil : commit
+            end.compact
+          end
+        end
+      end
+
+      commits.sort_by { |c| c.committed_date }.reverse
+    end
+
+    # Returns the unique identifier for the commit the given reference – like a
+    # branch name – is pointing to
+    #
+    # @abstract Has to be implemented by VCS subclasses
+    # @param [String] ref A symbolic reference name
+    # @return [Object] The unique identifier of the commit the reference is
+    #         pointing to
+    def id_for_ref(ref)
+      raise NotImplementedError
+    end
+
+    # Loads all branches and the corresponding commit IDs of this repository
+    #
+    # @abstract Has to be implemented by VCS specific subclasses
+    # @return [Hash<String, Object>] The names of all branches and the
+    #         corresponding commit IDs
+    def load_branches
+      raise NotImplementedError
+    end
+
     # Loads all commits from the given commit range
     #
-    # @abstract It has to be implemented by VCS specific subclasses
+    # @abstract Has to be implemented by VCS specific subclasses
     # @param [String, Range] range The range of commits for which the commits
     #        should be retrieved. This may be given as a string
     #        (`'master..development'`), a range (`'master'..'development'`) or
@@ -251,21 +395,46 @@ module Metior
       raise NotImplementedError
     end
 
-    # Parses a string with a single ref name into
+    # Loads the description of the project contained in the repository
+    #
+    # @abstract Has to be implemented by VCS specific subclasses
+    # @see #description
+    def load_description
+      raise NotImplementedError
+    end
+
+    # Loads the name of the project contained in the repository
+    #
+    # @abstract Has to be implemented by VCS specific subclasses
+    # @see #description
+    def load_name
+      raise NotImplementedError
+    end
+
+    # Loads all tags and the corresponding commit IDs of this repository
     #
-    # If a range is given it will be returned as-is.
+    # @abstract Has to be implemented by VCS specific subclasses
+    # @return [Hash<String, Object>] The names of all tags and the
+    #         corresponding commit IDs
+    def load_tags
+      raise NotImplementedError
+    end
+
+    # Parses a string or range of commit IDs or ref names into the coresponding
+    # range of unique commit IDs
     #
     # @param [String, Range] range The string that should be parsed for a range
     #        or an existing range
-    # @return [Range] The range parsed from a string or unchanged from the
-    #         given parameter
+    # @return [Range] The range of commit IDs parsed from the given parameter
+    # @see #id_for_ref
     def parse_range(range)
-      if range.is_a? Range
-        range
-      else
+      unless range.is_a? Range
         range = range.to_s.split '..'
-        ((range.size == 1) ? '' : range.first)..range.last
+        range = ((range.size == 1) ? '' : range.first)..range.last
       end
+
+      range = id_for_ref(range.first)..range.last if range.first != ''
+      range.first..id_for_ref(range.last)
     end
 
   end

data/lib/metior/vcs.rb

@@ -3,7 +3,6 @@
 #
 # Copyright (c) 2011, Sebastian Staudt
 
-require 'metior'
 require 'metior/errors'
 
 module Metior
@@ -41,6 +40,8 @@ module Metior
 
     # This module provided class methods for VCS implementation `Module`s that
     # implement smart auto-loading of dependencies and classes.
+    #
+    # @author Sebastian Staudt
     module ClassMethods
 
       # Missing constants may indicate
@@ -128,7 +129,7 @@ module Metior
     #        its implementation)
     # @see #supports?
     def support!(feature)
-      raise UnsupportedError unless supports? feature
+      raise UnsupportedError.new(vcs) unless supports? feature
     end
 
     # Checks if a specific feature is supported by the VCS (or its
@@ -137,7 +138,15 @@ module Metior
     # @return [true, false] `true` if the feature is supported
     # @see ClassMethods#supports?
     def supports?(feature)
-      singleton_class.included_modules.first.supports? feature
+      vcs.supports? feature
+    end
+
+    # Returns the VCS module that is included by this object
+    #
+    # @return [Metior::VCS] The VCS implementation module of this object
+    # @see Metior.vcs_types
+    def vcs
+      Metior.vcs_types[singleton_class::NAME.to_sym]
     end
 
   end