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
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.tsindex 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.tsindex 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: ContextBundconst 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: ContextBundgeneratedAt: 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: ContextBundlerenderSection(`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}`);