ci: check the prebuilt addon binds on every supported Node major

The existing jobs compile the addon with the same Node they then run it
under, so an incompatible prebuild cannot show up there. Build one prebuild
set and load it from each major a consumer may run, calling setupCore so
that lazily bound V8 symbols are resolved rather than only opening the file.

Author: not-matthias

.github/workflows/ci.yml

@@ -27,6 +27,45 @@ jobs:
       - run: pnpm install --frozen-lockfile --prefer-offline
       - run: pnpm turbo run lint typecheck test
 
+  native-abi:
+    runs-on: "ubuntu-latest"
+    name: Native addon ABI compatibility
+    env:
+      # The flags the runner passes in a real benchmark process.
+      NODE_OPTS: "--interpreted-frames-native-stack --allow-natives-syntax"
+    steps:
+      - uses: "actions/checkout@v4"
+        with:
+          fetch-depth: 0
+          submodules: true
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v6
+        with:
+          cache: pnpm
+          node-version-file: .nvmrc
+      - name: Restore turbo cache
+        uses: ./.github/actions/turbo-cache
+        with:
+          key-suffix: native-abi
+      - run: pnpm install --frozen-lockfile --prefer-offline
+      # One prebuild set, built once, then loaded by every Node major a
+      # consumer may run. The other jobs compile the addon with the same Node
+      # they run it under, so they cannot see an ABI mismatch.
+      - run: pnpm turbo run build --filter=@codspeed/core
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+      - run: node ${{ env.NODE_OPTS }} scripts/assert-native-binding.cjs
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+      - run: node ${{ env.NODE_OPTS }} scripts/assert-native-binding.cjs
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "26"
+      - run: node ${{ env.NODE_OPTS }} scripts/assert-native-binding.cjs
+
   list-examples:
     runs-on: "ubuntu-latest"
     name: List examples

scripts/assert-native-binding.cjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// Loads the prebuilt native addon through the same resolution a consumer gets
+// and runs the perf-map handler. Symbols in the addon are bound lazily, so a
+// prebuild that is incompatible with the running ABI loads without complaint
+// and only dies once a V8 entry point is actually called.
+const fs = require("fs");
+const path = require("path");
+
+const core = require(
+  path.join(__dirname, "..", "packages", "core", "dist", "index.cjs.js"),
+);
+
+const runtime = `Node ${process.version} (ABI ${process.versions.modules}, ${process.platform}-${process.arch})`;
+
+core.setupCore();
+core.teardownCore();
+
+const perfMap = path.join("/tmp", `perf-${process.pid}.map`);
+const entries = fs
+  .readFileSync(perfMap, "utf8")
+  .split("\n")
+  .filter((line) => line.length > 0);
+fs.unlinkSync(perfMap);
+
+if (entries.length === 0) {
+  throw new Error(`${runtime}: the perf map handler produced no entries`);
+}
+
+console.log(`${runtime}: bound, ${entries.length} perf map entries`);