@jridgewell/trace-mapping 0.3.31: LEAST_UPPER_BOUND

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.LEAST_UPPER_BOUND 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.LEAST_UPPER_BOUND
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:a5543ba30e3629596dda6fafdfe50711b2a51107dbaf8e6662810ddc585142f1","constraints":{"executionContext":"node"},"contract":["LEAST_UPPER_BOUND is exported as numeric constant -1","originalPositionFor with LEAST_UPPER_BOUND returns the exact mapping when query column matches segment start","originalPositionFor with LEAST_UPPER_BOUND returns the next segment when query column falls between segments","originalPositionFor with GREATEST_LOWER_BOUND returns the previous segment for comparison","originalPositionFor with LEAST_UPPER_BOUND returns null mapping when query column exceeds last segment","generatedPositionFor with LEAST_UPPER_BOUND returns the least upper bound generated position"],"goal":"verify @jridgewell/trace-mapping.LEAST_UPPER_BOUND 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.LEAST_UPPER_BOUND"]},"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.LEAST_UPPER_BOUND"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-trace-mapping-least-upper-bound",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-trace-mapping-least-upper-bound",
      "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-least-upper-bound",
  "version": "1.0.0",
  "description": "verify @jridgewell/trace-mapping.LEAST_UPPER_BOUND in pkg:npm/%40jridgewell/trace-mapping@0.3.31",
  "type": "module",
  "main": "src/index.mjs",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@jridgewell/trace-mapping": "0.3.31"
  },
  "license": "MIT-0"
}

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

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

/**
 * Creates a TraceMap from decoded line mappings.
 *
 * @param {string} sourceFile - Name of the source file.
 * @param {Array<Array<Array<number>>>} mappings - Decoded segment mappings.
 * @returns {TraceMap} Instantiated TraceMap.
 */
export function createTraceMap(sourceFile, mappings) {
  return new TraceMap({
    version: 3,
    sources: [sourceFile],
    names: [],
    mappings
  });
}

/**
 * Queries the original position for a generated line/column with a specific bias.
 *
 * @param {TraceMap} map - The TraceMap instance.
 * @param {number} line - 1-based generated line number.
 * @param {number} column - 0-based generated column number.
 * @param {number} bias - Bias constant (LEAST_UPPER_BOUND or GREATEST_LOWER_BOUND).
 * @returns {object} Original position mapping.
 */
export function getOriginalPosition(map, line, column, bias = LEAST_UPPER_BOUND) {
  return originalPositionFor(map, { line, column, bias });
}

/**
 * Queries the generated position for a source line/column with a specific bias.
 *
 * @param {TraceMap} map - The TraceMap instance.
 * @param {string} source - Source file name.
 * @param {number} line - 1-based source line number.
 * @param {number} column - 0-based source column number.
 * @param {number} bias - Bias constant (LEAST_UPPER_BOUND or GREATEST_LOWER_BOUND).
 * @returns {object} Generated position mapping.
 */
export function getGeneratedPosition(map, source, line, column, bias = LEAST_UPPER_BOUND) {
  return generatedPositionFor(map, { source, line, column, bias });
}

export {
  TraceMap,
  LEAST_UPPER_BOUND,
  GREATEST_LOWER_BOUND,
  originalPositionFor,
  generatedPositionFor
};

import assert from 'node:assert/strict';
import {
  LEAST_UPPER_BOUND,
  GREATEST_LOWER_BOUND,
  createTraceMap,
  getOriginalPosition,
  getGeneratedPosition,
  originalPositionFor,
  generatedPositionFor
} from '../src/index.mjs';

// 1. LEAST_UPPER_BOUND is exported as numeric constant -1
{
  assert.strictEqual(typeof LEAST_UPPER_BOUND, 'number', 'LEAST_UPPER_BOUND must be a number');
  assert.strictEqual(LEAST_UPPER_BOUND, -1, 'LEAST_UPPER_BOUND must equal -1');
  assert.strictEqual(GREATEST_LOWER_BOUND, 1, 'GREATEST_LOWER_BOUND must equal 1');
}

// Sample map setup:
// Generated line 1 has mappings at column 0 -> (orig line 1, col 0), column 10 -> (orig line 1, col 5), column 20 -> (orig line 1, col 15)
const sourceFile = 'input.js';
const mappings = [
  [
    [0, 0, 0, 0],
    [10, 0, 0, 5],
    [20, 0, 0, 15]
  ]
];
const map = createTraceMap(sourceFile, mappings);

// 2. originalPositionFor with LEAST_UPPER_BOUND returns the exact mapping when query column matches segment start
{
  const exact = getOriginalPosition(map, 1, 10, LEAST_UPPER_BOUND);
  assert.deepStrictEqual(exact, {
    source: sourceFile,
    line: 1,
    column: 5,
    name: null
  }, 'Exact column match should return the exact original position');
}

// 3. originalPositionFor with LEAST_UPPER_BOUND returns the next segment when query column falls between segments
{
  // Query column 5 is between column 0 and column 10.
  // LEAST_UPPER_BOUND should return the segment starting at column 10 (orig col 5).
  const upper = getOriginalPosition(map, 1, 5, LEAST_UPPER_BOUND);
  assert.deepStrictEqual(upper, {
    source: sourceFile,
    line: 1,
    column: 5,
    name: null
  }, 'LEAST_UPPER_BOUND should return the least upper bound segment at column 10');
}

// 4. originalPositionFor with GREATEST_LOWER_BOUND returns the previous segment for comparison
{
  // Query column 5 with GREATEST_LOWER_BOUND should return the segment starting at column 0 (orig col 0).
  const lower = getOriginalPosition(map, 1, 5, GREATEST_LOWER_BOUND);
  assert.deepStrictEqual(lower, {
    source: sourceFile,
    line: 1,
    column: 0,
    name: null
  }, 'GREATEST_LOWER_BOUND should return the greatest lower bound segment at column 0');
}

// 5. originalPositionFor with LEAST_UPPER_BOUND returns null mapping when query column exceeds last segment
{
  // Query column 25 is beyond the last segment at column 20.
  const outOfBounds = getOriginalPosition(map, 1, 25, LEAST_UPPER_BOUND);
  assert.deepStrictEqual(outOfBounds, {
    source: null,
    line: null,
    column: null,
    name: null
  }, 'LEAST_UPPER_BOUND beyond last column should return null mapping');
}

// 6. generatedPositionFor with LEAST_UPPER_BOUND returns the least upper bound generated position
{
  // Map where source input.js col 0 -> gen col 0, orig col 10 -> gen col 10, orig col 20 -> gen col 20
  const genMap = createTraceMap('src.js', [
    [
      [0, 0, 0, 0],
      [10, 0, 0, 10],
      [20, 0, 0, 20]
    ]
  ]);

  // Query source line 1, col 5 with LEAST_UPPER_BOUND -> should round up to gen column 10
  const genUpper = getGeneratedPosition(genMap, 'src.js', 1, 5, LEAST_UPPER_BOUND);
  assert.deepStrictEqual(genUpper, {
    line: 1,
    column: 10
  }, 'generatedPositionFor with LEAST_UPPER_BOUND should return generated column 10');

  // Comparison with GREATEST_LOWER_BOUND -> rounds down to gen column 0
  const genLower = getGeneratedPosition(genMap, 'src.js', 1, 5, GREATEST_LOWER_BOUND);
  assert.deepStrictEqual(genLower, {
    line: 1,
    column: 0
  }, 'generatedPositionFor with GREATEST_LOWER_BOUND should return generated column 0');
}

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