ansi-styles 6.2.3: hexToAnsi256

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 ansi-styles.hexToAnsi256 in pkg:npm/ansi-styles@6.2.3
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/ansi-styles@6.2.3
Demonstrate these symbols/APIs:
  - ansi-styles.hexToAnsi256

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:e87ef7562d29e53e9f61607d90a93f131706df6c97b64fb93d16e27d910771d8","contract":["hexToAnsi256 converts standard 6-digit hex color strings to 256-color palette ANSI codes","hexToAnsi256 converts 3-digit shorthand hex strings to equivalent 256-color palette ANSI codes","hexToAnsi256 converts numeric hex values and handles case-insensitive hex strings","hexToForegroundAnsi and hexToBackgroundAnsi generate valid 256-color ANSI escape sequences for foreground and background","applyHexColor formats text with foreground and background 256-color ANSI escape codes and resets styles"],"goal":"verify ansi-styles.hexToAnsi256 in pkg:npm/ansi-styles@6.2.3","kind":"HOW","packages":["pkg:npm/ansi-styles@6.2.3"],"schemaVersion":1,"symbols":["ansi-styles.hexToAnsi256"]},"contractCommand":["node","test/contract.js"],"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/ansi-styles@6.2.3"],"schemaVersion":1,"subject":"pkg:npm/ansi-styles@6.2.3","symbols":["ansi-styles.hexToAnsi256"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-ansi-styles-hex-to-ansi256",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-ansi-styles-hex-to-ansi256",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "ansi-styles": "6.2.3"
      }
    },
    "node_modules/ansi-styles": {
      "version": "6.2.3",
      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.3.tgz",
      "integrity": "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==",
      "license": "MIT",
      "engines": {
        "node": ">=12"
      },
      "funding": {
        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
      }
    }
  }
}

{
  "name": "sample-ansi-styles-hex-to-ansi256",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification for ansi-styles hexToAnsi256",
  "main": "src/index.js",
  "scripts": {
    "test": "node test/contract.js"
  },
  "dependencies": {
    "ansi-styles": "6.2.3"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify ansi-styles.hexToAnsi256 in pkg:npm/ansi-styles@6.2.3",
  "kind": "HOW",
  "packages": [
    "pkg:npm/ansi-styles@6.2.3"
  ],
  "symbols": [
    "ansi-styles.hexToAnsi256"
  ]
}

const ansiStylesModule = require('ansi-styles');

const ansiStyles = ansiStylesModule.default || ansiStylesModule;
const hexToAnsi256 = ansiStyles.hexToAnsi256;

/**
 * Converts a hex color string or number to an ANSI 256 color code (0-255).
 * @param {string | number} hex
 * @returns {number}
 */
function convertHexToAnsi256(hex) {
  if (hex === undefined || hex === null) {
    throw new Error('Hex color must be provided');
  }
  return hexToAnsi256(hex);
}

/**
 * Returns the ANSI escape sequence for setting the foreground color from a hex code.
 * @param {string | number} hex
 * @returns {string}
 */
function hexToForegroundAnsi(hex) {
  const code = convertHexToAnsi256(hex);
  return ansiStyles.color.ansi256(code);
}

/**
 * Returns the ANSI escape sequence for setting the background color from a hex code.
 * @param {string | number} hex
 * @returns {string}
 */
function hexToBackgroundAnsi(hex) {
  const code = convertHexToAnsi256(hex);
  return ansiStyles.bgColor.ansi256(code);
}

/**
 * Applies hex color styling to text.
 * @param {string} text
 * @param {string | number} hex
 * @param {{ isBackground?: boolean, bgHex?: string | number }} [options]
 * @returns {string}
 */
function applyHexColor(text, hex, options = {}) {
  if (typeof text !== 'string') {
    throw new TypeError('Text must be a string');
  }

  if (options.isBackground) {
    const bgOpen = hexToBackgroundAnsi(hex);
    return `${bgOpen}${text}${ansiStyles.bgColor.close}`;
  }

  const fgOpen = hexToForegroundAnsi(hex);
  if (options.bgHex !== undefined) {
    const bgOpen = hexToBackgroundAnsi(options.bgHex);
    return `${fgOpen}${bgOpen}${text}${ansiStyles.bgColor.close}${ansiStyles.color.close}`;
  }

  return `${fgOpen}${text}${ansiStyles.color.close}`;
}

module.exports = {
  ansiStyles,
  hexToAnsi256,
  convertHexToAnsi256,
  hexToForegroundAnsi,
  hexToBackgroundAnsi,
  applyHexColor,
};

const assert = require('node:assert');
const {
  ansiStyles,
  hexToAnsi256,
  convertHexToAnsi256,
  hexToForegroundAnsi,
  hexToBackgroundAnsi,
  applyHexColor,
} = require('../src/index.js');

// 1. hexToAnsi256 converts standard 6-digit hex color strings to 256-color palette ANSI codes
assert.strictEqual(typeof hexToAnsi256, 'function', 'hexToAnsi256 must be a function');
assert.strictEqual(hexToAnsi256('#ff0000'), 196, 'red hex must convert to 196');
assert.strictEqual(hexToAnsi256('ff0000'), 196, 'red hex without prefix must convert to 196');
assert.strictEqual(hexToAnsi256('#00ff00'), 46, 'green hex must convert to 46');
assert.strictEqual(hexToAnsi256('00ff00'), 46, 'green hex without prefix must convert to 46');
assert.strictEqual(hexToAnsi256('#0000ff'), 21, 'blue hex must convert to 21');
assert.strictEqual(hexToAnsi256('0000ff'), 21, 'blue hex without prefix must convert to 21');
assert.strictEqual(hexToAnsi256('#ffffff'), 231, 'white hex must convert to 231');
assert.strictEqual(hexToAnsi256('#000000'), 16, 'black hex must convert to 16');
assert.strictEqual(hexToAnsi256('#ffff00'), 226, 'yellow hex must convert to 226');
assert.strictEqual(hexToAnsi256('#ff00ff'), 201, 'magenta hex must convert to 201');
assert.strictEqual(hexToAnsi256('#00ffff'), 51, 'cyan hex must convert to 51');
assert.strictEqual(hexToAnsi256('#808080'), 244, 'gray hex must convert to 244');
assert.strictEqual(convertHexToAnsi256('#ff0000'), 196);

// 2. hexToAnsi256 converts 3-digit shorthand hex strings to equivalent 256-color palette ANSI codes
assert.strictEqual(hexToAnsi256('#f00'), 196, 'short red hex must convert to 196');
assert.strictEqual(hexToAnsi256('f00'), 196, 'short red hex without prefix must convert to 196');
assert.strictEqual(hexToAnsi256('#0f0'), 46, 'short green hex must convert to 46');
assert.strictEqual(hexToAnsi256('0f0'), 46, 'short green hex without prefix must convert to 46');
assert.strictEqual(hexToAnsi256('#00f'), 21, 'short blue hex must convert to 21');
assert.strictEqual(hexToAnsi256('00f'), 21, 'short blue hex without prefix must convert to 21');
assert.strictEqual(hexToAnsi256('#fff'), 231, 'short white hex must convert to 231');
assert.strictEqual(hexToAnsi256('#000'), 16, 'short black hex must convert to 16');
assert.strictEqual(hexToAnsi256('#f0f'), 201, 'short magenta hex must convert to 201');
assert.strictEqual(hexToAnsi256('#0ff'), 51, 'short cyan hex must convert to 51');

// 3. hexToAnsi256 converts numeric hex values and handles case-insensitive hex strings
assert.strictEqual(hexToAnsi256(0xff0000), 196, 'numeric red hex must convert to 196');
assert.strictEqual(hexToAnsi256(0x112233), 23, 'numeric hex 0x112233 must convert to 23');
assert.strictEqual(hexToAnsi256(0xabcdef), 153, 'numeric hex 0xabcdef must convert to 153');
assert.strictEqual(hexToAnsi256(0xffffff), 231, 'numeric white hex must convert to 231');
assert.strictEqual(hexToAnsi256('#FF0000'), 196, 'uppercase hex must convert correctly');
assert.strictEqual(hexToAnsi256('#F00'), 196, 'uppercase shorthand hex must convert correctly');
assert.strictEqual(hexToAnsi256('#AbCdEf'), hexToAnsi256('#abcdef'), 'mixed case hex must match lowercase hex');
assert.throws(() => convertHexToAnsi256(null), /Hex color must be provided/);
assert.throws(() => convertHexToAnsi256(undefined), /Hex color must be provided/);

// 4. hexToForegroundAnsi and hexToBackgroundAnsi generate valid 256-color ANSI escape sequences for foreground and background
assert.strictEqual(hexToForegroundAnsi('#ff0000'), '\u001B[38;5;196m');
assert.strictEqual(hexToForegroundAnsi('#00ff00'), '\u001B[38;5;46m');
assert.strictEqual(hexToForegroundAnsi('#0000ff'), '\u001B[38;5;21m');
assert.strictEqual(hexToForegroundAnsi('#ffffff'), '\u001B[38;5;231m');

assert.strictEqual(hexToBackgroundAnsi('#ff0000'), '\u001B[48;5;196m');
assert.strictEqual(hexToBackgroundAnsi('#00ff00'), '\u001B[48;5;46m');
assert.strictEqual(hexToBackgroundAnsi('#0000ff'), '\u001B[48;5;21m');
assert.strictEqual(hexToBackgroundAnsi('#000000'), '\u001B[48;5;16m');

// 5. applyHexColor formats text with foreground and background 256-color ANSI escape codes and resets styles
const message = 'CodeSampleX';
assert.strictEqual(applyHexColor(message, '#ff0000'), `\u001B[38;5;196m${message}\u001B[39m`);
assert.strictEqual(applyHexColor(message, '#00ff00'), `\u001B[38;5;46m${message}\u001B[39m`);
assert.strictEqual(applyHexColor(message, '#0000ff', { isBackground: true }), `\u001B[48;5;21m${message}\u001B[49m`);
assert.strictEqual(
  applyHexColor(message, '#ffff00', { bgHex: '#0000ff' }),
  `\u001B[38;5;226m\u001B[48;5;21m${message}\u001B[49m\u001B[39m`
);

assert.throws(() => applyHexColor(12345, '#ff0000'), TypeError);

console.log('All contract assertions passed successfully.');