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 { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { createServer, type Server, type ServerResponse } from "node:http";
import type { AddressInfo } from "node:net";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { execFileSync } from "node:child_process";
import { createHash } from "node:crypto";
import { Command } from "commander";
import { registerMapCommand } from "../commands/map.js";
import { canonicalWorkspacePath, mapResultCachePath, mapStalePath } from "../config.js";
import {
clearMapStale,
ensureFreshMap,
ensureFreshMapState,
MAP_REFRESH_ARG,
mapBackgroundRefreshEnabled,
mapBackgroundTimeoutMs,
mapRefreshDebounceMs,
mapRefreshInvocation,
mapStaleJson,
markMapStale,
readMapRefreshOutcome,
readMapStale,
runBackgroundMapRefresh,
type MapRefreshOutcome,
} from "../map-freshness.js";
import { acquireMapLock, lockPathForTest, mapLockHeld, requestMapRerun, takeMapRerun } from "../single-flight.js";
import { hasCompletedMapBaseline } from "../stale.js";
import { registerRemoteRunner } from "../remote.js";
/**
* The lazy half of a deferred `ix map` (CL-13). These drive the real `ix map`
* against a fake backend to get a deferred map, then check the two halves:
*
* - `ensureFreshMap`, run by every region view: never maps inline, answers
* at once, and starts at most one background refresh (the spawner is
* injected; no test starts a real process);
* - `runBackgroundMapRefresh`, what that detached process runs: at most one
* `/v1/map` under the map lock, the outcome recorded, and never the
* caller's exit code.
*/
/** A backend that answers what `ix map` and a refresh touch, and records the paths. */
class FakeBackend {
readonly requests: string[] = [];
readonly unknownPaths: string[] = [];
rev = 0;
/** uri -> the row `/v1/source-hashes` answers with. */
readonly hashes = new Map<string, { workspaceId: string | null; uri: string; hash: string }>();
/** The status `/v1/map` answers with; 200 serves a map. */
mapStatus = 200;
/** Delay before `/v1/map` answers, in ms. */
mapDelayMs = 0;
/** The outcome a 200 from `/v1/map` reports. */
mapOutcome = "full_local_completed";
/** Answer `/v1/map` with an empty map: no files, no regions. */
emptyMap = false;
/** Run when `/v1/map` is asked, before it answers. */
onMap: (() => void) | undefined;
private readonly patches = new Map<string, unknown[]>();
private server: Server | undefined;
mapRequests(): number {
return this.requests.filter(p => p === "/v1/map").length;
}
async start(): Promise<string> {
this.server = createServer((req, res) => {
const chunks: Buffer[] = [];
req.on("data", (c: Buffer) => chunks.push(c));
req.on("end", () => this.route(req.url ?? "/", Buffer.concat(chunks).toString("utf8"), res));
});
await new Promise<void>((resolve, reject) => {
this.server!.once("error", reject);
this.server!.listen(0, "127.0.0.1", resolve);
});
return `http://127.0.0.1:${(this.server!.address() as AddressInfo).port}`;
}
async stop(): Promise<void> {
if (!this.server) return;
const server = this.server;
server.closeAllConnections();
await new Promise<void>(resolve => server.close(() => resolve()));
}
private route(url: string, body: string, res: ServerResponse): void {
const path = new URL(url, "http://x").pathname;
this.requests.push(path);
const send = (code: number, payload: unknown): void => {
if (res.writableEnded) return;
res.writeHead(code, { "Content-Type": "application/json" });
res.end(JSON.stringify(payload));
};
if (path === "/v1/patches/bulk" || path === "/v1/patch") {
type SentPatch = { patchId?: string; source?: { uri?: string; sourceHash?: string; workspaceId?: string }; intent?: string; ops?: unknown[] };
let patches: SentPatch[] = [];
try {
const parsed = JSON.parse(body) as { patches?: SentPatch[] };
patches = parsed.patches ?? [parsed as SentPatch];
} catch { /* a body we cannot read is still a request */ }
this.rev += patches.length || 1;
for (const { patchId, source, intent, ops } of patches) {
if (patchId) this.patches.set(patchId, ops ?? []);
if (!source?.uri) continue;
if (intent?.startsWith("Deleted ")) this.hashes.delete(source.uri);
else if (source.sourceHash) {
this.hashes.set(source.uri, { workspaceId: source.workspaceId ?? null, uri: source.uri, hash: source.sourceHash });
}
}
return send(200, path === "/v1/patches/bulk"
? { rev: this.rev, applied: patches.length, status: "Ok" }
: { rev: this.rev, status: "Ok" });
}
if (path === "/v1/health") return send(200, { status: "ok", schema_version: 3, release_version: "1.0.30" });
if (path === "/v1/revisions/current") return send(200, this.rev);
if (path === "/v1/source-hashes") {
let uris: string[] = [];
try { uris = (JSON.parse(body) as { uris?: string[] }).uris ?? []; } catch { /* none */ }
return send(200, uris.filter(u => this.hashes.has(u)).map(u => this.hashes.get(u)));
}
// A changed file reconciles against the patch it replaces.
if (path.startsWith("/v1/patches/")) {
const ops = this.patches.get(decodeURIComponent(path.slice("/v1/patches/".length)));
return ops ? send(200, { data: { ops } }) : send(404, { error: "Patch not found" });
}
if (path.startsWith("/v1/entity/")) return send(200, { node: { kind: "function" }, edges: [] });
if (path.startsWith("/v1/stitch/system/")) return send(200, { systemId: null });
if (path === "/v1/stitch") return send(200, { stitched: 0, systemId: null, edges: [] });
if (path === "/v1/map") {
const hook = this.onMap;
this.onMap = undefined;
hook?.();
const answer = (): void => {
if (this.mapStatus !== 200) return send(this.mapStatus, { error: "map failed" });
const files = this.emptyMap ? 0 : this.hashes.size;
send(200, {
file_count: files,
region_count: this.emptyMap ? 0 : 1,
levels: 1,
map_rev: this.rev,
outcome: this.mapOutcome,
regions: this.emptyMap ? [] : [{
id: "r-mod", label: `Module of ${files}`, label_kind: "module", level: 1, file_count: files,
child_region_count: 0, parent_id: null, cohesion: 0.5, external_coupling: 0.1, boundary_ratio: 1,
confidence: 0.8, crosscut_score: 0, dominant_signals: ["imports"], interface_node_count: 0,
}],
edges: [],
hierarchy: [],
});
};
if (this.mapDelayMs > 0) setTimeout(answer, this.mapDelayMs);
else answer();
return;
}
this.unknownPaths.push(path);
return send(404, { error: `404: no such endpoint ${path}` });
}
}
const hashOf = (text: string) => createHash("sha256").update(Buffer.from(text, "utf8")).digest("hex");
describe("map refresh", () => {
vi.setConfig({ testTimeout: 60_000, hookTimeout: 30_000 });
let home = "";
let repo = "";
let backend: FakeBackend;
const saved: Record<string, string | undefined> = {};
/** Run `ix map <repo> --silent` in-process. */
async function map(...args: string[]): Promise<void> {
const write = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
const error = vi.spyOn(console, "error").mockImplementation(() => {});
const log = vi.spyOn(console, "log").mockImplementation(() => {});
try {
const program = new Command();
registerMapCommand(program);
await program.parseAsync(["node", "ix", "map", repo, "--silent", ...args]);
} finally {
write.mockRestore();
error.mockRestore();
log.mockRestore();
// Released on process exit, which an in-process run never reaches.
rmSync(lockPathForTest(repo), { force: true });
}
expect(process.exitCode ?? 0).toBe(0);
}
/**
* A mapped repo whose last `ix map` deferred the map after an edit: an
* automatic one (IX_AUTO_MAP=1, as the hooks run it), since only those defer.
*/
async function deferred(): Promise<void> {
await map();
writeFileSync(join(repo, "src", "m9.ts"), "export const nine = 9;\n", "utf8");
process.env.IX_AUTO_MAP = "1";
try { await map(); } finally { delete process.env.IX_AUTO_MAP; }
expect(readMapStale(repo), "the edit's map was deferred").not.toBeNull();
backend.requests.length = 0;
}
/** Captures stdout and stderr around `fn`. */
async function captured<T>(fn: () => Promise<T>): Promise<{ value: T; out: string; err: string }> {
const out: string[] = [];
const err: string[] = [];
const log = vi.spyOn(console, "log").mockImplementation((...a: unknown[]) => { out.push(a.map(String).join(" ")); });
const write = vi.spyOn(process.stdout, "write").mockImplementation((chunk: unknown) => { out.push(String(chunk)); return true; });
const ewrite = vi.spyOn(process.stderr, "write").mockImplementation((chunk: unknown) => { err.push(String(chunk)); return true; });
try {
const value = await fn();
return { value, out: out.join(""), err: err.join("") };
} finally {
log.mockRestore();
write.mockRestore();
ewrite.mockRestore();
}
}
/** Roots the injected spawner was asked to refresh. */
let spawned: string[] = [];
/** What the injected spawner does besides recording; nothing by default. */
let onSpawn: (root: string) => void = () => {};
/** A region view's `ensureFreshMap` for the fixture. */
async function read(now?: () => number) {
const r = await captured(() => ensureFreshMap({
root: repo,
now,
spawn: (root) => { spawned.push(root); onSpawn(root); },
}));
return { stale: r.value, out: r.out, err: r.err };
}
/** The detached child's work, run in-process. */
async function child(opts: Parameters<typeof runBackgroundMapRefresh>[1] = {}) {
const r = await captured(() => runBackgroundMapRefresh(repo, opts));
return { outcome: r.value, out: r.out, err: r.err };
}
beforeEach(async () => {
backend = new FakeBackend();
spawned = [];
onSpawn = () => {};
home = realpathSync(mkdtempSync(join(tmpdir(), "ix-freshness-home-")));
repo = realpathSync(mkdtempSync(join(tmpdir(), "ix-freshness-repo-")));
const endpoint = await backend.start();
for (const k of [
"HOME", "USERPROFILE", "IX_HOME", "IX_ENDPOINT", "IX_LOCK_DIR", "IX_AUTO_MAP", "IX_MAP_EAGER",
"IX_MAP_FULL_INGEST", "IX_MAP_DEADLINE_MS", "IX_MAP_REFRESH_DEBOUNCE_MS",
"IX_MAP_BACKGROUND_REFRESH", "IX_MAP_BACKGROUND_TIMEOUT_MS",
"IX_STITCH_COOLDOWN_MS", "IX_STITCH_WAIT_MS",
]) {
saved[k] = process.env[k];
delete process.env[k];
}
process.env.HOME = home;
process.env.USERPROFILE = home;
process.env.IX_HOME = join(home, ".ix");
process.env.IX_ENDPOINT = endpoint;
process.env.IX_LOCK_DIR = join(home, "locks");
mkdirSync(join(repo, "src"), { recursive: true });
for (let i = 0; i < 3; i++) {
writeFileSync(join(repo, "src", `m${i}.ts`), `export function f${i}(): number { return ${i}; }\n`, "utf8");
}
execFileSync("git", ["init", "-q"], { cwd: repo, stdio: "ignore" });
execFileSync("git", ["add", "-A"], { cwd: repo, stdio: "ignore" });
});
afterEach(async () => {
try {
expect(backend.unknownPaths, "endpoints the fake does not implement").toEqual([]);
} finally {
process.exitCode = undefined;
await backend.stop();
for (const [k, v] of Object.entries(saved)) {
if (v === undefined) delete process.env[k];
else process.env[k] = v;
}
for (const dir of [home, repo]) if (dir) rmSync(dir, { recursive: true, force: true });
home = "";
repo = "";
}
});
describe("ensureFreshMap (the reader)", () => {
it("reports the map its regions are from, as the deferred ix map named it", async () => {
await map();
writeFileSync(join(repo, "src", "m9.ts"), "export const nine = 9;\n", "utf8");
process.env.IX_AUTO_MAP = "1";
let shown: { map_stale: boolean; regions_as_of: { map_rev: number; file_count: number } | null };
try {
const r = await captured(async () => {
const program = new Command();
registerMapCommand(program);
await program.parseAsync(["node", "ix", "map", repo, "--format", "json"]);
});
shown = JSON.parse(r.out);
} finally {
delete process.env.IX_AUTO_MAP;
rmSync(lockPathForTest(repo), { force: true });
}
expect(shown.map_stale, "the edit's map was deferred").toBe(true);
expect(shown.regions_as_of).not.toBeNull();
expect(readMapStale(repo)?.regionsAsOf, "the marker names the same map").toEqual(shown.regions_as_of);
const r = await captured(() => ensureFreshMapState({ root: repo, spawn: () => {} }));
expect(r.value).toEqual({ mapStale: true, regionsAsOf: shown.regions_as_of });
expect(mapStaleJson(r.value)).toEqual({ map_stale: true, regions_as_of: shown.regions_as_of });
expect(r.out, "nothing on stdout").toBe("");
expect(readMapStale(repo)?.regionsAsOf, "recording the attempt keeps it").toEqual(shown.regions_as_of);
});
it("keeps the map a standing marker names when re-marked, and forgets it once the map is computed", () => {
markMapStale(repo, { ingestRev: 1, regionsAsOf: { map_rev: 4, file_count: 3 } });
markMapStale(repo, { ingestRev: 2 });
expect(readMapStale(repo)?.regionsAsOf).toEqual({ map_rev: 4, file_count: 3 });
clearMapStale(repo);
markMapStale(repo, { ingestRev: 3 });
expect(readMapStale(repo)).not.toBeNull();
expect(readMapStale(repo)?.regionsAsOf).toBeUndefined();
});
it("says nothing in the json fields when the map is fresh", async () => {
await map();
const r = await captured(() => ensureFreshMapState({ root: repo, spawn: () => {} }));
expect(r.value).toEqual({});
expect(mapStaleJson(r.value)).toEqual({});
});
it("makes no request and starts nothing without a marker", async () => {
await map();
backend.requests.length = 0;
const r = await read();
expect(r.stale).toBe(false);
expect(r.err).toBe("");
expect(backend.requests).toEqual([]);
expect(spawned).toEqual([]);
});
it("answers at once, maps nothing inline, and starts one background refresh", async () => {
await deferred();
const r = await read(() => 1_000_000);
expect(r.stale).toBe(true);
expect(r.out, "nothing on stdout").toBe("");
expect(backend.mapRequests(), "no /v1/map from the reader").toBe(0);
// The canonical root, which on Windows CI is the long form of the
// 8.3 temp path (RUNNER~1) that `realpathSync` leaves as it is.
expect(spawned).toEqual([canonicalWorkspacePath(repo)]);
expect(r.err).toBe("ix: architecture map is stale (refreshing in background); regions shown may predate recent edits. Run ix map --remap to refresh.\n");
expect(readMapStale(repo)?.lastAttemptAt, "the start is recorded for the debounce").toBe(1_000_000);
expect(mapLockHeld(repo), "the reader does not keep the lock").toBe(false);
});
it("returns without waiting for the refresh it started", async () => {
await deferred();
// A map slower than any hook budget, run as the child would run it.
backend.mapDelayMs = 3_000;
let running: Promise<unknown> | undefined;
onSpawn = (root) => { running = runBackgroundMapRefresh(root); };
const t0 = Date.now();
const r = await read();
const took = Date.now() - t0;
expect(r.stale).toBe(true);
expect(took, "the reader did not wait for the 3 s map").toBeLessThan(2_000);
expect(readMapStale(repo), "the refresh has not finished yet").not.toBeNull();
// Meanwhile another reader sees the refresh holding the lock.
await new Promise(resolve => setTimeout(resolve, 200));
const second = await read(() => Date.now() + 60_000);
expect(second.err).toMatch(/\(another ix map is running\)/);
expect(spawned, "and starts no second one").toHaveLength(1);
const outcome = await running as MapRefreshOutcome;
expect(outcome.ok).toBe(true);
expect(readMapStale(repo), "it cleared the marker").toBeNull();
expect(hasCompletedMapBaseline(repo)).toBe(true);
expect(backend.mapRequests()).toBe(1);
});
it("starts no refresh inside the debounce window, and one after it", async () => {
await deferred();
let clock = 1_000_000;
const now = () => clock;
await read(now);
expect(spawned).toHaveLength(1);
clock += 10_000;
const debounced = await read(now);
expect(spawned, "within 30 s of the start").toHaveLength(1);
expect(debounced.stale).toBe(true);
expect(debounced.err).toMatch(/^ix: architecture map is stale \(a refresh was tried moments ago\)/);
clock += 30_000;
await read(now);
expect(spawned, "after the window").toHaveLength(2);
expect(backend.mapRequests()).toBe(0);
});
it("starts no refresh while another process holds the map lock, and keeps the marker", async () => {
await deferred();
const marker = readMapStale(repo);
const holder = acquireMapLock(repo, "holder")!;
let r;
try {
r = await read();
} finally {
holder.release();
}
expect(spawned).toEqual([]);
expect(backend.requests).toEqual([]);
expect(readMapStale(repo)).toEqual(marker);
expect(r.stale).toBe(true);
expect(r.err).toMatch(/^ix: architecture map is stale \(another ix map is running\)/);
expect(r.err.trim().split("\n"), "one line").toHaveLength(1);
});
it("says why when the last background refresh failed and the retry is debounced", async () => {
await deferred();
backend.mapStatus = 500;
await child({ now: () => 1_000_000 });
const r = await read(() => 1_000_000 + 5_000);
expect(spawned).toEqual([]);
expect(r.err).toMatch(/^ix: architecture map is stale \(its last background refresh failed\)/);
});
it("never refreshes with IX_MAP_BACKGROUND_REFRESH=0, and says the map is stale", async () => {
await deferred();
process.env.IX_MAP_BACKGROUND_REFRESH = "0";
const r = await read();
expect(spawned).toEqual([]);
expect(backend.requests).toEqual([]);
expect(r.stale).toBe(true);
expect(r.err).toMatch(/^ix: architecture map is stale \(background refresh is off\)/);
expect(readMapStale(repo)?.lastAttemptAt, "nothing was attempted").toBeUndefined();
});
it("never throws or sets an exit code when the refresh cannot start", async () => {
await deferred();
onSpawn = () => { throw new Error("EAGAIN"); };
process.exitCode = undefined;
const r = await read();
expect(r.stale).toBe(true);
expect(r.err).toMatch(/\(its refresh could not start\)/);
expect(process.exitCode).toBeUndefined();
});
it("reads the marker again under the lock, and starts nothing for a map just refreshed", async () => {
await deferred();
const seen = readMapStale(repo)!;
writeFileSync(mapStalePath(repo), JSON.stringify({ ...seen, lastAttemptAt: 1 }));
// Between this reader's first look and its taking the lock, a refresh
// finishes and removes the marker. The debounce reads the clock at that
// first look, so the race is staged there.
let calls = 0;
const r = await read(() => {
if (calls++ === 0) rmSync(mapStalePath(repo), { force: true });
return 1_000_000;
});
expect(spawned).toEqual([]);
expect(r.stale).toBe(false);
expect(r.err).toBe("");
});
it("starts nothing for a workspace fed by a cloud runner", async () => {
await deferred();
registerRemoteRunner({ runIngestion: async () => {}, isReady: async () => true });
try {
await read();
} finally {
registerRemoteRunner({ runIngestion: async () => {}, isReady: async () => false });
}
expect(spawned).toEqual([]);
expect(backend.requests).toEqual([]);
expect(readMapStale(repo)).not.toBeNull();
});
it("treats a malformed marker as none", async () => {
await map();
mkdirSync(join(home, ".ix"), { recursive: true });
writeFileSync(mapStalePath(repo), "{not json");
expect(readMapStale(repo)).toBeNull();
writeFileSync(mapStalePath(repo), JSON.stringify({ since: "yesterday", ingestRev: 1 }));
expect(readMapStale(repo)).toBeNull();
backend.requests.length = 0;
await read();
expect(backend.requests).toEqual([]);
expect(spawned).toEqual([]);
});
});
describe("runBackgroundMapRefresh (the detached child)", () => {
it("maps once when the marker is set, records the map, clears the marker and the outcome", async () => {
await deferred();
expect(hasCompletedMapBaseline(repo)).toBe(false);
rmSync(mapResultCachePath(repo), { force: true });
const r = await child();
expect(r.out, "nothing on stdout").toBe("");
expect(backend.mapRequests()).toBe(1);
expect(readMapStale(repo)).toBeNull();
expect(hasCompletedMapBaseline(repo), "the map baseline is saved").toBe(true);
expect(existsSync(mapResultCachePath(repo)), "the result is stored").toBe(true);
expect(r.outcome).toMatchObject({ ok: true, pid: process.pid });
expect(readMapRefreshOutcome(repo)).toEqual(r.outcome);
expect(mapLockHeld(repo), "the lock is let go").toBe(false);
expect((await child()).outcome, "a second run is a no-op").toBeNull();
expect(backend.mapRequests()).toBe(1);
// And the next unchanged `ix map` reuses it rather than asking.
await map();
expect(backend.mapRequests()).toBe(1);
});
it("refreshes a root named under another spelling of the same directory", async () => {
// Windows CI names the temp dir C:\Users\RUNNER~1\... (an 8.3 short name),
// while `ix map` stores the long, canonical root in its baselines. A
// junction (a symlink on POSIX) is the same mismatch on any platform.
await deferred();
const alias = join(home, "repo-alias");
symlinkSync(repo, alias, "junction");
expect(hasCompletedMapBaseline(alias), "an alias reads the same ingest baseline").toBe(false);
const outcome = await runBackgroundMapRefresh(alias);
expect(backend.mapRequests()).toBe(1);
expect(outcome?.ok).toBe(true);
expect(readMapStale(repo)).toBeNull();
expect(hasCompletedMapBaseline(repo)).toBe(true);
expect(hasCompletedMapBaseline(alias), "and the alias sees the map as complete").toBe(true);
});
it("does nothing while another process holds the map lock", async () => {
await deferred();
const marker = readMapStale(repo);
const holder = acquireMapLock(repo, "holder")!;
try {
expect((await child()).outcome).toBeNull();
} finally {
holder.release();
}
expect(backend.requests).toEqual([]);
expect(readMapStale(repo)).toEqual(marker);
expect(readMapRefreshOutcome(repo)).toBeNull();
});
for (const [what, setUp, reason] of [
["a map whose outcome is not a completed one", (b: FakeBackend) => { b.mapOutcome = "partial"; }, /the map did not complete: outcome partial/],
["an empty map", (b: FakeBackend) => { b.emptyMap = true; }, /the map did not complete/],
] as const) {
it(`leaves the stored map, the baseline and the marker as they were after ${what}`, async () => {
await deferred();
const marker = readMapStale(repo)!;
const stored = readFileSync(mapResultCachePath(repo), "utf8");
setUp(backend);
process.exitCode = undefined;
const r = await child();
expect(r.out).toBe("");
expect(backend.mapRequests()).toBe(1);
expect(process.exitCode).toBeUndefined();
const kept = readMapStale(repo);
expect(kept, "the marker stays").not.toBeNull();
expect(kept?.since).toBe(marker.since);
expect(kept?.ingestRev).toBe(marker.ingestRev);
expect(readFileSync(mapResultCachePath(repo), "utf8"), "the last map is still stored").toBe(stored);
expect(hasCompletedMapBaseline(repo), "no completed map is claimed").toBe(false);
expect(r.outcome?.ok).toBe(false);
expect(r.outcome?.reason).toMatch(reason);
expect(readMapRefreshOutcome(repo)).toEqual(r.outcome);
});
}
it("records a failed request, never throws or sets an exit code, and keeps the marker", async () => {
await deferred();
const since = readMapStale(repo)!.since;
backend.mapStatus = 500;
process.exitCode = undefined;
const r = await child();
expect(process.exitCode).toBeUndefined();
expect(readMapStale(repo)?.since).toBe(since);
expect(r.outcome?.ok).toBe(false);
expect(r.outcome?.reason).toMatch(/^the map request failed: /);
expect(r.outcome?.reason, "one line").not.toContain("\n");
});
it("stops at its hard time limit, records why, and lets the lock go", async () => {
await deferred();
backend.mapDelayMs = 5_000;
process.exitCode = undefined;
const t0 = Date.now();
const r = await child({ timeoutMs: 300 });
expect(Date.now() - t0).toBeLessThan(3_000);
expect(r.outcome).toMatchObject({ ok: false, reason: "timed out after 0.3 s" });
expect(readMapStale(repo), "the marker stays").not.toBeNull();
expect(mapLockHeld(repo)).toBe(false);
expect(process.exitCode).toBeUndefined();
});
it("keeps a marker that was re-written while it mapped", async () => {
await deferred();
backend.onMap = () => markMapStale(repo, { since: Date.now() + 1, ingestRev: 999 });
const r = await child();
expect(backend.mapRequests()).toBe(1);
expect(readMapStale(repo)?.ingestRev, "a newer ingest's marker stays").toBe(999);
expect(r.outcome).toMatchObject({ ok: true, reason: expect.stringMatching(/files changed while it was refreshed/) });
});
it("runs a coalesced map's rerun request and re-marks the map stale", async () => {
await deferred();
const late = "export const late = 2;\n";
// An edit lands mid-refresh and its own `ix map` coalesces into the lock.
backend.onMap = () => {
writeFileSync(join(repo, "src", "m2.ts"), late, "utf8");
requestMapRerun(repo);
};
process.exitCode = undefined;
await child();
expect(backend.mapRequests(), "the refresh asked once").toBe(1);
expect(backend.hashes.get("src/m2.ts")?.hash, "the late edit reached the backend").toBe(hashOf(late));
expect(readMapStale(repo), "the edit's map is deferred in turn").not.toBeNull();
expect(takeMapRerun(repo), "and the request consumed").toBe(false);
expect(process.exitCode).toBeUndefined();
});
});
});
describe("mapRefreshInvocation", () => {
it("starts the same Node and CLI entry, detached, with no shell, no stdio and no window", async () => {
const inv = await mapRefreshInvocation("/w/repo", "/opt/ix/dist/cli/main.js", ["--inspect"]);
expect(inv.command).toBe(process.execPath);
expect(inv.args, "debugger flags are not cloned").toEqual(["/opt/ix/dist/cli/main.js", MAP_REFRESH_ARG, "/w/repo"]);
expect(inv.options).toMatchObject({ cwd: "/w/repo", detached: true, stdio: "ignore", windowsHide: true, shell: false });
});
it("keeps the source loader of a TypeScript entry", async () => {
const inv = await mapRefreshInvocation("/w/repo", "/src/cli/main.ts", ["--import", "tsx"]);
expect(inv.args).toEqual(["--import", "tsx", "/src/cli/main.ts", MAP_REFRESH_ARG, "/w/repo"]);
});
});
describe("refresh settings", () => {
it("mapRefreshDebounceMs defaults to 30 s, takes a plain number of ms, and 0 or empty for none", () => {
expect(mapRefreshDebounceMs(undefined)).toBe(30_000);
expect(mapRefreshDebounceMs("5000")).toBe(5_000);
expect(mapRefreshDebounceMs("0")).toBe(0);
expect(mapRefreshDebounceMs("")).toBe(0);
expect(mapRefreshDebounceMs("30s"), "not a number of ms keeps the default").toBe(30_000);
});
it("mapBackgroundRefreshEnabled is on unless set to 0", () => {
expect(mapBackgroundRefreshEnabled({})).toBe(true);
expect(mapBackgroundRefreshEnabled({ IX_MAP_BACKGROUND_REFRESH: "1" })).toBe(true);
expect(mapBackgroundRefreshEnabled({ IX_MAP_BACKGROUND_REFRESH: "0" })).toBe(false);
expect(mapBackgroundRefreshEnabled({ IX_MAP_BACKGROUND_REFRESH: " 0 " })).toBe(false);
});
it("mapBackgroundTimeoutMs defaults to 5 min and takes a plain positive number of ms", () => {
expect(mapBackgroundTimeoutMs(undefined)).toBe(300_000);
expect(mapBackgroundTimeoutMs("60000")).toBe(60_000);
expect(mapBackgroundTimeoutMs("0")).toBe(300_000);
expect(mapBackgroundTimeoutMs("5m")).toBe(300_000);
});
});