twigg 0.0.1

data/lib/twigg/commit_set.rb

@@ -0,0 +1,137 @@
+require 'forwardable'
+require 'set'
+
+module Twigg
+  class CommitSet
+    extend Forwardable
+    def_delegators :commits, :any?, :count, :each, :inject, :<<
+    attr_reader :commits
+
+    def initialize(commits = [])
+      @commits = commits
+    end
+
+    def additions
+      @additions ||= inject(0) do |memo, commit|
+        memo + commit.stat[:additions]
+      end
+    end
+
+    def deletions
+      @deletions ||= inject(0) do |memo, commit|
+        memo + commit.stat[:deletions]
+      end
+    end
+
+    def flesch_reading_ease
+      @flesch_reading_ease ||= inject(0) do |memo, commit|
+        memo + commit.flesch_reading_ease
+      end / count
+    end
+
+    def russianness
+      @russianness ||= inject(0) do |memo, commit|
+        memo + commit.russianness
+      end
+    end
+
+    def count_by_day(days)
+      start_date = Date.today - days
+      end_date = Date.today
+      date_to_commits = @commits.group_by { |commit| commit.date }
+      (start_date..end_date).map do |date|
+        { date: date, count: date_to_commits.fetch(date, []).count }
+      end
+    end
+
+    # Returns a copy of the receiver merged with `commit_set`.
+    def +(commit_set)
+      unless commit_set.is_a?(CommitSet)
+        raise TypeError, "expected Twigg::CommitSet, got #{commit_set.class}"
+      end
+
+      dup.tap do |other|
+        other.commits.concat(commit_set.commits)
+        other.commits.uniq!
+      end
+    end
+
+    def count_by_repo
+      counts = Hash.new(0)
+      each { |commit| counts[commit.repo] += 1 }
+      counts.sort_by { |repo, count| -count }.
+        map { |repo, count| { repo: repo, count: count } }
+    end
+
+    def select_author(author)
+      commits_for_author = @commits.select do |commit|
+        commit.author_names.include?(author)
+      end
+
+      self.class.new(commits_for_author)
+    end
+
+    def select_team(team)
+      members = Set.new(Config.teams[team])
+
+      commits_for_team = @commits.select do |commit|
+        commit.author_names.any? { |author| members.include?(author) }
+      end
+
+      self.class.new(commits_for_team)
+    end
+
+    def authors
+      @authors ||= author_to_commit_set.
+        sort_by { |author, commit_set| -commit_set.count }.
+        map { |author, commit_set| { author: author, commit_set: commit_set } }
+    end
+
+    # Returns a sparse pairing "matrix".
+    #
+    # Keys are pairer names. Values are hashes of pairees-to-count maps.
+    def pairs
+      PairMatrix.new(self)
+    end
+
+    def teams
+      set = author_to_commit_set
+
+      teams = Config.teams.each_pair.map do |team, members|
+        commits = members.each_with_object(self.class.new) do |member, commit_set|
+          if member = set.delete(member)
+            commit_set += member
+          end
+        end
+
+        if commits.any?
+          {
+            author:     team.to_s,
+            commit_set: commits,
+            authors:    members,
+          }
+        end
+      end.compact.sort_by { |team| -team[:commit_set].count }
+
+      unless set.empty?
+        teams << {
+          author:     Team::OTHER_TEAM_NAME,
+          commit_set: set.values.inject(self.class.new, :+),
+          authors:    set.keys,
+        }
+      end
+
+      teams
+    end
+
+  private
+
+    def author_to_commit_set
+      Hash.new { |h, k| h[k] = self.class.new }.tap do |set|
+        each do |commit|
+          commit.author_names.each { |author_name| set[author_name] << commit }
+        end
+      end
+    end
+  end
+end

data/lib/twigg/config.rb

@@ -0,0 +1,95 @@
+require 'forwardable'
+require 'shellwords'
+require 'yaml'
+
+module Twigg
+  # The Config class mediates all access to the Twigg config file.
+  #
+  # First, we look for a YAML file at the location specified by the TWIGGRC
+  # environment variable. If that isn't set, we fallback to looking for a config
+  # file at `~/.twiggrc`.
+  #
+  # Example use:
+  #
+  #   Config.bind                   # the bind address for the Twigg web app
+  #                                 # [default: 0.0.0.0]
+  #   Config.gerrit.host            # the (optional) Gerrit hostname
+  #                                 # [default: localhost]
+  #   Config.gerrit.port            # the (optional) Gerrit port
+  #                                 # [default: 29418]
+  #   Config.gerrit.user            # the (optional) Gerrit username
+  #                                 # [default: $USER environment variable]
+  #   Config.repositories_directory # where to find repositories
+  #
+  class Config
+    include Console
+
+    class << self
+      # For convenience, forward all messages to the underlying {Config}
+      # instance. This allows us to write things like `Config.bind` instead of
+      # the more verbose `Config.config.bind`.
+      extend Forwardable
+      def_delegators :config, :method_missing
+
+    private
+
+      # Maintain a "singleton" Config instance for convenient access.
+      def config
+        @config ||= new
+      end
+    end
+
+    def initialize
+      @settings = Settings.new(config_from_argv ||
+                               config_from_env ||
+                               config_from_home)
+    end
+
+  private
+
+    # Foward all messages to the underlying {Settings} instance.
+    def method_missing(method, *args, &block)
+      @settings.send(method, *args, &block)
+    end
+
+    def config_from_file(path)
+      YAML.load_file(path).tap do |contents|
+        if File.world_readable?(path)
+          warn "#{path} is world-readable"
+          stderr strip_heredoc(<<-DOC)
+
+            The Twigg config file may contain sensitive information, such as
+            access credentials for external services.
+
+            Suggested action: tighten the filesystem permissions with:
+
+                chmod 600 #{Shellwords.escape path}
+
+          DOC
+        end
+      end
+    end
+
+    def config_from_argv
+      # It is a bit of a smell to have the Config class know about argument
+      # processing, but, at least in development, Bundler will end up eagerly
+      # loading the config when it evaluates the Gemfile (and hence the
+      # twigg-app.gemspec), which means that this happens before the
+      # Twigg::Command.run method gets a chance to set things up properly.
+      path = consume_option(%w[-c --config], ARGV)
+      config_from_file(path) if path
+    end
+
+    def config_from_env
+      config_from_file(ENV['TWIGGRC']) if ENV['TWIGGRC']
+    end
+
+    TWIGGRC = '.twiggrc'
+
+    def config_from_home
+      config_from_file(File.join(Dir.home, TWIGGRC))
+    rescue Errno::ENOENT
+      {} # no custom config; assume defaults
+    end
+  end
+end

data/lib/twigg/console.rb

@@ -0,0 +1,68 @@
+module Twigg
+  # A collection of useful methods for code that is running in a console.
+  #
+  # Functionality includes printing, process lifecycle management and
+  # formatting.
+  module Console
+    extend self
+
+  private
+    # Print `msgs` to standard error
+    def stderr(*msgs)
+      STDERR.puts(*msgs)
+    end
+
+    # Exit with an exit code of 1, printing the optional `msg`, prefixed with
+    # "error: ", to standard error if present
+    def die(msg = nil)
+      error(msg) if msg
+      exit 1
+    end
+
+    # Print `msg` to the standard error, prefixed with "error: "
+    def error(msg)
+      stderr("error: #{msg}")
+    end
+
+    # Print `msg` to the standard error, prefixed with "warning: "
+    def warn(msg)
+      stderr "warning: #{msg}"
+    end
+
+    # Given a "heredoc" `doc`, find the non-empty line with the smallest indent,
+    # and strip that amount of whitespace from the beginning of each line.
+    #
+    # This allows us to write nicely indented copy that sits well with the
+    # surrounding code, irrespective of the level of indentation of the code,
+    # without emitting excessive whitespace to the user at runtime.
+    def strip_heredoc(doc)
+      indent = doc.scan(/^[ \t]*(?=\S)/).map(&:size).min || 0
+      doc.gsub(/^[ \t]{#{indent}}/, '')
+    end
+
+    # Given `switches` (which may be either a single switch or an array of
+    # switches) and an array of arguments, `args`, scans through the arguments
+    # looking for the switches and the corresponding values.
+    #
+    # This can be used, for example, to extract the value "/etc/twiggrc" from an
+    # argument list like "--verbose --debug --config /etc/twiggrc help".
+    #
+    # In the event that the switches appear multiple times in the list, the
+    # right-most wins. If a switch is found without a corresponding option an
+    # exception is raised.
+    #
+    # Consumes matching options (ie. deletes them from `args) and returns the
+    # corresponding (rightmost) value, or `nil` in the event there is no match.
+    def consume_option(switches, args)
+      # consume from left to right; rightmost will win
+      while index = args.find_index { |arg| Array(switches).include?(arg) }
+        switch, value = args.slice!(index, 2)
+        raise ArgumentError, "missing option (expected after #{switch})" unless value
+      end
+
+      value
+    end
+  end
+
+  Console.public_class_method :die
+end

data/lib/twigg/dependency.rb

@@ -0,0 +1,12 @@
+module Twigg
+  module Dependency
+  private
+
+    def with_dependency(gem, &block)
+      require gem
+      yield
+    rescue LoadError => e
+      Console.die "#{e}: try `gem install #{gem}`"
+    end
+  end
+end

data/lib/twigg/flesch.rb

@@ -0,0 +1,65 @@
+module Twigg
+  # Class which computes an approximation of the Flesch Reading Ease metric for
+  # a given piece of English-language text.
+  #
+  # @see {http://en.wikipedia.org/wiki/Flesch%E2%80%93Kincaid_readability_tests}
+  class Flesch
+    def initialize(string)
+      @string = string
+    end
+
+    def reading_ease
+      # from wikipedia:
+      ease = 206.835 -
+        1.015 * (total_words / total_sentences.to_f) -
+        84.6  * (total_syllables / total_words.to_f)
+
+      # beware NaN values (usually caused by empty commit messages),
+      # incompatible with JSON
+      ease.nan? ? 206.835 : ease
+    end
+
+  private
+
+    # Returns approximate count of words in the receiver.
+    def total_words
+      words.size
+    end
+
+    # Returns an array of "words" in the receiver. "Words" are defined as
+    # strings of consecutive "word" characters (as defined by the regex
+    # short-hand, `\w`).
+    def words
+      @words ||= @string.split(/\b/).select { |w| w.match /\w/ }
+    end
+
+    # Returns approximate total count of sentences in the receiver.
+    def total_sentences
+      @string.split(/\.+/).size
+    end
+
+    # Returns approximate total count of syllables in the receiever.
+    def total_syllables
+      words.inject(0) { |memo, word| memo + syllables(word) }
+    end
+
+    # Returns an approximate syllable count for `word`.
+    #
+    # Based on: {http://stackoverflow.com/questions/1271918/ruby-count-syllables}
+    def syllables(word)
+      # words of 3 letters or less count as 1 syllable; rare exceptions (eg.
+      # "ion") are not handled
+      return 1 if word.size <= 3
+
+      # - ignore final es, ed, e (except for le)
+      # - consecutive vowels count as one syllable
+      word.
+        downcase.
+        gsub(/W+/, ' '). # suppress punctuation
+        sub(/(?:[^laeiouy]es|ed|[^laeiouy]e)$/, '').
+        sub(/^y/, '').
+        scan(/[aeiouy]{1,2}/).
+        size
+    end
+  end
+end

data/lib/twigg/gatherer.rb

@@ -0,0 +1,15 @@
+module Twigg
+  module Gatherer
+    def self.gather(repositories_directory, days)
+      since = Time.now - days * 24 * 60 * 60
+
+      CommitSet.new.tap do |commit_set|
+        RepoSet.new(repositories_directory).for_each_repo do |repo|
+          repo.commits(since: since).each do |commit|
+            commit_set << commit
+          end
+        end
+      end
+    end
+  end
+end

data/lib/twigg/pair_matrix.rb

@@ -0,0 +1,83 @@
+require 'forwardable'
+
+module Twigg
+  # A PairMatrix is initialized with a {CommitSet} instance and computes
+  # pairing information for those commits.
+  class PairMatrix
+    extend Forwardable
+    def_delegators :pairs, :[], :keys
+
+    def initialize(commit_set)
+      @commit_set = commit_set
+    end
+
+    # Returns a sparse matrix representing the pairing permutations, and commit
+    # counts for each, in the receiver.
+    #
+    # The returned matrix is a Hash data structure and can be queried like so:
+    #
+    #     pm['Joe Lencioni']['Noah Silas']   #=> 3 (commit count by the pair)
+    #     pm['Tony Wooster']['Tony Wooster'] #=> 9 (commit count as solo author)
+    #     pm['Joe Lencioni']['Tony Wooster'] #=> 0 (no commits, no pairing)
+    #
+    # Note that the {#[]} method is forwarded to the underlying Hash, which
+    # means that the above examples work equally well whether `pm` is an
+    # instance of a {PairMatrix} or the result of a call to the the {#pairs}
+    # method on a {PairMatrix} instance.
+    def pairs
+      @pairs ||= sparse_matrix.tap do |matrix|
+        @commit_set.each do |commit|
+          authors = commit.author_names
+
+          # if you're solo, that's equivalent to pairing with yourself
+          authors *= 2 if authors.size == 1
+
+          authors.permutation(2).to_a.uniq.each do |pairer, pairee|
+            matrix[pairer][pairee] += 1
+          end
+        end
+      end
+    end
+
+    # Returns a sorted array of names corresponding to the authors represented
+    # in the matrix.
+    def authors
+      @authors ||= pairs.keys.sort
+    end
+
+    # Scan the matrix, identifying and returning the "solo" element (ie. one
+    # person working alone) with the highest number of commits.
+    def max_solo
+      @max_solo ||= pairs.inject(0) do |max, (pairee, pairs)|
+        [pairs.inject(0) do |max, (pairer, count)|
+          [pairee == pairer ? count : 0, max].max
+        end, max].max
+      end
+    end
+
+    # Scan the matrix, identifying and returning the "pair" element (ie. two
+    # distinct people pairing) with the highest number of commits.
+    def max_pair
+      @max_pair ||= pairs.inject(0) do |max, (pairee, pairs)|
+        [pairs.inject(0) do |max, (pairer, count)|
+          [pairee == pairer ? 0 : count, max].max
+        end, max].max
+      end
+    end
+
+  private
+
+    # Returns a Hash instance that models a sparse matrix.
+    #
+    # Looking up a pairee/pairer pair in the matrix returns 0 if the matrix does
+    # not have a value for that entry; for example:
+    #
+    #     sparse_matrix['Jimmy Kittiyachavalit']['Chris Chan'] #=> 0
+    #
+    def sparse_matrix
+      Hash.new do |hash, pairer|
+        hash[pairer] = Hash.new { |hash, pairee| hash[pairee] = 0 }
+      end
+    end
+  end
+end

data/lib/twigg/repo.rb

@@ -0,0 +1,134 @@
+require 'date'
+require 'pathname'
+
+module Twigg
+  # Abstraction around a Git repository on disk.
+  class Repo
+    class InvalidRepoError < RuntimeError; end
+
+    # Given `path` to a Git repository on disk sets up a `Repo` instance.
+    #
+    # Raises an {InvalidRepoError} if `path` does not point to the top level of
+    # an existent Git repo.
+    def initialize(path)
+      @path = Pathname.new(path)
+      raise InvalidRepoError unless valid?
+    end
+
+    # Returns an array of {Commit} objects reachable from the HEAD of the repo.
+    #
+    # There are a number of keyword arguments that correspond to the options of
+    # the same name to `git log`:
+    #
+    #   - `all:` : return reachable commits from all branches, not just HEAD
+    #   - `since:`: only return commits made since this Time
+    #
+    def commits(all: true, since: nil)
+      args = []
+      args << '--all' if all
+      args << "--since=#{since.to_i}" if since
+      @commits ||= {}
+      @commits[args] ||= parse_log(log(*args))
+    end
+
+    # Returns the name of the repo.
+    #
+    # The name is inferred from the final component of the repo path.
+    def name
+      @path.basename.to_s
+    end
+
+    def link
+      if Config.github.organization
+        "https://github.com/#{Config.github.organization}/#{name}"
+      end
+    end
+
+  private
+
+    STDERR_TO_STDOUT = [err: [:child, :out]]
+
+    def git_dir
+      @git_dir ||= begin
+        # first try repo "foo" (bare repo), then "foo/.git" (non-bare repo)
+        [@path, @path + '.git'].map(&:to_s).find do |path|
+          Process.wait(
+            IO.popen({ 'GIT_DIR' => path },
+                     %w[git rev-parse --git-dir] + STDERR_TO_STDOUT).pid
+          )
+          $?.success?
+        end
+      end
+    end
+
+    # Check to see if this is a valid repo:
+    #
+    #   - the repo path should exist
+    #   - the path should point to the top level of the repo
+    #   - the check should work for both bare and non-bare repos
+    #
+    # Delegates to `#git_dir`
+    alias :valid? :git_dir
+
+    # Runs the Git command, `command`, with args `args`.
+    def git(command, *args)
+      IO.popen([{ 'GIT_DIR' => git_dir },
+                'git', command, *args, *STDERR_TO_STDOUT], 'r') do |io|
+        io.read
+      end
+    end
+
+    def log(*args)
+      format = [
+        '%H',          # commit hash
+        '%n',          # newline
+        '%aN',         # author name (respecting .mailmap)
+        '%n',          # newline
+        '%ct',         # committer date, UNIX timestamp
+        '%n',          # newline
+        '%s',          # subject
+        '%n',          # newline
+        '%w(0,4,4)%b', # body, indented 4 spaces
+      ].join
+
+      git 'log', "--pretty=format:#{format}", '--numstat', *args
+    end
+
+    def parse_log(string)
+      [].tap do |commits|
+        lines = string.each_line
+        loop do
+          begin
+            commit           = { repo: self }
+            commit[:commit]  = lines.next.chomp
+            commit[:author]  = lines.next.chomp
+            commit[:date]    = Time.at(lines.next.chomp.to_i).to_date
+            commit[:subject] = lines.next.chomp rescue ''
+
+            commit[:body]    = []
+            while lines.peek =~ /^ {4}(.*)$/ && lines.next
+              commit[:body] << $~[1]
+            end
+            commit[:body]    = commit[:body].join("\n")
+            lines.next if lines.peek == "\n" # blank separator line
+
+            commit[:stat]    = Hash.new(0)
+            while lines.peek =~ /^(\d+|-)\t(\d+|-)\t.+$/ && lines.next
+              commit[:stat][:additions] += $~[1].to_i
+              commit[:stat][:deletions] += $~[2].to_i
+            end
+            lines.next if lines.peek == "\n" # blank separator line
+
+          rescue StopIteration
+            break # end of output
+          ensure
+            # if the underlying repo is bad (eg. no commits yet) this could
+            # raise an ArgumentError, so we rescue
+            commit = Commit.new(commit) rescue nil
+            commits << commit if commit
+          end
+        end
+      end
+    end
+  end
+end

data/lib/twigg/repo_set.rb

@@ -0,0 +1,31 @@
+require 'pathname'
+
+module Twigg
+  # Represents a set of Git repositories existing in a directory.
+  class RepoSet
+    def initialize(repositories_directory)
+      @repositories_directory = Pathname.new(repositories_directory)
+    end
+
+    # Execute `block` for each repo in the set.
+    #
+    # The {Repo} object is passed in to the block.
+    def for_each_repo(&block)
+      repos.each do |repo|
+        block.call(repo)
+      end
+    end
+
+    def repos
+      @repos ||= begin
+        Dir[File.join(@repositories_directory, '*')].map do |path|
+          begin
+            repo = Repo.new(path)
+          rescue Repo::InvalidRepoError
+            # most likely an empty or non-Git directory
+          end
+        end.compact
+      end
+    end
+  end
+end

data/lib/twigg/russian_novel.rb

@@ -0,0 +1,40 @@
+module Twigg
+  class RussianNovel
+    # The class takes a {CommitSet} and produces data that can be used to
+    # produce a d3 bubble chart:
+    #
+    #   https://github.com/mbostock/d3/wiki/Pack-Layout
+    #   http://bl.ocks.org/mbostock/4063269
+    #
+    # The bubble chart is an excellent format for representing the
+    # "Russianness" of an author's commit messages:
+    #
+    #   - size:  commit message line count (also known as "Russianness")
+    #   - text:  author name
+    #   - hover: detailed stats on "Russianness", Flesch Reading Ease score,
+    #            author and team name
+    #   - color: team
+    #
+    def initialize(commit_set)
+      @commit_set = commit_set
+    end
+
+    # Returns Russian Novel data in a d3-friendly format.
+    def data
+      @data ||= begin
+        team_map = Team.author_to_team_map
+
+        children = @commit_set.authors.map do |object|
+          {
+            'author'              => object[:author],
+            'russianness'         => object[:commit_set].russianness,
+            'flesch_reading_ease' => object[:commit_set].flesch_reading_ease,
+            'team'                => team_map[object[:author]],
+          }
+        end
+
+        { 'children' => children }
+      end
+    end
+  end
+end