Repository navigation
Conversation
SavedSourceMap holds three flags: enabled, nodeModules and generatedCode. The flags are the bits of one atomic byte. A thread that reads them sees the state of one call. --enable-source-maps is now a declared runtime flag. The flag turns the three flags on when the VM starts. A Worker without an execArgv uses the flag of its parent. A Worker with an execArgv uses only that list. bun test --parallel sends the flag to its workers. bun test --isolate puts the startup value back before each file. The package manager commands ignore the flag, as they ignore the other runtime flags. process.setSourceMapsEnabled() sets the switch. process.sourceMapsEnabled, module.getSourceMapsSupport() and module.setSourceMapsSupport() are new. Their values, defaults and errors are those of Node.js v26.3.0. The Process object loses its unused m_sourceMapsEnabled field. Nothing reads the switch yet, so stack traces do not change.
The lexer recorded the URL of a sourceMappingURL comment at a wrong offset. The offset was the sum of the start of the comment and the position of the pragma. The lexer now records the file offset of the URL. The JSX pragmas had the same error, so a warning about one of them pointed at a later line. The URL can now contain non-ASCII characters. The parser copies the range of the URL to the Ast. The printer gives the range to the source map handler and to the transpiler cache. SavedSourceMap::put_mappings takes the range as a parameter. An entry of the transpiler cache stores the range, so a cache hit gives put_mappings the same value as a print. The cache version is now 44. Nothing reads the range yet.
A file that another tool transpiled can name its source map in a sourceMappingURL comment. Bun ignored that map. Error.stack and a printed error showed positions in the file that was loaded. The switch is --enable-source-maps, process.setSourceMapsEnabled(true) or module.setSourceMapsSupport(true). With the switch off, nothing changes and no map file is opened. With the switch on, SavedSourceMap::put_mappings reads the map when the module loads. It reads a data: URL and a path, as Node.js v26.3.0 does. It does not read a URL with another scheme. It reads only a regular file. A failure is silent. The table stores a new record. The record has the map of the printer, the bytes of the module's map, and the file that the sources are relative to. The nodeModules option applies at load and at lookup. Nothing parses the bytes at load. A reader of a stack position now states the file that it wants the position in. PositionSpace::Original is for Error.stack, Error.captureStackTrace, console.trace and a printed error. These readers parse the bytes at the first lookup, outside the lock of the table. Then they map the position a second time. PositionSpace::Loaded is for CallSite objects, coverage, inline snapshots, test lines, the test reporter, cron and CPU profiles. These readers get the position in the loaded file, as before. Bun__remapStackFramePositions, remap_stack_frame_positions, resolve_source_mapping and resolve_mapping take the space as a required parameter. parse_json and parse_url take a policy. ParsePolicy::Bun keeps the rules for a map that Bun wrote. ParsePolicy::Node reads a map as Node.js does. sourcesContent is optional. sourceRoot goes directly before each source. A source resolves against the map file, or against the module for a data: URL. A printed error shows the lines of the original source if sourcesContent or the original file has them. If not, it shows the line of the loaded file and keeps the mapped frames, as Node.js does. bun test --isolate keeps a transpiled module for the next file. A change of the switch now clears that cache, because the map of a module is read when the module is transpiled.
A FIFO in place of a source map file does not stop a module that loads, with and without --enable-source-maps. The test runs on POSIX. After --hot loads a changed file again, a new error is mapped through the new source map of that file.
put_mappings keeps the URL of the sourceMappingURL comment and opens nothing. The first reader that asks for an original position reads and parses the map, and a map that cannot be used is not read again. Node.js reads the map at the same time since v26.9.0. The parse runs under its own AST allocator. A collection can format a stack while a loader on the same thread walks an AST in the thread's store, and parse_json resets that store. put_mappings takes the switch as a parameter. The JS thread reads it when it asks for the module, so a transpile on a pool thread does not depend on when that thread runs. bun test --isolate keeps a transpiled module by whether the switch asks for the module's own source map. A change of the switch no longer empties the cache of transpiled modules. A printed error asks for the source text only when it shows a code frame, and the record keeps the text that it took out of the map. A path with a NUL from a sourceMappingURL comment or from the sources of a map is not given to open.
…int, a NUL and two sources The tests that say what Node.js does were run against node v26.13.0.
…able, as node and on reload The tests load a module that has a sourceMappingURL comment while source maps are on. - With --inspect, Error.stack is in the original file. - An executable reads the source map of a file that it loads from disk. The frames of the bundled code stay where they are. - --cpu-prof and a parse error give positions in the loaded file. - With --isolate, a preload turns source maps on for each file. The second file takes the module from the cache. - Without --isolate, the next file sees the process.setSourceMapsEnabled() call of the file before it. - Bun as node reads the source map with --enable-source-maps. - A module that loads again frees the record of the load before it.
The parse frame of a SyntaxError was mapped through the own source map of the module, and the line of the error with it. The sourceURL of the error stayed the loaded file, so the two did not name one place. Node.js locates such an error in the loaded file.
…source text A frame that a read of .stack or a collection put in the original file is found again by the name of its source, in the own source maps that were read. The lines of the loaded file are no longer shown under a frame in the original file: only one order had them. The record of a module keeps no source text. The parse that reads the map for a printed error gives the text as well, and a later error reads the map again, as for every other map. One reader in bun_sourcemap opens every file that a source map names. It refuses a NUL, a FIFO and a device. With an Error.prepareStackTrace installed, the text that a collection makes for an unread stack is in the loaded file, as the call sites are. module.getSourceMapsSupport() gives one object until the switch is set again, as in Node.js.
…its own source map A transpiled module says whether it has a sourceMappingURL comment and whether the switch asked for that map. bun test --isolate gives the module to a later file only while the switch asks the same. A module with no such comment is no longer transpiled again when the switch changes.
The scan of a Worker's execArgv for its flags goes through the option table of the command line. The word after an option that takes a value is the value of that option, and the scan goes on after it. The scan stops at "--" and at the first positional. A word that the parser rejects is skipped. --enable-source-maps, --no-addons and --no-ffi-cc take effect after an option and its value, for example after --require ./preload.js. A Worker with --disallow-code-generation-from-strings there is refused. A word in the place of a value is that value, also when it has the text of a flag.
The lexer records the URL only if the marker is the third byte of the comment: //#, //@, /*# or /*@. This is the rule of esbuild. Before, a mention of the comment in other text named a source map. The runtime applies the rule of V8 to the recorded range. The comment must be a // comment. Only white space can follow the URL on its line. A comment that fails the rule gives the module no source map of its own. In debug builds, the lexer asserts that the range of each pragma argument is where its text is in the source. Three forms still differ from Node.js. docs/runtime/debugger.mdx lists them.
The lexer records the URL of a comment that starts with //# or //@, one white space character and sourceMappingURL=. White space before the URL is not a part of it, and only white space ends it. A block comment names no source map. The last such comment of a file counts, also when it has no URL. All 49 forms of the comment that were run give the same source map under Node.js v26.13.0. RuntimeTranspilerStore::transpile takes the switch from its caller.
A hook of Module.prototype._compile can give the native _compile another text than the loader gave the hook. The own source map of the module is for the file on the disk, so the module loses it then. A hook that gives the text on as it is keeps the map.
…n, bun build and a minified bundle The tests are in the block "a loaded file with its own source map". An ES module gets the switch as it is when import() is called. A second run takes the modules from the transpiler cache and prints the same. A module that import() reaches through a static import gets the switch as it is when Bun loads that module. Node.js gives it the switch as it is at the import() call. The test has the value of Node.js beside each line. A preload turns the switch on before the entry point loads its modules. A module that the entry point imports turns it on too late for the next import. The text that the onLoad of a plugin returns is mapped when the path of the module is a file path. It is not mapped in another namespace. A file that bun build makes for Bun keeps the positions of its build, with and without the switch. A file that bun build makes for Node.js is mapped through its sourceMappingURL comment. The collection that Bun runs after the entry point has loaded reads the source map before the program reads a stack. A frame of a one-line bundle of two sources can be in another source file than the one Node.js reports. A printed error has no source lines when nothing has the text of the source. The documentation lists these differences from Node.js. It says which built files keep the positions of their own build.
… --hot and --watch The own source map of a module is read once for each load of the module. A tool that builds a file writes the source map after it, so --hot could load the module and read the map of the build before. The watcher now has the file of the map, and a change of it loads the module again.
…etSourceMapsSupport Eight tests in the block "a loaded file with its own source map" say what Node.js prints. Each of them now runs its program under the Node.js on the PATH too, when that Node.js is v26.9.0 or later. Node.js gets a folder of its own with the same files. The test compares what Node.js prints with the table that Bun is held to, by the file and the line of each frame. Without such a Node.js, the test runs Bun only. The table of sourceMappingURL forms has four new rows: a path with a drive letter, with slashes and with backslashes, a backslash in a relative path, and a host. The table of source names has two new rows: a backslash in a relative source, and a source that starts with two slashes. These rows run on every platform. test-module-setsourcemapssupport.js is the file of Node.js v26.13.0.
Node.js refuses such a URL there. On Windows it is a UNC path. The rows of the tests that Node.js answers the same run under Node.js too, where a Node.js that reads source maps lazily is on the machine.
The bench is a port of benchmark/module/module-require-source-map.js of Node.js. It loads modules with no source map, with an inline source map and with an external source map. It also loads modules of more than 4 KiB, and modules through import(). Each class of module runs with the source maps switch off and with it on, in a process of its own. A run has three phases: the load, the first read of a stack of each module, and in Bun a collection that is the first reader of the source maps. The file runs under Node.js too, with --enable-source-maps.
Collaborator
Author
Collaborator
Author
|
Status
|
…rol character out of a Windows file name The AOT test that reads every getter of the host objects prints the new process.sourceMapsEnabled getter. Windows has no file with a control character in its name, so the row of the URL table that needs one runs on POSIX only.
Collaborator
Author
|
The two failures in Why this PR shows it
The defect is on
|
This was referenced Nov 2, 2026
…ce-maps-switch # Conflicts: # src/sourcemap/Mapping.rs
…ce-maps-switch # Conflicts: # src/jsc/RuntimeTranspilerStore.rs # src/jsc/SavedSourceMap.rs # src/jsc/VirtualMachine.rs # src/runtime/hw_exports.rs
This was referenced Nov 6, 2026
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #2125
Problem
//# sourceMappingURL=.Error.stacksaysat boom (/repro/index.js:5:15).node --enable-source-mapssaysindex.ts:6.--enable-source-mapsandprocess.setSourceMapsEnabled()do nothing.module.setSourceMapsSupport()does not exist.Fix
SavedSourceMap, off by default.put_mappingskeeps the URL of the comment. The first stack that needs the map reads it, as Node.js does since v26.9.0.OriginalforError.stackand printed errors,LoadedforCallSite, coverage, snapshots and profiles.test/js/bun/sourcemap/source-positions.test.ts, 36 new tests. Self-reviewed: 17 concerns raised, 15 addressed (see notes).Background
SavedSourceMapis the per-VM table of the maps that Bun's transpiler wrote, from the running text to the loaded file.requireof typeorm), the first.stackread only (no hook on main, Error.prepareStackTrace runs for a stack first read after a GC #46400).Downsides
module.findSourceMap(),evalandnew Functioncode,util.getCallSites(), index maps.Notes
Repro (the files of the issue,
tsc --sourceMapoutput):The same with an inline
data:application/json;base64,map. Node.js v26.13.0 printsindex.ts:6:9(V8 reports the column ofnew).What the switch is.
--enable-source-mapsandprocess.setSourceMapsEnabled(v)setenabled,nodeModulesandgeneratedCodetov.module.setSourceMapsSupport(enabled, { nodeModules, generatedCode })sets each.process.sourceMapsEnabledandmodule.getSourceMapsSupport()read them.module.setSourceMapsSupport(),module.getSourceMapsSupport()andprocess.sourceMapsEnabledare new in Bun. A Worker takes the command-line value, or its ownexecArgv.bun test --isolateputs the command-line value back before each file. A module innode_modulesis mapped only withnodeModules. A module is bound with the switch as it is when the module is asked for, and a lookup checks the switch again, as Node.js does.How a position is mapped. The lexer records the URL of the last
//# sourceMappingURL=or//@ sourceMappingURL=comment as V8 reads it (49 forms of the comment give the same answer as Node.js v26.13.0). The range goes throughAst, the printer and the transpiler cache toput_mappings, so a cache hit binds the same as a transpile. With the switch on, the table entry of the module is a record with Bun's map and the URL. AnOriginallookup first maps the running position to the loaded file, then reads the module's own map (once, a failure is kept) and maps on. Where the own map has nothing, the frame stays in the loaded file.Node.js parity that the tests run. Where a Node.js of v26.9.0 or later is on
PATH(CI has v26.12.1), these tests run the same fixture under Node.js and compare file and line: the 11 orderings of the switch, thenode_modulesrule, 54 forms of the URL, 21 forms of a source name, the ES module orderings, preloads,--target=nodeoutput andCallSite.test-module-setsourcemapssupport.jsof Node.js v26.13.0 is added verbatim and passes. Every row was checked against v26.13.0 and v26.12.1. Node.js v26.8 and earlier read the map at module load, so three orderings differ there.Measurements (release builds of cee9dd9 and of this branch, user instructions by
perf_event_openwith a fixed heap layout;perf,valgrind,straceandbloatyare not on the machine):requireof typeorm, 640 modules).mapopenednew Error().stack, switch offAstResolvedSourcestays 136 Bbun build --compile --aot --trimof hello world (CI, Linux x64)compile-aot-size.test.tsfails on main already: its limit is 25,880,000 B.mapopened, +0 reads, +128 kB. Node.js v26.13.0 also opens noneconsole.error(error)with a 1 MB map that hassourcesContentdata:URLbench/sourcemap/own-source-map-bench.mjsis a port of the benchmark of nodejs/node#65490 with two more phases. Load throughput with the switch off and on is within the noise of the base build in all five classes.Differences from Node.js (all in
docs/runtime/debugger.mdx):import()reaches through a static import gets the switch as it is when Bun loads that module.require.extensionshandler compiles withmodule._compile()is not mapped. A handler that changes the text before_compiletakes the module's own map away.--no-enable-source-mapsis no flag, and Bun does not readNODE_OPTIONS.Open, and why.
SourceMap#findEntryhas the same error). sourcemap: keep amappingssegment that has no source #47734 fixes the decoder. This PR needs no code change for it: a lookup that finds no source keeps the position in the loaded file, as in Node.js. A test of the two together is not written yet.bun_sourcemap::parse_jsonresets the AST store of the thread it runs on. A collection can run it in the middle of a.jsoncor.tomlload. This path parses under its own allocator and has a test for it. Main has the same error for a// @bunfile with a sidecar map. sourcemap: parse source-map JSON in a private AST scope #47703 fixes it inparse_jsonitself. When it lands, the allocator scope of this path is no longer needed.onLoadreturned #46148 gives a plugin's inline map to the printer. With both merged, a plugin's inline map would be applied twice under the switch. The order of the three needs a maintainer. bun test --coverage reports branches #46534 takes a transpiler cache version too. lexer: report JSX pragma warnings at the pragma argument #39636 and bundler: compose source maps through an input file's sourceMappingURL map #45638 carry the same fix of the pragma offsets in the lexer.testing=DelayFlowRules) fail with this change. They hold back rules by a hash that includes the ids of the built-ins, and the new exports ofnode:moduleandprocessshift the ids. The engine that main pins then gives an answer that depends on the order of its rules. The test that fails changes with the table of main: first the twoplugin-named-on-an-object-filled-under-the-keys-of-...-with-flow-rules-delayed.irfiles (ir-1,ir-5), and after the merge of 675ee5bcreate-require-read-late-on-a-copy-of-node-module-returns-a-require-function-with-flow-rules-delayed.ir(ir-6). The defect is in the value-flow solver of the engine (oven-sh/WebKit), not in this change: on main, the second test fails for 11 of 256 schedules, for exampletesting=DelayFlowRules:20. AOT: miscompilations and crashes found since #967, builds that never ended, faster loops WebKit#971 fixes the first, and on the engine of AOT: hangs, wrong answers, failed builds;bun test --aotfollows #44833's mocks #47605 256 of 256 schedules of the second pass, with and without the table of this branch (checked locally). AOT: hangs, wrong answers, failed builds;bun test --aotfollows #44833's mocks #47605 was closed without a merge on 2026-11-07. AOT: front end, test runs and tests for the rewritten compiler #47942 replaces the front end of the compiler and its tests, and these IR tests are not in its tree. Until it merges, one such test is red on this branch.module.findSourceMap(), generated code and the defaultError.prepareStackTracetext in the same release. They are not in this change.Suites run (debug build):
source-positions.test.ts361,external-sourcemap-stack-leak.test.ts4,isolation.test.ts157 (1 failure that main has too: a 5 s timeout in--isolate=modules),parallel.test.ts57,transpiler-cache.test.ts36,as-node.test.ts13,node-module-module.test.js85,sourcemap.test.js14,require-extensions.test.ts22,process.test.js201 (1 failure that main has too: the host's Node.js version),worker_threads.test.ts171,bundler_jsx.test.ts66,inspect-error.test.js47,capture-stack-trace.test.js76,transpiler.test.js258,bundler_comments.test.ts50, six vendored Node.js tests.bun run rust:check-allpasses for the 12 targets.no test proof · iteration 9 · platform-specific test(s) that do not run on this machine, deferring to CI, which covers all platforms: test/js/node/process/process.test.js, test/js/node/module/node-module-module.test.js, test/js/bun/sourcemap/source-positions.test.ts, test/cli/test/parallel.test.ts, test/cli/test/isolation.test.ts, test/cli/run/transpiler-cache.test.ts, test/cli/run/as-node.test.ts