bare-signals 5.0.0: constants

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 bare-signals.constants in pkg:npm/bare-signals@5.0.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/bare-signals@5.0.0
Demonstrate these symbols/APIs:
  - bare-signals.constants

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:5bdab0628282b13ff8a9441234d4ddc692c4996071f329c91dad73fd75a0f65f","contract":["package manifest exports Signal class and declares constants property in bare-signals@5.0.0","TypeScript definitions in index.d.ts declare constants as Record\u003cstring, number\u003e within Signal namespace","native C binding in binding.c exports signals map containing standard POSIX signal definitions","Signal.constants exposes the dictionary mapping signal names to numeric signal values","helper getSignalNumber resolves numeric value for supported signal names from constants","helper getSignalName performs reverse lookup of signal name from numeric value in constants","helper isSupportedSignal validates whether a given signal name exists in constants","Signal constructor resolves string signal names to numeric signums using constants map","Signal constructor rejects signal names absent from constants with UNKNOWN_SIGNAL error"],"goal":"verify bare-signals.constants in pkg:npm/bare-signals@5.0.0","kind":"HOW","packages":["pkg:npm/bare-signals@5.0.0"],"schemaVersion":1,"symbols":["bare-signals.constants"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/bare-signals@5.0.0"],"schemaVersion":1,"subject":"pkg:npm/bare-signals@5.0.0","symbols":["bare-signals.constants"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-bare-signals-constants",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-bare-signals-constants",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "bare-signals": "5.0.0"
      }
    },
    "node_modules/bare-events": {
      "version": "2.9.2",
      "resolved": "https://registry.npmjs.org/bare-events/-/bare-events-2.9.2.tgz",
      "integrity": "sha512-AIPKioV7/Y/8KfZ3AAhjPJxLLbY49S64Ym5DakZlUg75qQiTgUq9hEJoEwa4eUezPUlXRy/i5NpsKvo9jgKmoA==",
      "license": "Apache-2.0",
      "peerDependencies": {
        "bare-abort-controller": "*"
      },
      "peerDependenciesMeta": {
        "bare-abort-controller": {
          "optional": true
        }
      }
    },
    "node_modules/bare-signals": {
      "version": "5.0.0",
      "resolved": "https://registry.npmjs.org/bare-signals/-/bare-signals-5.0.0.tgz",
      "integrity": "sha512-8Gn8bBFUh2AUCJ9wWWFjSGWIo1HIUSIQnXRJGSm/f7GCDMqsuJhRmR1dT+HtDaDBkeu2l8Koxt2JLurfJ5yHVw==",
      "license": "Apache-2.0",
      "dependencies": {
        "bare-events": "^2.5.3"
      },
      "engines": {
        "bare": ">=1.7.0"
      }
    }
  }
}

{
  "name": "sample-bare-signals-constants",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "bare-signals": "5.0.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify bare-signals.constants in pkg:npm/bare-signals@5.0.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/bare-signals@5.0.0"
  ],
  "symbols": [
    "bare-signals.constants"
  ]
}

import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);

/**
 * Checks whether a signal name is present in the provided constants mapping.
 *
 * @param {string} signalName
 * @param {Record<string, number>} constants
 * @returns {boolean}
 */
export function isSupportedSignal(signalName, constants) {
  if (typeof signalName !== 'string' || !constants) {
    return false;
  }
  return Object.prototype.hasOwnProperty.call(constants, signalName);
}

/**
 * Resolves a signal name to its numeric signum using the constants mapping.
 * Throws UNKNOWN_SIGNAL if the signal name is not present in constants.
 *
 * @param {string} signalName
 * @param {Record<string, number>} constants
 * @returns {number}
 */
export function getSignalNumber(signalName, constants) {
  if (!isSupportedSignal(signalName, constants)) {
    const SignalError = require('bare-signals/errors');
    throw SignalError.UNKNOWN_SIGNAL(`Unknown signal '${signalName}'`);
  }
  return constants[signalName];
}

/**
 * Performs reverse lookup to find a signal name corresponding to a numeric signum.
 *
 * @param {number} signum
 * @param {Record<string, number>} constants
 * @returns {string | null}
 */
export function getSignalName(signum, constants) {
  if (typeof signum !== 'number' || !constants) {
    return null;
  }
  for (const [name, num] of Object.entries(constants)) {
    if (num === signum) {
      return name;
    }
  }
  return null;
}

/**
 * Returns a list of all signal names available in the constants mapping.
 *
 * @param {Record<string, number>} constants
 * @returns {string[]}
 */
export function listSupportedSignals(constants) {
  if (!constants || typeof constants !== 'object') {
    return [];
  }
  return Object.keys(constants);
}

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';
import fs from 'node:fs';
import path from 'node:path';
import {
  isSupportedSignal,
  getSignalNumber,
  getSignalName,
  listSupportedSignals,
} from '../src/index.mjs';

const require = createRequire(import.meta.url);

// 1. Resolve package manifest and verify export map and metadata
const pkgPath = require.resolve('bare-signals/package');
const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));

assert.equal(pkg.name, 'bare-signals', 'Package name must be bare-signals');
assert.equal(pkg.version, '5.0.0', 'Package version must be 5.0.0');
assert.equal(pkg.license, 'Apache-2.0', 'Package license must be Apache-2.0');
assert.equal(pkg.addon, true, 'Package must be marked as addon');
assert.equal(pkg.engines?.bare, '>=1.7.0', 'Package must specify Bare engine requirement');

assert.ok(pkg.exports, 'Package must define exports map');
assert.equal(pkg.exports['.'].types, './index.d.ts', 'Root export must specify index.d.ts types');
assert.equal(pkg.exports['.'].default, './index.js', 'Root export must specify index.js default');

const pkgDir = path.dirname(pkgPath);

// 2. Verify TypeScript type definitions in index.d.ts
const indexDts = fs.readFileSync(path.join(pkgDir, 'index.d.ts'), 'utf8');
assert.ok(indexDts.includes('declare class Signal'), 'index.d.ts must declare Signal class');
assert.ok(indexDts.includes('declare namespace Signal'), 'index.d.ts must declare Signal namespace');
assert.ok(
  indexDts.includes('export const constants: Record<string, number>'),
  'index.d.ts must declare constants as Record<string, number>'
);
assert.ok(indexDts.includes('export = Signal'), 'index.d.ts must export Signal');

// 3. Verify native C binding source in binding.c
const bindingCPath = path.join(pkgDir, 'binding.c');
assert.ok(fs.existsSync(bindingCPath), 'binding.c must exist');
const bindingC = fs.readFileSync(bindingCPath, 'utf8');
assert.ok(
  bindingC.includes('err = js_set_named_property(env, exports, "signals", signals);'),
  'binding.c must export signals property'
);
assert.ok(bindingC.includes('#ifdef SIGHUP'), 'binding.c must handle SIGHUP');
assert.ok(bindingC.includes('#ifdef SIGINT'), 'binding.c must handle SIGINT');
assert.ok(bindingC.includes('#ifdef SIGQUIT'), 'binding.c must handle SIGQUIT');
assert.ok(bindingC.includes('#ifdef SIGKILL'), 'binding.c must handle SIGKILL');
assert.ok(bindingC.includes('#ifdef SIGTERM'), 'binding.c must handle SIGTERM');

// 4. Mock binding to test Signal.constants in offline runtime
const bindingPath = path.join(pkgDir, 'binding.js');
const mockSignals = {
  SIGHUP: 1,
  SIGINT: 2,
  SIGQUIT: 3,
  SIGKILL: 9,
  SIGUSR1: 10,
  SIGUSR2: 12,
  SIGTERM: 15,
};

let nextHandleId = 1;
require.cache[bindingPath] = {
  id: bindingPath,
  filename: bindingPath,
  loaded: true,
  exports: {
    signals: mockSignals,
    init: (ctx, onsignal, onclose) => ({
      id: nextHandleId++,
      ctx,
      onsignal,
      onclose,
    }),
    start: () => {},
    stop: () => {},
    ref: () => {},
    unref: () => {},
    close: (handle) => {
      setImmediate(() => {
        handle.onclose.call(handle.ctx);
      });
    },
  },
};

const Signal = require('bare-signals');
assert.equal(typeof Signal, 'function', 'bare-signals export must be a class constructor');
assert.equal(typeof Signal.constants, 'object', 'Signal.constants must be an object');
assert.deepEqual(Signal.constants, mockSignals, 'Signal.constants must match mock signals map');
assert.equal(Signal.constants.SIGINT, 2, 'Signal.constants.SIGINT must be 2');
assert.equal(Signal.constants.SIGTERM, 15, 'Signal.constants.SIGTERM must be 15');
assert.equal(Signal.constants.SIGKILL, 9, 'Signal.constants.SIGKILL must be 9');

// 5. Test helper functions with constants
assert.equal(isSupportedSignal('SIGINT', Signal.constants), true, 'isSupportedSignal returns true for SIGINT');
assert.equal(isSupportedSignal('SIGUNKNOWN', Signal.constants), false, 'isSupportedSignal returns false for SIGUNKNOWN');
assert.equal(isSupportedSignal(null, Signal.constants), false, 'isSupportedSignal handles null safely');

assert.equal(getSignalNumber('SIGINT', Signal.constants), 2, 'getSignalNumber returns 2 for SIGINT');
assert.equal(getSignalNumber('SIGTERM', Signal.constants), 15, 'getSignalNumber returns 15 for SIGTERM');
assert.throws(
  () => getSignalNumber('SIGINVALID', Signal.constants),
  (err) => err.code === 'UNKNOWN_SIGNAL',
  'getSignalNumber throws UNKNOWN_SIGNAL for invalid signal'
);

assert.equal(getSignalName(2, Signal.constants), 'SIGINT', 'getSignalName returns SIGINT for signum 2');
assert.equal(getSignalName(15, Signal.constants), 'SIGTERM', 'getSignalName returns SIGTERM for signum 15');
assert.equal(getSignalName(999, Signal.constants), null, 'getSignalName returns null for unknown signum');

const supported = listSupportedSignals(Signal.constants);
assert.deepEqual(
  supported,
  ['SIGHUP', 'SIGINT', 'SIGQUIT', 'SIGKILL', 'SIGUSR1', 'SIGUSR2', 'SIGTERM'],
  'listSupportedSignals returns all registered signal names'
);

// 6. Test Signal constructor behavior with constants
const sig = new Signal('SIGINT');
assert.equal(sig._signum, 2, 'Signal constructor resolves SIGINT to signum 2 via constants');

const sigterm = new Signal('SIGTERM');
assert.equal(sigterm._signum, 15, 'Signal constructor resolves SIGTERM to signum 15 via constants');

assert.throws(
  () => new Signal('SIGNOTINCONSTANTS'),
  (err) => err.code === 'UNKNOWN_SIGNAL',
  'Signal constructor throws UNKNOWN_SIGNAL when signal name not in constants'
);

console.log('Contract tests passed successfully.');