@jridgewell/trace-mapping 0.3.31: generatedPositionFor

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

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:701cd15369af4a8bfb42e05c7353896c756992a64bff3adf38589d62641b3b13","constraints":{"executionContext":"node"},"contract":["generatedPositionFor maps original source, 1-based line, and 0-based column to generated line and column","generatedPositionFor returns null line and column when the queried position or source is not mapped","generatedPositionFor with GREATEST_LOWER_BOUND finds the generated position of the nearest mapping at or before the queried column","generatedPositionFor with LEAST_UPPER_BOUND finds the generated position of the nearest mapping at or after the queried column","generatedPositionFor correctly resolves positions across multiple source files in a single TraceMap"],"goal":"verify @jridgewell/trace-mapping.generatedPositionFor 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.generatedPositionFor"]},"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.generatedPositionFor"],"verifierAdapter":"node-typescript@1"}

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

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

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

/**
 * Creates a TraceMap instance from raw source map object or JSON string.
 */
function createTraceMap(map, mapUrl) {
  return new TraceMap(map, mapUrl);
}

/**
 * Finds the generated position for a given original source, line, column, and optional bias.
 */
function findGeneratedPosition(tracer, source, line, column, bias) {
  return generatedPositionFor(tracer, { source, line, column, bias });
}

module.exports = {
  TraceMap,
  generatedPositionFor,
  GREATEST_LOWER_BOUND,
  LEAST_UPPER_BOUND,
  createTraceMap,
  findGeneratedPosition,
};

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

const require = createRequire(import.meta.url);
const {
  TraceMap,
  generatedPositionFor,
  GREATEST_LOWER_BOUND,
  LEAST_UPPER_BOUND,
  createTraceMap,
  findGeneratedPosition,
} = require('../src/index.js');

const multiSourceMap = {
  version: 3,
  file: 'bundle.js',
  sources: ['math.js', 'main.js'],
  sourcesContent: [
    'export function add(a, b) {\n  return a + b;\n}\n',
    'import { add } from "./math";\nconsole.log(add(1, 2));\n',
  ],
  names: ['add', 'a', 'b', 'console', 'log'],
  mappings: [
    // Line 1 of bundle.js
    [
      [0, 0, 0, 0],       // math.js Line 1 (0), Col 0 -> bundle.js Line 1, Col 0
      [16, 0, 0, 16, 0],  // math.js Line 1 (0), Col 16 ("add") -> bundle.js Line 1, Col 16
    ],
    // Line 2 of bundle.js
    [
      [2, 0, 1, 2],       // math.js Line 2 (1), Col 2 ("return") -> bundle.js Line 2, Col 2
      [9, 0, 1, 9, 1],    // math.js Line 2 (1), Col 9 ("a") -> bundle.js Line 2, Col 9
      [13, 0, 1, 13, 2],  // math.js Line 2 (1), Col 13 ("b") -> bundle.js Line 2, Col 13
    ],
    // Line 3 of bundle.js
    [
      [0, 1, 0, 0],       // main.js Line 1 (0), Col 0 -> bundle.js Line 3, Col 0
      [0, 1, 1, 0, 3],    // main.js Line 2 (1), Col 0 ("console") -> bundle.js Line 3, Col 0
      [8, 1, 1, 8, 4],    // main.js Line 2 (1), Col 8 ("log") -> bundle.js Line 3, Col 8
      [12, 1, 1, 12, 0],  // main.js Line 2 (1), Col 12 ("add") -> bundle.js Line 3, Col 12
    ],
  ],
};

const tracer = createTraceMap(multiSourceMap);
assert.ok(tracer instanceof TraceMap, 'tracer should be a TraceMap instance');

// 1. generatedPositionFor maps original source, 1-based line, and 0-based column to generated line and column
const mathPos1 = findGeneratedPosition(tracer, 'math.js', 1, 0);
assert.strictEqual(mathPos1.line, 1, 'math.js 1:0 should map to generated line 1');
assert.strictEqual(mathPos1.column, 0, 'math.js 1:0 should map to generated column 0');

const mathPos2 = generatedPositionFor(tracer, { source: 'math.js', line: 1, column: 16 });
assert.strictEqual(mathPos2.line, 1, 'math.js 1:16 should map to generated line 1');
assert.strictEqual(mathPos2.column, 16, 'math.js 1:16 should map to generated column 16');

const mathPosReturn = findGeneratedPosition(tracer, 'math.js', 2, 2);
assert.strictEqual(mathPosReturn.line, 2, 'math.js 2:2 should map to generated line 2');
assert.strictEqual(mathPosReturn.column, 2, 'math.js 2:2 should map to generated column 2');

// 2. generatedPositionFor returns null line and column when the queried position or source is not mapped
const unmappedSource = generatedPositionFor(tracer, { source: 'unknown.js', line: 1, column: 0 });
assert.strictEqual(unmappedSource.line, null, 'unmapped source line should be null');
assert.strictEqual(unmappedSource.column, null, 'unmapped source column should be null');

const unmappedLine = findGeneratedPosition(tracer, 'math.js', 99, 0);
assert.strictEqual(unmappedLine.line, null, 'unmapped line should return null line');
assert.strictEqual(unmappedLine.column, null, 'unmapped line should return null column');

// 3. generatedPositionFor with GREATEST_LOWER_BOUND finds the generated position of the nearest mapping at or before the queried column
const glbResult = findGeneratedPosition(tracer, 'math.js', 2, 5, GREATEST_LOWER_BOUND);
assert.strictEqual(glbResult.line, 2, 'GLB for math.js 2:5 should match line 2');
assert.strictEqual(glbResult.column, 2, 'GLB for math.js 2:5 should match column 2 (return segment)');

// 4. generatedPositionFor with LEAST_UPPER_BOUND finds the generated position of the nearest mapping at or after the queried column
const lubResult = findGeneratedPosition(tracer, 'math.js', 2, 5, LEAST_UPPER_BOUND);
assert.strictEqual(lubResult.line, 2, 'LUB for math.js 2:5 should match line 2');
assert.strictEqual(lubResult.column, 9, 'LUB for math.js 2:5 should match column 9 ("a" segment)');

// 5. generatedPositionFor correctly resolves positions across multiple source files in a single TraceMap
const mainPos1 = findGeneratedPosition(tracer, 'main.js', 1, 0);
assert.strictEqual(mainPos1.line, 3, 'main.js 1:0 should map to generated line 3');
assert.strictEqual(mainPos1.column, 0, 'main.js 1:0 should map to generated column 0');

const mainPosLog = generatedPositionFor(tracer, { source: 'main.js', line: 2, column: 8 });
assert.strictEqual(mainPosLog.line, 3, 'main.js 2:8 should map to generated line 3');
assert.strictEqual(mainPosLog.column, 8, 'main.js 2:8 should map to generated column 8');

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