Skip to content

armgit / Ix

Public Imported from GitHub
0

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

fix(cli): one conflict reporter, ordered rules, and docs that agree

Joseph Mikhail87a7cdafb19e
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 results
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 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.ts
index 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.ts
index 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.ts
index 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.md
index 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 when
every 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.