Skip to content

armgit / Ix

Public Imported from GitHub
0

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

feat(read): cap symbol reads at READ_LINE_CAP with a next= cursor (CL-20B) (#826)

Ian Hock1c63d1f25fc1
diff --git a/docs-site/src/content/docs/concepts/how-it-works.md b/docs-site/src/content/docs/concepts/how-it-works.md
index adc5b680..8ad17900 100644
--- a/docs-site/src/content/docs/concepts/how-it-works.md
+++ b/docs-site/src/content/docs/concepts/how-it-works.md
@@ -54,7 +54,7 @@ they cut:
- `ix depends` and `ix trace` stop at depth 3 and 100 nodes. `truncated=true` means the node cap dropped nodes, and
`depth_limited=true` means the walk stopped descending.
-- `ix read <file>` stops at 400 lines and tells you the range of the next page.
+- `ix read` stops at 400 lines, for a file or a symbol, and gives the next page as a `next=` target to read.
- `ix context` budgets its evidence in tokens (3,000 by default).
Every limit can be raised with a flag. See the [flag reference](/reference/flags/).
diff --git a/docs-site/src/content/docs/guides/everyday-workflows.md b/docs-site/src/content/docs/guides/everyday-workflows.md
index b5f24acb..0d49c1e9 100644
--- a/docs-site/src/content/docs/guides/everyday-workflows.md
+++ b/docs-site/src/content/docs/guides/everyday-workflows.md
@@ -37,7 +37,7 @@ Pass `--kind` to `ix search`, which keeps results focused. A module-level consta
## "Show me the code"
```bash
-ix read verify_token # a symbol's own span
+ix read verify_token # a symbol's own span (paged at 400 lines)
ix read src/auth.py:10-50 # a line range
ix read src/auth.py --all # a whole file (otherwise paged at 400 lines)
```
diff --git a/docs/llm-format.md b/docs/llm-format.md
index 7a18b191..12af8225 100644
--- a/docs/llm-format.md
+++ b/docs/llm-format.md
@@ -218,6 +218,28 @@ Two commands cannot know a true total and say so rather than inventing one:
`offset_past_end`: more matches exist). `--format json` stays a bare array of matches with no
paging fields; the next offset is the offset plus its length.
+`ix read` caps a read at 400 lines and marks the `file` record with
+`truncated=true total_lines=<n> next=<target>`. `total_lines` is always a
+count, never a line number:
+
+- `target=file`: the lines in the file, and `next=<path>:<from>-<to>`.
+- `target=symbol`: the lines in the symbol's whole span, not the file. The
+ record also carries `span_end=<n>`, the symbol's last line, and
+ `next=<path>:<first>-<last>@<from>`: the symbol's span, resumed at `<from>`.
+ A span the graph places past EOF is clamped to the file first.
+
+A plain `path:a-b` is a range you typed and is never capped. A `path:a-b@from`
+cursor is capped again, and its record (`target=file-range`) repeats the same
+`total_lines`, `span_end` and a further `next=`, so following `next=` until it
+is absent reaches the symbol's last line. A cursor's path is relative to the
+workspace root, which is what `ix read` resolves it against, so it works from
+any directory inside the workspace:
+
+```
+file path=src/big.ts line_start=10 line_end=409 target=symbol symbol=bigFn kind=function truncated=true total_lines=1318 span_end=1327 next=src/big.ts:10-1327@410
+file path=src/big.ts line_start=410 line_end=809 target=file-range truncated=true total_lines=1318 span_end=1327 next=src/big.ts:10-1327@810
+```
+
## Rows an agent acts on
The rows below are the ones an agent reads and then opens, cites or edits, so
diff --git a/ix-cli/src/cli/__tests__/read-line-cap.test.ts b/ix-cli/src/cli/__tests__/read-line-cap.test.ts
index f1d6317e..bb1fdcfa 100644
--- a/ix-cli/src/cli/__tests__/read-line-cap.test.ts
+++ b/ix-cli/src/cli/__tests__/read-line-cap.test.ts
@@ -6,7 +6,29 @@ import { mkdtempSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from "node
import { tmpdir } from "node:os";
import { join } from "node:path";
-import { registerReadCommand } from "../commands/read.js";
+import { capSpan, registerReadCommand } from "../commands/read.js";
+
+// Symbol reads resolve through the graph; these stand in for it. The spreads
+// keep every other export real, so the file-read cases below are unaffected.
+const graph = vi.hoisted(() => ({ node: {} as Record<string, unknown> }));
+
+vi.mock("../bootstrap.js", async (orig) => ({
+ ...(await orig<typeof import("../bootstrap.js")>()),
+ resolveWorkspaceId: () => "ws-test",
+}));
+
+vi.mock("../resolve.js", async (orig) => ({
+ ...(await orig<typeof import("../resolve.js")>()),
+ resolveEntityFull: vi.fn(async () => ({ resolved: true, entity: { id: "e1" } })),
+ ensureReadScope: async () => {},
+ activeReadScope: () => ({}),
+}));
+
+vi.mock("../../client/api.js", () => ({
+ IxClient: class {
+ async entity() { return { node: graph.node, claims: [], edges: [] }; }
+ },
+}));
/**
* `ix read <file>` had no bound at all. Recorded reads ran 20,000 to 53,000
@@ -55,6 +77,7 @@ describe("ix read line cap", () => {
expect(logs[0]).toContain("truncated=true");
expect(logs[0]).toContain("total_lines=1734");
expect(logs[0]).toContain("next=src/big.ts:401-800");
+ expect(logs[0]).not.toContain("span_end=");
expect(logs[1]).toBe("content lines=400 numbered=true");
expect(logs[2]).toMatch(/^1\t/);
expect(logs[401]).toMatch(/^400\t/);
@@ -118,8 +141,275 @@ describe("ix read line cap", () => {
}
});
+ it("names a file cursor from the workspace root when run from a subdirectory", async () => {
+ mkdirSync(join(root, "lib"), { recursive: true });
+ writeFileSync(join(root, "lib", "big.ts"), BIG);
+ writeFileSync(join(root, "big.ts"), "decoy");
+ process.chdir(join(root, "lib"));
+ await read(["lib/big.ts", "--format", "llm"]);
+ expect(logs[0]).toContain("next=lib/big.ts:401-800");
+ logs = [];
+ await read(["lib/big.ts:401-800", "--format", "llm"]);
+ expect(logs[2]).toBe("401\tline 401");
+ });
+
it("does not offer a next page from the last one", async () => {
await read(["src/big.ts:1400-1734", "--format", "llm"]);
expect(logs[0]).not.toContain("next=");
});
});
+
+describe("ix read symbol cap", () => {
+ let root: string;
+ let logs: string[];
+ let errs: string[];
+ let originalCwd: string;
+
+ const BIG = Array.from({ length: 1734 }, (_, i) => `line ${i + 1}`).join("\n");
+
+ function symbolAt(start: number, end: number, content?: string): void {
+ graph.node = {
+ name: "bigFn",
+ kind: "function",
+ attrs: { line_start: start, line_end: end, ...(content ? { content } : {}) },
+ provenance: { source_uri: content ? undefined : join(root, "src", "big.ts") },
+ };
+ }
+
+ beforeEach(() => {
+ root = mkdtempSync(join(tmpdir(), "ix-read-symcap-"));
+ mkdirSync(join(root, "src"), { recursive: true });
+ writeFileSync(join(root, "src", "big.ts"), BIG);
+ originalCwd = process.cwd();
+ process.chdir(root);
+ logs = [];
+ errs = [];
+ vi.spyOn(console, "log").mockImplementation((...a: unknown[]) => void logs.push(a.map(String).join(" ")));
+ vi.spyOn(process.stderr, "write").mockImplementation((chunk: unknown) => {
+ errs.push(String(chunk));
+ return true;
+ });
+ });
+
+ afterEach(() => {
+ vi.restoreAllMocks();
+ process.chdir(originalCwd);
+ rmSync(root, { recursive: true, force: true });
+ });
+
+ async function read(args: string[]): Promise<void> {
+ const program = new Command();
+ program.name("ix").exitOverride();
+ registerReadCommand(program);
+ await program.parseAsync(["read", "bigFn", ...args, "--root", root], { from: "user" });
+ }
+
+ it("cuts a symbol longer than the cap and gives a cursor", async () => {
+ symbolAt(10, 1327);
+ await read(["--format", "llm"]);
+ expect(logs[0]).toContain("line_start=10 line_end=409");
+ expect(logs[0]).toContain("truncated=true");
+ expect(logs[0]).toContain("total_lines=1318");
+ expect(logs[0]).toContain("span_end=1327");
+ expect(logs[0]).toContain("next=src/big.ts:10-1327@410");
+ expect(logs[1]).toBe("content lines=400 numbered=true");
+ expect(logs[2]).toMatch(/^10\t/);
+ expect(logs[401]).toMatch(/^409\t/);
+ });
+
+ it("keeps the cursor inside the symbol", async () => {
+ symbolAt(1, 500);
+ await read(["--format", "llm"]);
+ expect(logs[0]).toContain("next=src/big.ts:1-500@401");
+ });
+
+ it("leaves a short symbol alone", async () => {
+ symbolAt(5, 20);
+ await read(["--format", "llm"]);
+ expect(logs[0]).toContain("line_end=20");
+ expect(logs[0]).not.toContain("truncated=");
+ expect(logs[0]).not.toContain("next=");
+ });
+
+ it("--all prints the whole symbol", async () => {
+ symbolAt(10, 1327);
+ await read(["--all", "--format", "llm"]);
+ expect(logs[0]).toContain("line_end=1327");
+ expect(logs[0]).not.toContain("truncated=");
+ expect(logs[0]).not.toContain("next=");
+ });
+
+ it("carries the cursor into json", async () => {
+ symbolAt(10, 1327);
+ await read(["--format", "json"]);
+ expect(JSON.parse(logs.join("\n"))).toMatchObject({
+ targetType: "symbol", lineStart: 10, lineEnd: 409, truncated: true, totalLines: 1318,
+ spanEnd: 1327, next: "src/big.ts:10-1327@410",
+ });
+ });
+
+ it("tells a person what they are missing, on stderr", async () => {
+ symbolAt(10, 1327);
+ await read([]);
+ const note = errs.join("");
+ expect(note).toContain("400 of 1318 lines");
+ expect(note).toContain("ix read src/big.ts:10-1327@410");
+ expect(note).toContain("--all");
+ expect(note).toContain("whole symbol");
+ expect(logs).toHaveLength(400);
+ });
+
+ it("returns stored content with no file whole, since it cannot be paged", async () => {
+ symbolAt(1, 900, Array.from({ length: 900 }, (_, i) => `c${i}`).join("\n"));
+ await read(["--format", "llm"]);
+ expect(logs[0]).toContain("line_end=900");
+ expect(logs[0]).not.toContain("truncated=");
+ expect(logs[0]).not.toContain("next=");
+ });
+
+ it("clamps a stale span that runs past EOF, so the cursor stays in the file", async () => {
+ // big.ts has 1734 lines; the graph still says the symbol ends at 2000.
+ symbolAt(1300, 2000);
+ await read(["--format", "llm"]);
+ expect(logs[0]).toContain("line_end=1699");
+ expect(logs[0]).toContain("total_lines=435");
+ expect(logs[0]).toContain("span_end=1734");
+ expect(logs[0]).toContain("next=src/big.ts:1300-1734@1700");
+ });
+
+ it("does not report truncated when the span only overflows past EOF", async () => {
+ symbolAt(1500, 2000);
+ await read(["--format", "llm"]);
+ expect(logs[0]).toContain("line_end=1734");
+ expect(logs[0]).not.toContain("truncated=");
+ expect(logs[0]).not.toContain("next=");
+ });
+
+ it("capSpan clamps the end to EOF", () => {
+ const lines = ["a", "b", "c"];
+ expect(capSpan(lines, 2, 9, 400)).toEqual({ content: "b\nc", lineStart: 2, lineEnd: 3 });
+ expect(capSpan(lines, 1, 9, 2)).toMatchObject({ lineEnd: 2, truncated: true, totalLines: 3, lastLine: 3 });
+ // Resumed from a cursor: the count is still the whole span's.
+ expect(capSpan(["a", "b", "c", "d", "e"], 1, 5, 2, 3)).toMatchObject({ content: "c\nd", lineStart: 3, lineEnd: 4, totalLines: 5, lastLine: 5 });
+ });
+
+ it("--all help names symbols as well as files", () => {
+ const program = new Command();
+ registerReadCommand(program);
+ const all = program.commands.find((c) => c.name() === "read")!.options.find((o) => o.long === "--all")!;
+ expect(all.description).toContain("file or symbol");
+ });
+
+ it("follows next= from a symbol read to the symbol's last line", async () => {
+ // A plain path:a-b cursor is a typed range, never capped and never given a
+ // cursor, so paging used to stop after page 2. Follow every next= instead.
+ symbolAt(10, 1327);
+ await read(["--format", "json"]);
+ const pages: Array<Record<string, unknown>> = [JSON.parse(logs.join("\n"))];
+ for (let hops = 0; pages[pages.length - 1].next && hops < 10; hops++) {
+ logs = [];
+ const program = new Command();
+ program.name("ix").exitOverride();
+ registerReadCommand(program);
+ await program.parseAsync(
+ ["read", String(pages[pages.length - 1].next), "--format", "json", "--root", root], { from: "user" });
+ pages.push(JSON.parse(logs.join("\n")));
+ }
+ expect(pages.map((p) => [p.lineStart, p.lineEnd])).toEqual([[10, 409], [410, 809], [810, 1209], [1210, 1327]]);
+ expect(pages.map((p) => p.next)).toEqual([
+ "src/big.ts:10-1327@410", "src/big.ts:10-1327@810", "src/big.ts:10-1327@1210", undefined,
+ ]);
+ // Every capped page names the same span: its size and where it ends.
+ for (const p of pages.slice(0, 3)) expect(p).toMatchObject({ truncated: true, totalLines: 1318, spanEnd: 1327 });
+ expect(pages[3].truncated).toBeUndefined();
+ // Each page is 400 lines of the right source.
+ expect(String(pages[1].content).split("\n")[0]).toBe("line 410");
+ expect(String(pages[3].content).split("\n").pop()).toBe("line 1327");
+ });
+
+ it("pages a cursor in llm format, and --all reads the rest of the span", async () => {
+ const program = () => {
+ const p = new Command();
+ p.name("ix").exitOverride();
+ registerReadCommand(p);
+ return p;
+ };
+ await program().parseAsync(["read", "src/big.ts:10-1327@410", "--format", "llm", "--root", root], { from: "user" });
+ expect(logs[0]).toContain("line_start=410 line_end=809");
+ expect(logs[0]).toContain("target=file-range");
+ expect(logs[0]).toContain("total_lines=1318 span_end=1327 next=src/big.ts:10-1327@810");
+ expect(logs[2]).toMatch(/^410\tline 410$/);
+ logs = [];
+ await program().parseAsync(["read", "src/big.ts:10-1327@410", "--all", "--format", "llm", "--root", root], { from: "user" });
+ expect(logs[0]).toContain("line_start=410 line_end=1327");
+ expect(logs[0]).not.toContain("next=");
+ });
+
+ it("rejects a cursor whose page start is outside its range", async () => {
+ const p = new Command();
+ p.name("ix").exitOverride();
+ registerReadCommand(p);
+ await p.parseAsync(["read", "src/big.ts:10-1327@5", "--format", "llm", "--root", root], { from: "user" });
+ expect(logs[0]).toContain("invalid_line_range");
+ expect(logs[0]).toContain("@n");
+ process.exitCode = 0;
+ });
+
+ it("keeps the old message for an ordinary invalid range", async () => {
+ const p = new Command();
+ p.name("ix").exitOverride();
+ registerReadCommand(p);
+ await p.parseAsync(["read", "src/big.ts:20-10", "--format", "llm", "--root", root], { from: "user" });
+ expect(logs[0]).toContain("Line numbers must start at 1 and the end must not precede the start.");
+ expect(logs[0]).not.toContain("@n");
+ process.exitCode = 0;
+ });
+
+ it("says --all on a cursor page reads the rest of the range", async () => {
+ const p = new Command();
+ p.name("ix").exitOverride();
+ registerReadCommand(p);
+ await p.parseAsync(["read", "src/big.ts:10-1327@410", "--root", root], { from: "user" });
+ const note = errs.join("");
+ expect(note).toContain("400 of 1318 lines");
+ expect(note).toContain("ix read src/big.ts:10-1327@810");
+ expect(note).toContain("--all for the rest of the range");
+ });
+
+ it("names the cursor from the workspace root, so it round-trips from a subdirectory", async () => {
+ // The symbol lives in lib/big.ts; <root>/big.ts is a different file with
+ // the same basename. A cwd-relative cursor (`big.ts:...`) printed from
+ // lib/ resolved against the root and read the decoy.
+ mkdirSync(join(root, "lib"), { recursive: true });
+ writeFileSync(join(root, "lib", "big.ts"), BIG);
+ writeFileSync(join(root, "big.ts"), Array.from({ length: 1734 }, (_, i) => `decoy ${i + 1}`).join("\n"));
+ graph.node = {
+ name: "bigFn",
+ kind: "function",
+ attrs: { line_start: 10, line_end: 1327 },
+ provenance: { source_uri: join(root, "lib", "big.ts") },
+ };
+ process.chdir(join(root, "lib"));
+ await read(["--format", "json"]);
+ const pages: Array<Record<string, unknown>> = [JSON.parse(logs.join("\n"))];
+ expect(pages[0].next).toBe("lib/big.ts:10-1327@410");
+ for (let hops = 0; pages[pages.length - 1].next && hops < 10; hops++) {
+ logs = [];
+ const program = new Command();
+ program.name("ix").exitOverride();
+ registerReadCommand(program);
+ await program.parseAsync(
+ ["read", String(pages[pages.length - 1].next), "--format", "json", "--root", root], { from: "user" });
+ pages.push(JSON.parse(logs.join("\n")));
+ }
+ expect(pages.map((p) => p.lineEnd)).toEqual([409, 809, 1209, 1327]);
+ for (const p of pages) expect(String(p.content)).not.toContain("decoy");
+ expect(String(pages[3].content).split("\n").pop()).toBe("line 1327");
+ });
+
+ it("capSpan returns an uncapped span unchanged", () => {
+ const lines = ["a", "b", "c"];
+ expect(capSpan(lines, 2, 3, 400)).toEqual({ content: "b\nc", lineStart: 2, lineEnd: 3 });
+ expect(capSpan(lines, 1, 3, undefined)).toEqual({ content: "a\nb\nc", lineStart: 1, lineEnd: 3 });
+ });
+});
diff --git a/ix-cli/src/cli/commands/read.ts b/ix-cli/src/cli/commands/read.ts
index a908eb76..617f9f5a 100644
--- a/ix-cli/src/cli/commands/read.ts
+++ b/ix-cli/src/cli/commands/read.ts
@@ -29,9 +29,24 @@ export interface ReadResult {
warning?: string;
/** Set when the default line cap stopped the read short of the file. */
truncated?: boolean;
- /** How many lines the file has, when the read was capped. */
+ /**
+ * How many lines the read's whole target has, when the read was capped: the
+ * file's line count for a file, and the span's line count (`spanEnd` minus
+ * its first line, plus one) for a symbol or a paged range. It is a count,
+ * never a line number; `spanEnd` is where a symbol or paged range ends.
+ */
totalLines?: number;
- /** The next page, ready to run: `path:401-800`. */
+ /**
+ * The last line of the symbol or paged range being paged, when the read was
+ * capped. Absent on plain file reads, where `totalLines` is already the last
+ * line.
+ */
+ spanEnd?: number;
+ /**
+ * The next page, ready to run. `path:401-800` for a file. For a symbol or a
+ * paged range it is `path:<first>-<last>@<from>`: the same span, read from
+ * `<from>` and capped again, so following it repeatedly reaches `spanEnd`.
+ */
next?: string;
}
@@ -74,8 +89,10 @@ function guardReadable(absPath: string, explicitRoot: string | undefined, what:
return false;
}
-function reportInvalidLineRange(target: string, format: string): void {
- const message = `Invalid line range in "${target}". Line numbers must start at 1 and the end must not precede the start.`;
+function reportInvalidLineRange(target: string, format: string, paged = false): void {
+ const message = paged
+ ? `Invalid line range in "${target}". Line numbers must start at 1, the end must not precede the start, and a page start (@n) must fall inside the range.`
+ : `Invalid line range in "${target}". Line numbers must start at 1 and the end must not precede the start.`;
if (format === "json") {
printJson({ error: "invalid_line_range", message });
} else if (format === "llm") {
@@ -119,54 +136,125 @@ function readFileRange(
}
/**
- * The shortest path that still names this file from where the caller stands.
+ * The path a `next=` cursor names its file by: relative to the workspace root,
+ * because that is what `ix read` resolves a relative target against.
*
- * `relativePath` is a prefix match against `process.cwd()`, which misses in two
- * ordinary cases: a cwd and a target that disagree about a symlink (macOS
- * resolves `/var` to `/private/var`, and any repo under a `~/code` link does
- * the same), and Windows, where the stored separator is `\` and the match is
- * written for `/`. A `next=` that comes back absolute still works when pasted,
- * but it is the token cost the cursor exists to avoid.
+ * It used to be relative to the cwd (`relativePath`). From a subdirectory of
+ * the workspace that cursor did not round-trip: `big.ts` printed from `src/`
+ * resolved to `<root>/big.ts`, which is a miss, a basename match, or a
+ * different file with the same name. A symbol's file is often outside the
+ * cwd's subtree, so symbol cursors hit this far more than file cursors did.
+ * Run from the root, the cursor is the same as before.
*
- * Falls back to the absolute path rather than to `..` — a cursor pointing out
- * of the tree is worse than a long one.
+ * Both sides are compared through `realpath` as a fallback, since a root
+ * reached through a symlink (macOS `/var` -> `/private/var`, a `~/code` link)
+ * fails a plain prefix match. Falls back to the absolute path rather than to
+ * `..`: a file outside the root is named the one way every cwd agrees on.
*/
-function readablePath(filePath: string): string {
- const relative = relativePath(filePath);
- if (relative && relative !== filePath) return relative;
+function cursorPath(filePath: string, root: string): string {
+ const inside = (from: string, to: string): string | undefined => {
+ const rel = path.relative(from, to);
+ return rel && !rel.startsWith("..") && !path.isAbsolute(rel) ? rel.split(path.sep).join("/") : undefined;
+ };
+ const direct = inside(path.resolve(root), path.resolve(filePath));
+ if (direct) return direct;
try {
- const fromCwd = path.relative(fs.realpathSync(process.cwd()), fs.realpathSync(filePath));
- if (fromCwd && !fromCwd.startsWith("..") && !path.isAbsolute(fromCwd)) {
- return fromCwd.split(path.sep).join("/");
- }
+ const real = inside(fs.realpathSync(root), fs.realpathSync(filePath));
+ if (real) return real;
} catch {
- // An unreadable cwd or a file deleted under us: the absolute path stands.
+ // An unreadable root or a file deleted under us: the absolute path stands.
}
return filePath;
}
/** `src/a.ts:401-800`, or nothing when the cap landed on the last line. */
-function nextPage(filePath: string, lineEnd: number, totalLines: number): string | undefined {
- if (lineEnd >= totalLines) return undefined;
+function nextPage(filePath: string, root: string, lineEnd: number, lastLine: number): string | undefined {
+ if (lineEnd >= lastLine) return undefined;
const from = lineEnd + 1;
- const to = Math.min(totalLines, lineEnd + READ_LINE_CAP);
- return `${readablePath(filePath)}:${from}-${to}`;
+ const to = Math.min(lastLine, lineEnd + READ_LINE_CAP);
+ return `${cursorPath(filePath, root)}:${from}-${to}`;
+}
+
+/**
+ * A paged span's next page: `src/a.ts:10-1327@410`. A plain `path:a-b` is a
+ * range the caller typed and is never capped, so a symbol's cursor in that
+ * form ended the paging after one hop; this form is capped again and carries
+ * the span with it, so every page has a cursor until the span's last line.
+ */
+function nextSpanPage(filePath: string, root: string, spanStart: number, lineEnd: number, lastLine: number): string | undefined {
+ if (lineEnd >= lastLine) return undefined;
+ return `${cursorPath(filePath, root)}:${spanStart}-${lastLine}@${lineEnd + 1}`;
}
/** Fold a capped read's cursor into the result the renderers see. */
function withCursor(
result: ReadResult,
- capped: { truncated?: boolean; totalLines?: number },
+ capped: { truncated?: boolean; totalLines?: number; lastLine?: number; spanStart?: number },
+ root: string,
): ReadResult {
if (!capped.truncated || capped.totalLines === undefined) return result;
+ if (capped.lastLine !== undefined && capped.spanStart !== undefined) {
+ return {
+ ...result,
+ truncated: true,
+ totalLines: capped.totalLines,
+ spanEnd: capped.lastLine,
+ next: nextSpanPage(result.path, root, capped.spanStart, result.lineEnd, capped.lastLine),
+ };
+ }
return {
...result,
truncated: true,
totalLines: capped.totalLines,
- next: nextPage(result.path, result.lineEnd, capped.totalLines),
+ next: nextPage(result.path, root, result.lineEnd, capped.lastLine ?? capped.totalLines),
};
}
+/**
+ * Cut a span at `cap` lines from `from` (its start, unless a paged cursor
+ * resumes it further in). `lastLine` is where the span ends, so a `next=`
+ * cursor never pages past it; `totalLines` is the whole span's line count,
+ * the same on every page. With no cap, or a remainder that fits, nothing is
+ * cut.
+ *
+ * The end is clamped to EOF first: a stale graph span that could not be
+ * re-anchored can claim lines the file no longer has, and an unclamped end
+ * would report `truncated` with a cursor that pages past the last line.
+ */
+export function capSpan(
+ lines: string[], start: number, rawEnd: number, cap?: number, from: number = start,
+): { content: string; lineStart: number; lineEnd: number; truncated?: boolean; totalLines?: number; lastLine?: number; spanStart?: number } {
+ const end = Math.max(start, Math.min(rawEnd, lines.length));
+ const first = Math.min(Math.max(from, start), end);
+ if (cap !== undefined && end - first + 1 > cap) {
+ const shownEnd = first + cap - 1;
+ return {
+ content: lines.slice(first - 1, shownEnd).join("\n"),
+ lineStart: first,
+ lineEnd: shownEnd,
+ truncated: true,
+ totalLines: end - start + 1,
+ lastLine: end,
+ spanStart: start,
+ };
+ }
+ return { content: lines.slice(first - 1, end).join("\n"), lineStart: first, lineEnd: end };
+}
+
+/**
+ * Read a file target: the whole file (capped), a typed `path:a-b` range
+ * (never capped), or a paged `path:a-b@from` cursor (capped, inside a-b).
+ */
+function readFileTarget(
+ filePath: string, start: number | undefined, end: number | undefined, pageFrom: number | undefined, cap: number | undefined,
+): ReturnType<typeof capSpan> {
+ if (pageFrom !== undefined && start !== undefined && end !== undefined) {
+ const lines = fs.readFileSync(filePath, "utf-8").split("\n");
+ return capSpan(lines, start, end, cap, pageFrom);
+ }
+ return readFileRange(filePath, start, end, cap);
+}
+
/**
* `ix read --format llm`.
*
@@ -216,6 +304,7 @@ export function renderReadLlm(result: ReadResult): string[] {
// The three fields that make a capped read recoverable in one call.
["truncated", result.truncated ? "true" : null],
["total_lines", result.totalLines !== undefined ? String(result.totalLines) : null],
+ ["span_end", result.spanEnd !== undefined ? String(result.spanEnd) : null],
["next", result.next],
]),
llmLine("content", [["lines", String(contentLines.length)], ["numbered", "true"]]),
@@ -275,9 +364,14 @@ export function outputResult(result: ReadResult, format: string): void {
}
if (result.truncated) {
stderr(chalk.dim(
- `\n ${result.lineEnd} of ${result.totalLines} lines`
+ `\n ${result.lineEnd - result.lineStart + 1} of ${result.totalLines} lines`
+ (result.next ? ` — next: ix read ${result.next}` : "")
- + ", or --all for the whole file",
+ + (result.targetType === "symbol"
+ ? ", or --all for the whole symbol"
+ : result.spanEnd !== undefined
+ // A cursor page starts at its @from, and so does --all on it.
+ ? ", or --all for the rest of the range"
+ : ", or --all for the whole file"),
));
}
}
@@ -315,10 +409,11 @@ export function registerReadCommand(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("--root <dir>", "Workspace root directory")
- .option("--all", `Read the whole file, past the ${READ_LINE_CAP}-line default cap`)
+ .option("--all", `Read the whole file or symbol, past the ${READ_LINE_CAP}-line default cap`)
.addHelpText("after", `\nResolution order:
1. Exact file path ix read src/main.ts
2. File path with line range ix read src/main.ts:10-50
+ (a capped read's next= cursor, path:10-1327@410, pages within 10-1327)
3. Unique filename match ix read Node.scala
4. Unique symbol match ix read IngestionService
5. Ambiguity candidates (prompted to disambiguate)
@@ -338,12 +433,21 @@ Examples:
const client = createClient();
// --- Step 1: Parse line range if present ---
- const lineRangeMatch = target.match(/^(.+?):(\d+)-(\d+)$/);
+ // `path:a-b` is a range the caller typed. `path:a-b@from` is a paged
+ // cursor (what a capped symbol read hands back as next=): lines a-b,
+ // read from `from` and capped like a whole file.
+ const lineRangeMatch = target.match(/^(.+?):(\d+)-(\d+)(?:@(\d+))?$/);
const rawTarget = lineRangeMatch ? lineRangeMatch[1] : target;
const rangeStart = lineRangeMatch ? parseInt(lineRangeMatch[2], 10) : undefined;
const rangeEnd = lineRangeMatch ? parseInt(lineRangeMatch[3], 10) : undefined;
+ const pageFrom = lineRangeMatch?.[4] !== undefined ? parseInt(lineRangeMatch[4], 10) : undefined;
if (rangeStart !== undefined && rangeEnd !== undefined && (rangeStart < 1 || rangeEnd < rangeStart)) {
- reportInvalidLineRange(target, opts.format);
+ reportInvalidLineRange(target, opts.format, pageFrom !== undefined);
+ return;
+ }
+ if (pageFrom !== undefined && rangeStart !== undefined && rangeEnd !== undefined
+ && (pageFrom < rangeStart || pageFrom > rangeEnd)) {
+ reportInvalidLineRange(target, opts.format, true);
return;
}
@@ -356,14 +460,14 @@ Examples:
if (fs.existsSync(resolvedPath) && fs.statSync(resolvedPath).isFile()) {
if (!guardReadable(resolvedPath, opts.root, "file", opts.format)) return;
const stale = checkStale(resolvedPath);
- const capped = readFileRange(resolvedPath, rangeStart, rangeEnd, cap);
+ const capped = readFileTarget(resolvedPath, rangeStart, rangeEnd, pageFrom, cap);
const result: ReadResult = withCursor({
targetType: lineRangeMatch ? "file-range" : "file",
path: resolvedPath,
lineStart: capped.lineStart,
lineEnd: capped.lineEnd,
content: capped.content,
- }, capped);
+ }, capped, root);
if (stale) { result.stale = true; result.warning = "Results may be stale; file has changed since last ingest."; }
outputResult(result, opts.format);
return;
@@ -391,14 +495,14 @@ Examples:
// guard is what stops a backend from naming a file off the disk.
if (!guardReadable(matchPath, opts.root, "graph file match", opts.format)) return;
const stale = checkStale(matchPath);
- const capped = readFileRange(matchPath, rangeStart, rangeEnd, cap);
+ const capped = readFileTarget(matchPath, rangeStart, rangeEnd, pageFrom, cap);
const result: ReadResult = withCursor({
targetType: "filename-match",
path: matchPath,
lineStart: capped.lineStart,
lineEnd: capped.lineEnd,
content: capped.content,
- }, capped);
+ }, capped, root);
if (stale) { result.stale = true; result.warning = "Results may be stale; file has changed since last ingest."; }
outputResult(result, opts.format);
return;
@@ -438,16 +542,16 @@ Examples:
node.attrs?.lineEnd ?? node.attrs?.line_end,
stale,
);
- const content = allLines.slice(range.lineStart - 1, range.lineEnd).join("\n");
- const result: ReadResult = {
+ const span = capSpan(allLines, range.lineStart, range.lineEnd, cap);
+ const result: ReadResult = withCursor({
targetType: "symbol",
path: absSourceUri,
- lineStart: range.lineStart,
- lineEnd: range.lineEnd,
- content,
+ lineStart: span.lineStart,
+ lineEnd: span.lineEnd,
+ content: span.content,
symbol: node.name,
kind: node.kind,
- };
+ }, span, root);
if (stale) {
result.stale = true;
result.warning = range.movedFrom
@@ -462,6 +566,9 @@ Examples:
const attrContent = node.attrs?.content;
if (attrContent) {
const lines = String(attrContent).split("\n");
+ // Deliberately uncapped: there is no file on disk to page, so a cap
+ // would drop lines 401+ with no cursor and no way to recover them
+ // (the MCP tool has no --all).
const result: ReadResult = {
targetType: "symbol",
path: absSourceUri ?? sourceUri ?? "(no source file)",
diff --git a/ix-cli/src/mcp/server.ts b/ix-cli/src/mcp/server.ts
index 42a7d27d..4ffc7920 100644
--- a/ix-cli/src/mcp/server.ts
+++ b/ix-cli/src/mcp/server.ts
@@ -484,7 +484,7 @@ export function createIxMcpServer(options: CreateServerOptions = {}): McpServer
registerTool(
ctx,
"ix_read",
- "Use when you have a symbol name but not its file or lines. Returns exactly that definition's source; also takes a path or path:start-end. Not needed when you already know path and range: Read does that.",
+ "Use when you have a symbol name but not its file or lines. Returns that definition's source, 400 lines a page (pass each next= back as symbol until none is given); also takes a path or path:start-end. Not needed when you already know path and range: Read does that.",
{
symbol: z.string().min(1).describe("a symbol, a path, or `path:start-end`"),
kind: z.string().min(1).optional(),
diff --git a/skills/ix/references/flags.md b/skills/ix/references/flags.md
index b62c8e36..8b4ceaf1 100644
--- a/skills/ix/references/flags.md
+++ b/skills/ix/references/flags.md
@@ -78,8 +78,12 @@ surfaces (#575).
(`ix_neighbors symbol=X relation=callers`), never as CLI flags.
- **`ix read <file>` stops at 400 lines.** The header then carries
`truncated=true total_lines=<n> next=<path>:401-800`, so the next page is one
- command away. A line range you typed (`ix read a.ts:1-900`) is never capped,
- a symbol target is its own span, and `--all` reads the whole file.
+ command away. A line range you typed (`ix read a.ts:1-900`) is never capped.
+ A symbol longer than 400 lines is capped the same way. Its header adds
+ `span_end=<last line>`, `total_lines` is the symbol's span length (a count,
+ not the file's), and `next=<path>:10-1327@410` resumes the symbol's span, is
+ capped again and carries its own `next=` until the symbol's last line.
+ `--all` reads the whole file or symbol.
- **`ix depends` and `ix trace` stop at depth 3 and 100 nodes.** Both were
unbounded, which on a hub is thousands of nodes the caller pays for before
seeing any. The output distinguishes the two ways a walk ends:
@@ -671,7 +675,7 @@ Read raw file content, line ranges, or symbol source code.
| `--path` | `<path>` | — | Restrict to symbols from files matching this path substring |
| `--pick` | `<n>` | — | Pick Nth candidate from ambiguous results (1-based) |
| `--root` | `<dir>` | — | Workspace root directory |
-| `--all` | — | off | Read the whole file, past the 400-line default cap |
+| `--all` | — | off | Read the whole file or symbol, past the 400-line default cap |
### `ix reset`