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.

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.py
index 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 missing
symbol 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.py
index 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, TypeVar
from sqlalchemy import select
-from repowise.core.persistence.models import Repository
+from repowise.core.persistence.models import GraphNode, Repository
from 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.py
index 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 annotations
FILE_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.py
index 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 os
from collections import Counter
-from collections.abc import Iterable
+from collections.abc import Callable, Iterable, Mapping
from typing import Any, NamedTuple
from sqlalchemy import select
@@ -49,13 +50,14 @@ from sqlalchemy import select
from repowise.core.persistence.database import get_session
from repowise.core.persistence.models import GraphNode, Page, WikiSymbol
from 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_index
from 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_FILE
from repowise.server.mcp_server._query_terms import STOPWORDS
from repowise.server.mcp_server._query_terms import content_terms as content_terms
from 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 = 3
class _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[in
saturated words (``dynamic`` + ``import``) falls outside both of them. This
asks 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:
continue
if 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 rows
diff --git a/packages/server/src/repowise/server/mcp_server/tool_search.py b/packages/server/src/repowise/server/mcp_server/tool_search.py
index 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_path
from 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_hits
from repowise.server.mcp_server._meta import EXHAUSTIVE_SWEEP_HINT
from repowise.server.mcp_server._meta import build_meta as _build_meta
from 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_pages
from 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 fixture
module is often exactly what the person searching wanted, so it keeps its
rank. 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 entry
async 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 | No
The retrievers run in parallel; a hit's score is the sum of
``1/(rank + k)`` over the retrievers that surfaced it, scaled into the
BM25 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 rank
the 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 the
floor.
"""
- 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 | No
entry = 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 | No
return 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.py
new file mode 100644
index 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)