node-abi 3.96.0

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:npm/node-abi@3.96.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/node-abi@3.96.0

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:b574bea27e75ac9a7d67089cf9b39a71c5a2adb21c9387b8d3f9f044c4931fab","contract":["getAbi is exported as a function from node-abi","getTarget is exported as a function from node-abi","getAbi resolves the ABI version string for standard Node.js release targets","getAbi defaults to node runtime when runtime parameter is omitted","getAbi resolves the ABI version string for Electron release targets","getAbi returns the input unchanged when a numeric ABI string is passed","getTarget resolves the target version string for given ABI and runtime","getAbi and getTarget throw error when queried with unsupported target version or ABI","allTargets and supportedTargets export target registry entries with runtime, target, abi, and lts properties"],"goal":"verify pkg:npm/node-abi@3.96.0","kind":"HOW","packages":["pkg:npm/node-abi@3.96.0"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/node-abi@3.96.0"],"schemaVersion":1,"subject":"pkg:npm/node-abi@3.96.0","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-node-abi",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-node-abi",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "node-abi": "3.96.0"
      }
    },
    "node_modules/node-abi": {
      "version": "3.96.0",
      "resolved": "https://registry.npmjs.org/node-abi/-/node-abi-3.96.0.tgz",
      "integrity": "sha512-rebQ/lz7i0EkoLzUVSrKRzA69zMkwLp95kKMWoMDkkM00Suxz0D7zEQPwRml5fQum24mj7bPvmlgLAmu2JCiYg==",
      "license": "MIT",
      "dependencies": {
        "semver": "^7.3.5"
      },
      "engines": {
        "node": ">=10"
      }
    },
    "node_modules/semver": {
      "version": "7.8.5",
      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.5.tgz",
      "integrity": "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==",
      "license": "ISC",
      "bin": {
        "semver": "bin/semver.js"
      },
      "engines": {
        "node": ">=10"
      }
    }
  }
}

{
  "name": "sample-node-abi",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room code sample for node-abi in node-abi@3.96.0",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "node-abi": "3.96.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/node-abi@3.96.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/node-abi@3.96.0"
  ]
}

const nodeAbi = require('node-abi');

/**
 * Resolves the Node or Electron ABI number string for a given target runtime version.
 *
 * @param {string} target - Runtime version string (e.g. '22.0.0').
 * @param {string} [runtime='node'] - Target runtime ('node' or 'electron').
 * @returns {string} The ABI version string.
 */
function resolveAbi(target, runtime = 'node') {
  return nodeAbi.getAbi(target, runtime);
}

/**
 * Resolves the target runtime version string for a given ABI number and runtime.
 *
 * @param {string} abi - ABI number string (e.g. '127').
 * @param {string} [runtime='node'] - Target runtime ('node' or 'electron').
 * @returns {string} The target version string.
 */
function resolveTarget(abi, runtime = 'node') {
  return nodeAbi.getTarget(abi, runtime);
}

/**
 * Checks whether a given target version string is in supportedTargets.
 *
 * @param {string} target - Target version string (e.g. '22.0.0').
 * @param {string} [runtime='node'] - Target runtime ('node' or 'electron').
 * @returns {boolean} True if supported, false otherwise.
 */
function isSupported(target, runtime = 'node') {
  const normalized = String(target).replace(/^v/, '');
  return nodeAbi.supportedTargets.some(
    (t) => t.runtime === runtime && t.target === normalized
  );
}

module.exports = {
  nodeAbi,
  getAbi: nodeAbi.getAbi,
  getTarget: nodeAbi.getTarget,
  allTargets: nodeAbi.allTargets,
  supportedTargets: nodeAbi.supportedTargets,
  deprecatedTargets: nodeAbi.deprecatedTargets,
  resolveAbi,
  resolveTarget,
  isSupported
};

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const {
  nodeAbi,
  getAbi,
  getTarget,
  allTargets,
  supportedTargets,
  deprecatedTargets,
  resolveAbi,
  resolveTarget,
  isSupported
} = require('../src/index.js');

async function runTests() {
  // 1. getAbi is exported as a function from node-abi
  assert.equal(typeof nodeAbi.getAbi, 'function', 'nodeAbi.getAbi must be a function');
  assert.equal(typeof getAbi, 'function', 'getAbi must be a function');
  assert.equal(typeof resolveAbi, 'function', 'resolveAbi helper must be a function');

  // 2. getTarget is exported as a function from node-abi
  assert.equal(typeof nodeAbi.getTarget, 'function', 'nodeAbi.getTarget must be a function');
  assert.equal(typeof getTarget, 'function', 'getTarget must be a function');
  assert.equal(typeof resolveTarget, 'function', 'resolveTarget helper must be a function');

  // 3. getAbi resolves the ABI version string for standard Node.js release targets
  assert.equal(resolveAbi('22.0.0', 'node'), '127', 'Node 22.0.0 should map to ABI 127');
  assert.equal(resolveAbi('20.0.0', 'node'), '115', 'Node 20.0.0 should map to ABI 115');
  assert.equal(resolveAbi('18.0.0', 'node'), '108', 'Node 18.0.0 should map to ABI 108');
  assert.equal(resolveAbi('24.0.0', 'node'), '137', 'Node 24.0.0 should map to ABI 137');
  assert.equal(resolveAbi('26.0.0', 'node'), '147', 'Node 26.0.0 should map to ABI 147');

  // 4. getAbi defaults to node runtime when runtime parameter is omitted
  assert.equal(resolveAbi('22.0.0'), '127', 'Omitting runtime should default to node');
  assert.equal(resolveAbi('20.0.0'), '115', 'Omitting runtime should default to node');

  // 5. getAbi resolves the ABI version string for Electron release targets
  assert.equal(resolveAbi('30.0.0', 'electron'), '123', 'Electron 30.0.0 should map to ABI 123');
  assert.equal(resolveAbi('28.0.0', 'electron'), '119', 'Electron 28.0.0 should map to ABI 119');
  assert.equal(resolveAbi('44.0.0-alpha.1', 'electron'), '149', 'Electron 44.0.0-alpha.1 should map to ABI 149');

  // 6. getAbi returns the input unchanged when a numeric ABI string is passed
  assert.equal(resolveAbi('127'), '127', 'Passing numeric ABI string should return itself');
  assert.equal(resolveAbi('149', 'electron'), '149', 'Passing numeric ABI string should return itself for electron');
  assert.equal(resolveAbi('v22.0.0', 'node'), '127', 'Leading v prefix should be stripped');

  // 7. getTarget resolves the target version string for given ABI and runtime
  assert.equal(resolveTarget('127', 'node'), '22.0.0', 'ABI 127 for node should resolve to 22.0.0');
  assert.equal(resolveTarget('123', 'electron'), '30.0.0', 'ABI 123 for electron should resolve to 30.0.0');
  assert.equal(resolveTarget('127'), '22.0.0', 'Omitting runtime should default to node');
  assert.equal(resolveTarget('22.0.0', 'node'), '22.0.0', 'Non-numeric target string should return itself');

  // 8. getAbi and getTarget throw error when queried with unsupported target version or ABI
  assert.throws(
    () => resolveAbi('999.0.0', 'node'),
    /Could not detect abi for version 999\.0\.0/,
    'getAbi should throw on unsupported version'
  );
  assert.throws(
    () => resolveTarget('99999', 'node'),
    /Could not detect target for abi 99999/,
    'getTarget should throw on unknown ABI'
  );

  // 9. allTargets and supportedTargets export target registry entries with runtime, target, abi, and lts properties
  assert.ok(Array.isArray(allTargets) && allTargets.length > 0, 'allTargets must be non-empty array');
  assert.ok(Array.isArray(supportedTargets) && supportedTargets.length > 0, 'supportedTargets must be non-empty array');
  assert.ok(Array.isArray(deprecatedTargets) && deprecatedTargets.length > 0, 'deprecatedTargets must be non-empty array');

  const targetNode22 = supportedTargets.find((t) => t.runtime === 'node' && t.target === '22.0.0');
  assert.ok(targetNode22, 'supportedTargets must contain node 22.0.0');
  assert.equal(targetNode22.abi, '127', 'node 22.0.0 abi must be 127');
  assert.equal(typeof targetNode22.lts, 'boolean', 'lts must be boolean');

  assert.equal(isSupported('22.0.0', 'node'), true, 'Node 22.0.0 should be supported');
  assert.equal(isSupported('v22.0.0', 'node'), true, 'v22.0.0 with prefix should be supported');
  assert.equal(isSupported('999.0.0', 'node'), false, 'Node 999.0.0 should not be supported');

  console.log('All contract assertions for node-abi passed successfully.');
}

runTests().catch((err) => {
  console.error('Contract test failed:', err);
  process.exit(1);
});