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): 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.ts
new file mode 100644
index 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.ts
index 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.ts
2. File path with line range ix read src/main.ts:10-50
@@ -215,7 +305,10 @@ Examples:
ix read IngestionService
ix read ingestFile --kind method
ix 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.md
index 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`, whose
schemas differed by one word. `--tools=all` advertises every tool, and the Pro
tools 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 an
ambiguous 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`