Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

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.ts
new file mode 100644
index 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.ts
index 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 match
2. Exact name + structural kind (class, function, etc.)
3. Exact name (any kind)
4. Exact filename/module match
5. 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: {