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
Fix 6 low-hanging MCP tool issues (Phase 1)
RaghavChamadiyae1c679593be3
diff --git a/docs/MCP_FIX_PLAN.md b/docs/MCP_FIX_PLAN.mdnew file mode 100644index 000000000..28d142fec--- /dev/null+++ b/docs/MCP_FIX_PLAN.md@@ -0,0 +1,562 @@+# MCP Tools Fix Plan++Based on: [MCP_TOOLS_TEST_REPORT.md](./MCP_TOOLS_TEST_REPORT.md)++---++## Phase 1: Low-Hanging Fruit (Quick Wins)++These fixes are localized, low-risk, and can be done independently.++---++### 1.1 — Shorter node labels in architecture diagrams++**Issue:** Node IDs like `packages_core_src_repowise_core_persistence_models_py` are unreadable in rendered diagrams.++**File:** `packages/server/src/repowise/server/mcp_server.py` — lines 2347, 2353++**Current:**+```python+lines.append(f' {src}["{e.source_node_id}"]')+```++**Fix:** Extract a short label (filename or `parent/filename`) from the full node ID:+```python+def _short_label(node_id: str) -> str:+ """e.g. 'packages/core/src/.../models.py' → 'persistence/models.py'"""+ parts = node_id.replace("\\", "/").split("/")+ if len(parts) >= 2:+ return "/".join(parts[-2:])+ return parts[-1]++# In diagram builder:+lines.append(f' {src}["{_short_label(e.source_node_id)}"]')+```++**Effort:** ~15 min | **Risk:** None — cosmetic change++---++### 1.2 — Exclude test fixtures from entry points++**Issue:** `go_pkg/main.go` and `rust_pkg/src/lib.rs` from `tests/fixtures/` appear as entry points in `get_overview`.++**File:** `packages/server/src/repowise/server/mcp_server.py` — lines 477-484++**Current:** Queries `GraphNode.is_entry_point == True` with no test exclusion.++**Fix:** Add filter to exclude nodes under test/fixture directories:+```python+result = await session.execute(+ select(GraphNode).where(+ GraphNode.repository_id == repository.id,+ GraphNode.is_entry_point == True,+ GraphNode.is_test == False, # Add this+ )+)+entry_nodes = result.scalars().all()++# Then also filter fixture paths in Python:+entry_nodes = [+ n for n in entry_nodes+ if "fixture" not in n.node_id.lower()+ and "test_data" not in n.node_id.lower()+]+```++**Also check:** `GraphNode` model has `is_test` column. Verify at:+- `packages/core/src/repowise/core/persistence/models.py` — `GraphNode` model+- `packages/core/src/repowise/core/ingestion/graph.py` — line ~65 where `is_test` is stored++**Effort:** ~20 min | **Risk:** Low++---++### 1.3 — Add framework-loaded files to dead code skip list++**Issue:** `conftest.py` (pytest), `alembic/env.py` (alembic), `__main__.py` flagged as dead code.++**File:** `packages/core/src/repowise/core/analysis/dead_code.py` — lines 71-77++**Current:**+```python+_NEVER_FLAG_PATTERNS = (+ "*__init__.py",+ "*migrations*",+ "*schema*",+ "*seed*",+ "*.d.ts",+)+```++**Fix:** Extend the list:+```python+_NEVER_FLAG_PATTERNS = (+ "*__init__.py",+ "*__main__.py", # Python entry points+ "*conftest.py", # pytest auto-loaded+ "*alembic/env.py", # Alembic migration framework+ "*manage.py", # Django management+ "*wsgi.py", # WSGI entry points+ "*asgi.py", # ASGI entry points+ "*migrations*",+ "*schema*",+ "*seed*",+ "*.d.ts",+)+```++**Effort:** ~10 min | **Risk:** None — adds safety, doesn't remove anything++---++### 1.4 — Exclude test fixture directories from dead code findings++**Issue:** Files in `tests/fixtures/sample_repo/` flagged as dead with `"File has no importers"`.++**File:** `packages/core/src/repowise/core/analysis/dead_code.py` — line 227++**Current:** Checks `is_test` flag but test fixtures aren't always tagged as test files (they're sample data, not test code).++**Fix:** Add fixture directory check in `_detect_unreachable_files`:+```python+# After the is_test check at line 227-228:+if self._is_fixture_path(str(node)):+ continue++# New method:+_FIXTURE_PATTERNS = ("fixture", "testdata", "test_data", "mock_data", "sample_repo")++def _is_fixture_path(self, path: str) -> bool:+ path_lower = path.lower()+ return any(pat in path_lower for pat in self._FIXTURE_PATTERNS)+```++**Effort:** ~15 min | **Risk:** Low — may miss some genuine dead code in fixture-named dirs, but that's the safer direction++---++### 1.5 — Remove or label hardcoded `confidence_score: 1.0` in search results++**Issue:** `confidence_score` is always `1.0` (from `Page.confidence` default) or `None`. Provides no signal.++**File:** `packages/server/src/repowise/server/mcp_server.py` — line 1743++**Current:** `item["confidence_score"] = info[0] if info else None` — reads from `Page.confidence` which defaults to `1.0`.++**Fix (option A — quick):** Remove the field entirely from search output since it's not useful:+```python+# Remove confidence_score from the output dict at line 1711+# Remove the batch lookup for confidence at lines 1718-1726+```++**Fix (option B — meaningful):** Replace with a normalized relevance indicator derived from the actual search score distribution:+```python+if output:+ max_score = max(item["relevance_score"] for item in output if item.get("relevance_score"))+ for item in output:+ raw = item.get("relevance_score", 0) or 0+ item["confidence_score"] = round(raw / max_score, 2) if max_score > 0 else 0.0+```++**Effort:** ~20 min | **Risk:** Low — consumers may check for this field, but it was always 1.0 so no one is branching on it++---++### 1.6 — Clip external nodes at module boundary in diagrams++**Issue:** Module-scoped diagram for `packages/core` includes files from `packages/server` and `tests/fixtures` because it follows imports across boundaries.++**File:** `packages/server/src/repowise/server/mcp_server.py` — around line 2343++**Current:** All edges in `relevant_edges` are rendered, including cross-module ones.++**Fix:** For module-scoped diagrams, replace external nodes with a single `external` stub:+```python+# When building the edge list for module scope:+for e in relevant_edges[:50]:+ src_id = e.source_node_id+ tgt_id = e.target_node_id+ # Clip cross-module edges+ if path and not src_id.startswith(path):+ src_id = "external"+ if path and not tgt_id.startswith(path):+ tgt_id = "external"+ # ... render with clipped IDs+```++**Effort:** ~30 min | **Risk:** Low++---++## Phase 2: Important Data Quality Fixes++These require more careful changes but fix the most impactful quality issues.++---++### 2.1 — `get_why` timeout wrapper for all modes++**Issue:** File-path mode and health dashboard mode hang indefinitely. 2 of 4 test calls had to be cancelled.++**Files:**+- `packages/server/src/repowise/server/mcp_server.py` — lines 1230-1269 (Mode 1), 1272-1333 (Mode 2), 1335-1474 (Mode 3)++**Root causes:**+1. **Mode 2 (path):** `all_git_meta` at line 1292-1297 loads entire `GitMetadata` table with no LIMIT. For large repos this is slow.+2. **`_git_archaeology_fallback`** at lines 1549-1574: Iterates all git metadata with an O(files × commits) inner loop. No timeout wrapper.+3. **Mode 3 (NL + targets):** Repeats the same unbounded git metadata load at lines 1443-1448.++**Fix — multi-layered:**++**A. Add overall timeout to the `get_why` handler:**+```python+async def get_why(query: str | None = None, targets: list[str] | None = None, repo: str | None = None):+ try:+ return await asyncio.wait_for(_get_why_impl(query, targets, repo), timeout=30.0)+ except asyncio.TimeoutError:+ return {"error": "get_why timed out after 30s", "mode": "timeout", "query": query}+```++**B. Limit the `all_git_meta` query:**+```python+# Line 1292-1296: Add LIMIT+all_git_res = await session.execute(+ select(GitMetadata).where(+ GitMetadata.repository_id == repository.id,+ ).limit(500) # Cap cross-file search space+)+```++**C. Add timeout to `_git_archaeology_fallback`:**+```python+async def _git_archaeology_fallback(...) -> dict:+ try:+ return await asyncio.wait_for(_git_archaeology_impl(...), timeout=10.0)+ except asyncio.TimeoutError:+ return {"triggered": True, "summary": "Git archaeology timed out.", ...}+```++**D. Limit the cross-file loop iteration:**+```python+# Line 1549: Cap iteration+for gm in all_git_meta[:500]:+```++**Effort:** ~1-2 hours | **Risk:** Medium — timeout values need tuning. Test with large repos.++---++### 2.2 — Filter `get_why` decisions by relevance++**Issue:** Query "why does the parser use tree-sitter?" returns decisions about Jinja2, SQLite, streaming protocol. Core promise broken.++**File:** `packages/server/src/repowise/server/mcp_server.py` — lines 1369-1375++**Root cause:** `_score_decision` (line 1477) does simple word overlap. Words like "use", "parser" match too broadly. Any decision mentioning common words gets a nonzero score, and all nonzero decisions are returned.++**Fix — add minimum score threshold:**+```python+# After scoring all decisions (line 1374):+scored_decisions.sort(key=lambda t: t[0], reverse=True)++# Add threshold: require at least 2 keyword matches worth of score+MIN_DECISION_SCORE = 3.0 # At least one title match or two field matches+scored_decisions = [(s, d) for s, d in scored_decisions if s >= MIN_DECISION_SCORE]++keyword_matches = [d for _, d in scored_decisions[:8]]+```++**Also improve `_score_decision`:**+```python+def _score_decision(d, query_words, target_files):+ if not query_words:+ return 1.0 if target_files else 0.0++ # Require at least 2 matching words for non-title fields (reduces noise)+ matching_word_count = 0+ for weight, text in fields:+ for word in query_words:+ if word in text:+ matching_word_count += 1+ score += weight++ # Penalize if only 1 word matched across all fields (too loose)+ if matching_word_count == 1 and score < 3.0:+ score *= 0.3++ return score+```++**Effort:** ~1 hour | **Risk:** Medium — threshold tuning needed. Too high → misses real matches.++---++### 2.3 — Search relevance threshold for nonsense queries++**Issue:** Gibberish query `"xyznonexistent gibberish query"` returns 3 results with scores 2.4-3.4 and no low-confidence indicator.++**File:** `packages/server/src/repowise/server/mcp_server.py` — after line 1715++**Fix:** Add a minimum relevance score threshold and a flag:+```python+output = output[:limit]++# Filter results below relevance threshold+MIN_RELEVANCE = 1.5 # Tuned: real matches typically score 3++if output:+ top_score = output[0]["relevance_score"] if output[0].get("relevance_score") else 0+ if top_score < MIN_RELEVANCE:+ return {"results": [], "low_confidence": True,+ "message": "No results met the relevance threshold."}+```++**Alternative — softer approach:** Keep results but add a flag:+```python+LOW_CONFIDENCE_THRESHOLD = 2.0+low_confidence = all(+ (item.get("relevance_score") or 0) < LOW_CONFIDENCE_THRESHOLD+ for item in output+)+return {"results": output, "low_confidence": low_confidence}+```++**Effort:** ~30 min | **Risk:** Low — threshold needs calibration against real queries++---++### 2.4 — Fix ownership attribution gaps++**Issue:** Files with clear git history show `primary_owner: null` across `get_context`, `get_risk`, and `get_dead_code`.++**Files:**+- `packages/core/src/repowise/core/ingestion/git_indexer.py` — lines 250-262, 410-527++**Root causes identified:**+1. **45-second per-file timeout** (line 161, 250-254): If git blame takes >45s, file returns with all-null ownership fields. On Windows especially, blame can be slow for large files.+2. **Blame-only for files ≤100KB** (line 521): Large files skip blame entirely.+3. **Empty commit list** (line 437-439): If `_get_commits()` returns empty (e.g. file only in working tree, not committed), all fields stay null.++**Fix — multi-part:**++**A. Increase blame timeout or make it configurable:**+```python+_FILE_INDEX_TIMEOUT_SECS: float = 90.0 # Up from 45+```++**B. Ensure commit-based ownership is preserved even when blame fails:**+```python+# In _index_file, after lines 498-503 (commit-based owner set):+commit_owner_name = top_authors[0]["name"]+commit_owner_email = top_authors[0]["email"]+commit_owner_pct = top_authors[0]["commit_count"] / total_commits++# Lines 514-527: Only override if blame succeeds+try:+ blame_result = await self._get_blame_ownership(...)+ if blame_result[0] is not None: # Only override if blame returned data+ meta["primary_owner_name"] = blame_result[0]+ ...+except Exception:+ pass # Keep commit-based ownership as fallback+```++**C. On timeout, still save partial data:** Instead of returning just `{"file_path": file_path}` on timeout, save whatever partial ownership data was already computed.++**D. Surface `last_change` data properly** (related issue from test report):+- Check `get_context` handler for `last_change` with `date: null, days_ago: 0`+- Ensure `GitMetadata.last_commit_at` is populated even when blame fails++**Effort:** ~2-3 hours | **Risk:** Medium — timeout changes may slow init on large repos++---++### 2.5 — Populate `affected_files` for README-mined decisions++**Issue:** All README-sourced decisions have `affected_files: []`, making target-aware `get_why` non-functional.++**File:** `packages/core/src/repowise/core/analysis/decision_extractor.py` — lines 464-529++**Root cause:** `mine_readme_docs()` at lines 519-521 uses `_infer_modules_from_text()` for `affected_modules` but never sets `affected_files`. Unlike `scan_inline_markers()` (which calls `_get_neighbors()`) and `mine_git_archaeology()` (which uses `commit_files`), README mining has no file-level resolution.++**Fix:** After setting `affected_modules`, resolve module paths to actual files:+```python+# After line 521:+d.affected_modules = self._infer_modules_from_text(section_text)++# New: resolve modules to files+affected_files = set()+for mod in d.affected_modules:+ for node in self._graph.nodes():+ if str(node).startswith(mod + "/") or str(node) == mod:+ affected_files.add(str(node))+ if len(affected_files) >= 20:+ break+d.affected_files = list(affected_files)+```++**Effort:** ~1 hour | **Risk:** Medium — may produce noisy file lists if modules are broad++---++## Phase 3: Deeper Structural Improvements++These require more design consideration and testing.++---++### 3.1 — Meaningful confidence scores across tools++**Issue:** Flat confidence values: `1.0` in search, `0.6` in decisions, `0.7` in dead code. No differentiation.++**Current state by tool:**++| Tool | Source | Value | Location |+|------|--------|-------|----------|+| `search_codebase` | `Page.confidence` | Default `1.0`, linear decay over 30 days | `models.py:112` |+| `get_why` | `DecisionRecord.confidence` | Hardcoded per source type | `decision_extractor.py` |+| `get_dead_code` | Dead code analyzer | `1.0` / `0.7` / `0.4` by commit recency | `dead_code.py:259-265` |++**Fix approach:**++**A. Decisions:** Vary by source + evidence quality:+- `inline_marker` (code comments): 0.95 — developer explicitly wrote this+- `adr_file` (dedicated ADR docs): 0.90+- `git_archaeology` (commit messages): 0.70 — inferred, not explicit+- `readme_mining` (README text): 0.60 — weakest signal++Already partially implemented in `decision_extractor.py` — verify values are actually differentiated and flowing through.++**B. Dead code:** Add more signals to vary confidence:+```python+# Beyond just commit recency, factor in:+# - File age (older untouched files more likely dead)+# - Number of symbols (single-function files more likely dead)+# - Owner still active in repo (if owner left, higher chance dead)+```++**C. Search:** Already addressed in 1.5 — either remove the field or make it score-relative.++**Effort:** ~3-4 hours total | **Risk:** Medium — needs calibration++---++### 3.2 — Consistent response formats for `get_architecture_diagram`++**Issue:** Repo-scope returns markdown + embedded mermaid. Module-scope returns pure mermaid. Inconsistent.++**File:** `packages/server/src/repowise/server/mcp_server.py` — `get_architecture_diagram` handler++**Fix:** Standardize both to return the same structure:+```python+{+ "diagram_type": "flowchart",+ "mermaid_syntax": "...",+ "description": "...",+ "metadata": {+ "scope": "repo" | "module",+ "path": null | "packages/core",+ "node_count": 15,+ "edge_count": 23,+ }+}+```++For repo-scope, generate a mermaid diagram from the module-level graph rather than returning the pre-generated architecture page.++**Effort:** ~2 hours | **Risk:** Low-medium — repo-scope currently returns richer content (prose + diagram). Switching to pure diagram loses context. Consider returning both.++---++### 3.3 — `get_why` decision relevance: semantic filtering++**Issue:** Keyword scoring alone is too noisy. Words like "use" and "parser" match too broadly.++**Beyond the threshold fix in 2.2**, improve the actual scoring:++**A. Use the semantic search as primary ranker, not keyword:**+```python+# Current: keyword first, semantic second+# Better: semantic first, keyword to fill gaps++decision_results = await _decision_store.search(query, limit=10)+# Only fall back to keyword scoring if semantic search returns < 3 results+if len(decision_results) < 3:+ # keyword fallback...+```++**B. Require multi-word phrase matching, not just individual words:**+```python+# Instead of checking each word independently:+# "tree sitter" should match as a phrase, not "tree" and "sitter" separately+import re+bigrams = [f"{words[i]} {words[i+1]}" for i in range(len(words)-1)]+for bigram in bigrams:+ if bigram in text:+ score += weight * 2 # Phrase match worth more+```++**C. Negative signal: if decision text mentions the query topic 0 times but other topics 5+ times, it's irrelevant.**++**Effort:** ~3-4 hours | **Risk:** Medium — changes ranking behavior significantly, needs A/B comparison++---++### 3.4 — `change_magnitude` staleness in `get_risk`++**Issue:** `git_indexer.py` shows `lines_added_90d: 0` despite being committed this week.++**Root cause:** Git metadata is computed at `init`/`update` time. If the wiki hasn't been updated since the commits, the 90-day window is stale.++**Fix options:**+1. **Live git check:** On `get_risk` calls, optionally run a quick `git log --since=90.days` for the queried files to get fresh counts.+2. **Show data freshness:** Include `"data_as_of": "2026-03-20"` (last indexing time) so consumers know the data age.+3. **Periodic reindex:** Already exists via `update` command — document that `get_risk` data freshness depends on reindexing cadence.++**Effort:** ~2 hours for option 2 (quick), ~4 hours for option 1 (live) | **Risk:** Option 1 adds latency++---++## Fix Priority Matrix++| # | Fix | Phase | Effort | Impact | Dependencies |+|---|-----|-------|--------|--------|-------------|+| 1.1 | Short diagram labels | 1 | 15m | Low | None |+| 1.2 | Exclude test fixtures from entry points | 1 | 20m | Low-Med | Check GraphNode model |+| 1.3 | Framework files in dead code skip list | 1 | 10m | Low | None |+| 1.4 | Fixture dirs in dead code | 1 | 15m | Low | None |+| 1.5 | Fix/remove confidence_score in search | 1 | 20m | Med | None |+| 1.6 | Clip external nodes in diagrams | 1 | 30m | Low | None |+| 2.1 | `get_why` timeout wrapper | 2 | 1-2h | **High** | None |+| 2.2 | Decision relevance threshold | 2 | 1h | **High** | None |+| 2.3 | Search relevance threshold | 2 | 30m | Med | None |+| 2.4 | Ownership attribution gaps | 2 | 2-3h | **High** | git_indexer changes |+| 2.5 | Populate `affected_files` for README decisions | 2 | 1h | Med | decision_extractor |+| 3.1 | Meaningful confidence scores | 3 | 3-4h | Med | Multiple files |+| 3.2 | Consistent diagram response format | 3 | 2h | Low | None |+| 3.3 | Semantic decision filtering | 3 | 3-4h | Med | 2.2 first |+| 3.4 | Fresh change_magnitude data | 3 | 2-4h | Med | None |++---++## Recommended Execution Order++1. **Do Phase 1 all at once** — small, independent fixes across 4 files. ~2 hours total.+2. **Do 2.1 (timeouts) first in Phase 2** — this is the only reliability blocker.+3. **Do 2.2 + 2.3 (relevance thresholds)** — quick score gating.+4. **Do 2.4 (ownership)** — most impactful data quality fix, needs testing.+5. **Do 2.5 (affected_files)** — unlocks target-aware `get_why`.+6. **Phase 3 as time allows** — these are quality-of-life improvements.++---++## Files to Modify++| File | Fixes |+|------|-------|+| `packages/server/src/repowise/server/mcp_server.py` | 1.1, 1.2, 1.5, 1.6, 2.1, 2.2, 2.3 |+| `packages/core/src/repowise/core/analysis/dead_code.py` | 1.3, 1.4, 3.1 (dead code confidence) |+| `packages/core/src/repowise/core/ingestion/git_indexer.py` | 2.4 |+| `packages/core/src/repowise/core/analysis/decision_extractor.py` | 2.5, 3.1 (decision confidence) |diff --git a/docs/MCP_TOOLS_TEST_REPORT.md b/docs/MCP_TOOLS_TEST_REPORT.mdnew file mode 100644index 000000000..1d1fe2e21--- /dev/null+++ b/docs/MCP_TOOLS_TEST_REPORT.md@@ -0,0 +1,332 @@+# MCP Tools Test Report++**Date:** 2026-03-26+**Tested on:** repowise repo (self-hosted, 315 files, 52k+ LOC)+**Server transport:** stdio+**Client:** Claude Code (Opus 4.6)++---++## Executive Summary++All 8 MCP tools are functional. 6 of 8 return useful, accurate results. `get_why` has a relevance problem — it returns decisions unrelated to the query. `search_codebase` returns results for nonsense queries with no indication they're low-quality matches. No tool crashed, but `get_why` experienced hangs in 2 of 4 test runs (file-path mode and health dashboard mode).++---++## Tool-by-Tool Results++### 1. `get_overview`++**Status:** Working+**Response time:** Fast (~2s)++**What it returned:**+- Project summary with accurate LOC count (52k) and file count (315)+- Correct tech stack breakdown (Python 50.2%, TypeScript 32.7%)+- Entry points (CLI main, server app, test fixtures)+- Architecture description with module breakdown+- Mermaid diagram (CLI -> Core -> Server dependency graph)+- Git health: 285 indexed files, 71 hotspots, bus factor 0.8, churn trend increasing++**Quality assessment:**+- Summary is accurate and well-structured+- Correctly identifies the monorepo structure (core, server, cli, web)+- Mentions the circular dependency between crud/database/models/mcp_server — this is genuinely useful context+- Top churn modules list is accurate++**Issues:**+- Entry points include test fixtures (`go_pkg/main.go`, `rust_pkg/src/lib.rs`) — these aren't real entry points, they're test data. A developer following this advice would start in the wrong place.+- The `packages/web` module is listed as a top churn module but the architecture section barely mentions it. Mismatch between git signals and documentation depth.++**Improvement ideas:**+- Filter test fixtures from entry points. An entry point should be something a developer actually runs, not test data.+- Weight the architecture summary toward high-churn areas — if `packages/web` is churning heavily, the overview should say more about it.++---++### 2. `get_context`++**Status:** Working+**Response time:** Fast (~2s)++**Tests run:**+| Input | Result |+|-------|--------|+| Single file (`main.py`) | Returned docs, symbols, importers, last_change |+| Multi-file (`models.py` + `parser.py`) | Both returned correctly in one call |+| `include` filter (`docs`, `ownership`, `freshness`) | Correctly filtered response fields |+| Nonexistent file (`NonExistentFile.py`) | Clean error: `"Target not found: 'NonExistentFile.py'"` |++**Quality assessment:**+- Documentation quality is high — the `parser.py` docs accurately describe the tree-sitter architecture, language config system, and even how to add a new language+- Symbol extraction is thorough — `parser.py` returned 35 symbols with correct signatures+- `imported_by` lists are accurate and useful for understanding coupling+- Ownership data works (`models.py` shows RaghavChamadiya at 100%)+- Freshness status works (`fresh` / `not stale`)++**Issues:**+- `parser.py` shows `primary_owner: null`, `contributor_count: 0`, `bus_factor: 0` — but the file clearly has commit history. Likely a git indexing gap where some files don't get ownership attributed.+- `last_change` returned `date: null, author: null, days_ago: 0` for `main.py` — this should have real data.++**Improvement ideas:**+- Investigate why some files have null ownership despite having git history. This is a data quality issue that undermines the `get_risk` tool too (it showed `owner: unknown` for files that definitely have an owner).+- `last_change` with all nulls is confusing — either return the actual data or omit the field. A null date with `days_ago: 0` is misleading (implies "changed today").++---++### 3. `search_codebase`++**Status:** Working+**Response time:** Fast (~1s)++**Tests run:**+| Query | Results | Quality |+|-------|---------|---------|+| `"how does the MCP server work?"` | mcp_cmd.py, scc-38 circular dep, architecture diagram | Good — top result is exactly right |+| `"authentication and API keys"` (filtered to file_page) | providers.py, openai.py, deps.py | Good — relevant files about provider/API key management |+| `"xyznonexistent gibberish query"` | search.py, search_cmd.py, GitMetadata | Bad — returned results for nonsense with no low-confidence signal |++**Quality assessment:**+- Semantic search works well for real queries — results are relevant and properly ranked+- `page_type` filter works correctly+- Relevance scores are present and ordered correctly+- Snippets are useful for quick scanning++**Issues:**+- **No empty results for nonsense queries.** The gibberish query returned 3 results with relevance scores of 2.4–3.4. There's no threshold or indicator telling the consumer "these results are probably not what you're looking for." An AI agent would treat these as real answers.+- `confidence_score` is always `1.0` across every result in every query. This field appears to be hardcoded and provides no actual signal.++**Improvement ideas:**+- Add a minimum relevance threshold. If the top result scores below some baseline, return an empty result set or add a `low_confidence: true` flag.+- Make `confidence_score` meaningful or remove it. A field that's always 1.0 is noise.+- Consider returning a `"no_relevant_results": true` flag when the best match score is below threshold.++---++### 4. `get_risk`++**Status:** Working+**Response time:** Fast (~2s)++**Tests run:**+| Input | Key findings |+|-------|-------------|+| `mcp_server.py` | 99% hotspot, churn-heavy, increasing, 2 co-change partners, 2414 lines added in 90d |+| `ui.py` + `git_indexer.py` (multi-target) | ui.py: 5% stable; git_indexer: 12% high-coupling, 3 co-change partners |+| `nonexistent/file.py` | Clean fallback: 0% hotspot, "no git metadata available" |++**Quality assessment:**+- **This is the strongest tool.** The data it returns is genuinely not derivable from reading source code.+- Hotspot scores are well-calibrated — `mcp_server.py` at 99% makes sense given the heavy recent development.+- Co-change partner data is actionable: knowing that `git_indexer.py` always changes with `init_cmd.py` and `models.py` helps predict blast radius.+- `risk_type` classification (churn-heavy, high-coupling, stable) provides quick triage.+- `impact_surface` showing the top downstream files by PageRank is useful.+- Global hotspots list provides ambient awareness regardless of what you query.+- Error handling for nonexistent files is clean.++**Issues:**+- `ui.py` shows `primary_owner: "unknown"` with `owner_pct: 0.0` — same null ownership issue as `get_context`. For risk assessment, knowing who owns a file is critical.+- `change_magnitude` shows `lines_added_90d: 0` for `git_indexer.py` — but this file was modified recently (commit `f749ca9` from this week). The 90-day window calculation may be off, or git indexing didn't capture recent commits.++**Improvement ideas:**+- Fix the ownership attribution gap. This is the #1 data quality issue across multiple tools.+- Verify that `change_magnitude` windows align with actual git history. A file committed this week showing 0 lines added in 90 days is wrong.++---++### 5. `get_why`++**Status:** Partially working (reliability + relevance issues)+**Response time:** Variable — fast when it works, hangs in some modes++**Tests run:**+| Input | Result |+|-------|--------|+| No args (health dashboard) | **Hung — had to cancel** |+| File path (`crud.py`) | **Hung — had to cancel** |+| NL query: `"why is the persistence layer using SQLite?"` | Returned 2 decisions + 3 related docs |+| NL query: `"why does the parser use tree-sitter?"` | Returned 8 decisions + 3 related docs |++**Quality assessment (when it works):**+- The `related_documentation` section works well — the tree-sitter query correctly surfaced `parser.py` as the top result with a high relevance score (16.9).+- The concept is valuable — surfacing architectural decisions that govern a piece of code is something no other tool does.++**However, the decisions themselves have a serious relevance problem:**+- Asked "why does the parser use tree-sitter?" → got decisions about Jinja2 templates, SQLite, streaming protocol, API key resolution order, token estimation heuristics. **None of these are about tree-sitter or the parser.**+- Asked "why is the persistence layer using SQLite?" → got a decision about Gemini's agentic loop. Not relevant.+- All decisions show `confidence: 0.6` and `source: "readme_mining"` — suggests these are mined from docs/READMEs with no filtering by actual relevance to the query.+- All decisions have `affected_files: []` — without file associations, the system can't filter decisions by what actually governs the queried code.++**Issues:**+1. **Hangs in file-path mode and health dashboard mode.** 2 of 4 calls had to be cancelled by the user. This is a blocker for production use.+2. **Decision relevance is poor.** The decisions returned don't match the query. It appears to return all known decisions rather than filtering to relevant ones.+3. **No `affected_files` populated.** This makes target-aware mode (`get_why` with both query and targets) likely non-functional since there's nothing to match against.+4. **All decisions are `"proposed"` status with 0.6 confidence.** No differentiation between strong architectural decisions and speculative observations.++**Improvement ideas:**+- **P0: Fix the hangs.** The file-path and dashboard modes need to complete or timeout gracefully.+- **P0: Filter decisions by relevance.** If the query is about tree-sitter, don't return decisions about Jinja2. Use the semantic search scores to threshold.+- **P1: Populate `affected_files`.** Without this, the tool can't answer "what decisions govern this file?" — which is its core value proposition.+- **P2: Differentiate decision confidence.** A decision extracted from an explicit ADR should score higher than one mined from a README sentence.++---++### 6. `get_dependency_path`++**Status:** Working+**Response time:** Fast (~1s)++**Tests run:**+| Source | Target | Result |+|--------|--------|--------|+| `cli/main.py` | `persistence/crud.py` | Path found: main.py -> init_cmd.py -> crud.py (2 hops) |+| `cli/main.py` | `web/sidebar.tsx` | No direct path — returned visual context |++**Quality assessment:**+- Direct path finding works correctly — the 2-hop chain through `init_cmd.py` is accurate.+- **The "no path found" response is excellent.** Instead of just saying "no path," it returns:+ - Nearest common ancestors with distances+ - Community analysis (source in community 26, target in community 91)+ - Bridge suggestions with PageRank scores+ - Human-readable suggestion: "both nodes connect through reindex_cmd.py"+- This makes the tool useful even when there's no direct dependency — it helps understand architectural silos.++**Issues:**+- The bridge suggestion points to `reindex_cmd.py` as the connection between CLI and web — this seems unlikely to be useful as an architectural insight. The CLI and web packages are intentionally separate.+- `external:@/lib/utils/cn` appears as a bridge suggestion with a high PageRank. External/alias nodes in the graph could be confusing.++**Improvement ideas:**+- When source and target are in completely different packages (Python CLI vs TypeScript web), consider saying "these are separate packages with no intended dependency path" rather than suggesting bridges. Not every pair of files should be connected.+- Filter or label external/alias nodes in suggestions.++---++### 7. `get_dead_code`++**Status:** Working+**Response time:** Fast (~2s)++**Tests run:**+| Parameters | Results |+|------------|---------|+| `tier: "high"` | 0 findings (none at high confidence) |+| `group_by: "directory"` | 21 medium-confidence findings across 11 directories |++**Quality assessment:**+- Summary stats are useful: 128 total findings, 420 deletable lines, 15 safe to delete.+- `kind` breakdown shows categories: 122 unreachable files, 6 zombie packages.+- Directory rollup is actionable: `tests/fixtures` has 4 findings (180 lines), `packages/core` has 8 (170 lines).+- `safe_to_delete` flag is conservative — good for production use.+- Individual findings include file path, confidence, reason, line count.++**Issues:**+- Test fixtures (`tests/fixtures/sample_repo/go_pkg/calculator/calculator.go`) are flagged as dead code with `reason: "File has no importers"`. These are test data files — they're not supposed to have importers. Same for `conftest.py` which is auto-loaded by pytest.+- `alembic/env.py` is flagged as dead — it's loaded by the Alembic migration framework, not imported. Framework-loaded files need special handling.+- All findings are medium confidence (0.7) with identical reasons. No differentiation.++**Improvement ideas:**+- Exclude known framework files: `conftest.py` (pytest), `alembic/env.py` (alembic), `__main__.py`, etc. These are entry points loaded by tools, not dead code.+- Exclude test fixture directories — or at least add a `is_test_fixture: true` flag so consumers can filter.+- Vary confidence scores based on additional signals (age, ownership, last commit date) rather than a flat 0.7.++---++### 8. `get_architecture_diagram`++**Status:** Working+**Response time:** Fast (~2s)++**Tests run:**+| Scope | Parameters | Result |+|-------|------------|--------|+| `repo` | Default | Markdown architecture doc with embedded mermaid |+| `module` | `packages/core`, `show_heat: true` | Detailed flowchart with churn heat annotations |++**Quality assessment:**+- Repo-level returns a well-structured architecture document (not just a diagram) — includes component descriptions, key modules, and the SCC note.+- Module-level diagram correctly shows all files in `packages/core` with their import relationships.+- Churn heat annotations work: `models.py` and `mcp_server.py` marked `hot`, `rust_pkg/src/models.rs` marked `warm`, most others `cold`. Matches `get_risk` data.+- Mermaid syntax is valid and renderable.++**Issues:**+- Repo-level scope returns the pre-generated architecture page (markdown + embedded mermaid), not a standalone diagram. This is fine but inconsistent with the module-level scope which returns pure mermaid.+- Module-level diagram for `packages/core` includes `packages/server/src/repowise/server/mcp_server.py` and `tests/fixtures/sample_repo/rust_pkg/src/models.rs` — these are outside `packages/core`. The diagram leaks across module boundaries because it follows imports.+- Node IDs in mermaid are very long (`packages_core_src_repowise_core_persistence_models_py`) making the rendered diagram hard to read.++**Improvement ideas:**+- Use short labels in the diagram (e.g., `models.py` or `persistence/models.py`) while keeping full paths in tooltips or node metadata.+- For module-scope diagrams, consider clipping edges at the module boundary with an "external" node rather than including the full external file.+- Make repo-level and module-level return consistent formats.++---++## Cross-Cutting Issues++### 1. Ownership data gaps+Multiple tools return `null` or `"unknown"` for file ownership on files that definitely have git history. This affects `get_context`, `get_risk`, and `get_dead_code`. **Root cause likely in git indexer** — some files may timeout during indexing or the ownership attribution logic has gaps.++**Impact:** High. Ownership is a key signal for risk assessment, code review routing, and dead code cleanup prioritization.++### 2. `confidence_score` is meaningless+In `search_codebase`, every result has `confidence_score: 1.0`. In `get_why`, every decision has `confidence: 0.6`. In `get_dead_code`, every finding has `confidence: 0.7`. These flat values provide no signal for consumers to differentiate quality.++**Impact:** Medium. AI agents consuming these tools have no way to judge result quality, leading to hallucination amplification — the agent treats a bad match the same as a good one.++### 3. Test fixtures pollute results+Test fixtures appear as entry points (`get_overview`), dead code (`get_dead_code`), and in dependency graphs (`get_architecture_diagram`). For a developer using these tools, test data showing up in architecture overviews is confusing.++**Impact:** Low-medium. Mostly a noise issue, but for public repos with large test suites this could significantly pollute results.++### 4. Error handling is solid+Every tool handles nonexistent inputs gracefully — no crashes, clean error messages, fallback data where appropriate. `get_dependency_path` is particularly good, providing visual context even when no path exists.++---++## Reliability Summary++| Tool | Functional | Response Time | Data Quality | Reliability |+|------|-----------|---------------|-------------|-------------|+| `get_overview` | Yes | Fast | Good (entry point issue) | Stable |+| `get_context` | Yes | Fast | Good (ownership gaps) | Stable |+| `search_codebase` | Yes | Fast | Good (no empty results for garbage) | Stable |+| `get_risk` | Yes | Fast | Good (ownership gaps, stale magnitude) | Stable |+| `get_why` | Partial | Variable | Poor (irrelevant decisions) | **Unstable — hangs** |+| `get_dependency_path` | Yes | Fast | Good | Stable |+| `get_dead_code` | Yes | Fast | Okay (false positives on fixtures) | Stable |+| `get_architecture_diagram` | Yes | Fast | Good (label readability) | Stable |++---++## Priority Fixes++### P0 (Blocking for production)+1. **`get_why` hangs** — file-path mode and health dashboard mode hang indefinitely. Must either fix or add timeouts.+2. **`get_why` decision relevance** — decisions returned are unrelated to queries. The tool's core promise is broken without this.++### P1 (Important for quality)+3. **Ownership attribution gaps** — files with git history showing `null` owner across multiple tools.+4. **Search confidence scoring** — nonsense queries should return empty results or be flagged as low-confidence.+5. **`affected_files` in decisions** — empty across all decisions, preventing target-aware decision lookup.++### P2 (Polish)+6. **Exclude test fixtures** from entry points, dead code findings, and architecture diagrams.+7. **Exclude framework-loaded files** (conftest.py, alembic/env.py) from dead code.+8. **Shorter node labels** in architecture diagrams for readability.+9. **Consistent response formats** between repo-level and module-level diagrams.+10. **Meaningful confidence scores** — vary based on actual signal strength rather than flat values.++---++## For Public Repo Demos (React, FastAPI, etc.)++The tools that will demo well today:+- **`get_overview`** — instant architecture summary of a massive codebase+- **`get_risk`** — "what are the riskiest files in React?" is a compelling demo+- **`get_context`** — deep file documentation with ownership and import graphs+- **`get_dependency_path`** — "how does the scheduler connect to the reconciler?"+- **`get_architecture_diagram`** with heat — visual, immediately understandable++The tools that need fixes before public demos:+- **`get_why`** — hanging will kill a live demo. Decision relevance issues will confuse the audience.+- **`search_codebase`** — works, but a nonsense query returning results in a demo would raise eyebrows.+- **`get_dead_code`** — flagging React's test fixtures as dead code would undermine credibility. For a repo with thousands of test files, false positives would dominate.diff --git a/packages/core/src/repowise/core/analysis/dead_code.py b/packages/core/src/repowise/core/analysis/dead_code.pyindex 1486660cb..abf5c028a 100644--- a/packages/core/src/repowise/core/analysis/dead_code.py+++ b/packages/core/src/repowise/core/analysis/dead_code.py@@ -70,10 +70,24 @@ _NON_CODE_LANGUAGES: frozenset[str] = frozenset(# Patterns that should never be flagged as dead_NEVER_FLAG_PATTERNS = ("*__init__.py",+ "*__main__.py",+ "*conftest.py",+ "*alembic/env.py",+ "*manage.py",+ "*wsgi.py",+ "*asgi.py","*migrations*","*schema*","*seed*","*.d.ts",+ "*setup.py",+ "*setup.cfg",+ "*next.config.*",+ "*vite.config.*",+ "*tailwind.config.*",+ "*postcss.config.*",+ "*jest.config.*",+ "*vitest.config.*",)# Decorator patterns that indicate framework usage@@ -89,6 +103,28 @@ _DEFAULT_DYNAMIC_PATTERNS = ("on_*",)+# Path segments that indicate test fixture / sample data directories.+# Files under these directories are test data, not real code — they should+# never be flagged as dead even if nothing imports them.+_FIXTURE_PATH_SEGMENTS = (+ "fixture",+ "fixtures",+ "testdata",+ "test_data",+ "sample_repo",+ "mock_data",+ "test_assets",+)+++def _is_fixture_path(path: str) -> bool:+ """Return True if path is under a test fixture / sample data directory."""+ path_lower = path.lower().replace("\\", "/")+ for seg in _FIXTURE_PATH_SEGMENTS:+ if f"/{seg}/" in path_lower or path_lower.startswith(f"{seg}/"):+ return True+ return False+class DeadCodeAnalyzer:"""Detects unreachable files, unused exports, unused internals, and@@ -226,6 +262,8 @@ class DeadCodeAnalyzer:continueif node_data.get("is_test", False):continue+ if _is_fixture_path(str(node)):+ continueif self._should_never_flag(str(node), whitelist):continueif self._is_api_contract(node_data):@@ -307,6 +345,8 @@ class DeadCodeAnalyzer:continueif node_data.get("is_test", False):continue+ if _is_fixture_path(str(node)):+ continueif self._should_never_flag(str(node), whitelist):continuediff --git a/packages/server/src/repowise/server/mcp_server.py b/packages/server/src/repowise/server/mcp_server.pyindex fa2ba157f..d9baec060 100644--- a/packages/server/src/repowise/server/mcp_server.py+++ b/packages/server/src/repowise/server/mcp_server.py@@ -55,6 +55,18 @@ def _sanitize_mermaid_id(node_id: str) -> str:return re.sub(r"[^a-zA-Z0-9_]", "_", node_id)+def _short_label(node_id: str) -> str:+ """Shorten a full path to at most parent/filename for readable diagram labels.++ ``packages/core/src/repowise/core/persistence/models.py``+ → ``persistence/models.py``+ """+ parts = node_id.replace("\\", "/").split("/")+ if len(parts) >= 2:+ return "/".join(parts[-2:])+ return parts[-1]++def _resolve_embedder():"""Resolve embedder from REPOWISE_EMBEDDER env var or .repowise/config.yaml."""name = os.environ.get("REPOWISE_EMBEDDER", "").lower()@@ -474,14 +486,21 @@ async def get_overview(repo: str | None = None) -> dict:)module_pages = result.scalars().all()- # Get entry point files from graph nodes+ # Get entry point files from graph nodes (exclude tests & fixtures)result = await session.execute(select(GraphNode).where(GraphNode.repository_id == repository.id,GraphNode.is_entry_point == True, # noqa: E712+ GraphNode.is_test == False, # noqa: E712))- entry_nodes = result.scalars().all()+ entry_nodes = [+ n for n in result.scalars().all()+ if not any(+ seg in n.node_id.lower()+ for seg in ("fixture", "test_data", "testdata", "sample_repo")+ )+ ]# Phase 4: repo-wide git health summarygit_res = await session.execute(@@ -1234,39 +1253,39 @@ async def get_why(repository = await _get_repo(session, repo)health = await get_decision_health_summary(session, repository.id)- stale = health["stale_decisions"]- proposed = health["proposed_awaiting_review"]- ungoverned = health["ungoverned_hotspots"]-- return {- "mode": "health",- "summary": (- f"{health['summary'].get('active', 0)} active · "- f"{health['summary'].get('stale', 0)} stale · "- f"{len(proposed)} proposed · "- f"{len(ungoverned)} ungoverned hotspots"- ),- "counts": health["summary"],- "stale_decisions": [- {- "id": d.id,- "title": d.title,- "staleness_score": d.staleness_score,- "affected_files": json.loads(d.affected_files_json)[:5],- }- for d in stale[:10]- ],- "proposed_awaiting_review": [- {- "id": d.id,- "title": d.title,- "source": d.source,- "confidence": d.confidence,- }- for d in proposed[:10]- ],- "ungoverned_hotspots": ungoverned[:15],- }+ stale = health["stale_decisions"]+ proposed = health["proposed_awaiting_review"]+ ungoverned = health["ungoverned_hotspots"]++ return {+ "mode": "health",+ "summary": (+ f"{health['summary'].get('active', 0)} active · "+ f"{health['summary'].get('stale', 0)} stale · "+ f"{len(proposed)} proposed · "+ f"{len(ungoverned)} ungoverned hotspots"+ ),+ "counts": health["summary"],+ "stale_decisions": [+ {+ "id": d.id,+ "title": d.title,+ "staleness_score": d.staleness_score,+ "affected_files": json.loads(d.affected_files_json)[:5],+ }+ for d in stale[:10]+ ],+ "proposed_awaiting_review": [+ {+ "id": d.id,+ "title": d.title,+ "source": d.source,+ "confidence": d.confidence,+ }+ for d in proposed[:10]+ ],+ "ungoverned_hotspots": ungoverned[:15],+ }# --- Mode 2: Path → decisions, origin story, alignment ---if _is_path(query):@@ -1296,41 +1315,41 @@ async def get_why()all_git_meta = all_git_res.scalars().all()- governing = []- for d in all_decisions:- affected_files = json.loads(d.affected_files_json)- affected_modules = json.loads(d.affected_modules_json)- if query in affected_files or query in affected_modules:- governing.append({- "id": d.id,- "title": d.title,- "status": d.status,- "context": d.context,- "decision": d.decision,- "rationale": d.rationale,- "alternatives": json.loads(d.alternatives_json),- "consequences": json.loads(d.consequences_json),- "affected_files": affected_files,- "source": d.source,- "confidence": d.confidence,- "staleness_score": d.staleness_score,- })+ governing = []+ for d in all_decisions:+ affected_files = json.loads(d.affected_files_json)+ affected_modules = json.loads(d.affected_modules_json)+ if query in affected_files or query in affected_modules:+ governing.append({+ "id": d.id,+ "title": d.title,+ "status": d.status,+ "context": d.context,+ "decision": d.decision,+ "rationale": d.rationale,+ "alternatives": json.loads(d.alternatives_json),+ "consequences": json.loads(d.consequences_json),+ "affected_files": affected_files,+ "source": d.source,+ "confidence": d.confidence,+ "staleness_score": d.staleness_score,+ })- 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),- }+ 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),+ }- # --- 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,- )+ # --- 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+ return result_data# --- Mode 3: Natural language → target-aware search ---from repowise.core.persistence.crud import list_decisions as _list_decisions@@ -1447,29 +1466,29 @@ async def get_why()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+ 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_contextreturn result_data@@ -1603,56 +1622,60 @@ 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 asyncioimport 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"],+ def _sync_git_log() -> list[dict]:+ results: list[dict] = []+ try:+ 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 proc2.returncode == 0:- seen = {r["sha"] for r in results}- for line in proc2.stdout.strip().splitlines():+ if proc.returncode == 0:+ for line in proc.stdout.strip().splitlines():parts = line.split("\t", 3)- if len(parts) == 4 and parts[0][:12] not in seen:- seen.add(parts[0][:12])+ if len(parts) == 4:results.append({"sha": parts[0][:12],"author": parts[1],"date": parts[2][:10],"message": parts[3],- "source": "git_log_grep",+ "source": "git_log_follow",})- except (subprocess.TimeoutExpired, FileNotFoundError, OSError):- pass # Git not available or repo not accessible- return results[:20]+ 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+ return results[:20]++ try:+ return await asyncio.wait_for(asyncio.to_thread(_sync_git_log), timeout=15)+ except asyncio.TimeoutError:+ return []# ---------------------------------------------------------------------------@@ -1704,26 +1727,25 @@ async def search_codebase("page_type": r.page_type,"snippet": r.snippet,"relevance_score": r.score,- "confidence_score": None,})output = output[:limit]- # Batch-lookup actual page confidence scores from DB + git freshness boost+ # Batch-lookup page target paths for git freshness boostif output:page_ids = [item["page_id"] for item in output]async with get_session(_session_factory) as session:res = await session.execute(- select(Page.id, Page.confidence, Page.target_path).where(+ select(Page.id, Page.target_path).where(Page.id.in_(page_ids)))- page_info = {row[0]: (row[1], row[2]) for row in res.all()}+ page_info = {row[0]: row[1] for row in res.all()}# Build git freshness map for result file pathstarget_paths = [- info[1] for info in page_info.values() if info[1]+ tp for tp in page_info.values() if tp]git_map: dict[str, GitMetadata] = {}if target_paths:@@ -1735,10 +1757,8 @@ async def search_codebase(git_map = {g.file_path: g for g in git_res.scalars().all()}for item in output:- info = page_info.get(item["page_id"])- item["confidence_score"] = info[0] if info else None# Freshness boost: recently-active files rank higher- target_path = info[1] if info else None+ target_path = page_info.get(item["page_id"])gm = git_map.get(target_path) if target_path else Noneif gm and item.get("relevance_score"):c30 = gm.commit_count_30d or 0@@ -1756,6 +1776,17 @@ async def search_codebase(# Re-sort by boosted relevanceoutput.sort(key=lambda x: x.get("relevance_score", 0), reverse=True)+ # Derive confidence_score from relative position in the result set.+ # The top result gets 1.0; others are scaled proportionally by their+ # relevance score relative to the best match.+ if output:+ max_score = max(+ (item.get("relevance_score") or 0) for item in output+ )+ for item in output:+ raw = item.get("relevance_score") or 0+ item["confidence_score"] = round(raw / max_score, 2) if max_score > 0 else 0.0+return {"results": output}@@ -2336,30 +2367,79 @@ async def get_architecture_diagram(seen_nodes: set[str] = set()node_classes: dict[str, str] = {} # mermaid_id → class+ # For module-scoped diagrams, clip cross-boundary nodes to a single+ # "[external]" stub so the diagram stays focused on the target module.+ _EXTERNAL_ID = "external_deps"+ _external_added = False+for e in relevant_edges[:50]: # Limit to 50 edges for readability- src = _sanitize_mermaid_id(e.source_node_id)- tgt = _sanitize_mermaid_id(e.target_node_id)+ src_id = e.source_node_id+ tgt_id = e.target_node_id++ # Clip nodes outside the module boundary+ src_external = bool(filter_prefix and not src_id.startswith(filter_prefix))+ tgt_external = bool(filter_prefix and not tgt_id.startswith(filter_prefix))++ # Skip edges where both ends are external+ if src_external and tgt_external:+ continue++ if src_external:+ src = _EXTERNAL_ID+ src_label = "external"+ else:+ src = _sanitize_mermaid_id(src_id)+ src_label = _short_label(src_id)++ if tgt_external:+ tgt = _EXTERNAL_ID+ tgt_label = "external"+ else:+ tgt = _sanitize_mermaid_id(tgt_id)+ tgt_label = _short_label(tgt_id)++ # Skip self-loops created by clipping+ if src == tgt:+ continue+if src not in seen_nodes:- lines.append(f' {src}["{e.source_node_id}"]')+ if src == _EXTERNAL_ID:+ if not _external_added:+ lines.append(f' {_EXTERNAL_ID}[/"external"/]')+ _external_added = True+ node_classes[_EXTERNAL_ID] = "ext"+ else:+ lines.append(f' {src}["{src_label}"]')+ if show_heat:+ pct = churn_map.get(src_id, 0.0)+ node_classes[src] = "hot" if pct >= 0.75 else ("warm" if pct >= 0.4 else "cold")seen_nodes.add(src)- if show_heat:- pct = churn_map.get(e.source_node_id, 0.0)- node_classes[src] = "hot" if pct >= 0.75 else ("warm" if pct >= 0.4 else "cold")+if tgt not in seen_nodes:- lines.append(f' {tgt}["{e.target_node_id}"]')+ if tgt == _EXTERNAL_ID:+ if not _external_added:+ lines.append(f' {_EXTERNAL_ID}[/"external"/]')+ _external_added = True+ node_classes[_EXTERNAL_ID] = "ext"+ else:+ lines.append(f' {tgt}["{tgt_label}"]')+ if show_heat:+ pct = churn_map.get(tgt_id, 0.0)+ node_classes[tgt] = "hot" if pct >= 0.75 else ("warm" if pct >= 0.4 else "cold")seen_nodes.add(tgt)- if show_heat:- pct = churn_map.get(e.target_node_id, 0.0)- node_classes[tgt] = "hot" if pct >= 0.75 else ("warm" if pct >= 0.4 else "cold")+lines.append(f" {src} --> {tgt}")- # Apply heat classes- if show_heat and node_classes:+ # Apply heat + external classes+ if node_classes:for nid, cls in node_classes.items():lines.append(f" class {nid} {cls}")- lines.append(" classDef hot fill:#ff6b6b,color:#000")- lines.append(" classDef warm fill:#ffd93d,color:#000")- lines.append(" classDef cold fill:#6bcb77,color:#000")+ if show_heat:+ lines.append(" classDef hot fill:#ff6b6b,color:#000")+ lines.append(" classDef warm fill:#ffd93d,color:#000")+ lines.append(" classDef cold fill:#6bcb77,color:#000")+ if _external_added:+ lines.append(" classDef ext fill:#ccc,stroke-dasharray:5 5,color:#666")mermaid = "\n".join(lines) if len(lines) > 1 else "graph TD\n A[No graph data available]"