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.

refactor(risk): split _assess_one_target into stages and move history clauses to tool_risk/history (#4047)

Raghav Chamadiya93ae6577943f
diff --git a/packages/server/src/repowise/server/mcp_server/tool_risk/assessment.py b/packages/server/src/repowise/server/mcp_server/tool_risk/assessment.py
index f8b71683f..1edbaf3c7 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_risk/assessment.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_risk/assessment.py
@@ -3,10 +3,7 @@
from __future__ import annotations
import asyncio
-import contextlib
-import json
-import math
-from datetime import UTC, datetime
+from datetime import datetime
from pathlib import Path
from typing import Any
@@ -26,104 +23,30 @@ from repowise.server.mcp_server._helpers import (
is_excluded,
)
from repowise.server.mcp_server._meta import served_root
+from repowise.server.mcp_server.tool_risk.history import ( # noqa: F401 re-exported
+ _BUG_PRONE_FIXES,
+ _TOP_FIX_SYMBOLS,
+ _churn_clause,
+ _classify_risk_type,
+ _compute_trend,
+ _defect_profile,
+ _derive_change_pattern,
+ _fix_clause,
+ _history_tier_card,
+ _load_commit_categories,
+ _owner_clause,
+ _top_fix_symbols,
+ fix_annotation,
+ history_fields,
+ risk_summary,
+)
from repowise.server.repo_paths import missing_path_hint, normalize_target_path
-#: A file carrying this many counted bug fixes reads as bug-prone. Same trigger
-#: the PR bot uses for prior defects, so the two surfaces agree on "a lot".
-_BUG_PRONE_FIXES = 3
-
-#: How many attributed symbols the defect profile names. Enough to say "mostly
-#: these", short enough to keep the block inside the per-file token budget.
-_TOP_FIX_SYMBOLS = 3
-
# Relationship rows are deliberately bounded independently. Their totals are
# computed after repository exclusions and before this presentation cap.
_RELATIONSHIP_LIMIT = 5
-def _derive_change_pattern(categories: dict[str, int]) -> str:
- """Derive a human-readable change pattern from commit category counts."""
- if not categories:
- return "uncategorized"
- total = sum(categories.values())
- if total == 0:
- return "uncategorized"
- dominant = max(categories, key=lambda k: categories[k])
- ratio = categories[dominant] / total
- if ratio >= 0.5:
- labels = {
- "feature": "feature-active",
- "refactor": "primarily refactored",
- "fix": "fix-heavy",
- "dependency": "dependency-churn",
- }
- return labels.get(dominant, dominant)
- return "mixed-activity"
-
-
-def _compute_trend(meta: Any) -> str:
- """Compute risk velocity from 30d vs 90d commit rates."""
- c30 = meta.commit_count_30d or 0
- c90 = meta.commit_count_90d or 0
- # Baseline: commits in the 60-day window before the last 30 days
- baseline_commits = c90 - c30
- recent_rate = c30 / 30.0
- baseline_rate = baseline_commits / 60.0
-
- if c90 == 0:
- return "stable"
- if baseline_rate == 0:
- return "increasing" if c30 > 0 else "stable"
- ratio = recent_rate / baseline_rate
- if ratio > 1.5:
- return "increasing"
- elif ratio < 0.5:
- return "decreasing"
- return "stable"
-
-
-def _classify_risk_type(meta: Any, dep_count: int, team_size: int | None = None) -> str:
- """Classify risk as churn-heavy, bug-prone, high-coupling, or bus-factor-risk.
-
- *team_size* is the repo's active-contributor count (90d). On a small
- team (≤ SMALL_TEAM_MAX_CONTRIBUTORS) a single-author file is the
- expected operating model, so ``bus-factor-risk`` is reserved for
- hotspot-active files there (issue #361). ``None`` = unknown → keep
- the historical behaviour.
-
- ``bug-prone`` reads the counted fix history rather than the old keyword
- scan over ``significant_commits``: that scan matched "fix" anywhere in a
- subject, counted doc and test commits, and had no recency at all, while
- ``prior_defect_count`` is the shape-filtered windowed count and
- ``bug_magnet`` is its decayed form. An index that predates the fix-event
- rollup reports 0/None here and simply falls through to the next rule,
- the same way every other backfilled column behaves until the next update.
- """
- from repowise.core.analysis.health.biomarkers.base import SMALL_TEAM_MAX_CONTRIBUTORS
-
- churn_score = meta.churn_percentile or 0.0
- bus_factor = getattr(meta, "bus_factor", 0) or 0
- total_commits = meta.commit_count_total or 0
-
- small_team = team_size is not None and team_size <= SMALL_TEAM_MAX_CONTRIBUTORS
-
- # Bug-prone takes priority: real counted fixes, decayed or plain.
- prior_defects = getattr(meta, "prior_defect_count", 0) or 0
- if getattr(meta, "bug_magnet", False) or prior_defects >= _BUG_PRONE_FIXES:
- return "bug-prone"
- if churn_score >= 0.7:
- return "churn-heavy"
- if (
- bus_factor == 1
- and total_commits > 20
- and (not small_team or bool(getattr(meta, "is_hotspot", False)))
- ):
- return "bus-factor-risk"
- if dep_count >= 5:
- return "high-coupling"
- return "stable"
-
-
async def _get_active_contributor_count(session: AsyncSession, repo_id: str) -> int | None:
"""Repo-wide active-contributor count from persisted git metadata.
@@ -302,127 +225,6 @@ def _build_co_changes(
return population, len(population)
-def fix_annotation(meta: Any, now: datetime | None = None) -> dict | None:
- """The shared count/age/magnet fix block used by context and risk.
-
- Centralized so the two tools agree on the wire format and the age contract
- is enforced once: the ``bug_magnet`` flag rides on the age and is never
- emitted alone. ``bug_magnet`` is a claim about RECENT fix pressure, so with
- no timestamp to anchor it the same word would describe a file fixed four
- times last month and one fixed four times two years ago.
-
- Read off the ``GitMetadata`` row the caller already loaded: no query.
- """
- count = getattr(meta, "prior_defect_count", 0) or 0
- if count <= 0:
- return None
-
- out: dict[str, Any] = {"fix_count": count}
- last_fix_at = getattr(meta, "last_fix_at", None)
- if isinstance(last_fix_at, datetime):
- # Rows are stored naive-UTC; compare on the same footing.
- ref = (
- datetime.now(UTC)
- if now is None
- else (now if now.tzinfo else now.replace(tzinfo=UTC))
- )
- moment = last_fix_at if last_fix_at.tzinfo else last_fix_at.replace(tzinfo=UTC)
- out["last_fix_days_ago"] = max(0, (ref - moment).days)
- if getattr(meta, "bug_magnet", False):
- out["bug_magnet"] = True
- return out
-
-
-def _fix_clause(profile: dict | None) -> str:
- """Lead clause for ``risk_summary``, or empty when there is no fix history.
-
- Trailing separator included so the caller concatenates without a dangling
- comma on files that have never been fixed. Never renders a count without an
- age: an unanchored count reads as a claim about the distant past.
- """
- if not profile or "last_fix_days_ago" not in profile:
- return ""
- n = profile["fix_count"]
- magnet = " (bug magnet)" if profile.get("bug_magnet") else ""
- return (
- f"{n} bug fix{'es' if n != 1 else ''} in 6mo, "
- f"last {profile['last_fix_days_ago']}d before the indexed commit{magnet}, "
- )
-
-
-def _churn_clause(churn_percentile: float, is_hotspot: bool, trend: str) -> str:
- """Churn clause for ``risk_summary``, or empty when the file is not a hotspot.
-
- ``churn_percentile`` is a rank (0 to 1), not a risk. Printed as a bare
- percentage it read like "100% risk", and it was printed for files below the
- hotspot cut too. So the clause states the rank as a rank ("top N%") and only
- for files the stored ``is_hotspot`` flag marks; ``trend`` stays available as
- its own field either way. Trailing separator included, as in ``_fix_clause``.
- """
- if not is_hotspot:
- return ""
- # Round before the ceiling: 1 - 0.86 is 0.14000000000000001 in floats, and
- # that would otherwise print as top 15%.
- top_pct = max(1, math.ceil(round((1.0 - churn_percentile) * 100, 6)))
- return f"churn hotspot, top {top_pct}% ({trend}), "
-
-
-def _defect_profile(meta: Any, now: datetime | None = None) -> dict | None:
- """What this file's counted bug fixes say about it, or ``None`` for silence.
-
- Built from the fix-event rollup already loaded on the ``GitMetadata`` row,
- so there is no second query. Silent when the file has no counted fixes, so a
- clean file and a repo with no fix history both add nothing to the response
- (the FileSignalsPanel convention).
-
- Every field is aggregate. No inducing commit is named here or anywhere else:
- file-level SZZ ran at 74.5% precision against the frozen judgments, which is
- fine for counting and too thin to accuse a commit.
-
- The approximation caveat on ``top_symbols`` lives in ``get_risk``'s docstring
- rather than in each row. It is the same sentence every time, and a constant
- string repeated once per target is exactly the per-file cost the lean-MCP
- work went to some trouble to remove.
- """
- profile = fix_annotation(meta, now=now)
- if profile is None:
- return None
- profile["window"] = "6 months"
-
- symbols = _top_fix_symbols(getattr(meta, "fix_symbol_counts_json", None))
- if symbols:
- profile["top_symbols"] = symbols
- return profile
-
-
-def _top_fix_symbols(raw: str | None) -> dict[str, int]:
- """Top few ``symbol -> fix count`` pairs, with the redundant path stripped.
-
- Stored keys are ``path/to/file.py::Name`` and the caller already knows the
- path, so the prefix is pure token cost in an MCP response. The stored map is
- written in descending-count order, so "top few" is a slice.
- """
- if not raw:
- return {}
- try:
- counts = json.loads(raw)
- except (TypeError, ValueError):
- return {}
- if not isinstance(counts, dict):
- return {}
- return {str(k).rsplit("::", 1)[-1]: int(v) for k, v in list(counts.items())[:_TOP_FIX_SYMBOLS]}
-
-
-def _load_commit_categories(meta: Any) -> dict:
- """Parse the persisted commit-category counts, tolerating malformed JSON."""
- categories: dict = {}
- cat_json = getattr(meta, "commit_categories_json", None)
- if cat_json:
- with contextlib.suppress(json.JSONDecodeError, TypeError):
- categories = json.loads(cat_json)
- return categories
-
-
async def _unresolved_reason(
target: str, lookup_path: str, repo_root: str | None
) -> dict[str, Any]:
@@ -452,45 +254,194 @@ async def _unresolved_reason(
return {"unresolved_reason": "no_such_path", **hint}
-def _history_tier_card(target: str, meta: Any, security_signals: list[dict]) -> dict:
- """The card for a file indexed at the history tier (``meta.history_only``).
+def _bounded_dependents(population: list[dict]) -> list[dict]:
+ """The first rows of *population*, keeping one transitive row when any exists.
- A non-code file keeps commit counts, windows and authorship, but no churn
- percentile, hotspot flag, co-change partners or fix rollup, so the scored
- card would print zeros nothing measured. This one carries only what was.
+ Without it a large direct fan-in would hide every transitive row while the
+ totals say transitive reach exists.
"""
- commits = meta.commit_count_total or 0
- last = meta.last_commit_at.isoformat() if meta.last_commit_at else None
- owner = meta.primary_owner_name or "unknown"
- pct = meta.primary_owner_commit_pct or 0.0
+ dependents = population[:_RELATIONSHIP_LIMIT]
+ first_transitive = next((row for row in population if not row["direct"]), None)
+ if (
+ first_transitive is not None
+ and dependents
+ and all(row["direct"] for row in dependents)
+ and len(population) > len(dependents)
+ ):
+ dependents[-1] = first_transitive
+ return dependents
+
+
+def _relationship_analysis() -> dict[str, Any]:
+ """Fresh ``relationship_analysis`` block; workspace enrichment fills the rest."""
return {
- "target": target,
- "signal_tier": "history",
- "signal_tier_reason": (
- "not a parsed code file: only commit history is indexed, so hotspot, "
- "co-change and risk classification do not apply"
- ),
- "commit_count_total": commits,
- "commit_count_90d": meta.commit_count_90d or 0,
- "last_commit_at": last,
- "trend": _compute_trend(meta),
- "primary_owner": owner,
- "owner_pct": pct,
- "contributor_count": meta.contributor_count or 0,
- "security_signals": security_signals,
- # Workspace enrichment adds its rows here; co-change covers code files only.
- "relationship_analysis": {
- "co_change": {
- "status": "unavailable",
- "scope": "git_history",
- "reason": "history-tier file",
- }
+ "dependencies": {
+ "status": "available",
+ "scope": "repository_graph",
+ "evidence_kind": "structural",
+ "max_depth": 2,
+ "runtime_breakage_claim": False,
},
- "risk_summary": (
- f"{target}: history only, {commits} commits, last {last[:10] if last else 'unknown'}, "
- f"{_owner_clause(owner, pct, None)}"
- ),
+ "consumers": {
+ "status": "unavailable",
+ "scope": "workspace_contract_links",
+ "reason": "workspace contract analysis is unavailable",
+ },
+ "cross_repo": {
+ "status": "unavailable",
+ "scope": "workspace_file_relationships",
+ "reason": "workspace relationship analysis is unavailable",
+ },
+ }
+
+
+def _dependency_card(
+ target: str,
+ lookup_path: str,
+ reverse_deps: dict[str, dict[str, set[str]]],
+ node_meta: dict[str, Any],
+ exclude_spec: Any,
+ collector: OmissionCollector | None,
+) -> tuple[dict[str, Any], int]:
+ """The card's structural-dependents fields and its direct dependents count."""
+ population = _dependency_population(lookup_path, reverse_deps, node_meta, exclude_spec)
+ dependents = _bounded_dependents(population)
+ ranked = sorted(population, key=lambda row: (-row["pagerank"], row["file_path"]))
+ impact_surface = ranked[:3]
+ direct_total = sum(row["direct"] for row in population)
+ # ``dependents_count`` is the compatibility field: direct graph dependents
+ # over the same post-exclusion population as the typed rows.
+ card: dict[str, Any] = {
+ "target": target,
+ "dependents_count": direct_total,
+ "dependents": dependents,
+ "dependents_total": len(population),
+ "dependents_emitted": len(dependents),
+ "dependents_truncated": len(dependents) < len(population),
+ "direct_dependents_total": direct_total,
+ "transitive_dependents_total": len(population) - direct_total,
+ "impact_surface": impact_surface,
+ "impact_surface_total": len(population),
+ "impact_surface_emitted": len(impact_surface),
+ "impact_surface_truncated": len(impact_surface) < len(population),
+ "consumers": [],
+ "consumers_total": 0,
+ "consumers_emitted": 0,
+ "consumers_truncated": False,
+ "cross_repo_links": [],
+ "cross_repo_links_total": 0,
+ "cross_repo_links_emitted": 0,
+ "cross_repo_links_truncated": False,
+ "relationship_analysis": _relationship_analysis(),
+ }
+ cap_collection(
+ card,
+ "dependents",
+ population,
+ _RELATIONSHIP_LIMIT,
+ collector,
+ emitted=dependents,
+ label=f"{target} :: dependents beyond cap={_RELATIONSHIP_LIMIT}",
+ preserve_counts=True,
+ )
+ cap_collection(
+ card,
+ "impact_surface",
+ ranked,
+ 3,
+ collector,
+ emitted=impact_surface,
+ label=f"{target} :: impact_surface beyond cap=3",
+ preserve_counts=True,
+ )
+ return card, direct_total
+
+
+async def _load_git_metadata(
+ session: AsyncSession, repo_id: str, lookup_path: str
+) -> GitMetadata | None:
+ """The target's ``GitMetadata`` row, keyed on the normalized POSIX path."""
+ res = await session.execute(
+ select(GitMetadata).where(
+ GitMetadata.repository_id == repo_id,
+ GitMetadata.file_path == lookup_path,
+ )
+ )
+ return res.scalar_one_or_none()
+
+
+async def _no_metadata_card(
+ card: dict[str, Any],
+ session: AsyncSession,
+ repo_id: str,
+ target: str,
+ lookup_path: str,
+ dep_count: int,
+) -> dict[str, Any]:
+ """Finish the card of a graph node with no git row (a new file)."""
+ card.update(
+ {
+ "hotspot_score": 0.0,
+ "is_hotspot": False,
+ "co_change_partners": [],
+ "co_change_partners_total": 0,
+ "co_change_partners_emitted": 0,
+ "co_change_partners_truncated": False,
+ }
+ )
+ card["relationship_analysis"]["co_change"] = {
+ "status": "unavailable",
+ "scope": "git_history",
+ "reason": "no git metadata is available for the target",
+ }
+ card.update(
+ {
+ "primary_owner": None,
+ "owner_pct": None,
+ "trend": "unknown",
+ "risk_type": "high-coupling" if dep_count >= 5 else "unknown",
+ }
+ )
+ card["test_gap"] = await _check_test_gap(session, repo_id, lookup_path)
+ card["security_signals"] = await _get_security_signals(session, repo_id, lookup_path)
+ card["risk_summary"] = f"{target} — no git metadata available"
+ return card
+
+
+def _apply_co_changes(
+ card: dict[str, Any],
+ meta: Any,
+ target: str,
+ structural_related: Any,
+ exclude_spec: Any,
+ collector: OmissionCollector | None,
+) -> int:
+ """Add the hotspot flags and co-change partners; return the partner total."""
+ population, total = _build_co_changes(meta, structural_related, exclude_spec)
+ co_changes = population[:_RELATIONSHIP_LIMIT]
+ card["hotspot_score"] = meta.churn_percentile or 0.0
+ # The stored flag already applies the absolute activity floors, which a
+ # client thresholding the score alone cannot reproduce.
+ card["is_hotspot"] = bool(getattr(meta, "is_hotspot", False))
+ card["co_change_partners"] = co_changes
+ card["co_change_partners_total"] = total
+ card["co_change_partners_emitted"] = len(co_changes)
+ card["co_change_partners_truncated"] = len(co_changes) < total
+ cap_collection(
+ card,
+ "co_change_partners",
+ population,
+ _RELATIONSHIP_LIMIT,
+ collector,
+ label=f"{target} :: co_change_partners beyond cap={_RELATIONSHIP_LIMIT}",
+ preserve_counts=True,
+ )
+ card["relationship_analysis"]["co_change"] = {
+ "status": "available",
+ "scope": "git_history",
+ "evidence_kind": "historical",
}
+ return total
async def _assess_one_target(
@@ -515,129 +466,27 @@ async def _assess_one_target(
- security_signals: list of {kind, severity, snippet} from security_findings.
"""
repo_id = repository.id
- result_data: dict[str, Any] = {"target": target}
-
repo_root = served_root(repository, repo_root)
+ # Callers pass paths in many forms (backslashes, ``./``, repo-absolute);
+ # stored rows are POSIX-relative. Every lookup keys on the normalized path,
+ # the response on what the caller asked for.
lookup_path = normalize_target_path(target, repo_root=repo_root)
- dependency_population = _dependency_population(
- lookup_path, reverse_deps, node_meta, exclude_spec
- )
- dependents = dependency_population[:_RELATIONSHIP_LIMIT]
- # If both distances exist, protect one transitive row from a large direct
- # fan-in. Otherwise the totals would say transitive reach exists while the
- # bounded typed field silently showed only direct rows.
- first_transitive = next((row for row in dependency_population if not row["direct"]), None)
- if (
- first_transitive is not None
- and dependents
- and all(row["direct"] for row in dependents)
- and len(dependency_population) > len(dependents)
- ):
- dependents[-1] = first_transitive
- impact_surface = sorted(
- dependency_population,
- key=lambda row: (-row["pagerank"], row["file_path"]),
- )[:3]
- direct_dependents_total = sum(row["direct"] for row in dependency_population)
- transitive_dependents_total = len(dependency_population) - direct_dependents_total
- # The compatibility count uses the same post-exclusion population as the
- # typed rows. ``all_edge_map`` remains in the signature for callers that
- # predate the typed adjacency, but no longer drives the public total.
- dep_count = direct_dependents_total
-
- result_data.update(
- {
- # ``dependents_count`` is the compatibility field: direct, directed
- # graph dependents only. It no longer absorbs co-change or contract
- # rows. The typed collection includes both direct and two-hop rows.
- "dependents_count": dep_count,
- "dependents": dependents,
- "dependents_total": len(dependency_population),
- "dependents_emitted": len(dependents),
- "dependents_truncated": len(dependents) < len(dependency_population),
- "direct_dependents_total": direct_dependents_total,
- "transitive_dependents_total": transitive_dependents_total,
- "impact_surface": impact_surface,
- "impact_surface_total": len(dependency_population),
- "impact_surface_emitted": len(impact_surface),
- "impact_surface_truncated": len(impact_surface) < len(dependency_population),
- "consumers": [],
- "consumers_total": 0,
- "consumers_emitted": 0,
- "consumers_truncated": False,
- "cross_repo_links": [],
- "cross_repo_links_total": 0,
- "cross_repo_links_emitted": 0,
- "cross_repo_links_truncated": False,
- "relationship_analysis": {
- "dependencies": {
- "status": "available",
- "scope": "repository_graph",
- "evidence_kind": "structural",
- "max_depth": 2,
- "runtime_breakage_claim": False,
- },
- "consumers": {
- "status": "unavailable",
- "scope": "workspace_contract_links",
- "reason": "workspace contract analysis is unavailable",
- },
- "cross_repo": {
- "status": "unavailable",
- "scope": "workspace_file_relationships",
- "reason": "workspace relationship analysis is unavailable",
- },
- },
- }
- )
- cap_collection(
- result_data,
- "dependents",
- dependency_population,
- _RELATIONSHIP_LIMIT,
+ # ``all_edge_map`` stays in the signature for older callers; the typed
+ # adjacency drives the counts.
+ result_data, dep_count = _dependency_card(
+ target,
+ lookup_path,
+ reverse_deps,
+ node_meta,
+ exclude_spec,
collector if include_graph else None,
- emitted=dependents,
- label=f"{target} :: dependents beyond cap={_RELATIONSHIP_LIMIT}",
- preserve_counts=True,
- )
- cap_collection(
- result_data,
- "impact_surface",
- sorted(dependency_population, key=lambda row: (-row["pagerank"], row["file_path"])),
- 3,
- collector if include_graph else None,
- emitted=impact_surface,
- label=f"{target} :: impact_surface beyond cap=3",
- preserve_counts=True,
)
+ meta = await _load_git_metadata(session, repo_id, lookup_path)
- # Callers reach get_risk with the file path in many forms — backslashes
- # (Windows), a leading ``./``, a trailing separator, or a repo-absolute
- # path — while git_metadata.file_path (and the graph node/edge ids) are
- # stored POSIX-relative. Exact-string equality against the raw target made
- # a row that exists look absent, and _assess_one_target then reported the
- # indistinguishable "no git metadata available" card (hotspot_score=0,
- # primary_owner=None, empty co_change_partners) — issue #1279. Normalize
- # once and key every file-path lookup on it, but keep the response keyed by
- # what the caller asked for.
- # Git metadata
- res = await session.execute(
- select(GitMetadata).where(
- GitMetadata.repository_id == repo_id,
- GitMetadata.file_path == lookup_path,
- )
- )
- meta = res.scalar_one_or_none()
-
- symbol_target = "::" in target
- if meta is None and lookup_path not in node_meta and not symbol_target:
- # Nothing below measured this target, so every numeric field would be
- # a structural zero no reader could tell from a measured one. Name the
- # miss and emit no counts.
- #
- # All three conditions are required. A graph node without a git row is
- # a real target (a new file); a ``path::Symbol`` id is an accepted
- # input shape here, so rejecting one is a different change.
+ if meta is None and lookup_path not in node_meta and "::" not in target:
+ # Nothing measured this target, so every count would be a structural
+ # zero. A graph node without a git row (a new file) and a
+ # ``path::Symbol`` id are real targets and fall through.
return {
"target": target,
"resolved": False,
@@ -652,136 +501,21 @@ async def _assess_one_target(
return _history_tier_card(target, meta, security)
if meta is None:
- result_data["hotspot_score"] = 0.0
- result_data["is_hotspot"] = False
- result_data["co_change_partners"] = []
- result_data["co_change_partners_total"] = 0
- result_data["co_change_partners_emitted"] = 0
- result_data["co_change_partners_truncated"] = False
- result_data["relationship_analysis"]["co_change"] = {
- "status": "unavailable",
- "scope": "git_history",
- "reason": "no git metadata is available for the target",
- }
- result_data["primary_owner"] = None
- result_data["owner_pct"] = None
- result_data["trend"] = "unknown"
- result_data["risk_type"] = "high-coupling" if dep_count >= 5 else "unknown"
- result_data["test_gap"] = await _check_test_gap(session, repo_id, lookup_path)
- result_data["security_signals"] = await _get_security_signals(session, repo_id, lookup_path)
- result_data["risk_summary"] = f"{target} — no git metadata available"
- return result_data
-
- hotspot_score = meta.churn_percentile or 0.0
-
- co_change_population, co_changes_total = _build_co_changes(
- meta, import_links.get(lookup_path, {}), exclude_spec
- )
- co_changes = co_change_population[:_RELATIONSHIP_LIMIT]
-
- owner = meta.primary_owner_name or "unknown"
- pct = meta.primary_owner_commit_pct or 0.0
- line_pct = getattr(meta, "primary_owner_line_pct", None)
-
- # --- Risk velocity (trend) ---
- trend = _compute_trend(meta)
-
- # --- Risk type classification ---
- risk_type = _classify_risk_type(meta, dep_count, team_size)
-
- # Phase 2: commit classification → change_pattern
- change_pattern = _derive_change_pattern(_load_commit_categories(meta))
-
- # Phase 2: recent owner & bus factor
- bus_factor = getattr(meta, "bus_factor", 0) or 0
-
- result_data["hotspot_score"] = hotspot_score
- # Emit the backend's hotspot classification, not a client re-derivation.
- # ``is_hotspot`` lives on the stored GitMetadata row and already applies
- # the absolute activity floors (issue #361); a client that thresholds the
- # score alone can reproduce the churn half but not the floors, so on a
- # quiet repo it would badge files the backend does not consider hotspots.
- result_data["is_hotspot"] = bool(getattr(meta, "is_hotspot", False))
- result_data["co_change_partners"] = co_changes
- result_data["co_change_partners_total"] = co_changes_total
- result_data["co_change_partners_emitted"] = len(co_changes)
- result_data["co_change_partners_truncated"] = len(co_changes) < co_changes_total
- cap_collection(
- result_data,
- "co_change_partners",
- co_change_population,
- _RELATIONSHIP_LIMIT,
- collector,
- label=f"{target} :: co_change_partners beyond cap={_RELATIONSHIP_LIMIT}",
- preserve_counts=True,
- )
- result_data["relationship_analysis"]["co_change"] = {
- "status": "available",
- "scope": "git_history",
- "evidence_kind": "historical",
- }
- result_data["primary_owner"] = owner
- result_data["owner_pct"] = pct
- result_data["owner_line_pct"] = line_pct
- result_data["recent_owner"] = getattr(meta, "recent_owner_name", None)
- result_data["recent_owner_pct"] = getattr(meta, "recent_owner_commit_pct", None)
- result_data["bus_factor"] = bus_factor
- result_data["contributor_count"] = getattr(meta, "contributor_count", 0) or 0
- result_data["trend"] = trend
- result_data["risk_type"] = risk_type
- result_data["change_pattern"] = change_pattern
- result_data["change_magnitude"] = {
- "lines_added_90d": getattr(meta, "lines_added_90d", 0) or 0,
- "lines_deleted_90d": getattr(meta, "lines_deleted_90d", 0) or 0,
- "avg_commit_size": round(getattr(meta, "avg_commit_size", 0.0) or 0.0, 1),
- }
- # Phase 3: rename tracking & merge commit proxy
- original_path = getattr(meta, "original_path", None)
- if original_path:
- result_data["original_path"] = original_path
- merge_commit_count = getattr(meta, "merge_commit_count_90d", 0) or 0
- if merge_commit_count > 0:
- result_data["merge_commit_count_90d"] = merge_commit_count
+ return await _no_metadata_card(
+ result_data, session, repo_id, target, lookup_path, dep_count
+ )
+ co_changes_total = _apply_co_changes(
+ result_data, meta, target, import_links.get(lookup_path, {}), exclude_spec, collector
+ )
+ result_data.update(history_fields(meta, dep_count, team_size))
defect_profile = _defect_profile(meta, now=as_of_ts)
if defect_profile is not None:
result_data["defect_profile"] = defect_profile
-
- # C. Test gaps + security signals
result_data["test_gap"] = await _check_test_gap(session, repo_id, lookup_path)
result_data["security_signals"] = await _get_security_signals(session, repo_id, lookup_path)
-
- capped = getattr(meta, "commit_count_capped", False)
- capped_note = " (history truncated — actual count may be higher)" if capped else ""
- result_data["commit_count_capped"] = capped
-
- bus_note = ""
- if bus_factor == 1 and (meta.commit_count_total or 0) > 20:
- bus_note = f", bus factor risk (sole maintainer: {owner})"
-
- # Lead with the bug-fix history when there is any. The summary used to open
- # on a churn percentile even where risk_type said "bug-prone", so the first
- # thing an agent read disagreed with the classification beside it. Counted
- # fixes are the better grounded defect signal, so they go first and churn
- # keeps its place as the next clause, for files that are churn hotspots.
- result_data["risk_summary"] = (
- f"{target} — {_fix_clause(defect_profile)}"
- f"{_churn_clause(hotspot_score, result_data['is_hotspot'], trend)}"
- f"{dep_count} direct dependents, {risk_type}, {change_pattern}, "
- f"{co_changes_total} co-change partners, {_owner_clause(owner, pct, line_pct)}"
- f"{bus_note}{capped_note}"
+ result_data["commit_count_capped"] = getattr(meta, "commit_count_capped", False)
+ result_data["risk_summary"] = risk_summary(
+ target, meta, result_data, defect_profile, dep_count, co_changes_total
)
-
return result_data
-
-
-def _owner_clause(owner: str, commit_pct: float, line_pct: float | None) -> str:
- """Name the owner with the share each figure actually measures.
-
- With blame, the owner is the top author of current lines, which need not
- be the top committer, so both shares are stated and neither is called the
- other.
- """
- if line_pct is None:
- return f"primary owner {owner} ({commit_pct:.0%} of commits)"
- return f"{owner} wrote {line_pct:.0%} of current lines ({commit_pct:.0%} of commits)"
diff --git a/packages/server/src/repowise/server/mcp_server/tool_risk/history.py b/packages/server/src/repowise/server/mcp_server/tool_risk/history.py
new file mode 100644
index 000000000..7a6e33f20
--- /dev/null
+++ b/packages/server/src/repowise/server/mcp_server/tool_risk/history.py
@@ -0,0 +1,317 @@
+"""Git-history fields and summary clauses of a get_risk target card.
+
+Pure functions over a loaded ``GitMetadata`` row: no queries.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import math
+from datetime import UTC, datetime
+from typing import Any
+
+#: A file carrying this many counted bug fixes reads as bug-prone. Same trigger
+#: the PR bot uses for prior defects, so the two surfaces agree on "a lot".
+_BUG_PRONE_FIXES = 3
+
+#: How many attributed symbols the defect profile names. Enough to say "mostly
+#: these", short enough to keep the block inside the per-file token budget.
+_TOP_FIX_SYMBOLS = 3
+
+
+def _derive_change_pattern(categories: dict[str, int]) -> str:
+ """Derive a human-readable change pattern from commit category counts."""
+ if not categories:
+ return "uncategorized"
+ total = sum(categories.values())
+ if total == 0:
+ return "uncategorized"
+ dominant = max(categories, key=lambda k: categories[k])
+ ratio = categories[dominant] / total
+ if ratio >= 0.5:
+ labels = {
+ "feature": "feature-active",
+ "refactor": "primarily refactored",
+ "fix": "fix-heavy",
+ "dependency": "dependency-churn",
+ }
+ return labels.get(dominant, dominant)
+ return "mixed-activity"
+
+
+def _compute_trend(meta: Any) -> str:
+ """Compute risk velocity from 30d vs 90d commit rates."""
+ c30 = meta.commit_count_30d or 0
+ c90 = meta.commit_count_90d or 0
+ # Baseline: commits in the 60-day window before the last 30 days
+ baseline_commits = c90 - c30
+ recent_rate = c30 / 30.0
+ baseline_rate = baseline_commits / 60.0
+
+ if c90 == 0:
+ return "stable"
+ if baseline_rate == 0:
+ return "increasing" if c30 > 0 else "stable"
+ ratio = recent_rate / baseline_rate
+ if ratio > 1.5:
+ return "increasing"
+ elif ratio < 0.5:
+ return "decreasing"
+ return "stable"
+
+
+def _classify_risk_type(meta: Any, dep_count: int, team_size: int | None = None) -> str:
+ """Classify risk as churn-heavy, bug-prone, high-coupling, or bus-factor-risk.
+
+ *team_size* is the repo's active-contributor count (90d). On a small team
+ a single-author file is the expected operating model, so
+ ``bus-factor-risk`` is reserved for hotspot files there; ``None`` means
+ unknown. ``bug-prone`` reads the counted, windowed fix history
+ (``prior_defect_count``) and its decayed form (``bug_magnet``); an index
+ without that rollup reports 0/None and falls through to the next rule.
+ """
+ from repowise.core.analysis.health.biomarkers.base import SMALL_TEAM_MAX_CONTRIBUTORS
+
+ churn_score = meta.churn_percentile or 0.0
+ bus_factor = getattr(meta, "bus_factor", 0) or 0
+ total_commits = meta.commit_count_total or 0
+
+ small_team = team_size is not None and team_size <= SMALL_TEAM_MAX_CONTRIBUTORS
+
+ # Bug-prone takes priority: real counted fixes, decayed or plain.
+ prior_defects = getattr(meta, "prior_defect_count", 0) or 0
+ if getattr(meta, "bug_magnet", False) or prior_defects >= _BUG_PRONE_FIXES:
+ return "bug-prone"
+ if churn_score >= 0.7:
+ return "churn-heavy"
+ if (
+ bus_factor == 1
+ and total_commits > 20
+ and (not small_team or bool(getattr(meta, "is_hotspot", False)))
+ ):
+ return "bus-factor-risk"
+ if dep_count >= 5:
+ return "high-coupling"
+ return "stable"
+
+
+def fix_annotation(meta: Any, now: datetime | None = None) -> dict | None:
+ """The shared count/age/magnet fix block used by context and risk.
+
+ Centralized so the two tools agree on the wire format and the age contract
+ is enforced once: the ``bug_magnet`` flag rides on the age and is never
+ emitted alone. ``bug_magnet`` is a claim about RECENT fix pressure, so with
+ no timestamp to anchor it the same word would describe a file fixed four
+ times last month and one fixed four times two years ago.
+
+ Read off the ``GitMetadata`` row the caller already loaded: no query.
+ """
+ count = getattr(meta, "prior_defect_count", 0) or 0
+ if count <= 0:
+ return None
+
+ out: dict[str, Any] = {"fix_count": count}
+ last_fix_at = getattr(meta, "last_fix_at", None)
+ if isinstance(last_fix_at, datetime):
+ # Rows are stored naive-UTC; compare on the same footing.
+ ref = (
+ datetime.now(UTC)
+ if now is None
+ else (now if now.tzinfo else now.replace(tzinfo=UTC))
+ )
+ moment = last_fix_at if last_fix_at.tzinfo else last_fix_at.replace(tzinfo=UTC)
+ out["last_fix_days_ago"] = max(0, (ref - moment).days)
+ if getattr(meta, "bug_magnet", False):
+ out["bug_magnet"] = True
+ return out
+
+
+def _fix_clause(profile: dict | None) -> str:
+ """Lead clause for ``risk_summary``, or empty when there is no fix history.
+
+ Trailing separator included so the caller concatenates without a dangling
+ comma on files that have never been fixed. Never renders a count without an
+ age: an unanchored count reads as a claim about the distant past.
+ """
+ if not profile or "last_fix_days_ago" not in profile:
+ return ""
+ n = profile["fix_count"]
+ magnet = " (bug magnet)" if profile.get("bug_magnet") else ""
+ return (
+ f"{n} bug fix{'es' if n != 1 else ''} in 6mo, "
+ f"last {profile['last_fix_days_ago']}d before the indexed commit{magnet}, "
+ )
+
+
+def _churn_clause(churn_percentile: float, is_hotspot: bool, trend: str) -> str:
+ """Churn clause for ``risk_summary``, or empty when the file is not a hotspot.
+
+ ``churn_percentile`` is a rank (0 to 1), not a risk, so the clause states it
+ as "top N%" and only for files the stored ``is_hotspot`` flag marks.
+ Trailing separator included, as in ``_fix_clause``.
+ """
+ if not is_hotspot:
+ return ""
+ # Round before the ceiling: 1 - 0.86 is 0.14000000000000001 in floats, and
+ # that would otherwise print as top 15%.
+ top_pct = max(1, math.ceil(round((1.0 - churn_percentile) * 100, 6)))
+ return f"churn hotspot, top {top_pct}% ({trend}), "
+
+
+def _defect_profile(meta: Any, now: datetime | None = None) -> dict | None:
+ """What this file's counted bug fixes say about it, or ``None`` for silence.
+
+ Built from the fix-event rollup on the loaded ``GitMetadata`` row. Silent
+ when the file has no counted fixes. Every field is aggregate: no inducing
+ commit is named. The approximation caveat on ``top_symbols`` lives once in
+ ``get_risk``'s docstring, not per row.
+ """
+ profile = fix_annotation(meta, now=now)
+ if profile is None:
+ return None
+ profile["window"] = "6 months"
+
+ symbols = _top_fix_symbols(getattr(meta, "fix_symbol_counts_json", None))
+ if symbols:
+ profile["top_symbols"] = symbols
+ return profile
+
+
+def _top_fix_symbols(raw: str | None) -> dict[str, int]:
+ """Top few ``symbol -> fix count`` pairs, with the redundant path stripped.
+
+ Stored keys are ``path/to/file.py::Name`` and the caller already knows the
+ path, so the prefix is pure token cost in an MCP response. The stored map is
+ written in descending-count order, so "top few" is a slice.
+ """
+ if not raw:
+ return {}
+ try:
+ counts = json.loads(raw)
+ except (TypeError, ValueError):
+ return {}
+ if not isinstance(counts, dict):
+ return {}
+ return {str(k).rsplit("::", 1)[-1]: int(v) for k, v in list(counts.items())[:_TOP_FIX_SYMBOLS]}
+
+
+def _load_commit_categories(meta: Any) -> dict:
+ """Parse the persisted commit-category counts, tolerating malformed JSON."""
+ categories: dict = {}
+ cat_json = getattr(meta, "commit_categories_json", None)
+ if cat_json:
+ with contextlib.suppress(json.JSONDecodeError, TypeError):
+ categories = json.loads(cat_json)
+ return categories
+
+
+def _owner_clause(owner: str, commit_pct: float, line_pct: float | None) -> str:
+ """Name the owner with the share each figure actually measures.
+
+ With blame, the owner is the top author of current lines, which need not
+ be the top committer, so both shares are stated and neither is called the
+ other.
+ """
+ if line_pct is None:
+ return f"primary owner {owner} ({commit_pct:.0%} of commits)"
+ return f"{owner} wrote {line_pct:.0%} of current lines ({commit_pct:.0%} of commits)"
+
+
+def _history_tier_card(target: str, meta: Any, security_signals: list[dict]) -> dict:
+ """The card for a file indexed at the history tier (``meta.history_only``).
+
+ A non-code file keeps commit counts, windows and authorship, but no churn
+ percentile, hotspot flag, co-change partners or fix rollup, so the scored
+ card would print zeros nothing measured. This one carries only what was.
+ """
+ commits = meta.commit_count_total or 0
+ last = meta.last_commit_at.isoformat() if meta.last_commit_at else None
+ owner = meta.primary_owner_name or "unknown"
+ pct = meta.primary_owner_commit_pct or 0.0
+ return {
+ "target": target,
+ "signal_tier": "history",
+ "signal_tier_reason": (
+ "not a parsed code file: only commit history is indexed, so hotspot, "
+ "co-change and risk classification do not apply"
+ ),
+ "commit_count_total": commits,
+ "commit_count_90d": meta.commit_count_90d or 0,
+ "last_commit_at": last,
+ "trend": _compute_trend(meta),
+ "primary_owner": owner,
+ "owner_pct": pct,
+ "contributor_count": meta.contributor_count or 0,
+ "security_signals": security_signals,
+ # Workspace enrichment adds its rows here; co-change covers code files only.
+ "relationship_analysis": {
+ "co_change": {
+ "status": "unavailable",
+ "scope": "git_history",
+ "reason": "history-tier file",
+ }
+ },
+ "risk_summary": (
+ f"{target}: history only, {commits} commits, last {last[:10] if last else 'unknown'}, "
+ f"{_owner_clause(owner, pct, None)}"
+ ),
+ }
+
+
+def history_fields(meta: Any, dep_count: int, team_size: int | None) -> dict[str, Any]:
+ """Ownership, trend, classification and change-shape fields, in wire order."""
+ fields: dict[str, Any] = {
+ "primary_owner": meta.primary_owner_name or "unknown",
+ "owner_pct": meta.primary_owner_commit_pct or 0.0,
+ "owner_line_pct": getattr(meta, "primary_owner_line_pct", None),
+ "recent_owner": getattr(meta, "recent_owner_name", None),
+ "recent_owner_pct": getattr(meta, "recent_owner_commit_pct", None),
+ "bus_factor": getattr(meta, "bus_factor", 0) or 0,
+ "contributor_count": getattr(meta, "contributor_count", 0) or 0,
+ "trend": _compute_trend(meta),
+ "risk_type": _classify_risk_type(meta, dep_count, team_size),
+ "change_pattern": _derive_change_pattern(_load_commit_categories(meta)),
+ "change_magnitude": {
+ "lines_added_90d": getattr(meta, "lines_added_90d", 0) or 0,
+ "lines_deleted_90d": getattr(meta, "lines_deleted_90d", 0) or 0,
+ "avg_commit_size": round(getattr(meta, "avg_commit_size", 0.0) or 0.0, 1),
+ },
+ }
+ original_path = getattr(meta, "original_path", None)
+ if original_path:
+ fields["original_path"] = original_path
+ merge_commit_count = getattr(meta, "merge_commit_count_90d", 0) or 0
+ if merge_commit_count > 0:
+ fields["merge_commit_count_90d"] = merge_commit_count
+ return fields
+
+
+def risk_summary(
+ target: str,
+ meta: Any,
+ card: dict[str, Any],
+ defect_profile: dict | None,
+ dep_count: int,
+ co_changes_total: int,
+) -> str:
+ """One-line ``risk_summary`` for a scored card.
+
+ Leads with counted bug fixes, the better grounded defect signal, so the
+ first clause agrees with ``risk_type``; churn follows for hotspot files.
+ """
+ capped_note = (
+ " (history truncated — actual count may be higher)" if card["commit_count_capped"] else ""
+ )
+ owner = card["primary_owner"]
+ bus_note = ""
+ if card["bus_factor"] == 1 and (meta.commit_count_total or 0) > 20:
+ bus_note = f", bus factor risk (sole maintainer: {owner})"
+ return (
+ f"{target} — {_fix_clause(defect_profile)}"
+ f"{_churn_clause(card['hotspot_score'], card['is_hotspot'], card['trend'])}"
+ f"{dep_count} direct dependents, {card['risk_type']}, {card['change_pattern']}, "
+ f"{co_changes_total} co-change partners, "
+ f"{_owner_clause(owner, card['owner_pct'], card['owner_line_pct'])}"
+ f"{bus_note}{capped_note}"
+ )