Skip to content

Commit

Permalink
Merge branch 'main' into proposal-strict-mode
Browse files Browse the repository at this point in the history
  • Loading branch information
@jkup
jkup authored Aug 14, 2024
2 parents a965cdf + 3b640fa commit 7427d96
Show file tree
Hide file tree
Showing 2 changed files with 109 additions and 98 deletions.
75 changes: 49 additions & 26 deletions proposals/scopes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ interface SourceMap {
interface OriginalScope {
start: OriginalPosition;
end: OriginalPosition;
kind: ScopeKind;
kind: string;
/** Class/module/function name. Can be used for stack traces or naming scopes in a debugger's scope view */
name?: string;
/** Symbols defined in this scope */
Expand All @@ -152,8 +152,6 @@ interface GeneratedRange {
children?: GeneratedRange[];
}

type ScopeKind = 'global' | 'class' | 'function' | 'block';

interface BindingRange {
from: GeneratedPosition;
to: GeneratedPosition;
Expand Down Expand Up @@ -194,12 +192,10 @@ Note: Each DATA represents one VLQ number.
* Note: this is the point in the original code where the scope starts. `line` is relative to the `line` of the preceding "start/end original scope" item.
* DATA column in the original code
* Note: Column is always absolute.
* DATA kind
* DATA kind offset into `names` field
* Note: This offset is relative to the offset of the last `kind` or absolute if this is the first `kind`.
* Note: This is type of the scope.
* 0x1 toplevel
* 0x2 function
* 0x3 class
* 0x4 block
* Note: JavaScript implementations should use `'global'`, `'class'`, `'function'`, and `'block'`.
* DATA field flags
* Note: binary flags that specify if a field is used for this scope.
* Note: Unknown flags would skip the whole scope.
Expand Down Expand Up @@ -297,7 +293,37 @@ function _z(_m) {
console.log("Hello World2"); // <- Inlined
```

Scopes:
Original Scopes:

```
A| var x = 1;
|B| function z(message) {
| | let y = 2;
| | console.log(message + y);
| | }
| z("Hello World");
```

`LX CY`: Line X Column Y

```
Start Original Scope L0 C0 { // A
kind: global
field flags: none
name: none
variables: x, z
}
Start Original Scope L1 C10 { // B
kind: function
field flags: has name
name: z
variables: message, y
}
End Original Scope L4 C1 // B
End Original Scope L5 C17 // A
```

Generated Ranges:

```
A| var _x = 1;
Expand All @@ -311,38 +337,35 @@ A| var _x = 1;
`LX CY`: Line X Column Y

```
Start Scope C0 { // A
field flags: has definition
info flags:
definition: file.js L1 C0 - L6 C17
Start Generated Range C0 { // A
field flags: has definition, is scope
definition: file.js, scope offset 0
callsite: none
bindings: x -> _x, z -> _z
}
;
Start Scope C16 { // B
field flags: has name, has definition
info flags: function, inherit parent bindings
name: z
definition: file.js L2 C20 - L5 C1
Start Generated Range C16 { // B
field flags: has definition, is scope
definition: file.js, scope offset 1
callsite: none
bindings: message -> _m, y -> _y
}
;
;
;
End Scope C1 // B
End Generated Range C1 // B
;
Start Scope C0 { // C
field flags: has name, has definition, has callsite
info flags: function, inherit parent bindings
name: z
definition: file.js L2 C0 - L5 C1
callsite: file.js L6 C0
Start Generated Range C0 { // C
field flags: has definition, has callsite
definition: file.js, scope offset 1
callsite: file.js L5 C0
bindings: message -> "Hello World", y -> 2
}
End Scope C28 // C
End Scope C28 // A
```

`XXXX` stands for a "Start Scope" item, `X` for an "End Scope" item
`XXXX` stands for a "Start Generated Range" item, `X` for an "End Generated Range" item
```
XXXX;XXXX;;;X;XXXX,X,X
```
Expand Down
132 changes: 60 additions & 72 deletions source-map.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Shortname: source-map
Level: 1
Status: STAGE0
URL: https://tc39.es/source-map/
Editor: Armin Ronacher, Sentry
Editor: Asumu Takikawa, Igalia
Former Editor: Victor Porof, Google
Former Editor: John Lenz, Google
Former Editor: Nick Fitzgerald, Mozilla
Expand Down Expand Up @@ -106,12 +106,7 @@ This work is licensed under a [Creative Commons Attribution-ShareAlike 3.0 Unpor
This document is a draft version of a hardened version of the Source Map v3
specification. In its current form, it's not a defined standard and is subject to
modifications. If you want to get involved you will find more information under
the following GitHub repositories:

* [Spec Repository](https://github.com/source-map/source-map-spec/): holds the different
specifications (v1, v2, v3 and the hardened v3 draft you are looking at)
* [RFC Repository](https://github.com/source-map/source-map-rfc/): meta
repository for change suggestions to the specification.
the following [Specification Repository](https://github.com/tc39/source-map).

Background {#background}
========================
Expand All @@ -120,7 +115,7 @@ The original source map format (v1) was created by Joseph Schorr for use by
Closure Inspector to enable source-level debugging of optimized JavaScript code
(although the format itself is language agnostic). However, as the size of the
projects using the source maps expanded the verbosity of the format started to
become a problem. The v2 ([[V2Format]]) was created by trading some simplicity
become a problem. The v2 [[V2Format]] was created by trading some simplicity
and flexibility to reduce the overall size of the source map. Even with the
changes made with the v2 version of the format, the source map file size was
limiting its usefulness. The v3 format is based on suggestions made by
Expand Down Expand Up @@ -151,22 +146,23 @@ them. The sign bit is counted towards the limit, but the continuation bits are n
<dfn>Source Mapping URL</dfn> refers to the URL referencing
the location of a source map from the [=Generated code=].

<ins><dfn>Column</dfn> is the 0 (zero) indexed offsets within a line of the
generated code measured. The definition for columns in source maps can depend on
the content type. For JavaScript and CSS based source maps are defined to be in
UTF-16 code units analogous to JavaScript string indexes. That means that
"A" (`LATIN CAPITAL LETTER A`) measures 1 code unit, and "🔥" (`FIRE`) measures
2 code units. For WebAssembly, columns are defined as byte offsets from the beginning
of the binary content (and there is only one group representing a line). Source maps
for other content types might diverge from this.
</ins>
<dfn>Column</dfn> is the zero-based indexed offset within a line of the
generated code. The definition for columns in source maps can depend on
the content type.

* For JavaScript and CSS based source maps are defined to be in
UTF-16 code units analogous to JavaScript string indexes. That means that
"A" (`LATIN CAPITAL LETTER A`) measures 1 code unit, and "🔥" (`FIRE`) measures
2 code units.
* For WebAssembly, columns are defined as byte offsets from the beginning
of the binary content (and there is only one group representing a line).
* Source maps for other content types might diverge from this.

General Goals {#general-goals}
==============================

<mark>The goals for the v3 format of Source Maps</mark>
The goals for the v3 format of Source Maps:

* Reduce the overall size to improve parse time, memory consumption, and download time.
* Support source-level debugging allowing bidirectional mapping
* Support server-side stack trace deobfuscation

Expand All @@ -189,43 +185,32 @@ following structure:
}
```

Note: The previous specification suggested an order to the keys in this file, but
for practical reasons, the order cannot be defined in many JSON generators and
has never been enforced.

<dfn><code>version</code></dfn> is the version field which must always be the number
`3` as an integer. The source map may be rejected in case of a value different from `3`.

<dfn><code>file</code></dfn> an optional name of the generated code
that this source map is associated with. <mark>It's not specified if this can
be a URL, relative path name, or just a base name. As such it has a mostly informal
character.</mark>

<dfn><code>sourceRoot</code></dfn> an optional source root,
useful for relocating source files on a server or removing repeated values in
the [=sources=] entry. This value is prepended to the individual entries in the
"source" field.

<dfn><code>sources</code></dfn> is a list of original sources
used by the [=mappings=] entry. Each entry is either a string that is a
(potentially relative) URL or `null` if the source name is not known.

<dfn><code>sourcesContent</code></dfn> an optional list
of source content (that is the [=Original Source=]), useful when the "source"
can't be hosted. The contents are listed in the same order as the [=sources=].
`null` may be used if some original sources should be retrieved by name.

<dfn><code>names</code></dfn> an optional list of symbol names which may be used by the [=mappings=] entry.

<dfn><code>mappings</code></dfn> a string with the encoded mapping data (see [[#mappings-structure]]).

<dfn><code>ignoreList</code></dfn> an optional list of indices of files that
should be considered third party code, such as framework code or bundler-generated code. 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=] array and lists the indices of all the known third-party sources
in the source map. Some browsers may also use the deprecated <code>x_google_ignoreList</code>
field if <code>ignoreList</code> is not present.
* <dfn><code>version</code></dfn> is the version field which must always be the number
`3` as an integer. The source map may be rejected in case of a value different from `3`.
* <dfn><code>file</code></dfn> is an optional name of the generated code
that this source map is associated with. It's not specified if this can
be a URL, relative path name, or just a base name. As such it has a mostly informal
character.
* <dfn><code>sourceRoot</code></dfn> is an optional source root,
useful for relocating source files on a server or removing repeated values in
the [=sources=] entry. This value is prepended to the individual entries in the
"source" field.
* <dfn><code>sources</code></dfn> is a list of original sources
used by the [=mappings=] entry. Each entry is either a string that is a
(potentially relative) URL or `null` if the source name is not known.
* <dfn><code>sourcesContent</code></dfn> is an optional list
of source content (that is the [=Original Source=]), useful when the "source"
can't be hosted. The contents are listed in the same order as the [=sources=].
`null` may be used if some original sources should be retrieved by name.
* <dfn><code>names</code></dfn> is an optional list of symbol names which may be used by the [=mappings=] entry.
* <dfn><code>mappings</code></dfn> is a string with the encoded mapping data (see [[#mappings-structure]]).
* <dfn><code>ignoreList</code></dfn> is an optional list of indices of files that
should be considered third party code, such as framework code or bundler-generated code. 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=] array and lists the indices of all the known third-party sources
in the source map. Some browsers may also use the deprecated <code>x_google_ignoreList</code>
field if <code>[=ignoreList=]</code> is not present.

Mappings Structure {#mappings-structure}
----------------------------------------
Expand Down Expand Up @@ -262,9 +247,17 @@ The fields in each segment are:
field is a base 64 VLQ relative to the previous occurrence of this field unless this
is the first occurrence of this field, in which case the whole value is represented.

Note: This encoding reduces the source map size by 50% relative to the V2 format in tests performed
Note: The purpose of this encoding is to reduce the source map size. VLQ encoding reduced source maps by 50% relative to the [[V2Format]] in tests performed
using Google Calendar.

Note: Segments with one field are intended to represent generated code that is unmapped because there
is no corresponding original source code, such as code that is generated by a compiler. Segments
with four fields represent mapped code where a corresponding name does not exist. Segments with five
fields represent mapped code that also has a mapped name.

Note: Using file offsets was considered but rejected in favor of using line/column data to avoid becoming
misaligned with the original due to platform-specific line endings.

Resolving Sources {#resolving-sources}
--------------------------------------

Expand All @@ -278,12 +271,6 @@ Source map consumers must ignore any additional unrecognized properties, rather
source map to be rejected, so that additional features can be added to this format without
breaking existing users.

Notes on File Offsets
---------------------

Using file offsets was considered but rejected in favor of using line/column data to avoid becoming
misaligned with the original due to platform-specific line endings.

Index Map
=========

Expand Down Expand Up @@ -323,20 +310,21 @@ The index map follows the form of the standard map. Like the regular source map
the file format is JSON with a top-level object. It shares the [=version=] and
[=file=] field from the regular source map, but gains a new [=sections=] field.

<dfn><code>sections</code></dfn> is an array of JSON objects that itself has two
fields [=offset=] and [=map=].
<dfn><code>sections</code></dfn> is an array of [=Section=] objects.

## Section

<dfn><code>offset</dfn></code> is an object with two fields, `line` and `column`,
that represent the offset into generated code that the referenced source map
represents.
Section objects have the following fields:

* <dfn><code>offset</dfn></code> is an object with two fields, `line` and `column`,
that represent the offset into generated code that the referenced source map
represents.

<dfn><code>map</code></dfn> is an embedded complete source map object.
An embedded map does not inherit any values from the containing index map.
* <dfn><code>map</code></dfn> is an embedded complete source map object.
An embedded map does not inherit any values from the containing index map.

The sections must be sorted by starting position and the represented sections
may not overlap.
must not overlap.

Conventions {#conventions}
==========================
Expand All @@ -347,7 +335,7 @@ when generating them.
Source Map Naming {#source-map-naming}
--------------------------------------

Optionally, a source map will have the same name as the generated file but with a `.map`
Commonly, a source map will have the same name as the generated file but with a `.map`
extension. For example, for `page.js` a source map named `page.js.map` would be generated.

Linking generated code to source maps {#linking-generated-code}
Expand Down

0 comments on commit 7427d96

Please sign in to comment.