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(mcp): name the nearest symbols when a get_context target misses (#3638)

Swati Ahuja5ecbe7d7469a
diff --git a/docs/reference/MCP_RESPONSE_FIELDS.md b/docs/reference/MCP_RESPONSE_FIELDS.md
index 554a85d7a..4f6744086 100644
--- a/docs/reference/MCP_RESPONSE_FIELDS.md
+++ b/docs/reference/MCP_RESPONSE_FIELDS.md
@@ -153,6 +153,7 @@ Per target, under `targets`:
| decisions | Titles by default. With `include=["decisions"]`, three lanes: `decisions` (accepted, governing), `candidates` (proposed, at most 3), `history` (accepted then withdrawn, at most 2) |
| `file_preview` | For a file with no indexed symbols: `lines`, `chars`, and for a markdown or reST document `heading_count` with the first three `headings`; otherwise the first three non-empty lines as `head` |
| `resolved_to`, `note` | A `path::Name` target whose symbol did not resolve answers with the file's card instead |
+| `did_you_mean` | On a symbol miss: up to five ids of the closest-named symbols (in that file when the file is real, else repo-wide), omitted when none is close |
| `cross_repo` | Workspace mode: `co_changes_with` partners in other repos and contract `consumers` / `providers` |
| `*_basis` | Beside an empty `callers`, `callees` or `used_by`: the language, how many call edges the index resolved for it, and the share that are guesses. An empty list means no resolved edge, not proof of none |
@@ -162,7 +163,7 @@ Opt-in blocks: `full_doc`, `ownership` (primary owner, bus factor, contributor c
**doc_drift.** `references` lists documents that name this file and still resolve to it. `documents_with_drift` says a listed document carries some assertion that no longer holds, anywhere in it, not necessarily about this file. Do not merge the two claims. `references_basis` states the limits; documents dropped by exclude rules are counted in `references_excluded`. An answer the store cannot support is a refusal: `{"unavailable": "not_computed"}` (the pass has not run yet), `"index_predates_doc_drift"`, or `"drift_read_failed"`.
-**Several targets under one budget.** Each target gets an equal share, and a small target's unused share passes to the others. A target over its share drops symbols first, then its optional blocks largest first (named in `dropped_blocks`). Miss `suggestions` and ambiguity `candidates` are never shed. When even the identity cards cannot all fit, whole targets go first; the response leads with `dropped_targets` and a `recovery` call narrowed to them.
+**Several targets under one budget.** Each target gets an equal share, and a small target's unused share passes to the others. A target over its share drops symbols first, then its optional blocks largest first (named in `dropped_blocks`). Miss `suggestions`, `did_you_mean` and ambiguity `candidates` are never shed. When even the identity cards cannot all fit, whole targets go first; the response leads with `dropped_targets` and a `recovery` call narrowed to them.
---
diff --git a/packages/server/src/repowise/server/mcp_server/_budget/budgeter.py b/packages/server/src/repowise/server/mcp_server/_budget/budgeter.py
index fe9aa4b92..d555c201b 100644
--- a/packages/server/src/repowise/server/mcp_server/_budget/budgeter.py
+++ b/packages/server/src/repowise/server/mcp_server/_budget/budgeter.py
@@ -411,6 +411,7 @@ _TARGET_IDENTITY_KEYS = frozenset(
"path",
"error",
"suggestions",
+ "did_you_mean",
"docs",
"parent_page",
"freshness",
diff --git a/packages/server/src/repowise/server/mcp_server/_symbol_lookup.py b/packages/server/src/repowise/server/mcp_server/_symbol_lookup.py
index d18c1cd8e..86dcd517a 100644
--- a/packages/server/src/repowise/server/mcp_server/_symbol_lookup.py
+++ b/packages/server/src/repowise/server/mcp_server/_symbol_lookup.py
@@ -17,8 +17,12 @@ matched as given, since ``.`` and ``/`` are meaningful inside them.
from __future__ import annotations
-from sqlalchemy import or_, select
+import difflib
+from typing import Any
+from sqlalchemy import func, or_, select
+
+from repowise.core.exclusion import is_excluded
from repowise.core.ingestion.symbol_identity import (
base_symbol_id,
id_segment_name,
@@ -317,3 +321,128 @@ def _pathless_qualified_name(symbol_id: str) -> str | None:
return None
dotted = name_variants(base)[0] if base else ""
return dotted if "." in dotted else None
+
+
+
+#: How many "did you mean" ids a missed target carries.
+NEAREST_LIMIT = 5
+#: ``difflib.get_close_matches`` cutoff. A ratio is 2*M/(a+b) with M <= the
+#: shorter length, so a name outside [3a/7, 7a/3] of the query's length ``a``
+#: can never pass it; the pools below filter on that window in SQL.
+_NEAREST_CUTOFF = 0.6
+#: Backstop caps for a repo-wide miss. Names are read closest length first,
+#: so the cap drops the least likely names; past it a match is missed (a
+#: trigram index on ``name`` is the upgrade). Rows are capped the same way;
+#: a file-scoped miss reads every symbol of the one file.
+_NEAREST_NAME_POOL = 2000
+_NEAREST_ROW_POOL = 500
+#: Pages of ``_NEAREST_ROW_POOL`` rows read while excluded files fill them. A
+#: pathspec has no SQL form, so exclusion runs here; past this many pages a
+#: match behind excluded rows is missed.
+_NEAREST_MAX_PAGES = 10
+
+
+def _length_window(n: int) -> tuple[int, int]:
+ # [ceil(3n/7), floor(7n/3)] for the 0.6 cutoff, in integers so a boundary
+ # length (n=7 allows 3) is not lost to float rounding.
+ return (3 * n + 6) // 7, 7 * n // 3
+
+
+async def _close_values(session, column, query: str, *where) -> list[str]:
+ """Values of ``column`` close to ``query``, from a bounded SQL pool.
+
+ The pool is values sharing the query's first letter in either case
+ (``lower()`` on both sides, so SQLite and PostgreSQL agree) inside the
+ length window, closest length first.
+ """
+ lo, hi = _length_window(len(query))
+ res = await session.execute(
+ select(column)
+ .where(
+ *where,
+ func.lower(column).like(f"{escape_like(query[0].lower())}%", escape=LIKE_ESCAPE),
+ func.length(column).between(lo, hi),
+ )
+ .group_by(column)
+ .order_by(func.abs(func.length(column) - len(query)), column)
+ .limit(_NEAREST_NAME_POOL)
+ )
+ values = [v for v in res.scalars().all() if v]
+ return difflib.get_close_matches(query, values, n=NEAREST_LIMIT, cutoff=_NEAREST_CUTOFF)
+
+
+async def _allowed_rows(session, stmt, exclude_spec: Any, *, capped: bool) -> list:
+ """Rows of ``stmt`` outside excluded files; with ``capped``, up to the row pool.
+
+ The cap counts allowed rows, so excluded ones cannot fill it: pages are
+ read until it is met or the rows run out, at most ``_NEAREST_MAX_PAGES``.
+ """
+ if not capped:
+ res = await session.execute(stmt)
+ return [r for r in res.all() if not is_excluded(r.file_path, exclude_spec)]
+ rows: list = []
+ for page_no in range(_NEAREST_MAX_PAGES):
+ res = await session.execute(
+ stmt.limit(_NEAREST_ROW_POOL).offset(page_no * _NEAREST_ROW_POOL)
+ )
+ page = res.all()
+ rows += [r for r in page if not is_excluded(r.file_path, exclude_spec)]
+ if len(page) < _NEAREST_ROW_POOL or len(rows) >= _NEAREST_ROW_POOL:
+ break
+ return rows[:_NEAREST_ROW_POOL]
+
+
+async def nearest_symbol_ids(
+ session,
+ repo_id: str,
+ query: str,
+ file_path: str | None = None,
+ exclude_spec: Any = None,
+) -> list[str]:
+ """Up to five symbol ids whose names read closest to ``query``, best first.
+
+ ``query`` is the name a target missed (``sned``, ``Clinet.send``). With
+ ``file_path`` the pool is that file's symbols, else names repo-wide; a
+ qualified query (``Clinet.send``) also narrows by the closest parent
+ names, so a common method name cannot crowd out the class asked for.
+ Each candidate is compared on as many trailing qualified-name segments
+ as the query has; symbols in files ``exclude_spec`` matches are never
+ offered. Empty when nothing is close.
+ """
+ dotted = name_variants(query)[0] if query else ""
+ bare = bare_name(dotted)
+ if not bare:
+ return []
+ where = [WikiSymbol.repository_id == repo_id]
+ if file_path:
+ where.append(WikiSymbol.file_path == file_path)
+ else:
+ close = await _close_values(session, WikiSymbol.name, bare, *where)
+ if not close:
+ return []
+ where.append(WikiSymbol.name.in_(close))
+ qualifier = dotted.rsplit(".", 2)[-2] if "." in dotted else ""
+ if qualifier:
+ parents = await _close_values(session, WikiSymbol.parent_name, qualifier, *where)
+ if parents:
+ where.append(WikiSymbol.parent_name.in_(parents))
+ stmt = (
+ select(
+ WikiSymbol.symbol_id,
+ WikiSymbol.name,
+ WikiSymbol.qualified_name,
+ WikiSymbol.file_path,
+ )
+ .where(*where)
+ .order_by(WikiSymbol.symbol_id)
+ )
+ rows = await _allowed_rows(session, stmt, exclude_spec, capped=not file_path)
+ depth = dotted.count(".") + 1
+ by_key: dict[str, list[str]] = {}
+ for sid, name, qualified, _path in rows:
+ key = ".".join(_dotted(qualified or name).split(".")[-depth:])
+ by_key.setdefault(key, []).append(sid)
+ keys = difflib.get_close_matches(
+ dotted, list(by_key), n=NEAREST_LIMIT, cutoff=_NEAREST_CUTOFF
+ )
+ return [sid for key in keys for sid in by_key[key]][:NEAREST_LIMIT]
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/targets.py b/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
index 2306f5478..b272b449f 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
@@ -58,7 +58,11 @@ from repowise.server.mcp_server._helpers import (
from repowise.server.mcp_server._index_state import index_state_key
from repowise.server.mcp_server._meta import uncommitted_targets
from repowise.server.mcp_server._references import path_identity, symbol_identity
-from repowise.server.mcp_server._symbol_lookup import resolve_symbol_rows, symbol_id_variants
+from repowise.server.mcp_server._symbol_lookup import (
+ nearest_symbol_ids,
+ resolve_symbol_rows,
+ symbol_id_variants,
+)
from repowise.server.mcp_server.tool_context.enrichment import (
_DOC_DRIFT_PATH,
_resolve_call_graph,
@@ -105,6 +109,32 @@ def _kind_rank(kind: str | None) -> int:
return 0 if kind in _TYPE_KINDS else 1 if kind in _CALLABLE_KINDS else 2
+async def _did_you_mean(
+ session: AsyncSession,
+ repo_id: str,
+ target: str,
+ file_path: str | None = None,
+ exclude_spec: Any = None,
+) -> dict[str, list[str]]:
+ """``{"did_you_mean": [...]}``: the nearest symbol ids to a missed name, or ``{}``.
+
+ The missed name follows the file head when ``file_path`` is given or the
+ head is a path (``src/a.py::sned``), else it is the whole target
+ (``Clinet.send``, ``httpx.Client::send``); a plain path has none. A path
+ has a separator, as in ``resolve_symbol_rows``' path-less rung.
+ """
+ head, sep, tail = target.partition("::")
+ path_head = any(c in head for c in "/\\")
+ if file_path or (sep and path_head):
+ query = tail
+ elif path_head:
+ return {}
+ else:
+ query = target
+ ids = await nearest_symbol_ids(session, repo_id, query, file_path, exclude_spec)
+ return {"did_you_mean": [symbol_identity(sid) for sid in ids]} if ids else {}
+
+
async def _compact_symbol_rows(
session: AsyncSession, repo_id: str, file_path: str, symbols: Any
) -> list[dict[str, Any]]:
@@ -638,12 +668,13 @@ async def _resolve_one_target(
file_part = target.split("::", 1)[0]
if file_part and file_part != target and not is_excluded(file_part, exclude_spec):
# file_part contains no "::", so this recursion is depth-1. The
- # caller is hunting for a name, so the symbol list is uncapped.
+ # caller is hunting for a name: ``did_you_mean`` picks the
+ # closest from every symbol of the file, so the list keeps its cap.
card = await _resolve_one_target(
session,
repository,
file_part,
- None if include is None else include | {"symbols"},
+ include,
compact,
exclude_spec=exclude_spec,
repo_root=repo_root,
@@ -655,10 +686,16 @@ async def _resolve_one_target(
if "error" not in card and card.get("type") == "file":
card["target"] = target
card["resolved_to"] = file_part
+ nearest = await _did_you_mean(session, repo_id, target, file_part)
+ card.update(nearest)
card["note"] = (
f"No symbol matched {target.split('::', 1)[1]!r} in this file; "
- f"showing the card for {file_part!r} instead. Pick the symbol "
- "you meant from the symbol list."
+ f"showing the card for {file_part!r} instead. "
+ + (
+ "Closest names are in did_you_mean."
+ if nearest
+ else "Pass include=['symbols'] for the full symbol list."
+ )
)
return card
@@ -689,13 +726,11 @@ async def _resolve_one_target(
)
suggestions = [row[0] for row in res.all() if row[0] != target]
suggestions = filter_path_list(suggestions, exclude_spec)
+ miss: dict[str, Any] = {"target": target, "error": f"Target not found: '{target}'"}
if suggestions:
- return {
- "target": target,
- "error": f"Target not found: '{target}'",
- "suggestions": suggestions,
- }
- return {"target": target, "error": f"Target not found: '{target}'"}
+ miss["suggestions"] = suggestions
+ miss.update(await _did_you_mean(session, repo_id, target, exclude_spec=exclude_spec))
+ return miss
result_data["target"] = target
result_data["type"] = target_type
diff --git a/tests/unit/server/mcp/test_context_symbol_card.py b/tests/unit/server/mcp/test_context_symbol_card.py
index e847533ee..202e43a7c 100644
--- a/tests/unit/server/mcp/test_context_symbol_card.py
+++ b/tests/unit/server/mcp/test_context_symbol_card.py
@@ -120,10 +120,15 @@ async def test_symbol_id_dropped_only_when_derivable(session, repository, dense_
assert len(plain) == 26
-async def test_unresolved_symbol_degrade_lists_every_symbol(
+async def test_unresolved_symbol_degrade_names_the_nearest_symbols(
session, repository, dense_file
) -> None:
- """The caller is hunting for a name, so the fallback card is uncapped."""
- card = await _card(session, repository, f"{_FILE}::Missing")
+ """The card keeps its cap; ``did_you_mean`` searches every symbol of the file.
+
+ ``VAR_17`` ranks past the 15-row cut, so only a whole-file search finds it.
+ """
+ card = await _card(session, repository, f"{_FILE}::VAR_17x")
assert card["resolved_to"] == _FILE
- assert len(card["docs"]["symbols"]) == 28
+ assert len(card["docs"]["symbols"]) == _SYMBOL_CAP
+ assert card["did_you_mean"][0] == f"{_FILE}::VAR_17"
+ assert len(card["did_you_mean"]) == 5
diff --git a/tests/unit/server/mcp/test_did_you_mean.py b/tests/unit/server/mcp/test_did_you_mean.py
new file mode 100644
index 000000000..bc8f59da1
--- /dev/null
+++ b/tests/unit/server/mcp/test_did_you_mean.py
@@ -0,0 +1,185 @@
+"""A missed symbol target names the closest real ids (``did_you_mean``).
+
+A mistyped name in a real file degrades to the file card; a full miss keeps
+its path suggestions. Both carry at most five nearest symbol ids, and none
+when nothing is close.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from repowise.core.persistence.models import GraphNode, Repository, WikiSymbol
+from repowise.server.mcp_server import _symbol_lookup
+from repowise.server.mcp_server._symbol_lookup import _length_window
+from repowise.server.mcp_server.tool_context.targets import _resolve_one_target
+
+_CLIENT = "httpx/_client.py"
+
+
+async def repository(session, populated_db) -> Repository:
+ repo = await session.get(Repository, populated_db)
+ session.add(
+ GraphNode(repository_id=repo.id, node_id=_CLIENT, node_type="file", language="python")
+ )
+ names = ["send", "close", "stream", "request", "build_request", "get", "post"]
+ names += [f"helper_{i}" for i in range(12)]
+ for line, name in enumerate(names, 1):
+ tail = name if name.startswith("helper") else f"Client::{name}"
+ session.add(
+ WikiSymbol(
+ repository_id=repo.id,
+ file_path=_CLIENT,
+ symbol_id=f"{_CLIENT}::{tail}",
+ name=name,
+ qualified_name=f"httpx._client.{tail.replace('::', '.')}",
+ parent_name=None if name.startswith("helper") else "Client",
+ kind="function" if name.startswith("helper") else "method",
+ signature=name,
+ start_line=line,
+ end_line=line,
+ language="python",
+ )
+ )
+ await session.flush()
+ return repo
+
+
+async def _card(session, repository, target) -> dict:
+ return await _resolve_one_target(session, repository, target, None, True, exclude_spec=None)
+
+
+async def test_a_mistyped_name_in_a_real_file_suggests_the_symbol(session, repository) -> None:
+ card = await _card(session, repository, f"{_CLIENT}::sned")
+ assert card["resolved_to"] == _CLIENT
+ assert card["did_you_mean"][0] == f"{_CLIENT}::Client::send"
+
+
+async def test_a_file_with_many_close_symbols_names_at_most_five(session, repository) -> None:
+ card = await _card(session, repository, f"{_CLIENT}::helper_x")
+ assert card["resolved_to"] == _CLIENT
+ assert 0 < len(card["did_you_mean"]) <= 5
+ assert all("helper_" in sid for sid in card["did_you_mean"])
+
+
[email protected]("target", ["Clinet.send", "Clinet::send", "missing/a.py::sned"])
+async def test_a_full_miss_suggests_the_symbol(session, repository, target) -> None:
+ card = await _card(session, repository, target)
+ assert card["error"].startswith("Target not found")
+ assert card["did_you_mean"][0] == f"{_CLIENT}::Client::send"
+
+
[email protected]("target", [f"{_CLIENT}::zzqx", "Qwxz.zzqx", "nowhere/zzqx.py"])
+async def test_nothing_close_suggests_nothing(session, repository, target) -> None:
+ card = await _card(session, repository, target)
+ assert "did_you_mean" not in card
+
+
+async def test_the_degrade_note_names_did_you_mean_only_when_present(session, repository) -> None:
+ close = await _card(session, repository, f"{_CLIENT}::sned")
+ assert "did_you_mean" in close["note"]
+ far = await _card(session, repository, f"{_CLIENT}::zzqx")
+ assert "did_you_mean" not in far["note"]
+ assert "include=['symbols']" in far["note"]
+
+
+def test_the_length_window_is_exactly_what_the_cutoff_allows() -> None:
+ """A length outside the window can never reach ratio 0.6; one inside can."""
+ for n in range(1, 40):
+ lo, hi = _length_window(n)
+ for m in range(1, 120):
+ assert (lo <= m <= hi) == (2 * min(n, m) / (n + m) >= 0.6), (n, m)
+
+
+def _method(repo_id: str, path: str, parent: str, name: str) -> WikiSymbol:
+ return WikiSymbol(
+ repository_id=repo_id,
+ file_path=path,
+ symbol_id=f"{path}::{parent}::{name}",
+ name=name,
+ qualified_name=f"{path[:-3].replace('/', '.')}.{parent}.{name}",
+ parent_name=parent,
+ kind="method",
+ signature=name,
+ start_line=1,
+ end_line=2,
+ language="python",
+ )
+
+
+async def test_the_name_pool_reads_close_lengths_first(
+ session, repository, monkeypatch
+) -> None:
+ """Short ``s*`` names sort first but cannot match ``sned_request``."""
+ monkeypatch.setattr(_symbol_lookup, "_NEAREST_NAME_POOL", 2)
+ for decoy in ("sa", "sab", "sabc", "sb"):
+ session.add(_method(repository.id, "a/decoy.py", "D", decoy))
+ session.add(_method(repository.id, "z/api.py", "Api", "send_request"))
+ await session.flush()
+ card = await _card(session, repository, "sned_request")
+ assert card["did_you_mean"] == ["z/api.py::Api::send_request"]
+
+
+async def test_a_qualified_miss_prefers_the_closest_class(
+ session, repository, monkeypatch
+) -> None:
+ """Many ``send`` methods sort before ``httpx/``; the parent narrows first."""
+ monkeypatch.setattr(_symbol_lookup, "_NEAREST_ROW_POOL", 3)
+ for i in range(10):
+ session.add(_method(repository.id, f"a/x{i}.py", f"Sender{i}", "send"))
+ await session.flush()
+ for target in ("Clinet.send", "httpx.Clinet::send"):
+ card = await _card(session, repository, target)
+ assert card["did_you_mean"][0] == f"{_CLIENT}::Client::send", target
+
+
+async def test_a_full_miss_never_suggests_an_excluded_file(session, repository) -> None:
+ import pathspec
+
+ excluded = pathspec.PathSpec.from_lines("gitwildmatch", ["httpx/*"])
+ card = await _resolve_one_target(
+ session, repository, "Clinet.send", None, True, exclude_spec=excluded
+ )
+ assert card["error"].startswith("Target not found")
+ assert "did_you_mean" not in card
+
+
+async def test_a_big_file_is_searched_whole(session, repository) -> None:
+ """600 symbols sort before the match; a capped read would never see it."""
+ big = "big.py"
+ session.add(GraphNode(repository_id=repository.id, node_id=big, node_type="file"))
+ names = [f"aaa_{i:03}" for i in range(600)] + ["zebra_handler"]
+ for line, name in enumerate(names, 1):
+ session.add(
+ WikiSymbol(
+ repository_id=repository.id,
+ file_path=big,
+ symbol_id=f"{big}::{name}",
+ name=name,
+ qualified_name=f"big.{name}",
+ kind="function",
+ signature=name,
+ start_line=line,
+ end_line=line,
+ language="python",
+ )
+ )
+ await session.flush()
+ card = await _card(session, repository, f"{big}::zebra_handlr")
+ assert card["did_you_mean"] == [f"{big}::zebra_handler"]
+
+
+async def test_excluded_rows_do_not_fill_the_row_pool(session, repository, monkeypatch) -> None:
+ """Excluded ``send`` methods sort first; the allowed one is still reached."""
+ import pathspec
+
+ monkeypatch.setattr(_symbol_lookup, "_NEAREST_ROW_POOL", 3)
+ for i in range(10):
+ session.add(_method(repository.id, f"a/x{i}.py", "Client", "send"))
+ await session.flush()
+ excluded = pathspec.PathSpec.from_lines("gitwildmatch", ["a/*"])
+ card = await _resolve_one_target(
+ session, repository, "Clinet.send", None, True, exclude_spec=excluded
+ )
+ assert card["did_you_mean"] == [f"{_CLIENT}::Client::send"]