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

code_maat_python/analyses/soc.py

@@ -0,0 +1,90 @@
+"""Sum of Coupling (SOC) analysis for code-maat-python.
+
+Calculate sum of coupling for each entity based on commit size.
+"""
+
+import pandas as pd
+
+from code_maat_python.parser import GitLogSchema
+
+
+def analyze_soc(df: pd.DataFrame, max_changeset_size: int = 30) -> pd.DataFrame:
+    """Calculate sum of coupling (SOC) for each entity.
+
+    Sum of Coupling provides a simpler metric than full logical coupling
+    analysis. For each commit with m files, each file gets a SOC score
+    of (m-1). This measures how often a file changes with other files,
+    without tracking which specific files it changes with.
+
+    Algorithm:
+    1. Filter out large commits (> max_changeset_size files)
+    2. For each commit, calculate commit size (number of files)
+    3. For each entity in a commit, add (commit_size - 1) to its SOC score
+    4. Sum all contributions per entity
+
+    This is simpler and faster than full coupling analysis, making it
+    useful for validating the data pipeline.
+
+    Args:
+        df: DataFrame with columns: entity, rev, author, date, loc_added, loc_deleted
+        max_changeset_size: Maximum number of files in a commit to consider (default: 30)
+
+    Returns:
+        DataFrame with columns:
+            - entity: File or module path
+            - soc: Sum of coupling score (integer)
+        Sorted by soc descending, then by entity name.
+
+    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/test.py', 'rev': '2', 'author': 'Bob', 'date': '2023-01-02'},
+        ... ]
+        >>> df = pd.DataFrame(data)
+        >>> result = analyze_soc(df)
+        >>> print(result)
+                  entity  soc
+        0    src/main.py    1
+        1   src/utils.py    1
+        2    src/test.py    0
+        # main.py and utils.py were in a commit together (m=2), so each gets soc=1
+        # test.py was alone (m=1), so gets soc=0
+    """
+    # Handle empty DataFrame
+    if df.empty:
+        return pd.DataFrame(columns=["entity", "soc"])
+
+    # Filter large commits BEFORE processing
+    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)].copy()
+
+    if df_filtered.empty:
+        return pd.DataFrame(columns=["entity", "soc"])
+
+    # Calculate commit sizes and map to each row
+    commit_size_map = (
+        df_filtered.groupby(GitLogSchema.REV, observed=True)[GitLogSchema.ENTITY]
+        .count()
+        .to_dict()
+    )
+
+    # Calculate SOC contribution for each entity occurrence
+    # For each occurrence of entity in a commit, add (commit_size - 1)
+    df_filtered["commit_size"] = df_filtered[GitLogSchema.REV].map(commit_size_map).astype(int)
+    df_filtered["soc_contribution"] = df_filtered["commit_size"] - 1
+
+    # Sum contributions per entity
+    result = (
+        df_filtered.groupby(GitLogSchema.ENTITY, observed=True)["soc_contribution"]
+        .sum()
+        .reset_index()
+        .rename(columns={"soc_contribution": "soc"})
+    )
+
+    # Convert to integer and sort
+    result["soc"] = result["soc"].astype(int)
+    result = result.sort_values(["soc", "entity"], ascending=[False, True])
+
+    return result.reset_index(drop=True)

code_maat_python/analyses/summary.py

@@ -0,0 +1,61 @@
+"""Summary statistics analysis for code-maat-python.
+
+Provides overview statistics for a repository.
+"""
+
+import pandas as pd
+
+from code_maat_python.parser import GitLogSchema
+
+
+def analyze_summary(df: pd.DataFrame) -> pd.DataFrame:
+    """Generate overview statistics.
+
+    Provides high-level statistics about the repository including
+    commit count, entity count, author count, and date range.
+
+    Args:
+        df: DataFrame with columns: entity, rev, author, date, loc_added, loc_deleted
+
+    Returns:
+        DataFrame with columns:
+            - statistic: Name of the statistic
+            - value: String representation of the value
+        Including: n-commits, n-entities, n-authors, first-commit, last-commit
+
+    Example:
+        >>> data = [
+        ...     {'entity': 'src/main.py', 'rev': 'abc', 'author': 'Dev1',
+        ...      'date': pd.to_datetime('2023-01-01')},
+        ...     {'entity': 'src/utils.py', 'rev': 'def', 'author': 'Dev2',
+        ...      'date': pd.to_datetime('2023-01-15')},
+        ... ]
+        >>> df = pd.DataFrame(data)
+        >>> result = analyze_summary(df)
+        >>> print(result)
+              statistic  value
+        0     n-commits      2
+        1    n-entities      2
+        2     n-authors      2
+        3  first-commit 2023-01-01
+        4   last-commit 2023-01-15
+    """
+    # Handle empty DataFrame
+    if df.empty:
+        return pd.DataFrame(columns=["statistic", "value"])
+
+    # Calculate statistics
+    stats = {
+        "n-commits": df[GitLogSchema.REV].nunique(),
+        "n-entities": df[GitLogSchema.ENTITY].nunique(),
+        "n-authors": df[GitLogSchema.AUTHOR].nunique(),
+        "first-commit": df[GitLogSchema.DATE].min().strftime("%Y-%m-%d"),
+        "last-commit": df[GitLogSchema.DATE].max().strftime("%Y-%m-%d"),
+    }
+
+    # Convert to DataFrame with specific order
+    result = pd.DataFrame(
+        [{"statistic": k, "value": str(v)} for k, v in stats.items()]
+    )
+
+    return result