feat: Add support for index source maps

Author: szuend

src/decode/decode.test.ts

@@ -13,7 +13,7 @@ import {
 } from "jsr:@std/assert";
 import { encodeSigned, encodeUnsigned } from "../vlq.ts";
 import { decode, DecodeMode } from "./decode.ts";
-import type { SourceMapJson } from "../scopes.d.ts";
+import type { IndexSourceMapJson, SourceMapJson } from "../scopes.d.ts";
 import { GeneratedRangeFlags, OriginalScopeFlags, Tag } from "../codec.ts";
 
 class ItemEncoder {
@@ -492,4 +492,69 @@ describe("decode", () => {
       ],
     ]);
   });
+
+  it("applies 'generatedOffset' option correctly for line 0", () => {
+    const scopes = new ScopeInfoBuilder().startRange(0, 0).endRange(0, 10)
+      .build();
+    const map = encode(scopes);
+
+    const info = decode(map, { generatedOffset: { line: 0, column: 20 } });
+
+    assertEquals(info.ranges[0].start, { line: 0, column: 20 });
+    assertEquals(info.ranges[0].end, { line: 0, column: 30 });
+  });
+
+  it("applies 'generatedOffset' option correctly for non-zero line and column", () => {
+    const scopes = new ScopeInfoBuilder().startRange(0, 10).endRange(0, 20)
+      .build();
+    const map = encode(scopes);
+
+    const info = decode(map, { generatedOffset: { line: 2, column: 5 } });
+
+    assertEquals(info.ranges[0].start, { line: 2, column: 15 });
+    assertEquals(info.ranges[0].end, { line: 2, column: 25 });
+  });
+
+  it("decodes index source maps", () => {
+    const map1 = encode(
+      new ScopeInfoBuilder().startRange(0, 0).endRange(0, 10)
+        .build(),
+    );
+    const map2 = encode(
+      new ScopeInfoBuilder().startRange(0, 0).endRange(1, 20)
+        .build(),
+    );
+    const map: IndexSourceMapJson = {
+      version: 3,
+      sections: [
+        { offset: { line: 0, column: 0 }, map: map1 },
+        { offset: { line: 1, column: 42 }, map: map2 },
+      ],
+    };
+
+    const info = decode(map);
+
+    assertEquals(info.ranges[0].start, { line: 0, column: 0 });
+    assertEquals(info.ranges[0].end, { line: 0, column: 10 });
+    assertEquals(info.ranges[1].start, { line: 1, column: 42 });
+    assertEquals(info.ranges[1].end, { line: 2, column: 20 });
+  });
+
+  it("ignores 'generatedOffset' option for index source maps", () => {
+    const map1 = encode(
+      new ScopeInfoBuilder().startRange(0, 0).endRange(0, 10)
+        .build(),
+    );
+    const map: IndexSourceMapJson = {
+      version: 3,
+      sections: [
+        { offset: { line: 0, column: 0 }, map: map1 },
+      ],
+    };
+
+    const info = decode(map, { generatedOffset: { line: 4, column: 42 } });
+
+    assertEquals(info.ranges[0].start, { line: 0, column: 0 });
+    assertEquals(info.ranges[0].end, { line: 0, column: 10 });
+  });
 });

src/decode/decode.ts

@@ -11,8 +11,11 @@ import {
 } from "../codec.ts";
 import type {
   GeneratedRange,
+  IndexSourceMapJson,
   OriginalScope,
+  Position,
   ScopeInfo,
+  SourceMap,
   SourceMapJson,
   SubRangeBinding,
 } from "../scopes.d.ts";
@@ -37,15 +40,64 @@ export const enum DecodeMode {
   LAX = 2,
 }
 
+export interface DecodeOptions {
+  mode: DecodeMode;
+
+  /**
+   * Offsets `start` and `end` of all generated ranges by the specified amount.
+   * Intended to be used when decoding sections of index source maps one-by-one.
+   *
+   * Has no effect when passing a {@link IndexSourceMapJson} directly to {@link decode}.
+   */
+  generatedOffset: Position;
+}
+
+export const DEFAULT_DECODE_OPTIONS: DecodeOptions = {
+  mode: DecodeMode.LAX,
+  generatedOffset: { line: 0, column: 0 },
+};
+
 export function decode(
+  sourceMap: SourceMap,
+  options: Partial<DecodeOptions> = DEFAULT_DECODE_OPTIONS,
+): ScopeInfo {
+  const opts = { ...DEFAULT_DECODE_OPTIONS, ...options };
+  if ("sections" in sourceMap) {
+    return decodeIndexMap(sourceMap, {
+      ...opts,
+      generatedOffset: { line: 0, column: 0 },
+    });
+  }
+  return decodeMap(sourceMap, opts);
+}
+
+function decodeMap(
   sourceMap: SourceMapJson,
-  options?: { mode: DecodeMode },
+  options: DecodeOptions,
 ): ScopeInfo {
   if (!sourceMap.scopes || !sourceMap.names) return { scopes: [], ranges: [] };
 
   return new Decoder(sourceMap.scopes, sourceMap.names, options).decode();
 }
 
+function decodeIndexMap(
+  sourceMap: IndexSourceMapJson,
+  options: DecodeOptions,
+): ScopeInfo {
+  const scopeInfo: ScopeInfo = { scopes: [], ranges: [] };
+
+  for (const section of sourceMap.sections) {
+    const { scopes, ranges } = decode(section.map, {
+      ...options,
+      generatedOffset: section.offset,
+    });
+    for (const scope of scopes) scopeInfo.scopes.push(scope);
+    for (const range of ranges) scopeInfo.ranges.push(range);
+  }
+
+  return scopeInfo;
+}
+
 const DEFAULT_SCOPE_STATE = {
   line: 0,
   column: 0,
@@ -77,10 +129,12 @@ class Decoder {
   #flatOriginalScopes: OriginalScope[] = [];
   #subRangeBindingsForRange = new Map<number, [number, number, number][]>();
 
-  constructor(scopes: string, names: string[], options?: { mode: DecodeMode }) {
+  constructor(scopes: string, names: string[], options: DecodeOptions) {
     this.#encodedScopes = scopes;
     this.#names = names;
-    this.#mode = options?.mode ?? DecodeMode.LAX;
+    this.#mode = options.mode;
+    this.#rangeState.line = options.generatedOffset.line;
+    this.#rangeState.column = options.generatedOffset.column;
   }
 
   decode(): ScopeInfo {

src/scopes.d.ts

@@ -159,6 +159,19 @@ export interface OriginalPosition extends Position {
   sourceIndex: number;
 }
 
+/**
+ * A standard source map, or index source map as per https://tc39.es/ecma426.
+ */
+export type SourceMap = SourceMapJson | IndexSourceMapJson;
+
+/**
+ * A standard index source map json object as per https://tc39.es/ecma426.
+ */
+export interface IndexSourceMapJson {
+  version: 3;
+  sections: Array<{ offset: Position; map: SourceMapJson }>;
+}
+
 /**
  * A standard source map json object as per https://tc39.es/ecma426.
  */