Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
fix(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.mdindex 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.pyindex 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.pyindex 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_excludedfrom 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 Nonedotted = 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.pyindex 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_keyfrom repowise.server.mcp_server._meta import uncommitted_targetsfrom 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"] = targetcard["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 missresult_data["target"] = targetresult_data["type"] = target_typediff --git a/tests/unit/server/mcp/test_context_symbol_card.py b/tests/unit/server/mcp/test_context_symbol_card.pyindex 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"]) == 5diff --git a/tests/unit/server/mcp/test_did_you_mean.py b/tests/unit/server/mcp/test_did_you_mean.pynew file mode 100644index 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"]