Skip to content

armgit / Ix

Public Imported from GitHub
0

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

feat(cli): search rows carry path:lines, and drop what is not a match

KageBinaryff3e066adbad
diff --git a/ix-cli/src/cli/__tests__/llm-tier3.test.ts b/ix-cli/src/cli/__tests__/llm-tier3.test.ts
index 81790465..7874fc88 100644
--- a/ix-cli/src/cli/__tests__/llm-tier3.test.ts
+++ b/ix-cli/src/cli/__tests__/llm-tier3.test.ts
@@ -36,13 +36,13 @@ describe("renderTextResultsLlm", () => {
describe("renderSearchLlm", () => {
it("emits a header, node rows, then diagnostic rows", () => {
const lines = renderSearchLlm(
- [{ name: "Foo", kind: "class", id: "abcdef1234567890", path: "src/a.ts", score: 5 }],
+ [{ name: "Foo", kind: "class", id: "abcdef1234567890", path: "src/a.ts", lines: "3-9", score: 5 }],
10,
[{ code: "unfiltered_search", message: "broad" }],
);
expect(lines).toEqual([
"search count=1 candidates=10",
- "node name=Foo kind=class id=abcdef12 path=src/a.ts score=5",
+ "node name=Foo kind=class path=src/a.ts lines=3-9 score=5",
"diagnostic code=unfiltered_search message=broad",
]);
});
diff --git a/ix-cli/src/cli/__tests__/row-noise.test.ts b/ix-cli/src/cli/__tests__/row-noise.test.ts
new file mode 100644
index 00000000..0b1e88a7
--- /dev/null
+++ b/ix-cli/src/cli/__tests__/row-noise.test.ts
@@ -0,0 +1,87 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { dropNonNameMatches, emptySearchHint, renderSearchLlm } from "../commands/search.js";
+import { setOutputShape } from "../output-shape.js";
+
+afterEach(() => setOutputShape({}));
+
+function row(name: string, tier: number, matchSource = "name_exact") {
+ return { node: { name, kind: "function" }, rank: { tier, score: -tier, matchSource } };
+}
+
+describe("search rows", () => {
+ it("carry the span, so the row is a place to read and not a name to grep for", () => {
+ const lines = renderSearchLlm(
+ [{ name: "resolveWorkspaceRoot", kind: "function", id: "fd53308b-67fb", path: "ix-cli/src/cli/config.ts", lines: "320-340", score: 0.83 }],
+ 30, [],
+ );
+ expect(lines[1]).toBe("node name=resolveWorkspaceRoot kind=function path=ix-cli/src/cli/config.ts lines=320-340 score=0.83");
+ });
+
+ it("keep an id only where name, kind and path collide", () => {
+ const lines = renderSearchLlm([
+ { name: "dup", kind: "function", id: "aaaaaaaa11112222", path: "a.ts", lines: "1-2" },
+ { name: "dup", kind: "function", id: "bbbbbbbb11112222", path: "a.ts", lines: "5-6" },
+ { name: "solo", kind: "function", id: "cccccccc11112222", path: "a.ts", lines: "9" },
+ ], 3, []);
+ expect(lines.slice(1)).toEqual([
+ "node name=dup kind=function id=aaaaaaaa path=a.ts lines=1-2",
+ "node name=dup kind=function id=bbbbbbbb path=a.ts lines=5-6",
+ "node name=solo kind=function path=a.ts lines=9",
+ ]);
+ });
+
+ it("print every id when the caller asks for them with --fields", () => {
+ setOutputShape({ fields: "name,id" });
+ const lines = renderSearchLlm([{ name: "solo", kind: "function", id: "cccccccc11112222", path: "a.ts" }], 1, []);
+ expect(lines[1]).toBe("node name=solo id=cccccccc");
+ });
+
+ it("mark a row that matched on something other than its name", () => {
+ const lines = renderSearchLlm([{ name: "other", kind: "function", path: "a.ts", score: 0.33, match: "claim_or_decision" }], 1, []);
+ expect(lines[1]).toBe("node name=other kind=function path=a.ts score=0.33 match=claim_or_decision");
+ });
+});
+
+describe("dropNonNameMatches", () => {
+ it("drops claim and provenance rows once a name matched exactly", () => {
+ const kept = dropNonNameMatches([
+ row("resolveWorkspaceRoot", 1),
+ row("resolveWorkspaceRootCache", 3, "name_partial"),
+ row("absoluteFromSourceUri", 4, "claim_or_decision"),
+ ]);
+ expect(kept.map((s) => s.node.name)).toEqual(["resolveWorkspaceRoot", "resolveWorkspaceRootCache"]);
+ });
+
+ it("keeps them when only partial names matched: they may be the only lead", () => {
+ const rows = [row("WorkspaceRootish", 3, "name_partial"), row("absoluteFromSourceUri", 4, "claim_or_decision")];
+ expect(dropNonNameMatches(rows)).toHaveLength(2);
+ });
+});
+
+describe("an empty search", () => {
+ it("says a phrase is the problem when it was given one", () => {
+ const hint = emptySearchHint("workspace resolve read");
+ expect(hint).toContain("one identifier");
+ expect(hint).toContain("e.g. workspace");
+ expect(hint).toContain("ix text");
+ });
+
+ it("names the filters it could drop", () => {
+ expect(emptySearchHint("zzq", { kind: "class", path: "src" })).toContain("drop --kind/--path");
+ expect(emptySearchHint("zzq")).not.toContain("drop");
+ });
+
+ it("follows count=0 with a hint record, and --quiet drops it", () => {
+ expect(renderSearchLlm([], 0, [], "try x")).toEqual(["search count=0 candidates=0", "hint text=\"try x\""]);
+ setOutputShape({ quiet: true });
+ expect(renderSearchLlm([], 0, [], "try x")).toEqual(["search count=0 candidates=0"]);
+ });
+
+ it("never adds the hint to a search that found something", () => {
+ const lines = renderSearchLlm([{ name: "a", kind: "function", path: "a.ts" }], 1, [], "try x");
+ expect(lines.some((l) => l.startsWith("hint"))).toBe(false);
+ });
+});
diff --git a/ix-cli/src/cli/commands/search.ts b/ix-cli/src/cli/commands/search.ts
index 0ac8f47b..145ca38c 100644
--- a/ix-cli/src/cli/commands/search.ts
+++ b/ix-cli/src/cli/commands/search.ts
@@ -5,35 +5,82 @@ import chalk from "chalk";
import { IxClient } from "../../client/api.js";
import { getEndpoint } from "../config.js";
import { resolveWorkspaceId } from "../bootstrap.js";
-import { formatNodes, relativePath, printJson } from "../format.js";
+import { disambiguatingIds, formatNodes, lineSpan, relativePath, printJson, rowLocation } from "../format.js";
import { baseScore, originPenalty, hasDefinitionOf, mergeById, resolveReadSystemId } from "../resolve.js";
import { isFileStemMatch } from "../candidate-origin.js";
import { applyRoleFilter, roleHint } from "../role-filter.js";
import { stderr } from "../stderr.js";
-import { llmLine, llmShortId } from "../llm.js";
+import { llmLine } from "../llm.js";
import { isQuiet, projectRow } from "../output-shape.js";
import { normalizePathSeparators } from "../path-match.js";
-/** Render `ix search` as llm records: a header line then one `node` row per hit (rank = order). */
+/** One `ix search` row as the llm renderer takes it. */
+export interface SearchLlmRow {
+ name: string;
+ kind: string;
+ id?: string;
+ path?: string;
+ /** `320-340`, from the graph's span; absent for a file or an unknown span. */
+ lines?: string;
+ score?: number;
+ /** Set only for a row that matched on something other than its name. */
+ match?: string;
+}
+
+/**
+ * Render `ix search` as llm records: a header line then one `node` row per hit
+ * (rank = order).
+ *
+ * `path` and `lines` together are the answer — the tool is described to agents
+ * as returning path:lines, and a row without the span sent them to grep for
+ * it. The id is printed only where two rows would otherwise read the same (see
+ * `disambiguatingIds`). A row that did not match by name says what it matched
+ * on in `match=`, so it cannot be mistaken for a definition.
+ */
export function renderSearchLlm(
- results: Array<{ name: string; kind: string; id?: string; path?: string; score?: number }>,
+ results: SearchLlmRow[],
totalCandidates: number, diagnostics: Array<{ code: string; message: string }>,
+ hint?: string,
): string[] {
const lines = [llmLine("search", [["count", results.length], ["candidates", totalCandidates]])];
- for (const r of results) {
+ const ids = disambiguatingIds(
+ results,
+ (r) => `${r.name}\u0000${r.kind}\u0000${r.path ?? ""}`,
+ (r) => r.id,
+ );
+ results.forEach((r, i) => {
lines.push(llmLine("node", projectRow([
- ["name", r.name], ["kind", r.kind], ["id", llmShortId(r.id)],
- ["path", r.path], ["score", r.score],
+ ["name", r.name], ["kind", r.kind], ["id", ids[i]],
+ ["path", r.path], ["lines", r.lines], ["score", r.score], ["match", r.match],
])));
- }
+ });
// Advice, not findings: `--quiet` drops it. An error still reaches the
// caller through the error path, which this is not.
if (!isQuiet()) {
for (const d of diagnostics) lines.push(llmLine("diagnostic", [["code", d.code], ["message", d.message]]));
+ if (hint && results.length === 0) lines.push(llmLine("hint", [["text", hint]]));
}
return lines;
}
+/**
+ * What to try after a search that found nothing.
+ *
+ * A bare `count=0` left an agent to guess why, and the usual reason is that it
+ * searched a phrase: search matches entity names, and no name contains
+ * "workspace resolve read".
+ */
+export function emptySearchHint(term: string, opts: { kind?: string; path?: string; language?: string } = {}): string {
+ const words = term.trim().split(/\s+/).filter((w) => w !== "");
+ if (words.length > 1) {
+ const longest = [...words].sort((a, b) => b.length - a.length)[0];
+ return `search matches one identifier by name, not a phrase. Search one word (e.g. ${longest}), or use ix text for a phrase.`;
+ }
+ const narrowed = [opts.kind && "--kind", opts.path && "--path", opts.language && "--language"].filter(Boolean);
+ const drop = narrowed.length > 0 ? `drop ${narrowed.join("/")}, ` : "";
+ return `No entity name matches. Try part of the name, ${drop}or use ix text for a literal string.`;
+}
+
/** Structural kinds that should rank higher than incidental matches. */
const STRUCTURAL_KINDS = new Set([
"class", "trait", "object", "interface", "function", "method", "module", "file",
@@ -210,6 +257,27 @@ export function dropIncidentalMatches(scored: Scored[]): Scored[] {
return named ? scored.filter((s) => s.rank.tier < INCIDENTAL_TIER) : scored;
}
+/** The name tiers: exact name (0-2). A partial name (3) is still a name match, but not a definition. */
+const EXACT_NAME_TIER = 2;
+
+/** Tier 4: the row matched on its provenance or a claim about it, not its name. */
+const NON_NAME_TIER = 4;
+
+/**
+ * Drop rows that did not match by name once one matched the name exactly.
+ *
+ * Searching `resolveWorkspaceRoot` returned its four definitions and then six
+ * rows at 0.33 — `absoluteFromSourceUri`, `createStaleProbe` — that matched a
+ * claim mentioning the term, because they call it. That is a callers answer
+ * served as a search answer, and an agent looking for a definition read it as
+ * padding. With no exact name in the set those rows can be the only lead, so
+ * they stay, marked `match=` in llm output.
+ */
+export function dropNonNameMatches(scored: Scored[]): Scored[] {
+ const exact = scored.some((s) => s.rank.tier <= EXACT_NAME_TIER);
+ return exact ? scored.filter((s) => s.rank.tier < NON_NAME_TIER) : scored;
+}
+
function normalizePath(value: string | undefined): string {
return (value ?? "").toLowerCase().replace(/\\/g, "/");
}
@@ -240,8 +308,9 @@ export function registerSearchCommand(program: Command): void {
rank here, behind it: imports of the name, CSS selectors, markdown
headings and JSON keys (for a code-like term), and copies in build
output (dist/, *.min.js, *-output.*), fixtures and samples
- 4. Exact filename/module match
- 5. Container-aware near match
+ 4. Partial name match
+ 5. Matched on provenance or a claim, not the name — dropped when any of
+ 1-3 matched; marked match=<source> in --format llm
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.
@@ -369,7 +438,7 @@ Examples:
// 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 hygienic = dropNonNameMatches(dropIncidentalMatches(foldChunkTwins(scored)));
const { filtered: roleFiltered, hiddenTestCount } = applyRoleFilter(
hygienic.map(s => s.node),
@@ -411,14 +480,17 @@ Examples:
const llmDiagnostics = diagnostics.filter((d) => d.code !== "unfiltered_search");
if (opts.format === "llm") {
- const rows = trimmed.map((s) => ({
+ const rows: SearchLlmRow[] = 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,
+ lines: lineSpan(rowLocation(s.node)),
score: tierRelevance(s.rank.tier),
+ match: s.rank.tier >= NON_NAME_TIER ? s.rank.matchSource : undefined,
}));
- for (const line of renderSearchLlm(rows, rawNodes.length, llmDiagnostics)) console.log(line);
+ const hint = emptySearchHint(term, opts);
+ for (const line of renderSearchLlm(rows, rawNodes.length, llmDiagnostics, hint)) console.log(line);
return;
}
@@ -439,10 +511,13 @@ Examples:
count: ranked.length,
totalCandidates: rawNodes.length,
},
- diagnostics,
+ diagnostics: ranked.length === 0
+ ? [...diagnostics, { code: "no_results", message: emptySearchHint(term, opts) }]
+ : diagnostics,
});
} else {
formatNodes(ranked, opts.format);
+ if (ranked.length === 0 && !isQuiet()) stderr(chalk.dim(emptySearchHint(term, opts)));
if (pathWindowLimited) stderr(chalk.dim(diagnostics.find(d => d.code === "path_search_truncated")!.message));
const hint = roleHint(hiddenTestCount);
if (hint) stderr(chalk.dim(hint));
diff --git a/ix-cli/src/cli/format.ts b/ix-cli/src/cli/format.ts
index f09c98d7..dde594dd 100644
--- a/ix-cli/src/cli/format.ts
+++ b/ix-cli/src/cli/format.ts
@@ -2,7 +2,7 @@
import chalk from "chalk";
import { llmLine, llmShortId } from "./llm.js";
-import { projectRow } from "./output-shape.js";
+import { projectRow, requestedFields } from "./output-shape.js";
export type ResultSource = "graph" | "text" | "graph+text" | "heuristic";
@@ -203,6 +203,29 @@ export function locationLabel(loc: { path?: string; lineStart?: number; lineEnd?
return span ? `${loc.path}:${span}` : loc.path;
}
+/**
+ * The ids a list of rows should print: only where nothing else on the row
+ * tells it apart from another row in the same answer.
+ *
+ * Every search and edge row used to carry an 8-character id, and nothing an
+ * agent does next takes one — `read`, `callers` and `explain` are all called
+ * by name and narrowed with `--path`. Two rows with the same name, kind and
+ * path are the exception: nothing a caller can pass tells them apart except
+ * the id (every symbol command takes one), so those keep it. `lines` is not
+ * part of the key because no command takes a span to pick by. A caller who
+ * asks for ids with `--fields id` gets them on every row.
+ */
+export function disambiguatingIds<T>(
+ rows: T[],
+ key: (row: T) => string,
+ id: (row: T) => string | undefined,
+): Array<string | undefined> {
+ const wanted = requestedFields()?.includes("id") ?? false;
+ const counts = new Map<string, number>();
+ for (const row of rows) counts.set(key(row), (counts.get(key(row)) ?? 0) + 1);
+ return rows.map((row) => (wanted || (counts.get(key(row)) ?? 0) > 1 ? llmShortId(id(row)) : undefined));
+}
+
export function confidenceColor(score: number): (text: string) => string {
if (score >= 0.8) return chalk.green;
if (score >= 0.5) return chalk.yellow;