@indigoai-us/hq-cloud 6.14.43 → 6.14.45

package/src/watcher-event-gate.test.ts

@@ -0,0 +1,212 @@
+/**
+ * The emit filter must run BEFORE handleEvent pays for a stat.
+ *
+ * The recursive backend hands every OS event to handleEvent, and a `rename`
+ * used to be lstat'd before the exclusion filter was consulted. On a real HQ
+ * that is one synchronous syscall for every file touched anywhere under
+ * `repos/` or `workspace/worktrees/` — build, install, and checkout churn the
+ * watcher immediately throws away. Scoped watch roots (see watch-roots.ts) keep
+ * most of that traffic from being delivered at all; this gate makes whatever
+ * still arrives cost a string compare instead of a syscall.
+ *
+ * This lives in its own file because it mocks `fs` module-wide, which would
+ * otherwise perturb the 53 tests in watcher.test.ts.
+ */
+
+import * as os from "os";
+import * as path from "path";
+
+import { describe, expect, it, vi } from "vitest";
+
+const { lstatCalls } = vi.hoisted(() => ({ lstatCalls: vi.fn() }));
+
+vi.mock("fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("fs")>();
+  return {
+    ...actual,
+    lstatSync: (...args: Parameters<typeof actual.lstatSync>) => {
+      lstatCalls(...args);
+      return actual.lstatSync(...args);
+    },
+  };
+});
+
+const { FakeClock, TreeWatcher } = await import("./watcher.js");
+
+const hqRoot = path.join(os.tmpdir(), "hqcloud-event-gate-root");
+/** Everything under `repos/` is out of scope, as file AND as directory. */
+const outOfScope = (abs: string) => !abs.split(path.sep).includes("repos");
+
+function makeWatcher() {
+  return new TreeWatcher({
+    hqRoot,
+    clock: new FakeClock(),
+    debounceMs: 100,
+    pathFilter: outOfScope,
+  });
+}
+
+describe("TreeWatcher.handleEvent — an excluded path costs no syscall", () => {
+  it("does NOT stat an out-of-scope rename before dropping it", () => {
+    const watcher = makeWatcher();
+    lstatCalls.mockClear();
+    try {
+      watcher.handleEvent(
+        path.join(hqRoot, "repos", "hq-cloud", "src", "a.ts"),
+        "rename",
+      );
+      expect(lstatCalls).not.toHaveBeenCalled();
+    } finally {
+      watcher.dispose();
+    }
+  });
+
+  it("still stats an in-scope rename, so kind classification is unchanged", () => {
+    const watcher = makeWatcher();
+    lstatCalls.mockClear();
+    try {
+      watcher.handleEvent(
+        path.join(hqRoot, "companies", "acme", "note.md"),
+        "rename",
+      );
+      expect(lstatCalls).toHaveBeenCalled();
+    } finally {
+      watcher.dispose();
+    }
+  });
+
+  it("skips its own seed walk when the backend already indexed directories", async () => {
+    // The scoped backend indexes every in-scope directory while planning its
+    // watch roots. TreeWatcher must NOT then walk the same tree again — on a
+    // real HQ root that walk is ~3.6s, and doing it twice per runner start was
+    // a straight doubling of startup cost for an identical index.
+    const fsp = await import("node:fs/promises");
+    const realRoot = await fsp.mkdtemp(
+      path.join(os.tmpdir(), "hqcloud-seed-fusion-"),
+    );
+    try {
+      await fsp.mkdir(path.join(realRoot, "companies", "acme", "knowledge"), {
+        recursive: true,
+      });
+
+      const watcher = new TreeWatcher({
+        hqRoot: realRoot,
+        clock: new FakeClock(),
+        pathFilter: () => true,
+        backendFactory: (opts) => {
+          opts.onDirectorySeen?.(path.join(realRoot, "companies"));
+          return {
+            close: () => {},
+            needsKnownKinds: true,
+            seededKnownKinds: true,
+            watchedPathCount: () => 1,
+          };
+        },
+      });
+      watcher.start();
+      // Exactly the one directory the backend reported — not the three that a
+      // second full walk of this tree would have found.
+      expect(watcher.knownDirectoryCount()).toBe(1);
+      watcher.dispose();
+    } finally {
+      await fsp.rm(realRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("still walks itself when the backend did NOT index directories", async () => {
+    const fsp = await import("node:fs/promises");
+    const realRoot = await fsp.mkdtemp(
+      path.join(os.tmpdir(), "hqcloud-seed-legacy-"),
+    );
+    try {
+      await fsp.mkdir(path.join(realRoot, "companies", "acme", "knowledge"), {
+        recursive: true,
+      });
+
+      const watcher = new TreeWatcher({
+        hqRoot: realRoot,
+        clock: new FakeClock(),
+        pathFilter: () => true,
+        backendFactory: () => ({
+          close: () => {},
+          needsKnownKinds: true,
+          watchedPathCount: () => 1,
+        }),
+      });
+      watcher.start();
+      expect(watcher.knownDirectoryCount()).toBe(3);
+      watcher.dispose();
+    } finally {
+      await fsp.rm(realRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("does not let a duplicate delete downgrade unlinkDir to unlink", () => {
+    // One path can reach handleEvent twice when two watches overlap (the
+    // scoped backend briefly runs its bootstrap watch alongside the planned
+    // ones so in-flight events are not dropped). The first unlinkDir clears
+    // the path's known-kind hint, so without this guard the duplicate lands as
+    // a plain `unlink` — narrowing the deletion scope the vault applies and
+    // discarding the captured descendant snapshots.
+    const clock = new FakeClock();
+    const w = new TreeWatcher({
+      hqRoot,
+      clock,
+      debounceMs: 100,
+      pathFilter: () => true,
+      captureLocalDeleteSnapshots: (relativePath, kind) =>
+        kind === "unlinkDir"
+          ? [
+              {
+                journalSlug: "acme",
+                journalPath: `${relativePath}/child.md`,
+                absolutePath: path.join(hqRoot, relativePath, "child.md"),
+                remoteEtag: "etag",
+                localHash: "hash",
+                localKind: "file" as const,
+              },
+            ]
+          : [],
+    });
+    const batches: Array<Map<string, { kind: string }> | undefined> = [];
+    w.onChange((_first, batch) => batches.push(batch?.changes as never));
+    try {
+      const dir = path.join(hqRoot, "companies", "acme", "moved");
+      w.handleEvent(dir, "unlinkDir");
+      w.handleEvent(dir, "unlink"); // duplicate delivery of the same delete
+      clock.advance(200);
+
+      const change = batches[0]?.get(dir) as
+        | { kind: string; deleteSnapshots?: unknown[] }
+        | undefined;
+      expect(change?.kind).toBe("unlinkDir");
+      expect(change?.deleteSnapshots).toHaveLength(1);
+    } finally {
+      w.dispose();
+    }
+  });
+
+  it("keeps emitting in-scope changes after the gate", () => {
+    const watcher = makeWatcher();
+    const clock = new FakeClock();
+    const w = new TreeWatcher({
+      hqRoot,
+      clock,
+      debounceMs: 100,
+      pathFilter: outOfScope,
+    });
+    watcher.dispose();
+    const rels: string[] = [];
+    w.onChange((_first, batch) => {
+      if (batch) rels.push(...batch.paths.values());
+    });
+    try {
+      w.handleEvent(path.join(hqRoot, "companies", "acme", "note.md"), "change");
+      w.handleEvent(path.join(hqRoot, "repos", "x", "code.ts"), "change");
+      clock.advance(200);
+      expect(rels).toEqual(["companies/acme/note.md"]);
+    } finally {
+      w.dispose();
+    }
+  });
+});