feat(core): warn when running on an untested Node.js version

The plugins ship ABI-pinned prebuilds for Node.js 22 and 24 only, so any
other major silently fails to load the native addon with no hint that the
runtime version is the cause.

Emit the warning before the native-binding check in setupCore, so the
version is still printed on the majors where the addon cannot load and
setupCore throws. The playwright plugin gets its own call because it
registers the integration itself and bypasses setupCore.

COD-3399

Author: not-matthias

packages/core/src/index.ts

@@ -1,6 +1,7 @@
 import { checkV8Flags } from "./introspection";
 import { MongoMeasurement } from "./mongoMeasurement";
 import native_core from "./native_core";
+import { warnOnUnsupportedNodeVersion } from "./nodeVersion";
 import { getCodspeedRunnerMode } from "./runnerMode";
 
 declare const __VERSION__: string;
@@ -12,6 +13,8 @@ export const isBound = native_core.isBound;
 export const mongoMeasurement = new MongoMeasurement();
 
 export const setupCore = () => {
+  warnOnUnsupportedNodeVersion();
+
   if (!native_core.isBound) {
     throw new Error(
       "Native core module is not bound, CodSpeed integration will not work properly",
@@ -44,6 +47,11 @@ export type {
   SetupInstrumentsResponse,
 } from "./generated/openapi";
 export { getV8Flags, tryIntrospect } from "./introspection";
+export {
+  getUnsupportedNodeVersionWarning,
+  SUPPORTED_NODE_MAJORS,
+  warnOnUnsupportedNodeVersion,
+} from "./nodeVersion";
 export { optimizeFunction, optimizeFunctionSync } from "./optimization";
 export { wrapWithRootFrame, wrapWithRootFrameSync } from "./rootFrame";
 export * from "./utils";

packages/core/src/nodeVersion.ts

@@ -0,0 +1,36 @@
+/**
+ * Node.js majors the plugins are built and tested against: the example matrix
+ * in .github/workflows/ci.yml and the prebuildify targets in package.json.
+ */
+export const SUPPORTED_NODE_MAJORS = [22, 24];
+
+/**
+ * Warning for a Node.js version outside the tested set, `null` when supported.
+ */
+export function getUnsupportedNodeVersionWarning(
+  version: string,
+): string | null {
+  const major = parseInt(version.split(".")[0], 10);
+  if (SUPPORTED_NODE_MAJORS.includes(major)) {
+    return null;
+  }
+  return `[CodSpeed] Node.js v${version} is not supported: CodSpeed is tested on Node.js ${SUPPORTED_NODE_MAJORS.join(", ")}. Support for other versions is experimental and measurements may be unstable.`;
+}
+
+let hasWarned = false;
+
+/**
+ * Print the unsupported-version warning at most once per process. Integrations
+ * call their setup path per suite or per worker.
+ */
+export function warnOnUnsupportedNodeVersion(): void {
+  if (hasWarned) {
+    return;
+  }
+  const warning = getUnsupportedNodeVersionWarning(process.versions.node);
+  if (warning === null) {
+    return;
+  }
+  hasWarned = true;
+  console.warn(warning);
+}

packages/core/tests/nodeVersion.integ.test.ts

@@ -0,0 +1,21 @@
+/* eslint-disable @typescript-eslint/no-require-imports */
+export {}; // Make this a module
+
+const { getUnsupportedNodeVersionWarning } = require("..") as {
+  getUnsupportedNodeVersionWarning: (version: string) => string | null;
+};
+
+describe("getUnsupportedNodeVersionWarning", () => {
+  it.each(["22.22.2", "24.19.0"])("should not warn on Node %s", (version) => {
+    expect(getUnsupportedNodeVersionWarning(version)).toBeNull();
+  });
+
+  it.each(["20.5.1", "23.11.0", "26.0.0"])(
+    "should warn on Node %s",
+    (version) => {
+      expect(getUnsupportedNodeVersionWarning(version)).toBe(
+        `[CodSpeed] Node.js v${version} is not supported: CodSpeed is tested on Node.js 22, 24. Support for other versions is experimental and measurements may be unstable.`,
+      );
+    },
+  );
+});

packages/playwright-plugin/src/index.ts

@@ -5,6 +5,7 @@ import {
   MARKER_TYPE_BENCHMARK_END,
   MARKER_TYPE_BENCHMARK_START,
   msToS,
+  warnOnUnsupportedNodeVersion,
   writeWalltimeResults,
   type Benchmark,
   type BenchmarkStats,
@@ -101,6 +102,8 @@ function ensureIntegrationSetup(): void {
   if (integrationInitialized) return;
   integrationInitialized = true;
 
+  warnOnUnsupportedNodeVersion();
+
   InstrumentHooks.setIntegration("node-custom", __VERSION__);
   InstrumentHooks.setEnvironment("nodejs", "version", process.versions.node);
   InstrumentHooks.setEnvironment("nodejs", "v8", process.versions.v8);