bare-signals 5.0.0: UNKNOWN_SIGNAL

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.UNKNOWN_SIGNAL 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.UNKNOWN_SIGNAL

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:7587f043da0abd92737f4982bd5d1dddd3d58b2447b174f3fd31cd80d1cbf401","contract":["package manifest exports Signal class and SignalError submodule in bare-signals@5.0.0","TypeScript definitions in index.d.ts declare SignalError extending Error with code property","SignalError.UNKNOWN_SIGNAL factory instantiates SignalError with code UNKNOWN_SIGNAL and formatted message","SignalError instances inherit from Error and capture runtime stack traces","SignalError is exported from bare-signals/errors submodule and exposed as Signal.errors","Signal constructor throws SignalError with code UNKNOWN_SIGNAL when passed an unrecognised signal name","Signal constructor does not initialize native bindings when an unknown signal string is rejected","helper resolveSignalNumber resolves known signal names and throws UNKNOWN_SIGNAL for invalid signals","helper safeCreateSignal catches UNKNOWN_SIGNAL and returns structured failure without throwing"],"goal":"verify bare-signals.UNKNOWN_SIGNAL in pkg:npm/bare-signals@5.0.0","kind":"HOW","packages":["pkg:npm/bare-signals@5.0.0"],"schemaVersion":1,"symbols":["bare-signals.UNKNOWN_SIGNAL"]},"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.UNKNOWN_SIGNAL"],"verifierAdapter":"node-typescript@1"}

{
  "name": "bare-signals-unknown-signal-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "bare-signals-unknown-signal-sample",
      "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": "bare-signals-unknown-signal-sample",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "bare-signals": "5.0.0"
  }
}

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

import { createRequire } from 'node:module';

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

/**
 * Checks whether an error is a bare-signals UNKNOWN_SIGNAL error.
 * @param {unknown} err
 * @returns {boolean}
 */
export function isUnknownSignalError(err) {
  return (
    err !== null &&
    typeof err === 'object' &&
    err.name === 'SignalError' &&
    err.code === 'UNKNOWN_SIGNAL'
  );
}

/**
 * Creates a SignalError with UNKNOWN_SIGNAL code.
 * @param {string} signalName
 * @returns {Error}
 */
export function createUnknownSignalError(signalName) {
  const SignalError = require('bare-signals/errors');
  return SignalError.UNKNOWN_SIGNAL(`Unknown signal '${signalName}'`);
}

/**
 * Resolves a signal number from a signal name or returns number as-is.
 * If the signal name is unrecognized in the constants map, throws SignalError.UNKNOWN_SIGNAL.
 *
 * @param {string | number} signum
 * @param {Record<string, number>} constants
 * @returns {number}
 */
export function resolveSignalNumber(signum, constants) {
  if (typeof signum === 'number') {
    return signum;
  }
  if (typeof signum === 'string') {
    if (!constants || !(signum in constants)) {
      const SignalError = require('bare-signals/errors');
      throw SignalError.UNKNOWN_SIGNAL(`Unknown signal '${signum}'`);
    }
    return constants[signum];
  }
  const SignalError = require('bare-signals/errors');
  throw SignalError.UNKNOWN_SIGNAL(`Invalid signal type '${typeof signum}'`);
}

/**
 * Attempts to instantiate a Signal instance using the provided Signal constructor.
 * Catches any UNKNOWN_SIGNAL error and returns a structured outcome object.
 *
 * @param {Function} SignalConstructor
 * @param {string | number} signum
 * @returns {{ ok: true, signal: any } | { ok: false, error: Error, isUnknownSignal: boolean }}
 */
export function safeCreateSignal(SignalConstructor, signum) {
  try {
    const signal = new SignalConstructor(signum);
    return { ok: true, signal };
  } catch (err) {
    return {
      ok: false,
      error: err,
      isUnknownSignal: isUnknownSignalError(err),
    };
  }
}

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';
import fs from 'node:fs';
import path from 'node:path';
import {
  isUnknownSignalError,
  createUnknownSignalError,
  resolveSignalNumber,
  safeCreateSignal,
} from '../src/index.mjs';

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

// 1. Resolve package manifest and verify export map for errors submodule
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.ok(pkg.exports, 'Package must define exports map');
assert.equal(pkg.exports['./errors'], './lib/errors.js', 'Errors export must specify lib/errors.js');

const pkgDir = path.dirname(pkgPath);

// 2. Verify TypeScript type definitions for SignalError in index.d.ts
const indexDts = fs.readFileSync(path.join(pkgDir, 'index.d.ts'), 'utf8');
assert.ok(
  indexDts.includes('declare class SignalError extends Error'),
  'index.d.ts must declare SignalError extending Error'
);
assert.ok(
  indexDts.includes('readonly code: string'),
  'index.d.ts must declare readonly code property on SignalError'
);
assert.ok(
  indexDts.includes('export { SignalEmitter as Emitter, SignalError as errors }'),
  'index.d.ts must export SignalError as errors'
);

// 3. Verify SignalError class directly via bare-signals/errors submodule
const SignalError = require('bare-signals/errors');

assert.equal(typeof SignalError, 'function', 'SignalError must be a class constructor');
assert.equal(typeof SignalError.UNKNOWN_SIGNAL, 'function', 'UNKNOWN_SIGNAL factory must exist');
assert.equal(typeof SignalError.SIGNAL_CLOSED, 'function', 'SIGNAL_CLOSED factory must exist');

// Contract: SignalError.UNKNOWN_SIGNAL factory instantiates SignalError with code UNKNOWN_SIGNAL and formatted message
const errCustom = SignalError.UNKNOWN_SIGNAL("Unrecognised signal 'SIGDUMMY'");
assert.equal(errCustom.name, 'SignalError', 'Error name property must be SignalError');
assert.equal(errCustom.code, 'UNKNOWN_SIGNAL', 'Error code property must be UNKNOWN_SIGNAL');
assert.equal(errCustom.message, "UNKNOWN_SIGNAL: Unrecognised signal 'SIGDUMMY'", 'Error message formatting');

// Contract: SignalError instances inherit from Error and capture runtime stack traces
assert.ok(errCustom instanceof Error, 'SignalError instance must be an instance of Error');
assert.ok(errCustom instanceof SignalError, 'SignalError instance must be an instance of SignalError');
assert.ok(typeof errCustom.stack === 'string' && errCustom.stack.length > 0, 'SignalError must capture stack trace');

// 4. Setup mock binding to test Signal constructor integration offline
const bindingPath = path.join(pkgDir, 'binding.js');
const mockSignals = {
  SIGHUP: 1,
  SIGINT: 2,
  SIGQUIT: 3,
  SIGTERM: 15,
  SIGUSR1: 10,
  SIGUSR2: 12,
};

let initCallCount = 0;
const bindingCalls = [];

require.cache[bindingPath] = {
  id: bindingPath,
  filename: bindingPath,
  loaded: true,
  exports: {
    signals: mockSignals,
    init: (ctx, onsignal, onclose) => {
      initCallCount++;
      const handle = { ctx, onsignal, onclose };
      bindingCalls.push({ op: 'init' });
      return handle;
    },
    start: () => {},
    stop: () => {},
    ref: () => {},
    unref: () => {},
    close: () => {},
  },
};

const Signal = require('bare-signals');

// Contract: SignalError is exported from bare-signals/errors submodule and exposed as Signal.errors
assert.equal(Signal.errors, SignalError, 'Signal.errors must match SignalError class');
assert.deepEqual(Signal.constants, mockSignals, 'Signal.constants must match mock signals');

// Verify valid signal instantiates properly and initializes native binding
const validSignal = new Signal('SIGINT');
assert.equal(validSignal._signum, 2, 'Valid signal name resolves to numeric signum');
assert.equal(initCallCount, 1, 'Valid signal initialization calls binding.init exactly once');

// Contract: Signal constructor throws SignalError with code UNKNOWN_SIGNAL when passed an unrecognised signal name
assert.throws(
  () => new Signal('SIGNONEXISTENT'),
  (err) => {
    return (
      err instanceof SignalError &&
      err.code === 'UNKNOWN_SIGNAL' &&
      err.message === "UNKNOWN_SIGNAL: Unknown signal 'SIGNONEXISTENT'"
    );
  },
  'Constructing Signal with unknown signal name must throw UNKNOWN_SIGNAL'
);

assert.throws(
  () => new Signal('SIGINVALID_TEST'),
  (err) => {
    return (
      err.name === 'SignalError' &&
      err.code === 'UNKNOWN_SIGNAL' &&
      err.message.includes('SIGINVALID_TEST')
    );
  },
  'Constructing Signal with another unknown signal name must throw UNKNOWN_SIGNAL'
);

// Contract: Signal constructor does not initialize native bindings when an unknown signal string is rejected
assert.equal(
  initCallCount,
  1,
  'Rejected unknown signals must never invoke native binding.init'
);

// 5. Verify helper functions from src/index.mjs
// Contract: helper isUnknownSignalError correctly identifies UNKNOWN_SIGNAL errors
assert.equal(isUnknownSignalError(errCustom), true, 'Identifies UNKNOWN_SIGNAL error instance');
assert.equal(isUnknownSignalError(new Error('generic error')), false, 'Rejects generic error');
assert.equal(isUnknownSignalError(null), false, 'Rejects null');
assert.equal(isUnknownSignalError(SignalError.SIGNAL_CLOSED('closed')), false, 'Rejects SIGNAL_CLOSED');

const createdErr = createUnknownSignalError('SIGCUSTOM');
assert.equal(isUnknownSignalError(createdErr), true);
assert.equal(createdErr.code, 'UNKNOWN_SIGNAL');

// Contract: helper resolveSignalNumber resolves known signal names and throws UNKNOWN_SIGNAL for invalid signals
assert.equal(resolveSignalNumber('SIGTERM', mockSignals), 15, 'Resolves SIGTERM to 15');
assert.equal(resolveSignalNumber(9, mockSignals), 9, 'Returns numeric signal as-is');
assert.throws(
  () => resolveSignalNumber('NOT_A_SIGNAL', mockSignals),
  (err) => isUnknownSignalError(err) && err.message.includes('NOT_A_SIGNAL'),
  'Throws UNKNOWN_SIGNAL for unknown signal name in resolveSignalNumber'
);

// Contract: helper safeCreateSignal catches UNKNOWN_SIGNAL and returns structured failure without throwing
const safeSuccess = safeCreateSignal(Signal, 'SIGTERM');
assert.equal(safeSuccess.ok, true, 'safeCreateSignal succeeds for known signal');
assert.equal(safeSuccess.signal._signum, 15, 'safeCreateSignal instantiates correct signal');

const safeFailure = safeCreateSignal(Signal, 'SIGBOGUS');
assert.equal(safeFailure.ok, false, 'safeCreateSignal returns ok=false for unknown signal');
assert.equal(safeFailure.isUnknownSignal, true, 'safeCreateSignal marks isUnknownSignal=true');
assert.equal(safeFailure.error.code, 'UNKNOWN_SIGNAL', 'safeCreateSignal captures error code');

console.log('All bare-signals.UNKNOWN_SIGNAL contract assertions passed successfully.');