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.

fix(search): validate question identifiers against the symbol table, and return no symbol for a name that doesn't exist (#2691)

Swati Ahuja7db5fd700c32
diff --git a/packages/server/src/repowise/server/mcp_server/_query_shape.py b/packages/server/src/repowise/server/mcp_server/_query_shape.py
index 193799c0f..0f3fbab55 100644
--- a/packages/server/src/repowise/server/mcp_server/_query_shape.py
+++ b/packages/server/src/repowise/server/mcp_server/_query_shape.py
@@ -9,6 +9,7 @@ from __future__ import annotations
import os.path
import re
+from collections.abc import Container
from functools import cache
@@ -127,24 +128,138 @@ _IDENT_TOKEN_RE = re.compile(
)
-def _embedded_identifiers(query: str) -> list[str]:
- """Identifier-shaped tokens carried inside a natural-language query."""
- return _IDENT_TOKEN_RE.findall(query)
+# Every word, dotted chains kept whole. Which of them are identifiers is
+# decided against the symbol table (``_embedded_identifiers`` with ``names``),
+# not by shape: shape alone misses ``proxyExecute`` and ``OpenAIProvider`` and
+# takes ``TypeScript``.
+_WORD_CHAIN_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*")
-def _identifier_candidates(query: str, mode: str) -> list[str]:
+def _identifier_shaped(token: str) -> bool:
+ """At least 3 chars with a capital, an underscore or a digit. Plain
+ lowercase words (``method``, ``class``) name symbols too broadly to count."""
+ return len(token) >= 3 and ("_" in token or any(ch.isupper() or ch.isdigit() for ch in token))
+
+
+def _folds_case(token: str) -> bool:
+ """Whether a case-insensitive match may stand for ``token``.
+
+ Mixed case past the first letter, or an underscore. A sentence-initial
+ ``Where`` or an all-caps ``API`` would otherwise fold onto a lowercase
+ ``where`` or ``api`` symbol, which the question never named.
+ """
+ body = token.strip("_")
+ return "_" in body or (
+ any(ch.islower() for ch in body) and any(ch.isupper() for ch in body[1:])
+ )
+
+
+def _names_symbol(token: str, names: Container[str]) -> bool:
+ """Case-sensitive first, then case-insensitive where ``_folds_case`` allows;
+ a dotted token also counts when its last part names a symbol."""
+ if token in names or (_folds_case(token) and token.lower() in names):
+ return True
+ return "." in token and _names_symbol(token.rsplit(".", 1)[1], names)
+
+
+def _embedded_identifiers(query: str, names: Container[str] | None = None) -> list[str]:
+ """Identifier tokens carried inside a natural-language query.
+
+ Without ``names``: the shape regex alone. With ``names`` (the indexed
+ symbol names), a token counts when it names at least one of them, or the
+ last part of a dotted token does: ``executeWithTool`` and
+ ``client.proxyExecute`` count when indexed, ``TypeScript`` does not unless
+ a symbol carries that name. A token no prose word fits
+ (``_looks_like_code_name``) counts even unindexed, so a search can say it
+ does not exist. ``names`` is tested for the token, then for its lowered
+ form, so a container that also answers for each name's lowered spelling
+ gets the case-insensitive leg.
+ """
+ if names is None:
+ return _IDENT_TOKEN_RE.findall(query)
+ return [
+ token
+ for token in _name_tokens(query)
+ if _names_symbol(token, names) or _looks_like_code_name(token)
+ ]
+
+
+def _name_tokens(query: str) -> list[str]:
+ """Words that could name a symbol: identifier-shaped, or dotted chains."""
+ return [t for t in _WORD_CHAIN_RE.findall(query) if "." in t or _identifier_shaped(t)]
+
+
+def _name_lookup_keys(query: str) -> set[str]:
+ """Lowered names ``_embedded_identifiers`` may test for ``query``, so a
+ caller loads only these rows of the symbol table."""
+ return {t.rsplit(".", 1)[-1].lower() for t in _name_tokens(query)}
+
+
+_CAMEL_HUMP_RE = re.compile(r"[A-Z]+(?![a-z])|[A-Z][a-z0-9]*|[a-z0-9]+")
+_LOWER_CAMEL_RE = re.compile(r"[a-z]{2,}[a-z0-9]*[A-Z][a-z]")
+
+
+def _looks_like_code_name(token: str) -> bool:
+ """Shaped so no prose word or product name fits it.
+
+ snake_case, lowerCamel (``proxyExecute``), or three or more capitalised
+ humps (``AnthropicStreamingAdapter``). ``TypeScript``, ``GitHub``,
+ ``iPhone`` and ``macOS`` do not fit, so a name like them that matches no
+ symbol never reads as "that symbol does not exist".
+ """
+ if not _WORD_CHAIN_RE.fullmatch(token):
+ return False # prose around a name ("AuthService login") is not one name
+ leaf = token.rsplit(".", 1)[-1].strip("_")
+ if "_" in leaf or _LOWER_CAMEL_RE.match(leaf):
+ return True
+ return leaf[:1].isupper() and len(_CAMEL_HUMP_RE.findall(leaf)) >= 3
+
+
+def _names_a_path(token: str, paths: list[str]) -> bool:
+ """Whether ``token``'s last dotted part is a directory or file stem among
+ ``paths``: a module the question names, which no symbol table carries."""
+ leaf = token.rsplit(".", 1)[-1]
+ return any(leaf == seg.split(".", 1)[0] for path in paths for seg in path.split("/"))
+
+
+# The label and score ceiling on the pages a search returns for a named
+# symbol that is not indexed: they answer the prose around the name at best.
+NOT_THE_NAMED_SYMBOL = "related, not the named symbol"
+_NOT_THE_NAMED_SYMBOL_CEILING = 0.45
+
+
+def _mark_not_the_named_symbol(items: list[dict]) -> None:
+ """Label ``items`` as related to the question, not the missing symbol, and
+ hold their scores under the 0.5 an agent would trust.
+
+ ``relevance_score`` (what ranks and what clients read) is scaled so the
+ best item sits at the ceiling, keeping the order; ``confidence_score`` is
+ capped where present.
+ """
+ top = max((item.get("relevance_score") or 0.0 for item in items), default=0.0)
+ scale = min(1.0, _NOT_THE_NAMED_SYMBOL_CEILING / top) if top else 1.0
+ for item in items:
+ item["relation"] = NOT_THE_NAMED_SYMBOL
+ if item.get("relevance_score"):
+ item["relevance_score"] = round(item["relevance_score"] * scale, 4)
+ if "confidence_score" in item:
+ item["confidence_score"] = min(item["confidence_score"], _NOT_THE_NAMED_SYMBOL_CEILING)
+
+
+def _identifier_candidates(query: str, mode: str, names: Container[str] | None = None) -> list[str]:
"""Identifier tokens the query is asking after, for the exact-match signal.
A single-token query IS the identifier (symbol mode); a natural-language
query carrying identifiers (hybrid mode) exposes them the same way
``_resolve_mode`` used to route here. Concept/path queries name none.
+ ``names`` validates the hybrid tokens (see ``_embedded_identifiers``).
"""
if mode == "symbol":
q = query.strip()
canonical = _canonical_symbol_query(q)
return [q, canonical[1]] if canonical else ([q] if q else [])
if mode == "hybrid":
- return _embedded_identifiers(query)
+ return _embedded_identifiers(query, names)
return []
@@ -184,14 +299,15 @@ def _has_exact_symbol(candidates: list[str], symbols: list[dict]) -> bool:
_VALID_MODES = {"auto", "concept", "symbol", "path", "hybrid"}
-def _resolve_mode(query: str, mode: str | None) -> str:
+def _resolve_mode(query: str, mode: str | None, names: Container[str] | None = 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.
+ the exact heuristics that previously only emitted a grep_hint. With
+ ``names``, only validated identifiers route to hybrid.
"""
m = (mode or "auto").lower()
if m not in _VALID_MODES:
@@ -204,7 +320,7 @@ def _resolve_mode(query: str, mode: str | None) -> str:
return "path"
if _looks_like_exact_token(query):
return "symbol"
- if _embedded_identifiers(query):
+ if _embedded_identifiers(query, names):
return "hybrid"
return "concept"
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py b/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py
index 80447f217..a499991ee 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py
@@ -16,6 +16,7 @@ from typing import Any
from sqlalchemy import select
from repowise.core.persistence.models import WikiSymbol
+from repowise.server.mcp_server._query_shape import _WORD_CHAIN_RE, _identifier_shaped
from repowise.server.mcp_server._verify import verify_and_heal
from repowise.server.mcp_server.tool_answer.config import (
_ENRICH_TOP_N_HITS,
@@ -77,23 +78,11 @@ def _extract_question_identifiers(question: str) -> set[str]:
snake_case, CamelCase and dotted paths, at least 3 chars and not
stopwords. Drives question-aware promotion in ``_hydrate_symbols_for_hits``.
"""
- import re
-
ids: set[str] = set()
- for tok in re.findall(r"[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*", question):
+ for tok in _WORD_CHAIN_RE.findall(question):
# A dotted path yields both the full thing and each part.
- parts = tok.split(".")
- candidates = [tok, *parts]
- for c in candidates:
- if len(c) < 3:
- continue
- if c.lower() in _STOPWORDS:
- continue
- # Pure-lowercase words (``method``, ``class``) match too broadly.
- has_upper = any(ch.isupper() for ch in c)
- has_under = "_" in c
- has_digit = any(ch.isdigit() for ch in c)
- if has_upper or has_under or has_digit:
+ for c in (tok, *tok.split(".")):
+ if c.lower() not in _STOPWORDS and _identifier_shaped(c):
ids.add(c)
return ids
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 430998a6a..03fc15004 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_search.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_search.py
@@ -6,6 +6,7 @@ import asyncio
import contextlib
import logging
import re
+from collections.abc import Container
from typing import Any
from sqlalchemy import select
@@ -44,13 +45,17 @@ from repowise.server.mcp_server._query_shape import (
_DECISION_DOWNWEIGHT,
_MIN_RELEVANCE_SCORE,
_VALID_MODES,
+ NOT_THE_NAMED_SYMBOL,
_canonical_symbol_query,
_embedded_identifiers,
_fetch_limit_for,
_has_exact_symbol,
_identifier_candidates,
_is_why_shaped,
+ _looks_like_code_name,
_looks_like_exact_token,
+ _mark_not_the_named_symbol,
+ _names_a_path,
_qual_norm,
_resolve_mode,
_symbol_matches_name,
@@ -58,6 +63,7 @@ from repowise.server.mcp_server._query_shape import (
from repowise.server.mcp_server._references import path_identity, symbol_identity
from repowise.server.mcp_server._retrieval_rank import rerank_by_context_coverage
from repowise.server.mcp_server.tool_search_symbols import (
+ indexed_names,
search_paths_single,
search_symbols_single,
)
@@ -120,7 +126,12 @@ def _prose_dominates(query: str, identifiers: list[str]) -> bool:
def _interleave_hybrid(
- query: str, symbols: list[dict], concepts: list[dict], limit: int, exact: bool
+ query: str,
+ symbols: list[dict],
+ concepts: list[dict],
+ limit: int,
+ exact: bool,
+ names: Container[str] | None = None,
) -> list[dict]:
"""Order one hybrid result window from the two incomparable score scales.
@@ -136,7 +147,7 @@ def _interleave_hybrid(
synthesis in get_answer". There, concept pages lead and the fuzzy symbols
fall to the tail (nothing is dropped, only reordered within the window).
"""
- if not exact and concepts and _prose_dominates(query, _embedded_identifiers(query)):
+ if not exact and concepts and _prose_dominates(query, _embedded_identifiers(query, names)):
reserved = min(len(symbols), limit // 2)
return (concepts[: max(1, limit - reserved)] + symbols)[:limit]
reserved = min(len(concepts), limit // 2)
@@ -784,7 +795,7 @@ def _result_paths(results: list[dict]) -> list[str]:
return paths
-def _grep_hint_for(query: str) -> str | None:
+def _grep_hint_for(query: str, names: Container[str] | None = None) -> str | None:
"""Zero-result recovery hint for identifier-shaped queries, else ``None``.
Only attached when the search produced nothing (see call sites) — a
@@ -797,7 +808,7 @@ def _grep_hint_for(query: str) -> str | None:
f"No indexed match for identifier {query!r}. Retry with "
'mode="symbol" (or check spelling/casing). ' + EXHAUSTIVE_SWEEP_HINT
)
- if idents := _embedded_identifiers(query):
+ if idents := _embedded_identifiers(query, names):
shown = ", ".join(repr(t) for t in idents[:3])
return (
f"Query names identifier(s) {shown} but nothing matched. Search "
@@ -820,6 +831,30 @@ def _tag_repo(items: list[dict], ctx, multi: bool) -> None:
item["repo"] = ctx.alias
+def _missing_named_symbols(
+ candidates: list[str], symbols: list[dict], canonical: bool, concepts: list[dict]
+) -> list[str]:
+ """Code-shaped names the query asks after that no returned symbol matches
+ exactly (or returned module path carries): they do not exist here. Judged
+ per name, so an indexed name beside a missing one hides nothing. Their
+ fuzzy neighbours would stand in for them, so the caller keeps only exact
+ symbols; the pages are marked here as related to the question, not the
+ symbol."""
+ if canonical:
+ return []
+ page_paths = [c.get("target_path") or "" for c in concepts]
+ missing = [
+ c
+ for c in candidates
+ if _looks_like_code_name(c)
+ and not _has_exact_symbol([c], symbols)
+ and not _names_a_path(c, page_paths)
+ ]
+ if missing:
+ _mark_not_the_named_symbol(concepts)
+ return missing
+
+
async def _structured_search(
query: str,
limit: int,
@@ -829,6 +864,7 @@ async def _structured_search(
repo: str | None,
mode: str,
grep_hint: str | None,
+ names: Container[str] | None = None,
) -> dict:
"""Run symbol / path / hybrid search and shape the response.
@@ -855,7 +891,7 @@ async def _structured_search(
if canonical_symbol:
symbol_query = canonical_symbol[1]
if mode == "hybrid":
- _idents = _embedded_identifiers(query)
+ _idents = _embedded_identifiers(query, names)
if _idents:
symbol_query = " ".join(_idents)
@@ -879,7 +915,7 @@ async def _structured_search(
symbols.sort(key=lambda x: -(x.get("score") or 0.0))
files.sort(key=lambda x: -(x.get("score") or 0.0))
- candidates = _identifier_candidates(query, mode)
+ candidates = _identifier_candidates(query, mode, names)
if mode == "symbol":
symbols = _protect_exact_symbols(query, symbols)
elif mode == "hybrid" and candidates:
@@ -891,6 +927,9 @@ async def _structured_search(
# Computed once here so the hybrid interleave and the exact-match note below
# agree on the same signal.
exact = _has_exact_symbol(candidates, symbols) if candidates else False
+ missing = _missing_named_symbols(candidates, symbols, bool(canonical_symbol), concepts)
+ if missing:
+ symbols = [s for s in symbols if _has_exact_symbol(candidates, [s])]
if mode == "symbol":
results = symbols[:limit]
@@ -903,7 +942,7 @@ async def _structured_search(
# 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))
- results = _interleave_hybrid(query, symbols, concepts, limit, exact)
+ results = _interleave_hybrid(query, symbols, concepts, limit, exact, names)
repository = None
if not multi:
@@ -934,8 +973,15 @@ async def _structured_search(
# there is no exact hit to distinguish from the fuzz. ``candidates`` /
# ``exact`` were computed above so ordering and this note stay consistent.
if candidates:
- response["exact_match"] = exact
- if not exact:
+ response["exact_match"] = exact and not missing
+ if missing:
+ shown = ", ".join(repr(c) for c in missing[:3])
+ response["note"] = (
+ f"No indexed symbol is named {shown}, so no symbol is returned "
+ f"for it. Any page here is {NOT_THE_NAMED_SYMBOL}. Recheck the "
+ "spelling, or search a shorter part of the name. " + EXHAUSTIVE_SWEEP_HINT
+ )
+ elif not exact:
shown = ", ".join(repr(c) for c in candidates[:3])
response["note"] = (
f"No indexed symbol exactly matches {shown}. The results are "
@@ -1003,8 +1049,6 @@ async def search_codebase(
mode: auto | concept | symbol | path | hybrid.
symbol_kind: filter symbol hits by kind (function|class|method|...).
"""
- grep_hint = _grep_hint_for(query)
-
# An unknown kind used to take the same ``return False`` as a kind that is
# simply inapplicable, so a typo and a real empty result looked identical.
ignored: list[dict[str, Any]] = []
@@ -1015,11 +1059,14 @@ async def search_codebase(
if mode is not None and mode.lower() in _VALID_MODES:
mode = mode.lower()
mode = resolve_enum_argument(mode, _VALID_MODES, argument="mode", ignored=ignored)
- resolved_mode = _resolve_mode(query, mode)
+ # Loaded once so routing, candidates, ordering and the hint validate alike.
+ names = await indexed_names(await _contexts_for(repo), query)
+ grep_hint = _grep_hint_for(query, names)
+ resolved_mode = _resolve_mode(query, mode, names)
if resolved_mode in ("symbol", "path", "hybrid"):
structured = await _structured_search(
- query, limit, page_type, kind, symbol_kind, repo, resolved_mode, grep_hint
+ query, limit, page_type, kind, symbol_kind, repo, resolved_mode, grep_hint, names
)
attach_ignored_arguments(structured, ignored)
return structured
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
index e693c2af6..584022e47 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_search_symbols.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_search_symbols.py
@@ -33,7 +33,7 @@ from repowise.server.mcp_server._helpers import (
escape_like,
is_excluded,
)
-from repowise.server.mcp_server._query_shape import _qual_norm
+from repowise.server.mcp_server._query_shape import _name_lookup_keys, _qual_norm
from repowise.server.mcp_server._symbol_lookup import symbol_rank_key
# Candidate ceiling: scoring/sorting happens in Python, so the SQL pre-filter
@@ -186,6 +186,28 @@ async def _tombstoned_paths(session, repo_id: str, paths: set[str]) -> set[str]:
return {row[0] for row in res.all()}
+async def indexed_names(contexts: list, query: str) -> set[str]:
+ """The indexed symbol names ``query`` could name, each also lowered: the
+ ``names`` container ``_embedded_identifiers`` validates against."""
+ keys = _name_lookup_keys(query)
+ names: set[str] = set()
+ if not keys:
+ return names
+ for ctx in contexts:
+ async with get_session(ctx.session_factory) as session:
+ repository = await _get_repo(session)
+ res = await session.execute(
+ select(WikiSymbol.name)
+ .distinct()
+ .where(
+ WikiSymbol.repository_id == repository.id,
+ func.lower(WikiSymbol.name).in_(sorted(keys)),
+ )
+ )
+ names.update(name for (name,) in res.all() if name)
+ return names | {name.lower() for name in names}
+
+
async def search_symbols_single(
ctx: Any,
query: str,
diff --git a/tests/unit/server/mcp/test_search.py b/tests/unit/server/mcp/test_search.py
index d1c345d53..71909eab8 100644
--- a/tests/unit/server/mcp/test_search.py
+++ b/tests/unit/server/mcp/test_search.py
@@ -81,6 +81,42 @@ async def _seed_page(page_id, target_path, page_type="file_page"):
await session.commit()
+async def _seed_symbol(name):
+ """Insert a WikiSymbol named ``name`` into the setup_mcp DB."""
+ from datetime import UTC, datetime
+
+ from sqlalchemy import select
+
+ import repowise.server.mcp_server as mcp_mod
+ from repowise.core.persistence.database import get_session
+ from repowise.core.persistence.models import Page, WikiSymbol
+
+ now = datetime(2026, 1, 1, tzinfo=UTC)
+ async with get_session(mcp_mod._session_factory) as session:
+ rid = (await session.execute(select(Page.repository_id).limit(1))).scalar()
+ session.add(
+ WikiSymbol(
+ id=f"seed-{name}",
+ repository_id=rid,
+ file_path="src/net/client.py",
+ symbol_id=f"src/net/client.py::{name}",
+ name=name,
+ qualified_name=f"net.client.{name}",
+ kind="function",
+ signature=f"def {name}()",
+ start_line=1,
+ end_line=5,
+ visibility="public",
+ is_async=False,
+ complexity_estimate=1,
+ language="python",
+ created_at=now,
+ updated_at=now,
+ )
+ )
+ await session.commit()
+
+
@pytest.mark.asyncio
@pytest.mark.parametrize("glob", ["*", "?"])
async def test_path_search_accepts_trailing_glob(setup_mcp, glob):
@@ -930,9 +966,9 @@ class TestIdentifierGrepHint:
async def test_camelcase_identifier_gets_hint(self, setup_mcp):
from repowise.server.mcp_server import search_codebase
- result = await search_codebase("how does LanguageRegistry resolve specs")
+ result = await search_codebase("how does LanguageRegistryLoader resolve specs")
assert "grep_hint" in result
- assert "LanguageRegistry" in result["grep_hint"]
+ assert "LanguageRegistryLoader" in result["grep_hint"]
@pytest.mark.asyncio
async def test_plain_english_query_gets_no_hint(self, setup_mcp):
@@ -1034,15 +1070,113 @@ class TestExactMatchSignal:
@pytest.mark.asyncio
async def test_fuzzy_only_sets_false_with_note(self, setup_mcp):
- # "AuthServiceXyz" token-overlaps AuthService (a hit) but matches no
- # symbol exactly — the signal must fire even though results are non-empty.
+ # "AuthServ" token-overlaps AuthService (a hit) but matches no symbol
+ # exactly — the signal must fire even though results are non-empty. Two
+ # humps, like a product name, so it is not read as a missing code name.
from repowise.server.mcp_server import search_codebase
- result = await search_codebase("AuthServiceXyz", mode="symbol")
+ result = await search_codebase("AuthServ", mode="symbol")
assert result["results"], "fuzzy neighbour should still be returned"
assert result["exact_match"] is False
assert "exactly matches" in result.get("note", "")
+ @pytest.mark.asyncio
+ @pytest.mark.parametrize(
+ "query",
+ [
+ # Code-shaped names no symbol carries. "AuthServiceXyz" used to
+ # return AuthService as a fuzzy neighbour, standing in for it.
+ "AuthServiceXyz",
+ "executeToolWithRetryBackoff",
+ "validate_trigger_nonce",
+ "AnthropicStreamingAdapter",
+ "getToolkitMigrationPlan",
+ "where is validate_trigger_nonce defined",
+ ],
+ )
+ async def test_a_missing_code_name_returns_no_symbol(self, setup_mcp, query):
+ import repowise.server.mcp_server as mcp_mod
+ from repowise.server.mcp_server import search_codebase
+ from repowise.server.mcp_server._query_shape import NOT_THE_NAMED_SYMBOL
+
+ async def fake_search(q, limit=10):
+ return [_mk_result("file_page:src/db/models.py", "DB", "file_page", "", 0.9)]
+
+ mcp_mod._vector_store.search = fake_search
+ result = await search_codebase(query)
+ assert not [r for r in result["results"] if r.get("type") == "symbol"]
+ assert result["exact_match"] is False
+ assert "No indexed symbol is named" in result["note"]
+ if " " in query:
+ assert result["results"], "the prose query should still return its page"
+ for hit in result["results"]:
+ assert hit["relation"] == NOT_THE_NAMED_SYMBOL
+ assert hit["relevance_score"] <= 0.45
+
+ @pytest.mark.asyncio
+ async def test_pages_for_a_missing_name_are_capped_in_rank_order(self, setup_mcp):
+ # relevance_score is what hybrid pages carry and clients rank on.
+ import repowise.server.mcp_server as mcp_mod
+ from repowise.server.mcp_server import search_codebase
+
+ async def fake_search(q, limit=10):
+ return [
+ _mk_result("file_page:src/db/models.py", "DB", "file_page", "", 0.9),
+ _mk_result("file_page:src/auth/service.py", "Auth", "file_page", "", 0.8),
+ ]
+
+ mcp_mod._vector_store.search = fake_search
+ result = await search_codebase("where is validate_trigger_nonce defined")
+ scores = [hit["relevance_score"] for hit in result["results"]]
+ assert len(scores) == 2
+ assert scores == sorted(scores, reverse=True)
+ assert scores[0] == 0.45 and scores[1] < 0.45
+
+ @pytest.mark.asyncio
+ async def test_a_missing_name_beside_an_indexed_one_is_still_named(self, setup_mcp):
+ # Exactness is per name: AuthService is indexed, AuthServiceXyz is not.
+ import repowise.server.mcp_server as mcp_mod
+ from repowise.server.mcp_server import search_codebase
+
+ async def fake_search(q, limit=10):
+ return [_mk_result("file_page:src/db/models.py", "DB", "file_page", "", 0.9)]
+
+ mcp_mod._vector_store.search = fake_search
+ result = await search_codebase("how does AuthService and AuthServiceXyz work")
+ assert result["mode"] == "hybrid"
+ assert result["exact_match"] is False
+ assert "'AuthServiceXyz'" in result["note"]
+ symbols = [r for r in result["results"] if r.get("type") == "symbol"]
+ assert [s["name"] for s in symbols] == ["AuthService"]
+
+ @pytest.mark.asyncio
+ @pytest.mark.parametrize(
+ "name, query",
+ [
+ ("proxyExecute", "how does proxyExecute retry"),
+ ("HTTPClient", "how does HTTPClient send"),
+ ],
+ )
+ async def test_an_indexed_name_routes_hybrid_through_the_symbol_table(
+ self, setup_mcp, name, query
+ ):
+ # The shape regex alone misses both; the symbol table names them.
+ from repowise.server.mcp_server import search_codebase
+
+ await _seed_symbol(name)
+ result = await search_codebase(query)
+ assert result["mode"] == "hybrid"
+ assert result["exact_match"] is True
+ assert result["results"][0]["name"] == name
+
+ @pytest.mark.asyncio
+ async def test_a_product_word_no_symbol_carries_stays_concept(self, setup_mcp):
+ from repowise.server.mcp_server import search_codebase
+
+ result = await search_codebase("Is TypeScript used anywhere in this repo")
+ assert result.get("mode") != "hybrid"
+ assert "exact_match" not in result
+
@pytest.mark.asyncio
async def test_concept_query_gets_no_signal(self, setup_mcp):
from repowise.server.mcp_server import search_codebase
diff --git a/tests/unit/server/mcp/test_search_query_shape.py b/tests/unit/server/mcp/test_search_query_shape.py
index 15060d102..1ecdf421b 100644
--- a/tests/unit/server/mcp/test_search_query_shape.py
+++ b/tests/unit/server/mcp/test_search_query_shape.py
@@ -15,6 +15,9 @@ from repowise.server.mcp_server.tool_search import (
_fetch_limit_for,
_has_exact_symbol,
_is_why_shaped,
+ _looks_like_code_name,
+ _mark_not_the_named_symbol,
+ _names_a_path,
_resolve_mode,
)
@@ -76,3 +79,93 @@ def test_the_shape_module_loads_no_registry_or_database() -> None:
)
out = subprocess.run([sys.executable, "-c", code], capture_output=True, text=True, check=True)
assert out.stdout.strip() == "[]"
+
+
+# A made-up repo's symbol table: what `_embedded_identifiers(query, names)`
+# validates tokens against. The name set also answers for each lowered name,
+# which is how a caller turns on the case-insensitive leg.
+_INDEXED = ["executeWithTool", "proxyExecute", "OpenAIProvider", "Session", "refresh", "load_spec"]
+_NAMES = {*_INDEXED, *(n.lower() for n in _INDEXED)}
+
+
+ "query, expected",
+ [
+ # lowerCamel: the shape regex alone misses both.
+ ("how does executeWithTool call proxyExecute", ["executeWithTool", "proxyExecute"]),
+ # Acronym inside a CamelCase name.
+ ("where is OpenAIProvider defined", ["OpenAIProvider"]),
+ # Dotted: the chain counts when its last part names a symbol.
+ ("what does client.proxyExecute return", ["client.proxyExecute"]),
+ ("when is Session.refresh called", ["Session.refresh"]),
+ ("how does load_spec work", ["load_spec"]),
+ # Case-insensitive after case-sensitive, for mixed-case tokens.
+ ("where is openAIProvider", ["openAIProvider"]),
+ # Language and product words name no symbol, so they are not identifiers.
+ ("how does the TypeScript SDK differ from the Python one", []),
+ ("does JavaScript support this", []),
+ # A capitalised sentence word never folds onto a lowercase symbol.
+ ("Refresh the token", []),
+ ],
+)
+def test_embedded_identifiers_validated_against_the_symbol_table(query, expected) -> None:
+ assert _embedded_identifiers(query, _NAMES) == expected
+
+
+def test_a_language_word_is_an_identifier_only_when_a_symbol_carries_it() -> None:
+ assert _embedded_identifiers("how does TypeScript work", {"TypeScript"}) == ["TypeScript"]
+ # Unvalidated, the shape regex keeps its old reading.
+ assert _embedded_identifiers("how does TypeScript work") == ["TypeScript"]
+
+
+def test_resolve_mode_routes_on_validated_identifiers() -> None:
+ assert _resolve_mode("how does executeWithTool work", None, _NAMES) == "hybrid"
+ assert _resolve_mode("how does the TypeScript client work", None, _NAMES) == "concept"
+
+
+ "token",
+ [
+ "executeToolWithRetryBackoff",
+ "getToolkitMigrationPlan",
+ "AnthropicStreamingAdapter",
+ "validate_trigger_nonce",
+ "OpenAIProvider",
+ "MAX_RETRIES",
+ "client.proxyExecute",
+ ],
+)
+def test_code_shaped_names(token) -> None:
+ assert _looks_like_code_name(token)
+
+
+ "token",
+ [
+ "TypeScript",
+ "JavaScript",
+ "GitHub",
+ "PostgreSQL",
+ "iPhone",
+ "macOS",
+ "Python",
+ "API",
+ "AuthService login",
+ ],
+)
+def test_product_and_language_words_are_not_code_shaped(token) -> None:
+ assert not _looks_like_code_name(token)
+
+
+def test_a_module_path_is_not_a_missing_symbol() -> None:
+ paths = ["app/services/mcp_tools/_tools_search.py", "src/client.ts"]
+ assert _names_a_path("app.services.mcp_tools", paths)
+ assert _names_a_path("_tools_search", paths)
+ assert not _names_a_path("validate_trigger_nonce", paths)
+
+
+def test_pages_for_a_missing_symbol_are_labelled_and_capped() -> None:
+ items = [{"confidence_score": 0.9}, {"confidence_score": 0.2}, {}]
+ _mark_not_the_named_symbol(items)
+ assert {item["relation"] for item in items} == {"related, not the named symbol"}
+ assert [item.get("confidence_score") for item in items] == [0.45, 0.2, None]