Skip to content

armgit / Ix

Public Imported from GitHub
0

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

fix(watch): refresh through canonical map ingestion (#421)

Hiro-Chibafef671cca4e9
diff --git a/ix-cli/src/cli/__tests__/map-auto-skip.test.ts b/ix-cli/src/cli/__tests__/map-auto-skip.test.ts
index 8e1861dd..4ef148db 100644
--- a/ix-cli/src/cli/__tests__/map-auto-skip.test.ts
+++ b/ix-cli/src/cli/__tests__/map-auto-skip.test.ts
@@ -1,5 +1,17 @@
-import { afterEach, describe, expect, it } from 'vitest';
-import { shouldSkipAutoMap } from '../commands/map.js';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { hostname } from 'node:os';
+import { Command } from 'commander';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+ applyRequestedMapCoalesceExitCode,
+ mapModeForIngest,
+ registerMapCommand,
+ requestedMapCoalesceExitCode,
+ shouldSkipAutoMap,
+} from '../commands/map.js';
+import { lockPathForTest } from '../single-flight.js';
describe('shouldSkipAutoMap', () => {
afterEach(() => { delete process.env.IX_AUTO_MAP_CLOUD; });
@@ -21,3 +33,63 @@ describe('shouldSkipAutoMap', () => {
expect(shouldSkipAutoMap({ auto: true, cloudReady: true })).toBe(false);
});
});
+
+describe('requestedMapCoalesceExitCode', () => {
+ it('accepts a private non-zero process exit code', () => {
+ expect(requestedMapCoalesceExitCode('75')).toBe(75);
+ });
+
+ it.each([undefined, '', '0', '256', '1.5', 'nope'])('ignores invalid value %s', value => {
+ expect(requestedMapCoalesceExitCode(value)).toBeUndefined();
+ });
+
+ it('applies the requested exit code on the map-lock coalesce path', () => {
+ let applied: number | undefined;
+
+ expect(applyRequestedMapCoalesceExitCode('75', code => { applied = code; })).toBe(true);
+ expect(applied).toBe(75);
+ });
+
+ it('preserves normal exit behavior when the private option is absent', () => {
+ const apply = vi.fn();
+
+ expect(applyRequestedMapCoalesceExitCode(undefined, apply)).toBe(false);
+ expect(apply).not.toHaveBeenCalled();
+ });
+
+ it('makes the real map action exit before ingest when its lock is contended', async () => {
+ const lockDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ix-map-coalesce-'));
+ const root = path.join(lockDir, 'workspace');
+ fs.mkdirSync(root);
+ process.env.IX_LOCK_DIR = lockDir;
+ process.env.IX_MAP_COALESCE_EXIT_CODE = '75';
+ fs.writeFileSync(lockPathForTest(root), JSON.stringify({
+ pid: process.pid,
+ host: hostname(),
+ startedAt: Date.now(),
+ label: 'held by test',
+ }));
+
+ try {
+ const program = new Command();
+ registerMapCommand(program);
+ await program.parseAsync(['node', 'ix', 'map', root, '--silent']);
+ expect(process.exitCode).toBe(75);
+ } finally {
+ process.exitCode = undefined;
+ delete process.env.IX_LOCK_DIR;
+ delete process.env.IX_MAP_COALESCE_EXIT_CODE;
+ fs.rmSync(lockDir, { recursive: true, force: true });
+ }
+ });
+});
+
+describe('mapModeForIngest', () => {
+ it('keeps ordinary map ingestion topology-only', () => {
+ expect(mapModeForIngest(undefined)).toBe(true);
+ });
+
+ it('lets watch request full canonical patches after the map lock is acquired', () => {
+ expect(mapModeForIngest('1')).toBe(false);
+ });
+});
diff --git a/ix-cli/src/cli/__tests__/watch-dedup.test.ts b/ix-cli/src/cli/__tests__/watch-dedup.test.ts
index 5eb30623..861da937 100644
--- a/ix-cli/src/cli/__tests__/watch-dedup.test.ts
+++ b/ix-cli/src/cli/__tests__/watch-dedup.test.ts
@@ -1,57 +1,277 @@
-import { describe, it, expect } from "vitest";
import * as fs from "node:fs";
import * as path from "node:path";
-import { readFileContent } from "../commands/watch-utils.js";
+import { spawnSync } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it, vi } from "vitest";
+import {
+ WatchRefreshScheduler,
+ canonicalMapInvocation,
+ childCliArgs,
+ mapRetryDelay,
+ prepareMigratedWorkspaceRefresh,
+ runCanonicalMap,
+ shouldWatch,
+ updatePollingSnapshot,
+} from "../commands/watch.js";
-const watchTsPath = path.resolve(__dirname, "../commands/watch.ts");
-const watchContent = fs.readFileSync(watchTsPath, "utf-8");
+describe("WatchRefreshScheduler", () => {
+ it("serializes refreshes and coalesces requests made while one is running", async () => {
+ let releaseFirst!: () => void;
+ const first = new Promise<void>((resolve) => {
+ releaseFirst = resolve;
+ });
+ let runs = 0;
+ let active = 0;
+ let maxActive = 0;
+ const refresh = vi.fn(async () => {
+ runs++;
+ active++;
+ maxActive = Math.max(maxActive, active);
+ if (runs === 1) await first;
+ active--;
+ });
+ const errors: unknown[] = [];
+ const scheduler = new WatchRefreshScheduler(refresh, (err) => errors.push(err));
-// ── Unit tests for readFileContent ──────────────────────────────────
+ scheduler.request();
+ scheduler.request();
+ scheduler.request();
+ expect(refresh).toHaveBeenCalledTimes(1);
-describe("readFileContent", () => {
- it("reads an existing file", () => {
- const result = readFileContent(watchTsPath);
- expect(result).not.toBeNull();
- expect(result).toContain("readFileContent");
+ releaseFirst();
+ await scheduler.waitForIdle();
+
+ expect(refresh).toHaveBeenCalledTimes(2);
+ expect(maxActive).toBe(1);
+ expect(errors).toEqual([]);
});
- it("returns null for non-existent file", () => {
- const result = readFileContent("/tmp/ix-test-nonexistent-file-abc123.ts");
- expect(result).toBeNull();
+ it("reports a failed refresh and remains usable", async () => {
+ const failure = new Error("backend rejected patch");
+ const refresh = vi.fn().mockRejectedValueOnce(failure).mockResolvedValueOnce(undefined);
+ const onError = vi.fn();
+ const scheduler = new WatchRefreshScheduler(refresh, onError);
+
+ scheduler.request();
+ await scheduler.waitForIdle();
+ scheduler.request();
+ await scheduler.waitForIdle();
+
+ expect(onError).toHaveBeenCalledWith(failure);
+ expect(refresh).toHaveBeenCalledTimes(2);
});
});
-// ── Source-reading: watch.ts watcher correctness ────────────────────
+describe("canonical watch refresh", () => {
+ it("keeps TypeScript runtime loaders without copying debugger flags", () => {
+ expect(
+ childCliArgs(
+ "/workspace/src/cli/main.ts",
+ ["--version"],
+ [
+ "--inspect=0",
+ "--require",
+ "/workspace/node_modules/tsx/dist/preflight.cjs",
+ "--import=file:///workspace/node_modules/tsx/dist/loader.mjs",
+ "--trace-warnings",
+ ],
+ ),
+ ).toEqual([
+ "--require",
+ "/workspace/node_modules/tsx/dist/preflight.cjs",
+ "--import=file:///workspace/node_modules/tsx/dist/loader.mjs",
+ "/workspace/src/cli/main.ts",
+ "--version",
+ ]);
+ });
-describe("watch.ts watcher correctness", () => {
- it("uses content hash for deduplication", () => {
- expect(watchContent).toContain("hashContent");
- expect(watchContent).toContain("createHash");
- expect(watchContent).toContain('lastHash.get(filePath) === hash');
+ it("drops parent runtime flags for a built JavaScript entry", () => {
+ expect(
+ childCliArgs(
+ "/workspace/dist/cli/main.js",
+ ["--help"],
+ ["--inspect=0", "--require", "preflight.cjs", "--import", "loader.mjs"],
+ ),
+ ).toEqual(["/workspace/dist/cli/main.js", "--help"]);
});
- it("re-reads file at ingest time, not event time", () => {
- // readFileContent called inside ingestFile, not in the event handler
- expect(watchContent).toContain("readFileContent(filePath)");
- // The debounce callback does NOT read the file
- expect(watchContent).toContain("content is re-read at ingest time");
+ it("starts both the tsx source CLI and a normal built CLI child", () => {
+ const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+ const tempRoot = fs.mkdtempSync(path.join(packageRoot, ".watch-child-runtime-"));
+ const ixHome = path.join(tempRoot, "ix-home");
+ fs.mkdirSync(ixHome);
+ fs.writeFileSync(
+ path.join(ixHome, ".version-check.json"),
+ JSON.stringify({ latest: "0.9.3", checkedAt: Date.now() }),
+ );
+ const env = { ...process.env, IX_HOME: ixHome, NO_COLOR: "1" };
+
+ try {
+ const sourceEntry = path.join(packageRoot, "src/cli/main.ts");
+ const source = spawnSync(
+ process.execPath,
+ childCliArgs(sourceEntry, ["--version"], ["--inspect=0", "--import", "tsx"]),
+ { cwd: packageRoot, env, encoding: "utf8" },
+ );
+ expect(source.status, source.stderr).toBe(0);
+ expect(source.stdout.trim()).toBe("0.9.3");
+ expect(source.stderr).not.toContain("Debugger listening");
+
+ const outDir = path.join(tempRoot, "dist");
+ const build = spawnSync(
+ process.execPath,
+ [
+ path.join(packageRoot, "node_modules/typescript/bin/tsc"),
+ "-p",
+ path.join(packageRoot, "tsconfig.build.json"),
+ "--outDir",
+ outDir,
+ "--declaration",
+ "false",
+ ],
+ { cwd: packageRoot, env, encoding: "utf8" },
+ );
+ expect(build.status, build.stderr || build.stdout).toBe(0);
+
+ const builtEntry = path.join(outDir, "cli/main.js");
+ const built = spawnSync(
+ process.execPath,
+ childCliArgs(builtEntry, ["--help"], ["--inspect=0", "--import", "tsx"]),
+ { cwd: packageRoot, env, encoding: "utf8" },
+ );
+ expect(built.status, built.stderr).toBe(0);
+ expect(built.stdout).toContain("ix — System Intelligence CLI");
+ expect(built.stderr).not.toContain("Debugger listening");
+ } finally {
+ fs.rmSync(tempRoot, { recursive: true, force: true });
+ }
+ }, 30_000);
+
+ it("delegates the workspace root to the existing map command with full ingest enabled", () => {
+ const root = "/workspace/project";
+ const entry = "/workspace/dist/cli/main.js";
+ const map = canonicalMapInvocation(root, entry, ["--inspect=0"]);
+
+ expect(map.command).toBe(process.execPath);
+ expect(map.args).toEqual([entry, "map", root, "--silent"]);
+ expect(map.env.IX_AUTO_MAP).toBe("1");
+ expect(map.env.IX_MAP_FULL_INGEST).toBe("1");
+ expect(map.env.IX_MAP_COALESCE_EXIT_CODE).toBe("75");
});
- it("uses short debounce (300ms)", () => {
- expect(watchContent).toContain("DEBOUNCE_MS = 300");
+ it("retries a map coalesced by another process so the change is not lost", async () => {
+ const exits = [75, 0];
+ const launch = vi.fn(() => {
+ const child = new EventEmitter();
+ queueMicrotask(() => child.emit("exit", exits.shift(), null));
+ return child as any;
+ });
+ const wait = vi.fn().mockResolvedValue(undefined);
+
+ await runCanonicalMap("/workspace/project", launch, wait);
+
+ expect(launch).toHaveBeenCalledTimes(2);
+ expect(wait).toHaveBeenCalledOnce();
});
- it("tracks last hash per file", () => {
- expect(watchContent).toContain("lastHash");
- expect(watchContent).toContain("lastHash.set(filePath, hash)");
+ it("propagates a canonical map failure without spinning", async () => {
+ const launch = vi.fn(() => {
+ const child = new EventEmitter();
+ queueMicrotask(() => child.emit("exit", 2, null));
+ return child as any;
+ });
+
+ await expect(runCanonicalMap("/workspace/project", launch)).rejects.toThrow(
+ "ix map failed (exit 2)",
+ );
+ expect(launch).toHaveBeenCalledOnce();
});
- it("skips ingest when content hash unchanged", () => {
- expect(watchContent).toContain("unchanged (hash)");
+ it("gives up on a lock that is never released instead of retrying forever", async () => {
+ // A holder that never exits 0 — a crashed process whose lockfile outlived
+ // it. Unbounded, this spawned a Node process every second indefinitely.
+ const launch = vi.fn(() => {
+ const child = new EventEmitter();
+ queueMicrotask(() => child.emit("exit", 75, null));
+ return child as any;
+ });
+ const wait = vi.fn().mockResolvedValue(undefined);
+
+ await expect(runCanonicalMap("/workspace/project", launch, wait, () => {})).rejects.toThrow(
+ /stayed coalesced across \d+ attempts/,
+ );
+ expect(launch.mock.calls.length).toBeLessThanOrEqual(45);
+ expect(wait).toHaveBeenCalledTimes(launch.mock.calls.length);
});
- it("coalesces rapid events per file via debounce map", () => {
- expect(watchContent).toContain("pending.get(fullPath)");
- expect(watchContent).toContain("clearTimeout(existing)");
+ it("tells the user why it is waiting, since the child map runs --silent", async () => {
+ const exits = [75, 75, 75, 0];
+ const launch = vi.fn(() => {
+ const child = new EventEmitter();
+ queueMicrotask(() => child.emit("exit", exits.shift(), null));
+ return child as any;
+ });
+ const notify = vi.fn();
+
+ await runCanonicalMap("/workspace/project", launch, vi.fn().mockResolvedValue(undefined), notify);
+
+ expect(notify).toHaveBeenCalledOnce();
+ expect(notify.mock.calls[0]![0]).toMatch(/another ix map holds this workspace/);
+ });
+
+ it("backs off exponentially up to a ceiling", () => {
+ expect([1, 2, 3, 4, 5, 6].map(mapRetryDelay)).toEqual([1000, 2000, 4000, 8000, 16000, 30000]);
+ // Capped, so a long wait costs attempts rather than unbounded sleep growth.
+ expect(mapRetryDelay(45)).toBe(30000);
+ // 45 attempts spans past single-flight's 20-minute stale-lock window.
+ const total = Array.from({ length: 45 }, (_, i) => mapRetryDelay(i + 1)).reduce((a, b) => a + b, 0);
+ expect(total).toBeGreaterThan(20 * 60 * 1000);
+ });
+
+ it("keeps delete events eligible without requiring the file to exist", () => {
+ expect(shouldWatch("/workspace/project", "/workspace/project/deleted.ts")).toBe(true);
+ });
+
+ it("clears the parent's baseline before migration refresh crosses into a child process", () => {
+ const clear = vi.fn();
+ const root = "/workspace/migrated";
+
+ prepareMigratedWorkspaceRefresh(root, clear);
+
+ expect(clear).toHaveBeenCalledWith(root);
+ expect(canonicalMapInvocation(root, "/workspace/dist/cli/main.js").args).toEqual([
+ "/workspace/dist/cli/main.js",
+ "map",
+ root,
+ "--silent",
+ ]);
+ });
+});
+
+describe("updatePollingSnapshot", () => {
+ it("detects new, modified, and deleted files", () => {
+ const mtimes = new Map([
+ ["kept.ts", 1],
+ ["changed.ts", 1],
+ ["deleted.ts", 1],
+ ]);
+ const current = ["kept.ts", "changed.ts", "new.ts"];
+ const values = new Map([
+ ["kept.ts", 1],
+ ["changed.ts", 2],
+ ["new.ts", 3],
+ ]);
+
+ const changed = updatePollingSnapshot(current, mtimes, (filePath) => values.get(filePath)!);
+
+ expect(changed).toEqual(["changed.ts", "new.ts", "deleted.ts"]);
+ expect(mtimes).toEqual(values);
+ });
+
+ it("detects a backwards mtime change instead of requiring mtime to increase", () => {
+ const mtimes = new Map([["restored.ts", 10]]);
+
+ expect(updatePollingSnapshot(["restored.ts"], mtimes, () => 5)).toEqual(["restored.ts"]);
});
});
diff --git a/ix-cli/src/cli/commands/map.ts b/ix-cli/src/cli/commands/map.ts
index e195a01c..b3662ebc 100644
--- a/ix-cli/src/cli/commands/map.ts
+++ b/ix-cli/src/cli/commands/map.ts
@@ -38,6 +38,30 @@ export function shouldSkipAutoMap(opts: { auto: boolean; cloudReady: boolean }):
return true;
}
+/** Optional exit code for callers that must distinguish coalescing from success. */
+export function requestedMapCoalesceExitCode(
+ raw = process.env.IX_MAP_COALESCE_EXIT_CODE,
+): number | undefined {
+ if (raw === undefined) return undefined;
+ const code = Number(raw);
+ return Number.isInteger(code) && code >= 1 && code <= 255 ? code : undefined;
+}
+
+export function applyRequestedMapCoalesceExitCode(
+ raw = process.env.IX_MAP_COALESCE_EXIT_CODE,
+ apply: (code: number) => void = code => { process.exitCode = code; },
+): boolean {
+ const code = requestedMapCoalesceExitCode(raw);
+ if (code === undefined) return false;
+ apply(code);
+ return true;
+}
+
+/** Watch opts into full patches; ordinary `ix map` keeps its topology-only ingest. */
+export function mapModeForIngest(raw = process.env.IX_MAP_FULL_INGEST): boolean {
+ return raw !== "1";
+}
+
export interface MapRegion {
id: string;
label: string;
@@ -175,6 +199,7 @@ Examples:
if (!silent && opts.format !== "json" && opts.format !== "llm") {
process.stderr.write(chalk.dim(" Another ix map is already running for this workspace — skipping.\n"));
}
+ applyRequestedMapCoalesceExitCode();
return; // coalesce; the in-flight map will refresh the graph
}
@@ -256,7 +281,7 @@ Examples:
format: (machineFormat || silent) ? "json" : "text",
printSummary: false,
suppressOutput: true,
- mapMode: true,
+ mapMode: mapModeForIngest(),
deadlineSignal,
// `ix map` has no --debug, so the per-file `[commit error] <uri>`
// detail was unreachable from the command that produced the
diff --git a/ix-cli/src/cli/commands/watch.ts b/ix-cli/src/cli/commands/watch.ts
index d0710807..f4964213 100644
--- a/ix-cli/src/cli/commands/watch.ts
+++ b/ix-cli/src/cli/commands/watch.ts
@@ -1,14 +1,11 @@
import * as fs from "node:fs";
import * as path from "node:path";
-import * as crypto from "node:crypto";
+import { spawn } from "node:child_process";
+import type { SpawnOptions } from "node:child_process";
import type { Command } from "commander";
import chalk from "chalk";
-import { spawnSync } from "node:child_process";
-import { IxClient } from "../../client/api.js";
-import { getEndpoint, resolveWorkspaceRoot, clearIngestMtimeCache } from "../config.js";
-import { bootstrap, ensureWorkspaceId, ensureWorkspaceIdState } from "../bootstrap.js";
-import { loadWatchIngestionModules } from "./ingestion-loader.js";
-import { readFileContent } from "./watch-utils.js";
+import { resolveWorkspaceRoot, clearIngestMtimeCache } from "../config.js";
+import { bootstrap, ensureWorkspaceIdState } from "../bootstrap.js";
import { SUPPORTED_EXTENSIONS } from "../supported-extensions.js";
const SUPPORTED_NAMES = new Set([
@@ -24,21 +21,263 @@ const IGNORE_DIRS = new Set([
]);
const DEBOUNCE_MS = 300;
+const MAP_COALESCED_EXIT_CODE = 75;
+const MAP_RETRY_MS = 1000;
+const MAP_RETRY_MAX_MS = 30_000;
+/**
+ * How many times a coalesced map is retried before the refresh is given up on.
+ *
+ * The backoff below reaches its 30s ceiling after five doublings (31s of
+ * waiting), so 45 attempts spans roughly 21 minutes. That is deliberately just
+ * past `DEFAULT_LOCK_MAX_MS` in single-flight.ts (20 min), which is the point at
+ * which a lock whose holder died is stolen — so a genuinely long map is still
+ * waited out, and only a lock that outlives its own staleness window gives up.
+ *
+ * A fixed 1s retry with no ceiling reached that same 20 minutes in ~1,200 Node
+ * process spawns. This reaches it in 45.
+ */
+const MAP_RETRY_ATTEMPTS = 45;
+/** Retrying silently for minutes looks identical to a watcher that has died. */
+const MAP_RETRY_NOTIFY_AFTER = 3;
-/** Compute SHA-256 hash of file content for dedup. */
-function hashContent(content: string): string {
- return crypto.createHash("sha256").update(content).digest("hex");
+interface MapChild {
+ once(event: "error", listener: (err: Error) => void): unknown;
+ once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
}
-/**
- * Convert an absolute path to a workspace-relative POSIX path. This is the
- * canonical source_uri and the basis for every deterministic node/edge/chunk
- * id, so it must match what `ix ingest` emits (see toWorkspaceRelative in
- * ingest.ts). Forcing POSIX separators keeps ids stable across operating
- * systems and never embeds an absolute host path.
- */
-function toWorkspaceRelative(root: string, absPath: string): string {
- return path.relative(root, absPath).split(path.sep).join("/");
+type MapLauncher = (command: string, args: string[], options: SpawnOptions) => MapChild;
+
+const RUNTIME_LOADER_FLAGS = new Set([
+ "--import", "--loader", "--experimental-loader", "--require", "-r",
+]);
+
+/** Preserve source loaders for a TypeScript CLI entry without cloning debugger flags. */
+export function childCliArgs(
+ entry: string,
+ cliArgs: string[],
+ execArgv: string[] = process.execArgv,
+): string[] {
+ if (!/\.[cm]?tsx?$/.test(entry)) return [entry, ...cliArgs];
+
+ const loaders: string[] = [];
+ for (let index = 0; index < execArgv.length; index++) {
+ const arg = execArgv[index]!;
+ if (RUNTIME_LOADER_FLAGS.has(arg)) {
+ const value = execArgv[index + 1];
+ if (value !== undefined) {
+ loaders.push(arg, value);
+ index++;
+ }
+ continue;
+ }
+ if (
+ [...RUNTIME_LOADER_FLAGS].some(flag => arg.startsWith(`${flag}=`)) ||
+ (arg.startsWith("-r") && !arg.startsWith("--") && arg.length > 2)
+ ) {
+ loaders.push(arg);
+ }
+ }
+
+ return [...loaders, entry, ...cliArgs];
+}
+
+export function canonicalMapInvocation(
+ root: string,
+ entry = process.argv[1],
+ execArgv = process.execArgv,
+): { command: string; args: string[]; env: NodeJS.ProcessEnv } {
+ if (!entry) throw new Error("Could not locate the Ix CLI entry point.");
+ return {
+ command: process.execPath,
+ args: childCliArgs(entry, ["map", root, "--silent"], execArgv),
+ env: {
+ ...process.env,
+ IX_AUTO_MAP: "1",
+ IX_MAP_FULL_INGEST: "1",
+ IX_MAP_COALESCE_EXIT_CODE: String(MAP_COALESCED_EXIT_CODE),
+ },
+ };
+}
+
+function runChild(
+ invocation: ReturnType<typeof canonicalMapInvocation>,
+ launch: MapLauncher,
+): Promise<{ code: number | null; signal: NodeJS.Signals | null }> {
+ return new Promise((resolve, reject) => {
+ const child = launch(invocation.command, invocation.args, {
+ env: invocation.env,
+ stdio: "inherit",
+ });
+ child.once("error", reject);
+ child.once("exit", (code, signal) => {
+ if (code === 0 || code === MAP_COALESCED_EXIT_CODE) {
+ resolve({ code, signal });
+ } else {
+ reject(new Error(`ix map failed${signal ? ` (${signal})` : ` (exit ${code ?? 1})`}`));
+ }
+ });
+ });
+}
+
+/** Exponential backoff, capped, so a held lock costs attempts rather than spawns. */
+export function mapRetryDelay(attempt: number): number {
+ return Math.min(MAP_RETRY_MS * 2 ** (attempt - 1), MAP_RETRY_MAX_MS);
+}
+
+export async function runCanonicalMap(
+ root: string,
+ launch: MapLauncher = spawn as MapLauncher,
+ wait: (ms: number) => Promise<void> = ms => new Promise(resolve => setTimeout(resolve, ms)),
+ notify: (message: string) => void = message => console.error(`${chalk.dim("[watch]")} ${message}`),
+): Promise<void> {
+ const invocation = canonicalMapInvocation(root);
+ for (let attempt = 1; attempt <= MAP_RETRY_ATTEMPTS; attempt++) {
+ const { code } = await runChild(invocation, launch);
+ if (code === 0) return;
+ // Exit 75 means another ix map holds the workspace lock. The child runs
+ // --silent, so without this the watcher looks hung rather than patient.
+ if (attempt === MAP_RETRY_NOTIFY_AFTER) {
+ notify("another ix map holds this workspace; waiting for it to finish...");
+ }
+ await wait(mapRetryDelay(attempt));
+ }
+ throw new Error(
+ `ix map stayed coalesced across ${MAP_RETRY_ATTEMPTS} attempts; another ix map has held the workspace lock the whole time`,
+ );
+}
+
+/** Serialize refreshes and coalesce changes during a run into one trailing refresh. */
+export class WatchRefreshScheduler {
+ private running = false;
+ private queued = false;
+ private idleWaiters: Array<() => void> = [];
+
+ constructor(
+ private readonly refresh: () => Promise<void>,
+ private readonly onError: (err: unknown) => void,
+ ) {}
+
+ request(): void {
+ this.queued = true;
+ if (!this.running) void this.drain();
+ }
+
+ waitForIdle(): Promise<void> {
+ if (!this.running && !this.queued) return Promise.resolve();
+ return new Promise(resolve => this.idleWaiters.push(resolve));
+ }
+
+ private async drain(): Promise<void> {
+ this.running = true;
+ try {
+ while (this.queued) {
+ this.queued = false;
+ try {
+ await this.refresh();
+ } catch (err) {
+ this.onError(err);
+ }
+ }
+ } finally {
+ this.running = false;
+ for (const resolve of this.idleWaiters.splice(0)) resolve();
+ }
+ }
+}
+
+/** Detect new, changed, and deleted files while advancing the polling snapshot. */
+export function updatePollingSnapshot(
+ currentFiles: string[],
+ mtimes: Map<string, number>,
+ statMtime: (filePath: string) => number = filePath => fs.statSync(filePath).mtimeMs,
+): string[] {
+ const next = new Map<string, number>();
+ const changed: string[] = [];
+
+ for (const filePath of currentFiles) {
+ try {
+ const mtime = statMtime(filePath);
+ next.set(filePath, mtime);
+ if (mtimes.get(filePath) !== mtime) changed.push(filePath);
+ } catch {
+ // A racy delete is handled by the missing-file pass below.
+ }
+ }
+
+ const current = new Set(next.keys());
+ for (const filePath of mtimes.keys()) {
+ if (!current.has(filePath)) changed.push(filePath);
+ }
+
+ mtimes.clear();
+ for (const [filePath, mtime] of next) mtimes.set(filePath, mtime);
+ return changed;
+}
+
+function isSupportedPath(filePath: string): boolean {
+ const ext = path.extname(filePath).toLowerCase();
+ return SUPPORTED_EXTENSIONS.has(ext) || SUPPORTED_NAMES.has(path.basename(filePath));
+}
+
+export function shouldWatch(root: string, filePath: string): boolean {
+ if (!isSupportedPath(filePath)) return false;
+ const segments = path.relative(root, filePath).split(path.sep);
+ return !segments.some(segment => IGNORE_DIRS.has(segment));
+}
+
+export function prepareMigratedWorkspaceRefresh(
+ root: string,
+ clear: (workspaceRoot: string) => void = clearIngestMtimeCache,
+): void {
+ clear(root);
+}
+
+function collectFiles(dir: string): string[] {
+ const results: string[] = [];
+ const stack = [dir];
+ while (stack.length > 0) {
+ const current = stack.pop()!;
+ let entries: fs.Dirent[];
+ try { entries = fs.readdirSync(current, { withFileTypes: true }); }
+ catch { continue; }
+ for (const entry of entries) {
+ if (IGNORE_DIRS.has(entry.name)) continue;
+ if (entry.name.startsWith(".") && entry.isDirectory()) continue;
+ const fullPath = path.join(current, entry.name);
+ if (entry.isDirectory()) stack.push(fullPath);
+ else if (entry.isFile() && isSupportedPath(fullPath)) results.push(fullPath);
+ }
+ }
+ return results;
+}
+
+function createBatchNotifier(root: string, scheduler: WatchRefreshScheduler): {
+ notify(filePath: string): void;
+ cancel(): void;
+} {
+ const pending = new Set<string>();
+ let timer: NodeJS.Timeout | undefined;
+
+ const flush = () => {
+ timer = undefined;
+ for (const filePath of [...pending].sort()) {
+ console.log(`${chalk.dim("[watch]")} changed: ${path.relative(root, filePath)}`);
+ }
+ pending.clear();
+ scheduler.request();
+ };
+
+ return {
+ notify(filePath: string) {
+ pending.add(filePath);
+ if (timer) clearTimeout(timer);
+ timer = setTimeout(flush, DEBOUNCE_MS);
+ },
+ cancel() {
+ if (timer) clearTimeout(timer);
+ pending.clear();
+ },
+ };
}
export function registerWatchCommand(program: Command): void {
@@ -48,24 +287,15 @@ export function registerWatchCommand(program: Command): void {
.option("--path <path>", "Restrict watching to a subdirectory")
.option("--root <dir>", "Workspace root directory")
.action(async (opts: { path?: string; root?: string }) => {
+ const root = path.resolve(resolveWorkspaceRoot(opts.root));
try {
- await bootstrap();
+ await bootstrap(root);
} catch (err: any) {
console.error(chalk.red("Error:"), err.message);
process.exit(1);
}
- const root = resolveWorkspaceRoot(opts.root);
- const { workspaceId, migrated } = ensureWorkspaceIdState(root);
- // If the workspace_id was just migrated to the path-based id (Ix#225 gap 2), the
- // new id has no nodes yet and watch only ingests files as they change — so do a
- // one-time full re-ingest under the new id first (clear the mtime cache so the
- // spawned map re-ingests everything, then run it synchronously before watching).
- if (migrated) {
- console.error(chalk.dim("[watch] Workspace migrated to a stable id; re-ingesting once before watching..."));
- clearIngestMtimeCache(root);
- spawnSync(process.argv[0], [process.argv[1], "map", root, "--silent"], { stdio: "inherit" });
- }
+ const { migrated } = ensureWorkspaceIdState(root);
const watchPath = opts.path
? path.resolve(root, opts.path)
: root;
@@ -75,88 +305,36 @@ export function registerWatchCommand(program: Command): void {
process.exit(1);
}
- const client = new IxClient(getEndpoint());
+ const refresh = () => runCanonicalMap(root);
+ const scheduler = new WatchRefreshScheduler(refresh, err =>
+ console.error(`${chalk.red("[watch]")} refresh error: ${(err as Error).message}`)
+ );
+
+ if (migrated) {
+ console.error(chalk.dim("[watch] Workspace migrated to a stable id; re-ingesting once before watching..."));
+ prepareMigratedWorkspaceRefresh(root);
+ await refresh();
+ }
const relative = path.relative(root, watchPath) || ".";
console.log(chalk.cyan(`[watch] Watching ${relative}`));
console.log(chalk.dim(`[watch] Debounce: ${DEBOUNCE_MS}ms`));
console.log(chalk.dim("[watch] Press Ctrl+C to stop.\n"));
- // Track pending changes with debounce + content hash dedup
- const pending = new Map<string, NodeJS.Timeout>();
- const lastHash = new Map<string, string>();
-
- function shouldWatch(filePath: string): boolean {
- const ext = path.extname(filePath).toLowerCase();
- const basename = path.basename(filePath);
- if (!SUPPORTED_EXTENSIONS.has(ext) && !SUPPORTED_NAMES.has(basename)) return false;
- // Check no segment is an ignored dir
- const segments = path.relative(root, filePath).split(path.sep);
- return !segments.some(s => IGNORE_DIRS.has(s));
- }
-
- async function ingestFile(filePath: string): Promise<void> {
- const [{ parseFile }, { buildPatch }] = await loadWatchIngestionModules();
- // Workspace-relative POSIX path drives source_uri and node identity; it
- // must match `ix ingest` or the same file ingested via watch vs ingest
- // would mint divergent node ids and reintroduce absolute-path coupling.
- const relPath = toWorkspaceRelative(root, filePath);
-
- // Re-read content at actual ingest time (not at event time)
- const content = readFileContent(filePath);
- if (content === null) return;
-
- // Skip if content hash is unchanged since last ingest
- const hash = hashContent(content);
- if (lastHash.get(filePath) === hash) {
- console.log(`${chalk.dim("[watch]")} unchanged (hash): ${relPath}`);
- return;
- }
-
- try {
- const parsed = parseFile(relPath, content);
- if (!parsed) {
- console.log(`${chalk.dim("[watch]")} skipped (unsupported): ${relPath}`);
- return;
- }
- const patch = buildPatch(parsed, hash, workspaceId);
- const result = await client.commitPatch(patch);
- lastHash.set(filePath, hash);
- console.log(`${chalk.cyan("[watch]")} ingested: ${chalk.bold(relPath)} → rev ${result.rev}`);
- } catch (err: any) {
- console.error(`${chalk.red("[watch]")} error ingesting ${relPath}: ${err.message}`);
- }
- }
+ const batch = createBatchNotifier(root, scheduler);
// Use fs.watch recursively
try {
const watcher = fs.watch(watchPath, { recursive: true }, (_event, filename) => {
if (!filename) return;
const fullPath = path.resolve(watchPath, filename);
- if (!shouldWatch(fullPath)) return;
-
- // Check file still exists (might be a delete event)
- if (!fs.existsSync(fullPath)) return;
-
- const rel = path.relative(root, fullPath);
-
- // Cancel any existing debounce for this file
- const existing = pending.get(fullPath);
- if (existing) clearTimeout(existing);
-
- // Set new debounce — content is re-read at ingest time, not here
- pending.set(fullPath, setTimeout(async () => {
- pending.delete(fullPath);
- console.log(`${chalk.dim("[watch]")} changed: ${rel}`);
- await ingestFile(fullPath);
- }, DEBOUNCE_MS));
+ if (shouldWatch(root, fullPath)) batch.notify(fullPath);
});
// Keep process alive
process.on("SIGINT", () => {
watcher.close();
- // Clear pending timers
- for (const timer of pending.values()) clearTimeout(timer);
+ batch.cancel();
console.log(chalk.dim("\n[watch] Stopped."));
process.exit(0);
});
@@ -164,7 +342,7 @@ export function registerWatchCommand(program: Command): void {
// Fallback to polling if fs.watch with recursive isn't supported
if (err.code === "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM") {
console.log(chalk.dim("[watch] Falling back to polling mode (2s interval)..."));
- await pollMode(watchPath, root, client);
+ pollMode(watchPath, root, scheduler);
} else {
throw err;
}
@@ -175,81 +353,29 @@ export function registerWatchCommand(program: Command): void {
/**
* Fallback polling mode for platforms where recursive fs.watch isn't available.
*/
-async function pollMode(
+function pollMode(
watchPath: string,
root: string,
- client: IxClient
-): Promise<void> {
- const [{ parseFile }, { buildPatch }] = await loadWatchIngestionModules();
- const workspaceId = ensureWorkspaceId(root);
+ scheduler: WatchRefreshScheduler,
+): void {
const mtimes = new Map<string, number>();
- function collectFiles(dir: string): string[] {
- const results: string[] = [];
- const stack = [dir];
- while (stack.length > 0) {
- const current = stack.pop()!;
- let entries: fs.Dirent[];
- try { entries = fs.readdirSync(current, { withFileTypes: true }); }
- catch { continue; }
- for (const entry of entries) {
- if (IGNORE_DIRS.has(entry.name)) continue;
- if (entry.name.startsWith(".") && entry.isDirectory()) continue;
- const fullPath = path.join(current, entry.name);
- if (entry.isDirectory()) {
- stack.push(fullPath);
- } else if (entry.isFile()) {
- const ext = path.extname(entry.name).toLowerCase();
- if (SUPPORTED_EXTENSIONS.has(ext) || SUPPORTED_NAMES.has(entry.name)) {
- results.push(fullPath);
- }
- }
- }
- }
- return results;
- }
-
// Initial scan
for (const f of collectFiles(watchPath)) {
try { mtimes.set(f, fs.statSync(f).mtimeMs); } catch {}
}
- const poll = async () => {
- const currentFiles = collectFiles(watchPath);
- const changed: string[] = [];
-
- for (const f of currentFiles) {
- try {
- const mtime = fs.statSync(f).mtimeMs;
- const prev = mtimes.get(f);
- if (prev === undefined || mtime > prev) {
- changed.push(f);
- mtimes.set(f, mtime);
- }
- } catch {}
+ const interval = setInterval(() => {
+ const changed = updatePollingSnapshot(collectFiles(watchPath), mtimes);
+ if (changed.length === 0) return;
+ for (const filePath of changed.sort()) {
+ console.log(`${chalk.dim("[watch]")} changed: ${path.relative(root, filePath)}`);
}
-
- for (const f of changed) {
- const relPath = toWorkspaceRelative(root, f);
- console.log(`${chalk.dim("[watch]")} changed: ${relPath}`);
- try {
- const content = readFileContent(f);
- if (!content) continue;
- const parsed = parseFile(relPath, content);
- if (!parsed) continue;
- const hash = hashContent(content);
- const patch = buildPatch(parsed, hash, workspaceId);
- const result = await client.commitPatch(patch);
- console.log(`${chalk.cyan("[watch]")} ingested: ${chalk.bold(relPath)} → rev ${result.rev}`);
- } catch (err: any) {
- console.error(`${chalk.red("[watch]")} error: ${err.message}`);
- }
- }
- };
-
- setInterval(poll, 2000);
+ scheduler.request();
+ }, 2000);
process.on("SIGINT", () => {
+ clearInterval(interval);
console.log(chalk.dim("\n[watch] Stopped."));
process.exit(0);
});