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
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.tsindex 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.tsnew file mode 100644index 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.tsindex 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, markdownheadings and JSON keys (for a code-like term), and copies in buildoutput (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 llm6. Fuzzy/incidental match — dropped when any of 1-5 matchedA 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.tsindex 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;