repokeeper 0.0.1

data/LICENSE

@@ -0,0 +1,14 @@
+Copyright (c) 2014 Anatoliy Plastinin
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <http://www.gnu.org/licenses/>.

data/README.md

@@ -0,0 +1,184 @@
+# Repokeeper
+
+## What's all this about?
+
+Repokeeper is a tool for git repositories analysis that highlights common
+flaws/bad practices in a workflow.
+
+## Flaws in workflow? What does it mean?
+
+Flaws commonly seen in repository management.
+
+## Why do I need a tool for this?
+
+There are many tools for static code analysis like rubocop, flay, flog,
+codeclimate and etc.
+Why not analyze repositories?
+Unlike code, which can be refactored to fix issues, it's not possible to
+refactor repo history (of course, you can rewrite git history, but rewriting
+commits merged into master branch is a bad idea).
+By using Repokeeper, you can explore what was wrong in project's history, and
+then adjust your process accordingly.
+
+
+Problems with project management usually leave traces in repository history and
+structure.
+For instance, a rush in delivery of features to production can lead to debugging
+and fixing in production, which in turn, leads to many `fix`-like commits.
+
+## Story behind this project
+
+Once upon a time... while reviewing a pull request, the author found two commits
+saying:
+
+    Implementing uploader
+    Implementing uploader
+
+His immediate thoughts were: "WTF??? What is it? Did the first attempt fail to
+work?"
+But then, he decided to write a tool to analyze other repos to see if this was a
+unique case, or if he had stumbled upon a more common problem.
+
+## What can this tool tell me about my repo?
+
+Tool detects following problems:
+
+* **Short commit message.**
+The most important thing one can do using any VCS is to write meaningful commit
+message, because it will help others to better understand your changes.
+If you find commit messages like: `fix` or `!!!`, that means someone doesn't do
+a good job in revealing the intention behind these commits.
+
+* **Duplicate commit message.**
+A sequence of two or more sequential commits with the same message might
+indicate that someone didn't find time to squash those commits or that someone
+pushed a fix to master (or even deployed it to production) and it didn't work.
+
+* **Merge commit.**
+This is a commit with 2 parents. It's hard to follow project history if it
+includes tons of merges.
+This analysis might be useful in case you follow rebase and fast-forward only
+merges workflow. Read more about rebase
+[here](http://randyfay.com/content/rebase-workflow-git)
+or [here](http://robots.thoughtbot.com/rebase-like-a-boss).
+
+* **Issues with branches**.
+Branches analyzers are experimental, and there are will be changes in future.
+At this moment, the tool reports a warning if you have too many local or remote
+branches.
+Too many branches can indicate that you aren’t maintaining your repository well
+(i.e., you aren’t deleting local and remote feature branches after merging it).
+
+## OK, I want to try it
+
+Install it from ruby gems
+
+    $ gem install repokeeper
+
+After that
+
+* Goto some repo's directory
+* Run `repokeeper`
+* Have fun
+
+Also you can pass a path to repository, instead switching to the directory with
+the repository: `repokeeper super_cool_project`
+
+You can override default analyzers settings providing a config file with `-c`
+option, e.g. `repokeeper -c .repokeeper.yml`
+
+See `config/default.yml` for configuration file example.
+
+**NOTE:** `repokeeper` without `-c` argument doesn't load `.repokeeper.yml`
+from current directory even if it exists.
+
+## I have a big project, and use non-fastforward merges all the time
+
+If you are annoyed by tons of merge commits warnings, you can disable it,
+by `enabled: false` option in config file.
+
+## More fun with custom formatters
+
+You can provide custom formatter class to change output the way you want,
+or calculate statistics.
+
+To do this you should require ruby file with formatter class using `--require`
+option and provide formatter class name using `--formatter` option.
+
+### Complex example on how to use custom formatters
+
+Let's create a list of most common short commit messages in a repository.
+
+```{ruby}
+# messages_score_formatter.rb
+class MessagesScoreFormatter
+  def initialize(out_stream = $stdout)
+    @out_stream = out_stream
+  end
+
+  def started
+    @counts = Hash.new(0)
+  end
+
+  def commits_analyzer_results(analyzer_name, offenses)
+    Array(offenses).each do |offense|
+      messsage = offense.commit.message.strip.downcase
+      @counts[messsage] += 1
+    end
+  end
+
+  def branches_analyzer_results(analyzer_name, offenses)
+  end
+
+  def finished
+    @counts.sort_by{ |_, v| -v }.each do |k, v|
+      @out_stream.puts "#{k}: #{v}"
+    end
+  end
+end
+```
+
+We are interested to use only short commit messages analyzer, so other analyzers
+can be disabled in configuration file:
+
+```{yaml}
+# .repokeeper.yml
+local_branches_count:
+  enabled: false
+
+remote_branches_count:
+  enabled: false
+
+merge_commits:
+  enabled: false
+
+short_commit_message:
+  message_min_length: 10
+
+similar_commits:
+  enabled: false
+```
+
+And everything is ready to run:
+
+    repokeeper --require ./messages_score_formatter.rb \
+               --formatter MessagesScoreFormatter \
+               -c .repokeeper.yml super_cool_project
+
+## Contributing
+
+You know what to do.
+But don't forget to run `repokeeper` against your new commits ;)
+
+
+## Contact
+
+Anatoliy Plastinin
+
+- http://github.com/antlypls
+- http://twitter.com/antlypls
+- hello@antlypls.com
+
+## License
+
+See `LICENSE`

data/bin/repokeeper

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH << File.expand_path('../../lib', __FILE__)
+
+require 'repokeeper'
+
+Repokeeper::CLI.go!

data/config/default.yml

@@ -0,0 +1,13 @@
+local_branches_count:
+  max_local_branches: 5
+
+remote_branches_count:
+  max_remote_branches: 5
+
+merge_commits:
+
+short_commit_message:
+  message_min_length: 10
+
+similar_commits:
+  min_edit_distance: 4

data/lib/repokeeper/analyzers/analyzer.rb

@@ -0,0 +1,26 @@
+module Repokeeper::Analyzers
+  # Base class for sequential commits analyzers
+  class Analyzer
+    @all = AnalyzersSet.new
+
+    def self.all
+      @all.clone
+    end
+
+    def self.inherited(subclass)
+      @all << subclass
+    end
+
+    def initialize(config)
+      @config = config || {}
+    end
+
+    def name
+      self.class.name.split('::').last
+    end
+
+    def enabled?
+      @config.fetch('enabled') { true }
+    end
+  end
+end

data/lib/repokeeper/analyzers/analyzers_set.rb

@@ -0,0 +1,11 @@
+module Repokeeper::Analyzers
+  class AnalyzersSet < Array
+    def commits_analyzers
+      select { |a| a.type == :commit }
+    end
+
+    def branch_analyzers
+      select { |a| a.type == :branch }
+    end
+  end
+end

data/lib/repokeeper/analyzers/branches/local_branches_count.rb

@@ -0,0 +1,20 @@
+module Repokeeper::Analyzers
+  class LocalBranchesCount < Analyzer
+    include BranchesAnalyzer
+    include BranchesCount
+
+    def max_branches
+      @config['max_local_branches']
+    end
+
+    private
+
+    def get_branches(repo)
+      repo.local_branches
+    end
+
+    def message
+      'too many local branches'
+    end
+  end
+end

data/lib/repokeeper/analyzers/branches/remote_branches_count.rb

@@ -0,0 +1,20 @@
+module Repokeeper::Analyzers
+  class RemoteBranchesCount < Analyzer
+    include BranchesAnalyzer
+    include BranchesCount
+
+    def max_branches
+      @config['max_remote_branches']
+    end
+
+    private
+
+    def get_branches(repo)
+      repo.remote_branches
+    end
+
+    def message
+      'too many remote branches'
+    end
+  end
+end

data/lib/repokeeper/analyzers/commits/merge_commits.rb

@@ -0,0 +1,11 @@
+module Repokeeper::Analyzers
+  # Analyzes merge commits
+  # commits level analyzer
+  class MergeCommits < Analyzer
+    include CommitsAnalyzer
+
+    def process_commit(commit)
+      create_offense(commit, 'merge commit') if commit.parents.count > 1
+    end
+  end
+end

data/lib/repokeeper/analyzers/commits/short_commit_message.rb

@@ -0,0 +1,26 @@
+module Repokeeper::Analyzers
+  # Analyzes short commit messages
+  # sign of undescriptive message
+  # commits level analyzer
+  class ShortCommitMessage < Analyzer
+    include CommitsAnalyzer
+
+    def message_min_length
+      @config['message_min_length']
+    end
+
+    def process_commit(commit)
+      create_offense_message(commit) if error?(commit)
+    end
+
+    private
+
+    def error?(commit)
+      commit.message.length < message_min_length
+    end
+
+    def create_offense_message(commit)
+      create_offense(commit, "Short commit message: #{commit.message}")
+    end
+  end
+end

data/lib/repokeeper/analyzers/commits/similar_commits.rb

@@ -0,0 +1,44 @@
+module Repokeeper::Analyzers
+  # Checks for similar commits messages in commit ant its parents
+  # commits level analyzer
+  class SimilarCommits < Analyzer
+    include CommitsAnalyzer
+
+    def min_edit_distance
+      @config['min_edit_distance']
+    end
+
+    def process_commit(commit)
+      commit.parents.map do |parent|
+        compare_commits(commit, parent)
+      end.compact
+    end
+
+    private
+
+    def compare_commits(newer, older)
+      new_message = clean_commit_message(newer)
+      old_message = clean_commit_message(older)
+
+      distance = Repokeeper::Utils.edit_distance(new_message, old_message)
+      error = error_message_by_distance(distance, new_message, old_message)
+      create_offense_for_error(error, newer, older)
+    end
+
+    def error_message_by_distance(distance, new_message, old_message)
+      if distance == 0
+        "Same commit message: '#{new_message}'"
+      elsif distance < min_edit_distance
+        "Similar commit messages: '#{new_message}' and '#{old_message}'"
+      end
+    end
+
+    def create_offense_for_error(error, newer, older)
+      create_offense(newer, "#{error}. See #{older.oid}") if error
+    end
+
+    def clean_commit_message(commit)
+      commit.message.gsub(/[\t\n]/, ' ').strip
+    end
+  end
+end

data/lib/repokeeper/analyzers/mixins/branches_analyzer.rb

@@ -0,0 +1,13 @@
+module Repokeeper::Analyzers
+  module BranchesAnalyzer
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      def type
+        :branch
+      end
+    end
+  end
+end

data/lib/repokeeper/analyzers/mixins/branches_count.rb

@@ -0,0 +1,22 @@
+module Repokeeper::Analyzers
+  module BranchesCount
+    def analyze(repo)
+      branches = get_branches(repo)
+      report(branches) if error?(branches)
+    end
+
+    private
+
+    def error?(branches)
+      branches.count > max_branches
+    end
+
+    def report(branches)
+      create_offense(branches)
+    end
+
+    def create_offense(branches)
+      Repokeeper::Offenses::BranchesOffense.new(branches, message, name)
+    end
+  end
+end

data/lib/repokeeper/analyzers/mixins/commits_analyzer.rb

@@ -0,0 +1,19 @@
+module Repokeeper::Analyzers
+  module CommitsAnalyzer
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      def type
+        :commit
+      end
+    end
+
+    private
+
+    def create_offense(commit, message)
+      Repokeeper::Offenses::CommitOffense.new(commit, message, name)
+    end
+  end
+end

data/lib/repokeeper/analyzers.rb

@@ -0,0 +1,10 @@
+require_relative 'analyzers/mixins/branches_analyzer'
+require_relative 'analyzers/mixins/branches_count'
+require_relative 'analyzers/mixins/commits_analyzer'
+require_relative 'analyzers/analyzers_set'
+require_relative 'analyzers/analyzer'
+require_relative 'analyzers/commits/merge_commits'
+require_relative 'analyzers/commits/short_commit_message'
+require_relative 'analyzers/commits/similar_commits'
+require_relative 'analyzers/branches/local_branches_count'
+require_relative 'analyzers/branches/remote_branches_count'

data/lib/repokeeper/cli.rb

@@ -0,0 +1,62 @@
+require 'methadone'
+
+module Repokeeper
+  class CLI
+    include Methadone::Main
+    include Methadone::CLILogging
+
+    version VERSION, compact: true
+    description 'Repokeeper checks your repo for flaws'
+
+    arg :path, :optional,
+        'path to repo to analyze, current dir if not specified'
+
+    on '-r REV_RANGE', '--rev-range',
+       'Revisions to analyze by commits analyzers'
+
+    on '-c CONFIG_FILE', '--config',
+       'Configuration file'
+
+    on '--require REQUIRE_FILE',
+       'File to require'
+
+    on '--formatter FORMATTER_CLASS',
+       'Formatter class'
+
+    main do |path|
+      file_to_require = options['require']
+      require file_to_require if file_to_require
+
+      formatter_class = formatter_class_by_name(options['formatter'])
+
+      config_file = options['config']
+      repo_analyzer = create_analyzer(path, config_file, formatter_class)
+      range = rev_range(options['rev-range'])
+      repo_analyzer.analyze(range)
+    end
+
+    def self.formatter_class_by_name(name)
+      if name && !name.empty?
+        const_get(name)
+      else
+        SimpleTextFormatter
+      end
+    end
+
+    def self.create_analyzer(path, config_file, formatter_class)
+      formatter = formatter_class.new
+
+      analyzers = Analyzers::Analyzer.all
+
+      proxy = RepoProxy.new(path)
+      config = Config.read(config_file)
+      RepoAnalyzer.new(proxy, formatter, analyzers, config)
+    end
+
+    def self.rev_range(rev_spec)
+      parser = RevParser.new(rev_spec)
+      parser.parse
+      parser.range
+    end
+  end
+end

data/lib/repokeeper/config.rb

@@ -0,0 +1,43 @@
+module Repokeeper
+  class Config
+    HOME_DIR = File.expand_path('../../../', __FILE__)
+    CONFIG_DIR = File.join(HOME_DIR, 'config')
+    DEFAULT_CONFIG = File.join(CONFIG_DIR, 'default.yml')
+
+    def initialize(hash)
+      @config = hash
+    end
+
+    def for(klass)
+      key = klass.name.split('::').last
+                 .gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+      @config[key]
+    end
+
+    def self.read(file_path = nil)
+      config_file = read_configuration_file(file_path)
+      config = merge_hashes(default_configuration, config_file)
+      new(config)
+    end
+
+    def self.default_configuration
+      read_configuration_file(DEFAULT_CONFIG)
+    end
+
+    def self.read_configuration_file(file_path)
+      return {} unless file_path
+      YAML.load_file(file_path)
+    end
+    private_class_method :read_configuration_file
+
+    def self.merge_hashes(hash1, hash2)
+      hash1.merge(hash2) do |_, oldval, newval|
+        old_hash = Hash(oldval)
+        new_hash = Hash(newval)
+
+        old_hash.merge(new_hash)
+      end
+    end
+    private_class_method :read_configuration_file
+  end
+end

data/lib/repokeeper/offenses/branches_offense.rb

@@ -0,0 +1,8 @@
+module Repokeeper
+  module Offenses
+    class BranchesOffense < Struct.new(:branches, :message, :analyzer_name)
+      # we want Array(offense) to return [offense]
+      undef_method :to_a
+    end
+  end
+end

data/lib/repokeeper/offenses/commit_offense.rb

@@ -0,0 +1,8 @@
+module Repokeeper
+  module Offenses
+    class CommitOffense < Struct.new(:commit, :message, :analyzer_name)
+      # we want Array(offense) to return [offense]
+      undef_method :to_a
+    end
+  end
+end

data/lib/repokeeper/repo_analyzer.rb

@@ -0,0 +1,68 @@
+module Repokeeper
+  # provides infrastructure for running commits analyzers
+  class RepoAnalyzer
+    def initialize(repo_proxy, formatter, analyzers, config)
+      @analyzers = analyzers
+      @formatter = formatter
+      @repo = repo_proxy
+      @config = config
+    end
+
+    def analyze(rev_range = nil)
+      @rev_range = rev_range
+
+      @formatter.started
+      run_commits_analyzers
+      run_branches_analyzers
+      @formatter.finished
+    end
+
+    private
+
+    def commits_analyzers
+      @analyzers.commits_analyzers
+    end
+
+    def branch_analyzers
+      @analyzers.branch_analyzers
+    end
+
+    def enabled_analyzers(collection)
+      collection
+        .map { |analyzer_class| instantiate_analyzer(analyzer_class) }
+        .select { |analyzer| analyzer.enabled? }
+    end
+
+    def enabled_commits_analyzers
+      @enabled_commits_analyzers ||= enabled_analyzers(commits_analyzers)
+    end
+
+    def enabled_branches_analyzers
+      @enabled_branches_analyzers ||= enabled_analyzers(branch_analyzers)
+    end
+
+    def run_commits_analyzers
+      commits.each do |commit|
+        enabled_commits_analyzers.each do |analyzer|
+          result = analyzer.process_commit(commit)
+          @formatter.commits_analyzer_results(analyzer.name, result)
+        end
+      end
+    end
+
+    def run_branches_analyzers
+      enabled_branches_analyzers.each do |analyzer|
+        result = analyzer.analyze(@repo)
+        @formatter.branches_analyzer_results(analyzer.name, result)
+      end
+    end
+
+    def instantiate_analyzer(analyzer_class)
+      analyzer_class.new(@config.for(analyzer_class))
+    end
+
+    def commits
+      @commits ||= @repo.commits(@rev_range)
+    end
+  end
+end