diff --git a/proposals/scopes.md b/proposals/scopes.md
index fd6a333..0ea5a78 100644
--- a/proposals/scopes.md
+++ b/proposals/scopes.md
@@ -132,9 +132,15 @@ interface SourceMap {
interface OriginalScope {
start: OriginalPosition;
end: OriginalPosition;
- kind: string;
+ /** Serves as a label in source-map consumers */
+ kind?: string;
/** Class/module/function name. Can be used for stack traces or naming scopes in a debugger's scope view */
name?: string;
+ /**
+ * Whether this scope corresponds to the semantic equivalent of a function call in
+ * the authored language, and as such can show up in stack traces.
+ */
+ isStackFrame: boolean;
/** Symbols defined in this scope */
variables?: string[];
children?: OriginalScope[];
@@ -143,7 +149,18 @@ interface OriginalScope {
interface GeneratedRange {
start: GeneratedPosition;
end: GeneratedPosition;
- isScope: boolean;
+ /**
+ * Whether this range is a JavaScript function/method/generator/constructor and can show
+ * up in Error.stack as a stack frame.
+ */
+ isStackFrame: boolean;
+ /**
+ * Whether calls to this range should be removed from stack traces.
+ * Intended for outlined functions or transpiler inserted function that correspond
+ * to an original scope, but should be hidden from stack traces (e.g. an original block
+ * scope outlined into a function).
+ */
+ isHidden: boolean;
originalScope?: OriginalScope;
/** If this scope corresponds to an inlined function body, record the callsite of the inlined function in the original code */
callsite?: OriginalPosition;
@@ -199,17 +216,20 @@ 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 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.
- * Note: JavaScript implementations should use `'global'`, `'class'`, `'function'`, and `'block'`.
-* DATA field flags
+* DATA flags
* Note: binary flags that specify if a field is used for this scope.
* Note: Unknown flags would skip the whole scope.
* 0x1 has name
+ * 0x2 has kind
+ * 0x4 is stack frame
* name: (only exists if `has name` flag is set)
* DATA offset into `names` field
* Note: This name should be shown as function name in the stack trace for function scopes.
+* kind: (only exists if `has kind` flag is set)
+ * DATA 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.
+ * Note: JavaScript implementations should use `'global'`, `'class'`, `'function'`, and `'block'`.
* variables:
* for each variable:
* DATA offset into `names` field for the original symbol name defined in this scope
@@ -231,7 +251,8 @@ Note: Each DATA represents one VLQ number.
* Note: Unknown flags would skip the whole scope.
* 0x1 has definition
* 0x2 has callsite
- * 0x4 is scope
+ * 0x4 is stack frame
+ * 0x8 is hidden
* definition: (only existing if `has definition` flag is set)
* DATA offset into `sources`
* Note: This offset is relative to the offset of the last definition or absolute if this is the first definition
diff --git a/source-map.bs b/source-map.bs
index 7ef7d67..45f74f5 100644
--- a/source-map.bs
+++ b/source-map.bs
@@ -1,5 +1,5 @@
-Title: Source Map
+Title: Source Map Format Specification
H1: Source Map
Shortname: source-map
Level: none
@@ -19,6 +19,7 @@ Abstract: This Ecma standard defines the Source Map format, used for mapping tra
No Abstract: true
Markup Shorthands: markdown yes
Group: tc39
+Boilerplate: references no
@@ -66,6 +67,30 @@ urlPrefix:https://tc39.es/ecma262/#; type:dfn; spec:ecmascript
url:prod-TemplateSubstitutionTail; text:TemplateSubstitutionTail
url:prod-WhiteSpace; text:WhiteSpace
url:sec-ecmascript-language-lexical-grammar; text:ECMAScript Lexical Grammar
+ url:prod-Arguments; text:Arguments
+ url:prod-BindingIdentifier; text:BindingIdentifier
+ url:prod-ClassElementName; text:ClassElementName
+ url:prod-FormalParameters; text:FormalParameters
+ url:prod-FunctionDeclaration; text:FunctionDeclaration
+ url:prod-FunctionExpression; text:FunctionExpression
+ url:prod-Expression; text:Expression
+ url:prod-AsyncFunctionDeclaration; text:AsyncFunctionDeclaration
+ url:prod-AsyncFunctionExpression; text:AsyncFunctionExpression
+ url:prod-ArrowFormalParameters; text:ArrowFormalParameters
+ url:prod-ArrowFunction; text:ArrowFunction
+ url:prod-ArrowParameters; text:ArrowParameters
+ url:prod-AsyncArrowFunction; text:AsyncArrowFunction
+ url:prod-AsyncArrowBindingIdentifier; text:AsyncArrowBindingIdentifier
+ url:prod-GeneratorDeclaration; text:GeneratorDeclaration
+ url:prod-GeneratorExpression; text:GeneratorExpression
+ url:prod-MethodDefinition; text:MethodDefinition
+ url:prod-AsyncGeneratorDeclaration; text:AsyncGeneratorDeclaration
+ url:prod-AsyncGeneratorExpression; text:AsyncGeneratorExpression
+ url:prod-IdentifierReference; text:IdentifierReference
+ url:prod-LexicalDeclaration; text:LexicalDeclaration
+ url:prod-VariableStatement; text:VariableStatement
+ url:sec-parameter-lists; text:Parameter List
+ url:sec-syntactic-grammar; text:Syntactic Grammar
urlPrefix:https://webassembly.github.io/spec/core/; type:dfn; spec:wasm
url:binary/modules.html#binary-customsec; text:custom section
@@ -120,15 +145,6 @@ urlPrefix:https://webassembly.github.io/spec/core/; type:dfn; spec:wasm
}
-About this Specification
-
-The document at [https://tc39.es/source-map/](https://tc39.es/source-map/) is the most accurate and
-up-to-date source map specification. It contains the content of the most recently published snapshot
-plus any modifications that will be included in the next snapshot.
-
-If you want to get involved you will find more information at the [specification
-repository](https://github.com/tc39/source-map).
-
Introduction
This Ecma Standard defines the Source Map Format, used for mapping transpiled source code back to the original sources.
@@ -137,6 +153,13 @@ The source map format has the following goals:
* Support source-level debugging allowing bidirectional mapping
* Support server-side stack trace deobfuscation
+The document at [https://tc39.es/source-map/](https://tc39.es/source-map/) is the most accurate and
+up-to-date source map specification. It contains the content of the most recently published snapshot
+plus any modifications that will be included in the next snapshot.
+
+If you want to get involved you will find more information at the [specification
+repository](https://github.com/tc39/source-map).
+
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
@@ -197,7 +220,74 @@ IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Scope {#scope}
==============
-This Standard defines the Source Map Format.
+This Standard defines the source map format, used by different types of
+developer tools to improve the debugging experience of code compiled to
+JavaScript, WebAssembly, and CSS.
+
+Conformance {#conformance}
+==========================
+
+A conforming source map document is a JSON document that conforms to the
+structure detailed in this specification.
+
+A conforming source map generator should generate documents which are
+conforming source map documents, and can be decoded by the algorithms in this
+specification without reporting any errors (even those which are specified as
+optional).
+
+A conforming source map consumer should implement the algorithms specified in this
+specification for retrieving (where applicable) and decoding source map documents.
+A conforming consumer is permitted to ignore errors or report them without
+terminating where the specification indicates that an algorithm may
+[=optionally report an error=].
+
+References {#references}
+========================
+
+
+
+Normative References
+
Terms and definitions {#terminology}
====================================
@@ -526,7 +616,7 @@ sources=] |sources|, run the followi
be the result.
1. If |relativeNameIndex| is not null, then:
1. Increase |nameIndex| by |relativeNameIndex|.
- 1. If |nameIndex| is negative or greater than |names|'s [=list/size=], [=optionally
+ 1. If |nameIndex| is negative or greater than or equal to |names|'s [=list/size=], [=optionally
report an error=].
1. Else, set |decodedMapping|'s [=decoded mapping/name=] to |names|[|nameIndex|].
1. If |position| does not point to the end of |segment|, [=optionally report an
@@ -590,6 +680,70 @@ as per [=ECMAScript Lexical Grammar=]. [=decoded mapping|Mapping=] entries must
[=Comment=], [=HashbangComment=], [=StringLiteral=], [=Template=],
[=TemplateSubstitutionTail=], [=WhiteSpace=] and [=LineTerminator=].
+### [=decoded mapping/Names=] for generated JavaScript code
+
+Source map generators should create a [=decoded mapping|mapping=] entry with a
+[=decoded mapping/name=] field for a JavaScript token, if
+
+1. The original source language construct maps semantically to the generated
+ JavaScript code.
+
+1. The original source language construct has a name.
+
+Then the [=decoded mapping/name=] of the [=decoded mapping|mapping=] entry should be
+the name of the original source language construct. A [=decoded mapping|mapping=] with
+a non-null [=decoded mapping/name=] is called a named mapping.
+
+Example: A minifier renaming functions and variables or removing function names
+from immediately invoked function expressions.
+
+The following enumeration lists productions of the ECMAScript [=Syntactic Grammar=]
+and the respective token or non-terminal (on the right-hand side of the production)
+for which source map generators should emit a [=named mapping=].
+The [=decoded mapping|mapping=] entry created for such tokens must follow [[#mappings-javascript]].
+
+The enumeration should be understood as the "minimum". In general,
+source map generators are free to emit any additional [=named mappings=].
+
+Note: The enumeration also lists tokens where generators "may" emit named [=decoded mapping|mappings=] in addition
+to the tokens where they "should". These reflect the reality where existing tooling emits or
+expects [=named mappings=]. The duplicated [=named mapping=] is comparably cheap: Indices into
+[=json/names=] are encoded relative to each other so subsequent mappings to the same name are
+encoded as 0 (`A`).
+
+1. The [=BindingIdentifier=](s) for [=LexicalDeclaration=], [=VariableStatement=]
+ and [=Parameter List=].
+
+1. The [=BindingIdentifier=] for [=FunctionDeclaration=], [=FunctionExpression=],
+ [=AsyncFunctionDeclaration=], [=AsyncFunctionExpression=], [=GeneratorDeclaration=],
+ [=GeneratorExpression=], [=AsyncGeneratorDeclaration=], and [=AsyncGeneratorExpression=] if it
+ exists, or the opening parenthesis `(` preceding the [=FormalParameters=] otherwise.
+
+ Source map generators may chose to emit a [=named mapping=] on the opening parenthesis regardless of
+ the presence of the [=BindingIdentifier=].
+
+1. For an [=ArrowFunction=] or [=AsyncArrowFunction=]:
+ 1. The `=>` token where [=ArrowFunction=] is produced with a single [=BindingIdentifier=] for
+ [=ArrowParameters=]. Or [=AsyncArrowFunction=] is produced with an [=AsyncArrowBindingIdentifier=].
+
+ Note: This describes the case of (async) arrow functions with a single parameter, where
+ that single parameter is not wrapped in parenthesis.
+
+ 1. The opening parenthesis `(` where [=ArrowFunction=] or [=AsyncArrowFunction=] is produced
+ with [=ArrowFormalParameters=].
+
+ Source map generators may chose to additionally emit a named [=decoded mapping|mapping=]
+ on the `=>` token for consistency with (1).
+
+1. The [=ClassElementName=] for [=MethodDefinition=]. This includes generators, async
+ methods, async generators and accessors. For [=MethodDefinition=] where
+ [=ClassElementName=] is "constructor", the [=decoded mapping/name=] should be the original
+ class name if applicable.
+
+ Source map generators may chose to additionally emit a named [=decoded mapping|mapping=] on the opening parenthesis `(`.
+
+1. Source map generators may emit named [=decoded mapping|mappings=] for [=IdentifierReference=] in [=Expression=].
+
Resolving Sources {#resolving-sources}
--------------------------------------