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.

Enhance get_dead_code, get_risk, and get_why MCP tools with actionable intelligence

RaghavChamadiyaa0e72b2bb066
diff --git a/packages/server/src/wikicode/server/chat_tools.py b/packages/server/src/wikicode/server/chat_tools.py
index 3fe94ada4..355f1d68a 100644
--- a/packages/server/src/wikicode/server/chat_tools.py
+++ b/packages/server/src/wikicode/server/chat_tools.py
@@ -66,7 +66,7 @@ _TOOL_SCHEMAS: list[dict[str, Any]] = [
},
{
"name": "get_risk",
- "description": "Assess modification risk for files: hotspot score, dependents, co-change partners, ownership.",
+ "description": "Assess modification risk with trend analysis: hotspot score + velocity (increasing/stable/decreasing), risk type (churn-heavy/bug-prone/high-coupling), impact surface (top 3 modules that would break), dependents, co-change partners, ownership.",
"parameters": {
"type": "object",
"properties": {
@@ -83,11 +83,16 @@ _TOOL_SCHEMAS: list[dict[str, Any]] = [
},
{
"name": "get_why",
- "description": "Query architectural decisions: health dashboard (no query), path-based lookup, or natural language search.",
+ "description": "Intent archaeology: understand why code was built a certain way. Path lookup returns origin story (who, when, key commits linked to decisions) and alignment score. Natural language search scores across all decision fields. Use targets to anchor search to specific files.",
"parameters": {
"type": "object",
"properties": {
"query": {"type": "string", "description": "Natural language question, file/module path, or omit for health dashboard."},
+ "targets": {
+ "type": "array",
+ "items": {"type": "string"},
+ "description": "File paths to anchor the search. Decisions governing these files are prioritized.",
+ },
"repo": {"type": "string", "description": "Repository identifier."},
},
"required": [],
@@ -125,7 +130,7 @@ _TOOL_SCHEMAS: list[dict[str, Any]] = [
},
{
"name": "get_dead_code",
- "description": "List dead code findings: unreachable files, unused exports, zombie packages.",
+ "description": "Get a tiered refactor plan for dead code. Returns findings in high/medium/low confidence tiers with per-directory rollups, ownership hotspots, and impact estimates. Use group_by for rollup views, tier to focus on one band.",
"parameters": {
"type": "object",
"properties": {
@@ -133,7 +138,11 @@ _TOOL_SCHEMAS: list[dict[str, Any]] = [
"kind": {"type": "string", "description": "Filter: unreachable_file, unused_export, unused_internal, zombie_package."},
"min_confidence": {"type": "number", "description": "Minimum confidence threshold (default 0.5).", "default": 0.5},
"safe_only": {"type": "boolean", "description": "Only return safe-to-delete findings.", "default": False},
- "limit": {"type": "integer", "description": "Max findings (default 20).", "default": 20},
+ "limit": {"type": "integer", "description": "Max findings per tier (default 20).", "default": 20},
+ "tier": {"type": "string", "description": "Focus on one tier: high (>=0.8), medium (0.5-0.8), or low (<0.5)."},
+ "directory": {"type": "string", "description": "Filter to a directory prefix (e.g. src/legacy)."},
+ "owner": {"type": "string", "description": "Filter by primary owner name."},
+ "group_by": {"type": "string", "description": "Rollup view: 'directory' or 'owner'."},
},
"required": [],
},
diff --git a/packages/server/src/wikicode/server/mcp_server.py b/packages/server/src/wikicode/server/mcp_server.py
index fff963dec..de5c1a963 100644
--- a/packages/server/src/wikicode/server/mcp_server.py
+++ b/packages/server/src/wikicode/server/mcp_server.py
@@ -233,6 +233,200 @@ def _is_path(query: str) -> bool:
return ext in _CODE_EXTS
+def _build_origin_story(
+ file_path: str, git_meta: Any | None, governing_decisions: list[dict],
+) -> dict:
+ """Build the human context / origin story for a file from stored metadata."""
+ if git_meta is None:
+ return {
+ "available": False,
+ "summary": f"No git history available for {file_path}.",
+ }
+
+ authors = json.loads(git_meta.top_authors_json) if git_meta.top_authors_json else []
+ commits = json.loads(git_meta.significant_commits_json) if git_meta.significant_commits_json else []
+
+ # Find the earliest significant commit as the "creation" context
+ earliest_commit = None
+ if commits:
+ sorted_commits = sorted(commits, key=lambda c: c.get("date", ""))
+ earliest_commit = sorted_commits[0]
+
+ # Link commits to decisions via keyword overlap
+ linked_decisions = []
+ for d in governing_decisions:
+ # Build a keyword set from the decision
+ decision_text = f"{d.get('title', '')} {d.get('decision', '')} {d.get('rationale', '')}".lower()
+ decision_words = set(decision_text.split())
+ decision_words -= {"the", "a", "an", "is", "for", "to", "of", "in", "and", "or", "with"}
+
+ # Find commits whose messages overlap with this decision
+ related_commits = []
+ for c in commits:
+ msg = c.get("message", "").lower()
+ msg_words = set(msg.split())
+ msg_words -= {"the", "a", "an", "is", "for", "to", "of", "in", "and", "or", "with"}
+ overlap = decision_words & msg_words
+ # Require at least 1 meaningful word match
+ if len(overlap) >= 1:
+ related_commits.append({
+ "sha": c.get("sha", ""),
+ "message": c.get("message", ""),
+ "author": c.get("author", ""),
+ "date": c.get("date", ""),
+ "matching_keywords": sorted(overlap)[:5],
+ })
+
+ linked_decisions.append({
+ "title": d.get("title", ""),
+ "status": d.get("status", ""),
+ "source": d.get("source", ""),
+ "rationale": d.get("rationale", ""),
+ "evidence_commits": related_commits,
+ })
+
+ # Build narrative summary
+ primary = git_meta.primary_owner_name or "unknown"
+ total = git_meta.commit_count_total or 0
+ first_date = git_meta.first_commit_at.strftime("%Y-%m-%d") if git_meta.first_commit_at else "unknown"
+ last_date = git_meta.last_commit_at.strftime("%Y-%m-%d") if git_meta.last_commit_at else "unknown"
+ age = git_meta.age_days or 0
+
+ parts = [f"Created ~{first_date}, last modified {last_date} ({age} days old)."]
+ parts.append(f"Primary author: {primary} ({total} total commits).")
+
+ if earliest_commit:
+ parts.append(
+ f"Earliest key commit: \"{earliest_commit.get('message', '')}\" "
+ f"by {earliest_commit.get('author', 'unknown')} on {earliest_commit.get('date', 'unknown')}."
+ )
+
+ if linked_decisions:
+ decision_titles = [d["title"] for d in linked_decisions[:3]]
+ parts.append(f"Governed by: {', '.join(decision_titles)}.")
+ # Highlight any commit-decision links
+ for ld in linked_decisions:
+ if ld["evidence_commits"]:
+ ec = ld["evidence_commits"][0]
+ parts.append(
+ f"Commit \"{ec['message']}\" by {ec['author']} "
+ f"is evidence for \"{ld['title']}\"."
+ )
+
+ contributor_count = len(authors)
+ if contributor_count > 1:
+ names = [a.get("name", "") for a in authors[:3]]
+ parts.append(f"Contributors: {', '.join(names)}.")
+
+ return {
+ "available": True,
+ "primary_author": primary,
+ "author_commit_pct": git_meta.primary_owner_commit_pct,
+ "contributors": authors[:5],
+ "total_commits": total,
+ "first_commit": first_date,
+ "last_commit": last_date,
+ "age_days": age,
+ "key_commits": commits[:5],
+ "linked_decisions": linked_decisions,
+ "summary": " ".join(parts),
+ }
+
+
+def _compute_alignment(
+ file_path: str, governing: list[dict], all_decisions: list,
+) -> dict:
+ """Compute how well a file aligns with established architectural decisions."""
+ if not governing:
+ return {
+ "score": "none",
+ "explanation": (
+ f"No architectural decisions govern {file_path}. "
+ "This file is ungoverned — it may be an outlier or simply undocumented."
+ ),
+ "governing_count": 0,
+ "active_count": 0,
+ "deprecated_count": 0,
+ "stale_count": 0,
+ "sibling_coverage": None,
+ }
+
+ # Count decision statuses
+ active = [d for d in governing if d["status"] == "active"]
+ deprecated = [d for d in governing if d["status"] in ("deprecated", "superseded")]
+ stale = [d for d in governing if d.get("staleness_score", 0) > 0.5]
+ proposed = [d for d in governing if d["status"] == "proposed"]
+
+ # Check sibling files — do neighbors share the same decisions?
+ dir_path = "/".join(file_path.split("/")[:-1])
+ sibling_decision_ids = set()
+ file_decision_titles = {d["title"] for d in governing}
+
+ for d in all_decisions:
+ affected = json.loads(d.affected_files_json)
+ affected_modules = json.loads(d.affected_modules_json)
+ for af in affected:
+ af_dir = "/".join(af.split("/")[:-1])
+ if af_dir == dir_path and af != file_path:
+ sibling_decision_ids.add(d.title)
+
+ # Overlap: how many of sibling decisions also cover this file
+ if sibling_decision_ids:
+ shared = file_decision_titles & sibling_decision_ids
+ sibling_coverage = len(shared) / len(sibling_decision_ids)
+ else:
+ sibling_coverage = None # No siblings to compare
+
+ # Compute alignment score
+ if deprecated and not active and not proposed:
+ score = "low"
+ explanation = (
+ f"All governing decisions are deprecated/superseded. "
+ f"This file likely contains technical debt that should be migrated."
+ )
+ elif stale and len(stale) >= len(governing) / 2:
+ score = "low"
+ explanation = (
+ f"{len(stale)} of {len(governing)} governing decision(s) are stale. "
+ f"The architectural rationale may no longer apply."
+ )
+ elif active:
+ if sibling_coverage is not None and sibling_coverage >= 0.5:
+ score = "high"
+ explanation = (
+ f"Follows {len(active)} active decision(s) shared with sibling files. "
+ f"This file aligns with established patterns in {dir_path}/."
+ )
+ elif sibling_coverage is not None and sibling_coverage < 0.5:
+ score = "medium"
+ explanation = (
+ f"Has {len(active)} active decision(s) but limited overlap with "
+ f"sibling files in {dir_path}/. May use a different pattern than neighbors."
+ )
+ else:
+ score = "high"
+ explanation = f"Governed by {len(active)} active decision(s)."
+ elif proposed:
+ score = "medium"
+ explanation = (
+ f"Governed by {len(proposed)} proposed (unreviewed) decision(s). "
+ f"Patterns are established but not yet formally approved."
+ )
+ else:
+ score = "medium"
+ explanation = f"Governed by {len(governing)} decision(s) with mixed status."
+
+ return {
+ "score": score,
+ "explanation": explanation,
+ "governing_count": len(governing),
+ "active_count": len(active),
+ "deprecated_count": len(deprecated),
+ "stale_count": len(stale),
+ "sibling_coverage": round(sibling_coverage, 2) if sibling_coverage is not None else None,
+ }
+
+
# ---------------------------------------------------------------------------
# Tool 1: get_overview (unchanged)
# ---------------------------------------------------------------------------
@@ -639,11 +833,15 @@ async def _assess_one_target(
target: str,
all_edge_map: dict[str, int],
import_links: dict[str, set[str]],
+ reverse_deps: dict[str, set[str]],
+ node_meta: dict[str, Any],
) -> dict:
"""Assess risk for a single target file."""
repo_id = repository.id
result_data: dict[str, Any] = {"target": target}
+ dep_count = all_edge_map.get(target, 0)
+
# Git metadata
res = await session.execute(
select(GitMetadata).where(
@@ -655,15 +853,19 @@ async def _assess_one_target(
if meta is None:
result_data["hotspot_score"] = 0.0
- result_data["dependents_count"] = all_edge_map.get(target, 0)
+ result_data["dependents_count"] = dep_count
result_data["co_change_partners"] = []
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["impact_surface"] = _compute_impact_surface(
+ target, reverse_deps, node_meta,
+ )
result_data["risk_summary"] = f"{target} — no git metadata available"
return result_data
hotspot_score = meta.churn_percentile or 0.0
- dep_count = all_edge_map.get(target, 0)
# Co-change partners
partners = json.loads(meta.co_change_partners_json)
@@ -680,19 +882,114 @@ async def _assess_one_target(
owner = meta.primary_owner_name or "unknown"
pct = meta.primary_owner_commit_pct or 0.0
+ # --- Risk velocity (trend) ---
+ trend = _compute_trend(meta)
+
+ # --- Risk type classification ---
+ risk_type = _classify_risk_type(meta, dep_count)
+
+ # --- Impact surface ---
+ impact_surface = _compute_impact_surface(target, reverse_deps, node_meta)
+
result_data["hotspot_score"] = hotspot_score
result_data["dependents_count"] = dep_count
result_data["co_change_partners"] = co_changes
result_data["primary_owner"] = owner
result_data["owner_pct"] = pct
+ result_data["trend"] = trend
+ result_data["risk_type"] = risk_type
+ result_data["impact_surface"] = impact_surface
result_data["risk_summary"] = (
- f"{target} — hotspot score {hotspot_score:.0%}, {dep_count} dependents, "
+ f"{target} — hotspot score {hotspot_score:.0%} ({trend}), "
+ f"{dep_count} dependents, {risk_type}, "
f"{len(co_changes)} co-change partners, owned {pct:.0%} by {owner}"
)
return result_data
+_FIX_PATTERN = re.compile(
+ r"\b(fix|bug|patch|hotfix|revert|regression|broken|crash|error)\b",
+ re.IGNORECASE,
+)
+
+
+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) -> str:
+ """Classify risk as churn-heavy, bug-prone, or high-coupling."""
+ # Count bug-fix commits from significant_commits messages
+ commits = json.loads(meta.significant_commits_json) if meta.significant_commits_json else []
+ fix_count = sum(
+ 1 for c in commits
+ if _FIX_PATTERN.search(c.get("message", ""))
+ )
+
+ churn_score = meta.churn_percentile or 0.0
+
+ # Bug-prone takes priority if fix ratio is high
+ if commits and fix_count / len(commits) >= 0.4:
+ return "bug-prone"
+ if churn_score >= 0.7:
+ return "churn-heavy"
+ if dep_count >= 5:
+ return "high-coupling"
+ return "stable"
+
+
+def _compute_impact_surface(
+ target: str,
+ reverse_deps: dict[str, set[str]],
+ node_meta: dict[str, Any],
+) -> list[dict]:
+ """Find the top 3 most critical modules that depend on this file."""
+ # BFS up to 2 hops through reverse dependencies
+ visited: set[str] = set()
+ frontier = {target}
+ for _ in range(2):
+ next_frontier: set[str] = set()
+ for node in frontier:
+ for dep in reverse_deps.get(node, set()):
+ if dep != target and dep not in visited:
+ visited.add(dep)
+ next_frontier.add(dep)
+ frontier = next_frontier
+
+ if not visited:
+ return []
+
+ # Rank by pagerank (most critical first)
+ ranked = []
+ for dep in visited:
+ meta = node_meta.get(dep)
+ ranked.append({
+ "file_path": dep,
+ "pagerank": meta.pagerank if meta else 0.0,
+ "is_entry_point": meta.is_entry_point if meta else False,
+ })
+ ranked.sort(key=lambda x: -x["pagerank"])
+ return ranked[:3]
+
+
@mcp.tool()
async def get_risk(
targets: list[str],
@@ -700,9 +997,13 @@ async def get_risk(
) -> dict:
"""Assess modification risk for one or more files before making changes.
- Pass ALL files you plan to modify in a single call. Returns hotspot
- score, dependents, co-change partners, and a plain-English risk summary
- for each target, plus the top 5 global hotspots for ambient awareness.
+ Pass ALL files you plan to modify in a single call. Returns per-file:
+ - hotspot_score and trend ("increasing"/"stable"/"decreasing")
+ - risk_type ("churn-heavy"/"bug-prone"/"high-coupling"/"stable")
+ - impact_surface: top 3 critical modules that would break
+ - dependents, co-change partners, ownership
+
+ Plus the top 5 global hotspots for ambient awareness.
Example: get_risk(["src/auth/service.py", "src/auth/middleware.py"])
@@ -714,7 +1015,7 @@ async def get_risk(
repository = await _get_repo(session, repo)
repo_id = repository.id
- # Pre-load edge counts (dependents = incoming edges)
+ # Pre-load edges
res = await session.execute(
select(GraphEdge).where(
GraphEdge.repository_id == repo_id,
@@ -723,14 +1024,25 @@ async def get_risk(
all_edges = res.scalars().all()
dep_counts: dict[str, int] = {}
import_links: dict[str, set[str]] = {}
+ reverse_deps: dict[str, set[str]] = {} # target -> set of importers
for e in all_edges:
dep_counts[e.target_node_id] = dep_counts.get(e.target_node_id, 0) + 1
import_links.setdefault(e.source_node_id, set()).add(e.target_node_id)
import_links.setdefault(e.target_node_id, set()).add(e.source_node_id)
+ reverse_deps.setdefault(e.target_node_id, set()).add(e.source_node_id)
+
+ # Pre-load graph nodes for pagerank / impact surface
+ node_res = await session.execute(
+ select(GraphNode).where(GraphNode.repository_id == repo_id)
+ )
+ node_meta = {n.node_id: n for n in node_res.scalars().all()}
# Assess each target
results = await asyncio.gather(*[
- _assess_one_target(session, repository, t, dep_counts, import_links)
+ _assess_one_target(
+ session, repository, t, dep_counts, import_links,
+ reverse_deps, node_meta,
+ )
for t in targets
])
@@ -770,19 +1082,25 @@ async def get_risk(
@mcp.tool()
async def get_why(
query: str | None = None,
+ targets: list[str] | None = None,
repo: str | None = None,
) -> dict:
- """Understand why code is built the way it is, using architectural decision records.
+ """Understand why code is built the way it is — intent archaeology.
- Three modes:
- 1. get_why("why is auth using JWT?") — semantic search over decisions
- 2. get_why("src/auth/service.py") — all decisions governing a specific file
- 3. get_why() — decision health dashboard: stale decisions, ungoverned hotspots
+ Four modes:
+ 1. get_why("why is auth using JWT?") — semantic + keyword search over decisions
+ 2. get_why("src/auth/service.py") — all decisions governing a specific file,
+ plus origin story and alignment score
+ 3. get_why("why was caching added?", targets=["src/auth/cache.py"]) —
+ target-aware search: prioritizes decisions governing the target files
+ 4. get_why() — decision health dashboard
Always call this before making architectural changes.
Args:
query: Natural language question, file/module path, or omit for health dashboard.
+ targets: Optional file paths to anchor the search. Decisions governing
+ these files are prioritized in results.
repo: Repository path, name, or ID.
"""
# --- Mode 1: No query → health dashboard ---
@@ -827,7 +1145,7 @@ async def get_why(
"ungoverned_hotspots": ungoverned[:15],
}
- # --- Mode 2: Path → decisions governing that path ---
+ # --- Mode 2: Path → decisions, origin story, alignment ---
if _is_path(query):
async with get_session(_session_factory) as session:
repository = await _get_repo(session, repo)
@@ -838,6 +1156,23 @@ async def get_why(
)
all_decisions = res.scalars().all()
+ # Load git metadata for origin story
+ git_res = await session.execute(
+ select(GitMetadata).where(
+ GitMetadata.repository_id == repository.id,
+ GitMetadata.file_path == query,
+ )
+ )
+ git_meta = git_res.scalar_one_or_none()
+
+ # Pre-load all git metadata for cross-file search (used by fallback)
+ all_git_res = await session.execute(
+ select(GitMetadata).where(
+ GitMetadata.repository_id == repository.id,
+ )
+ )
+ all_git_meta = all_git_res.scalars().all()
+
governing = []
for d in all_decisions:
affected_files = json.loads(d.affected_files_json)
@@ -858,13 +1193,23 @@ async def get_why(
"staleness_score": d.staleness_score,
})
- return {
+ result_data: dict[str, Any] = {
"mode": "path",
"path": query,
"decisions": governing,
+ "origin_story": _build_origin_story(query, git_meta, governing),
+ "alignment": _compute_alignment(query, governing, all_decisions),
}
- # --- Mode 3: Natural language → search ---
+ # --- Fallback: git archaeology when no decisions found ---
+ if not governing:
+ result_data["git_archaeology"] = await _git_archaeology_fallback(
+ query, git_meta, all_git_meta, repository,
+ )
+
+ return result_data
+
+ # --- Mode 3: Natural language → target-aware search ---
from wikicode.core.persistence.crud import list_decisions as _list_decisions
async with get_session(_session_factory) as session:
@@ -873,17 +1218,38 @@ async def get_why(
session, repository.id, include_proposed=True, limit=200
)
- # Keyword scoring
+ # Load git metadata for targets (for origin context in results)
+ target_git: dict[str, Any] = {}
+ if targets:
+ for t in targets:
+ git_res = await session.execute(
+ select(GitMetadata).where(
+ GitMetadata.repository_id == repository.id,
+ GitMetadata.file_path == t,
+ )
+ )
+ meta = git_res.scalar_one_or_none()
+ if meta:
+ target_git[t] = meta
+
+ # Build target file set for boosting
+ target_set = set(targets) if targets else set()
+
+ # Weighted keyword scoring across ALL decision fields
query_lower = query.lower()
query_words = set(query_lower.split())
- scored_decisions = []
+ # Remove stop words for better matching
+ stop_words = {"why", "was", "is", "the", "a", "an", "this", "that", "how",
+ "what", "when", "where", "for", "to", "of", "in", "it", "be"}
+ query_words -= stop_words
+
+ scored_decisions: list[tuple[float, Any]] = []
for d in all_decisions:
- text = f"{d.title} {d.decision} {d.rationale}".lower()
- match_count = sum(1 for w in query_words if w in text)
- if match_count > 0:
- scored_decisions.append((match_count, d))
+ score = _score_decision(d, query_words, target_set)
+ if score > 0:
+ scored_decisions.append((score, d))
scored_decisions.sort(key=lambda t: t[0], reverse=True)
- keyword_matches = [d for _, d in scored_decisions[:5]]
+ keyword_matches = [d for _, d in scored_decisions[:8]]
# Semantic search over decision vector store
decision_results = []
@@ -914,6 +1280,7 @@ async def get_why(
"status": d.status,
"decision": d.decision,
"rationale": d.rationale,
+ "context": d.context,
"consequences": json.loads(d.consequences_json),
"affected_files": json.loads(d.affected_files_json),
"source": d.source,
@@ -930,7 +1297,7 @@ async def get_why(
"relevance_score": r.score,
})
- return {
+ result_data: dict[str, Any] = {
"mode": "search",
"query": query,
"decisions": merged_decisions[:8],
@@ -946,6 +1313,224 @@ async def get_why(
],
}
+ # If targets provided, include target context
+ if targets:
+ async with get_session(_session_factory) as session2:
+ # Load all git metadata for cross-file search
+ all_git_res = await session2.execute(
+ select(GitMetadata).where(
+ GitMetadata.repository_id == repository.id,
+ )
+ )
+ all_git_meta_list = all_git_res.scalars().all()
+
+ target_context = {}
+ for t in targets:
+ t_governing = []
+ for d in all_decisions:
+ affected = json.loads(d.affected_files_json)
+ affected_mods = json.loads(d.affected_modules_json)
+ if t in affected or any(t.startswith(m + "/") for m in affected_mods):
+ t_governing.append({"title": d.title, "status": d.status})
+ git_m = target_git.get(t)
+ ctx_entry: dict[str, Any] = {
+ "governing_decisions": t_governing,
+ "origin": _build_origin_story(t, git_m, t_governing) if git_m else {
+ "available": False,
+ "summary": f"No git history for {t}.",
+ },
+ }
+ # Git archaeology fallback when no decisions found
+ if not t_governing:
+ ctx_entry["git_archaeology"] = await _git_archaeology_fallback(
+ t, git_m, all_git_meta_list, repository,
+ )
+ target_context[t] = ctx_entry
+ result_data["target_context"] = target_context
+
+ return result_data
+
+
+def _score_decision(
+ d: Any, query_words: set[str], target_files: set[str],
+) -> float:
+ """Score a decision against query words with field weighting and target boosting."""
+ if not query_words:
+ return 1.0 if target_files else 0.0
+
+ # Build weighted text fields
+ fields = [
+ (3.0, d.title.lower()),
+ (2.0, d.decision.lower()),
+ (2.0, d.rationale.lower()),
+ (1.5, d.context.lower()),
+ (1.0, " ".join(json.loads(d.consequences_json)).lower()),
+ (1.0, " ".join(json.loads(d.tags_json)).lower()),
+ (1.5, " ".join(json.loads(d.affected_files_json)).lower()),
+ (1.0, (d.evidence_file or "").lower()),
+ ]
+
+ score = 0.0
+ for weight, text in fields:
+ for word in query_words:
+ if word in text:
+ score += weight
+
+ # Target file boosting: decisions governing target files get a bonus
+ if target_files:
+ affected = set(json.loads(d.affected_files_json))
+ affected_mods = json.loads(d.affected_modules_json)
+ for t in target_files:
+ if t in affected:
+ score += 5.0 # Strong boost for exact file match
+ elif any(t.startswith(m + "/") for m in affected_mods):
+ score += 3.0 # Module-level match
+
+ return score
+
+
+async def _git_archaeology_fallback(
+ file_path: str,
+ git_meta: Any | None,
+ all_git_meta: list,
+ repository: Any,
+) -> dict:
+ """When no decisions govern a file, mine git history for intent signals."""
+ result: dict[str, Any] = {"triggered": True}
+
+ # --- Layer 1: File's own significant commits ---
+ file_commits = []
+ if git_meta and git_meta.significant_commits_json:
+ commits = json.loads(git_meta.significant_commits_json)
+ file_commits = [
+ {
+ "sha": c.get("sha", ""),
+ "message": c.get("message", ""),
+ "author": c.get("author", ""),
+ "date": c.get("date", ""),
+ }
+ for c in commits
+ ]
+ result["file_commits"] = file_commits
+
+ # --- Layer 2: Cross-file search — other files' commits mentioning this file ---
+ basename = file_path.rsplit("/", 1)[-1] if "/" in file_path else file_path
+ stem = basename.rsplit(".", 1)[0] if "." in basename else basename
+ # Convert snake_case/kebab to searchable terms: auth_cache_service -> {"auth", "cache", "service"}
+ search_terms = set(re.split(r"[_\-/.]", stem.lower()))
+ search_terms.discard("")
+ # Also search for the full basename
+ search_terms.add(basename.lower())
+
+ cross_references = []
+ for gm in all_git_meta:
+ if gm.file_path == file_path:
+ continue
+ commits = json.loads(gm.significant_commits_json) if gm.significant_commits_json else []
+ for c in commits:
+ msg_lower = c.get("message", "").lower()
+ # Match if the commit message mentions the file basename or 2+ stem terms
+ matched_terms = [t for t in search_terms if t in msg_lower]
+ if basename.lower() in msg_lower or len(matched_terms) >= 2:
+ cross_references.append({
+ "source_file": gm.file_path,
+ "sha": c.get("sha", ""),
+ "message": c.get("message", ""),
+ "author": c.get("author", ""),
+ "date": c.get("date", ""),
+ "matched_terms": matched_terms,
+ })
+ # Deduplicate by SHA and sort by date descending
+ seen_shas: set[str] = set()
+ unique_refs = []
+ for cr in cross_references:
+ if cr["sha"] not in seen_shas:
+ seen_shas.add(cr["sha"])
+ unique_refs.append(cr)
+ unique_refs.sort(key=lambda x: x.get("date", ""), reverse=True)
+ result["cross_references"] = unique_refs[:10]
+
+ # --- Layer 3: Live git log (when local repo exists) ---
+ git_log_results = []
+ local_path = getattr(repository, "local_path", None)
+ if local_path and os.path.isdir(os.path.join(local_path, ".git")):
+ git_log_results = await _run_git_log(local_path, file_path, stem)
+ result["git_log"] = git_log_results
+
+ # --- Summary ---
+ total = len(file_commits) + len(unique_refs) + len(git_log_results)
+ if total > 0:
+ result["summary"] = (
+ f"No architectural decisions found for {file_path}, but git archaeology "
+ f"recovered {len(file_commits)} direct commit(s), "
+ f"{len(unique_refs)} cross-reference(s), and "
+ f"{len(git_log_results)} git log result(s). "
+ "Review these to understand the intent behind this code."
+ )
+ else:
+ result["summary"] = (
+ f"No architectural decisions or git history found for {file_path}. "
+ "This file may be new or not yet indexed."
+ )
+
+ return result
+
+
+async def _run_git_log(
+ repo_path: str, file_path: str, stem: str,
+) -> list[dict]:
+ """Run git log against the local repo for deeper history. Best-effort."""
+ import subprocess
+
+ results = []
+ try:
+ # Search for commits that touched this file
+ proc = subprocess.run(
+ ["git", "log", "--follow", "--format=%H\t%an\t%ai\t%s", "-20", "--", file_path],
+ cwd=repo_path,
+ capture_output=True,
+ text=True,
+ timeout=10,
+ )
+ if proc.returncode == 0:
+ for line in proc.stdout.strip().splitlines():
+ parts = line.split("\t", 3)
+ if len(parts) == 4:
+ results.append({
+ "sha": parts[0][:12],
+ "author": parts[1],
+ "date": parts[2][:10],
+ "message": parts[3],
+ "source": "git_log_follow",
+ })
+
+ # Also grep for the class/function name in commit messages
+ if stem and len(stem) >= 3:
+ proc2 = subprocess.run(
+ ["git", "log", "--all", "--grep", stem, "--format=%H\t%an\t%ai\t%s", "-10"],
+ cwd=repo_path,
+ capture_output=True,
+ text=True,
+ timeout=10,
+ )
+ if proc2.returncode == 0:
+ seen = {r["sha"] for r in results}
+ for line in proc2.stdout.strip().splitlines():
+ parts = line.split("\t", 3)
+ if len(parts) == 4 and parts[0][:12] not in seen:
+ seen.add(parts[0][:12])
+ results.append({
+ "sha": parts[0][:12],
+ "author": parts[1],
+ "date": parts[2][:10],
+ "message": parts[3],
+ "source": "git_log_grep",
+ })
+ except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+ pass # Git not available or repo not accessible
+
+ return results[:20]
+
# ---------------------------------------------------------------------------
# Tool 5: search_codebase (unchanged)
@@ -1233,7 +1818,7 @@ def _build_visual_context(
# ---------------------------------------------------------------------------
-# Tool 7: get_dead_code (unchanged)
+# Tool 7: get_dead_code (tiered refactor plan)
# ---------------------------------------------------------------------------
@@ -1244,77 +1829,204 @@ async def get_dead_code(
min_confidence: float = 0.5,
safe_only: bool = False,
limit: int = 20,
+ tier: str | None = None,
+ directory: str | None = None,
+ owner: str | None = None,
+ group_by: str | None = None,
) -> dict:
- """Get dead and unused code findings. Use before cleanup tasks.
+ """Get a tiered refactor plan for dead and unused code.
+
+ Returns findings organized into confidence tiers (high/medium/low),
+ with per-directory rollups, ownership hotspots, and impact estimates
+ so you can prioritize cleanup.
- Results sorted by confidence desc, then lines desc (biggest wins first).
+ Use group_by="directory" for a directory-level overview, or
+ group_by="owner" to see who owns the most dead code. Use tier
+ to focus on a single confidence band.
Args:
repo: Repository path, name, or ID.
kind: Filter by kind (unreachable_file, unused_export, unused_internal, zombie_package).
min_confidence: Minimum confidence threshold (default 0.5).
safe_only: Only return findings marked safe_to_delete (default false).
- limit: Maximum findings to return (default 20).
+ limit: Maximum findings per tier (default 20).
+ tier: Focus on a single tier: "high" (>=0.8), "medium" (0.5-0.8), or "low" (<0.5).
+ directory: Filter findings to a specific directory prefix.
+ owner: Filter findings by primary owner name.
+ group_by: "directory" for per-directory rollup, "owner" for ownership hotspots.
"""
async with get_session(_session_factory) as session:
repository = await _get_repo(session, repo)
- query = (
- select(DeadCodeFinding)
- .where(
- DeadCodeFinding.repository_id == repository.id,
- DeadCodeFinding.status == "open",
- DeadCodeFinding.confidence >= min_confidence,
- )
- .order_by(DeadCodeFinding.confidence.desc(), DeadCodeFinding.lines.desc())
+ # Fetch all open findings for summary computation
+ all_query = select(DeadCodeFinding).where(
+ DeadCodeFinding.repository_id == repository.id,
+ DeadCodeFinding.status == "open",
)
+ all_result = await session.execute(all_query)
+ all_findings = list(all_result.scalars().all())
- if kind:
- query = query.where(DeadCodeFinding.kind == kind)
- if safe_only:
- query = query.where(DeadCodeFinding.safe_to_delete == True) # noqa: E712
- query = query.limit(limit)
+ # --- Apply filters ---
+ filtered = all_findings
+ if kind:
+ filtered = [f for f in filtered if f.kind == kind]
+ if safe_only:
+ filtered = [f for f in filtered if f.safe_to_delete]
+ if min_confidence > 0:
+ filtered = [f for f in filtered if f.confidence >= min_confidence]
+ if directory:
+ prefix = directory.rstrip("/") + "/"
+ filtered = [f for f in filtered if f.file_path.startswith(prefix)]
+ if owner:
+ owner_lower = owner.lower()
+ filtered = [f for f in filtered if f.primary_owner and f.primary_owner.lower() == owner_lower]
+
+ # --- Build tiered structure ---
+ tiers = _build_tiers(filtered, limit, tier)
+
+ # --- Summary across ALL open findings (unfiltered) ---
+ by_kind: dict[str, int] = {}
+ for f in all_findings:
+ by_kind[f.kind] = by_kind.get(f.kind, 0) + 1
+
+ summary = {
+ "total_findings": len(all_findings),
+ "filtered_findings": len(filtered),
+ "deletable_lines": sum(f.lines for f in all_findings if f.safe_to_delete),
+ "safe_to_delete_count": sum(1 for f in all_findings if f.safe_to_delete),
+ "by_kind": by_kind,
+ }
- result = await session.execute(query)
- findings = list(result.scalars().all())
+ result: dict[str, Any] = {"summary": summary, "tiers": tiers}
- # Compute summary
- all_result = await session.execute(
- select(DeadCodeFinding).where(
- DeadCodeFinding.repository_id == repository.id,
- DeadCodeFinding.status == "open",
- )
- )
- all_findings = list(all_result.scalars().all())
+ # --- Grouping views ---
+ if group_by == "directory":
+ result["by_directory"] = _rollup_by_directory(filtered)
+ elif group_by == "owner":
+ result["by_owner"] = _rollup_by_owner(filtered)
+
+ # --- Impact estimate ---
+ result["impact"] = _compute_impact(tiers)
- by_kind: dict[str, int] = {}
- for f in all_findings:
- by_kind[f.kind] = by_kind.get(f.kind, 0) + 1
+ return result
+
+
+def _serialize_finding(f: Any) -> dict:
+ """Serialize a single DeadCodeFinding to dict."""
+ return {
+ "kind": f.kind,
+ "file_path": f.file_path,
+ "symbol_name": f.symbol_name,
+ "confidence": f.confidence,
+ "reason": f.reason,
+ "safe_to_delete": f.safe_to_delete,
+ "lines": f.lines,
+ "last_commit_at": f.last_commit_at.isoformat() if f.last_commit_at else None,
+ "primary_owner": f.primary_owner,
+ "age_days": f.age_days,
+ }
+
+def _build_tiers(
+ findings: list, limit: int, tier_filter: str | None,
+) -> dict:
+ """Split findings into high/medium/low confidence tiers."""
+ high = sorted(
+ [f for f in findings if f.confidence >= 0.8],
+ key=lambda f: (-f.confidence, -f.lines),
+ )
+ medium = sorted(
+ [f for f in findings if 0.5 <= f.confidence < 0.8],
+ key=lambda f: (-f.confidence, -f.lines),
+ )
+ low = sorted(
+ [f for f in findings if f.confidence < 0.5],
+ key=lambda f: (-f.confidence, -f.lines),
+ )
+
+ def _tier_block(name: str, items: list, description: str) -> dict:
return {
- "summary": {
- "total_findings": len(all_findings),
- "deletable_lines": sum(f.lines for f in all_findings if f.safe_to_delete),
- "safe_to_delete_count": sum(1 for f in all_findings if f.safe_to_delete),
- "by_kind": by_kind,
- },
- "findings": [
- {
- "kind": f.kind,
- "file_path": f.file_path,
- "symbol_name": f.symbol_name,
- "confidence": f.confidence,
- "reason": f.reason,
- "safe_to_delete": f.safe_to_delete,
- "lines": f.lines,
- "last_commit_at": f.last_commit_at.isoformat() if f.last_commit_at else None,
- "primary_owner": f.primary_owner,
- "age_days": f.age_days,
- }
- for f in findings
- ],
+ "description": description,
+ "count": len(items),
+ "lines": sum(f.lines for f in items),
+ "safe_count": sum(1 for f in items if f.safe_to_delete),
+ "findings": [_serialize_finding(f) for f in items[:limit]],
+ "truncated": len(items) > limit,
}
+ tiers = {}
+ if tier_filter is None or tier_filter == "high":
+ tiers["high"] = _tier_block(
+ "high", high,
+ "High confidence (>=0.8): Zero references in the codebase. Safe to delete.",
+ )
+ if tier_filter is None or tier_filter == "medium":
+ tiers["medium"] = _tier_block(
+ "medium", medium,
+ "Medium confidence (0.5-0.8): Likely unused but may have indirect references. Review before deleting.",
+ )
+ if tier_filter is None or tier_filter == "low":
+ tiers["low"] = _tier_block(
+ "low", low,
+ "Low confidence (<0.5): Potentially used via dynamic imports or reflection. Investigate first.",
+ )
+ return tiers
+
+
+def _rollup_by_directory(findings: list) -> list[dict]:
+ """Group findings by top-level directory."""
+ dirs: dict[str, dict] = {}
+ for f in findings:
+ parts = f.file_path.split("/")
+ # Use first two path segments as directory key, or just the first
+ dir_key = "/".join(parts[:2]) if len(parts) > 2 else parts[0]
+ if dir_key not in dirs:
+ dirs[dir_key] = {"directory": dir_key, "count": 0, "lines": 0, "safe_count": 0}
+ dirs[dir_key]["count"] += 1
+ dirs[dir_key]["lines"] += f.lines
+ if f.safe_to_delete:
+ dirs[dir_key]["safe_count"] += 1
+
+ return sorted(dirs.values(), key=lambda d: -d["lines"])
+
+
+def _rollup_by_owner(findings: list) -> list[dict]:
+ """Group findings by primary owner."""
+ owners: dict[str, dict] = {}
+ for f in findings:
+ name = f.primary_owner or "unowned"
+ if name not in owners:
+ owners[name] = {"owner": name, "count": 0, "lines": 0, "safe_count": 0}
+ owners[name]["count"] += 1
+ owners[name]["lines"] += f.lines
+ if f.safe_to_delete:
+ owners[name]["safe_count"] += 1
+
+ return sorted(owners.values(), key=lambda o: -o["lines"])
+
+
+def _compute_impact(tiers: dict) -> dict:
+ """Compute total impact across tiers."""
+ total_lines = 0
+ safe_lines = 0
+ for tier_data in tiers.values():
+ total_lines += tier_data["lines"]
+ # Approximate safe lines from findings in the tier
+ for f in tier_data["findings"]:
+ if f["safe_to_delete"]:
+ safe_lines += f["lines"]
+
+ return {
+ "total_lines_reclaimable": total_lines,
+ "safe_lines_reclaimable": safe_lines,
+ "recommendation": (
+ "Start with the 'high' tier — these have zero references and are safe to remove. "
+ "Then review 'medium' tier findings with your team."
+ if total_lines > 0
+ else "No dead code found matching your filters."
+ ),
+ }
+
# ---------------------------------------------------------------------------
# Tool 8: get_architecture_diagram (unchanged)
diff --git a/packages/server/src/wikicode/server/routers/chat.py b/packages/server/src/wikicode/server/routers/chat.py
index 770cabd3a..4af48451f 100644
--- a/packages/server/src/wikicode/server/routers/chat.py
+++ b/packages/server/src/wikicode/server/routers/chat.py
@@ -446,13 +446,27 @@ def _build_tool_summary(tool_name: str, result: dict[str, Any]) -> str:
if tool_name == "get_risk":
targets = result.get("targets", {})
- return f"Risk assessment for {len(targets)} file(s)"
+ increasing = sum(1 for t in targets.values() if t.get("trend") == "increasing")
+ bug_prone = sum(1 for t in targets.values() if t.get("risk_type") == "bug-prone")
+ parts = [f"Risk assessment for {len(targets)} file(s)"]
+ if increasing:
+ parts.append(f"{increasing} increasing")
+ if bug_prone:
+ parts.append(f"{bug_prone} bug-prone")
+ return ", ".join(parts)
if tool_name == "get_why":
mode = result.get("mode", "")
if mode == "health":
counts = result.get("counts", {})
return f"Decision health: {counts.get('active', 0)} active, {counts.get('stale', 0)} stale"
+ if mode == "path":
+ decisions = result.get("decisions", [])
+ alignment = result.get("alignment", {})
+ score = alignment.get("score", "unknown")
+ origin = result.get("origin_story", {})
+ author = origin.get("primary_author", "unknown") if origin.get("available") else "unknown"
+ return f"{len(decisions)} decision(s), alignment: {score}, author: {author}"
decisions = result.get("decisions", [])
return f"Found {len(decisions)} decision(s)"
@@ -474,7 +488,11 @@ def _build_tool_summary(tool_name: str, result: dict[str, Any]) -> str:
if tool_name == "get_dead_code":
summary = result.get("summary", {})
- return f"{summary.get('total_findings', 0)} findings, {summary.get('deletable_lines', 0)} deletable lines"
+ tiers = result.get("tiers", {})
+ high_count = tiers.get("high", {}).get("count", 0)
+ total = summary.get("total_findings", 0)
+ lines = summary.get("deletable_lines", 0)
+ return f"{total} findings ({high_count} high-confidence), {lines} deletable lines"
if tool_name == "get_architecture_diagram":
return f"Generated {result.get('diagram_type', 'diagram')}"
diff --git a/tests/unit/server/test_mcp.py b/tests/unit/server/test_mcp.py
index fda3b1c46..3fe379946 100644
--- a/tests/unit/server/test_mcp.py
+++ b/tests/unit/server/test_mcp.py
@@ -700,6 +700,21 @@ async def test_get_risk_single_target(setup_mcp):
assert "risk_summary" in t
assert "hotspot score" in t["risk_summary"]
+ # Trend: 30d=3, 90d=8 → baseline_rate=0.083, recent=0.1 → stable
+ assert t["trend"] in ("increasing", "stable", "decreasing")
+
+ # Risk type: churn_percentile=0.92, no fix keywords → churn-heavy
+ assert t["risk_type"] == "churn-heavy"
+
+ # Impact surface: middleware.py depends on service.py
+ assert len(t["impact_surface"]) >= 1
+ impact_files = [s["file_path"] for s in t["impact_surface"]]
+ assert "src/auth/middleware.py" in impact_files
+ # Each entry has pagerank and is_entry_point
+ for s in t["impact_surface"]:
+ assert "pagerank" in s
+ assert "is_entry_point" in s
+
@pytest.mark.asyncio
async def test_get_risk_multiple_targets(setup_mcp):
@@ -709,6 +724,10 @@ async def test_get_risk_multiple_targets(setup_mcp):
targets = result["targets"]
assert len(targets) == 2
assert "global_hotspots" in result
+ # Both targets should have trend and risk_type
+ for t in targets.values():
+ assert "trend" in t
+ assert "risk_type" in t
@pytest.mark.asyncio
@@ -728,7 +747,23 @@ async def test_get_risk_no_git_metadata(setup_mcp):
result = await get_risk(["src/auth/middleware.py"])
t = result["targets"]["src/auth/middleware.py"]
assert t["hotspot_score"] == 0.0 # No git metadata for this file
+ assert t["trend"] == "unknown"
assert "risk_summary" in t
+ # Impact surface and risk_type still computed from graph data
+ assert "risk_type" in t
+ assert "impact_surface" in t
+
+
+async def test_get_risk_stable_file(setup_mcp):
+ from wikicode.server.mcp_server import get_risk
+
+ result = await get_risk(["src/db/models.py"])
+ t = result["targets"]["src/db/models.py"]
+ # 0 commits in 30d and 90d → stable
+ assert t["trend"] == "stable"
+ # churn_percentile=0.15, dep_count=1, no fix keywords → stable
+ assert t["risk_type"] == "stable"
# ---- Tool 4: get_why ----
@@ -755,6 +790,145 @@ async def test_get_why_file_path(setup_mcp):
assert len(result["decisions"]) >= 1
assert any(d["title"] == "Use JWT for authentication" for d in result["decisions"])
+ # Origin story
+ origin = result["origin_story"]
+ assert origin["available"] is True
+ assert origin["primary_author"] == "Alice"
+ assert origin["total_commits"] == 42
+ assert len(origin["key_commits"]) >= 1
+ assert len(origin["contributors"]) >= 1
+ assert "Alice" in origin["summary"]
+
+ # Alignment — dec1 is "proposed", both service.py and middleware.py share it
+ alignment = result["alignment"]
+ assert alignment["score"] in ("high", "medium", "low", "none")
+ assert alignment["governing_count"] >= 1
+ assert "explanation" in alignment
+
+
+async def test_get_why_file_path_commit_decision_linkage(setup_mcp):
+ from wikicode.server.mcp_server import get_why
+
+ result = await get_why("src/auth/service.py")
+ origin = result["origin_story"]
+
+ # "Add JWT support" commit should link to "Use JWT for authentication" decision
+ # because "JWT" appears in both the commit message and decision title
+ linked = origin["linked_decisions"]
+ assert len(linked) >= 1
+ jwt_decision = next((d for d in linked if d["title"] == "Use JWT for authentication"), None)
+ assert jwt_decision is not None
+ assert len(jwt_decision["evidence_commits"]) >= 1
+ ec = jwt_decision["evidence_commits"][0]
+ assert "JWT" in ec["message"] or "jwt" in ec["message"].lower()
+ assert "matching_keywords" in ec
+
+
+async def test_get_why_natural_language_with_targets(setup_mcp):
+ from wikicode.server.mcp_server import get_why
+
+ # Search with targets — decisions governing service.py should be boosted
+ result = await get_why(
+ "authentication approach",
+ targets=["src/auth/service.py"],
+ )
+ assert result["mode"] == "search"
+ assert len(result["decisions"]) >= 1
+
+ # target_context should be present
+ assert "target_context" in result
+ ctx = result["target_context"]["src/auth/service.py"]
+ assert len(ctx["governing_decisions"]) >= 1
+ assert ctx["origin"]["available"] is True
+ assert ctx["origin"]["primary_author"] == "Alice"
+
+
+async def test_get_why_expanded_keyword_search(setup_mcp):
+ from wikicode.server.mcp_server import get_why
+
+ # Search for "security" — should match via tags_json on dec1
+ result = await get_why("security")
+ assert result["mode"] == "search"
+ # dec1 has tags=["auth", "security"], should be found
+ assert len(result["decisions"]) >= 1
+ assert any(d.get("title") == "Use JWT for authentication" for d in result["decisions"])
+
+
+async def test_get_why_file_no_git_metadata(setup_mcp):
+ from wikicode.server.mcp_server import get_why
+
+ # middleware.py has no GitMetadata in the fixture
+ result = await get_why("src/auth/middleware.py")
+ assert result["mode"] == "path"
+ origin = result["origin_story"]
+ assert origin["available"] is False
+ assert "No git history" in origin["summary"]
+
+ # But it still has decisions (dec1 affects middleware.py)
+ assert len(result["decisions"]) >= 1
+ alignment = result["alignment"]
+ assert alignment["governing_count"] >= 1
+
+
+async def test_get_why_file_ungoverned(setup_mcp):
+ from wikicode.server.mcp_server import get_why
+
+ # Use a path that has no decisions — triggers git archaeology fallback
+ result = await get_why("src/other/utils.py")
+ assert result["mode"] == "path"
+ assert result["alignment"]["score"] == "none"
+ assert "ungoverned" in result["alignment"]["explanation"]
+
+ # Git archaeology fallback should be triggered
+ assert "git_archaeology" in result
+ arch = result["git_archaeology"]
+ assert arch["triggered"] is True
+ assert "summary" in arch
+ assert "file_commits" in arch
+ assert "cross_references" in arch
+ assert "git_log" in arch
+
+
+async def test_get_why_fallback_with_cross_references(setup_mcp):
+ from wikicode.server.mcp_server import get_why
+
+ # src/auth/service.py has git metadata with commits mentioning "auth"
+ # Query a nonexistent auth file — cross-references should find commits
+ # from service.py that mention "auth" terms
+ result = await get_why("src/auth/new_handler.py")
+ assert result["mode"] == "path"
+ assert len(result["decisions"]) == 0 # No decisions for this file
+
+ arch = result["git_archaeology"]
+ assert arch["triggered"] is True
+ # Cross-references may find commits from service.py whose messages
+ # contain "auth" (matching the path stem "new_handler" won't match,
+ # but the file_commits will still be empty since no git metadata exists)
+ assert isinstance(arch["cross_references"], list)
+
+
+async def test_get_why_targets_fallback(setup_mcp):
+ from wikicode.server.mcp_server import get_why
+
+ # Search with a target that has no governing decisions
+ result = await get_why(
+ "why does this exist",
+ targets=["src/other/unknown.py"],
+ )
+ assert result["mode"] == "search"
+ ctx = result["target_context"]["src/other/unknown.py"]
+ assert len(ctx["governing_decisions"]) == 0
+ # Fallback should trigger
+ assert "git_archaeology" in ctx
+ assert ctx["git_archaeology"]["triggered"] is True
+
@pytest.mark.asyncio
async def test_get_why_no_args(setup_mcp):
@@ -896,10 +1070,19 @@ async def test_get_dead_code(setup_mcp):
result = await get_dead_code()
assert result["summary"]["total_findings"] == 3
assert result["summary"]["safe_to_delete_count"] == 2
- # Default min_confidence=0.5, so all findings at >= 0.5 are included
- findings = result["findings"]
- assert len(findings) == 3
- assert findings[0]["confidence"] >= findings[1]["confidence"] # sorted desc
+
+ # Tiered structure: dc1 (0.9) in high, dc2 (0.7) + dc3 (0.5) in medium
+ tiers = result["tiers"]
+ assert tiers["high"]["count"] == 1
+ assert tiers["medium"]["count"] == 2
+ assert tiers["low"]["count"] == 0
+
+ # High tier findings sorted by confidence desc
+ high_findings = tiers["high"]["findings"]
+ assert high_findings[0]["confidence"] >= 0.8
+
+ # Impact estimate present
+ assert result["impact"]["total_lines_reclaimable"] > 0
@pytest.mark.asyncio
@@ -907,8 +1090,9 @@ async def test_get_dead_code_safe_only(setup_mcp):
from wikicode.server.mcp_server import get_dead_code
result = await get_dead_code(safe_only=True)
- for f in result["findings"]:
- assert f["safe_to_delete"] is True
+ for tier_data in result["tiers"].values():
+ for f in tier_data["findings"]:
+ assert f["safe_to_delete"] is True
@pytest.mark.asyncio
@@ -916,8 +1100,9 @@ async def test_get_dead_code_by_kind(setup_mcp):
from wikicode.server.mcp_server import get_dead_code
result = await get_dead_code(kind="unreachable_file", min_confidence=0.0)
- for f in result["findings"]:
- assert f["kind"] == "unreachable_file"
+ for tier_data in result["tiers"].values():
+ for f in tier_data["findings"]:
+ assert f["kind"] == "unreachable_file"
@pytest.mark.asyncio
@@ -925,7 +1110,46 @@ async def test_get_dead_code_low_confidence(setup_mcp):
from wikicode.server.mcp_server import get_dead_code
result = await get_dead_code(min_confidence=0.0)
- assert len(result["findings"]) == 3 # All 3 findings included
+ total = sum(t["count"] for t in result["tiers"].values())
+ assert total == 3 # All 3 findings included
+
+
+async def test_get_dead_code_tier_filter(setup_mcp):
+ from wikicode.server.mcp_server import get_dead_code
+
+ result = await get_dead_code(tier="high")
+ assert "high" in result["tiers"]
+ assert "medium" not in result["tiers"]
+ assert "low" not in result["tiers"]
+ assert result["tiers"]["high"]["count"] == 1
+
+
+async def test_get_dead_code_group_by_directory(setup_mcp):
+ from wikicode.server.mcp_server import get_dead_code
+
+ result = await get_dead_code(group_by="directory", min_confidence=0.0)
+ assert "by_directory" in result
+ dirs = result["by_directory"]
+ assert len(dirs) >= 1
+ # Each dir entry has count, lines, safe_count
+ for d in dirs:
+ assert "directory" in d
+ assert "count" in d
+ assert "lines" in d
+
+
+async def test_get_dead_code_group_by_owner(setup_mcp):
+ from wikicode.server.mcp_server import get_dead_code
+
+ result = await get_dead_code(group_by="owner", min_confidence=0.0)
+ assert "by_owner" in result
+ owners = result["by_owner"]
+ assert len(owners) >= 1
+ owner_names = [o["owner"] for o in owners]
+ assert "Bob" in owner_names # Bob owns dc2 + dc3
# ---- MCP config generation ----