Skip to content

lib: implement source map scopes decoder - #67594

Open
legendecas wants to merge 2 commits into
nodejs:mainfrom
legendecas:source-maps-scopes
Open

legendecas wants to merge 2 commits into
nodejs:mainfrom
legendecas:source-maps-scopes

Conversation

@legendecas

@legendecas legendecas commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

Implements the TC39 Source Maps Stage 3 https://github.com/tc39/ecma426/blob/main/proposals/scopes.md proposal decoder. This does not implement the stack trace formatter of the scopes. The stack trace formatter will be in a follow-up.

The Source Maps Scopes proposal would allow Node.js to print a human readable stacktrace variable and function names, with inlined function frames.

For example, a transpiler inlines inner into outer, renames outer to a, and calls it through a generated helper h:

// original.js
function outer() {
  inner();
}
function inner() {
  throw new Error('boom');
}
outer();

// generated.js
function a() {
  throw new Error('boom');
}
function h(f) {
  return f();
}
h(a);
//# sourceMappingURL=generated.js.map

Without scopes info, Node.js prints a stack trace like:

Error: boom
    at a (/path/to/original.js:5:9)
    at global (/path/to/original.js:5:9)
    at Object.<anonymous> (/path/to/original.js:7:1)

With the scopes in the source map, the stack trace can show the original
functions, restore the inlined inner frame, and leave out the helper h:

Error: boom
    at inner (/path/to/original.js:5:9)
    at outer (/path/to/original.js:2:3)
    at Object.<anonymous> (/path/to/original.js:7:1)

The first commit moves the VLQ decoder into a dedicated vlq.js so that the decoder can be shared by the regular Source Maps parser and the new Scopes parser.

The new decoder is tested against https://github.com/tc39/source-map-tests/tree/main/decoding in the test/test262 suite.


Assisted-by: Claude

@legendecas legendecas added the source maps Issues and PRs related to source map support. label Nov 18, 2026
@nodejs-github-bot nodejs-github-bot added the needs-ci PRs that need a full CI run. label Nov 18, 2026
@codecov

codecov Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 92.40048% with 63 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.73%. Comparing base (030745c) to head (3e58349).
⚠️ Report is 1 commits behind head on main.

Files with missing lines Patch % Lines
lib/internal/source_map/scopes.js 89.74% 59 Missing and 2 partials ⚠️
lib/internal/source_map/source_map.js 98.21% 2 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main   #67594      +/-   ##
==========================================
+ Coverage   90.72%   90.73%   +0.01%     
==========================================
  Files         801      803       +2     
  Lines      280960   281708     +748     
  Branches    54260    54361     +101     
==========================================
+ Hits       254892   255617     +725     
- Misses      16248    16257       +9     
- Partials     9820     9834      +14     
Files with missing lines Coverage Δ
lib/internal/source_map/vlq.js 100.00% <100.00%> (ø)
lib/internal/source_map/source_map.js 99.30% <98.21%> (-0.33%) ⬇️
lib/internal/source_map/scopes.js 89.74% <89.74%> (ø)

... and 34 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Signed-off-by: Chengzhong Wu <cwu631@bloomberg.net>
Implements the stage 3 https://github.com/tc39/ecma426/blob/main/proposals/scopes.md
proposal decoder. This does not implement the stack trace formatter of
the scopes. The stack trace formatter will be in a follow-up.

Signed-off-by: Chengzhong Wu <cwu631@bloomberg.net>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-ci PRs that need a full CI run. source maps Issues and PRs related to source map support.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants