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
feat(mcp): hybrid symbol and path search in search_codebase (#484) (#558)
Raghav Chamadiya36a9103476f3
diff --git a/docs/MCP_TOOLS.md b/docs/MCP_TOOLS.mdindex 219e3de1d..f6a45034c 100644--- a/docs/MCP_TOOLS.md+++ b/docs/MCP_TOOLS.md@@ -22,7 +22,7 @@ repowise mcp --transport sse --port 7338 # legacy SSE transport| `get_answer` | One-call RAG Q&A | First call on any code question || `get_context` | Rich context for targets | Before reading or modifying code || `get_symbol` | Raw source bytes for one symbol | When you need one function/class body |-| `search_codebase` | Semantic search | Discovering code by topic |+| `search_codebase` | Hybrid symbol / path / concept search | Finding a symbol or file, or discovering code by topic || `get_risk` | Modification risk | Before changing hotspot files || `get_why` | Architectural decisions | Before structural changes || `get_dead_code` | Unreachable code | Cleanup tasks |@@ -218,25 +218,52 @@ get_symbol(symbol_id="repowise#a1b2c3d4e5f6", query="FAILED")## `search_codebase`-Semantic search over the full wiki. Natural language queries.+Hybrid code search over RepoWise's indexes. A single tool that, depending on+the shape of the query, searches the indexed **symbols**, **file paths**, or+the **wiki** — instead of forcing a fallback to Grep for identifiers.**Parameters:**| Parameter | Type | Required | Description ||-----------|------|----------|-------------|-| `query` | string | Yes | Natural language search query |+| `query` | string | Yes | Identifier, path, or natural-language query |+| `limit` | int | No | Max results (default 5) |+| `mode` | string | No | `auto` (default) \| `concept` \| `symbol` \| `path` \| `hybrid` |+| `kind` | string | No | `implementation` \| `test` \| `config` \| `doc` |+| `symbol_kind` | string | No | Restrict symbol hits by kind (`function`, `class`, `method`, …) |+| `page_type` | string | No | `file_page` \| `module_page` \| `symbol_spotlight` (concept mode) || `repo` | string | No | *(workspace only)* Target repo alias, or `"all"` to search across workspace |-**Returns:** Ranked wiki pages with relevance scores, snippets, and file paths.+**Modes:**-**When to use:** When `get_answer` returned low confidence and you need to discover candidate pages by topic. Also useful for broad exploration ("how do we handle retries?", "payment processing flow").+- **`auto`** (default) routes by query shape:+ - an **identifier** (`GitIndexer`, `index_repo`) → searches indexed symbols;+ - a **path** (`core/ingestion/indexer.py`) → searches file pages;+ - **prose** ("how do we handle retries?") → wiki-semantic search;+ - mixed prose + identifier → **hybrid** (symbol hits first, then concept pages).+- **`concept`** forces the original wiki-semantic behavior.+- **`symbol`** / **`path`** force the structural search.-In workspace mode, searches across all repos and merges results.+**Returns:**-**Example call:**+- *Symbol hits* — `{type: "symbol", symbol_id, name, kind, file, start_line, end_line, signature, next: "get_symbol"}`. Ranked by exact-name/qualified-name match, query-token coverage, then graph centrality (PageRank / betweenness / entry-point); non-test before test unless `kind="test"`.+- *File hits* — `{type: "file", page_id, file, title, next: "get_context"}`.+- *Concept hits* — ranked wiki pages with `relevance_score`, `snippet`, `target_path`, and a `search_method` (`embedding` vs `bm25` fallback).++Tombstoned and `exclude_patterns`-excluded results are filtered. In workspace+mode, structural and concept searches both federate across repos and merge.++**When to use:** Locating a function/class/method by name, resolving a+path-shaped query, or discovering pages by topic — the symbol/file shapes pipe+directly into `get_symbol` / `get_context`.++**Example calls:**```-search_codebase(query="rate limit OR throttle OR retry")+search_codebase(query="GitIndexer index_repo") # → symbol hits+search_codebase(query="core/ingestion/indexer.py") # → file hits+search_codebase(query="rate limit OR throttle OR retry") # → wiki pages+search_codebase(query="login", mode="symbol", symbol_kind="method")```---diff --git a/packages/core/src/repowise/core/generation/templates/claude_md.j2 b/packages/core/src/repowise/core/generation/templates/claude_md.j2index b40c01c7b..a86281a92 100644--- a/packages/core/src/repowise/core/generation/templates/claude_md.j2+++ b/packages/core/src/repowise/core/generation/templates/claude_md.j2@@ -116,7 +116,7 @@ This repo has the Repowise MCP server configured. The tools below answer questio| `get_answer(question)` | Synthesised answer with citations and a content-grounded `confidence`. First call for "how does X work" / "where is Y" / "why is Z". Value questions may return `grounding: "extracted"` — the verbatim source line, no synthesis involved. On low confidence returns `best_guesses` with one-line justifications. || `get_context(targets=[...])` | Triage card for files/modules/symbols — title, summary, signatures, `hotspot` bit, `decision_records` titles, `symbol_id`s. File targets auto-upgrade to a `verified` skeleton (every signature, ~37% of a full Read). `include=["callers"]` works on file targets too (import + call rollup). || `get_symbol(...)` | Source bytes with live-verified bounds. Three forms: `"path.py::Name"` (indexed symbol), `"path.py:140-180"` (live range read, ≤200 lines), `"repowise#<hex>"` (omission ref). Index misses return `fallback_lines` from a live grep instead of a dead end. |-| `search_codebase(query, kind?)` | Find pages by concept when you don't know the file. Results carry `search_method` (`embedding` vs `bm25` fallback). Decision records rank below file pages unless the query is why-shaped. Identifier-bearing queries get a `grep_hint` — prefer Grep for those tokens. |+| `search_codebase(query, mode?, kind?, symbol_kind?)` | Hybrid code search. `mode="auto"` (default) routes by query shape: an identifier → indexed symbol hits (`symbol_id`/`file`/line bounds — pipe into `get_symbol`), a path → file pages (pipe into `get_context`), prose → wiki-semantic search, mixed → hybrid (symbols first). Force a branch with `mode=symbol\|path\|concept\|hybrid`. Concept hits carry `search_method` (`embedding` vs `bm25` fallback); decision records rank below file pages unless the query is why-shaped. || `get_why(query, targets?)` | Architectural decision archaeology — *why* the code is shaped this way. Call before refactors or pattern divergences. Falls back to git archaeology when no ADRs exist for a file. || `get_risk(targets, changed_files?)` | What history says about touching these files: churn, owners, blast radius. Pass `changed_files` for PR mode → returns a `directive` (`will_break`, `missing_cochanges`, `missing_tests`). || `get_dead_code(...)` | Tiered unreachable / unused-export / zombie-package findings. Run before a cleanup sprint, not before a targeted fix. |diff --git a/packages/core/src/repowise/core/generation/templates/workspace_claude_md.j2 b/packages/core/src/repowise/core/generation/templates/workspace_claude_md.j2index ecf9bf68a..2239abd0a 100644--- a/packages/core/src/repowise/core/generation/templates/workspace_claude_md.j2+++ b/packages/core/src/repowise/core/generation/templates/workspace_claude_md.j2@@ -62,7 +62,7 @@ These tools work across all repos in this workspace. Pass `repo="alias"` to scop| `get_answer(question)` | Synthesised answer with verified citations and a calibrated `retrieval_quality`. First call for "how does X work" / "why is Y like this". On low confidence returns `best_guesses` with one-line justifications. || `get_context(targets=[...])` | Triage card for files/modules/symbols — title, summary, signatures, `hotspot` bit, `decision_records` titles, and `symbol_id`s to pipe into `get_symbol`. Use `include=[...]` to widen. NOT for source bytes. || `get_symbol("path/to/file.py::Name")` | Raw source bytes for one indexed symbol with exact line bounds. Cheaper than `Read` + offset math. |-| `search_codebase(query, kind?)` | Find pages by concept when you don't know the file. Each result tags its `search_method` (`embedding` vs `bm25`). For exact identifiers use Grep. |+| `search_codebase(query, mode?, kind?, symbol_kind?)` | Hybrid code search. `mode="auto"` routes by query shape: identifier → indexed symbol hits (pipe `symbol_id` into `get_symbol`), path → file pages (`get_context`), prose → semantic search. Force with `mode=symbol\|path\|concept\|hybrid`. Concept hits tag `search_method` (`embedding` vs `bm25`). || `get_why(query, targets?)` | Architectural decision archaeology — *why* the code is shaped this way. Call before refactors. Falls back to git archaeology when no ADRs exist. || `get_risk(targets, changed_files?)` | What history says about touching these files. Pass `changed_files` for PR mode → returns a `directive` (`will_break`, `missing_cochanges`, `missing_tests`) plus cross-repo blast radius. || `get_dead_code(...)` | Tiered unreachable / unused-export / zombie-package findings; cross-repo consumer detection lowers confidence on shared exports. |diff --git a/packages/server/README.md b/packages/server/README.mdindex cfcaccab9..552f58936 100644--- a/packages/server/README.md+++ b/packages/server/README.md@@ -246,7 +246,7 @@ repowise mcp --transport sse # legacy SSE transport on port 7338| `get_context(targets)` | Docs, ownership, history, decisions, freshness for files/modules/symbols | When you need to understand specific code before reading or modifying it || `get_risk(targets)` | Hotspot score, dependents, co-change partners, risk summary | Before modifying files — assess what could break || `get_why(query?)` | Architectural decisions, rationale, constraints | Before making architectural changes — understand existing intent |-| `search_codebase(query)` | Semantic search over full wiki | When you don't know where something lives |+| `search_codebase(query, mode?)` | Hybrid symbol / path / concept search (auto-routes by query shape) | When locating a symbol, a file, or code by topic || `get_dependency_path(from, to)` | Connection path between two files/modules | When you need to understand how two things are connected || `get_dead_code` | Unused/unreachable code sorted by cleanup impact | Before cleanup tasks || `get_answer(question)` | One-call RAG with confidence gating and caching | First call on any code question |diff --git a/packages/server/src/repowise/server/chat_tools.py b/packages/server/src/repowise/server/chat_tools.pyindex 2580c5105..ae8947f1b 100644--- a/packages/server/src/repowise/server/chat_tools.py+++ b/packages/server/src/repowise/server/chat_tools.py@@ -192,12 +192,19 @@ def _build_registry() -> dict[str, ToolDef]:search_codebase,)+ async def _search_concept(query: str, **kwargs):+ # Chat surfaces wiki documentation pages (see the schema/artifact_type+ # below), so pin the concept branch — the symbol/path modes return+ # symbol/file shapes the chat artifact renderer doesn't expect.+ kwargs["mode"] = "concept"+ return await search_codebase(query, **kwargs)+func_map: dict[str, Callable] = {"get_overview": get_overview,"get_context": get_context,"get_risk": get_risk,"get_why": get_why,- "search_codebase": search_codebase,+ "search_codebase": _search_concept,"get_dead_code": get_dead_code,}diff --git a/packages/server/src/repowise/server/mcp_server/tool_overview.py b/packages/server/src/repowise/server/mcp_server/tool_overview.pyindex c848c82ef..4a4af391d 100644--- a/packages/server/src/repowise/server/mcp_server/tool_overview.py+++ b/packages/server/src/repowise/server/mcp_server/tool_overview.py@@ -772,7 +772,9 @@ async def get_overview(repo: str | None = None) -> dict:"get_context hotspot: true → get_risk before editing","get_context decision_records → get_why(targets=[...]) for rationale","PR review → get_risk(targets, changed_files) and read directive first",- "search_codebase grep_hint present → prefer Grep for those identifiers",+ "search_codebase(query) auto-routes: identifier → symbol hits "+ "(pipe symbol_id into get_symbol), path → files (get_context), "+ "prose → wiki search. Force with mode=symbol|path|concept|hybrid.",],"reread_triggers": "Only re-read source on bounds: approximate, ""stale_warning in _meta, or search_method: bm25.",diff --git a/packages/server/src/repowise/server/mcp_server/tool_search.py b/packages/server/src/repowise/server/mcp_server/tool_search.pyindex 04f4f5305..e0bbf043c 100644--- a/packages/server/src/repowise/server/mcp_server/tool_search.py+++ b/packages/server/src/repowise/server/mcp_server/tool_search.py@@ -13,16 +13,20 @@ from repowise.core.persistence.models import (GitMetadata,Page,)-from repowise.server.mcp_server import _state+from repowise.core.registry import mcp_tool_registry as mcpfrom repowise.server.mcp_server._helpers import (_get_exclude_spec,_get_repo,+ _is_path,_resolve_all_contexts,_resolve_repo_context,filter_dicts_by_key,)from repowise.server.mcp_server._meta import build_meta as _build_meta-from repowise.core.registry import mcp_tool_registry as mcp+from repowise.server.mcp_server.tool_search_symbols import (+ search_paths_single,+ search_symbols_single,+)# Minimum relevance score below which results are dropped. Prevents# returning semantically unrelated pages when the corpus has no real match.@@ -425,6 +429,116 @@ def _grep_hint_for(query: str) -> str | None:return None+_VALID_MODES = {"auto", "concept", "symbol", "path", "hybrid"}+++def _resolve_mode(query: str, mode: str | None) -> str:+ """Resolve ``mode="auto"`` to a concrete branch from the query shape.++ Explicit modes pass through. ``auto`` routes path-shaped queries to path+ search, single identifier-shaped tokens to symbol search, and queries that+ merely *carry* an identifier inside natural language to hybrid; everything+ else stays concept (the original wiki-semantic path). The routing reuses+ the exact heuristics that previously only emitted a grep_hint.+ """+ m = (mode or "auto").lower()+ if m not in _VALID_MODES:+ m = "auto"+ if m != "auto":+ return m+ if _is_path(query):+ return "path"+ if _looks_like_exact_token(query):+ return "symbol"+ if _embedded_identifiers(query):+ return "hybrid"+ return "concept"+++async def _contexts_for(repo: str | None) -> list:+ """The repo contexts a structured search runs over (one, or all in 'all')."""+ if repo == "all":+ return await _resolve_all_contexts()+ return [await _resolve_repo_context(repo)]+++def _tag_repo(items: list[dict], ctx, multi: bool) -> None:+ if multi:+ for item in items:+ item["repo"] = ctx.alias+++async def _structured_search(+ query: str,+ limit: int,+ page_type: str | None,+ kind: str | None,+ symbol_kind: str | None,+ repo: str | None,+ mode: str,+ grep_hint: str | None,+) -> dict:+ """Run symbol / path / hybrid search and shape the response.++ Honours ``repo="all"`` (federates across contexts, then re-ranks by score),+ per-repo ``exclude_patterns`` and tombstones (enforced inside the+ single-repo helpers). The grep_hint is attached only as a fallback — when+ the structural index produced nothing, the agent still has a path forward.+ """+ contexts = await _contexts_for(repo)+ multi = len(contexts) > 1++ symbols: list[dict] = []+ files: list[dict] = []+ concepts: list[dict] = []++ for ctx in contexts:+ if mode in ("symbol", "hybrid"):+ s = await search_symbols_single(ctx, query, limit, symbol_kind=symbol_kind, kind=kind)+ _tag_repo(s, ctx, multi)+ symbols.extend(s)+ if mode == "path":+ f = await search_paths_single(ctx, query, limit)+ _tag_repo(f, ctx, multi)+ files.extend(f)+ if mode == "hybrid":+ c, method = await _search_single_repo(ctx, query, limit, page_type, kind)+ for item in c:+ item.setdefault("search_method", method)+ item["type"] = "page"+ _tag_repo(c, ctx, multi)+ concepts.extend(c)++ symbols.sort(key=lambda x: -(x.get("score") or 0.0))+ files.sort(key=lambda x: -(x.get("score") or 0.0))++ if mode == "symbol":+ results = symbols[:limit]+ elif mode == "path":+ results = files[:limit]+ else: # hybrid — symbol matches first, then concept pages for new files+ sym_files = {s.get("file") for s in symbols}+ concepts = [c for c in concepts if c.get("target_path") not in sym_files]+ # Federation appends per-repo concept lists in repo order — re-rank by+ # relevance so a strong page in repo B isn't buried under repo A's weak+ # ones. (Single-repo: already sorted upstream; this is a no-op.)+ concepts.sort(key=lambda x: -(x.get("relevance_score") or 0.0))+ # Reserve up to half the window for concept pages so hybrid stays+ # hybrid: a flood of symbol matches must not truncate every page out.+ reserved = min(len(concepts), limit // 2)+ results = (symbols[: max(1, limit - reserved)] + concepts)[:limit]++ repository = None+ if not multi:+ async with get_session(contexts[0].session_factory) as session:+ repository = await _get_repo(session)++ response: dict = {"results": results, "mode": mode, "_meta": _build_meta(repository=repository)}+ if grep_hint and not results:+ response["grep_hint"] = grep_hint+ return response++@mcp.tool()async def search_codebase(query: str,@@ -432,23 +546,36 @@ async def search_codebase(page_type: str | None = None,kind: str | None = None,repo: str | None = None,+ mode: str = "auto",+ symbol_kind: str | None = None,) -> dict:- """Find pages by concept — semantic search across the wiki.+ """Find code by concept, symbol, or path — hybrid codebase search.- For conceptual queries ("rate limiting", "where do we handle webhooks")- when you don't know the file. For exact identifiers use Grep —- identifier-bearing queries get a grep_hint. Results carry search_method- ("embedding", or "bm25" fallback: verify those). Decision records rank- below file pages unless the query is why-shaped.+ mode="auto" (default) routes the query: identifier-shaped queries search+ the indexed symbols (returns symbol_id/file/line bounds — pipe into+ get_symbol), path-shaped queries resolve files (pipe into get_context),+ and conceptual queries ("rate limiting", "where do we handle webhooks")+ run wiki-semantic search. Mixed natural-language + identifier queries run+ hybrid (symbol hits first, then concept pages). Concept results carry+ search_method ("embedding" or "bm25" fallback: verify those); decision+ records rank below file pages unless the query is why-shaped.Args:- query: natural-language query.+ query: identifier, path, or natural-language query.limit: max results (default 5).- page_type: file_page | module_page | symbol_spotlight.- kind: implementation | test | config | doc.+ page_type: file_page | module_page | symbol_spotlight (concept only).+ kind: implementation | test | config | doc (concept/symbol modes).repo: alias, or "all" for workspace-wide.+ mode: auto | concept | symbol | path | hybrid.+ symbol_kind: filter symbol hits by kind (function|class|method|...)."""grep_hint = _grep_hint_for(query)+ resolved_mode = _resolve_mode(query, mode)++ if resolved_mode in ("symbol", "path", "hybrid"):+ return await _structured_search(+ query, limit, page_type, kind, symbol_kind, repo, resolved_mode, grep_hint+ )if repo == "all":# kind is filtered per-repo inside _search_single_repo, before eachdiff --git a/packages/server/src/repowise/server/mcp_server/tool_search_symbols.py b/packages/server/src/repowise/server/mcp_server/tool_search_symbols.pynew file mode 100644index 000000000..d0351640a--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_search_symbols.py@@ -0,0 +1,304 @@+"""Symbol and path search backing ``search_codebase`` modes (issue #484).++Where the concept path (in :mod:`tool_search`) searches the wiki vector store,+this module searches RepoWise's own persisted structural index — ``WikiSymbol``+for the canonical symbol rows and ``GraphNode`` for the ranking signals+(pagerank, betweenness, entry-point, test status). Identifier- and path-shaped+queries that used to bottom out in a ``grep_hint`` now resolve to the actual+indexed symbol/file, and each result carries the ``symbol_id``/``file``/line+bounds plus a ``next`` pointer (``get_symbol`` / ``get_context``) so the agent+can pipe straight into byte-level retrieval.++No new index: every field served here was already persisted at ingest time.+``WikiSymbol`` is treated as canonical (it is what ``get_symbol`` resolves+against, so a symbol surfaced here is always retrievable); ``GraphNode`` is a+left-join used only for ranking and degrades gracefully when a symbol has no+graph node.+"""++from __future__ import annotations++import re+from typing import Any++from sqlalchemy import case, func, or_, select++from repowise.core.persistence.database import get_session+from repowise.core.persistence.models import GraphNode, Page, WikiSymbol+from repowise.server.mcp_server._helpers import (+ _get_exclude_spec,+ _get_repo,+ is_excluded,+)++# Path tokens that mark a symbol's file as a test (mirrors tool_search's set).+_TEST_PATH_TOKENS = ("/test/", "/tests/", "/__tests__/", "test_", "_test.", ".spec.", ".test.")++# Candidate ceiling: scoring/sorting happens in Python, so the SQL pre-filter+# caps how many rows we pull. Generous enough that the true top-`limit` is+# always inside the window, bounded so a pathological LIKE can't load the table.+_MAX_CANDIDATES = 400+++def _is_test_path(path: str | None) -> bool:+ tp = (path or "").lower()+ return any(tok in tp for tok in _TEST_PATH_TOKENS)+++def _tokens(text: str | None) -> set[str]:+ """Lowercase token set, splitting on non-alnum AND camelCase humps.++ ``GitIndexer.index_repo`` -> {git, indexer, index, repo}. Tokens shorter+ than two chars are dropped (they match too broadly to be useful signal).+ """+ if not text:+ return set()+ out: set[str] = set()+ for part in re.split(r"[^A-Za-z0-9]+", text):+ if not part:+ continue+ # Insert boundaries at camelCase humps (fooBar, HTTPServer).+ camel = re.sub(r"(?<=[a-z0-9])(?=[A-Z])", " ", part)+ camel = re.sub(r"(?<=[A-Z])(?=[A-Z][a-z])", " ", camel)+ for tok in camel.split():+ t = tok.lower()+ if len(t) >= 2:+ out.add(t)+ return out+++def _qual_norm(name: str | None) -> str:+ """Normalize a qualified name's separators (``::``/``/`` -> ``.``), lowered."""+ s = name or ""+ for sep in ("::", "/"):+ s = s.replace(sep, ".")+ return s.lower()+++def _score_symbol(+ row: WikiSymbol, gnode: GraphNode | None, qtokens: set[str], qnorm: str+) -> float:+ """Rank a candidate symbol against the query (higher = better).++ Tiers, in priority order: exact name / qualified-name match, the query's+ leaf token naming the symbol, query-token coverage, substring fallback,+ then graph-centrality and entry-point boosts. Tests are penalised so a+ non-test definition ranks above its test unless the caller asked for tests.+ """+ name = (row.name or "").lower()+ qn = _qual_norm(row.qualified_name)+ stoks = _tokens(row.name) | _tokens(row.qualified_name)++ score = 0.0+ # Exact match on the bare name or the (separator-normalised) qualified name.+ if qnorm and qnorm in (name, qn):+ score += 100.0+ # The query explicitly names the leaf identifier (e.g. "...index_repo").+ if name and name in qtokens:+ score += 40.0+ # Token coverage: how much of the query the symbol's tokens account for.+ if qtokens:+ matched = qtokens & stoks+ score += 30.0 * (len(matched) / len(qtokens))+ if qtokens <= stoks: # every query token is present+ score += 20.0+ # Substring fallback for partial identifiers ("index_re").+ if qnorm and (qnorm in name or qnorm in qn):+ score += 10.0++ # Graph signals — bounded so a high-pagerank file can't outrank a real+ # name match. pagerank/betweenness are small floats; cap their reach.+ if gnode is not None:+ score += min(gnode.pagerank or 0.0, 0.1) * 50.0+ score += min(gnode.betweenness or 0.0, 0.1) * 20.0+ if gnode.is_entry_point:+ score += 3.0++ if (gnode is not None and gnode.is_test) or _is_test_path(row.file_path):+ score -= 5.0+ return score+++def _symbol_kind_for_request_kind(kind: str | None, is_test: bool) -> bool:+ """Whether a symbol passes the coarse ``kind`` filter (implementation/test).++ Symbols only ever come from code files, so ``config``/``doc`` never match a+ symbol — those kinds filter symbol search to empty by design (the caller+ wanted a manifest or a doc page, not a symbol).+ """+ if not kind:+ return True+ if kind == "test":+ return is_test+ if kind == "implementation":+ return not is_test+ return False # config / doc: symbols don't qualify+++def _candidate_filter(qtokens: set[str], qnorm: str):+ """Build the SQL OR-clause that pre-selects scoring candidates.++ Exact name/qualified-name equality plus a LIKE per query token (length+ >= 2). Keeps the Python-side scoring window small without missing the+ real top hits.+ """+ clauses = []+ if qnorm:+ # Case-insensitive equality — WikiSymbol.name keeps original casing and+ # SQLite "=" is case-sensitive, so a lowercased qnorm would never match.+ clauses.append(func.lower(WikiSymbol.name) == qnorm)+ clauses.append(WikiSymbol.qualified_name.ilike(f"%{qnorm}%"))+ for tok in qtokens:+ clauses.append(WikiSymbol.name.ilike(f"%{tok}%"))+ clauses.append(WikiSymbol.qualified_name.ilike(f"%{tok}%"))+ return or_(*clauses) if clauses else None+++def _symbol_result(row: WikiSymbol, score: float) -> dict:+ """Shape one symbol row into the issue #484 result contract."""+ return {+ "type": "symbol",+ "symbol_id": row.symbol_id,+ "name": row.name,+ "kind": row.kind,+ "file": row.file_path,+ "start_line": row.start_line,+ "end_line": row.end_line,+ "signature": row.signature or "",+ "qualified_name": row.qualified_name,+ "language": row.language,+ "score": round(score, 4),+ "next": "get_symbol",+ }+++async def _tombstoned_paths(session, repo_id: str, paths: set[str]) -> set[str]:+ """File paths whose page is tombstoned (deleted/renamed since indexing)."""+ if not paths:+ return set()+ res = await session.execute(+ select(Page.target_path).where(+ Page.repository_id == repo_id,+ Page.target_path.in_(paths),+ Page.freshness_status == "tombstone",+ )+ )+ return {row[0] for row in res.all()}+++async def search_symbols_single(+ ctx: Any,+ query: str,+ limit: int,+ *,+ symbol_kind: str | None = None,+ kind: str | None = None,+) -> list[dict]:+ """Symbol search against one repo context. Returns ranked result dicts."""+ qnorm = query.strip().lower()+ qtokens = _tokens(query)+ clause = _candidate_filter(qtokens, qnorm)+ if clause is None:+ return []++ async with get_session(ctx.session_factory) as session:+ repository = await _get_repo(session)+ stmt = select(WikiSymbol).where(+ WikiSymbol.repository_id == repository.id,+ clause,+ )+ if symbol_kind:+ stmt = stmt.where(WikiSymbol.kind == symbol_kind)+ # Front-load exact name matches and shorter names so the candidate cap+ # can never evict the true top hit on a common token (e.g. "index"+ # LIKE-matching thousands of rows). Scoring still re-ranks in Python.+ stmt = stmt.order_by(+ case((func.lower(WikiSymbol.name) == qnorm, 0), else_=1),+ func.length(WikiSymbol.name),+ ).limit(_MAX_CANDIDATES)+ rows = list((await session.execute(stmt)).scalars().all())+ if not rows:+ return []++ # One batched fetch of graph nodes for the candidate symbol_ids.+ sym_ids = [r.symbol_id for r in rows]+ gres = await session.execute(+ select(GraphNode).where(+ GraphNode.repository_id == repository.id,+ GraphNode.node_id.in_(sym_ids),+ )+ )+ gmap = {g.node_id: g for g in gres.scalars().all()}++ tombstoned = await _tombstoned_paths(session, repository.id, {r.file_path for r in rows})++ spec = _get_exclude_spec(ctx.path)+ scored: list[tuple[float, WikiSymbol]] = []+ for row in rows:+ if is_excluded(row.file_path, spec) or row.file_path in tombstoned:+ continue+ g = gmap.get(row.symbol_id)+ is_test = (g is not None and g.is_test) or _is_test_path(row.file_path)+ if not _symbol_kind_for_request_kind(kind, is_test):+ continue+ scored.append((_score_symbol(row, g, qtokens, qnorm), row))++ # Highest score first; deterministic tiebreak on symbol_id.+ scored.sort(key=lambda pair: (-pair[0], pair[1].symbol_id or ""))+ return [_symbol_result(row, score) for score, row in scored[:limit]]+++def _path_score(target_path: str, qnorm: str) -> float:+ """Rank a file path against a path-shaped query (higher = better)."""+ tp = target_path.lower()+ base = tp.rsplit("/", 1)[-1]+ score = 0.0+ if tp == qnorm or base == qnorm:+ score += 100.0+ if base.startswith(qnorm) or base == qnorm:+ score += 40.0+ if qnorm in tp:+ score += 20.0+ # Prefer the shallower / shorter path among equal matches.+ score -= len(tp) * 0.001+ return score+++async def search_paths_single(ctx: Any, query: str, limit: int) -> list[dict]:+ """Path search against one repo context. Returns ranked file result dicts."""+ qnorm = query.strip().lower().replace("\\", "/")+ if not qnorm:+ return []++ async with get_session(ctx.session_factory) as session:+ repository = await _get_repo(session)+ res = await session.execute(+ select(Page.id, Page.title, Page.target_path, Page.freshness_status).where(+ Page.repository_id == repository.id,+ Page.page_type == "file_page",+ Page.target_path.ilike(f"%{qnorm}%"),+ )+ )+ rows = res.all()++ spec = _get_exclude_spec(ctx.path)+ scored: list[tuple[float, Any]] = []+ for page_id, title, target_path, freshness in rows:+ if not target_path or freshness == "tombstone":+ continue+ if is_excluded(target_path, spec):+ continue+ scored.append((_path_score(target_path, qnorm), (page_id, title, target_path)))++ scored.sort(key=lambda pair: (-pair[0], pair[1][2]))+ return [+ {+ "type": "file",+ "page_id": page_id,+ "title": title,+ "file": target_path,+ "score": round(score, 4),+ "next": "get_context",+ }+ for score, (page_id, title, target_path) in scored[:limit]+ ]diff --git a/plugins/claude-code/README.md b/plugins/claude-code/README.mdindex 84e44824a..cbb6a3a7b 100644--- a/plugins/claude-code/README.md+++ b/plugins/claude-code/README.md@@ -78,7 +78,7 @@ Registered automatically when the plugin is enabled:| `get_answer` | Cited, synthesised answer to a code question + a calibrated confidence || `get_context` | Triage card (docs, signatures, hotspot bit, callers, decisions) for files/modules/symbols || `get_symbol` | Raw source of one symbol with exact line bounds |-| `search_codebase` | Semantic search over the wiki |+| `search_codebase` | Hybrid code search — `mode="auto"` routes identifiers to indexed symbols, paths to files, prose to semantic wiki search || `get_risk` | Per-file hotspot, dependents, co-changes, owners; PR `directive` block with `changed_files` || `get_why` | Architectural decisions — search, path-anchored, or health dashboard || `get_dead_code` | Unused/unreachable findings tiered by confidence |diff --git a/plugins/claude-code/skills/codebase-exploration/SKILL.md b/plugins/claude-code/skills/codebase-exploration/SKILL.mdindex 5ddf4518b..1f994fb60 100644--- a/plugins/claude-code/skills/codebase-exploration/SKILL.md+++ b/plugins/claude-code/skills/codebase-exploration/SKILL.md@@ -21,7 +21,7 @@ plain file reads don't, usually in one round-trip instead of many.|---|---|| First orientation in an unfamiliar repo | `get_overview()` — architecture summary, key modules, entry points, git health, knowledge map. Skip it once you have the map. || A direct answer to "how/where/why does X work" | `get_answer(question="…")` — synthesised answer with citations + a `retrieval_quality` signal. Collapses the search → read → reason loop. |-| Candidate files for a fuzzy concept | `search_codebase(query="…")` — semantic wiki search. Each hit reports `search_method` (`embedding` vs `bm25` fallback). Use Grep for exact identifiers. |+| Find a symbol, file, or fuzzy concept | `search_codebase(query="…")` — hybrid search. `mode="auto"` routes an identifier to indexed symbol hits (`symbol_id`/line bounds → pipe into `get_symbol`), a path to file pages (→ `get_context`), and prose to semantic wiki search (each hit reports `search_method`: `embedding` vs `bm25`). Force a branch with `mode=symbol\|path\|concept\|hybrid`; narrow symbols with `symbol_kind`. || A triage card for specific files/symbols | `get_context(targets=[…])` — title, summary, signatures, hotspot bit, top callers, decision titles, symbol_ids. Batch many targets in one call. || The actual source of one symbol | `get_symbol("path/to/file.py::Name")` — exact bytes with line bounds. Cheaper than Read + offset math. Use a `symbol_id` from `get_context`. |@@ -32,7 +32,10 @@ plain file reads don't, usually in one round-trip instead of many.- High confidence → answer it, cite the paths.- `medium`/`low` confidence → follow `best_guesses[0].file` or`fallback_targets[0]` into `get_context`, then `get_symbol` for bytes.-3. More files around a concept → `search_codebase`, then `get_context` on the+3. A named symbol or a path → `search_codebase(query="Name")` /+ `search_codebase(query="path/to/file.py")`; symbol hits pipe straight into+ `get_symbol`, file hits into `get_context`.+4. More files around a concept → `search_codebase`, then `get_context` on thehits (batched), then `get_symbol` only for the bodies you actually need.Fall back to raw Read/Grep only when the indexed context doesn't cover thediff --git a/plugins/codex/skills/codebase-exploration/SKILL.md b/plugins/codex/skills/codebase-exploration/SKILL.mdindex 81ab3d80d..3ae07e10f 100644--- a/plugins/codex/skills/codebase-exploration/SKILL.md+++ b/plugins/codex/skills/codebase-exploration/SKILL.md@@ -13,7 +13,7 @@ Call `get_overview()` first. It returns the architecture summary, module map, en## Answering How Or Where Questions-1. Call `search_codebase(query="topic or symbol")` to find relevant documented modules and files.+1. Call `search_codebase(query="topic, symbol, or path")`. It auto-routes: an identifier returns indexed symbol hits (`symbol_id` + line bounds — pipe into `get_symbol`), a path returns file pages, and prose runs semantic search. Force a branch with `mode=symbol|path|concept|hybrid`.2. Call `get_context(targets=[...])` with all relevant files from the search results in one batch.3. Read raw source only after the indexed context is not specific enough for the user’s question.diff --git a/tests/unit/server/mcp/test_search.py b/tests/unit/server/mcp/test_search.pyindex c54dddda6..73a541236 100644--- a/tests/unit/server/mcp/test_search.py+++ b/tests/unit/server/mcp/test_search.py@@ -294,6 +294,199 @@ class TestDecisionDemotionAndRescue:assert result["results"][0]["page_type"] == "decision_record"+class TestSymbolSearch:+ """mode="symbol" / "auto" routing into the structural index (issue #484)."""++ @pytest.mark.asyncio+ async def test_exact_name_returns_symbol_shape(self, setup_mcp):+ from repowise.server.mcp_server import search_codebase++ result = await search_codebase("AuthService", mode="symbol")+ assert result["mode"] == "symbol"+ hits = result["results"]+ assert hits, "exact name must resolve to a symbol"+ top = hits[0]+ assert top["type"] == "symbol"+ assert top["symbol_id"] == "src/auth/service.py::AuthService"+ assert top["name"] == "AuthService"+ assert top["kind"] == "class"+ assert top["file"] == "src/auth/service.py"+ assert top["start_line"] == 10+ assert top["end_line"] == 100+ assert top["next"] == "get_symbol"++ @pytest.mark.asyncio+ async def test_auto_routes_bare_identifier_to_symbol(self, setup_mcp):+ from repowise.server.mcp_server import search_codebase++ result = await search_codebase("AuthService")+ assert result["mode"] == "symbol"+ assert any(r["symbol_id"] == "src/auth/service.py::AuthService" for r in result["results"])++ @pytest.mark.asyncio+ async def test_camelcase_multitoken_qualified_match(self, setup_mcp):+ # "AuthService login" must surface AuthService.login via token coverage.+ from repowise.server.mcp_server import search_codebase++ result = await search_codebase("AuthService login", mode="symbol")+ ids = [r["symbol_id"] for r in result["results"]]+ assert "src/auth/service.py::login" in ids++ @pytest.mark.asyncio+ async def test_symbol_kind_filter(self, setup_mcp):+ from repowise.server.mcp_server import search_codebase++ result = await search_codebase("login", mode="symbol", symbol_kind="class")+ # login is a method, not a class — the kind filter removes it.+ assert all(r["kind"] == "class" for r in result["results"])+ assert not any(r["name"] == "login" for r in result["results"])++ @pytest.mark.asyncio+ async def test_no_match_falls_back_to_grep_hint(self, setup_mcp):+ from repowise.server.mcp_server import search_codebase++ result = await search_codebase("NonexistentSymbol", mode="symbol")+ assert result["results"] == []+ assert "grep_hint" in result++ @pytest.mark.asyncio+ async def test_excluded_symbol_dropped(self, setup_mcp, monkeypatch):+ # Exclude the auth file at query time; the symbol must not surface.+ import pathspec++ import repowise.server.mcp_server.tool_search_symbols as ss++ spec = pathspec.PathSpec.from_lines("gitwildmatch", ["src/auth/**"])+ monkeypatch.setattr(ss, "_get_exclude_spec", lambda _p: spec)++ from repowise.server.mcp_server import search_codebase++ result = await search_codebase("AuthService", mode="symbol")+ assert result["results"] == []++ @pytest.mark.asyncio+ async def test_tombstoned_symbol_dropped(self, setup_mcp, factory):+ # Tombstone the auth service page; its symbols must be filtered out.+ from sqlalchemy import update++ from repowise.core.persistence.models import Page++ async with factory() as s:+ await s.execute(+ update(Page)+ .where(Page.id == "file_page:src/auth/service.py")+ .values(freshness_status="tombstone")+ )+ await s.commit()++ from repowise.server.mcp_server import search_codebase++ result = await search_codebase("AuthService", mode="symbol")+ assert not any(r["file"] == "src/auth/service.py" for r in result["results"])+++class TestPathSearch:+ """mode="path" / "auto" routing into file pages."""++ @pytest.mark.asyncio+ async def test_path_query_resolves_file(self, setup_mcp):+ from repowise.server.mcp_server import search_codebase++ result = await search_codebase("src/auth/service.py", mode="path")+ assert result["mode"] == "path"+ files = [r["file"] for r in result["results"]]+ assert "src/auth/service.py" in files+ top = result["results"][0]+ assert top["type"] == "file"+ assert top["next"] == "get_context"++ @pytest.mark.asyncio+ async def test_auto_routes_path_shaped_query(self, setup_mcp):+ from repowise.server.mcp_server import search_codebase++ result = await search_codebase("src/db/models.py")+ assert result["mode"] == "path"+ assert any(r["file"] == "src/db/models.py" for r in result["results"])+++class TestHybridSearch:+ """Mixed natural-language + identifier queries run hybrid."""++ @pytest.mark.asyncio+ async def test_auto_routes_mixed_query_to_hybrid(self, setup_mcp):+ from repowise.server.mcp_server import search_codebase++ result = await search_codebase("where is AuthService defined")+ assert result["mode"] == "hybrid"++ @pytest.mark.asyncio+ async def test_hybrid_puts_symbols_first(self, setup_mcp):+ import repowise.server.mcp_server as mcp_mod+ from repowise.server.mcp_server import search_codebase++ async def fake_search(query, limit=10):+ return [+ _mk_result(+ "file_page:src/auth/service.py",+ "Auth Service",+ "file_page",+ "src/auth/service.py",+ 0.42,+ ),+ ]++ mcp_mod._vector_store.search = fake_search+ result = await search_codebase("how does AuthService work", mode="hybrid")+ assert result["results"][0]["type"] == "symbol"++ @pytest.mark.asyncio+ async def test_hybrid_keeps_concept_page_alongside_symbol(self, setup_mcp):+ # A concept page for a DIFFERENT file (not the symbol's own file, which+ # would dedupe out) must survive the merge — hybrid is symbols AND pages.+ import repowise.server.mcp_server as mcp_mod+ from repowise.server.mcp_server import search_codebase++ async def fake_search(query, limit=10):+ return [+ _mk_result(+ "file_page:src/db/models.py",+ "DB Models",+ "file_page",+ "src/db/models.py",+ 0.6,+ ),+ ]++ mcp_mod._vector_store.search = fake_search+ result = await search_codebase("how does AuthService work", mode="hybrid", limit=5)+ types = {r["type"] for r in result["results"]}+ assert "symbol" in types, "symbol hit must be present"+ assert "page" in types, "concept page must survive the merge"+++class TestConceptModeUnchanged:+ """Forcing mode="concept" preserves the original semantic behavior."""++ @pytest.mark.asyncio+ async def test_concept_mode_runs_semantic(self, setup_mcp):+ import repowise.server.mcp_server as mcp_mod+ from repowise.server.mcp_server import search_codebase++ await mcp_mod._vector_store.embed_and_upsert(+ "file_page:src/auth/service.py",+ "Auth Service — Main authentication service class",+ {+ "title": "Auth Service",+ "page_type": "file_page",+ "target_path": "src/auth/service.py",+ },+ )+ result = await search_codebase("AuthService", mode="concept")+ # Concept mode does not set the structural "mode" routing key.+ assert "results" in result+ assert all(r.get("type") != "symbol" for r in result["results"])++class TestIdentifierGrepHint:@pytest.mark.asyncioasync def test_multiword_query_with_identifier_gets_hint(self, setup_mcp):diff --git a/website/mcp-server.md b/website/mcp-server.mdindex dd9be8346..0666efc05 100644--- a/website/mcp-server.md+++ b/website/mcp-server.md@@ -321,27 +321,36 @@ get_why(query="why is rate limiting done in the app layer")----### `search_codebase(query, limit?, page_type?)`+### `search_codebase(query, limit?, mode?, kind?, symbol_kind?, page_type?)`-Semantic search over the full wiki using natural language.+Hybrid code search. Depending on the query, it searches the indexed **symbols**, **file paths**, or the **wiki** — a single tool for "find this function", "find this file", and "find code about this topic".**Parameters:**-- `query` (string) — natural language query+- `query` (string) — identifier, path, or natural-language query- `limit` (int, default 5) — max results-- `page_type` (optional) — filter to `"file"`, `"module"`, or `"repository"`+- `mode` (optional) — `auto` (default) \| `concept` \| `symbol` \| `path` \| `hybrid`+- `kind` (optional) — `implementation` \| `test` \| `config` \| `doc`+- `symbol_kind` (optional) — restrict symbol hits by kind (`function`, `class`, `method`, …)+- `page_type` (optional) — `file_page` \| `module_page` \| `symbol_spotlight` (concept mode)-**Returns:** Ranked list of wiki pages with relevance scores and short excerpts. Recently-changed files receive a freshness boost.+**Modes:** `auto` routes by shape — an identifier searches indexed symbols (results carry `symbol_id` + line bounds, pipe into `get_symbol`), a path searches file pages (pipe into `get_context`), prose runs wiki-semantic search, and mixed queries run hybrid (symbols first). Force a branch with an explicit `mode`.-**When to use:** When locating code — prefer over `grep`/`find` for conceptual searches.+**Returns:** Symbol hits (`symbol_id`, `file`, line bounds, `signature`, `next: "get_symbol"`), file hits (`page_id`, `file`, `next: "get_context"`), or ranked wiki pages with relevance scores and a `search_method`. Recently-changed files receive a freshness boost.++**When to use:** Locating a symbol or file by name, or discovering code by topic — prefer over `grep`/`find`.**Example:**```+search_codebase(query="GitIndexer index_repo")++→ 1. symbol packages/core/.../git_indexer/indexer.py::GitIndexer.index_repo+ async def index_repo(...) -> tuple[GitIndexSummary, list[dict]] (lines 75-306)+ next: get_symbol+search_codebase(query="how database connections are pooled")→ 1. packages/server/src/repowise/server/db.py (0.92)"Creates async SQLAlchemy engine with connection pooling..."- 2. packages/core/src/repowise/core/persistence/session.py (0.87)- "Session factory configured with pool_size=5..."```---