Skip to content

armgit / Ix

Public Imported from GitHub
0

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

Merge #456's llm records, and make the budget block records too

KageBinary401b8bd1ff76
diff --cc ix-cli/src/cli/__tests__/context-investigation.test.ts
index 0175072a,98dbe151..89234100
--- a/ix-cli/src/cli/__tests__/context-investigation.test.ts
+++ b/ix-cli/src/cli/__tests__/context-investigation.test.ts
@@@ -268,111 -267,141 +268,253 @@@ describe("ix context investigation stat
expect(existsSync(join(home, ".version-check.json"))).toBe(false);
});
- // `--diff --format llm` used to fall through to the prose renderer (the
- // diff path only branched on `json`). The llm branch mirrors `renderBundle`'s
- // contract: counts always emitted, items prefixed with `+`/`-` so the wire
- // format stays one-record-per-line. These tests pin that.
+ 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);
++ // Records, not the prose block with the colons moved. `scope=requested`
++ // carries `applied=false` so the precedence rule — saved budgets govern
++ // --diff — is a field an agent can test rather than a sentence to read.
++ expect(llm.lines).toContain("budgets scope=saved entities=5 relationships=1 evidence=2 chars=12000");
++ expect(llm.lines).toContain("budgets scope=requested evidence=25 applied=false");
++ expect(llm.lines).toContain("budgets scope=effective entities=5 relationships=1 evidence=2 chars=12000");
++ // And none of the prose survives into the record stream.
++ expect(llm.lines.some((l) => l.includes(":") && l.startsWith(" "))).toBe(false);
+
+ // 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$/, ""));
++ const parsed = JSON.parse(json.lines[0]);
+ expect(parsed.budgets.saved).toEqual(saved.budgets);
+ expect(parsed.budgets.requested).toEqual(requested);
+ expect(parsed.budgets.effective).toEqual(saved.budgets);
+ });
++
++ // `--diff --format llm` used to fall through to the prose renderer, because
++ // the diff path only branched on `json`. The llm branch emits records built
++ // by `llmLine`, so a value carrying a space is quoted rather than splitting
++ // the record. These tests pin that.
+ describe("--format llm rendering", () => {
+ function captureLog(fn: () => void): string[] {
+ const lines: string[] = [];
+ const orig = console.log;
+ console.log = (...args: unknown[]) => {
+ for (const arg of args) lines.push(String(arg));
+ };
+ try {
+ fn();
+ } finally {
+ console.log = orig;
+ }
+ return lines;
+ }
+
+ it("emits a header and counts for an empty diff without falling back to prose", () => {
+ const saved = bundleWith([makeClaim("renders to DOM", 0.9)]);
+ saveInvestigation("widget-llm", saved);
+ const stored = loadInvestigation("widget-llm")!;
+ const fresh = bundleWith([makeClaim("renders to DOM", 0.9)]);
+
+ const lines = captureLog(() => renderInvestigationDiff(stored, fresh, "llm"));
+
+ expect(lines[0]).toBe(
+ "diff investigation=widget-llm target=Widget freshness_previous=current freshness_current=current",
+ );
+ // Zero is the answer to the question --diff was asked, so it is carried
+ // rather than dropped as a default.
- expect(lines[1]).toBe(
++ expect(lines).toContain(
+ "count added_entities=0 removed_entities=0 added_relationships=0 removed_relationships=0" +
+ " added_evidence=0 removed_evidence=0 added_claims=0 removed_claims=0",
+ );
+ // No `renderSection` lines means we did not fall back to prose.
+ expect(lines.some((l) => l.startsWith("==") || l.startsWith(" "))).toBe(false);
+ });
+
+ it("lists added and removed entities, relationships, evidence and claims", () => {
+ const saved = bundleWith([makeClaim("renders to DOM", 0.9)]);
+ saveInvestigation("widget-llm-busy", saved);
+ const stored = loadInvestigation("widget-llm-busy")!;
+
+ const fresh = buildBundle({
+ resolved: { id: "entity-1", name: "Widget", kind: "class", resolutionMode: "exact" },
+ facts: makeFacts(),
+ context: makeContext({
+ claims: [makeClaim("renders to DOM", 0.9), makeClaim("mounts to DOM", 0.7)],
+ nodes: [
+ {
+ id: "entity-2",
+ kind: "method",
+ name: "render",
+ attrs: {},
+ provenance: { sourceUri: "src/widget.ts", extractor: "tree-sitter", sourceType: "source", observedAt: "2026-01-01T00:00:00Z" },
+ createdRev: 1,
+ createdAt: "2026-01-01T00:00:00Z",
+ updatedAt: "2026-01-01T00:00:00Z",
+ },
+ {
+ id: "entity-3",
+ kind: "method",
+ name: "mount",
+ attrs: {},
+ provenance: { sourceUri: "src/widget.ts", extractor: "tree-sitter", sourceType: "source", observedAt: "2026-01-01T00:00:00Z" },
+ createdRev: 2,
+ createdAt: "2026-01-01T00:00:00Z",
+ updatedAt: "2026-01-01T00:00:00Z",
+ },
+ ],
+ // Fresh side replaces the saved `calls` edge with `holds` — so the
+ // diff sees a removed relationship (calls) and an added one (holds),
+ // matching what an agent would observe when a refactor renames a
+ // graph predicate.
+ edges: [
+ { id: "edge-add", src: "entity-1", dst: "entity-3", predicate: "holds", attrs: {}, createdRev: 2 },
+ ],
+ }),
+ provenance: { sourceType: "source", extractor: "tree-sitter", observedAt: "2026-01-01T00:00:00Z" },
+ asOfRev: undefined,
+ depth: undefined,
+ budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxChars: 12000 },
+ });
+
+ const lines = captureLog(() => renderInvestigationDiff(stored, fresh, "llm"));
+
+ // Counts match the deterministic diff structure. The fresh bundle adds
+ // a new claim (mounts to DOM) and replaces the `calls` evidence with a
+ // `holds` one, so it has 2 added evidence records and 1 removed — the
+ // skolem IDs are `claim:<claim_id>` and
+ // `relationship:<src>:<dst>:<predicate>`, so a stale predicate in the
+ // ranked evidence list yields a real added/removed pair.
- expect(lines[1]).toBe(
++ expect(lines).toContain(
+ "count added_entities=1 removed_entities=0 added_relationships=1 removed_relationships=1" +
+ " added_evidence=2 removed_evidence=1 added_claims=1 removed_claims=0",
+ );
+
+ // The change is a field, not a prefix fused to the record kind, so a
+ // consumer routing on `entity` matches both sides of the comparison.
+ expect(lines).toContain("entity change=added kind=method name=mount");
+ expect(lines).toContain("relationship change=removed src=entity-1 pred=calls dst=entity-2");
+ expect(lines).toContain("relationship change=added src=entity-1 pred=holds dst=entity-3");
+
+ // A claim id carries the statement, so it contains spaces — quoted, per
+ // docs/llm-format.md. Unquoted, `id=claim-mounts to DOM` is three tokens
+ // and a consumer reads the id as `claim-mounts`.
+ expect(lines).toContain('claim change=added id="claim-mounts to DOM" status=active');
+
+ // An evidence title is a sentence. Same rule, and the reason the value
+ // must never be built with a template literal.
+ expect(lines).toContain(
+ 'evidence change=added score=30 kind=relationship title="entity-1 --holds--> entity-3"',
+ );
+ expect(lines).toContain(
+ 'evidence change=removed score=30 kind=relationship title="entity-1 --calls--> entity-2"',
+ );
+
+ // One record per line — the wire format invariant.
+ for (const line of lines) expect(line).not.toContain("\n");
+ });
+
+ it("does not regress the prose (text) renderer", () => {
+ const saved = bundleWith([makeClaim("renders to DOM", 0.9)]);
+ saveInvestigation("widget-llm-text", saved);
+ const stored = loadInvestigation("widget-llm-text")!;
+ const fresh = bundleWith([makeClaim("renders to DOM", 0.9), makeClaim("mounts to DOM", 0.7)]);
+
+ const lines = captureLog(() => renderInvestigationDiff(stored, fresh, "text"));
+
+ // Prose path still emits its summary header and the `+N`/`-N` totals.
+ expect(lines.some((l) => l.includes("Investigation diff: widget-llm-text"))).toBe(true);
+ expect(lines.some((l) => /claims:\s+-\d+\s+\+\d+/.test(l))).toBe(true);
+ expect(lines.some((l) => /entities:\s+-\d+\s+\+\d+/.test(l))).toBe(true);
+ });
+ });
});
diff --cc ix-cli/src/cli/commands/context.ts
index 4879ea3c,8f42d65f..664e4254
--- a/ix-cli/src/cli/commands/context.ts
+++ b/ix-cli/src/cli/commands/context.ts
@@@ -400,51 -390,7 +400,72 @@@ function renderSavedInvestigation(id: s
renderBundle(saved.bundle, format);
}
-export function diffInvestigations(saved: SavedInvestigation, fresh: ContextBundle): InvestigationDiff {
+interface BudgetSnapshot {
+ maxEntities: number;
+ maxRelationships: number;
+ maxEvidence: number;
+ maxChars: number;
+}
+
++/**
++ * A budget snapshot as llm record fields.
++ *
++ * Absent values are simply absent — `llmField` drops nullish, so a partial
++ * override needs no `not-given` sentinel the way the prose form does.
++ */
++function budgetFields(b: Partial<BudgetSnapshot>): Record<string, number | undefined> {
++ return {
++ entities: b.maxEntities,
++ relationships: b.maxRelationships,
++ evidence: b.maxEvidence,
++ chars: b.maxChars,
++ };
++}
++
+/** 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".
++ * Read the raw `--max-*` strings commander collected into numbers.
++ *
++ * Deliberately *not* clamped, unlike the action handler's `clampInt` calls for
++ * a direct run: these values are reported, never applied — saved budgets
++ * govern `--diff` — so clamping them would misreport what the caller actually
++ * asked for. If they are ever made to win on the fresh side, they must be
++ * clamped at that point, and the ranges live in the handler.
++ *
++ * An absent or whitespace-only string means the flag was not passed.
+ */
+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));
@@@ -528,29 -446,55 +549,76 @@@ export function renderInvestigationDiff
console.log(JSON.stringify(diff, null, 2));
return;
}
+ if (format === "llm") {
+ // `ix context --diff --format llm` used to fall through to the prose
+ // renderer below, because this path only branched on `json`. That made the
+ // most common agent path the worst one: escaping the prose is what `llm`
+ // exists for.
+ //
+ // Every line goes through `llmLine`, never a template literal. The values
+ // here are the ones most likely to contain a space in the whole CLI — an
+ // evidence title is a sentence, and a claim id carries the statement — and
+ // `key=value` with an unquoted space is not a record a consumer can split.
+ // `llmQuote` also encodes newlines, so a title cannot break the one
+ // record per line invariant.
+ printLlmLines([
+ llmLine("diff", {
+ investigation: saved.id,
+ target: fresh.target.name,
+ freshness_previous: prev.freshness.classification,
+ freshness_current: fresh.freshness.classification,
+ }),
++ // Which budgets governed the comparison. `scope=requested` appears
++ // only when --max-* flags were passed, and carries `applied=false`
++ // rather than a sentence explaining itself: the precedence rule is
++ // that saved budgets govern --diff, and a field an agent can test
++ // beats a note it has to read.
++ llmLine("budgets", { scope: "saved", ...budgetFields(diff.budgets.saved) }),
++ ...(diff.budgets.requested
++ ? [llmLine("budgets", { scope: "requested", ...budgetFields(diff.budgets.requested), applied: false })]
++ : []),
++ llmLine("budgets", { scope: "effective", ...budgetFields(diff.budgets.effective) }),
+ // One record rather than eight, and the zeros are kept: "nothing was
+ // added" is the answer to the question `--diff` was asked, so dropping
+ // it as a default would remove the signal.
+ llmLine("count", {
+ added_entities: diff.added.entities.length,
+ removed_entities: diff.removed.entities.length,
+ added_relationships: diff.added.relationships.length,
+ removed_relationships: diff.removed.relationships.length,
+ added_evidence: diff.added.evidence.length,
+ removed_evidence: diff.removed.evidence.length,
+ added_claims: diff.added.claims.length,
+ removed_claims: diff.removed.claims.length,
+ }),
+ // `change=` rather than a `+`/`-` prefix on the record kind: a consumer
+ // routing on the kind should still match `entity` on both sides of the
+ // comparison, and a fused marker means it matches neither.
+ ...diff.added.entities.map((e) => llmLine("entity", { change: "added", kind: e.kind, name: e.name })),
+ ...diff.removed.entities.map((e) => llmLine("entity", { change: "removed", kind: e.kind, name: e.name })),
+ ...diff.added.relationships.map((r) => llmLine("relationship", { change: "added", src: r.src, pred: r.predicate, dst: r.dst })),
+ ...diff.removed.relationships.map((r) => llmLine("relationship", { change: "removed", src: r.src, pred: r.predicate, dst: r.dst })),
+ ...diff.added.evidence.map((e) => llmLine("evidence", { change: "added", score: e.score, kind: e.kind, title: e.title })),
+ ...diff.removed.evidence.map((e) => llmLine("evidence", { change: "removed", score: e.score, kind: e.kind, title: e.title })),
+ ...diff.added.claims.map((c) => llmLine("claim", { change: "added", id: c.id, status: c.status })),
+ ...diff.removed.claims.map((c) => llmLine("claim", { change: "removed", id: c.id, status: c.status })),
+ ]);
+ return;
+ }
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}`);
++ // Prose only: `--format llm` returned above with records of its own. The
++ // llm branch here used to be this same block with the colons moved, which
++ // is the one thing the format is defined not to be.
++ console.log(` budgets:`);
++ console.log(` saved : ${formatBudgets(diff.budgets.saved)}`);
++ if (diff.budgets.requested) {
++ console.log(` requested : ${formatBudgets(diff.budgets.requested, true)}`);
+ } 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(` 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}`);