Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
feat(cli): --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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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 = {}): McpServerreturn 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 } = {}): stringif (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.mdindex 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.mdindex 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 |