ruby-maat 1.0.0

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/doc/intro.md

@@ -0,0 +1,3 @@
+# Introduction to code-maat
+
+TODO: write [great documentation](http://jacobian.org/writing/great-documentation/what-to-write/)

data/exe/ruby-maat

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/ruby_maat"
+
+RubyMaat::CLI.new.run(ARGV)

data/lib/ruby_maat/analysis/authors.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module RubyMaat
+  module Analysis
+    # Authors analysis - counts distinct authors per entity
+    # Research shows that the number of authors of a module is related to quality problems
+    class Authors < BaseAnalysis
+      def analyze(dataset, options = {})
+        min_revs = options[:min_revs] || 1
+
+        # Group by entity and count distinct authors and revisions manually
+        entity_stats = {}
+
+        dataset.to_df.to_a.each do |row|
+          entity = row["entity"]
+          author = row["author"]
+          revision = row["revision"]
+
+          entity_stats[entity] ||= {authors: Set.new, revisions: Set.new}
+          entity_stats[entity][:authors] << author
+          entity_stats[entity][:revisions] << revision
+        end
+
+        # Build results and apply minimum revisions filter
+        results = []
+        entity_stats.each do |entity, stats|
+          n_revs = stats[:revisions].size
+          next if n_revs < min_revs
+
+          results << {
+            entity: entity,
+            "n-authors": stats[:authors].size,
+            "n-revs": n_revs
+          }
+        end
+
+        # Sort by number of authors (descending), then by revisions (descending)
+        results.sort! do |a, b|
+          comparison = b[:"n-authors"] <=> a[:"n-authors"]
+          comparison.zero? ? b[:"n-revs"] <=> a[:"n-revs"] : comparison
+        end
+
+        to_csv_data(results, [:entity, :"n-authors", :"n-revs"])
+      end
+    end
+  end
+end

data/lib/ruby_maat/analysis/base_analysis.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module RubyMaat
+  module Analysis
+    # Base class for all analysis modules
+    class BaseAnalysis
+      def analyze(dataset, options = {})
+        raise NotImplementedError, "Subclasses must implement analyze method"
+      end
+
+      protected
+
+      # Filter dataset by minimum revisions threshold
+      def filter_by_min_revisions(dataset, min_revs)
+        return dataset if min_revs <= 1
+
+        dataset.filter_min_revisions(min_revs)
+      end
+
+      # Helper to convert analysis results to CSV-compatible format
+      def to_csv_data(results, columns)
+        if results.empty?
+          # Create empty dataframe with proper column structure
+          empty_data = {}
+          columns.each { |col| empty_data[col] = [] }
+          return Rover::DataFrame.new(empty_data)
+        end
+
+        if results.is_a?(Rover::DataFrame)
+          # Already a dataframe
+          results
+        elsif results.first.is_a?(Hash)
+          # Array of hashes
+          Rover::DataFrame.new(results)
+        else
+          # Custom data structure - convert to hash format
+          data = results.map { |item| format_row(item, columns) }
+          Rover::DataFrame.new(data)
+        end
+      end
+
+      def format_row(item, columns)
+        if item.respond_to?(:to_h)
+          item.to_h.slice(*columns)
+        else
+          # Assume item is an array matching column order
+          columns.zip(item).to_h
+        end
+      end
+
+      # Mathematical utilities
+      def safe_divide(numerator, denominator)
+        return 0 if denominator.nil? || denominator.zero?
+
+        (numerator.to_f / denominator).round(2)
+      end
+
+      def percentage(part, total)
+        (safe_divide(part, total) * 100).round(0)
+      end
+
+      # Calculate average of two numbers
+      def average(first_value, second_value)
+        return 0 if first_value.nil? || second_value.nil?
+
+        ((first_value + second_value) / 2.0).round(1)
+      end
+    end
+  end
+end

data/lib/ruby_maat/analysis/churn.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module RubyMaat
+  module Analysis
+    module Churn
+      # Absolute churn analysis - code churn trends over time
+      class Absolute < BaseAnalysis
+        def analyze(dataset, _options = {})
+          # Group by date and sum churn metrics, count commits
+          results = {}
+
+          dataset.to_df.each_row do |row|
+            date = row["date"]
+            added = row["loc_added"] || 0
+            deleted = row["loc_deleted"] || 0
+            revision = row["revision"]
+
+            results[date] ||= {date: date, added: 0, deleted: 0, revisions: Set.new}
+            results[date][:added] += added
+            results[date][:deleted] += deleted
+            results[date][:revisions] << revision
+          end
+
+          # Convert to final format
+          final_results = results.values.map do |result|
+            {
+              date: result[:date],
+              added: result[:added],
+              deleted: result[:deleted],
+              commits: result[:revisions].size
+            }
+          end
+
+          # Sort by date
+          final_results.sort_by! { |r| r[:date] }
+
+          to_csv_data(final_results, %i[date added deleted commits])
+        end
+      end
+
+      # Author churn analysis - churn metrics per author
+      class ByAuthor < BaseAnalysis
+        def analyze(dataset, _options = {})
+          # Group by author and sum churn metrics, count commits
+          results = {}
+
+          dataset.to_df.each_row do |row|
+            author = row["author"]
+            added = row["loc_added"] || 0
+            deleted = row["loc_deleted"] || 0
+            revision = row["revision"]
+
+            results[author] ||= {author: author, added: 0, deleted: 0, revisions: Set.new}
+            results[author][:added] += added
+            results[author][:deleted] += deleted
+            results[author][:revisions] << revision
+          end
+
+          # Convert to final format
+          final_results = results.values.map do |result|
+            {
+              author: result[:author],
+              added: result[:added],
+              deleted: result[:deleted],
+              commits: result[:revisions].size
+            }
+          end
+
+          # Sort by total churn (added + deleted) descending, then by added lines descending, then by author
+          final_results.sort! do |a, b|
+            total_churn_b = b[:added] + b[:deleted]
+            total_churn_a = a[:added] + a[:deleted]
+            churn_comparison = total_churn_b <=> total_churn_a
+
+            if churn_comparison.zero?
+              added_comparison = b[:added] <=> a[:added]
+              added_comparison.zero? ? a[:author] <=> b[:author] : added_comparison
+            else
+              churn_comparison
+            end
+          end
+
+          to_csv_data(final_results, %i[author added deleted commits])
+        end
+      end
+
+      # Entity churn analysis - churn metrics per entity
+      class ByEntity < BaseAnalysis
+        def analyze(dataset, options = {})
+          min_revs = options[:min_revs] || 5
+
+          # Group by entity and sum churn metrics
+          results = {}
+
+          dataset.to_df.each_row do |row|
+            entity = row["entity"]
+            added = row["loc_added"] || 0
+            deleted = row["loc_deleted"] || 0
+            revision = row["revision"]
+
+            results[entity] ||= {entity: entity, added: 0, deleted: 0, revisions: Set.new}
+            results[entity][:added] += added
+            results[entity][:deleted] += deleted
+            results[entity][:revisions] << revision
+          end
+
+          # Filter by minimum revisions and format results
+          filtered_results = results.values.map do |result|
+            next if result[:revisions].size < min_revs
+
+            {
+              entity: result[:entity],
+              added: result[:added],
+              deleted: result[:deleted],
+              commits: result[:revisions].size
+            }
+          end.compact
+
+          # Sort by total churn descending
+          filtered_results.sort_by! { |r| -(r[:added] + r[:deleted]) }
+
+          to_csv_data(filtered_results, %i[entity added deleted commits])
+        end
+      end
+
+      # Ownership analysis - churn metrics per author per entity
+      class Ownership < BaseAnalysis
+        def analyze(dataset, _options = {})
+          # Group by entity and author
+          results = {}
+
+          dataset.to_df.each_row do |row|
+            entity = row["entity"]
+            author = row["author"]
+            added = row["loc_added"] || 0
+            deleted = row["loc_deleted"] || 0
+
+            key = [entity, author]
+            results[key] ||= {entity: entity, author: author, added: 0, deleted: 0}
+            results[key][:added] += added
+            results[key][:deleted] += deleted
+          end
+
+          # Sort by entity, then by total contribution descending
+          sorted_results = results.values.sort do |a, b|
+            entity_comparison = a[:entity] <=> b[:entity]
+            if entity_comparison.zero?
+              total_b = b[:added] + b[:deleted]
+              total_a = a[:added] + a[:deleted]
+              total_b <=> total_a
+            else
+              entity_comparison
+            end
+          end
+
+          to_csv_data(sorted_results, %i[entity author added deleted])
+        end
+      end
+
+      # Main developer analysis - primary contributor per entity (by lines)
+      class MainDeveloper < BaseAnalysis
+        def analyze(dataset, options = {})
+          min_revs = options[:min_revs] || 5
+
+          # Group contributions by entity and author
+          entity_contributions = {}
+          entity_totals = {}
+
+          dataset.to_df.each_row do |row|
+            entity = row["entity"]
+            author = row["author"]
+            added = row["loc_added"] || 0
+            row["loc_deleted"] || 0
+
+            entity_contributions[entity] ||= {}
+            entity_contributions[entity][author] ||= {added: 0, revisions: Set.new}
+            entity_contributions[entity][author][:added] += added
+            entity_contributions[entity][author][:revisions] << row["revision"]
+
+            entity_totals[entity] ||= 0
+            entity_totals[entity] += added
+          end
+
+          # Find main developer for each entity
+          results = []
+
+          entity_contributions.each do |entity, authors|
+            total_revisions = authors.values.map { |data| data[:revisions] }.reduce(Set.new, &:|).size
+            next if total_revisions < min_revs
+
+            # Find author with most added lines (tie-break by author name alphabetically)
+            main_author = authors.max_by { |author, data| [data[:added], author] }
+            next unless main_author
+
+            author_name, author_data = main_author
+            total_added = entity_totals[entity]
+            ownership = total_added.positive? ? (author_data[:added].to_f / total_added).round(2) : 0.0
+
+            results << {
+              entity: entity,
+              "main-dev": author_name,
+              added: author_data[:added],
+              "total-added": total_added,
+              ownership: ownership
+            }
+          end
+
+          # Sort by entity name
+          results.sort_by! { |r| r[:entity] }
+
+          to_csv_data(results, %i[entity main-dev added total-added ownership])
+        end
+      end
+
+      # Refactoring main developer - entities with frequent changes by main developer
+      class RefactoringMainDeveloper < BaseAnalysis
+        def analyze(dataset, options = {})
+          min_revs = options[:min_revs] || 5
+
+          # First find main developers
+          main_dev_analysis = MainDeveloper.new
+          main_devs_df = main_dev_analysis.analyze(dataset, options)
+
+          # Convert to hash for lookup
+          main_devs = {}
+          main_devs_df.each_row do |row|
+            main_devs[row[:entity]] = row[:main_dev]
+          end
+
+          # Count revisions by main developer per entity
+          results = []
+
+          main_devs.each do |entity, main_dev|
+            entity_data = dataset.to_df.filter { |row| row[:entity] == entity && row[:author] == main_dev }
+            main_dev_revisions = entity_data[:revision].uniq.size
+
+            next if main_dev_revisions < min_revs
+
+            results << {
+              entity: entity,
+              main_dev: main_dev,
+              added: main_dev_revisions, # Number of revisions by main dev
+              deleted: 0
+            }
+          end
+
+          # Sort by number of revisions descending
+          results.sort_by! { |r| -r[:added] }
+
+          to_csv_data(results, %i[entity main_dev added deleted])
+        end
+      end
+    end
+  end
+end

data/lib/ruby_maat/analysis/code_age.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module RubyMaat
+  module Analysis
+    # Code age analysis - measures how long since each entity was last modified
+    class CodeAge < BaseAnalysis
+      def analyze(dataset, options = {})
+        reference_date = options[:age_time_now] || Date.today
+
+        # Find the latest modification date for each entity
+        entity_latest_dates = {}
+
+        dataset.to_df.each_row do |row|
+          entity = row["entity"]
+          date = row["date"]
+
+          entity_latest_dates[entity] = date if entity_latest_dates[entity].nil? || date > entity_latest_dates[entity]
+        end
+
+        # Calculate age in months for each entity
+        results = entity_latest_dates.map do |entity, last_date|
+          months_old = calculate_months_between(last_date, reference_date)
+
+          {
+            entity: entity,
+            "age-months": months_old
+          }
+        end
+
+        # Sort by age descending (oldest first)
+        results.sort_by! { |r| -r[:"age-months"] }
+
+        to_csv_data(results, %i[entity age-months])
+      end
+
+      private
+
+      def calculate_months_between(start_date, end_date)
+        return 0 if start_date >= end_date
+
+        years = end_date.year - start_date.year
+        months = end_date.month - start_date.month
+
+        total_months = (years * 12) + months
+
+        # Adjust if the day hasn't been reached yet in the end month
+        total_months -= 1 if end_date.day < start_date.day
+
+        [total_months, 0].max
+      end
+    end
+  end
+end

data/lib/ruby_maat/analysis/commit_messages.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module RubyMaat
+  module Analysis
+    # Commit messages analysis - word frequency analysis of commit messages
+    class CommitMessages < BaseAnalysis
+      def analyze(dataset, options = {})
+        expression = options[:expression_to_match]
+
+        # Extract commit messages
+        messages = dataset.to_df[:message].compact
+
+        # Filter by regex if provided
+        if expression
+          regex = Regexp.new(expression, Regexp::IGNORECASE)
+          messages = messages.grep(regex)
+        end
+
+        # Tokenize and count words
+        word_frequencies = Hash.new(0)
+
+        messages.each do |message|
+          # Simple tokenization: split on whitespace and punctuation, convert to lowercase
+          words = message.downcase.split(/[^a-zA-Z0-9]+/).reject(&:empty?)
+
+          # Filter out common stop words and very short words
+          words = words.reject { |word| word.length < 3 || stop_words.include?(word) }
+
+          words.each { |word| word_frequencies[word] += 1 }
+        end
+
+        # Convert to results format
+        results = word_frequencies.map do |word, frequency|
+          {
+            word: word,
+            frequency: frequency
+          }
+        end
+
+        # Sort by frequency descending
+        results.sort_by! { |r| -r[:frequency] }
+
+        to_csv_data(results, %i[word frequency])
+      end
+
+      private
+
+      def stop_words
+        %w[
+          the and or but for with from that this will was are has have had been
+          can could would should may might must shall
+          not don't doesn't didn't won't wasn't weren't isn't aren't hasn't haven't
+          add fix update remove delete change modify refactor implement
+        ].to_set
+      end
+    end
+  end
+end

data/lib/ruby_maat/analysis/communication.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module RubyMaat
+  module Analysis
+    # Communication analysis - identifies developer collaboration patterns
+    # Based on Conway's Law: organizations design systems that mirror their communication structure
+    class Communication < BaseAnalysis
+      def analyze(dataset, options = {})
+        min_revs = options[:min_revs] || 5
+        min_shared_revs = options[:min_shared_revs] || 5
+
+        # Group entities by author to find their work domains
+        author_entities = {}
+
+        dataset.to_df.each_row do |row|
+          author = row[:author]
+          entity = row[:entity]
+
+          author_entities[author] ||= Set.new
+          author_entities[author] << entity
+        end
+
+        # Find pairs of authors who work on shared entities
+        results = []
+        author_pairs = author_entities.keys.combination(2)
+
+        author_pairs.each do |author1, author2|
+          shared_entities = author_entities[author1] & author_entities[author2]
+          next if shared_entities.size < min_shared_revs
+
+          author1_entities = author_entities[author1].size
+          author2_entities = author_entities[author2].size
+
+          # Communication strength based on shared work
+          avg_entities = average(author1_entities, author2_entities)
+          next if avg_entities < min_revs
+
+          communication_strength = percentage(shared_entities.size, avg_entities)
+
+          results << {
+            author: author1,
+            peer: author2,
+            shared: shared_entities.size,
+            average: avg_entities.ceil,
+            strength: communication_strength
+          }
+        end
+
+        # Sort by communication strength descending
+        results.sort_by! { |r| -r[:strength] }
+
+        to_csv_data(results, %i[author peer shared average strength])
+      end
+    end
+  end
+end