feat(vpx): add an opt-in bundle cache for script startup

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/command_vpx_script/snapshots/vpx_script_module_formats.global.md

@@ -9,12 +9,12 @@ A .cts that uses export is CommonJS with ES module syntax; it fails with a clear
 **Exit code:** 1
 
 ```
-<repo>/packages/cli/dist/script-preload.cjs:477
-        const result = oxcNode.load(url, context, nextLoad, HELPER_MODULE_NAME);
-                               ^
+<repo>/packages/cli/dist/script-preload.cjs:507
+        const result = oxcNode().load(url, context, nextLoad, HELPER_MODULE_NAME);
+                                 ^
 
 Error: Failed to transform <workspace>/src/both.cts: a `.cts` file is CommonJS, but this one uses ES module syntax (`import`, `export` or `import.meta`), which oxc-node does not compile to CommonJS. Rename it to `.mts` to run it as an ES module, or write it as CommonJS with `import x = require("...")` and `export =`.
-    at load (<repo>/packages/cli/dist/script-preload.cjs:477:25)
+    at load (<repo>/packages/cli/dist/script-preload.cjs:507:27)
     at nextStep (node:internal/modules/customization_hooks:189:26)
     at loadWithHooks (node:internal/modules/customization_hooks:374:18)
     at #loadSync (node:internal/modules/esm/loader:865:14)
@@ -37,12 +37,12 @@ Importing it reports the same error
 **Exit code:** 1
 
 ```
-<repo>/packages/cli/dist/script-preload.cjs:477
-        const result = oxcNode.load(url, context, nextLoad, HELPER_MODULE_NAME);
-                               ^
+<repo>/packages/cli/dist/script-preload.cjs:507
+        const result = oxcNode().load(url, context, nextLoad, HELPER_MODULE_NAME);
+                                 ^
 
 Error: Failed to transform <workspace>/src/both.cts: a `.cts` file is CommonJS, but this one uses ES module syntax (`import`, `export` or `import.meta`), which oxc-node does not compile to CommonJS. Rename it to `.mts` to run it as an ES module, or write it as CommonJS with `import x = require("...")` and `export =`.
-    at load (<repo>/packages/cli/dist/script-preload.cjs:477:25)
+    at load (<repo>/packages/cli/dist/script-preload.cjs:507:27)
     at nextStep (node:internal/modules/customization_hooks:189:26)
     at loadWithHooks (node:internal/modules/customization_hooks:374:18)
     at #loadSync (node:internal/modules/esm/loader:865:14)

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/command_vpx_script/snapshots/vpx_script_module_formats.local.md

@@ -9,12 +9,12 @@ A .cts that uses export is CommonJS with ES module syntax; it fails with a clear
 **Exit code:** 1
 
 ```
-<repo>/packages/cli/dist/script-preload.cjs:477
-        const result = oxcNode.load(url, context, nextLoad, HELPER_MODULE_NAME);
-                               ^
+<repo>/packages/cli/dist/script-preload.cjs:507
+        const result = oxcNode().load(url, context, nextLoad, HELPER_MODULE_NAME);
+                                 ^
 
 Error: Failed to transform <workspace>/src/both.cts: a `.cts` file is CommonJS, but this one uses ES module syntax (`import`, `export` or `import.meta`), which oxc-node does not compile to CommonJS. Rename it to `.mts` to run it as an ES module, or write it as CommonJS with `import x = require("...")` and `export =`.
-    at load (<repo>/packages/cli/dist/script-preload.cjs:477:25)
+    at load (<repo>/packages/cli/dist/script-preload.cjs:507:27)
     at nextStep (node:internal/modules/customization_hooks:189:26)
     at loadWithHooks (node:internal/modules/customization_hooks:374:18)
     at #loadSync (node:internal/modules/esm/loader:865:14)
@@ -37,12 +37,12 @@ Importing it reports the same error
 **Exit code:** 1
 
 ```
-<repo>/packages/cli/dist/script-preload.cjs:477
-        const result = oxcNode.load(url, context, nextLoad, HELPER_MODULE_NAME);
-                               ^
+<repo>/packages/cli/dist/script-preload.cjs:507
+        const result = oxcNode().load(url, context, nextLoad, HELPER_MODULE_NAME);
+                                 ^
 
 Error: Failed to transform <workspace>/src/both.cts: a `.cts` file is CommonJS, but this one uses ES module syntax (`import`, `export` or `import.meta`), which oxc-node does not compile to CommonJS. Rename it to `.mts` to run it as an ES module, or write it as CommonJS with `import x = require("...")` and `export =`.
-    at load (<repo>/packages/cli/dist/script-preload.cjs:477:25)
+    at load (<repo>/packages/cli/dist/script-preload.cjs:507:27)
     at nextStep (node:internal/modules/customization_hooks:189:26)
     at loadWithHooks (node:internal/modules/customization_hooks:374:18)
     at #loadSync (node:internal/modules/esm/loader:865:14)

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/command_vpx_script/snapshots/vpx_script_tsconfig_transforms.global.md

@@ -34,12 +34,12 @@ Decorators without experimentalDecorators fail with a clear error
 **Exit code:** 1
 
 ```
-<repo>/packages/cli/dist/script-preload.cjs:477
-        const result = oxcNode.load(url, context, nextLoad, HELPER_MODULE_NAME);
-                               ^
+<repo>/packages/cli/dist/script-preload.cjs:507
+        const result = oxcNode().load(url, context, nextLoad, HELPER_MODULE_NAME);
+                                 ^
 
 Error: Failed to transform file://<workspace>/plain/decorators.ts: decorators require `"experimentalDecorators": true` in a tsconfig.json that includes this file; standard (TC39) decorators are not supported yet
-    at load (<repo>/packages/cli/dist/script-preload.cjs:477:25)
+    at load (<repo>/packages/cli/dist/script-preload.cjs:507:27)
     at nextStep (node:internal/modules/customization_hooks:189:26)
     at loadWithHooks (node:internal/modules/customization_hooks:374:18)
     at #loadSync (node:internal/modules/esm/loader:865:14)

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/command_vpx_script/snapshots/vpx_script_tsconfig_transforms.local.md

@@ -34,12 +34,12 @@ Decorators without experimentalDecorators fail with a clear error
 **Exit code:** 1
 
 ```
-<repo>/packages/cli/dist/script-preload.cjs:477
-        const result = oxcNode.load(url, context, nextLoad, HELPER_MODULE_NAME);
-                               ^
+<repo>/packages/cli/dist/script-preload.cjs:507
+        const result = oxcNode().load(url, context, nextLoad, HELPER_MODULE_NAME);
+                                 ^
 
 Error: Failed to transform file://<workspace>/plain/decorators.ts: decorators require `"experimentalDecorators": true` in a tsconfig.json that includes this file; standard (TC39) decorators are not supported yet
-    at load (<repo>/packages/cli/dist/script-preload.cjs:477:25)
+    at load (<repo>/packages/cli/dist/script-preload.cjs:507:27)
     at nextStep (node:internal/modules/customization_hooks:189:26)
     at loadWithHooks (node:internal/modules/customization_hooks:374:18)
     at #loadSync (node:internal/modules/esm/loader:865:14)

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/command_vpx_script_bundle_cache/after.ts

@@ -0,0 +1 @@
+((globalThis as { order?: string[] }).order ??= []).push('after');

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/command_vpx_script_bundle_cache/computed.ts

@@ -0,0 +1,6 @@
+import { counter } from './shared.ts';
+
+export function computed(): string {
+  counter.value += 10;
+  return 'loaded';
+}

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/command_vpx_script_bundle_cache/data.json

@@ -0,0 +1 @@
+{ "name": "fixture-data" }

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/command_vpx_script_bundle_cache/env-main.ts

@@ -0,0 +1,8 @@
+// Order of execution: a bundled module sets the environment, a CommonJS dependency reads it
+// while it loads, and another bundled module runs after both.
+import './load-env.ts';
+import { url } from 'reads-env';
+import './after.ts';
+
+const order = (globalThis as { order?: string[] }).order ?? [];
+console.log(`url=${url} order=${order.join(',')}`);

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/command_vpx_script_bundle_cache/globals-main.ts

@@ -0,0 +1,5 @@
+// An ES module dependency that uses a free `require()`, which Node.js does not define for
+// it: the `catch` path runs.
+import { path } from 'uses-require';
+
+console.log(`path=${path}`);

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/command_vpx_script_bundle_cache/lazy.ts

@@ -0,0 +1,6 @@
+import { counter } from './shared.ts';
+
+export function lazy(): string {
+  counter.value++;
+  return 'loaded';
+}

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/command_vpx_script_bundle_cache/lib.ts

@@ -0,0 +1,24 @@
+import path from 'node:path';
+
+export enum Color {
+  Red = 'red',
+  Blue = 'blue',
+}
+
+export class Store {
+  items: number[] = [];
+
+  constructor(private readonly name: string) {}
+
+  add(id: number): void {
+    this.items.push(id);
+  }
+
+  fail(): never {
+    throw new Error(`store ${this.name} failed`);
+  }
+}
+
+export function where(): string {
+  return path.basename(import.meta.dirname);
+}

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/command_vpx_script_bundle_cache/load-env.ts

@@ -0,0 +1,2 @@
+process.env.FIXTURE_URL = 'from-load-env';
+((globalThis as { order?: string[] }).order ??= []).push('load-env');

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/command_vpx_script_bundle_cache/main.ts

@@ -0,0 +1,33 @@
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import cjs from 'dep-cjs';
+import { esm } from 'dep-esm';
+
+import data from './data.json' with { type: 'json' };
+import { Color, Store, where } from './lib.ts';
+import { counter } from './shared.ts';
+
+const store = new Store('main');
+store.add(1);
+counter.value++;
+console.log(
+  `color=${Color.Red} items=${store.items.length} esm=${esm()} cjs=${cjs.cjs()} json=${data.name}`,
+);
+const isMain = import.meta.url === pathToFileURL(process.argv[1]!).href;
+const filename = fileURLToPath(import.meta.url) === import.meta.filename;
+console.log(`main=${isMain} filename=${filename} dirname=${where()} class=${Store.name}`);
+
+const mode = process.argv[2];
+if (mode === 'lazy') {
+  // A literal import() that the recorded run did not reach.
+  const { lazy } = await import('./lazy.ts');
+  console.log(`lazy=${lazy()} counter=${counter.value}`);
+} else if (mode === 'computed') {
+  // A computed import(), which the run resolves from this file.
+  const name = 'computed';
+  const { computed } = await import(`./${name}.ts`);
+  console.log(`computed=${computed()} counter=${counter.value}`);
+  console.log(`resolve=${import.meta.resolve('dep-esm').endsWith('/dep-esm/index.js')}`);
+} else if (mode === 'throw') {
+  store.fail();
+}

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/command_vpx_script_bundle_cache/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "command-vpx-script-bundle-cache",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": "22.23.4"
+  }
+}

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/command_vpx_script_bundle_cache/shared.ts

@@ -0,0 +1 @@
+export const counter = { value: 0 };

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/command_vpx_script_bundle_cache/snapshots.toml

@@ -0,0 +1,67 @@
+[[case]]
+name = "vpx_script_bundle_cache"
+vp = ["local", "global"]
+env = { VPX_BUNDLE_CACHE = "1", VPX_BUNDLE_CACHE_DEBUG = "1" }
+comment = "VPX_BUNDLE_CACHE=1 records a run, bundles the script's ES modules, and runs the bundle until an input changes. The debug lines show each decision; the builder runs before exit under VPX_BUNDLE_CACHE_DEBUG=1."
+steps = [
+  { argv = ["vpx", "./main.ts"], comment = "The first run loads each module and records the run; the builder then bundles its ES modules" },
+  { argv = ["vpx", "./main.ts"], comment = "Later runs load the bundle without the native loader; import.meta, CommonJS and ES module dependencies, and JSON behave as before" },
+  { argv = ["vpx", "./main.ts", "lazy"], comment = "A literal import() the recorded run did not reach runs from the bundle, with one instance of shared.ts" },
+  { argv = ["vpx", "./main.ts", "throw"], comment = "Stack traces map to the source files", continue-on-failure = true },
+  { argv = ["vpt", "replace-file-content", "lib.ts", "Red = 'red'", "Red = 'crimson'"], snapshot = false },
+  { argv = ["vpx", "./main.ts"], comment = "An edited source file drops the bundle" },
+  { argv = ["vpx", "./main.ts"], comment = "The rebuilt bundle has the edit" },
+  { argv = ["vpx", "./main.ts"], envs = [["VPX_BUNDLE_CACHE", "0"]], comment = "Without VPX_BUNDLE_CACHE=1, the script runs as before" },
+]
+
+[[case]]
+name = "vpx_script_bundle_cache_computed_import"
+vp = ["local", "global"]
+env = { VPX_BUNDLE_CACHE = "1", VPX_BUNDLE_CACHE_DEBUG = "1" }
+comment = "A computed import() resolves from its own module. A module that only it loads, and that imports a bundled module, makes a second instance once; the run warns, and the next build leaves the bundled module out."
+steps = [
+  { argv = ["vpx", "./main.ts"], comment = "The recorded run does not reach the computed import()" },
+  { argv = ["vpx", "./main.ts", "computed"], comment = "computed.ts loads from its own file and imports shared.ts from its file too: two instances, so counter=1" },
+  { argv = ["vpx", "./main.ts", "computed"], comment = "The next run records again, and the build leaves shared.ts out" },
+  { argv = ["vpx", "./main.ts", "computed"], comment = "From then on, shared.ts has one instance" },
+]
+
+[[case]]
+name = "vpx_script_bundle_cache_commonjs_globals"
+vp = ["local", "global"]
+env = { VPX_BUNDLE_CACHE = "1", VPX_BUNDLE_CACHE_DEBUG = "1" }
+comment = "An ES module that uses `require` without declaring it stays out of the bundle: Rolldown would give it a working `require()`, which Node.js does not."
+steps = [
+  { argv = ["vpx", "./globals-main.ts"], comment = "The recorded run; the build leaves the dependency out" },
+  { argv = ["vpx", "./globals-main.ts"], comment = "The bundled run takes the same path" },
+]
+
+[[case]]
+name = "vpx_script_bundle_cache_order"
+vp = ["local", "global"]
+env = { VPX_BUNDLE_CACHE = "1", VPX_BUNDLE_CACHE_DEBUG = "1" }
+comment = "Modules outside the bundle run where they ran without it: a CommonJS dependency that reads the environment while it loads sees what a bundled module before it set."
+steps = [
+  { argv = ["vpx", "./env-main.ts"], comment = "The recorded run" },
+  { argv = ["vpx", "./env-main.ts"], comment = "The bundled run keeps the order" },
+]
+
+[[case]]
+name = "vpx_script_bundle_cache_top_level_await"
+vp = ["local", "global"]
+env = { VPX_BUNDLE_CACHE = "1", VPX_BUNDLE_CACHE_DEBUG = "1" }
+comment = "A dependency that awaits at its top level keeps the script off the bundle, where its chunk could wait for itself. The script runs as without the cache."
+steps = [
+  { argv = ["vpx", "./tla-main.ts"], comment = "The recorded run; the build reports why it does not bundle" },
+  { argv = ["vpx", "./tla-main.ts"], comment = "Later runs load each module, with the same result" },
+]
+
+[[case]]
+name = "vpx_script_bundle_cache_unsupported"
+vp = "local"
+env = { VPX_BUNDLE_CACHE = "1", VPX_BUNDLE_CACHE_DEBUG = "1" }
+comment = "Options that load other modules or hooks, or change how the script runs, turn the cache off."
+steps = [
+  { argv = ["vpx", "--import", "./shared.ts", "./main.ts"], comment = "Another --import preload could register hooks that the bundle would bypass" },
+  { argv = ["vpx", "./main.ts"], envs = [["NODE_V8_COVERAGE", "${workspace}/coverage"]], comment = "Coverage reports source files, not a bundle" },
+]