Merge branch 'main' into spec-review-first-pass

CONTRIBUTING.md

@@ -27,8 +27,7 @@ Thanks for helping out in the [source map effort](https://ecma-international.org
 We've been thinking about _source map constituencies_ in the following terms. Please feel free to suggest better titles or categorization methods!
 
 1. Generators. Bundlers, transpilers, compilers. Tools that have access to the source code and emit (among other things) source maps.
-2. Debuggers. Browsers and [standalone debuggers](https://www.replay.io/). These are tools that have access to the source map and the generated code.
-3. Error monitoring tools. Tools like Sentry and New Relic. These tools have access to an error stack trace and a source map.
+2. Debuggers. Browsers, [standalone debuggers](https://www.replay.io/) and stack trace rewriters like [Node](https://nodejs.org/en) and [Sentry](https://sentry.io/).
 
 When considering changes, this list of tools might be useful: https://github.com/jkup/source-map-users
 
@@ -37,5 +36,4 @@ When considering changes, this list of tools might be useful: https://github.com
 We've been categorizing our testing efforts into three groups, each matching with a [constituency](#constituencies).
 
 1. Validators. For testing generator tools, we'd like to have the ability to validate a source map on its own as well as a source map being a valid map between a source and a generated file. We did a mini hackathon day on what this might look like: https://github.com/jkup/source-map-validator
-2. Debuggers. For browsers, we'd like a suite of tests that can run wherever browsers apply source maps to their debug tools like Chrome DevTools. We'd like generic tests that browsers can use showing they apply source maps correctly. My assumption is they each already have their own suite of tests ([Chrome tests](https://github.com/ChromeDevTools/devtools-frontend/blob/main/test/e2e/sources/sourcemap_test.ts), [Firefox tests](https://github.com/mozilla/source-map/tree/master/test)) for this and we'll need to figure out how to integrate with their test harness and extract a shared base of tests we all could use.
-3. Stack trace validators. For tools like Sentry and New Relic, we'd like tests that ensure source maps are correctly applied to the stack trace and that new features like [Debug ID](https://github.com/tc39/source-map-rfc/blob/main/proposals/debug-id.md) are working correctly.
+2. Debuggers. For browsers, we'd like a suite of tests that can run wherever browsers apply source maps to their debug tools like Chrome DevTools. We'd like generic tests that browsers can use showing they apply source maps correctly. My assumption is they each already have their own suite of tests ([Chrome tests](https://github.com/ChromeDevTools/devtools-frontend/blob/main/test/e2e/sources/sourcemap_test.ts), [Firefox tests](https://github.com/mozilla/source-map/tree/master/test)) for this and we'll need to figure out how to integrate with their test harness and extract a shared base of tests we all could use. For stack trace rewriters, we'd like tests that can show source maps being correctly applied to error stacks.

PROCESS.md

@@ -20,9 +20,9 @@ When a proposal reaches Stage 3, no further improvements are possible without im
 
 ## Stage 4 (complete)
 
-- 2 source map generators ready
-- 2 interactive debuggers
-- 2 stack trace decoder implementations
+- 2 generators
+- 2 debuggers
+- 1 complete end to end workflow
 - Test suite is complete
 
 When a proposal reaches Stage 4, it is ready to land in the editor draft. There might still be editorial changes, but all the semantics are final.

proposals/scopes.md

@@ -244,17 +244,24 @@ Note: Each DATA represents one VLQ number.
 * bindings:
   * Note: the number of bindings must match the number of variables in the definition scope
   * for each binding:
-    * Let M be the number of sub-ranges for the current variable in this generated range (where the expression differs on how to obtain the current variable’s value)
-    * DATA offset into `names` field or -1
-      * Note: The value expression for the current variable either for the whole generated range (if M == 1), or for the sub-range that starts at the beginning of this generated range.
-      * Note: Use -1 to indicate that the current variable is unavailable (e.g. due to shadowing) in this range.
-    * If M > 1, then
-      * DATA negative number of sub-ranges (-M)
+    * Note: The value expression for the current variable either for the whole generated range (if M == 1), or for the sub-range that starts at the beginning of this generated range.
+    * Note: Use -1 to indicate that the current variable is unavailable (e.g. due to shadowing) in this range.
+    * DATA M either an index into `names` field (if M is >= -1), or the number of sub-ranges for the current variable in this generated range (where the expression differs on how to obtain the current variable’s value)
+    * If M == -1, then
+        * Do nothing.
+        * Note: The variable is not accessible within this generated range.
+    * Else if M >= 0, then
+        * M is used as an index into `names` field
+        * Note: The variable is accessible by evaluating the value expression for the entirety of this generated range.
+    * Else,
+      * Note: there are at least 2 sub-ranges.
+      * DATA offset into `names` field or -1
+        * Note: The variable is accessible using this value expression starting from the beginning of the generated range until the start of the next sub-range.
+        * Note: Use -1 to indicate that the current variable is unavailable (e.g. due to shadowing) in this sub-range.
       * (M - 1) times
         * DATA line in the generated code
+          * Note: The line is relative to the previous sub-range line or the start of the current generated range item if it’s the first for this loop.
         * DATA column in the generated code
-          * Note: This is the point (exclusive) in the generated code until the previous expression must be used to obtain the current variable’s value.
-          * Note: The line is relative to the previous sub-range line or the start of the current generated range item if it’s the first.
           * Note: The column is relative to the column of the previous sub-range if it’s on the same line or absolute if it’s on a new line.
         * DATA offset into `names` field or -1
           * Note: The expression to obtain the current variable’s value in the sub-range that starts at line/column and ends at either the next sub-range start or this generated range’s end.

source-map.bs

@@ -139,7 +139,9 @@ into the string least significant first, and where the least significant bit of
 the first digit is used as the sign bit.
 
 Note: The values that can be represented by the VLQ Base64 encoded are limited to
-32-bit quantities until some use case for larger values is presented.
+32-bit quantities until some use case for larger values is presented.  This
+means that values exceeding 32-bits are invalid and implementations may reject
+them. The sign bit is counted towards the limit, but the continuation bits are not.
 
 <dfn>Source Mapping URL</dfn> refers to the URL referencing
 the location of a source map from the [=Generated code=].