Start with strict/loose decode mode

Author: szuend

mod.ts

@@ -14,7 +14,7 @@ export type {
 } from "./src/scopes.d.ts";
 
 export { encode } from "./src/encode/encode.ts";
-export { decode } from "./src/decode/decode.ts";
+export { decode, type DecodeMode } from "./src/decode/decode.ts";
 
 export { ScopeInfoBuilder } from "./src/builder/builder.ts";
 export { SafeScopeInfoBuilder } from "./src/builder/safe_builder.ts";

src/decode/decode.ts

@@ -18,10 +18,30 @@ import type {
 } from "../scopes.d.ts";
 import { TokenIterator } from "../vlq.ts";
 
-export function decode(sourceMap: SourceMapJson): ScopeInfo {
+/**
+ * The mode decides how well-formed the encoded scopes have to be, to be accepted by the decoder.
+ *
+ * LOOSE is the default and is much more lenient. It's still best effort though and the decoder doesn't
+ * implement any error recovery: e.g. superfluous "start" items can lead to whole trees being omitted.
+ *
+ * STRICT mode will throw in the following situations:
+ *
+ *   - Encountering ORIGINAL_SCOPE_END, or GENERATED_RANGE_END items that don't have matching *_START items.
+ *   - Miss-matches between the number of variables in a scope vs the number of value expressions in the ranges.
+ *   - Out-of-bound indices into the "names" array.
+ */
+export const enum DecodeMode {
+  STRICT = 1,
+  LOOSE = 2,
+}
+
+export function decode(
+  sourceMap: SourceMapJson,
+  options?: { mode: DecodeMode },
+): ScopeInfo {
   if (!sourceMap.scopes || !sourceMap.names) return { scopes: [], ranges: [] };
 
-  return new Decoder(sourceMap.scopes, sourceMap.names).decode();
+  return new Decoder(sourceMap.scopes, sourceMap.names, options).decode();
 }
 
 const DEFAULT_SCOPE_STATE = {
@@ -43,6 +63,7 @@ const DEFAULT_RANGE_STATE = {
 class Decoder {
   readonly #encodedScopes: string;
   readonly #names: string[];
+  readonly #mode: DecodeMode;
 
   #scopes: (OriginalScope | null)[] = [];
   #ranges: GeneratedRange[] = [];
@@ -56,9 +77,10 @@ class Decoder {
   readonly #countToScope = new Map<number, OriginalScope>();
   #scopeCounter = 0;
 
-  constructor(scopes: string, names: string[]) {
+  constructor(scopes: string, names: string[], options?: { mode: DecodeMode }) {
     this.#encodedScopes = scopes;
     this.#names = names;
+    this.#mode = options?.mode ?? DecodeMode.LOOSE;
   }
 
   decode(): ScopeInfo {