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
// Copyright 2026 Ix Infrastructure Inc.
import { describe, expect, it } from "vitest";
import { describeCommitOutcome, describeStitchFailure, describeStitchSkipped, ingestCompletedCleanly, isStitchUnsupported, shouldPrintStitchSkipped } 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("describeCommitOutcome after `ix reset` (IN-19C)", () => {
it("is still fatal, and says the graph is still empty rather than unchanged", () => {
const outcome = describeCommitOutcome(12, 0, "--verbose", false, 0, false, true);
expect(outcome.kind).toBe("fatal");
const message = outcome.kind === "fatal" ? outcome.message : "";
expect(message).not.toContain("unchanged");
expect(message).toContain("this workspace's graph is still empty");
expect(message).toContain("--verbose");
});
it("keeps the old text without the flag, and warns the same on a partial run", () => {
const old = describeCommitOutcome(12, 0, "--verbose", false, 0, false);
expect(old.kind === "fatal" && old.message).toContain("The graph is unchanged");
expect(describeCommitOutcome(3, 9, "--verbose", false, 0, false, true).kind).toBe("warn");
});
});
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);
});
});
describe("describeCommitOutcome when the deadline fired", () => {
it("does not tell the user to raise the budget when NOTHING committed", () => {
// With a 5-minute per-request timeout and a 15-minute budget, a stalled
// backend fits ~3 attempts in -- the cutoff's streak cannot reach its limit,
// so the run ends on the deadline. "Raise IX_MAP_DEADLINE_MS" is then advice
// to wait longer on a backend that answered nothing.
const out = describeCommitOutcome(20, 0, "--verbose", true, 0);
expect(out.kind).toBe("fatal");
if (out.kind === "ok") throw new Error("expected a message");
expect(out.message).toContain("without committing anything");
// Both readings are live: the deadline covers discovery, hashing and parse
// too, so a large repo can spend it before the first commit is attempted --
// and there raising it IS the fix. Name both rather than assert one.
expect(out.message).toContain("raise IX_MAP_DEADLINE_MS");
expect(out.message).toContain("not accepting writes");
expect(out.message).toContain("ix doctor");
});
it("still points at the budget when work was getting done", () => {
const out = describeCommitOutcome(20, 4000, "--verbose", true, 0);
expect(out.kind).toBe("warn");
if (out.kind === "ok") throw new Error("expected a message");
expect(out.message).toContain("Raise IX_MAP_DEADLINE_MS");
});
it("reports the deadline ahead of the cutoff when both happened", () => {
// A run that skipped a handful to the cutoff and then lost thousands to the
// clock lost far more to the clock; blaming the cutoff hides the number that
// would change the outcome.
const out = describeCommitOutcome(5000, 100, "--verbose", true, 7);
if (out.kind === "ok") throw new Error("expected a message");
expect(out.message).toContain("Raise IX_MAP_DEADLINE_MS");
expect(out.message).not.toContain("never sent");
});
});
describe("describeCommitOutcome when both the cutoff and the deadline fired", () => {
it("names the cutoff's share instead of blaming the clock for all of it", () => {
// 200 patches withheld from a refusing backend, then 3 more lost to the
// clock. Reporting all 203 as "abandoned when the map deadline fired ...
// raise IX_MAP_DEADLINE_MS" is the wrong remedy for 200 of them, and it
// contradicts the banner above, which names the split.
const out = describeCommitOutcome(203, 50, "--verbose", true, 200);
if (out.kind === "ok") throw new Error("expected a message");
expect(out.message).toContain("3 of 253 file patches were abandoned when the map deadline fired");
expect(out.message).toContain("200 more were withheld earlier by the commit cutoff");
expect(out.message).toContain("see the cutoff above");
});
it("keeps the plain wording when the cutoff withheld nothing", () => {
const out = describeCommitOutcome(3, 50, "--verbose", true, 0);
if (out.kind === "ok") throw new Error("expected a message");
expect(out.message).toContain("3 of 53 file patches were abandoned when the map deadline fired");
expect(out.message).not.toContain("withheld earlier");
});
});
describe("describeCommitOutcome with a commit cutoff", () => {
it("points at the cutoff even when the drain placed every held patch", () => {
// The cutoff fired, so the banner above has already named the endpoint and
// quoted the backend's error -- but nothing was left unsent, and gating on
// that count sent the reader to the generic "Re-run with --debug to see
// why" directly beneath a message that had just told them why. The 12-file
// reproduction at the default limit lands here: five fan-out failures trip
// it, the drain sends the remaining seven, none are "never sent".
const out = describeCommitOutcome(12, 0, "--debug", false, 0, true);
expect(out.kind).toBe("fatal");
if (out.kind === "ok") throw new Error("expected a message");
expect(out.message).toContain("See the cutoff above");
expect(out.message).not.toContain("never sent");
// And it must still point AT the flag here. Every one of these errors came
// from a patch that was sent and did emit a per-file line, so the sibling
// message's "the flag will not add to it" -- true when patches were held
// back unsent -- would steer the reader away from the only detail there is.
expect(out.message).toContain("--debug lists the individual failures");
expect(out.message).not.toContain("will not add to it");
});
it("still names the unsent count when there is one", () => {
const out = describeCommitOutcome(12, 0, "--debug", false, 3, true);
if (out.kind === "ok") throw new Error("expected a message");
expect(out.message).toContain("3 of them never sent");
});
it("points at the cutoff instead of a flag that would show nothing", () => {
// The cutoff has already printed the endpoint, the streak and the error. A
// patch that was never sent produces no per-file line, so the usual advice
// sends the reader to --verbose for output that does not exist.
const out = describeCommitOutcome(20, 0, "--verbose", false, 15);
expect(out.kind).toBe("fatal");
if (out.kind === "ok") throw new Error("expected a message");
expect(out.message).toContain("15 of them never sent");
expect(out.message).toContain("See the cutoff above");
expect(out.message).not.toContain("to see why");
});
it("warns rather than fails when some patches landed first", () => {
const out = describeCommitOutcome(15, 40, "--verbose", false, 15);
expect(out.kind).toBe("warn");
});
it("leaves the ordinary messages alone when nothing was cut off", () => {
const none = describeCommitOutcome(3, 0, "--verbose", false, 0);
const some = describeCommitOutcome(3, 10, "--verbose", false, 0);
expect(none.kind).toBe("fatal");
expect(some.kind).toBe("warn");
if (none.kind !== "ok") expect(none.message).toContain("Ingest committed nothing");
if (some.kind !== "ok") expect(some.message).toContain("Re-run 'ix map' to retry");
});
});
describe("describeStitchFailure", () => {
it("reports incomplete cross-repository relationships without dumping an HTML response", () => {
const message = describeStitchFailure(new Error("504: <html>\nlarge proxy response"));
expect(message).toContain("Cross-workspace stitch failed");
expect(message).toContain("HTTP 504");
expect(message).toContain("cross-repository relationships may be incomplete");
expect(message).not.toContain("large proxy response");
});
it("does not read a three-digit run elsewhere in the message as a status", () => {
expect(describeStitchFailure(new Error("connect ECONNREFUSED 127.0.0.1:8090")))
.toContain("backend request failed");
});
});
describe("shouldPrintStitchSkipped", () => {
// Ix#620. `run-errors` computed a message and then never printed it, on the
// grounds that the run had "already said so". It had not: the line it
// deferred to reports that the graph is missing THOSE FILES and says to
// re-run `ix map` -- while what was actually withheld is the whole
// workspace's cross-workspace registration, and a plain re-run is
// incremental, lands on the silent `incomplete` branch, and never recovers
// it. Measured: one commit error in 2,067 patches cost a 2,066-file
// workspace every cross-repo edge it had, on a run that exited 0.
it("prints for run-errors", () => {
expect(shouldPrintStitchSkipped("run-errors", false)).toBe(true);
});
// The other half of the rule, and the reason this is not just "print
// everything": `incomplete` fires on nearly every incremental map, so it is
// the steady state rather than an event.
it("stays silent for incomplete", () => {
expect(shouldPrintStitchSkipped("incomplete", false)).toBe(false);
});
it("prints for every other refusal", () => {
for (const rule of ["lost-parses", "run-errors", "cooling", "in-flight", "deadline"] as const) {
expect(shouldPrintStitchSkipped(rule, false), rule).toBe(true);
}
});
// `ix map` passes suppressOutput and is deliberately one terse line per run.
// The machine token still carries the rule, so nothing is lost by staying
// quiet here -- including for the rule this issue made loud.
it("never prints under --silent, not even for run-errors", () => {
for (const rule of ["run-errors", "lost-parses", "incomplete", "deadline"] as const) {
expect(shouldPrintStitchSkipped(rule, true), rule).toBe(false);
}
});
});
describe("describeStitchSkipped", () => {
const cooling = "the last stitch was cut off after 62s and may still be running";
const contended = "another ix run is already stitching http://localhost:8090";
// Ix#620. `run-errors` was the one rule that computed a message and then
// never printed it, on the grounds that the run had "already said so". The
// line it was deferring to says the graph is missing THOSE FILES and tells
// the user to re-run `ix map` — neither of which is true of the stitch: the
// whole workspace's registration is withheld, and a plain re-run is
// incremental, lands on the silent `incomplete` branch, and never recovers
// it. So the text has to name the consequence and name `--force`.
it("names the registration and the only remedy that recovers it (run-errors)", () => {
const msg = describeStitchSkipped(
"this run had parse or commit errors, so its registration would be built from an incomplete picture of the repo",
"run-errors",
);
expect(msg.startsWith("Note:")).toBe(true);
// Not "those files" — the thing withheld is the cross-workspace registration.
expect(msg).toContain("Cross-workspace stitch not started");
// `ix map` alone does NOT get back in; only a forced re-ingest does.
expect(msg).toContain("--force");
});
it("is a Note, not a failure, and leads with the reason", () => {
const msg = describeStitchSkipped(cooling, "cooling");
expect(msg.startsWith("Note:")).toBe(true);
expect(msg).not.toContain("Warning");
expect(msg).toContain(cooling);
});
it("stays short by default, but still carries a remedy that works", () => {
// 15 minutes of auto-map hooks, one Note each, so the long form's three
// sentences of unchanging advice were too much. But the reason alone is not
// enough either: waiting the cooldown out and re-running does NOT recover,
// because the mtime baseline is already written and the next map never
// enters the stitch block. The one thing that does has to be in the short
// form.
const msg = describeStitchSkipped(cooling, "cooling");
expect(msg.length).toBeLessThan(260);
expect(msg).toContain("ix ingest <root> --force");
expect(msg).not.toContain("Source patches were committed");
});
it("offers the plain re-run FIRST on contention, but still names --force", () => {
// --verbose is off by default, so this is the advice almost everyone sees,
// and it has to be both true and proportionate. The other run may be
// registering this same workspace and finishing a second later, so a forced
// monorepo re-ingest is the wrong thing to lead with -- but a plain re-run
// ALONE was a promise this code cannot keep: a skipped stitch does not stop
// the run persisting its mtime baseline, so the re-run is incremental and
// never reaches the stitch block. It prints nothing and exits 0.
const msg = describeStitchSkipped(contended, "in-flight");
expect(msg).toContain("Re-run once that finishes");
expect(msg).toContain("--force");
expect(msg.indexOf("Re-run")).toBeLessThan(msg.indexOf("--force"));
});
it("names --force on the deadline rule too, since a longer budget alone does not register", () => {
const msg = describeStitchSkipped("the map ran out of time", "deadline");
expect(msg).toContain("IX_MAP_DEADLINE_MS");
expect(msg).toContain("--force");
const verbose = describeStitchSkipped("the map ran out of time", "deadline", true);
expect(verbose).toContain("nothing was registered either");
expect(verbose).toContain("--force");
});
it("gives the remedy under --verbose, and picks it by RULE", () => {
const cool = describeStitchSkipped(cooling, "cooling", true);
expect(cool).toContain("Once the cooldown expires");
expect(cool).toContain("ix ingest <root> --force");
expect(cool).toContain("Source patches were committed");
const busy = describeStitchSkipped(contended, "in-flight", true);
expect(busy).toContain("may be registering a different workspace");
expect(busy).not.toContain("Once the cooldown expires");
});
});
describe("isStitchUnsupported", () => {
it.each([404, 501])("treats %d as a backend that does not implement stitch", (status) => {
expect(isStitchUnsupported(new Error(`${status}: Not Found`))).toBe(true);
});
it.each([500, 502, 504])("treats %d as a real failure worth surfacing", (status) => {
expect(isStitchUnsupported(new Error(`${status}: upstream timeout`))).toBe(false);
});
it("treats a transport error with no status as a real failure", () => {
expect(isStitchUnsupported(new Error("connect ECONNREFUSED 127.0.0.1:8090"))).toBe(false);
});
});