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.

Phase 3 git intelligence: rename tracking, incremental fix, PR context, merge signals, smart staleness

RaghavChamadiya94b462592e43
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd.py b/packages/cli/src/repowise/cli/commands/init_cmd.py
index 9cbca048b..907c6a6b3 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd.py
@@ -245,6 +245,12 @@ def _interactive_provider_wizard(model_flag: str | None) -> tuple[str, str]:
default=None,
help="Max commits to analyze per file and for co-change detection (default: 500, max: 5000). Saved to config.",
)
+ "--follow-renames",
+ is_flag=True,
+ default=False,
+ help="Use git log --follow to track files across renames (slower but more accurate history). Saved to config.",
+)
def init_command(
path: str | None,
provider_name: str | None,
@@ -261,6 +267,7 @@ def init_command(
index_only: bool,
exclude: tuple[str, ...],
commit_limit: int | None,
+ follow_renames: bool,
) -> None:
"""Generate wiki documentation for a codebase.
@@ -286,6 +293,11 @@ def init_command(
if commit_limit is not None:
config["commit_limit"] = resolved_commit_limit
+ # Resolve follow_renames: CLI flag → config.yaml
+ resolved_follow_renames: bool = follow_renames or config.get("follow_renames", False)
+ if follow_renames:
+ config["follow_renames"] = True
+
embedder = _resolve_embedder(embedder_name)
if index_only:
@@ -356,7 +368,11 @@ def init_command(
try:
from repowise.core.ingestion.git_indexer import GitIndexer
- git_indexer = GitIndexer(repo_path, commit_limit=resolved_commit_limit)
+ git_indexer = GitIndexer(
+ repo_path,
+ commit_limit=resolved_commit_limit,
+ follow_renames=resolved_follow_renames,
+ )
def _run_git_indexing() -> tuple:
def on_start(total: int) -> None:
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd.py b/packages/cli/src/repowise/cli/commands/update_cmd.py
index 921dc64cf..306e592b5 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd.py
@@ -118,7 +118,12 @@ def update_command(
from repowise.core.ingestion.git_indexer import GitIndexer
_commit_limit = repo_config.get("commit_limit")
- git_indexer = GitIndexer(repo_path, commit_limit=_commit_limit)
+ _follow_renames = repo_config.get("follow_renames", False)
+ git_indexer = GitIndexer(
+ repo_path,
+ commit_limit=_commit_limit,
+ follow_renames=_follow_renames,
+ )
changed_paths = [fd.path for fd in file_diffs]
updated_meta = run_async(git_indexer.index_changed_files(changed_paths))
git_meta_map = {m["file_path"]: m for m in updated_meta}
@@ -196,6 +201,22 @@ def update_command(
for page in generated_pages:
await upsert_page_from_generated(session, page, repo_id)
+ # Persist updated git metadata + recompute percentiles
+ if git_meta_map:
+ try:
+ from repowise.core.persistence.crud import (
+ recompute_git_percentiles,
+ upsert_git_metadata_bulk,
+ )
+
+ async with get_session(sf) as session:
+ await upsert_git_metadata_bulk(
+ session, repo_id, list(git_meta_map.values()),
+ )
+ await recompute_git_percentiles(session, repo_id)
+ except Exception:
+ pass # git persistence is best-effort
+
# Decision records: persist new markers + recompute staleness
try:
if new_decision_markers:
diff --git a/packages/core/alembic/versions/0008_git_phase3_rename_merge.py b/packages/core/alembic/versions/0008_git_phase3_rename_merge.py
new file mode 100644
index 000000000..3737a61fb
--- /dev/null
+++ b/packages/core/alembic/versions/0008_git_phase3_rename_merge.py
@@ -0,0 +1,38 @@
+"""Add Phase 3 git intelligence columns to git_metadata.
+
+New signals: rename tracking (original_path) and merge commit
+frequency (merge_commit_count_90d).
+
+Revision ID: 0008
+Revises: 0007
+Create Date: 2026-03-26
+"""
+
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers
+revision: str = "0008"
+down_revision: Union[str, None] = "0007"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+ op.add_column(
+ "git_metadata",
+ sa.Column("original_path", sa.Text, nullable=True),
+ )
+ op.add_column(
+ "git_metadata",
+ sa.Column("merge_commit_count_90d", sa.Integer, nullable=False, server_default="0"),
+ )
+
+
+def downgrade() -> None:
+ op.drop_column("git_metadata", "merge_commit_count_90d")
+ op.drop_column("git_metadata", "original_path")
diff --git a/packages/core/src/repowise/core/analysis/decision_extractor.py b/packages/core/src/repowise/core/analysis/decision_extractor.py
index 680e78d1a..2ab308a15 100644
--- a/packages/core/src/repowise/core/analysis/decision_extractor.py
+++ b/packages/core/src/repowise/core/analysis/decision_extractor.py
@@ -532,18 +532,33 @@ class DecisionExtractor:
# Staleness computation (static method)
# ------------------------------------------------------------------
+ # Keywords that signal a decision may have been contradicted or superseded.
+ _CONFLICT_SIGNALS = frozenset({
+ "replace", "remove", "deprecate", "switch from", "migrate away",
+ "drop", "revert", "undo", "disable", "eliminate",
+ })
+
@staticmethod
def compute_staleness(
decision_created_at: datetime,
affected_files: list[str],
git_meta_map: dict[str, dict],
+ decision_text: str = "",
) -> float:
- """Compute staleness score for a decision. Returns 0.0–1.0."""
+ """Compute staleness score for a decision. Returns 0.0–1.0.
+
+ In addition to commit volume and age, checks whether recent commit
+ messages contain keywords that conflict with the decision text
+ (e.g. decision says "use Redis" but a recent commit says "migrate
+ away from Redis"). This boosts staleness when the underlying code
+ may have diverged from the decision's intent.
+ """
if not affected_files:
return 0.0
now = datetime.now(timezone.utc)
scores: list[float] = []
+ decision_lower = decision_text.lower()
for fp in affected_files:
meta = git_meta_map.get(fp)
@@ -557,17 +572,48 @@ class DecisionExtractor:
last_commit = datetime.fromisoformat(
last_commit.replace("Z", "+00:00")
)
- if isinstance(decision_created_at, str):
- decision_created_at = datetime.fromisoformat(
- decision_created_at.replace("Z", "+00:00")
+ _created = decision_created_at
+ if isinstance(_created, str):
+ _created = datetime.fromisoformat(
+ _created.replace("Z", "+00:00")
)
- if last_commit > decision_created_at:
- age_days = (now - decision_created_at).days
+ if last_commit > _created:
+ age_days = (now - _created).days
commit_count = meta.get("commit_count_90d", 0)
- score = min(
+ base_score = min(
1.0,
commit_count / 15 * 0.7 + age_days / 365 * 0.3,
)
+
+ # Keyword conflict boost: check if recent commits
+ # contradict the decision's content.
+ conflict_boost = 0.0
+ if decision_lower:
+ sig_json = meta.get("significant_commits_json", "[]")
+ try:
+ sig_commits = json.loads(sig_json) if isinstance(sig_json, str) else sig_json
+ except (json.JSONDecodeError, TypeError):
+ sig_commits = []
+ for sc in sig_commits:
+ sc_date = sc.get("date", "")
+ # Only consider commits after the decision was created
+ if sc_date and sc_date > _created.isoformat():
+ msg_lower = sc.get("message", "").lower()
+ for signal in DecisionExtractor._CONFLICT_SIGNALS:
+ if signal in msg_lower:
+ # Check if the commit message shares meaningful
+ # words with the decision text (context overlap)
+ msg_words = set(msg_lower.split())
+ dec_words = set(decision_lower.split())
+ overlap = msg_words & dec_words - {
+ "the", "a", "an", "to", "in", "for",
+ "and", "or", "of", "is", "was", "with",
+ }
+ if len(overlap) >= 2:
+ conflict_boost = max(conflict_boost, 0.3)
+ break
+
+ score = min(1.0, base_score + conflict_boost)
scores.append(score)
else:
scores.append(0.0)
diff --git a/packages/core/src/repowise/core/ingestion/git_indexer.py b/packages/core/src/repowise/core/ingestion/git_indexer.py
index a110d0583..67e4cfa09 100644
--- a/packages/core/src/repowise/core/ingestion/git_indexer.py
+++ b/packages/core/src/repowise/core/ingestion/git_indexer.py
@@ -86,6 +86,10 @@ _COMMIT_CATEGORIES: dict[str, re.Pattern[str]] = {
# Co-change temporal decay: half-life ~125 days (lambda for exp(-t/tau)).
_CO_CHANGE_DECAY_TAU: float = 180.0
+# Regex to extract PR/MR numbers from commit messages.
+# Matches: "#123", "Merge pull request #456", "(#789)", "!42" (GitLab MR)
+_PR_NUMBER_RE = re.compile(r"(?:pull request |)\#(\d+)|\(#(\d+)\)|!(\d+)")
+
# Allowlist of extensions for which per-file git indexing (blame, commit
# history, hotspot/stable classification) is worth running. Anything NOT in
# this set is skipped — data, config, markup, dotfiles, and binaries add no
@@ -184,9 +188,16 @@ class GitIndexer:
and return an empty summary. All downstream features degrade gracefully.
"""
- def __init__(self, repo_path: str | Path, *, commit_limit: int | None = None) -> None:
+ def __init__(
+ self,
+ repo_path: str | Path,
+ *,
+ commit_limit: int | None = None,
+ follow_renames: bool = False,
+ ) -> None:
self.repo_path = Path(repo_path)
self.commit_limit = commit_limit or _DEFAULT_COMMIT_LIMIT
+ self.follow_renames = follow_renames
async def index_repo(
self,
@@ -402,10 +413,13 @@ class GitIndexer:
"recent_owner_commit_pct": None,
"bus_factor": 0,
"contributor_count": 0,
+ # Phase 3 fields
+ "original_path": None,
+ "merge_commit_count_90d": 0,
}
try:
- commits = list(repo.iter_commits(paths=file_path, max_count=self.commit_limit))
+ commits = self._get_commits(file_path, repo)
except Exception:
return meta
@@ -499,18 +513,24 @@ class GitIndexer:
except Exception:
pass # blame is best-effort
- # Significant commits + classification
+ # Significant commits + classification + PR extraction
sig_commits = []
category_counts: Counter[str] = Counter()
for c in commits:
msg = c.message.strip().split("\n")[0][:200]
if self._is_significant_commit(c.message, c.author.name or ""):
- sig_commits.append({
+ entry: dict[str, Any] = {
"sha": c.hexsha[:8],
"date": c.committed_datetime.isoformat(),
"message": msg,
"author": c.author.name or "unknown",
- })
+ }
+ # Extract PR/MR number from commit message
+ pr_match = _PR_NUMBER_RE.search(c.message)
+ if pr_match:
+ pr_num = pr_match.group(1) or pr_match.group(2) or pr_match.group(3)
+ entry["pr_number"] = int(pr_num)
+ sig_commits.append(entry)
if len(sig_commits) >= 10:
break
# Classify ALL commits (not just significant) for accurate ratios
@@ -531,6 +551,17 @@ class GitIndexer:
(added + deleted) / c90 if c90 > 0 else 0.0
)
+ # Original path detection (rename tracking)
+ if self.follow_renames:
+ orig = self._detect_original_path(file_path, repo)
+ if orig:
+ meta["original_path"] = orig
+
+ # Merge commit count (coordination bottleneck signal)
+ meta["merge_commit_count_90d"] = self._get_merge_commit_count(
+ file_path, repo, ninety_days_ago,
+ )
+
# Stable classification
if meta["commit_count_total"] > 10 and meta["commit_count_90d"] == 0:
meta["is_stable"] = True
@@ -540,6 +571,66 @@ class GitIndexer:
return meta
+ def _get_commits(self, file_path: str, repo: Any) -> list[Any]:
+ """Get commits for a file, optionally following renames via --follow."""
+ if not self.follow_renames:
+ return list(repo.iter_commits(paths=file_path, max_count=self.commit_limit))
+
+ # --follow tracks the file across renames; iter_commits doesn't support it.
+ # Get SHAs via git log --follow, then resolve to commit objects.
+ try:
+ raw = repo.git.log(
+ "--follow", f"-{self.commit_limit}",
+ "--format=%H",
+ "--", file_path,
+ )
+ except Exception:
+ return []
+
+ commits = []
+ for line in raw.splitlines():
+ sha = line.strip()
+ if sha:
+ try:
+ commits.append(repo.commit(sha))
+ except Exception:
+ continue
+ return commits
+
+ def _detect_original_path(self, file_path: str, repo: Any) -> str | None:
+ """If --follow reveals the file was renamed, return its earliest prior path."""
+ try:
+ raw = repo.git.log(
+ "--follow", f"-{self.commit_limit}",
+ "--format=", "--name-only",
+ "--", file_path,
+ )
+ except Exception:
+ return None
+
+ # Paths appear newest-first; the last distinct path is the original.
+ prev_path: str | None = None
+ for line in raw.splitlines():
+ p = line.strip()
+ if p and p != file_path:
+ prev_path = p # keep overwriting — last one is oldest
+ return prev_path
+
+ def _get_merge_commit_count(
+ self, file_path: str, repo: Any, since: datetime,
+ ) -> int:
+ """Count how many merge commits touched this file since a given date."""
+ try:
+ raw = repo.git.log(
+ "--merges",
+ f"--since={since.strftime('%Y-%m-%d')}",
+ "--format=%H",
+ "--", file_path,
+ )
+ except Exception:
+ return 0
+ return sum(1 for line in raw.splitlines() if line.strip())
+
def _get_blame_ownership(
self, file_path: str, repo: Any
) -> tuple[str | None, str | None, float | None]:
@@ -739,7 +830,8 @@ class GitIndexer:
return dict(result)
- def _compute_percentiles(self, metadata_list: list[dict]) -> None:
+ @staticmethod
+ def _compute_percentiles(metadata_list: list[dict]) -> None:
"""Compute churn_percentile and is_hotspot. Mutates in place."""
if not metadata_list:
return
diff --git a/packages/core/src/repowise/core/persistence/crud.py b/packages/core/src/repowise/core/persistence/crud.py
index af3875700..7c3fff5b7 100644
--- a/packages/core/src/repowise/core/persistence/crud.py
+++ b/packages/core/src/repowise/core/persistence/crud.py
@@ -719,6 +719,36 @@ async def upsert_git_metadata_bulk(
await session.flush()
+async def recompute_git_percentiles(
+ session: AsyncSession, repository_id: str,
+) -> int:
+ """Reload all git_metadata rows and recompute churn_percentile + is_hotspot.
+
+ Called after incremental updates so that percentile rankings stay fresh
+ without a full ``repowise init``. Returns the number of rows updated.
+ """
+ result = await session.execute(
+ select(GitMetadata).where(GitMetadata.repository_id == repository_id)
+ )
+ rows = result.scalars().all()
+ if not rows:
+ return 0
+
+ # Sort by 90-day commit count for percentile ranking
+ sorted_rows = sorted(rows, key=lambda r: r.commit_count_90d or 0)
+ total = len(sorted_rows)
+
+ for rank, row in enumerate(sorted_rows):
+ pct = rank / total if total > 0 else 0.0
+ row.churn_percentile = pct
+ c90 = row.commit_count_90d or 0
+ row.is_hotspot = pct >= 0.75 and c90 > 0
+ row.updated_at = _now_utc()
+
+ await session.flush()
+ return total
+
+
# ---------------------------------------------------------------------------
# DeadCodeFinding CRUD
# ---------------------------------------------------------------------------
@@ -1079,30 +1109,12 @@ async def recompute_decision_staleness(
if not affected:
continue
- scores: list[float] = []
- for fp in affected:
- meta = git_meta_map.get(fp)
- if meta is None:
- scores.append(1.0) # file deleted or not tracked
- continue
- last_commit = meta.get("last_commit_at")
- if last_commit and dec.created_at:
- # Parse if string
- if isinstance(last_commit, str):
- last_commit = datetime.fromisoformat(
- last_commit.replace("Z", "+00:00")
- )
- if last_commit > dec.created_at:
- age_days = (now - dec.created_at).days
- commit_count = meta.get("commit_count_90d", 0)
- file_score = min(1.0, commit_count / 15 * 0.7 + age_days / 365 * 0.3)
- scores.append(file_score)
- else:
- scores.append(0.0)
- else:
- scores.append(0.0)
+ from repowise.core.analysis.decision_extractor import DecisionExtractor
- new_score = sum(scores) / len(scores) if scores else 0.0
+ decision_text = f"{dec.title} {dec.decision} {dec.rationale}"
+ new_score = DecisionExtractor.compute_staleness(
+ dec.created_at, affected, git_meta_map, decision_text=decision_text,
+ )
if abs(new_score - dec.staleness_score) > 0.01:
dec.staleness_score = round(new_score, 3)
dec.updated_at = now
diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.py
index 0f1e38fb1..afa8ab2ad 100644
--- a/packages/core/src/repowise/core/persistence/models.py
+++ b/packages/core/src/repowise/core/persistence/models.py
@@ -315,6 +315,10 @@ class GitMetadata(Base):
bus_factor: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
contributor_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+ # Rename tracking & merge conflict proxy (Phase 3)
+ original_path: Mapped[str | None] = mapped_column(Text, nullable=True)
+ merge_commit_count_90d: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+
created_at: Mapped[datetime] = mapped_column(
DateTime(timezone=True), nullable=False, default=_now_utc
)
diff --git a/packages/server/src/repowise/server/mcp_server.py b/packages/server/src/repowise/server/mcp_server.py
index 75404746c..cd497ee0e 100644
--- a/packages/server/src/repowise/server/mcp_server.py
+++ b/packages/server/src/repowise/server/mcp_server.py
@@ -921,6 +921,10 @@ async def _assess_one_target(
bus_factor = getattr(meta, "bus_factor", 0) or 0
contributor_count = getattr(meta, "contributor_count", 0) or 0
+ # Phase 3: rename tracking & merge commit proxy
+ original_path = getattr(meta, "original_path", None)
+ merge_commit_count = getattr(meta, "merge_commit_count_90d", 0) or 0
+
result_data["hotspot_score"] = hotspot_score
result_data["dependents_count"] = dep_count
result_data["co_change_partners"] = co_changes
@@ -939,6 +943,10 @@ async def _assess_one_target(
"avg_commit_size": round(avg_size, 1),
}
result_data["impact_surface"] = impact_surface
+ if original_path:
+ result_data["original_path"] = original_path
+ if merge_commit_count > 0:
+ result_data["merge_commit_count_90d"] = merge_commit_count
capped = getattr(meta, "commit_count_capped", False)
capped_note = " (history truncated — actual count may be higher)" if capped else ""