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
takikawa wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Range mappings: spec text for proposal #233

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
84cb0cd
Range mappings: add spec text for decoding, parsing, and lookup (#232)
takikawa Oct 20, 2025
6f1d343
Range mappings: quick fixes for review feedback (#234)
takikawa Nov 14, 2025
1f349be
Range mappings: refactor decoding out of mapping decoding (#235)
takikawa Nov 14, 2025
cd34a78
Range mappings: Change index encoding to start at 0 (#252)
takikawa Apr 15, 2026
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
234 changes: 231 additions & 3 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": "B;;A",
"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 @@ -683,6 +685,9 @@
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>Let _rangeMappings_ be DecodeRangeMappings(_rangeMappingsField_).</ins>
1. <ins>Perform UpdateMappingsForRangeMappings(_mappings_, _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 @@ -960,7 +969,7 @@
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_.
</emu-alg>
<emu-grammar>
Expand All @@ -986,7 +995,7 @@
1. Perform DecodeMappingsField of |Name| with arguments _state_, _mappings_, _names_ and _sources_.
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. Let _decodedMapping_ be a new DecodedMappingRecord { [[GeneratedPosition]]: _generatedPosition_, [[OriginalPosition]]: _originalPosition_, [[Name]]: _name_, <ins>[[IsRangeMapping]]: *false*</ins> }.
1. Append _decodedMapping_ to _mappings_.
</emu-alg>
<emu-grammar>
Expand Down Expand Up @@ -1119,6 +1128,199 @@
</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 following fields.</p>
<emu-table id="table-decode-range-mapping-state-record-fields" caption="Fields of Decode Range Mappings State 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 or ~none~</td>
</tr>
</table>
</emu-table>

<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 ~none~.
1. Perform DecodeRangeMappingsField of |RangeMappingLineList| with arguments _state_ and _rangeMappings_.
</emu-alg>
<emu-grammar>
RangeMappingLine : [empty]
</emu-grammar>
<emu-alg>
1. Return.
</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_ and _rangeMappings_.
</emu-alg>
<emu-grammar>
RangeMapping :
Vlq
</emu-grammar>
<emu-alg>
1. Let _relativeIndex_ be the VLQUnsignedValue of |Vlq|.
1. If _relativeIndex_ = 0 and _state_.[[MappingIndex]] is not ~none~, then
1. Optionally report an error.
Comment thread
jridgewell marked this conversation as resolved.
1. If _state_.[[MappingIndex]] is ~none~, then
1. Set _state_.[[MappingIndex]] to _relativeIndex_.
1. Else,
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. Append _rangeMappingOffset_ to _rangeMappings_.
</emu-alg>
</emu-clause>

<emu-clause id="sec-DecodeRangeMappings" type="abstract operation">
<h1>
DecodeRangeMappings (
_rawRangeMappings_: a String or *null*,
): a List of Decoded Range Mapping Offset Records
</h1>
<dl class="header"></dl>
<emu-alg>
1. Let _rangeMappings_ be a new empty List.
1. If _rawRangeMappings_ is *null*, return _rangeMappings_.
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 { [[GeneratedLine]]: 0, [[MappingIndex]]: ~none~ }.
1. Perform DecodeRangeMappingsField of _rangeMappingsNode_ with arguments _state_ and _rangeMappings_.
1. Return _rangeMappings_.
</emu-alg>
</emu-clause>

<emu-clause id="sec-UpdateMappingsForRangeMapping" type="abstract operation">
<h1>
UpdateMappingsForRangeMappings (
_mappings_: a List of Decoded Mapping Records,
_rangeMappingsOffsets_: a List of Decoded Range Mapping Offset Records,
): ~unused~
</h1>
<dl class="header"></dl>
<emu-alg>
1. For each Decoded Range Mapping Offset Record _rangeMappingOffset_ of _rangeMappingsOffsets_, do
1. Let _mapping_ be the result of FindMappingForRangeMappingOffset(_mappings_, _rangeMappingOffset_).
1. If _mapping_ is ~not-found~, then
1. Optionally report an error.
1. Else,
1. If _mapping_.[[OriginalPosition]] is *null*, optionally report an error.
1. Assert: _mapping_.[[IsRangeMapping]] is *false*.
1. Set _mapping_.[[IsRangeMapping]] to *true*.
</emu-alg>
</emu-clause>

<emu-clause id="sec-FindMappingForRangeMappingOffset" type="abstract operation">
<h1>
FindMappingForRangeMappingOffset (
_mappings_: a List of Decoded Mapping Records,
_offset_: a Decoded Range Mapping Offset Record,
): a Decoded Mapping Record or ~not-found~
</h1>
<dl class="header"></dl>
<emu-alg>
1. Let _currentLine_ be *null*.
Copy link
Copy Markdown
Member

@jridgewell jridgewell Feb 28, 2026

Choose a reason for hiding this comment

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

Nit: -1, so we have a consistent number type?

1. Let _currentIndex_ be 0.
1. For each Decoded Mapping Record _mapping_ of _mappings_, do
1. If _currentLine_ ≠ _mapping_.[[GeneratedLine]], then
1. Set _currentLine_ to _mapping_.[[GeneratedLine]].
1. Set _currentIndex_ to 0.
1. Else,
1. Set _currentIndex_ to _currentIndex_ + 1.
1. If _currentLine_ = _offset_.[[GeneratedLine]] and _currentIndex_ = _offset_.[[MappingIndex]], then
1. Return _mapping_.
Comment on lines +1315 to +1318
Copy link
Copy Markdown
Member

@jridgewell jridgewell Feb 28, 2026

Choose a reason for hiding this comment

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

Nit:

Suggested change
1. Else,
1. Set _currentIndex_ to _currentIndex_ + 1.
1. If _currentLine_ = _offset_.[[GeneratedLine]] and _currentIndex_ = _offset_.[[MappingIndex]], then
1. Return _mapping_.
1. If _currentLine_ = _offset_.[[GeneratedLine]] and _currentIndex_ = _offset_.[[MappingIndex]], then
1. Return _mapping_.
1. Set _currentIndex_ to _currentIndex_ + 1.

1. Return ~not-found~.
</emu-alg>
</emu-clause>
</emu-clause>
</ins>
</emu-clause>

<emu-clause id="sec-sources">
Expand Down Expand Up @@ -1570,10 +1772,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 1572 to +1775
Copy link
Copy Markdown
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
Loading