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(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.mdindex 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.mdindex 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 rangeix read src/auth.py --all # a whole file (otherwise paged at 400 lines)```diff --git a/docs/llm-format.md b/docs/llm-format.mdindex 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 nopaging 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 onThe rows below are the ones an agent reads and then opens, cites or edits, sodiff --git a/ix-cli/src/cli/__tests__/read-line-cap.test.ts b/ix-cli/src/cli/__tests__/read-line-cap.test.tsindex 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 "nodeimport { 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.tsindex 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.ts2. 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.scala4. Unique symbol match ix read IngestionService5. 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.tsindex 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 = {}): McpServerregisterTool(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.mdindex 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 wereunbounded, which on a hub is thousands of nodes the caller pays for beforeseeing 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`