@indigoai-us/hq-cloud 6.14.44 → 6.14.45

package/test/e2e/watcher-scoped-coverage.test.ts

@@ -0,0 +1,381 @@
+/**
+ * REAL-fs regressions for the scoped watch-root backend.
+ *
+ * These assert on what the OS DELIVERS, not on what TreeWatcher emits. That
+ * distinction is the whole point of this backend: the emit filter has always
+ * dropped excluded paths correctly, so emissions look identical whether or not
+ * the watch set is scoped. What changes is whether the event reaches the
+ * process at all — which is the CPU cost this backend exists to remove, and
+ * the only way these regressions are observable.
+ *
+ * So each test drives `startScopedRecursiveWatch` directly and counts raw
+ * `onEvent` calls.
+ *
+ * Checked against the pre-fix backend, three of these fail without their fix —
+ * the new-exclusion firehose, the attach-failure report, and the mid-plan
+ * window. The mid-plan case only became meaningful once the walk was made
+ * deliberately slow: with a microsecond-wide window it was racing FSEvents
+ * stream warm-up and flapped between runs, which is a flaky test rather than
+ * a regression test.
+ *
+ * The delete/recreate case passes either way on macOS, because FSEvents
+ * watches by PATH — a recreated directory keeps reporting through the stale
+ * handle. That does not hold on Windows (`ReadDirectoryChangesW` is
+ * handle-based) and is not guaranteed by any API contract, so dropping stale
+ * handles is deliberate belt-and-braces and this test is kept as a guard: it
+ * pins that the re-plan did not BREAK behavior that already worked.
+ */
+
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  startScopedRecursiveWatch,
+  type ScopedWatchBackend,
+} from "../../src/watcher.js";
+
+let hqRoot: string;
+let backend: ScopedWatchBackend | null = null;
+
+/** `excluded/` anywhere in the tree is out of scope, like `node_modules/`. */
+const makeFilter = (root: string) => (abs: string): boolean => {
+  const rel = path.relative(root, abs);
+  if (rel === "" || rel.startsWith("..")) return false;
+  return !rel.split(path.sep).includes("excluded");
+};
+
+beforeEach(async () => {
+  hqRoot = await mkdtemp(path.join(tmpdir(), "hqcloud-scoped-cov-"));
+});
+
+afterEach(async () => {
+  backend?.close();
+  backend = null;
+  await rm(hqRoot, { recursive: true, force: true });
+});
+
+const settle = (ms = 800) => new Promise((r) => setTimeout(r, ms));
+
+/** Raw events the OS delivered for paths under `prefix`. */
+function eventsUnder(onEvent: ReturnType<typeof vi.fn>, prefix: string): number {
+  return onEvent.mock.calls.filter(
+    ([p]) => typeof p === "string" && p.startsWith(prefix),
+  ).length;
+}
+
+/**
+ * Guard against a vacuous pass. Half of these tests assert that ZERO events
+ * arrive, which is trivially true if the backend attached no watches at all —
+ * so every test first proves the backend is actually live.
+ */
+function expectLiveBackend(b: ScopedWatchBackend): void {
+  expect(b.attachFailures).toBe(0);
+  expect(b.watchedPathCount()).toBeGreaterThan(0);
+}
+
+/**
+ * This backend is the macOS/Windows one: it is built entirely on recursive
+ * `fs.watch`, which Linux does not implement (`startTreeWatch` routes Linux to
+ * chokidar instead). Running these there watches nothing, which would let the
+ * "expect zero events" cases pass for the wrong reason.
+ */
+const SUPPORTS_RECURSIVE_WATCH =
+  process.platform === "darwin" || process.platform === "win32";
+
+describe.skipIf(!SUPPORTS_RECURSIVE_WATCH)("scoped watch roots — the OS stops reporting excluded trees", () => {
+  it(
+    "stops delivering events from an excluded directory created AFTER planning",
+    async () => {
+      // The regression that would defeat the whole change: at plan time the
+      // tree is clean, so it collapses to ONE recursive root at hqRoot.
+      // Creating `work/excluded/` afterwards puts a high-churn bucket back
+      // inside that root. Without re-planning, the creation event looks
+      // "already covered" and every write beneath it is delivered again —
+      // exactly the firehose this backend removes.
+      await mkdir(path.join(hqRoot, "work", "keep"), { recursive: true });
+      const onEvent = vi.fn();
+      backend = startScopedRecursiveWatch(
+        hqRoot,
+        makeFilter(hqRoot),
+        onEvent,
+        () => {},
+      );
+      expectLiveBackend(backend);
+      // Wait out the bootstrap drain window: the temporary whole-tree watch is
+      // deliberately held open briefly after planning so in-flight events are
+      // not dropped with the handle. This test measures the steady state.
+      await settle(2600);
+
+      const excluded = path.join(hqRoot, "work", "excluded");
+      await mkdir(path.join(excluded, "deep"), { recursive: true });
+      await settle();
+
+      onEvent.mockClear();
+      for (let i = 0; i < 5; i++) {
+        await writeFile(path.join(excluded, "deep", `build-${i}.log`), "noise\n");
+      }
+      await settle();
+
+      expect(eventsUnder(onEvent, excluded)).toBe(0);
+    },
+    20000,
+  );
+
+  it(
+    "still delivers in-scope siblings after re-planning around a new exclusion",
+    async () => {
+      // Re-planning must SPLIT the root, not tear coverage off the good part.
+      const keep = path.join(hqRoot, "work", "keep");
+      await mkdir(keep, { recursive: true });
+      const onEvent = vi.fn();
+      backend = startScopedRecursiveWatch(
+        hqRoot,
+        makeFilter(hqRoot),
+        onEvent,
+        () => {},
+      );
+      expectLiveBackend(backend);
+      await settle();
+
+      await mkdir(path.join(hqRoot, "work", "excluded"), { recursive: true });
+      await settle();
+
+      onEvent.mockClear();
+      await writeFile(path.join(keep, "note.md"), "# hi\n");
+      await settle();
+
+      expect(eventsUnder(onEvent, keep)).toBeGreaterThan(0);
+    },
+    20000,
+  );
+
+  it(
+    "re-attaches after a watched directory is deleted and recreated",
+    async () => {
+      // A recreated directory has a NEW inode. A stale handle left in the watch
+      // set makes the path look covered forever, so nothing under the
+      // replacement is ever delivered again.
+      const work = path.join(hqRoot, "work");
+      const keep = path.join(work, "keep");
+      await mkdir(keep, { recursive: true });
+      // An exclusion at the root forces `hqRoot` to be SHALLOW, so `work/` is
+      // its own recursive root — the handle that goes stale on delete.
+      await mkdir(path.join(hqRoot, "excluded"), { recursive: true });
+      const onEvent = vi.fn();
+      backend = startScopedRecursiveWatch(
+        hqRoot,
+        makeFilter(hqRoot),
+        onEvent,
+        () => {},
+      );
+      expectLiveBackend(backend);
+      await settle();
+
+      await rm(work, { recursive: true, force: true });
+      await settle();
+      await mkdir(keep, { recursive: true });
+      await settle();
+
+      onEvent.mockClear();
+      await writeFile(path.join(keep, "reborn.md"), "# back\n");
+      await settle();
+
+      expect(eventsUnder(onEvent, keep)).toBeGreaterThan(0);
+    },
+    25000,
+  );
+
+  it(
+    "delivers a change made while the planning walk is still running",
+    async () => {
+      // Planning is synchronous and takes seconds on a real tree. Without a
+      // bootstrap watch over the root first, anything written during that
+      // window is invisible to event-driven push until the next cadence poll.
+      await mkdir(path.join(hqRoot, "work"), { recursive: true });
+      await mkdir(path.join(hqRoot, "excluded"), { recursive: true });
+      const target = path.join(hqRoot, "work", "during-plan.md");
+
+      const onEvent = vi.fn();
+      let fired = false;
+      const filter = makeFilter(hqRoot);
+      /** Block the walk so the planning window is wide and unambiguous. */
+      const spin = (ms: number) => {
+        const until = Date.now() + ms;
+        while (Date.now() < until) {
+          /* deliberately synchronous — this IS the planning walk */
+        }
+      };
+      const slowFilter = (abs: string, isDir?: boolean): boolean => {
+        // Mutate from inside the planning walk itself — the one moment the
+        // tree is being traversed and no scoped watch exists yet.
+        if (!fired) {
+          fired = true;
+          // Let the OS watch stream warm up first — a write in the same
+          // microsecond as stream creation is genuinely racy on macOS and
+          // would make this test flaky rather than meaningful. Then write, and
+          // keep blocking so the write is unambiguously INSIDE the walk.
+          spin(600);
+          // eslint-disable-next-line @typescript-eslint/no-require-imports
+          require("node:fs").writeFileSync(target, "# mid-plan\n");
+          spin(400);
+        }
+        return filter(abs, isDir);
+      };
+
+      backend = startScopedRecursiveWatch(hqRoot, slowFilter, onEvent, () => {});
+      expectLiveBackend(backend);
+      await settle(1500);
+
+      expect(fired).toBe(true);
+      expect(eventsUnder(onEvent, target)).toBeGreaterThan(0);
+    },
+    20000,
+  );
+
+  it(
+    "drops watches BELOW a deleted directory, not just the directory itself",
+    async () => {
+      // The OS reports the removed directory, not each of its descendants, so
+      // a drop that only removes the exact path leaks every watch underneath
+      // it — open handles that never close, plus a stale recursive root that
+      // will mark a later recreation as already-covered. These runners live
+      // for many hours, so the leak accumulates.
+      const outer = path.join(hqRoot, "outer");
+      // `excluded` children make outer and outer/inner SHALLOW, so both they
+      // and their in-scope children each hold their own watch.
+      await mkdir(path.join(outer, "excluded"), { recursive: true });
+      await mkdir(path.join(outer, "inner", "excluded"), { recursive: true });
+      await mkdir(path.join(outer, "inner", "keep"), { recursive: true });
+      await mkdir(path.join(hqRoot, "excluded"), { recursive: true });
+
+      const onEvent = vi.fn();
+      backend = startScopedRecursiveWatch(
+        hqRoot,
+        makeFilter(hqRoot),
+        onEvent,
+        () => {},
+      );
+      expectLiveBackend(backend);
+      const before = backend.watchedPathCount();
+      // hqRoot + outer + outer/inner + outer/inner/keep
+      expect(before).toBeGreaterThanOrEqual(4);
+      await settle(2600);
+
+      await rm(outer, { recursive: true, force: true });
+      await settle();
+
+      // Every watch at or below `outer` must be gone — only hqRoot remains.
+      expect(backend.watchedPathCount()).toBe(1);
+    },
+    25000,
+  );
+
+  it(
+    "keeps re-planning bounded when several exclusions appear at once",
+    async () => {
+      // Each newly-created excluded directory under a recursive root forces a
+      // re-plan, and a re-plan walks that root's subtree synchronously — so an
+      // install creating many excluded directories at once looks like it should
+      // cost that walk once per directory, on the event loop.
+      //
+      // It does not, and this test pins WHY: the first re-plan SPLITS the
+      // covering root, so each subsequent exclusion is re-planned against a
+      // much smaller root. The work is self-limiting. This is a guard, not a
+      // regression test — it passes without any coalescing precisely because
+      // the splitting already bounds the cost, and it would start failing if a
+      // future change made re-plans walk from the top each time.
+      const work = path.join(hqRoot, "work");
+      for (const n of ["p1", "p2", "p3", "p4"]) {
+        await mkdir(path.join(work, n, "src"), { recursive: true });
+      }
+      const seen = vi.fn();
+      backend = startScopedRecursiveWatch(
+        hqRoot,
+        makeFilter(hqRoot),
+        () => {},
+        () => {},
+        seen,
+      );
+      expectLiveBackend(backend);
+      await settle(2600);
+
+      // One directory visit per in-scope dir per walk. Four exclusions
+      // appearing together must cost ONE walk, not four.
+      const perWalk = seen.mock.calls.length;
+      expect(perWalk).toBeGreaterThan(0);
+      seen.mockClear();
+
+      await Promise.all(
+        ["p1", "p2", "p3", "p4"].map((n) =>
+          mkdir(path.join(work, n, "excluded"), { recursive: true }),
+        ),
+      );
+      await settle(2000);
+
+      // Allow one full walk plus slack; four independent walks would be ~4x.
+      expect(seen.mock.calls.length).toBeLessThan(perWalk * 2);
+    },
+    30000,
+  );
+
+  it(
+    "does not report an error when a watched directory is simply deleted",
+    async () => {
+      // A deleted watched root could plausibly be re-added by a re-plan, with
+      // fs.watch then throwing ENOENT and surfacing a watcher error plus a full
+      // resync for an ordinary delete. It is not, because the stale-handle drop
+      // returns before any re-plan is considered. A guard on that ordering:
+      // deleting a directory must stay silent.
+      const work = path.join(hqRoot, "work");
+      await mkdir(path.join(work, "keep"), { recursive: true });
+      await mkdir(path.join(hqRoot, "excluded"), { recursive: true });
+
+      const errors: unknown[] = [];
+      backend = startScopedRecursiveWatch(
+        hqRoot,
+        makeFilter(hqRoot),
+        () => {},
+        (e) => errors.push(e),
+      );
+      expectLiveBackend(backend);
+      await settle(2600);
+
+      await rm(work, { recursive: true, force: true });
+      await settle(1500);
+
+      expect(errors).toEqual([]);
+    },
+    25000,
+  );
+
+  it("reports attach failures so the caller can reject a partial plan", async () => {
+    // Real attach failure, no mocking: `b/` is planned during the walk, then
+    // deleted before applyPlan reaches it, so its fs.watch throws ENOENT.
+    // A planned root we could not attach is a permanent hole in coverage —
+    // the caller must see it and fall back rather than run half-blind.
+    const doomed = path.join(hqRoot, "b");
+    await mkdir(path.join(hqRoot, "a"), { recursive: true });
+    await mkdir(doomed, { recursive: true });
+    // An exclusion at the root keeps hqRoot shallow, so `a/` and `b/` are
+    // planned as their own recursive roots instead of collapsing into one.
+    await mkdir(path.join(hqRoot, "excluded"), { recursive: true });
+
+    const errors: unknown[] = [];
+    const { rmSync } = await import("node:fs");
+    backend = startScopedRecursiveWatch(
+      hqRoot,
+      makeFilter(hqRoot),
+      () => {},
+      (e) => errors.push(e),
+      (dir) => {
+        if (dir === doomed) rmSync(doomed, { recursive: true, force: true });
+      },
+    );
+
+    expect(backend.attachFailures).toBeGreaterThan(0);
+    expect(errors.length).toBeGreaterThan(0);
+  }, 20000);
+});