From c48ac6f8f41fa4e2bbcbb024297b4d1667770249 Mon Sep 17 00:00:00 2001 From: Asumu Takikawa Date: Tue, 8 Apr 2025 00:40:57 -0700 Subject: [PATCH 1/5] Add algorithm for retrieving original positions Introduces a new section with algorithms for using Decoded Source Map Records in order to perform lookups. The section is intended to have multiple operations in the future but only has one for now. Additionally, this introduces an explicit sort of the mappings when they are put in a decoded source map record. --- spec.emu | 33 ++++++++++++++++++++++++++++++--- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/spec.emu b/spec.emu index 80411e1..0b1a950 100644 --- a/spec.emu +++ b/spec.emu @@ -489,7 +489,7 @@

Position Record

-

A Position Record is a tuple of a non-negative line and non-negative column number:

+

A Position Record is a tuple of a non-negative line and non-negative column number:

@@ -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_ }. @@ -1270,8 +1271,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_. @@ -1545,6 +1545,33 @@ return lastURL; + +

Operations on source map records

+ +

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.

+

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.

+ + +

+ GetOriginalPosition ( + _sourceMapRecord_: a Decoded Source Map Record, + _generatedPosition_: a Position Record, + ): a Decoded Mapping Record or *null* +

+
+ + 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_. + + + +

Conventions

From a95121ba09e8c6e6ad53e5cc5961bdcd2f1e0bb1 Mon Sep 17 00:00:00 2001 From: Asumu Takikawa Date: Tue, 2 Sep 2025 17:19:43 -0700 Subject: [PATCH 2/5] Return an original position instead of the entry This makes more sense given the name of the function --- spec.emu | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec.emu b/spec.emu index 0b1a950..ec15879 100644 --- a/spec.emu +++ b/spec.emu @@ -1556,7 +1556,7 @@ return lastURL; GetOriginalPosition ( _sourceMapRecord_: a Decoded Source Map Record, _generatedPosition_: a Position Record, - ): a Decoded Mapping Record or *null* + ): an Original Position Record or *null*
@@ -1564,10 +1564,10 @@ return lastURL; 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. Return _closest_.[[OriginalPosition]]. 1. Else, 1. Set _closest_ to _mapping_. - 1. Return _closest_. + 1. Return _closest_.[[OriginalPosition]]. From 583d0728ba52f5751d6c46f7b770df3fc9f68d3e Mon Sep 17 00:00:00 2001 From: Asumu Takikawa Date: Fri, 5 Sep 2025 12:08:51 -0700 Subject: [PATCH 3/5] Use "last" instead of "closest" in GetOriginalPosition --- spec.emu | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/spec.emu b/spec.emu index ec15879..dfd45c6 100644 --- a/spec.emu +++ b/spec.emu @@ -1561,13 +1561,13 @@ return lastURL;
1. Let _mappings_ be _sourceMapRecord_.[[Mappings]]. - 1. Let _closest_ be *null*. + 1. Let _last_ 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_.[[OriginalPosition]]. + 1. Return _last_.[[OriginalPosition]]. 1. Else, - 1. Set _closest_ to _mapping_. - 1. Return _closest_.[[OriginalPosition]]. + 1. Set _last_ to _mapping_. + 1. Return _last_.[[OriginalPosition]]. From 48084c9a8bd280a47f567279ad7eb659b1084706 Mon Sep 17 00:00:00 2001 From: Asumu Takikawa Date: Wed, 24 Sep 2025 17:19:17 -0700 Subject: [PATCH 4/5] Change GetOriginalPosition to return a list of positions The operation now returns all matching positions by first finding the greatest lower bound and then returning all positions mapped from the same original location. Pluralized the operation name too --- spec.emu | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/spec.emu b/spec.emu index dfd45c6..43625db 100644 --- a/spec.emu +++ b/spec.emu @@ -1549,25 +1549,29 @@ return lastURL;

Operations on source map records

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.

-

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.

+

The GetOriginalPositions operation may be used to query the positions in an original source that correspond 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.

- +

- GetOriginalPosition ( + GetOriginalPositions ( _sourceMapRecord_: a Decoded Source Map Record, _generatedPosition_: a Position Record, - ): an Original Position Record or *null* + ): a List of Original Position Records

1. Let _mappings_ be _sourceMapRecord_.[[Mappings]]. 1. Let _last_ 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 _last_.[[OriginalPosition]]. - 1. Else, - 1. Set _last_ to _mapping_. - 1. Return _last_.[[OriginalPosition]]. + 1. Let _originalPositions_ be a new empty List. + 1. For each element _mapping_ of _mappings_, in reverse List order, do + 1. If the result of performing ComparePositions(_mapping_.[[GeneratedPosition]], _generatedPosition_) is ~lesser~ or ~equal~, then + 1. If _last_ is *null*, then + 1. Set _last_ to _mapping_. + 1. If _last_ is not *null*, then + 1. For each element _mapping_ of _mappings_, do + 1. If the result of performing ComparePositions(_last_.[[GeneratedPosition]], _mapping_.[[GeneratedPosition]]) is ~equal~, then + 1. Append _mapping_.[[OriginalPosition]] to _originalPositions_. + 1. Return _originalPositions_. From 7b08afd41edb2451362e893f46fce0017ede2e39 Mon Sep 17 00:00:00 2001 From: Asumu Takikawa Date: Thu, 25 Sep 2025 12:37:43 -0700 Subject: [PATCH 5/5] Swap order based on PR feedback --- spec.emu | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec.emu b/spec.emu index 43625db..140d2df 100644 --- a/spec.emu +++ b/spec.emu @@ -1564,8 +1564,8 @@ return lastURL; 1. Let _last_ be *null*. 1. Let _originalPositions_ be a new empty List. 1. For each element _mapping_ of _mappings_, in reverse List order, do - 1. If the result of performing ComparePositions(_mapping_.[[GeneratedPosition]], _generatedPosition_) is ~lesser~ or ~equal~, then - 1. If _last_ is *null*, then + 1. If _last_ is *null*, then + 1. If the result of performing ComparePositions(_mapping_.[[GeneratedPosition]], _generatedPosition_) is ~lesser~ or ~equal~, then 1. Set _last_ to _mapping_. 1. If _last_ is not *null*, then 1. For each element _mapping_ of _mappings_, do