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.

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.py
index 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* digest
from __future__ import annotations
+import logging
import sqlite3
from 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 None
diff --git a/tests/unit/cli/test_augment_search.py b/tests/unit/cli/test_augment_search.py
index 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 ClassVar
from unittest.mock import patch
import 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