@babel/code-frame 8.0.0: codeFrameColumns

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 @babel/code-frame.codeFrameColumns in pkg:npm/%40babel/code-frame@8.0.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40babel/code-frame@8.0.0
Demonstrate these symbols/APIs:
  - @babel/code-frame.codeFrameColumns
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - runtime: node@22.23.2

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:4a0dd41bb8c7d39b192f4a627e163031519bb379c7159e0c9cdd2bdfcb7d595f","constraints":{"executionContext":"node"},"contract":["codeFrameColumns exports a function that formats code frames pointing to source locations","codeFrameColumns highlights a single location with gutter line numbers, active line indicator, and caret marker","codeFrameColumns highlights a column range on a single line with multiple underline markers","codeFrameColumns highlights a multi-line range across start and end locations","codeFrameColumns attaches a custom error message to the highlighted marker line","codeFrameColumns restricts surrounding visible context using linesAbove and linesBelow options","codeFrameColumns offsets displayed line numbers using startLine option","highlight exports a function that tokenizes and formats JavaScript syntax"],"goal":"verify @babel/code-frame.codeFrameColumns in pkg:npm/%40babel/code-frame@8.0.0","kind":"HOW","packages":["pkg:npm/%40babel/code-frame@8.0.0"],"schemaVersion":1,"symbols":["@babel/code-frame.codeFrameColumns"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40babel/code-frame@8.0.0"],"schemaVersion":1,"subject":"pkg:npm/%40babel/code-frame@8.0.0","symbols":["@babel/code-frame.codeFrameColumns"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-babel-code-frame",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-babel-code-frame",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@babel/code-frame": "8.0.0"
      }
    },
    "node_modules/@babel/code-frame": {
      "version": "8.0.0",
      "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-8.0.0.tgz",
      "integrity": "sha512-dYYg153EyN2Ekbqw2zAsbd6/JR+9N2SEoC7YV2GyyqMM7x9bLDTjBD6XBhSMLH0wtIVyJj03jWNriQhaN+eoCw==",
      "license": "MIT",
      "dependencies": {
        "@babel/helper-validator-identifier": "^8.0.0",
        "js-tokens": "^10.0.0"
      },
      "engines": {
        "node": "^22.18.0 || >=24.11.0"
      }
    },
    "node_modules/@babel/helper-validator-identifier": {
      "version": "8.0.4",
      "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-8.0.4.tgz",
      "integrity": "sha512-4wFaiLd0bVo4cIoTXI3zKI038NIWE/cr3jvBjejOVYVxV/m8Ltav1USiGzG1fmS5J2RhgEOgXNNK46cRPnRsrg==",
      "license": "MIT",
      "engines": {
        "node": "^22.18.0 || >=24.11.0"
      }
    },
    "node_modules/js-tokens": {
      "version": "10.0.0",
      "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-10.0.0.tgz",
      "integrity": "sha512-lM/UBzQmfJRo9ABXbPWemivdCW8V2G8FHaHdypQaIy523snUjog0W71ayWXTjiR+ixeMyVHN2XcpnTd/liPg/Q==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-babel-code-frame",
  "version": "1.0.0",
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "@babel/code-frame": "8.0.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify @babel/code-frame.codeFrameColumns in pkg:npm/%40babel/code-frame@8.0.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40babel/code-frame@8.0.0"
  ],
  "symbols": [
    "@babel/code-frame.codeFrameColumns"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "runtime": "node@22.23.2"
  }
}

import assert from 'node:assert/strict';
import { codeFrameColumns, highlight } from '@babel/code-frame';

// 1. codeFrameColumns exports a function that formats code frames pointing to source locations
assert.equal(typeof codeFrameColumns, 'function', 'codeFrameColumns must be a function');

// 2. codeFrameColumns highlights a single location with gutter line numbers, active line indicator, and caret marker
{
  const rawLines = [
    'function greet(name) {',
    '  console.log("Hello " + name);',
    '}'
  ].join('\n');

  const loc = {
    start: { line: 2, column: 3 }
  };
  const result = codeFrameColumns(rawLines, loc);

  assert.equal(typeof result, 'string', 'result must be a string');
  assert.ok(result.includes('1 | function greet(name) {'), 'must include line 1');
  assert.ok(result.includes('> 2 |   console.log("Hello " + name);'), 'must include active marker > on line 2');
  assert.ok(result.includes('3 | }'), 'must include line 3');
  assert.ok(result.includes('^'), 'must include caret marker ^');
}

// 3. codeFrameColumns highlights a column range on a single line with multiple underline markers
{
  const rawLines = 'const total = calculateSum(a, b);';
  const loc = {
    start: { line: 1, column: 15 },
    end: { line: 1, column: 27 }
  };
  const result = codeFrameColumns(rawLines, loc);

  assert.ok(result.includes('> 1 | const total = calculateSum(a, b);'), 'must point to line 1');
  assert.ok(result.includes('^^^^^^^^^^^^'), 'must underline entire column range');
}

// 4. codeFrameColumns highlights a multi-line range across start and end locations
{
  const rawLines = [
    'const config = {',
    '  debug: true,',
    '  timeout: 5000',
    '};'
  ].join('\n');

  const loc = {
    start: { line: 2, column: 3 },
    end: { line: 3, column: 16 }
  };
  const result = codeFrameColumns(rawLines, loc);

  assert.ok(result.includes('> 2 |   debug: true,'), 'line 2 must be marked as active');
  assert.ok(result.includes('> 3 |   timeout: 5000'), 'line 3 must be marked as active');
  assert.ok(result.includes('1 | const config = {'), 'line 1 must be present in context');
  assert.ok(result.includes('4 | };'), 'line 4 must be present in context');
}

// 5. codeFrameColumns attaches a custom error message to the highlighted marker line
{
  const rawLines = 'const answer = undefinedVar + 1;';
  const loc = {
    start: { line: 1, column: 16 }
  };
  const message = 'undefinedVar is not defined';
  const result = codeFrameColumns(rawLines, loc, { message });

  assert.ok(result.includes(message), 'result must contain the custom error message');
  assert.ok(result.includes(`^ ${message}`), 'message should be placed next to the caret pointer');
}

// 6. codeFrameColumns restricts surrounding visible context using linesAbove and linesBelow options
{
  const rawLines = [
    '/* line 1 */',
    '/* line 2 */',
    '/* line 3 */',
    '/* line 4 - target */',
    '/* line 5 */',
    '/* line 6 */',
    '/* line 7 */'
  ].join('\n');

  const loc = {
    start: { line: 4, column: 1 }
  };
  const result = codeFrameColumns(rawLines, loc, {
    linesAbove: 1,
    linesBelow: 1
  });

  assert.ok(!result.includes('line 1'), 'line 1 should be excluded');
  assert.ok(!result.includes('line 2'), 'line 2 should be excluded');
  assert.ok(result.includes('line 3'), 'line 3 should be included (linesAbove: 1)');
  assert.ok(result.includes('> 4 | /* line 4 - target */'), 'line 4 must be included');
  assert.ok(result.includes('line 5'), 'line 5 should be included (linesBelow: 1)');
  assert.ok(!result.includes('line 6'), 'line 6 should be excluded');
  assert.ok(!result.includes('line 7'), 'line 7 should be excluded');
}

// 7. codeFrameColumns offsets displayed line numbers using startLine option
{
  const snippet = 'return isValid ? "valid" : "invalid";';
  const loc = {
    start: { line: 100, column: 1 }
  };
  const result = codeFrameColumns(snippet, loc, {
    startLine: 100
  });

  assert.ok(result.includes('> 100 | return isValid ? "valid" : "invalid";'), 'gutter line number must start at 100');
}

// 8. highlight exports a function that tokenizes and formats JavaScript syntax
{
  assert.equal(typeof highlight, 'function', 'highlight must be a function');
  const code = 'const count = 42; // counter variable';
  const formatted = highlight(code);
  assert.equal(typeof formatted, 'string', 'highlighted code must be a string');
  assert.ok(formatted.includes('count'), 'highlighted code must preserve token content');
  assert.ok(formatted.includes('42'), 'highlighted code must preserve number literal');
  assert.ok(formatted.includes('counter variable'), 'highlighted code must preserve comment');
}

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