builder-util-runtime 9.7.0: UUID

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 builder-util-runtime.UUID in pkg:npm/builder-util-runtime@9.7.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/builder-util-runtime@9.7.0
Demonstrate these symbols/APIs:
  - builder-util-runtime.UUID

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:533d060b77dc669da254a1a91a1e96573d6eb6b56084132627bb0433136d9da6","contract":["assert UUID.v5 generates a deterministic RFC4122 v5 UUID string given a name and namespace Buffer","assert UUID constructor instantiates from a valid UUID string and 16-byte Buffer with correct toString and inspect representation","assert UUID.check validates string and Buffer UUIDs, identifies nil UUID, and rejects malformed inputs","assert UUID constructor throws Error on invalid UUID string or invalid Buffer","assert UUID.parse converts formatted UUID string to 16-byte Buffer matching UUID.OID"],"goal":"verify builder-util-runtime.UUID in pkg:npm/builder-util-runtime@9.7.0","kind":"HOW","packages":["pkg:npm/builder-util-runtime@9.7.0"],"schemaVersion":1,"symbols":["builder-util-runtime.UUID"]},"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/builder-util-runtime@9.7.0"],"schemaVersion":1,"subject":"pkg:npm/builder-util-runtime@9.7.0","symbols":["builder-util-runtime.UUID"],"verifierAdapter":"node-typescript@1"}

import { UUID } from 'builder-util-runtime';

/**
 * Generates a deterministic RFC4122 v5 UUID string for a given name within a namespace.
 * @param {string | Buffer} name
 * @param {Buffer} [namespace=UUID.OID]
 * @returns {string}
 */
export function generateV5UUID(name, namespace = UUID.OID) {
  return UUID.v5(name, namespace);
}

/**
 * Parses a string or Buffer into a UUID object instance.
 * @param {string | Buffer} input
 * @returns {UUID}
 */
export function parseUUID(input) {
  return new UUID(input);
}

/**
 * Validates a UUID string or Buffer.
 * @param {unknown} value
 * @returns {false | { version: number | undefined; variant: string; format: string }}
 */
export function checkUUID(value) {
  return UUID.check(value);
}

/**
 * Converts a 36-character formatted UUID string into a 16-byte Buffer.
 * @param {string} uuidString
 * @returns {Buffer}
 */
export function uuidToBuffer(uuidString) {
  return UUID.parse(uuidString);
}

export { UUID };

{
  "name": "builder-util-runtime-uuid-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "builder-util-runtime-uuid-sample",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "builder-util-runtime": "9.7.0"
      }
    },
    "node_modules/builder-util-runtime": {
      "version": "9.7.0",
      "resolved": "https://registry.npmjs.org/builder-util-runtime/-/builder-util-runtime-9.7.0.tgz",
      "integrity": "sha512-g/kR520giAFYkSXTzcmF3kqQq7wi8F6N6SzeDgZrqTBN+VHdmgWOyTdD1yD7AATDId/yXLvuP34CxW46/BwCdw==",
      "license": "MIT",
      "dependencies": {
        "debug": "^4.3.4",
        "sax": "^1.2.4"
      },
      "engines": {
        "node": ">=12.0.0"
      }
    },
    "node_modules/debug": {
      "version": "4.4.3",
      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
      "license": "MIT",
      "dependencies": {
        "ms": "^2.1.3"
      },
      "engines": {
        "node": ">=6.0"
      },
      "peerDependenciesMeta": {
        "supports-color": {
          "optional": true
        }
      }
    },
    "node_modules/ms": {
      "version": "2.1.3",
      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
      "license": "MIT"
    },
    "node_modules/sax": {
      "version": "1.6.1",
      "resolved": "https://registry.npmjs.org/sax/-/sax-1.6.1.tgz",
      "integrity": "sha512-42tBVwLWnaQvW5zc4HbZrTuWccECCZfBi92FDuwtqxasH+JbPB3/FOKb1m222K42R4WxuxzzMsTswfzgtSu64Q==",
      "license": "BlueOak-1.0.0",
      "engines": {
        "node": ">=11.0.0"
      }
    }
  }
}

{
  "name": "builder-util-runtime-uuid-sample",
  "version": "1.0.0",
  "description": "Demonstrate builder-util-runtime.UUID usage and behavior",
  "main": "index.mjs",
  "type": "module",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "builder-util-runtime": "9.7.0"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify builder-util-runtime.UUID in pkg:npm/builder-util-runtime@9.7.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/builder-util-runtime@9.7.0"
  ],
  "symbols": [
    "builder-util-runtime.UUID"
  ]
}

import assert from 'node:assert/strict';
import { UUID } from 'builder-util-runtime';
import { generateV5UUID, parseUUID, checkUUID, uuidToBuffer } from '../index.mjs';

// 1. assert UUID.v5 generates a deterministic RFC4122 v5 UUID string given a name and namespace Buffer
{
  const name = 'sample-app';
  const v5String = generateV5UUID(name, UUID.OID);
  assert.equal(typeof v5String, 'string', 'UUID.v5 must return a string');
  assert.equal(v5String, generateV5UUID(name, UUID.OID), 'UUID.v5 must produce identical string for identical inputs');
  assert.equal(v5String, UUID.v5(name, UUID.OID), 'Helper generateV5UUID must match UUID.v5 output');

  const checkResult = UUID.check(v5String);
  assert.ok(checkResult, 'Generated v5 UUID string must pass UUID.check');
  assert.equal(checkResult.version, 5, 'UUID version must be 5');
  assert.equal(checkResult.variant, 'rfc4122', 'UUID variant must be rfc4122');
  assert.equal(checkResult.format, 'ascii', 'UUID format must be ascii');
}

// 2. assert UUID constructor instantiates from a valid UUID string and 16-byte Buffer with correct toString and inspect representation
{
  const validUuidStr = '6ba7b812-9dad-11d1-80b4-00c04fd430c8';
  const uuidFromStr = parseUUID(validUuidStr);
  assert.ok(uuidFromStr instanceof UUID, 'Must be an instance of UUID');
  assert.equal(uuidFromStr.toString(), validUuidStr, 'toString must return original uuid string');
  assert.equal(uuidFromStr.inspect(), `UUID v1 ${validUuidStr}`, 'inspect must include version and string representation');

  const buf = UUID.parse(validUuidStr);
  const uuidFromBuf = parseUUID(buf);
  assert.ok(uuidFromBuf instanceof UUID, 'Must instantiate UUID from Buffer');
  assert.equal(uuidFromBuf.toString(), validUuidStr, 'toString from Buffer-created UUID must return formatted string');
  assert.equal(uuidFromBuf.inspect(), `UUID v1 ${validUuidStr}`);
}

// 3. assert UUID.check validates string and Buffer UUIDs, identifies nil UUID, and rejects malformed inputs
{
  const validStr = '01234567-89ab-4def-8123-456789abcdef';
  const checkedStr = checkUUID(validStr);
  assert.ok(checkedStr);
  assert.equal(checkedStr.version, 4);
  assert.equal(checkedStr.variant, 'rfc4122');
  assert.equal(checkedStr.format, 'ascii');

  const validBuf = UUID.parse(validStr);
  const checkedBuf = checkUUID(validBuf);
  assert.ok(checkedBuf);
  assert.equal(checkedBuf.version, 4);
  assert.equal(checkedBuf.variant, 'rfc4122');
  assert.equal(checkedBuf.format, 'binary');

  // Nil UUID
  const nilStr = '00000000-0000-0000-0000-000000000000';
  assert.deepEqual(checkUUID(nilStr), { version: undefined, variant: 'nil', format: 'ascii' });
  assert.deepEqual(checkUUID(Buffer.alloc(16)), { version: undefined, variant: 'nil', format: 'binary' });

  // Invalid formats return false
  assert.equal(checkUUID('not-a-valid-uuid'), false);
  assert.equal(checkUUID(Buffer.alloc(10)), false);
}

// 4. assert UUID constructor throws Error on invalid UUID string or invalid Buffer
{
  assert.throws(
    () => parseUUID('invalid-uuid-string'),
    (err) => err instanceof Error && err.message === 'not a UUID',
    'Must throw "not a UUID" for malformed string'
  );

  assert.throws(
    () => parseUUID(Buffer.alloc(8)),
    (err) => err instanceof Error && err.message === 'not a UUID',
    'Must throw "not a UUID" for Buffer shorter than 16 bytes'
  );
}

// 5. assert UUID.parse converts formatted UUID string to 16-byte Buffer matching UUID.OID
{
  const oidStr = '6ba7b812-9dad-11d1-80b4-00c04fd430c8';
  const buf = uuidToBuffer(oidStr);
  assert.ok(Buffer.isBuffer(buf), 'uuidToBuffer must return a Buffer');
  assert.equal(buf.length, 16, 'Buffer length must be 16 bytes');
  assert.ok(buf.equals(UUID.OID), 'Parsed OID string must equal UUID.OID Buffer');
}

console.log('All contract tests passed.');