code-maat-python 0.1.0__py3-none-any.whl

code_maat_python/__init__.py

@@ -0,0 +1,12 @@
+"""
+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"
+__author__ = "Cameron Yick"
+__license__ = "GPL-3.0"
+
+# Version info
+VERSION = __version__

code_maat_python/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running code-maat-python as a module with python -m code_maat_python"""
+from code_maat_python.cli import main
+
+if __name__ == "__main__":
+    main()

code_maat_python/analyses/__init__.py

@@ -0,0 +1,39 @@
+"""Analysis modules for code-maat-python."""
+
+from code_maat_python.analyses.authors import analyze_authors
+from code_maat_python.analyses.churn import (
+    abs_churn,
+    author_churn,
+    entity_churn,
+    entity_ownership,
+    main_dev,
+    refactoring_main_dev,
+)
+from code_maat_python.analyses.coupling import analyze_coupling
+from code_maat_python.analyses.effort import (
+    entity_effort,
+    fragmentation,
+    main_dev_by_revs,
+)
+from code_maat_python.analyses.entities import analyze_entities
+from code_maat_python.analyses.revisions import analyze_revisions
+from code_maat_python.analyses.soc import analyze_soc
+from code_maat_python.analyses.summary import analyze_summary
+
+__all__ = [
+    "abs_churn",
+    "analyze_authors",
+    "analyze_coupling",
+    "analyze_entities",
+    "analyze_revisions",
+    "analyze_soc",
+    "analyze_summary",
+    "author_churn",
+    "entity_churn",
+    "entity_effort",
+    "entity_ownership",
+    "fragmentation",
+    "main_dev",
+    "main_dev_by_revs",
+    "refactoring_main_dev",
+]

code_maat_python/analyses/age.py

@@ -0,0 +1,101 @@
+"""Code age analysis for code-maat-python."""
+
+import pandas as pd
+
+from code_maat_python.parser import GitLogSchema
+
+
+def code_age(df: pd.DataFrame, reference_date: pd.Timestamp | None = None) -> pd.DataFrame:
+    """Calculate age of entities in months since last modification.
+
+    This analysis helps identify stale code that hasn't been modified recently,
+    which may indicate technical debt, abandoned features, or stable components.
+
+    Args:
+        df: DataFrame with GitLogSchema columns (entity, rev, author, date, loc_added, loc_deleted).
+            Multiple commits to the same entity are allowed; the latest date is used.
+        reference_date: Reference date for age calculation. If None, uses current date.
+            Should be timezone-naive or match the timezone of dates in df.
+
+    Returns:
+        DataFrame with columns:
+            - entity: File path (str)
+            - age-months: Number of months since last modification (int)
+        Sorted by age-months descending (oldest entities first).
+
+        For empty input, returns empty DataFrame with correct schema.
+
+    Raises:
+        ValueError: If df doesn't have required columns (entity, date).
+
+    Example:
+        >>> import pandas as pd
+        >>> from code_maat_python.analyses.age import code_age
+        >>> from code_maat_python.parser import parse_git_log
+        >>>
+        >>> # Parse git log
+        >>> df = parse_git_log("git.log")
+        >>>
+        >>> # Calculate age using current date
+        >>> result = code_age(df)
+        >>> print(result.head())
+           entity           age-months
+        0  legacy_file.py   24
+        1  old_module.py    18
+        2  stable.py        12
+        >>>
+        >>> # Calculate age with custom reference date
+        >>> ref_date = pd.Timestamp('2023-12-31')
+        >>> result = code_age(df, reference_date=ref_date)
+        >>> print(result.head())
+           entity           age-months
+        0  legacy_file.py   18
+        1  old_module.py    12
+
+    Note:
+        Age calculation uses 30.44 days per month (365.25/12) for accuracy.
+        Ages are rounded to the nearest whole month.
+    """
+    # 1. Handle empty DataFrame
+    if df.empty:
+        return pd.DataFrame(columns=["entity", "age-months"])
+
+    # 2. Validate required columns
+    required_cols = {GitLogSchema.ENTITY, GitLogSchema.DATE}
+    if not required_cols.issubset(df.columns):
+        missing = required_cols - set(df.columns)
+        raise ValueError(f"DataFrame missing required columns: {missing}")
+
+    # 3. Set reference_date to now if None
+    if reference_date is None:
+        reference_date = pd.Timestamp.now()
+
+    # 4. Ensure date column is datetime
+    if not pd.api.types.is_datetime64_any_dtype(df[GitLogSchema.DATE]):
+        df = df.copy()
+        df[GitLogSchema.DATE] = pd.to_datetime(df[GitLogSchema.DATE])
+
+    # 5. Find last modification date per entity (groupby + max)
+    last_dates = df.groupby(GitLogSchema.ENTITY, observed=True)[GitLogSchema.DATE].max()
+
+    # 6. Calculate age in months: (reference_date - last_date).days / 30.44
+    age_days = (reference_date - last_dates).dt.days
+    age_months = age_days / 30.44
+
+    # 7. Round to nearest month and convert to int
+    age_months = age_months.round().astype(int)
+
+    # 8. Create result DataFrame
+    result = pd.DataFrame(
+        {
+            "entity": last_dates.index,
+            "age-months": age_months.values,
+        }
+    )
+
+    # 9. Sort by age descending (oldest first)
+    result = result.sort_values(by=["age-months"], ascending=False)
+
+    # 10. Reset index and return with explicit column ordering
+    result = result.reset_index(drop=True)
+    return result[["entity", "age-months"]]

code_maat_python/analyses/authors.py

@@ -0,0 +1,60 @@
+"""Author analysis for code-maat-python.
+
+Analyzes distinct authors per entity with revision counts.
+"""
+
+import pandas as pd
+
+from code_maat_python.parser import GitLogSchema
+
+
+def analyze_authors(df: pd.DataFrame) -> pd.DataFrame:
+    """Count distinct authors per entity with revision counts.
+
+    Identifies how many authors have worked on each entity and how
+    many revisions each entity has undergone.
+
+    Args:
+        df: DataFrame with columns: entity, rev, author, date, loc_added, loc_deleted
+
+    Returns:
+        DataFrame with columns:
+            - entity: File or module path
+            - n-authors: Number of distinct authors
+            - n-revs: Number of revisions
+
+    Example:
+        >>> data = [
+        ...     {'entity': 'src/main.py', 'rev': '1', 'author': 'Alice', 'date': '2023-01-01'},
+        ...     {'entity': 'src/main.py', 'rev': '2', 'author': 'Bob', 'date': '2023-01-02'},
+        ...     {'entity': 'src/utils.py', 'rev': '1', 'author': 'Alice', 'date': '2023-01-01'},
+        ... ]
+        >>> df = pd.DataFrame(data)
+        >>> result = analyze_authors(df)
+        >>> print(result)
+                  entity  n-authors  n-revs
+        0    src/main.py          2       2
+        1   src/utils.py          1       1
+    """
+    # Handle empty DataFrame
+    if df.empty:
+        return pd.DataFrame(columns=["entity", "n-authors", "n-revs"])
+
+    # Group by entity and calculate metrics
+    result = (
+        df.groupby(GitLogSchema.ENTITY, observed=True)
+        .agg(
+            **{
+                "n-authors": (GitLogSchema.AUTHOR, "nunique"),
+                "n-revs": (GitLogSchema.REV, "nunique"),
+            }
+        )
+        .reset_index()
+    )
+
+    # Sort by number of authors descending, then by entity name
+    result = result.sort_values(
+        by=["n-authors", GitLogSchema.ENTITY], ascending=[False, True]
+    )
+
+    return result.reset_index(drop=True)

code_maat_python/analyses/churn.py

@@ -0,0 +1,353 @@
+"""Churn analysis for code-maat-python.
+
+Analyzes code churn metrics including lines added/deleted by date, author,
+and entity, as well as main developer identification.
+"""
+
+import pandas as pd
+
+from code_maat_python.parser import GitLogSchema
+
+
+def abs_churn(df: pd.DataFrame) -> pd.DataFrame:
+    """Calculate absolute code churn per date.
+
+    Calculates the total lines added and deleted for each date in the
+    commit history. Only dates with commits are included.
+
+    Args:
+        df: DataFrame with columns: entity, rev, author, date, loc_added, loc_deleted
+
+    Returns:
+        DataFrame with columns:
+            - date: Commit date
+            - added: Total lines added on that date
+            - deleted: Total lines deleted on that date
+            - commits: Number of commits on that date
+
+    Example:
+        >>> data = [
+        ...     {'entity': 'A', 'rev': '1', 'author': 'Dev1', 'date': '2023-01-01',
+        ...      'loc_added': 10, 'loc_deleted': 5},
+        ...     {'entity': 'B', 'rev': '2', 'author': 'Dev2', 'date': '2023-01-01',
+        ...      'loc_added': 15, 'loc_deleted': 3},
+        ... ]
+        >>> df = pd.DataFrame(data)
+        >>> result = abs_churn(df)
+    """
+    # Handle empty DataFrame
+    if df.empty:
+        return pd.DataFrame(columns=["date", "added", "deleted", "commits"])
+
+    # Group by date and aggregate churn metrics
+    result = (
+        df.groupby(GitLogSchema.DATE, observed=True)
+        .agg(
+            added=(GitLogSchema.LOC_ADDED, "sum"),
+            deleted=(GitLogSchema.LOC_DELETED, "sum"),
+            commits=(GitLogSchema.REV, "nunique"),
+        )
+        .reset_index()
+    )
+
+    # Sort by date ascending
+    result = result.sort_values(by=[GitLogSchema.DATE], ascending=True)
+
+    return result.reset_index(drop=True)
+
+
+def author_churn(df: pd.DataFrame) -> pd.DataFrame:
+    """Calculate total churn per author.
+
+    Sums the total lines added and deleted for each contributing author
+    across all entities and commits.
+
+    Args:
+        df: DataFrame with columns: entity, rev, author, date, loc_added, loc_deleted
+
+    Returns:
+        DataFrame with columns:
+            - author: Author name
+            - added: Total lines added by author
+            - deleted: Total lines deleted by author
+            - commits: Number of commits by author
+
+    Example:
+        >>> data = [
+        ...     {'entity': 'A', 'rev': '1', 'author': 'Alice', 'date': '2023-01-01',
+        ...      'loc_added': 10, 'loc_deleted': 5},
+        ...     {'entity': 'B', 'rev': '2', 'author': 'Alice', 'date': '2023-01-02',
+        ...      'loc_added': 15, 'loc_deleted': 3},
+        ... ]
+        >>> df = pd.DataFrame(data)
+        >>> result = author_churn(df)
+    """
+    # Handle empty DataFrame
+    if df.empty:
+        return pd.DataFrame(columns=["author", "added", "deleted", "commits"])
+
+    # Group by author and aggregate churn metrics
+    result = (
+        df.groupby(GitLogSchema.AUTHOR, observed=True)
+        .agg(
+            added=(GitLogSchema.LOC_ADDED, "sum"),
+            deleted=(GitLogSchema.LOC_DELETED, "sum"),
+            commits=(GitLogSchema.REV, "nunique"),
+        )
+        .reset_index()
+    )
+
+    # Sort by author name ascending
+    result = result.sort_values(by=[GitLogSchema.AUTHOR], ascending=True)
+
+    return result.reset_index(drop=True)
+
+
+def entity_churn(df: pd.DataFrame) -> pd.DataFrame:
+    """Calculate absolute churn per entity.
+
+    Returns the total lines added and deleted for each entity (file).
+    Entities are sorted by lines added in descending order, as this is
+    a better predictor of post-release defects.
+
+    Args:
+        df: DataFrame with columns: entity, rev, author, date, loc_added, loc_deleted
+
+    Returns:
+        DataFrame with columns:
+            - entity: File or module path
+            - added: Total lines added to entity
+            - deleted: Total lines deleted from entity
+            - commits: Number of commits affecting entity
+
+    Example:
+        >>> data = [
+        ...     {'entity': 'main.py', 'rev': '1', 'author': 'Dev1', 'date': '2023-01-01',
+        ...      'loc_added': 100, 'loc_deleted': 10},
+        ...     {'entity': 'main.py', 'rev': '2', 'author': 'Dev2', 'date': '2023-01-02',
+        ...      'loc_added': 50, 'loc_deleted': 5},
+        ... ]
+        >>> df = pd.DataFrame(data)
+        >>> result = entity_churn(df)
+    """
+    # Handle empty DataFrame
+    if df.empty:
+        return pd.DataFrame(columns=["entity", "added", "deleted", "commits"])
+
+    # Group by entity and aggregate churn metrics
+    result = (
+        df.groupby(GitLogSchema.ENTITY, observed=True)
+        .agg(
+            added=(GitLogSchema.LOC_ADDED, "sum"),
+            deleted=(GitLogSchema.LOC_DELETED, "sum"),
+            commits=(GitLogSchema.REV, "nunique"),
+        )
+        .reset_index()
+    )
+
+    # Sort by lines added descending (better predictor of defects)
+    result = result.sort_values(by=["added"], ascending=False)
+
+    return result.reset_index(drop=True)
+
+
+def entity_ownership(df: pd.DataFrame) -> pd.DataFrame:
+    """Calculate ownership of each entity by author based on churn.
+
+    Returns a table showing how much each author has contributed to each
+    entity in terms of lines added and deleted. This helps identify code
+    ownership patterns.
+
+    Args:
+        df: DataFrame with columns: entity, rev, author, date, loc_added, loc_deleted
+
+    Returns:
+        DataFrame with columns:
+            - entity: File or module path
+            - author: Author name
+            - added: Lines added by author to entity
+            - deleted: Lines deleted by author from entity
+
+    Example:
+        >>> data = [
+        ...     {'entity': 'main.py', 'rev': '1', 'author': 'Alice', 'date': '2023-01-01',
+        ...      'loc_added': 100, 'loc_deleted': 10},
+        ...     {'entity': 'main.py', 'rev': '2', 'author': 'Bob', 'date': '2023-01-02',
+        ...      'loc_added': 50, 'loc_deleted': 5},
+        ... ]
+        >>> df = pd.DataFrame(data)
+        >>> result = entity_ownership(df)
+    """
+    # Handle empty DataFrame
+    if df.empty:
+        return pd.DataFrame(columns=["entity", "author", "added", "deleted"])
+
+    # Group by entity and author, aggregate churn metrics
+    result = (
+        df.groupby([GitLogSchema.ENTITY, GitLogSchema.AUTHOR], observed=True)
+        .agg(
+            added=(GitLogSchema.LOC_ADDED, "sum"),
+            deleted=(GitLogSchema.LOC_DELETED, "sum"),
+        )
+        .reset_index()
+    )
+
+    # Sort by entity ascending
+    result = result.sort_values(by=[GitLogSchema.ENTITY], ascending=True)
+
+    return result.reset_index(drop=True)
+
+
+def main_dev(df: pd.DataFrame) -> pd.DataFrame:
+    """Identify the main developer of each entity by lines added.
+
+    The main developer is the author who has contributed the most lines
+    of code (added) to each entity. Returns ownership percentage.
+
+    Args:
+        df: DataFrame with columns: entity, rev, author, date, loc_added, loc_deleted
+
+    Returns:
+        DataFrame with columns:
+            - entity: File or module path
+            - main-dev: Primary developer name
+            - added: Lines added by main developer
+            - total-added: Total lines added to entity
+            - ownership: Ownership percentage (0-100)
+
+    Example:
+        >>> data = [
+        ...     {'entity': 'main.py', 'rev': '1', 'author': 'Alice', 'date': '2023-01-01',
+        ...      'loc_added': 100, 'loc_deleted': 10},
+        ...     {'entity': 'main.py', 'rev': '2', 'author': 'Bob', 'date': '2023-01-02',
+        ...      'loc_added': 50, 'loc_deleted': 5},
+        ... ]
+        >>> df = pd.DataFrame(data)
+        >>> result = main_dev(df)
+    """
+    # Handle empty DataFrame
+    if df.empty:
+        return pd.DataFrame(columns=["entity", "main-dev", "added", "total-added", "ownership"])
+
+    # Calculate lines added by each author per entity
+    entity_author_added = (
+        df.groupby([GitLogSchema.ENTITY, GitLogSchema.AUTHOR], observed=True)[
+            GitLogSchema.LOC_ADDED
+        ]
+        .sum()
+        .reset_index()
+    )
+
+    # Calculate total lines added per entity
+    entity_total_added = (
+        df.groupby(GitLogSchema.ENTITY, observed=True)[GitLogSchema.LOC_ADDED]
+        .sum()
+        .reset_index()
+        .rename(columns={GitLogSchema.LOC_ADDED: "total-added"})
+    )
+
+    # Find the author with max lines added per entity
+    main_devs = (
+        entity_author_added.loc[
+            entity_author_added.groupby(GitLogSchema.ENTITY, observed=True)[
+                GitLogSchema.LOC_ADDED
+            ].idxmax()
+        ]
+        .rename(
+            columns={
+                GitLogSchema.AUTHOR: "main-dev",
+                GitLogSchema.LOC_ADDED: "added",
+            }
+        )
+        .reset_index(drop=True)
+    )
+
+    # Merge with total added
+    result = main_devs.merge(entity_total_added, on=GitLogSchema.ENTITY)
+
+    # Calculate ownership percentage
+    # Use max(total, 1) to handle entities with only deletions
+    result["ownership"] = (result["added"] / result["total-added"].clip(lower=1) * 100).round(2)
+
+    # Sort by entity ascending
+    result = result.sort_values(by=[GitLogSchema.ENTITY], ascending=True)
+
+    return result.reset_index(drop=True)
+
+
+def refactoring_main_dev(df: pd.DataFrame) -> pd.DataFrame:
+    """Identify the main developer of each entity by lines removed.
+
+    This alternative calculation identifies the main developer as the
+    author who has removed the most lines of code. The idea is that
+    removing code represents more active design choices and refactoring.
+
+    Args:
+        df: DataFrame with columns: entity, rev, author, date, loc_added, loc_deleted
+
+    Returns:
+        DataFrame with columns:
+            - entity: File or module path
+            - main-dev: Primary developer name
+            - removed: Lines removed by main developer
+            - total-removed: Total lines removed from entity
+            - ownership: Ownership percentage (0-100)
+
+    Example:
+        >>> data = [
+        ...     {'entity': 'main.py', 'rev': '1', 'author': 'Alice', 'date': '2023-01-01',
+        ...      'loc_added': 10, 'loc_deleted': 100},
+        ...     {'entity': 'main.py', 'rev': '2', 'author': 'Bob', 'date': '2023-01-02',
+        ...      'loc_added': 5, 'loc_deleted': 50},
+        ... ]
+        >>> df = pd.DataFrame(data)
+        >>> result = refactoring_main_dev(df)
+    """
+    # Handle empty DataFrame
+    if df.empty:
+        return pd.DataFrame(columns=["entity", "main-dev", "removed", "total-removed", "ownership"])
+
+    # Calculate lines deleted by each author per entity
+    entity_author_deleted = (
+        df.groupby([GitLogSchema.ENTITY, GitLogSchema.AUTHOR], observed=True)[
+            GitLogSchema.LOC_DELETED
+        ]
+        .sum()
+        .reset_index()
+    )
+
+    # Calculate total lines deleted per entity
+    entity_total_deleted = (
+        df.groupby(GitLogSchema.ENTITY, observed=True)[GitLogSchema.LOC_DELETED]
+        .sum()
+        .reset_index()
+        .rename(columns={GitLogSchema.LOC_DELETED: "total-removed"})
+    )
+
+    # Find the author with max lines deleted per entity
+    main_devs = (
+        entity_author_deleted.loc[
+            entity_author_deleted.groupby(GitLogSchema.ENTITY, observed=True)[
+                GitLogSchema.LOC_DELETED
+            ].idxmax()
+        ]
+        .rename(
+            columns={
+                GitLogSchema.AUTHOR: "main-dev",
+                GitLogSchema.LOC_DELETED: "removed",
+            }
+        )
+        .reset_index(drop=True)
+    )
+
+    # Merge with total deleted
+    result = main_devs.merge(entity_total_deleted, on=GitLogSchema.ENTITY)
+
+    # Calculate ownership percentage
+    # Use max(total, 1) to handle entities with only additions
+    result["ownership"] = (result["removed"] / result["total-removed"].clip(lower=1) * 100).round(2)
+
+    # Sort by entity ascending
+    result = result.sort_values(by=[GitLogSchema.ENTITY], ascending=True)
+
+    return result.reset_index(drop=True)