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(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.mdindex 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=rootregion 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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: anungrouped.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.tsindex 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): stringreturn 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: RunRipgrepreturn;}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 setif (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.tsindex 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. */