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
fix(cli): one conflict reporter, ordered rules, and docs that agree
Joseph Mikhail87a7cdafb19e
diff --git a/CLAUDE.md b/CLAUDE.mdindex 36c277b8..becee9cd 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -267,7 +267,9 @@ ix inventory --kind function --format json- Use `ix inventory` instead of `ix search ""` for listing entities by kind- Use `ix diff --summary` for broad revision comparisons (server-side, fast)- Use `--full` only when you need every individual change-- Always use `--limit` to cap result sets+- Always use `--limit` to cap result sets — except on `ix diff`, where+ `--summary` and `--full` each already fix the volume and passing `--limit`+ alongside either is refused rather than silently ignored- Use `--format llm` when you are reading the output; `--format json` only when chaining results between commands or extracting a specific field- Use `--path` or `--language` to restrict text searches- Use exact entity IDs from previous JSON resultsdiff --git a/ix-cli/src/cli/__tests__/context-mode-conflict.test.ts b/ix-cli/src/cli/__tests__/context-mode-conflict.test.tsindex cc1e55af..173cec87 100644--- a/ix-cli/src/cli/__tests__/context-mode-conflict.test.ts+++ b/ix-cli/src/cli/__tests__/context-mode-conflict.test.ts@@ -73,14 +73,19 @@ describe("detectContextModeConflict", () => {expect(msg).toMatch(/--resume cannot be combined with --out/);});- it("suggests --format json to --resume --out when format is non-json", () => {- const msg = detectContextModeConflict({- resume: "x",- out: "/tmp/x.json",- format: "llm",- });- expect(msg).toMatch(/--resume cannot be combined with --out/);- expect(msg).toMatch(/--format json with --out/);+ it("never advises --resume --out to retry a combination it also rejects", () => {+ // The hint used to be "use --format json with --out", which fires this same+ // branch: the user did as they were told and got the identical error, this+ // time with no advice at all. Whatever the message suggests must be+ // something that is not itself refused here.+ for (const format of ["text", "json", "llm"]) {+ const msg = detectContextModeConflict({ resume: "x", out: "/tmp/x.json", format })!;+ expect(msg).toMatch(/--resume cannot be combined with --out/);+ expect(msg).not.toMatch(/--format json with --out/);+ // And the way out it does name has to work.+ expect(msg).toMatch(/>/);+ expect(detectContextModeConflict({ resume: "x", format: "json" })).toBeUndefined();+ }});it("flags --diff + --save (C-1)", () => {@@ -142,6 +147,73 @@ describe("detectDiffModeConflict", () => {const b = detectDiffModeConflict({ summary: true, full: true });expect(b).toMatch(/--summary ignores --limit and --full/);});++ it("names --summary, not --full, when all three are passed", () => {+ // Only the two-flag pairs were covered, and the three-flag case took the+ // `--full && --limit` branch: the user was told to drop one of two flags+ // that `--summary` was going to ignore anyway, while the message naming the+ // flag actually in charge was unreachable for this input.+ const msg = detectDiffModeConflict({ summary: true, full: true, limit: "20" });+ expect(msg).toMatch(/--summary ignores --limit and --full/);+ expect(msg).not.toMatch(/--full and --limit cannot be combined/);+ });+});++/**+ * The gap the detectors are for is a flag the user typed doing nothing. A flag+ * added later with no rule written for it reopens exactly that gap, silently:+ * `ContextModeOptions` was a hand-copied five-field shape, `--list` was added+ * to `ContextOptions` on a sibling branch, and neither the typechecker nor any+ * test noticed the detector could not see it.+ *+ * So one side of this comes from the live Commander registration and the other+ * is hand-listed. Two hand-lists can be wrong together; a list checked against+ * the command cannot be. Adding an option to `ix context` fails here until it+ * is classified — a mode flag with a rule, or a build knob.+ */+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;+ /** Flags that shape the bundle a mode produces; any pair of these is legal. */+ const CONTEXT_BUILD_FLAGS = [+ "kind", "path", "pick", "depth", "asOfRev",+ "maxEntities", "maxRelationships", "maxEvidence", "maxChars", "format",+ ];++ function registeredAttributes(register: (p: Command) => void, name: string): string[] {+ const program = new Command();+ program.name("ix").exitOverride();+ register(program);+ const cmd = program.commands.find((c) => c.name() === name)!;+ return cmd.options.map((o) => o.attributeName()).sort();+ }++ it("classifies every option ix context registers", () => {+ expect(registeredAttributes(registerContextCommand, "context")).toEqual(+ [...CONTEXT_MODE_FLAGS, ...CONTEXT_BUILD_FLAGS].sort(),+ );+ });++ it("refuses every pair of mode flags", () => {+ for (const a of CONTEXT_MODE_FLAGS) {+ for (const b of CONTEXT_MODE_FLAGS) {+ if (a >= b) continue;+ const opts = { [a]: "x", [b]: "y" } as Record<string, string>;+ expect(+ detectContextModeConflict(opts),+ `no rule for --${a} + --${b}`,+ ).toBeTruthy();+ }+ }+ });++ it("leaves every single mode flag alone", () => {+ // The mirror of the above: a rule that fires on one flag would refuse the+ // command's ordinary use, and a pair-only assertion cannot see that.+ for (const flag of CONTEXT_MODE_FLAGS) {+ expect(detectContextModeConflict({ [flag]: "x" })).toBeUndefined();+ }+ });});/**diff --git a/ix-cli/src/cli/commands/context.ts b/ix-cli/src/cli/commands/context.tsindex 12c56abe..9e125fde 100644--- a/ix-cli/src/cli/commands/context.ts+++ b/ix-cli/src/cli/commands/context.ts@@ -2,7 +2,6 @@ import type { Command } from "commander";import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";import { homedir } from "node:os";import { dirname, join, resolve } from "node:path";-import chalk from "chalk";import {BUNDLE_SCHEMA,@@ -20,7 +19,7 @@ import type {} from "../../client/types.js";import { getEndpoint } from "../config.js";import { collectFacts, type EntityFacts } from "../explain/facts.js";-import { llmError, printLlmLines } from "../llm.js";+import { printLlmLines, reportModeConflict } from "../llm.js";import { parsePickOption } from "../options.js";import { resolveFileOrEntity } from "../resolve.js";import { createStaleProbe } from "../stale.js";@@ -138,7 +137,7 @@ export function registerContextCommand(program: Command): void {.action(async (target: string | undefined, opts: ContextOptions) => {const conflict = detectContextModeConflict(opts);if (conflict) {- reportContextModeConflict(conflict, opts.format);+ reportModeConflict(conflict, opts.format);return;}if (opts.resume) {@@ -271,18 +270,20 @@ async function buildFreshBundle(}-/** Saved investigation state lives under ~/.ix/investigations. *//**- * Subset of `ContextOptions` consumed by `detectContextModeConflict`. Kept as a- * structural type so the detector can be unit-tested without driving Commander.+ * The `ContextOptions` fields `detectContextModeConflict` consumes.+ *+ * `Pick`, not a hand-copied shape: the detector exists to stop a typed flag+ * being a no-op, so its idea of the flags must come from the same declaration+ * the action handler uses. Written out field-by-field it drifted immediately --+ * `--list` was added to `ContextOptions` on a sibling branch and the detector+ * could not see it, with nothing from the typechecker to say so. `Partial` so+ * the pure function can still be called with one flag at a time in a test,+ * without inventing a `format`.*/-export interface ContextModeOptions {- resume?: string;- diff?: string;- save?: string;- out?: string;- format?: string;-}+export type ContextModeOptions = Partial<+ Pick<ContextOptions, "resume" | "diff" | "save" | "out" | "format">+>;/*** Detect mutually-incompatible mode/output flags on `ix context` and return a@@ -306,10 +307,14 @@ export function detectContextModeConflict(return "--resume cannot be combined with --save; --resume only renders a saved investigation, while --save writes a new one. Run --save on a fresh build instead.";}if (opts.resume && opts.out) {+ // No "use --format json with --out" hint here. That hint was unactionable:+ // this branch fires on `--resume` plus `--out` whatever the format, so a+ // user who followed it landed straight back on the same error, this time+ // with no advice at all. The two things that do work are a redirect and+ // the saved file itself, so name those.return "--resume cannot be combined with --out; --resume renders to stdout."- + (opts.format && opts.format !== "json"- ? " Use --format json with --out if you need to persist the rendered output."- : "");+ + " Redirect it (`ix context --resume <id> --format json > <path>`), or read"+ + " IX_HOME/investigations/<id>.json, which is already the saved JSON.";}if (opts.diff && opts.save) {return "--diff cannot be combined with --save; --diff renders a comparison against a saved investigation. To persist the fresh side as a new investigation, run the fresh build without --diff and use --save there.";@@ -323,21 +328,7 @@ export function detectContextModeConflict(return undefined;}-/**- * Render a detected mode conflict and mark the process exit code.- *- * `--format llm` gets the record form the rest of the CLI emits for errors —- * `error code=... message="..."`, on stdout, with the exit code still non-zero- * (imports.ts, trace.ts, smells.ts, locate.ts, callers.ts all do this, and- * docs/llm-format.md specifies the shape). An agent is told to pass the flag- * unconditionally, so an error it cannot read is an error it cannot act on.- */-export function reportContextModeConflict(message: string, format?: string): void {- if (format === "llm") console.log(llmError("mode_conflict", message));- else console.error(chalk.red("Error:"), message);- process.exitCode = 1;-}-+/** Saved investigation state lives under ~/.ix/investigations. */function investigationDir(): string {// IX_HOME is the Ix home *directory*, not the investigations directory —// backend-status.ts, docker.ts and upgrade.ts all read it as `IX_HOME ||diff --git a/ix-cli/src/cli/commands/diff.ts b/ix-cli/src/cli/commands/diff.tsindex f30a0e61..8f749e37 100644--- a/ix-cli/src/cli/commands/diff.ts+++ b/ix-cli/src/cli/commands/diff.ts@@ -10,7 +10,7 @@ import { IxClient } from "../../client/api.js";import { getEndpoint } from "../config.js";import { resolveFileOrEntity, resolveEntityFull, printResolved, looksFileLike, type ResolvedEntity } from "../resolve.js";import { formatDiff, relativePath } from "../format.js";-import { llmLine, llmError } from "../llm.js";+import { llmLine, llmError, reportModeConflict } from "../llm.js";import { parsePickOption } from "../options.js";/**@@ -35,6 +35,13 @@ export interface DiffModeOptions {* explicit-conflict style in subsystems.ts. `--full --limit <n>` is also* flagged: `--full` is documented as "no limit" so the silent precedence over* `--limit` was the same kind of UX gap.+ *+ * Order is load-bearing, not incidental. `--summary` is the flag that wins at+ * runtime, so when it is present its message is the one that names the flag+ * actually in charge. Checking `--full --limit` first meant+ * `ix diff 3 5 --summary --full --limit 20` reported "--full and --limit cannot+ * be combined" -- two flags `--summary` was going to ignore anyway -- and the+ * message that would have explained the run was unreachable for that input.*/export function detectDiffModeConflict(opts: DiffModeOptions,@@ -42,33 +49,18 @@ export function detectDiffModeConflict(if (opts.summary && opts.content) {return "--summary and --content cannot be combined; --summary renders counts only, --content renders the full textual diff. Pick one.";}- if (opts.full && opts.limit !== undefined) {- return "--full and --limit cannot be combined; --full is documented to return all changes without a limit. Drop --limit, or drop --full to keep the existing limit.";- }if (opts.summary &&(opts.full || opts.limit !== undefined)) {return "--summary ignores --limit and --full; --summary is server-side counts only. Drop --summary to control change volume, or drop --limit/--full.";}+ if (opts.full && opts.limit !== undefined) {+ return "--full and --limit cannot be combined; --full is documented to return all changes without a limit. Drop --limit, or drop --full to keep the existing limit.";+ }return undefined;}-/**- * Render a detected mode conflict and mark the process exit code.- *- * `--format llm` gets the record form the rest of the CLI emits for errors —- * `error code=... message="..."`, on stdout, with the exit code still non-zero- * (imports.ts, trace.ts, smells.ts, locate.ts, callers.ts all do this, and- * docs/llm-format.md specifies the shape). An agent is told to pass the flag- * unconditionally, so an error it cannot read is an error it cannot act on.- */-export function reportDiffModeConflict(message: string, format?: string): void {- if (format === "llm") console.log(llmError("mode_conflict", message));- else console.error(chalk.red("Error:"), message);- process.exitCode = 1;-}-/** Render a `--summary` diff as a single llm record. */function renderDiffSummaryLlm(result: any): string {const s = result.summary || {};@@ -490,7 +482,7 @@ export function registerDiffCommand(program: Command): void {}) => {const conflict = detectDiffModeConflict(opts);if (conflict) {- reportDiffModeConflict(conflict, opts.format);+ reportModeConflict(conflict, opts.format);return;}const client = new IxClient(getEndpoint());diff --git a/ix-cli/src/cli/llm.ts b/ix-cli/src/cli/llm.tsindex 5339010e..8a30b9ad 100644--- a/ix-cli/src/cli/llm.ts+++ b/ix-cli/src/cli/llm.ts@@ -18,6 +18,8 @@* newlines/tabs are encoded as `\n`/`\r`/`\t` so a record never spans lines.*/+import chalk from "chalk";+/** A field value before rendering. Nullish/empty values are omitted. */export type LlmValue = string | number | boolean | null | undefined;@@ -98,3 +100,26 @@ export function printLlmLines(lines: Array<string | null | undefined>): void {if (line != null) console.log(line);}}++/**+ * Report a mutually-exclusive flag combination in the format the caller asked+ * for, and mark the run failed.+ *+ * Both halves matter. `--format llm` gets the `error code=... message="..."`+ * record on stdout that imports.ts, trace.ts, locate.ts and callers.ts already+ * emit and that docs/llm-format.md specifies: an agent is told to pass the flag+ * unconditionally, so an error it cannot parse is an error it cannot act on.+ * Every other format gets the human line on stderr, so a `--format json` caller+ * piping to `jq` never finds prose in the payload.+ *+ * One function because it was otherwise written twice, byte for byte including+ * its docblock, in `context.ts` and `diff.ts`. What it encodes -- which stream,+ * which record kind, which exit code -- is a convention that has to change+ * everywhere at once or not at all, and `subsystems.ts` already carries six+ * copies of the stderr half for the same reason.+ */+export function reportModeConflict(message: string, format?: string): void {+ if (format === "llm") console.log(llmError("mode_conflict", message));+ else console.error(chalk.red("Error:"), message);+ process.exitCode = 1;+}diff --git a/skills/ix/references/commands.md b/skills/ix/references/commands.mdindex e281fcaa..c7160357 100644--- a/skills/ix/references/commands.md+++ b/skills/ix/references/commands.md@@ -97,7 +97,9 @@ ix inventory --kind function --path auth.py --format llm- Use `ix inventory` instead of `ix search ""` for listing entities by kind.- Use `ix diff --summary` for broad revision comparisons; `--full` only whenevery individual change is needed.-- Always use `--limit` to cap result sets.+- Always use `--limit` to cap result sets. Not on `ix diff --summary` or+ `ix diff --full`, though: each already fixes the volume, so `--limit`+ alongside either is refused rather than silently ignored.- Use `--path` or `--language` to restrict text searches.- Reuse exact entity IDs from previous JSON results when chaining commands.- Decompose large questions into multiple targeted calls.