Skip to content

armgit / Ix

Public Imported from GitHub
0

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

fix(context): put the diff's llm records through the format's own writer

KageBinarye8b2a8719a54
diff --git a/docs/llm-format.md b/docs/llm-format.md
index 7a2808e5..51c7be06 100644
--- a/docs/llm-format.md
+++ b/docs/llm-format.md
@@ -83,6 +83,22 @@ contains method=12 field=4
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.
+
Error line:
```
diff --git a/ix-cli/src/cli/__tests__/context-investigation.test.ts b/ix-cli/src/cli/__tests__/context-investigation.test.ts
index eb40afa2..98dbe151 100644
--- a/ix-cli/src/cli/__tests__/context-investigation.test.ts
+++ b/ix-cli/src/cli/__tests__/context-investigation.test.ts
@@ -294,22 +294,20 @@ describe("ix context investigation state", () => {
const lines = captureLog(() => renderInvestigationDiff(stored, fresh, "llm"));
- expect(lines[0]).toBe("diff investigation=widget-llm target=Widget");
- expect(lines).toContain("freshness_previous=current");
- expect(lines).toContain("freshness_current=current");
- expect(lines).toContain("count added_entities=0");
- expect(lines).toContain("count removed_entities=0");
- expect(lines).toContain("count added_relationships=0");
- expect(lines).toContain("count removed_relationships=0");
- expect(lines).toContain("count added_evidence=0");
- expect(lines).toContain("count removed_evidence=0");
- expect(lines).toContain("count added_claims=0");
- expect(lines).toContain("count removed_claims=0");
+ 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(
+ "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/removed entities, relationships, evidence and claims with +/- prefixes", () => {
+ 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")!;
@@ -363,36 +361,30 @@ describe("ix context investigation state", () => {
// 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");
- expect(lines).toContain("count removed_entities=0");
- expect(lines).toContain("count added_relationships=1");
- expect(lines).toContain("count removed_relationships=1");
- expect(lines).toContain("count added_evidence=2");
- expect(lines).toContain("count removed_evidence=1");
- expect(lines).toContain("count added_claims=1");
- expect(lines).toContain("count removed_claims=0");
-
- // Items tagged with +/- so an agent can route without parsing prose.
- expect(lines).toContain("+entity kind=method name=mount");
- expect(lines).toContain("-relationship src=entity-1 pred=calls dst=entity-2");
- expect(lines).toContain("+relationship src=entity-1 pred=holds dst=entity-3");
- expect(lines).toContain("+claim id=claim-mounts to DOM");
- expect(
- lines.some(
- (l) =>
- l.startsWith("+evidence ") &&
- l.includes("kind=relationship") &&
- l.includes("entity-1 --holds--> entity-3"),
- ),
- ).toBe(true);
- expect(
- lines.some(
- (l) =>
- l.startsWith("-evidence ") &&
- l.includes("kind=relationship") &&
- l.includes("entity-1 --calls--> entity-2"),
- ),
- ).toBe(true);
+ expect(lines[1]).toBe(
+ "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");
diff --git a/ix-cli/src/cli/commands/context.ts b/ix-cli/src/cli/commands/context.ts
index 6ac93751..8f42d65f 100644
--- a/ix-cli/src/cli/commands/context.ts
+++ b/ix-cli/src/cli/commands/context.ts
@@ -15,7 +15,7 @@ import type {
} from "../../client/types.js";
import { getEndpoint } from "../config.js";
import { collectFacts, type EntityFacts } from "../explain/facts.js";
-import { printLlmLines } from "../llm.js";
+import { llmLine, printLlmLines } from "../llm.js";
import { parsePickOption } from "../options.js";
import { resolveFileOrEntity } from "../resolve.js";
import { createStaleProbe } from "../stale.js";
@@ -447,32 +447,48 @@ export function renderInvestigationDiff(saved: SavedInvestigation, fresh: Contex
return;
}
if (format === "llm") {
- // `ix context --diff --format llm` previously fell through to the prose
- // renderer below because the diff path only branched on `json`. That made
- // the most common agent path (`--diff --format llm`) the worst one: the
- // prose scaling was the whole reason `llm` exists. Mirror `renderBundle`'s
- // llm branch and emit one record per line in the same `key=value` wire
- // format the rest of the CLI uses.
+ // `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([
- `diff investigation=${saved.id} target=${fresh.target.name}`,
- `freshness_previous=${prev.freshness.classification}`,
- `freshness_current=${fresh.freshness.classification}`,
- `count added_entities=${diff.added.entities.length}`,
- `count removed_entities=${diff.removed.entities.length}`,
- `count added_relationships=${diff.added.relationships.length}`,
- `count removed_relationships=${diff.removed.relationships.length}`,
- `count added_evidence=${diff.added.evidence.length}`,
- `count removed_evidence=${diff.removed.evidence.length}`,
- `count added_claims=${diff.added.claims.length}`,
- `count removed_claims=${diff.removed.claims.length}`,
- ...diff.added.entities.map((e) => `+entity kind=${e.kind} name=${e.name}`),
- ...diff.removed.entities.map((e) => `-entity kind=${e.kind} name=${e.name}`),
- ...diff.added.relationships.map((r) => `+relationship src=${r.src} pred=${r.predicate} dst=${r.dst}`),
- ...diff.removed.relationships.map((r) => `-relationship src=${r.src} pred=${r.predicate} dst=${r.dst}`),
- ...diff.added.evidence.map((e) => `+evidence score=${e.score} kind=${e.kind} title=${e.title.replaceAll("\n", " ")}`),
- ...diff.removed.evidence.map((e) => `-evidence score=${e.score} kind=${e.kind} title=${e.title.replaceAll("\n", " ")}`),
- ...diff.added.claims.map((c) => `+claim id=${(c as { id?: string }).id ?? ""}`),
- ...diff.removed.claims.map((c) => `-claim id=${(c as { id?: string }).id ?? ""}`),
+ llmLine("diff", {
+ investigation: saved.id,
+ target: fresh.target.name,
+ freshness_previous: prev.freshness.classification,
+ freshness_current: fresh.freshness.classification,
+ }),
+ // 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;
}