Add 'framework' for decoding tests with a sample scope test

decoding/README.md

@@ -0,0 +1,16 @@
+# Decoding tests
+
+This directory contains various source map files along with expectations to help implementations verify source map decoding.
+
+Each source map `<file name>.map`, is accompanied by:
+
+  * a `<file name>.map.golden` file, containing a [Decoded Source Map Record](https://tc39.es/ecma426/#decoded-source-map-record) in JSON format
+  * an optional `<file name>.map.error` file. It is present for source maps where the spec would ["optionally report an error"](https://tc39.es/ecma426/#sec-optional-errors). At the moment, the `<file name>.error` file only serves as a marker. But in the future it may be turned into a JSON with more information about the number and specifics of the expected errors.
+
+## .golden format
+
+The JSON format of the `.golden` files, attempts to follow the [Decoded Source Map Record](https://tc39.es/ecma426/#decoded-source-map-record) closely, but since the "Decoded Source Map Record" has cycles, we deviate slightly. The exact format is documented in [./source-map-record.d.ts](./source-map-record.d.ts).
+
+## Proposals
+
+Each source map proposal gets its own sub-directory. If a proposal adds new specification records or extends existing records, the sub-directory should contain a separate `<proposal>/<proposal>.d.ts` that describes the extended golden files. See [./scopes/scopes.d.ts](./scopes/scopes.d.ts) as an example. Once a proposal reaches stage 4, the `<proposal>/<proposal>.d.ts` file is merged into the [./source-map-record.d.ts](./source-map-record.d.ts).

decoding/scopes/scopes.d.ts

@@ -0,0 +1,48 @@
+
+/// <reference path="../source-map-record.d.ts" />
+
+interface SourceMapRecord {
+  ranges: GeneratedRangeRecord[];
+}
+
+interface SourceRecord {
+  scope: OriginalScopeRecord|null;
+}
+
+/**
+ * Corresponds to a [Original Scope Record](https://tc39.es/ecma426/branch/proposal-scopes/#sec-original-scope-record-type)
+ */
+interface OriginalScopeRecord {
+  start: PositionRecord;
+  end: PositionRecord;
+  name: string|null;
+  kind: string|null;
+  isStackFrame: boolean;
+  variables: string[];
+  children: OriginalScopeRecord[];
+}
+
+/**
+ * Corresponds to a [Generated Range Record](https://tc39.es/ecma426/branch/proposal-scopes/#sec-generated-range-record-type)
+ */
+interface GeneratedRangeRecord {
+  start: PositionRecord;
+  end: PositionRecord;
+  /**
+   * An index into a flattened list of {@link OriginalScopeRecord}. The flattened list is obtained by iterating
+   * {@link SourceMapRecord.sources} from `0` to `SourceMapRecord.sources.length` and traverse each {@link SourceRecord.scope} in [pre-order](https://en.wikipedia.org/wiki/Tree_traversal#Pre-order,_NLR).
+   */
+  definitionIndex: number|null;
+  stackFrameType: 'none'|'original'|'hidden';
+  bindings: BindingRecord[][];
+  callSite: OriginalPositionRecord|null;
+  children: GeneratedRangeRecord[];
+}
+
+/**
+ * Corresponds to a [Binding Record](https://tc39.es/ecma426/branch/proposal-scopes/#sec-binding-record-type)
+ */
+interface BindingRecord {
+  from: PositionRecord;
+  binding: string|null;
+}

decoding/scopes/single-root-original-scope.map

@@ -0,0 +1,12 @@
+{
+  "version": 3,
+  "file": "single-root-original-scope.js",
+  "sources": [
+    "original_0.js"
+  ],
+  "mappings": "",
+  "names": [
+    "global"
+  ],
+  "scopes": "BCAAA,CKA,ECAA,FK"
+}

decoding/scopes/single-root-original-scope.map.golden

@@ -0,0 +1,43 @@
+{
+  "file": "single-root-original-scope.js",
+  "mappings": [],
+  "sources": [
+    {
+      "url": "original_0.js",
+      "content": null,
+      "ignored": false,
+      "scope": {
+        "start": {
+          "line": 0,
+          "column": 0
+        },
+        "end": {
+          "line": 10,
+          "column": 0
+        },
+        "name": null,
+        "kind": "global",
+        "isStackFrame": false,
+        "variables": [],
+        "children": []
+      }
+    }
+  ],
+  "ranges": [
+    {
+      "start": {
+        "line": 0,
+        "column": 0
+      },
+      "end": {
+        "line": 0,
+        "column": 10
+      },
+      "definitionIndex": 0,
+      "stackFrameType": "none",
+      "callSite": null,
+      "bindings": [],
+      "children": []
+    }
+  ]
+}

decoding/source-map-record.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The global type of a .golden JSON.
+ */
+interface SourceMapRecord {
+  file: string|null;
+  sources: SourceRecord[];
+  mappings: MappingRecord[];
+}
+
+/**
+ * Corresponds to a [Decoded Source Record](https://tc39.es/ecma426/#decoded-source-record)
+ */
+interface SourceRecord {
+  url: string|null;
+  content: string|null;
+  ignored: boolean;
+}
+
+/**
+ * Corresponds to a [Decoded Mapping Record](https://tc39.es/ecma426/#decoded-mapping-record)
+ */
+interface MappingRecord {
+  generatedPosition: PositionRecord;
+  originalPosition: OriginalPositionRecord|null;
+  name: string|null;
+}
+
+/**
+ * Corresponds to a [Position Record](https://tc39.es/ecma426/#sec-position-record-type)
+ */
+interface PositionRecord {
+  line: number;
+  column: number;
+}
+
+/**
+ * Corresponds to a [Original Position Record](https://tc39.es/ecma426/#sec-original-position-record-type)
+ */
+interface OriginalPositionRecord {
+  /** An index into {@link SourceMapRecord.sources}. */
+  sourceIndex: number;
+  line: number;
+  column: number;
+}