Skip to content

armgit / Ix

Public Imported from GitHub
0

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

feat(context): say what the budget cut, and the cheapest way to get it back

KageBinary7ca29b073bd0
diff --git a/ix-cli/src/cli/__tests__/context-truncation-hint.test.ts b/ix-cli/src/cli/__tests__/context-truncation-hint.test.ts
new file mode 100644
index 00000000..2584e91b
--- /dev/null
+++ b/ix-cli/src/cli/__tests__/context-truncation-hint.test.ts
@@ -0,0 +1,76 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+import { describe, expect, it } from "vitest";
+
+import { truncationAdvice } from "../commands/context.js";
+
+function bundle(
+ target: { name: string; kind: string },
+ cut: Array<{ what: string; count: number }>,
+): never {
+ return {
+ target: { id: "t", resolutionMode: "exact", ...target },
+ truncation: {
+ entitiesTruncated: 0,
+ relationshipsTruncated: 0,
+ evidenceTruncated: cut.reduce((n, c) => n + c.count, 0),
+ charactersTruncated: 0,
+ cut,
+ },
+ } as never;
+}
+
+describe("truncationAdvice", () => {
+ it("says nothing when nothing was cut", () => {
+ expect(truncationAdvice(bundle({ name: "x", kind: "function" }, []))).toBeUndefined();
+ });
+
+ it("names what went, largest first, and pluralises on the count", () => {
+ const advice = truncationAdvice(
+ bundle({ name: "format.ts", kind: "file" }, [
+ { what: "member", count: 36 },
+ { what: "import", count: 12 },
+ { what: "claim", count: 1 },
+ ]),
+ );
+ expect(advice).toContain("cut: 36 members, 12 imports, 1 claim");
+ });
+
+ it("names at most three categories, so the hint stays one line", () => {
+ const advice = truncationAdvice(
+ bundle({ name: "x", kind: "function" }, [
+ { what: "member", count: 4 },
+ { what: "import", count: 3 },
+ { what: "caller", count: 2 },
+ { what: "claim", count: 1 },
+ ]),
+ );
+ expect(advice).not.toContain("claim");
+ });
+
+ it("sends a container that lost its members to one of them, not to a bigger budget", () => {
+ const advice = truncationAdvice(bundle({ name: "format.ts", kind: "file" }, [{ what: "member", count: 36 }]))!;
+ expect(advice).toContain("run ix context on one of them");
+ expect(advice).toContain("raise --max-tokens");
+ });
+
+ it("sends a symbol to the bounded command that answers the same question", () => {
+ const cases: Array<[string, string]> = [
+ ["caller", "ix callers verify"],
+ ["dependent", "ix impact verify"],
+ ["import", "ix imports verify"],
+ ["call", "ix callees verify"],
+ ["relationship", "ix depends verify"],
+ ["claim", "ix conflicts verify"],
+ ];
+ for (const [what, expected] of cases) {
+ const advice = truncationAdvice(bundle({ name: "verify", kind: "function" }, [{ what, count: 9 }]))!;
+ expect(advice, what).toContain(expected);
+ }
+ });
+
+ it("falls back to the one lever that works for anything", () => {
+ const advice = truncationAdvice(bundle({ name: "x", kind: "function" }, [{ what: "provenance", count: 1 }]))!;
+ expect(advice).toBe("cut: 1 provenance — raise --max-tokens");
+ });
+});
diff --git a/ix-cli/src/cli/commands/context.ts b/ix-cli/src/cli/commands/context.ts
index ef284ee0..e5576f3a 100644
--- a/ix-cli/src/cli/commands/context.ts
+++ b/ix-cli/src/cli/commands/context.ts
@@ -258,6 +258,15 @@ interface ContextBundle {
relationshipsTruncated: number;
evidenceTruncated: number;
charactersTruncated: number;
+ /**
+ * What the budget dropped, by category, largest first.
+ *
+ * The counts above say how much went; this says what it was. "Rerun with
+ * larger --max-* budgets" was the same sentence for a file that lost 36 of
+ * its own members and for a symbol that lost two claims, and it named the
+ * one lever that costs the caller the most to pull.
+ */
+ cut?: Array<{ what: string; count: number }>;
};
metadata: {
asOfRev?: number;
@@ -1639,6 +1648,8 @@ export function buildBundle(input: BuildInput): ContextBundle {
}
bundle.evidence = evidence.slice(0, kept);
bundle.truncation.evidenceTruncated = evidence.length - kept;
+ const dropped = summariseCut(evidence.slice(kept));
+ if (dropped.length > 0) bundle.truncation.cut = dropped;
const fullChars = sizedEvidence.reduce((sum, entry) => sum + entry.size, 0);
bundle.truncation.charactersTruncated = Math.max(0, fullChars - chars);
@@ -1840,6 +1851,13 @@ export function renderBundle(bundle: ContextBundle, format: string): void {
truncated_evidence: bundle.truncation.evidenceTruncated,
truncated_chars: bundle.truncation.charactersTruncated,
}),
+ // What the budget dropped, and the cheapest command that gets it back.
+ // The header's `truncated_*` counters say how much went; without this the
+ // caller's only move is a bigger budget for the same query, which is the
+ // most expensive one available.
+ truncationAdvice(bundle)
+ ? llmLine("diagnostic", { code: "bundle_truncated", message: truncationAdvice(bundle) })
+ : null,
// Evidence only, as before. The entity, relationship and claim lists are
// deliberately still counts here: `--format llm` is the token-minimal
// surface, the ranked evidence is what it exists to deliver, and
@@ -1874,13 +1892,96 @@ export function renderBundle(bundle: ContextBundle, format: string): void {
const trunc = bundle.truncation;
if (trunc.entitiesTruncated + trunc.relationshipsTruncated + trunc.evidenceTruncated > 0) {
+ const advice = truncationAdvice(bundle);
renderNote(
- `Truncated: ${trunc.entitiesTruncated} entities, ${trunc.relationshipsTruncated} relationships, ${trunc.evidenceTruncated} evidence items. Rerun with larger --max-* budgets for more.`,
+ `Truncated: ${trunc.entitiesTruncated} entities, ${trunc.relationshipsTruncated} relationships, ${trunc.evidenceTruncated} evidence items.`
+ + (advice ? ` ${advice}` : " Raise --max-tokens for more."),
);
}
console.log();
}
+/**
+ * Evidence sources, as the word a hint can put a number in front of.
+ *
+ * Keyed on `source` rather than `kind`: `kind` is `structural` for members,
+ * imports, calls, callers and dependents alike, and "cut: 48 structural" is the
+ * uninformative sentence this exists to replace.
+ */
+const CUT_LABELS: Record<string, string> = {
+ "facts.container": "container",
+ "facts.members": "member",
+ "facts.imports": "import",
+ "facts.callees": "call",
+ "facts.neighbours": "neighbouring definition",
+ "facts.callers": "caller",
+ "facts.dependents": "dependent",
+ "context.claims": "claim",
+ "context.decisions": "decision",
+ "context.conflicts": "conflict",
+ "context.intents": "intent",
+ "context.edges": "relationship",
+};
+
+/** Group the evidence a budget dropped by category, largest first. */
+function summariseCut(dropped: EvidenceItem[]): Array<{ what: string; count: number }> {
+ const counts = new Map<string, number>();
+ for (const item of dropped) {
+ const what = CUT_LABELS[item.source] ?? item.kind;
+ counts.set(what, (counts.get(what) ?? 0) + 1);
+ }
+ return [...counts.entries()]
+ .map(([what, count]) => ({ what, count }))
+ .sort((a, b) => b.count - a.count || a.what.localeCompare(b.what));
+}
+
+/**
+ * The cheapest command that gets back what the budget dropped.
+ *
+ * Target-specific because the answer is: a file that lost its own members wants
+ * one of those members as a target, not a bigger budget for the file; a symbol
+ * that lost callers wants `ix callers`, which is bounded and ranked and costs a
+ * fraction of a bundle. `--max-tokens` is named last, as the lever that works
+ * for anything and pays for everything.
+ */
+function cutLever(bundle: ContextBundle, top: { what: string }): string {
+ const name = bundle.target.name;
+ const container = ["file", "module", "class", "object", "trait", "interface"]
+ .includes(bundle.target.kind.toLowerCase());
+ switch (top.what) {
+ case "member":
+ return container
+ ? `run ix context on one of them, or raise --max-tokens`
+ : `ix contains ${name}, or raise --max-tokens`;
+ case "caller":
+ return `ix callers ${name}, or raise --max-tokens`;
+ case "dependent":
+ return `ix impact ${name}, or raise --max-tokens`;
+ case "import":
+ return `ix imports ${name}, or raise --max-tokens`;
+ case "call":
+ return `ix callees ${name}, or raise --max-tokens`;
+ case "relationship":
+ return `ix depends ${name}, or raise --max-tokens`;
+ case "claim":
+ case "conflict":
+ return `ix conflicts ${name}, or raise --max-tokens`;
+ default:
+ return `raise --max-tokens`;
+ }
+}
+
+/** One sentence naming what was cut and the cheapest way to get it back. */
+export function truncationAdvice(bundle: ContextBundle): string | undefined {
+ const cut = bundle.truncation.cut ?? [];
+ if (cut.length === 0) return undefined;
+ const named = cut
+ .slice(0, 3)
+ .map((c) => `${c.count} ${c.what}${c.count === 1 ? "" : "s"}`)
+ .join(", ");
+ return `cut: ${named} — ${cutLever(bundle, cut[0])}`;
+}
+
/** Members placed ahead of the backend's context nodes; the evidence shows as many. */
const LEADING_MEMBERS = 10;
diff --git a/ix-cli/src/cli/context-bundle-schema.ts b/ix-cli/src/cli/context-bundle-schema.ts
index 42394363..de3aecf1 100644
--- a/ix-cli/src/cli/context-bundle-schema.ts
+++ b/ix-cli/src/cli/context-bundle-schema.ts
@@ -116,6 +116,10 @@ export const contextBundleSchema = z.object({
maxChars: z.number().int().positive(),
}),
truncation: z.object({
+ // Optional for the same reason `budgets.maxTokens` is: a bundle saved
+ // before this field existed carries the counters and nothing else, and an
+ // undeclared key would be stripped from every new one on its way to disk.
+ cut: z.array(z.object({ what: z.string(), count: z.number().int().positive() })).optional(),
entitiesTruncated: z.number().int().nonnegative(),
relationshipsTruncated: z.number().int().nonnegative(),
evidenceTruncated: z.number().int().nonnegative(),