@jridgewell/trace-mapping 0.3.31: originalPositionFor

# Tracing original positions with `@jridgewell/trace-mapping`

`search_known_solution` returned `NO_SAFE_MATCH` for `@jridgewell/trace-mapping.originalPositionFor` in `pkg:npm/%40jridgewell/trace-mapping@0.3.31`.

This sample demonstrates and verifies using `originalPositionFor`:
1. Generated coordinate conventions: line is 1-based, column is 0-based.
2. Exact mapping lookups return `{ source, line, column, name }` with `name` populated if present in the segment, or `null` if absent.
3. Needle columns between segment boundaries are resolved using `bias`:
   - `GREATEST_LOWER_BOUND` (default) selects the preceding segment.
   - `LEAST_UPPER_BOUND` selects the subsequent segment.
4. Out-of-bounds or unmapped queries return `{ source: null, line: null, column: null, name: null }` safely without throwing exceptions.
5. Works across both encoded (VLQ string) and decoded (array of segments) source map structures via `TraceMap`.

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.originalPositionFor 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.originalPositionFor
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:29a3ced7a0ca4db346cd2870c5282d766e3c6395fd85c987b8f0e4d3c72226ba","constraints":{"executionContext":"node"},"contract":["originalPositionFor resolves 1-based line and 0-based column to source file, 1-based original line, 0-based original column, and name identifier when mapped.","originalPositionFor returns name: null when the mapped segment does not contain a name index.","When needle column falls between segments, bias GREATEST_LOWER_BOUND chooses the preceding segment and LEAST_UPPER_BOUND chooses the succeeding segment.","Queries for unmapped lines or positions before the first segment return an object with all null properties instead of throwing.","TraceMap parses both encoded VLQ mapping strings and decoded segment arrays for originalPositionFor lookup."],"goal":"verify @jridgewell/trace-mapping.originalPositionFor 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.originalPositionFor"]},"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.originalPositionFor"],"verifierAdapter":"node-typescript@1"}

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

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

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

/**
 * Traces a generated line and column position back to its original source position.
 * Line is 1-based, column is 0-based.
 *
 * @param {import('@jridgewell/trace-mapping').SourceMapInput} map
 * @param {number} line
 * @param {number} column
 * @param {import('@jridgewell/trace-mapping').Bias} [bias]
 * @returns {import('@jridgewell/trace-mapping').OriginalMapping | import('@jridgewell/trace-mapping').InvalidOriginalMapping}
 */
export function traceOriginalPosition(map, line, column, bias = GREATEST_LOWER_BOUND) {
  const tracer = map instanceof TraceMap ? map : new TraceMap(map);
  return originalPositionFor(tracer, { line, column, bias });
}

export { TraceMap, originalPositionFor, GREATEST_LOWER_BOUND, LEAST_UPPER_BOUND };

import assert from 'node:assert/strict';
import {
  TraceMap,
  originalPositionFor,
  GREATEST_LOWER_BOUND,
  LEAST_UPPER_BOUND
} from '@jridgewell/trace-mapping';

// 1. Encoded source map: verify exact position lookups with and without name
const encodedMap = {
  version: 3,
  file: 'bundle.js',
  sources: ['app.js'],
  sourcesContent: ['function hello() {\n  console.log("hi");\n}'],
  names: ['hello', 'log'],
  // line 1: col 0 -> app.js:1:0 (name: hello), col 9 -> app.js:1:9 (no name)
  // line 2: col 2 -> app.js:2:2 (name: log), col 14 -> app.js:2:14 (no name)
  mappings: 'AAAAA,SAAS;EACPC,YAAY'
};

const tracerEncoded = new TraceMap(encodedMap);

// Exact match with name identifier
const pos1 = originalPositionFor(tracerEncoded, { line: 1, column: 0 });
assert.deepStrictEqual(pos1, {
  source: 'app.js',
  line: 1,
  column: 0,
  name: 'hello'
});

// Exact match without name identifier
const pos2 = originalPositionFor(tracerEncoded, { line: 1, column: 9 });
assert.deepStrictEqual(pos2, {
  source: 'app.js',
  line: 1,
  column: 9,
  name: null
});

// 2. Bias selection when needle column falls between mapping segments
// Between column 0 and column 9 on line 1:
const posDefault = originalPositionFor(tracerEncoded, { line: 1, column: 4 });
assert.deepStrictEqual(posDefault, {
  source: 'app.js',
  line: 1,
  column: 0,
  name: 'hello'
}, 'Default bias must be GREATEST_LOWER_BOUND');

const posGLB = originalPositionFor(tracerEncoded, { line: 1, column: 4, bias: GREATEST_LOWER_BOUND });
assert.deepStrictEqual(posGLB, {
  source: 'app.js',
  line: 1,
  column: 0,
  name: 'hello'
});

const posLUB = originalPositionFor(tracerEncoded, { line: 1, column: 4, bias: LEAST_UPPER_BOUND });
assert.deepStrictEqual(posLUB, {
  source: 'app.js',
  line: 1,
  column: 9,
  name: null
});

// 3. Unmapped line or column before first segment returns all-null object without error
const unmappedLine = originalPositionFor(tracerEncoded, { line: 99, column: 0 });
assert.deepStrictEqual(unmappedLine, {
  source: null,
  line: null,
  column: null,
  name: null
});

const unmappedBeforeCol = originalPositionFor(tracerEncoded, { line: 2, column: 0 });
assert.deepStrictEqual(unmappedBeforeCol, {
  source: null,
  line: null,
  column: null,
  name: null
});

// 4. Decoded source map: verify TraceMap creation and originalPositionFor mapping
const decodedMap = {
  version: 3,
  sources: ['entry.js'],
  names: ['foo'],
  mappings: [
    [
      [0, 0, 0, 0, 0], // genCol:0, srcIdx:0, srcLine:0, srcCol:0, nameIdx:0
      [10, 0, 0, 10]    // genCol:10, srcIdx:0, srcLine:0, srcCol:10
    ]
  ]
};

const tracerDecoded = new TraceMap(decodedMap);
const decodedPos = originalPositionFor(tracerDecoded, { line: 1, column: 0 });
assert.deepStrictEqual(decodedPos, {
  source: 'entry.js',
  line: 1,
  column: 0,
  name: 'foo'
});

console.log('All trace-mapping.originalPositionFor contract assertions passed.');