@jridgewell/trace-mapping 0.3.31: TraceMap

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/trace-mapping.TraceMap in pkg:npm/%40jridgewell/trace-mapping@0.3.31
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40jridgewell/trace-mapping@0.3.31
Demonstrate these symbols/APIs:
  - @jridgewell/trace-mapping.TraceMap

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:33edb37968e3b0e3944cfdf76b86db8e23916fb6c39fba93f36f78394db7688b","contract":["TraceMap constructs an instance from a JSON string representation of a v3 sourcemap","TraceMap constructs an instance from an object containing decoded mappings array","TraceMap clones an existing TraceMap instance preserving sources and mappings","originalPositionFor resolves the original source file, 1-based line, 0-based column, and token name for a generated position","originalPositionFor returns null fields for unmapped generated positions","generatedPositionFor resolves generated line and column for an original source location","sourceContentFor retrieves embedded source file content by source file name","decodedMappings and encodedMappings extract segment arrays and VLQ encoded string from a TraceMap"],"goal":"verify @jridgewell/trace-mapping.TraceMap in pkg:npm/%40jridgewell/trace-mapping@0.3.31","kind":"HOW","packages":["pkg:npm/%40jridgewell/trace-mapping@0.3.31"],"schemaVersion":1,"symbols":["@jridgewell/trace-mapping.TraceMap"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40jridgewell/trace-mapping@0.3.31"],"schemaVersion":1,"subject":"pkg:npm/%40jridgewell/trace-mapping@0.3.31","symbols":["@jridgewell/trace-mapping.TraceMap"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-trace-mapping-tracemap",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-trace-mapping-tracemap",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@jridgewell/trace-mapping": "0.3.31"
      }
    },
    "node_modules/@jridgewell/resolve-uri": {
      "version": "3.1.2",
      "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz",
      "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==",
      "license": "MIT",
      "engines": {
        "node": ">=6.0.0"
      }
    },
    "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"
    },
    "node_modules/@jridgewell/trace-mapping": {
      "version": "0.3.31",
      "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz",
      "integrity": "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==",
      "license": "MIT",
      "dependencies": {
        "@jridgewell/resolve-uri": "^3.1.0",
        "@jridgewell/sourcemap-codec": "^1.4.14"
      }
    }
  }
}

{
  "name": "sample-trace-mapping-tracemap",
  "version": "1.0.0",
  "description": "verify @jridgewell/trace-mapping.TraceMap in pkg:npm/%40jridgewell/trace-mapping@0.3.31",
  "type": "module",
  "main": "src/index.js",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@jridgewell/trace-mapping": "0.3.31"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify @jridgewell/trace-mapping.TraceMap in pkg:npm/%40jridgewell/trace-mapping@0.3.31",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40jridgewell/trace-mapping@0.3.31"
  ],
  "symbols": [
    "@jridgewell/trace-mapping.TraceMap"
  ]
}

import {
  TraceMap,
  originalPositionFor,
  generatedPositionFor,
  sourceContentFor,
  decodedMappings,
  encodedMappings
} from '@jridgewell/trace-mapping';

/**
 * Creates a new TraceMap instance from a raw source map object, JSON string, or existing TraceMap.
 *
 * @param {object|string|TraceMap} mapInput - Raw map object, serialized JSON string, or TraceMap instance.
 * @returns {TraceMap} The constructed TraceMap instance.
 */
export function createTraceMap(mapInput) {
  return new TraceMap(mapInput);
}

/**
 * Resolves original position for a generated line and column.
 *
 * @param {TraceMap} map - TraceMap instance.
 * @param {number} line - 1-based line in generated code.
 * @param {number} column - 0-based column in generated code.
 * @param {number} [bias] - Tracing bias (GREATEST_LOWER_BOUND or LEAST_UPPER_BOUND).
 * @returns {{ source: string|null, line: number|null, column: number|null, name: string|null }}
 */
export function lookupOriginalPosition(map, line, column, bias) {
  return originalPositionFor(map, { line, column, bias });
}

/**
 * Resolves generated position for an original source file, line, and column.
 *
 * @param {TraceMap} map - TraceMap instance.
 * @param {string} source - Original source filename.
 * @param {number} line - 1-based line in source code.
 * @param {number} column - 0-based column in source code.
 * @param {number} [bias] - Tracing bias.
 * @returns {{ line: number|null, column: number|null }}
 */
export function lookupGeneratedPosition(map, source, line, column, bias) {
  return generatedPositionFor(map, { source, line, column, bias });
}

/**
 * Retrieves the embedded source content for a given source filename.
 *
 * @param {TraceMap} map - TraceMap instance.
 * @param {string} source - Source filename.
 * @returns {string|null} The source file content or null if not found.
 */
export function getSourceContent(map, source) {
  return sourceContentFor(map, source);
}

/**
 * Retrieves decoded mapping segments from a TraceMap instance.
 *
 * @param {TraceMap} map - TraceMap instance.
 * @returns {Array<Array<Array<number>>>} Decoded mapping segments.
 */
export function getDecodedMappings(map) {
  return decodedMappings(map);
}

/**
 * Retrieves the VLQ-encoded mappings string from a TraceMap instance.
 *
 * @param {TraceMap} map - TraceMap instance.
 * @returns {string} VLQ encoded mappings string.
 */
export function getEncodedMappings(map) {
  return encodedMappings(map);
}

import assert from 'node:assert';
import { TraceMap } from '@jridgewell/trace-mapping';
import {
  createTraceMap,
  lookupOriginalPosition,
  lookupGeneratedPosition,
  getSourceContent,
  getDecodedMappings,
  getEncodedMappings
} from '../src/index.js';

// Sample sourcemap payload
const rawMap = {
  version: 3,
  file: 'output.js',
  sources: ['src/app.js'],
  sourcesContent: ['const greeting = "hello";\nconsole.log(greeting);'],
  names: ['greeting', 'log'],
  mappings: 'AAAA,MAAMA,QAAW;AACjBC,QAAQC,IAAI,CAACF'
};

// 1. TraceMap constructs an instance from a JSON string representation of a v3 sourcemap
{
  const jsonStr = JSON.stringify(rawMap);
  const map = createTraceMap(jsonStr);
  assert.strictEqual(map.version, 3, 'TraceMap version must be 3');
  assert.strictEqual(map.file, 'output.js', 'TraceMap file must match');
  assert.deepStrictEqual(map.sources, ['src/app.js'], 'Sources array must match');
  assert.deepStrictEqual(map.names, ['greeting', 'log'], 'Names array must match');
}

// 2. TraceMap constructs an instance from an object containing decoded mappings array
{
  const decodedInput = {
    version: 3,
    sources: ['src/app.js'],
    names: ['greeting'],
    mappings: [
      [[0, 0, 0, 0], [6, 0, 0, 6, 0]]
    ]
  };
  const map = createTraceMap(decodedInput);
  assert.strictEqual(map.version, 3);
  assert.deepStrictEqual(map.sources, ['src/app.js']);
  const encoded = getEncodedMappings(map);
  assert.strictEqual(encoded, 'AAAA,MAAMA');
}

// 3. TraceMap clones an existing TraceMap instance preserving sources and mappings
{
  const original = createTraceMap(rawMap);
  const cloned = createTraceMap(original);
  assert.strictEqual(cloned.version, 3);
  assert.deepStrictEqual(cloned.sources, original.sources);
  assert.strictEqual(getEncodedMappings(cloned), getEncodedMappings(original));
}

// 4. originalPositionFor resolves the original source file, 1-based line, 0-based column, and token name for a generated position
{
  const map = createTraceMap(rawMap);
  const pos = lookupOriginalPosition(map, 1, 6);
  assert.strictEqual(pos.source, 'src/app.js');
  assert.strictEqual(pos.line, 1);
  assert.strictEqual(pos.column, 6);
  assert.strictEqual(pos.name, 'greeting');
}

// 5. originalPositionFor returns null fields for unmapped generated positions
{
  const map = createTraceMap(rawMap);
  const unmapped = lookupOriginalPosition(map, 999, 999);
  assert.strictEqual(unmapped.source, null);
  assert.strictEqual(unmapped.line, null);
  assert.strictEqual(unmapped.column, null);
  assert.strictEqual(unmapped.name, null);
}

// 6. generatedPositionFor resolves generated line and column for an original source location
{
  const map = createTraceMap(rawMap);
  const genPos = lookupGeneratedPosition(map, 'src/app.js', 2, 8);
  assert.strictEqual(genPos.line, 2);
  assert.strictEqual(genPos.column, 8);
}

// 7. sourceContentFor retrieves embedded source file content by source file name
{
  const map = createTraceMap(rawMap);
  const content = getSourceContent(map, 'src/app.js');
  assert.strictEqual(content, 'const greeting = "hello";\nconsole.log(greeting);');
  const missing = getSourceContent(map, 'nonexistent.js');
  assert.strictEqual(missing, null);
}

// 8. decodedMappings and encodedMappings extract segment arrays and VLQ encoded string from a TraceMap
{
  const map = createTraceMap(rawMap);
  const decoded = getDecodedMappings(map);
  assert(Array.isArray(decoded), 'Decoded mappings must be an array of lines');
  assert.strictEqual(decoded.length, 2, 'Decoded mappings must have 2 lines');
  assert.deepStrictEqual(decoded[0][0], [0, 0, 0, 0]);

  const encoded = getEncodedMappings(map);
  assert.strictEqual(encoded, rawMap.mappings);
}

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