Skip to content

armgit / Ix

Public Imported from GitHub
0

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

Merge branch 'feat/forge-hr-02a' into feat/forge-hr-02b

KageBinaryae09592bd93d
diff --cc docs/llm-format.md
index e8036ef8,71ee2a00..7aa195ef
--- a/docs/llm-format.md
+++ b/docs/llm-format.md
@@@ -125,24 -125,10 +125,28 @@@ callers target=verify_token shown=50 to
diagnostic code=results_truncated next_offset=50 message="212 callers; showing 50. next: ix callers --offset 50 verify_token"
```
+A list that can be paged says where the next page starts: `next_offset=` on
+the `results_truncated` diagnostic, and a `next:` command in its message that
+repeats the caller's flags with `--offset`. A page past the first carries
+`offset=` on its header. A page that starts at or past the end is not an
+error: it prints a `diagnostic code=offset_past_end` and exits 0.
+
+The edge commands page over what one `/v1/expand` call returns, and the
+server stops at 1000 edges. When it reports a cut, or returns a full 1000,
+`total` is a floor: the list stays `results_truncated` on every page, its
+message says "At least N" and names the cap, no offset is called past the
+end, and the JSON summary carries `capped: true`. Past the cap, narrow the
+target (`--kind`, `--path`) instead of paging.
+
+```
+callers target=verify_token offset=50 shown=50 total=212 resolved=50
+diagnostic code=results_truncated next_offset=100 message="212 callers; showing 51-100. next: ix callers --offset 100 verify_token"
+```
+
+ The `next:` text is for whoever reads it: over MCP it is the tool's own
+ input (`next: offset=50`), not a CLI command. A command with no `--offset`
+ never prints `next:`; its message says `Raise --limit to see them.`
+
`shown < total` is the only signal that a list is partial, and it exists
because the header used to carry a single `total` field holding the length of
the *cut* list — so `ix callers` on a symbol with 212 callers reported
diff --cc ix-cli/src/cli/__tests__/honest-truncation.test.ts
index eae80771,07a47b94..28cb721c
--- a/ix-cli/src/cli/__tests__/honest-truncation.test.ts
+++ b/ix-cli/src/cli/__tests__/honest-truncation.test.ts
@@@ -1,20 -1,13 +1,21 @@@
// Copyright 2026 Ix Infrastructure Inc.
import { Command } from "commander";
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
-import { renderEdgeResultsLlm, sliceEdgeResults, sliceRanked, truncationHint } from "../format.js";
+const listByKind = vi.hoisted(() => vi.fn());
+vi.mock("../../client/factory.js", () => ({ createClient: () => ({ listByKind }) }));
+vi.mock("../resolve.js", () => ({ resolveReadSystemId: async () => undefined }));
+vi.mock("../bootstrap.js", () => ({ resolveWorkspaceId: () => "ws" }));
+
+import {
+ formatTextResults, renderEdgeResultsLlm, renderTextResultsLlm, sliceEdgeResults, sliceRanked, truncationHint,
+ type TextResult,
+} from "../format.js";
- import { nextPageCommand } from "../paging.js";
+ import { IX_CALLER_ENV } from "../next-step.js";
+ import { nextPageCommand, shellQuote } from "../paging.js";
-import { renderInventoryLlm } from "../commands/inventory.js";
-import { scanWindow, textResultPriority } from "../commands/text.js";
+import { LIST_MAX_ROWS, registerInventoryCommand, renderInventoryLlm } from "../commands/inventory.js";
+import { compareTextResults, keepTopK, scanWindow, textResultPriority } from "../commands/text.js";
function node(name: string, path?: string) {
return { id: `${name}-0000-0000-0000-000000000000`, name, kind: "function", ...(path ? { provenance: { source_uri: path } } : {}) };
diff --cc ix-cli/src/cli/format.ts
index 80e5917c,d8b6912b..fc5ab803
--- a/ix-cli/src/cli/format.ts
+++ b/ix-cli/src/cli/format.ts
@@@ -198,23 -198,21 +198,30 @@@ export function expandCapped(result: {
|| (result.nodes?.length ?? 0) >= EXPAND_MAX_EDGES;
}
+/**
+ * Which rows a page printed: `51-100` past the first page, the bare count on
+ * it. A page that printed nothing is `0` — with `--limit 0 --offset 50` the
+ * range form would read `51-50`.
+ */
+function pageRange(slice: Slice<unknown>): string {
+ const offset = slice.offset ?? 0;
+ return offset > 0 && slice.shown > 0 ? `${offset + 1}-${offset + slice.shown}` : `${slice.shown}`;
+}
+
- /** What was left out, and the one flag that gets it. */
+ /**
+ * What was left out, and the one flag that gets it.
+ *
+ * `next:` is printed only when the caller set `slice.next`: that is how a
+ * command says it takes `--offset`. `sliceRanked` sets `nextOffset` on every
+ * truncated slice, including slices cut by commands with no `--offset` (`ix
+ * impact`'s leaf rows), and pointing those at a flag they reject would send the
+ * reader into an unknown-option error.
+ */
export function truncationHint(slice: Slice<unknown>, relation: string): string {
- const offset = slice.offset ?? 0;
if (slice.capped) return cappedHint(slice, relation);
- const range = offset > 0 ? `${offset + 1}-${offset + slice.shown}` : `${slice.shown}`;
+ const range = pageRange(slice);
- if (slice.nextOffset === undefined) return `${slice.total} ${relation}; showing ${range}. Raise --limit to see them.`;
- const next = slice.next ?? `--offset ${slice.nextOffset}`;
- return `${slice.total} ${relation}; showing ${range}. next: ${next}`;
+ if (slice.nextOffset === undefined || slice.next === undefined) return `${slice.total} ${relation}; showing ${range}. Raise --limit to see them.`;
+ return `${slice.total} ${relation}; showing ${range}. next: ${slice.next}`;
}
/**
@@@ -225,10 -223,12 +232,11 @@@ function cappedHint(slice: Slice<unknow
const offset = slice.offset ?? 0;
const head = `At least ${slice.total} ${relation} (the server returns at most ${EXPAND_MAX_EDGES} edges)`;
if (slice.nextOffset !== undefined) {
- return `${head}; showing ${pageRange(slice)}. next: ${slice.next ?? `--offset ${slice.nextOffset}`}`;
- const range = offset > 0 ? `${offset + 1}-${offset + slice.shown}` : `${slice.shown}`;
- if (slice.next !== undefined) return `${head}; showing ${range}. next: ${slice.next}`;
- return `${head}; showing ${range}. Raise --limit, or narrow the target with --kind or --path, to see the rest.`;
++ if (slice.next !== undefined) return `${head}; showing ${pageRange(slice)}. next: ${slice.next}`;
++ return `${head}; showing ${pageRange(slice)}. Raise --limit, or narrow the target with --kind or --path, to see the rest.`;
}
const where = slice.shown > 0
- ? `showing ${offset > 0 ? `${offset + 1}-${offset + slice.shown}` : slice.shown}, the end of what it returned`
+ ? `showing ${pageRange(slice)}, the end of what it returned`
: offset > 0 ? `--offset ${offset} is beyond the rows it returned` : "showing 0";
return `${head}; ${where}. Narrow the target with --kind or --path to see the rest.`;
}