@mandujs/core 0.53.3 → 0.54.1

package/src/bundler/safe-build.test.ts

@@ -1,201 +1,201 @@
-import { describe, it, expect, beforeEach, afterEach } from "bun:test";
-import { mkdtemp, writeFile, rm } from "fs/promises";
-import { tmpdir } from "os";
-import path from "path";
-
-import { safeBuild, _getConcurrencyState } from "./safe-build";
-
-/**
- * These tests verify that safeBuild caps concurrent Bun.build invocations.
- * We build tiny entrypoints; correctness of the output is not under test here —
- * that's covered by build.test.ts. We're testing the semaphore only.
- */
-
-let rootDir: string;
-
-beforeEach(async () => {
-  rootDir = await mkdtemp(path.join(tmpdir(), "mandu-safebuild-test-"));
-});
-
-afterEach(async () => {
-  try {
-    await rm(rootDir, { recursive: true, force: true });
-  } catch {
-    // Windows may hold locks briefly after Bun.build
-  }
-});
-
-async function makeEntry(name: string, body = "export const x = 1;\n"): Promise<string> {
-  const file = path.join(rootDir, `${name}.ts`);
-  await writeFile(file, body);
-  return file;
-}
-
-describe("safeBuild", () => {
-  it("returns the same BuildOutput shape as Bun.build", async () => {
-    const entry = await makeEntry("a");
-    const result = await safeBuild({
-      entrypoints: [entry],
-      outdir: rootDir,
-      target: "browser",
-    });
-    expect(result.success).toBe(true);
-    expect(Array.isArray(result.outputs)).toBe(true);
-    expect(result.outputs.length).toBeGreaterThan(0);
-  });
-
-  it("propagates build errors without swallowing them", async () => {
-    const entry = await makeEntry("b", "import x from './does-not-exist';\nexport default x;\n");
-    // Bun.build either returns { success: false } or throws AggregateError
-    // depending on the failure mode. safeBuild must propagate either without
-    // altering semantics.
-    let caught: unknown = null;
-    let result: Awaited<ReturnType<typeof safeBuild>> | null = null;
-    try {
-      result = await safeBuild({
-        entrypoints: [entry],
-        outdir: rootDir,
-        target: "browser",
-      });
-    } catch (err) {
-      caught = err;
-    }
-    const softFailed = result !== null && !result.success;
-    const hardFailed = caught !== null;
-    expect(softFailed || hardFailed).toBe(true);
-  });
-
-  it("caps concurrent builds (never exceeds max) under fan-out", async () => {
-    const { max } = _getConcurrencyState();
-    expect(max).toBeGreaterThanOrEqual(1);
-
-    const entries = await Promise.all(
-      Array.from({ length: 8 }, (_, i) => makeEntry(`fan-${i}`)),
-    );
-
-    // Sample concurrency peak on a microtask schedule.
-    let peak = 0;
-    const sampler = setInterval(() => {
-      const { active } = _getConcurrencyState();
-      if (active > peak) peak = active;
-    }, 0);
-
-    try {
-      const results = await Promise.all(
-        entries.map((entry) =>
-          safeBuild({
-            entrypoints: [entry],
-            outdir: rootDir,
-            target: "browser",
-            naming: path.basename(entry, ".ts") + ".[ext]",
-          }),
-        ),
-      );
-      for (const r of results) {
-        expect(r.success).toBe(true);
-      }
-    } finally {
-      clearInterval(sampler);
-    }
-
-    // Peak observed concurrency must be <= max. Exact equality is not
-    // guaranteed because all 8 may resolve faster than the sampler ticks,
-    // but crucially peak must never exceed the cap.
-    expect(peak).toBeLessThanOrEqual(max);
-  });
-
-  it("drains the queue: all builds eventually complete", async () => {
-    const entries = await Promise.all(
-      Array.from({ length: 6 }, (_, i) => makeEntry(`drain-${i}`)),
-    );
-    const results = await Promise.all(
-      entries.map((entry) =>
-        safeBuild({
-          entrypoints: [entry],
-          outdir: rootDir,
-          target: "browser",
-          naming: path.basename(entry, ".ts") + ".[ext]",
-        }),
-      ),
-    );
-    expect(results.every((r) => r.success)).toBe(true);
-
-    // Semaphore must be fully released
-    const state = _getConcurrencyState();
-    expect(state.active).toBe(0);
-    expect(state.queued).toBe(0);
-  });
-
-  it("slot handoff — new callers cannot bypass queued waiters (regression for cap+1 race)", async () => {
-    // Scenario: a build completes with a waiter queued; a NEW safeBuild call
-    // fires on the same microtask. A prior revision decremented `active`
-    // before resolving the waiter, leaving a microtask-sized window where
-    // the new caller saw `active < max`, skipped the wait, and became the
-    // cap+1 concurrent build. This test launches 3*max + 1 builds, samples
-    // active at every slot release, and asserts the peak never exceeds max.
-    const { max } = _getConcurrencyState();
-    const N = max * 3 + 1; // always enough to trigger at least one handoff
-    const entries = await Promise.all(
-      Array.from({ length: N }, (_, i) => makeEntry(`handoff-${i}`)),
-    );
-
-    let peak = 0;
-    let samples = 0;
-    // Sample active-slot count while the build burst is in flight. An earlier
-    // revision of this test used a `while (!stop) { await Promise.resolve() }`
-    // microtask busy-loop to push sampling granularity below setInterval's
-    // Windows 4ms-ish clamp. That deadlocks under Bun 1.3.x on Windows:
-    // `await Promise.resolve()` stays on the microtask queue, which runs
-    // to exhaustion before Bun's libuv I/O phase — so Bun.build completion
-    // callbacks never fire, `releaseSlot()` never runs, and the promises
-    // returned by the 7 parallel `safeBuild()` calls hang indefinitely.
-    // Reproduction: `bun test src/bundler/safe-build.test.ts` times out with
-    // only the banner printed (confirmed with a standalone repro of the
-    // sampler + 7 safeBuild calls — hung at "start" past 60s).
-    //
-    // Fix: yield to the macrotask queue via `setImmediate`. This lets
-    // libuv I/O callbacks run between samples, so Bun.build completes and
-    // `releaseSlot()` advances the queue. Per-tick granularity on Node/Bun
-    // is still sub-millisecond and fires ~hundreds of times during a 7-
-    // build burst — more than enough to statistically catch the cap+1
-    // regression window if it ever returned (the window is microtask-sized,
-    // but any cross-tick sampling with high fan-out has a realistic chance
-    // of landing inside it). The strict assertion is still `peak <= max`.
-    let stop = false;
-    const sample = async () => {
-      for (;;) {
-        if (stop) break;
-        const { active } = _getConcurrencyState();
-        if (active > peak) peak = active;
-        samples++;
-        // Yield to libuv I/O phase so Bun.build callbacks can fire.
-        await new Promise<void>((resolve) => setImmediate(resolve));
-      }
-    };
-    const sampler = sample();
-
-    try {
-      const results = await Promise.all(
-        entries.map((entry) =>
-          safeBuild({
-            entrypoints: [entry],
-            outdir: rootDir,
-            target: "browser",
-            naming: path.basename(entry, ".ts") + ".[ext]",
-          }),
-        ),
-      );
-      expect(results.every((r) => r.success)).toBe(true);
-    } finally {
-      stop = true;
-      await sampler;
-    }
-
-    expect(peak).toBeLessThanOrEqual(max);
-    expect(samples).toBeGreaterThan(0);
-
-    const state = _getConcurrencyState();
-    expect(state.active).toBe(0);
-    expect(state.queued).toBe(0);
-  });
-});
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtemp, writeFile, rm } from "fs/promises";
+import { tmpdir } from "os";
+import path from "path";
+
+import { safeBuild, _getConcurrencyState } from "./safe-build";
+
+/**
+ * These tests verify that safeBuild caps concurrent Bun.build invocations.
+ * We build tiny entrypoints; correctness of the output is not under test here —
+ * that's covered by build.test.ts. We're testing the semaphore only.
+ */
+
+let rootDir: string;
+
+beforeEach(async () => {
+  rootDir = await mkdtemp(path.join(tmpdir(), "mandu-safebuild-test-"));
+});
+
+afterEach(async () => {
+  try {
+    await rm(rootDir, { recursive: true, force: true });
+  } catch {
+    // Windows may hold locks briefly after Bun.build
+  }
+});
+
+async function makeEntry(name: string, body = "export const x = 1;\n"): Promise<string> {
+  const file = path.join(rootDir, `${name}.ts`);
+  await writeFile(file, body);
+  return file;
+}
+
+describe("safeBuild", () => {
+  it("returns the same BuildOutput shape as Bun.build", async () => {
+    const entry = await makeEntry("a");
+    const result = await safeBuild({
+      entrypoints: [entry],
+      outdir: rootDir,
+      target: "browser",
+    });
+    expect(result.success).toBe(true);
+    expect(Array.isArray(result.outputs)).toBe(true);
+    expect(result.outputs.length).toBeGreaterThan(0);
+  });
+
+  it("propagates build errors without swallowing them", async () => {
+    const entry = await makeEntry("b", "import x from './does-not-exist';\nexport default x;\n");
+    // Bun.build either returns { success: false } or throws AggregateError
+    // depending on the failure mode. safeBuild must propagate either without
+    // altering semantics.
+    let caught: unknown = null;
+    let result: Awaited<ReturnType<typeof safeBuild>> | null = null;
+    try {
+      result = await safeBuild({
+        entrypoints: [entry],
+        outdir: rootDir,
+        target: "browser",
+      });
+    } catch (err) {
+      caught = err;
+    }
+    const softFailed = result !== null && !result.success;
+    const hardFailed = caught !== null;
+    expect(softFailed || hardFailed).toBe(true);
+  });
+
+  it("caps concurrent builds (never exceeds max) under fan-out", async () => {
+    const { max } = _getConcurrencyState();
+    expect(max).toBeGreaterThanOrEqual(1);
+
+    const entries = await Promise.all(
+      Array.from({ length: 8 }, (_, i) => makeEntry(`fan-${i}`)),
+    );
+
+    // Sample concurrency peak on a microtask schedule.
+    let peak = 0;
+    const sampler = setInterval(() => {
+      const { active } = _getConcurrencyState();
+      if (active > peak) peak = active;
+    }, 0);
+
+    try {
+      const results = await Promise.all(
+        entries.map((entry) =>
+          safeBuild({
+            entrypoints: [entry],
+            outdir: rootDir,
+            target: "browser",
+            naming: path.basename(entry, ".ts") + ".[ext]",
+          }),
+        ),
+      );
+      for (const r of results) {
+        expect(r.success).toBe(true);
+      }
+    } finally {
+      clearInterval(sampler);
+    }
+
+    // Peak observed concurrency must be <= max. Exact equality is not
+    // guaranteed because all 8 may resolve faster than the sampler ticks,
+    // but crucially peak must never exceed the cap.
+    expect(peak).toBeLessThanOrEqual(max);
+  });
+
+  it("drains the queue: all builds eventually complete", async () => {
+    const entries = await Promise.all(
+      Array.from({ length: 6 }, (_, i) => makeEntry(`drain-${i}`)),
+    );
+    const results = await Promise.all(
+      entries.map((entry) =>
+        safeBuild({
+          entrypoints: [entry],
+          outdir: rootDir,
+          target: "browser",
+          naming: path.basename(entry, ".ts") + ".[ext]",
+        }),
+      ),
+    );
+    expect(results.every((r) => r.success)).toBe(true);
+
+    // Semaphore must be fully released
+    const state = _getConcurrencyState();
+    expect(state.active).toBe(0);
+    expect(state.queued).toBe(0);
+  });
+
+  it("slot handoff — new callers cannot bypass queued waiters (regression for cap+1 race)", async () => {
+    // Scenario: a build completes with a waiter queued; a NEW safeBuild call
+    // fires on the same microtask. A prior revision decremented `active`
+    // before resolving the waiter, leaving a microtask-sized window where
+    // the new caller saw `active < max`, skipped the wait, and became the
+    // cap+1 concurrent build. This test launches 3*max + 1 builds, samples
+    // active at every slot release, and asserts the peak never exceeds max.
+    const { max } = _getConcurrencyState();
+    const N = max * 3 + 1; // always enough to trigger at least one handoff
+    const entries = await Promise.all(
+      Array.from({ length: N }, (_, i) => makeEntry(`handoff-${i}`)),
+    );
+
+    let peak = 0;
+    let samples = 0;
+    // Sample active-slot count while the build burst is in flight. An earlier
+    // revision of this test used a `while (!stop) { await Promise.resolve() }`
+    // microtask busy-loop to push sampling granularity below setInterval's
+    // Windows 4ms-ish clamp. That deadlocks under Bun 1.3.x on Windows:
+    // `await Promise.resolve()` stays on the microtask queue, which runs
+    // to exhaustion before Bun's libuv I/O phase — so Bun.build completion
+    // callbacks never fire, `releaseSlot()` never runs, and the promises
+    // returned by the 7 parallel `safeBuild()` calls hang indefinitely.
+    // Reproduction: `bun test src/bundler/safe-build.test.ts` times out with
+    // only the banner printed (confirmed with a standalone repro of the
+    // sampler + 7 safeBuild calls — hung at "start" past 60s).
+    //
+    // Fix: yield to the macrotask queue via `setImmediate`. This lets
+    // libuv I/O callbacks run between samples, so Bun.build completes and
+    // `releaseSlot()` advances the queue. Per-tick granularity on Node/Bun
+    // is still sub-millisecond and fires ~hundreds of times during a 7-
+    // build burst — more than enough to statistically catch the cap+1
+    // regression window if it ever returned (the window is microtask-sized,
+    // but any cross-tick sampling with high fan-out has a realistic chance
+    // of landing inside it). The strict assertion is still `peak <= max`.
+    let stop = false;
+    const sample = async () => {
+      for (;;) {
+        if (stop) break;
+        const { active } = _getConcurrencyState();
+        if (active > peak) peak = active;
+        samples++;
+        // Yield to libuv I/O phase so Bun.build callbacks can fire.
+        await new Promise<void>((resolve) => setImmediate(resolve));
+      }
+    };
+    const sampler = sample();
+
+    try {
+      const results = await Promise.all(
+        entries.map((entry) =>
+          safeBuild({
+            entrypoints: [entry],
+            outdir: rootDir,
+            target: "browser",
+            naming: path.basename(entry, ".ts") + ".[ext]",
+          }),
+        ),
+      );
+      expect(results.every((r) => r.success)).toBe(true);
+    } finally {
+      stop = true;
+      await sampler;
+    }
+
+    expect(peak).toBeLessThanOrEqual(max);
+    expect(samples).toBeGreaterThan(0);
+
+    const state = _getConcurrencyState();
+    expect(state.active).toBe(0);
+    expect(state.queued).toBe(0);
+  });
+});

package/src/bundler/safe-build.ts

@@ -1,103 +1,103 @@
-/**
- * Concurrency-limited wrapper around `Bun.build`.
- *
- * Why this exists:
- * - `Bun.build` exhibits failure modes under high concurrent invocation —
- *   observed as `AggregateError: Bundle failed` with missing output shims
- *   (e.g. `_react-dom-client.js`) when 5+ builds fire in parallel and
- *   multiple test worker processes pile on simultaneously.
- * - Our own `buildClientBundles` fans out vendor-shim builds via `Promise.all`
- *   (5 concurrent). Combined with parallel test workers or concurrent dev-mode
- *   rebuilds, total concurrent `Bun.build` invocations can exceed what the
- *   runtime/OS resolves reliably, yielding intermittent failures that are
- *   hard to diagnose.
- *
- * Design:
- * - Process-wide semaphore. Default cap: `2` concurrent `Bun.build` per
- *   process. Tunable via `MANDU_BUN_BUILD_CONCURRENCY` (positive integer).
- * - FIFO queue — no priority, no cancellation. Callers get `Bun.build`'s
- *   `BuildOutput` result (or exception) transparently.
- * - In-process only. Cross-worker coordination is not this module's job;
- *   per-worker throttling already prevents the observed failure modes in
- *   our test matrix.
- *
- * Correctness — slot handoff:
- * - The semaphore does slot *handoff* rather than release-then-acquire. When
- *   a build completes with waiters queued, the slot is transferred directly
- *   to the next waiter (active count never drops). A previous revision had
- *   a classic acquire race: `releaseSlot()` decremented `active` before the
- *   waiter's `active++` ran, which opened a microtask-sized window where a
- *   concurrent `safeBuild()` call could observe `active < max`, skip the
- *   wait, and join in — yielding `cap+1` concurrent builds.
- */
-
-import type { BuildConfig, BuildOutput } from "bun";
-
-const DEFAULT_MAX_CONCURRENT = 2;
-
-function parseMaxConcurrent(): number {
-  const raw = process.env.MANDU_BUN_BUILD_CONCURRENCY;
-  if (!raw) return DEFAULT_MAX_CONCURRENT;
-  const parsed = Number.parseInt(raw, 10);
-  if (!Number.isFinite(parsed) || parsed < 1) return DEFAULT_MAX_CONCURRENT;
-  return parsed;
-}
-
-const maxConcurrent = parseMaxConcurrent();
-let active = 0;
-const waiters: Array<() => void> = [];
-
-/**
- * Acquire a slot. When `active < max`, increment synchronously and return.
- * Otherwise, queue and await a direct handoff from a completing build —
- * the completing build does NOT decrement `active`; it resolves our waiter,
- * and `active` stays at `max` through the transition. This prevents a
- * microtask-window race where a third caller could see `active < max` and
- * skip the wait entirely.
- */
-function acquireSlot(): Promise<void> {
-  if (active < maxConcurrent) {
-    active++;
-    return Promise.resolve();
-  }
-  return new Promise<void>((resolve) => {
-    waiters.push(resolve);
-  });
-}
-
-/**
- * Release a slot. If a waiter is queued, hand the slot off directly (keep
- * `active` at `max`, resolve the waiter). Otherwise decrement `active`.
- */
-function releaseSlot(): void {
-  const next = waiters.shift();
-  if (next) {
-    // Direct handoff — `active` stays at max, waiter resumes holding the slot.
-    next();
-  } else {
-    active--;
-  }
-}
-
-/**
- * Runs `Bun.build(options)` subject to a process-wide concurrency cap.
- * Preserves the exact return type and error semantics of `Bun.build`.
- *
- * Note: this wrapper only caps concurrency *within* a single process. Test
- * harnesses that spawn multiple worker processes still see each worker run
- * up to `maxConcurrent` concurrent builds — see Phase 0.6 for cross-process
- * coordination work.
- */
-export async function safeBuild(options: BuildConfig): Promise<BuildOutput> {
-  await acquireSlot();
-  try {
-    return await Bun.build(options);
-  } finally {
-    releaseSlot();
-  }
-}
-
-/** Exposed for tests — not part of the public API. */
-export function _getConcurrencyState() {
-  return { active, queued: waiters.length, max: maxConcurrent };
-}
+/**
+ * Concurrency-limited wrapper around `Bun.build`.
+ *
+ * Why this exists:
+ * - `Bun.build` exhibits failure modes under high concurrent invocation —
+ *   observed as `AggregateError: Bundle failed` with missing output shims
+ *   (e.g. `_react-dom-client.js`) when 5+ builds fire in parallel and
+ *   multiple test worker processes pile on simultaneously.
+ * - Our own `buildClientBundles` fans out vendor-shim builds via `Promise.all`
+ *   (5 concurrent). Combined with parallel test workers or concurrent dev-mode
+ *   rebuilds, total concurrent `Bun.build` invocations can exceed what the
+ *   runtime/OS resolves reliably, yielding intermittent failures that are
+ *   hard to diagnose.
+ *
+ * Design:
+ * - Process-wide semaphore. Default cap: `2` concurrent `Bun.build` per
+ *   process. Tunable via `MANDU_BUN_BUILD_CONCURRENCY` (positive integer).
+ * - FIFO queue — no priority, no cancellation. Callers get `Bun.build`'s
+ *   `BuildOutput` result (or exception) transparently.
+ * - In-process only. Cross-worker coordination is not this module's job;
+ *   per-worker throttling already prevents the observed failure modes in
+ *   our test matrix.
+ *
+ * Correctness — slot handoff:
+ * - The semaphore does slot *handoff* rather than release-then-acquire. When
+ *   a build completes with waiters queued, the slot is transferred directly
+ *   to the next waiter (active count never drops). A previous revision had
+ *   a classic acquire race: `releaseSlot()` decremented `active` before the
+ *   waiter's `active++` ran, which opened a microtask-sized window where a
+ *   concurrent `safeBuild()` call could observe `active < max`, skip the
+ *   wait, and join in — yielding `cap+1` concurrent builds.
+ */
+
+import type { BuildConfig, BuildOutput } from "bun";
+
+const DEFAULT_MAX_CONCURRENT = 2;
+
+function parseMaxConcurrent(): number {
+  const raw = process.env.MANDU_BUN_BUILD_CONCURRENCY;
+  if (!raw) return DEFAULT_MAX_CONCURRENT;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed < 1) return DEFAULT_MAX_CONCURRENT;
+  return parsed;
+}
+
+const maxConcurrent = parseMaxConcurrent();
+let active = 0;
+const waiters: Array<() => void> = [];
+
+/**
+ * Acquire a slot. When `active < max`, increment synchronously and return.
+ * Otherwise, queue and await a direct handoff from a completing build —
+ * the completing build does NOT decrement `active`; it resolves our waiter,
+ * and `active` stays at `max` through the transition. This prevents a
+ * microtask-window race where a third caller could see `active < max` and
+ * skip the wait entirely.
+ */
+function acquireSlot(): Promise<void> {
+  if (active < maxConcurrent) {
+    active++;
+    return Promise.resolve();
+  }
+  return new Promise<void>((resolve) => {
+    waiters.push(resolve);
+  });
+}
+
+/**
+ * Release a slot. If a waiter is queued, hand the slot off directly (keep
+ * `active` at `max`, resolve the waiter). Otherwise decrement `active`.
+ */
+function releaseSlot(): void {
+  const next = waiters.shift();
+  if (next) {
+    // Direct handoff — `active` stays at max, waiter resumes holding the slot.
+    next();
+  } else {
+    active--;
+  }
+}
+
+/**
+ * Runs `Bun.build(options)` subject to a process-wide concurrency cap.
+ * Preserves the exact return type and error semantics of `Bun.build`.
+ *
+ * Note: this wrapper only caps concurrency *within* a single process. Test
+ * harnesses that spawn multiple worker processes still see each worker run
+ * up to `maxConcurrent` concurrent builds — see Phase 0.6 for cross-process
+ * coordination work.
+ */
+export async function safeBuild(options: BuildConfig): Promise<BuildOutput> {
+  await acquireSlot();
+  try {
+    return await Bun.build(options);
+  } finally {
+    releaseSlot();
+  }
+}
+
+/** Exposed for tests — not part of the public API. */
+export function _getConcurrencyState() {
+  return { active, queued: waiters.length, max: maxConcurrent };
+}