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

code_maat_python/analyses/communication.py

@@ -0,0 +1,151 @@
+"""Communication analysis for code-maat-python."""
+
+from itertools import combinations
+
+import pandas as pd
+
+from code_maat_python.parser import GitLogSchema
+
+
+def communication(df: pd.DataFrame, min_shared: int = 5, min_coupling: int = 30) -> pd.DataFrame:
+    """Calculate communication needs between developers based on shared entities.
+
+    This analysis identifies developers who work on the same code files, indicating
+    a need for communication and coordination. The strength metric normalizes by
+    each developer's total workload to avoid bias toward highly active developers.
+
+    CRITICAL IMPLEMENTATION NOTE: Self-pairs (author, author) are used internally
+    to track each author's total entity count for normalization, but are excluded
+    from the final output.
+
+    Args:
+        df: DataFrame with GitLogSchema columns (entity, rev, author, date, loc_added, loc_deleted).
+            Multiple commits to the same entity by the same author are deduplicated.
+        min_shared: Minimum number of shared entities required for a pair to be included.
+            Default is 5.
+        min_coupling: Minimum coupling strength percentage required (0-100).
+            Default is 30. Strength is calculated as:
+            (shared_entities / average_total_entities) * 100
+
+    Returns:
+        DataFrame with columns:
+            - author: First developer name (str), alphabetically sorted
+            - peer: Second developer name (str), alphabetically sorted
+            - shared: Number of entities both authors worked on (int)
+            - strength: Communication coupling strength percentage (int)
+        Sorted by strength descending, then shared descending.
+
+        Self-pairs (author, author) are NOT included in output.
+        For empty input or no pairs meeting thresholds, returns empty DataFrame with correct schema.
+
+    Raises:
+        ValueError: If df doesn't have required columns (entity, author).
+
+    Example:
+        >>> import pandas as pd
+        >>> from code_maat_python.analyses.communication import communication
+        >>> from code_maat_python.parser import parse_git_log
+        >>>
+        >>> # Parse git log
+        >>> df = parse_git_log("git.log")
+        >>>
+        >>> # Find developer pairs with high communication needs
+        >>> result = communication(df, min_shared=5, min_coupling=30)
+        >>> print(result.head())
+           author    peer  shared  strength
+        0  Alice     Bob   12      85
+        1  Alice     Charlie 8    60
+        2  Bob       Charlie 6    45
+        >>>
+        >>> # Use stricter thresholds
+        >>> result = communication(df, min_shared=10, min_coupling=50)
+
+    Note:
+        Strength calculation uses self-pairs internally to normalize:
+        - Self-pair (A, A) tracks total entities touched by author A
+        - Regular pair (A, B) tracks shared entities between A and B
+        - Strength = (shared / ((A_total + B_total) / 2)) * 100
+        - Self-pairs are excluded from final results
+    """
+    # 1. Handle empty DataFrame
+    if df.empty:
+        return pd.DataFrame(columns=["author", "peer", "shared", "strength"])
+
+    # 2. Validate required columns
+    required_cols = {GitLogSchema.ENTITY, GitLogSchema.AUTHOR}
+    if not required_cols.issubset(df.columns):
+        missing = required_cols - set(df.columns)
+        raise ValueError(f"DataFrame missing required columns: {missing}")
+
+    # 3. Get unique author-entity pairs (deduplicate multiple commits)
+    unique_pairs = (
+        df[[GitLogSchema.ENTITY, GitLogSchema.AUTHOR]].drop_duplicates().reset_index(drop=True)
+    )
+
+    # 4. Track pairs: (author1, author2) -> shared entity count
+    # Also track self-pairs: (author, author) -> total entity count for that author
+    pair_counts: dict[tuple[str, str], int] = {}
+
+    # 5. Calculate total entities per author (self-pairs for normalization)
+    author_totals = (
+        unique_pairs.groupby(GitLogSchema.AUTHOR, observed=True)[GitLogSchema.ENTITY]
+        .nunique()
+        .to_dict()
+    )
+    for author, total in author_totals.items():
+        pair_counts[(author, author)] = total
+
+    # 6. Find shared entities between author pairs
+    for _entity, group in unique_pairs.groupby(GitLogSchema.ENTITY, observed=True):
+        authors = sorted(group[GitLogSchema.AUTHOR].unique())
+
+        # Generate all pairs (excluding self-pairs for shared counts)
+        for author1, author2 in combinations(authors, 2):
+            # Keep alphabetical order
+            pair_key = (author1, author2)
+            pair_counts[pair_key] = pair_counts.get(pair_key, 0) + 1
+
+    # 7. Calculate communication strength for each pair
+    results = []
+    for (author1, author2), shared_count in pair_counts.items():
+        # Skip self-pairs in output (they were only for normalization)
+        if author1 == author2:
+            continue
+
+        # Get total entities for each author from self-pairs
+        author1_total = pair_counts.get((author1, author1), 0)
+        author2_total = pair_counts.get((author2, author2), 0)
+
+        # Calculate average work
+        avg_work = (author1_total + author2_total) / 2
+
+        # Protect against division by zero
+        if avg_work == 0:
+            continue
+
+        # Calculate strength percentage and round
+        strength = int(round((shared_count / avg_work) * 100))
+
+        # Apply filters (using rounded strength)
+        if shared_count >= min_shared and strength >= min_coupling:
+            results.append(
+                {
+                    "author": author1,
+                    "peer": author2,
+                    "shared": shared_count,
+                    "strength": strength,
+                }
+            )
+
+    # 8. Create result DataFrame
+    if not results:
+        return pd.DataFrame(columns=["author", "peer", "shared", "strength"])
+
+    result_df = pd.DataFrame(results)
+
+    # 9. Sort by strength descending, then shared descending
+    result_df = result_df.sort_values(by=["strength", "shared"], ascending=[False, False])
+
+    # 10. Reset index and return with explicit column ordering
+    result_df = result_df.reset_index(drop=True)
+    return result_df[["author", "peer", "shared", "strength"]]

code_maat_python/analyses/coupling.py

@@ -0,0 +1,136 @@
+"""Logical coupling analysis for code-maat-python.
+
+Calculate logical coupling between files based on co-change frequency.
+"""
+
+from collections import Counter
+from itertools import combinations
+
+import pandas as pd
+
+from code_maat_python.parser import GitLogSchema
+
+
+def analyze_coupling(
+    df: pd.DataFrame,
+    min_revs: int = 5,
+    min_shared_revs: int = 5,
+    min_coupling: int = 30,
+    max_coupling: int = 100,
+    max_changeset_size: int = 30,
+) -> pd.DataFrame:
+    """Calculate logical coupling between files.
+
+    Logical coupling identifies files that frequently change together,
+    which may indicate hidden dependencies, architectural issues, or
+    related functionality that should be refactored together.
+
+    Algorithm (from PYTHON_MIGRATION_PLAN.md lines 99-296):
+    1. Group commits by revision
+    2. Filter out large commits (> max_changeset_size files) BEFORE processing
+    3. Generate all 2-combinations of files per commit using itertools.combinations
+    4. Count co-occurrence frequencies
+    5. Calculate coupling degree: (shared_revs / avg_revs) * 100
+    6. Apply thresholds: min_revs, min_shared_revs, min_coupling, max_coupling
+
+    Critical notes:
+    - Large commits must be filtered BEFORE generating pairs (performance)
+    - Use itertools.combinations(files, 2) for efficiency
+    - Duplicate pairs are automatically handled by combinations (A,B) not (B,A)
+    - Average revisions = (entity1_revs + entity2_revs) / 2
+
+    Args:
+        df: DataFrame with columns: entity, rev, author, date, loc_added, loc_deleted
+        min_revs: Minimum average number of revisions for both modules (default: 5)
+        min_shared_revs: Minimum shared revisions between modules (default: 5)
+        min_coupling: Minimum coupling percentage threshold (default: 30)
+        max_coupling: Maximum coupling percentage threshold (default: 100)
+        max_changeset_size: Maximum number of files in a commit to consider (default: 30)
+
+    Returns:
+        DataFrame with columns:
+            - entity: First file in the coupled pair
+            - coupled: Second file in the coupled pair
+            - degree: Coupling degree as integer percentage (0-100)
+            - average-revs: Average number of revisions as integer
+        Sorted by degree descending, then by entity and coupled names.
+
+    Example:
+        >>> data = [
+        ...     {'entity': 'src/main.py', 'rev': '1', 'author': 'Alice', 'date': '2023-01-01'},
+        ...     {'entity': 'src/utils.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': '2', 'author': 'Bob', 'date': '2023-01-02'},
+        ... ]
+        >>> df = pd.DataFrame(data)
+        >>> result = analyze_coupling(df, min_revs=1, min_shared_revs=1, min_coupling=50)
+        >>> print(result)
+                 entity        coupled  degree  average-revs
+        0   src/main.py  src/utils.py     100             2
+    """
+    # Handle empty DataFrame
+    if df.empty:
+        return pd.DataFrame(columns=["entity", "coupled", "degree", "average-revs"])
+
+    # 1. Filter large commits BEFORE processing (critical for performance)
+    commit_sizes = df.groupby(GitLogSchema.REV, observed=True)[GitLogSchema.ENTITY].count()
+    valid_revs = commit_sizes[commit_sizes <= max_changeset_size].index
+    df_filtered = df[df[GitLogSchema.REV].isin(valid_revs)]
+
+    if df_filtered.empty:
+        return pd.DataFrame(columns=["entity", "coupled", "degree", "average-revs"])
+
+    # 2. Generate file pairs per commit using itertools.combinations
+    pairs: list[tuple[str, str]] = []
+    for rev, group in df_filtered.groupby(GitLogSchema.REV, observed=True):
+        files = sorted(group[GitLogSchema.ENTITY].unique())
+        if len(files) >= 2:
+            # Generate all 2-combinations (automatically handles duplicates)
+            pairs.extend(combinations(files, 2))
+
+    if not pairs:
+        return pd.DataFrame(columns=["entity", "coupled", "degree", "average-revs"])
+
+    # 3. Count co-occurrences
+    pair_counts = Counter(pairs)
+
+    # 4. Count revisions per module
+    module_revs = (
+        df_filtered.groupby(GitLogSchema.ENTITY, observed=True)[GitLogSchema.REV]
+        .nunique()
+        .to_dict()
+    )
+
+    # 5. Calculate coupling degree and apply thresholds
+    results = []
+    for (entity1, entity2), shared_revs in pair_counts.items():
+        entity1_revs = module_revs[entity1]
+        entity2_revs = module_revs[entity2]
+        avg_revs = (entity1_revs + entity2_revs) / 2.0
+        coupling = (shared_revs / avg_revs) * 100.0
+
+        # 6. Apply all thresholds
+        if (
+            avg_revs >= min_revs
+            and shared_revs >= min_shared_revs
+            and min_coupling <= coupling <= max_coupling
+        ):
+            results.append(
+                {
+                    "entity": entity1,
+                    "coupled": entity2,
+                    "degree": int(coupling),
+                    "average-revs": int(avg_revs),
+                }
+            )
+
+    if not results:
+        return pd.DataFrame(columns=["entity", "coupled", "degree", "average-revs"])
+
+    # Sort by degree descending, then by entity and coupled names
+    result_df = pd.DataFrame(results)
+    result_df = result_df.sort_values(
+        ["degree", "entity", "coupled"], ascending=[False, True, True]
+    )
+
+    return result_df.reset_index(drop=True)

code_maat_python/analyses/effort.py

@@ -0,0 +1,210 @@
+"""Effort analysis for code-maat-python.
+
+Analyzes author contributions by revision count and calculates
+code fragmentation metrics.
+"""
+
+import pandas as pd
+
+from code_maat_python.parser import GitLogSchema
+from code_maat_python.utils.math import fractal_value
+
+
+def entity_effort(df: pd.DataFrame) -> pd.DataFrame:
+    """Calculate author contribution to each entity by revision count.
+
+    Identifies how many revisions each author contributed to each entity,
+    providing a measure of effort that works for all VCS systems.
+
+    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
+            - author-revs: Number of revisions by author for this entity
+            - total-revs: Total revisions for this entity
+
+    Example:
+        >>> data = [
+        ...     {'entity': 'main.py', 'rev': '1', 'author': 'Alice', 'date': '2023-01-01'},
+        ...     {'entity': 'main.py', 'rev': '2', 'author': 'Alice', 'date': '2023-01-02'},
+        ...     {'entity': 'main.py', 'rev': '3', 'author': 'Bob', 'date': '2023-01-03'},
+        ... ]
+        >>> df = pd.DataFrame(data)
+        >>> result = entity_effort(df)
+    """
+    # Handle empty DataFrame
+    if df.empty:
+        return pd.DataFrame(columns=["entity", "author", "author-revs", "total-revs"])
+
+    # Count revisions per entity-author combination
+    entity_author_revs = (
+        df.groupby([GitLogSchema.ENTITY, GitLogSchema.AUTHOR], observed=True)[GitLogSchema.REV]
+        .nunique()
+        .reset_index()
+        .rename(columns={GitLogSchema.REV: "author-revs"})
+    )
+
+    # Count total revisions per entity
+    entity_total_revs = (
+        df.groupby(GitLogSchema.ENTITY, observed=True)[GitLogSchema.REV]
+        .nunique()
+        .reset_index()
+        .rename(columns={GitLogSchema.REV: "total-revs"})
+    )
+
+    # Merge to get complete picture
+    result = entity_author_revs.merge(entity_total_revs, on=GitLogSchema.ENTITY)
+
+    # Sort by entity ascending, then by author-revs descending (stable sort)
+    # This matches the Clojure implementation which uses stable sort
+    result = result.sort_values(by=["author-revs"], ascending=False)  # First sort by revs
+    result = result.sort_values(
+        by=[GitLogSchema.ENTITY], ascending=True, kind="stable"
+    )  # Then stable sort by entity
+
+    return result.reset_index(drop=True)
+
+
+def main_dev_by_revs(df: pd.DataFrame) -> pd.DataFrame:
+    """Identify the main developer of each entity by revision count.
+
+    The main developer is the author who has contributed the most revisions
+    to each entity. Returns ownership percentage based on revision count.
+
+    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: Number of revisions by main developer
+            - total-added: Total revisions for entity
+            - ownership: Ownership percentage (0-100)
+
+    Example:
+        >>> data = [
+        ...     {'entity': 'main.py', 'rev': '1', 'author': 'Alice', 'date': '2023-01-01'},
+        ...     {'entity': 'main.py', 'rev': '2', 'author': 'Alice', 'date': '2023-01-02'},
+        ...     {'entity': 'main.py', 'rev': '3', 'author': 'Bob', 'date': '2023-01-03'},
+        ... ]
+        >>> df = pd.DataFrame(data)
+        >>> result = main_dev_by_revs(df)
+    """
+    # Handle empty DataFrame
+    if df.empty:
+        return pd.DataFrame(columns=["entity", "main-dev", "added", "total-added", "ownership"])
+
+    # Count revisions per entity-author combination
+    entity_author_revs = (
+        df.groupby([GitLogSchema.ENTITY, GitLogSchema.AUTHOR], observed=True)[GitLogSchema.REV]
+        .nunique()
+        .reset_index()
+        .rename(columns={GitLogSchema.REV: "author-revs"})
+    )
+
+    # Count total revisions per entity
+    entity_total_revs = (
+        df.groupby(GitLogSchema.ENTITY, observed=True)[GitLogSchema.REV]
+        .nunique()
+        .reset_index()
+        .rename(columns={GitLogSchema.REV: "total-revs"})
+    )
+
+    # Find the author with max revisions per entity
+    main_devs = (
+        entity_author_revs.loc[
+            entity_author_revs.groupby(GitLogSchema.ENTITY, observed=True)["author-revs"].idxmax()
+        ]
+        .rename(
+            columns={
+                GitLogSchema.AUTHOR: "main-dev",
+                "author-revs": "added",
+            }
+        )
+        .reset_index(drop=True)
+    )
+
+    # Merge with total revisions
+    result = main_devs.merge(entity_total_revs, on=GitLogSchema.ENTITY)
+    result = result.rename(columns={"total-revs": "total-added"})
+
+    # Calculate ownership percentage
+    result["ownership"] = (result["added"] / result["total-added"] * 100).round(2)
+
+    # Sort by entity ascending
+    result = result.sort_values(by=[GitLogSchema.ENTITY], ascending=True)
+
+    return result.reset_index(drop=True)
+
+
+def fragmentation(df: pd.DataFrame) -> pd.DataFrame:
+    """Calculate fragmentation for each entity using fractal value.
+
+    The fractal value measures how fragmented contributions are across
+    authors. Formula: FV = 1 - Σ(ai/nc)²
+
+    Args:
+        df: DataFrame with columns: entity, rev, author, date, loc_added, loc_deleted
+
+    Returns:
+        DataFrame with columns:
+            - entity: File or module path
+            - fractal-value: Fragmentation metric (0 to <1)
+              - 0: Single author (no fragmentation)
+              - →1: Highly fragmented across many authors
+            - total-revs: Total revisions for entity
+
+    Example:
+        >>> data = [
+        ...     {'entity': 'main.py', 'rev': '1', 'author': 'Alice', 'date': '2023-01-01'},
+        ...     {'entity': 'main.py', 'rev': '2', 'author': 'Alice', 'date': '2023-01-02'},
+        ...     {'entity': 'utils.py', 'rev': '3', 'author': 'Alice', 'date': '2023-01-03'},
+        ...     {'entity': 'utils.py', 'rev': '4', 'author': 'Bob', 'date': '2023-01-04'},
+        ... ]
+        >>> df = pd.DataFrame(data)
+        >>> result = fragmentation(df)
+    """
+    # Handle empty DataFrame
+    if df.empty:
+        return pd.DataFrame(columns=["entity", "fractal-value", "total-revs"])
+
+    # Count revisions per entity-author combination
+    entity_author_revs = (
+        df.groupby([GitLogSchema.ENTITY, GitLogSchema.AUTHOR], observed=True)[GitLogSchema.REV]
+        .nunique()
+        .reset_index()
+        .rename(columns={GitLogSchema.REV: "author-revs"})
+    )
+
+    # Count total revisions per entity
+    entity_total_revs = (
+        df.groupby(GitLogSchema.ENTITY, observed=True)[GitLogSchema.REV].nunique().to_dict()
+    )
+
+    # Calculate fractal value for each entity
+    results = []
+    for entity, group in entity_author_revs.groupby(GitLogSchema.ENTITY, observed=True):
+        contributions = group["author-revs"].tolist()
+        total_revs = entity_total_revs[entity]
+
+        # Use the fractal_value utility function
+        fv = fractal_value(contributions)
+
+        results.append(
+            {
+                "entity": entity,
+                "fractal-value": round(fv, 2),
+                "total-revs": total_revs,
+            }
+        )
+
+    result = pd.DataFrame(results)
+
+    # Sort by fractal-value descending, then by total-revs descending
+    result = result.sort_values(by=["fractal-value", "total-revs"], ascending=[False, False])
+
+    return result.reset_index(drop=True)

code_maat_python/analyses/entities.py

@@ -0,0 +1,51 @@
+"""Entity listing analysis for code-maat-python.
+
+Lists all entities with basic statistics.
+"""
+
+import pandas as pd
+
+from code_maat_python.parser import GitLogSchema
+
+
+def analyze_entities(df: pd.DataFrame) -> pd.DataFrame:
+    """List all entities with statistics.
+
+    Provides a simple listing of all entities (files) in the repository
+    with the number of times they appear in commits.
+
+    Args:
+        df: DataFrame with columns: entity, rev, author, date, loc_added, loc_deleted
+
+    Returns:
+        DataFrame with columns:
+            - entity: File or module path
+            - n-commits: Number of commit records (entity appearances)
+        Sorted by entity name.
+
+    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_entities(df)
+        >>> print(result)
+                  entity  n-commits
+        0    src/main.py          2
+        1   src/utils.py          1
+    """
+    # Handle empty DataFrame
+    if df.empty:
+        return pd.DataFrame(columns=["entity", "n-commits"])
+
+    # Count occurrences of each entity
+    result = (
+        df.groupby(GitLogSchema.ENTITY, observed=True)
+        .size()
+        .reset_index(name="n-commits")
+        .sort_values("entity")
+    )
+
+    return result.reset_index(drop=True)

code_maat_python/analyses/revisions.py

@@ -0,0 +1,56 @@
+"""Revision frequency analysis for code-maat-python.
+
+Analyzes and sorts entities by their revision frequency.
+"""
+
+import pandas as pd
+
+from code_maat_python.parser import GitLogSchema
+
+
+def analyze_revisions(df: pd.DataFrame) -> pd.DataFrame:
+    """Sort entities by revision frequency.
+
+    Counts the number of times each entity has been revised and sorts
+    by frequency in descending order. This helps identify the most
+    frequently changed files in a codebase.
+
+    Args:
+        df: DataFrame with columns: entity, rev, author, date, loc_added, loc_deleted
+
+    Returns:
+        DataFrame with columns:
+            - entity: File or module path
+            - n-revs: Number of revisions
+        Sorted by n-revs descending, then by entity name.
+
+    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/main.py', 'rev': '3', 'author': 'Alice', 'date': '2023-01-03'},
+        ...     {'entity': 'src/utils.py', 'rev': '1', 'author': 'Alice', 'date': '2023-01-01'},
+        ... ]
+        >>> df = pd.DataFrame(data)
+        >>> result = analyze_revisions(df)
+        >>> print(result)
+                  entity  n-revs
+        0    src/main.py       3
+        1   src/utils.py       1
+    """
+    # Handle empty DataFrame
+    if df.empty:
+        return pd.DataFrame(columns=["entity", "n-revs"])
+
+    # Count unique revisions per entity
+    result = (
+        df.groupby(GitLogSchema.ENTITY, observed=True)[GitLogSchema.REV]
+        .nunique()
+        .reset_index()
+    )
+    result.columns = ["entity", "n-revs"]
+
+    # Sort by revision count descending, then by entity name
+    result = result.sort_values(by=["n-revs", "entity"], ascending=[False, True])
+
+    return result.reset_index(drop=True)