lib: add context.diagnostic api 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

@@ -607,6 +607,33 @@ useful when a higher-level tool measures work in a worker and needs to exclude
 message transport from the duration. `record()` is mutually exclusive with
 `start()` and `end()` within one callback and must be called exactly once.
 
+### `context.diagnostic(message[, options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `message` {string} The diagnostic message.
+* `options` {Object}
+  * `level` {string} Either `'info'` or `'warning'`. **Default:** `'info'`.
+  * `detail` {any} Additional structured-cloneable diagnostic data. With CLI
+    process isolation, it must also be supported by advanced child process
+    serialization.
+* Returns: {undefined}
+
+Queues a diagnostic associated with the current benchmark, phase, and sample
+index. Multiple diagnostics preserve call order. They are emitted after the
+sample callback settles and before that sample's `'bench:sample'` event. Warmup
+diagnostics are emitted even though warmup samples are not. Diagnostics queued
+before a callback failure are emitted before the failed `'bench:complete'`
+event and do not themselves cause the benchmark to fail. If a timeout or abort
+wins before the callback settles, queued diagnostics might not be emitted.
+
+The message and options are validated, and detail is cloned, synchronously.
+Calling `diagnostic()` between `context.start()` and `context.end()` therefore
+includes that work in the measured duration. Invalid arguments or an
+uncloneable detail violate the sample contract.
+
 ### `context.done()`
 
 <!-- YAML
@@ -695,10 +722,13 @@ left for reporters and higher-level tools to collect.
 `'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 `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.
+array. `'bench:diagnostic'` reports loading, suite, and hook errors as well as
+public context diagnostics. A context diagnostic contains the benchmark-scoped
+identity fields, `phase`, `index`, `message`, `level`, source location, and
+optional `detail`. `'bench:summary'` 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
 

lib/internal/bench_runner/benchmark.js

@@ -245,18 +245,20 @@ class BenchContext {
   #endCalled = false;
   #index;
   #invalid = false;
+  #onDiagnostic;
   #phase;
   #recordCalled = false;
   #sample = null;
   #startCalled = false;
   #startTime;
 
-  constructor(bench, signal, phase, index) {
+  constructor(bench, signal, phase, index, onDiagnostic) {
     this.name = bench.name;
     this.params = bench.params;
     this.signal = signal;
     this.#phase = phase;
     this.#index = index;
+    this.#onDiagnostic = onDiagnostic;
   }
 
   get index() {
@@ -267,6 +269,29 @@ class BenchContext {
     return this.#phase;
   }
 
+  diagnostic(message, options = kEmptyObject) {
+    if (this.#closed) {
+      this.#invalid = true;
+      throw new ERR_INVALID_STATE('benchmark sample is no longer active');
+    }
+    try {
+      validateString(message, 'message');
+      validateObject(options, 'options');
+      const { detail, level = 'info' } = options;
+      validateString(level, 'options.level');
+      if (level !== 'info' && level !== 'warning') {
+        throw new ERR_INVALID_ARG_VALUE(
+          'options.level', level, "must be 'info' or 'warning'");
+      }
+      const diagnostic = { __proto__: null, level, message };
+      if (detail !== undefined) diagnostic.detail = structuredClone(detail);
+      this.#onDiagnostic(diagnostic);
+    } catch (error) {
+      this.#invalid = true;
+      throw error;
+    }
+  }
+
   start() {
     if (this.#closed) {
       this.#invalid = true;
@@ -402,7 +427,7 @@ class BenchContext {
     this.#closed = true;
     if (this.#invalid) {
       throw new ERR_INVALID_STATE(
-        'benchmark sample violated the start()/end() contract');
+        'benchmark sample violated the context method contract');
     }
     if (!this.#recordCalled && !this.#startCalled) {
       throw new ERR_INVALID_STATE(

lib/internal/bench_runner/cli.js

@@ -327,6 +327,14 @@ function isStringArray(value) {
   return true;
 }
 
+function isContextDiagnostic(record) {
+  return record.type === 'bench:diagnostic' &&
+    (record.data.benchId !== undefined ||
+     record.data.phase !== undefined ||
+     record.data.index !== undefined ||
+     record.data.detail !== undefined);
+}
+
 function validateRecord(record) {
   if (record === null || typeof record !== 'object' ||
       !kEventTypes.has(record.type) || record.data === null ||
@@ -339,8 +347,10 @@ function validateRecord(record) {
     throw new ERR_INVALID_ARG_VALUE(
       'benchmark child message', record, 'is not a valid benchmark record');
   }
+  const contextDiagnostic = isContextDiagnostic(record);
   if ((record.type === 'bench:plan' || record.type === 'bench:start' ||
-       record.type === 'bench:sample' || record.type === 'bench:complete') &&
+       record.type === 'bench:sample' || record.type === 'bench:complete' ||
+       contextDiagnostic) &&
       (typeof record.data.fileRunId !== 'string' ||
        typeof record.data.benchId !== 'string' ||
        (record.data.parentId !== null &&
@@ -385,6 +395,21 @@ function validateRecord(record) {
         'is not a valid benchmark plan');
     }
   }
+  if (contextDiagnostic &&
+      ((record.data.phase !== 'warmup' &&
+        record.data.phase !== 'measurement') ||
+       !NumberIsSafeInteger(record.data.index) || record.data.index < 0 ||
+       record.data.index > 0xFFFFFFFF ||
+       typeof record.data.message !== 'string' ||
+       (record.data.level !== 'info' && record.data.level !== 'warning') ||
+       typeof record.data.file !== 'string' ||
+       !NumberIsSafeInteger(record.data.line) || record.data.line < 0 ||
+       !NumberIsSafeInteger(record.data.column) || record.data.column < 0 ||
+       record.data.error !== undefined)) {
+    throw new ERR_INVALID_ARG_VALUE(
+      'benchmark child diagnostic', record.data,
+      'is not a valid benchmark diagnostic');
+  }
   if (record.type === 'bench:summary') {
     const { counts, duration_ns, success } = record.data;
     if (typeof success !== 'boolean' || typeof duration_ns !== 'bigint' ||
@@ -602,6 +627,7 @@ async function runChild(path, options, scope, onRecord) {
     stdio: ['inherit', 'pipe', 'pipe', 'ipc'],
   });
   let protocolError;
+  let activeBenchId;
   let plansComplete = false;
   let recordPending = false;
   let summaryReceived = false;
@@ -662,7 +688,14 @@ async function runChild(path, options, scope, onRecord) {
       }
       recordPending = true;
       const record = deserializeRecord(validateRecord(message.record));
-      if (summaryReceived || (record.type === 'bench:plan' && plansComplete)) {
+      const contextDiagnostic = isContextDiagnostic(record);
+      if (summaryReceived || (record.type === 'bench:plan' && plansComplete) ||
+          (record.type === 'bench:start' && activeBenchId !== undefined) ||
+          ((record.type === 'bench:sample' || contextDiagnostic) &&
+           activeBenchId !== record.data.benchId) ||
+          (record.type === 'bench:complete' && activeBenchId !== undefined &&
+           activeBenchId !== record.data.benchId) ||
+          (record.type === 'bench:summary' && activeBenchId !== undefined)) {
         throw new ERR_INVALID_ARG_VALUE(
           'benchmark child message', message,
           'does not have a valid lifecycle sequence');
@@ -671,6 +704,12 @@ async function runChild(path, options, scope, onRecord) {
           record.type !== 'bench:diagnostic') {
         plansComplete = true;
       }
+      if (record.type === 'bench:start') {
+        activeBenchId = record.data.benchId;
+      } else if (record.type === 'bench:complete' &&
+                 activeBenchId === record.data.benchId) {
+        activeBenchId = undefined;
+      }
       if (record.type === 'bench:summary') summaryReceived = true;
       record.data.runId = options.runId;
       record.data.fileRunId = scope.fileRunId;