Skip to content

armgit / Ix

Public Imported from GitHub
0

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

fix(cli): report what a bounded list left behind, and rank before cutting it

KageBinary28ebb8d34f33
diff --git a/docs/llm-format.md b/docs/llm-format.md
index 37c2453b..27956a02 100644
--- a/docs/llm-format.md
+++ b/docs/llm-format.md
@@ -48,6 +48,30 @@ region id=cli kind=subsystem label="Client" parent=root
region id=srv kind=subsystem label="Server" parent=root
```
+## Bounded lists
+
+Any command that cuts its answer to `--limit` says both numbers on its header
+record: `shown` is what follows, `total` is what there was before the cut.
+
+```
+callers target=verify_token shown=50 total=212 resolved=48 unresolved=2
+diagnostic code=results_truncated message="212 callers; showing 50. Raise --limit to see the rest."
+```
+
+`shown < total` is the only signal that a list is partial, and it exists
+because the header used to carry a single `total` field holding the length of
+the *cut* list — so `ix callers` on a symbol with 212 callers reported
+`total=50`, which reads as "this symbol has 50 callers".
+
+Two commands cannot know a true total and say so rather than inventing one:
+
+- `ix inventory` reports `shown=N truncated=true`. The backend applies the
+ limit and has no count endpoint, so the CLI only knows the window it asked
+ for came back full.
+- `ix text` reports `shown=N scanned=M`: ripgrep's traversal is bounded by a
+ scan window, and `scanned` is how many matches were ranked, not how many
+ exist.
+
## Examples
`ix stats`:
diff --git a/ix-cli/src/cli/__tests__/format.test.ts b/ix-cli/src/cli/__tests__/format.test.ts
index d3d086c8..7b09ab64 100644
--- a/ix-cli/src/cli/__tests__/format.test.ts
+++ b/ix-cli/src/cli/__tests__/format.test.ts
@@ -7,6 +7,7 @@ import {
formatConflicts,
formatDecisions,
formatTextResults,
+ sliceRanked,
confidenceColor,
} from "../format.js";
@@ -310,14 +311,14 @@ describe("formatTextResults", () => {
it("should output JSON when format is json", () => {
const spy = vi.spyOn(console, "log").mockImplementation(() => {});
const results = [{ path: "src/foo.ts", line_start: 42, line_end: 42, snippet: "const foo = bar;", engine: "ripgrep", score: 1.0 }];
- formatTextResults(results, "json");
+ formatTextResults(sliceRanked(results, 20), "json");
expect(spy).toHaveBeenCalledWith(JSON.stringify(results, null, 2));
spy.mockRestore();
});
it("should show 'No text matches found.' for empty results", () => {
const spy = vi.spyOn(console, "log").mockImplementation(() => {});
- formatTextResults([], "text");
+ formatTextResults(sliceRanked([], 20), "text");
expect(spy).toHaveBeenCalledWith("No text matches found.");
spy.mockRestore();
});
@@ -325,7 +326,7 @@ describe("formatTextResults", () => {
it("should display path:line_start and snippet in text mode", () => {
const spy = vi.spyOn(console, "log").mockImplementation(() => {});
const results = [{ path: "src/foo.ts", line_start: 42, line_end: 42, snippet: "const foo = bar;", engine: "ripgrep", score: 1.0 }];
- formatTextResults(results, "text");
+ formatTextResults(sliceRanked(results, 20), "text");
const output = spy.mock.calls.map(c => c[0]).join("\n");
expect(output).toContain("src/foo.ts");
expect(output).toContain(":42");
diff --git a/ix-cli/src/cli/__tests__/honest-truncation.test.ts b/ix-cli/src/cli/__tests__/honest-truncation.test.ts
new file mode 100644
index 00000000..e9d42670
--- /dev/null
+++ b/ix-cli/src/cli/__tests__/honest-truncation.test.ts
@@ -0,0 +1,110 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+import { describe, expect, it } from "vitest";
+
+import { renderEdgeResultsLlm, sliceEdgeResults, sliceRanked } from "../format.js";
+import { renderInventoryLlm } from "../commands/inventory.js";
+import { scanWindow, textResultPriority } from "../commands/text.js";
+
+function node(name: string, path?: string) {
+ return { id: `${name}-0000-0000-0000-000000000000`, name, kind: "function", ...(path ? { provenance: { source_uri: path } } : {}) };
+}
+
+describe("sliceRanked", () => {
+ it("reports the count before the cut, not after it", () => {
+ const all = Array.from({ length: 212 }, (_, i) => node(`caller${i}`, "src/a.ts"));
+ const slice = sliceRanked(all, 50);
+ expect(slice.shown).toBe(50);
+ expect(slice.total).toBe(212);
+ expect(slice.truncated).toBe(true);
+ });
+
+ it("is not truncated when everything fits", () => {
+ const slice = sliceRanked([node("a", "src/a.ts")], 50);
+ expect(slice).toMatchObject({ shown: 1, total: 1, truncated: false });
+ });
+
+ it("keeps the source order among rows that rank equally", () => {
+ const all = [node("b", "src/b.ts"), node("a", "src/a.ts")];
+ expect(sliceRanked(all, 10, () => 0).rows.map((n) => n.name)).toEqual(["b", "a"]);
+ });
+
+ it("does not mutate the caller's array", () => {
+ const all = [node("b", "src/b.ts"), node("a")];
+ const copy = [...all];
+ sliceRanked(all, 10, (n) => (n.provenance ? 0 : 1));
+ expect(all).toEqual(copy);
+ });
+});
+
+describe("sliceEdgeResults", () => {
+ it("keeps followable rows over dangling ones when the cut bites", () => {
+ const all = [
+ { id: "aaaaaaaa-1111-0000-0000-000000000000", name: "d41d8cd98f00b204e9800998ecf8427e", kind: "method" },
+ { id: "bbbbbbbb-2222-0000-0000-000000000000", name: "handleLogin", kind: "method" },
+ { id: "cccccccc-3333-0000-0000-000000000000", name: "verify", kind: "method", provenance: { source_uri: "src/a.ts" } },
+ ];
+ const rows = sliceEdgeResults(all, 2).rows.map((n) => n.name);
+ expect(rows).toEqual(["verify", "handleLogin"]);
+ });
+
+ it("still reports the rows it dropped", () => {
+ const all = [
+ { id: "aaaaaaaa-1111-0000-0000-000000000000", name: "d41d8cd98f00b204e9800998ecf8427e", kind: "method" },
+ { id: "bbbbbbbb-2222-0000-0000-000000000000", name: "handleLogin", kind: "method", provenance: { source_uri: "src/a.ts" } },
+ ];
+ const header = renderEdgeResultsLlm(sliceEdgeResults(all, 1), "callers", "verify_token", "graph")[0];
+ expect(header).toBe("callers target=verify_token shown=1 total=2 resolved=1");
+ });
+
+ it("names the flag that would show the rest", () => {
+ const all = Array.from({ length: 212 }, (_, i) => node(`c${i}`, "src/a.ts"));
+ const lines = renderEdgeResultsLlm(sliceEdgeResults(all, 50), "callers", "verify_token", "graph");
+ expect(lines[1]).toBe(
+ 'diagnostic code=results_truncated message="212 callers; showing 50. Raise --limit to see the rest."',
+ );
+ });
+});
+
+describe("renderInventoryLlm", () => {
+ it("says shown, and marks a full window rather than inventing a total", () => {
+ const nodes = [{ name: "Foo", kind: "class", provenance: { source_uri: "src/a.ts" } }];
+ expect(renderInventoryLlm("class", null, nodes, true).slice(0, 2)).toEqual([
+ "inventory kind=class shown=1 truncated=true",
+ 'diagnostic code=results_truncated message="More than 1 class entities exist. Raise --limit, or narrow with --path."',
+ ]);
+ });
+
+ it("says nothing about truncation when the window was not full", () => {
+ const nodes = [{ name: "Foo", kind: "class", provenance: { source_uri: "src/a.ts" } }];
+ expect(renderInventoryLlm("class", null, nodes)[0]).toBe("inventory kind=class shown=1");
+ });
+});
+
+describe("text result ranking", () => {
+ it("scans past the limit so ranking has something to rank", () => {
+ expect(scanWindow(20)).toBe(100);
+ expect(scanWindow(1)).toBe(5);
+ expect(scanWindow(400)).toBe(500);
+ });
+
+ it("puts code above tests, and tests above prose", () => {
+ expect(textResultPriority("ix-cli/src/cli/format.ts")).toBe(0);
+ expect(textResultPriority("ix-cli/src/cli/__tests__/format.test.ts")).toBe(1);
+ expect(textResultPriority("ix-cli/test/fixtures/a.ts")).toBe(1);
+ expect(textResultPriority("README.md")).toBe(2);
+ expect(textResultPriority("docs/api/README.md")).toBe(2);
+ expect(textResultPriority("package-lock.json")).toBe(2);
+ });
+
+ it("reorders the answer before the limit cuts it", () => {
+ const rows = [
+ { path: "README.md", line_start: 1, line_end: 1, snippet: "a", engine: "ripgrep", score: 1 },
+ { path: "docs/guide.md", line_start: 2, line_end: 2, snippet: "b", engine: "ripgrep", score: 1 },
+ { path: "src/a.ts", line_start: 3, line_end: 3, snippet: "c", engine: "ripgrep", score: 1 },
+ ];
+ const slice = sliceRanked(rows, 1, (r) => textResultPriority(r.path));
+ expect(slice.rows.map((r) => r.path)).toEqual(["src/a.ts"]);
+ expect(slice.total).toBe(3);
+ });
+});
diff --git a/ix-cli/src/cli/__tests__/llm-tier2.test.ts b/ix-cli/src/cli/__tests__/llm-tier2.test.ts
index 427b0eb2..3fca8ef5 100644
--- a/ix-cli/src/cli/__tests__/llm-tier2.test.ts
+++ b/ix-cli/src/cli/__tests__/llm-tier2.test.ts
@@ -1,7 +1,7 @@
// Copyright 2026 Ix Infrastructure Inc.
import { describe, it, expect } from "vitest";
-import { renderEdgeResultsLlm } from "../format.js";
+import { renderEdgeResultsLlm, sliceEdgeResults } from "../format.js";
import { renderInventoryLlm } from "../commands/inventory.js";
import { renderRankLlm } from "../commands/rank.js";
import { renderDependsLlm, type DependencyNode } from "../commands/depends.js";
@@ -13,15 +13,15 @@ describe("renderEdgeResultsLlm", () => {
{ id: "abcdef1234567890", name: "handleLogin", kind: "method", provenance: { source_uri: "src/a.ts" } },
{ id: "deadbeef00000000", name: "", kind: "method" },
];
- const lines = renderEdgeResultsLlm(nodes, "callers", "verify_token", "graph");
- expect(lines[0]).toBe("callers target=verify_token total=2 resolved=1 unresolved=1");
+ const lines = renderEdgeResultsLlm(sliceEdgeResults(nodes, 50), "callers", "verify_token", "graph");
+ expect(lines[0]).toBe("callers target=verify_token shown=2 total=2 resolved=1 unresolved=1");
expect(lines[1]).toBe("ref name=handleLogin kind=method id=abcdef12 path=src/a.ts");
expect(lines[2]).toBe("ref kind=method id=deadbeef resolved=false");
});
it("emits a no_edges diagnostic when empty", () => {
- const lines = renderEdgeResultsLlm([], "callees", "foo", "graph");
- expect(lines[0]).toBe("callees target=foo total=0 resolved=0");
+ const lines = renderEdgeResultsLlm(sliceEdgeResults([], 50), "callees", "foo", "graph");
+ expect(lines[0]).toBe("callees target=foo shown=0 total=0 resolved=0");
expect(lines[1]).toBe('diagnostic code=no_edges message="No callees edges found."');
});
});
@@ -35,7 +35,7 @@ describe("renderInventoryLlm", () => {
];
const lines = renderInventoryLlm("class", "auth", nodes);
expect(lines).toEqual([
- "inventory kind=class scope=auth total=3",
+ "inventory kind=class scope=auth shown=3",
"file path=src/a.ts items=Foo,Bar",
"item name=Baz kind=class",
]);
diff --git a/ix-cli/src/cli/__tests__/llm-tier3.test.ts b/ix-cli/src/cli/__tests__/llm-tier3.test.ts
index 6495b5fa..81790465 100644
--- a/ix-cli/src/cli/__tests__/llm-tier3.test.ts
+++ b/ix-cli/src/cli/__tests__/llm-tier3.test.ts
@@ -1,7 +1,7 @@
// Copyright 2026 Ix Infrastructure Inc.
import { describe, it, expect } from "vitest";
-import { renderNodesLlm, renderPatchesLlm, renderTextResultsLlm, type TextResult } from "../format.js";
+import { renderNodesLlm, renderPatchesLlm, renderTextResultsLlm, sliceRanked, type TextResult } from "../format.js";
import { renderSearchLlm } from "../commands/search.js";
import { renderHistoryLlm } from "../commands/history.js";
@@ -26,7 +26,10 @@ describe("renderTextResultsLlm", () => {
const results: TextResult[] = [
{ path: "src/a.ts", line_start: 42, line_end: 42, snippet: " const x = 1 ", engine: "ripgrep", score: 1, language: "typescript" },
];
- expect(renderTextResultsLlm(results)).toEqual(['match path=src/a.ts line=42 lang=typescript snippet="const x = 1"']);
+ expect(renderTextResultsLlm(sliceRanked(results, 20))).toEqual([
+ "text shown=1 scanned=1",
+ 'match path=src/a.ts line=42 lang=typescript snippet="const x = 1"',
+ ]);
});
});
diff --git a/ix-cli/src/cli/__tests__/text-workspace-boundary.test.ts b/ix-cli/src/cli/__tests__/text-workspace-boundary.test.ts
index 0e97ce97..9122a3a6 100644
--- a/ix-cli/src/cli/__tests__/text-workspace-boundary.test.ts
+++ b/ix-cli/src/cli/__tests__/text-workspace-boundary.test.ts
@@ -5,7 +5,7 @@ import { Command } from "commander";
import { mkdtempSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
-import { registerTextCommand, resolveTextSearchPath } from "../commands/text.js";
+import { registerTextCommand, resolveTextSearchPath, scanWindow } from "../commands/text.js";
describe("text workspace boundary", () => {
let fixture: string;
@@ -62,7 +62,11 @@ describe("text workspace boundary", () => {
await run(["text", "boundaryNeedle", "--root", workspace, "--path", "src", "--format", "json"]);
- expect(runRipgrep).toHaveBeenCalledWith(expect.arrayContaining(["boundaryNeedle", join(workspace, "src")]), 20);
+ // The scan window, not `--limit`: ranking has to see more rows than it prints.
+ expect(runRipgrep).toHaveBeenCalledWith(
+ expect.arrayContaining(["boundaryNeedle", join(workspace, "src")]),
+ scanWindow(20),
+ );
expect(JSON.parse(logs.join("\n"))).toMatchObject([{ path: "src/inside.ts" }]);
expect(process.exitCode).toBeUndefined();
});
diff --git a/ix-cli/src/cli/commands/callers.ts b/ix-cli/src/cli/commands/callers.ts
index 58a52e55..1c9c273f 100644
--- a/ix-cli/src/cli/commands/callers.ts
+++ b/ix-cli/src/cli/commands/callers.ts
@@ -6,7 +6,7 @@ import type { Command } from "commander";
import chalk from "chalk";
import { IxClient } from "../../client/api.js";
import { getEndpoint, resolveWorkspaceRoot } from "../config.js";
-import { formatEdgeResults, relativePath } from "../format.js";
+import { formatEdgeResults, relativePath, sliceEdgeResults } from "../format.js";
import { parsePickOption } from "../options.js";
import { resolveFileOrReport, printResolved } from "../resolve.js";
import { stderr } from "../stderr.js";
@@ -72,7 +72,7 @@ export function registerCallersCommand(program: Command): void {
if (opts.format === "llm") {
console.log(llmLine("callers", [
["target", target.name], ["source", "text"],
- ["total", textResults.length], ["candidates", candidatesFound],
+ ["shown", textResults.length], ["total", candidatesFound],
]));
console.log(llmLine("diagnostic", [
["code", "text_fallback_used"],
@@ -113,9 +113,9 @@ export function registerCallersCommand(program: Command): void {
} catch { /* ripgrep not available or no matches */ }
// Both graph and text empty
- formatEdgeResults([], "callers", target.name, opts.format, target, "graph");
+ formatEdgeResults(sliceEdgeResults([], limit), "callers", target.name, opts.format, target, "graph");
} else {
- formatEdgeResults(result.nodes.slice(0, limit), "callers", target.name, opts.format, target, "graph");
+ formatEdgeResults(sliceEdgeResults(result.nodes, limit), "callers", target.name, opts.format, target, "graph");
}
});
@@ -140,6 +140,6 @@ export function registerCallersCommand(program: Command): void {
direction: "out",
predicates: ["CALLS", "REFERENCES"],
});
- formatEdgeResults(result.nodes.slice(0, calleeLimit), "callees", target.name, opts.format, target, "graph");
+ formatEdgeResults(sliceEdgeResults(result.nodes, calleeLimit), "callees", target.name, opts.format, target, "graph");
});
}
diff --git a/ix-cli/src/cli/commands/contains.ts b/ix-cli/src/cli/commands/contains.ts
index 331fd387..e962045c 100644
--- a/ix-cli/src/cli/commands/contains.ts
+++ b/ix-cli/src/cli/commands/contains.ts
@@ -3,7 +3,7 @@
import type { Command } from "commander";
import { IxClient } from "../../client/api.js";
import { getEndpoint } from "../config.js";
-import { formatEdgeResults } from "../format.js";
+import { formatEdgeResults, sliceEdgeResults } from "../format.js";
import { parsePickOption } from "../options.js";
import { resolveFileOrReport, printResolved } from "../resolve.js";
@@ -25,7 +25,6 @@ export function registerContainsCommand(program: Command): void {
if (!target) return;
if (opts.format === "text") printResolved(target);
const result = await client.expand(target.id, { direction: "out", predicates: ["CONTAINS"] });
- const limited = result.nodes.slice(0, limit);
- formatEdgeResults(limited, "contains", target.name, opts.format, target, "graph");
+ formatEdgeResults(sliceEdgeResults(result.nodes, limit), "contains", target.name, opts.format, target, "graph");
});
}
diff --git a/ix-cli/src/cli/commands/imports.ts b/ix-cli/src/cli/commands/imports.ts
index fd916ea0..a68bf18b 100644
--- a/ix-cli/src/cli/commands/imports.ts
+++ b/ix-cli/src/cli/commands/imports.ts
@@ -3,7 +3,7 @@
import type { Command } from "commander";
import { IxClient } from "../../client/api.js";
import { getEndpoint } from "../config.js";
-import { formatEdgeResults } from "../format.js";
+import { formatEdgeResults, sliceEdgeResults } from "../format.js";
import { resolveFileOrReport, printResolved } from "../resolve.js";
import { parsePickOption } from "../options.js";
@@ -25,7 +25,7 @@ export function registerImportsCommand(program: Command): void {
if (!target) return;
if (opts.format === "text") printResolved(target);
const result = await client.expand(target.id, { direction: "out", predicates: ["IMPORTS"] });
- formatEdgeResults(result.nodes.slice(0, limit), "imports", target.name, opts.format, target, "graph");
+ formatEdgeResults(sliceEdgeResults(result.nodes, limit), "imports", target.name, opts.format, target, "graph");
});
program
@@ -45,6 +45,6 @@ export function registerImportsCommand(program: Command): void {
if (!target) return;
if (opts.format === "text") printResolved(target);
const result = await client.expand(target.id, { direction: "in", predicates: ["IMPORTS"] });
- formatEdgeResults(result.nodes.slice(0, limit), "imported-by", target.name, opts.format, target, "graph");
+ formatEdgeResults(sliceEdgeResults(result.nodes, limit), "imported-by", target.name, opts.format, target, "graph");
});
}
diff --git a/ix-cli/src/cli/commands/inventory.ts b/ix-cli/src/cli/commands/inventory.ts
index f65cbcef..e7c9eb0d 100644
--- a/ix-cli/src/cli/commands/inventory.ts
+++ b/ix-cli/src/cli/commands/inventory.ts
@@ -15,8 +15,16 @@ import { normalizePathSeparators } from "../path-match.js";
* source file with its entity names comma-joined (entities without a path
* become standalone `item` rows). Grouping mirrors the json renderer to avoid
* repeating the path on every entity.
+ *
+ * The header says `shown`, not `total`. The backend applies `--limit` itself,
+ * so this side never sees how many entities of that kind exist — it only knows
+ * whether the window it asked for came back full. Printing the length of a
+ * capped list as a total is the claim that made `ix callers` report 50 callers
+ * for a symbol with 212.
*/
-export function renderInventoryLlm(kind: string, scope: string | null, nodes: any[]): string[] {
+export function renderInventoryLlm(
+ kind: string, scope: string | null, nodes: any[], truncated = false,
+): string[] {
const byFile = new Map<string, string[]>();
const ungrouped: Array<{ name: string; kind: string }> = [];
for (const n of nodes) {
@@ -31,7 +39,18 @@ export function renderInventoryLlm(kind: string, scope: string | null, nodes: an
ungrouped.push({ name, kind: String(n.kind) });
}
}
- const lines = [llmLine("inventory", [["kind", kind], ["scope", scope ?? undefined], ["total", nodes.length]])];
+ const lines = [llmLine("inventory", [
+ ["kind", kind],
+ ["scope", scope ?? undefined],
+ ["shown", nodes.length],
+ ["truncated", truncated || undefined],
+ ])];
+ if (truncated) {
+ lines.push(llmLine("diagnostic", [
+ ["code", "results_truncated"],
+ ["message", `More than ${nodes.length} ${kind} entities exist. Raise --limit, or narrow with --path.`],
+ ]));
+ }
for (const [path, names] of byFile) {
lines.push(llmLine("file", [["path", path], ["items", names.join(",")]]));
}
@@ -72,7 +91,11 @@ Examples:
// `--path src\cli` matched nothing in either place (Ix#636). Case is
// untouched — see path-match.ts.
const pathNeedle = opts.path ? normalizePathSeparators(opts.path) : undefined;
- let nodes = await client.listByKind(opts.kind, { limit, workspaceId: systemId ? undefined : resolveWorkspaceId(), scope: pathNeedle, systemId });
+ // One past the limit, so a full window is distinguishable from an exact
+ // fit. The backend has no count endpoint, so this is the only honest
+ // answer available: "there is at least one more".
+ let nodes = await client.listByKind(opts.kind, { limit: limit + 1, workspaceId: systemId ? undefined : resolveWorkspaceId(), scope: pathNeedle, systemId });
+ const truncated = nodes.length > limit;
if (pathNeedle) {
nodes = nodes.filter((n) => {
@@ -86,6 +109,7 @@ Examples:
});
}
+ nodes = nodes.slice(0, limit);
const scope = opts.path ?? null;
if (opts.format === "json") {
@@ -111,7 +135,8 @@ Examples:
const output: any = {
kind: opts.kind,
scope: scope ?? undefined,
- total: nodes.length,
+ shown: nodes.length,
+ truncated,
byFile: grouped,
};
if (ungrouped.length > 0) output.ungrouped = ungrouped;
@@ -120,7 +145,7 @@ Examples:
}
if (opts.format === "llm") {
- for (const line of renderInventoryLlm(opts.kind, scope, nodes)) console.log(line);
+ for (const line of renderInventoryLlm(opts.kind, scope, nodes, truncated)) console.log(line);
return;
}
@@ -129,7 +154,8 @@ Examples:
return;
}
- console.log(`Inventory: ${nodes.length} ${opts.kind} entities${scope ? ` in ${scope}` : ""}`);
+ const more = truncated ? " (more exist — raise --limit)" : "";
+ console.log(`Inventory: ${nodes.length} ${opts.kind} entities${scope ? ` in ${scope}` : ""}${more}`);
for (const n of nodes) {
const name = n.name || n.attrs?.name || "(unnamed)";
const path = String(
diff --git a/ix-cli/src/cli/commands/text.ts b/ix-cli/src/cli/commands/text.ts
index 4a984041..9841f711 100644
--- a/ix-cli/src/cli/commands/text.ts
+++ b/ix-cli/src/cli/commands/text.ts
@@ -4,7 +4,7 @@ import { spawn } from "node:child_process";
import { createInterface } from "node:readline";
import path from "node:path";
import type { Command } from "commander";
-import { formatTextResults, type TextResult } from "../format.js";
+import { formatTextResults, sliceRanked, type TextResult } from "../format.js";
import { isPathInsideResolvedRoot, resolveWorkspaceRoot } from "../config.js";
import { stderr } from "../stderr.js";
import { llmError } from "../llm.js";
@@ -52,6 +52,47 @@ export function resolveTextSearchPath(root: string, searchPath: string): string
return path.resolve(root, searchPath);
}
+/**
+ * How far past `--limit` the scan looks before ranking.
+ *
+ * ripgrep walks the tree in directory order, so a plain `--limit 20` returns
+ * the first twenty matches it happened to reach — which on this repo means
+ * `docs/` and `README.md` before any code, because `d` and `R` sort early.
+ * Ranking the twenty rows it already cut cannot fix that; the scan has to see
+ * more than it prints. Bounded so a term matching everything is still one
+ * cheap pass.
+ */
+const SCAN_WINDOW_FACTOR = 5;
+const SCAN_WINDOW_MAX = 500;
+
+export function scanWindow(limit: number): number {
+ return Math.min(Math.max(limit * SCAN_WINDOW_FACTOR, limit), SCAN_WINDOW_MAX);
+}
+
+const TEST_PATH = /(^|\/)(tests?|__tests__|fixtures?|testdata|spec)(\/|$)|\.(test|spec)\./i;
+const PROSE_FILE = /\.(md|markdown|mdx|rst|txt|adoc)$/i;
+const GENERATED_FILE = /(^|\/)(package-lock\.json|[^/]*\.lock|[^/]*\.sum)$/i;
+
+/**
+ * Code first, then tests and fixtures, then prose and lockfiles.
+ *
+ * `ix mcp` describes this command's output as "ranked hits" and it was not
+ * ranked at all — it was ripgrep's traversal order. A README mentioning a
+ * symbol is the weakest evidence of the three: it cannot be called, read as a
+ * definition, or edited with any confidence. A test at least shows the symbol
+ * in use.
+ *
+ * Only these three bands, and the sort is stable, so within a band ripgrep's
+ * order survives. The alternative — scoring by line content — guesses at what
+ * the caller meant from a single grep term.
+ */
+export function textResultPriority(filePath: string): number {
+ const normalized = filePath.split(path.sep).join("/");
+ if (PROSE_FILE.test(normalized) || GENERATED_FILE.test(normalized)) return 2;
+ if (TEST_PATH.test(normalized)) return 1;
+ return 0;
+}
+
export function registerTextCommand(program: Command, executeRipgrep: RunRipgrep = runRipgrep): void {
program
.command("text <term>")
@@ -79,8 +120,11 @@ export function registerTextCommand(program: Command, executeRipgrep: RunRipgrep
return;
}
try {
+ const window = scanWindow(limit);
const rgArgs = [
"--json",
+ // Per file, deliberately still `--limit`: one file monopolising the
+ // scan window is the failure this is here to avoid.
"--max-count", String(limit),
];
@@ -101,7 +145,7 @@ export function registerTextCommand(program: Command, executeRipgrep: RunRipgrep
// other tool until the timeout and leaves the child process behind.
rgArgs.push("--", term, searchPath);
- const { stdout } = await executeRipgrep(rgArgs, limit);
+ const { stdout } = await executeRipgrep(rgArgs, window);
const results: TextResult[] = [];
for (const line of stdout.split("\n")) {
@@ -130,7 +174,10 @@ export function registerTextCommand(program: Command, executeRipgrep: RunRipgrep
}
}
- formatTextResults(results.slice(0, limit), opts.format);
+ formatTextResults(
+ sliceRanked(results, limit, (r) => textResultPriority(r.path)),
+ opts.format,
+ );
} catch (err: any) {
if (err.code === "ENOENT") {
stderr("Error: ripgrep (rg) is not installed. Install it: https://github.com/BurntSushi/ripgrep#installation");
@@ -138,7 +185,7 @@ export function registerTextCommand(program: Command, executeRipgrep: RunRipgrep
}
// rg exit 1 = no matches; render as empty result set
if (err.code === 1 || err.status === 1) {
- formatTextResults([], opts.format);
+ formatTextResults(sliceRanked([] as TextResult[], limit), opts.format);
return;
}
// rg exit 2 = usage/regex error (e.g. literal "\n" in regex,
diff --git a/ix-cli/src/cli/format.ts b/ix-cli/src/cli/format.ts
index 65d88785..d5bc9526 100644
--- a/ix-cli/src/cli/format.ts
+++ b/ix-cli/src/cli/format.ts
@@ -56,6 +56,74 @@ export function compactTreeNode(node: any): any {
return out;
}
+// ── Bounded lists ──────────────────────────────────────────────────────────
+
+/** A list that was cut to `--limit`, and what it left behind. */
+export interface Slice<T> {
+ /** The rows to print. */
+ rows: T[];
+ /** How many rows are printed. */
+ shown: number;
+ /** How many there were before the cut. */
+ total: number;
+ truncated: boolean;
+}
+
+/**
+ * Rank, then cut, then report both numbers.
+ *
+ * Every one of these commands used to slice first and then report the length of
+ * the slice as `total`, so `ix callers` on a symbol with 212 callers answered
+ * `total=50` — a number an agent has no reason to disbelieve, and which reads
+ * as "this symbol has 50 callers". The order matters as much as the count: a
+ * cut applied to an unranked list keeps whichever rows the graph happened to
+ * return first.
+ *
+ * `priority` is a small integer, low first, and the sort is stable, so rows
+ * that rank equally keep the order the backend gave them. It is not a general
+ * re-sort: the backend order carries information this layer cannot reconstruct,
+ * and the only claim made here is that rows the caller can act on should
+ * survive the cut before rows it cannot.
+ */
+export function sliceRanked<T>(all: T[], limit: number, priority?: (item: T) => number): Slice<T> {
+ const ranked = priority ? [...all].sort((a, b) => priority(a) - priority(b)) : all;
+ const rows = Number.isFinite(limit) ? ranked.slice(0, limit) : [...ranked];
+ return { rows, shown: rows.length, total: all.length, truncated: rows.length < all.length };
+}
+
+/**
+ * A name the extractor could not resolve to an entity — a raw id standing in
+ * for a call target that was never ingested.
+ */
+function isRawIdName(value: string): boolean {
+ return /^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(value) || /^[0-9a-f]{32,}$/i.test(value);
+}
+
+function edgeRowPriority(node: any): number {
+ const name = node.name || node.attrs?.name || "";
+ const resolved = !!name && !isRawIdName(name);
+ if (!resolved) return 2;
+ const path = node.provenance?.source_uri ?? node.provenance?.sourceUri ?? node.attrs?.path;
+ return path ? 0 : 1;
+}
+
+/**
+ * Cut an edge expansion to `--limit`, keeping the rows a caller can follow.
+ *
+ * A row whose name is a raw id is a dangling reference: `explain`, `read` and
+ * `callers` can all do nothing with it. A named row with no path costs the
+ * caller a `locate` before it can be read. Neither should displace a row that
+ * carries both.
+ */
+export function sliceEdgeResults(nodes: any[], limit: number): Slice<any> {
+ return sliceRanked(nodes, limit, edgeRowPriority);
+}
+
+/** What was left out, and the one flag that gets it. */
+export function truncationHint(slice: Slice<unknown>, relation: string): string {
+ return `${slice.total} ${relation}; showing ${slice.shown}. Raise --limit to see the rest.`;
+}
+
export function confidenceColor(score: number): (text: string) => string {
if (score >= 0.8) return chalk.green;
if (score >= 0.5) return chalk.yellow;
@@ -403,17 +471,32 @@ export interface TextResult {
}
/** Render lexical search hits as llm `match` records (one per line). */
-export function renderTextResultsLlm(results: TextResult[]): string[] {
- return results.map((r) => llmLine("match", [
- ["path", relativePath(r.path) ?? r.path],
- ["line", r.line_start],
- ["lang", r.language],
- ["symbol", r.symbol_hint],
- ["snippet", r.snippet.trim()],
- ]));
+export function renderTextResultsLlm(slice: Slice<TextResult>): string[] {
+ const lines = [llmLine("text", [
+ ["shown", slice.shown],
+ ["scanned", slice.total],
+ ["truncated", slice.truncated || undefined],
+ ])];
+ if (slice.truncated) {
+ lines.push(llmLine("diagnostic", [
+ ["code", "results_truncated"],
+ ["message", `${slice.total} matches scanned; showing the ${slice.shown} highest-ranked. Narrow with --path or --language, or raise --limit.`],
+ ]));
+ }
+ for (const r of slice.rows) {
+ lines.push(llmLine("match", [
+ ["path", relativePath(r.path) ?? r.path],
+ ["line", r.line_start],
+ ["lang", r.language],
+ ["symbol", r.symbol_hint],
+ ["snippet", r.snippet.trim()],
+ ]));
+ }
+ return lines;
}
-export function formatTextResults(results: TextResult[], format: string): void {
+export function formatTextResults(slice: Slice<TextResult>, format: string): void {
+ const results = slice.rows;
if (format === "json") {
const compact = results.map(r => ({
...r,
@@ -423,7 +506,7 @@ export function formatTextResults(results: TextResult[], format: string): void {
return;
}
if (format === "llm") {
- for (const line of renderTextResultsLlm(results)) console.log(line);
+ for (const line of renderTextResultsLlm(slice)) console.log(line);
return;
}
if (results.length === 0) {
@@ -473,15 +556,13 @@ export function formatLocateResults(results: LocateResult[], format: string): vo
* then one `ref` row per related entity. Unresolved targets carry resolved=false.
*/
export function renderEdgeResultsLlm(
- nodes: any[], relation: string, symbol: string,
+ slice: Slice<any>, relation: string, symbol: string,
source?: ResultSource, diagnostics?: Diagnostic[]
): string[] {
- const isRawId = (s: string) =>
- /^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(s) || /^[0-9a-f]{32,}$/i.test(s);
- const refs = nodes.map((n: any) => {
+ const refs = slice.rows.map((n: any) => {
const name = n.name || n.attrs?.name || "";
return {
- resolved: !!name && !isRawId(name),
+ resolved: !!name && !isRawIdName(name),
name,
kind: n.kind ?? undefined,
id: n.id ?? undefined,
@@ -491,11 +572,18 @@ export function renderEdgeResultsLlm(
const unresolved = refs.filter((r) => !r.resolved).length;
const lines = [llmLine(relation, [
["target", symbol],
- ["total", refs.length],
+ ["shown", slice.shown],
+ ["total", slice.total],
["resolved", refs.length - unresolved],
["unresolved", unresolved > 0 ? unresolved : undefined],
["source", source && source !== "graph" ? source : undefined],
])];
+ if (slice.truncated) {
+ lines.push(llmLine("diagnostic", [
+ ["code", "results_truncated"],
+ ["message", truncationHint(slice, relation)],
+ ]));
+ }
if (refs.length === 0 && (!diagnostics || diagnostics.length === 0)) {
lines.push(llmLine("diagnostic", [["code", "no_edges"], ["message", `No ${relation} edges found.`]]));
}
@@ -511,17 +599,15 @@ export function renderEdgeResultsLlm(
}
export function formatEdgeResults(
- nodes: any[], relation: string, symbol: string, format: string,
+ slice: Slice<any>, relation: string, symbol: string, format: string,
resolvedTarget?: { id: string; kind: string; name: string; resolutionMode?: string },
source?: ResultSource,
diagnostics?: Diagnostic[]
): void {
- // Check for UUID-like names that indicate unresolved references
- const isRawId = (s: string) =>
- /^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(s) || /^[0-9a-f]{32,}$/i.test(s);
+ const nodes = slice.rows;
if (format === "llm") {
- for (const line of renderEdgeResultsLlm(nodes, relation, symbol, source, diagnostics)) {
+ for (const line of renderEdgeResultsLlm(slice, relation, symbol, source, diagnostics)) {
console.log(line);
}
return;
@@ -530,7 +616,7 @@ export function formatEdgeResults(
if (format === "json") {
const results = nodes.map((n: any) => {
const name = n.name || n.attrs?.name || "";
- const resolved = !!name && !isRawId(name);
+ const resolved = !!name && !isRawIdName(name);
const ref: any = {
name: resolved ? name : undefined,
kind: n.kind ?? undefined,
@@ -565,6 +651,12 @@ export function formatEdgeResults(
} else if (diagnostics && diagnostics.length > 0) {
output.diagnostics = diagnostics;
}
+ if (slice.truncated) {
+ output.diagnostics = [
+ ...(output.diagnostics ?? []),
+ { code: "results_truncated", message: truncationHint(slice, relation) },
+ ];
+ }
const unresolvedCount = results.filter((r: any) => r.resolved === false).length;
if (unresolvedCount > 0) {
output.diagnostics = [
@@ -572,7 +664,13 @@ export function formatEdgeResults(
{ code: "dangling_reference_filtered", message: `${unresolvedCount} result(s) could not be resolved to named entities.` },
];
}
- output.summary = { total: results.length, resolved: results.length - unresolvedCount, unresolved: unresolvedCount };
+ output.summary = {
+ shown: slice.shown,
+ total: slice.total,
+ resolved: results.length - unresolvedCount,
+ unresolved: unresolvedCount,
+ truncated: slice.truncated,
+ };
console.log(JSON.stringify(output, null, 2));
return;
}
@@ -588,12 +686,13 @@ export function formatEdgeResults(
for (const n of nodes) {
const name = n.name || n.attrs?.name || "";
const shortId = n.id?.slice(0, 8) ?? "";
- if (!name || isRawId(name)) {
+ if (!name || isRawIdName(name)) {
console.log(` ${chalk.cyan((n.kind ?? "").padEnd(10))} ${chalk.dim(shortId)} ${chalk.dim("(unresolved)")}`);
} else {
console.log(` ${chalk.cyan((n.kind ?? "").padEnd(10))} ${chalk.dim(shortId)} ${chalk.bold(name)}`);
}
}
+ if (slice.truncated) console.log(chalk.dim(` ${truncationHint(slice, relation)}`));
}
/** Render detected conflicts as llm `conflict` records. */