@evolu/nodejs 3.0.1 → 3.2.0

package/README.md

@@ -1,11 +1,20 @@
 # Evolu for Node.js
 
-This package provides Evolu for [Node.js](https://nodejs.org) 24+.
+This package provides Evolu for [Node.js](https://nodejs.org) 24.20+.
 
 ## Documentation
 
 For detailed information and usage examples, please visit [evolu.dev](https://www.evolu.dev).
 
+## Test overview reporter
+
+`@evolu/nodejs/TestOverviewReporter` lists Node.js test files slowest-first while
+preserving native failure diagnostics, run totals, and coverage output:
+
+```sh
+node --test --test-reporter=@evolu/nodejs/TestOverviewReporter
+```
+
 ## Community
 
 The Evolu community is on [GitHub Discussions](https://github.com/evoluhq/evolu/discussions), where you can ask questions and voice ideas.

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

@@ -1 +1 @@
-{"version":3,"file":"TestBundle.d.ts","sourceRoot":"","sources":["../../src/TestBundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAYL,KAAK,gBAAgB,EACrB,KAAK,cAAc,EAQpB,MAAM,eAAe,CAAC;AA4CvB,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,mDAAmD;IACnD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,sDAAsD;AACtD,MAAM,MAAM,oBAAoB,GAAG,cAAc,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAE1E,0DAA0D;AAC1D,MAAM,MAAM,gBAAgB,GAAG,cAAc,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;AAE5E,qEAAqE;AACrE,MAAM,WAAW,UAAW,SAAQ,cAAc;IAChD,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/E;AAED,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACvD;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClD;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,uEAAuE;IACvE,QAAQ,CAAC,eAAe,CAAC,EAAE,gBAAgB,CAAC;IAC5C,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,eAAO,MAAM,UAAU,qFAMpB,iBAAiB,KAAG,OAAO,CAAC,gBAAgB,CAgK9C,CAAC"}
+{"version":3,"file":"TestBundle.d.ts","sourceRoot":"","sources":["../../src/TestBundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAaL,KAAK,gBAAgB,EACrB,KAAK,cAAc,EASpB,MAAM,eAAe,CAAC;AA4CvB,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,mDAAmD;IACnD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,sDAAsD;AACtD,MAAM,MAAM,oBAAoB,GAAG,cAAc,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAE1E,0DAA0D;AAC1D,MAAM,MAAM,gBAAgB,GAAG,cAAc,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;AAE5E,qEAAqE;AACrE,MAAM,WAAW,UAAW,SAAQ,cAAc;IAChD,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/E;AAED,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACvD;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClD;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,uEAAuE;IACvE,QAAQ,CAAC,eAAe,CAAC,EAAE,gBAAgB,CAAC;IAC5C,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,eAAO,MAAM,UAAU,qFAMpB,iBAAiB,KAAG,OAAO,CAAC,gBAAgB,CA+J9C,CAAC"}

package/dist/src/TestBundle.js

@@ -62,7 +62,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
-import { allSettled, assert, assertType, instanceOf, createRun, durationToMillis, escapeRegExp, filterArray, isErr, mapArray, safelyStringifyUnknownValue, String as StringType, timeout, TimeoutError, tryAsync, } from "@evolu/common";
+import { allSettled, assert, assertLength, assertSame, assertType, instanceOf, createRun, durationToMillis, escapeRegExp, isErr, mapArray, partitionArray, safelyStringifyUnknownValue, String as StringType, timeout, TimeoutError, tryAsync, } from "@evolu/common";
 import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
@@ -186,7 +186,7 @@ export const testBundle = async ({ cases, aliases = {}, outputDirectory, bundlin
                 error,
             };
         }), { concurrency: availableParallelism() }));
-        const failures = filterArray(results, isErr);
+        const [failures, successes] = partitionArray(results, isErr);
         if (failures.length > 0) {
             const errors = mapArray(failures, ({ error: { caseName, bundler, error } }) => {
                 const message = error instanceof Error
@@ -202,8 +202,7 @@ export const testBundle = async ({ cases, aliases = {}, outputDirectory, bundlin
         const bundleEntriesByCase = new Map();
         for (const [caseName] of caseEntries)
             bundleEntriesByCase.set(caseName, []);
-        for (const result of results) {
-            assert(result.ok, "Expected every bundle test to succeed.");
+        for (const result of successes) {
             const { caseName, bundle } = result.value;
             const entries = bundleEntriesByCase.get(caseName);
             assert(entries, `Missing bundle test case "${caseName}".`);
@@ -289,11 +288,11 @@ const testViteBundler = {
         const output = await vite.build({
             root: dirname(entryPath),
             configFile: false,
-            envFile: false,
+            envDir: false,
             logLevel: "silent",
             resolve: {
                 alias: Object.entries(aliases).map(([name, replacement]) => ({
-                    find: new RegExp(`^${escapeRegExp(name)}$`),
+                    find: new RegExp(`^${escapeRegExp(name)}$`, "u"),
                     replacement,
                 })),
             },
@@ -314,12 +313,11 @@ const testViteBundler = {
         });
         assert(Array.isArray(output), "Vite did not return build outputs.");
         const outputs = output;
-        assert(outputs.length === 1, "Vite did not return one build output.");
+        assertLength(outputs, 1);
         const viteOutput = outputs[0];
-        assert(viteOutput, "Vite did not return a build output.");
-        assert(viteOutput.output.length === 1, "Vite did not emit one JavaScript chunk.");
+        assertLength(viteOutput.output, 1);
         const chunk = viteOutput.output[0];
-        assert(chunk, "Vite did not emit a JavaScript chunk.");
+        assertSame(chunk.type, "chunk");
         assertType(StringType, chunk.code);
         return {
             code: chunk.code,
@@ -414,7 +412,7 @@ const runTestBundler = (bundlerName, options) => async (run) => tryAsync(async (
     assertType(ErrorType, error);
     return error;
 });
-const ErrorType = /*#__PURE__*/ instanceOf(globalThis.Error);
+const ErrorType = /*#__PURE__*/ instanceOf(Error);
 // TODO: Replace the evaluated CommonJS worker with an ESM module worker.
 const testBundleWorkerSource = String.raw `
 const { parentPort, workerData } = require("node:worker_threads");

package/dist/src/TestJSDoc.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Utilities for testing TypeScript examples embedded in JSDoc and Markdown.
+ *
+ * These utilities use the dedicated `@evolu/nodejs/TestJSDoc` entry point so
+ * normal `@evolu/nodejs` imports do not evaluate TypeScript and JSDoc tooling.
+ *
+ * @module
+ */
+import { type ReadonlyRecord } from "@evolu/common";
+/**
+ * Options for linting, 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;
+}
+/**
+ * Lints, 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 imported in source order by one Node.js
+ * process. Lint, compilation, and execution failures are reported together.
+ * Examples are linted with `@evolu/oxlint-config`. Evolu's required polyfills
+ * are installed before each example runs.
+ *
+ * Install `@evolu/oxlint-config`, `@evolu/typescript-config`, `oxlint`,
+ * `oxlint-tsgolint`, and TypeScript as development dependencies in the project
+ * that calls this helper.
+ *
+ * Write every TypeScript fence as a standalone, deterministic example and
+ * explicitly import its dependencies and assertions. Use `assertType` to prove
+ * static contracts, `assertEqual` for Data comparisons, `assert` with a
+ * descriptive message for invariants and narrowing, and `assertOk` or
+ * `assertErr` for Results. Prefix intentionally unused declarations with `_`;
+ * an underscore-prefixed declaration must remain unused. 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/nodejs/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",
+ *       ' * import { assertEqual } from "@evolu/common";',
+ *       " *",
+ *       " * assertEqual(1 + 1, 2);",
+ *       " * ``" + "`",
+ *       " *" + "/",
+ *       "export {};",
+ *     ].join("\n"),
+ *   );
+ *   await testJSDocExamples({
+ *     cwd: process.cwd(),
+ *     include: sourcePath,
+ *   });
+ * } 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

@@ -0,0 +1 @@
+{"version":3,"file":"TestJSDoc.d.ts","sourceRoot":"","sources":["../../src/TestJSDoc.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAY,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAiB9D;;;GAGG;AACH,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;AA+CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,eAAO,MAAM,iBAAiB,kDAK3B,wBAAwB,KAAG,OAAO,CAAC,IAAI,CAgKzC,CAAC"}

package/dist/src/TestJSDoc.js

@@ -0,0 +1,452 @@
+/**
+ * Utilities for testing TypeScript examples embedded in JSDoc and Markdown.
+ *
+ * These utilities use the dedicated `@evolu/nodejs/TestJSDoc` entry point so
+ * normal `@evolu/nodejs` imports do not evaluate TypeScript and JSDoc tooling.
+ *
+ * @module
+ */
+import { mapArray } 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 { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { stripVTControlCharacters } from "node:util";
+const jsdocPattern = /\/\*\*[\s\S]*?\*\//gu;
+const fencePattern = /(?:```|~~~)([^\n]*)\n([\s\S]*?)(?:(```|~~~)|$)/gu;
+const markdownFilePattern = /\.mdx?$/iu;
+const packageNamePattern = /^(?:@[a-z\d][a-z\d._~-]*\/)?[a-z\d][a-z\d._~-]*$/iu;
+const packageSubpathSegmentPattern = /^[a-z\d][a-z\d._~-]*$/iu;
+const polyfillsPath = fileURLToPath(import.meta.resolve("@evolu/common/polyfills"));
+/**
+ * Lints, 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 imported in source order by one Node.js
+ * process. Lint, compilation, and execution failures are reported together.
+ * Examples are linted with `@evolu/oxlint-config`. Evolu's required polyfills
+ * are installed before each example runs.
+ *
+ * Install `@evolu/oxlint-config`, `@evolu/typescript-config`, `oxlint`,
+ * `oxlint-tsgolint`, and TypeScript as development dependencies in the project
+ * that calls this helper.
+ *
+ * Write every TypeScript fence as a standalone, deterministic example and
+ * explicitly import its dependencies and assertions. Use `assertType` to prove
+ * static contracts, `assertEqual` for Data comparisons, `assert` with a
+ * descriptive message for invariants and narrowing, and `assertOk` or
+ * `assertErr` for Results. Prefix intentionally unused declarations with `_`;
+ * an underscore-prefixed declaration must remain unused. 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/nodejs/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",
+ *       ' * import { assertEqual } from "@evolu/common";',
+ *       " *",
+ *       " * assertEqual(1 + 1, 2);",
+ *       " * ``" + "`",
+ *       " *" + "/",
+ *       "export {};",
+ *     ].join("\n"),
+ *   );
+ *   await testJSDocExamples({
+ *     cwd: process.cwd(),
+ *     include: sourcePath,
+ *   });
+ * } 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)))).toSorted();
+    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 typescriptConfigPath = resolve(dirname(resolvePackageJSON(workingDirectory, "@evolu/typescript-config")), "base.json");
+    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 };
+        });
+        const compilerConfigPath = join(temporaryDirectory, "tsconfig.json");
+        writeFileSync(compilerConfigPath, JSON.stringify({
+            extends: typescriptConfigPath,
+            compilerOptions: {
+                allowImportingTsExtensions: true,
+                composite: false,
+                declaration: false,
+                declarationMap: false,
+                incremental: false,
+                lib: ["dom", "esnext"],
+                module: "NodeNext",
+                noEmit: true,
+                noUnusedLocals: false,
+                noUnusedParameters: false,
+                target: "es2022",
+                types: ["node"],
+            },
+            files: generatedExamples.map(({ generatedPath }) => generatedPath),
+        }));
+        let lintError;
+        try {
+            await lintJSDocExamples(generatedExamples, compilerConfigPath, workingDirectory);
+        }
+        catch (error) {
+            assert(error instanceof Error, "Expected Oxlint to fail with an Error.");
+            lintError = error;
+        }
+        let compilationError;
+        try {
+            await runProcess(process.execPath, [compilerPath, "--project", compilerConfigPath], workingDirectory, "Documentation example TypeScript compilation", {
+                details: generatedExamplesToDetails(generatedExamples, temporaryDirectory, workingDirectory),
+            });
+        }
+        catch (error) {
+            assert(error instanceof Error, "Expected TypeScript compilation to fail with an Error.");
+            compilationError = error;
+        }
+        const runnableExamples = compilationError === undefined
+            ? generatedExamples
+            : getExamplesWithoutCompilationErrors(generatedExamples, compilationError, workingDirectory);
+        let executionError;
+        try {
+            await runJSDocExamples(runnableExamples, temporaryDirectory, workingDirectory);
+        }
+        catch (error) {
+            assert(error instanceof Error, "Expected example execution to fail with an Error.");
+            executionError = error;
+        }
+        const failures = [];
+        if (lintError !== undefined)
+            failures.push(lintError);
+        if (compilationError !== undefined)
+            failures.push(compilationError);
+        if (executionError !== undefined)
+            failures.push(executionError);
+        const firstFailure = failures[0];
+        if (failures.length === 1 && firstFailure !== undefined) {
+            throw firstFailure;
+        }
+        if (failures.length > 1) {
+            throw new AggregateError(failures.flatMap((failure) => failure instanceof AggregateError
+                ? failure.errors
+                : [failure]), mapArray(failures, ({ message }) => message).join("\n"));
+        }
+    }
+    finally {
+        rmSync(temporaryDirectory, { force: true, recursive: true });
+    }
+};
+const lintJSDocExamples = async (examples, compilerConfigPath, workingDirectory) => {
+    const oxlintPath = resolvePackageBinary(workingDirectory, "oxlint", "oxlint");
+    const tsgolintPath = resolvePackageBinary(workingDirectory, "oxlint-tsgolint", "tsgolint");
+    const sharedOxlintConfigPath = resolve(dirname(resolvePackageJSON(workingDirectory, "@evolu/oxlint-config")), "config.jsonc");
+    const oxlintConfigPath = join(dirname(compilerConfigPath), "oxlint.json");
+    writeFileSync(oxlintConfigPath, JSON.stringify({
+        extends: [sharedOxlintConfigPath],
+        overrides: [
+            {
+                files: ["**/*.{ts,tsx,mts}"],
+                rules: {
+                    "eslint/no-unused-vars": [
+                        "error",
+                        {
+                            args: "all",
+                            argsIgnorePattern: "^_",
+                            caughtErrors: "all",
+                            caughtErrorsIgnorePattern: "^_",
+                            destructuredArrayIgnorePattern: "^_",
+                            reportUsedIgnorePattern: true,
+                            varsIgnorePattern: "^_",
+                        },
+                    ],
+                },
+            },
+        ],
+    }));
+    await runProcess(process.execPath, [
+        oxlintPath,
+        "--config",
+        oxlintConfigPath,
+        "--deny-warnings",
+        "--format",
+        "json",
+        "--tsconfig",
+        compilerConfigPath,
+        "--report-unused-disable-directives-severity=error",
+        ...mapArray(examples, ({ generatedPath }) => generatedPath),
+    ], workingDirectory, "Documentation example Oxlint", {
+        environment: { OXLINT_TSGOLINT_PATH: tsgolintPath },
+        exitErrorFromOutput: (stdout, stderr) => oxlintOutputToError(stdout, stderr, examples, workingDirectory),
+    });
+};
+const oxlintOutputToError = (stdout, stderr, examples, workingDirectory) => {
+    const { diagnostics } = JSON.parse(stdout);
+    if (diagnostics.length === 0) {
+        return new Error(["Documentation example Oxlint failed.", stdout, stderr]
+            .filter(Boolean)
+            .join("\n"));
+    }
+    const examplesByGeneratedPath = new Map(mapArray(examples, (example) => [example.generatedPath, example]));
+    const errors = diagnostics
+        .map((diagnostic) => {
+        const example = examplesByGeneratedPath.get(resolve(workingDirectory, diagnostic.filename));
+        assert(example !== undefined, `Oxlint reported an unknown generated example: ${diagnostic.filename}.`);
+        const label = diagnostic.labels[0];
+        assert(label !== undefined, `Oxlint did not report a source location for ${diagnostic.filename}.`);
+        const line = example.sourceLine + label.span.line - 5;
+        const filePath = relative(workingDirectory, example.filePath);
+        const code = diagnostic.code ?? "";
+        return {
+            code,
+            filePath,
+            line,
+            message: `${filePath}:${line}: ${code === "" ? "" : `${code}: `}${diagnostic.message}${diagnostic.help === undefined ? "" : ` ${diagnostic.help}`}`,
+        };
+    })
+        .toSorted((first, second) => first.filePath.localeCompare(second.filePath) ||
+        first.line - second.line ||
+        first.code.localeCompare(second.code))
+        .map(({ message }) => new Error(message));
+    return new AggregateError(errors, [
+        "Documentation example Oxlint failed.",
+        ...mapArray(errors, ({ message }) => `- ${message}`),
+    ].join("\n"));
+};
+const generatedExamplesToDetails = (examples, temporaryDirectory, workingDirectory) => [
+    "Generated example sources:",
+    ...mapArray(examples, ({ filePath, generatedPath, line }) => `- ${relative(temporaryDirectory, generatedPath)}: ${relative(workingDirectory, filePath)}:${line}`),
+].join("\n");
+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+/u);
+        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 untrimmedExampleSource = stripJSDocPrefixes
+            ? fence[2].replaceAll(/^[ \t]*\* ?/gmu, "")
+            : fence[2];
+        const exampleSource = untrimmedExampleSource.trim();
+        assert(exampleSource.length > 0, `${filePath}:${line} has an empty TypeScript example.`);
+        const sourceLine = line +
+            getLineNumber(untrimmedExampleSource, untrimmedExampleSource.indexOf(exampleSource));
+        examples.push({ filePath, line, source: exampleSource, sourceLine });
+    }
+    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))};`,
+    "installPolyfills();",
+    example.source,
+].join("\n\n");
+const resolveTypeScriptCompiler = (workingDirectory, typescriptPackage) => resolvePackageBinary(workingDirectory, typescriptPackage, "tsc");
+const resolvePackageBinary = (workingDirectory, packageName, binaryName) => {
+    const packagePath = resolvePackageJSON(workingDirectory, packageName);
+    const packageJson = JSON.parse(readFileSync(packagePath, "utf8"));
+    const namedBinaries = typeof packageJson.bin === "object" ? Object.values(packageJson.bin) : [];
+    const binary = typeof packageJson.bin === "string"
+        ? packageJson.bin
+        : (packageJson.bin?.[binaryName] ??
+            (namedBinaries.length === 1 ? namedBinaries[0] : undefined));
+    assert(binary !== undefined, `${packageName} does not expose a ${binaryName} executable.`);
+    return resolve(dirname(packagePath), binary);
+};
+const resolvePackageJSON = (workingDirectory, packageName) => {
+    const packagePath = findPackageJSON(packageName, pathToFileURL(join(workingDirectory, "package.json")));
+    assert(packagePath !== undefined, `Cannot resolve ${packageName} from ${workingDirectory}.`);
+    return packagePath;
+};
+const runJSDocExamples = async (examples, temporaryDirectory, workingDirectory) => {
+    if (examples.length === 0)
+        return;
+    const runnerPath = join(temporaryDirectory, "run-examples.mjs");
+    const resultPath = join(temporaryDirectory, "run-examples-result.json");
+    writeFileSync(runnerPath, [
+        'import { writeFileSync } from "node:fs";',
+        "",
+        `const examples = ${JSON.stringify(mapArray(examples, ({ generatedPath }) => pathToFileURL(generatedPath).href))};`,
+        "const failures = [];",
+        "for (const [index, example] of examples.entries()) {",
+        "  try {",
+        "    await import(example);",
+        "  } catch (error) {",
+        "    failures.push({",
+        "      index,",
+        "      message: error instanceof Error ? error.message : String(error),",
+        "    });",
+        "  }",
+        "}",
+        `writeFileSync(${JSON.stringify(resultPath)}, JSON.stringify({ failures }));`,
+        "",
+    ].join("\n"));
+    await runProcess(process.execPath, [runnerPath], workingDirectory, "Node.js execution");
+    const { failures } = JSON.parse(readFileSync(resultPath, "utf8"));
+    if (failures.length === 0)
+        return;
+    const errors = mapArray(failures, ({ index, message }) => {
+        const example = examples[index];
+        assert(example !== undefined, `Expected generated example at index ${index}.`);
+        return new Error(`${relative(workingDirectory, example.filePath)}:${example.line}: ${message}`);
+    });
+    throw new AggregateError(errors, [
+        "JSDoc example execution failed.",
+        ...mapArray(errors, (error) => `- ${error.message}`),
+    ].join("\n"));
+};
+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}`;
+};
+const runProcess = (command, args, cwd, operation, { details, environment, exitErrorFromOutput, } = {}) => new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+        cwd,
+        env: environment === undefined
+            ? process.env
+            : { ...process.env, ...environment },
+        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;
+        }
+        const stdoutText = Buffer.concat(stdout).toString("utf8");
+        const stderrText = Buffer.concat(stderr).toString("utf8");
+        if (exitErrorFromOutput !== undefined) {
+            try {
+                reject(exitErrorFromOutput(stdoutText, stderrText));
+            }
+            catch (error) {
+                reject(new Error([
+                    `${operation} failed while reading its output.`,
+                    stdoutText,
+                    stderrText,
+                ]
+                    .filter(Boolean)
+                    .join("\n"), { cause: error }));
+            }
+            return;
+        }
+        reject(new Error([
+            `${operation} failed${signal === null ? ` with exit code ${String(code)}` : ` from signal ${signal}`}.`,
+            details,
+            stdoutText,
+            stderrText,
+        ]
+            .filter(Boolean)
+            .join("\n")));
+    });
+});

package/dist/src/TestOverviewReporter.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Overview reporting for Node.js tests.
+ *
+ * Use the dedicated `@evolu/nodejs/TestOverviewReporter` entry point directly
+ * with Node.js:
+ *
+ * ```sh
+ * node --test --test-reporter=@evolu/nodejs/TestOverviewReporter
+ * ```
+ *
+ * @module
+ */
+import { type TestEvent } from "node:test/reporters";
+/**
+ * Lists test files slowest-first and preserves Node.js failure diagnostics, run
+ * totals, and coverage output.
+ *
+ * Durations longer than 300 ms are highlighted when terminal colors are
+ * supported.
+ */
+declare const testOverviewReporter: (source: AsyncIterable<TestEvent> | Iterable<TestEvent>) => AsyncGenerator<string | Uint8Array, void>;
+export default testOverviewReporter;
+//# sourceMappingURL=TestOverviewReporter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TestOverviewReporter.d.ts","sourceRoot":"","sources":["../../src/TestOverviewReporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAKhE;;;;;;GAMG;AACH,QAAA,MAAM,oBAAoB,WAChB,aAAa,CAAC,SAAS,CAAC,GAAG,QAAQ,CAAC,SAAS,CAAC,KACrD,cAAc,CAAC,MAAM,GAAG,UAAU,EAAE,IAAI,CAuD1C,CAAC;eAEa,oBAAoB"}