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): stop at 400 lines, and say where the next 400 are (#697)
Ian Hock4bc1356fe29c
diff --git a/ix-cli/src/cli/__tests__/read-line-cap.test.ts b/ix-cli/src/cli/__tests__/read-line-cap.test.tsnew file mode 100644index 00000000..0c643840--- /dev/null+++ b/ix-cli/src/cli/__tests__/read-line-cap.test.ts@@ -0,0 +1,123 @@+// Copyright 2026 Ix Infrastructure Inc.++import { Command } from "commander";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import { mkdtempSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { registerReadCommand } from "../commands/read.js";++/**+ * `ix read <file>` had no bound at all. Recorded reads ran 20,000 to 53,000+ * tokens, on a target whose size the caller cannot see before asking.+ */+describe("ix read line 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");++ beforeEach(() => {+ root = mkdtempSync(join(tmpdir(), "ix-read-cap-"));+ mkdirSync(join(root, "src"), { recursive: true });+ writeFileSync(join(root, "src", "big.ts"), BIG);+ writeFileSync(join(root, "src", "small.ts"), "one\ntwo\nthree");+ 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", ...args, "--root", root], { from: "user" });+ }++ it("stops at 400 lines and says how to get the next 400", async () => {+ await read(["src/big.ts", "--format", "llm"]);+ expect(logs[0]).toContain("line_start=1 line_end=400");+ 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[1]).toBe("content lines=400");+ });++ it("--all restores the whole file", async () => {+ await read(["src/big.ts", "--all", "--format", "llm"]);+ expect(logs[0]).toContain("line_end=1734");+ expect(logs[0]).not.toContain("truncated=");+ expect(logs[0]).not.toContain("next=");+ });++ it("never caps a range the caller typed", async () => {+ // They said what they wanted; 900 lines is an answer to a question asked.+ await read(["src/big.ts:1-900", "--format", "llm"]);+ expect(logs[0]).toContain("line_end=900");+ expect(logs[0]).not.toContain("truncated=true");+ });++ it("leaves a file that fits alone", async () => {+ await read(["src/small.ts", "--format", "llm"]);+ expect(logs[0]).toContain("line_end=3");+ expect(logs[0]).not.toContain("truncated=");+ });++ it("carries the cursor into json", async () => {+ await read(["src/big.ts", "--format", "json"]);+ const payload = JSON.parse(logs.join("\n"));+ expect(payload).toMatchObject({+ lineStart: 1, lineEnd: 400, truncated: true, totalLines: 1734,+ next: "src/big.ts:401-800",+ });+ });++ it("tells a person what they are missing, on stderr", async () => {+ await read(["src/big.ts"]);+ const note = errs.join("");+ expect(note).toContain("400 of 1734 lines");+ expect(note).toContain("ix read src/big.ts:401-800");+ expect(note).toContain("--all");+ // The source itself is still on stdout, all 400 lines of it.+ expect(logs).toHaveLength(400);+ });++ it("keeps the cursor relative when the root is reached through a symlink", async () => {+ // macOS resolves `/var` to `/private/var`, so `process.cwd()` and a path+ // built from `--root` disagree about a link on every temp-dir run there;+ // any repo under a `~/code` symlink does the same on Linux. A prefix match+ // against cwd misses, and the cursor used to come back absolute.+ const linked = join(originalCwd === root ? tmpdir() : tmpdir(), `ix-read-cap-link-${process.pid}`);+ rmSync(linked, { force: true });+ symlinkSync(root, linked, "dir");+ try {+ const program = new Command();+ program.name("ix").exitOverride();+ registerReadCommand(program);+ await program.parseAsync(["read", "src/big.ts", "--format", "llm", "--root", linked], { from: "user" });+ expect(logs[0]).toContain("next=src/big.ts:401-800");+ } finally {+ rmSync(linked, { force: true });+ }+ });++ 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=");+ });+});diff --git a/ix-cli/src/cli/commands/read.ts b/ix-cli/src/cli/commands/read.tsindex 8c5b3aef..2a689920 100644--- a/ix-cli/src/cli/commands/read.ts+++ b/ix-cli/src/cli/commands/read.ts@@ -24,6 +24,12 @@ export interface ReadResult {kind?: string;stale?: boolean;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. */+ totalLines?: number;+ /** The next page, ready to run: `path:401-800`. */+ next?: string;}interface AmbiguityResult {@@ -77,13 +83,85 @@ function reportInvalidLineRange(target: string, format: string): void {process.exitCode = 1;}-function readFileRange(filePath: string, start?: number, end?: number): { content: string; lineStart: number; lineEnd: number } {+/**+ * How much of a file a caller gets without asking for more.+ *+ * `ix read <file>` had no bound at all, and a file is the one target whose size+ * the caller cannot see before asking: recorded reads ran 20,000 to 53,000+ * tokens, and one benchmark run read the same file in eleven slices because the+ * first read arrived from the wrong anchor and cost too much to repeat.+ *+ * 400 lines is roughly 4-6k tokens of TypeScript — enough to hold a whole+ * small module, and small enough that a wrong guess is cheap to abandon. A+ * range the caller typed is never capped: they said what they wanted.+ */+const READ_LINE_CAP = 400;++function readFileRange(+ filePath: string,+ start?: number,+ end?: number,+ cap?: number,+): { content: string; lineStart: number; lineEnd: number; truncated?: boolean; totalLines?: number } {const raw = fs.readFileSync(filePath, "utf-8");const lines = raw.split("\n");const lineStart = start ?? 1;- const lineEnd = end ?? lines.length;- const content = lines.slice(lineStart - 1, lineEnd).join("\n");- return { content, lineStart, lineEnd };+ const requestedEnd = end ?? lines.length;+ const capped = cap !== undefined && end === undefined && requestedEnd - lineStart + 1 > cap+ ? lineStart + cap - 1+ : requestedEnd;+ const content = lines.slice(lineStart - 1, capped).join("\n");+ if (capped === requestedEnd) return { content, lineStart, lineEnd: capped };+ return { content, lineStart, lineEnd: capped, truncated: true, totalLines: lines.length };+}++/**+ * The shortest path that still names this file from where the caller stands.+ *+ * `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.+ *+ * Falls back to the absolute path rather than to `..` — a cursor pointing out+ * of the tree is worse than a long one.+ */+function readablePath(filePath: string): string {+ const relative = relativePath(filePath);+ if (relative && relative !== filePath) return relative;+ 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("/");+ }+ } catch {+ // An unreadable cwd 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;+ const from = lineEnd + 1;+ const to = Math.min(totalLines, lineEnd + READ_LINE_CAP);+ return `${readablePath(filePath)}:${from}-${to}`;+}++/** Fold a capped read's cursor into the result the renderers see. */+function withCursor(+ result: ReadResult,+ capped: { truncated?: boolean; totalLines?: number },+): ReadResult {+ if (!capped.truncated || capped.totalLines === undefined) return result;+ return {+ ...result,+ truncated: true,+ totalLines: capped.totalLines,+ next: nextPage(result.path, result.lineEnd, capped.totalLines),+ };}/**@@ -110,6 +188,10 @@ export function renderReadLlm(result: ReadResult): string[] {["symbol", result.symbol],["kind", result.kind],["stale", result.stale ? "true" : null],+ // 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],+ ["next", result.next],]),llmLine("content", [["lines", String(contentLines.length)]]),...contentLines,@@ -166,6 +248,13 @@ export function outputResult(result: ReadResult, format: string): void {for (let i = 0; i < lines.length; i++) {console.log(`${chalk.dim(String(result.lineStart + i).padStart(4))} ${lines[i]}`);}+ if (result.truncated) {+ stderr(chalk.dim(+ `\n ${result.lineEnd} of ${result.totalLines} lines`+ + (result.next ? ` — next: ix read ${result.next}` : "")+ + ", or --all for the whole file",+ ));+ }}}@@ -201,6 +290,7 @@ 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`).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@@ -215,7 +305,10 @@ Examples:ix read IngestionServiceix read ingestFile --kind methodix read verify_token --path auth`)- .action(async (target: string, opts: { format: string; kind?: string; path?: string; pick?: number; root?: string }) => {+ .action(async (target: string, opts: { format: string; kind?: string; path?: string; pick?: number; root?: string; all?: boolean }) => {+ // A range the caller typed is theirs; a whole file is capped unless they+ // say otherwise.+ const cap = opts.all ? undefined : READ_LINE_CAP;const root = resolveWorkspaceRoot(opts.root);const client = new IxClient(getEndpoint());@@ -234,14 +327,14 @@ Examples:if (fs.existsSync(resolvedPath) && fs.statSync(resolvedPath).isFile()) {if (!guardReadable(resolvedPath, opts.root, "file", opts.format)) return;const stale = checkStale(resolvedPath);- const { content, lineStart, lineEnd } = readFileRange(resolvedPath, rangeStart, rangeEnd);- const result: ReadResult = {+ const capped = readFileRange(resolvedPath, rangeStart, rangeEnd, cap);+ const result: ReadResult = withCursor({targetType: lineRangeMatch ? "file-range" : "file",path: resolvedPath,- lineStart,- lineEnd,- content,- };+ lineStart: capped.lineStart,+ lineEnd: capped.lineEnd,+ content: capped.content,+ }, capped);if (stale) { result.stale = true; result.warning = "Results may be stale; file has changed since last ingest."; }outputResult(result, opts.format);return;@@ -250,6 +343,16 @@ Examples:// --- Step 3: Try unique filename match (always, not just file-like targets) ---// read should prefer resolving to a real file before trying symbol match.// e.g. "ix read Node" should find Node.scala before trying symbol resolution.+ //+ // C-3 also asked for the reverse on an extension-less target — symbol+ // before filename, because `ix read config` means the symbol far more+ // often than the file. It is NOT done here: the only way to know a+ // symbol exists is to ask, and `read-local-first.test.ts` guarantees+ // zero round trips for exactly this case, after a measured 60-80s+ // incident. The line cap below removes the cost that motivated the flip+ // (a whole file is now 400 lines with a cursor, not 20-53k tokens), so+ // the remaining question is precision, and it is worth one explicit+ // decision rather than a quiet change here.{const filenameMatches = await tryFilenameMatch(client, rawTarget, root);if (filenameMatches.length === 1) {@@ -259,14 +362,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 { content, lineStart, lineEnd } = readFileRange(matchPath, rangeStart, rangeEnd);- const result: ReadResult = {+ const capped = readFileRange(matchPath, rangeStart, rangeEnd, cap);+ const result: ReadResult = withCursor({targetType: "filename-match",path: matchPath,- lineStart,- lineEnd,- content,- };+ lineStart: capped.lineStart,+ lineEnd: capped.lineEnd,+ content: capped.content,+ }, capped);if (stale) { result.stale = true; result.warning = "Results may be stale; file has changed since last ingest."; }outputResult(result, opts.format);return;diff --git a/skills/ix/references/flags.md b/skills/ix/references/flags.mdindex 1b32c7c4..ec2ecbda 100644--- a/skills/ix/references/flags.md+++ b/skills/ix/references/flags.md@@ -58,6 +58,10 @@ surfaces (#575).replaces `ix_callers` / `ix_callees` / `ix_imports` / `ix_imported_by`, whoseschemas differed by one word. `--tools=all` advertises every tool, and the Protools are offered under both whenever Pro is installed.+- **`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.- **`--pick <n>` is 1-based** everywhere it appears, and is how you resolve anambiguous target without re-running with a longer name.- **`--no-recursive` and `--no-open` negate a default-on behaviour**, so their@@ -481,6 +485,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 |### `ix reset`