@jridgewell/sourcemap-codec 1.5.5: decode

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 @jridgewell/sourcemap-codec.decode in pkg:npm/%40jridgewell/sourcemap-codec@1.5.5
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40jridgewell/sourcemap-codec@1.5.5
Demonstrate these symbols/APIs:
  - @jridgewell/sourcemap-codec.decode

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:1f7ba793ce9e0b9f623989a003e668ed715df56c71dd06c8a6847be034a4b218","contract":["decode parses empty mappings string to a single empty line array","decode parses single 1-element segment containing generated column offset","decode parses single 4-element segment containing generated column, source index, original line, and original column","decode parses single 5-element segment containing generated column, source index, original line, original column, and name index","decode parses multiple segments within the same line separated by commas","decode parses multiple lines separated by semicolons including empty lines","decodeToSegments helper transforms decoded segments into structured field objects","countTotalSegments helper counts total number of mapping segments across all lines"],"goal":"verify @jridgewell/sourcemap-codec.decode in pkg:npm/%40jridgewell/sourcemap-codec@1.5.5","kind":"HOW","packages":["pkg:npm/%40jridgewell/sourcemap-codec@1.5.5"],"schemaVersion":1,"symbols":["@jridgewell/sourcemap-codec.decode"]},"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/%40jridgewell/sourcemap-codec@1.5.5"],"schemaVersion":1,"subject":"pkg:npm/%40jridgewell/sourcemap-codec@1.5.5","symbols":["@jridgewell/sourcemap-codec.decode"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-sourcemap-codec-decode",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-sourcemap-codec-decode",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@jridgewell/sourcemap-codec": "1.5.5"
      }
    },
    "node_modules/@jridgewell/sourcemap-codec": {
      "version": "1.5.5",
      "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz",
      "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-sourcemap-codec-decode",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "@jridgewell/sourcemap-codec": "1.5.5"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify @jridgewell/sourcemap-codec.decode in pkg:npm/%40jridgewell/sourcemap-codec@1.5.5",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40jridgewell/sourcemap-codec@1.5.5"
  ],
  "symbols": [
    "@jridgewell/sourcemap-codec.decode"
  ]
}

import { decode } from '@jridgewell/sourcemap-codec';

/**
 * Decode a source map mappings string into an array of lines containing segments.
 *
 * @param {string} mappings
 * @returns {number[][][]}
 */
export function decodeMappings(mappings) {
  return decode(mappings);
}

/**
 * Decode a mappings string and transform raw segment tuples into structured objects.
 *
 * @param {string} mappings
 * @returns {Array<Array<{ generatedColumn: number, sourceIndex?: number, originalLine?: number, originalColumn?: number, nameIndex?: number }>>}
 */
export function decodeToSegments(mappings) {
  const decoded = decode(mappings);
  return decoded.map((line) =>
    line.map((segment) => {
      const segObj = {
        generatedColumn: segment[0]
      };
      if (segment.length >= 4) {
        segObj.sourceIndex = segment[1];
        segObj.originalLine = segment[2];
        segObj.originalColumn = segment[3];
      }
      if (segment.length >= 5) {
        segObj.nameIndex = segment[4];
      }
      return segObj;
    })
  );
}

/**
 * Count total number of mapping segments across all lines.
 *
 * @param {string} mappings
 * @returns {number}
 */
export function countTotalSegments(mappings) {
  const decoded = decode(mappings);
  return decoded.reduce((total, line) => total + line.length, 0);
}

import assert from 'node:assert/strict';
import { decode } from '@jridgewell/sourcemap-codec';
import {
  decodeMappings,
  decodeToSegments,
  countTotalSegments
} from '../src/index.mjs';

// Contract 1: decode parses empty mappings string to a single empty line array
{
  const result = decode('');
  assert.deepEqual(result, [[]], 'empty mappings string should decode to [[]]');
  assert.deepEqual(decodeMappings(''), [[]], 'decodeMappings helper handles empty mappings');
}

// Contract 2: decode parses single 1-element segment containing generated column offset
{
  // 'K' in VLQ decodes to [5]
  const result = decode('K');
  assert.deepEqual(result, [[[5]]], '1-element segment decodes generatedColumn only');
}

// Contract 3: decode parses single 4-element segment containing generated column, source index, original line, and original column
{
  // 'AAAA' in VLQ decodes to [0, 0, 0, 0]
  const result = decode('AAAA');
  assert.deepEqual(result, [[[0, 0, 0, 0]]], '4-element segment decodes generatedColumn, sourceIndex, originalLine, originalColumn');
}

// Contract 4: decode parses single 5-element segment containing generated column, source index, original line, original column, and name index
{
  // 'AAAAA' in VLQ decodes to [0, 0, 0, 0, 0]
  const result = decode('AAAAA');
  assert.deepEqual(result, [[[0, 0, 0, 0, 0]]], '5-element segment decodes generatedColumn, sourceIndex, originalLine, originalColumn, nameIndex');
}

// Contract 5: decode parses multiple segments within the same line separated by commas
{
  // 'AAAA,CAAC' -> [0, 0, 0, 0], [1, 0, 0, 1]
  const result = decode('AAAA,CAAC');
  assert.deepEqual(
    result,
    [
      [
        [0, 0, 0, 0],
        [1, 0, 0, 1]
      ]
    ],
    'multiple segments on the same line are decoded properly'
  );
}

// Contract 6: decode parses multiple lines separated by semicolons including empty lines
{
  // 'AAAA;;EAAA' -> Line 0: [0,0,0,0], Line 1: [], Line 2: [2,0,0,1]
  const result = decode('AAAA;;EAAA');
  assert.deepEqual(
    result,
    [
      [[0, 0, 0, 0]],
      [],
      [[2, 0, 0, 0]]
    ],
    'multiple lines and empty lines separated by semicolons are decoded properly'
  );
}

// Contract 7: decodeToSegments helper transforms decoded segments into structured field objects
{
  const structured = decodeToSegments('AAAAA,CAAC;EAAA');
  assert.equal(structured.length, 2);
  assert.deepEqual(structured[0][0], {
    generatedColumn: 0,
    sourceIndex: 0,
    originalLine: 0,
    originalColumn: 0,
    nameIndex: 0
  });
  assert.deepEqual(structured[0][1], {
    generatedColumn: 1,
    sourceIndex: 0,
    originalLine: 0,
    originalColumn: 1
  });
  assert.deepEqual(structured[1][0], {
    generatedColumn: 2,
    sourceIndex: 0,
    originalLine: 0,
    originalColumn: 1
  });
}

// Contract 8: countTotalSegments helper counts total number of mapping segments across all lines
{
  assert.equal(countTotalSegments(''), 0);
  assert.equal(countTotalSegments('AAAA'), 1);
  assert.equal(countTotalSegments('AAAA,CAAC;EAAA'), 3);
}

console.log('All @jridgewell/sourcemap-codec.decode contract tests passed successfully.');