chalk 6.0.0: Chalk

# Chalk.Chalk Instance & Lifecycle Contract Notes

## Search Results
`search_known_solution` for `chalk.Chalk` in `pkg:npm/chalk@6.0.0` returned `NO_SAFE_MATCH`.

## What a Model Would Have Written Instead
1. **Export shape error**: Accessing `new chalk.Chalk()` or `new chalk.Instance()` off the default export `chalk`.
2. **`visible` modifier behavior**: Assuming `chalk.visible('text')` returns plain string `'text'` when `level` is `0` (like other styles do when disabled), whereas `visible` specifically returns an empty string `''` when `level <= 0`.
3. **Multiline escape sequences**: Assuming ANSI styling codes wrap the whole string without handling `\n` or `\r\n`, whereas Chalk explicitly closes the active style before the newline and re-opens after the newline to prevent terminal escape bleed.
4. **Invalid level validation**: Expecting non-integer or out-of-range level values (like `-1`, `4`, `'2'`, `1.5`) to coerce silently, whereas Chalk strictly validates levels with `assertValidLevel` and throws an Error.

## How the Wrong Version Fails
1. **Loudly at runtime**: `new chalk.Chalk()` throws `TypeError: chalk.Chalk is not a constructor` because in Chalk v5+, `Chalk` is exclusively a named ESM export.
2. **Loudly in test assertions**: Asserting `c0.visible('msg') === 'msg'` fails with `AssertionError: '' === 'msg'`.
3. **Loudly in multiline regex / assertions**: Asserting `'\u001b[31mfoo\nbar\u001b[39m'` fails because Chalk emits `'\u001b[31mfoo\u001b[39m\n\u001b[31mbar\u001b[39m'`.
4. **Loudly at construction/mutation**: Setting `level: 4` or `level: -1` throws `Error: The `level` should be an integer from 0 to 3`.

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 chalk.Chalk in pkg:npm/chalk@6.0.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/chalk@6.0.0
Demonstrate these symbols/APIs:
  - chalk.Chalk

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:7fd202c05e87e6d13a8262412c737e1b5decfe1da832fe66129941be2a5c905a","contract":["import Chalk constructor as a named export rather than accessing undefined chalk.Chalk on default export","construct Chalk instance with valid level 0, 1, 2, or 3","reject invalid level values in Chalk constructor and instance level setter with descriptive error","dynamically update ANSI rendering behavior when mutating instance level","invoke Chalk instance as a callable function to format single or multiple space-delimited arguments","chain multiple style modifiers and background/foreground colors with properly nested opening and reverse closing ANSI sequences","return empty string for visible modifier when level is 0 and render styled text when level is greater than 0","close and reopen ANSI color escape codes across LF and CRLF line breaks to prevent style bleeding","reopen enclosing parent ANSI styles when nested child styling sequences close","verify chalkStderr is exported as an independent Chalk instance with a numeric color support level"],"goal":"verify chalk.Chalk in pkg:npm/chalk@6.0.0","kind":"HOW","packages":["pkg:npm/chalk@6.0.0"],"schemaVersion":1,"symbols":["chalk.Chalk"]},"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/chalk@6.0.0"],"schemaVersion":1,"subject":"pkg:npm/chalk@6.0.0","symbols":["chalk.Chalk"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-1431592547",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "dependencies": {
        "chalk": "^6.0.0"
      }
    },
    "node_modules/chalk": {
      "version": "6.0.0",
      "resolved": "https://registry.npmjs.org/chalk/-/chalk-6.0.0.tgz",
      "integrity": "sha512-2uNTXIuTTxk7ciZgAU1BQcgnchcG0xXnrs6jzkQfj9SsRa9M2s5zE8WT96hS6KmG4MzWHSrvH43DF1m4XRkrFg==",
      "license": "MIT",
      "engines": {
        "node": ">=22"
      },
      "funding": {
        "url": "https://github.com/chalk/chalk?sponsor=1"
      }
    }
  }
}

{
  "name": "sample-1431592547",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "chalk": "6.0.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify chalk.Chalk in pkg:npm/chalk@6.0.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/chalk@6.0.0"
  ],
  "symbols": [
    "chalk.Chalk"
  ]
}

import chalk, { Chalk, chalkStderr } from 'chalk';

/**
 * Creates a new Chalk instance with the specified options.
 *
 * @param {import('chalk').Options} [options]
 * @returns {import('chalk').ChalkInstance}
 */
export function createCustomChalk(options) {
  return new Chalk(options);
}

/**
 * Inspects default export and named exports to verify export shape.
 */
export function inspectChalkExports() {
  return {
    chalkConstructorType: typeof Chalk,
    defaultExportHasChalk: typeof chalk.Chalk !== 'undefined',
    defaultExportHasInstance: typeof chalk.Instance !== 'undefined',
    hasChalkStderr: typeof chalkStderr === 'function',
    stderrLevelType: typeof chalkStderr?.level,
  };
}

/**
 * Formats a message with multiple space-separated arguments using a Chalk instance.
 *
 * @param {import('chalk').ChalkInstance} customChalk
 * @param {...unknown} args
 * @returns {string}
 */
export function formatWithInstance(customChalk, ...args) {
  return customChalk(...args);
}

/**
 * Formats text using multiple chained modifiers and styles.
 *
 * @param {import('chalk').ChalkInstance} customChalk
 * @param {string} text
 * @returns {string}
 */
export function formatChained(customChalk, text) {
  return customChalk.bold.red.bgWhite(text);
}

/**
 * Demonstrates the visible modifier behavior.
 * When level is 0, visible() returns empty string; when level > 0, returns the text.
 *
 * @param {import('chalk').ChalkInstance} customChalk
 * @param {string} text
 * @returns {{ plainVisible: string, styledVisible: string }}
 */
export function formatVisible(customChalk, text) {
  return {
    plainVisible: customChalk.visible(text),
    styledVisible: customChalk.red.visible(text),
  };
}

/**
 * Formats multiline text with newlines (LF or CRLF).
 * Chalk automatically closes the style before \n and re-opens after \n.
 *
 * @param {import('chalk').ChalkInstance} customChalk
 * @param {string} text
 * @returns {string}
 */
export function formatMultiline(customChalk, text) {
  return customChalk.red(text);
}

/**
 * Formats nested colored text.
 * Chalk re-opens enclosing style after the inner style closing escape code.
 *
 * @param {import('chalk').ChalkInstance} customChalk
 * @param {string} outerPrefix
 * @param {string} innerText
 * @param {string} outerSuffix
 * @returns {string}
 */
export function formatNested(customChalk, outerPrefix, innerText, outerSuffix) {
  return customChalk.red(`${outerPrefix} ${customChalk.blue(innerText)} ${outerSuffix}`);
}

import { strict as assert } from 'node:assert';
import {
  createCustomChalk,
  inspectChalkExports,
  formatWithInstance,
  formatChained,
  formatVisible,
  formatMultiline,
  formatNested,
} from '../src/index.mjs';

// 1. Chalk constructor is exported as named export; default export does not attach Chalk or Instance
const exportInfo = inspectChalkExports();
assert.equal(exportInfo.chalkConstructorType, 'function', 'Chalk must be exported as constructor function');
assert.equal(exportInfo.defaultExportHasChalk, false, 'chalk.Chalk is undefined on default export in v5+');
assert.equal(exportInfo.defaultExportHasInstance, false, 'chalk.Instance is undefined on default export in v5+');
assert.equal(exportInfo.hasChalkStderr, true, 'chalkStderr is exported as an independent Chalk instance');
assert.equal(exportInfo.stderrLevelType, 'number', 'chalkStderr has a numeric color support level');

// 2. Construct Chalk instance with valid levels (0, 1, 2, 3)
const c0 = createCustomChalk({ level: 0 });
const c1 = createCustomChalk({ level: 1 });
const c2 = createCustomChalk({ level: 2 });
const c3 = createCustomChalk({ level: 3 });

assert.equal(c0.level, 0, 'Level 0 instance configured');
assert.equal(c1.level, 1, 'Level 1 instance configured');
assert.equal(c2.level, 2, 'Level 2 instance configured');
assert.equal(c3.level, 3, 'Level 3 instance configured');

// 3. Reject invalid levels in constructor and setter
const expectedLevelError = { message: 'The `level` should be an integer from 0 to 3' };
assert.throws(() => createCustomChalk({ level: -1 }), expectedLevelError, 'Negative level rejected');
assert.throws(() => createCustomChalk({ level: 4 }), expectedLevelError, 'Level > 3 rejected');
assert.throws(() => createCustomChalk({ level: '2' }), expectedLevelError, 'String level rejected');
assert.throws(() => createCustomChalk({ level: 1.5 }), expectedLevelError, 'Float level rejected');

const dynamicInstance = createCustomChalk({ level: 3 });
assert.throws(() => { dynamicInstance.level = 5; }, expectedLevelError, 'Setter rejects level > 3');
assert.throws(() => { dynamicInstance.level = -1; }, expectedLevelError, 'Setter rejects negative level');

// 4. Mutating instance level changes styling behavior dynamically
assert.equal(dynamicInstance.red('msg'), '\u001b[31mmsg\u001b[39m', 'Level 3 renders ANSI red');
dynamicInstance.level = 0;
assert.equal(dynamicInstance.red('msg'), 'msg', 'Level 0 returns unstyled string');

// 5. Invoke Chalk instance as callable function with single and multiple arguments
assert.equal(formatWithInstance(c3, 'single'), 'single', 'Single argument returned as string');
assert.equal(formatWithInstance(c3, 'hello', 'world', 42), 'hello world 42', 'Multiple arguments joined with spaces');
assert.equal(formatWithInstance(c3), '', 'Empty invocation returns empty string');

// 6. Chain multiple modifiers and background/foreground colors with matching opening and reverse closing codes
const chainedOutput = formatChained(c3, 'alert');
assert.equal(
  chainedOutput,
  '\u001b[1m\u001b[31m\u001b[47malert\u001b[49m\u001b[39m\u001b[22m',
  'bold (1/22), red (31/39), bgWhite (47/49) chained with reverse closing tags'
);

// 7. Visible modifier returns empty string when level is 0, and renders content when level > 0
const visibleAtZero = formatVisible(c0, 'status');
assert.equal(visibleAtZero.plainVisible, '', 'visible() returns empty string when level is 0');
assert.equal(visibleAtZero.styledVisible, '', 'red.visible() returns empty string when level is 0');

const visibleAtThree = formatVisible(c3, 'status');
assert.equal(visibleAtThree.plainVisible, 'status', 'visible() returns content when level > 0');
assert.equal(visibleAtThree.styledVisible, '\u001b[31mstatus\u001b[39m', 'red.visible() styles content when level > 0');

// 8. Close and reopen ANSI styles across LF and CRLF line breaks
const multilineLf = formatMultiline(c3, 'first\nsecond');
assert.equal(
  multilineLf,
  '\u001b[31mfirst\u001b[39m\n\u001b[31msecond\u001b[39m',
  'Style closes before LF and re-opens after LF'
);

const multilineCrlf = formatMultiline(c3, 'first\r\nsecond');
assert.equal(
  multilineCrlf,
  '\u001b[31mfirst\u001b[39m\r\n\u001b[31msecond\u001b[39m',
  'Style closes before CRLF and re-opens after CRLF'
);

// 9. Re-open enclosing parent styles when nested child styling closes
const nestedOutput = formatNested(c3, 'Outer', 'Inner', 'Trailing');
assert.equal(
  nestedOutput,
  '\u001b[31mOuter \u001b[34mInner\u001b[39m\u001b[31m Trailing\u001b[39m',
  'Enclosing red style (31m) re-opened after inner blue style close (39m)'
);

console.log('CONTRACT PASS: All chalk.Chalk instance contracts verified successfully.');