Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.pyindex 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 annotationsimport asyncio-import contextlib-import json-import math-from datetime import UTC, datetime+from datetime import datetimefrom pathlib import Pathfrom 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 totalasync 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 signalsresult_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.pynew file mode 100644index 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}"+ )