node-addon-api 1.7.2

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-addon-api@1.7.2
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/node-addon-api@1.7.2

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:e9cb9587a68bacfdef89a5ff205ae6c2599c98adbd3b78392b957b27f23b4a02","contract":["include exports quoted string path pointing to node-addon-api C++ header directory","gyp exports string path pointing to node_api.gyp configuration target","isNodeApiBuiltin and needsFlag export boolean properties indicating runtime Node-API support","getAddonConfig returns configuration metadata matching node-addon-api package exports","parseIncludePaths extracts unquoted directories from the include property","verifyHeaders confirms presence of napi.h and napi-inl.h header files in include paths"],"goal":"verify pkg:npm/node-addon-api@1.7.2","kind":"HOW","packages":["pkg:npm/node-addon-api@1.7.2"],"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-addon-api@1.7.2"],"schemaVersion":1,"subject":"pkg:npm/node-addon-api@1.7.2","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-node-addon-api",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-node-addon-api",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "node-addon-api": "1.7.2"
      }
    },
    "node_modules/node-addon-api": {
      "version": "1.7.2",
      "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-1.7.2.tgz",
      "integrity": "sha512-ibPK3iA+vaY1eEjESkQkM0BbCqFOaZMiXRTtdB0u7b4djtY6JnsjvPdUHVMg6xQt3B8fpTTWHI9A+ADjM9frzg==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-node-addon-api",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of pkg:npm/node-addon-api@1.7.2",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "node-addon-api": "1.7.2"
  }
}

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

'use strict';

const fs = require('node:fs');
const path = require('node:path');
const nodeAddonApi = require('node-addon-api');

/**
 * Returns the raw exports of node-addon-api.
 *
 * @returns {object} The node-addon-api export object.
 */
function getAddonApi() {
  return nodeAddonApi;
}

/**
 * Parses the include string from node-addon-api into an array of clean directory paths.
 *
 * @returns {string[]} Array of include directory paths.
 */
function parseIncludePaths() {
  const includeStr = nodeAddonApi.include;
  if (!includeStr || typeof includeStr !== 'string') {
    return [];
  }
  const matches = includeStr.match(/"([^"]+)"/g);
  if (matches) {
    return matches.map((item) => item.replace(/^"|"$/g, ''));
  }
  return [includeStr.replace(/^"|"$/g, '')];
}

/**
 * Verifies that required C++ headers (napi.h and napi-inl.h) exist in the include paths.
 *
 * @returns {{ hasNapiH: boolean, hasNapiInlH: boolean, headerPath: string | null }}
 */
function verifyHeaders() {
  const paths = parseIncludePaths();
  for (const dir of paths) {
    const napiH = path.join(dir, 'napi.h');
    const napiInlH = path.join(dir, 'napi-inl.h');
    if (fs.existsSync(napiH) && fs.existsSync(napiInlH)) {
      return {
        hasNapiH: true,
        hasNapiInlH: true,
        headerPath: dir
      };
    }
  }
  return {
    hasNapiH: false,
    hasNapiInlH: false,
    headerPath: null
  };
}

/**
 * Returns configuration metadata for building addons.
 *
 * @returns {{ include: string, gyp: string, isNodeApiBuiltin: boolean, needsFlag: boolean }}
 */
function getAddonConfig() {
  return {
    include: nodeAddonApi.include,
    gyp: nodeAddonApi.gyp,
    isNodeApiBuiltin: nodeAddonApi.isNodeApiBuiltin,
    needsFlag: nodeAddonApi.needsFlag
  };
}

module.exports = {
  getAddonApi,
  parseIncludePaths,
  verifyHeaders,
  getAddonConfig
};

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

const require = createRequire(import.meta.url);
const addonApi = require('node-addon-api');
const {
  getAddonApi,
  parseIncludePaths,
  verifyHeaders,
  getAddonConfig
} = require('../src/index.js');

async function testAll() {
  // 1. Direct export assertions for node-addon-api package
  assert.equal(typeof addonApi, 'object', 'node-addon-api should export an object');
  assert.notEqual(addonApi, null, 'node-addon-api export should not be null');

  // 2. include exports quoted string path pointing to node-addon-api C++ header directory
  assert.equal(typeof addonApi.include, 'string', 'addonApi.include must be a string');
  assert.ok(addonApi.include.length > 0, 'addonApi.include must not be empty');
  assert.ok(addonApi.include.startsWith('"') && addonApi.include.endsWith('"'), 'addonApi.include must be double-quoted');

  // 3. gyp exports string path pointing to node_api.gyp configuration target
  assert.equal(typeof addonApi.gyp, 'string', 'addonApi.gyp must be a string');
  assert.ok(addonApi.gyp.includes('node_api.gyp'), 'addonApi.gyp must contain node_api.gyp');

  // 4. isNodeApiBuiltin and needsFlag export boolean properties
  assert.equal(typeof addonApi.isNodeApiBuiltin, 'boolean', 'addonApi.isNodeApiBuiltin must be a boolean');
  assert.equal(typeof addonApi.needsFlag, 'boolean', 'addonApi.needsFlag must be a boolean');

  // 5. getAddonConfig returns structured metadata matching package exports
  const config = getAddonConfig();
  assert.deepEqual(config, {
    include: addonApi.include,
    gyp: addonApi.gyp,
    isNodeApiBuiltin: addonApi.isNodeApiBuiltin,
    needsFlag: addonApi.needsFlag
  }, 'getAddonConfig should match raw addonApi properties');

  // 6. parseIncludePaths extracts unquoted directories from include property
  const includePaths = parseIncludePaths();
  assert.ok(Array.isArray(includePaths), 'parseIncludePaths must return an array');
  assert.ok(includePaths.length >= 1, 'parseIncludePaths must find at least one include path');
  for (const dir of includePaths) {
    assert.ok(fs.existsSync(dir), `Include directory ${dir} must exist on disk`);
  }

  // 7. verifyHeaders confirms availability of napi.h and napi-inl.h
  const headerCheck = verifyHeaders();
  assert.equal(headerCheck.hasNapiH, true, 'napi.h must be present in include directory');
  assert.equal(headerCheck.hasNapiInlH, true, 'napi-inl.h must be present in include directory');
  assert.ok(headerCheck.headerPath !== null, 'headerPath must be resolved');

  const napiHContent = fs.readFileSync(path.join(headerCheck.headerPath, 'napi.h'), 'utf8');
  assert.ok(napiHContent.includes('napi_'), 'napi.h must contain napi_ symbols');

  console.log('All node-addon-api contract tests passed successfully.');
}

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