Skip to content

armgit / Ix

Public Imported from GitHub
0

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

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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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);