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): make --list refusals real and its ids resumable

Joseph Mikhail4000ba401aeb
diff --git a/docs/llm-format.md b/docs/llm-format.md
index 7a2808e5..b7e84c9a 100644
--- a/docs/llm-format.md
+++ b/docs/llm-format.md
@@ -83,6 +83,21 @@ contains method=12 field=4
item name=parseFile kind=method
```
+`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 --git a/ix-cli/src/cli/__tests__/context-investigation.test.ts b/ix-cli/src/cli/__tests__/context-investigation.test.ts
index 675a913d..fc6f492c 100644
--- a/ix-cli/src/cli/__tests__/context-investigation.test.ts
+++ b/ix-cli/src/cli/__tests__/context-investigation.test.ts
@@ -426,15 +426,87 @@ describe("ix context investigation state", () => {
// 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).sort()).toEqual(["widget-a", "widget-b"]);
+ expect(list.saved.map((s) => s.id)).toEqual(["widget-b", "widget-a", "widget-c"]);
expect(list.skipped).toBe(0);
- // savedAt differs at least by a millisecond across the two writes; even
- // on the rare same-ms tie the id tiebreaker keeps order deterministic.
- expect(list.saved[0].id === "widget-a" || list.saved[0].id === "widget-b").toBe(true);
+ });
+
+ 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", () => {
@@ -471,36 +543,46 @@ describe("ix context investigation state", () => {
saveInvestigation("good", bundleWith([makeClaim("renders to DOM", 0.9)]));
const { saved } = listInvestigations();
- const capture = (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") };
- };
-
- const json = capture(() => renderInvestigationList(saved, 3, "json"));
+ const json = captureStreams(() => renderInvestigationList(saved, 3, "json"));
expect(() => JSON.parse(json.out)).not.toThrow();
- expect(JSON.parse(json.out)).toHaveLength(1);
+ 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 = capture(() => renderInvestigationList(saved, 3, "llm"));
+ 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 = capture(() => renderInvestigationList(saved, 0, "llm"));
+ 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", () => {
diff --git a/ix-cli/src/cli/__tests__/context-mode-conflict.test.ts b/ix-cli/src/cli/__tests__/context-mode-conflict.test.ts
index 173cec87..89e2be9f 100644
--- a/ix-cli/src/cli/__tests__/context-mode-conflict.test.ts
+++ b/ix-cli/src/cli/__tests__/context-mode-conflict.test.ts
@@ -109,6 +109,34 @@ describe("detectContextModeConflict", () => {
expect(detectContextModeConflict({ resume: "x", ...other })).toMatch(/--resume/);
}
});
+
+ it("flags --list + --resume, which its own guard could never reach", () => {
+ // `--list`'s guard named `--resume`, but it sat below `if (opts.resume)`,
+ // which returns first. `ix context --list --resume widget` rendered one
+ // investigation, exited 0, and never said the listing had been dropped.
+ // Checked before any mode branch, that race cannot happen.
+ expect(detectContextModeConflict({ list: true, resume: "x" })).toMatch(
+ /--list and --resume cannot be combined/,
+ );
+ });
+
+ it("flags --list + --out, which nothing checked at all", () => {
+ // `ix context --list --out /tmp/list.json` listed to stdout, wrote no file,
+ // and exited 0 — the silent-ignore gap this detector exists to close, on
+ // the newest flag on the command it guards.
+ expect(detectContextModeConflict({ list: true, out: "/tmp/list.json" })).toMatch(
+ /--list cannot be combined with --out/,
+ );
+ });
+
+ it("flags a positional target alongside --list", () => {
+ // A positional is as ignorable as a flag: `ix context Widget --list`
+ // dropped the target with nothing said.
+ expect(detectContextModeConflict({ list: true }, "Widget")).toMatch(/--list takes no target/);
+ // …and a target without --list is the ordinary path.
+ expect(detectContextModeConflict({}, "Widget")).toBeUndefined();
+ expect(detectContextModeConflict({ list: true })).toBeUndefined();
+ });
});
describe("detectDiffModeConflict", () => {
@@ -173,7 +201,7 @@ describe("detectDiffModeConflict", () => {
*/
describe("mode-flag coverage does not drift from the command", () => {
/** Flags that select what the command does, or where its output goes. */
- const CONTEXT_MODE_FLAGS = ["out", "save", "resume", "diff"] as const;
+ const CONTEXT_MODE_FLAGS = ["out", "save", "resume", "diff", "list"] as const;
/** Flags that shape the bundle a mode produces; any pair of these is legal. */
const CONTEXT_BUILD_FLAGS = [
"kind", "path", "pick", "depth", "asOfRev",
@@ -276,6 +304,11 @@ describe("ix context action surfaces mode conflicts on stderr and exits 1", () =
{ args: ["context", "--diff", "x", "--save", "y"], expect: /--diff cannot be combined with --save/ },
{ args: ["context", "--diff", "x", "--out", "/tmp/x.json"], expect: /--diff cannot be combined with --out/ },
{ args: ["context", "--save", "y", "--out", "/tmp/x.json"], expect: /--save and --out cannot be combined/ },
+ { args: ["context", "--list", "--resume", "x"], expect: /--list and --resume cannot be combined/ },
+ { args: ["context", "--list", "--diff", "x"], expect: /--list and --diff cannot be combined/ },
+ { args: ["context", "--list", "--save", "y"], expect: /--list cannot be combined with --save/ },
+ { args: ["context", "--list", "--out", "/tmp/x.json"], expect: /--list cannot be combined with --out/ },
+ { args: ["context", "Widget", "--list"], expect: /--list takes no target/ },
])("ix $args → stderr matches $expect and exit code is 1", ({ args, expect: re }) => {
const r = runProgram(registerContextCommand, args);
expect(r.exitCode).toBe(1);
diff --git a/ix-cli/src/cli/commands/context.ts b/ix-cli/src/cli/commands/context.ts
index 5da4e3c3..9ef7fb2c 100644
--- a/ix-cli/src/cli/commands/context.ts
+++ b/ix-cli/src/cli/commands/context.ts
@@ -137,7 +137,7 @@ export function registerContextCommand(program: Command): void {
"\nExamples:\n ix context IngestionService\n ix context src/main.ts --format json\n ix context Widget --max-entities 20 --max-evidence 10\n ix context Widget --save widget-investigation\n ix context --resume widget-investigation\n ix context --diff widget-investigation\n ix context --list",
)
.action(async (target: string | undefined, opts: ContextOptions) => {
- const conflict = detectContextModeConflict(opts);
+ const conflict = detectContextModeConflict(opts, target);
if (conflict) {
reportModeConflict(conflict, opts.format);
return;
@@ -147,14 +147,9 @@ export function registerContextCommand(program: Command): void {
return;
}
if (opts.list) {
- if (opts.save || opts.diff || opts.resume) {
- // A refusal exits non-zero, the way `refuseInvestigation` does two
- // functions down and the way the sibling commands do: a warning with
- // a success status tells a script the listing it never got was fine.
- renderWarning("--list cannot be combined with --save, --diff or --resume.");
- process.exitCode = 1;
- return;
- }
+ // No guard of its own: every combination it used to check is refused
+ // above, before any mode branch can return first. The old one lived
+ // here, below `if (opts.resume)`, so its `--resume` arm was dead.
const listed = listInvestigations();
renderInvestigationList(listed.saved, listed.skipped, opts.format);
return;
@@ -297,7 +292,7 @@ async function buildFreshBundle(
* without inventing a `format`.
*/
export type ContextModeOptions = Partial<
- Pick<ContextOptions, "resume" | "diff" | "save" | "out" | "format">
+ Pick<ContextOptions, "resume" | "diff" | "save" | "out" | "list" | "format">
>;
/**
@@ -311,10 +306,37 @@ export type ContextModeOptions = Partial<
* well-defined combined behaviour. Catching these combinations up front and
* surfacing them as a hard error mirrors the explicit-conflict style in
* subsystems.ts and prevents the user's typed flag from being a no-op.
+ *
+ * `--list` is checked here rather than inside the list branch, and that is the
+ * point rather than tidiness. Its own guard sat below `if (opts.resume)`, which
+ * returns first, so the `--list --resume` arm of it could never fire: the user
+ * asked for a listing, silently got one investigation rendered, and the exit
+ * code said it went fine. A guard that runs before every mode branch cannot
+ * lose that race.
+ *
+ * `target` is a parameter because a positional is as ignorable as a flag:
+ * `ix context Widget --list` dropped the target with nothing said.
*/
export function detectContextModeConflict(
opts: ContextModeOptions,
+ target?: string,
): string | undefined {
+ if (opts.list && target) {
+ return `--list takes no target; it enumerates every saved investigation. Drop "${target}", or drop --list to build a fresh bundle for it.`;
+ }
+ if (opts.list && opts.resume) {
+ return "--list and --resume cannot be combined; --list enumerates saved investigations, --resume renders one. Run --list first, then --resume the id you want.";
+ }
+ if (opts.list && opts.diff) {
+ return "--list and --diff cannot be combined; --list enumerates saved investigations, --diff compares one against a fresh build.";
+ }
+ if (opts.list && opts.save) {
+ return "--list cannot be combined with --save; --list reads saved investigations, --save writes one, and --list builds no bundle to write.";
+ }
+ if (opts.list && opts.out) {
+ return "--list cannot be combined with --out; --list enumerates to stdout."
+ + " Redirect it (`ix context --list --format json > <path>`) if you need the listing on disk.";
+ }
if (opts.resume && opts.diff) {
return "--resume and --diff cannot be combined; --resume renders a saved investigation, --diff renders a comparison against one.";
}
@@ -381,6 +403,29 @@ export function sanitizeId(id: string): string {
return out || "unnamed";
}
+/**
+ * Recover the id the user typed from the id stored on disk.
+ *
+ * `sanitizeId` is injective and deliberately *not* idempotent — it encodes `~`
+ * as `~7E` precisely so a raw `~` cannot be confused with an escape — so the
+ * stored form is the wrong thing to hand back to the user. `ix context --list`
+ * printed it anyway, next to "Resume with: ix context --resume <id>", and
+ * `--resume` sanitizes what it is given: an id saved as `widget/auth` was
+ * listed as `widget~2Fauth`, and resuming that looked for `widget~7E2Fauth`,
+ * which does not exist. `saveInvestigation`'s own note echoes the id the user
+ * typed, so the two affordances contradicted each other.
+ *
+ * `sanitizeId(unsanitizeId(stored)) === stored` for every id this CLI wrote,
+ * which is what makes the listed id usable. A hand-written file whose id is
+ * outside `sanitizeId`'s range has no input that reaches it and is not a case
+ * this recovers.
+ */
+export function unsanitizeId(stored: string): string {
+ return stored.replace(/~([0-9A-Fa-f]{2})/g, (_m, hex: string) =>
+ String.fromCharCode(parseInt(hex, 16)),
+ );
+}
+
export function saveInvestigation(id: string, bundle: ContextBundle): void {
const dir = investigationDir();
mkdirSync(dir, { recursive: true });
@@ -482,23 +527,58 @@ export function listInvestigations(): { saved: SavedInvestigation[]; skipped: nu
return { saved: out, skipped };
}
+/** One saved investigation as `--list` describes it: what it is, not what is in it. */
+interface InvestigationSummary {
+ /** The id to type back, not the id on disk — see `unsanitizeId`. */
+ id: string;
+ savedAt: string;
+ target: { name: string; kind: string };
+ freshness: ContextBundle["freshness"];
+ counts: { entities: number; relationships: number; evidence: number };
+ truncation: ContextBundle["truncation"];
+}
+
+/** Summarise one saved investigation for the listing. */
+function summariseInvestigation(s: SavedInvestigation): InvestigationSummary {
+ const b = s.bundle;
+ return {
+ id: unsanitizeId(s.id),
+ savedAt: s.savedAt,
+ target: { name: b.target.name, kind: b.target.kind },
+ freshness: b.freshness,
+ counts: {
+ entities: b.entities.length,
+ relationships: b.relationships.length,
+ evidence: b.evidence.length,
+ },
+ truncation: b.truncation,
+ };
+}
+
/**
* Render the saved investigations produced by `listInvestigations`.
*
- * JSON stays the array of saved envelopes; llm emits a summary record and one
- * record per investigation; text prints the tabular summary.
+ * Every format carries the same summary: what each investigation is, how big
+ * it is, and how stale. Not the bundles themselves — `--list` is the discovery
+ * step, and twenty saved investigations is twenty complete bundles, up to 50
+ * entities, 100 relationships and 12000 characters of evidence each. A caller
+ * that wants one of them asks for it by id with `--resume <id> --format json`.
*
* `skipped` is reported in each format's own terms, and never on stdout except
- * as a field. It used to be a `renderWarning` inside the enumerator — which is
- * `console.log` — so a single corrupt file prepended a chalk-coloured prose
- * line to the payload and `ix context --list --format json | jq` failed on it.
- * The human warning goes to stderr; the machine formats carry a count.
+ * as a field — including in `json`, which returns an object for exactly that
+ * reason: an array has nowhere to put it, so a machine caller could not tell
+ * that files had been rejected while the human saw a warning saying so. It used
+ * to be a `renderWarning` inside the enumerator — which is `console.log` — so a
+ * single corrupt file prepended a chalk-coloured prose line to the payload and
+ * `ix context --list --format json | jq` failed on it. The human warning goes to
+ * stderr; the machine formats carry a count.
*/
export function renderInvestigationList(
items: SavedInvestigation[],
skipped: number,
format: string,
): void {
+ const summaries = items.map(summariseInvestigation);
if (skipped > 0 && format !== "llm") {
// `console.error`, not `renderWarning`: every renderer in ui.ts writes to
// stdout, which is exactly how this line used to end up inside the JSON a
@@ -511,57 +591,56 @@ export function renderInvestigationList(
);
}
if (format === "json") {
- console.log(JSON.stringify(items, null, 2));
+ console.log(JSON.stringify({ investigations: summaries, skipped }, null, 2));
return;
}
if (format === "llm") {
printLlmLines([
// `skipped` is a field rather than a warning: it is the one thing about
// the listing an agent cannot see from the records themselves.
- llmLine("investigations", { total: items.length, skipped: skipped || undefined }),
- ...items.map((s) =>
+ llmLine("investigations", { total: summaries.length, skipped: skipped || undefined }),
+ ...summaries.map((s) =>
llmLine("investigation", {
id: s.id,
saved_at: s.savedAt,
- target: s.bundle.target.name,
- target_kind: s.bundle.target.kind,
- classification: s.bundle.freshness.classification,
- stale: s.bundle.freshness.stale,
- entities: s.bundle.entities.length,
- relationships: s.bundle.relationships.length,
- evidence: s.bundle.evidence.length,
- truncated_entities: s.bundle.truncation.entitiesTruncated,
- truncated_relationships: s.bundle.truncation.relationshipsTruncated,
- truncated_evidence: s.bundle.truncation.evidenceTruncated,
- truncated_chars: s.bundle.truncation.charactersTruncated,
+ target: s.target.name,
+ target_kind: s.target.kind,
+ classification: s.freshness.classification,
+ stale: s.freshness.stale,
+ entities: s.counts.entities,
+ relationships: s.counts.relationships,
+ evidence: s.counts.evidence,
+ truncated_entities: s.truncation.entitiesTruncated,
+ truncated_relationships: s.truncation.relationshipsTruncated,
+ truncated_evidence: s.truncation.evidenceTruncated,
+ truncated_chars: s.truncation.charactersTruncated,
}),
),
]);
return;
}
- if (items.length === 0) {
+ if (summaries.length === 0) {
renderNote("No saved investigations. Use `ix context <target> --save <id>` to create one.");
return;
}
- renderSection(`Saved investigations (${items.length})`);
- for (const s of items) {
- const b = s.bundle;
+ renderSection(`Saved investigations (${summaries.length})`);
+ for (const s of summaries) {
console.log(` ${s.id}`);
- console.log(` target: ${b.target.name} (${b.target.kind})`);
+ console.log(` target: ${s.target.name} (${s.target.kind})`);
console.log(` saved_at: ${s.savedAt}`);
- console.log(` freshness: ${b.freshness.classification}`);
+ console.log(` freshness: ${s.freshness.classification}`);
console.log(
- ` counts: entities=${b.entities.length} relationships=${b.relationships.length} evidence=${b.evidence.length}`,
+ ` counts: entities=${s.counts.entities} relationships=${s.counts.relationships} evidence=${s.counts.evidence}`,
);
if (
- b.truncation.entitiesTruncated ||
- b.truncation.relationshipsTruncated ||
- b.truncation.evidenceTruncated ||
- b.truncation.charactersTruncated
+ s.truncation.entitiesTruncated ||
+ s.truncation.relationshipsTruncated ||
+ s.truncation.evidenceTruncated ||
+ s.truncation.charactersTruncated
) {
console.log(
- ` truncated: entities=${b.truncation.entitiesTruncated} relationships=${b.truncation.relationshipsTruncated} evidence=${b.truncation.evidenceTruncated} chars=${b.truncation.charactersTruncated}`,
+ ` truncated: entities=${s.truncation.entitiesTruncated} relationships=${s.truncation.relationshipsTruncated} evidence=${s.truncation.evidenceTruncated} chars=${s.truncation.charactersTruncated}`,
);
}
}