@jridgewell/trace-mapping 0.3.31: allGeneratedPositionsFor

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.allGeneratedPositionsFor 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.allGeneratedPositionsFor
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: esm
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:3165c48a4085630898a3bb08cadf9835157f7ab9d7abd25594b45622ab3a6ebe","constraints":{"executionContext":"node"},"contract":["allGeneratedPositionsFor returns all generated line and column mappings for an original source location","allGeneratedPositionsFor returns multiple matching generated positions across lines and columns","allGeneratedPositionsFor returns an empty array when source is not present or unmapped","allGeneratedPositionsFor supports LEAST_UPPER_BOUND and GREATEST_LOWER_BOUND search biases","allGeneratedPositionsFor throws error when line is less than 1 or column is negative"],"goal":"verify @jridgewell/trace-mapping.allGeneratedPositionsFor 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.allGeneratedPositionsFor"]},"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","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.allGeneratedPositionsFor"],"verifierAdapter":"node-typescript@1"}

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

{
  "schemaVersion": 1,
  "goal": "verify @jridgewell/trace-mapping.allGeneratedPositionsFor in pkg:npm/%40jridgewell/trace-mapping@0.3.31",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40jridgewell/trace-mapping@0.3.31"
  ],
  "symbols": [
    "@jridgewell/trace-mapping.allGeneratedPositionsFor"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "esm",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

import {
  TraceMap,
  allGeneratedPositionsFor,
  LEAST_UPPER_BOUND,
  GREATEST_LOWER_BOUND,
} from '@jridgewell/trace-mapping';

export {
  TraceMap,
  allGeneratedPositionsFor,
  LEAST_UPPER_BOUND,
  GREATEST_LOWER_BOUND,
};

import assert from 'node:assert/strict';
import {
  TraceMap,
  allGeneratedPositionsFor,
  LEAST_UPPER_BOUND,
  GREATEST_LOWER_BOUND,
} from '../src/index.js';

// Decoded source map with mappings across multiple lines and columns
const mapData = {
  version: 3,
  sources: ['input.js', 'helper.js'],
  sourcesContent: ['const a = 1;\nconst b = 2;\n', 'export const c = 3;\n'],
  names: ['a', 'b', 'c'],
  mappings: [
    // generated line 1:
    [
      [0, 0, 0, 0, 0],   // col 0 -> input.js line 1 (0-based 0), col 0
      [10, 0, 0, 6, 0],  // col 10 -> input.js line 1, col 6
      [20, 0, 0, 0, 0],  // col 20 -> input.js line 1, col 0 (duplicate target)
    ],
    // generated line 2:
    [
      [0, 0, 0, 0, 0],   // col 0 -> input.js line 1, col 0 (another target on line 2)
      [5, 0, 1, 0, 1],   // col 5 -> input.js line 2, col 0
      [15, 1, 0, 0, 2],  // col 15 -> helper.js line 1, col 0
    ],
    // generated line 3:
    [
      [0, 0, 0, 10],     // col 0 -> input.js line 1, col 10
      [10, 0, 0, 20],    // col 10 -> input.js line 1, col 20
    ],
  ],
};

const tracer = new TraceMap(mapData);

// 1. allGeneratedPositionsFor returns all generated line and column mappings for an original source location
const singlePositions = allGeneratedPositionsFor(tracer, {
  source: 'input.js',
  line: 1,
  column: 6,
});
assert.ok(Array.isArray(singlePositions), 'should return an array');
assert.strictEqual(singlePositions.length, 1, 'should return exactly 1 generated position');
assert.deepStrictEqual(singlePositions[0], { line: 1, column: 10 });

const helperPositions = allGeneratedPositionsFor(tracer, {
  source: 'helper.js',
  line: 1,
  column: 0,
});
assert.strictEqual(helperPositions.length, 1, 'should return 1 generated position for helper');
assert.deepStrictEqual(helperPositions[0], { line: 2, column: 15 });

// 2. allGeneratedPositionsFor returns multiple matching generated positions across lines and columns
const multiPositions = allGeneratedPositionsFor(tracer, {
  source: 'input.js',
  line: 1,
  column: 0,
});
assert.ok(Array.isArray(multiPositions), 'should return an array');
assert.strictEqual(multiPositions.length, 3, 'should return 3 generated positions');
assert.deepStrictEqual(multiPositions, [
  { line: 1, column: 0 },
  { line: 1, column: 20 },
  { line: 2, column: 0 },
]);

// 3. allGeneratedPositionsFor returns an empty array when source is not present or unmapped
const missingSource = allGeneratedPositionsFor(tracer, {
  source: 'nonexistent.js',
  line: 1,
  column: 0,
});
assert.ok(Array.isArray(missingSource), 'should return an array for missing source');
assert.strictEqual(missingSource.length, 0, 'should return empty array for missing source');

const missingLine = allGeneratedPositionsFor(tracer, {
  source: 'input.js',
  line: 99,
  column: 0,
});
assert.ok(Array.isArray(missingLine), 'should return an array for unmapped line');
assert.strictEqual(missingLine.length, 0, 'should return empty array for unmapped line');

// 4. allGeneratedPositionsFor supports LEAST_UPPER_BOUND and GREATEST_LOWER_BOUND search biases
const leastUpperBound = allGeneratedPositionsFor(tracer, {
  source: 'input.js',
  line: 1,
  column: 15,
  bias: LEAST_UPPER_BOUND,
});
assert.strictEqual(leastUpperBound.length, 1, 'LEAST_UPPER_BOUND should find upper segment');
assert.deepStrictEqual(leastUpperBound[0], { line: 3, column: 10 });

const greatestLowerBound = allGeneratedPositionsFor(tracer, {
  source: 'input.js',
  line: 1,
  column: 15,
  bias: GREATEST_LOWER_BOUND,
});
assert.strictEqual(greatestLowerBound.length, 1, 'GREATEST_LOWER_BOUND should find lower segment');
assert.deepStrictEqual(greatestLowerBound[0], { line: 3, column: 0 });

// 5. allGeneratedPositionsFor throws error when line is less than 1 or column is negative
assert.throws(
  () => {
    allGeneratedPositionsFor(tracer, { source: 'input.js', line: 0, column: 0 });
  },
  {
    message: '`line` must be greater than 0 (lines start at line 1)',
  }
);

assert.throws(
  () => {
    allGeneratedPositionsFor(tracer, { source: 'input.js', line: 1, column: -1 });
  },
  {
    message: '`column` must be greater than or equal to 0 (columns start at column 0)',
  }
);

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