code-maat

A Python implementation of Code Maat by Adam Tornhill. Analyzes Git repository history to identify code coupling, change patterns, and team dynamics.

Overview

code-maat extracts insights from version control history:

• Temporal coupling: Files that change together frequently
• Code churn: Change frequency and stability metrics
• Knowledge distribution: Contributor patterns and code ownership
• Team coordination: Communication needs inferred from code changes

These analyses help identify architectural dependencies not visible in static code structure, inform code review priorities, and understand how teams interact with code over time.

Why Use This Tool?

Version control history contains information about code dependencies that aren't captured by static analysis. Files that frequently change together often share hidden coupling through business logic, data structures, or implicit contracts, even when they don't import each other directly.

Research shows that files with high temporal coupling have 2-10x higher defect rates (Predicting Faults from Cached History, MSR 2008). Understanding these patterns helps with:

• Prioritizing code review effort on coupled changes
• Identifying coordination requirements between team members
• Finding knowledge silos and ownership concentration
• Discovering stable versus volatile areas of the codebase

Installation

# Using pip
pip install code-maat

# From source with Poetry
git clone https://github.com/hydrosquall/code-maat.git
cd code-maat
poetry install

Quick Start

Generate a Git log in the required format:

cd your-project
git log --all -M -C --numstat --date=short --pretty=format:'--%h--%cd--%cn' > git.log

Run a coupling analysis to find files that frequently change together:

code-maat coupling git.log --min-coupling 50 --rows 10
# Or: python -m code_maat_python coupling git.log --min-coupling 50 --rows 10

Example output:

entity,coupled,degree,average-revs
src/models/user.py,src/views/profile.py,87,45
src/api/auth.py,src/middleware/session.py,76,32
src/utils/validators.py,src/forms/registration.py,65,28

This indicates user.py and profile.py change together in 87% of commits where either file changes, based on 45 average revisions. High coupling may indicate shared responsibilities or implicit dependencies worth reviewing.

Available Analyses

code-maat provides 17 analysis types:

See REFERENCE.md for detailed command documentation.

Documentation

• Setup Guide — Git log format, shell aliases, advanced options
• Use Cases & Best Practices — Application scenarios and analysis patterns
• Command Reference — Complete command documentation
• FAQ — Common questions and further reading
• Contributing — Contribution guidelines

License

GPL-3.0 — see LICENSE for details.

This project is inspired by and compatible with Code Maat by Adam Tornhill.