@dimina-kit/devkit 0.1.2-dev.20260612025610 → 0.1.2-dev.20260615070430

package/dist/rebuild-scheduler.js

@@ -0,0 +1,58 @@
+/**
+ * Serialize rebuild runs with a dirty-flag + trailing rerun, replacing the old
+ * `if (isBuilding) return` early-exit in `openProject`'s rebuild loop, which
+ * silently DROPPED any watcher event that landed while a build was in flight
+ * (a save made during the ~1-2s compile window never produced a rebuild — the
+ * simulator stayed stale until the user saved again).
+ *
+ * Semantics:
+ *  - `schedule()` while idle starts `run` immediately.
+ *  - `schedule()` while `run` is in flight never starts a concurrent run
+ *    (`build()` chdir()s into the project — concurrency would corrupt cwd);
+ *    it marks the state dirty instead.
+ *  - When the in-flight run settles and the state is dirty, exactly one
+ *    trailing run starts: N saves during one build coalesce into 1 rerun.
+ *    The trailing run is itself schedulable-against, recursively.
+ *  - A rejecting run neither wedges the scheduler nor drops a pending dirty
+ *    flag — `run` is expected to do its own error reporting (`onBuildError`).
+ */
+export function createRebuildScheduler(run) {
+    let running = false;
+    let dirty = false;
+    function start() {
+        running = true;
+        // `run` stays synchronously invoked (idle schedule() starts the build
+        // in the same tick), but a SYNCHRONOUS throw must funnel into the same
+        // swallow-and-continue path as a rejection — a bare `run()` call would
+        // let the throw escape before `.catch` attaches, leaving `running`
+        // stuck at true and wedging every future schedule().
+        let settled;
+        try {
+            settled = run();
+        }
+        catch {
+            settled = Promise.reject();
+        }
+        settled
+            .catch(() => {
+            // Failures are `run`'s responsibility to report; the scheduler
+            // only guarantees liveness (no wedge, no lost dirty flag).
+        })
+            .then(() => {
+            running = false;
+            if (dirty) {
+                dirty = false;
+                start();
+            }
+        });
+    }
+    return {
+        schedule() {
+            if (running) {
+                dirty = true;
+                return;
+            }
+            start();
+        },
+    };
+}

package/dist/rebuild-scheduler.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=rebuild-scheduler.test.d.ts.map

package/dist/rebuild-scheduler.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rebuild-scheduler.test.d.ts","sourceRoot":"","sources":["../src/rebuild-scheduler.test.ts"],"names":[],"mappings":""}

package/dist/rebuild-scheduler.test.js

@@ -0,0 +1,201 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import * as devkit from './index.js';
+function getCreateRebuildScheduler() {
+    const factory = devkit.createRebuildScheduler;
+    expect(typeof factory, 'devkit must export createRebuildScheduler(run) — the dirty-flag + trailing-rerun replacement for the "if (isBuilding) return" drop in openProject\'s rebuild()').toBe('function');
+    return factory;
+}
+/** A `run` whose completion the test controls call-by-call. */
+function makeDeferredRun() {
+    const pending = [];
+    const run = vi.fn(() => new Promise((resolve, reject) => {
+        pending.push({ resolve, reject });
+    }));
+    return {
+        run,
+        /** Settle the i-th started run (0-based). */
+        finish: (i) => pending[i].resolve(),
+        fail: (i, err) => pending[i].reject(err),
+    };
+}
+/** Let queued microtasks/then-chains drain. */
+async function settle(ms = 25) {
+    await new Promise(resolve => setTimeout(resolve, ms));
+}
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+describe('createRebuildScheduler — saves during an in-flight build must not be dropped', () => {
+    it('runs the build immediately when idle', async () => {
+        const createRebuildScheduler = getCreateRebuildScheduler();
+        const { run } = makeDeferredRun();
+        const scheduler = createRebuildScheduler(run);
+        scheduler.schedule();
+        await vi.waitFor(() => expect(run).toHaveBeenCalledTimes(1));
+    });
+    it('never starts a concurrent build while one is in flight', async () => {
+        const createRebuildScheduler = getCreateRebuildScheduler();
+        const { run } = makeDeferredRun();
+        const scheduler = createRebuildScheduler(run);
+        scheduler.schedule();
+        await vi.waitFor(() => expect(run).toHaveBeenCalledTimes(1));
+        // Saves landing mid-build must not spawn parallel compiler runs
+        // (build() chdir()s into the project — concurrency would corrupt cwd).
+        scheduler.schedule();
+        scheduler.schedule();
+        await settle();
+        expect(run).toHaveBeenCalledTimes(1);
+    });
+    it('coalesces N saves during one build into EXACTLY ONE trailing rebuild', async () => {
+        const createRebuildScheduler = getCreateRebuildScheduler();
+        const { run, finish } = makeDeferredRun();
+        const scheduler = createRebuildScheduler(run);
+        scheduler.schedule();
+        await vi.waitFor(() => expect(run).toHaveBeenCalledTimes(1));
+        // Three rapid saves while build #0 is still compiling.
+        scheduler.schedule();
+        scheduler.schedule();
+        scheduler.schedule();
+        await settle();
+        expect(run, 'no concurrent run may start').toHaveBeenCalledTimes(1);
+        // Build #0 finishes → the dirty flag triggers ONE trailing rerun.
+        finish(0);
+        await vi.waitFor(() => expect(run).toHaveBeenCalledTimes(2));
+        // The trailing run finishes with nothing else dirty → quiescent.
+        finish(1);
+        await settle();
+        expect(run, '3 saves during one build = 1 trailing rebuild, not 3').toHaveBeenCalledTimes(2);
+    });
+    it('does NOT rerun when nothing was scheduled during the build', async () => {
+        const createRebuildScheduler = getCreateRebuildScheduler();
+        const { run, finish } = makeDeferredRun();
+        const scheduler = createRebuildScheduler(run);
+        scheduler.schedule();
+        await vi.waitFor(() => expect(run).toHaveBeenCalledTimes(1));
+        finish(0);
+        await settle();
+        expect(run, 'a clean build with no mid-flight saves must not loop').toHaveBeenCalledTimes(1);
+    });
+    it('saves during the trailing run coalesce again (chained trailing runs)', async () => {
+        const createRebuildScheduler = getCreateRebuildScheduler();
+        const { run, finish } = makeDeferredRun();
+        const scheduler = createRebuildScheduler(run);
+        scheduler.schedule();
+        await vi.waitFor(() => expect(run).toHaveBeenCalledTimes(1));
+        scheduler.schedule(); // dirty during run #0
+        finish(0);
+        await vi.waitFor(() => expect(run).toHaveBeenCalledTimes(2));
+        scheduler.schedule(); // dirty during trailing run #1
+        scheduler.schedule();
+        finish(1);
+        await vi.waitFor(() => expect(run).toHaveBeenCalledTimes(3));
+        finish(2);
+        await settle();
+        expect(run).toHaveBeenCalledTimes(3);
+    });
+    it('stays usable after the build rejects', async () => {
+        const createRebuildScheduler = getCreateRebuildScheduler();
+        const { run, fail } = makeDeferredRun();
+        const scheduler = createRebuildScheduler(run);
+        scheduler.schedule();
+        await vi.waitFor(() => expect(run).toHaveBeenCalledTimes(1));
+        fail(0, new Error('compile exploded'));
+        await settle();
+        // A later save must still trigger a build — the scheduler must not wedge.
+        scheduler.schedule();
+        await vi.waitFor(() => expect(run).toHaveBeenCalledTimes(2));
+    });
+    it('a save during a FAILING build still gets its trailing rebuild', async () => {
+        const createRebuildScheduler = getCreateRebuildScheduler();
+        const { run, finish, fail } = makeDeferredRun();
+        const scheduler = createRebuildScheduler(run);
+        scheduler.schedule();
+        await vi.waitFor(() => expect(run).toHaveBeenCalledTimes(1));
+        scheduler.schedule(); // the save that fixes the broken code
+        fail(0, new Error('syntax error mid-edit'));
+        // The dirty flag set during the failing build must survive the failure.
+        await vi.waitFor(() => expect(run).toHaveBeenCalledTimes(2));
+        finish(1);
+        await settle();
+        expect(run).toHaveBeenCalledTimes(2);
+    });
+});
+// ─── ROUND 2 — `run` throwing SYNCHRONOUSLY (not rejecting) ──────────────────
+//
+// Regression tests for the wedge found in review: `start()` sets
+// `running = true` and then calls `run()` bare. If `run` throws synchronously
+// (e.g. a config/IO error raised before the build's first await — no promise
+// ever exists), the `.catch().then()` settle chain is never attached, so:
+//   - the exception escapes through `schedule()` to the watcher callsite,
+//   - `running` stays true FOREVER,
+//   - every later `schedule()` only sets `dirty` and is silently swallowed —
+//     the project never rebuilds again until the process restarts.
+//
+// The documented contract ("a failing run neither wedges the scheduler nor
+// drops a pending dirty flag", with failures being `run`'s responsibility to
+// report) must hold regardless of HOW the run fails: rejection and synchronous
+// throw are the same event to the scheduler.
+describe('ROUND 2 — createRebuildScheduler: run() throwing synchronously must not wedge the scheduler', () => {
+    /** A `run` that throws synchronously on the i-th call(s), resolves otherwise. */
+    function makeSyncThrowingRun(throwOnCalls) {
+        const run = vi.fn(() => {
+            if (throwOnCalls.includes(run.mock.calls.length)) {
+                throw new Error('sync failure before any promise exists');
+            }
+            return Promise.resolve();
+        });
+        return run;
+    }
+    it('schedule() does not propagate a synchronous throw from run (same swallow semantics as a rejection)', () => {
+        const createRebuildScheduler = getCreateRebuildScheduler();
+        const run = makeSyncThrowingRun([1]);
+        const scheduler = createRebuildScheduler(run);
+        // BUG CAUGHT: today the throw escapes start() → schedule() → the watcher
+        // callsite, which never expected schedule() to throw.
+        expect(() => scheduler.schedule()).not.toThrow();
+        expect(run).toHaveBeenCalledTimes(1);
+    });
+    it('a later save still triggers a build after run threw synchronously (no permanent running=true wedge)', async () => {
+        const createRebuildScheduler = getCreateRebuildScheduler();
+        const run = makeSyncThrowingRun([1]);
+        const scheduler = createRebuildScheduler(run);
+        // Tolerate the current buggy escape so this test isolates the WEDGE, not
+        // the throw itself (the throw is pinned by the test above).
+        try {
+            scheduler.schedule();
+        }
+        catch {
+            // current buggy behavior — swallowed so we can probe liveness
+        }
+        expect(run).toHaveBeenCalledTimes(1);
+        await settle();
+        // BUG CAUGHT: `running` was never reset, so this schedule() only sets
+        // `dirty` and the rebuild is silently dropped forever.
+        scheduler.schedule();
+        await vi.waitFor(() => expect(run).toHaveBeenCalledTimes(2));
+    });
+    it('a dirty flag set during a synchronously-throwing run still gets its trailing rebuild', async () => {
+        const createRebuildScheduler = getCreateRebuildScheduler();
+        // Run #1: a watcher event lands re-entrantly while the build is starting
+        // (running=true → marks dirty), THEN the build throws synchronously.
+        const run = vi.fn(() => {
+            if (run.mock.calls.length === 1) {
+                scheduler.schedule(); // the save that fixes the broken state
+                throw new Error('sync failure before any promise exists');
+            }
+            return Promise.resolve();
+        });
+        const scheduler = createRebuildScheduler(run);
+        try {
+            scheduler.schedule();
+        }
+        catch {
+            // current buggy behavior — swallowed so we can probe the dirty flag
+        }
+        // BUG CAUGHT: the dirty flag set during run #1 is never consumed because
+        // the settle chain (which performs the trailing rerun) was never attached.
+        await vi.waitFor(() => expect(run).toHaveBeenCalledTimes(2));
+        await settle();
+        expect(run, 'exactly one trailing rebuild — no loop').toHaveBeenCalledTimes(2);
+    });
+});

package/dist/watch-rebuild.testutil.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Write `file` with `contentFor(attempt)`; if `settled` (e.g. the onRebuild
+ * promise) does not resolve within ~400ms, re-write with the next attempt's
+ * content (guaranteed size/mtime change → fresh inotify event) and keep
+ * retrying until `settled` resolves or the test's own vitest timeout fires.
+ *
+ * `contentFor` MUST embed `attempt` so successive writes differ in length —
+ * an identical-bytes rewrite can be coalesced by the OS into no new event.
+ */
+export declare function writeUntilSettled(settled: Promise<unknown>, file: string, contentFor: (attempt: number) => string): Promise<void>;
+/**
+ * Like `writeUntilSettled` but waits on a polled PREDICATE instead of a
+ * promise — for the `vi.waitFor(buildSends === N)` / `logEntries.length > 0`
+ * style waiters where the thing being awaited is observable state, not a
+ * one-shot resolve. Re-writes the file every ~400ms until `predicate()` is
+ * true. Same coalescing-safety contract: predicate must be count-agnostic /
+ * monotone-reached (a `>=`, a "saw output", or a stable equality that extra
+ * coalesced rebuilds cannot overshoot).
+ */
+export declare function writeUntilPredicate(predicate: () => boolean, file: string, contentFor: (attempt: number) => string): Promise<void>;
+//# sourceMappingURL=watch-rebuild.testutil.d.ts.map

package/dist/watch-rebuild.testutil.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-rebuild.testutil.d.ts","sourceRoot":"","sources":["../src/watch-rebuild.testutil.ts"],"names":[],"mappings":"AA+BA;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACtC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,EACzB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GACrC,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACxC,SAAS,EAAE,MAAM,OAAO,EACxB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GACrC,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/watch-rebuild.testutil.js

@@ -0,0 +1,81 @@
+import fs from 'node:fs';
+/**
+ * FLAKE-HARDENING HELPER (not a test file — name avoids the `*.test.ts` glob).
+ *
+ * Why this exists
+ * ───────────────
+ * The watcher-driven rebuild tests in compile-worker.test.ts /
+ * open-project-compile-log.test.ts / compile-worker-leak.test.ts exercise the
+ * ONE genuinely-real moving part left after fork is mocked: chokidar's inotify
+ * watch. A single `fs.writeFileSync` produces a single inotify `change` event,
+ * and under CI load (Linux inotify + a concurrent REAL dmcc compile in
+ * open-project-compile-log.test.ts pegging the CPU) chokidar can DROP that lone
+ * event — the rebuild never fires and the test waits forever (PR #44's 30s
+ * timeout at compile-worker.test.ts:297).
+ *
+ * The fix is NOT a longer timeout (the event is lost, not slow): re-issue the
+ * filesystem write — with micro-varied content so size+mtime change and a fresh
+ * inotify event is guaranteed — until the rebuild we're waiting on actually
+ * lands. The rebuild scheduler (rebuild-scheduler.ts) coalesces every extra
+ * write into exactly ONE trailing build, so re-writing is safe for the
+ * count-agnostic / `>=` assertions these helpers are applied to.
+ *
+ * ⚠️ This is flake hardening, NOT goalpost-moving: no assertion is touched.
+ * Only apply these helpers where the assertion is count-agnostic or `>=`
+ * (re-triggering an extra coalesced rebuild cannot change the outcome). Tests
+ * that pin an EXACT rebuild/build-send count must not use them.
+ */
+const REWRITE_INTERVAL_MS = 400;
+/**
+ * Write `file` with `contentFor(attempt)`; if `settled` (e.g. the onRebuild
+ * promise) does not resolve within ~400ms, re-write with the next attempt's
+ * content (guaranteed size/mtime change → fresh inotify event) and keep
+ * retrying until `settled` resolves or the test's own vitest timeout fires.
+ *
+ * `contentFor` MUST embed `attempt` so successive writes differ in length —
+ * an identical-bytes rewrite can be coalesced by the OS into no new event.
+ */
+export async function writeUntilSettled(settled, file, contentFor) {
+    let done = false;
+    const guard = settled.then(() => { done = true; }, () => { done = true; });
+    let attempt = 0;
+    // First write happens immediately; subsequent re-writes only if still unsettled.
+    for (;;) {
+        fs.writeFileSync(file, contentFor(attempt));
+        attempt += 1;
+        const tick = await Promise.race([
+            guard.then(() => 'settled'),
+            sleep(REWRITE_INTERVAL_MS).then(() => 'retry'),
+        ]);
+        if (tick === 'settled' || done)
+            break;
+    }
+    await settled;
+}
+/**
+ * Like `writeUntilSettled` but waits on a polled PREDICATE instead of a
+ * promise — for the `vi.waitFor(buildSends === N)` / `logEntries.length > 0`
+ * style waiters where the thing being awaited is observable state, not a
+ * one-shot resolve. Re-writes the file every ~400ms until `predicate()` is
+ * true. Same coalescing-safety contract: predicate must be count-agnostic /
+ * monotone-reached (a `>=`, a "saw output", or a stable equality that extra
+ * coalesced rebuilds cannot overshoot).
+ */
+export async function writeUntilPredicate(predicate, file, contentFor) {
+    let attempt = 0;
+    for (;;) {
+        fs.writeFileSync(file, contentFor(attempt));
+        attempt += 1;
+        const start = Date.now();
+        while (Date.now() - start < REWRITE_INTERVAL_MS) {
+            if (predicate())
+                return;
+            await sleep(25);
+        }
+        if (predicate())
+            return;
+    }
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dimina-kit/devkit",
-  "version": "0.1.2-dev.20260612025610",
+  "version": "0.1.2-dev.20260615070430",
   "description": "Development toolkit for Dimina mini-apps with H5 container preview",
   "keywords": [
     "dimina",
@@ -52,8 +52,8 @@
     "eslint": "^10.2.1",
     "typescript": "5.9.2",
     "vitest": "^4.1.4",
-    "@dimina-kit/eslint-config": "0.1.0",
-    "@dimina-kit/typescript-config": "0.1.0"
+    "@dimina-kit/typescript-config": "0.1.0",
+    "@dimina-kit/eslint-config": "0.1.0"
   },
   "dependencies": {
     "@dimina/compiler": "1.0.16",