@evolu/vitest 1.0.1 → 2.0.1

package/README.md

@@ -1,8 +1,13 @@
 # Evolu Vitest
 
-Vitest assertions and test utilities for Evolu.
+Vitest assertions for Evolu.
+
+Evolu uses `node:test` with the platform-agnostic assertions from
+`@evolu/common` for Node-only unit and integration tests. This package remains
+available for projects that use Vitest and want Result assertions with Vitest
+semantics.
 
 ## Documentation
 
-For detailed information and usage examples, please visit
-[evolu.dev](https://www.evolu.dev).
+See Evolu's [testing convention](https://www.evolu.dev/docs/testing) for runner
+and assertion guidance.

package/dist/src/BrowserConfig.d.ts

@@ -0,0 +1,10 @@
+type BrowserName = "chromium" | "firefox" | "webkit";
+interface BrowserInstance {
+    readonly browser: BrowserName;
+}
+export declare const createBrowserInstances: ({ coverage, mode, }: {
+    readonly coverage: boolean;
+    readonly mode: string;
+}) => Array<BrowserInstance>;
+export {};
+//# sourceMappingURL=BrowserConfig.d.ts.map

package/dist/src/BrowserConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserConfig.d.ts","sourceRoot":"","sources":["../../src/BrowserConfig.ts"],"names":[],"mappings":"AAAA,KAAK,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAErD,UAAU,eAAe;IACvB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B;AAkBD,eAAO,MAAM,sBAAsB,wBAGhC;IACD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,KAAG,KAAK,CAAC,eAAe,CAIU,CAAC"}

package/dist/src/BrowserConfig.js

@@ -0,0 +1,15 @@
+// V8 coverage only works with Chromium.
+const chromiumBrowserNames = ["chromium"];
+const compatibilityBrowserNames = [
+    "firefox",
+    "webkit",
+];
+const browserNamesByMode = {
+    chromium: ["chromium"],
+    firefox: ["firefox"],
+    webkit: ["webkit"],
+    "firefox-webkit": ["firefox", "webkit"],
+};
+export const createBrowserInstances = ({ coverage, mode, }) => (coverage
+    ? chromiumBrowserNames
+    : (browserNamesByMode[mode] ?? compatibilityBrowserNames)).map((browser) => ({ browser }));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@evolu/vitest",
-  "version": "1.0.1",
-  "description": "Vitest assertions and test utilities for Evolu",
+  "version": "2.0.1",
+  "description": "Vitest assertions for Evolu",
   "keywords": [
     "evolu",
     "vitest"
@@ -22,29 +22,19 @@
     ".": {
       "types": "./dist/src/index.d.ts",
       "import": "./dist/src/index.js"
-    },
-    "./TestJSDoc": {
-      "types": "./dist/src/TestJSDoc.d.ts",
-      "import": "./dist/src/TestJSDoc.js"
-    }
-  },
-  "typesVersions": {
-    "*": {
-      "TestJSDoc": [
-        "./dist/src/TestJSDoc.d.ts"
-      ]
     }
   },
   "files": [
     "dist/src/**",
+    "!dist/**/*.test.*",
     "src/**",
     "README.md"
   ],
   "devDependencies": {
+    "@evolu/common": "8.8.0",
+    "@evolu/typescript-config": "0.1.1",
     "@typescript/native": "npm:typescript@^7.0.2",
-    "vitest": "^4.1.2",
-    "@evolu/common": "8.1.0",
-    "@evolu/typescript-config": "0.0.2"
+    "vitest": "^4.1.11"
   },
   "peerDependencies": {
     "@evolu/common": "^8.0.0",
@@ -54,7 +44,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=24.0.0"
+    "node": ">=24.20.0"
   },
   "sideEffects": false,
   "scripts": {

package/src/BrowserConfig.test.ts

@@ -0,0 +1,34 @@
+import { assertEqual } from "@evolu/common";
+import { describe, it } from "node:test";
+import { createBrowserInstances } from "./BrowserConfig.ts";
+
+describe("createBrowserInstances", () => {
+  it("uses Chromium for coverage", () => {
+    assertEqual(createBrowserInstances({ coverage: true, mode: "" }), [
+      { browser: "chromium" },
+    ]);
+  });
+
+  it("defaults to Firefox and WebKit without coverage", () => {
+    assertEqual(createBrowserInstances({ coverage: false, mode: "" }), [
+      { browser: "firefox" },
+      { browser: "webkit" },
+    ]);
+  });
+
+  it("selects browsers by mode", () => {
+    assertEqual(createBrowserInstances({ coverage: false, mode: "chromium" }), [
+      { browser: "chromium" },
+    ]);
+    assertEqual(createBrowserInstances({ coverage: false, mode: "firefox" }), [
+      { browser: "firefox" },
+    ]);
+    assertEqual(createBrowserInstances({ coverage: false, mode: "webkit" }), [
+      { browser: "webkit" },
+    ]);
+    assertEqual(
+      createBrowserInstances({ coverage: false, mode: "firefox-webkit" }),
+      [{ browser: "firefox" }, { browser: "webkit" }],
+    );
+  });
+});

package/src/BrowserConfig.ts

@@ -0,0 +1,33 @@
+type BrowserName = "chromium" | "firefox" | "webkit";
+
+interface BrowserInstance {
+  readonly browser: BrowserName;
+}
+
+// V8 coverage only works with Chromium.
+const chromiumBrowserNames: ReadonlyArray<BrowserName> = ["chromium"];
+const compatibilityBrowserNames: ReadonlyArray<BrowserName> = [
+  "firefox",
+  "webkit",
+];
+
+const browserNamesByMode: Readonly<
+  Record<string, ReadonlyArray<BrowserName> | undefined>
+> = {
+  chromium: ["chromium"],
+  firefox: ["firefox"],
+  webkit: ["webkit"],
+  "firefox-webkit": ["firefox", "webkit"],
+};
+
+export const createBrowserInstances = ({
+  coverage,
+  mode,
+}: {
+  readonly coverage: boolean;
+  readonly mode: string;
+}): Array<BrowserInstance> =>
+  (coverage
+    ? chromiumBrowserNames
+    : (browserNamesByMode[mode] ?? compatibilityBrowserNames)
+  ).map((browser) => ({ browser }));

package/src/index.test.ts

@@ -0,0 +1,74 @@
+import {
+  assertThrowsInstanceOf,
+  assertType,
+  err,
+  type Err,
+  ok,
+  type Ok,
+  type Result,
+} from "@evolu/common";
+import { describe, it } from "node:test";
+import { expectErr, expectOk } from "./index.ts";
+
+const createOkResult = (): Result<number, string> => ok(42);
+const createErrResult = (): Result<number, string> => err("error");
+
+describe("expectOk", () => {
+  it("accepts an Ok and narrows the Result", () => {
+    const result = createOkResult();
+
+    expectOk(result, 42);
+
+    assertType<typeof result, Ok<number>>();
+  });
+
+  it("rejects an Err", () => {
+    assertThrowsInstanceOf(() => expectOk(createErrResult(), 42), Error);
+  });
+
+  it("rejects an unexpected value", () => {
+    assertThrowsInstanceOf(() => expectOk(createOkResult(), 41), Error);
+  });
+
+  it("narrows a heterogeneous Result union", () => {
+    const createResult = ():
+      Result<number, "NumberError"> | Result<string, "StringError"> => ok(42);
+    const result = createResult();
+
+    expectOk(result, 42);
+
+    assertType<typeof result, Ok<number> | Ok<string>>();
+  });
+});
+
+describe("expectErr", () => {
+  it("accepts an Err and narrows the Result", () => {
+    const result = createErrResult();
+
+    expectErr(result, "error");
+
+    assertType<typeof result, Err<string>>();
+  });
+
+  it("rejects an Ok", () => {
+    assertThrowsInstanceOf(() => expectErr(createOkResult(), "error"), Error);
+  });
+
+  it("rejects an unexpected error", () => {
+    assertThrowsInstanceOf(
+      () => expectErr(createErrResult(), "another error"),
+      Error,
+    );
+  });
+
+  it("narrows a heterogeneous Result union", () => {
+    const createResult = ():
+      Result<number, "NumberError"> | Result<string, "StringError"> =>
+      err("NumberError");
+    const result = createResult();
+
+    expectErr(result, "NumberError");
+
+    assertType<typeof result, Err<"NumberError"> | Err<"StringError">>();
+  });
+});

package/dist/src/TestJSDoc.d.ts

@@ -1,75 +0,0 @@
-/**
- * Vitest utilities for testing TypeScript examples embedded in JSDoc and
- * Markdown.
- *
- * These utilities use the dedicated `@evolu/vitest/TestJSDoc` entry point so
- * normal `@evolu/vitest` imports do not evaluate Node.js test tooling.
- *
- * @module
- */
-import { type ReadonlyRecord } from "@evolu/common";
-/** Options for compiling and executing TypeScript documentation examples. */
-export interface TestJSDocExamplesOptions {
-    /** Source files or glob patterns resolved from `cwd`. */
-    readonly include: string | ReadonlyArray<string>;
-    /** Package imports redirected to absolute TypeScript entry paths. */
-    readonly aliases?: ReadonlyRecord<string, string>;
-    /** Directory used for globbing and package resolution. */
-    readonly cwd?: string;
-    /** TypeScript compiler package. Defaults to `"typescript"`. */
-    readonly typescriptPackage?: string;
-}
-/**
- * Compiles and executes every TypeScript example in the included JSDoc comments
- * and Markdown files.
- *
- * Examples are compiled together as isolated TypeScript modules. Examples
- * without compilation errors are then run concurrently, bounded by the CPU
- * parallelism available to the process. Compilation and execution failures are
- * reported together. Vitest's `assert`, `expect`, and `expectTypeOf`, along
- * with Evolu's `expectOk` and `expectErr`, are injected into each module.
- *
- * Write every TypeScript fence as a standalone, deterministic example and
- * import its dependencies. Use `expectTypeOf` to prove static contracts and an
- * appropriate runtime assertion such as `expect`, `expectOk`, or `expectErr`
- * instead of describing expected behavior only in comments.
- *
- * Package aliases are useful for examples documenting an entry point that is
- * not exported yet. Package subpaths can be aliased independently. Each alias
- * target must be an absolute TypeScript module path exposing the named exports
- * used by the example.
- *
- * ### Example
- *
- * ```ts
- * import { testJSDocExamples } from "@evolu/vitest/TestJSDoc";
- * import { mkdtemp, rm, writeFile } from "node:fs/promises";
- * import { tmpdir } from "node:os";
- * import { join } from "node:path";
- *
- * const directory = await mkdtemp(join(tmpdir(), "evolu-jsdoc-example-"));
- * try {
- *   const sourcePath = join(directory, "Example.ts");
- *   await writeFile(
- *     sourcePath,
- *     [
- *       "/**",
- *       " * ``" + "`ts",
- *       " * expect(1 + 1).toBe(2);",
- *       " * ``" + "`",
- *       " *" + "/",
- *       "export {};",
- *     ].join("\n"),
- *   );
- *   await testJSDocExamples({
- *     cwd: process.cwd(),
- *     include: sourcePath,
- *     typescriptPackage: "@typescript/native",
- *   });
- * } finally {
- *   await rm(directory, { force: true, recursive: true });
- * }
- * ```
- */
-export declare const testJSDocExamples: ({ include, aliases, cwd, typescriptPackage, }: TestJSDocExamplesOptions) => Promise<void>;
-//# sourceMappingURL=TestJSDoc.d.ts.map

package/dist/src/TestJSDoc.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"TestJSDoc.d.ts","sourceRoot":"","sources":["../../src/TestJSDoc.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAOL,KAAK,cAAc,EAGpB,MAAM,eAAe,CAAC;AAkBvB,6EAA6E;AAC7E,MAAM,WAAW,wBAAwB;IACvC,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACjD,qEAAqE;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClD,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AA8BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,eAAO,MAAM,iBAAiB,kDAK3B,wBAAwB,KAAG,OAAO,CAAC,IAAI,CAsIzC,CAAC"}

package/dist/src/TestJSDoc.js

@@ -1,376 +0,0 @@
-/**
- * Vitest utilities for testing TypeScript examples embedded in JSDoc and
- * Markdown.
- *
- * These utilities use the dedicated `@evolu/vitest/TestJSDoc` entry point so
- * normal `@evolu/vitest` imports do not evaluate Node.js test tooling.
- *
- * @module
- */
-var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
-    if (value !== null && value !== void 0) {
-        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
-        var dispose, inner;
-        if (async) {
-            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
-            dispose = value[Symbol.asyncDispose];
-        }
-        if (dispose === void 0) {
-            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
-            dispose = value[Symbol.dispose];
-            if (async) inner = dispose;
-        }
-        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
-        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
-        env.stack.push({ value: value, dispose: dispose, async: async });
-    }
-    else if (async) {
-        env.stack.push({ async: true });
-    }
-    return value;
-};
-var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
-    return function (env) {
-        function fail(e) {
-            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
-            env.hasError = true;
-        }
-        var r, s = 0;
-        function next() {
-            while (r = env.stack.pop()) {
-                try {
-                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
-                    if (r.dispose) {
-                        var result = r.dispose.call(r.value);
-                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
-                    }
-                    else s |= 1;
-                }
-                catch (e) {
-                    fail(e);
-                }
-            }
-            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
-            if (env.hasError) throw env.error;
-        }
-        return next();
-    };
-})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
-    var e = new Error(message);
-    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
-});
-import { allSettled, createRun, filterArray, isErr, mapArray, PositiveInt, safelyStringifyUnknownValue, tryAsync, } from "@evolu/common";
-import assert from "node:assert/strict";
-import { spawn } from "node:child_process";
-import { globSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync, } from "node:fs";
-import { findPackageJSON } from "node:module";
-import { availableParallelism } from "node:os";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { stripVTControlCharacters } from "node:util";
-const jsdocPattern = /\/\*\*[\s\S]*?\*\//g;
-const fencePattern = /(?:```|~~~)([^\n]*)\n([\s\S]*?)(?:(```|~~~)|$)/g;
-const markdownFilePattern = /\.mdx?$/i;
-const packageNamePattern = /^(?:@[a-z\d][a-z\d._~-]*\/)?[a-z\d][a-z\d._~-]*$/i;
-const packageSubpathSegmentPattern = /^[a-z\d][a-z\d._~-]*$/i;
-const polyfillsPath = fileURLToPath(import.meta.resolve("@evolu/common/polyfills"));
-/**
- * Compiles and executes every TypeScript example in the included JSDoc comments
- * and Markdown files.
- *
- * Examples are compiled together as isolated TypeScript modules. Examples
- * without compilation errors are then run concurrently, bounded by the CPU
- * parallelism available to the process. Compilation and execution failures are
- * reported together. Vitest's `assert`, `expect`, and `expectTypeOf`, along
- * with Evolu's `expectOk` and `expectErr`, are injected into each module.
- *
- * Write every TypeScript fence as a standalone, deterministic example and
- * import its dependencies. Use `expectTypeOf` to prove static contracts and an
- * appropriate runtime assertion such as `expect`, `expectOk`, or `expectErr`
- * instead of describing expected behavior only in comments.
- *
- * Package aliases are useful for examples documenting an entry point that is
- * not exported yet. Package subpaths can be aliased independently. Each alias
- * target must be an absolute TypeScript module path exposing the named exports
- * used by the example.
- *
- * ### Example
- *
- * ```ts
- * import { testJSDocExamples } from "@evolu/vitest/TestJSDoc";
- * import { mkdtemp, rm, writeFile } from "node:fs/promises";
- * import { tmpdir } from "node:os";
- * import { join } from "node:path";
- *
- * const directory = await mkdtemp(join(tmpdir(), "evolu-jsdoc-example-"));
- * try {
- *   const sourcePath = join(directory, "Example.ts");
- *   await writeFile(
- *     sourcePath,
- *     [
- *       "/**",
- *       " * ``" + "`ts",
- *       " * expect(1 + 1).toBe(2);",
- *       " * ``" + "`",
- *       " *" + "/",
- *       "export {};",
- *     ].join("\n"),
- *   );
- *   await testJSDocExamples({
- *     cwd: process.cwd(),
- *     include: sourcePath,
- *     typescriptPackage: "@typescript/native",
- *   });
- * } finally {
- *   await rm(directory, { force: true, recursive: true });
- * }
- * ```
- */
-export const testJSDocExamples = async ({ include, aliases = {}, cwd = process.cwd(), typescriptPackage = "typescript", }) => {
-    const workingDirectory = realpathSync(resolve(cwd));
-    const patterns = typeof include === "string" ? [include] : include;
-    assert(patterns.length > 0, "Documentation example tests require included files.");
-    const filePaths = Array.from(new Set(globSync(patterns, { cwd: workingDirectory }).map((filePath) => resolve(workingDirectory, filePath)))).sort();
-    assert(filePaths.length > 0, "No files matched the documentation example patterns.");
-    const examples = filePaths.flatMap((filePath) => extractDocumentationExamples(readFileSync(filePath, "utf8"), filePath));
-    assert(examples.length > 0, "No TypeScript documentation examples were found.");
-    const compilerPath = resolveTypeScriptCompiler(workingDirectory, typescriptPackage);
-    const temporaryRoot = join(workingDirectory, "tmp");
-    mkdirSync(temporaryRoot, { recursive: true });
-    const temporaryDirectory = mkdtempSync(join(temporaryRoot, "evolu-jsdoc-"));
-    try {
-        writeFileSync(join(temporaryDirectory, "package.json"), JSON.stringify({ type: "module" }));
-        createPackageAliases(temporaryDirectory, aliases);
-        const generatedExamples = examples.map((example, index) => {
-            const generatedPath = join(temporaryDirectory, `example-${index}.ts`);
-            writeFileSync(generatedPath, transformJSDocExample(example, generatedPath));
-            return { ...example, generatedPath };
-        });
-        // TODO: Lint generated examples with Oxc after the repository migration.
-        // Treat top-level declarations as example output and ignore `using`
-        // bindings whose disposal is their purpose.
-        const compilerConfigPath = join(temporaryDirectory, "tsconfig.json");
-        writeFileSync(compilerConfigPath, JSON.stringify({
-            compilerOptions: {
-                allowImportingTsExtensions: true,
-                erasableSyntaxOnly: true,
-                esModuleInterop: true,
-                exactOptionalPropertyTypes: true,
-                lib: ["DOM", "ESNext"],
-                module: "NodeNext",
-                moduleResolution: "NodeNext",
-                noEmit: true,
-                skipLibCheck: true,
-                strict: true,
-                target: "ES2022",
-                types: ["node"],
-                verbatimModuleSyntax: true,
-            },
-            files: generatedExamples.map(({ generatedPath }) => generatedPath),
-        }));
-        let compilationError;
-        try {
-            await runProcess(process.execPath, [compilerPath, "--project", compilerConfigPath], workingDirectory, "Documentation example TypeScript compilation", [
-                "Generated example sources:",
-                ...generatedExamples.map(({ filePath, generatedPath, line }) => `- ${relative(temporaryDirectory, generatedPath)}: ${relative(workingDirectory, filePath)}:${line}`),
-            ].join("\n"));
-        }
-        catch (error) {
-            compilationError =
-                error instanceof Error
-                    ? error
-                    : new Error(safelyStringifyUnknownValue(error));
-        }
-        const runnableExamples = compilationError === undefined
-            ? generatedExamples
-            : getExamplesWithoutCompilationErrors(generatedExamples, compilationError, workingDirectory);
-        let executionError;
-        try {
-            await runJSDocExamples(runnableExamples, workingDirectory);
-        }
-        catch (error) {
-            executionError =
-                error instanceof Error
-                    ? error
-                    : new Error(safelyStringifyUnknownValue(error));
-        }
-        if (compilationError !== undefined && executionError !== undefined) {
-            const executionErrors = executionError instanceof AggregateError
-                ? executionError.errors
-                : [executionError];
-            throw new AggregateError([compilationError, ...executionErrors], `${compilationError.message}\n${executionError.message}`);
-        }
-        if (compilationError !== undefined)
-            throw compilationError;
-        if (executionError !== undefined)
-            throw executionError;
-    }
-    finally {
-        rmSync(temporaryDirectory, { force: true, recursive: true });
-    }
-};
-const getExamplesWithoutCompilationErrors = (examples, compilationError, workingDirectory) => {
-    const compilationErrorMessage = stripVTControlCharacters(compilationError.message);
-    const examplesWithErrors = examples.filter(({ generatedPath }) => [generatedPath, relative(workingDirectory, generatedPath)].some((path) => [`${path}(`, `${path}:`].some((segment) => compilationErrorMessage.includes(segment))));
-    if (examplesWithErrors.length === 0)
-        return [];
-    return examples.filter((example) => !examplesWithErrors.includes(example));
-};
-const extractDocumentationExamples = (source, filePath) => {
-    if (markdownFilePattern.test(filePath)) {
-        return extractFencedExamples(source, source, filePath, 0, false);
-    }
-    const examples = [];
-    for (const jsdoc of source.matchAll(jsdocPattern)) {
-        examples.push(...extractFencedExamples(source, jsdoc[0], filePath, jsdoc.index, true));
-    }
-    return examples;
-};
-const extractFencedExamples = (source, fencedSource, filePath, offset, stripJSDocPrefixes) => {
-    const examples = [];
-    for (const fence of fencedSource.matchAll(fencePattern)) {
-        const metadata = fence[1].trim().toLowerCase().split(/\s+/);
-        if (!["ts", "typescript"].includes(metadata[0])) {
-            continue;
-        }
-        const line = getLineNumber(source, offset + fence.index);
-        const closingFence = fence[3];
-        assert(closingFence !== undefined, `${filePath}:${line} has an unclosed TypeScript example fence.`);
-        const exampleSource = (stripJSDocPrefixes ? fence[2].replace(/^[ \t]*\* ?/gm, "") : fence[2]).trim();
-        assert(exampleSource.length > 0, `${filePath}:${line} has an empty TypeScript example.`);
-        examples.push({ filePath, line, source: exampleSource });
-    }
-    return examples;
-};
-const getLineNumber = (source, offset) => {
-    let line = 1;
-    for (let index = 0; index < offset; index++) {
-        if (source.charCodeAt(index) === 10)
-            line++;
-    }
-    return line;
-};
-const transformJSDocExample = (example, generatedPath) => [
-    `import { installPolyfills } from ${JSON.stringify(pathToImportSpecifier(generatedPath, polyfillsPath))};`,
-    'import { expectErr, expectOk } from "@evolu/vitest";',
-    'import { assert, expect, expectTypeOf } from "vitest";',
-    "installPolyfills();",
-    example.source,
-].join("\n\n");
-const resolveTypeScriptCompiler = (workingDirectory, typescriptPackage) => {
-    const packagePath = findPackageJSON(typescriptPackage, pathToFileURL(join(workingDirectory, "package.json")));
-    assert(packagePath !== undefined, `Cannot resolve ${typescriptPackage} from ${workingDirectory}.`);
-    const packageJson = JSON.parse(readFileSync(packagePath, "utf8"));
-    const compiler = typeof packageJson.bin === "string" ? packageJson.bin : packageJson.bin.tsc;
-    assert(compiler !== undefined, `${typescriptPackage} does not expose a tsc executable.`);
-    return resolve(dirname(packagePath), compiler);
-};
-const runJSDocExamples = async (examples, workingDirectory) => {
-    const env_1 = { stack: [], error: void 0, hasError: false };
-    try {
-        const run = __addDisposableResource(env_1, createRun(), true);
-        const results = await run.ok(allSettled(examples, (example) => async (run) => tryAsync(() => runProcess(process.execPath, [example.generatedPath], workingDirectory, "Node.js execution"), (error) => {
-            run.signal.throwIfAborted();
-            return { error, example };
-        }), { concurrency: PositiveInt.orThrow(availableParallelism()) }));
-        const failures = filterArray(results, isErr);
-        if (failures.length === 0)
-            return;
-        const errors = mapArray(failures, ({ error: { error, example: { filePath, line }, }, }) => {
-            const message = error instanceof Error
-                ? error.message
-                : safelyStringifyUnknownValue(error);
-            return new Error(`${relative(workingDirectory, filePath)}:${line}: ${message}`, { cause: error });
-        });
-        throw new AggregateError(errors, [
-            "JSDoc example execution failed.",
-            ...mapArray(errors, (error) => `- ${error.message}`),
-        ].join("\n"));
-    }
-    catch (e_1) {
-        env_1.error = e_1;
-        env_1.hasError = true;
-    }
-    finally {
-        const result_1 = __disposeResources(env_1);
-        if (result_1)
-            await result_1;
-    }
-};
-const createPackageAliases = (temporaryDirectory, aliases) => {
-    const aliasesByPackageName = new Map();
-    for (const [name, target] of Object.entries(aliases)) {
-        assert(isAbsolute(target), `Package alias ${name} must be absolute.`);
-        const segments = name.split("/");
-        const packageSegmentCount = name.startsWith("@") ? 2 : 1;
-        const packageName = segments.slice(0, packageSegmentCount).join("/");
-        const subpathSegments = segments.slice(packageSegmentCount);
-        assert(packageNamePattern.test(packageName) &&
-            subpathSegments.every((segment) => packageSubpathSegmentPattern.test(segment)), `Invalid package alias: ${name}.`);
-        const subpath = subpathSegments.join("/");
-        const packageAliases = aliasesByPackageName.get(packageName) ?? [];
-        packageAliases.push({ subpath, targetPath: realpathSync(target) });
-        aliasesByPackageName.set(packageName, packageAliases);
-    }
-    for (const [packageName, packageAliases] of aliasesByPackageName) {
-        const packageSegments = packageName.split("/");
-        const packageDirectory = join(temporaryDirectory, "node_modules", ...packageSegments);
-        mkdirSync(packageDirectory, { recursive: true });
-        const exportsBySubpath = {};
-        for (const { subpath, targetPath } of packageAliases) {
-            const entryPathWithoutExtension = subpath || "index";
-            const exportName = subpath ? `./${subpath}` : ".";
-            exportsBySubpath[exportName] = {
-                types: `./${entryPathWithoutExtension}.ts`,
-                default: `./${entryPathWithoutExtension}.js`,
-            };
-            for (const extension of ["ts", "js"]) {
-                const entryPath = join(packageDirectory, `${entryPathWithoutExtension}.${extension}`);
-                mkdirSync(dirname(entryPath), { recursive: true });
-                writeFileSync(entryPath, `export * from ${JSON.stringify(pathToImportSpecifier(entryPath, targetPath))};\n`);
-            }
-        }
-        writeFileSync(join(packageDirectory, "package.json"), JSON.stringify({
-            name: packageName,
-            type: "module",
-            exports: exportsBySubpath,
-        }));
-    }
-};
-const pathToImportSpecifier = (from, to) => {
-    const path = relative(dirname(from), to).split(sep).join("/");
-    return path.startsWith(".") ? path : `./${path}`;
-};
-const runProcess = (command, args, cwd, operation, details) => new Promise((resolve, reject) => {
-    const child = spawn(command, args, {
-        cwd,
-        stdio: ["ignore", "pipe", "pipe"],
-    });
-    const stdout = [];
-    const stderr = [];
-    child.stdout.on("data", (chunk) => {
-        stdout.push(chunk);
-    });
-    child.stderr.on("data", (chunk) => {
-        stderr.push(chunk);
-    });
-    child.once("error", (error) => {
-        reject(new Error([`${operation} failed.`, details].filter(Boolean).join("\n"), {
-            cause: error,
-        }));
-    });
-    child.once("close", (code, signal) => {
-        if (code === 0) {
-            resolve();
-            return;
-        }
-        reject(new Error([
-            `${operation} failed${signal === null ? ` with exit code ${String(code)}` : ` from signal ${signal}`}.`,
-            details,
-            Buffer.concat(stdout).toString("utf8"),
-            Buffer.concat(stderr).toString("utf8"),
-        ]
-            .filter(Boolean)
-            .join("\n")));
-    });
-});

package/src/TestJSDoc.ts

@@ -1,574 +0,0 @@
-/**
- * Vitest utilities for testing TypeScript examples embedded in JSDoc and
- * Markdown.
- *
- * These utilities use the dedicated `@evolu/vitest/TestJSDoc` entry point so
- * normal `@evolu/vitest` imports do not evaluate Node.js test tooling.
- *
- * @module
- */
-
-import {
-  allSettled,
-  createRun,
-  filterArray,
-  isErr,
-  mapArray,
-  PositiveInt,
-  type ReadonlyRecord,
-  safelyStringifyUnknownValue,
-  tryAsync,
-} from "@evolu/common";
-import assert from "node:assert/strict";
-import { spawn } from "node:child_process";
-import {
-  globSync,
-  mkdirSync,
-  mkdtempSync,
-  readFileSync,
-  realpathSync,
-  rmSync,
-  writeFileSync,
-} from "node:fs";
-import { findPackageJSON } from "node:module";
-import { availableParallelism } from "node:os";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { stripVTControlCharacters } from "node:util";
-
-/** Options for compiling and executing TypeScript documentation examples. */
-export interface TestJSDocExamplesOptions {
-  /** Source files or glob patterns resolved from `cwd`. */
-  readonly include: string | ReadonlyArray<string>;
-  /** Package imports redirected to absolute TypeScript entry paths. */
-  readonly aliases?: ReadonlyRecord<string, string>;
-  /** Directory used for globbing and package resolution. */
-  readonly cwd?: string;
-  /** TypeScript compiler package. Defaults to `"typescript"`. */
-  readonly typescriptPackage?: string;
-}
-
-interface JSDocExample {
-  readonly filePath: string;
-  readonly line: number;
-  readonly source: string;
-}
-
-interface GeneratedJSDocExample extends JSDocExample {
-  readonly generatedPath: string;
-}
-
-interface JSDocExampleFailure {
-  readonly error: unknown;
-  readonly example: GeneratedJSDocExample;
-}
-
-interface TypeScriptPackage {
-  readonly bin: string | { readonly tsc?: string };
-}
-
-const jsdocPattern = /\/\*\*[\s\S]*?\*\//g;
-const fencePattern = /(?:```|~~~)([^\n]*)\n([\s\S]*?)(?:(```|~~~)|$)/g;
-const markdownFilePattern = /\.mdx?$/i;
-const packageNamePattern = /^(?:@[a-z\d][a-z\d._~-]*\/)?[a-z\d][a-z\d._~-]*$/i;
-const packageSubpathSegmentPattern = /^[a-z\d][a-z\d._~-]*$/i;
-const polyfillsPath = fileURLToPath(
-  import.meta.resolve("@evolu/common/polyfills"),
-);
-
-/**
- * Compiles and executes every TypeScript example in the included JSDoc comments
- * and Markdown files.
- *
- * Examples are compiled together as isolated TypeScript modules. Examples
- * without compilation errors are then run concurrently, bounded by the CPU
- * parallelism available to the process. Compilation and execution failures are
- * reported together. Vitest's `assert`, `expect`, and `expectTypeOf`, along
- * with Evolu's `expectOk` and `expectErr`, are injected into each module.
- *
- * Write every TypeScript fence as a standalone, deterministic example and
- * import its dependencies. Use `expectTypeOf` to prove static contracts and an
- * appropriate runtime assertion such as `expect`, `expectOk`, or `expectErr`
- * instead of describing expected behavior only in comments.
- *
- * Package aliases are useful for examples documenting an entry point that is
- * not exported yet. Package subpaths can be aliased independently. Each alias
- * target must be an absolute TypeScript module path exposing the named exports
- * used by the example.
- *
- * ### Example
- *
- * ```ts
- * import { testJSDocExamples } from "@evolu/vitest/TestJSDoc";
- * import { mkdtemp, rm, writeFile } from "node:fs/promises";
- * import { tmpdir } from "node:os";
- * import { join } from "node:path";
- *
- * const directory = await mkdtemp(join(tmpdir(), "evolu-jsdoc-example-"));
- * try {
- *   const sourcePath = join(directory, "Example.ts");
- *   await writeFile(
- *     sourcePath,
- *     [
- *       "/**",
- *       " * ``" + "`ts",
- *       " * expect(1 + 1).toBe(2);",
- *       " * ``" + "`",
- *       " *" + "/",
- *       "export {};",
- *     ].join("\n"),
- *   );
- *   await testJSDocExamples({
- *     cwd: process.cwd(),
- *     include: sourcePath,
- *     typescriptPackage: "@typescript/native",
- *   });
- * } finally {
- *   await rm(directory, { force: true, recursive: true });
- * }
- * ```
- */
-export const testJSDocExamples = async ({
-  include,
-  aliases = {},
-  cwd = process.cwd(),
-  typescriptPackage = "typescript",
-}: TestJSDocExamplesOptions): Promise<void> => {
-  const workingDirectory = realpathSync(resolve(cwd));
-  const patterns = typeof include === "string" ? [include] : include;
-  assert(
-    patterns.length > 0,
-    "Documentation example tests require included files.",
-  );
-
-  const filePaths = Array.from(
-    new Set(
-      globSync(patterns, { cwd: workingDirectory }).map((filePath) =>
-        resolve(workingDirectory, filePath),
-      ),
-    ),
-  ).sort();
-  assert(
-    filePaths.length > 0,
-    "No files matched the documentation example patterns.",
-  );
-
-  const examples = filePaths.flatMap((filePath) =>
-    extractDocumentationExamples(readFileSync(filePath, "utf8"), filePath),
-  );
-  assert(
-    examples.length > 0,
-    "No TypeScript documentation examples were found.",
-  );
-
-  const compilerPath = resolveTypeScriptCompiler(
-    workingDirectory,
-    typescriptPackage,
-  );
-  const temporaryRoot = join(workingDirectory, "tmp");
-  mkdirSync(temporaryRoot, { recursive: true });
-
-  const temporaryDirectory = mkdtempSync(join(temporaryRoot, "evolu-jsdoc-"));
-
-  try {
-    writeFileSync(
-      join(temporaryDirectory, "package.json"),
-      JSON.stringify({ type: "module" }),
-    );
-    createPackageAliases(temporaryDirectory, aliases);
-
-    const generatedExamples = examples.map((example, index) => {
-      const generatedPath = join(temporaryDirectory, `example-${index}.ts`);
-      writeFileSync(
-        generatedPath,
-        transformJSDocExample(example, generatedPath),
-      );
-      return { ...example, generatedPath } satisfies GeneratedJSDocExample;
-    });
-    // TODO: Lint generated examples with Oxc after the repository migration.
-    // Treat top-level declarations as example output and ignore `using`
-    // bindings whose disposal is their purpose.
-    const compilerConfigPath = join(temporaryDirectory, "tsconfig.json");
-    writeFileSync(
-      compilerConfigPath,
-      JSON.stringify({
-        compilerOptions: {
-          allowImportingTsExtensions: true,
-          erasableSyntaxOnly: true,
-          esModuleInterop: true,
-          exactOptionalPropertyTypes: true,
-          lib: ["DOM", "ESNext"],
-          module: "NodeNext",
-          moduleResolution: "NodeNext",
-          noEmit: true,
-          skipLibCheck: true,
-          strict: true,
-          target: "ES2022",
-          types: ["node"],
-          verbatimModuleSyntax: true,
-        },
-        files: generatedExamples.map(({ generatedPath }) => generatedPath),
-      }),
-    );
-
-    let compilationError: Error | undefined;
-    try {
-      await runProcess(
-        process.execPath,
-        [compilerPath, "--project", compilerConfigPath],
-        workingDirectory,
-        "Documentation example TypeScript compilation",
-        [
-          "Generated example sources:",
-          ...generatedExamples.map(
-            ({ filePath, generatedPath, line }) =>
-              `- ${relative(temporaryDirectory, generatedPath)}: ${relative(workingDirectory, filePath)}:${line}`,
-          ),
-        ].join("\n"),
-      );
-    } catch (error) {
-      compilationError =
-        error instanceof Error
-          ? error
-          : new Error(safelyStringifyUnknownValue(error));
-    }
-
-    const runnableExamples =
-      compilationError === undefined
-        ? generatedExamples
-        : getExamplesWithoutCompilationErrors(
-            generatedExamples,
-            compilationError,
-            workingDirectory,
-          );
-
-    let executionError: Error | undefined;
-    try {
-      await runJSDocExamples(runnableExamples, workingDirectory);
-    } catch (error) {
-      executionError =
-        error instanceof Error
-          ? error
-          : new Error(safelyStringifyUnknownValue(error));
-    }
-
-    if (compilationError !== undefined && executionError !== undefined) {
-      const executionErrors: ReadonlyArray<unknown> =
-        executionError instanceof AggregateError
-          ? (executionError.errors as ReadonlyArray<unknown>)
-          : [executionError];
-      throw new AggregateError(
-        [compilationError, ...executionErrors],
-        `${compilationError.message}\n${executionError.message}`,
-      );
-    }
-    if (compilationError !== undefined) throw compilationError;
-    if (executionError !== undefined) throw executionError;
-  } finally {
-    rmSync(temporaryDirectory, { force: true, recursive: true });
-  }
-};
-
-const getExamplesWithoutCompilationErrors = (
-  examples: ReadonlyArray<GeneratedJSDocExample>,
-  compilationError: Error,
-  workingDirectory: string,
-): ReadonlyArray<GeneratedJSDocExample> => {
-  const compilationErrorMessage = stripVTControlCharacters(
-    compilationError.message,
-  );
-  const examplesWithErrors = examples.filter(({ generatedPath }) =>
-    [generatedPath, relative(workingDirectory, generatedPath)].some((path) =>
-      [`${path}(`, `${path}:`].some((segment) =>
-        compilationErrorMessage.includes(segment),
-      ),
-    ),
-  );
-
-  if (examplesWithErrors.length === 0) return [];
-
-  return examples.filter((example) => !examplesWithErrors.includes(example));
-};
-
-const extractDocumentationExamples = (
-  source: string,
-  filePath: string,
-): ReadonlyArray<JSDocExample> => {
-  if (markdownFilePattern.test(filePath)) {
-    return extractFencedExamples(source, source, filePath, 0, false);
-  }
-
-  const examples: Array<JSDocExample> = [];
-  for (const jsdoc of source.matchAll(jsdocPattern)) {
-    examples.push(
-      ...extractFencedExamples(source, jsdoc[0], filePath, jsdoc.index, true),
-    );
-  }
-
-  return examples;
-};
-
-const extractFencedExamples = (
-  source: string,
-  fencedSource: string,
-  filePath: string,
-  offset: number,
-  stripJSDocPrefixes: boolean,
-): ReadonlyArray<JSDocExample> => {
-  const examples: Array<JSDocExample> = [];
-
-  for (const fence of fencedSource.matchAll(fencePattern)) {
-    const metadata = fence[1].trim().toLowerCase().split(/\s+/);
-    if (!["ts", "typescript"].includes(metadata[0])) {
-      continue;
-    }
-
-    const line = getLineNumber(source, offset + fence.index);
-    const closingFence = fence[3] as string | undefined;
-    assert(
-      closingFence !== undefined,
-      `${filePath}:${line} has an unclosed TypeScript example fence.`,
-    );
-    const exampleSource = (
-      stripJSDocPrefixes ? fence[2].replace(/^[ \t]*\* ?/gm, "") : fence[2]
-    ).trim();
-    assert(
-      exampleSource.length > 0,
-      `${filePath}:${line} has an empty TypeScript example.`,
-    );
-    examples.push({ filePath, line, source: exampleSource });
-  }
-
-  return examples;
-};
-
-const getLineNumber = (source: string, offset: number): number => {
-  let line = 1;
-  for (let index = 0; index < offset; index++) {
-    if (source.charCodeAt(index) === 10) line++;
-  }
-  return line;
-};
-
-const transformJSDocExample = (
-  example: JSDocExample,
-  generatedPath: string,
-): string =>
-  [
-    `import { installPolyfills } from ${JSON.stringify(pathToImportSpecifier(generatedPath, polyfillsPath))};`,
-    'import { expectErr, expectOk } from "@evolu/vitest";',
-    'import { assert, expect, expectTypeOf } from "vitest";',
-    "installPolyfills();",
-    example.source,
-  ].join("\n\n");
-
-const resolveTypeScriptCompiler = (
-  workingDirectory: string,
-  typescriptPackage: string,
-): string => {
-  const packagePath = findPackageJSON(
-    typescriptPackage,
-    pathToFileURL(join(workingDirectory, "package.json")),
-  );
-  assert(
-    packagePath !== undefined,
-    `Cannot resolve ${typescriptPackage} from ${workingDirectory}.`,
-  );
-  const packageJson = JSON.parse(
-    readFileSync(packagePath, "utf8"),
-  ) as TypeScriptPackage;
-  const compiler =
-    typeof packageJson.bin === "string" ? packageJson.bin : packageJson.bin.tsc;
-  assert(
-    compiler !== undefined,
-    `${typescriptPackage} does not expose a tsc executable.`,
-  );
-  return resolve(dirname(packagePath), compiler);
-};
-
-const runJSDocExamples = async (
-  examples: ReadonlyArray<GeneratedJSDocExample>,
-  workingDirectory: string,
-): Promise<void> => {
-  await using run = createRun();
-  const results = await run.ok(
-    allSettled(
-      examples,
-      (example) => async (run) =>
-        tryAsync(
-          () =>
-            runProcess(
-              process.execPath,
-              [example.generatedPath],
-              workingDirectory,
-              "Node.js execution",
-            ),
-          (error) => {
-            run.signal.throwIfAborted();
-            return { error, example } satisfies JSDocExampleFailure;
-          },
-        ),
-      { concurrency: PositiveInt.orThrow(availableParallelism()) },
-    ),
-  );
-
-  const failures = filterArray(results, isErr);
-  if (failures.length === 0) return;
-
-  const errors = mapArray(
-    failures,
-    ({
-      error: {
-        error,
-        example: { filePath, line },
-      },
-    }) => {
-      const message =
-        error instanceof Error
-          ? error.message
-          : safelyStringifyUnknownValue(error);
-      return new Error(
-        `${relative(workingDirectory, filePath)}:${line}: ${message}`,
-        { cause: error },
-      );
-    },
-  );
-  throw new AggregateError(
-    errors,
-    [
-      "JSDoc example execution failed.",
-      ...mapArray(errors, (error) => `- ${error.message}`),
-    ].join("\n"),
-  );
-};
-
-const createPackageAliases = (
-  temporaryDirectory: string,
-  aliases: ReadonlyRecord<string, string>,
-): void => {
-  const aliasesByPackageName = new Map<
-    string,
-    Array<{
-      readonly subpath: string;
-      readonly targetPath: string;
-    }>
-  >();
-
-  for (const [name, target] of Object.entries(aliases)) {
-    assert(isAbsolute(target), `Package alias ${name} must be absolute.`);
-    const segments = name.split("/");
-    const packageSegmentCount = name.startsWith("@") ? 2 : 1;
-    const packageName = segments.slice(0, packageSegmentCount).join("/");
-    const subpathSegments = segments.slice(packageSegmentCount);
-    assert(
-      packageNamePattern.test(packageName) &&
-        subpathSegments.every((segment) =>
-          packageSubpathSegmentPattern.test(segment),
-        ),
-      `Invalid package alias: ${name}.`,
-    );
-    const subpath = subpathSegments.join("/");
-    const packageAliases = aliasesByPackageName.get(packageName) ?? [];
-    packageAliases.push({ subpath, targetPath: realpathSync(target) });
-    aliasesByPackageName.set(packageName, packageAliases);
-  }
-
-  for (const [packageName, packageAliases] of aliasesByPackageName) {
-    const packageSegments = packageName.split("/");
-    const packageDirectory = join(
-      temporaryDirectory,
-      "node_modules",
-      ...packageSegments,
-    );
-    mkdirSync(packageDirectory, { recursive: true });
-    const exportsBySubpath: Record<
-      string,
-      { readonly types: string; readonly default: string }
-    > = {};
-
-    for (const { subpath, targetPath } of packageAliases) {
-      const entryPathWithoutExtension = subpath || "index";
-      const exportName = subpath ? `./${subpath}` : ".";
-      exportsBySubpath[exportName] = {
-        types: `./${entryPathWithoutExtension}.ts`,
-        default: `./${entryPathWithoutExtension}.js`,
-      };
-
-      for (const extension of ["ts", "js"]) {
-        const entryPath = join(
-          packageDirectory,
-          `${entryPathWithoutExtension}.${extension}`,
-        );
-        mkdirSync(dirname(entryPath), { recursive: true });
-        writeFileSync(
-          entryPath,
-          `export * from ${JSON.stringify(pathToImportSpecifier(entryPath, targetPath))};\n`,
-        );
-      }
-    }
-
-    writeFileSync(
-      join(packageDirectory, "package.json"),
-      JSON.stringify({
-        name: packageName,
-        type: "module",
-        exports: exportsBySubpath,
-      }),
-    );
-  }
-};
-
-const pathToImportSpecifier = (from: string, to: string): string => {
-  const path = relative(dirname(from), to).split(sep).join("/");
-  return path.startsWith(".") ? path : `./${path}`;
-};
-
-const runProcess = (
-  command: string,
-  args: ReadonlyArray<string>,
-  cwd: string,
-  operation: string,
-  details?: string,
-): Promise<void> =>
-  new Promise((resolve, reject) => {
-    const child = spawn(command, args, {
-      cwd,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    const stdout: Array<Buffer> = [];
-    const stderr: Array<Buffer> = [];
-    child.stdout.on("data", (chunk: Buffer) => {
-      stdout.push(chunk);
-    });
-    child.stderr.on("data", (chunk: Buffer) => {
-      stderr.push(chunk);
-    });
-    child.once("error", (error) => {
-      reject(
-        new Error(
-          [`${operation} failed.`, details].filter(Boolean).join("\n"),
-          {
-            cause: error,
-          },
-        ),
-      );
-    });
-    child.once("close", (code, signal) => {
-      if (code === 0) {
-        resolve();
-        return;
-      }
-      reject(
-        new Error(
-          [
-            `${operation} failed${signal === null ? ` with exit code ${String(code)}` : ` from signal ${signal}`}.`,
-            details,
-            Buffer.concat(stdout).toString("utf8"),
-            Buffer.concat(stderr).toString("utf8"),
-          ]
-            .filter(Boolean)
-            .join("\n"),
-        ),
-      );
-    });
-  });