Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(health): change-entropy and co-change scatter signals (#301)

Raghav Chamadiya67f8b373d67e
diff --git a/docs/CODE_HEALTH.md b/docs/CODE_HEALTH.md
index 00b45a898..20b94b33b 100644
--- a/docs/CODE_HEALTH.md
+++ b/docs/CODE_HEALTH.md
@@ -1,9 +1,9 @@
# Code Health
-Repowise computes a 1–10 health score for every file in your repo from seventeen
+Repowise computes a 1–10 health score for every file in your repo from nineteen
deterministic biomarkers — McCabe complexity, deep nesting, brain methods,
clone detection, untested hotspots, function-level churn, code-age volatility,
-ownership dispersion, relative churn, organizational risk, and more. **No LLM calls, no cloud requirement.** Pure
+ownership dispersion, relative churn, change entropy, co-change scatter, and more. **No LLM calls, no cloud requirement.** Pure
Python over tree-sitter + git data, designed to finish in under 30 seconds on a
3 000-file repo.
@@ -26,13 +26,13 @@ most:
| Category | Cap | Biomarkers |
|------------------------|-------|------------|
-| Organizational | −3.5 | developer_congestion, knowledge_loss, hidden_coupling, function_hotspot, code_age_volatility, ownership_risk, churn_risk |
+| Organizational | −3.5 | developer_congestion, knowledge_loss, hidden_coupling, function_hotspot, code_age_volatility, ownership_risk, churn_risk, change_entropy, co_change_scatter |
| Structural complexity | −2.5 | brain_method, nested_complexity, bumpy_road, complex_conditional |
| Test coverage | −2.0 | untested_hotspot, coverage_gap |
| Size & complexity | −1.5 | complex_method, large_method, primitive_obsession |
| Duplication | −1.0 | dry_violation |
-Seventeen biomarkers across five categories. `function_hotspot` and
+Nineteen biomarkers across five categories. `function_hotspot` and
`code_age_volatility` are blame-based and sit in the organizational bucket —
both are tier-aware and stay silent on ESSENTIAL-tier repos until the per-line
blame index is built.
@@ -42,7 +42,7 @@ let the strongest empirical predictors deduct more than the uniform severity
table alone allows. `developer_congestion` is multiplied by 1.5,
`untested_hotspot` by 1.3, `ownership_risk` by 1.3 (the strongest defect
correlate in the literature), `function_hotspot` (a follow-up biomarker) and
-`churn_risk` by 1.2, and `knowledge_loss` is de-rated to 0.4. The de-rating is OSS-calibrated
+`churn_risk` and `change_entropy` by 1.2 and 1.1, and `knowledge_loss` is de-rated to 0.4. The de-rating is OSS-calibrated
(legacy code gets handed off because it works); enterprise users where
attrition is a real risk should raise it back via per-repo overrides — see
plan §3.5.
@@ -135,6 +135,22 @@ is. Because the trigger is a ratio to NLOC, it does not simply re-flag large
files. Fires when the file is actively churning (≥ 5 recent commits, top
quartile of repo churn) and relative churn ≥ 1.0.
+**change_entropy** — How scattered a file's change history is, adapted from
+Hassan's History Complexity Metric. Each commit is treated as a one-period
+window whose entropy is `log2(files-touched)`, distributed across its files and
+decayed over time. A file repeatedly caught up in wide, scattered commits
+scores high; one changed in focused, single-purpose commits stays low even if
+it changes often — so this is *not* a churn proxy. Fires when the file is
+actively changing (≥ 3 recent commits) and sits in the top 20% of repo change
+entropy. Tier-aware: silent on ESSENTIAL-tier repos (no co-change walk).
+
+**co_change_scatter** — Breadth of coupling. Counts the distinct files a file
+co-changes with above the indexer's recording threshold; a high count means
+editing it tends to ripple across the codebase (shotgun surgery). This is the
+breadth complement to `hidden_coupling`, which flags *specific* undeclared
+coupled pairs. Fires on actively-changing files (≥ 3 recent commits) coupled to
+≥ 8 distinct partners. Tier-aware: silent on ESSENTIAL-tier repos.
+
## Test coverage
Pass coverage reports straight into the analyzer:
@@ -229,7 +245,7 @@ Health: 7.4 (avg) · 6.2 (hotspots) · 2.1 (worst: payments/processor.ts)
| Feature | Repowise | CodeScene | DeepSource | Sourcery |
|----------------------------------|:--:|:--:|:--:|:--:|
-| Code health score (1–10) | ✅ 17 biomarkers | ✅ 25–30 | ❌ | ❌ |
+| Code health score (1–10) | ✅ 19 biomarkers | ✅ 25–30 | ❌ | ❌ |
| Brain Method detection | ✅ | ✅ | ❌ | ❌ |
| Test coverage intelligence | ✅ LCOV/Cobertura/Clover | ❌ | ❌ | ❌ |
| Untested hotspot detection | ✅ coverage × hotspot | ❌ | ❌ | ❌ |
diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.md
index b4029f521..891433bf4 100644
--- a/docs/architecture/code-health.md
+++ b/docs/architecture/code-health.md
@@ -107,7 +107,9 @@ analysis/health/
├── function_hotspot.py
├── code_age_volatility.py
├── ownership_risk.py
- └── churn_risk.py
+ ├── churn_risk.py
+ ├── change_entropy.py
+ └── co_change_scatter.py
```
### Persistence
@@ -310,7 +312,7 @@ higher than dormant ones.
---
-## 5. The 17 biomarkers and their categories
+## 5. The 19 biomarkers and their categories
Each biomarker is a stateless class implementing the `Biomarker` Protocol
from `biomarkers/base.py`:
@@ -324,7 +326,7 @@ class Biomarker(Protocol):
| Category | Cap | Biomarkers |
|------------------------|------|------------|
-| Organizational | −3.5 | developer_congestion, knowledge_loss, hidden_coupling, function_hotspot, code_age_volatility, ownership_risk, churn_risk |
+| Organizational | −3.5 | developer_congestion, knowledge_loss, hidden_coupling, function_hotspot, code_age_volatility, ownership_risk, churn_risk, change_entropy, co_change_scatter |
| Structural complexity | −2.5 | brain_method, nested_complexity, bumpy_road, complex_conditional |
| Test coverage | −2.0 | untested_hotspot, coverage_gap |
| Size & complexity | −1.5 | complex_method, large_method, primitive_obsession |
@@ -333,9 +335,27 @@ class Biomarker(Protocol):
`ownership_risk` (long-run minor-contributor dispersion, Bird et al.) and
`churn_risk` (size-normalized relative churn, Nagappan-Ball) are git-only
process signals computed from `top_authors_json` / `lines_added_90d` /
-`churn_percentile` — fields the git indexer already produces. `knowledge_loss`
-is activity-gated so abandoned-but-stable files (the survivor effect) no longer
-fire.
+`churn_percentile` — fields the git indexer already produces. `change_entropy`
+(Hassan's History Complexity Metric) and `co_change_scatter` (breadth of
+co-change coupling, D'Ambros) are likewise git-only and read the
+`change_entropy` / `change_entropy_pct` fields (see §5.1) and
+`co_change_partners_json`. `knowledge_loss` is activity-gated so
+abandoned-but-stable files (the survivor effect) no longer fire.
+
+### 5.1 Change-entropy git-layer fields
+
+`change_entropy` is computed during the **single** FULL-tier co-change walk
+(`ingestion/git_indexer/co_change.py::compute_co_changes_and_entropy`) — no
+extra `git log` subprocess. For each commit touching a set of tracked files
+`F` (with `2 ≤ |F| ≤ 30`; wider commits are dropped as noise, Hassan's filter),
+the commit's entropy is `log2(|F|)`, distributed uniformly (`1/|F|` per file)
+and decayed with the same τ=180d half-life as co-change. The decay-weighted sum
+per file is `git_meta["change_entropy"]`. `enrich.compute_percentiles` then
+derives `change_entropy_pct` by ranking **only files with positive entropy**
+(zero-entropy files — the ESSENTIAL tier, or files only ever changed alone —
+keep pct 0.0 so the biomarker stays silent). Both fields are persisted on
+`git_metadata` (migration `0025`) and the additive-reconcile path back-fills
+them on legacy DBs.
`biomarkers/registry.py` is an **explicit list**, not auto-discovery —
keeps the registration order deterministic and lets tests inject extras
diff --git a/packages/core/alembic/versions/0025_git_change_entropy.py b/packages/core/alembic/versions/0025_git_change_entropy.py
new file mode 100644
index 000000000..c7503f398
--- /dev/null
+++ b/packages/core/alembic/versions/0025_git_change_entropy.py
@@ -0,0 +1,39 @@
+"""Add change_entropy + change_entropy_pct columns to git_metadata.
+
+Stores Hassan's History Complexity Metric (decay-weighted per-commit change
+scatter) and its repo-wide percentile, computed during the FULL-tier
+co-change walk and consumed by the ``change_entropy`` health biomarker.
+
+Revision ID: 0025
+Revises: 0024
+Create Date: 2026-05-29
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers
+revision: str = "0025"
+down_revision: str | None = "0024"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+ op.add_column(
+ "git_metadata",
+ sa.Column("change_entropy", sa.Float, nullable=False, server_default="0.0"),
+ )
+ op.add_column(
+ "git_metadata",
+ sa.Column("change_entropy_pct", sa.Float, nullable=False, server_default="0.0"),
+ )
+
+
+def downgrade() -> None:
+ op.drop_column("git_metadata", "change_entropy_pct")
+ op.drop_column("git_metadata", "change_entropy")
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/README.md b/packages/core/src/repowise/core/analysis/health/biomarkers/README.md
index db8554adb..16171565f 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/README.md
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/README.md
@@ -9,7 +9,7 @@ class Biomarker(Protocol):
def detect(self, ctx: FileContext) -> list[BiomarkerResult]: ...
```
-## Registered detectors (17)
+## Registered detectors (19)
Structural complexity (cap −2.5):
- `brain_method` — symbols simultaneously long, complex, and central.
@@ -44,6 +44,12 @@ Organizational (cap −3.5):
- `churn_risk` — relative churn: a file whose 90-day window rewrote a
large fraction of its own lines (size-normalized, so it doesn't simply
re-flag big files).
+- `change_entropy` — Hassan's History Complexity Metric: how scattered a
+ file's changes are across noisy commits (not a churn proxy). Reads the
+ FULL-tier `change_entropy` / `change_entropy_pct` git fields.
+- `co_change_scatter` — breadth of co-change coupling: a file coupled to
+ many others (shotgun surgery). Complements `hidden_coupling`, which
+ flags specific undeclared pairs.
Caps were recalibrated to lift `organizational` (was −1.0) and de-rate
`size_and_complexity` / `duplication` per plan §3.1. A per-biomarker
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/change_entropy.py b/packages/core/src/repowise/core/analysis/health/biomarkers/change_entropy.py
new file mode 100644
index 000000000..f193f61ec
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/change_entropy.py
@@ -0,0 +1,97 @@
+"""Change Entropy — files whose changes are scattered across noisy commits.
+
+Hassan ("Predicting Faults Using the Complexity of Code Changes", ICSE 2009)
+showed that the *entropy* of a file's change history — how spread-out and
+chaotic its modifications are over time — predicts faults (r≈0.55-0.78),
+independently of raw churn. A file repeatedly caught up in wide, scattered
+commits accumulates a high History Complexity Metric; one changed in focused,
+single-purpose commits stays low even if it changes often.
+
+The git indexer computes the decay-weighted per-file HCM during the co-change
+walk (``git_meta["change_entropy"]``) and its repo-wide percentile
+(``change_entropy_pct``). This biomarker is the consumer.
+
+Fires when the file is both actively changing and in the top entropy band:
+
+- ``change_entropy_pct`` ≥ 0.80, AND
+- ``commit_count_90d`` ≥ 3 (entropy only matters for files in motion).
+
+Tier-aware: on the ESSENTIAL git tier (and for files that never co-changed)
+``change_entropy`` is 0 and its percentile 0.0, so the detector stays silent.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..models import Severity
+from .base import BiomarkerResult, FileContext
+
+_MIN_PERCENTILE = 0.80
+_HIGH_PERCENTILE = 0.90
+_CRITICAL_PERCENTILE = 0.95
+_MIN_COMMITS_90D = 3
+
+
+def _as_float(value: object, default: float = 0.0) -> float:
+ try:
+ return float(value) # type: ignore[arg-type]
+ except (TypeError, ValueError):
+ return default
+
+
+def _as_int(value: object, default: int = 0) -> int:
+ try:
+ return int(value or 0) # type: ignore[arg-type]
+ except (TypeError, ValueError):
+ return default
+
+
+class ChangeEntropyDetector:
+ name = "change_entropy"
+ category = "organizational"
+
+ def detect(self, ctx: FileContext) -> list[BiomarkerResult]:
+ meta: dict[str, Any] = ctx.git_meta or {}
+
+ entropy = _as_float(meta.get("change_entropy"))
+ # No entropy signal → ESSENTIAL tier or a file that only ever changed
+ # alone. Treat as no signal rather than guessing.
+ if entropy <= 0.0:
+ return []
+
+ percentile = _as_float(meta.get("change_entropy_pct"))
+ commits_90d = _as_int(meta.get("commit_count_90d"))
+ if percentile < _MIN_PERCENTILE or commits_90d < _MIN_COMMITS_90D:
+ return []
+
+ is_hotspot = bool(meta.get("is_hotspot"))
+ if percentile >= _CRITICAL_PERCENTILE and is_hotspot:
+ severity = Severity.CRITICAL
+ elif percentile >= _HIGH_PERCENTILE:
+ severity = Severity.HIGH
+ else:
+ severity = Severity.MEDIUM
+
+ return [
+ BiomarkerResult(
+ biomarker_type=self.name,
+ severity=severity,
+ function_name=None,
+ line_start=None,
+ line_end=None,
+ details={
+ "change_entropy": round(entropy, 4),
+ "change_entropy_pct": round(percentile, 3),
+ "commit_count_90d": commits_90d,
+ },
+ reason=(
+ f"changes are scattered across noisy commits "
+ f"(top {(1 - percentile) * 100:.0f}% change entropy); "
+ "a strong history-based fault predictor"
+ ),
+ )
+ ]
+
+
+BIOMARKER = ChangeEntropyDetector()
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/co_change_scatter.py b/packages/core/src/repowise/core/analysis/health/biomarkers/co_change_scatter.py
new file mode 100644
index 000000000..c34f373cd
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/co_change_scatter.py
@@ -0,0 +1,101 @@
+"""Co-change Scatter — files coupled to many others (shotgun surgery).
+
+D'Ambros et al. found that a file co-changing with a *large number* of
+distinct partners is a modest but real defect signal: every edit risks
+rippling across the codebase. This is the breadth complement to
+``hidden_coupling`` (which flags *specific* undeclared coupled pairs); here we
+flag a file coupled to *many* others regardless of whether the links are
+declared.
+
+Reads ``git_meta["co_change_partners_json"]`` (the decay-weighted partner list
+the git indexer already stores). **scatter** = the number of distinct partners
+whose ``co_change_count`` clears the indexer's recording threshold (2.0).
+
+Fires when the file is actively changing and broadly coupled:
+
+- ``scatter`` ≥ 8 (shotgun-surgery territory), AND
+- ``commit_count_90d`` ≥ 3.
+
+Tier-aware: when ``co_change_partners_json`` is empty (ESSENTIAL git tier) the
+detector emits nothing.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from ..models import Severity
+from .base import BiomarkerResult, FileContext
+
+_MIN_PARTNER_WEIGHT = 2.0
+_SCATTER_THRESHOLD = 8
+_HIGH_SCATTER = 15
+_MIN_COMMITS_90D = 3
+
+
+def _count_scatter(meta: dict[str, Any]) -> int:
+ raw = meta.get("co_change_partners_json")
+ if not raw:
+ return 0
+ try:
+ partners = json.loads(raw)
+ except (TypeError, ValueError):
+ return 0
+ scatter = 0
+ for p in partners:
+ if not isinstance(p, dict):
+ continue
+ weight = p.get("co_change_count") or p.get("count") or 0
+ try:
+ if float(weight) >= _MIN_PARTNER_WEIGHT:
+ scatter += 1
+ except (TypeError, ValueError):
+ continue
+ return scatter
+
+
+def _as_int(value: object, default: int = 0) -> int:
+ try:
+ return int(value or 0) # type: ignore[arg-type]
+ except (TypeError, ValueError):
+ return default
+
+
+class CoChangeScatterDetector:
+ name = "co_change_scatter"
+ category = "organizational"
+
+ def detect(self, ctx: FileContext) -> list[BiomarkerResult]:
+ meta: dict[str, Any] = ctx.git_meta or {}
+
+ scatter = _count_scatter(meta)
+ if scatter < _SCATTER_THRESHOLD:
+ return []
+
+ commits_90d = _as_int(meta.get("commit_count_90d"))
+ if commits_90d < _MIN_COMMITS_90D:
+ return []
+
+ severity = Severity.HIGH if scatter >= _HIGH_SCATTER else Severity.MEDIUM
+
+ return [
+ BiomarkerResult(
+ biomarker_type=self.name,
+ severity=severity,
+ function_name=None,
+ line_start=None,
+ line_end=None,
+ details={
+ "scatter": scatter,
+ "commit_count_90d": commits_90d,
+ },
+ reason=(
+ f"co-changes with {scatter} distinct files — editing this "
+ "file tends to ripple across the codebase (shotgun surgery)"
+ ),
+ )
+ ]
+
+
+BIOMARKER = CoChangeScatterDetector()
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/registry.py b/packages/core/src/repowise/core/analysis/health/biomarkers/registry.py
index 4a169bafe..062d49311 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/registry.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/registry.py
@@ -14,7 +14,9 @@ from collections.abc import Sequence
from .base import Biomarker, BiomarkerResult, FileContext
from .brain_method import BrainMethodDetector
from .bumpy_road import BumpyRoadDetector
+from .change_entropy import ChangeEntropyDetector
from .churn_risk import ChurnRiskDetector
+from .co_change_scatter import CoChangeScatterDetector
from .code_age_volatility import CodeAgeVolatilityDetector
from .complex_conditional import ComplexConditionalDetector
from .complex_method import ComplexMethodDetector
@@ -48,6 +50,8 @@ _DETECTOR_FACTORIES: list[type[Biomarker]] = [
CodeAgeVolatilityDetector, # type: ignore[list-item]
OwnershipRiskDetector, # type: ignore[list-item]
ChurnRiskDetector, # type: ignore[list-item]
+ ChangeEntropyDetector, # type: ignore[list-item]
+ CoChangeScatterDetector, # type: ignore[list-item]
]
diff --git a/packages/core/src/repowise/core/analysis/health/scoring.py b/packages/core/src/repowise/core/analysis/health/scoring.py
index a3568b6da..561b7c5b3 100644
--- a/packages/core/src/repowise/core/analysis/health/scoring.py
+++ b/packages/core/src/repowise/core/analysis/health/scoring.py
@@ -59,6 +59,8 @@ _BIOMARKER_WEIGHT_MULTIPLIER: dict[str, float] = {
"hidden_coupling": 1.0,
"ownership_risk": 1.3,
"churn_risk": 1.2,
+ "change_entropy": 1.1,
+ "co_change_scatter": 1.0,
"knowledge_loss": 0.4,
# Governance — additive pass, weights are informational
"contradictory_decision": 1.0,
@@ -87,6 +89,8 @@ _BIOMARKER_CATEGORY: dict[str, str] = {
"code_age_volatility": "organizational",
"ownership_risk": "organizational",
"churn_risk": "organizational",
+ "change_entropy": "organizational",
+ "co_change_scatter": "organizational",
# Governance biomarkers — written by the additive governance pass
"ungoverned_hotspot": "organizational",
"stale_governance": "organizational",
diff --git a/packages/core/src/repowise/core/analysis/health/suggestions.py b/packages/core/src/repowise/core/analysis/health/suggestions.py
index e0a542e7b..50c18678a 100644
--- a/packages/core/src/repowise/core/analysis/health/suggestions.py
+++ b/packages/core/src/repowise/core/analysis/health/suggestions.py
@@ -111,6 +111,18 @@ _TEMPLATES: dict[str, str] = {
"so lock in current behavior and slow the rate of structural "
"edits."
),
+ "change_entropy": (
+ "Calm this file's change history. Its modifications arrive in wide, "
+ "scattered commits — a strong history-based fault predictor. Land "
+ "future edits in focused, single-purpose commits, and consider "
+ "splitting the file so unrelated changes stop landing together."
+ ),
+ "co_change_scatter": (
+ "Reduce the blast radius. This file co-changes with many others, so "
+ "every edit ripples across the codebase. Tighten its interface, move "
+ "shared concerns behind a stable boundary, or split it so callers "
+ "depend on smaller, more cohesive units."
+ ),
"knowledge_loss": (
"Document the surviving knowledge. The primary author(s) of "
"this file are no longer active — pair-program with someone "
diff --git a/packages/core/src/repowise/core/ingestion/git_indexer/_constants.py b/packages/core/src/repowise/core/ingestion/git_indexer/_constants.py
index 526795ed2..f5b049745 100644
--- a/packages/core/src/repowise/core/ingestion/git_indexer/_constants.py
+++ b/packages/core/src/repowise/core/ingestion/git_indexer/_constants.py
@@ -123,6 +123,13 @@ _DEFAULT_CO_CHANGE_MIN_COUNT: int = 2
# correctness change: typical commits sit well under 20 files.
_MAX_FILES_PER_COMMIT_FOR_COCHANGE: int = 200
+# Change-entropy uses a tighter file-set cap than co-change. Hassan (2009)
+# excludes very wide commits from the History Complexity Metric because a
+# sweeping edit spreads its "change probability" so thinly that it adds noise
+# rather than signal. 30 follows the commonly cited Hassan filter; commits
+# above it are dropped from the entropy accumulation entirely.
+_MAX_FILES_PER_COMMIT_FOR_ENTROPY: int = 30
+
# Commit message classification regexes (Phase 2.2).
_COMMIT_CATEGORIES: dict[str, re.Pattern[str]] = {
"feature": re.compile(
diff --git a/packages/core/src/repowise/core/ingestion/git_indexer/co_change.py b/packages/core/src/repowise/core/ingestion/git_indexer/co_change.py
index 311192ec9..435372170 100644
--- a/packages/core/src/repowise/core/ingestion/git_indexer/co_change.py
+++ b/packages/core/src/repowise/core/ingestion/git_indexer/co_change.py
@@ -1,9 +1,14 @@
-"""Repo-wide co-change accumulation (FULL-tier signal).
+"""Repo-wide co-change accumulation + change entropy (FULL-tier signals).
-A single ``git log --name-only`` walk records decay-weighted co-occurrence
-pairs across all tracked files. This is the second of the two expensive
-signals the ESSENTIAL tier defers; the FULL tier (and the backfill worker)
-run it.
+A single ``git log --name-only`` walk feeds two history signals at once:
+
+* **Co-change** — decay-weighted co-occurrence pairs across tracked files.
+* **Change entropy** — Hassan's History Complexity Metric (2009), capturing
+ how scattered each file's changes are over time.
+
+Both are derived from the same commit iteration so the FULL tier (and the
+backfill worker) pay for only one ``git log`` subprocess. The ESSENTIAL tier
+defers the whole walk; absent fields are treated as "no signal" downstream.
"""
from __future__ import annotations
@@ -22,33 +27,44 @@ from ._constants import (
_DEFAULT_CO_CHANGE_COMMIT_LIMIT,
_DEFAULT_CO_CHANGE_MIN_COUNT,
_MAX_FILES_PER_COMMIT_FOR_COCHANGE,
+ _MAX_FILES_PER_COMMIT_FOR_ENTROPY,
)
logger = structlog.get_logger(__name__)
-__all__ = ["compute_co_changes"]
+__all__ = ["compute_co_changes", "compute_co_changes_and_entropy"]
-def compute_co_changes(
+def compute_co_changes_and_entropy(
repo: Any,
all_files: set[str],
commit_limit: int = _DEFAULT_CO_CHANGE_COMMIT_LIMIT,
min_count: int = _DEFAULT_CO_CHANGE_MIN_COUNT,
on_commit_done: Callable[[], None] | None = None,
on_co_change_start: Callable[[int], None] | None = None,
-) -> dict[str, list[dict]]:
- """Walk recent commits and record co-occurrence pairs for tracked files.
+) -> tuple[dict[str, list[dict]], dict[str, float]]:
+ """Walk recent commits once, returning ``(co_changes, change_entropy)``.
Uses a single ``git log --name-only`` call instead of spawning one
``git diff`` subprocess per commit — O(1) processes vs O(commit_limit).
- Applies exponential temporal decay so recent co-changes weigh more than
- ancient ones. ``on_co_change_start(total)`` is called once with the actual
- number of commits found; ``on_commit_done()`` after each commit block.
+ **Co-change** applies exponential temporal decay so recent co-changes weigh
+ more than ancient ones. ``on_co_change_start(total)`` is called once with the
+ actual number of commits found; ``on_commit_done()`` after each commit block.
Both run from a thread-pool thread; callers must ensure thread safety.
+
+ **Change entropy** adapts Hassan's History Complexity Metric: each commit is
+ a one-period window whose entropy is ``log2(|F|)`` (``|F|`` = tracked files
+ it touched), distributed uniformly (``1/|F|`` each) across those files with
+ the same temporal decay. A file only ever changed alone (``|F| == 1``, so
+ ``log2(1) == 0``) accrues no entropy; a file repeatedly caught in wide,
+ scattered commits accrues a lot. Commits touching more than
+ ``_MAX_FILES_PER_COMMIT_FOR_ENTROPY`` files are dropped as noise. The return
+ value maps ``file_path → decayed HCM sum`` (only files with a positive sum).
"""
pair_scores: defaultdict[tuple[str, str], float] = defaultdict(float)
pair_last_date: dict[tuple[str, str], int] = {} # pair → latest Unix ts
+ entropy_scores: defaultdict[str, float] = defaultdict(float)
now_ts = time.time()
try:
@@ -60,7 +76,7 @@ def compute_co_changes(
"--format=%x00%ct",
)
except Exception:
- return {}
+ return {}, {}
actual_commits = raw.count("\x00")
if on_co_change_start is not None:
@@ -71,19 +87,30 @@ def compute_co_changes(
def _flush_commit() -> None:
nonlocal current_ts
- if len(current) < 2:
+ n = len(current)
+ if n < 2:
return
- if len(current) > _MAX_FILES_PER_COMMIT_FOR_COCHANGE:
+ age_days = max((now_ts - current_ts) / 86400.0, 0.0)
+ weight = math.exp(-age_days / _CO_CHANGE_DECAY_TAU)
+
+ # Change entropy (Hassan HCM). The commit-as-period entropy is
+ # ``log2(n)``; each of its files gets the uniform ``1/n`` share, so the
+ # per-file contribution is ``weight * log2(n) / n``. Wide mass-edit
+ # commits are excluded with a tighter cap than co-change.
+ if n <= _MAX_FILES_PER_COMMIT_FOR_ENTROPY:
+ contribution = weight * math.log2(n) / n
+ for path in current:
+ entropy_scores[path] += contribution
+
+ if n > _MAX_FILES_PER_COMMIT_FOR_COCHANGE:
# Mass-edit commit — skip pair generation entirely (see constant
# docstring). Logged at debug for traceability.
logger.debug(
"co_change_skip_oversized_commit",
- files_in_commit=len(current),
+ files_in_commit=n,
threshold=_MAX_FILES_PER_COMMIT_FOR_COCHANGE,
)
return
- age_days = max((now_ts - current_ts) / 86400.0, 0.0)
- weight = math.exp(-age_days / _CO_CHANGE_DECAY_TAU)
sorted_files = sorted(current)
for i in range(len(sorted_files)):
for j in range(i + 1, len(sorted_files)):
@@ -140,6 +167,8 @@ def compute_co_changes(
for fp in result:
result[fp].sort(key=lambda x: x["co_change_count"], reverse=True)
+ entropy = {fp: round(score, 6) for fp, score in entropy_scores.items() if score > 0.0}
+
logger.debug(
"co_change_computed",
commits=actual_commits,
@@ -147,8 +176,29 @@ def compute_co_changes(
pairs_considered=len(pair_scores),
pairs_above_threshold=sum(1 for s in pair_scores.values() if s >= min_count),
files_with_partners=len(result),
+ files_with_entropy=len(entropy),
min_count=min_count,
commit_limit=commit_limit,
)
- return dict(result)
+ return dict(result), entropy
+
+
+def compute_co_changes(
+ repo: Any,
+ all_files: set[str],
+ commit_limit: int = _DEFAULT_CO_CHANGE_COMMIT_LIMIT,
+ min_count: int = _DEFAULT_CO_CHANGE_MIN_COUNT,
+ on_commit_done: Callable[[], None] | None = None,
+ on_co_change_start: Callable[[int], None] | None = None,
+) -> dict[str, list[dict]]:
+ """Co-change-only wrapper over :func:`compute_co_changes_and_entropy`.
+
+ Preserves the historical signature for the instance shim and existing
+ tests. Production indexing calls the combined function directly so the
+ single ``git log`` walk feeds both signals.
+ """
+ co_changes, _entropy = compute_co_changes_and_entropy(
+ repo, all_files, commit_limit, min_count, on_commit_done, on_co_change_start
+ )
+ return co_changes
diff --git a/packages/core/src/repowise/core/ingestion/git_indexer/enrich.py b/packages/core/src/repowise/core/ingestion/git_indexer/enrich.py
index 1dbf8a320..8c8839351 100644
--- a/packages/core/src/repowise/core/ingestion/git_indexer/enrich.py
+++ b/packages/core/src/repowise/core/ingestion/git_indexer/enrich.py
@@ -51,9 +51,7 @@ def detect_original_path(repo: Any, file_path: str, commit_limit: int) -> str |
return prev_path
-def get_blame_ownership(
- repo: Any, file_path: str
-) -> tuple[str | None, str | None, float | None]:
+def get_blame_ownership(repo: Any, file_path: str) -> tuple[str | None, str | None, float | None]:
"""Compute primary owner from git blame (who wrote the most lines)."""
try:
blame = repo.blame("HEAD", file_path)
@@ -140,3 +138,20 @@ def compute_percentiles(metadata_list: list[dict]) -> None:
churn_pct = meta.get("churn_percentile", 0.0)
if churn_pct >= 0.75 and commit_90d > 0:
meta["is_hotspot"] = True
+
+ # change_entropy percentile (mirrors churn_percentile). Rank ONLY files
+ # that carry a positive entropy signal; files with zero entropy — every
+ # file on the ESSENTIAL tier, plus FULL-tier files that only ever changed
+ # alone — keep pct 0.0 so the change_entropy biomarker stays silent. (A
+ # naive rank-everything would hand the topmost zero-entropy file a high
+ # percentile when most files are zero.)
+ for meta in metadata_list:
+ meta.setdefault("change_entropy_pct", 0.0)
+ entropy_idxs = [
+ i for i in range(total) if (metadata_list[i].get("change_entropy") or 0.0) > 0.0
+ ]
+ n_ent = len(entropy_idxs)
+ if n_ent > 0:
+ entropy_idxs.sort(key=lambda i: metadata_list[i].get("change_entropy") or 0.0)
+ for rank, idx in enumerate(entropy_idxs):
+ metadata_list[idx]["change_entropy_pct"] = rank / n_ent
diff --git a/packages/core/src/repowise/core/ingestion/git_indexer/file_history.py b/packages/core/src/repowise/core/ingestion/git_indexer/file_history.py
index 003531b22..8b274df52 100644
--- a/packages/core/src/repowise/core/ingestion/git_indexer/file_history.py
+++ b/packages/core/src/repowise/core/ingestion/git_indexer/file_history.py
@@ -106,6 +106,11 @@ def new_meta(file_path: str) -> dict[str, Any]:
"merge_commit_count_90d": 0,
# Temporal hotspot score (exponentially decayed churn)
"temporal_hotspot_score": 0.0,
+ # Change entropy (Hassan HCM) — populated repo-wide by the co-change
+ # walk, percentile by enrich.compute_percentiles. Default 0.0 leaves
+ # the signal silent on the ESSENTIAL tier / files that never co-changed.
+ "change_entropy": 0.0,
+ "change_entropy_pct": 0.0,
}
diff --git a/packages/core/src/repowise/core/ingestion/git_indexer/indexer.py b/packages/core/src/repowise/core/ingestion/git_indexer/indexer.py
index 480965e29..e9503af33 100644
--- a/packages/core/src/repowise/core/ingestion/git_indexer/indexer.py
+++ b/packages/core/src/repowise/core/ingestion/git_indexer/indexer.py
@@ -24,7 +24,7 @@ from ._constants import (
_DEFAULT_COMMIT_LIMIT,
_FILE_INDEX_TIMEOUT_SECS,
)
-from .co_change import compute_co_changes
+from .co_change import compute_co_changes, compute_co_changes_and_entropy
from .enrich import compute_percentiles
from .file_history import index_file
from .records import GitIndexSummary, _CommitRec, _should_skip_index
@@ -115,9 +115,7 @@ class GitIndexer:
if not self.follow_renames:
from ..git_commit_index import load_commit_index
- commit_index = load_commit_index(
- repo, self.commit_limit, set(indexable_files)
- )
+ commit_index = load_commit_index(repo, self.commit_limit, set(indexable_files))
include_blame = self.tier.includes_blame
@@ -126,9 +124,7 @@ class GitIndexer:
try:
import git as gitpython
- thread_repo = gitpython.Repo(
- self.repo_path, search_parent_directories=True
- )
+ thread_repo = gitpython.Repo(self.repo_path, search_parent_directories=True)
try:
precomputed = commit_index.get(file_path) if commit_index else None
return index_file(
@@ -160,9 +156,7 @@ class GitIndexer:
)
result = {"file_path": file_path}
except Exception as exc:
- logger.debug(
- "Git indexing failed for file", path=file_path, error=str(exc)
- )
+ logger.debug("Git indexing failed for file", path=file_path, error=str(exc))
result = {"file_path": file_path}
if on_file_done is not None:
on_file_done()
@@ -170,17 +164,18 @@ class GitIndexer:
file_tasks = [index_one(fp) for fp in indexable_files]
- async def _co_change_task() -> dict[str, list[dict]]:
+ async def _co_change_task() -> tuple[dict[str, list[dict]], dict[str, float]]:
# ESSENTIAL tier defers co-change entirely (the expensive repo-wide
- # walk) — return empty and let a FULL backfill fill it in.
+ # walk) — return empty and let a FULL backfill fill it in. Change
+ # entropy rides the same walk, so it's deferred together.
if not self.tier.includes_co_change:
if on_co_change_done is not None:
with contextlib.suppress(Exception):
on_co_change_done()
- return {}
+ return {}, {}
result = await loop.run_in_executor(
executor,
- compute_co_changes,
+ compute_co_changes_and_entropy,
repo,
set(tracked_files),
max(self.commit_limit, _DEFAULT_CO_CHANGE_COMMIT_LIMIT),
@@ -193,7 +188,7 @@ class GitIndexer:
on_co_change_done()
return result
- metadata_list, co_changes = await asyncio.gather(
+ metadata_list, (co_changes, change_entropy) = await asyncio.gather(
asyncio.gather(*file_tasks, return_exceptions=True),
_co_change_task(),
)
@@ -209,11 +204,13 @@ class GitIndexer:
else:
results.append(r)
- # Merge co-change partners into per-file metadata
+ # Merge co-change partners + change entropy into per-file metadata.
for meta in results:
fp = meta["file_path"]
if fp in co_changes:
meta["co_change_partners_json"] = json.dumps(co_changes[fp])
+ if fp in change_entropy:
+ meta["change_entropy"] = change_entropy[fp]
compute_percentiles(results)
@@ -253,9 +250,7 @@ class GitIndexer:
try:
import git as gitpython
- thread_repo = gitpython.Repo(
- self.repo_path, search_parent_directories=True
- )
+ thread_repo = gitpython.Repo(self.repo_path, search_parent_directories=True)
try:
return index_file(
thread_repo,
diff --git a/packages/core/src/repowise/core/persistence/crud/git.py b/packages/core/src/repowise/core/persistence/crud/git.py
index fccbaea9c..2a17cf966 100644
--- a/packages/core/src/repowise/core/persistence/crud/git.py
+++ b/packages/core/src/repowise/core/persistence/crud/git.py
@@ -130,13 +130,17 @@ async def recompute_git_percentiles(
session: AsyncSession,
repository_id: str,
) -> int:
- """Recompute churn_percentile + is_hotspot using a SQL PERCENT_RANK window function.
+ """Recompute churn_percentile, is_hotspot, and change_entropy_pct using SQL
+ PERCENT_RANK window functions.
Called after incremental updates so that percentile rankings stay fresh
without a full ``repowise init``. Returns the number of rows updated.
- Primary ranking signal is temporal_hotspot_score (exponentially decayed churn);
- commit_count_90d is the tiebreak. Works on both SQLite (3.25+) and PostgreSQL.
+ Primary churn ranking signal is temporal_hotspot_score (exponentially decayed
+ churn); commit_count_90d is the tiebreak. change_entropy_pct ranks files by
+ change_entropy ascending — zero-entropy files tie at the minimum (0.0), so
+ they stay below the biomarker's ≥0.80 gate. Works on both SQLite (3.25+) and
+ PostgreSQL.
"""
# First check how many rows exist so we can return the count without an
# extra query after the UPDATE.
@@ -149,17 +153,23 @@ async def recompute_git_percentiles(
sql = """
WITH ranked AS (
- SELECT id, PERCENT_RANK() OVER (
- PARTITION BY repository_id
- ORDER BY COALESCE(temporal_hotspot_score, 0.0), commit_count_90d
- ) AS prank
+ SELECT id,
+ PERCENT_RANK() OVER (
+ PARTITION BY repository_id
+ ORDER BY COALESCE(temporal_hotspot_score, 0.0), commit_count_90d
+ ) AS prank,
+ PERCENT_RANK() OVER (
+ PARTITION BY repository_id
+ ORDER BY COALESCE(change_entropy, 0.0)
+ ) AS erank
FROM git_metadata
WHERE repository_id = :repo_id
)
UPDATE git_metadata
SET churn_percentile = (SELECT prank FROM ranked WHERE ranked.id = git_metadata.id),
is_hotspot = ((SELECT prank FROM ranked WHERE ranked.id = git_metadata.id) >= 0.75
- AND git_metadata.commit_count_90d > 0)
+ AND git_metadata.commit_count_90d > 0),
+ change_entropy_pct = (SELECT erank FROM ranked WHERE ranked.id = git_metadata.id)
WHERE repository_id = :repo_id;
"""
await session.execute(text(sql), {"repo_id": repository_id})
diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.py
index e7c88700f..03d98b6e3 100644
--- a/packages/core/src/repowise/core/persistence/models.py
+++ b/packages/core/src/repowise/core/persistence/models.py
@@ -391,6 +391,12 @@ class GitMetadata(Base):
# Temporal hotspot score: exponentially time-decayed churn signal
temporal_hotspot_score: Mapped[float | None] = mapped_column(Float, nullable=True, default=0.0)
+ # Change entropy (Hassan History Complexity Metric): decay-weighted sum of
+ # per-commit scatter (log2(files-touched)/files-touched) and its repo-wide
+ # percentile. Populated by the FULL-tier co-change walk.
+ change_entropy: Mapped[float] = mapped_column(Float, nullable=False, default=0.0)
+ change_entropy_pct: Mapped[float] = mapped_column(Float, nullable=False, default=0.0)
+
created_at: Mapped[datetime] = mapped_column(
DateTime(timezone=True), nullable=False, default=_now_utc
)
diff --git a/tests/unit/health/test_organizational_biomarkers.py b/tests/unit/health/test_organizational_biomarkers.py
index aa98368a1..35339ae30 100644
--- a/tests/unit/health/test_organizational_biomarkers.py
+++ b/tests/unit/health/test_organizational_biomarkers.py
@@ -1,12 +1,18 @@
"""Organizational biomarker tests: Developer Congestion, Knowledge Loss,
-Ownership Risk, Churn Risk."""
+Ownership Risk, Churn Risk, Change Entropy, Co-change Scatter."""
from __future__ import annotations
import json
from repowise.core.analysis.health.biomarkers import FileContext
+from repowise.core.analysis.health.biomarkers.change_entropy import (
+ ChangeEntropyDetector,
+)
from repowise.core.analysis.health.biomarkers.churn_risk import ChurnRiskDetector
+from repowise.core.analysis.health.biomarkers.co_change_scatter import (
+ CoChangeScatterDetector,
+)
from repowise.core.analysis.health.biomarkers.developer_congestion import (
DeveloperCongestionDetector,
)
@@ -248,3 +254,106 @@ def test_churn_risk_skips_size_proportionate_churn():
"lines_deleted_90d": 10, # 30/120 = 0.25 < 1.0
}
assert ChurnRiskDetector().detect(_ctx(meta)) == []
+
+
+# ---- change_entropy ------------------------------------------------------
+
+
+def test_change_entropy_fires_on_high_percentile():
+ meta = {
+ "change_entropy": 1.4,
+ "change_entropy_pct": 0.88,
+ "commit_count_90d": 6,
+ "is_hotspot": False,
+ }
+ out = ChangeEntropyDetector().detect(_ctx(meta))
+ assert len(out) == 1
+ assert out[0].severity == "medium" # 0.80 <= pct < 0.90
+ assert out[0].details["change_entropy_pct"] == 0.88
+
+
+def test_change_entropy_escalates_to_critical_on_hotspot():
+ meta = {
+ "change_entropy": 3.2,
+ "change_entropy_pct": 0.97,
+ "commit_count_90d": 9,
+ "is_hotspot": True,
+ }
+ out = ChangeEntropyDetector().detect(_ctx(meta))
+ assert out
+ assert out[0].severity == "critical" # pct >= 0.95 and hotspot
+
+
+def test_change_entropy_skips_when_below_percentile():
+ meta = {
+ "change_entropy": 0.6,
+ "change_entropy_pct": 0.5, # below the 0.80 floor
+ "commit_count_90d": 6,
+ }
+ assert ChangeEntropyDetector().detect(_ctx(meta)) == []
+
+
+def test_change_entropy_skips_low_activity():
+ meta = {
+ "change_entropy": 2.0,
+ "change_entropy_pct": 0.95,
+ "commit_count_90d": 2, # below the 3-commit activity gate
+ }
+ assert ChangeEntropyDetector().detect(_ctx(meta)) == []
+
+
+def test_change_entropy_silent_without_signal():
+ # ESSENTIAL tier / file that never co-changed → no entropy, no firing
+ # even though the (defaulted) percentile field is present.
+ meta = {"change_entropy": 0.0, "change_entropy_pct": 0.0, "commit_count_90d": 8}
+ assert ChangeEntropyDetector().detect(_ctx(meta)) == []
+
+
+# ---- co_change_scatter ---------------------------------------------------
+
+
+def _partners(*pairs: tuple[str, float]) -> str:
+ return json.dumps([{"file_path": p, "co_change_count": c} for p, c in pairs])
+
+
+def test_co_change_scatter_fires_on_broad_coupling():
+ meta = {
+ "co_change_partners_json": _partners(*[(f"m{i}.py", 3.0) for i in range(9)]),
+ "commit_count_90d": 5,
+ }
+ out = CoChangeScatterDetector().detect(_ctx(meta))
+ assert len(out) == 1
+ assert out[0].severity == "medium" # 8 <= scatter < 15
+ assert out[0].details["scatter"] == 9
+
+
+def test_co_change_scatter_high_severity_on_heavy_coupling():
+ meta = {
+ "co_change_partners_json": _partners(*[(f"m{i}.py", 2.5) for i in range(16)]),
+ "commit_count_90d": 7,
+ }
+ out = CoChangeScatterDetector().detect(_ctx(meta))
+ assert out
+ assert out[0].severity == "high" # scatter >= 15
+
+
+def test_co_change_scatter_ignores_weak_partners():
+ # Many partners, but all below the 2.0 weight floor → scatter == 0.
+ meta = {
+ "co_change_partners_json": _partners(*[(f"m{i}.py", 1.0) for i in range(12)]),
+ "commit_count_90d": 5,
+ }
+ assert CoChangeScatterDetector().detect(_ctx(meta)) == []
+
+
+def test_co_change_scatter_skips_low_activity():
+ meta = {
+ "co_change_partners_json": _partners(*[(f"m{i}.py", 3.0) for i in range(10)]),
+ "commit_count_90d": 1,
+ }
+ assert CoChangeScatterDetector().detect(_ctx(meta)) == []
+
+
+def test_co_change_scatter_silent_on_essential_tier():
+ # Empty partner list (ESSENTIAL git tier) → no signal.
+ assert CoChangeScatterDetector().detect(_ctx({"commit_count_90d": 8})) == []
diff --git a/tests/unit/health/test_scoring_snapshot.py b/tests/unit/health/test_scoring_snapshot.py
index 7981ce006..fb3e59315 100644
--- a/tests/unit/health/test_scoring_snapshot.py
+++ b/tests/unit/health/test_scoring_snapshot.py
@@ -45,6 +45,8 @@ _EXPECTED_BIOMARKER_WEIGHT_MULTIPLIER = {
"hidden_coupling": 1.0,
"ownership_risk": 1.3,
"churn_risk": 1.2,
+ "change_entropy": 1.1,
+ "co_change_scatter": 1.0,
"knowledge_loss": 0.4,
# Phase 4B governance biomarkers (informational — surfaced as findings,
# not fed back into the score pass, which has already run upstream).
@@ -71,6 +73,8 @@ _EXPECTED_BIOMARKER_CATEGORY = {
"code_age_volatility": "organizational",
"ownership_risk": "organizational",
"churn_risk": "organizational",
+ "change_entropy": "organizational",
+ "co_change_scatter": "organizational",
# Phase 4B governance biomarkers.
"ungoverned_hotspot": "organizational",
"stale_governance": "organizational",
diff --git a/tests/unit/test_git_indexer.py b/tests/unit/test_git_indexer.py
index 5c608b06b..ebe535b2e 100644
--- a/tests/unit/test_git_indexer.py
+++ b/tests/unit/test_git_indexer.py
@@ -321,18 +321,21 @@ class TestNumstatParsing:
now = datetime.now(UTC)
recent_ts = int((now - timedelta(days=5)).timestamp())
- raw = self._build_log_output("src/app.py", [
- {
- "sha": "aaa11111",
- "ts": recent_ts,
- "subject": "feat: big change",
- "numstat_lines": [
- ("100", "50", "src/app.py"), # target: should count
- ("500", "300", "src/other.py"), # not target: must NOT count
- ("200", "100", "src/utils.py"), # not target: must NOT count
- ],
- },
- ])
+ raw = self._build_log_output(
+ "src/app.py",
+ [
+ {
+ "sha": "aaa11111",
+ "ts": recent_ts,
+ "subject": "feat: big change",
+ "numstat_lines": [
+ ("100", "50", "src/app.py"), # target: should count
+ ("500", "300", "src/other.py"), # not target: must NOT count
+ ("200", "100", "src/utils.py"), # not target: must NOT count
+ ],
+ },
+ ],
+ )
mock_repo.git.log.return_value = raw
meta = indexer._index_file("src/app.py", mock_repo)
@@ -348,16 +351,19 @@ class TestNumstatParsing:
recent_ts = int((datetime.now(UTC) - timedelta(days=5)).timestamp())
- raw = self._build_log_output("icon.png", [
- {
- "sha": "bbb22222",
- "ts": recent_ts,
- "subject": "feat: add icon",
- "numstat_lines": [
- ("-", "-", "icon.png"),
- ],
- },
- ])
+ raw = self._build_log_output(
+ "icon.png",
+ [
+ {
+ "sha": "bbb22222",
+ "ts": recent_ts,
+ "subject": "feat: add icon",
+ "numstat_lines": [
+ ("-", "-", "icon.png"),
+ ],
+ },
+ ],
+ )
mock_repo.git.log.return_value = raw
meta = indexer._index_file("icon.png", mock_repo)
@@ -496,6 +502,87 @@ class TestCoChangeBelowThresholdSkipped:
assert result == {}
+# ---------------------------------------------------------------------------
+# 6b. test_change_entropy
+# ---------------------------------------------------------------------------
+
+
+class TestChangeEntropy:
+ """Hassan HCM: focused single-file commits → ~0 entropy; wide scattered
+ commits → high entropy; commits above the file-set cap are excluded."""
+
+ def test_change_entropy_focused_vs_scattered(self) -> None:
+ import time
+
+ from repowise.core.ingestion.git_indexer.co_change import (
+ compute_co_changes_and_entropy,
+ )
+
+ scattered_peers = [f"peer_{i}.py" for i in range(9)]
+ huge_peers = [f"huge_{i}.py" for i in range(34)]
+ all_files = {"focused.py", "scattered.py", "bigcommit.py"}
+ all_files.update(scattered_peers)
+ all_files.update(huge_peers)
+
+ now = int(time.time())
+ blocks: list[str] = []
+ # 3 focused commits: focused.py changes ALONE (|F| == 1 → log2(1) == 0).
+ for i in range(3):
+ blocks.append(f"\x00{now - i * 86400}\nfocused.py\n")
+ # 3 scattered commits: scattered.py amid 9 peers (|F| == 10).
+ for i in range(3):
+ files = "\n".join(["scattered.py", *scattered_peers])
+ blocks.append(f"\x00{now - i * 86400}\n{files}\n")
+ # 1 mass-edit commit (|F| == 35 > 30): bigcommit.py must get NO entropy.
+ big_files = "\n".join(["bigcommit.py", *huge_peers])
+ blocks.append(f"\x00{now}\n{big_files}\n")
+
+ mock_repo = MagicMock()
+ mock_repo.git.log.return_value = "".join(blocks)
+
+ _co, entropy = compute_co_changes_and_entropy(
+ mock_repo, all_files, commit_limit=2000, min_count=2
+ )
+
+ # Focused file changed alone → no entropy entry.
+ assert entropy.get("focused.py", 0.0) == 0.0
+ # Scattered file accrued positive entropy.
+ assert entropy.get("scattered.py", 0.0) > 0.0
+ # Mass-edit commit excluded → bigcommit.py gets nothing from it.
+ assert entropy.get("bigcommit.py", 0.0) == 0.0
+ # Scattered clearly dominates focused.
+ assert entropy["scattered.py"] > entropy.get("focused.py", 0.0)
+
+ def test_change_entropy_percentile_silent_when_all_zero(self) -> None:
+ """ESSENTIAL-tier shape (no entropy on any file) → all pct stay 0.0."""
+ from repowise.core.ingestion.git_indexer.enrich import compute_percentiles
+
+ metadata_list = [
+ {"file_path": f"f{i}.py", "commit_count_90d": 5, "change_entropy": 0.0}
+ for i in range(5)
+ ]
+ compute_percentiles(metadata_list)
+ for m in metadata_list:
+ assert m["change_entropy_pct"] == 0.0
+
+ def test_change_entropy_percentile_ranks_nonzero(self) -> None:
+ """Only files with positive entropy are ranked; zero-entropy files stay 0.0."""
+ from repowise.core.ingestion.git_indexer.enrich import compute_percentiles
+
+ metadata_list = [
+ {"file_path": "zero.py", "change_entropy": 0.0},
+ {"file_path": "low.py", "change_entropy": 0.5},
+ {"file_path": "mid.py", "change_entropy": 1.0},
+ {"file_path": "high.py", "change_entropy": 2.0},
+ ]
+ compute_percentiles(metadata_list)
+ pct = {m["file_path"]: m["change_entropy_pct"] for m in metadata_list}
+ assert pct["zero.py"] == 0.0
+ # Three nonzero files ranked 0, 1, 2 over n=3 → 0.0, 0.333, 0.667.
+ assert pct["high.py"] > pct["mid.py"] > pct["low.py"]
+ assert pct["high.py"] == pytest.approx(2 / 3)
+
+
# ---------------------------------------------------------------------------
# 7. test_blame_ownership_computed
# ---------------------------------------------------------------------------