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

code_maat_python/transformers/time_grouper.py

@@ -0,0 +1,146 @@
+"""Time-based grouper transformer.
+
+Groups commits within time windows into logical changesets.
+"""
+
+import pandas as pd
+
+from code_maat_python.parser import GitLogSchema
+
+
+def group_by_time(df: pd.DataFrame, window: str = "1D") -> pd.DataFrame:
+    """Group commits within a time window into logical changesets.
+
+    Takes temporal commits and groups them into logical changesets based on
+    a sliding time window. Within each window, entities are deduplicated
+    (keeping the first occurrence) and assigned a new revision ID based on
+    the window end date.
+
+    Args:
+        df: DataFrame with GitLogSchema columns (rev, date, author, entity, loc_added, loc_deleted)
+        window: Pandas frequency string (e.g., '1D', '2D', '1W', '7D')
+                Default: '1D' (1 day window)
+                See: https://pandas.pydata.org/docs/user_guide/timeseries.html#offset-aliases
+
+    Returns:
+        DataFrame with same schema, but commits grouped by time window.
+        Entities are deduplicated within windows (keeping first occurrence).
+        Revision IDs are set to window end dates in ISO format (YYYY-MM-DD).
+
+    Raises:
+        ValueError: If DataFrame is missing required columns or window format is invalid
+
+    Examples:
+        >>> data = [
+        ...     {"entity": "file.py", "author": "Alice", "rev": "r1", "date": "2023-01-01"},
+        ...     {"entity": "file.py", "author": "Bob", "rev": "r2", "date": "2023-01-01"},
+        ... ]
+        >>> df = pd.DataFrame(data)
+        >>> result = group_by_time(df, window="1D")
+        >>> len(result)  # Deduplicated to 1 entity
+        1
+        >>> result.iloc[0]["author"]  # Keeps first occurrence
+        'Alice'
+        >>> result.iloc[0]["rev"]  # Window end date as revision
+        '2023-01-01'
+    """
+    # STEP 1: Handle empty DataFrame (ALWAYS FIRST)
+    if df.empty:
+        return GitLogSchema.create_empty_dataframe()
+
+    # STEP 2: Validate required columns
+    required_cols = set(GitLogSchema.columns())
+    if not required_cols.issubset(df.columns):
+        missing = required_cols - set(df.columns)
+        raise ValueError(f"DataFrame missing required columns: {missing}")
+
+    # STEP 3: Validate window parameter
+    if not isinstance(window, str):
+        raise ValueError(f"window must be a string, got {type(window).__name__}")
+    try:
+        pd.Timedelta(window)  # Validates format
+    except ValueError as e:
+        raise ValueError(f"Invalid window format '{window}': {e}") from e
+
+    # STEP 4: Ensure date column is datetime (don't mutate input!)
+    if not pd.api.types.is_datetime64_any_dtype(df[GitLogSchema.DATE]):
+        df = df.copy()
+        df[GitLogSchema.DATE] = pd.to_datetime(df[GitLogSchema.DATE])
+
+    # STEP 5: Normalize dates to daily granularity (remove time component)
+    df_normalized = df.copy()
+    df_normalized[GitLogSchema.DATE] = pd.to_datetime(
+        df_normalized[GitLogSchema.DATE].dt.date
+    )
+
+    # STEP 7: Apply rolling window logic with smart deduplication
+    # Track entities and when they were last output to avoid duplicating
+    # entities in overlapping windows
+    results = []
+    window_delta = pd.Timedelta(window)
+    entity_last_output: dict[str, pd.Timestamp] = {}  # entity -> last output date
+
+    # Process only dates that have actual commits
+    unique_dates = sorted(df_normalized[GitLogSchema.DATE].unique())
+
+    for current_date in unique_dates:
+        # Calculate window start (inclusive)
+        window_start = current_date - window_delta + pd.Timedelta("1D")
+
+        # Get all commits within this window
+        window_mask = (df_normalized[GitLogSchema.DATE] >= window_start) & (
+            df_normalized[GitLogSchema.DATE] <= current_date
+        )
+        window_data = df_normalized[window_mask]
+
+        if window_data.empty:
+            continue
+
+        # STEP 8: Deduplicate entities with keep='first' (STABLE SORT!)
+        unique_data = window_data.drop_duplicates(
+            subset=[GitLogSchema.ENTITY],
+            keep="first",  # CRITICAL!
+        )
+
+        # STEP 9: Filter out entities already output in a recent overlapping window
+        # An entity should only be output again if its current window doesn't overlap
+        # with the window where it was last output
+        entities_to_output = []
+        for idx, row in unique_data.iterrows():
+            entity = row[GitLogSchema.ENTITY]
+            last_output_date = entity_last_output.get(entity)
+
+            if last_output_date is None:
+                # First time seeing this entity
+                entities_to_output.append(idx)
+                entity_last_output[entity] = current_date
+            else:
+                # Check if windows overlap
+                # Last window: [last_output_date - window_delta + 1D, last_output_date]
+                # Current window: [current_date - window_delta + 1D, current_date]
+                # They overlap if: last_output_date >= current_date - window_delta + 1D
+                current_window_start = current_date - window_delta + pd.Timedelta("1D")
+
+                # Windows overlap if last_output_date >= current_window_start
+                if last_output_date >= current_window_start:
+                    # Overlapping window - skip this entity
+                    continue
+                else:
+                    # Non-overlapping window - output again
+                    entities_to_output.append(idx)
+                    entity_last_output[entity] = current_date
+
+        if entities_to_output:
+            output_data = unique_data.loc[entities_to_output].copy()
+            # Assign window end date as new revision ID
+            output_data[GitLogSchema.REV] = current_date.strftime("%Y-%m-%d")
+            results.append(output_data)
+
+    # STEP 10: Concatenate results
+    if not results:
+        return GitLogSchema.create_empty_dataframe()
+
+    result = pd.concat(results, ignore_index=True)
+
+    # STEP 11: Return with GitLogSchema column ordering
+    return result[GitLogSchema.columns()]

code_maat_python/utils/math.py

@@ -0,0 +1,105 @@
+"""Mathematical utilities for analyses."""
+
+from typing import Union
+
+Number = Union[int, float]
+
+
+def percentage(value: Number, total: Number) -> float:
+    """Calculate percentage.
+
+    Args:
+        value: Numerator value
+        total: Denominator value
+
+    Returns:
+        Percentage as float (0-100 range)
+
+    Raises:
+        ValueError: If total is zero
+
+    Example:
+        >>> percentage(25, 100)
+        25.0
+    """
+    if total == 0:
+        raise ValueError("Cannot calculate percentage with zero total")
+    return (value / total) * 100.0
+
+
+def average(*values: Number) -> float:
+    """Calculate average of values.
+
+    Args:
+        *values: Variable number of numeric values
+
+    Returns:
+        Average as float
+
+    Raises:
+        ValueError: If no values provided
+
+    Example:
+        >>> average(10, 20, 30)
+        20.0
+    """
+    if not values:
+        raise ValueError("Cannot calculate average of zero values")
+    return sum(values) / len(values)
+
+
+def fractal_value(contributions: list[Number]) -> float:
+    """Calculate fractal fragmentation value.
+
+    The fractal value measures how fragmented contributions are across
+    contributors. Formula: FV = 1 - Σ(ai/nc)²
+
+    Args:
+        contributions: List of contribution counts per contributor
+
+    Returns:
+        Fractal value in range [0, 1)
+        - 0: Single contributor (no fragmentation)
+        - →1: Highly fragmented across many contributors
+
+    Raises:
+        ValueError: If contributions list is empty
+
+    Example:
+        >>> fractal_value([100])  # Single contributor
+        0.0
+        >>> fractal_value([50, 50])  # Two equal contributors
+        0.5
+        >>> fractal_value([33, 33, 34])  # Three ~equal contributors
+        0.6667
+    """
+    if not contributions:
+        raise ValueError("Cannot calculate fractal value with no contributions")
+
+    total = sum(contributions)
+    if total == 0:
+        return 0.0
+
+    return 1.0 - sum((count / total) ** 2 for count in contributions)
+
+
+def clamp(value: Number, min_value: Number, max_value: Number) -> Number:
+    """Clamp value to range [min_value, max_value].
+
+    Args:
+        value: Value to clamp
+        min_value: Minimum allowed value
+        max_value: Maximum allowed value
+
+    Returns:
+        Clamped value
+
+    Example:
+        >>> clamp(150, 0, 100)
+        100
+        >>> clamp(-10, 0, 100)
+        0
+        >>> clamp(50, 0, 100)
+        50
+    """
+    return max(min_value, min(value, max_value))