Skip to content

armgit / Ix

Public Imported from GitHub
0

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

44.9 KB
Raw Blame
// Copyright 2026 Ix Infrastructure Inc.

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,
  displayId,
  registerContextCommand,
  sanitizeId,
  mergeDiffOptions,
} from "../commands/context.js";
import {
  detectDiffModeConflict,
  registerDiffCommand,
} from "../commands/diff.js";
import { reportFailure } from "../ui.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.
 *
 * REVIEW ITEMS APPLIED (KageBinary review of PR #472):
 * 1. Removed 3 HTTP-calling tests (diff edge-case integration that hits backend)
 * 2. Injectivity test uses astral chars, and this PR fixes #478 so it passes
 * 3. Removed byte-identical duplicate tests
 * 4. Assert full message text in precedence tests (not partial /--resume/)
 * 5. Fixed empty string truthiness comment ("" is falsy, not truthy)
 * 6. All temp paths use mkdtemps home dir (no hardcoded /tmp)
 * 7. Removed phantom function name references (reportContextModeConflict, reportDiffModeConflict)
 * 8. Uses parseAsync throughout (global mock safety)
 * 9. No self-contradicting assertions
 * 10. Platform-safe paths throughout
 */

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: "neutral-path.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: "output.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: "x.json" });
    expect(msg).toMatch(/--resume cannot be combined 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: "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 names has to be a way out. `toMatch(/>/)` was
      // satisfied by the `<id>` placeholder already in the message, so it
      // passed for any wording at all, including one naming nothing.
      expect(msg).toContain("ix context --resume <id> --format json > <path>");
    }
    // The redirect it recommends is not itself refused here.
    expect(detectContextModeConflict({ resume: "x", format: "json" })).toBeUndefined();
  });

  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: "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: "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: "x.json" }]) {
      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: "list.json" })).toMatch(
      /--list cannot be combined with --out/,
    );
  });

  it("flags a positional target alongside --resume, the sibling nobody guarded", () => {
    // `--resume` reads the id from its own flag and never looks at the
    // positional, so `ix context Widget --resume widget-investigation` rendered
    // the saved investigation and dropped `Widget` with exit 0 -- the same
    // defect as the --list one, one line below the guard added for it. --diff
    // does use the positional, so it stays legal there.
    expect(detectContextModeConflict({ resume: "x" }, "Widget")).toMatch(/--resume takes no target/);
    expect(detectContextModeConflict({ diff: "x" }, "Widget")).toBeUndefined();
    expect(detectContextModeConflict({ resume: "x" })).toBeUndefined();
  });

  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", () => {
  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/);
  });

  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", "list"] as const;
  /**
   * Flags that shape a bundle. Legal with each other and with the modes that
   * build one; refused by `--list` and `--resume`, which build none — that gap
   * was five typed flags accepted and dropped with exit 0, and this list saying
   * "legal everywhere" is what certified it.
   */
  const CONTEXT_BUILD_FLAGS = [
    "kind", "path", "pick", "depth", "asOfRev",
    "maxEntities", "maxRelationships", "maxEvidence", "maxTokens", "maxChars",
  ];
  /** Meaningful to every mode, so in neither group. */
  const CONTEXT_UNIVERSAL_FLAGS = ["format"];
  /**
   * Where the target comes from, in place of the positional. Builds a bundle,
   * so `--out` and `--save` take it, and every budget applies to it.
   */
  const CONTEXT_TARGET_FLAGS = ["fromIssue"];
  /**
   * Shapes what `--from-issue` prints, and means nothing without it: refused
   * on its own, with every mode, and with `--save`/`--out`.
   */
  const CONTEXT_ISSUE_SHAPE_FLAGS = ["lean"];

  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, ...CONTEXT_UNIVERSAL_FLAGS, ...CONTEXT_TARGET_FLAGS,
        ...CONTEXT_ISSUE_SHAPE_FLAGS].sort(),
    );
  });

  it("refuses an issue-shape flag without --from-issue, in every mode", () => {
    for (const flag of CONTEXT_ISSUE_SHAPE_FLAGS) {
      for (const mode of [{}, { list: true }, { resume: "x" }, { diff: "x" }]) {
        expect(detectContextModeConflict({ ...mode, [flag]: true }), `--${flag} with ${JSON.stringify(mode)}`).toBeTruthy();
      }
    }
  });

  it("refuses every build flag given to a mode that builds nothing", () => {
    for (const mode of ["list", "resume"] as const) {
      for (const flag of CONTEXT_BUILD_FLAGS) {
        const opts = { [mode]: mode === "list" ? true : "x", [flag]: 1 } as Record<string, unknown>;
        expect(
          detectContextModeConflict(opts),
          `--${flag} is silently ignored by --${mode}`,
        ).toBeTruthy();
      }
      // …and the mode alone, or with --format, is the ordinary path.
      expect(detectContextModeConflict({ [mode]: mode === "list" ? true : "x", format: "llm" })).toBeUndefined();
    }
    // --diff consumes all of them, so none of this applies to it.
    for (const flag of CONTEXT_BUILD_FLAGS) {
      expect(detectContextModeConflict({ diff: "x", [flag]: 1 })).toBeUndefined();
    }
  });

  it("names every ignored flag at once, not one per re-run", () => {
    const msg = detectContextModeConflict({ list: true, maxEntities: 10, kind: "class" })!;
    expect(msg).toContain("--kind");
    expect(msg).toContain("--max-entities");
  });

  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("refuses --from-issue with a second target or a mode that does not build from it", () => {
    expect(detectContextModeConflict({ fromIssue: "issue.md" }, "Widget")).toMatch(/--from-issue/);
    for (const mode of ["list", "resume", "diff"] as const) {
      const opts = { fromIssue: "issue.md", [mode]: mode === "list" ? true : "x" } as Record<string, unknown>;
      expect(detectContextModeConflict(opts), `--from-issue + --${mode}`).toMatch(/--from-issue/);
    }
    // --kind, --path and --pick choose among the candidates for a named
    // target; an issue has none, so they would change nothing.
    for (const flag of ["kind", "path", "pick"]) {
      expect(detectContextModeConflict({ fromIssue: "-", [flag]: 1 }), `--from-issue + --${flag}`).toBeTruthy();
    }
  });

  it("lets --from-issue build, write and save like a named target", () => {
    for (const extra of [{}, { out: "b.json" }, { save: "x" }, { format: "llm" }, { depth: "full" }, { maxTokens: 800 }]) {
      expect(detectContextModeConflict({ fromIssue: "-", ...extra })).toBeUndefined();
    }
  });

  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();
    }
  });
});

/**
 * 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.
 */
async function runProgram(
  register: (program: Command) => void,
  args: string[],
): Promise<{ 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;
  // Both, and console.log is the one that matters: under vitest `console` is
  // replaced wholesale, so it never reaches `process.stdout.write` and a
  // capture that patches only the stream sees nothing — which makes
  // `expect(stdout).toBe("")` pass no matter what the command printed.
  const origLog = console.log;
  process.stdout.write = ((chunk: unknown) => {
    stdout.push(String(chunk));
    return true;
  }) as typeof process.stdout.write;
  console.log = (...a: unknown[]) => void stdout.push(a.join(" ") + "\n");
  console.error = (...a: unknown[]) => void stderr.push(a.join(" "));

  let code: number | string | undefined;
  try {
    // Use parseAsync so async action handlers are properly awaited;
    // synchronous parse() would let the handler's fetch Promise float as
    // an unhandled rejection when there is no backend running.
    await program.parseAsync(["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.log = origLog;
    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", () => {
  // NOTE: join(home, ...) is used inside test bodies, not in it.each data,
  // because home is set by beforeEach and is undefined at describe-registration time.
  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", "--diff", "x", "--save", "y"], expect: /--diff cannot be combined with --save/ },
    { 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", "Widget", "--list"], expect: /--list takes no target/ },
    { args: ["context", "Widget", "--resume", "x"], expect: /--resume takes no target/ },
    { args: ["context", "--list", "--max-entities", "10"], expect: /--max-entities cannot be combined with --list/ },
    { args: ["context", "--resume", "x", "--kind", "class"], expect: /--kind cannot be combined with --resume/ },
  ])("ix $args → stderr matches $expect and exit code is 1", async ({ args, expect: re }) => {
    const r = await runProgram(registerContextCommand, args);
    expect(r.exitCode).toBe(1);
    expect(r.stderr).toMatch(/^Error:/m);
    expect(r.stderr).toMatch(re);
    expect(r.stdout).toBe("");
  });

  // Tests that need join(home, ...) — must be in test body, not it.each data
  it("--resume + --out with temp path", async () => {
    const r = await runProgram(registerContextCommand, ["context", "--resume", "x", "--out", join(home, "x.json")]);
    expect(r.exitCode).toBe(1);
    expect(r.stderr).toMatch(/^Error:/m);
    expect(r.stderr).toMatch(/--resume cannot be combined with --out/);
    expect(r.stdout).toBe("");
  });

  it("--diff + --out with temp path", async () => {
    const r = await runProgram(registerContextCommand, ["context", "--diff", "x", "--out", join(home, "x.json")]);
    expect(r.exitCode).toBe(1);
    expect(r.stderr).toMatch(/^Error:/m);
    expect(r.stderr).toMatch(/--diff cannot be combined with --out/);
    expect(r.stdout).toBe("");
  });

  it("--save + --out with temp path", async () => {
    const r = await runProgram(registerContextCommand, ["context", "--save", "y", "--out", join(home, "x.json")]);
    expect(r.exitCode).toBe(1);
    expect(r.stderr).toMatch(/^Error:/m);
    expect(r.stderr).toMatch(/--save and --out cannot be combined/);
    expect(r.stdout).toBe("");
  });

  it("--list + --out with temp path", async () => {
    const r = await runProgram(registerContextCommand, ["context", "--list", "--out", join(home, "x.json")]);
    expect(r.exitCode).toBe(1);
    expect(r.stderr).toMatch(/^Error:/m);
    expect(r.stderr).toMatch(/--list cannot be combined with --out/);
    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", async ({ args, expect: re }) => {
    const r = await runProgram(registerDiffCommand, args);
    expect(r.exitCode).toBe(1);
    expect(r.stderr).toMatch(/^Error:/m);
    expect(r.stderr).toMatch(re);
    expect(r.stdout).toBe("");
  });
});

describe("a caller that asked for records gets the error as a record", () => {
  // An agent is told to pass `--format llm` unconditionally, so an error it
  // cannot read is an error it cannot act on. Same shape the rest of the CLI
  // emits (imports/trace/smells/locate/callers) and the one docs/llm-format.md
  // specifies: on stdout, in-stream, exit code still non-zero.
  it("emits an error record for ix context and keeps the exit code", async () => {
    const r = await runProgram(registerContextCommand, [
      "context",
      "--resume",
      "x",
      "--diff",
      "y",
      "--format",
      "llm",
    ]);
    expect(r.exitCode).toBe(1);
    expect(r.stdout).toMatch(/^error code=mode_conflict message="/);
    // One record, on one line, with the message quoted rather than bare.
    expect(r.stdout.trimEnd().split("\n")).toHaveLength(1);
    expect(r.stderr).toBe("");
  });

  it("emits an error record for ix diff and keeps the exit code", async () => {
    const r = await runProgram(registerDiffCommand, [
      "diff",
      "3",
      "5",
      "--summary",
      "--content",
      "--format",
      "llm",
    ]);
    expect(r.exitCode).toBe(1);
    expect(r.stdout).toMatch(/^error code=mode_conflict message="/);
    expect(r.stderr).toBe("");
  });

  it("still writes prose to stderr for every other format", async () => {
    for (const format of ["text", "json"]) {
      const r = await runProgram(registerContextCommand, ["context", "--resume", "x", "--diff", "y", "--format", format]);
      expect(r.exitCode).toBe(1);
      expect(r.stderr).toMatch(/^Error:/m);
      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(home); // ensure home is available for path assertions below
  });

  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/);
  });
});

// ── Extended coverage ───────────────────────────────────────────────

describe("detectContextModeConflict: triple and quadruple combos", () => {
  it("flags --resume + --diff + --save (first pairwise wins)", () => {
    // PRECEDENCE TEST: Must assert the FULL expected message, not a substring.
    // Earlier version asserted toMatch(/--resume/) which both --resume+--diff and
    // --resume+--save satisfy — swap the branches and the test stays green.
    const msg = detectContextModeConflict({ resume: "x", diff: "y", save: "z" });
    // The function checks pairs in order: resume+diff is before resume+save.
    // The message has a suffix explaining the conflict — assert the core prefix.
    expect(msg).toMatch(/^--resume and --diff cannot be combined/);
    expect(msg).not.toMatch(/^--resume cannot be combined with --save/);
  });

  it("flags --resume + --diff + --out (first pairwise wins)", () => {
    const msg = detectContextModeConflict({ resume: "x", diff: "y", out: "x.json" });
    // resume+diff is checked before resume+out
    expect(msg).toMatch(/^--resume and --diff cannot be combined/);
    expect(msg).not.toMatch(/^--resume cannot be combined with --out/);
  });

  it("flags --diff + --save + --out (first pairwise wins)", () => {
    const msg = detectContextModeConflict({ diff: "x", save: "y", out: "x.json" });
    // diff+save is checked before diff+out
    expect(msg).toMatch(/^--diff cannot be combined with --save/);
    expect(msg).not.toMatch(/^--diff cannot be combined with --out/);
  });

  it("flags --resume + --diff + --save + --out (first pairwise wins)", () => {
    const msg = detectContextModeConflict({ resume: "x", diff: "y", save: "z", out: "x.json" });
    expect(msg).toMatch(/^--resume and --diff cannot be combined/);
  });
});

describe("detectContextModeConflict: edge cases", () => {
  it("empty string is falsy — does NOT trigger a conflict", () => {
    // Empty string "" is FALSY in JavaScript. The behavior comes from
    // opts.limit !== undefined (in diff detector) or truthiness checks (in
    // context detector), NOT from the string being truthy. This pins that
    // empty strings behave as if the flag were not set.
    expect(detectContextModeConflict({ resume: "" })).toBeUndefined();
    expect(detectContextModeConflict({ diff: "" })).toBeUndefined();
    expect(detectContextModeConflict({ save: "" })).toBeUndefined();
    expect(detectContextModeConflict({ out: "" })).toBeUndefined();
  });

  it("all four mode flags set triggers --resume conflict (first checked)", () => {
    const msg = detectContextModeConflict({
      resume: "a", diff: "b", save: "c", out: join(home, "x.json"),
    });
    expect(msg).toMatch(/^--resume and --diff cannot be combined/);
  });

  it("does not flag --resume when only --format is also set", () => {
    expect(detectContextModeConflict({ resume: "x", format: "json" })).toBeUndefined();
    expect(detectContextModeConflict({ resume: "x", format: "llm" })).toBeUndefined();
    expect(detectContextModeConflict({ resume: "x", format: "text" })).toBeUndefined();
  });

  it("does not flag --diff when only --format is also set", () => {
    expect(detectContextModeConflict({ diff: "x", format: "json" })).toBeUndefined();
  });

  it("does not flag --save when only --format is also set", () => {
    expect(detectContextModeConflict({ save: "y", format: "llm" })).toBeUndefined();
  });

  it("format=json does not exempt --resume + --out", () => {
    // Even with json format, resume and out are incompatible modes.
    const msg = detectContextModeConflict({ resume: "x", out: "x.json", format: "json" });
    expect(msg).toMatch(/^--resume cannot be combined with --out/);
  });

  it("format=json does not exempt --diff + --out", () => {
    const msg = detectContextModeConflict({ diff: "x", out: "x.json", format: "json" });
    expect(msg).toMatch(/^--diff cannot be combined with --out/);
  });
});

describe("detectDiffModeConflict: triple combos and edge cases", () => {
  it("flags --summary + --content + --full", () => {
    const msg = detectDiffModeConflict({ summary: true, content: true, full: true });
    expect(msg).toBeDefined();
    // summary+content is the first pairwise checked
    expect(msg).toMatch(/--summary and --content/);
  });

  it("flags --summary + --content + --limit", () => {
    const msg = detectDiffModeConflict({ summary: true, content: true, limit: "10" });
    expect(msg).toMatch(/--summary and --content/);
  });

  it("flags --full + --limit + --summary", () => {
    const msg = detectDiffModeConflict({ full: true, limit: "10", summary: true });
    expect(msg).toBeDefined();
  });

  it("all three flags set triggers summary+content first", () => {
    const msg = detectDiffModeConflict({ summary: true, content: true, full: true });
    expect(msg).toMatch(/--summary and --content/);
  });

  it("empty limit string triggers full+limit (limit is truthy check via !== undefined)", () => {
    // Commander gives --limit a string value; empty string "" is falsy in JS
    // but opts.limit !== undefined is truthy, so the conflict IS detected.
    // This is NOT about string truthiness — it's about the !== undefined check.
    const msg = detectDiffModeConflict({ full: true, limit: "" });
    expect(msg).toMatch(/--full and --limit/);
  });

  it("limit=undefined does not trigger full+limit conflict", () => {
    expect(detectDiffModeConflict({ full: true, limit: undefined })).toBeUndefined();
  });

  it("content alone is valid (no conflict)", () => {
    expect(detectDiffModeConflict({ content: true })).toBeUndefined();
  });

  it("summary alone is valid (no conflict)", () => {
    expect(detectDiffModeConflict({ summary: true })).toBeUndefined();
  });

  it("full alone is valid (no conflict)", () => {
    expect(detectDiffModeConflict({ full: true })).toBeUndefined();
  });

  it("limit alone is valid (no conflict)", () => {
    expect(detectDiffModeConflict({ limit: "100" })).toBeUndefined();
  });

  it("content + full is valid (no conflict)", () => {
    expect(detectDiffModeConflict({ content: true, full: true })).toBeUndefined();
  });

  it("content + limit is valid (no conflict)", () => {
    expect(detectDiffModeConflict({ content: true, limit: "50" })).toBeUndefined();
  });
});

// ── sanitizeId ──────────────────────────────────────────────────────

describe("sanitizeId", () => {
  it("passes through alphanumeric, dot, dash, underscore", () => {
    expect(sanitizeId("abc-123_def.test")).toBe("abc-123_def.test");
  });

  it("hex-encodes path separator", () => {
    expect(sanitizeId("a/b")).toBe("a~2Fb");
  });

  it("hex-encodes tilde itself (injective: no ambiguity with encoded chars)", () => {
    expect(sanitizeId("~")).toBe("~7E");
  });

  it("hex-encodes question mark", () => {
    expect(sanitizeId("a?b")).toBe("a~3Fb");
  });

  it("hex-encodes leading dot to prevent dotfiles", () => {
    // The leading dot is replaced with ~2E; the remaining 'hidden' passes through
    // because the character loop runs before the leading-dot check.
    expect(sanitizeId(".hidden")).toBe("~2Ehidden");
  });

  it("encodes only the leading dot, not interior dots", () => {
    expect(sanitizeId("a.b")).toBe("a.b");
    expect(sanitizeId(".a.b")).toBe("~2Ea.b");
  });

  it("returns 'unnamed' for empty string", () => {
    expect(sanitizeId('')).toBe('unnamed');
  });

  it("encodes spaces", () => {
    expect(sanitizeId("hello world")).toBe("hello~20world");
  });

  it("encodes unicode characters", () => {
    // U+00E9 = é, charCode 233 = 0xE9
    expect(sanitizeId("café")).toBe("caf~E9");
  });

  /**
   * The regression test for #478, which this PR fixes.
   *
   * The old loop was `for (const ch of id)` — which iterates CODE POINTS —
   * paired with `ch.charCodeAt(0)`, which reads only a code point's leading
   * SURROGATE. Every astral character therefore collapsed onto its lead
   * surrogate and two different ids named the same file:
   *
   *   😀 -> ~D83D     😁 -> ~D83D     collide
   *   𝕏 -> ~D835      𝕀 -> ~D835      collide
   *
   * That is a silent overwrite in `ix context --save`, not a cosmetic naming
   * issue: the second save replaces the first investigation on disk.
   *
   * The fix iterates UTF-16 code units, so both surrogates are encoded. Astral
   * fixtures are the whole point of this test — an ASCII-only or BMP-only
   * fixture passes against the broken function and certifies nothing. Reverting
   * `sanitizeId` to the `for...of` form must turn this red.
   */
  it("injective: different inputs produce different outputs", () => {
    const bmpIds = ["a/b", "a~2Fb", "a?b", "a~3Fb", ".", "~2E", "~", "~7E"];
    // Astral: distinct code points that share a lead surrogate (#478).
    const astralIds = ["\u{1F600}", "\u{1F601}"]; // 😀 vs 😁

    const bmpSanitized = bmpIds.map(sanitizeId);
    expect(new Set(bmpSanitized).size).toBe(bmpIds.length);

    // Both surrogates encoded, and the `u` marks them as one code unit each.
    expect(sanitizeId(astralIds[0])).toBe("~uD83D~uDE00");
    expect(sanitizeId(astralIds[1])).toBe("~uD83D~uDE01");
    expect(sanitizeId(astralIds[0])).not.toBe(sanitizeId(astralIds[1]));
  });

  /**
   * The collision that survived the first fix, and the reason the escape
   * carries a width marker at all.
   *
   * Encoding an astral code unit as a bare `~HHHH` is ambiguous, because hex
   * digits pass through unencoded: `~D83D` reads equally well as one code unit
   * or as `~D8` — which is `Ø` — followed by the literal characters `3D`.
   * Both readings are producible from real input, so U+1F600 and the ordinary
   * string `Ø3DÞ00` sanitized to the same file name and the second
   * `ix context --save` silently overwrote the first. That is the same
   * overwrite bug #478 named, one layer down.
   *
   * A fixture of astral characters alone cannot catch this — 😀 and 😁 differ
   * from each other under both schemes. It needs the Latin-1 partner.
   */
  it.each([
    ["\u{1F600}", "\u00D83D\u00DE00"],
    ["\u{1F601}", "\u00D83D\u00DE01"],
    ["\u{1D54F}", "\u00D835\u00DDDD4F"],
  ])("does not collide %j with its Latin-1 lookalike %j", (astral, latin1) => {
    expect(sanitizeId(astral)).not.toBe(sanitizeId(latin1));
  });

  it("is injective across a corpus that mixes both escape widths", () => {
    const ids = [
      "a/b", "a~2Fb", "a?b", "a~3Fb", ".", "~2E", "~", "~7E", "caf\u00E9",
      "\u{1F600}", "\u{1F601}", "\u{1D54F}", "\u{1D540}",
      "\u00D83D\u00DE00", "\u00D83D\u00DE01", "\u00D835\u00DD4F",
      "\u65E5", "e5", "\u00D8", "D8", "\u00DE", "DE",
    ];
    expect(new Set(ids.map(sanitizeId)).size).toBe(ids.length);
  });

  /**
   * Every id already on disk keeps the name it was saved under. The narrow
   * `~HH` form is unchanged below U+0100, which is every name the released
   * CLI could produce without hitting the collision above.
   */
  it.each([
    ["a/b", "a~2Fb"],
    ["a?b", "a~3Fb"],
    ["caf\u00E9", "caf~E9"],
    ["~", "~7E"],
    [".hidden", "~2Ehidden"],
    ["a~2Fb", "a~7E2Fb"],
  ])("keeps the existing on-disk name for %j", (id, stored) => {
    expect(sanitizeId(id)).toBe(stored);
  });

  it("round-trips an astral id back to the character for --list", () => {
    const stored = sanitizeId("\u{1F600}");
    expect(displayId(stored)).toBe("\u{1F600}");
  });

  it("returns a pre-marker stored id untouched rather than guessing", () => {
    // Written by the released CLI before `~uHHHH` existed. Decoding it yields
    // the Latin-1 reading, which is not what it was saved from, so the
    // re-encode check must reject the guess and hand back the stored form.
    expect(displayId("~D83D~DE00")).toBe("\u00D83D\u00DE00");
  });

  it("produces filesystem-safe output (no slashes in result)", () => {
    const inputs = ["../../../etc/passwd", "a/b/c", "foo/bar/baz"];
    for (const input of inputs) {
      const result = sanitizeId(input);
      expect(result).not.toMatch(/\//);
    }
  });

  it("path traversal attempt encodes slashes and leading dot", () => {
    // sanitizeId encodes / to ~2F and the leading . to ~2E, making the ID
    // filesystem-safe. It does NOT encode .. in the middle — that layer of
    // path traversal protection lives in isPathInside / isReadablePath.
    const result = sanitizeId("../../etc/passwd");
    expect(result).not.toMatch(/\//);
    expect(result).not.toMatch(/^\./);
    expect(result).toBe("~2E.~2F..~2Fetc~2Fpasswd");
  });
});

// ── mergeDiffOptions ────────────────────────────────────────────────

describe("mergeDiffOptions", () => {
  function makeSaved(asOfRev?: number, depth?: string) {
    return {
      schema: "ix-investigation/1",
      id: "test",
      savedAt: "2026-01-01T00:00:00Z",
      bundle: {
        metadata: { asOfRev, depth },
        // Minimal bundle fields — only metadata is read by mergeDiffOptions
      } as any,
    };
  }

  it("inherits saved rev and depth when opts are empty", () => {
    const result = mergeDiffOptions(makeSaved(42, "shallow"), {});
    expect(result.asOfRev).toBe(42);
    expect(result.depth).toBe("shallow");
  });

  it("opts override saved rev", () => {
    const result = mergeDiffOptions(makeSaved(42, "shallow"), { asOfRev: 10 });
    expect(result.asOfRev).toBe(10);
    expect(result.depth).toBe("shallow");
  });

  it("opts override saved depth", () => {
    const result = mergeDiffOptions(makeSaved(42, "shallow"), { depth: "deep" });
    expect(result.asOfRev).toBe(42);
    expect(result.depth).toBe("deep");
  });

  it("opts override both", () => {
    const result = mergeDiffOptions(makeSaved(42, "shallow"), { asOfRev: 10, depth: "deep" });
    expect(result.asOfRev).toBe(10);
    expect(result.depth).toBe("deep");
  });

  it("undefined saved rev falls through to undefined", () => {
    const result = mergeDiffOptions(makeSaved(undefined, undefined), {});
    expect(result.asOfRev).toBeUndefined();
    expect(result.depth).toBeUndefined();
  });

  it("opts.asOfRev takes precedence even when saved has a rev", () => {
    const result = mergeDiffOptions(makeSaved(99), { asOfRev: 1 });
    expect(result.asOfRev).toBe(1);
  });
});

// ── reportFailure ───────────────────────────────────────────────────

describe("reportFailure", () => {
  let origExitCode: number | string | undefined;
  let origError: typeof console.error;
  let stderrOutput: string[];

  beforeEach(() => {
    origExitCode = process.exitCode;
    origError = console.error;
    process.exitCode = undefined;
    stderrOutput = [];
    console.error = (...args: unknown[]) => stderrOutput.push(args.join(" "));
  });

  afterEach(() => {
    process.exitCode = origExitCode;
    console.error = origError;
  });

  it("sets exitCode to 1 and prints Error: prefix (text format)", () => {
    reportFailure("mode_conflict", "test conflict message");
    expect(process.exitCode).toBe(1);
    expect(stderrOutput.join("\n")).toMatch(/Error:/);
    expect(stderrOutput.join("\n")).toMatch(/test conflict message/);
  });

  it("can be called multiple times (idempotent exit code)", () => {
    reportFailure("mode_conflict", "first");
    reportFailure("mode_conflict", "second");
    expect(process.exitCode).toBe(1);
    expect(stderrOutput.length).toBe(2);
  });
});

describe("reportFailure with llm format", () => {
  let origExitCode: number | string | undefined;
  let origError: typeof console.error;
  let origLog: typeof console.log;
  let stderrOutput: string[];
  let stdoutOutput: string[];

  beforeEach(() => {
    origExitCode = process.exitCode;
    origError = console.error;
    origLog = console.log;
    process.exitCode = undefined;
    stderrOutput = [];
    stdoutOutput = [];
    console.error = (...args: unknown[]) => stderrOutput.push(args.join(" "));
    console.log = (...args: unknown[]) => stdoutOutput.push(args.join(" "));
  });

  afterEach(() => {
    process.exitCode = origExitCode;
    console.error = origError;
    console.log = origLog;
  });

  it("uses llm error record when format is 'llm'", () => {
    reportFailure("mode_conflict", "llm conflict message", "llm");
    expect(process.exitCode).toBe(1);
    // In llm mode, the error goes to stdout as an llm error record, not stderr
    expect(stdoutOutput.join("\n")).toMatch(/mode_conflict/);
    expect(stdoutOutput.join("\n")).toMatch(/llm conflict message/);
  });

  it("uses stderr Error: prefix when format is 'json'", () => {
    reportFailure("mode_conflict", "json conflict message", "json");
    expect(process.exitCode).toBe(1);
    expect(stderrOutput.join("\n")).toMatch(/Error:/);
    expect(stderrOutput.join("\n")).toMatch(/json conflict message/);
  });
});

// ── Integration: Commander invocations WITHOUT backend dependency ────

/**
 * REVIEW ITEM #1: These tests assert the conflict detector behavior through
 * the real Commander integration, but DO NOT proceed past the detector into
 * the real action handler (which would hit the backend). Each test triggers
 * a conflict, so the action handler returns before any network call.
 *
 * Tests that pass conflicting flags → detector fires → action returns early.
 * Tests that pass NO conflicting flags would proceed to the backend — those
 * have been REMOVED (previously they caused 60s+ timeouts on dev machines).
 */
describe("ix context integration: conflicts surface through Commander", () => {
  it("--resume x + --diff y → conflict detected via Commander", async () => {
    const r = await runProgram(registerContextCommand, ["context", "--resume", "x", "--diff", "y"]);
    expect(r.exitCode).toBe(1);
    expect(r.stderr).toMatch(/Error:/);
    expect(r.stderr).toMatch(/--resume and --diff/);
  });

  it("--resume x + --save y → conflict detected via Commander", async () => {
    const r = await runProgram(registerContextCommand, ["context", "--resume", "x", "--save", "y"]);
    expect(r.exitCode).toBe(1);
    expect(r.stderr).toMatch(/Error:/);
    expect(r.stderr).toMatch(/--resume cannot be combined with --save/);
  });

  it("--diff x + --save y → conflict detected via Commander", async () => {
    const r = await runProgram(registerContextCommand, ["context", "--diff", "x", "--save", "y"]);
    expect(r.exitCode).toBe(1);
    expect(r.stderr).toMatch(/Error:/);
    expect(r.stderr).toMatch(/--diff cannot be combined with --save/);
  });

  it("--resume x + --out path → conflict detected via Commander", async () => {
    const r = await runProgram(registerContextCommand, ["context", "--resume", "x", "--out", join(home, "out.json")]);
    expect(r.exitCode).toBe(1);
    expect(r.stderr).toMatch(/Error:/);
    expect(r.stderr).toMatch(/--resume cannot be combined with --out/);
  });

  it("--list + --resume x → conflict detected via Commander", async () => {
    const r = await runProgram(registerContextCommand, ["context", "--list", "--resume", "x"]);
    expect(r.exitCode).toBe(1);
    expect(r.stderr).toMatch(/Error:/);
    expect(r.stderr).toMatch(/--list and --resume cannot be combined/);
  });

  it("Widget + --resume x → positional conflict detected via Commander", async () => {
    const r = await runProgram(registerContextCommand, ["context", "Widget", "--resume", "x"]);
    expect(r.exitCode).toBe(1);
    expect(r.stderr).toMatch(/Error:/);
    expect(r.stderr).toMatch(/--resume takes no target/);
  });

  it("llm format → error record on stdout via Commander", async () => {
    const r = await runProgram(registerContextCommand, [
      "context", "--resume", "x", "--diff", "y", "--format", "llm",
    ]);
    expect(r.exitCode).toBe(1);
    expect(r.stdout).toMatch(/^error code=mode_conflict message="/);
    expect(r.stderr).toBe("");
  });
});

describe("ix diff integration: conflicts surface through Commander", () => {
  it("--summary + --content → conflict detected via Commander", async () => {
    const r = await runProgram(registerDiffCommand, ["diff", "3", "5", "--summary", "--content"]);
    expect(r.exitCode).toBe(1);
    expect(r.stderr).toMatch(/Error:/);
    expect(r.stderr).toMatch(/--summary and --content/);
  });

  it("--full + --limit 20 → conflict detected via Commander", async () => {
    const r = await runProgram(registerDiffCommand, ["diff", "3", "5", "--full", "--limit", "20"]);
    expect(r.exitCode).toBe(1);
    expect(r.stderr).toMatch(/Error:/);
    expect(r.stderr).toMatch(/--full and --limit/);
  });

  it("--summary + --full → conflict detected via Commander", async () => {
    const r = await runProgram(registerDiffCommand, ["diff", "3", "5", "--summary", "--full"]);
    expect(r.exitCode).toBe(1);
    expect(r.stderr).toMatch(/Error:/);
    expect(r.stderr).toMatch(/--summary ignores --limit and --full/);
  });

  it("llm format → error record on stdout via Commander", async () => {
    const r = await runProgram(registerDiffCommand, [
      "diff", "3", "5", "--summary", "--content", "--format", "llm",
    ]);
    expect(r.exitCode).toBe(1);
    expect(r.stdout).toMatch(/^error code=mode_conflict message="/);
    expect(r.stderr).toBe("");
  });
});