Skip to content

armgit / Ix

Public Imported from GitHub
0

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

fix(map): fail loudly when patches do not commit instead of reporting success (#347)

KageBinary4258d9f55418
diff --git a/ix-cli/src/cli/__tests__/ingest-commit-outcome.test.ts b/ix-cli/src/cli/__tests__/ingest-commit-outcome.test.ts
new file mode 100644
index 00000000..95382b35
--- /dev/null
+++ b/ix-cli/src/cli/__tests__/ingest-commit-outcome.test.ts
@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+
+import { describeCommitOutcome, ingestCompletedCleanly } from "../commands/ingest.js";
+
+describe("describeCommitOutcome", () => {
+ it("says nothing when every patch committed", () => {
+ expect(describeCommitOutcome(0, 120)).toEqual({ kind: "ok" });
+ expect(describeCommitOutcome(0, 0)).toEqual({ kind: "ok" });
+ });
+
+ it("is fatal when nothing landed at all", () => {
+ // The case this exists for. `ix map` passes suppressOutput, so a run where
+ // the backend accepted no patches used to return normally and let map.ts
+ // print regions built from a stale graph. map.ts turns a throw into
+ // emitError + exit 1, so being fatal here is what makes the failure visible.
+ const outcome = describeCommitOutcome(42, 0);
+ expect(outcome.kind).toBe("fatal");
+ expect(outcome.kind === "fatal" && outcome.message).toContain("committed nothing");
+ expect(outcome.kind === "fatal" && outcome.message).toContain("42");
+ });
+
+ it("warns but does not throw when the run was partly successful", () => {
+ // Some patches landed, so the graph moved forward and failing the whole
+ // command would be an overreaction. The mtime cache is not written on a run
+ // with commit errors, so the next run retries the files that failed.
+ const outcome = describeCommitOutcome(3, 97);
+ expect(outcome.kind).toBe("warn");
+ expect(outcome.kind === "warn" && outcome.message).toContain("3 of 100");
+ });
+
+ it("counts the total as failures plus successes, not files discovered", () => {
+ // Skipped-unchanged files are not part of this ratio; quoting a denominator
+ // that includes them would understate how much of the attempted work failed.
+ const outcome = describeCommitOutcome(1, 1);
+ expect(outcome.kind === "warn" && outcome.message).toContain("1 of 2");
+ });
+
+ it("keeps the fatal message grammatical for a single patch", () => {
+ const one = describeCommitOutcome(1, 0);
+ expect(one.kind === "fatal" && one.message).toContain("all 1 patch failed");
+ const many = describeCommitOutcome(2, 0);
+ expect(many.kind === "fatal" && many.message).toContain("all 2 patches failed");
+ });
+
+ it("treats a negative count as nothing to report", () => {
+ // Defensive: the caller increments a counter, but nothing here should turn
+ // an impossible value into a thrown error that fails an otherwise fine run.
+ //
+ // patchesApplied must be 0 here. With a positive value the fatal branch is
+ // unreachable under any implementation of the first guard, so the case
+ // asserted nothing about the invariant it names.
+ expect(describeCommitOutcome(-1, 0)).toEqual({ kind: "ok" });
+ expect(describeCommitOutcome(-1, 10)).toEqual({ kind: "ok" });
+ });
+
+ it("names a flag the running command actually has", () => {
+ // `ix map` has no --debug and never passed one to ingestFiles, so the
+ // remediation the message offered was inert on the only path where the
+ // failure is otherwise invisible. map passes --verbose instead.
+ const mapFatal = describeCommitOutcome(5, 0, "--verbose");
+ expect(mapFatal.kind === "fatal" && mapFatal.message).toContain("--verbose");
+ expect(mapFatal.kind === "fatal" && mapFatal.message).not.toContain("--debug");
+
+ const mapWarn = describeCommitOutcome(5, 5, "--verbose");
+ expect(mapWarn.kind === "warn" && mapWarn.message).toContain("--verbose");
+
+ // ix ingest keeps --debug, which it does have.
+ const ingestFatal = describeCommitOutcome(5, 0);
+ expect(ingestFatal.kind === "fatal" && ingestFatal.message).toContain("--debug");
+ });
+
+ it("blames the deadline, not the backend, when the run was cut short", () => {
+ // A fired map deadline aborts every in-flight request, and each abort lands
+ // in commitErrors. Reporting that as "the backend rejected your patches"
+ // points the user at the wrong system; the fix is a longer budget.
+ const fatal = describeCommitOutcome(40, 0, "--verbose", true);
+ expect(fatal.kind).toBe("fatal");
+ expect(fatal.kind === "fatal" && fatal.message).toContain("ran out of time");
+ expect(fatal.kind === "fatal" && fatal.message).toContain("IX_MAP_DEADLINE_MS");
+ expect(fatal.kind === "fatal" && fatal.message).not.toContain("failed to commit.");
+
+ // Still only fatal when nothing landed — a partial run under the deadline
+ // moved the graph forward and is a warning, same as any other partial.
+ const partial = describeCommitOutcome(40, 10, "--verbose", true);
+ expect(partial.kind).toBe("warn");
+ expect(partial.kind === "warn" && partial.message).toContain("ran out of time");
+ });
+});
+
+describe("ingestCompletedCleanly", () => {
+ it("is false when patches failed to commit", () => {
+ // The guard the PR calls load-bearing, and the one nothing pinned: it
+ // gates the mtime cache. Persisting the cache after a failed commit records
+ // the file at its current mtime, the next run skips it as unchanged, and it
+ // stays missing from the graph until a --force — a worse bug than the
+ // silent success being fixed, and one introduced by splitting the counters.
+ expect(ingestCompletedCleanly(0, 1)).toBe(false);
+ expect(ingestCompletedCleanly(0, 99)).toBe(false);
+ });
+
+ it("is false when files failed to parse", () => {
+ expect(ingestCompletedCleanly(1, 0)).toBe(false);
+ });
+
+ it("is true only when neither happened", () => {
+ expect(ingestCompletedCleanly(0, 0)).toBe(true);
+ });
+});
diff --git a/ix-cli/src/cli/commands/ingest.ts b/ix-cli/src/cli/commands/ingest.ts
index cf768ae6..d547d858 100644
--- a/ix-cli/src/cli/commands/ingest.ts
+++ b/ix-cli/src/cli/commands/ingest.ts
@@ -387,6 +387,95 @@ export function registerIngestCommand(program: Command): void {
});
}
+export type CommitOutcome =
+ | { kind: "ok" }
+ | { kind: "warn"; message: string }
+ | { kind: "fatal"; message: string };
+
+/**
+ * Decide how loudly a run should complain about patches that failed to commit.
+ *
+ * Split out of `ingestFiles` so the rule is testable without a backend: the
+ * failure it guards against is one nobody can see, so a rule nobody can test
+ * is not much of an improvement.
+ *
+ * Partial failure warns rather than throws — some patches landed, the graph
+ * moved forward, and the mtime cache is not written on a run with commit
+ * errors, so the next run retries the rest. Committing nothing is the case
+ * where carrying on would state something false about the graph, and `map.ts`
+ * already turns a throw into `emitError` plus exit 1.
+ */
+export function describeCommitOutcome(
+ commitErrors: number,
+ patchesApplied: number,
+ /**
+ * The flag that turns on per-file commit detail for the command being run.
+ * `ix map` has no `--debug` and never passes one — telling its users to use
+ * it sent them to an option that does not exist, on the one path where the
+ * failure is otherwise invisible.
+ */
+ debugFlag: string = "--debug",
+ /** True when the run was cut short by the map deadline rather than rejected. */
+ deadlineHit: boolean = false
+): CommitOutcome {
+ if (commitErrors <= 0) return { kind: "ok" };
+ const attempted = commitErrors + patchesApplied;
+
+ if (deadlineHit) {
+ // Distinguishable because the two need opposite responses: a rejected
+ // patch is a backend problem, a deadline is our own wall clock and the fix
+ // is a longer budget or a smaller repo. Folding both into "failed to
+ // commit" is the same information loss this change exists to undo.
+ return {
+ kind: patchesApplied === 0 ? "fatal" : "warn",
+ message:
+ `Ingest ran out of time: ${commitErrors} of ${attempted} file patches were abandoned when ` +
+ `the map deadline fired. The graph is missing those files. Raise IX_MAP_DEADLINE_MS or map a smaller path.`,
+ };
+ }
+
+ if (patchesApplied === 0) {
+ const patches = commitErrors === 1 ? "patch" : "patches";
+ return {
+ kind: "fatal",
+ message:
+ `Ingest committed nothing: all ${commitErrors} ${patches} failed to commit. ` +
+ `The graph is unchanged and may now be stale. Re-run with ${debugFlag} to see why.`,
+ };
+ }
+ return {
+ kind: "warn",
+ message:
+ `Warning: ${commitErrors} of ${attempted} file patches failed to commit; ` +
+ `the graph is missing those files. Re-run 'ix map' to retry, or ${debugFlag} to see why.`,
+ };
+}
+
+/**
+ * Did the run finish with the graph fully matching what it set out to ingest?
+ *
+ * Three things are conditional on this: persisting the mtime cache, the
+ * post-migration cleanup of the old workspace id, and writing the stitch
+ * registry. All three were previously written as `parseErrors === 0`, which
+ * worked only because commit failures were folded into `parseErrors`.
+ *
+ * The mtime cache is the one that bites. Persisting it after a failed commit
+ * records the file as ingested at its current mtime, so the next run skips it
+ * as unchanged and it stays missing from the graph until a `--force` — a worse
+ * bug than the silent success this change removes, and one introduced *by*
+ * splitting the counters. Named and exported so the rule itself is pinned by a
+ * test instead of living as a conjunct three call sites have to remember.
+ *
+ * That pins the rule, not its application: nothing yet fails if a call site
+ * stops calling this. `ingestFiles` has no test at all — it needs a backend —
+ * so the three call sites below, the `process.exitCode` on a partial failure,
+ * and the debug-flag wiring are all still verified by reading rather than by
+ * execution.
+ */
+export function ingestCompletedCleanly(parseErrors: number, commitErrors: number): boolean {
+ return parseErrors === 0 && commitErrors === 0;
+}
+
// ---------------------------------------------------------------------------
// File ingestion — parse locally, send via /v1/patch
// ---------------------------------------------------------------------------
@@ -627,6 +716,7 @@ export async function ingestFiles(
let patchesApplied = 0;
let filesSkipped = 0;
let parseErrors = 0;
+ let commitErrors = 0;
let tooLarge = 0;
let minifiedLikely = 0;
let latestRev = 0;
@@ -876,7 +966,12 @@ export async function ingestFiles(
if (result.rev > latestRev) latestRev = result.rev;
patchesApplied++;
} catch (commitErr) {
- parseErrors++;
+ // Counted apart from parseErrors: a patch that parsed fine and
+ // failed to commit means the graph is now behind the working
+ // tree, which is a different problem from a file we could not
+ // read. Reporting it as a parse error hid that distinction in
+ // both the summary and the JSON contract.
+ commitErrors++;
if (debug) {
const errMsg = String(commitErr);
const truncated = errMsg.length > 200 ? errMsg.slice(0, 200) + '…' : errMsg;
@@ -1261,14 +1356,19 @@ export async function ingestFiles(
// Persist mtime cache so next run can skip unchanged files quickly.
// Only save when no parse errors (avoid poisoning cache on partial failures).
- if (!opts.force && parseErrors === 0 && currentMtimes.size > 0) {
+ // commitErrors counts here too, and must: it used to be folded into
+ // parseErrors, so splitting the counters without naming it in each of these
+ // three guards would start caching mtimes for files whose patches never
+ // landed. The next run would skip them as unchanged and they would stay
+ // missing from the graph until a --force.
+ if (!opts.force && ingestCompletedCleanly(parseErrors, commitErrors) && currentMtimes.size > 0) {
saveMtimeCache(projectRoot, currentMtimes);
}
// Migration cleanup (Ix#225 gap 2): the re-ingest under the new path-based id has
// committed, so delete the OLD id's now-orphaned nodes/edges/patches. Best-effort —
// a failure here is non-fatal (orphans are harmless dead storage, cleanable later).
- if (workspaceMigrated && previousWorkspaceId && parseErrors === 0) {
+ if (workspaceMigrated && previousWorkspaceId && ingestCompletedCleanly(parseErrors, commitErrors)) {
try {
await client.deleteWorkspace(previousWorkspaceId);
if (debug) process.stderr.write(` Cleaned up pre-migration nodes under ${previousWorkspaceId}.\n`);
@@ -1286,7 +1386,7 @@ export async function ingestFiles(
// registration intact rather than overwriting it with a partial set; a fresh
// map, `--force`, or a post-reset re-map re-registers. (Incremental registry
// updates that touch only changed files are a future refinement.)
- if (stitchEnabled && filesSkipped === 0 && stitchFiles.length > 0 && parseErrors === 0) {
+ if (stitchEnabled && filesSkipped === 0 && stitchFiles.length > 0 && ingestCompletedCleanly(parseErrors, commitErrors)) {
try {
const entry = pickEntryFile(stitchFiles);
const provides = entry
@@ -1357,7 +1457,35 @@ export async function ingestFiles(
const elapsed = ((performance.now() - start) / 1000).toFixed(2);
+ // Reported before the suppressOutput return, and thrown when nothing landed.
+ //
+ // `ix map` passes suppressOutput unconditionally, so every commit failure
+ // used to exit here silently: ingestFiles never threw, never set exitCode,
+ // and map.ts went on to print its regions. CLAUDE.md RULE 5 has every agent
+ // run `ix map --silent` after an edit, so a backend that accepted nothing
+ // left the agent believing the graph was current while `ix search` and
+ // `ix impact` answered from a stale one. A wrong answer nobody can see is
+ // worse than a failed command.
+ const commitReport = describeCommitOutcome(
+ commitErrors,
+ patchesApplied,
+ // ix map has no --debug and never passes one; --verbose is its equivalent.
+ opts.mapMode === true ? "--verbose" : "--debug",
+ opts.deadlineSignal?.aborted === true
+ );
+ if (commitReport.kind === "warn") {
+ process.stderr.write(` ${commitReport.message}\n`);
+ // Non-zero even though we do not throw. A partial failure still means the
+ // graph does not match the working tree, and the caller — usually a hook
+ // running `ix map --silent` under CLAUDE.md RULE 5 — reads the exit code,
+ // not stderr. Exiting 0 here made the severity of an identical fault depend
+ // on how many files happened to change: one file failing was fatal, the
+ // same failure alongside a file that landed was silent.
+ process.exitCode = 1;
+ }
+
if (opts.suppressOutput === true) {
+ if (commitReport.kind === "fatal") throw new Error(commitReport.message);
return;
}
@@ -1370,6 +1498,7 @@ export async function ingestFiles(
entitiesParsed,
latestRev,
skipReasons: { unchanged: filesSkipped, emptyFile: 0, parseError: parseErrors, tooLarge, minifiedLikely },
+ commitErrors,
elapsedSeconds: parseFloat(elapsed),
timings: {
...timings,
@@ -1389,13 +1518,20 @@ export async function ingestFiles(
console.log(` changed: ${filesChanged} files`);
if (filesSkipped > 0) console.log(` ${chalk.dim('skipped unchanged:')} ${filesSkipped}`);
if (parseErrors > 0) console.log(` ${chalk.red('parse errors:')} ${parseErrors}`);
+ if (commitErrors > 0) console.log(` ${chalk.red('commit errors:')} ${commitErrors}`);
if (tooLarge > 0) console.log(` ${chalk.dim('skipped too large:')} ${tooLarge}`);
if (minifiedLikely > 0) console.log(` ${chalk.dim('skipped minified:')} ${minifiedLikely}`);
console.log(` rev: ${latestRev}`);
if (patchesApplied === 0 && filesDiscovered === 0) {
console.log(chalk.yellow('\n Warning: No files found. Check the path and supported extensions.'));
- } else if (patchesApplied === 0 && filesDiscovered > 0) {
+ } else if (patchesApplied === 0 && filesDiscovered > 0 && commitErrors === 0) {
+ // commitErrors === 0, or this reads "All files unchanged since last
+ // ingest" directly under "commit errors: 12". Files were not unchanged —
+ // they were rejected. This branch was unreachable on the fatal path until
+ // the throw moved below the summary so `--format json` could still emit,
+ // which is exactly the kind of false statement about the graph this
+ // change exists to stop making.
console.log(chalk.dim('\n All files unchanged since last ingest.'));
}
@@ -1441,6 +1577,13 @@ export async function ingestFiles(
console.log();
}
+
+ // Thrown last, so a total failure still emits its report first. Throwing
+ // before the JSON branch made `ix ingest --format json` print nothing at all
+ // on the very run a consumer most needs to parse — empty stdout and exit 1,
+ // where main emitted a valid document carrying patchesApplied: 0. The
+ // suppressOutput path above throws earlier because it has no report to emit.
+ if (commitReport.kind === "fatal") throw new Error(commitReport.message);
}
// ---------------------------------------------------------------------------
diff --git a/ix-cli/src/cli/commands/map.ts b/ix-cli/src/cli/commands/map.ts
index 6594fd31..97e31274 100644
--- a/ix-cli/src/cli/commands/map.ts
+++ b/ix-cli/src/cli/commands/map.ts
@@ -121,7 +121,7 @@ export function registerMapCommand(program: Command): void {
.option("--graph", "Render the hierarchy as a graph/tree view (default)")
.option("--list", "Render the ranked list view instead of the default graph/tree view")
.option("--full", "Force full local map, bypassing automatic safety limits (advanced/testing)")
- .option("--verbose", "Show raw confidence scores, crosscut scores, boundary ratios, and signals")
+ .option("--verbose", "Show raw confidence/crosscut scores and signals, plus per-file ingest diagnostics (including why a patch failed to commit)")
.option("--silent", "Suppress all output except a one-line summary (useful for LLM hooks)")
.addHelpText(
"after",
@@ -155,7 +155,7 @@ Examples:
ix map --list
ix map --all-items
ix map . --full
- ix --debug map . --full`
+ ix map . --full --verbose`
)
.action(async (pathArg: string | undefined, opts: { format: string; level?: string; minConfidence: string; maxItems: string; allItems?: boolean; sort: string; graph?: boolean; list?: boolean; full?: boolean; verbose?: boolean; silent?: boolean }) => {
const cwd = pathArg ? resolve(pathArg) : process.cwd();
@@ -257,6 +257,11 @@ Examples:
suppressOutput: true,
mapMode: true,
deadlineSignal,
+ // `ix map` has no --debug, so the per-file `[commit error] <uri>`
+ // detail was unreachable from the command that produced the
+ // failure — and the failure message told the user to pass a flag
+ // that does not exist. --verbose is map's equivalent lever.
+ debug: Boolean(opts.verbose),
});
} catch (err: any) {
emitError(formatFetchError(err));