e2e 0.16.0 → 0.18.0

package/dist/cli/run-output.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The `e2e run` process's stdout and stderr. User code runs in this process
+ * too (the config's top-level code, test files while they are collected,
+ * reporters) and may print a secret, so every write to either stream goes
+ * through a `RunnerOutput`, redacted, until the process exits; only the list
+ * reporter writes to the terminal past it.
+ */
+import { RunnerOutput } from '../run/process-output.ts';
+/**
+ * Takes over `process.stdout` and `process.stderr` for the rest of the
+ * process, once: a reporter the run stopped waiting for, or a timer the
+ * config or a test file set, can still print after the run. The caller ends
+ * the run's output with `end()`, which flushes what is held and stops
+ * showing output through the list reporter; later writes stay redacted, and
+ * their last unfinished piece prints at exit.
+ */
+export declare function claimRunnerOutput(): RunnerOutput;

package/dist/cli/run-output.js

@@ -0,0 +1,45 @@
+/**
+ * The `e2e run` process's stdout and stderr. User code runs in this process
+ * too (the config's top-level code, test files while they are collected,
+ * reporters) and may print a secret, so every write to either stream goes
+ * through a `RunnerOutput`, redacted, until the process exits; only the list
+ * reporter writes to the terminal past it.
+ */
+import { RunnerOutput } from '../run/process-output.js';
+import { processSecrets } from '../run/secrecy.js';
+/**
+ * Encodings in which a string spells bytes rather than text: the write puts
+ * those bytes on the terminal, so they are what is redacted. A string in any
+ * other encoding is the text itself, redacted and written as UTF-8.
+ */
+const BYTE_ENCODINGS = new Set(['hex', 'base64', 'base64url']);
+/** The process's claimed output, once claimed: the wrappers stay for the rest of the process. */
+let claimed;
+/**
+ * Takes over `process.stdout` and `process.stderr` for the rest of the
+ * process, once: a reporter the run stopped waiting for, or a timer the
+ * config or a test file set, can still print after the run. The caller ends
+ * the run's output with `end()`, which flushes what is held and stops
+ * showing output through the list reporter; later writes stay redacted, and
+ * their last unfinished piece prints at exit.
+ */
+export function claimRunnerOutput() {
+    if (claimed !== undefined)
+        return claimed;
+    const streams = { stdout: process.stdout, stderr: process.stderr };
+    const terminal = {
+        stdout: streams.stdout.write.bind(streams.stdout),
+        stderr: streams.stderr.write.bind(streams.stderr),
+    };
+    const output = new RunnerOutput(terminal, processSecrets);
+    for (const name of ['stdout', 'stderr']) {
+        streams[name].write = ((chunk, encoding, callback) => {
+            const done = typeof encoding === 'function' ? encoding : callback;
+            const bytes = typeof chunk === 'string' && typeof encoding === 'string' && BYTE_ENCODINGS.has(encoding);
+            return output.write(name, bytes ? Buffer.from(chunk, encoding) : chunk, done);
+        });
+    }
+    process.once('exit', () => output.end());
+    claimed = output;
+    return output;
+}

package/dist/collect/collect.js

@@ -2,7 +2,7 @@
 import { realpathSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { compileGlob, compileGlobList, discoverFiles, GLOB_SYNTAX, literalPrefix, matchesGlob } from '../internal/globs.js';
-import { CollectionError } from '../internal/errors.js';
+import { CollectionError, isE2EError } from '../internal/errors.js';
 import { setupTestId, testId } from '../internal/ids.js';
 import { explainModuleError } from '../config/diagnose.js';
 import { importModule } from '../config/load.js';
@@ -338,6 +338,10 @@ export async function collect(config, positionals = []) {
         uncollected,
     };
 }
+/** A `CollectionError` from this module copy or the one a test file's imports loaded. */
+function isCollectionError(cause) {
+    return isE2EError(cause) && cause.code === 'COLLECTION_ERROR';
+}
 /**
  * Imports each discovered file once in the collection realm. A collection
  * error in a selected file, or in any file of a run nothing narrowed, throws;
@@ -356,11 +360,11 @@ async function collectFiles(config, discovered, isSelected, narrowed, lines) {
         }
         catch (cause) {
             if (skippable) {
-                uncollected.push({ file, reason: cause instanceof CollectionError ? cause.message : explainModuleError(cause, absolutePath) });
+                uncollected.push({ file, reason: isCollectionError(cause) ? cause.message : explainModuleError(cause, absolutePath) });
                 continue;
             }
             // A registration error names the option but not the module it came from.
-            if (cause instanceof CollectionError)
+            if (isCollectionError(cause))
                 throw new CollectionError(`${file}: ${cause.message}`, { cause });
             throw new CollectionError(`failed to collect ${file}: ${explainModuleError(cause, absolutePath)}`, { cause });
         }
@@ -368,7 +372,7 @@ async function collectFiles(config, discovered, isSelected, narrowed, lines) {
             files.push(collectFromRegistration(config.projectRoot, absolutePath, registration, isSelected(file), lines.get(file)));
         }
         catch (cause) {
-            if (!skippable || !(cause instanceof CollectionError))
+            if (!skippable || !isCollectionError(cause))
                 throw cause;
             uncollected.push({ file, reason: cause.message });
         }

package/dist/collect/registry.js

@@ -318,8 +318,9 @@ function validateDescribeOptions(options, parent) {
     }
 }
 /**
- * The active collector lives on globalThis because test modules load in an
- * isolated module realm (tsx) and must reach the runner's collector instance.
+ * The active collector lives on globalThis because a test module may import a
+ * copy of e2e other than the runner's and must still reach the runner's
+ * collector instance.
  */
 const collectorSlot = realmSlot('e2e.activeCollector.v1');
 /**
@@ -355,12 +356,10 @@ function requireCollector(api) {
 const PACKAGE_ROOT = path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url))));
 /**
  * The runner's own source roots, whose frames are never a test's location.
- * `dist/` is where the published module runs; `src/` is where tsx's source maps
- * relocate those very frames (and where the module runs in this repository).
+ * `dist/` is where the published module runs; `src/` is where it runs in this
+ * repository.
  */
 const RUNNER_ROOTS = ['src', 'dist'].map((dir) => `${path.join(PACKAGE_ROOT, dir)}${path.sep}`);
-/** `at name (file:line:column)` or `at file:line:column`, with or without a `file://` scheme. */
-const STACK_FRAME = /\(?(?:file:\/\/)?([^()\s]+?):(\d+):(\d+)\)?$/;
 const NODE_MODULES_SEGMENT = /[\\/]node_modules[\\/]/;
 /** The path with symlinks resolved, or the path itself when it cannot be resolved. */
 function realPath(file) {
@@ -371,6 +370,26 @@ function realPath(file) {
         return file;
     }
 }
+/** `at name (location:line:column)` or `at location:line:column`, either one after `async` for an awaiting caller. */
+const STACK_FRAME = /^at (?:async )?(?:[^(]*? \()?(.+?):(\d+):(\d+)\)?$/;
+/**
+ * Every frame of the current stack as a source location, the async frames
+ * of awaiting callers included (a test file that awaits a helper declaring
+ * tests is one), at the source positions Node.js's source maps give them.
+ * Read from the stack text: `util.getCallSites` leaves the async frames out,
+ * and with source maps on Node.js does not hand `Error.prepareStackTrace`
+ * the call sites at all.
+ */
+function stackLocations() {
+    return (new Error().stack ?? '').split('\n').slice(1).flatMap((line) => {
+        const match = STACK_FRAME.exec(line.trim());
+        if (match === null)
+            return [];
+        // An ES module names itself by URL, the loader's cache-busting query included; a mapped frame or CommonJS by path.
+        const file = match[1].startsWith('file:') ? fileURLToPath(match[1]) : match[1];
+        return [{ file, line: Number(match[2]), column: Number(match[3]) }];
+    });
+}
 /**
  * Where a test was declared, read off the stack of its `test()` call. The
  * innermost frame in the module being collected wins, so a test declared
@@ -382,19 +401,11 @@ function realPath(file) {
  * package's frames are never a test's location.
  */
 function captureSource(moduleFile) {
-    const stack = new Error().stack;
-    if (stack === undefined)
-        return undefined;
     let outsideModule;
-    for (const line of stack.split('\n').slice(1)) {
-        const match = STACK_FRAME.exec(line.trim());
-        if (match === null)
-            continue;
-        // The loader imports every module with a cache-busting query, which is not part of the file.
-        const file = decodeURIComponent(match[1]).replace(/[?#].*$/, '');
+    for (const location of stackLocations()) {
+        const { file } = location;
         if (RUNNER_ROOTS.some((root) => file.startsWith(root)) || file.startsWith('node:'))
             continue;
-        const location = { file, line: Number(match[2]), column: Number(match[3]) };
         if (moduleFile !== undefined && (file === moduleFile || realPath(file) === moduleFile)) {
             return location;
         }

package/dist/config/compiled-files.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The files e2e's loader compiles, and the one policy both of its hooks
+ * follow: TypeScript and JSX are compiled wherever they are; the project's
+ * tsconfig.json governs a file the project owns (outside `node_modules`),
+ * while an installed package's source compiles with defaults, as its author
+ * shipped it without the project's settings.
+ */
+/** The module system a compiled file runs under. */
+export type ModuleFormat = 'module' | 'commonjs';
+/** What the loader knows about one compiled extension. */
+export interface CompiledExtension {
+    /** The syntax oxc parses. */
+    readonly lang: 'ts' | 'tsx' | 'jsx';
+    readonly format: ModuleFormat;
+}
+/** Whether the `file:` URL `url` is the project's own, outside `node_modules`. */
+export declare function isProjectFile(url: URL): boolean;
+/** A file the loader compiles. */
+export interface CompiledSource {
+    readonly file: string;
+    readonly kind: CompiledExtension;
+    /** Whether the project's tsconfig.json governs it; false for an installed package's source. */
+    readonly project: boolean;
+}
+/** The compiled file `url` names, or undefined for any other module. */
+export declare function compiledSource(url: string | undefined): CompiledSource | undefined;
+/**
+ * The files TypeScript tries, in order, for an import that wrote
+ * `extension` (`x.ts`, `x.tsx`, `x.js`, `x.jsx` for `./x.js`). Empty for an
+ * extension TypeScript does not swap.
+ */
+export declare function writtenCandidates(extension: string): readonly string[];
+/** Tried, in order, after an extensionless path and after a directory's `index`: what `./x.js` would find, then JSON. */
+export declare const IMPLIED_EXTENSIONS: readonly string[];
+/** The `globalThis` symbol key of the `require` compiled CommonJS uses where Node.js's skips resolve hooks. */
+export declare const HOOKED_REQUIRE_KEY = "e2e.hooked-require.v1";

package/dist/config/compiled-files.js

@@ -0,0 +1,50 @@
+/**
+ * The files e2e's loader compiles, and the one policy both of its hooks
+ * follow: TypeScript and JSX are compiled wherever they are; the project's
+ * tsconfig.json governs a file the project owns (outside `node_modules`),
+ * while an installed package's source compiles with defaults, as its author
+ * shipped it without the project's settings.
+ */
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Every extension the loader compiles. */
+const COMPILED = {
+    '.ts': { lang: 'ts', format: 'module' },
+    '.tsx': { lang: 'tsx', format: 'module' },
+    '.jsx': { lang: 'jsx', format: 'module' },
+    '.mts': { lang: 'ts', format: 'module' },
+    '.cts': { lang: 'ts', format: 'commonjs' },
+};
+/** The files TypeScript tries, in order, for an import that writes each JavaScript extension. */
+const WRITTEN = {
+    '.js': ['.ts', '.tsx', '.js', '.jsx'],
+    '.jsx': ['.tsx', '.ts', '.jsx', '.js'],
+    '.mjs': ['.mts', '.mjs'],
+    '.cjs': ['.cts', '.cjs'],
+};
+/** A file inside an installed package. */
+const INSTALLED = /\/node_modules\//;
+/** Whether the `file:` URL `url` is the project's own, outside `node_modules`. */
+export function isProjectFile(url) {
+    return url.protocol === 'file:' && !INSTALLED.test(url.pathname);
+}
+/** The compiled file `url` names, or undefined for any other module. */
+export function compiledSource(url) {
+    if (url?.startsWith('file:') !== true)
+        return undefined;
+    const parsed = new URL(url);
+    const kind = COMPILED[path.extname(parsed.pathname)];
+    return kind === undefined ? undefined : { file: fileURLToPath(parsed), kind, project: isProjectFile(parsed) };
+}
+/**
+ * The files TypeScript tries, in order, for an import that wrote
+ * `extension` (`x.ts`, `x.tsx`, `x.js`, `x.jsx` for `./x.js`). Empty for an
+ * extension TypeScript does not swap.
+ */
+export function writtenCandidates(extension) {
+    return WRITTEN[extension] ?? [];
+}
+/** Tried, in order, after an extensionless path and after a directory's `index`: what `./x.js` would find, then JSON. */
+export const IMPLIED_EXTENSIONS = [...writtenCandidates('.js'), '.json'];
+/** The `globalThis` symbol key of the `require` compiled CommonJS uses where Node.js's skips resolve hooks. */
+export const HOOKED_REQUIRE_KEY = 'e2e.hooked-require.v1';

package/dist/config/diagnose.js

@@ -6,6 +6,7 @@
  */
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { withHint } from '../internal/errors.js';
 import { addDevDependencyCommand, detectPackageManager } from '../internal/package-manager.js';
 import { didYouMean, suggest } from '../internal/suggest.js';
@@ -44,18 +45,6 @@ const REMOVED_EXPORTS = {
         toolAppliesTo: 'toolAppliesTo was removed from e2e/agent: the built-in agent offers a defined tool only on the platforms its annotations name',
     },
 };
-/**
- * The hint for TypeScript an installed package ships under a CommonJS scope:
- * the file is there, but it loads through `require`, which the TypeScript
- * loader does not hook, so Node reports it missing under the loader's query.
- */
-function commonJsTypeScriptHint(file) {
-    let dir = path.dirname(file);
-    while (!existsSync(path.join(dir, 'package.json')) && path.dirname(dir) !== dir)
-        dir = path.dirname(dir);
-    const manifest = path.join(dir, 'package.json');
-    return `${file} exists: ${manifest} declares no "type": "module", so the file loads as CommonJS, which e2e's TypeScript loader does not transform; import the package's compiled JavaScript, or have the package declare "type": "module"`;
-}
 /**
  * The message of a failed import of `importer`, extended with what to do
  * about it when the cause is one the runner recognizes. Any other cause keeps
@@ -63,13 +52,23 @@ function commonJsTypeScriptHint(file) {
  */
 export function explainModuleError(cause, importer) {
     const message = cause instanceof Error ? cause.message : String(cause);
-    return withHint(message, moduleErrorHint(message, cause?.code, importer));
+    return withHint(`${message}${syntaxErrorLocation(cause, message)}`, moduleErrorHint(message, cause?.code, importer));
+}
+/**
+ * ` (file:line)` for a SyntaxError Node.js raised linking or parsing a
+ * module, which names the line only in the first line of its stack, not in
+ * its message; empty for any other error.
+ */
+function syntaxErrorLocation(cause, message) {
+    if (!(cause instanceof SyntaxError))
+        return '';
+    const located = /^(.+?):(\d+)\n/.exec(cause.stack ?? '');
+    if (located === null || message.includes(located[1]))
+        return '';
+    const file = located[1].startsWith('file:') ? fileURLToPath(located[1]) : located[1];
+    return ` (${file}:${located[2]})`;
 }
 function moduleErrorHint(message, code, importer) {
-    if (code === 'MODULE_NOT_FOUND') {
-        const loaded = /Cannot find module '([^']+)\?namespace=[^']*'/.exec(message)?.[1];
-        return loaded !== undefined && existsSync(loaded) ? commonJsTypeScriptHint(loaded) : '';
-    }
     if (code === 'ERR_MODULE_NOT_FOUND') {
         const missing = /Cannot find (?:package|module) '([^']+)'/.exec(message)?.[1];
         if (missing !== undefined && !missing.startsWith('.') && !path.isAbsolute(missing)) {
@@ -117,8 +116,11 @@ function missingExportHint(specifier, exportName) {
     const removed = REMOVED_EXPORTS[specifier]?.[exportName];
     if (removed !== undefined)
         return removed;
-    if (specifier !== 'e2e')
-        return '';
+    if (specifier !== 'e2e') {
+        if (!/^[A-Z]/.test(exportName))
+            return '';
+        return `if ${exportName} is a type (an interface or a type alias), import it with import type { ${exportName} }: e2e compiles each file on its own, without type information, so an import of a type has to say so, as under TypeScript's isolatedModules; with emitDecoratorMetadata, the same holds for a type a decorated member's annotation names`;
+    }
     const suggestion = suggest(exportName, RUNTIME_EXPORTS);
     if (suggestion !== undefined)
         return `did you mean "${suggestion}"?`;

package/dist/config/esm-hooks.d.ts

@@ -1,56 +1,51 @@
 /**
- * Module customization hook: the TypeScript a project owns is ESM, whatever
- * the nearest package.json says, and a module graph loaded afresh stays
- * fresh down every path import.
+ * e2e's TypeScript loader: synchronous module customization hooks
+ * (`module.registerHooks`) that run config, test, and helper TypeScript and
+ * JSX on Node.js, for `import` and `require` alike. `compiled-files.ts` says
+ * which files it compiles and which tsconfig.json governs them.
  *
- * Config and tests load through tsx's ESM API. tsx types a `.ts` file by its
- * package scope and hands a CommonJS-scoped one to Node's require, which that
- * API never hooks, so the import fails as "cannot find module" on a path that
- * carries e2e's cache-busting query. Registered before tsx, this hook runs
- * inside tsx's chain: tsx's resolve receives `format: 'module'` from it and
- * transforms the file as ESM. A Next.js app, or any package without
- * `"type": "module"`, keeps its module type.
+ * Resolve: an import written in a compiled file follows TypeScript's rules;
+ * every other import, JavaScript's included, resolves as Node.js resolves it.
+ * - A relative or absolute path: `./x.js` names the first of `x.ts`,
+ *   `x.tsx`, `x.js`, and `x.jsx` that exists (`./x.jsx` tries `x.tsx`, `x.ts`,
+ *   `x.jsx`, `x.js`; `./x.mjs` names `x.mts`, `./x.cjs` names `x.cts`), an
+ *   extensionless `./x` names `x.ts`, `x.tsx`, `x.js`, `x.jsx`, or `x.json`,
+ *   and a directory names its index the same way.
+ * - A bare specifier the project's tsconfig.json maps through `paths` or
+ *   `baseUrl` names the mapped file, before any package of that name.
+ * - A `#` import or package export that names a missing `./x.js` (or `.jsx`,
+ *   `.mjs`, `.cjs`) names the TypeScript file behind it, for an `import`.
  *
- * Forced: a file reached by path (the entry file URL, `./helper.ts`, and
- * tsconfig `paths` aliases, which tsx maps to `file:` URLs on every platform
- * before calling this hook), and TypeScript a bare or `#` specifier resolves
- * to outside `node_modules` from a module tsx loads for e2e: a workspace
- * package that exports its `.ts` source, the monorepo pattern, would
- * otherwise hit the same dead end. A module Node loads itself, such as one a
- * `.cjs` helper requires, keeps its format, so Node strips its types; forced
- * to ESM there, nothing would. An installed package under `node_modules`
- * keeps the format its own manifest declares; `.cts` files stay CommonJS.
+ * Format: `.ts`, `.mts`, `.tsx`, and `.jsx` are ES modules wherever they are
+ * and whatever the nearest package.json says, so a Next.js app, or any
+ * package without `"type": "module"`, keeps its module type and still runs
+ * its TypeScript tests, whether it is imported or a CommonJS file requires it;
+ * `.cts` is CommonJS. A JSON file imported without `with { type: 'json' }`
+ * loads as a module whose default export is the parsed file.
  *
- * A module imported with the `e2e-graph` query parameter hands it on to every
- * file it reaches by path or `#` import outside `node_modules`, so the project's own graph
- * (a config and the base config or targets file it imports) evaluates afresh
- * with it, while packages stay one shared instance.
+ * Freshness: a module imported with the `e2e-graph` query parameter hands it
+ * on to every file it reaches by path or `#` import outside `node_modules`,
+ * so the project's own graph (a config and the base config or targets file
+ * it imports) evaluates afresh with it, while packages stay one shared
+ * instance. The graph's tsconfig.json and file lookups are its own too
+ * (`tsconfig.ts`).
+ *
+ * This module, and everything it imports from e2e, is loaded by Node.js's
+ * own type stripping when a worker runs from source (`register.ts`), so it
+ * holds to erasable TypeScript: no enums, namespaces, or parameter
+ * properties.
  */
-import type { ResolveHook, ResolveHookContext, ResolveHookSync } from 'node:module';
-type Resolution = ReturnType<ResolveHookSync>;
-/** The tsx namespace e2e registers; tsx tags every URL it loads with it. */
-export declare const TSX_NAMESPACE = "e2e";
+import { type LoadHookSync, type ResolveHookSync } from 'node:module';
 /**
  * A URL that evaluates `absolutePath` afresh under `key`; with `graph`,
  * every project file it imports by path or `#` import is fresh too.
  */
 export declare function freshModuleURL(absolutePath: string, key: string, graph: boolean): string;
+export declare const resolve: ResolveHookSync;
+export declare const load: LoadHookSync;
 /**
- * The resolution, with TypeScript marked as an ES module when it is reached
- * by path, or is a project file reached any other way from a module tsx
- * loads under e2e's namespace.
- */
-export declare function asModule(specifier: string, context: Pick<ResolveHookContext, 'parentURL'>, resolution: Resolution): Resolution;
-/**
- * The resolution, joined to its importer's fresh graph: a project file
- * reached by path or by a `#` import from a module that carries
- * `GRAPH_PARAM` carries it too. A package reached by name keeps its shared
- * instance, even a workspace package that resolves outside `node_modules`: a
- * second instance of it would import a second instance of e2e itself.
+ * Registers the hooks once per process, and has stack traces follow the
+ * source maps the compiled files carry. Refuses a Node.js whose module hooks
+ * the loader cannot rely on (`node-version.ts`).
  */
-export declare function inGraph(specifier: string, context: Pick<ResolveHookContext, 'parentURL'>, resolution: Resolution): Resolution;
-/** For `module.registerHooks`. */
-export declare const resolveSync: ResolveHookSync;
-/** For `module.register`, which reads this export from the hook module. */
-export declare const resolve: ResolveHook;
-export {};
+export declare function registerLoader(): void;