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): surface effective/requested/saved budgets on `ix context --diff`

Alot1z58aea409b151
diff --git a/ix-cli/src/cli/__tests__/context-investigation.test.ts b/ix-cli/src/cli/__tests__/context-investigation.test.ts
index b10e6737..0175072a 100644
--- a/ix-cli/src/cli/__tests__/context-investigation.test.ts
+++ b/ix-cli/src/cli/__tests__/context-investigation.test.ts
@@ -1,7 +1,7 @@
import { existsSync, mkdtempSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import type {
ConflictReport,
@@ -17,6 +17,8 @@ import {
diffInvestigations,
loadInvestigation,
mergeDiffOptions,
+ parseRequestedBudgets,
+ renderInvestigationDiff,
saveInvestigation,
} from "../commands/context.js";
@@ -265,4 +267,112 @@ describe("ix context investigation state", () => {
expect(existsSync(join(home, "..", "escape.json"))).toBe(false);
expect(existsSync(join(home, ".version-check.json"))).toBe(false);
});
+
+ it("exposes effective budgets on every --diff diff, sourced from the saved investigation", () => {
+ // The reproduction in B-4 showed that --max-* flags on the CLI do not change
+ // the fresh side's budget: buildFreshBundle always receives saved.bundle.budgets.
+ // The transparency fix surfaces that fact as data instead of hiding it, so
+ // agents reading the diff JSON can answer "what budget governed this comparison"
+ // without reading the source.
+ const saved = bundleWith([makeClaim("renders to DOM", 0.9)]);
+ saved.budgets = { maxEntities: 5, maxRelationships: 1, maxEvidence: 2, maxChars: 12000 };
+ saveInvestigation("widget-check", saved);
+ const stored = loadInvestigation("widget-check")!;
+ const fresh = bundleWith([makeClaim("renders to DOM", 0.9)]);
+
+ // Without CLI overrides, requested is absent and effective mirrors saved.
+ const baselineDiff = diffInvestigations(stored, fresh);
+ expect(baselineDiff.budgets.saved).toEqual({ maxEntities: 5, maxRelationships: 1, maxEvidence: 2, maxChars: 12000 });
+ expect(baselineDiff.budgets.requested).toBeUndefined();
+ expect(baselineDiff.budgets.effective).toEqual(baselineDiff.budgets.saved);
+ expect(baselineDiff.budgets.note).toMatch(/no --max-\* overrides/i);
+
+ // With CLI overrides parsed from raw commander strings, requested captures
+ // every flag the user passed (even ones that disagree with saved), and the
+ // note makes the precedence explicit.
+ const requested = parseRequestedBudgets({ maxEntities: "50", maxEvidence: "25", maxRelationships: "100" });
+ expect(requested).toEqual({ maxEntities: 50, maxEvidence: 25, maxRelationships: 100 });
+
+ const overrideDiff = diffInvestigations(stored, fresh, requested);
+ expect(overrideDiff.budgets.requested).toEqual(requested);
+ // Critical invariant: the fresh bundle was still built with saved budgets,
+ // so effective is the saved snapshot, not the requested one.
+ expect(overrideDiff.budgets.effective).toEqual(overrideDiff.budgets.saved);
+ expect(overrideDiff.budgets.note).toMatch(/--max-\* flags on the CLI are recorded/i);
+ });
+
+ it("treats whitespace, empty, or non-numeric --max-* strings as not provided", () => {
+ // parseRequestedBudgets must mirror commander semantics: only flag-shaped
+ // arguments count as "user override", not noise from shell quoting or
+ // accidental empty strings. This is what stops the diff output from
+ // reporting a phantom override. Numeric "0" is a real override (someone
+ // asking for "0 entities" forces an empty bundle and is what they meant),
+ // so it survives the parse — but non-strings, blanks, and NaN-producing
+ // tokens do not.
+ expect(parseRequestedBudgets({})).toBeUndefined();
+ expect(parseRequestedBudgets({ maxEntities: "", maxEvidence: " " })).toBeUndefined();
+ expect(parseRequestedBudgets({ maxEntities: undefined })).toBeUndefined();
+ expect(parseRequestedBudgets({ maxEntities: "abc" })).toBeUndefined();
+ expect(parseRequestedBudgets({ maxEntities: "0" })).toEqual({ maxEntities: 0 });
+ expect(parseRequestedBudgets({ maxEntities: "10", maxChars: undefined })).toEqual({ maxEntities: 10 });
+ const partial = parseRequestedBudgets({ maxEntities: "10", maxEvidence: "5", maxRelationships: "0", maxChars: "12000" });
+ expect(partial).toEqual({ maxEntities: 10, maxEvidence: 5, maxRelationships: 0, maxChars: 12000 });
+ });
+
+ it("renders the budget block in --diff text and llm output", () => {
+ // Spy on console.log so we can assert exactly what humans and LLMs see.
+ // This is the regression guard for the user-visible transparency: if a
+ // future refactor flattens renderInvestigationDiff back to "entities/-
+ // +", the budget block disappears and the silent ignore comes back.
+ const saved = bundleWith([makeClaim("renders to DOM", 0.9)]);
+ saved.budgets = { maxEntities: 5, maxRelationships: 1, maxEvidence: 2, maxChars: 12000 };
+ saveInvestigation("widget-check", saved);
+ const stored = loadInvestigation("widget-check")!;
+ const fresh = bundleWith([makeClaim("renders to DOM", 0.9)]);
+ const requested = { maxEvidence: 25 };
+
+ const capture = () => {
+ const lines: string[] = [];
+ const spy = vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+ lines.push(args.map((a) => String(a)).join(" "));
+ });
+ return { lines, restore: () => spy.mockRestore() };
+ };
+
+ const text = capture();
+ try {
+ renderInvestigationDiff(stored, fresh, "text", requested);
+ } finally {
+ text.restore();
+ }
+ expect(text.lines.some((l) => l.includes("budgets:"))).toBe(true);
+ expect(text.lines.some((l) => l.includes("saved :"))).toBe(true);
+ expect(text.lines.some((l) => l.includes("requested :")) && text.lines.some((l) => l.includes("evidence=25"))).toBe(true);
+ expect(text.lines.some((l) => l.includes("effective :") && l.includes("evidence=2"))).toBe(true);
+
+ const llm = capture();
+ try {
+ renderInvestigationDiff(stored, fresh, "llm", requested);
+ } finally {
+ llm.restore();
+ }
+ expect(llm.lines.some((l) => l.trim() === "budgets")).toBe(true);
+ expect(llm.lines.some((l) => l.includes("saved :") && l.includes("evidence=2"))).toBe(true);
+ expect(llm.lines.some((l) => l.includes("requested :") && l.includes("evidence=25"))).toBe(true);
+ expect(llm.lines.some((l) => l.includes("effective :") && l.includes("evidence=2"))).toBe(true);
+
+ // json format must already cover this branch in diffInvestigations itself,
+ // but assert here that the path is wired and the renderer doesn't double-print.
+ const json = capture();
+ try {
+ renderInvestigationDiff(stored, fresh, "json", requested);
+ } finally {
+ json.restore();
+ }
+ expect(json.lines).toHaveLength(1);
+ const parsed = JSON.parse(json.lines[0].replace(/^undefined$/, ""));
+ expect(parsed.budgets.saved).toEqual(saved.budgets);
+ expect(parsed.budgets.requested).toEqual(requested);
+ expect(parsed.budgets.effective).toEqual(saved.budgets);
+ });
});
diff --git a/ix-cli/src/cli/commands/context.ts b/ix-cli/src/cli/commands/context.ts
index 5d868db9..4879ea3c 100644
--- a/ix-cli/src/cli/commands/context.ts
+++ b/ix-cli/src/cli/commands/context.ts
@@ -123,10 +123,14 @@ export function registerContextCommand(program: Command): void {
.option("--pick <n>", "Pick Nth candidate from ambiguous results (1-based)", parsePickOption)
.option("--depth <depth>", "Context-graph expansion depth")
.option("--as-of-rev <n>", "Historical context as of a graph revision")
- .option("--max-entities <n>", "Maximum entities in the bundle", "50")
- .option("--max-relationships <n>", "Maximum relationships in the bundle", "100")
- .option("--max-evidence <n>", "Maximum evidence items in the bundle", "25")
- .option("--max-chars <n>", "Maximum characters of evidence output", "12000")
+ // The --max-* flags default to undefined rather than "50"/"100"/etc. so
+ // parseRequestedBudgets can tell whether the user actually supplied an
+ // override on the command line. The numeric defaults are still applied at
+ // build time via clampInt(opts.max*, 1, 500, 50).
+ .option("--max-entities <n>", "Maximum entities in the bundle")
+ .option("--max-relationships <n>", "Maximum relationships in the bundle")
+ .option("--max-evidence <n>", "Maximum evidence items in the bundle")
+ .option("--max-chars <n>", "Maximum characters of evidence output")
.option("--format <fmt>", "Output format (text|json|llm)", "text")
.option("--out <path>", "Write the JSON bundle to this file instead of stdout")
.option("--save <id>", "Persist the bundle as a resumable investigation state")
@@ -144,13 +148,19 @@ export function registerContextCommand(program: Command): void {
if (opts.diff) {
const saved = loadInvestigation(opts.diff);
if (!saved) return;
+ // The fresh side of --diff is currently built with the saved investigation's
+ // own budgets (ix-cli/src/cli/commands/context.ts: `buildFreshBundle(..., saved.bundle.budgets)`),
+ // so any --max-* flags the user passes on the CLI are not applied to the
+ // fresh bundle. We capture the requested values separately so the diff output
+ // can surface them to humans and agents instead of silently dropping them.
+ const requestedBudgets = parseRequestedBudgets(opts);
const fresh = await buildFreshBundle(
target ?? saved.bundle.target.name,
{ ...opts, ...mergeDiffOptions(saved, opts) },
saved.bundle.budgets,
);
if (!fresh) return;
- renderInvestigationDiff(saved, fresh, opts.format);
+ renderInvestigationDiff(saved, fresh, opts.format, requestedBudgets);
return;
}
if (!target) {
@@ -390,7 +400,51 @@ function renderSavedInvestigation(id: string, format: string): void {
renderBundle(saved.bundle, format);
}
-export function diffInvestigations(saved: SavedInvestigation, fresh: ContextBundle): InvestigationDiff {
+interface BudgetSnapshot {
+ maxEntities: number;
+ maxRelationships: number;
+ maxEvidence: number;
+ maxChars: number;
+}
+
+/** Compact one-line representation of a budget snapshot for human rendering. */
+function formatBudgets(b: Partial<BudgetSnapshot>, partial = false): string {
+ const fmt = (val: number | undefined, key: string): string =>
+ `${key}=${val === undefined ? "not-given" : String(val)}`;
+ const segments = [
+ fmt(b.maxEntities, "entities"),
+ fmt(b.maxRelationships, "relationships"),
+ fmt(b.maxEvidence, "evidence"),
+ fmt(b.maxChars, "chars"),
+ ].join(" ");
+ return partial ? `${segments} (CLI override; not applied to --diff fresh side)` : segments;
+}
+
+/**
+ * Apply the same clamping rules the action handler uses for direct --save runs
+ * to a budget object parsed from raw commander string values. Treats an absent
+ * or whitespace-only string as "user did not pass this flag".
+ */
+export function parseRequestedBudgets(opts: Partial<ContextOptions>): Partial<BudgetSnapshot> | undefined {
+ const fields: Array<keyof BudgetSnapshot> = ["maxEntities", "maxRelationships", "maxEvidence", "maxChars"];
+ const out: Partial<BudgetSnapshot> = {};
+ let provided = false;
+ for (const key of fields) {
+ const raw = opts[key] as string | undefined;
+ if (typeof raw !== "string" || raw.trim() === "") continue;
+ const parsed = Number.parseInt(raw, 10);
+ if (!Number.isFinite(parsed)) continue;
+ out[key] = parsed;
+ provided = true;
+ }
+ return provided ? out : undefined;
+}
+
+export function diffInvestigations(
+ saved: SavedInvestigation,
+ fresh: ContextBundle,
+ requestedBudgets?: Partial<BudgetSnapshot>,
+): InvestigationDiff {
const prev = saved.bundle;
const addedEntities = fresh.entities.filter((e) => !prev.entities.some((p) => p.id === e.id));
const removedEntities = prev.entities.filter((p) => !fresh.entities.some((e) => e.id === p.id));
@@ -405,6 +459,12 @@ export function diffInvestigations(saved: SavedInvestigation, fresh: ContextBund
const addedClaims = fresh.claims.filter((c) => !prev.claims.some((p) => p.id === c.id));
const removedClaims = prev.claims.filter((p) => !fresh.claims.some((c) => c.id === p.id));
+ // Surface the silent "saved budgets govern --diff" precedence as data instead
+ // of hiding it. Today `effective` always equals `saved`; if a future change
+ // ever lets CLI overrides win on the fresh side, this block is the single
+ // place that flips and the diff output is the only observable truth.
+ const effective: BudgetSnapshot = { ...saved.bundle.budgets };
+
return {
schema: "ix-investigation-diff/1",
investigation: saved.id,
@@ -412,6 +472,17 @@ export function diffInvestigations(saved: SavedInvestigation, fresh: ContextBund
generatedAt: new Date().toISOString(),
target: fresh.target,
freshness: { previous: prev.freshness, current: fresh.freshness },
+ budgets: {
+ saved: saved.bundle.budgets,
+ requested: requestedBudgets,
+ effective,
+ // The note exists so an agent reading the JSON alone can tell why a
+ // --max-* flag it passed on the CLI did not change the comparison
+ // footprint, without having to read source to find the precedence rule.
+ note: requestedBudgets
+ ? "Saved investigation budgets govern --diff; --max-* flags on the CLI are recorded above for transparency but not applied to the fresh side."
+ : "Saved investigation budgets govern --diff; no --max-* overrides were supplied on the CLI.",
+ },
added: {
entities: addedEntities,
relationships: addedRelationships,
@@ -434,13 +505,24 @@ interface InvestigationDiff {
generatedAt: string;
target: ContextBundle["target"];
freshness: { previous: ContextBundle["freshness"]; current: ContextBundle["freshness"] };
+ budgets: {
+ saved: BudgetSnapshot;
+ requested?: Partial<BudgetSnapshot>;
+ effective: BudgetSnapshot;
+ note: string;
+ };
added: { entities: ContextBundle["entities"]; relationships: ContextBundle["relationships"]; evidence: EvidenceItem[]; claims: ContextBundle["claims"] };
removed: { entities: ContextBundle["entities"]; relationships: ContextBundle["relationships"]; evidence: EvidenceItem[]; claims: ContextBundle["claims"] };
}
-function renderInvestigationDiff(saved: SavedInvestigation, fresh: ContextBundle, format: string): void {
+export function renderInvestigationDiff(
+ saved: SavedInvestigation,
+ fresh: ContextBundle,
+ format: string,
+ requestedBudgets?: Partial<BudgetSnapshot>,
+): void {
const prev = saved.bundle;
- const diff = diffInvestigations(saved, fresh);
+ const diff = diffInvestigations(saved, fresh, requestedBudgets);
if (format === "json") {
console.log(JSON.stringify(diff, null, 2));
@@ -449,6 +531,26 @@ function renderInvestigationDiff(saved: SavedInvestigation, fresh: ContextBundle
renderSection(`Investigation diff: ${saved.id}`);
console.log(` freshness: ${prev.freshness.classification} -> ${fresh.freshness.classification}`);
+ if (format === "llm") {
+ console.log(` budgets`);
+ console.log(` saved : ${formatBudgets(diff.budgets.saved)}`);
+ if (diff.budgets.requested) {
+ console.log(` requested : ${formatBudgets(diff.budgets.requested as BudgetSnapshot, true)}`);
+ } else {
+ console.log(` requested : (none — no --max-* flags passed)`);
+ }
+ console.log(` effective : ${formatBudgets(diff.budgets.effective)}`);
+ console.log(` note : ${diff.budgets.note}`);
+ } else {
+ console.log(` budgets:`);
+ console.log(` saved : ${formatBudgets(diff.budgets.saved)}`);
+ if (diff.budgets.requested) {
+ console.log(` requested : ${formatBudgets(diff.budgets.requested as BudgetSnapshot, true)}`);
+ } else {
+ console.log(` requested : (none)`);
+ }
+ console.log(` effective : ${formatBudgets(diff.budgets.effective)}`);
+ }
console.log(` entities: -${diff.removed.entities.length} +${diff.added.entities.length}`);
console.log(` relationships: -${diff.removed.relationships.length} +${diff.added.relationships.length}`);
console.log(` evidence: -${diff.removed.evidence.length} +${diff.added.evidence.length}`);