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): constructors, project-name words and module names stop steering retrieval; ruled-out files drop (#3773)
Swati Ahuja6508013500e4
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 15d720d67..71fb8469a 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@@ -196,6 +196,7 @@ from repowise.server.mcp_server.tool_answer.symbols import (_extract_value_answer,_hydrate_candidate_defines,_hydrate_symbols_for_hits,+ drop_ruled_out_files,lead_with_files,place_named_files,)@@ -354,6 +355,7 @@ async def _run_retrieval_pipeline(hits = lead_with_files(hits, traced)if named := _in_scope(issue.named):hits = place_named_files(hits, named)+ hits = drop_ruled_out_files(hits, question)# The pre-cap ranking feeds ``candidates``: files below the synthesis cut# are still the best answer to "where do I look next".resolved_pool = list(hits)diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/callers.py b/packages/server/src/repowise/server/mcp_server/tool_answer/callers.pyindex b727bb17f..f2db30140 100644--- a/packages/server/src/repowise/server/mcp_server/tool_answer/callers.py+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/callers.py@@ -21,6 +21,7 @@ from repowise.core.persistence.models import GraphEdge, GraphNodefrom repowise.core.test_paths import is_test_pathfrom repowise.server.mcp_server._budget import cap_collectionfrom repowise.server.mcp_server._edit_sites import attach_call_text, first_call_line+from repowise.server.mcp_server._graph_files import graph_file_pathsfrom repowise.server.mcp_server._helpers import filter_dicts_by_keyfrom repowise.server.mcp_server._query_shape import _unmistakably_codefrom repowise.server.mcp_server._wrapper_callers import (@@ -29,6 +30,7 @@ from repowise.server.mcp_server._wrapper_callers import (forwarding_wrapper_callers,)from repowise.server.mcp_server.tool_answer.config import _RELEVANCE_NAME_WEIGHT+from repowise.server.mcp_server.tool_answer.hydration import _text_stems_SUBJECT = (r"\b(?:who|which|what)(?:\s+(?:non-test|production|source|other|file|files|function|"@@ -144,7 +146,7 @@ def _qualifier_matches(node: GraphNode, qualifier: str) -> bool:async def _named_targets(- session: AsyncSession, repo_id: str, names: list[str]+ session: AsyncSession, repo_id: str, names: list[str], question: str = "") -> list[GraphNode]:res = await session.execute(select(GraphNode).where(@@ -158,10 +160,15 @@ async def _named_targets(for node in res.scalars().all():if node.file_path and not is_test_path(node.file_path, node.language):by_leaf.setdefault(node.name, []).append(node)+ modules = await _modules_meant(session, repo_id, names, question)out: list[GraphNode] = []for name in names:qualifier, _, leaf = name.rpartition(".")defs = by_leaf.get(leaf, [])+ if leaf in modules:+ paths, rest = modules[leaf]+ # A same-named def elsewhere stays only when its own location is on topic.+ defs = [n for n in defs if n.file_path in paths or rest & _owner_words(n)]# A qualifier that matches no definition drops the name rather than# widening it to every same-named symbol.if qualifier:@@ -171,6 +178,61 @@ async def _named_targets(return out[:_MAX_TARGETS]+async def _modules_meant(+ session: AsyncSession, repo_id: str, names: list[str], question: str+) -> dict[str, tuple[set[str], set[str]]]:+ """Bare names the question uses for a module of that file stem.++ ``symbol_identity`` can be a module and a function in another file. The+ question means the module when the rest of its words name the module's own+ definitions ("how does symbol_identity assign discriminators" names+ ``symbol_discriminator``). Maps each name to the module's files and those+ other words. Lowercase names only: a capitalised one names a type, whose+ file is often named after it.+ """+ files = await _module_files(+ session, repo_id, {n for n in names if "." not in n and n[:1].islower()}+ )+ if not files:+ return {}+ res = await session.execute(+ select(GraphNode.file_path, GraphNode.name).where(+ GraphNode.repository_id == repo_id,+ GraphNode.node_type == "symbol",+ GraphNode.file_path.in_(set().union(*files.values())),+ )+ )+ defined: dict[str, set[str]] = {}+ for path, name in res.all():+ defined.setdefault(path, set()).update(_text_stems(name or ""))+ # The caller phrase ("where is it called") says nothing about the topic.+ topic = _NAMED_CALLER_QUESTION.sub(" ", _CALLER_QUESTION.sub(" ", question))+ out: dict[str, tuple[set[str], set[str]]] = {}+ for name, paths in files.items():+ rest = _text_stems(topic) - _text_stems(name)+ if rest & set().union(*(defined.get(p, set()) for p in paths)):+ out[name] = (paths, rest)+ return out+++async def _module_files(session: AsyncSession, repo_id: str, names: set[str]) -> dict[str, set[str]]:+ """The production files each of *names* is the file stem of."""+ files: dict[str, set[str]] = {}+ if not names:+ return files+ for path in await graph_file_paths(session, repo_id):+ stem = PurePosixPath(path).stem+ if stem in names and not is_test_path(path):+ files.setdefault(stem, set()).add(path)+ return files+++def _owner_words(node: GraphNode) -> set[str]:+ """The words of a def's file name and its own scoped name."""+ local = node.node_id.split("::", 1)[-1]+ return _text_stems(f"{PurePosixPath(node.file_path or '').stem} {local}")++async def _retrieved_targets(session: AsyncSession, repo_id: str, hits: list[dict]) -> list[GraphNode]:@@ -265,7 +327,7 @@ async def caller_evidence(if not is_caller_question(question, question_ids):return NO_EVIDENCEnamed = _named_ids(question_ids)- targets = await _named_targets(session, repo_id, named) if named else []+ targets = await _named_targets(session, repo_id, named, question) if named else []cross_file = not targetsif cross_file:if not _CALLER_QUESTION.search(question):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 5221cca97..6e4e1e5ba 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@@ -307,7 +307,9 @@ _ANSWER_COVERAGE_FLOOR = 0.5# 22: ``confidence`` also asks whether the top hit covers the question's words.# 23: bodies include the function holding a literal the question writes, and an# exact name off the topic no longer anchors its definition; a question-named-# body grounds the answer only when it carries what else was asked.+# body grounds the answer only when it carries what else was asked;+# constructors fold into their class and a file the question rules out is+# dropped._ANSWER_SCHEMA_VERSION = 23# Above this a whole-file Read costs more than the answer, so the low-confidencediff --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 7c63ad2ed..25ef9bb87 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@@ -22,6 +22,7 @@ from repowise.core.test_paths import is_test_related_pathfrom repowise.server.mcp_server._line_hits import production_linesfrom repowise.server.mcp_server._query_shape import (_WORD_CHAIN_RE,+ _folds_case,_identifier_shaped,_looks_like_code_name,)@@ -35,6 +36,7 @@ from repowise.server.mcp_server.tool_answer.config import (_HOMONYM_UNION_BODY_MAX_LINES,_HOMONYM_UNION_CHAR_BUDGET,_HOMONYM_UNION_PROSE_DEF_CEILING,+ _INLINE_BODY_MAX_LINES,_INLINE_BODY_MAX_SYMBOLS,_LITERAL_SCAN_MAX_TOKENS,_SPECIFIC_TOKEN_MAX_FILES,@@ -267,6 +269,7 @@ async def _anchor_symbol_hits(if not row.file_path or row.kind not in _ANCHOR_KINDS:continueby_name.setdefault(row.name, []).append(row)+ by_name = {name: _without_constructors(cands) for name, cands in by_name.items()}# Verify bounds before slicing: union and anchored bodies are served at# high trust, so a drifted row would ground them in the wrong lines.@@ -288,15 +291,16 @@ async def _anchor_symbol_hits(return dliteral: dict[str, list] = {}- if question and repo_root is not None and not is_symbol_lookup_question(question, question_ids):+ prose = bool(question) and not is_symbol_lookup_question(question, question_ids)+ if prose and repo_root is not None:guard = _TopicGuard(repo_root, hits, question, qids_lower)- by_name = await _trusted_over_topic(by_name, qids_lower, guard)+ by_name = await _trusted_over_topic(by_name, question_ids, guard)literal = await _literal_holders(session, repo_id, question_ids - indexed_names, guard)- chosen = await _choose_anchor_symbols(by_name, qids_lower, _verified_dict, homonyms)+ chosen = await _choose_anchor_symbols(by_name, question_ids, _verified_dict, homonyms)if not chosen and not literal:return hits, homonyms- await _anchor_chosen_symbols(hits, chosen, _verified_dict)+ await _anchor_chosen_symbols(hits, chosen, _verified_dict, prose=prose)for token, rows in literal.items():await _anchor_chosen_symbols(hits, rows, _verified_dict, named_by=token)hits.sort(key=lambda h: h.get("score", 0.0), reverse=True)@@ -332,7 +336,9 @@ class _TopicGuard:return self._lines[token]async def trusts(self, token: str, row) -> bool:- if row.file_path in self.topical:+ # A plain capitalised word (``Gson``, ``Client``) is also prose, often the+ # project's own name, so its file ranking high proves nothing.+ if row.file_path in self.topical and _folds_case(token):return True# Before the count: a name only tests write counts zero production files.if is_test_related_path(row.file_path) and not self.about_tests:@@ -346,7 +352,7 @@ class _TopicGuard:async def _trusted_over_topic(- by_name: dict[str, list], qids_lower: set[str], guard: _TopicGuard+ by_name: dict[str, list], question_ids: set[str], guard: _TopicGuard) -> dict[str, list]:"""*by_name* without the defs an exact name may not anchor (see :class:`_TopicGuard`).@@ -357,7 +363,7 @@ async def _trusted_over_topic(trusted = [cfor c in cands- if _question_names_parent(c, qids_lower) or await guard.trusts(name, c)+ if _question_names_parent(c, question_ids) or await guard.trusts(name, c)]if trusted:kept[name] = trusted@@ -416,18 +422,41 @@ def _innermost_holders(defs: list, rows: list[dict]) -> Counter:return held-def _question_names_parent(cand, qids_lower: set[str]) -> bool:- """Whether the question names this def's parent, or a qualifier of it."""- if (cand.parent_name or "").lower() in qids_lower:+def _without_constructors(cands: list) -> list:+ """*cands* without the constructors of a class that is itself among them.++ A constructor shares its class's name, so a question writing ``Gson`` would+ otherwise get the class's overloaded constructors as homonyms of each other,+ each one "named by its parent". The name means the class.+ """+ classes = {(c.file_path, c.name) for c in cands if c.kind in ("class", "interface")}+ return [+ c+ for c in cands+ if not (+ (c.file_path, c.name) in classes+ and (c.parent_name or "").rsplit(".", 1)[-1] == c.name+ )+ ]+++def _question_names_parent(cand, question_ids: set[str]) -> bool:+ """Whether the question names this def's parent, or a qualifier of it.++ A qualifier must be written as code: a plain word (``Java``) also spells a+ directory of the qualified name.+ """+ if (cand.parent_name or "").lower() in {q.lower() for q in question_ids}:return Truequalified = (cand.qualified_name or "").lower()name = (cand.name or "").lower()- return any(q in qualified for q in qids_lower if len(q) >= 4 and q != name)+ code = {q.lower() for q in question_ids if "." in q or _folds_case(q)}+ return any(q in qualified for q in code if len(q) >= 4 and q != name)async def _choose_anchor_symbols(by_name: dict[str, list],- qids_lower: set[str],+ question_ids: set[str],verified_dict: Callable[[Any], Awaitable[dict]],homonyms: dict[str, Any],) -> list:@@ -437,7 +466,7 @@ async def _choose_anchor_symbols(*homonyms* instead, as a union or a qualified miss."""# Qualifiers the question used (dotted forms like ``decisionextractor.extract_all``).- qualifiers = {q for q in qids_lower if "." in q}+ qualifiers = {q.lower() for q in question_ids if "." in q}chosen: list = []for name, cands in by_name.items():if len(cands) == 1:@@ -445,7 +474,7 @@ async def _choose_anchor_symbols(continue# Disambiguate a homonym when the question names its parent or the# parent appears in the qualified name.- narrowed = [c for c in cands if _question_names_parent(c, qids_lower)]+ narrowed = [c for c in cands if _question_names_parent(c, question_ids)]if len(narrowed) == 1:chosen.append(narrowed[0])continue@@ -470,11 +499,14 @@ async def _anchor_chosen_symbols(chosen: list,verified_dict: Callable[[Any], Awaitable[dict]],named_by: str | None = None,+ prose: bool = False,) -> None:"""Boost (or insert) each chosen def's file and stash the def on it.``named_by`` is the identifier the question wrote when the def holds it- rather than being named by it.+ rather than being named by it. On a ``prose`` question a class the inline+ cap would cut is not stashed: its head answers no "how does X do Y", and+ its file still leads."""by_path = {h.get("target_path"): h for h in hits}top_score = max((h.get("score", 0.0) for h in hits), default=0.0)@@ -493,6 +525,13 @@ async def _anchor_chosen_symbols(vd = await verified_dict(sym)if vd.get("_approx"):continue+ # The cap's own test: ``_read_symbol_source`` cuts past start + max_lines.+ if (+ prose+ and sym.kind in ("class", "interface")+ and vd["end_line"] > vd["start_line"] + _INLINE_BODY_MAX_LINES+ ):+ continuetarget.setdefault("_anchor_symbols", []).append({"name": sym.name,@@ -519,6 +558,36 @@ def lead_with_files(hits: list[dict], paths: list[str]) -> list[dict]:return led + [h for h in hits if id(h) not in led_ids]+# "outside foo.py", "other than src/legacy/": a file or directory the question+# rules out. Only a name with an extension or a slash counts, so prose such as+# "outside the loop" rules out nothing.+_RULED_OUT_RE = re.compile(+ r"\b(?:outside(?:\s+of)?|other\s+than|except(?:\s+(?:for|in))?|excluding|besides|"+ r"apart\s+from)\s+(?:the\s+)?[`'\"]?((?:[\w.-]+/)*[\w-]+\.\w+(?!\.?\w)|(?:[\w.-]+/)+)",+ re.IGNORECASE,+)+++def drop_ruled_out_files(hits: list[dict], question: str) -> list[dict]:+ """``hits`` without the files the question explicitly rules out.++ "Which code parses X outside foo.py" asks for everything but foo.py, which+ is also the file its words match best.+ """+ ruled = [m.lower() for m in _RULED_OUT_RE.findall(question)]+ if not ruled:+ return hits++ # Matched as a path suffix, so "pkg/utils.py" rules out only that file. A bare+ # "utils.py" rules out every utils.py: the question gives nothing to tell+ # them apart (ceiling; a ranked pick would need the question's other words).+ def out(path: str) -> bool:+ p = "/" + path.split("::", 1)[0].lower()+ return any(p.endswith("/" + r) if not r.endswith("/") else "/" + r in p for r in ruled)++ return [h for h in hits if not out(h.get("target_path") or "")]++# A file defining a named identifier is a milder signal than a trace frame: it# joins just below the top three, and stays put when it already ranks there._NAMED_FILE_SLOT = 3diff --git a/tests/unit/server/mcp/test_answer_graph_callers.py b/tests/unit/server/mcp/test_answer_graph_callers.pyindex b34b97a7f..82bdd5a53 100644--- a/tests/unit/server/mcp/test_answer_graph_callers.py+++ b/tests/unit/server/mcp/test_answer_graph_callers.py@@ -212,6 +212,48 @@ async def test_qualified_name_keeps_its_qualifier(session, populated_db):assert missed.rows == []+async def test_a_module_name_means_the_module_when_the_question_names_its_defs(+ session, populated_db+):+ """``symbol_identity`` is a module and a function elsewhere; the topic picks one."""+ rid = populated_db+ py = {"language": "python"}+ module = "core/symbol_identity.py"+ session.add_all(+ [+ GraphNode(+ id=f"gc_{module}", repository_id=rid, node_id=module, node_type="file",+ file_path=module, language="python", created_at=_NOW,+ ),+ _sym(rid, f"{module}::symbol_discriminator", **py),+ _sym(rid, "core/references.py::symbol_identity", **py),+ _sym(rid, "core/parser.py::parse_file", lines=(1, 90), **py),+ _sym(rid, "core/views.py::render", lines=(1, 20), **py),+ _edge(rid, "core/parser.py::parse_file", f"{module}::symbol_discriminator"),+ _edge(rid, "core/views.py::render", "core/references.py::symbol_identity"),+ ]+ )+ await session.flush()+ hits = [+ {+ "target_path": module,+ "symbols": [{"name": "symbol_discriminator", "kind": "function", "_relevance": 9}],+ }+ ]++ ev = await callers.caller_evidence(+ session, rid, "How does symbol_identity pick a discriminator, and where is it called?",+ {"symbol_identity"}, hits,+ )+ assert [r["caller"] for r in ev.rows] == ["core/parser.py::parse_file"]+ # Nothing but the name: the function stays the target.+ ev = await callers.caller_evidence(+ session, rid, "Where is symbol_identity called?", {"symbol_identity"}, hits+ )+ assert [r["caller"] for r in ev.rows] == ["core/views.py::render"]++@pytest.mark.asyncioasync def test_go_target_resolved_from_retrieval_lists_other_files_only(session, populated_db):rid = populated_dbdiff --git a/tests/unit/server/mcp/test_answer_topic_guard.py b/tests/unit/server/mcp/test_answer_topic_guard.pyindex 585682909..c4fc6dd48 100644--- a/tests/unit/server/mcp/test_answer_topic_guard.py+++ b/tests/unit/server/mcp/test_answer_topic_guard.py@@ -13,7 +13,11 @@ import pytestfrom repowise.server.mcp_server._hit_symbols import _stemfrom repowise.server.mcp_server._prose_symbols import _rarest_terms, _SymbolTextIndexfrom repowise.server.mcp_server.tool_answer.bodies import _gather_body_candidates-from repowise.server.mcp_server.tool_answer.symbols import _anchor_symbol_hits+from repowise.server.mcp_server.tool_answer.config import _INLINE_BODY_MAX_LINES+from repowise.server.mcp_server.tool_answer.symbols import (+ _anchor_symbol_hits,+ drop_ruled_out_files,+)class _Sym:@@ -187,6 +191,88 @@ async def test_a_prose_word_is_not_scanned_for(tmp_path):+def _class_file(name: str, length: int = 200) -> str:+ lines = [f"public class {name} {{", " int x;", "", "", f" {name}(int x) {{", " }"]+ return "\n".join(lines + [" // body"] * (length - len(lines) - 1) + ["}"]) + "\n"+++def _class_and_constructors(name: str, path: str, ctors: int, end: int = 200) -> list[_Sym]:+ rows = [_Sym(name, path, 1, end, kind="class")]+ rows += [_Sym(name, path, 5, 6, kind="method", parent_name=name) for _ in range(ctors)]+ return rows+++async def test_a_class_and_its_constructors_are_one_definition(tmp_path):+ path = "stream/JsonReader.java"+ _write(tmp_path, path, _class_file("JsonReader"))+ rows = _class_and_constructors("JsonReader", path, 2)+ hits = [{"target_path": path, "score": 3.0}]+ out, homonyms = await _anchor_symbol_hits(+ _Session(list(rows)), "r", {"JsonReader"}, hits, repo_root=tmp_path,+ question="How does JsonReader skip the non-execute prefix?",+ )+ assert not homonyms["union"]+ assert out[0]["target_path"] == path and out[0]["_symbol_anchored"]+ # Prose: the class head a cap would cut answers nothing; its file still leads.+ assert not out[0].get("_anchor_symbols")+ # A bare lookup still serves the class.+ out, _ = await _anchor_symbol_hits(+ _Session(list(rows)), "r", {"JsonReader"}, [], repo_root=tmp_path, question="JsonReader"+ )+ assert [(a["name"], a["kind"]) for a in out[0]["_anchor_symbols"]] == [("JsonReader", "class")]++[email protected]("extra, stashed", [(0, True), (1, False)])+async def test_a_class_head_is_skipped_exactly_when_the_inline_cap_cuts_it(tmp_path, extra, stashed):+ end = 1 + _INLINE_BODY_MAX_LINES + extra+ path = "stream/JsonReader.java"+ _write(tmp_path, path, _class_file("JsonReader", end))+ out, _ = await _anchor_symbol_hits(+ _Session(_class_and_constructors("JsonReader", path, 1, end)), "r", {"JsonReader"},+ [{"target_path": path, "score": 3.0}], repo_root=tmp_path,+ question="How does JsonReader skip the non-execute prefix?",+ )+ assert bool(out[0].get("_anchor_symbols")) is stashed+++async def test_a_plain_word_project_name_does_not_anchor_its_class(tmp_path):+ # ``Gson`` names the project, its main class and its constructors.+ path = "src/main/java/com/google/gson/Gson.java"+ _write(tmp_path, path, _class_file("Gson"))+ for i in range(4):+ _write(tmp_path, f"src/main/java/com/google/gson/Use{i}.java", "Gson g = new Gson();\n")+ hits = [{"target_path": path, "score": 3.0}]+ out, homonyms = await _anchor_symbol_hits(+ _Session(_class_and_constructors("Gson", path, 2)), "r", {"Gson", "Java"}, hits,+ repo_root=tmp_path,+ question="Where does Gson throw the duplicate key error on a Java map?",+ )+ assert not homonyms["union"]+ assert not any(h.get("_symbol_anchored") for h in out)+++def test_a_file_the_question_rules_out_leaves_the_hits():+ hits = [+ {"target_path": "core/symbol_identity.py"},+ {"target_path": "core/symbol_identity.py::split_id"},+ {"target_path": "core/call_resolver.py"},+ {"target_path": "legacy/old.py"},+ ]+ kept = drop_ruled_out_files(hits, "Which code parses the suffix, outside symbol_identity.py?")+ assert [h["target_path"] for h in kept] == ["core/call_resolver.py", "legacy/old.py"]+ kept = drop_ruled_out_files(hits, "Who reads the suffix other than legacy/?")+ assert [h["target_path"] for h in kept][-1] == "core/call_resolver.py"+ # A path with a directory rules out only that file; a bare name, every file of it.+ twins = [{"target_path": "a/utils.py"}, {"target_path": "b/utils.py"}]+ assert drop_ruled_out_files(twins, "who escapes it outside b/utils.py?") == twins[:1]+ assert drop_ruled_out_files(twins, "who escapes it outside utils.py?") == []+ # Prose and a dotted module path rule nothing out.+ assert drop_ruled_out_files(hits, "what runs outside the loop, besides a.b.c?") == hits++@pytest.mark.asyncioasync def test_a_name_only_tests_write_does_not_anchor_a_fixture(tmp_path):# No production file writes the name, which must not read as "specific".