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
feat(search): return files that have no wiki page (#3210)
Raghav Chamadiyabef2529dda50
diff --git a/packages/server/src/repowise/server/mcp_server/_answer_pipeline.py b/packages/server/src/repowise/server/mcp_server/_answer_pipeline.pyindex 02970fb33..a4fc5d593 100644--- a/packages/server/src/repowise/server/mcp_server/_answer_pipeline.py+++ b/packages/server/src/repowise/server/mcp_server/_answer_pipeline.py@@ -528,7 +528,9 @@ class _SymbolLegResult:self.symbol_names = symbol_names-async def _safe_symbol_search(ctx: Any, question: str) -> list[_SymbolLegResult]:+async def _safe_symbol_search(+ ctx: Any, question: str, *, pageless: bool = False+) -> list[_SymbolLegResult]:"""File pages whose symbols the question's words name. [] on any failure.Ungated: it runs on every question, not only on ones that happen to carry@@ -539,7 +541,8 @@ async def _safe_symbol_search(ctx: Any, question: str) -> list[_SymbolLegResult]Best-effort with a timeout, like the other two legs: a slow or missingsymbol index degrades ``get_answer`` to its previous behaviour rather than- failing the call.+ failing the call. ``pageless`` keeps files that have no page, as pageless+ rows, for a caller that can serve them."""try:pages = await asyncio.wait_for(@@ -548,6 +551,7 @@ async def _safe_symbol_search(ctx: Any, question: str) -> list[_SymbolLegResult]question,max_files=_SYMBOL_LEG_MAX_PAGES,symbol_limit=_SYMBOL_LEG_FETCH_LIMIT,+ pageless=pageless,),timeout=5.0,)diff --git a/packages/server/src/repowise/server/mcp_server/_graph_files.py b/packages/server/src/repowise/server/mcp_server/_graph_files.pyindex 51ec62361..b534e5ffa 100644--- a/packages/server/src/repowise/server/mcp_server/_graph_files.py+++ b/packages/server/src/repowise/server/mcp_server/_graph_files.py@@ -22,7 +22,7 @@ from typing import Any, TypeVarfrom sqlalchemy import select-from repowise.core.persistence.models import Repository+from repowise.core.persistence.models import GraphNode, Repositoryfrom repowise.server.mcp_server._index_state import index_state_key_T = TypeVar("_T")@@ -80,7 +80,10 @@ def keep_projected_edge(def reset_cache() -> None:"""Drop every cached projection. For tests and for a re-index in-process."""+ global _LOCK_CACHE.clear()+ # A lock that once waited is bound to that event loop; a fresh one is not.+ _LOCK = asyncio.Lock()def _cached(repo_id: str, key: str, name: str) -> Any | None:@@ -122,3 +125,19 @@ async def per_index(while len(_CACHE) > _CACHE_MAX_REPOS:_CACHE.popitem(last=False)return value+++async def graph_file_paths(session: Any, repo_id: str) -> tuple[str, ...]:+ """Every indexed file's path, with or without a wiki page. Read-only."""++ async def build() -> tuple[str, ...]:+ res = await session.execute(+ select(GraphNode.node_id).where(+ GraphNode.repository_id == repo_id,+ GraphNode.node_type == "file",+ ~GraphNode.node_id.startswith("external:"),+ )+ )+ return tuple(sorted(p for (p,) in res.all() if p))++ return await per_index(session, repo_id, "graph_file_paths", build)diff --git a/packages/server/src/repowise/server/mcp_server/_page_paths.py b/packages/server/src/repowise/server/mcp_server/_page_paths.pyindex 39ab3573f..e041f36e2 100644--- a/packages/server/src/repowise/server/mcp_server/_page_paths.py+++ b/packages/server/src/repowise/server/mcp_server/_page_paths.py@@ -16,6 +16,10 @@ it.from __future__ import annotations+# A search row for an indexed file that has no wiki page: its ``target_path``+# is the file, and there is no page behind its id to read.+PAGELESS_FILE = "file"+# Page types whose ``target_path`` is a real repository-relative file path.## ``symbol_spotlight`` is included because its target_path is ``file.py::Sym``:@@ -28,6 +32,7 @@ from __future__ import annotationsFILE_BACKED_PAGE_TYPES: frozenset[str] = frozenset({"file_page",+ PAGELESS_FILE,"symbol_spotlight","api_contract","infra_page",diff --git a/packages/server/src/repowise/server/mcp_server/_prose_symbols.py b/packages/server/src/repowise/server/mcp_server/_prose_symbols.pyindex 9891fe02a..3255fdebd 100644--- a/packages/server/src/repowise/server/mcp_server/_prose_symbols.py+++ b/packages/server/src/repowise/server/mcp_server/_prose_symbols.py@@ -40,8 +40,9 @@ prose-to-symbol search useless.from __future__ import annotations+import osfrom collections import Counter-from collections.abc import Iterable+from collections.abc import Callable, Iterable, Mappingfrom typing import Any, NamedTuplefrom sqlalchemy import select@@ -49,13 +50,14 @@ from sqlalchemy import selectfrom repowise.core.persistence.database import get_sessionfrom repowise.core.persistence.models import GraphNode, Page, WikiSymbolfrom repowise.core.test_paths import is_test_path, is_test_related_path-from repowise.server.mcp_server._graph_files import per_index+from repowise.server.mcp_server._graph_files import graph_file_paths, per_indexfrom repowise.server.mcp_server._helpers import (_get_exclude_spec,_get_repo,is_excluded,)from repowise.server.mcp_server._hit_symbols import _stem+from repowise.server.mcp_server._page_paths import PAGELESS_FILEfrom repowise.server.mcp_server._query_terms import STOPWORDSfrom repowise.server.mcp_server._query_terms import content_terms as content_termsfrom repowise.server.mcp_server.tool_search_symbols import (@@ -63,6 +65,7 @@ from repowise.server.mcp_server.tool_search_symbols import (_symbol_result,_tokens,_tombstoned_paths,+ file_path_index,)# Rows pulled per term. Bounded per term so a common word cannot evict the@@ -94,6 +97,9 @@ _GENERIC_MEMBER_NAMES = frozenset({"get", "run", "main"})# one short name is rare even when each word alone is everywhere._NAME_COVER_MIN_WORDS = 2_NAME_COVER_MIN_SHARE = 2 / 3+# A file name the question spells word for word, at least this long, is as+# specific as a page hit. Two words (``test_matcher``) often name a role, not a topic.+_FULL_COVER_MIN_WORDS = 3class _SymbolTextIndex(NamedTuple):@@ -154,6 +160,32 @@ def _candidates_for_term(index: _SymbolTextIndex, term: str) -> tuple[list[int],return window, len(window) >= _PER_TERM_CANDIDATES+def _covered_positions(+ postings: Mapping[str, Iterable[int]],+ size: Callable[[int], int],+ terms: Iterable[str],+ stem: Callable[[str], str] = _stem,+) -> Counter[int]:+ """Positions whose words the query's words mostly spell, with how many they spell.++ ``postings`` maps a word, folded by ``stem``, to the positions carrying it+ and ``size`` gives a position's own word count (see :func:`_name_covered`).+ """+ stems = {stem(t) for t in terms}+ if len(stems) < _NAME_COVER_MIN_WORDS:+ return Counter()+ hits: Counter[int] = Counter()+ for stem in stems:+ hits.update(postings.get(stem, ()))+ return Counter(+ {+ i: n+ for i, n in hits.items()+ if n >= _NAME_COVER_MIN_WORDS and n >= _NAME_COVER_MIN_SHARE * size(i)+ }+ )++def _name_cover_candidates(index: _SymbolTextIndex, terms: list[str]) -> list[int]:"""Symbols whose name the query's words mostly spell (see :func:`_name_covered`).@@ -161,19 +193,8 @@ def _name_cover_candidates(index: _SymbolTextIndex, terms: list[str]) -> list[insaturated words (``dynamic`` + ``import``) falls outside both of them. Thisasks for the combination directly, from the inverted name words."""- stems = {_stem(t) for t in terms}- if len(stems) < _NAME_COVER_MIN_WORDS:- return []- hits: Counter[int] = Counter()- for stem in stems:- hits.update(index.postings.get(stem, ()))- covered = [- i- for i, n in hits.items()- if n >= _NAME_COVER_MIN_WORDS- and n >= _NAME_COVER_MIN_SHARE * len(_name_words(index.names[i]))- ]- covered.sort(key=lambda i: (-hits[i], len(index.names[i]), index.symbol_ids[i]))+ hits = _covered_positions(index.postings, lambda i: len(_name_words(index.names[i])), terms)+ covered = sorted(hits, key=lambda i: (-hits[i], len(index.names[i]), index.symbol_ids[i]))return covered[:_PER_TERM_CANDIDATES]@@ -339,6 +360,7 @@ async def symbol_backed_pages(*,max_files: int,symbol_limit: int = 20,+ pageless: bool = False,) -> list[dict]:"""File pages whose indexed symbols the words of *question* name.@@ -368,38 +390,145 @@ async def symbol_backed_pages(paths: list[str] = []names: dict[str, list[str]] = {}+ signatures: dict[str, str] = {}for hit in symbols:path = hit.get("file")if not path:continueif path not in names:paths.append(path)+ signatures[path] = hit.get("signature") or ""names.setdefault(path, []).append(hit.get("name") or "")paths = paths[:max_files]if not paths:return []async with get_session(ctx.session_factory) as session:- res = await session.execute(- select(Page.id, Page.target_path, Page.title, Page.summary, Page.page_type).where(- Page.target_path.in_(paths),- Page.page_type == "file_page",- Page.freshness_status != "tombstone",- )+ by_path = await _file_pages(session, paths)+ # Without ``pageless`` a file with no page is dropped: the caller only+ # ranks pages.+ out = [+ by_path.get(p) or _pageless_row(p, signatures[p])+ for p in paths+ if p in by_path or pageless+ ]+ for row in out:+ # The names that earned the page its place, for a ranker that would+ # otherwise judge it on prose that never mentions them.+ row["symbol_names"] = names[row["target_path"]]+ return out+++async def _file_pages(session, paths: list[str]) -> dict[str, dict]:+ """The live file page of each of *paths* that has one, by path."""+ res = await session.execute(+ select(Page.id, Page.target_path, Page.title, Page.summary, Page.page_type).where(+ Page.target_path.in_(paths),+ Page.page_type == "file_page",+ Page.freshness_status != "tombstone",)- by_path = {- row[1]: {- "page_id": row[0],- "target_path": row[1],- "title": row[2] or f"File: {row[1]}",- "summary": row[3] or "",- "page_type": row[4] or "file_page",- # The names that earned the page its place, for a ranker that- # would otherwise judge it on prose that never mentions them.- "symbol_names": names[row[1]],- }- for row in res.all()+ )+ return {+ row[1]: {+ "page_id": row[0],+ "target_path": row[1],+ "title": row[2] or f"File: {row[1]}",+ "summary": row[3] or "",+ "page_type": row[4] or "file_page",}- # A symbol whose file has no page cannot be read, so it contributes- # nothing and is dropped rather than ranked.- return [by_path[p] for p in paths if p in by_path]+ for row in res.all()+ }+++def _pageless_row(path: str, snippet: str) -> dict:+ """A file row for an indexed file that has no wiki page."""+ return {+ "page_id": f"{PAGELESS_FILE}:{path}",+ "target_path": path,+ "title": path,+ "summary": snippet,+ "page_type": PAGELESS_FILE,+ }+++class _FilenameIndex(NamedTuple):+ """One repo's file names as stemmed words, paged or not, by position."""++ paths: tuple[str, ...]+ paged: frozenset[str] # paths with a file page, live or tombstoned+ sizes: tuple[int, ...] # how many words each file name has+ postings: dict[str, tuple[int, ...]] # file name word -> positions+++def _fold(word: str) -> str:+ """:func:`_stem` plus ``-ing`` / ``-ed`` / ``-e``, so ``highlight`` meets+ ``highlighting`` and ``parse`` meets ``parsed``. File names only: symbol+ names are matched with the plain stem."""+ word = _stem(word)+ for suffix in ("ing", "ed", "e"):+ if word.endswith(suffix) and len(word) - len(suffix) >= 4:+ return word[: -len(suffix)]+ return word+++def _filename_words(path: str) -> set[str]:+ """``src/config/exec-command-highlighting.ts`` -> ``{exec, command, highlight}``.++ The file name only: a directory names a whole area, not the file.+ """+ name = os.path.splitext(path.rsplit("/", 1)[-1])[0]+ return {_fold(t) for t in _tokens(name) if t not in STOPWORDS}+++async def _filename_index(session, repo_id: str) -> _FilenameIndex:+ # Read before ``per_index`` takes its lock, since that lock is not reentrant.+ paged = (await file_path_index(session, repo_id)).paths+ paths = tuple(sorted(set(paged) | set(await graph_file_paths(session, repo_id))))++ async def build() -> _FilenameIndex:+ words = [_filename_words(p) for p in paths]+ postings: dict[str, list[int]] = {}+ for i, ws in enumerate(words):+ for w in ws:+ postings.setdefault(w, []).append(i)+ return _FilenameIndex(+ paths,+ frozenset(paged),+ tuple(len(ws) for ws in words),+ {w: tuple(pos) for w, pos in postings.items()},+ )++ return await per_index(session, repo_id, "prose_filename_words", build)+++async def filename_backed_pages(ctx: Any, question: str, *, max_files: int) -> list[dict]:+ """Files whose file name the words of *question* mostly spell, as page rows.++ The same cover rule as symbol names: ``exec command highlighting`` reaches+ ``exec-command-highlighting.ts``. A file with no page gets a pageless row,+ and ``full_cover`` says the question spells every word of the name.+ Most-covered first, then shorter names.+ """+ terms = content_terms(question)+ if not terms or max_files <= 0:+ return []+ async with get_session(ctx.session_factory) as session:+ repository = await _get_repo(session)+ index = await _filename_index(session, repository.id)+ hits = _covered_positions(index.postings, index.sizes.__getitem__, terms, _fold)+ if not hits:+ return []+ ranked = sorted(hits, key=lambda i: (-hits[i], index.sizes[i], index.paths[i]))[+ :max_files+ ]+ by_path = await _file_pages(session, [index.paths[i] for i in ranked])+ rows = []+ for i in ranked:+ path = index.paths[i]+ # A tombstoned page's file is gone, so it gets no pageless row either.+ if path not in by_path and path in index.paged:+ continue+ row = by_path.get(path) or _pageless_row(path, "")+ row["full_cover"] = hits[i] >= max(index.sizes[i], _FULL_COVER_MIN_WORDS)+ rows.append(row)+ return rowsdiff --git a/packages/server/src/repowise/server/mcp_server/tool_search.py b/packages/server/src/repowise/server/mcp_server/tool_search.pyindex 4a054124e..c97f65c7c 100644--- a/packages/server/src/repowise/server/mcp_server/tool_search.py+++ b/packages/server/src/repowise/server/mcp_server/tool_search.py@@ -24,8 +24,10 @@ from repowise.core.test_paths import is_test_path, is_test_related_pathfrom repowise.server.mcp_server._answer_pipeline import (_RRF_K,_RRF_SCORE_SCALE,+ _SYMBOL_LEG_MAX_PAGES,_SYMBOL_LEG_RRF_K,_safe_symbol_search,+ _SymbolLegResult,)from repowise.server.mcp_server._budget import (OmissionCollector,@@ -48,11 +50,13 @@ from repowise.server.mcp_server._line_hits import attach_line_hitsfrom repowise.server.mcp_server._meta import EXHAUSTIVE_SWEEP_HINTfrom repowise.server.mcp_server._meta import build_meta as _build_metafrom repowise.server.mcp_server._page_paths import (+ PAGELESS_FILE,add_row_paths,file_candidates,file_path_of,hit_file_path,)+from repowise.server.mcp_server._prose_symbols import filename_backed_pagesfrom repowise.server.mcp_server._query_shape import (_DECISION_DOWNWEIGHT,_MIN_RELEVANCE_SCORE,@@ -268,15 +272,19 @@ def _is_test_query(query: str) -> bool:return bool(_TEST_QUERY_RE.search(query))+# Rows that are one whole file, with or without a page behind them.+_FILE_ROW_TYPES = ("file_page", PAGELESS_FILE)++def _is_test_page(item: dict) -> bool:- """True when a hit is a file_page documenting a test file.+ """True when a hit is a whole-file row for a test file.Tests only, deliberately not test support: a ``conftest.py`` or a fixturemodule is often exactly what the person searching wanted, so it keeps itsrank. The ``kind`` filter counts both (see :func:`_classify_hit_kind`) —asking for tests and asking to rank tests lower are different questions."""- return item.get("page_type") == "file_page" and is_test_path(item.get("target_path") or "")+ return item.get("page_type") in _FILE_ROW_TYPES and is_test_path(item.get("target_path") or "")def _downweight_test_pages(output: list[dict], query: str) -> None:@@ -481,7 +489,7 @@ def _classify_hit_kind(target_path: str, page_type: str) -> str:tp = (target_path or "").lower()if page_type in ("module_page", "symbol_spotlight") or tp.endswith(".md"):return "doc"- if not tp or page_type not in ("file_page",):+ if not tp or page_type not in _FILE_ROW_TYPES:return "doc"if any(tok in tp for tok in _CONFIG_PATH_TOKENS):return "config"@@ -528,7 +536,7 @@ def _attach_paths(output: list[dict], page_info: dict) -> None:takes gold containment from 19 to 39 of 50 instances."""for item in output:- item["target_path"] = page_info.get(item["page_id"], "")+ item["target_path"] = page_info.get(item["page_id"], item.get("target_path", ""))if "::" in item["target_path"]:item["symbol_id"] = symbol_identity(item["target_path"])item["target_path"] = path_identity(item["target_path"].split("::", 1)[0])@@ -563,7 +571,8 @@ def _drop_derivable_page_ids(results: list[dict]) -> list[dict]:for item in results:target = item.get("target_path") or item.get("path", "")derived = f"{item.get('page_type', '')}:{target}"- if item.get("page_id") == derived:+ # A row for a file with no page has an id that names no page.+ if item.get("page_id") == derived or item.get("page_type") == PAGELESS_FILE:item.pop("page_id", None)return results@@ -693,6 +702,26 @@ async def _safe_vector(ctx, query: str, limit: int) -> list:return []+_FILENAME_LEG_RRF_K = _SYMBOL_LEG_RRF_K+++async def _safe_filename_search(ctx, query: str) -> list[tuple[_SymbolLegResult, bool]]:+ """Files whose file name the query spells, each with whether it spells all of+ the name. Bounded and failure-swallowing."""+ with contextlib.suppress(Exception):+ pages = await asyncio.wait_for(+ filename_backed_pages(ctx, query, max_files=_SYMBOL_LEG_MAX_PAGES), timeout=5.0+ )+ return [+ (+ _SymbolLegResult(p["page_id"], p["title"], p["summary"][:200], p["page_type"], []),+ p["full_cover"],+ )+ for p in pages+ ]+ return []++def _symbol_leg_target(fused: dict[str, dict], page_id: str) -> str:"""The fused page a symbol-leg file page credits: the best page of its file.@@ -712,7 +741,7 @@ def _symbol_leg_target(fused: dict[str, dict], page_id: str) -> str:def _fused_entry(r) -> dict:"""Seed a fused-result dict from a retriever hit (RRF score added by caller)."""- return {+ entry = {"page_id": r.page_id,"title": r.title,"page_type": r.page_type,@@ -720,6 +749,10 @@ def _fused_entry(r) -> dict:"_rrf": 0.0,"_sources": set(),}+ if r.page_type == PAGELESS_FILE:+ # No page row to load it from later.+ entry["target_path"] = r.page_id.partition(":")[2]+ return entryasync def _fused_retrieve(ctx, query: str, fetch_limit: int, page_type: str | None) -> list[dict]:@@ -728,8 +761,10 @@ async def _fused_retrieve(ctx, query: str, fetch_limit: int, page_type: str | NoThe retrievers run in parallel; a hit's score is the sum of``1/(rank + k)`` over the retrievers that surfaced it, scaled into theBM25 range the downstream relevance gates were tuned against. Each hit- carries a ``sources`` list (``"fts"``, ``"vector"``, ``"symbol"``): a page- found by several retrievers is a stronger match than one found by one mode.+ carries a ``sources`` list (``"fts"``, ``"vector"``, ``"symbol"``,+ ``"filename"``): a page found by several retrievers is a stronger match+ than one found by one mode. The symbol and filename legs also name files+ that have no page, as ``page_type: "file"`` rows.This mirrors get_answer's ``hybrid_retrieve`` so the two entry points rankthe same corpus identically. The prior path ran vector search and fell@@ -743,10 +778,11 @@ async def _fused_retrieve(ctx, query: str, fetch_limit: int, page_type: str | No(for RRF) is the hit's place in the retriever's own list, unchanged by thefloor."""- fts_results, vec_results, sym_results = await asyncio.gather(+ fts_results, vec_results, sym_results, name_results = await asyncio.gather(_safe_fts(ctx, query, fetch_limit),_safe_vector(ctx, query, fetch_limit),- _safe_symbol_search(ctx, query),+ _safe_symbol_search(ctx, query, pageless=True),+ _safe_filename_search(ctx, query),)fused: dict[str, dict] = {}@@ -762,12 +798,22 @@ async def _fused_retrieve(ctx, query: str, fetch_limit: int, page_type: str | Noentry = fused.setdefault(r.page_id, _fused_entry(r))entry["_rrf"] += 1.0 / (rank + _RRF_K)entry["_sources"].add("fts")- # File pages whose symbol names the query's words spell. Weighted below the- # page legs, as in get_answer; it has no raw score to floor.+ # Files whose symbol names the query's words spell, paged or not. Weighted+ # below the page legs, as in get_answer; it has no raw score to floor.for rank, r in enumerate(sym_results):entry = fused.setdefault(_symbol_leg_target(fused, r.page_id), _fused_entry(r))entry["_rrf"] += 1.0 / (rank + _SYMBOL_LEG_RRF_K)entry["_sources"].add("symbol")+ # Files whose file name the query's words spell, weighted as a name match.+ # It adds files the other legs missed and never reorders a page they found.+ # A name of three or more words the query spells in full weighs like a page hit.+ for rank, (r, full) in enumerate(name_results):+ target = _symbol_leg_target(fused, r.page_id)+ if target in fused and r.page_type != PAGELESS_FILE:+ continue+ entry = fused.setdefault(target, _fused_entry(r))+ entry["_rrf"] += 1.0 / (rank + (_RRF_K if full else _FILENAME_LEG_RRF_K))+ entry["_sources"].add("filename")output: list[dict] = []for entry in fused.values():@@ -780,6 +826,28 @@ async def _fused_retrieve(ctx, query: str, fetch_limit: int, page_type: str | Noreturn output+def _rerank_pages_first(output: list[dict], query: str) -> list[dict]:+ """Coverage rerank whose window weights come from the pages alone.++ The weights are relative to the window, so rows for files without a page+ would reorder the pages among themselves. They are scored against a copy+ of the pages instead, and only take their own place among them.+ """+ pages = [item for item in output if item.get("page_type") != PAGELESS_FILE]+ pageless = [item for item in output if item.get("page_type") == PAGELESS_FILE]+ if pageless:+ rerank_by_context_coverage(+ [dict(item) for item in pages] + pageless,+ query,+ score_key="relevance_score",+ floor=0.5,+ )+ pages = rerank_by_context_coverage(pages, query, score_key="relevance_score", floor=0.5)+ if not pageless:+ return pages+ return sorted(pages + pageless, key=lambda item: item.get("relevance_score", 0.0), reverse=True)++async def _search_single_repo(ctx, query: str, limit: int, page_type: str | None, kind: str | None = None) -> list[dict]:@@ -1317,12 +1385,7 @@ async def search_codebase(# Re-sort by adjusted relevance with retrieval noise (decisions on# non-why queries, test pages on non-test queries) hard-demoted, then# collapse near-duplicate decisions to one.- output = rerank_by_context_coverage(- output,- query,- score_key="relevance_score",- floor=0.5,- )+ output = _rerank_pages_first(output, query)# After the coverage rerank, whose window-relative weights cannot tell# a word rare across the repo from one rare in these few hits.boost_named_paths(diff --git a/tests/unit/server/mcp/test_filename_leg.py b/tests/unit/server/mcp/test_filename_leg.pynew file mode 100644index 000000000..48d780be1--- /dev/null+++ b/tests/unit/server/mcp/test_filename_leg.py@@ -0,0 +1,267 @@+"""Concept search reaches indexed files that have no wiki page.++A file is found by its file name (the filename leg) or by its symbol names (the+symbol leg). Synthetic files in TypeScript (kebab), Python (snake) and Go+(camel), plus distractors that share one word with a query or match only+through directories.+"""++from __future__ import annotations++import asyncio+import json+from datetime import UTC, datetime+from types import SimpleNamespace++import pytest++from repowise.core.persistence.models import GraphNode, Page, WikiSymbol+from repowise.server.mcp_server import _graph_files+from repowise.server.mcp_server._prose_symbols import filename_backed_pages++_NOW = datetime(2026, 3, 19, 12, 0, 0, tzinfo=UTC)++# path, symbol, language. None of these has a page.+_PAGELESS = [+ ("src/config/exec-command-highlighting.ts", "resolveExecCommandHighlighting", "typescript"),+ ("app/ingest/dynamic_import_resolver.py", "resolve_dynamic_import", "python"),+ ("internal/queue/retryBackoffPolicy.go", "NextRetryDelay", "go"),+ # Distractors.+ ("src/config/highlighting.ts", "highlight", "typescript"),+ ("src/exec/command/highlighting/index.ts", "run", "typescript"),+ ("app/ingest/import_cache_eviction_policy_table.py", "evict", "python"),+ ("src/config/exec-command-highlighting.test.ts", "check", "typescript"),+]++_QUERIES = [+ ("exec command highlighting", "src/config/exec-command-highlighting.ts"),+ ("how are dynamic imports resolved", "app/ingest/dynamic_import_resolver.py"),+ ("which retry backoff policy applies", "internal/queue/retryBackoffPolicy.go"),+]+++def _page(rid: str, path: str, i: int) -> Page:+ return Page(+ id=f"file_page:{path}",+ repository_id=rid,+ page_type="file_page",+ title=f"File: {path}",+ content="overview",+ target_path=path,+ source_hash=f"fh{i}",+ model_name="mock",+ provider_name="mock",+ generation_level=2,+ confidence=0.5,+ freshness_status="fresh",+ metadata_json="{}",+ created_at=_NOW,+ updated_at=_NOW,+ )+++async def _seed_pageless(session, rid: str) -> None:+ for i, (path, name, language) in enumerate(_PAGELESS):+ session.add(+ GraphNode(+ id=f"pl{i}",+ repository_id=rid,+ node_id=path,+ node_type="file",+ language=language,+ symbol_count=1,+ created_at=_NOW,+ )+ )+ session.add(+ WikiSymbol(+ id=f"pls{i}",+ repository_id=rid,+ file_path=path,+ symbol_id=f"{path}::{name}",+ name=name,+ qualified_name=name,+ kind="function",+ signature=f"{name}()",+ start_line=12,+ end_line=20,+ docstring="",+ visibility="public",+ is_async=False,+ complexity_estimate=1,+ language=language,+ parent_name=None,+ created_at=_NOW,+ updated_at=_NOW,+ )+ )+ await session.commit()+++async def ctx(session, repo_id, factory, tmp_path):+ await _seed_pageless(session, repo_id)+ # One paged file, so pages and pageless rows meet in one result.+ session.add(_page(repo_id, "internal/queue/retryBackoffPolicy.go", 0))+ await session.commit()+ return SimpleNamespace(session_factory=factory, path=str(tmp_path))+++async def _paths(ctx, question: str) -> list[tuple[str, str]]:+ rows = await filename_backed_pages(ctx, question, max_files=8)+ return [(r["target_path"], r["page_type"]) for r in rows]+++async def test_file_name_leg_covers_files_with_and_without_a_page(ctx):+ assert (await _paths(ctx, "exec command highlighting"))[0] == (+ "src/config/exec-command-highlighting.ts",+ "file",+ )+ assert (await _paths(ctx, "which retry backoff policy applies"))[0] == (+ "internal/queue/retryBackoffPolicy.go",+ "file_page",+ )+++async def test_inflected_query_words_still_spell_the_name(ctx):+ rows = await filename_backed_pages(ctx, "where do we highlight an exec command", max_files=8)+ assert rows[0]["target_path"] == "src/config/exec-command-highlighting.ts"+ assert rows[0]["full_cover"]+ partial = await filename_backed_pages(ctx, "command highlighting", max_files=8)+ assert not partial[0]["full_cover"]+++async def test_one_shared_word_reaches_nothing(ctx):+ assert await _paths(ctx, "how is highlighting configured") == []+++async def test_directory_words_and_long_names_do_not_count(ctx):+ paths = [p for p, _ in await _paths(ctx, "exec command highlighting")]+ assert "src/exec/command/highlighting/index.ts" not in paths+ assert "src/config/highlighting.ts" not in paths+ # import + policy are two of the five words in the table's name.+ assert await _paths(ctx, "import policy") == []+++async def pageless_mcp(setup_mcp, session):+ await _seed_pageless(session, setup_mcp)+ return setup_mcp+++def _by_path(result: dict) -> dict[str, dict]:+ return {r["path"]: r for r in result["results"] if r.get("path")}++[email protected](("question", "path"), _QUERIES)+async def test_prose_query_returns_a_file_that_has_no_page(pageless_mcp, question, path):+ from repowise.server.mcp_server import search_codebase++ result = await search_codebase(question, mode="concept", limit=10)+ row = _by_path(result)[path]+ assert row["page_type"] == "file"+ assert row["symbols"][0].endswith(":12")+ assert {"filename", "symbol"} & set(row["sources"])+ assert "page_id" not in row+ assert path in [c["path"] for c in result.get("candidates", [])]+++async def test_pageless_rows_leave_the_order_of_pages_alone(pageless_mcp, monkeypatch):+ from repowise.server.mcp_server import search_codebase, tool_search++ query = "auth service middleware exec command highlighting"+ with_rows = await search_codebase(query, mode="concept", limit=10)++ symbol_search = tool_search._safe_symbol_search+ name_search = tool_search._safe_filename_search++ async def symbols_paged_only(ctx, q, *, pageless=False):+ return await symbol_search(ctx, q)++ async def names_paged_only(ctx, q):+ return [(r, full) for r, full in await name_search(ctx, q) if r.page_type != "file"]++ monkeypatch.setattr(tool_search, "_safe_symbol_search", symbols_paged_only)+ monkeypatch.setattr(tool_search, "_safe_filename_search", names_paged_only)+ without = await search_codebase(query, mode="concept", limit=10)++ paged = [r["path"] for r in with_rows["results"] if r.get("page_type") != "file"]+ assert any(r.get("page_type") == "file" for r in with_rows["results"])+ assert paged == [r.get("path") for r in without["results"]][: len(paged)]+++async def test_filters_apply_to_pageless_rows(pageless_mcp, tmp_path):+ from repowise.server.mcp_server import search_codebase++ target = "src/config/exec-command-highlighting.ts"+ query = "exec command highlighting"+ assert target not in _by_path(await search_codebase(query, mode="concept", kind="test"))+ assert target not in _by_path(+ await search_codebase(query, mode="concept", page_type="file_page")+ )+ implementation = await search_codebase(query, mode="concept", kind="implementation")+ assert "src/config/exec-command-highlighting.test.ts" not in _by_path(implementation)++ (tmp_path / ".gitignore").write_text("src/config/\n", encoding="utf-8")+ assert target not in _by_path(await search_codebase(query, mode="concept", limit=10))+++async def test_a_pageless_test_file_ranks_below_its_source(pageless_mcp):+ from repowise.server.mcp_server import search_codebase++ result = await search_codebase("exec command highlighting", mode="concept", limit=10)+ paths = [r.get("path") for r in result["results"]]+ test_file = "src/config/exec-command-highlighting.test.ts"+ assert paths.index("src/config/exec-command-highlighting.ts") < paths.index(test_file)++[email protected]("query", ["AuthService", "resolveExecCommandHighlighting"])+async def test_identifier_query_is_unchanged_by_pageless_rows(pageless_mcp, monkeypatch, query):+ from repowise.server.mcp_server import search_codebase, tool_search++ with_legs = await search_codebase(query)++ async def no_leg(ctx, question, **_):+ return []++ monkeypatch.setattr(tool_search, "_safe_filename_search", no_leg)+ monkeypatch.setattr(tool_search, "_safe_symbol_search", no_leg)+ without_legs = await search_codebase(query)+ with_legs["_meta"].pop("timing", None)+ without_legs["_meta"].pop("timing", None)+ assert json.dumps(with_legs, sort_keys=True, default=str) == json.dumps(+ without_legs, sort_keys=True, default=str+ )+++def test_reset_cache_frees_the_lock_from_its_event_loop():+ async def contend() -> None:+ async with _graph_files._LOCK:+ waiter = asyncio.ensure_future(_graph_files._LOCK.acquire())+ await asyncio.sleep(0)+ await waiter+ _graph_files._LOCK.release()++ asyncio.run(contend())+ _graph_files.reset_cache()+ asyncio.run(contend())++[email protected]("kwargs", [{"mode": "hybrid"}, {"mode": "concept", "repo": "all"}])+async def test_pageless_rows_ship_no_page_id_on_any_route(pageless_mcp, kwargs):+ from repowise.server.mcp_server import search_codebase++ result = await search_codebase("exec command highlighting", limit=10, **kwargs)+ rows = [r for r in result["results"] if r.get("page_type") == "file"]+ assert rows+ assert all("page_id" not in r for r in rows)