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 'fix/context-list-investigations' into fix/context-diff-budget-transparency
Joseph Mikhaild33141f6732e
diff --cc docs/llm-format.mdindex 51c7be06,b7e84c9a..998c35af--- a/docs/llm-format.md+++ b/docs/llm-format.md@@@ -83,21 -83,20 +83,35 @@@ contains method=12 field=item name=parseFile kind=method```+`ix context --diff <id>`:++```+diff investigation=widget target=Widget freshness_previous=current freshness_current=stale+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+entity change=added kind=method name=mount+relationship change=removed src=entity-1 pred=calls dst=entity-2+evidence change=added score=30 kind=relationship title="entity-1 --holds--> entity-3"+claim change=added id="claim-mounts to DOM" status=active+```++The counts keep their zeros: "nothing was added" is the answer `--diff` was+asked for, not a default worth dropping. Added and removed share one record+kind and separate on `change=`, so a consumer routing on `entity` sees both+sides of the comparison.+ `ix context --list`:++ ```+ investigations total=2 skipped=1+ investigation id=widget saved_at=2026-01-03T09:12:44.108Z target=Widget target_kind=class classification=current entities=12 relationships=20 evidence=8+ investigation id=auth-path saved_at=2026-01-02T17:03:11.882Z target=verify_token target_kind=function classification=stale stale=true entities=31 relationships=64 evidence=25 truncated_evidence=4+ ```++ `skipped` counts saved files that did not match the contract and is present+ only when it is non-zero — it is the one thing about a listing that cannot be+ seen from the records themselves. `id` is the id `--resume` and `--diff` take,+ not the file name on disk; the two differ whenever an id contains a character+ outside `[A-Za-z0-9._-]`. The counts describe each bundle; the bundles+ themselves are not in the listing, and `ix context --resume <id>` fetches one.Error line:diff --cc ix-cli/src/cli/__tests__/context-investigation.test.tsindex 00cd7608,fc6f492c..8fc58909--- a/ix-cli/src/cli/__tests__/context-investigation.test.ts+++ b/ix-cli/src/cli/__tests__/context-investigation.test.ts@@@ -15,10 -15,10 +15,12 @@@ import type { EntityFacts } from "../eximport {buildBundle,diffInvestigations,+ listInvestigations,+ renderInvestigationList,loadInvestigation,mergeDiffOptions,+ parseRequestedBudgets,+ renderInvestigationDiff,saveInvestigation,} from "../commands/context.js";@@@ -422,253 -422,189 +424,439 @@@ describe("ix context investigation statexpect(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();+ }+ // 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]);+ 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).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).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);+ });+ });+++ // `ix context --list` enumerates saved investigations for discovery.+ // Without it, neither humans nor agents can see what they have stored —+ // the only path was reading the JSON files directly.+ describe("listInvestigations", () => {+ /**+ * Run `fn` with stdout and stderr captured separately.+ *+ * One helper for the whole block, and multi-arg calls joined with a space+ * the way a terminal shows them: the two ad-hoc capturers this replaces+ * disagreed on that (one joined, one pushed each argument as its own line),+ * so identical output produced different arrays depending on which test you+ * happened to be reading.+ */+ const captureStreams = (fn: () => void) => {+ const out: string[] = [];+ const err: string[] = [];+ const origLog = console.log;+ const origErr = console.error;+ console.log = (...a: unknown[]) => void out.push(a.join(" "));+ console.error = (...a: unknown[]) => void err.push(a.join(" "));+ try {+ fn();+ } finally {+ console.log = origLog;+ console.error = origErr;+ }+ return { out: out.join("\n"), err: err.join("\n") };+ };++ /** Restamp a saved investigation's `savedAt`, leaving everything else alone. */+ const stampSavedAt = (id: string, savedAt: string) => {+ const path = join(investigationsDir(), `${id}.json`);+ const state = JSON.parse(readFileSync(path, "utf8"));+ writeFileSync(path, JSON.stringify({ ...state, savedAt }), "utf8");+ };++ it("returns saved investigations newest-first", () => {+ // The timestamps are set explicitly because `saveInvestigation` stamps+ // them from the clock and three writes inside one millisecond is the+ // ordinary case, not the rare one. The previous version of this test+ // asserted `saved[0].id === "widget-a" || saved[0].id === "widget-b"` and+ // called `.sort()` on the ids before comparing them, so it was true for+ // either order: inverting the comparator left every assertion green and+ // ordering — the function's whole stated purpose — had no coverage.+ saveInvestigation("widget-a", bundleWith([makeClaim("renders to DOM", 0.9)]));+ saveInvestigation("widget-b", bundleWith([makeClaim("mounts to DOM", 0.7)]));+ saveInvestigation("widget-c", bundleWith([makeClaim("unmounts cleanly", 0.5)]));+ stampSavedAt("widget-a", "2026-01-02T00:00:00.000Z");+ stampSavedAt("widget-b", "2026-01-03T00:00:00.000Z");+ stampSavedAt("widget-c", "2026-01-01T00:00:00.000Z");++ const list = listInvestigations();+ expect(list.saved.map((s) => s.id)).toEqual(["widget-b", "widget-a", "widget-c"]);+ expect(list.skipped).toBe(0);+ });++ it("breaks a same-millisecond tie on the id, stably", () => {+ // The reason the comparator has a second clause at all: two saves in the+ // same millisecond must still come back in the same order every run.+ for (const id of ["widget-c", "widget-a", "widget-b"]) {+ saveInvestigation(id, bundleWith([makeClaim("renders to DOM", 0.9)]));+ stampSavedAt(id, "2026-01-01T00:00:00.000Z");+ }+ expect(listInvestigations().saved.map((s) => s.id)).toEqual([+ "widget-a",+ "widget-b",+ "widget-c",+ ]);+ });++ it("lists an id that --resume can actually take back", () => {+ // `sanitizeId` is injective and deliberately not idempotent — it encodes+ // `~` as `~7E` so a raw `~` cannot be mistaken for an escape — so the id+ // stored on disk is the wrong thing to print next to "Resume with:".+ // `widget/auth` was saved as `widget~2Fauth` and listed as that, and+ // resuming it looked for `widget~7E2Fauth`, which does not exist.+ saveInvestigation("widget/auth", bundleWith([makeClaim("renders to DOM", 0.9)]));+ const [only] = listInvestigations().saved;+ expect(only.id).toBe("widget~2Fauth"); // on disk, as stored++ const { out } = captureStreams(() => renderInvestigationList([only], 0, "json"));+ const listed = JSON.parse(out).investigations[0].id;+ expect(listed).toBe("widget/auth");+ // The whole point: the id the listing offers has to load.+ expect(loadInvestigation(listed)?.bundle.target.name).toBe("Widget");+ });++ it("skips files whose envelope or bundle does not match the contract", () => {+ saveInvestigation("good", bundleWith([makeClaim("renders to DOM", 0.9)]));+ const dir = investigationsDir();+ writeFileSync(join(dir, "corrupt-envelope.json"), JSON.stringify({ schema: "ix-investigation/9", bundle: {} }));+ writeFileSync(join(dir, "truncated.json"), "{not json");+ writeFileSync(join(dir, "tampered-body.json"), JSON.stringify({+ schema: "ix-investigation/1",+ id: "tampered-body",+ savedAt: "2026-01-01T00:00:00Z",+ bundle: { schema: "ix-context-bundle/1", generatedAt: "x", entities: "not-an-array" },+ }));+ writeFileSync(join(dir, "readme.md"), "not a state file");++ const list = listInvestigations();+ expect(list.saved.map((s) => s.id)).toEqual(["good"]);+ // Counted and handed back, not printed: the enumerator runs before the+ // renderer knows whether the caller asked for JSON.+ expect(list.skipped).toBe(3);+ // The three corrupt files do not poison the listing.+ expect(readdirSync(dir).filter((f) => f.endsWith(".json"))).toHaveLength(4);+ });++ it("returns an empty listing when the investigations dir does not exist yet", () => {+ expect(listInvestigations()).toEqual({ saved: [], skipped: 0 });+ saveInvestigation("first", bundleWith([makeClaim("renders to DOM", 0.9)]));+ expect(listInvestigations().saved).toHaveLength(1);+ });++ it("keeps the skip report off stdout in every machine format", () => {+ // json must stay parseable and llm must stay records, so the human+ // warning goes to stderr and the machine formats carry a count instead.+ saveInvestigation("good", bundleWith([makeClaim("renders to DOM", 0.9)]));+ const { saved } = listInvestigations();++ const json = captureStreams(() => renderInvestigationList(saved, 3, "json"));+ expect(() => JSON.parse(json.out)).not.toThrow();+ const parsed = JSON.parse(json.out);+ expect(parsed.investigations).toHaveLength(1);+ // An array had nowhere to put this, so a machine caller could not tell+ // three files had been rejected while the human saw a warning saying so.+ expect(parsed.skipped).toBe(3);+ expect(json.err).toContain("3 saved investigation file(s)");++ const llm = captureStreams(() => renderInvestigationList(saved, 3, "llm"));+ expect(llm.out.split("\n")[0]).toBe("investigations total=1 skipped=3");+ // The count is the record's business; nothing is written beside it.+ expect(llm.err).toBe("");++ // And with nothing skipped the field is simply absent.+ const clean = captureStreams(() => renderInvestigationList(saved, 0, "llm"));+ expect(clean.out.split("\n")[0]).toBe("investigations total=1");+ expect(clean.err).toBe("");+ // `skipped` is still there in json, as a zero rather than as nothing:+ // "none were rejected" is an answer, and its absence is not.+ const cleanJson = captureStreams(() => renderInvestigationList(saved, 0, "json"));+ expect(JSON.parse(cleanJson.out).skipped).toBe(0);+ });++ it("returns a summary per investigation, not the bundles themselves", () => {+ // `--list` is the discovery step. Twenty saved investigations is twenty+ // complete bundles — up to 50 entities, 100 relationships and 12000+ // characters of evidence each — and a caller that wants one of them asks+ // for it by id with `--resume <id> --format json`.+ saveInvestigation("widget", bundleWith([makeClaim("renders to DOM", 0.9)]));+ const { saved } = listInvestigations();+ expect(saved[0].bundle.evidence.length).toBeGreaterThan(0);++ const { out } = captureStreams(() => renderInvestigationList(saved, 0, "json"));+ const [item] = JSON.parse(out).investigations;+ expect(Object.keys(item).sort()).toEqual(+ ["counts", "freshness", "id", "savedAt", "target", "truncation"].sort(),+ );+ expect(item.counts.evidence).toBe(saved[0].bundle.evidence.length);+ expect(out).not.toContain("renders to DOM");+ });++ it("prints nothing itself, whatever it finds", () => {+ // The defect this replaces: the warning was a `renderWarning` inside the+ // enumerator, and every renderer in ui.ts writes to stdout. One corrupt+ // file therefore prepended a chalk-coloured prose line to the payload,+ // and `ix context --list --format json | jq` failed on it.+ saveInvestigation("good", bundleWith([makeClaim("renders to DOM", 0.9)]));+ writeFileSync(join(investigationsDir(), "truncated.json"), "{not json");++ const lines: string[] = [];+ const origLog = console.log;+ const origErr = console.error;+ console.log = (...a: unknown[]) => void lines.push(a.join(" "));+ console.error = (...a: unknown[]) => void lines.push(a.join(" "));+ try {+ listInvestigations();+ } finally {+ console.log = origLog;+ console.error = origErr;+ }+ expect(lines).toEqual([]);+ });+ });});