Skip to content

Spec: add algorithm for retrieving original position #195

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Spec: add algorithm for retrieving original position #195

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cd17d6f
Add algorithm for retrieving original positions
takikawa Apr 8, 2025
396b12b
Return an original position instead of the entry
takikawa Sep 3, 2025
7f57d00
Use "last" instead of "closest" in GetOriginalPosition
takikawa Sep 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 30 additions & 3 deletions spec.emu
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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~.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why move this?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Previously the sort was only done below in the index map algorithm to check validity. It's moved here so that decoded mappings are guaranteed to be sorted, because otherwise the search algorithm for looking up positions is slower.

1. Return the Decoded Source Map Record { [[File]]: _fileField_, [[Sources]]: _sources_, [[Mappings]]: _mappings_ }.
</emu-alg>

Expand Down Expand Up @@ -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>

Expand Down Expand Up @@ -1539,6 +1539,33 @@ 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>

<emu-clause id="sec-GetOriginalPosition" type="abstract operation">
<h1>
GetOriginalPosition (
_sourceMapRecord_: a Decoded Source Map Record,
_generatedPosition_: a Position Record,
): an Original Position Record or *null*
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also changed this to return the original position record instead of the entry. Given the name of the operation it probably makes more sense to return the position record, and that also makes a bit more sense for the range mappings proposal spec text (since you just return a modified position, rather than making up a new mapping with a modified position).

This should also be ok for PR #219 which only uses the original position part.

</h1>
<dl class="header"></dl>
<emu-alg>
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]].
</emu-alg>
</emu-clause>
</emu-clause>

<emu-annex id="sec-conventions">
<h1>Conventions</h1>

Expand Down