@evolu/nodejs 3.1.0 → 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}".`);
@@ -314,13 +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.");
-        const viteOutput = outputs.at(0);
-        assert(viteOutput, "Vite did not return a build output.");
-        assert(viteOutput.output.length === 1, "Vite did not emit one JavaScript chunk.");
-        const chunk = viteOutput.output.at(0);
-        assert(chunk, "Vite did not emit a JavaScript chunk.");
-        assert(chunk.type === "chunk", "Vite did not emit a JavaScript chunk.");
+        assertLength(outputs, 1);
+        const viteOutput = outputs[0];
+        assertLength(viteOutput.output, 1);
+        const chunk = viteOutput.output[0];
+        assertSame(chunk.type, "chunk");
         assertType(StringType, chunk.code);
         return {
             code: chunk.code,
@@ -415,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/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"}

package/dist/src/TestOverviewReporter.js

@@ -0,0 +1,66 @@
+/**
+ * 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 { relative } from "node:path";
+import { dot, spec } from "node:test/reporters";
+import { styleText } from "node:util";
+const slowTestThresholdMs = 300;
+/**
+ * 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.
+ */
+const testOverviewReporter = async function* (source) {
+    const fileSummaries = [];
+    const dotOutput = [];
+    const specEvents = [];
+    let hasFailures = false;
+    const captureEvents = async function* () {
+        for await (const event of source) {
+            if (event.type === "test:fail")
+                hasFailures = true;
+            if (event.type === "test:summary" && event.data.file !== undefined) {
+                fileSummaries.push({ ...event.data, file: event.data.file });
+            }
+            if (event.type === "test:coverage" || event.type === "test:diagnostic") {
+                specEvents.push(event);
+            }
+            yield event;
+        }
+    };
+    for await (const output of dot(captureEvents()))
+        dotOutput.push(output);
+    fileSummaries.sort((a, b) => b.duration_ms - a.duration_ms);
+    if (hasFailures) {
+        for (const output of dotOutput)
+            yield output;
+    }
+    if (fileSummaries.length > 0) {
+        yield `${styleText("bold", "Test files:")}\n\n`;
+        for (const { counts, duration_ms, file, success } of fileSummaries) {
+            const testLabel = counts.tests === 1 ? "test" : "tests";
+            const status = styleText(success ? "green" : "red", success ? "✔" : "✖");
+            const tests = styleText("dim", `(${counts.tests} ${testLabel})`);
+            const duration = styleText(duration_ms > slowTestThresholdMs ? "yellow" : "green", `${Math.round(duration_ms)}ms`);
+            yield `${status} ${relative(process.cwd(), file)} ${tests} ${duration}\n`;
+        }
+        yield "\n";
+    }
+    const summaryReporter = spec();
+    for (const event of specEvents)
+        summaryReporter.write(event);
+    summaryReporter.end();
+    yield* summaryReporter;
+};
+export default testOverviewReporter;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolu/nodejs",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Evolu for Node.js",
   "author": "Daniel Steigerwald <daniel@steigerwald.cz>",
   "license": "MIT",
@@ -29,6 +29,11 @@
       "types": "./dist/src/TestJSDoc.d.ts",
       "import": "./dist/src/TestJSDoc.js",
       "default": "./dist/src/TestJSDoc.js"
+    },
+    "./TestOverviewReporter": {
+      "types": "./dist/src/TestOverviewReporter.d.ts",
+      "import": "./dist/src/TestOverviewReporter.js",
+      "default": "./dist/src/TestOverviewReporter.js"
     }
   },
   "typesVersions": {
@@ -38,11 +43,15 @@
       ],
       "TestJSDoc": [
         "./dist/src/TestJSDoc.d.ts"
+      ],
+      "TestOverviewReporter": [
+        "./dist/src/TestOverviewReporter.d.ts"
       ]
     }
   },
   "files": [
     "dist/src/**",
+    "!dist/**/*.test.*",
     "src/**",
     "README.md"
   ],
@@ -51,9 +60,9 @@
     "ws": "^8.21.3"
   },
   "devDependencies": {
-    "@evolu/common": "8.6.0",
-    "@evolu/oxlint-config": "0.1.0",
-    "@evolu/typescript-config": "0.1.0",
+    "@evolu/common": "8.8.0",
+    "@evolu/oxlint-config": "0.2.0",
+    "@evolu/typescript-config": "0.1.1",
     "@types/better-sqlite3": "^9.6.0",
     "@types/node": "^24.10.9",
     "@types/ws": "^8.18.1",
@@ -65,7 +74,7 @@
   },
   "peerDependencies": {
     "@evolu/common": "^8.0.0",
-    "@evolu/oxlint-config": "^0.1.0",
+    "@evolu/oxlint-config": "^0.2.0",
     "@evolu/typescript-config": "^0.1.0",
     "oxlint": "^1.79.0",
     "oxlint-tsgolint": "7.0.2001",
@@ -97,7 +106,7 @@
     }
   },
   "engines": {
-    "node": ">=24.0.0"
+    "node": ">=24.20.0"
   },
   "publishConfig": {
     "access": "public"

package/src/Cli.test.ts

@@ -0,0 +1,90 @@
+import {
+  assertEqual,
+  assertErr,
+  assertOk,
+  assertTrue,
+  testAbortError,
+  testAbortReason,
+  testCreateRun,
+} from "@evolu/common";
+import { test } from "node:test";
+import { spawn } from "./Cli.ts";
+
+test("spawn succeeds with inherited stdio and a configured cwd", async () => {
+  await using run = testCreateRun();
+  const scriptsDirectory = new URL("../../../scripts/", import.meta.url);
+  const result = await run(
+    spawn(
+      process.execPath,
+      ["-e", 'process.exit(process.cwd().endsWith("scripts") ? 0 : 1)'],
+      { cwd: scriptsDirectory },
+    ),
+  );
+
+  assertOk(result);
+});
+
+test("spawn returns a start error", async () => {
+  await using run = testCreateRun();
+  const result = await run(spawn("evolu-command-that-does-not-exist", []));
+
+  assertErr(result);
+  const { message } = result.error;
+  assertTrue(
+    message.startsWith("Failed to start evolu-command-that-does-not-exist:"),
+  );
+  assertEqual(result, {
+    ok: false,
+    error: {
+      type: "SpawnError",
+      command: "evolu-command-that-does-not-exist",
+      exitCode: null,
+      signal: null,
+      message,
+    },
+  });
+});
+
+test("spawn returns a non-zero exit error", async () => {
+  await using run = testCreateRun();
+  const result = await run(spawn(process.execPath, ["-e", "process.exit(7)"]));
+  const command = `${process.execPath} -e process.exit(7)`;
+
+  assertErr(result, {
+    type: "SpawnError",
+    command,
+    exitCode: 7,
+    signal: null,
+    message: `${command} exited with code 7.`,
+  });
+});
+
+test("spawn returns a signal exit error", async () => {
+  await using run = testCreateRun();
+  const result = await run(
+    spawn(process.execPath, ["-e", 'process.kill(process.pid, "SIGTERM")']),
+  );
+  const command = `${process.execPath} -e process.kill(process.pid, "SIGTERM")`;
+
+  assertErr(result, {
+    type: "SpawnError",
+    command,
+    exitCode: null,
+    signal: "SIGTERM",
+    message: `${command} exited from SIGTERM.`,
+  });
+});
+
+test("spawn aborts its child process with the Run", async () => {
+  await using run = testCreateRun();
+  const fiber = run.abortable(
+    spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)"]),
+  );
+
+  await new Promise<void>((resolve) => {
+    setImmediate(resolve);
+  });
+  fiber.abort(testAbortReason);
+
+  assertErr(await fiber, testAbortError);
+});

package/src/Platform.test.ts

@@ -0,0 +1,32 @@
+import {
+  assertEqual,
+  assertSame,
+  assertType,
+  PositiveInt,
+} from "@evolu/common";
+import { mock, test } from "node:test";
+import type {
+  AvailableParallelism,
+  AvailableParallelismDep,
+} from "./Platform.ts";
+
+const nodeAvailableParallelism = mock.fn<() => number>();
+
+mock.module("node:os", {
+  // @ts-expect-error -- Node.js 24.20 replaces the deprecated namedExports option with exports, which @types/node 24.13 does not declare yet.
+  exports: { availableParallelism: nodeAvailableParallelism },
+});
+
+const { availableParallelism } = await import("./Platform.ts");
+
+test("availableParallelism returns the validated Node.js value", () => {
+  nodeAvailableParallelism.mock.mockImplementation(() => 128);
+
+  const parallelism = availableParallelism();
+  const deps = { availableParallelism } satisfies AvailableParallelismDep;
+
+  assertType<typeof availableParallelism, AvailableParallelism>();
+  assertType<typeof parallelism, PositiveInt>();
+  assertSame(deps.availableParallelism, availableParallelism);
+  assertEqual(parallelism, 128);
+});

package/src/TestBundle.ts

@@ -14,18 +14,20 @@
 import {
   allSettled,
   assert,
+  assertLength,
+  assertSame,
   assertType,
   instanceOf,
   createRun,
   durationToMillis,
   escapeRegExp,
-  filterArray,
   isErr,
   mapArray,
   type NonEmptyReadonlyArray,
   type PositiveDuration,
   type ReadonlyRecord,
   type Result,
+  partitionArray,
   safelyStringifyUnknownValue,
   String as StringType,
   type Task,
@@ -301,7 +303,7 @@ export const testBundle = async ({
     ),
   );
 
-  const failures = filterArray(results, isErr);
+  const [failures, successes] = partitionArray(results, isErr);
   if (failures.length > 0) {
     const errors = mapArray(
       failures,
@@ -331,8 +333,7 @@ export const testBundle = async ({
   >();
   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}".`);
@@ -438,16 +439,11 @@ const testViteBundler: TestBundler = {
     >;
     assert(Array.isArray(output), "Vite did not return build outputs.");
     const outputs: ReadonlyArray<ViteOutput> = output;
-    assert(outputs.length === 1, "Vite did not return one build output.");
-    const viteOutput = outputs.at(0);
-    assert(viteOutput, "Vite did not return a build output.");
-    assert(
-      viteOutput.output.length === 1,
-      "Vite did not emit one JavaScript chunk.",
-    );
-    const chunk = viteOutput.output.at(0);
-    assert(chunk, "Vite did not emit a JavaScript chunk.");
-    assert(chunk.type === "chunk", "Vite did not emit a JavaScript chunk.");
+    assertLength(outputs, 1);
+    const viteOutput = outputs[0];
+    assertLength(viteOutput.output, 1);
+    const chunk = viteOutput.output[0];
+    assertSame(chunk.type, "chunk");
     assertType(StringType, chunk.code);
 
     return {
@@ -582,7 +578,7 @@ interface TestBundleWorkerError {
   readonly stack: string;
 }
 
-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`

package/src/TestOverviewReporter.test.ts

@@ -0,0 +1,219 @@
+import { assertEqual, assertFalse, assertTrue } from "@evolu/common";
+import { relative, resolve } from "node:path";
+import { describe, it } from "node:test";
+import type { TestEvent } from "node:test/reporters";
+import { stripVTControlCharacters } from "node:util";
+
+import testOverviewReporter from "./TestOverviewReporter.ts";
+
+const createFileSummaryEvent = ({
+  durationMs,
+  file,
+  success,
+  tests,
+}: {
+  readonly durationMs: number;
+  readonly file: string;
+  readonly success: boolean;
+  readonly tests: number;
+}): TestEvent => ({
+  type: "test:summary",
+  data: {
+    counts: {
+      cancelled: 0,
+      passed: success ? tests : tests - 1,
+      skipped: 0,
+      suites: 0,
+      tests,
+      todo: 0,
+      topLevel: tests,
+    },
+    duration_ms: durationMs,
+    file,
+    success,
+  },
+});
+
+const collectReporterOutput = async (
+  events: ReadonlyArray<TestEvent>,
+): Promise<string> => {
+  let output = "";
+  for await (const chunk of testOverviewReporter(events)) {
+    output +=
+      typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk);
+  }
+  return stripVTControlCharacters(output);
+};
+
+describe("testOverviewReporter", () => {
+  it("reports test files slowest-first", async () => {
+    const fastFile = resolve("packages/common/src/Fast.test.ts");
+    const slowFile = resolve("packages/common/src/Slow.test.ts");
+    const output = await collectReporterOutput([
+      createFileSummaryEvent({
+        durationMs: 2.4,
+        file: fastFile,
+        success: true,
+        tests: 1,
+      }),
+      createFileSummaryEvent({
+        durationMs: 312.6,
+        file: slowFile,
+        success: true,
+        tests: 2,
+      }),
+      {
+        type: "test:summary",
+        data: {
+          counts: {
+            cancelled: 0,
+            passed: 3,
+            skipped: 0,
+            suites: 0,
+            tests: 3,
+            todo: 0,
+            topLevel: 3,
+          },
+          duration_ms: 15,
+          file: undefined,
+          success: true,
+        },
+      },
+    ]);
+
+    assertEqual(
+      output,
+      `Test files:
+
+✔ ${relative(process.cwd(), slowFile)} (2 tests) 313ms
+✔ ${relative(process.cwd(), fastFile)} (1 test) 2ms
+
+`,
+    );
+  });
+
+  it("preserves Node.js failure diagnostics", async () => {
+    const cause = new Error("Expected Ada.");
+    const error = Object.assign(new Error("Test failed.", { cause }), {
+      cause,
+    });
+    const file = resolve("packages/common/src/Failing.test.ts");
+    const output = await collectReporterOutput([
+      {
+        type: "test:fail",
+        data: {
+          details: { duration_ms: 1, error, type: "test" },
+          file,
+          name: "fails",
+          nesting: 0,
+          testNumber: 1,
+        },
+      },
+      createFileSummaryEvent({
+        durationMs: 1,
+        file,
+        success: false,
+        tests: 1,
+      }),
+    ]);
+
+    assertTrue(output.includes("Failed tests:"));
+    assertTrue(output.includes("Test failed."));
+    assertTrue(output.includes(`✖ ${relative(process.cwd(), file)}`));
+  });
+
+  it("preserves failures without file summaries", async () => {
+    const cause = new Error("Module failed to load.");
+    const error = Object.assign(new Error("Test failed.", { cause }), {
+      cause,
+    });
+    const details: Extract<
+      TestEvent,
+      { readonly type: "test:fail" }
+    >["data"]["details"] = {
+      duration_ms: 1,
+      error,
+      type: "test",
+    };
+    const failure: TestEvent = {
+      type: "test:fail",
+      data: {
+        details,
+        file: resolve("packages/common/src/Failing.test.ts"),
+        name: "fails to load",
+        nesting: 0,
+        testNumber: 1,
+      },
+    };
+    const output = await collectReporterOutput([failure]);
+
+    assertTrue(output.includes("Failed tests:"));
+    assertTrue(output.includes("Module failed to load."));
+    assertFalse(output.includes("Test files:"));
+  });
+
+  it("uses Node.js summary and coverage formatting", async () => {
+    const output = await collectReporterOutput([
+      {
+        type: "test:diagnostic",
+        data: {
+          level: "info",
+          message: "skipped 1",
+          nesting: 0,
+        },
+      },
+      {
+        type: "test:diagnostic",
+        data: {
+          level: "error",
+          message: "Coverage threshold was not met.",
+          nesting: 0,
+        },
+      },
+      {
+        type: "test:coverage",
+        data: {
+          nesting: 0,
+          summary: {
+            files: [
+              {
+                branches: [],
+                coveredBranchCount: 1,
+                coveredFunctionCount: 1,
+                coveredLineCount: 1,
+                coveredBranchPercent: 100,
+                coveredFunctionPercent: 100,
+                coveredLinePercent: 100,
+                functions: [],
+                lines: [{ count: 1, line: 1 }],
+                path: resolve("packages/common/src/Foo.ts"),
+                totalBranchCount: 1,
+                totalFunctionCount: 1,
+                totalLineCount: 1,
+              },
+            ],
+            thresholds: { branch: 1, function: 1, line: 1 },
+            totals: {
+              coveredBranchCount: 1,
+              coveredFunctionCount: 1,
+              coveredLineCount: 1,
+              coveredBranchPercent: 100,
+              coveredFunctionPercent: 100,
+              coveredLinePercent: 100,
+              totalBranchCount: 1,
+              totalFunctionCount: 1,
+              totalLineCount: 1,
+            },
+            workingDirectory: process.cwd(),
+          },
+        },
+      },
+    ]);
+
+    assertTrue(output.includes("Coverage threshold was not met."));
+    assertTrue(output.includes("skipped 1"));
+    assertTrue(output.includes("start of coverage report"));
+    assertTrue(output.includes("Foo.ts"));
+    assertFalse(output.includes("Test files:"));
+  });
+});

package/src/TestOverviewReporter.ts

@@ -0,0 +1,86 @@
+/**
+ * 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 { relative } from "node:path";
+import { dot, spec, type TestEvent } from "node:test/reporters";
+import { styleText } from "node:util";
+
+const slowTestThresholdMs = 300;
+
+/**
+ * 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.
+ */
+const testOverviewReporter = async function* (
+  source: AsyncIterable<TestEvent> | Iterable<TestEvent>,
+): AsyncGenerator<string | Uint8Array, void> {
+  const fileSummaries: Array<
+    Extract<TestEvent, { readonly type: "test:summary" }>["data"] & {
+      readonly file: string;
+    }
+  > = [];
+  const dotOutput: Array<string> = [];
+  const specEvents: Array<TestEvent> = [];
+  let hasFailures = false;
+
+  const captureEvents = async function* (): AsyncGenerator<TestEvent, void> {
+    for await (const event of source) {
+      if (event.type === "test:fail") hasFailures = true;
+
+      if (event.type === "test:summary" && event.data.file !== undefined) {
+        fileSummaries.push({ ...event.data, file: event.data.file });
+      }
+
+      if (event.type === "test:coverage" || event.type === "test:diagnostic") {
+        specEvents.push(event);
+      }
+
+      yield event;
+    }
+  };
+
+  for await (const output of dot(captureEvents())) dotOutput.push(output);
+
+  fileSummaries.sort((a, b) => b.duration_ms - a.duration_ms);
+
+  if (hasFailures) {
+    for (const output of dotOutput) yield output;
+  }
+
+  if (fileSummaries.length > 0) {
+    yield `${styleText("bold", "Test files:")}\n\n`;
+
+    for (const { counts, duration_ms, file, success } of fileSummaries) {
+      const testLabel = counts.tests === 1 ? "test" : "tests";
+      const status = styleText(success ? "green" : "red", success ? "✔" : "✖");
+      const tests = styleText("dim", `(${counts.tests} ${testLabel})`);
+      const duration = styleText(
+        duration_ms > slowTestThresholdMs ? "yellow" : "green",
+        `${Math.round(duration_ms)}ms`,
+      );
+      yield `${status} ${relative(process.cwd(), file)} ${tests} ${duration}\n`;
+    }
+
+    yield "\n";
+  }
+
+  const summaryReporter = spec();
+  for (const event of specEvents) summaryReporter.write(event);
+  summaryReporter.end();
+  yield* summaryReporter;
+};
+
+export default testOverviewReporter;

package/src/Time.test.ts

@@ -0,0 +1,67 @@
+import {
+  assertEqual,
+  assertThrowsInstanceOf,
+  assertType,
+  Millis,
+} from "@evolu/common";
+import { afterEach, describe, it, mock } from "node:test";
+import type { HrDuration, HrTime, NodejsTime } from "./Time.ts";
+import {
+  createNodejsTime,
+  hrDurationBetween,
+  hrDurationToMillis,
+  millisToHrDuration,
+} from "./Time.ts";
+
+describe("NodejsTime", () => {
+  afterEach(() => {
+    mock.restoreAll();
+  });
+
+  it("createNodejsTime exposes the native high-resolution clock", () => {
+    mock.method(process.hrtime, "bigint", () => 123n);
+
+    const time: NodejsTime = createNodejsTime();
+    const now: HrTime = time.hrtime();
+
+    assertEqual(now, 123n);
+  });
+});
+
+describe("hrDurationBetween", () => {
+  it("returns elapsed nanoseconds", () => {
+    const result = hrDurationBetween(100n as HrTime, 125n as HrTime);
+
+    assertType<typeof result, HrDuration>();
+    assertEqual(result, 25n);
+  });
+
+  it("rejects an end time before the start time", () => {
+    assertEqual(
+      assertThrowsInstanceOf(
+        () => hrDurationBetween(125n as HrTime, 100n as HrTime),
+        Error,
+      ).message,
+      "High-resolution end time must not precede start time",
+    );
+  });
+});
+
+describe("hrDurationToMillis", () => {
+  it("rounds to the nearest millisecond", () => {
+    const result = hrDurationToMillis(1_499_999n as HrDuration);
+
+    assertType<typeof result, Millis>();
+    assertEqual(result, 1);
+    assertEqual(hrDurationToMillis(1_500_000n as HrDuration), 2);
+  });
+});
+
+describe("millisToHrDuration", () => {
+  it("converts milliseconds to nanoseconds", () => {
+    const result = millisToHrDuration(Millis.orThrow(2));
+
+    assertType<typeof result, HrDuration>();
+    assertEqual(result, 2_000_000n);
+  });
+});