@jridgewell/trace-mapping 0.3.31: eachMapping

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

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:2d802c778f9322023819b065e323afb68efc0c26aa903428d8916e643ce74088","contract":["eachMapping iterates across all mapped segments in generated line and column order","eachMapping resolves 1-based original line, 0-based original column, source path, and identifier name for 5-element segments","eachMapping provides null source, original positions, and name for 1-element unmapped segments","eachMapping handles decoded map objects and empty source maps gracefully","iterateMappings and collectMappings helper functions accurately proxy and aggregate eachMapping iterations"],"goal":"verify @jridgewell/trace-mapping.eachMapping 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.eachMapping"]},"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","packageManagerVersion":"10.9.8","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.eachMapping"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-trace-mapping-each-mapping",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-trace-mapping-each-mapping",
      "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-each-mapping",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of @jridgewell/trace-mapping eachMapping",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "@jridgewell/trace-mapping": "0.3.31"
  }
}

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

const { TraceMap, eachMapping } = require('@jridgewell/trace-mapping');

/**
 * Iterate over each mapping in a source map or TraceMap instance.
 * @param {TraceMap | object} tracer - TraceMap instance or raw map object
 * @param {(mapping: { generatedLine: number, generatedColumn: number, originalLine: number | null, originalColumn: number | null, source: string | null, name: string | null }) => void} callback
 */
function iterateMappings(tracer, callback) {
  const mapInstance = tracer instanceof TraceMap ? tracer : new TraceMap(tracer);
  eachMapping(mapInstance, callback);
}

/**
 * Collect all mappings from a source map or TraceMap instance into an array.
 * @param {TraceMap | object} tracer - TraceMap instance or raw map object
 * @returns {Array<{ generatedLine: number, generatedColumn: number, originalLine: number | null, originalColumn: number | null, source: string | null, name: string | null }>}
 */
function collectMappings(tracer) {
  const result = [];
  iterateMappings(tracer, (mapping) => {
    result.push({
      generatedLine: mapping.generatedLine,
      generatedColumn: mapping.generatedColumn,
      originalLine: mapping.originalLine,
      originalColumn: mapping.originalColumn,
      source: mapping.source,
      name: mapping.name,
    });
  });
  return result;
}

module.exports = {
  TraceMap,
  eachMapping,
  iterateMappings,
  collectMappings,
};

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const {
  TraceMap,
  eachMapping,
  iterateMappings,
  collectMappings,
} = require('../src/index.js');

// Standard v3 source map
const rawMap = {
  version: 3,
  file: 'output.js',
  sources: ['input.js'],
  sourcesContent: ['const greeting = "hello world";\nconsole.log(greeting);\n'],
  names: ['greeting', 'console', 'log'],
  mappings: 'AAAA,MAAMA,WAAW,aAAjB;AACAC,QAAQC,GAAR,CAAYF,QAAZ',
};

const tracer = new TraceMap(rawMap);

// 1. eachMapping iterates across all mapped segments in generated line and column order
const visited = [];
eachMapping(tracer, (mapping) => {
  visited.push({
    generatedLine: mapping.generatedLine,
    generatedColumn: mapping.generatedColumn,
    originalLine: mapping.originalLine,
    originalColumn: mapping.originalColumn,
    source: mapping.source,
    name: mapping.name,
  });
});

assert.strictEqual(visited.length, 9, 'should visit all 9 mappings in the map');

for (let i = 1; i < visited.length; i++) {
  const prev = visited[i - 1];
  const curr = visited[i];
  if (curr.generatedLine === prev.generatedLine) {
    assert.ok(
      curr.generatedColumn > prev.generatedColumn,
      `generatedColumn should increase on line ${curr.generatedLine}`
    );
  } else {
    assert.ok(
      curr.generatedLine > prev.generatedLine,
      'generatedLine should increase monotonically'
    );
  }
}

// 2. eachMapping resolves 1-based original line, 0-based original column, source path, and identifier name for 5-element segments
assert.deepStrictEqual(visited[0], {
  generatedLine: 1,
  generatedColumn: 0,
  source: 'input.js',
  originalLine: 1,
  originalColumn: 0,
  name: null,
});

assert.deepStrictEqual(visited[1], {
  generatedLine: 1,
  generatedColumn: 6,
  source: 'input.js',
  originalLine: 1,
  originalColumn: 6,
  name: 'greeting',
});

assert.deepStrictEqual(visited[4], {
  generatedLine: 2,
  generatedColumn: 0,
  source: 'input.js',
  originalLine: 2,
  originalColumn: 0,
  name: 'console',
});

assert.deepStrictEqual(visited[5], {
  generatedLine: 2,
  generatedColumn: 8,
  source: 'input.js',
  originalLine: 2,
  originalColumn: 8,
  name: 'log',
});

// 3. eachMapping provides null source, original positions, and name for 1-element unmapped segments
const unmapped = {
  version: 3,
  sources: ['input.js'],
  names: ['foo'],
  mappings: [
    [[0], [10, 0, 0, 0]],
    [[5, 0, 1, 2, 0]],
  ],
};
const unmappedTracer = new TraceMap(unmapped);
const unmappedList = [];
eachMapping(unmappedTracer, (m) => {
  unmappedList.push({
    generatedLine: m.generatedLine,
    generatedColumn: m.generatedColumn,
    originalLine: m.originalLine,
    originalColumn: m.originalColumn,
    source: m.source,
    name: m.name,
  });
});

assert.strictEqual(unmappedList.length, 3, 'should have 3 mappings across 2 lines');
assert.deepStrictEqual(unmappedList[0], {
  generatedLine: 1,
  generatedColumn: 0,
  source: null,
  originalLine: null,
  originalColumn: null,
  name: null,
});
assert.deepStrictEqual(unmappedList[1], {
  generatedLine: 1,
  generatedColumn: 10,
  source: 'input.js',
  originalLine: 1,
  originalColumn: 0,
  name: null,
});
assert.deepStrictEqual(unmappedList[2], {
  generatedLine: 2,
  generatedColumn: 5,
  source: 'input.js',
  originalLine: 2,
  originalColumn: 2,
  name: 'foo',
});

// 4. eachMapping handles decoded map objects and empty source maps gracefully
const emptyMap = {
  version: 3,
  sources: [],
  names: [],
  mappings: '',
};
const emptyList = [];
eachMapping(new TraceMap(emptyMap), (m) => emptyList.push(m));
assert.strictEqual(emptyList.length, 0, 'empty map should yield 0 mappings');

// 5. iterateMappings and collectMappings helper functions accurately proxy and aggregate eachMapping iterations
const collected = collectMappings(tracer);
assert.deepStrictEqual(collected, visited, 'collectMappings should return all mappings');

let iterCount = 0;
iterateMappings(rawMap, () => {
  iterCount++;
});
assert.strictEqual(iterCount, 9, 'iterateMappings should accept raw map object and invoke callback for each mapping');

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