feat(search): per-file diversification so top-K isn't one class's methods

[andreinknv]

Summary

When a query matches many symbols in a single file, current ranking returns the matching class plus 9 of its members from the same file. The first hit is informative; the next 9 are implementation detail that pushes peer files (subclasses, callers, sibling modules) past the limit. This PR caps results per file so search surfaces representative breadth across the codebase rather than burying the user in one class's internals.

Empirical lift on codegraph (limit=10, default perFileCap=3)

Query	Before (max from one file)	After
ExtractionOrchestrator	10/10	9/10 (only one file matches; backfill kicks in)
database	8/10	3/10
config	5/10	3/10
resolve	4/10	3/10
extract / parse	3 (no regression)	3

Top-1 result is preserved in every case — diversification only reorders second-and-onward.

Components

• SearchOptions.perFileCap?: number in src/types.ts — default 3; set to 0 to disable.

• diversifyByFile(results, limit, perFileCap) in src/search/query-utils.ts: pure function. First pass picks at most perFileCap per file in score order. If limit isn't yet filled, backfills from skipped (in original score order) so we never return fewer results than the caller requested.

• Wiring in src/db/queries.ts: applied after the existing rescoring pass, when there are more candidates than the caller's limit. Relies on the existing 5× internal over-fetch in searchNodesFTS for headroom — no new multiplier added (multiplier-on-multiplier composition was the reviewer's blocking concern in an earlier draft).

• 13 regression tests covering pure-function behavior (cap, backfill, top-preservation, perFileCap=0, limit edges) + integration tests against an end-to-end DB.

Files changed

File	Change
src/types.ts	Add perFileCap to SearchOptions
src/search/query-utils.ts	Add diversifyByFile pure helper
src/db/queries.ts	Wire diversifyByFile into searchNodes; comment on the over-fetch composition
__tests__/diversify.test.ts (NEW)	13 regression tests

Why this PR (not symbol clustering)

The previous proposal was symbol clustering — grouping User/UserService/UserController into a "User feature." After prototyping against codegraph (which is a tool-style codebase, not entity-style), the clusters that emerged were mostly verb collisions (get*, extract*, resolve*) — naming convention noise, not features. Result diversification turned out to be the actual cure for the pain point clustering was meant to address: "search returned 10 hits, all from one class" → "search returned representatives across files."

Test plan

• npm test: 393/393 pass on macOS
• npx tsc --noEmit clean
• Bench script confirms the lift in the table above
• Independent reviewer pass before pushing — addressed three findings:
  • Multiplier-on-multiplier (4× outer × 5× inner = 20× for large limits): outer multiplier removed; the inner over-fetch is sufficient. Re-ran bench to confirm no regression.
  • Within-limit reorder: documented as intentional pure-function behavior; integration path correctly skips when results.length <= limit.
  • MCP exposure of perFileCap: deferred — default 3 is the desired new behavior; MCP callers pick it up implicitly.

Backwards compatibility note

A caller relying on getting all 10 hits from one file via searchNodes will now see at most 3 (with backfill if no peers exist). The new behavior is opt-out via perFileCap: 0.

🤖 Generated with Claude Code