@unrift/core 0.3.0 → 0.4.0

package/dist/esm/mock/fs.d.ts

@@ -0,0 +1,54 @@
+/**
+ * File system mocking - `mock.fs()`.
+ *
+ * Backed by `memfs` today (private implementation detail behind the
+ * `FakeFsBackend` interface). The plan is to swap memfs for a hand-rolled
+ * package later; consumers of this module should only depend on the public
+ * `FakeFsHandle` surface, not on memfs types directly.
+ *
+ * Interception is layered on Tier A module mocking - `mock.doMock` is
+ * called for `node:fs` and `node:fs/promises`, so the fake takes effect
+ * when test code does `await import("node:fs")` or `await import("node:fs/promises")`.
+ * Static `import { readFileSync } from "node:fs"` is NOT intercepted in
+ * Tier A (planned for Tier B). See the docs page for the explicit limit
+ * list and workarounds.
+ */
+/**
+ * `Volume.fromJSON()` accepts a path-to-content map. `null` represents an
+ * empty directory; strings are file contents.
+ */
+export type FakeFsState = Record<string, string | null>;
+/** Public handle returned by `mock.fs()`. */
+export interface FakeFsHandle {
+    /** Dump the current state as a path-to-content map. */
+    toJSON(): FakeFsState;
+    /** Replace the current state with the given map. */
+    fromJSON(state: FakeFsState): void;
+    /** Read a file's contents, or null if it doesn't exist. */
+    read(path: string): string | null;
+    /** Write a file, creating parent directories as needed. */
+    write(path: string, content: string): void;
+    /** Check whether a path exists in the fake fs. */
+    exists(path: string): boolean;
+    /** Delete a file. Returns true if something was removed. */
+    delete(path: string): boolean;
+    /** List entries in a directory. Returns an empty array if missing. */
+    list(dir: string): string[];
+    /**
+     * Unpatch node:fs and node:fs/promises for this handle's interception.
+     * Idempotent, and a no-op if a later mock.fs() call has already superseded
+     * this handle - so holding an old handle for snapshotting can't tear down
+     * the current volume's interception.
+     */
+    restore(): void;
+}
+/**
+ * Install an in-memory file system as `node:fs` and `node:fs/promises`
+ * for the duration of the test. Subsequent `await import("node:fs")`
+ * calls return the fake.
+ *
+ * Calling `mock.fs()` while a fake is already installed swaps in a fresh
+ * volume - the previous handle's references stop receiving updates.
+ */
+export declare function fs(initial?: FakeFsState): FakeFsHandle;
+//# sourceMappingURL=fs.d.ts.map

package/dist/esm/mock/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../../src/mock/fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;AAqFxD,6CAA6C;AAC7C,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,MAAM,IAAI,WAAW,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IACnC,2DAA2D;IAC3D,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAClC,2DAA2D;IAC3D,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,kDAAkD;IAClD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,4DAA4D;IAC5D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,sEAAsE;IACtE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B;;;;;OAKG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAeD;;;;;;;GAOG;AACH,wBAAgB,EAAE,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,YAAY,CAkCtD"}

package/dist/esm/mock/fs.js

@@ -0,0 +1,125 @@
+/**
+ * File system mocking - `mock.fs()`.
+ *
+ * Backed by `memfs` today (private implementation detail behind the
+ * `FakeFsBackend` interface). The plan is to swap memfs for a hand-rolled
+ * package later; consumers of this module should only depend on the public
+ * `FakeFsHandle` surface, not on memfs types directly.
+ *
+ * Interception is layered on Tier A module mocking - `mock.doMock` is
+ * called for `node:fs` and `node:fs/promises`, so the fake takes effect
+ * when test code does `await import("node:fs")` or `await import("node:fs/promises")`.
+ * Static `import { readFileSync } from "node:fs"` is NOT intercepted in
+ * Tier A (planned for Tier B). See the docs page for the explicit limit
+ * list and workarounds.
+ */
+import { Volume, createFsFromVolume } from "memfs";
+import { doMock, unmock } from "./module.js";
+import { activeRestorers } from "./spy.js";
+/**
+ * The current implementation factory. Swap this single line when replacing
+ * memfs with a hand-rolled backend - no other code changes needed.
+ */
+function createBackend(initial) {
+    const vol = Volume.fromJSON(initial ?? {});
+    const fsExports = createFsFromVolume(vol);
+    // memfs's createFsFromVolume returns the fs surface; .promises is on it.
+    const fsPromisesExports = fsExports
+        .promises;
+    return {
+        fsExports,
+        fsPromisesExports,
+        toJSON: () => vol.toJSON(),
+        fromJSON: (state) => {
+            vol.reset();
+            vol.fromJSON(state);
+        },
+        readFile: (path) => {
+            try {
+                return vol.readFileSync(path, "utf8");
+            }
+            catch {
+                return null;
+            }
+        },
+        writeFile: (path, content) => {
+            // memfs throws if the parent directory doesn't exist; create it for
+            // ergonomic test code.
+            const lastSlash = path.lastIndexOf("/");
+            if (lastSlash > 0) {
+                vol.mkdirSync(path.slice(0, lastSlash), { recursive: true });
+            }
+            vol.writeFileSync(path, content);
+        },
+        exists: (path) => vol.existsSync(path),
+        remove: (path) => {
+            try {
+                vol.unlinkSync(path);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        list: (dir) => {
+            try {
+                return vol.readdirSync(dir);
+            }
+            catch {
+                return [];
+            }
+        },
+    };
+}
+// Process-global singleton: only one fake fs interception is active at a time.
+// Safe under sequential per-file execution + afterEach(restoreAll); parallel
+// per-file execution (see ISSUES.md) would need per-worker isolation.
+let activeBackend;
+const restoreFakeFs = () => {
+    if (!activeBackend)
+        return;
+    unmock("node:fs");
+    unmock("node:fs/promises");
+    activeBackend = undefined;
+    activeRestorers.delete(restoreFakeFs);
+};
+/**
+ * Install an in-memory file system as `node:fs` and `node:fs/promises`
+ * for the duration of the test. Subsequent `await import("node:fs")`
+ * calls return the fake.
+ *
+ * Calling `mock.fs()` while a fake is already installed swaps in a fresh
+ * volume - the previous handle's references stop receiving updates.
+ */
+export function fs(initial) {
+    // Tear down any existing fake before installing the new one so the
+    // module-mocking registrations don't stack.
+    if (activeBackend) {
+        unmock("node:fs");
+        unmock("node:fs/promises");
+    }
+    const backend = createBackend(initial);
+    activeBackend = backend;
+    doMock("node:fs", () => backend.fsExports);
+    doMock("node:fs/promises", () => backend.fsPromisesExports);
+    activeRestorers.add(restoreFakeFs);
+    const handle = {
+        toJSON: () => backend.toJSON(),
+        fromJSON: (state) => backend.fromJSON(state),
+        read: (path) => backend.readFile(path),
+        write: (path, content) => backend.writeFile(path, content),
+        exists: (path) => backend.exists(path),
+        delete: (path) => backend.remove(path),
+        list: (dir) => backend.list(dir),
+        // Only tear down the interception if THIS handle still owns it. A later
+        // mock.fs() call orphans this handle - its volume lives on for snapshot
+        // inspection, but restoring it must not rip out the newer volume's
+        // interception. On an orphaned handle this is a no-op (also makes restore
+        // idempotent: a second call finds activeBackend already cleared).
+        restore: () => {
+            if (activeBackend === backend)
+                restoreFakeFs();
+        },
+    };
+    return handle;
+}

package/dist/esm/mock/index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `mock` namespace - single entry point for all mocking utilities.
+ *
+ * Both forms are supported:
+ *   import { mock } from "unrift";
+ *   mock.fn();
+ *   mock.spyOn(obj, "method");
+ *
+ *   import { spy, spyOn } from "unrift";
+ *   spy();
+ *
+ * They produce identical objects.
+ */
+import { spy, spyOn, isSpy, clearAllMocks, resetAllMocks, restoreAllMocks } from "./spy";
+import { mockObject, mockClass } from "./auto";
+import { stub, mockGlobal } from "./stub";
+import { mockFetch, mockFetchOnce } from "./fetch";
+import { useFakeTimers, useRealTimers, advanceTimersByTime, advanceTimersByTimeAsync, runAllTimers, runAllTimersAsync, runOnlyPendingTimers, runOnlyPendingTimersAsync, getTimerCount, setSystemTime, getRealSystemTime } from "./timers";
+import { doMock, unmock, listMockedSpecs, fromModule } from "./module";
+import { fs as mockFs } from "./fs";
+export { spy, spyOn, isSpy, mockObject, mockClass, stub, mockGlobal, mockFetch, mockFetchOnce, useFakeTimers, useRealTimers, advanceTimersByTime, advanceTimersByTimeAsync, runAllTimers, runAllTimersAsync, runOnlyPendingTimers, runOnlyPendingTimersAsync, getTimerCount, setSystemTime, getRealSystemTime, doMock, unmock, listMockedSpecs, fromModule, mockFs, clearAllMocks, resetAllMocks, restoreAllMocks, };
+export type { Spy, MockState, MockResult, AnyFn } from "./spy";
+export type { MockFetch, FetchMatcher, MockResponseInit, MockFetchResponse, } from "./fetch";
+export type { UseFakeTimersOptions, FakeableApi } from "./timers";
+export type { LoaderMessage } from "./module";
+export type { FakeFsHandle, FakeFsState } from "./fs";
+/**
+ * Unified mock namespace. Mirrors Jest / Vitest naming so existing test
+ * code reads naturally:
+ *
+ *   mock.fn(impl?)            // spy()
+ *   mock.spyOn(obj, key)
+ *   mock.object(obj)          // auto-spy every method
+ *   mock.class(Ctor)          // auto-spy every method on instances
+ *   mock.global(key, value)   // stub on globalThis
+ *   mock.stub(target, key, value)
+ *   mock.clearAll()
+ *   mock.resetAll()
+ *   mock.restoreAll()
+ */
+export declare const mock: {
+    readonly fn: typeof spy;
+    readonly spyOn: typeof spyOn;
+    readonly object: typeof mockObject;
+    readonly class: typeof mockClass;
+    readonly global: typeof mockGlobal;
+    readonly stub: typeof stub;
+    readonly fetch: import("./fetch").MockFetch;
+    readonly fetchOnce: typeof mockFetchOnce;
+    readonly useFakeTimers: typeof useFakeTimers;
+    readonly useRealTimers: typeof useRealTimers;
+    readonly advanceTimersByTime: typeof advanceTimersByTime;
+    readonly advanceTimersByTimeAsync: typeof advanceTimersByTimeAsync;
+    readonly runAllTimers: typeof runAllTimers;
+    readonly runAllTimersAsync: typeof runAllTimersAsync;
+    readonly runOnlyPendingTimers: typeof runOnlyPendingTimers;
+    readonly runOnlyPendingTimersAsync: typeof runOnlyPendingTimersAsync;
+    readonly getTimerCount: typeof getTimerCount;
+    readonly setSystemTime: typeof setSystemTime;
+    readonly getRealSystemTime: typeof getRealSystemTime;
+    readonly doMock: typeof doMock;
+    readonly unmock: typeof unmock;
+    readonly fromModule: typeof fromModule;
+    readonly listMockedSpecs: typeof listMockedSpecs;
+    readonly fs: typeof mockFs;
+    readonly clearAll: typeof clearAllMocks;
+    readonly resetAll: typeof resetAllMocks;
+    readonly restoreAll: typeof restoreAllMocks;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/mock/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mock/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,GAAG,EACH,KAAK,EACL,KAAK,EACL,aAAa,EACb,aAAa,EACb,eAAe,EAChB,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EACL,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,EACZ,iBAAiB,EACjB,oBAAoB,EACpB,yBAAyB,EACzB,aAAa,EACb,aAAa,EACb,iBAAiB,EAClB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACvE,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,MAAM,MAAM,CAAC;AAEpC,OAAO,EACL,GAAG,EACH,KAAK,EACL,KAAK,EACL,UAAU,EACV,SAAS,EACT,IAAI,EACJ,UAAU,EACV,SAAS,EACT,aAAa,EACb,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,EACZ,iBAAiB,EACjB,oBAAoB,EACpB,yBAAyB,EACzB,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,MAAM,EACN,MAAM,EACN,eAAe,EACf,UAAU,EACV,MAAM,EACN,aAAa,EACb,aAAa,EACb,eAAe,GAChB,CAAC;AAEF,YAAY,EAAE,GAAG,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAC/D,YAAY,EACV,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAClE,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,MAAM,CAAC;AAEtD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkCP,CAAC"}

package/dist/esm/mock/index.js

@@ -0,0 +1,70 @@
+/**
+ * `mock` namespace - single entry point for all mocking utilities.
+ *
+ * Both forms are supported:
+ *   import { mock } from "unrift";
+ *   mock.fn();
+ *   mock.spyOn(obj, "method");
+ *
+ *   import { spy, spyOn } from "unrift";
+ *   spy();
+ *
+ * They produce identical objects.
+ */
+import { spy, spyOn, isSpy, clearAllMocks, resetAllMocks, restoreAllMocks, } from "./spy.js";
+import { mockObject, mockClass } from "./auto.js";
+import { stub, mockGlobal } from "./stub.js";
+import { mockFetch, mockFetchOnce } from "./fetch.js";
+import { useFakeTimers, useRealTimers, advanceTimersByTime, advanceTimersByTimeAsync, runAllTimers, runAllTimersAsync, runOnlyPendingTimers, runOnlyPendingTimersAsync, getTimerCount, setSystemTime, getRealSystemTime, } from "./timers.js";
+import { doMock, unmock, listMockedSpecs, fromModule } from "./module.js";
+import { fs as mockFs } from "./fs.js";
+export { spy, spyOn, isSpy, mockObject, mockClass, stub, mockGlobal, mockFetch, mockFetchOnce, useFakeTimers, useRealTimers, advanceTimersByTime, advanceTimersByTimeAsync, runAllTimers, runAllTimersAsync, runOnlyPendingTimers, runOnlyPendingTimersAsync, getTimerCount, setSystemTime, getRealSystemTime, doMock, unmock, listMockedSpecs, fromModule, mockFs, clearAllMocks, resetAllMocks, restoreAllMocks, };
+/**
+ * Unified mock namespace. Mirrors Jest / Vitest naming so existing test
+ * code reads naturally:
+ *
+ *   mock.fn(impl?)            // spy()
+ *   mock.spyOn(obj, key)
+ *   mock.object(obj)          // auto-spy every method
+ *   mock.class(Ctor)          // auto-spy every method on instances
+ *   mock.global(key, value)   // stub on globalThis
+ *   mock.stub(target, key, value)
+ *   mock.clearAll()
+ *   mock.resetAll()
+ *   mock.restoreAll()
+ */
+export const mock = {
+    fn: spy,
+    spyOn,
+    object: mockObject,
+    class: mockClass,
+    global: mockGlobal,
+    stub,
+    fetch: mockFetch,
+    fetchOnce: mockFetchOnce,
+    useFakeTimers,
+    useRealTimers,
+    advanceTimersByTime,
+    advanceTimersByTimeAsync,
+    runAllTimers,
+    runAllTimersAsync,
+    runOnlyPendingTimers,
+    runOnlyPendingTimersAsync,
+    getTimerCount,
+    setSystemTime,
+    getRealSystemTime,
+    // Tier A module mocking - dynamic imports of external specs only.
+    // The hoisted `mock.module(spec, factory)` for static imports is
+    // planned for Tier B and intentionally not exposed yet.
+    doMock,
+    unmock,
+    fromModule,
+    listMockedSpecs,
+    // File system mocking - backed by memfs, layered on Tier A module
+    // mocking. Works with `await import("node:fs")`; static imports of
+    // node:fs are not intercepted yet (planned for Tier B).
+    fs: mockFs,
+    clearAll: clearAllMocks,
+    resetAll: resetAllMocks,
+    restoreAll: restoreAllMocks,
+};

package/dist/esm/mock/module-loader.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Node module customization hook for unrift module mocking (Tier A).
+ *
+ * Registered by `bin/unrift.mjs` via `module.register()`. Runs in a
+ * worker thread (Node 20.6+ / 18.19+ behavior). Communicates with the
+ * main thread via a `MessagePort` to learn which specs have been mocked.
+ *
+ * Why we use `receiveMessageOnPort()` instead of `port.on("message")`:
+ * the resolve hook runs synchronously from the perspective of the
+ * import pipeline, but Worker `MessagePort` listeners are async.
+ * `receiveMessageOnPort()` (Node 18.7+) drains pending messages
+ * synchronously so registrations posted from the main thread are
+ * visible by the time the corresponding `await import(spec)` reaches
+ * us.
+ *
+ * The generated synthetic module source runs back in the MAIN thread
+ * (Node's loader output is evaluated in the importing thread, not the
+ * loader thread). That source reads exports from `globalThis.__unriftMocks`,
+ * which the main thread populates in `mock.doMock()`.
+ *
+ * Source compiled by tsc and shipped at `dist/esm/mock/module-loader.js`.
+ */
+import { type MessagePort } from "node:worker_threads";
+interface InitializeData {
+    port: MessagePort;
+}
+/**
+ * Generate ESM source for a mocked spec. The source executes in the
+ * MAIN thread (not the loader thread) - that's where the actual mock
+ * object lives, keyed in `globalThis.__unriftMocks`.
+ *
+ * Pure function so future tiers can reuse this for hoisted (Tier B)
+ * and relative (Tier C) mocks without rewriting the emitter.
+ */
+export declare function generateMockSource(spec: string, exportKeys: readonly string[]): string;
+/** Node hook: called once when the loader is registered. */
+export declare function initialize(data: InitializeData): void;
+interface ResolveContext {
+    conditions: readonly string[];
+    importAttributes?: Record<string, string>;
+    parentURL?: string;
+}
+interface ResolveResult {
+    url: string;
+    format?: string;
+    shortCircuit?: boolean;
+    importAttributes?: Record<string, string>;
+}
+type DefaultResolve = (specifier: string, context: ResolveContext) => ResolveResult | Promise<ResolveResult>;
+/** Node hook: short-circuit mocked specs to a `unrift-mock:` URL. */
+export declare function resolve(specifier: string, context: ResolveContext, nextResolve: DefaultResolve): Promise<ResolveResult>;
+interface LoadContext {
+    format?: string;
+    importAttributes?: Record<string, string>;
+    conditions?: readonly string[];
+}
+interface LoadResult {
+    format: string;
+    source?: string | ArrayBuffer | Uint8Array;
+    shortCircuit?: boolean;
+}
+type DefaultLoad = (url: string, context: LoadContext) => LoadResult | Promise<LoadResult>;
+/** Node hook: emit synthetic ESM source for mocked specs. */
+export declare function load(url: string, context: LoadContext, nextLoad: DefaultLoad): Promise<LoadResult>;
+export {};
+//# sourceMappingURL=module-loader.d.ts.map

package/dist/esm/mock/module-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-loader.d.ts","sourceRoot":"","sources":["../../../src/mock/module-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAwB,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAQ7E,UAAU,cAAc;IACtB,IAAI,EAAE,WAAW,CAAC;CACnB;AAmCD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,SAAS,MAAM,EAAE,GAC5B,MAAM,CAuBR;AAED,4DAA4D;AAC5D,wBAAgB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAErD;AAED,UAAU,cAAc;IACtB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,aAAa;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED,KAAK,cAAc,GAAG,CACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,KACpB,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;AAE5C,qEAAqE;AACrE,wBAAsB,OAAO,CAC3B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,WAAW,EAAE,cAAc,GAC1B,OAAO,CAAC,aAAa,CAAC,CAexB;AAED,UAAU,WAAW;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,UAAU,UAAU;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,CAAC;IAC3C,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,KAAK,WAAW,GAAG,CACjB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,WAAW,KACjB,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,6DAA6D;AAC7D,wBAAsB,IAAI,CACxB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,WAAW,GACpB,OAAO,CAAC,UAAU,CAAC,CA0BrB"}

package/dist/esm/mock/module-loader.js

@@ -0,0 +1,123 @@
+/**
+ * Node module customization hook for unrift module mocking (Tier A).
+ *
+ * Registered by `bin/unrift.mjs` via `module.register()`. Runs in a
+ * worker thread (Node 20.6+ / 18.19+ behavior). Communicates with the
+ * main thread via a `MessagePort` to learn which specs have been mocked.
+ *
+ * Why we use `receiveMessageOnPort()` instead of `port.on("message")`:
+ * the resolve hook runs synchronously from the perspective of the
+ * import pipeline, but Worker `MessagePort` listeners are async.
+ * `receiveMessageOnPort()` (Node 18.7+) drains pending messages
+ * synchronously so registrations posted from the main thread are
+ * visible by the time the corresponding `await import(spec)` reaches
+ * us.
+ *
+ * The generated synthetic module source runs back in the MAIN thread
+ * (Node's loader output is evaluated in the importing thread, not the
+ * loader thread). That source reads exports from `globalThis.__unriftMocks`,
+ * which the main thread populates in `mock.doMock()`.
+ *
+ * Source compiled by tsc and shipped at `dist/esm/mock/module-loader.js`.
+ */
+import { receiveMessageOnPort } from "node:worker_threads";
+import { MOCKS_GLOBAL_KEY, MOCK_URL_PREFIX, } from "./module.js";
+// Loader-thread state. Populated by `initialize()` and updated by
+// drainMessages() on every resolve() call.
+let loaderPort;
+const registered = new Map();
+/**
+ * Pull every pending message off the port synchronously. Called at the
+ * top of every resolve() and load() hook so the loader's view of the
+ * registry is always current.
+ */
+function drainMessages() {
+    if (!loaderPort)
+        return;
+    let received = receiveMessageOnPort(loaderPort);
+    while (received !== undefined) {
+        const message = received.message;
+        if (message.type === "register") {
+            registered.set(message.spec, {
+                registrationId: message.registrationId,
+                exportKeys: message.exportKeys,
+            });
+        }
+        else if (message.type === "unregister") {
+            registered.delete(message.spec);
+        }
+        received = receiveMessageOnPort(loaderPort);
+    }
+}
+/**
+ * Generate ESM source for a mocked spec. The source executes in the
+ * MAIN thread (not the loader thread) - that's where the actual mock
+ * object lives, keyed in `globalThis.__unriftMocks`.
+ *
+ * Pure function so future tiers can reuse this for hoisted (Tier B)
+ * and relative (Tier C) mocks without rewriting the emitter.
+ */
+export function generateMockSource(spec, exportKeys) {
+    const specJson = JSON.stringify(spec);
+    const lines = [
+        `// Generated by unrift module mocking - do not edit.`,
+        `const __mocks = globalThis[${JSON.stringify(MOCKS_GLOBAL_KEY)}];`,
+        `if (!__mocks || !__mocks.has(${specJson})) {`,
+        `  throw new Error(`,
+        `    "Unrift module mock registry is missing the entry for " + ${specJson} + ". " +`,
+        `    "This usually means mock.unmock() ran between registration and import."`,
+        `  );`,
+        `}`,
+        `const __exports = __mocks.get(${specJson});`,
+    ];
+    for (const key of exportKeys) {
+        if (key === "default") {
+            lines.push(`export default __exports.default;`);
+        }
+        else {
+            lines.push(`export const ${key} = __exports[${JSON.stringify(key)}];`);
+        }
+    }
+    return lines.join("\n");
+}
+/** Node hook: called once when the loader is registered. */
+export function initialize(data) {
+    loaderPort = data.port;
+}
+/** Node hook: short-circuit mocked specs to a `unrift-mock:` URL. */
+export async function resolve(specifier, context, nextResolve) {
+    drainMessages();
+    const entry = registered.get(specifier);
+    if (entry) {
+        // Embed the registration ID in the URL so Node's URL-keyed module
+        // cache treats each re-mock of the same spec as a fresh module.
+        return {
+            url: `${MOCK_URL_PREFIX}${specifier}?v=${entry.registrationId}`,
+            format: "module",
+            shortCircuit: true,
+        };
+    }
+    return nextResolve(specifier, context);
+}
+/** Node hook: emit synthetic ESM source for mocked specs. */
+export async function load(url, context, nextLoad) {
+    if (url.startsWith(MOCK_URL_PREFIX)) {
+        drainMessages();
+        // URL shape: `unrift-mock:<spec>?v=<registrationId>`
+        const withoutPrefix = url.slice(MOCK_URL_PREFIX.length);
+        const queryIdx = withoutPrefix.indexOf("?");
+        const spec = queryIdx === -1 ? withoutPrefix : withoutPrefix.slice(0, queryIdx);
+        const entry = registered.get(spec);
+        if (!entry) {
+            // The user called mock.unmock() between resolve() and load().
+            // Fall through to the real module so the import still works.
+            return nextLoad(spec, context);
+        }
+        return {
+            format: "module",
+            source: generateMockSource(spec, entry.exportKeys),
+            shortCircuit: true,
+        };
+    }
+    return nextLoad(url, context);
+}

package/dist/esm/mock/module.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Module mocking - main-thread registry and public API (Tier A).
+ *
+ * Tier A scope:
+ *   - `mock.doMock(spec, factory)` registers a mock for an external module
+ *     specifier (bare package name or `node:*` built-in).
+ *   - Subsequent `await import(spec)` calls return the factory's result.
+ *   - Static imports are NOT supported in Tier A; see the docs / ISSUES.md
+ *     for the planned Tier B (hoisted `mock.module`) work.
+ *
+ * Architecture:
+ *   - bin/unrift.mjs registers `module-loader.js` via `module.register()` and
+ *     pipes a MessagePort into the loader thread.
+ *   - The main-side port is stashed on `globalThis.__unriftLoaderPort` before
+ *     the test runner starts.
+ *   - `doMock()` invokes the factory once, caches the result on
+ *     `globalThis.__unriftMocks`, and posts a `register` message with the
+ *     spec + export-key list to the loader.
+ *   - The loader (see module-loader.ts) drains pending messages on every
+ *     resolve() and short-circuits matched specs to a synthetic module that
+ *     reads back from `globalThis.__unriftMocks`.
+ *
+ * Future tiers will reuse the same registry shape and IPC protocol -
+ * adding `register-hoisted` (Tier B) and `register-relative` (Tier C)
+ * message types without breaking the existing surface.
+ */
+/**
+ * Sentinel field name on globalThis. Loader-generated synthetic source
+ * reads back through this same name, so it must stay stable.
+ */
+export declare const MOCKS_GLOBAL_KEY = "__unriftMocks";
+/** Sentinel field name for the IPC port set by bin/unrift.mjs. */
+export declare const LOADER_PORT_GLOBAL_KEY = "__unriftLoaderPort";
+/** URL prefix the loader uses for mocked modules. Public so tests can assert. */
+export declare const MOCK_URL_PREFIX = "unrift-mock:";
+/**
+ * Message contract between main thread and loader thread. Stable across
+ * future tiers - new message types extend this union.
+ *
+ * `registrationId` is a monotonically increasing number embedded in the
+ * synthetic mock URL. It defeats Node's URL-keyed module cache so that
+ * re-mocking the same spec in a later test yields a fresh module (rather
+ * than returning the previous test's cached mock).
+ */
+export type LoaderMessage = {
+    type: "register";
+    spec: string;
+    registrationId: number;
+    exportKeys: readonly string[];
+} | {
+    type: "unregister";
+    spec: string;
+};
+type ModuleFactory = () => Record<string, unknown>;
+/**
+ * Register a mock for `spec`. Subsequent `await import(spec)` calls will
+ * resolve to the factory's return value instead of the real module.
+ *
+ * Tier A constraints (planned to be lifted in Tier B and beyond):
+ *   - Only **dynamic** imports (`await import(spec)`) hit the mock; static
+ *     `import { x } from "spec"` is hoisted by ESM above this call and
+ *     will see the real module.
+ *   - Only **external** specifiers work - bare package names (`"react"`)
+ *     and Node built-ins (`"node:fs"`). Relative specs (`"./bar"`) are
+ *     bundled inline by esbuild and can't be intercepted at runtime.
+ *   - The factory is invoked **once** at registration time. Its return
+ *     value is reused for every subsequent import.
+ *
+ * Throws if the Unrift CLI loader isn't attached (i.e., tests were run
+ * with raw `node` instead of `unrift`).
+ */
+export declare function doMock(spec: string, factory: ModuleFactory): void;
+/**
+ * Remove a previously registered mock. Subsequent `await import(spec)`
+ * calls fall through to the real module.
+ */
+export declare function unmock(spec: string): void;
+/** Returns the current set of mocked specs. Useful for tests / debugging. */
+export declare function listMockedSpecs(): readonly string[];
+/**
+ * Convenience helper: imports the real module, builds a version with every
+ * function export wrapped in a spy, registers it via `mock.doMock`, and
+ * returns the mocked exports.
+ *
+ * Non-function exports are passed through unchanged. Tests can customize
+ * individual spies with `.mockReturnValue`, `.mockImplementation`, etc.
+ *
+ * Subject to the same Tier A limits as `doMock` - only affects
+ * `await import(spec)` after the call. Static imports of `spec` see the
+ * real module.
+ *
+ * @example
+ *   const fs = await mock.fromModule("node:fs");
+ *   fs.readFileSync.mockReturnValue("fake content");
+ *   // ... test code that does `await import("node:fs")` now gets the spies
+ */
+export declare function fromModule<T extends Record<string, unknown>>(spec: string): Promise<T>;
+export {};
+//# sourceMappingURL=module.d.ts.map

package/dist/esm/mock/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../../../src/mock/module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AASH;;;GAGG;AACH,eAAO,MAAM,gBAAgB,kBAAkB,CAAC;AAEhD,kEAAkE;AAClE,eAAO,MAAM,sBAAsB,uBAAuB,CAAC;AAE3D,iFAAiF;AACjF,eAAO,MAAM,eAAe,iBAAiB,CAAC;AAE9C;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GACrB;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B,GACD;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC,KAAK,aAAa,GAAG,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAwFnD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,IAAI,CAqCjE;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAQzC;AAED,6EAA6E;AAC7E,wBAAgB,eAAe,IAAI,SAAS,MAAM,EAAE,CAEnD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChE,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,CAAC,CAAC,CAyBZ"}