@jridgewell/trace-mapping 0.3.31: encodedMap

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.encodedMap 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.encodedMap

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:78d1b609fb6a1cd3c6d99f6a48ceb155f53702c5cc8e5bfa39666933d9883856","contract":["encodedMap serializes a TraceMap constructed from a DecodedSourceMap into an EncodedSourceMap with VLQ string mappings","encodedMap preserves existing encoded VLQ string mappings when TraceMap is constructed from an EncodedSourceMap","encodedMap preserves source map metadata properties including file, sourceRoot, sourcesContent, and ignoreList","encodedMap normalizes legacy x_google_ignoreList into the standard ignoreList field","encodedMap produces an empty string mappings field when given a source map with empty mappings","reconstructing a TraceMap from the output of encodedMap preserves original and generated position lookups","exporting encodeToSourceMapJson helper converts a TraceMap into a valid JSON-serializable encoded source map string"],"goal":"verify @jridgewell/trace-mapping.encodedMap 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.encodedMap"]},"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/trace-mapping@0.3.31"],"schemaVersion":1,"subject":"pkg:npm/%40jridgewell/trace-mapping@0.3.31","symbols":["@jridgewell/trace-mapping.encodedMap"],"verifierAdapter":"node-typescript@1"}

import { TraceMap, encodedMap } from '@jridgewell/trace-mapping';

/**
 * Converts a TraceMap or raw source map into an EncodedSourceMap object.
 * @param {import('@jridgewell/trace-mapping').SourceMapInput | TraceMap} input
 * @returns {import('@jridgewell/trace-mapping').EncodedSourceMap}
 */
export function toEncodedMap(input) {
  const tracer = input instanceof TraceMap ? input : new TraceMap(input);
  return encodedMap(tracer);
}

/**
 * Converts a TraceMap or raw source map into a JSON-serialized string of an EncodedSourceMap.
 * @param {import('@jridgewell/trace-mapping').SourceMapInput | TraceMap} input
 * @returns {string}
 */
export function encodeToSourceMapJson(input) {
  return JSON.stringify(toEncodedMap(input));
}

export { TraceMap, encodedMap };

{
  "name": "sample-trace-mapping",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-trace-mapping",
      "version": "1.0.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",
  "version": "1.0.0",
  "type": "module",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@jridgewell/trace-mapping": "0.3.31"
  }
}

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

import assert from 'node:assert/strict';
import { TraceMap, encodedMap, originalPositionFor, generatedPositionFor } from '@jridgewell/trace-mapping';
import { toEncodedMap, encodeToSourceMapJson } from '../index.js';

// 1. encodedMap serializes a TraceMap constructed from a DecodedSourceMap into an EncodedSourceMap with VLQ string mappings
{
  const decodedSourceMap = {
    version: 3,
    file: 'bundle.js',
    sources: ['foo.js'],
    sourcesContent: ['function foo() { return 1; }'],
    names: ['foo'],
    mappings: [
      [[0, 0, 0, 0, 0], [10, 0, 0, 9]],
      [[0, 0, 0, 16]]
    ]
  };
  const tracer = new TraceMap(decodedSourceMap);
  const encoded = encodedMap(tracer);

  assert.equal(encoded.version, 3);
  assert.equal(encoded.file, 'bundle.js');
  assert.deepEqual(encoded.sources, ['foo.js']);
  assert.deepEqual(encoded.sourcesContent, ['function foo() { return 1; }']);
  assert.deepEqual(encoded.names, ['foo']);
  assert.equal(typeof encoded.mappings, 'string');
  assert.equal(encoded.mappings, 'AAAAA,UAAS;AAAO');
}

// 2. encodedMap preserves existing encoded VLQ string mappings when TraceMap is constructed from an EncodedSourceMap
{
  const encodedInput = {
    version: 3,
    sources: ['bar.js'],
    names: ['bar'],
    mappings: 'AAAA;AACA'
  };
  const tracer = new TraceMap(encodedInput);
  const encoded = encodedMap(tracer);

  assert.equal(encoded.version, 3);
  assert.deepEqual(encoded.sources, ['bar.js']);
  assert.deepEqual(encoded.names, ['bar']);
  assert.equal(encoded.mappings, 'AAAA;AACA');
}

// 3. encodedMap preserves source map metadata properties including file, sourceRoot, sourcesContent, and ignoreList
{
  const mapWithMeta = {
    version: 3,
    file: 'output.min.js',
    sourceRoot: 'https://example.com/src',
    sources: ['src/app.ts', 'src/util.ts'],
    sourcesContent: ['const app = 1;', 'const util = 2;'],
    names: ['app', 'util'],
    mappings: 'AAAA;AACA',
    ignoreList: [1]
  };
  const tracer = new TraceMap(mapWithMeta);
  const encoded = encodedMap(tracer);

  assert.equal(encoded.file, 'output.min.js');
  assert.equal(encoded.sourceRoot, 'https://example.com/src');
  assert.deepEqual(encoded.sources, ['src/app.ts', 'src/util.ts']);
  assert.deepEqual(encoded.sourcesContent, ['const app = 1;', 'const util = 2;']);
  assert.deepEqual(encoded.names, ['app', 'util']);
  assert.deepEqual(encoded.ignoreList, [1]);
  assert.equal(encoded.mappings, 'AAAA;AACA');
}

// 4. encodedMap normalizes legacy x_google_ignoreList into the standard ignoreList field
{
  const mapWithGoogleIgnore = {
    version: 3,
    sources: ['node_modules/dep.js'],
    names: [],
    mappings: 'AAAA',
    x_google_ignoreList: [0]
  };
  const tracer = new TraceMap(mapWithGoogleIgnore);
  const encoded = encodedMap(tracer);

  assert.deepEqual(encoded.ignoreList, [0]);
}

// 5. encodedMap produces an empty string mappings field when given a source map with empty mappings
{
  const emptyDecodedMap = {
    version: 3,
    sources: [],
    names: [],
    mappings: []
  };
  const tracer = new TraceMap(emptyDecodedMap);
  const encoded = encodedMap(tracer);

  assert.equal(encoded.mappings, '');
  assert.deepEqual(encoded.sources, []);
  assert.deepEqual(encoded.names, []);
}

// 6. reconstructing a TraceMap from the output of encodedMap preserves original and generated position lookups
{
  const originalMap = {
    version: 3,
    sources: ['src/math.ts'],
    sourcesContent: ['export const add = (a, b) => a + b;'],
    names: ['add'],
    mappings: [
      [[0, 0, 0, 13, 0]]
    ]
  };
  const tracer1 = new TraceMap(originalMap);
  const encoded = encodedMap(tracer1);
  const tracer2 = new TraceMap(encoded);

  const orig1 = originalPositionFor(tracer1, { line: 1, column: 0 });
  const orig2 = originalPositionFor(tracer2, { line: 1, column: 0 });
  assert.deepEqual(orig1, orig2);
  assert.deepEqual(orig1, {
    source: 'src/math.ts',
    line: 1,
    column: 13,
    name: 'add'
  });

  const gen1 = generatedPositionFor(tracer1, { source: 'src/math.ts', line: 1, column: 13 });
  const gen2 = generatedPositionFor(tracer2, { source: 'src/math.ts', line: 1, column: 13 });
  assert.deepEqual(gen1, gen2);
  assert.deepEqual(gen1, { line: 1, column: 0 });
}

// 7. exporting encodeToSourceMapJson helper converts a TraceMap into a valid JSON-serializable encoded source map string
{
  const decodedMapInput = {
    version: 3,
    file: 'output.js',
    sources: ['input.js'],
    names: [],
    mappings: [[[0, 0, 0, 0]]]
  };
  const jsonStr = encodeToSourceMapJson(decodedMapInput);
  const parsed = JSON.parse(jsonStr);

  assert.equal(parsed.version, 3);
  assert.equal(parsed.file, 'output.js');
  assert.deepEqual(parsed.sources, ['input.js']);
  assert.equal(parsed.mappings, 'AAAA');
}

console.log('All @jridgewell/trace-mapping.encodedMap contract assertions passed.');