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(augment): gate the rescue's FTS fallback on query-token coverage (#2092) (#2214)
Punk Dev Robot7a731a8a39b6
diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/search.py b/packages/cli/src/repowise/cli/commands/augment_cmd/search.pyindex 6c16ca71d..8c9821e34 100644--- a/packages/cli/src/repowise/cli/commands/augment_cmd/search.py+++ b/packages/cli/src/repowise/cli/commands/augment_cmd/search.py@@ -21,6 +21,7 @@ and are not billed to the savings ledger; only the *served* digestfrom __future__ import annotations+import loggingimport sqlite3from pathlib import Path@@ -50,6 +51,14 @@ _RESCUE_TOP_N = 2# answer depend on row order; this is small enough to stay one indexed lookup# and large enough that the ranking, not the LIMIT, picks the winner._RESCUE_EXACT_FETCH = 8+# Distinct query tokens (per ``_pattern_terms``) that must appear in an FTS+# row's title/path/snippet before the zero-result rescue names it (#2092). A+# multi-token pattern where one common token matches still returns rows, so+# the fallback needs a quality gate — and it cannot be a score floor: SQLite+# BM25 is unbounded while PostgreSQL ts_rank is ~0-1, so any constant is+# wrong on one dialect. Token coverage is dialect- and corpus-independent.+# Patterns with fewer content tokens require all of them.+_RESCUE_FTS_MIN_TERMS = 2# Files the triage ranker considers. Ranking is over the grep's own matches,# so this only bites on floods wider than 200 files, where the tail is taken# by match count, the one signal available before any index lookup.@@ -785,29 +794,67 @@ async def _rescue(f"{first[1]} `{first[0]}` in {first[2]}{line}{extras}")- # Fall back to FTS on wiki content. Only return if the FTS row actually- # points at a code page (file/module/api), not a generic doc page.+ # Fall back to FTS on wiki content.fts = FullTextSearch(engine)try:fts_rows = await fts.search(pattern, limit=3)except Exception:fts_rows = []+ return _rescue_fts_text(pattern, fts_rows)+++def _rescue_fts_text(pattern: str, fts_rows: list) -> str | None:+ """The FTS-fallback line, or ``None`` when no row earns it.++ Only a row pointing at a code page (file/module/api), not a generic doc+ page, qualifies — and it must pass the coverage gate (#2092): a+ multi-token pattern where only one common token matches ("fallback")+ still returns rows, and a confident wrong suggestion is worse than+ silence. The score is unusable as a gate — the two dialects return+ incompatible scales — so the row itself must carry the query's tokens.+ Same guard family as the widened path's ``_pattern_terms`` check in+ ``_handle_search_post``.++ A pattern whose subtokens are all <3 chars has no terms, so ``needed``+ is 0 and the gate stays open — the pre-gate behaviour, deliberately:+ there is nothing to measure coverage against.+ """+ terms = _pattern_terms(pattern)+ needed = min(_RESCUE_FTS_MIN_TERMS, len(terms))for r in fts_rows:- target = getattr(r, "target_path", None) or ""+ raw_target = getattr(r, "target_path", None) or ""+ target = raw_target.split("::")[0]page_type = getattr(r, "page_type", "") or ""- if "::" in target:- target = target.split("::")[0]- if target and page_type in (+ if not target or page_type not in ("file","file_page","module_page","api_contract","infra_page",):- return (- f"[repowise] No literal match for `{pattern}`. "- f"Wiki suggests `{target}` ({page_type})."+ continue+ haystack = " ".join(+ (+ getattr(r, "title", "") or "",+ raw_target,+ getattr(r, "snippet", "") or "",+ )+ ).lower()+ covered = sum(1 for t in terms if t in haystack)+ if covered < needed:+ # Not a break: rows are few and a later one may cover.+ logging.getLogger(__name__).debug(+ "rescue FTS near-miss: `%s` covers %d/%d terms of `%s`",+ target,+ covered,+ needed,+ pattern,)+ continue+ return (+ f"[repowise] No literal match for `{pattern}`. "+ f"Wiki suggests `{target}` ({page_type})."+ )return Nonediff --git a/tests/unit/cli/test_augment_search.py b/tests/unit/cli/test_augment_search.pyindex 769250e42..2317d8fbb 100644--- a/tests/unit/cli/test_augment_search.py+++ b/tests/unit/cli/test_augment_search.py@@ -13,6 +13,7 @@ and are exercised end-to-end in integration tests instead.from __future__ import annotations+from typing import ClassVarfrom unittest.mock import patchimport pytest@@ -748,3 +749,127 @@ class TestWidenedRescueGate:session = _FakeSession([])out = await _rescue(session, None, 1, "parse_yaml", "parse_yaml", {"src/a.py": 3})assert out is None+++class _FtsRow:+ """Shape of ``SearchResult`` as the rescue's FTS fallback reads it."""++ def __init__(self, target_path, page_type="file_page", title="", snippet=""):+ self.target_path = target_path+ self.page_type = page_type+ self.title = title+ self.snippet = snippet+ self.score = 0.0 # never read: the gate is coverage, not score (#2092)+++class _FakeFTS:+ """Stands in for ``FullTextSearch``; returns the canned rows."""++ rows: ClassVar[list] = []++ def __init__(self, engine) -> None:+ pass++ async def search(self, query, limit=10):+ return list(self.rows)+++def fts_rows(monkeypatch):+ """Route the rescue's FTS fallback to canned rows; yields the setter.++ ``_rescue`` imports ``FullTextSearch`` from ``repowise.core.persistence``+ inside the function body, so the patch lands on the source module.+ """+ import repowise.core.persistence as persistence++ monkeypatch.setattr(persistence, "FullTextSearch", _FakeFTS)++ def _set(rows):+ _FakeFTS.rows = rows++ yield _set+ _FakeFTS.rows = []+++class TestRescueFtsCoverageGate:+ """#2092: the FTS fallback must not fire on a single-token ride.++ The gate is query-token coverage, not a score floor — SQLite BM25 and+ PostgreSQL ts_rank are on incompatible scales, so any constant floor+ silently kills the fallback on one dialect.+ """++ WEAK = "bluetooth codec negotiation fallback"++ async def test_single_token_ride_is_silent(self, fts_rows) -> None:+ """The #2092 repro: only "fallback" matches an unrelated hook file."""+ fts_rows(+ [+ _FtsRow(+ "config/shared/claude/hooks/prefer-web-tools.py",+ title="prefer-web-tools.py",+ snippet="falls back to the web fetch tool as a fallback",+ )+ ]+ )+ out = await _rescue(_FakeSession([]), None, 1, self.WEAK, "bluetooth")+ assert out is None++ async def test_covered_row_fires(self, fts_rows) -> None:+ fts_rows(+ [+ _FtsRow(+ "config/audio/bluetooth.conf",+ snippet="bluetooth codec selection and profile switching",+ )+ ]+ )+ out = await _rescue(_FakeSession([]), None, 1, self.WEAK, "bluetooth")+ assert out == (+ f"[repowise] No literal match for `{self.WEAK}`. "+ "Wiki suggests `config/audio/bluetooth.conf` (file_page)."+ )++ async def test_gate_scans_past_a_weak_row(self, fts_rows) -> None:+ """A weak first row must not mask a covered later row."""+ fts_rows(+ [+ _FtsRow("src/unrelated.py", snippet="a fallback path"),+ _FtsRow(+ "config/audio/bluetooth.conf",+ snippet="bluetooth codec negotiation",+ ),+ ]+ )+ out = await _rescue(_FakeSession([]), None, 1, self.WEAK, "bluetooth")+ assert out is not None+ assert "config/audio/bluetooth.conf" in out++ async def test_single_token_pattern_still_fires(self, fts_rows) -> None:+ """Zero-result rescue allows generic single-token patterns; the gate+ requires all available terms when there are fewer than two."""+ fts_rows(+ [+ _FtsRow(+ "scripts/containerd-gc.sh",+ snippet="containerd image cleanup schedule",+ )+ ]+ )+ out = await _rescue(_FakeSession([]), None, 1, "containerd", "containerd")+ assert out is not None+ assert "scripts/containerd-gc.sh" in out++ async def test_non_code_page_is_still_skipped(self, fts_rows) -> None:+ fts_rows(+ [+ _FtsRow(+ "docs/overview",+ page_type="repo_overview",+ snippet="bluetooth codec negotiation fallback",+ )+ ]+ )+ out = await _rescue(_FakeSession([]), None, 1, self.WEAK, "bluetooth")+ assert out is None