lib: add runId, fileRunId, entryFile, namePath to node:bench

Signed-off-by: James M Snell <jasnell@gmail.com>
Assisted-by: Opencode
PR-URL: #65631
Reviewed-By: Filip Skokan <panva.ip@gmail.com>

Author: jasnell

doc/api/bench.md

@@ -137,6 +137,12 @@ Benchmark files passed to `--bench` should declare benchmarks but must not call
 `--bench-warmup`, `--bench-reporter`, and `--bench-reporter-destination`. See
 the [command-line options documentation][] for details.
 
+Preload modules passed through `--require` or `--import` should not declare
+benchmarks. Such declarations are not associated with an entry file and have
+an `entryFile` value of `null`. Their `fileRunId` identifies the runner or child
+execution in which they occurred. With process isolation, a preload is evaluated
+and its declarations run once for every benchmark child process.
+
 ## Benchmark reporters
 
 The built-in reporters are available from the scheme-only
@@ -262,9 +268,19 @@ benchmark. Later benchmarks continue to run.
 A timeout or abort cannot interrupt synchronous JavaScript and does not forcibly
 cancel asynchronous work that ignores `context.signal`.
 
-The stable `benchId` is based on the source file, hierarchical suite and
-benchmark names, and canonicalized parameters. Declaring the same identity
-more than once reports an error rather than merging the samples.
+The `benchId` is based on the declaration source file, hierarchical suite and
+benchmark names, and canonicalized parameters. It is stable for repeated runs
+from the same source location, but the embedded source value is not normalized
+across checkout roots, module formats, operating systems, or path casing.
+
+Execution scope is represented separately. A `runId` identifies one logical
+run, while `fileRunId` identifies a file runner or child execution within that
+run. The `entryFile` field records which entry-file import caused a declaration
+and is `null` for declarations made by preload modules.
+The same `benchId` can therefore occur under multiple `fileRunId` values when
+entry files use a shared declaration helper. Declaring the same `benchId` more
+than once within one file execution scope reports an error rather than merging
+the samples.
 
 ### `bench.skip([name][, options], fn)`
 
@@ -537,14 +553,20 @@ The events are emitted in execution order:
 * `'bench:diagnostic'`
 * `'bench:summary'`
 
-Every benchmark-scoped event contains `benchId` and `parentId`.
+Every benchmark-scoped event contains `runId`, `fileRunId`, `entryFile`,
+`benchId`, `parentId`, and `namePath`. `runId` and `fileRunId` are opaque and
+change between runs. `entryFile` identifies the top-level benchmark file whose
+loading caused the declaration, while `file` identifies the source location of
+the declaration itself. `parentId` is based on the containing suite's source
+file and hierarchical name path.
+
 `'bench:complete'` data contains a [benchmark result][]. A failed result has an
 additional `error` property and may contain samples recorded before the error.
 A skipped result has an additional `skip` property and an empty `samples`
 array. `'bench:diagnostic'` reports suite and hook errors. `'bench:summary'`
-contains overall `success`, `counts`, `duration_ns`, and `file` properties. The
-`file` is {string|null}; it is `null` when the summary aggregates multiple
-files.
+contains overall `runId`, `fileRunId`, `entryFile`, `success`, `counts`,
+`duration_ns`, and `file` properties. `fileRunId`, `entryFile`, and `file` are
+{string|null}; they are `null` when the summary aggregates multiple files.
 
 ## Sample result
 
@@ -560,10 +582,15 @@ Each measured sample has the following properties:
 
 A completed benchmark result contains:
 
-* `benchId` {string} The stable benchmark identity.
+* `runId` {string} The opaque logical run identity.
+* `fileRunId` {string} The opaque file runner or child execution identity.
+* `entryFile` {string|null} The top-level file that caused this declaration.
+* `benchId` {string} The stable declaration identity within the same source
+  layout.
 * `parentId` {string|null} The stable containing suite identity.
 * `name` {string} The benchmark name.
-* `file` {string} The source file.
+* `namePath` {string\[]} The hierarchical suite and benchmark names.
+* `file` {string} The declaration source file.
 * `line` {number} The source line.
 * `column` {number} The source column.
 * `tags` {string\[]} The inherited canonical tags.

lib/internal/bench_runner/benchmark.js

@@ -48,6 +48,7 @@ const { structuredClone } = require('internal/worker/js_transferable');
 const { bigint: hrtime } = process.hrtime;
 const kDefaultSamples = 30;
 const kDefaultWarmup = 0;
+const kEmptyNamePath = ObjectFreeze([]);
 const kEmptyParams = ObjectFreeze({ __proto__: null });
 const kEmptyTags = ObjectFreeze([]);
 
@@ -163,10 +164,19 @@ class Suite extends AsyncResource {
     this.name = name;
     this.fn = fn;
     this.loc = createLocation(loc, harness.entryFile);
+    this.isRoot = isRoot;
+    this.fileScope = isRoot ? null :
+      (parent.isRoot ? harness.getFileScope() : parent.fileScope);
+    this.namePath = isRoot ? kEmptyNamePath :
+      ObjectFreeze(getNamePath(parent, name));
+    this.suiteId = isRoot ? null : JSONStringify([
+      this.loc.file,
+      this.namePath,
+    ]);
+    this.parentId = isRoot || parent.isRoot ? null : parent.suiteId;
     this.only = validated.only;
     this.skip = validated.skip;
     this.tags = validated.tags;
-    this.isRoot = isRoot;
     this.children = [];
     this.hooks = {
       __proto__: null,
@@ -214,17 +224,15 @@ class Bench extends AsyncResource {
     this.warmup = warmup;
     this.timeout = timeout;
     this.outerSignal = signal;
-    this.namePath = getNamePath(parent, name);
+    this.fileScope = parent.isRoot ? harness.getFileScope() : parent.fileScope;
+    this.namePath = ObjectFreeze(getNamePath(parent, name));
     this.fullName = ArrayPrototypeJoin(this.namePath, ' ');
     this.benchId = JSONStringify([
       this.loc.file,
       this.namePath,
       this.params,
     ]);
-    this.parentId = parent.isRoot ? null : JSONStringify([
-      this.loc.file,
-      getNamePath(parent.parent, parent.name),
-    ]);
+    this.parentId = parent.suiteId;
     this.finished = false;
     this.result = null;
     this.completion = PromiseWithResolvers();

lib/internal/bench_runner/cli.js

@@ -2,6 +2,7 @@
 
 const {
   ArrayFrom,
+  ArrayIsArray,
   ArrayPrototypeFilter,
   ArrayPrototypeIncludes,
   ArrayPrototypeJoin,
@@ -32,6 +33,9 @@ const {
   kBenchmarksStreamDrain,
 } = require('internal/bench_runner/benchmarks_stream');
 const {
+  configureRunScope,
+  createRunId,
+  runInFileScope,
   runBenchmarks,
 } = require('internal/bench_runner/harness');
 const { deserializeError, serializeError } = require('internal/error_serdes');
@@ -116,6 +120,19 @@ function createChildFileList(patterns, cwd) {
   return null;
 }
 
+function createFileScopes(files, options) {
+  const scopes = [];
+  for (let i = 0; i < files.length; i++) {
+    ArrayPrototypePush(scopes, {
+      __proto__: null,
+      entryFile: resolve(options.cwd, files[i]),
+      fileRunId: options.isChild && i === 0 &&
+        options.fileRunId !== undefined ? options.fileRunId : createRunId(),
+    });
+  }
+  return scopes;
+}
+
 function parseNamePattern(value) {
   if (value.length === 0) return undefined;
   try {
@@ -163,11 +180,15 @@ function parseCommandLine() {
     __proto__: null,
     cwd: process.cwd(),
     destinations,
+    fileRunId: isChild && process.env.NODE_BENCH_FILE_RUN_ID ?
+      process.env.NODE_BENCH_FILE_RUN_ID : undefined,
     isChild,
     isolation: getOptionValue('--bench-isolation'),
     namePattern: parseNamePattern(getOptionValue('--bench-name-pattern')),
     namePatternSource: getOptionValue('--bench-name-pattern'),
     reporters,
+    runId: isChild && process.env.NODE_BENCH_RUN_ID ?
+      process.env.NODE_BENCH_RUN_ID : undefined,
     samples,
     warmup,
   };
@@ -292,7 +313,24 @@ function deserializeRecord(record) {
 function validateRecord(record) {
   if (record === null || typeof record !== 'object' ||
       !kEventTypes.has(record.type) || record.data === null ||
-      typeof record.data !== 'object') {
+      typeof record.data !== 'object' ||
+      typeof record.data.runId !== 'string' ||
+      (record.data.fileRunId !== null &&
+       typeof record.data.fileRunId !== 'string') ||
+      (record.data.entryFile !== null &&
+       typeof record.data.entryFile !== 'string')) {
+    throw new ERR_INVALID_ARG_VALUE(
+      'benchmark child message', record, 'is not a valid benchmark record');
+  }
+  if ((record.type === 'bench:start' || record.type === 'bench:sample' ||
+       record.type === 'bench:complete') &&
+      (typeof record.data.benchId !== 'string' ||
+       (record.data.parentId !== null &&
+        typeof record.data.parentId !== 'string') ||
+       typeof record.data.name !== 'string' ||
+       !ArrayIsArray(record.data.namePath) ||
+       ArrayPrototypeSome(
+         record.data.namePath, (name) => typeof name !== 'string'))) {
     throw new ERR_INVALID_ARG_VALUE(
       'benchmark child message', record, 'is not a valid benchmark record');
   }
@@ -345,14 +383,17 @@ async function loadBenchmarkFiles(files, options, modules, onRecord) {
   for (let i = 0; i < files.length; i++) {
     const file = resolve(options.cwd, files[i]);
     try {
-      await loader.import(pathToFileURL(file), parentURL, kEmptyObject);
+      await runInFileScope(options.fileScopes[i], () =>
+        loader.import(pathToFileURL(file), parentURL, kEmptyObject));
     } catch (error) {
       loadFailed = true;
       await onRecord({
         __proto__: null,
         type: 'bench:diagnostic',
         data: {
           __proto__: null,
+          runId: options.runId,
+          ...options.fileScopes[i],
           message: error?.message ?? String(error),
           error,
           level: 'error',
@@ -377,6 +418,10 @@ async function loadBenchmarkFiles(files, options, modules, onRecord) {
     if (record.type === 'bench:summary') {
       record.data.file = files.length === 1 ?
         resolve(options.cwd, files[0]) : null;
+      record.data.fileRunId = files.length === 1 ?
+        options.fileScopes[0].fileRunId : null;
+      record.data.entryFile = files.length === 1 ?
+        options.fileScopes[0].entryFile : null;
       summary = record.data;
     }
     await onRecord(record);
@@ -445,14 +490,16 @@ function getChildArgs(path, options) {
   return args;
 }
 
-async function runChild(path, options, onRecord) {
+async function runChild(path, options, scope, onRecord) {
   const child = spawn(process.execPath, getChildArgs(path, options), {
     __proto__: null,
     cwd: options.cwd,
     env: {
       __proto__: null,
       ...process.env,
       NODE_BENCH_CONTEXT: 'child',
+      NODE_BENCH_FILE_RUN_ID: scope.fileRunId,
+      NODE_BENCH_RUN_ID: options.runId,
     },
     serialization: 'advanced',
     stdio: ['inherit', 'pipe', 'pipe', 'ipc'],
@@ -487,6 +534,8 @@ async function runChild(path, options, onRecord) {
       type: 'bench:diagnostic',
       data: {
         __proto__: null,
+        runId: options.runId,
+        ...scope,
         message,
         level: 'info',
         file: path,
@@ -506,8 +555,15 @@ async function runChild(path, options, onRecord) {
   child.on('message', (message) => {
     if (message?.type !== kChildMessageType) return;
     try {
-      const pending = handleRecord(
-        deserializeRecord(validateRecord(message.record)));
+      const record = deserializeRecord(validateRecord(message.record));
+      record.data.runId = options.runId;
+      if (record.data.fileRunId !== null) {
+        record.data.fileRunId = scope.fileRunId;
+      }
+      if (record.data.entryFile !== null) {
+        record.data.entryFile = scope.entryFile;
+      }
+      const pending = handleRecord(record);
       trackPending(pending);
     } catch (error) {
       protocolError = error;
@@ -533,10 +589,11 @@ async function runIsolated(files, options, output) {
 
   for (let i = 0; i < files.length; i++) {
     const path = files[i];
+    const scope = options.fileScopes[i];
     let childSummary;
     let result;
     try {
-      result = await runChild(path, options, (record) => {
+      result = await runChild(path, options, scope, (record) => {
         if (record.type === 'bench:summary') {
           childSummary = record.data;
           return;
@@ -547,6 +604,8 @@ async function runIsolated(files, options, output) {
       success = false;
       output.diagnostic({
         __proto__: null,
+        runId: options.runId,
+        ...scope,
         message: error.message,
         error,
         level: 'error',
@@ -570,6 +629,8 @@ async function runIsolated(files, options, output) {
           `exit code ${result.code}` : `signal ${result.signal}`;
         output.diagnostic({
           __proto__: null,
+          runId: options.runId,
+          ...scope,
           message: `Benchmark file '${path}' failed with ${status}`,
           level: 'error',
           file: path,
@@ -578,8 +639,12 @@ async function runIsolated(files, options, output) {
     }
   }
 
+  const scope = files.length === 1 ? options.fileScopes[0] : null;
   const summary = {
     __proto__: null,
+    runId: options.runId,
+    fileRunId: scope?.fileRunId ?? null,
+    entryFile: scope?.entryFile ?? null,
     success: success && (process.exitCode ?? 0) === 0,
     counts,
     duration_ns: hrtime() - start,
@@ -596,6 +661,19 @@ async function run(patterns) {
     createBenchmarkFileList(patterns, options.cwd);
   if (files === null) return { __proto__: null, success: false };
 
+  options.runId ??= createRunId();
+  options.fileScopes = createFileScopes(files, options);
+  const scope = files.length === 1 ? options.fileScopes[0] : {
+    __proto__: null,
+    entryFile: null,
+    fileRunId: options.runId,
+  };
+  configureRunScope({
+    __proto__: null,
+    runId: options.runId,
+    ...scope,
+  });
+
   if (options.isChild) {
     try {
       const modules = await loadUserImports(options);