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
feat(cli): reject contradictory mode/output flag combinations
Alot1z54311470684a
diff --git a/ix-cli/src/cli/__tests__/context-mode-conflict.test.ts b/ix-cli/src/cli/__tests__/context-mode-conflict.test.tsnew file mode 100644index 00000000..a37b22bb--- /dev/null+++ b/ix-cli/src/cli/__tests__/context-mode-conflict.test.ts@@ -0,0 +1,246 @@+import { mkdtempSync, rmSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { afterEach, beforeEach, describe, expect, it } from "vitest";+import { Command } from "commander";++import {+ detectContextModeConflict,+ registerContextCommand,+} from "../commands/context.js";+import {+ detectDiffModeConflict,+ registerDiffCommand,+} from "../commands/diff.js";++/**+ * C-1..C-4 silent-ignore flag gaps in `ix context` and C-5 in `ix diff` are now+ * surfaced as hard errors at the top of the action handler. These tests pin+ * both the pure functions and the integration through the real Commander+ * registration. The detectors run before any network call, so the action+ * returns before touching the real Ix backend; no mocks are needed for the+ * conflict paths.+ */++let home: string;+let origExitCode: number | string | undefined;++beforeEach(() => {+ home = mkdtempSync(join(tmpdir(), "ix-mode-conflict-test-"));+ process.env.IX_HOME = home;+ origExitCode = process.exitCode;+ process.exitCode = undefined;+});++afterEach(() => {+ delete process.env.IX_HOME;+ rmSync(home, { recursive: true, force: true });+ process.exitCode = origExitCode;+});++describe("detectContextModeConflict", () => {+ it("returns undefined when no flags are set", () => {+ expect(detectContextModeConflict({})).toBeUndefined();+ });++ it("returns undefined for a single mode flag with neutral extras", () => {+ expect(detectContextModeConflict({ resume: "x" })).toBeUndefined();+ expect(detectContextModeConflict({ diff: "x" })).toBeUndefined();+ expect(detectContextModeConflict({ save: "y" })).toBeUndefined();+ expect(detectContextModeConflict({ out: "/tmp/x.json" })).toBeUndefined();+ });++ it("returns undefined for the legal save+resolve target run", () => {+ // Fresh build with --save is fine; this is the contract path.+ expect(detectContextModeConflict({ save: "y", format: "text" })).toBeUndefined();+ // Fresh build with --out is fine in json mode (the existing renderWarning+ // path still applies; the conflict detector does not flag it).+ expect(detectContextModeConflict({ out: "/tmp/x.json", format: "json" })).toBeUndefined();+ });++ it("flags --resume + --diff", () => {+ const msg = detectContextModeConflict({ resume: "x", diff: "y" });+ expect(msg).toMatch(/--resume and --diff cannot be combined/);+ });++ it("flags --resume + --save", () => {+ const msg = detectContextModeConflict({ resume: "x", save: "y" });+ expect(msg).toMatch(/--resume cannot be combined with --save/);+ });++ it("flags --resume + --out (C-3 right-hand case)", () => {+ const msg = detectContextModeConflict({ resume: "x", out: "/tmp/x.json" });+ 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("flags --diff + --save (C-1)", () => {+ const msg = detectContextModeConflict({ diff: "x", save: "y" });+ expect(msg).toMatch(/--diff cannot be combined with --save/);+ });++ it("flags --diff + --out (C-3 left-hand case)", () => {+ const msg = detectContextModeConflict({ diff: "x", out: "/tmp/x.json" });+ expect(msg).toMatch(/--diff cannot be combined with --out/);+ });++ it("flags --save + --out (C-4): two different write targets", () => {+ const msg = detectContextModeConflict({ save: "y", out: "/tmp/x.json" });+ expect(msg).toMatch(/--save and --out cannot be combined/);+ });++ it("flags --resume alongside every other write flag", () => {+ // The three write flags the resume branch returns before.+ for (const other of [{ diff: "y" }, { save: "y" }, { out: "/tmp/x.json" }]) {+ expect(detectContextModeConflict({ resume: "x", ...other })).toMatch(/--resume/);+ }+ });+});++describe("detectDiffModeConflict", () => {+ it("returns undefined when no flags are set", () => {+ expect(detectDiffModeConflict({})).toBeUndefined();+ });++ it("returns undefined for legal single flags", () => {+ expect(detectDiffModeConflict({ summary: true })).toBeUndefined();+ expect(detectDiffModeConflict({ content: true })).toBeUndefined();+ expect(detectDiffModeConflict({ full: true })).toBeUndefined();+ expect(detectDiffModeConflict({ limit: "20" })).toBeUndefined();+ });++ it("flags --summary + --content (C-5)", () => {+ const msg = detectDiffModeConflict({ summary: true, content: true });+ expect(msg).toMatch(/--summary and --content cannot be combined/);+ });++ it("flags --full + --limit", () => {+ const msg = detectDiffModeConflict({ full: true, limit: "20" });+ expect(msg).toMatch(/--full and --limit cannot be combined/);+ });++ it("does NOT flag --full without --limit (--full alone is the documented path)", () => {+ expect(detectDiffModeConflict({ full: true })).toBeUndefined();+ });++ it("does NOT flag --limit alone (default behaviour)", () => {+ expect(detectDiffModeConflict({ limit: "20" })).toBeUndefined();+ });++ it("flags --summary alongside --limit or --full", () => {+ const a = detectDiffModeConflict({ summary: true, limit: "20" });+ expect(a).toMatch(/--summary ignores --limit and --full/);+ const b = detectDiffModeConflict({ summary: true, full: true });+ expect(b).toMatch(/--summary ignores --limit and --full/);+ });+});++/**+ * Drive the real `registerX` functions through Commander so we verify that:+ *+ * 1. the detector runs FIRST in the action handler (no network call);+ * 2. the surfaced message lands on stderr with an "Error:" prefix;+ * 3. process.exitCode is set to 1;+ * 4. resolution/fresh-build code paths do NOT touch stdout.+ *+ * No HTTP backend is required for the conflict paths because the detector+ * runs at the top of the action handler.+ */+function runProgram(+ register: (program: Command) => void,+ args: string[],+): { stderr: string; exitCode: number | string | undefined; stdout: string } {+ const program = new Command();+ program.name("ix").exitOverride();+ register(program);++ const stdout: string[] = [];+ const stderr: string[] = [];+ const origStdout = process.stdout.write.bind(process.stdout);+ const origErr = console.error;+ process.stdout.write = ((chunk: unknown) => {+ stdout.push(String(chunk));+ return true;+ }) as typeof process.stdout.write;+ console.error = (...a: unknown[]) => void stderr.push(a.join(" "));++ let code: number | string | undefined;+ try {+ program.parse(["node", "ix", ...args]);+ } catch (e) {+ // exitOverride turns process.exit into a CommanderError; we still want+ // the (possibly already-set) exitCode. The error message ends up in+ // stderr elsewhere; do not forward here.+ void e;+ } finally {+ code = process.exitCode;+ process.stdout.write = origStdout;+ console.error = origErr;+ }+ return { stderr: stderr.join("\n"), stdout: stdout.join(""), exitCode: code };+}++describe("ix context action surfaces mode conflicts on stderr and exits 1", () => {+ it.each([+ { args: ["context", "--resume", "x", "--diff", "y"], expect: /--resume and --diff/ },+ { args: ["context", "--resume", "x", "--save", "y"], expect: /--resume cannot be combined with --save/ },+ { args: ["context", "--resume", "x", "--out", "/tmp/x.json"], expect: /--resume cannot be combined with --out/ },+ { 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/ },+ ])("ix $args → stderr matches $expect and exit code is 1", ({ args, expect: re }) => {+ const r = runProgram(registerContextCommand, args);+ expect(r.exitCode).toBe(1);+ expect(r.stderr).toMatch(/^Error:/m);+ expect(r.stderr).toMatch(re);+ expect(r.stdout).toBe("");+ });+});++describe("ix diff action surfaces mode conflicts on stderr and exits 1", () => {+ it.each([+ { args: ["diff", "3", "5", "--summary", "--content"], expect: /--summary and --content cannot be combined/ },+ { args: ["diff", "3", "5", "--full", "--limit", "20"], expect: /--full and --limit cannot be combined/ },+ { args: ["diff", "3", "5", "--summary", "--limit", "20"], expect: /--summary ignores --limit and --full/ },+ { args: ["diff", "3", "5", "--summary", "--full"], expect: /--summary ignores --limit and --full/ },+ ])("ix diff $args → stderr matches $expect and exit code is 1", ({ args, expect: re }) => {+ const r = runProgram(registerDiffCommand, args);+ expect(r.exitCode).toBe(1);+ expect(r.stderr).toMatch(/^Error:/m);+ expect(r.stderr).toMatch(re);+ expect(r.stdout).toBe("");+ });+});++describe("ix help coverage stays intact (smoke)", () => {+ it("context help still lists --resume, --diff, --save, --out", () => {+ const program = new Command();+ program.name("ix").exitOverride();+ registerContextCommand(program);+ const help = program.commands.find((c) => c.name() === "context")!.helpInformation();+ expect(help).toMatch(/--save <id>/);+ expect(help).toMatch(/--resume <id>/);+ expect(help).toMatch(/--diff <id>/);+ expect(help).toMatch(/--out <path>/);+ });++ it("diff help still lists --summary, --content, --full, --limit", () => {+ const program = new Command();+ program.name("ix").exitOverride();+ registerDiffCommand(program);+ const help = program.commands.find((c) => c.name() === "diff")!.helpInformation();+ expect(help).toMatch(/--summary/);+ expect(help).toMatch(/--content/);+ expect(help).toMatch(/--full/);+ expect(help).toMatch(/--limit/);+ });+});diff --git a/ix-cli/src/cli/commands/context.ts b/ix-cli/src/cli/commands/context.tsindex 5d868db9..de771448 100644--- a/ix-cli/src/cli/commands/context.ts+++ b/ix-cli/src/cli/commands/context.ts@@ -2,6 +2,7 @@ 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 { contextBundleSchema } from "../context-bundle-schema.js";@@ -137,6 +138,11 @@ 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",).action(async (target: string | undefined, opts: ContextOptions) => {+ const conflict = detectContextModeConflict(opts);+ if (conflict) {+ reportContextModeConflict(conflict);+ return;+ }if (opts.resume) {renderSavedInvestigation(opts.resume, opts.format);return;@@ -268,6 +274,63 @@ 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.+ */+export interface ContextModeOptions {+ resume?: string;+ diff?: string;+ save?: string;+ out?: string;+ format?: string;+}++/**+ * Detect mutually-incompatible mode/output flags on `ix context` and return a+ * human-readable message naming the conflict, or `undefined` if no conflict.+ *+ * The action handler used to silently drop `--save` and `--out` whenever+ * `--resume` or `--diff` was passed (those branches `return` before the+ * `--save`/`--out` branches ever run). It also accepted `--save <id>` alongside+ * `--out <file>`, which describes two different write targets and so has no+ * 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.+ */+export function detectContextModeConflict(+ opts: ContextModeOptions,+): string | undefined {+ if (opts.resume && opts.diff) {+ return "--resume and --diff cannot be combined; --resume renders a saved investigation, --diff renders a comparison against one.";+ }+ if (opts.resume && opts.save) {+ 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) {+ 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."+ : "");+ }+ 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.";+ }+ if (opts.diff && opts.out) {+ return "--diff cannot be combined with --out; --diff renders the comparison to stdout.";+ }+ if (opts.save && opts.out) {+ return "--save and --out cannot be combined; --save writes to IX_HOME/investigations/<id>.json, while --out writes to a caller-chosen path. Pick one.";+ }+ return undefined;+}++/** Render a detected mode conflict and mark the process exit code. */+export function reportContextModeConflict(message: string): void {+ console.error(chalk.red("Error:"), message);+ process.exitCode = 1;+}+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 b06c894f..ab116464 100644--- a/ix-cli/src/cli/commands/diff.ts+++ b/ix-cli/src/cli/commands/diff.ts@@ -6,6 +6,53 @@ import { promisify } from "node:util";import type { Command } from "commander";import chalk from "chalk";import { IxClient } from "../../client/api.js";++/**+ * Subset of `DiffOptions` consumed by `detectDiffModeConflict`. Kept as a+ * structural type so the detector can be unit-tested without driving Commander.+ */+export interface DiffModeOptions {+ summary?: boolean;+ content?: boolean;+ full?: boolean;+ limit?: string;+}++/**+ * Detect mutually-incompatible output flags on `ix diff` and return a+ * human-readable message naming the conflict, or `undefined` if no conflict.+ *+ * The action handler early-returns on `--summary` before the `--content` branch+ * is reached, so passing both flags silently dropped `--content` (and the user+ * got a summary when they asked for the full textual diff). Catching the+ * combination up front and surfacing it as a hard error mirrors the+ * 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.+ */+export function detectDiffModeConflict(+ opts: DiffModeOptions,+): string | undefined {+ 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.";+ }+ return undefined;+}++/** Render a detected mode conflict and mark the process exit code. */+export function reportDiffModeConflict(message: string): void {+ console.error(chalk.red("Error:"), message);+ process.exitCode = 1;+}import { getEndpoint } from "../config.js";import { resolveFileOrEntity, resolveEntityFull, printResolved, looksFileLike, type ResolvedEntity } from "../resolve.js";import { formatDiff, relativePath } from "../format.js";@@ -431,6 +478,11 @@ export function registerDiffCommand(program: Command): void {entity?: string; summary?: boolean; content?: boolean; limit?: string; full?: boolean; format: string;kind?: string; path?: string; pick?: number;}) => {+ const conflict = detectDiffModeConflict(opts);+ if (conflict) {+ reportDiffModeConflict(conflict);+ return;+ }const client = new IxClient(getEndpoint());const from = parseInt(fromRev, 10);const to = parseInt(toRev, 10);