Add algorithms for retrieving original & generated positions

Introduces a new section with algorithms for using Decoded Source Map Records
in order to perform lookups. For generated positions, a list of matching
positions is returned.

Additionally, this introduces an explicit sort of the mappings
when they are put in a decoded source map record. This makes the algorithms
more straightforward.

Author: takikawa

spec.emu

@@ -489,7 +489,7 @@
 
   <emu-clause id="sec-position-record-type">
     <h1>Position Record</h1>
-    <p>A <dfn>Position Record</dfn> is a tuple of a non-negative line and non-negative column number:</p>
+    <p>A <dfn variants="Position Records">Position Record</dfn> is a tuple of a non-negative line and non-negative column number:</p>
     <emu-table id="table-position-record-fields" caption="Position Record Fields">
       <table>
         <thead>
@@ -683,6 +683,7 @@
         1. Let _sources_ be DecodeSourceMapSources(_baseURL_, _sourceRootField_, _sourcesField_, _sourcesContentField_, _ignoreListField_).
         1. Let _namesField_ be GetOptionalListOfStrings(_json_, *"names"*).
         1. Let _mappings_ be DecodeMappings(_mappingsField_, _namesField_, _sources_).
+        1. [declared="a,b"] Sort _mappings_ in ascending order, with a Decoded Mapping Record _a_ being less than a Decoded Mapping Record _b_ if ComparePositions(_a_.[[GeneratedPosition]], _b_.[[GeneratedPosition]]) is ~lesser~.
         1. Return the Decoded Source Map Record { [[File]]: _fileField_, [[Sources]]: _sources_, [[Mappings]]: _mappings_ }.
       </emu-alg>
 
@@ -1264,8 +1265,7 @@
               1. Append _mapping_ to _offsetMappings_.
             1. Set _sourceMap_.[[Mappings]] to the list-concatenation of _sourceMap_.[[Mappings]] and _offsetMappings_.
             1. Set _previousOffsetPosition_ to _offsetPosition_.
-            1. [declared="a,b"] Let _sortedMappings_ be a copy of _offsetMappings_, sorted in ascending order, with a Decoded Mapping Record _a_ being less than a Decoded Mapping Record _b_ if ComparePositions(_a_.[[GeneratedPosition]], _b_.[[GeneratedPosition]]) is ~lesser~.
-            1. If _sortedMappings_ is not empty, set _previousLastMapping_ to the last element of _sortedMappings_.
+            1. If _offsetMappings_ is not empty, set _previousLastMapping_ to the last element of _offsetMappings_.
         1. Return _sourceMap_.
     </emu-alg>
 
@@ -1539,6 +1539,75 @@ return lastURL;</code></pre>
   </emu-clause>
 </emu-clause>
 
+<emu-clause id="sec-operations-on-source-map-records">
+  <h1>Operations on source map records</h1>
+
+  <p>After decoding a source map, source map consumers can use the resulting Decoded Source Map Records to look up position information for debugging or other use cases. This section describes the behaviour of typical operations that may be supported by source map consumers.</p>
+  <p>The GetOriginalPosition operation may be used to query the position in an original source that corresponds to a position in the generated code. For example, this can be used in a debugger to navigate from the generated code to the original source based on a user's mouse click.</p>
+  <p>The GetGeneratedPositionsForOriginalLine is used to query the positions in the generated code that map to a position in the original source. There may be multiple generated code positions that map to a given original position. The result list can be further filtered, for example, to match a particular column. This operation could be used, for example, as part of setting breakpoints at all generated lines that match a particular line in the original source that a user clicks in a debugger.</p>
+
+  <emu-clause id="sec-GetOriginalPosition" type="abstract operation">
+    <h1>
+      GetOriginalPosition (
+        _sourceMapRecord_: a Decoded Source Map Record,
+        _generatedPosition_: a Position Record,
+      ): a Decoded Mapping Record or *null*
+    </h1>
+    <dl class="header"></dl>
+    <emu-alg>
+      1. Let _mappings_ be _sourceMapRecord_.[[Mappings]].
+      1. Let _closest_ be *null*.
+      1. For each element _mapping_ of _mappings_, do
+        1. If the result of performing ComparePositions(_mapping_.[[GeneratedPosition]], _generatedPosition_) is ~greater~, then
+          1. Return _closest_.
+        1. Else,
+          1. Set _closest_ to _mapping_.
+      1. Return _closest_.
+    </emu-alg>
+  </emu-clause>
+
+  <emu-clause id="sec-GetGeneratedPositionsForOriginalLine" type="abstract operation">
+    <h1>
+      GetGeneratedPositionsForOriginalLine (
+        _sourceMapRecord_: a Decoded Source Map Record,
+        _originalSource_: a Decoded Source Record,
+        _originalLine_: a non-negative integral Number,
+      ): a list of Position Records
+    </h1>
+    <dl class="header"></dl>
+    <emu-alg>
+      1. Let _mappings_ be _sourceMapRecord_.[[Mappings]].
+      1. Let _generatedPositions_ be a new empty List.
+      1. Let _reverseMappings_ be ComputeReverseMappings(_mappings_, _originalSource_).
+      1. For each element _mapping_ of _reverseMappings_, do
+        1. Let _originalPosition_ be _mapping_.[[OriginalPosition]].
+        1. If _originalPosition_ ≠ *null*, then
+          1. If _originalPosition_.[[Line]] is equal to _originalLine_, then
+            1. Append _mapping_.[[GeneratedPosition]] to _generatedPositions_.
+      1. Return _generatedPositions_.
+    </emu-alg>
+
+    <emu-clause id="sec-ComputeReverseMappings" type="abstract operation">
+      <h1>
+        ComputeReverseMappings (
+          _mappings_: a list of Decoded Mapping Records,
+          _originalSource_: a Decoded Source Record,
+        ): a list of Decoded Mapping Records
+      </h1>
+      <dl class="header"></dl>
+      <emu-alg>
+        1. Let _reverseMappings_ be a new empty List.
+        1. For each element _mapping_ of _mappings_, do
+          1. If _mapping_.[[OriginalSource]] ≠ *null*, then
+            1. If _mapping_.[[OriginalSource]] and _originalSource_ are the same Decoded Source Record, then
+              1. Append _mapping_ to _reverseMappings_.
+        1. [declared="a,b"] Sort _reverseMappings_ in ascending order, with a Decoded Mapping Record _a_ being less than a Decoded Mapping Record _b_ if ComparePositions(_a_.[[GeneratedPosition]], _b_.[[GeneratedPosition]]) is ~lesser~.
+        1. Return _reverseMappings_.
+      </emu-alg>
+    </emu-clause>
+  </emu-clause>
+</emu-clause>
+
 <emu-annex id="sec-conventions">
   <h1>Conventions</h1>