Skip to content

[source maps] Add support for scopes proposal call stacks - #9400

Open
kripken wants to merge 7 commits into
WebAssembly:mainfrom
kripken:scopes
Open

kripken wants to merge 7 commits into
WebAssembly:mainfrom
kripken:scopes

Conversation

@kripken

@kripken kripken commented Nov 17, 2026

Copy link
Copy Markdown
Member

The scopes proposal extends source maps to add inlined call stacks and
variable bindings:

https://tc39.es/ecma426/branch/proposal-scopes/#sec-source-map-format

This PR adds support for call stacks. We can now read the "scopes" and
"ranges" additions to the spec, and write them. To support multiple call
stacks for each expression in our IR, we shift from storing a single
DebugLocation to a SmallVector of them. When we inline, we simply
push more scopes on the stack.

For convenience and for debuggability, the ;;@ src.cpp:10:5:funcname
annotations are extended to support multiple scopes. For example, if we
have

  (func $caller
    ;;@ caller.cpp:10:5:CallerFunc
    (call $callee)
  )

  (func $callee
    ;;@ callee.cpp:2:3:CalleeFunc
    (nop)
  )

then after inlining we'd have this:

  (func $caller
    ;;@ caller.cpp:10:5:CallerFunc
    ;;@ callee.cpp:2:3:CalleeFunc
    (nop)
  )

That nop is now annotated as having a call stack of both the
caller and the inlined code, as if we never inlined. The ;;@
annotations are simply the stack frames in order.

Most of the changes in this PR are simple things that fall out
of the move from a single DebugLocation to a vector of them.
Otherwise, Inlining is extended to concatenate inlined stacks,
and then there are the messy details of the source maps
format itself (which is quite complex and uses VLQ encoding).

Comment thread src/parser/contexts.h Outdated
Comment on lines +2108 to +2109
locs.push_back(
Function::DebugLocation{it->second, *line, *col, symbolNameIndex});

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Looks like this can be emplace_back to avoid a move

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Sounds good, done.

Comment thread src/wasm/source-map.cpp Resolved
Comment thread src/wasm/source-map.cpp Outdated
}

if (activeRanges.empty()) {
result.push_back(Function::DebugLocation{file, line, col, sym});

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

We can use emplace_back here and the three instances below

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Also done.

@stevenfontanella

Copy link
Copy Markdown
Member

As a meta-comment, maybe it'd be better to split up the PRs like this into separate PRs doing only parsing/printing/etc. in the future? I think I'd find it easier to review that way.

@kripken

kripken commented Nov 18, 2026

Copy link
Copy Markdown
Member Author

As a meta-comment, maybe it'd be better to split up the PRs like this into separate PRs doing only parsing/printing/etc. in the future? I think I'd find it easier to review that way.

An issue is that those PRs would not be able to test themselves well. Another option might be to separate them into commits in a single PR, would you prefer that?

@stevenfontanella

Copy link
Copy Markdown
Member

Ideally I think we should make the code testable independently which is part of the advantage of splitting things out. I don't know this code well though, so I don't know how practical that is.

Splitting it into separate commits sounds good too. I can keep reviewing like this or if you want to rewrite the history I think that'd be helpful.

Replace `std::optional<DebugLocation>` with `DebugLocations`
(`SmallVector<DebugLocation, 1>`) on `Function::debugLocations`,
`prologLocation`, and `epilogLocation` so expressions can hold a stack
of source locations from outermost caller to innermost inlined frame
(while keeping an empty vector to stop debug location propagation).

Update `IRBuilder`, `ModuleUtils::copyFunctionWithoutAdd`,
`DebugLocationPropagation`, and the C API accordingly, while keeping
WAT and binary source map I/O behavior unchanged for now.
Update `ParseDefsCtx::setSrcLoc` to collect all `;;@` (`src`)
annotations attached to an instruction into `Function::DebugLocations`,
ordered from outermost caller to innermost frame, while resetting the
collected stack when an empty `;;@` annotation is encountered.
Update `PrintSExpression::printDebugLocation` and `lastPrintedLocation`
to operate on `Function::DebugLocations` directly, emitting one `;;@`
line per stack frame in order.
Teach `SourceMapReader` to parse `"scopes"` (`OriginalScopeStart`/`End`,
names, and kinds) and `"ranges"` (`GeneratedRangeStart`/`End`,
`GeneratedRangeCallSite` `'I'`, and `GeneratedRangeRelativeCallSite`
`'J'`), and reconstruct the full `Function::DebugLocations` call stack
at each binary offset in `readDebugLocationAt`.
Track full `Function::DebugLocations` stacks in `WasmBinaryWriter`.
Emit innermost locations to `"mappings"` (deduplicating consecutive
identical leaf mappings across scope transitions), and when inlined
scopes are present, synthesize `"scopes"` (`OriginalScope` stack frame
entries per source file) and `"ranges"` (nested `GeneratedRange` trees
with `'I'` call site records).
When inlining a call site that has debug locations, attach the call's
`DebugLocations` to the wrapper block (and local-zeroing initializers)
and prepend the caller's locations onto all tracked expressions in the
inlined callee body.

Add unit and lit tests covering inlining with source map scopes and
end-to-end roundtripping across binary source maps and WAT text.
@kripken

kripken commented Nov 19, 2026

Copy link
Copy Markdown
Member Author

Ok, now split into separate commits. Hopefully that is helpful. Total diff is unchanged.

Some of the commits lack testing, which is my main concern about this splitting up - the real tests arrive only at the very end. But inside a single PR that's fine.

(My other concern in general is atomicity in the git log, but this is an entirely new feature, so that isn't relevant.)

# Conflicts:
#	src/wasm/source-map.cpp

@JesusFileto JesusFileto left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Hey! left a couple of general comments in relation to how binaryen follows scopes according to the spec since I've been dealing with them on the generator side with Emscripten. hope they help :)

Comment thread src/wasm/wasm-binary.cpp
Comment on lines +1722 to +1733
for (size_t j = 0; j < locs->size(); ++j) {
const auto& dl = (*locs)[j];
TargetFrame tf;
if (dl.symbolNameIndex) {
auto it = scopeIndices.find({dl.fileIndex, *dl.symbolNameIndex});
if (it != scopeIndices.end()) {
tf.def = ScopeDef{dl.fileIndex, it->second};
}
}
tf.isStackFrame = (j == 0);
if (j > 0) {
tf.callSite = CallSite{(*locs)[j - 1].fileIndex,

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

It seems that definition is only set if the frame has a name but stack frame and call site are set regardless. In the scopes spec it states that the definition cannot be null.

A non-null [[CallSite]] field marks the [generated range](https://tc39.es/ecma426/branch/proposal-
scopes/#sec-terms-and-definitions-generated-range) as an inlined scope. If the [[CallSite]] field of a generated range is not null, then:

[[Definition]] must not be null.
[[Definition]].[[IsStackFrame]] must be true.
[[StackFrameType]] must be none.

Maybe we can use a different lookup mechanism more than just (file, name) or we can add a name entry with a placeholder for unnamed function scopes.

Comment thread src/wasm/wasm-binary.cpp
Comment on lines +1740 to +1747
size_t common = 0;
while (common < openStack.size() && common < targetFrames.size() &&
openStack[common].frame == targetFrames[common]) {
++common;
}
while (openStack.size() > common) {
closeTopRange(offset);
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

When locs is null, targetFrames is empty and so common = 0 . This means that all open ranges are closed including the function range. The next located instruction in the function then opens a new function range, so a function with gaps in its locations is written as several function ranges, and the code in the gaps points to nothing.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Ideally a no location frame should be skipped and the next debug location should decide whether the range should be closed if the next frame is a new function or closed if it is the same function.

Comment thread test/gtest/source-map.cpp
EXPECT_EQ(loc->lineNumber, line);
EXPECT_EQ(loc->columnNumber, col);
EXPECT_EQ(loc->symbolNameIndex, sym);
ASSERT_FALSE(loc.empty());

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Check the size instead to verify that there isn't an index 1 that the test misses. Ditto for other tests.

On that note now that we have #8879, we can use more structured assertions which do this like

EXPECT_THAT(UnorderedElementsAre({file, line, ...}))

Which I think would work if loc is an aggregate, ok to leave it out though.

Comment thread src/parser/contexts.h
auto [it, inserted] = debugSymbolNameIndices.insert(
{symbolName, debugSymbolNameIndices.size()});
if (inserted) {
assert(wasm.debugInfoSymbolNames.size() == it->second);

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

nit: this assertion looks redundant. This is what we just inserted anyway?

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants