Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

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.md
index 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.j2
index 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.j2
index 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.md
index 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.py
index 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.py
index 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.py
index 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 mcp
from 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 each
diff --git a/packages/server/src/repowise/server/mcp_server/tool_search_symbols.py b/packages/server/src/repowise/server/mcp_server/tool_search_symbols.py
new file mode 100644
index 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.md
index 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.md
index 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 the
hits (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 the
diff --git a/plugins/codex/skills/codebase-exploration/SKILL.md b/plugins/codex/skills/codebase-exploration/SKILL.md
index 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.py
index 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.asyncio
async def test_multiword_query_with_identifier_gets_hint(self, setup_mcp):
diff --git a/website/mcp-server.md b/website/mcp-server.md
index 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..."
```
---