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
Merge branch 'feat/forge-hr-02a' into feat/forge-hr-02b
KageBinaryae09592bd93d
diff --cc docs/llm-format.mdindex 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 todiagnostic 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 existsbecause the header used to carry a single `total` field holding the length ofthe *cut* list — so `ix callers` on a symbol with 212 callers reporteddiff --cc ix-cli/src/cli/__tests__/honest-truncation.test.tsindex 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.tsindex 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<unknowconst 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.`;}