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): --offset paging for callers, callees, imports, imported-by and contains (HR-02A)

KageBinaryb6121b0d358e
diff --git a/ix-cli/src/cli/__tests__/honest-truncation.test.ts b/ix-cli/src/cli/__tests__/honest-truncation.test.ts
index e9d42670..fb84af0f 100644
--- a/ix-cli/src/cli/__tests__/honest-truncation.test.ts
+++ b/ix-cli/src/cli/__tests__/honest-truncation.test.ts
@@ -1,8 +1,10 @@
// Copyright 2026 Ix Infrastructure Inc.
+import { Command } from "commander";
import { describe, expect, it } from "vitest";
import { renderEdgeResultsLlm, sliceEdgeResults, sliceRanked } from "../format.js";
+import { nextPageCommand } from "../paging.js";
import { renderInventoryLlm } from "../commands/inventory.js";
import { scanWindow, textResultPriority } from "../commands/text.js";
@@ -61,11 +63,110 @@ describe("sliceEdgeResults", () => {
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."',
+ 'diagnostic code=results_truncated next_offset=50 message="212 callers; showing 50. next: --offset 50"',
);
});
});
+describe("paging with --offset", () => {
+ const mixed = () => [
+ ...Array.from({ length: 70 }, (_, i) => node(`p${i}`, "src/a.ts")),
+ ...Array.from({ length: 70 }, (_, i) => node(`n${i}`)),
+ ...Array.from({ length: 72 }, (_, i) => ({ id: `${i.toString(16).padStart(8, "0")}-1111-0000-0000-000000000000`, name: "d41d8cd98f00b204e9800998ecf8427e", kind: "method" })),
+ ];
+
+ it("pages concatenate to the full ranked list with no overlap or gap", () => {
+ const all = mixed();
+ const full = sliceEdgeResults(all, Infinity).rows;
+ const got: any[] = [];
+ let offset = 0;
+ for (;;) {
+ const s = sliceEdgeResults(all, 50, offset);
+ got.push(...s.rows);
+ if (s.nextOffset === undefined) break;
+ offset = s.nextOffset;
+ }
+ expect(got).toEqual(full);
+ expect(new Set(got.map((n) => n.id)).size).toBe(212);
+ });
+
+ it("a middle page names the next offset", () => {
+ const s = sliceEdgeResults(mixed(), 50, 50);
+ expect(s).toMatchObject({ offset: 50, shown: 50, total: 212, truncated: true, nextOffset: 100 });
+ const lines = renderEdgeResultsLlm(s, "callers", "t", "graph");
+ expect(lines[0]).toBe("callers target=t offset=50 shown=50 total=212 resolved=50");
+ expect(lines[1]).toContain("next_offset=100");
+ expect(lines[1]).toContain("showing 51-100. next: --offset 100");
+ });
+
+ it("uses the caller's next command when given", () => {
+ const s = { ...sliceEdgeResults(mixed(), 50), next: "ix callers t --offset 50" };
+ expect(renderEdgeResultsLlm(s, "callers", "t", "graph")[1]).toContain("next: ix callers t --offset 50");
+ });
+
+ it("the last page has no hint", () => {
+ const s = sliceEdgeResults(mixed(), 50, 200);
+ expect(s).toMatchObject({ shown: 12, truncated: false });
+ expect(s.nextOffset).toBeUndefined();
+ const lines = renderEdgeResultsLlm(s, "callers", "t", "graph");
+ expect(lines.some((l) => l.includes("results_truncated"))).toBe(false);
+ });
+
+ it("past the end says so instead of no_edges", () => {
+ const s = sliceEdgeResults(mixed(), 50, 300);
+ expect(s).toMatchObject({ rows: [], total: 212, truncated: false });
+ const lines = renderEdgeResultsLlm(s, "callers", "t", "graph");
+ expect(lines.some((l) => l.startsWith("diagnostic code=offset_past_end"))).toBe(true);
+ expect(lines.some((l) => l.includes("no_edges"))).toBe(false);
+ });
+
+ it("--limit 0 gives no next offset and does not claim past-the-end", () => {
+ const s = sliceEdgeResults(mixed().slice(0, 5), 0);
+ expect(s).toMatchObject({ rows: [], shown: 0, total: 5, truncated: true });
+ expect(s.nextOffset).toBeUndefined();
+ const lines = renderEdgeResultsLlm(s, "callers", "t", "graph");
+ expect(lines[1]).toBe('diagnostic code=results_truncated message="5 callers; showing 0. Raise --limit to see them."');
+ expect(lines.some((l) => l.includes("offset_past_end") || l.includes("no_edges"))).toBe(false);
+ });
+
+ it("an offset with --limit 0 is not past the end while rows remain", () => {
+ const s = sliceEdgeResults(mixed(), 0, 50);
+ expect(s.nextOffset).toBeUndefined();
+ const lines = renderEdgeResultsLlm(s, "callers", "t", "graph");
+ expect(lines.some((l) => l.includes("offset_past_end"))).toBe(false);
+ });
+
+ it("leaves the header and rows alone without an offset", () => {
+ const lines = renderEdgeResultsLlm(sliceEdgeResults([node("a", "src/a.ts")], 50), "callers", "t", "graph");
+ expect(lines[0]).toBe("callers target=t shown=1 total=1 resolved=1");
+ expect(lines).toHaveLength(2);
+ });
+});
+
+describe("nextPageCommand", () => {
+ function parsed(argv: string[]): Command {
+ const cmd = new Command("callers")
+ .argument("<symbol>")
+ .option("--limit <n>", "", "50")
+ .option("--kind <kind>")
+ .option("--offset <n>", "", "0")
+ .exitOverride();
+ cmd.parse(argv, { from: "user" });
+ return cmd;
+ }
+
+ it("keeps only typed options and drops --offset", () => {
+ const cmd = parsed(["--kind", "method", "--offset", "50", "x"]);
+ expect(nextPageCommand(cmd, ["x"], 100)).toBe("ix callers --kind method --offset 100 x");
+ });
+
+ it("quotes a symbol with a space and guards a leading dash", () => {
+ const cmd = parsed(["a b"]);
+ expect(nextPageCommand(cmd, ["a b"], 50)).toBe("ix callers --offset 50 'a b'");
+ expect(nextPageCommand(cmd, ["-x"], 50)).toBe("ix callers --offset 50 -- -x");
+ });
+});
+
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" } }];
diff --git a/ix-cli/src/cli/__tests__/mcp-tool-params.test.ts b/ix-cli/src/cli/__tests__/mcp-tool-params.test.ts
index db5ca174..f442413c 100644
--- a/ix-cli/src/cli/__tests__/mcp-tool-params.test.ts
+++ b/ix-cli/src/cli/__tests__/mcp-tool-params.test.ts
@@ -51,6 +51,39 @@ describe("resolving an ambiguous symbol over MCP", () => {
]);
});
+ it("forwards --offset on ix_neighbors", async () => {
+ const { calls, runIx } = recorder();
+ const client = await connect(runIx);
+ await client.callTool({ name: "ix_neighbors", arguments: { symbol: "config", relation: "imported_by", limit: 20, offset: 50 } });
+ expect(calls).toEqual([
+ ["imported-by", "--limit=20", "--offset=50", "--format=llm", "--", "config"],
+ ]);
+ });
+
+ it("forwards --offset on the single-relation tools too", async () => {
+ // Their truncation diagnostic carries next_offset=, so each one has to be
+ // able to take it back; a hint the tool cannot act on is no hint.
+ const { calls, runIx } = recorder();
+ const client = await connect(runIx);
+ await client.callTool({ name: "ix_callers", arguments: { symbol: "config", limit: 20, offset: 50 } });
+ expect(calls).toEqual([
+ ["callers", "--limit=20", "--offset=50", "--format=llm", "--", "config"],
+ ]);
+ });
+
+ it("offers offset only on the edge tools", async () => {
+ const client = await connect(async () => ({ ok: true, stdout: "ok", stderr: "" }));
+ const tools = (await client.listTools()).tools;
+ const has = (name: string) =>
+ "offset" in (((tools.find((t) => t.name === name)!.inputSchema) as { properties?: Record<string, unknown> }).properties ?? {});
+ for (const name of ["ix_neighbors", "ix_callers", "ix_callees", "ix_imports", "ix_imported_by"]) {
+ expect(has(name), name).toBe(true);
+ }
+ for (const name of ["ix_impact", "ix_read", "ix_explain"]) {
+ expect(has(name), name).toBe(false);
+ }
+ });
+
it("sends nothing for the flags the caller left out", async () => {
const { calls, runIx } = recorder();
const client = await connect(runIx);
diff --git a/ix-cli/src/cli/commands/callers.ts b/ix-cli/src/cli/commands/callers.ts
index 1c24f9d8..034384c0 100644
--- a/ix-cli/src/cli/commands/callers.ts
+++ b/ix-cli/src/cli/commands/callers.ts
@@ -9,6 +9,7 @@ import { resolveWorkspaceRoot } from "../config.js";
import { formatEdgeResults, printJson, relativePath, sliceEdgeResults, type Diagnostic } from "../format.js";
import { checkGraphHealth, graphHealthProse, isUnhealthy, type GraphHealth } from "../graph-health.js";
import { parsePickOption } from "../options.js";
+import { nextPageCommand, OFFSET_FLAG, parseOffset } from "../paging.js";
import { activeReadScope, resolveFileOrReport, printResolved } from "../resolve.js";
import { stderr } from "../stderr.js";
import { llmLine } from "../llm.js";
@@ -51,11 +52,13 @@ export function registerCallersCommand(program: Command): void {
.option("--path <path>", "Restrict to symbols from files matching this path substring")
.option("--pick <n>", "Pick Nth candidate from ambiguous results (1-based)", parsePickOption)
.option("--limit <n>", "Max results to show", "50")
+ .option("--offset <n>", OFFSET_FLAG, "0")
.option("--format <fmt>", "Output format (text|json|llm)", "text")
- .addHelpText("after", "\nExamples:\n ix callers verify_token\n ix callers processPayment --format json\n ix callers parse --kind method --limit 20")
- .action(async (symbol: string, opts: { kind?: string; path?: string; pick?: number; limit: string; format: string }) => {
+ .addHelpText("after", "\nExamples:\n ix callers verify_token\n ix callers processPayment --format json\n ix callers parse --kind method --limit 20\n ix callers verify_token --offset 50")
+ .action(async (symbol: string, opts: { kind?: string; path?: string; pick?: number; limit: string; offset: string; format: string }, cmd: Command) => {
const client = createClient();
const limit = parseInt(opts.limit, 10);
+ const offset = parseOffset(opts.offset);
const resolveOpts = { kind: opts.kind, path: opts.path, pick: opts.pick };
const target = await resolveFileOrReport(client, symbol, resolveOpts, opts.format);
if (!target) return;
@@ -73,7 +76,7 @@ export function registerCallersCommand(program: Command): void {
const remedy = health.fix ?? "ix ingest --force --recursive .";
if (result.nodes.length === 0) {
- // Fallback to text search
+ // Fallback to text search. It shows a fixed 10 rows and ignores --offset.
try {
const root = resolveWorkspaceRoot();
// The timeout bounds a search that rg could otherwise run for ever.
@@ -161,10 +164,11 @@ export function registerCallersCommand(program: Command): void {
}
} catch { /* ripgrep not available or no matches */ }
- // Both graph and text empty
+ // Both graph and text empty (also the health-gated path: --offset does not apply).
formatEdgeResults(sliceEdgeResults([], limit), "callers", target.name, opts.format, target, "graph", health.diagnostics);
} else {
- const slice = sliceEdgeResults(result.nodes, limit);
+ const slice = sliceEdgeResults(result.nodes, limit, offset);
+ if (slice.nextOffset !== undefined) slice.next = nextPageCommand(cmd, [symbol], slice.nextOffset);
const site = await edgeTargetFor(client, target, "callers");
formatEdgeResults({ ...slice, rows: withEdgeSites(slice.rows, "callers", site) }, "callers", target.name, opts.format, target, "graph", health.diagnostics);
}
@@ -177,11 +181,13 @@ export function registerCallersCommand(program: Command): void {
.option("--path <path>", "Restrict to symbols from files matching this path substring")
.option("--pick <n>", "Pick Nth candidate from ambiguous results (1-based)", parsePickOption)
.option("--limit <n>", "Max results to show", "50")
+ .option("--offset <n>", OFFSET_FLAG, "0")
.option("--format <fmt>", "Output format (text|json|llm)", "text")
.addHelpText("after", "\nExamples:\n ix callees processPayment\n ix callees parse --format json")
- .action(async (symbol: string, opts: { kind?: string; path?: string; pick?: number; limit: string; format: string }) => {
+ .action(async (symbol: string, opts: { kind?: string; path?: string; pick?: number; limit: string; offset: string; format: string }, cmd: Command) => {
const client = createClient();
const calleeLimit = parseInt(opts.limit, 10);
+ const calleeOffset = parseOffset(opts.offset);
const resolveOpts = { kind: opts.kind, path: opts.path, pick: opts.pick };
const target = await resolveFileOrReport(client, symbol, resolveOpts, opts.format);
if (!target) return;
@@ -194,7 +200,8 @@ export function registerCallersCommand(program: Command): void {
});
const health = await healthDiagnostics(healthCheck);
bannerOverRows(health, opts.format, result.nodes.length);
- const slice = sliceEdgeResults(result.nodes, calleeLimit);
+ const slice = sliceEdgeResults(result.nodes, calleeLimit, calleeOffset);
+ if (slice.nextOffset !== undefined) slice.next = nextPageCommand(cmd, [symbol], slice.nextOffset);
const site = await edgeTargetFor(client, target, "callees");
formatEdgeResults({ ...slice, rows: withEdgeSites(slice.rows, "callees", site) }, "callees", target.name, opts.format, target, "graph", health.diagnostics);
});
diff --git a/ix-cli/src/cli/commands/contains.ts b/ix-cli/src/cli/commands/contains.ts
index 676b43df..f41a7b7c 100644
--- a/ix-cli/src/cli/commands/contains.ts
+++ b/ix-cli/src/cli/commands/contains.ts
@@ -4,6 +4,7 @@ import type { Command } from "commander";
import { createClient } from "../../client/factory.js";
import { formatEdgeResults, sliceEdgeResults } from "../format.js";
import { parsePickOption } from "../options.js";
+import { nextPageCommand, OFFSET_FLAG, parseOffset } from "../paging.js";
import { resolveFileOrReport, printResolved } from "../resolve.js";
export function registerContainsCommand(program: Command): void {
@@ -14,16 +15,20 @@ export function registerContainsCommand(program: Command): void {
.option("--path <path>", "Restrict to symbols from files matching this path substring")
.option("--pick <n>", "Pick Nth candidate from ambiguous results (1-based)", parsePickOption)
.option("--limit <n>", "Max results to show", "50")
+ .option("--offset <n>", OFFSET_FLAG, "0")
.option("--format <fmt>", "Output format (text|json|llm)", "text")
.addHelpText("after", "\nExamples:\n ix contains IngestionService\n ix contains auth.py --kind file --format json\n ix contains MyClass --limit 20\n ix contains package --path crates/regex/Cargo.toml")
- .action(async (symbol: string, opts: { kind?: string; path?: string; pick?: number; limit: string; format: string }) => {
+ .action(async (symbol: string, opts: { kind?: string; path?: string; pick?: number; limit: string; offset: string; format: string }, cmd: Command) => {
const client = createClient();
const limit = parseInt(opts.limit, 10);
+ const offset = parseOffset(opts.offset);
const resolveOpts = { kind: opts.kind, path: opts.path, pick: opts.pick };
const target = await resolveFileOrReport(client, symbol, resolveOpts, opts.format);
if (!target) return;
if (opts.format === "text") printResolved(target);
const result = await client.expand(target.id, { direction: "out", predicates: ["CONTAINS"] });
- formatEdgeResults(sliceEdgeResults(result.nodes, limit), "contains", target.name, opts.format, target, "graph");
+ const slice = sliceEdgeResults(result.nodes, limit, offset);
+ if (slice.nextOffset !== undefined) slice.next = nextPageCommand(cmd, [symbol], slice.nextOffset);
+ formatEdgeResults(slice, "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 b4105c4f..d44fd8e7 100644
--- a/ix-cli/src/cli/commands/imports.ts
+++ b/ix-cli/src/cli/commands/imports.ts
@@ -5,6 +5,7 @@ import { createClient } from "../../client/factory.js";
import { formatEdgeResults, sliceEdgeResults } from "../format.js";
import { resolveFileOrReport, printResolved } from "../resolve.js";
import { parsePickOption } from "../options.js";
+import { nextPageCommand, OFFSET_FLAG, parseOffset } from "../paging.js";
import { edgeTargetFor, withEdgeSites } from "../edge-sites.js";
export function registerImportsCommand(program: Command): void {
@@ -15,17 +16,20 @@ export function registerImportsCommand(program: Command): void {
.option("--path <path>", "Restrict to symbols from files matching this path substring")
.option("--pick <n>", "Pick Nth candidate from ambiguous results (1-based)", parsePickOption)
.option("--limit <n>", "Max results to show", "50")
+ .option("--offset <n>", OFFSET_FLAG, "0")
.option("--format <fmt>", "Output format (text|json|llm)", "text")
.addHelpText("after", "\nExamples:\n ix imports auth.py\n ix imports IngestionService --format json")
- .action(async (symbol: string, opts: { kind?: string; path?: string; pick?: number; limit: string; format: string }) => {
+ .action(async (symbol: string, opts: { kind?: string; path?: string; pick?: number; limit: string; offset: string; format: string }, cmd: Command) => {
const client = createClient();
const limit = parseInt(opts.limit, 10);
+ const offset = parseOffset(opts.offset);
const resolveOpts = { kind: opts.kind, path: opts.path, pick: opts.pick };
const target = await resolveFileOrReport(client, symbol, resolveOpts, opts.format);
if (!target) return;
if (opts.format === "text") printResolved(target);
const result = await client.expand(target.id, { direction: "out", predicates: ["IMPORTS"] });
- const slice = sliceEdgeResults(result.nodes, limit);
+ const slice = sliceEdgeResults(result.nodes, limit, offset);
+ if (slice.nextOffset !== undefined) slice.next = nextPageCommand(cmd, [symbol], slice.nextOffset);
const site = await edgeTargetFor(client, target, "imports");
formatEdgeResults({ ...slice, rows: withEdgeSites(slice.rows, "imports", site) }, "imports", target.name, opts.format, target, "graph");
});
@@ -37,17 +41,20 @@ export function registerImportsCommand(program: Command): void {
.option("--path <path>", "Restrict to symbols from files matching this path substring")
.option("--pick <n>", "Pick Nth candidate from ambiguous results (1-based)", parsePickOption)
.option("--limit <n>", "Max results to show", "50")
+ .option("--offset <n>", OFFSET_FLAG, "0")
.option("--format <fmt>", "Output format (text|json|llm)", "text")
.addHelpText("after", "\nExamples:\n ix imported-by AuthProvider\n ix imported-by io.circe.Json --format json")
- .action(async (symbol: string, opts: { kind?: string; path?: string; pick?: number; limit: string; format: string }) => {
+ .action(async (symbol: string, opts: { kind?: string; path?: string; pick?: number; limit: string; offset: string; format: string }, cmd: Command) => {
const client = createClient();
const limit = parseInt(opts.limit, 10);
+ const offset = parseOffset(opts.offset);
const resolveOpts = { kind: opts.kind, path: opts.path, pick: opts.pick };
const target = await resolveFileOrReport(client, symbol, resolveOpts, opts.format);
if (!target) return;
if (opts.format === "text") printResolved(target);
const result = await client.expand(target.id, { direction: "in", predicates: ["IMPORTS"] });
- const slice = sliceEdgeResults(result.nodes, limit);
+ const slice = sliceEdgeResults(result.nodes, limit, offset);
+ if (slice.nextOffset !== undefined) slice.next = nextPageCommand(cmd, [symbol], slice.nextOffset);
const site = await edgeTargetFor(client, target, "imported-by");
formatEdgeResults({ ...slice, rows: withEdgeSites(slice.rows, "imported-by", site) }, "imported-by", target.name, opts.format, target, "graph");
});
diff --git a/ix-cli/src/cli/format.ts b/ix-cli/src/cli/format.ts
index 8c6d7b7a..803af16d 100644
--- a/ix-cli/src/cli/format.ts
+++ b/ix-cli/src/cli/format.ts
@@ -105,6 +105,12 @@ export interface Slice<T> {
/** How many there were before the cut. */
total: number;
truncated: boolean;
+ /** How many ranked rows were skipped before `rows` (paging); absent means 0. */
+ offset?: number;
+ /** The `--offset` of the next page; set only when rows remain. */
+ nextOffset?: number;
+ /** The command that prints the next page, when the caller can build one. */
+ next?: string;
}
/**
@@ -123,10 +129,16 @@ export interface Slice<T> {
* 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> {
+export function sliceRanked<T>(all: T[], limit: number, priority?: (item: T) => number, offset = 0): 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 };
+ const rows = Number.isFinite(limit) ? ranked.slice(offset, offset + limit) : ranked.slice(offset);
+ const truncated = offset + rows.length < all.length;
+ const slice: Slice<T> = { rows, shown: rows.length, total: all.length, truncated };
+ if (offset > 0) slice.offset = offset;
+ // A page that printed nothing (`--limit 0`) has no next page to point at:
+ // `next_offset` would equal this offset and a caller following it would loop.
+ if (truncated && rows.length > 0) slice.nextOffset = offset + rows.length;
+ return slice;
}
/**
@@ -153,13 +165,26 @@ function edgeRowPriority(node: any): number {
* 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);
+export function sliceEdgeResults(nodes: any[], limit: number, offset = 0): Slice<any> {
+ return sliceRanked(nodes, limit, edgeRowPriority, offset);
}
/** 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.`;
+ const offset = slice.offset ?? 0;
+ const range = offset > 0 ? `${offset + 1}-${offset + slice.shown}` : `${slice.shown}`;
+ if (slice.nextOffset === undefined) return `${slice.total} ${relation}; showing ${range}. Raise --limit to see them.`;
+ const next = slice.next ?? `--offset ${slice.nextOffset}`;
+ return `${slice.total} ${relation}; showing ${range}. next: ${next}`;
+}
+
+/** The message for a page that starts at or past the end of the list. */
+function pastEndMessage(slice: Slice<unknown>, relation: string): string {
+ return `${slice.total} ${relation}; --offset ${slice.offset ?? 0} is past the end.`;
+}
+
+function isPastEnd(slice: Slice<unknown>): boolean {
+ return slice.total > 0 && (slice.offset ?? 0) >= slice.total;
}
// ── Row locations ──────────────────────────────────────────────────────────
@@ -700,6 +725,7 @@ export function renderEdgeResultsLlm(
const unresolved = refs.filter((r) => !r.resolved).length;
const lines = [llmLine(relation, [
["target", symbol],
+ ["offset", slice.offset ? slice.offset : undefined],
["shown", slice.shown],
["total", slice.total],
["resolved", refs.length - unresolved],
@@ -709,10 +735,13 @@ export function renderEdgeResultsLlm(
if (slice.truncated) {
lines.push(llmLine("diagnostic", [
["code", "results_truncated"],
+ ["next_offset", slice.nextOffset],
["message", truncationHint(slice, relation)],
]));
}
- if (refs.length === 0 && (!diagnostics || diagnostics.length === 0)) {
+ if (refs.length === 0 && isPastEnd(slice)) {
+ lines.push(llmLine("diagnostic", [["code", "offset_past_end"], ["message", pastEndMessage(slice, relation)]]));
+ } else if (refs.length === 0 && !slice.truncated && (!diagnostics || diagnostics.length === 0)) {
lines.push(llmLine("diagnostic", [["code", "no_edges"], ["message", `No ${relation} edges found.`]]));
}
for (const d of diagnostics ?? []) {
@@ -783,7 +812,9 @@ export function formatEdgeResults(
}
}
if (nodes.length === 0) {
- output.diagnostics = diagnostics ?? [{ code: "no_edges", message: `No ${relation} edges found for resolved entity.` }];
+ output.diagnostics = isPastEnd(slice)
+ ? [{ code: "offset_past_end", message: pastEndMessage(slice, relation) }]
+ : diagnostics ?? (slice.truncated ? undefined : [{ code: "no_edges", message: `No ${relation} edges found for resolved entity.` }]);
} else if (diagnostics && diagnostics.length > 0) {
output.diagnostics = diagnostics;
}
@@ -806,12 +837,18 @@ export function formatEdgeResults(
resolved: results.length - unresolvedCount,
unresolved: unresolvedCount,
truncated: slice.truncated,
+ offset: slice.offset ?? 0,
+ ...(slice.nextOffset !== undefined ? { nextOffset: slice.nextOffset } : {}),
};
printJson(output);
return;
}
if (nodes.length === 0) {
- const reason = diagnostics?.[0]?.message ?? `No ${relation} found for "${symbol}".`;
+ const reason = isPastEnd(slice)
+ ? pastEndMessage(slice, relation)
+ : slice.truncated
+ ? truncationHint(slice, relation)
+ : diagnostics?.[0]?.message ?? `No ${relation} found for "${symbol}".`;
console.log(reason);
return;
}
diff --git a/ix-cli/src/cli/paging.ts b/ix-cli/src/cli/paging.ts
new file mode 100644
index 00000000..2785aa1b
--- /dev/null
+++ b/ix-cli/src/cli/paging.ts
@@ -0,0 +1,46 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+import type { Command } from "commander";
+
+/** Help text for `--offset`, shared so the flag reads the same on every command. */
+export const OFFSET_FLAG = "Skip the first N results (use the next: hint to page)";
+
+/**
+ * `--offset` as a number. The root option validator already rejects a typed
+ * value that is not a non-negative integer, so this only supplies the default.
+ */
+export function parseOffset(raw?: string): number {
+ const n = parseInt(raw ?? "0", 10);
+ return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+const SAFE_WORD = /^[A-Za-z0-9_./:@%+=,-]+$/;
+
+function shellQuote(word: string): string {
+ if (SAFE_WORD.test(word)) return word;
+ return `'${word.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * The command line that prints the next page: the same command, the same
+ * positionals, the options the caller typed, and `--offset nextOffset`.
+ */
+export function nextPageCommand(cmd: Command, positionals: string[], nextOffset: number): string {
+ const parts = ["ix", cmd.name()];
+ for (const option of cmd.options) {
+ const name = option.attributeName();
+ if (option.long === "--offset") continue;
+ if (cmd.getOptionValueSource(name) !== "cli") continue;
+ const value = cmd.opts()[name];
+ if (value === undefined || value === null || value === false) continue;
+ if (value === true || !option.long) {
+ if (option.long) parts.push(option.long);
+ continue;
+ }
+ parts.push(option.long, shellQuote(String(value)));
+ }
+ parts.push("--offset", String(nextOffset));
+ if (positionals.some((p) => p.startsWith("-"))) parts.push("--");
+ for (const p of positionals) parts.push(shellQuote(p));
+ return parts.join(" ");
+}
diff --git a/ix-cli/src/mcp/server.ts b/ix-cli/src/mcp/server.ts
index 9af0b8e7..5732d695 100644
--- a/ix-cli/src/mcp/server.ts
+++ b/ix-cli/src/mcp/server.ts
@@ -516,7 +516,7 @@ export function createIxMcpServer(options: CreateServerOptions = {}): McpServer
"ix_neighbors",
"Use when you need who calls X, what X calls, what X imports, or which files import X, across the repo. Returns one row per resolved edge with path:lines, where grep finds every same-named symbol too. For transitive reach use ix_impact.",
{
- ...SYMBOL_TOOL_INPUT,
+ ...EDGE_TOOL_INPUT,
relation: z
.enum(["callers", "callees", "imports", "imported_by"])
.describe("callers = who calls it; callees = what it calls"),
@@ -528,14 +528,14 @@ export function createIxMcpServer(options: CreateServerOptions = {}): McpServer
return runFormatted(
runIx,
"ix_neighbors",
- ix(command, [stringArg(input, "symbol")], symbolOptions(input)),
+ ix(command, [stringArg(input, "symbol")], symbolOptions(input, { offset: true })),
);
},
);
- registerSymbolTool(ctx, runIx, "ix_callers", "Who calls this. Rows carry path:lines. Prefer ix_neighbors relation=callers.", "callers");
- registerSymbolTool(ctx, runIx, "ix_callees", "What this calls. Rows carry path:lines. Prefer ix_neighbors relation=callees.", "callees");
- registerSymbolTool(ctx, runIx, "ix_imported_by", "What imports this. Rows carry path:lines. Prefer ix_neighbors relation=imported_by.", "imported-by");
- registerSymbolTool(ctx, runIx, "ix_imports", "What this imports. Rows carry path:lines. Prefer ix_neighbors relation=imports.", "imports");
+ registerSymbolTool(ctx, runIx, "ix_callers", "Who calls this, with path:lines. Prefer ix_neighbors.", "callers", EDGE_TOOL_INPUT);
+ registerSymbolTool(ctx, runIx, "ix_callees", "What this calls, with path:lines. Prefer ix_neighbors.", "callees", EDGE_TOOL_INPUT);
+ registerSymbolTool(ctx, runIx, "ix_imported_by", "What imports this, with path:lines. Prefer ix_neighbors.", "imported-by", EDGE_TOOL_INPUT);
+ registerSymbolTool(ctx, runIx, "ix_imports", "What this imports, with path:lines. Prefer ix_neighbors.", "imports", EDGE_TOOL_INPUT);
registerTool(
ctx,
"ix_depends",
@@ -747,8 +747,24 @@ const SYMBOL_TOOL_INPUT = {
limit: z.number().int().min(1).max(500).optional(),
} as const;
+/**
+ * The edge tools (ix_neighbors and the four single-relation tools) page with
+ * `offset`, following `next_offset=` on a results_truncated diagnostic: every
+ * tool that can print that diagnostic has to be able to take the offset back.
+ * Kept out of SYMBOL_TOOL_INPUT so ix_impact, ix_read and ix_explain do not
+ * grow a flag their commands lack. No description: five copies would push the
+ * full catalog past its tools/list budget (mcp-structured-output.test.ts), and
+ * for the same reason the four single-relation descriptions no longer spell
+ * out the ix_neighbors relation their own name already gives. An offset past
+ * the end is answered with an offset_past_end diagnostic, not an error.
+ */
+const EDGE_TOOL_INPUT = {
+ ...SYMBOL_TOOL_INPUT,
+ offset: z.number().int().min(0).max(100000).optional(),
+} as const;
+
/** Turn the shared disambiguation input into CLI flags. */
-function symbolOptions(input: ToolInput, opts: { limit?: boolean } = {}): string[] {
+function symbolOptions(input: ToolInput, opts: { limit?: boolean; offset?: boolean } = {}): string[] {
const options: string[] = [];
pushOption(options, "--kind", input.kind);
pushOption(options, "--path", input.path);
@@ -756,6 +772,9 @@ function symbolOptions(input: ToolInput, opts: { limit?: boolean } = {}): string
if (opts.limit !== false && typeof input.limit === "number") {
options.push(`--limit=${numberArg(input, "limit")}`);
}
+ if (opts.offset === true && typeof input.offset === "number") {
+ options.push(`--offset=${numberArg(input, "offset")}`);
+ }
return options;
}
@@ -767,8 +786,9 @@ function registerSymbolTool(
command: string,
input: z.ZodRawShape = SYMBOL_TOOL_INPUT,
): void {
+ const offset = "offset" in input;
registerTool(ctx, name, description, input, async (args) =>
- runFormatted(runIx, name, ix(command, [stringArg(args, "symbol")], symbolOptions(args))),
+ runFormatted(runIx, name, ix(command, [stringArg(args, "symbol")], symbolOptions(args, { offset }))),
);
}
diff --git a/skills/ix/references/commands.md b/skills/ix/references/commands.md
index e6895f50..33bd131c 100644
--- a/skills/ix/references/commands.md
+++ b/skills/ix/references/commands.md
@@ -189,6 +189,8 @@ ix inventory --kind function --path auth.py
- Always use `--limit` to cap result sets. Not on `ix diff --summary` or
`ix diff --full`, though: each already fixes the volume, so `--limit`
alongside either is refused rather than silently ignored.
+- Page `callers`, `callees`, `imports`, `imported-by` and `contains` with
+ `--offset`, following the `next:` hint (or `next_offset=` in llm output).
- Use `--path` or `--language` to restrict text searches.
- Reuse exact entity IDs from previous JSON results when chaining commands.
- Decompose large questions into multiple targeted calls.
diff --git a/skills/ix/references/flags.md b/skills/ix/references/flags.md
index e2f27d31..fef27c00 100644
--- a/skills/ix/references/flags.md
+++ b/skills/ix/references/flags.md
@@ -149,6 +149,7 @@ Show methods/functions called by the given symbol (cross-file).
| `--path` | `<path>` | — | Restrict to symbols from files matching this path substring |
| `--pick` | `<n>` | — | Pick Nth candidate from ambiguous results (1-based) |
| `--limit` | `<n>` | `50` | Max results to show |
+| `--offset` | `<n>` | `0` | Skip the first N results (use the next: hint to page) |
| `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) |
| `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |
| `--quiet` | — | off | Drop headers, section titles and advisory hints |
@@ -164,6 +165,7 @@ Show methods/functions that call the given symbol (cross-file).
| `--path` | `<path>` | — | Restrict to symbols from files matching this path substring |
| `--pick` | `<n>` | — | Pick Nth candidate from ambiguous results (1-based) |
| `--limit` | `<n>` | `50` | Max results to show |
+| `--offset` | `<n>` | `0` | Skip the first N results (use the next: hint to page) |
| `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) |
| `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |
| `--quiet` | — | off | Drop headers, section titles and advisory hints |
@@ -224,6 +226,7 @@ Show members contained by the given entity (class, module, file).
| `--path` | `<path>` | — | Restrict to symbols from files matching this path substring |
| `--pick` | `<n>` | — | Pick Nth candidate from ambiguous results (1-based) |
| `--limit` | `<n>` | `50` | Max results to show |
+| `--offset` | `<n>` | `0` | Skip the first N results (use the next: hint to page) |
| `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) |
| `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |
| `--quiet` | — | off | Drop headers, section titles and advisory hints |
@@ -448,6 +451,7 @@ Show what imports the given entity.
| `--path` | `<path>` | — | Restrict to symbols from files matching this path substring |
| `--pick` | `<n>` | — | Pick Nth candidate from ambiguous results (1-based) |
| `--limit` | `<n>` | `50` | Max results to show |
+| `--offset` | `<n>` | `0` | Skip the first N results (use the next: hint to page) |
| `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) |
| `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |
| `--quiet` | — | off | Drop headers, section titles and advisory hints |
@@ -463,6 +467,7 @@ Show what the given entity imports.
| `--path` | `<path>` | — | Restrict to symbols from files matching this path substring |
| `--pick` | `<n>` | — | Pick Nth candidate from ambiguous results (1-based) |
| `--limit` | `<n>` | `50` | Max results to show |
+| `--offset` | `<n>` | `0` | Skip the first N results (use the next: hint to page) |
| `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) |
| `--pretty` | — | off | Indent JSON output; the default only when stdout is a terminal |
| `--quiet` | — | off | Drop headers, section titles and advisory hints |