@jridgewell/trace-mapping 0.3.31: GREATEST_LOWER_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.GREATEST_LOWER_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.GREATEST_LOWER_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:91717aae49a98ae1d5491d74b7d7b1c2c570f35eadff43d3dc609738770b59ad","constraints":{"executionContext":"node"},"contract":["assert GREATEST_LOWER_BOUND constant has numeric value 1 and LEAST_UPPER_BOUND has -1","assert originalPositionFor with GREATEST_LOWER_BOUND resolves to greatest lower bound segment when exact position is not mapped","assert originalPositionFor defaults to GREATEST_LOWER_BOUND bias when bias option is omitted","assert originalPositionFor with GREATEST_LOWER_BOUND returns null fields when queried before first mapped segment","assert generatedPositionFor with GREATEST_LOWER_BOUND resolves to greatest lower bound generated position","assert findOriginalPosition and findGeneratedPosition helper functions correctly wrap lookup with GREATEST_LOWER_BOUND"],"goal":"verify @jridgewell/trace-mapping.GREATEST_LOWER_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.GREATEST_LOWER_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.GREATEST_LOWER_BOUND"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-trace-mapping-greatest-lower-bound",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-trace-mapping-greatest-lower-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-greatest-lower-bound",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "dependencies": {
    "@jridgewell/trace-mapping": "0.3.31"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify @jridgewell/trace-mapping.GREATEST_LOWER_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.GREATEST_LOWER_BOUND"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "esm",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

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

/**
 * Creates a TraceMap instance from raw source map input.
 * @param {import('@jridgewell/trace-mapping').SourceMapInput} mapInput
 * @returns {TraceMap}
 */
export function createTracer(mapInput) {
  return new TraceMap(mapInput);
}

/**
 * Look up original source position with configurable bias (defaults to GREATEST_LOWER_BOUND).
 * @param {TraceMap} tracer
 * @param {{ line: number; column: number; bias?: number }} needle
 * @returns {import('@jridgewell/trace-mapping').OriginalMapping | import('@jridgewell/trace-mapping').InvalidOriginalMapping}
 */
export function findOriginalPosition(tracer, needle) {
  return originalPositionFor(tracer, {
    line: needle.line,
    column: needle.column,
    bias: needle.bias !== undefined ? needle.bias : GREATEST_LOWER_BOUND
  });
}

/**
 * Look up generated position for an original source location with configurable bias.
 * @param {TraceMap} tracer
 * @param {{ source: string; line: number; column: number; bias?: number }} needle
 * @returns {import('@jridgewell/trace-mapping').GeneratedMapping | import('@jridgewell/trace-mapping').InvalidGeneratedMapping}
 */
export function findGeneratedPosition(tracer, needle) {
  return generatedPositionFor(tracer, {
    source: needle.source,
    line: needle.line,
    column: needle.column,
    bias: needle.bias !== undefined ? needle.bias : GREATEST_LOWER_BOUND
  });
}

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

import assert from 'node:assert/strict';
import {
  TraceMap,
  GREATEST_LOWER_BOUND,
  LEAST_UPPER_BOUND,
  originalPositionFor,
  generatedPositionFor,
  createTracer,
  findOriginalPosition,
  findGeneratedPosition
} from '../src/index.mjs';

// Sample source map:
// Line 1:
// - gen col 5  -> input.js line 1 col 0 (name: "foo")
// - gen col 15 -> input.js line 1 col 10 (name: "bar")
const mapV3 = {
  version: 3,
  sources: ['input.js'],
  names: ['foo', 'bar'],
  mappings: 'KAAAA,UAAUC'
};

const tracer = createTracer(mapV3);

// 1. GREATEST_LOWER_BOUND constant verification
assert.strictEqual(typeof GREATEST_LOWER_BOUND, 'number', 'GREATEST_LOWER_BOUND should be a number');
assert.strictEqual(GREATEST_LOWER_BOUND, 1, 'GREATEST_LOWER_BOUND should equal 1');
assert.strictEqual(LEAST_UPPER_BOUND, -1, 'LEAST_UPPER_BOUND should equal -1');

// 2. originalPositionFor with GREATEST_LOWER_BOUND resolves to greatest lower bound segment
{
  // Query between segments at gen col 10 (segment at col 5 maps to orig col 0, segment at col 15 maps to orig col 10)
  const posGLB = originalPositionFor(tracer, { line: 1, column: 10, bias: GREATEST_LOWER_BOUND });
  assert.deepStrictEqual(posGLB, {
    source: 'input.js',
    line: 1,
    column: 0,
    name: 'foo'
  });

  // Contrast with LEAST_UPPER_BOUND which returns the next segment
  const posLUB = originalPositionFor(tracer, { line: 1, column: 10, bias: LEAST_UPPER_BOUND });
  assert.deepStrictEqual(posLUB, {
    source: 'input.js',
    line: 1,
    column: 10,
    name: 'bar'
  });
}

// 3. originalPositionFor defaults to GREATEST_LOWER_BOUND bias when bias is omitted
{
  const posDefault = originalPositionFor(tracer, { line: 1, column: 10 });
  const posExplicitGLB = originalPositionFor(tracer, { line: 1, column: 10, bias: GREATEST_LOWER_BOUND });
  assert.deepStrictEqual(posDefault, posExplicitGLB);
}

// 4. originalPositionFor with GREATEST_LOWER_BOUND returns null fields when queried before first mapped segment
{
  const posBefore = originalPositionFor(tracer, { line: 1, column: 2, bias: GREATEST_LOWER_BOUND });
  assert.deepStrictEqual(posBefore, {
    source: null,
    line: null,
    column: null,
    name: null
  });

  // Exactly at first mapped segment (col 5)
  const posExact = originalPositionFor(tracer, { line: 1, column: 5, bias: GREATEST_LOWER_BOUND });
  assert.deepStrictEqual(posExact, {
    source: 'input.js',
    line: 1,
    column: 0,
    name: 'foo'
  });
}

// 5. generatedPositionFor with GREATEST_LOWER_BOUND resolves to greatest lower bound generated position
{
  // Query between source columns: source line 1 col 5 (orig col 0 -> gen col 5, orig col 10 -> gen col 15)
  const genGLB = generatedPositionFor(tracer, {
    source: 'input.js',
    line: 1,
    column: 5,
    bias: GREATEST_LOWER_BOUND
  });
  assert.deepStrictEqual(genGLB, {
    line: 1,
    column: 5
  });

  const genLUB = generatedPositionFor(tracer, {
    source: 'input.js',
    line: 1,
    column: 5,
    bias: LEAST_UPPER_BOUND
  });
  assert.deepStrictEqual(genLUB, {
    line: 1,
    column: 15
  });
}

// 6. findOriginalPosition and findGeneratedPosition helper functions
{
  const helperPos = findOriginalPosition(tracer, { line: 1, column: 10 });
  assert.deepStrictEqual(helperPos, {
    source: 'input.js',
    line: 1,
    column: 0,
    name: 'foo'
  });

  const helperGen = findGeneratedPosition(tracer, { source: 'input.js', line: 1, column: 5 });
  assert.deepStrictEqual(helperGen, {
    line: 1,
    column: 5
  });
}

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