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(answer): spend the per-file symbol budget on the question, not the top of the file (#1597)
Raghav Chamadiya201af9298afe
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py b/packages/server/src/repowise/server/mcp_server/tool_answer/answer.pyindex 0fbf134c0..2a1454f99 100644--- a/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py@@ -342,7 +342,7 @@ async def _run_retrieval_pipeline(with contextlib.suppress(Exception):async with get_session(ctx.session_factory) as session:await _hydrate_symbols_for_hits(- session, repo_id, hits, ctx, question_ids=question_ids+ session, repo_id, hits, ctx, question_ids=question_ids, question=question)# And the shortlist BELOW the synthesis cap: `candidates` names# those files and, until now, said nothing about any of them.diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/config.py b/packages/server/src/repowise/server/mcp_server/tool_answer/config.pyindex 5c674ec1f..62ec72411 100644--- a/packages/server/src/repowise/server/mcp_server/tool_answer/config.py+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/config.py@@ -32,6 +32,26 @@ _MAX_SYMBOLS_PER_HIT = 4_MATCHED_SYMBOL_DOC_CHARS = 400_MATCHED_SYMBOL_SOURCE_LINES = 40+# Which symbols survive the per-file cap. A `start_line` tiebreak served a+# document-order prefix, so on a file larger than its symbol budget the symbol+# the question was about could not be reached at all. Scoring the already-loaded+# name / signature / docstring against the question's content terms changes which+# symbols fill the same budget, not how many: no extra I/O, no prompt growth.+# A name hit outranks a signature hit outranks a mention in the docstring. With+# no signal every score is 0 and the sort falls back to `start_line` as before.+_RELEVANCE_NAME_WEIGHT = 3+_RELEVANCE_SIG_WEIGHT = 2+_RELEVANCE_DOC_WEIGHT = 1+# Score the docstring's opening prose only, so a long one can't out-score a+# precise name on word count alone.+_RELEVANCE_DOC_CHARS = 400+# A source excerpt used to require a question IDENTIFIER match, so a question+# phrased in prose reached the right symbols and then showed only their+# signatures — the "excerpts don't include the actual code" answer. The leading+# few symbols the question scored against get a body too. Bounded hard: this is+# the one part of the change that adds prompt text.+_RELEVANT_EXCERPT_MAX_SYMBOLS = 2+# How many question-named symbol bodies get_answer inlines in `symbol_bodies`.# The hydrator already reads these bodies live for synthesis; surfacing them# in the response collapses the get_answer -> get_symbol drill-down ondiff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py b/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.pyindex af134eafb..43e163163 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 sqlalchemy import selectfrom repowise.core.persistence.models import WikiSymbolfrom repowise.server.mcp_server._page_paths import hit_file_path+from repowise.server.mcp_server._query_terms import content_terms, split_humpsfrom repowise.server.mcp_server._verify import verify_and_healfrom repowise.server.mcp_server.tool_answer.config import (_DEFINES_MAX_FILES,@@ -29,12 +30,99 @@ from repowise.server.mcp_server.tool_answer.config import (_MAX_RICH_SIG_LINES,_MAX_SYMBOLS_PER_HIT,_MAX_SYMBOLS_TOP_HIT,+ _RELEVANCE_DOC_CHARS,+ _RELEVANCE_DOC_WEIGHT,+ _RELEVANCE_NAME_WEIGHT,+ _RELEVANCE_SIG_WEIGHT,+ _RELEVANT_EXCERPT_MAX_SYMBOLS,_STOPWORDS,_SYNTH_FULL_BODY_MAX_SYMBOLS,_SYNTH_FULL_SOURCE_LINES,)from repowise.server.mcp_server.tool_search import _prose_dominates+# Suffixes stripped so a question's word reaches the identifier that answers it+# ("routing" -> the `route` symbol). Longest first; never stems below 4 chars.+_STEM_SUFFIXES = ("tion", "ing", "ion", "es", "ed", "er", "s")+++def _stem(token: str) -> str:+ for suffix in _STEM_SUFFIXES:+ if token.endswith(suffix) and len(token) - len(suffix) >= 4:+ return token[: -len(suffix)]+ return token+++def _text_stems(text: str) -> set[str]:+ """Stemmed content tokens of *text*, hump- and separator-split."""+ return {+ _stem(tok.lower())+ for tok in re.split(r"[^A-Za-z0-9]+", split_humps(text))+ if len(tok) >= 3 and tok.lower() not in _STOPWORDS+ }+++def _stem_hit(term: str, tokens: set[str]) -> bool:+ """Whether *term* names one of *tokens*, allowing a shared 4-char root."""+ if term in tokens:+ return True+ return any(+ min(len(term), len(tok)) >= 4 and (term.startswith(tok) or tok.startswith(term))+ for tok in tokens+ )+++def _question_names_symbol(row, qids_lower: set[str]) -> bool:+ """Whether an identifier from the question names this symbol.++ Substring-matching the whole qualified name marked every symbol in a package+ whose path shares a word with the question, which flattened the promotion to+ a no-op. Matching is against the symbol's own name, its full qualified name,+ or its parent: asking about a class should still reach its methods.+ """+ if not qids_lower:+ return False+ name_lower = (row.name or "").lower()+ parent_lower = (row.parent_name or "").lower()+ return (+ name_lower in qids_lower+ or (row.qualified_name or "").lower() in qids_lower+ or (bool(parent_lower) and parent_lower in qids_lower)+ or any(+ q in name_lower+ for q in qids_lower+ if len(q) >= 5 # avoid spurious substring matches on short tokens+ )+ )+++def _symbol_relevance(entry: dict, terms: set[str]) -> int:+ """How strongly a symbol's own text answers the question's content terms.++ Reads only what hydration already loaded, so it adds no I/O to the call.+ """+ if not terms:+ return 0+ name_tokens = _text_stems(entry.get("name") or "")+ sig_tokens = _text_stems(entry.get("signature") or "")+ # Docstrings are the bulk of the text to tokenize and the weakest signal, so+ # they are only read once a term has missed the name and the signature.+ doc_tokens: set[str] | None = None+ score = 0+ for term in terms:+ if _stem_hit(term, name_tokens):+ score += _RELEVANCE_NAME_WEIGHT+ elif _stem_hit(term, sig_tokens):+ score += _RELEVANCE_SIG_WEIGHT+ else:+ if doc_tokens is None:+ doc_tokens = _text_stems(+ (entry.get("docstring") or "")[:_RELEVANCE_DOC_CHARS]+ )+ if _stem_hit(term, doc_tokens):+ score += _RELEVANCE_DOC_WEIGHT+ return score+def _extract_question_identifiers(question: str) -> set[str]:"""Pull out Python-looking identifiers the question names explicitly.@@ -774,6 +862,7 @@ async def _hydrate_symbols_for_hits(hits: list[dict],ctx: Any = None,question_ids: set[str] | None = None,+ question: str = "",) -> None:"""Mutate `hits` in place: attach `symbols` list to top-N file_page hits.@@ -788,10 +877,16 @@ async def _hydrate_symbols_for_hits(Top hit gets ``_MAX_SYMBOLS_TOP_HIT`` slots; secondaries get the smaller``_MAX_SYMBOLS_PER_HIT``. Symbols not matching a question id carry theshort 120-char docstring; matched symbols carry 400 chars + source body.++ ``question`` decides which symbols fill those slots when the file holds more+ than fit, and earns the leading few a source body: a question phrased in+ prose names no identifier, so nothing matches and nothing would carry code."""question_ids = question_ids or set()# Case-folded copy for matching.qids_lower = {q.lower() for q in question_ids}+ # Once per call: the question's terms, stemmed to match identifier roots.+ term_stems = {_stem(t) for t in content_terms(question)}# Identify the top file_page hits in retrieval-rank order. `hits` is# already sorted by descending score upstream.@@ -845,21 +940,7 @@ async def _hydrate_symbols_for_hits(rich_sig = _read_signature_from_source(repo_root, row.file_path, start_line, text=text)- # Does the symbol name match any identifier from the question?- name_lower = (row.name or "").lower()- qname_lower = (row.qualified_name or "").lower()- matched = bool(- qids_lower- and (- name_lower in qids_lower- or qname_lower in qids_lower- or any(- q in name_lower or q in qname_lower- for q in qids_lower- if len(q) >= 5 # avoid spurious substring matches on short tokens- )- )- )+ matched = _question_names_symbol(row, qids_lower)entry: dict[str, Any] = {"name": row.name,"kind": row.kind,@@ -868,7 +949,11 @@ async def _hydrate_symbols_for_hits("start_line": start_line,"end_line": end_line,"_matched": matched,+ "_verified": verified,}+ # Scored once here, not in the sort key, so a dense file pays for it per+ # symbol rather than per comparison.+ entry["_relevance"] = _symbol_relevance(entry, term_stems)if matched and verified:src = _read_symbol_source(repo_root, row.file_path, start_line, end_line, text=text@@ -877,15 +962,16 @@ async def _hydrate_symbols_for_hits(entry["source_excerpt"] = srcby_file.setdefault(row.file_path, []).append(entry)- # Sort: matched symbols first (document order within the match group),- # then unmatched in start_line order. Cap per file — top hit gets more- # slots than secondary hits.+ # Sort: matched symbols first, then by relevance to the question, then in+ # start_line order. Cap per file — top hit gets more slots than secondary+ # hits. This decides WHICH symbols are kept; the kept slice is put back into+ # reading order below, so consumers still see document order.for i, h in enumerate(hits):path = h.get("target_path")if path not in by_file:continuesyms = by_file[path]- syms.sort(key=lambda s: (not s["_matched"], s["start_line"]))+ syms.sort(key=lambda s: (not s["_matched"], -s["_relevance"], s["start_line"]))cap = _MAX_SYMBOLS_TOP_HIT if i == 0 else _MAX_SYMBOLS_PER_HIT# Force-include the exact symbol the question named (via anchoring) so a# class-name flood — where every sibling method "matches" through the@@ -903,6 +989,26 @@ async def _hydrate_symbols_for_hits(if len(kept) >= cap:breakkept.append(s)+ # A prose question names no identifier, so nothing is `_matched` and the+ # slate would carry signatures only. Give the leading few symbols the+ # question scored against a body, so the excerpts hold the code the+ # question is about. `kept` is still in priority order here.+ bodied = 0+ for s in kept:+ if bodied >= _RELEVANT_EXCERPT_MAX_SYMBOLS:+ break+ if s.get("source_excerpt") or not s["_relevance"] or not s["_verified"]:+ continue+ src = _read_symbol_source(+ repo_root,+ path,+ s["start_line"],+ s.get("end_line") or 0,+ text=text_cache.get(path),+ )+ if src:+ s["source_excerpt"] = src+ bodied += 1# Upgrade the top question-relevant symbols to the inline-body depth# BEFORE the reading-order sort, while `kept` is still in priority order# (anchors, then matched, then unmatched). The default 40-line excerptdiff --git a/tests/unit/server/mcp/test_answer_symbol_relevance.py b/tests/unit/server/mcp/test_answer_symbol_relevance.pynew file mode 100644index 000000000..31fc19a4e--- /dev/null+++ b/tests/unit/server/mcp/test_answer_symbol_relevance.py@@ -0,0 +1,116 @@+"""Calibration: the per-file symbol budget must go to the question, not the top.++A file with more symbols than its budget used to serve a document-order prefix,+so on a large file the symbol the question was actually about could not be+reached at all — the more code the file held, the smaller the served fraction+and the stronger the top-of-file bias. The budget is unchanged; what fills it+is now scored against the question's content terms.+"""++from __future__ import annotations++from types import SimpleNamespace++from repowise.core.persistence.models import WikiSymbol+from repowise.server.mcp_server.tool_answer.config import _MAX_SYMBOLS_TOP_HIT+from repowise.server.mcp_server.tool_answer.symbols import _hydrate_symbols_for_hits++# Twice the budget, so half the file cannot be served whatever the ordering.+_SYMBOL_COUNT = _MAX_SYMBOLS_TOP_HIT * 2+_BODY_LINES = 4+++def _write_module(tmp_path, names: list[str]) -> list[int]:+ """One trivial function per name; returns their 1-indexed def lines."""+ lines: list[str] = []+ starts: list[int] = []+ for name in names:+ starts.append(len(lines) + 1)+ lines.append(f"def {name}(request):")+ lines.extend(f" step{i} = {i}" for i in range(_BODY_LINES))+ lines.append(" return request")+ (tmp_path / "app.py").write_text("\n".join(lines) + "\n", encoding="utf-8")+ return starts+++async def _hydrate(session, repo_id, tmp_path, names, question):+ starts = _write_module(tmp_path, names)+ for i, name in enumerate(names):+ session.add(+ WikiSymbol(+ id=f"sym-{i}",+ repository_id=repo_id,+ file_path="app.py",+ symbol_id=f"app.py::{name}",+ name=name,+ qualified_name=f"app.{name}",+ kind="function",+ signature=f"def {name}(request)",+ start_line=starts[i],+ end_line=starts[i] + _BODY_LINES + 1,+ docstring="",+ visibility="public",+ is_async=False,+ complexity_estimate=1,+ language="python",+ parent_name=None,+ )+ )+ await session.commit()+ hits = [{"target_path": "app.py", "page_type": "file_page"}]+ await _hydrate_symbols_for_hits(+ session, repo_id, hits, SimpleNamespace(path=tmp_path), question=question+ )+ return hits[0]["symbols"]+++_ROUTING_NAMES = [f"helper{i}" for i in range(_SYMBOL_COUNT - 1)] + ["find_route"]+_ROUTING_QUESTION = "How does routing work in this app?"+++async def test_late_symbol_named_by_the_question_survives_the_cap(+ session, repo_id, tmp_path+) -> None:+ """The routing code is at the end of the file; the question asks about it."""+ served = await _hydrate(+ session, repo_id, tmp_path, _ROUTING_NAMES, _ROUTING_QUESTION+ )+ names = [s["name"] for s in served]++ assert "find_route" in names, "document order buried the symbol the question named"+ assert len(names) <= _MAX_SYMBOLS_TOP_HIT, "the budget itself must not grow"+++async def test_no_content_term_falls_back_to_document_order(+ session, repo_id, tmp_path+) -> None:+ """With nothing to score, the served slice is the old start_line prefix."""+ names = [f"helper{i}" for i in range(_SYMBOL_COUNT)]+ served = await _hydrate(session, repo_id, tmp_path, names, "How does it work?")++ assert [s["name"] for s in served] == names[:_MAX_SYMBOLS_TOP_HIT]+++async def test_served_slice_stays_in_reading_order(session, repo_id, tmp_path) -> None:+ """Relevance decides what is kept, never what order consumers read it in."""+ served = await _hydrate(+ session, repo_id, tmp_path, _ROUTING_NAMES, _ROUTING_QUESTION+ )+ names = [s["name"] for s in served]++ assert names == sorted(names, key=_ROUTING_NAMES.index)+++async def test_prose_question_still_earns_a_source_body(+ session, repo_id, tmp_path+) -> None:+ """A prose question matches no identifier, so nothing would carry code."""+ served = await _hydrate(+ session, repo_id, tmp_path, _ROUTING_NAMES, _ROUTING_QUESTION+ )+ scored = [s for s in served if s["name"] == "find_route"]++ assert scored and scored[0].get("source_excerpt"), (+ "the symbol the question scored against was served without its body"+ )+ assert not any(s["_matched"] for s in served), "prose names no identifier"