Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
fix(search): prune the answer before the limit, and score it the right way up (#687)
Ian Hockd17a364334c7
diff --git a/ix-cli/src/cli/__tests__/search-hygiene.test.ts b/ix-cli/src/cli/__tests__/search-hygiene.test.tsnew file mode 100644index 00000000..190fdaae--- /dev/null+++ b/ix-cli/src/cli/__tests__/search-hygiene.test.ts@@ -0,0 +1,91 @@+// Copyright 2026 Ix Infrastructure Inc.++import { describe, expect, it } from "vitest";++import { dropIncidentalMatches, foldChunkTwins, tierRelevance } from "../commands/search.js";++function row(node: Record<string, unknown>, tier: number) {+ return { node, rank: { tier, score: -tier, matchSource: "test" } };+}++function withPath(name: string, kind: string, path: string) {+ return { name, kind, provenance: { sourceUri: path } };+}++describe("tierRelevance", () => {+ it("is positive, bounded and best-first", () => {+ const scores = [0, 1, 2, 3, 4, 5].map(tierRelevance);+ expect(scores).toEqual([1, 0.83, 0.67, 0.5, 0.33, 0.17]);+ for (const score of scores) {+ expect(score).toBeGreaterThan(0);+ expect(score).toBeLessThanOrEqual(1);+ }+ for (let i = 1; i < scores.length; i += 1) expect(scores[i]).toBeLessThan(scores[i - 1]);+ });++ it("clamps a tier outside the known range rather than going negative", () => {+ expect(tierRelevance(-3)).toBe(1);+ expect(tierRelevance(99)).toBe(tierRelevance(5));+ });+});++describe("foldChunkTwins", () => {+ it("drops a chunk whose symbol is already in the answer", () => {+ const folded = foldChunkTwins([+ row(withPath("resolveWorkspaceRoot", "function", "ix-cli/src/cli/config.ts"), 0),+ row(withPath("resolveWorkspaceRoot", "chunk", "ix-cli/src/cli/config.ts"), 0),+ ]);+ expect(folded.map((s) => s.node.kind)).toEqual(["function"]);+ });++ it("keeps a chunk that is the only row standing for its text", () => {+ const folded = foldChunkTwins([+ row(withPath("resolveWorkspaceRoot", "function", "ix-cli/src/cli/config.ts"), 0),+ row(withPath("file_body:120", "chunk", "ix-cli/src/cli/config.ts"), 3),+ ]);+ expect(folded).toHaveLength(2);+ });++ it("keeps a same-named chunk from a different file", () => {+ // Same name, different file: not a twin, and the symbol row for that file+ // is not in the answer to replace it.+ const folded = foldChunkTwins([+ row(withPath("parse", "function", "ix-cli/src/a.ts"), 0),+ row(withPath("parse", "chunk", "ix-cli/src/b.ts"), 0),+ ]);+ expect(folded).toHaveLength(2);+ });++ it("leaves a chunk-only answer alone", () => {+ const rows = [row(withPath("file_body:1", "chunk", "a.ts"), 5)];+ expect(foldChunkTwins(rows)).toEqual(rows);+ });+});++describe("dropIncidentalMatches", () => {+ it("drops the bottom tier when something matched by name", () => {+ const kept = dropIncidentalMatches([+ row(withPath("search", "method", "a.ts"), 1),+ row(withPath("unrelated", "function", "b.ts"), 5),+ ]);+ expect(kept.map((s) => s.node.name)).toEqual(["search"]);+ });++ it("keeps the bottom tier when it is all there is", () => {+ const rows = [+ row(withPath("unrelated", "function", "b.ts"), 5),+ row(withPath("other", "function", "c.ts"), 5),+ ];+ expect(dropIncidentalMatches(rows)).toEqual(rows);+ });++ it("runs before the limit, so a dropped row makes room", () => {+ const scored = [+ row(withPath("a", "function", "a.ts"), 0),+ row(withPath("fuzz", "config_entry", "z.ts"), 5),+ row(withPath("b", "function", "b.ts"), 3),+ ];+ const shown = dropIncidentalMatches(scored).slice(0, 2);+ expect(shown.map((s) => s.node.name)).toEqual(["a", "b"]);+ });+});diff --git a/ix-cli/src/cli/commands/search.ts b/ix-cli/src/cli/commands/search.tsindex d5410abd..c4076856 100644--- a/ix-cli/src/cli/commands/search.ts+++ b/ix-cli/src/cli/commands/search.ts@@ -101,6 +101,77 @@ function searchSort(return aName.localeCompare(bName);}+/** Tier 0 through tier 5 — see `rankScore`. */+const TIER_COUNT = 6;++/** The lowest tier: nothing in the name matched, only an attribute did. */+const INCIDENTAL_TIER = 5;++/**+ * The tier as a 0-1 relevance, best first.+ *+ * The internal sort key is negative and "lower is better" — `score=-101` above+ * `score=-31` — which is exactly backwards from what every other score an agent+ * meets means, and it leaked into `--format json` and `--format llm` as the only+ * number on the row. There are six tiers, so each is worth a sixth: 1.00 for an+ * exact name and kind, down to 0.17 for a match that came from an attribute.+ *+ * Deliberately per-tier and not per-row: the sub-score that separates two rows+ * inside a tier is a sum of two heuristics with no calibrated meaning, and the+ * order it produces is already carried by the order the rows are printed in+ * (and by `rank` in JSON). A number that looks more precise than it is invites+ * an agent to threshold on it.+ */+export function tierRelevance(tier: number): number {+ const clamped = Math.min(Math.max(tier, 0), TIER_COUNT - 1);+ return Math.round(((TIER_COUNT - clamped) / TIER_COUNT) * 100) / 100;+}++type Scored = { node: any; rank: { tier: number; score: number; matchSource: string } };++function rowPath(node: any): string {+ return normalizePath(node.provenance?.sourceUri ?? node.provenance?.source_uri ?? "");+}++/**+ * Drop a chunk row when the symbol it was cut from is already in the answer.+ *+ * A chunk is a retrieval unit: the ingester emits one per symbol, named after+ * that symbol and carrying a `DEFINES` edge to it (core-ingestion+ * `patch-builder.ts`). So a search that matches a function by name matches its+ * chunk too, and the pair arrives as two rows with the same name and the same+ * file — one of which no command can then do anything with, because `explain`,+ * `callers` and `read` all want the symbol.+ *+ * A chunk with no twin survives: an unnamed `file_body:` chunk is the only row+ * standing for that part of the file, and dropping it would lose the hit.+ */+export function foldChunkTwins(scored: Scored[]): Scored[] {+ const symbols = new Set(+ scored+ .filter((s) => (s.node.kind || "").toLowerCase() !== "chunk")+ .map((s) => `${(s.node.name || "").toLowerCase()}\u0000${rowPath(s.node)}`),+ );+ if (symbols.size === 0) return scored;+ return scored.filter((s) => {+ if ((s.node.kind || "").toLowerCase() !== "chunk") return true;+ return !symbols.has(`${(s.node.name || "").toLowerCase()}\u0000${rowPath(s.node)}`);+ });+}++/**+ * Drop the bottom tier once something actually matched by name.+ *+ * Tier 5 is the resolver's fallback: no part of the name matched and the row is+ * here because a term appeared somewhere in the node's attributes. Next to a+ * real hit it is filler that pushes a relevant row off the end of `--limit`.+ * With nothing better in the set it is the only answer there is, so it stays.+ */+export function dropIncidentalMatches(scored: Scored[]): Scored[] {+ const named = scored.some((s) => s.rank.tier < INCIDENTAL_TIER);+ return named ? scored.filter((s) => s.rank.tier < INCIDENTAL_TIER) : scored;+}+function normalizePath(value: string | undefined): string {return (value ?? "").toLowerCase().replace(/\\/g, "/");}@@ -120,13 +191,15 @@ export function registerSearchCommand(program: Command): void {.option("--include-tests", "Include test and fixture entities in results").option("--tests-only", "Show only test and fixture entities").option("--semantic", "Use vector-similarity (embedding) search instead of keyword matching")- .addHelpText("after", `\nRanking priority:+ .addHelpText("after", `\nRanking priority (score 1.00 down to 0.17):1. Exact name + exact kind match2. Exact name + structural kind (class, function, etc.)3. Exact name (any kind)4. Exact filename/module match5. Container-aware near match- 6. Fuzzy/incidental match+ 6. Fuzzy/incidental match — dropped when any of 1-5 matched++A chunk is folded away when the symbol it was cut from is already in the answer.Use --path to filter results from specific directories.Keyword searches send --path to the backend as a candidate filter (backend 1.0.31+)@@ -214,12 +287,18 @@ Examples:if (!opts.semantic) scored.sort(searchSort);+ // Rank, then prune, then cut. Both passes run before `--limit` so a row+ // dropped here makes room for a real one instead of leaving a shorter+ // answer. Semantic search keeps its own ordering but is pruned the same+ // way: a chunk twin is just as useless there.+ const hygienic = dropIncidentalMatches(foldChunkTwins(scored));+const { filtered: roleFiltered, hiddenTestCount } = applyRoleFilter(- scored.map(s => s.node),+ hygienic.map(s => s.node),{ includeTests: opts.includeTests, testsOnly: opts.testsOnly },);// Re-wrap with scores for trimming- const roleFilteredScored = scored.filter(s => roleFiltered.includes(s.node));+ const roleFilteredScored = hygienic.filter(s => roleFiltered.includes(s.node));const trimmed = roleFilteredScored.slice(0, limit);const ranked = trimmed.map(s => s.node);@@ -242,16 +321,26 @@ Examples:message: roleHint(hiddenTestCount)!,});}+ // `unfiltered_search` fires on every search that did not pass `--kind`,+ // which is most of them, and says the same eighteen words each time+ // about results the caller can already see. It stays in JSON, where a+ // program may be keyed to it, and stays out of the record stream an+ // agent reads.+ //+ // Taken after every push, not before: `test_candidates_hidden` is the+ // one diagnostic here that names rows the caller CANNOT see, and it is+ // added below the `unfiltered_search` push.+ const llmDiagnostics = diagnostics.filter((d) => d.code !== "unfiltered_search");if (opts.format === "llm") {- const rows = trimmed.map((s, i) => ({+ const rows = trimmed.map((s) => ({name: s.node.name || (s.node.attrs as any)?.name || "(unnamed)",kind: s.node.kind,id: s.node.id,path: relativePath(s.node.provenance?.sourceUri) ?? undefined,- score: s.rank.score,+ score: tierRelevance(s.rank.tier),}));- for (const line of renderSearchLlm(rows, rawNodes.length, diagnostics)) console.log(line);+ for (const line of renderSearchLlm(rows, rawNodes.length, llmDiagnostics)) console.log(line);return;}@@ -265,7 +354,7 @@ Examples:language: (s.node.attrs as any)?.language ?? undefined,rank: i + 1,tier: s.rank.tier,- score: s.rank.score,+ score: tierRelevance(s.rank.tier),matchSource: s.rank.matchSource,})),summary: {