Skip to content

Range mappings: spec text for proposal #233

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 1 commit into
base: main
Choose a base branch
from
Open

Range mappings: spec text for proposal #233

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
211 changes: 196 additions & 15 deletions spec.emu
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -572,6 +572,7 @@
"sourcesContent": [null, null],
"names": ["src", "maps", "are", "fun"],
"mappings": "A,AAAB;;ABCDE",
"rangeMappings": "C;;B",
"ignoreList": [0]
}
</code></pre>
Expand All @@ -583,6 +584,7 @@
<li>The <dfn id="json-sourcesContent"><code>sourcesContent</code> field</dfn> is an optional list of source content (i.e. the original source) strings, used when the source cannot be hosted. The contents are listed in the same order as in the sources field. Entries may be *null* if some <emu-xref href="#sec-terms-and-definitions-original-source">original sources</emu-xref> should be retrieved by name.</li>
<li>The <dfn id="json-names"><code>names</code> field</dfn> is an optional list of symbol names which may be used by the mappings field.</li>
<li>The <dfn id="json-mappings"><code>mappings</code> field</dfn> is a string with the encoded mapping data (see section <emu-xref href="#sec-mappings"></emu-xref>).</li>
<ins class="block"><li>The <dfn id="json-rangeMappings"><code>rangeMappings</code> field</dfn> is a string with the encoded range mappings data (see section <emu-xref href="#sec-rangeMappings"></emu-xref>).</li></ins>
<li>The <dfn id="json-ignoreList"><code>ignoreList</code> field</dfn> is an optional list of indices of files that should be considered third party code, such as framework code or bundler-<emu-not-ref>generated code</emu-not-ref>. This allows developer tools to avoid code that developers likely don't want to see or step through, without requiring developers to configure this beforehand. It refers to the sources field and lists the indices of all the known third-party sources in the source map. Some browsers may also use the deprecated `x_google_ignoreList` field if `ignoreList` is not present.</li>
</ul>

Expand Down Expand Up @@ -682,7 +684,10 @@
1. Let _ignoreListField_ be GetOptionalListOfArrayIndexes(_json_, *"ignoreList"*).
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. <ins>Let _rangeMappingsField_ be GetOptionalString(_json_, *"rangeMappings"*).</ins>
1. <ins>If _rangeMappingsField_ is *null*, set _rangeMappingsField_ to *""*.</ins>
1. <ins>Let _rangeMappings_ be DecodeRangeMappings(_rangeMappingsField_).</ins>
1. Let _mappings_ be DecodeMappings(_mappingsField_, _namesField_, _sources_, <ins>_rangeMappings_</ins>).
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>
Expand Down Expand Up @@ -834,6 +839,10 @@
<td>[[Name]]</td>
<td>a String or *null*</td>
</tr>
<tr>
<td><ins>[[IsRangeMapping]]</ins></td>
<td><ins>a Boolean</ins></td>
</tr>
</table>
</emu-table>

Expand Down Expand Up @@ -913,6 +922,10 @@
<td>[[NameIndex]]</td>
<td>a non-negative integer</td>
</tr>
<tr>
<td><ins>[[MappingIndex]]</ins></td>
<td><ins>a non-negative integer</ins></td>
</tr>
</table>
</emu-table>

Expand All @@ -923,6 +936,7 @@
_mappings_: a List of Decoded Mapping Records,
_names_: a List of Strings,
_sources_: a List of Decoded Source Records,
<ins>_rangeMappings_: a List of of Decoded Range Mapping Offset Records,</ins>
)
</h1>
<dl class="header"></dl>
Expand All @@ -931,10 +945,11 @@
Line `;` LineList
</emu-grammar>
<emu-alg>
1. Perform DecodeMappingsField of |Line| with arguments _state_, _mappings_, _names_ and _sources_.
1. Perform DecodeMappingsField of |Line| with arguments _state_, _mappings_, _names_<ins>,</ins> <del>and</del> _sources_ <ins>and _rangeMappings_</ins>.
1. Set _state_.[[GeneratedLine]] to _state_.[[GeneratedLine]] + 1.
1. Set _state_.[[GeneratedColumn]] to 0.
1. Perform DecodeMappingsField of |LineList| with arguments _state_, _mappings_, _names_ and _sources_.
1. <ins>Set _state_.[[MappingIndex]] to 0.</ins>
1. Perform DecodeMappingsField of |LineList| with arguments _state_, _mappings_, _names_<ins>,</ins> <del>and</del> _sources_ <ins>and _rangeMappings_</ins>.
</emu-alg>
<emu-grammar>
Line : [empty]
Expand All @@ -947,47 +962,50 @@
Mapping `,` MappingList
</emu-grammar>
<emu-alg>
1. Perform DecodeMappingsField of |Mapping| with arguments _state_, _mappings_, _names_ and _sources_.
1. Perform DecodeMappingsField of |MappingList| with arguments _state_, _mappings_, _names_ and _sources_.
1. Perform DecodeMappingsField of |Mapping| with arguments _state_, _mappings_, _names_<ins>,</ins> <del>and</del> _sources_ <ins>and _rangeMappings_</ins>.
1. Perform DecodeMappingsField of |MappingList| with arguments _state_, _mappings_, _names_<ins>,</ins> <del>and</del> _sources_ <ins>and _rangeMappings_</ins>.
</emu-alg>
<emu-grammar>
Mapping :
GeneratedColumn
</emu-grammar>
<emu-alg>
1. Perform DecodeMappingsField of |GeneratedColumn| with arguments _state_, _mappings_, _names_ and _sources_.
1. Perform DecodeMappingsField of |GeneratedColumn| with arguments _state_, _mappings_, _names_<ins>,</ins> <del>and</del> _sources_ <ins>and _rangeMappings_</ins>.
1. If _state_.[[GeneratedColumn]] &lt; 0, then
1. Optionally report an error.
1. Return.
1. Let _position_ be a new Position Record { [[Line]]: _state_.[[GeneratedLine]], [[Column]]: _state_.[[GeneratedColumn]] }.
1. Let _decodedMapping_ be a new DecodedMappingRecord { [[GeneratedPosition]]: _position_, [[OriginalPosition]]: *null*, [[Name]]: *null* }.
1. Let _decodedMapping_ be a new DecodedMappingRecord { [[GeneratedPosition]]: _position_, [[OriginalPosition]]: *null*, [[Name]]: *null*, <ins>[[IsRangeMapping]]: *false*</ins> }.
1. Append _decodedMapping_ to _mappings_.
1. <ins>Set _state_.[[MappingIndex]] to _state_.[[MappingIndex]] + 1.</ins>
</emu-alg>
<emu-grammar>
Mapping :
GeneratedColumn OriginalSource OriginalLine OriginalColumn Name?
</emu-grammar>
<emu-alg>
1. Perform DecodeMappingsField of |GeneratedColumn| with arguments _state_, _mappings_, _names_ and _sources_.
1. Perform DecodeMappingsField of |GeneratedColumn| with arguments _state_, _mappings_, _names_<ins>,</ins> <del>and</del> _sources_ <ins>and _rangeMappings_</ins>.
1. If _state_.[[GeneratedColumn]] &lt; 0, then
1. Optionally report an error.
1. Return.
1. Let _generatedPosition_ be a new Position Record { [[Line]]: _state_.[[GeneratedLine]], [[Column]]: _state_.[[GeneratedColumn]] }.
1. Perform DecodeMappingsField of |OriginalSource| with arguments _state_, _mappings_, _names_ and _sources_.
1. Perform DecodeMappingsField of |OriginalLine| with arguments _state_, _mappings_, _names_ and _sources_.
1. Perform DecodeMappingsField of |OriginalColumn| with arguments _state_, _mappings_, _names_ and _sources_.
1. Perform DecodeMappingsField of |OriginalSource| with arguments _state_, _mappings_, _names_<ins>,</ins> <del>and</del> _sources_ <ins>and _rangeMappings_</ins>.
1. Perform DecodeMappingsField of |OriginalLine| with arguments _state_, _mappings_, _names_<ins>,</ins> <del>and</del> _sources_ <ins>and _rangeMappings_</ins>.
1. Perform DecodeMappingsField of |OriginalColumn| with arguments _state_, _mappings_, _names_<ins>,</ins> <del>and</del> _sources_ <ins>and _rangeMappings_</ins>.
1. If _state_.[[SourceIndex]] &lt; 0 or _state_.[[SourceIndex]] ≥ the number of elements of _sources_ or _state_.[[OriginalLine]] &lt; 0 or _state_.[[OriginalColumn]] &lt; 0, then
1. Optionally report an error.
1. Let _originalPosition_ be *null*.
1. Else,
1. Let _originalPosition_ be a new Original Position Record { [[Source]]: _sources_[_state_.[[SourceIndex]]], [[Line]]: _state_.[[OriginalLine]], [[Column]]: _state_.[[OriginalColumn]] }.
1. Let _name_ be *null*.
1. If |Name| is present, then
1. Perform DecodeMappingsField of |Name| with arguments _state_, _mappings_, _names_ and _sources_.
1. Perform DecodeMappingsField of |Name| with arguments _state_, _mappings_, _names_<ins>,</ins> <del>and</del> _sources_ <ins>and _rangeMappings_</ins>.
1. If _state_.[[NameIndex]] &lt; 0 or _state_.[[NameIndex]] ≥ the number of elements of _names_, optionally report an error.
1. Else, set _name_ to _names_[_state_.[[NameIndex]]].
1. Let _decodedMapping_ be a new DecodedMappingRecord { [[GeneratedPosition]]: _generatedPosition_, [[OriginalPosition]]: _originalPosition_, [[Name]]: _name_ }.
1. <ins>Let _isRangeMapping_ be the result of performing LookupRangeMapping with arguments _rangeMappings_, _state.[[GeneratedLine]], and _state.[[MappingIndex]].</ins>
Copy link
Member

@nicolo-ribaudo nicolo-ribaudo Oct 23, 2025

Choose a reason for hiding this comment

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

Suggested change
1. <ins>Let _isRangeMapping_ be the result of performing LookupRangeMapping with arguments _rangeMappings_, _state.[[GeneratedLine]], and _state.[[MappingIndex]].</ins>
1. <ins>Let _isRangeMapping_ be the result of performing LookupRangeMapping with arguments _rangeMappings_, _state_.[[GeneratedLine]], and _state_.[[MappingIndex]].</ins>

1. Let _decodedMapping_ be a new DecodedMappingRecord { [[GeneratedPosition]]: _generatedPosition_, [[OriginalPosition]]: _originalPosition_, [[Name]]: _name_, <ins>[[IsRangeMapping]]: _isRangeMapping_</ins> }.
1. Append _decodedMapping_ to _mappings_.
1. <ins>Set _state_.[[MappingIndex]] to _state_.[[MappingIndex]] + 1.</ins>
</emu-alg>
<emu-grammar>
GeneratedColumn :
Expand Down Expand Up @@ -1038,6 +1056,7 @@
_rawMappings_: a String,
_names_: a List of Strings,
_sources_: a List of Decoded Source Records,
<ins>_rangeMappings_: a List of Decoded Range Mapping Offset Records,</ins>
): a List of Decoded Mapping Record
</h1>
<dl class="header"></dl>
Expand All @@ -1048,7 +1067,7 @@
1. Optionally report an error.
1. Return _mappings_.
1. Let _state_ be a new Decode Mapping State Record with all fields set to 0.
1. Perform DecodeMappingsField of _mappingsNode_ with arguments _state_, _mappings_, _names_ and _sources_.
1. Perform DecodeMappingsField of _mappingsNode_ with arguments _state_, _mappings_, _names_<ins>,</ins> <del>and</del> _sources_ <ins>and _rangeMappings_</ins>.
1. Return _mappings_.
</emu-alg>
</emu-clause>
Expand Down Expand Up @@ -1119,6 +1138,142 @@
</li>
</ul>
</emu-clause>

<ins class="block">

<emu-clause id="sec-rangeMappings">
<h1>Range mappings</h1>

<p>A <dfn>range mapping</dfn> is a mapping that specifies mapped positions in the original source for a continuous range of positions in the generated code rather than for a single position. Each mapping in a source map can be specified to be a range mapping or not based on the encoded offsets in the rangeMappings field. A range mapping maps every position starting at its generated position field and ending before the generated position field of the next mapping, where the mapped original position is the mapping's original position field offset by the generated position's distance from the start of the range.</p>

<p>A <dfn id="decoded-range-mapping-record" variants="Decoded Range Mapping Offset Records">Decoded Range Mapping Offset Record</dfn> has the following fields:</p>
<emu-table id="table-decoded-range-mapping-offset-fields" caption="Fields of Decoded Range Mapping Offset Records">
<table>
<thead>
<tr>
<th>
Field Name
</th>
<th>
Value Type
</th>
</tr>
</thead>
<tr>
<td>[[GeneratedLine]]</td>
<td>a non-negative integer</td>
</tr>
<tr>
<td>[[MappingIndex]]</td>
<td>a non-negative integer</td>
</tr>
</table>
</emu-table>

<p>A <dfn id="decode-range-mappings-state-record" variants="Decode Range Mappings State Records">Decode Range Mappings State Record</dfn> has the same fields as a Decoded Range Mapping Offset Record.</p>

<emu-clause id="sec-range-mappings-grammar">
<h1>Range mappings grammar</h1>
<p>The range mappings String must adhere to the following grammar:</p>

<emu-grammar type="definition">
RangeMappingsField :
RangeMappingLineList

RangeMappingLineList :
RangeMappingLine
RangeMappingLine `;` RangeMappingLineList

RangeMappingLine :
RangeMappingList?

RangeMappingList :
RangeMapping
RangeMapping RangeMappingList

RangeMapping :
Vlq
</emu-grammar>
</emu-clause>

<emu-clause id="sec-DecodeRangeMappingsField" type="sdo">
<h1>
DecodeRangeMappingsField (
_state_: a Decode Range Mappings State Record,
_rangeMappings_: a List of Decoded Range Mapping Offset Records,
)
</h1>
<dl class="header"></dl>
<emu-grammar>
RangeMappingLineList :
RangeMappingLine `;` RangeMappingLineList
</emu-grammar>
<emu-alg>
1. Perform DecodeRangeMappingsField of |RangeMappingLine| with arguments _state_ and _rangeMappings_.
1. Set _state_.[[GeneratedLine]] to _state_.[[GeneratedLine]] + 1.
1. Set _state_.[[MappingIndex]] to 0.
1. Perform DecodeRangeMappingsField of |RangeMappingLineList| with arguments _state_ and _rangeMappings_.
</emu-alg>
<emu-grammar>
RangeMappingList :
RangeMapping RangeMappingList
</emu-grammar>
<emu-alg>
1. Perform DecodeRangeMappingsField of |RangeMapping| with arguments _state_ and _rangeMappings_.
1. Perform DecodeRangeMappingsField of |RangeMappingList| with arguments _state_, _rangeMappings_.
</emu-alg>
<emu-grammar>
RangeMapping :
Vlq
</emu-grammar>
<emu-alg>
1. Let _relativeIndex_ be the VLQUnsignedValue of |Vlq|.
1. If _relativeIndex_ is 0, then
1. Optionally report an error.
1. Set _state_.[[MappingIndex]] to _state_.[[MappingIndex]] + _relativeIndex_.
1. Let _rangeMappingOffset_ be a new Decoded Range Mapping Offset Record { [[GeneratedLine]]: _state_.[[GeneratedLine]], [[MappingIndex]]: _state_.[[MappingIndex]] - 1 }.
1. Append _rangeMappingOffset_ to _rangeMappings_.
</emu-alg>
</emu-clause>

<emu-clause id="sec-DecodeRangeMappings" type="abstract operation">
<h1>
DecodeRangeMappings (
_rawRangeMappings_: a String,
): a List of Decoded Range Mapping Offset Records
</h1>
<dl class="header"></dl>
<emu-alg>
1. Let _rangeMappings_ be a new empty List.
1. Let _rangeMappingsNode_ be the root Parse Node when parsing _rawRangeMappings_ using |RangeMappingsField| as the goal symbol.
1. If parsing failed, then
1. Optionally report an error.
1. Return _rangeMappings_.
1. Let _state_ be a new Decode Range Mappings State Record with all fields set to 0.
1. Perform DecodeRangeMappingsField of _rangeMappingsNode_ with arguments _state_ and _rangeMappings_.
1. Return _rangeMappings_.
</emu-alg>
</emu-clause>

<emu-clause id="sec-LookupRangeMapping" type="abstract operation">
<h1>
LookupRangeMapping (
_rangeMappings_: a List of Decoded Range Mapping Offset Records,
_generatedLine_: an integral Number,
_mappingIndex_: an integral Number,
): a Boolean
</h1>
<dl class="header"></dl>
<emu-alg>
1. Let _rangeMappingOffset_ be a new Decoded Range Mapping Offset Record { [[GeneratedLine]] : _generatedLine_, [[MappingIndex]]: _mappingIndex_ }.
1. If _rangeMappingOffset_ is an element of _rangeMappings_, then
1. Return *true*.
1. Else,
1. Return *false*.
</emu-alg>
</emu-clause>
</emu-clause>
</ins>
</emu-clause>

<emu-clause id="sec-sources">
Expand Down Expand Up @@ -1570,10 +1725,36 @@ return lastURL;</code></pre>
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. <ins>If _mapping_.[[IsRangeMapping]] is true, then</ins>
Comment on lines 1727 to +1728
Copy link
Member

@nicolo-ribaudo nicolo-ribaudo Oct 20, 2025

Choose a reason for hiding this comment

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

(copy-pasting my message from the other PR, to make it more visible)

If we are looking at the mappings at e here:

abcdefg

and we have none but we have two mappings right before at c, out of which one is the range mappings, maybe we should exclude the non-range one? Since the range one actually ends up being an exact match.

Not exactly sure though.

1. <ins>Append GetRangeMappedPosition(_generatedPosition_, _mapping_) to _originalPositions_.</ins>
1. <ins>Else,</ins>
1. Append _mapping_.[[OriginalPosition]] to _originalPositions_.
1. Return _originalPositions_.
</emu-alg>
</emu-clause>

<ins class="block">

<emu-clause id="sec-GetRangeMappedPosition" type="abstract operation">
<h1>
GetRangeMappedPosition (
_lookupPosition_: a Position Record,
_mapping_: a Decoded Mapping Record,
): an Original Position Record
</h1>
<dl class="header"></dl>
<emu-alg>
1. Let _lineDelta_ be _lookupPosition_.[[Line]] - _mapping_.[[GeneratedPosition]].[[Line]].
1. Assert: _lineDelta_ ≥ 0.
1. If _lineDelta_ is 0, then
1. Let _columnDelta_ be _lookupPosition_.[[Column]] - _mapping_.[[GeneratedPosition]].[[Column]].
1. Else,
1. Let _columnDelta_ be 0.
1. Assert: _columnDelta_ ≥ 0.
1. Return a new Original Position Record { [[Source]]: _mapping_.[[Source]], [[Line]]: _mapping_.[[OriginalPosition]].[[Line]] + _lineDelta_, [[Column]]: _mapping_.[[OriginalPosition]].[[Column]] + _columnDelta_ }.
</emu-alg>
</emu-clause>
</ins>
</emu-clause>

<emu-annex id="sec-conventions">
Expand Down