code-maat-python 0.1.0__tar.gz → 0.1.1__tar.gz

code_maat_python-0.1.1/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: code-maat-python
+Version: 0.1.1
+Summary: Modern Python tool for mining and analyzing version control system data
+License: GPL-3.0
+License-File: LICENSE
+Keywords: vcs,git,analysis,mining,coupling,churn
+Author: Cameron Yick
+Author-email: cameron.yick@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Version Control
+Requires-Dist: click (>=8.1.0,<9.0.0)
+Requires-Dist: pandas (>=2.0.0,<3.0.0)
+Requires-Dist: python-dateutil (>=2.8.0,<3.0.0)
+Project-URL: Homepage, https://github.com/hydrosquall/code-maat-python
+Project-URL: Repository, https://github.com/hydrosquall/code-maat-python
+Description-Content-Type: text/markdown
+
+# code-maat-python
+
+[![License: GPL-3.0](https://img.shields.io/badge/License-GPL%203.0-blue.svg)](https://opensource.org/licenses/GPL-3.0)
+[![Python: 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+A Python implementation of [Code Maat](https://github.com/adamtornhill/code-maat) by Adam Tornhill. Analyzes Git repository history to identify code coupling, change patterns, and team dynamics.
+
+## Overview
+
+code-maat-python 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](https://dl.acm.org/doi/10.1145/1453101.1453106)). 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
+
+```bash
+# Using pip
+pip install code-maat-python
+
+# From source with Poetry
+git clone https://github.com/hydrosquall/code-maat-python.git
+cd code-maat-python
+poetry install
+```
+
+## Quick Start
+
+Generate a Git log in the required format:
+
+```bash
+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:
+
+```bash
+code-maat-python coupling git.log --min-coupling 50 --rows 10
+# Or: python -m code_maat_python coupling git.log --min-coupling 50 --rows 10
+```
+
+Example output:
+```csv
+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-python provides 17 analysis types:
+
+| Command | Description | Use Case |
+|---------|-------------|----------|
+| `coupling` | Temporal coupling between file pairs | Identify files that frequently change together |
+| `soc` | Sum of coupling scores per entity | Aggregate coupling metric for prioritization |
+| `entity-churn` | Lines added/deleted per entity over time | Measure change volatility |
+| `age` | Time since last modification | Identify stable or abandoned code |
+| `communication` | Shared code changes between authors | Map coordination requirements |
+| `authors` | Number of distinct authors per entity | Measure knowledge distribution |
+| `entity-ownership` | Line contribution percentage by author | Determine primary code owners |
+| `main-dev` | Primary contributor by lines changed | Identify domain experts |
+| `main-dev-by-revs` | Primary contributor by commit count | Identify active maintainers |
+| `refactoring-main-dev` | Primary contributor to refactorings | Track code quality effort |
+| `revisions` | Commit count per entity | Find frequently modified files |
+| `abs-churn` | Aggregate churn over time windows | Track development activity trends |
+| `author-churn` | Per-author contribution over time | Analyze individual contribution patterns |
+| `entity-effort` | Commit count per entity | Quantify development effort distribution |
+| `fragmentation` | Author distribution per entity | Detect coordination overhead |
+| `summary` | Repository-wide statistics | Overview metrics |
+| `entities` | List of all tracked entities | Verify log parsing scope |
+
+See [REFERENCE.md](REFERENCE.md) for detailed command documentation.
+
+## Documentation
+
+- [Setup Guide](docs/SETUP.md) — Git log format, shell aliases, advanced options
+- [Use Cases & Best Practices](docs/USE_CASES.md) — Application scenarios and analysis patterns
+- [Command Reference](REFERENCE.md) — Complete command documentation
+- [FAQ](docs/FAQ.md) — Common questions and further reading
+- [Contributing](CONTRIBUTING.md) — Contribution guidelines
+
+## License
+
+GPL-3.0 — see [LICENSE](LICENSE) for details.
+
+This project is inspired by and compatible with [Code Maat](https://github.com/adamtornhill/code-maat) by Adam Tornhill.
+

code_maat_python-0.1.1/README.md

@@ -0,0 +1,106 @@
+# code-maat-python
+
+[![License: GPL-3.0](https://img.shields.io/badge/License-GPL%203.0-blue.svg)](https://opensource.org/licenses/GPL-3.0)
+[![Python: 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+A Python implementation of [Code Maat](https://github.com/adamtornhill/code-maat) by Adam Tornhill. Analyzes Git repository history to identify code coupling, change patterns, and team dynamics.
+
+## Overview
+
+code-maat-python 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](https://dl.acm.org/doi/10.1145/1453101.1453106)). 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
+
+```bash
+# Using pip
+pip install code-maat-python
+
+# From source with Poetry
+git clone https://github.com/hydrosquall/code-maat-python.git
+cd code-maat-python
+poetry install
+```
+
+## Quick Start
+
+Generate a Git log in the required format:
+
+```bash
+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:
+
+```bash
+code-maat-python coupling git.log --min-coupling 50 --rows 10
+# Or: python -m code_maat_python coupling git.log --min-coupling 50 --rows 10
+```
+
+Example output:
+```csv
+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-python provides 17 analysis types:
+
+| Command | Description | Use Case |
+|---------|-------------|----------|
+| `coupling` | Temporal coupling between file pairs | Identify files that frequently change together |
+| `soc` | Sum of coupling scores per entity | Aggregate coupling metric for prioritization |
+| `entity-churn` | Lines added/deleted per entity over time | Measure change volatility |
+| `age` | Time since last modification | Identify stable or abandoned code |
+| `communication` | Shared code changes between authors | Map coordination requirements |
+| `authors` | Number of distinct authors per entity | Measure knowledge distribution |
+| `entity-ownership` | Line contribution percentage by author | Determine primary code owners |
+| `main-dev` | Primary contributor by lines changed | Identify domain experts |
+| `main-dev-by-revs` | Primary contributor by commit count | Identify active maintainers |
+| `refactoring-main-dev` | Primary contributor to refactorings | Track code quality effort |
+| `revisions` | Commit count per entity | Find frequently modified files |
+| `abs-churn` | Aggregate churn over time windows | Track development activity trends |
+| `author-churn` | Per-author contribution over time | Analyze individual contribution patterns |
+| `entity-effort` | Commit count per entity | Quantify development effort distribution |
+| `fragmentation` | Author distribution per entity | Detect coordination overhead |
+| `summary` | Repository-wide statistics | Overview metrics |
+| `entities` | List of all tracked entities | Verify log parsing scope |
+
+See [REFERENCE.md](REFERENCE.md) for detailed command documentation.
+
+## Documentation
+
+- [Setup Guide](docs/SETUP.md) — Git log format, shell aliases, advanced options
+- [Use Cases & Best Practices](docs/USE_CASES.md) — Application scenarios and analysis patterns
+- [Command Reference](REFERENCE.md) — Complete command documentation
+- [FAQ](docs/FAQ.md) — Common questions and further reading
+- [Contributing](CONTRIBUTING.md) — Contribution guidelines
+
+## License
+
+GPL-3.0 — see [LICENSE](LICENSE) for details.
+
+This project is inspired by and compatible with [Code Maat](https://github.com/adamtornhill/code-maat) by Adam Tornhill.

{code_maat_python-0.1.0 → code_maat_python-0.1.1}/code_maat_python/__init__.py

@@ -4,7 +4,7 @@ code-maat-python: Modern Python tool for mining VCS data with pandas.
 A rewrite of Code Maat (by Adam Tornhill) using pandas for data analysis.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 __author__ = "Cameron Yick"
 __license__ = "GPL-3.0"
 

{code_maat_python-0.1.0 → code_maat_python-0.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "code-maat-python"
-version = "0.1.0"
+version = "0.1.1"
 description = "Modern Python tool for mining and analyzing version control system data"
 authors = ["Cameron Yick <cameron.yick@gmail.com>"]
 license = "GPL-3.0"