Runtime plugins: positions go through the inline source map of what onLoad returned

docs/runtime/plugins.mdx

@@ -244,6 +244,38 @@ Bun.build({
 
 This plugin transforms all imports of the form `import env from "env"` into a JavaScript module that exports the current environment variables.
 
+#### Source maps
+
+A plugin that you register with `Bun.plugin()` can end `contents` with an inline source map of the file it rewrote: a `//# sourceMappingURL=` comment on a line of its own, with the map as a base64 `data:application/json` URL. Bun then reports stack traces and `bun test --coverage` lines at their positions in the file instead of their positions in `contents`.
+
+```ts plugin.ts icon="/icons/typescript.svg"
+import MagicString from "magic-string";
+import { basename } from "node:path";
+
+Bun.plugin({
+  name: "banner",
+  setup(build) {
+    build.onLoad({ filter: /\.ts$/ }, async ({ path }) => {
+      const code = new MagicString(await Bun.file(path).text());
+      code.prepend("/* generated */\n");
+      const map = code.generateMap({ source: basename(path), hires: true });
+      return {
+        contents: `${code}\n//# sourceMappingURL=${map.toUrl()}`,
+        loader: "ts",
+      };
+    });
+  },
+});
+```
+
+Load `plugin.ts` with [`preload`](/runtime/bunfig#preload), so that it runs before the files it rewrites.
+
+The map's `sources` must have exactly one entry, and it must resolve to the file. Bun resolves a relative entry from the file's directory, and does not read `sourceRoot`. Bun ignores any other map.
+
+Code that the map does not cover has no position in the file. Coverage leaves it out, and a stack frame in it keeps its position in `contents`.
+
+`Bun.build()` does not read the comment. With `--inspect`, the debugger shows `contents`, so all positions stay in `contents`.
+
 #### `.defer()`
 
 The `onLoad` callback receives a `defer` function, which returns a `Promise` that resolves once Bun has loaded all _other_ modules. Await it when a module's contents depend on other modules.

packages/bun-types/bun.d.ts

@@ -6387,6 +6387,15 @@ declare module "bun" {
   interface OnLoadResultSourceCode {
     /**
      * The source code of the module
+     *
+     * In a runtime plugin, `contents` can end with a
+     * `//# sourceMappingURL=data:application/json;base64,...` comment. If the
+     * only entry in that map's `sources` resolves to the file being loaded,
+     * stack traces and `bun test --coverage` report positions in the file
+     * instead of positions in `contents`. Code that the map does not cover
+     * keeps its position in `contents` and is left out of coverage.
+     *
+     * The comment has no effect in `Bun.build()` or with `--inspect`.
      */
     contents: string | ArrayBufferView | ArrayBuffer | SharedArrayBuffer;
     /**

src/js_printer/lib.rs

@@ -1267,6 +1267,8 @@ pub fn write_json_string<W: Write + ?Sized, const ENCODING: Encoding>(
 pub struct SourceMapHandler<'a> {
     pub(crate) ctx: NonNull<()>,
     pub(crate) callback: fn(*mut (), SourceMap::Chunk, &bun_ast::Source) -> crate::Result<()>,
+    /// The map the source came with.
+    pub input_source_map: Option<&'a SourceMap::ParsedSourceMap>,
     _marker: core::marker::PhantomData<&'a mut ()>,
 }
 
@@ -1306,6 +1308,7 @@ impl<'a> SourceMapHandler<'a> {
             // Type-erased to `*mut ()` and cast back to `*mut T` inside the thunk before dereference.
             ctx: NonNull::from(ctx).cast::<()>(),
             callback: thunk::<T>,
+            input_source_map: None,
             _marker: core::marker::PhantomData,
         }
     }
@@ -7673,6 +7676,10 @@ pub(crate) fn get_source_map_builder<'a, const IS_BUN_PLATFORM: bool>(
             },
             None => LineOffsetTables::None,
         },
+        input_source_map: opts
+            .source_map_handler
+            .as_ref()
+            .and_then(|handler| handler.input_source_map),
         ..Default::default()
     };
     // Pre-size the VLQ mappings buffer. With `--minify` we emit roughly one

src/jsc/VirtualMachine.rs

@@ -1722,6 +1722,7 @@ impl VirtualMachine {
         SourceMapHandlerGetter {
             vm: self,
             printer,
+            input_source_map: None,
             _marker: core::marker::PhantomData,
         }
     }
@@ -3824,6 +3825,8 @@ pub fn process_fetch_log(
 pub struct SourceMapHandlerGetter<'a> {
     vm: *mut VirtualMachine,
     printer: *mut bun_js_printer::BufferPrinter,
+    /// The map the source came with.
+    pub input_source_map: Option<&'a bun_sourcemap::ParsedSourceMap>,
     _marker: core::marker::PhantomData<&'a mut ()>,
 }
 
@@ -3843,6 +3846,7 @@ impl<'a> SourceMapHandlerGetter<'a> {
         Self {
             vm,
             printer,
+            input_source_map: None,
             _marker: core::marker::PhantomData,
         }
     }
@@ -3901,11 +3905,15 @@ impl<'a> SourceMapHandlerGetter<'a> {
             Some(d) if d.mode != crate::debugger::Mode::Connect
         );
         if !wants_inline_source_map {
+            let input_source_map = self.input_source_map;
             // `source_mappings` is a value field on the VM, exclusively
             // borrowed for the returned handler's lifetime (bounded by
             // `&mut self`).
-            return bun_js_printer::SourceMapHandler::for_(self.vm_source_mappings_mut());
+            let mut handler = bun_js_printer::SourceMapHandler::for_(self.vm_source_mappings_mut());
+            handler.input_source_map = input_source_map;
+            return handler;
         }
+        // The inspector shows the source, so the mappings stay positions in it.
         bun_js_printer::SourceMapHandler::for_(self)
     }
 }

src/runtime/jsc_hooks.rs

@@ -2491,6 +2491,7 @@ fn transpile_source_code_of_any_provenance(
             // ── Node-fallback virtual source ────────────────────────────────
             let fallback_source: bun_ast::Source;
             let mut virtual_source = args.virtual_source;
+            let input_source_map = virtual_source.and_then(bun_sourcemap::parse_input_source_map);
             if is_node_override {
                 if let Some(code) = node_fallbacks::contents_from_path(specifier) {
                     {
@@ -2633,7 +2634,9 @@ fn transpile_source_code_of_any_provenance(
                     keep_json_and_toml_as_one_statement: true,
                     allow_bytecode_cache: true,
                     set_breakpoint_on_first_line,
+                    // The cache's key is the text. With an input source map the path matters too.
                     runtime_transpiler_cache: if !disable_transpilying
+                        && input_source_map.is_none()
                         && !<RuntimeTranspilerCache as bun_bundler::RuntimeTranspilerCacheExt>::disabled()
                     {
                         Some(&mut cache)
@@ -3102,6 +3105,7 @@ fn transpile_source_code_of_any_provenance(
                     // is bounded by the block.
                     let mut mapper =
                         unsafe { (*jsc_vm).source_map_handler((*extra).source_code_printer) };
+                    mapper.input_source_map = input_source_map.as_deref();
                     // SAFETY: per fn contract — `jsc_vm` / `extra.source_code_printer`
                     // are live; the printer borrow is scoped to this call.
                     let print_result = unsafe {

src/sourcemap/Chunk.rs

@@ -4,8 +4,9 @@ use bun_paths::fs::FileSystem;
 use bun_ptr::RawSlice;
 
 use crate::{
-    InternalSourceMap, LineOffsetTable, SourceMapState, append_mapping_to_buffer,
-    internal_source_map, line_offset_table, line_offset_table::LineOffsetTableColumns as _,
+    InternalSourceMap, LineOffsetTable, Ordinal, ParsedSourceMap, SourceMapState,
+    append_mapping_to_buffer, internal_source_map, line_offset_table,
+    line_offset_table::LineOffsetTableColumns as _,
 };
 
 #[derive(Clone)]
@@ -350,6 +351,9 @@ impl LineOffsetTables<'_> {
     }
 }
 
+/// The `source_index` of a mapping that [`NewBuilder::input_source_map`] does not cover.
+pub const NOT_IN_INPUT_SOURCE_MAP: i32 = 1;
+
 pub struct NewBuilder<'a, T: SourceMapFormatCtx> {
     pub source_map: SourceMapFormat<T>,
     pub line_offset_tables: LineOffsetTables<'a>,
@@ -382,6 +386,9 @@ pub struct NewBuilder<'a, T: SourceMapFormatCtx> {
 
     /// When generating sourcemappings for bun, we store a count of how many mappings there were
     pub prepend_count: bool,
+
+    /// The map the source came with. Each mapping goes through it, or gets [`NOT_IN_INPUT_SOURCE_MAP`].
+    pub input_source_map: Option<&'a ParsedSourceMap>,
 }
 
 impl<T: SourceMapFormatCtx + Default> Default for NewBuilder<'_, T> {
@@ -401,6 +408,7 @@ impl<T: SourceMapFormatCtx + Default> Default for NewBuilder<'_, T> {
             line_starts_with_mapping: false,
             cover_lines_without_mappings: false,
             prepend_count: false,
+            input_source_map: None,
         }
     }
 }
@@ -603,7 +611,23 @@ impl NewBuilder<'_, VLQSourceMap> {
     }
 
     #[inline(always)]
-    pub(crate) fn append_mapping(&mut self, current_state: SourceMapState) {
+    pub(crate) fn append_mapping(&mut self, mut current_state: SourceMapState) {
+        if let Some(input) = self.input_source_map {
+            if let Some(mapping) = input.find_mapping(
+                Ordinal::from_zero_based(current_state.original_line),
+                Ordinal::from_zero_based(current_state.original_column),
+            ) {
+                current_state.source_index = 0;
+                current_state.original_line = mapping.original.lines.zero_based();
+                // The distance from the mapping stays, so a map with one mapping per line keeps the columns.
+                current_state.original_column =
+                    mapping.original.columns.zero_based().saturating_add(
+                        current_state.original_column - mapping.generated.columns.zero_based(),
+                    );
+            } else {
+                current_state.source_index = NOT_IN_INPUT_SOURCE_MAP;
+            }
+        }
         self.append_mapping_without_remapping(current_state);
     }
 

src/sourcemap/ParsedSourceMap.rs

@@ -237,6 +237,19 @@ impl ParsedSourceMap {
         !self.external_source_names.is_empty()
     }
 
+    pub fn only_source_is(&self, path: &[u8]) -> bool {
+        use bun_paths::{platform::Auto, resolve_path};
+
+        let [name] = self.external_source_names.as_slice() else {
+            return false;
+        };
+        bun_paths::is_absolute(path)
+            && resolve_path::join_abs_string_checked::<Auto>(
+                resolve_path::dirname::<Auto>(path),
+                &[name],
+            ) == Some(path)
+    }
+
     pub fn find_mapping(&self, line: Ordinal, column: Ordinal) -> Option<Mapping> {
         if let Some(ism) = &self.internal {
             return ism.find(line, column);

src/sourcemap/lib.rs

@@ -841,7 +841,9 @@ pub(crate) fn parse_url(
                         else {
                             break 'try_data_url;
                         };
-                        if &after[..comma] != b"base64" {
+                        // Babel and magic-string write `charset=utf-8;base64`.
+                        let parameters = &after[..comma];
+                        if parameters != b"base64" && !parameters.ends_with(b";base64") {
                             break 'try_data_url;
                         }
                         let base64_data = &after[comma + 1..];
@@ -866,6 +868,22 @@ pub(crate) fn parse_url(
     parse_json(json_bytes, hint)
 }
 
+/// The inline source map of what an `onLoad` plugin returned for a file, if it is a map of that file.
+pub fn parse_input_source_map(source: &bun_ast::Source) -> Option<std::sync::Arc<ParsedSourceMap>> {
+    let url = find_source_mapping_url_u8(source.contents())?;
+    let arena = bun_alloc::Arena::new();
+    let map = parse_url(&arena, url.slice(), ParseUrlResultHint::MappingsOnly)
+        .ok()?
+        .map?;
+    if !map.only_source_is(source.path.text) {
+        return None;
+    }
+    // A map that the file ends with too says how the file was made, and the plugin passed it on.
+    let is_from_the_file = bun_sys::File::read_from(bun_sys::Fd::cwd(), source.path.text)
+        .is_ok_and(|file| find_source_mapping_url_u8(&file).is_some_and(|own| *own == *url));
+    (!is_from_the_file).then_some(map)
+}
+
 /// Parses a JSON source-map
 ///
 /// `source` must be in UTF-8 and can be freed after this call.
@@ -907,15 +925,12 @@ pub(crate) fn parse_json(source: &[u8], hint: ParseUrlResultHint) -> crate::Resu
         return Err(crate::Error::InvalidSourceMap);
     };
 
-    let sources_content = match json
-        .get(b"sourcesContent")
-        .ok_or(crate::Error::InvalidSourceMap)?
-        .data
-    {
-        bun_ast::ExprData::EArrayJSON(arr) => arr,
-        _ => return Err(crate::Error::InvalidSourceMap),
+    let sources_content = match json.get(b"sourcesContent").map(|contents| contents.data) {
+        Some(bun_ast::ExprData::EArrayJSON(arr)) => Some(arr),
+        Some(bun_ast::ExprData::ENull(_)) | None => None,
+        Some(_) => return Err(crate::Error::InvalidSourceMap),
     };
-    let sources_content = sources_content.get();
+    let sources_content = sources_content.as_ref().map(|arr| arr.get().items());
 
     let sources_paths = match json
         .get(b"sources")
@@ -927,15 +942,16 @@ pub(crate) fn parse_json(source: &[u8], hint: ParseUrlResultHint) -> crate::Resu
     };
     let sources_paths = sources_paths.get();
 
-    if sources_content.items().len() != sources_paths.items().len() {
+    if sources_content.is_some_and(|contents| contents.len() != sources_paths.items().len()) {
         return Err(crate::Error::InvalidSourceMap);
     }
+    let sources_content = sources_content.unwrap_or_default();
 
     let source_only = matches!(hint, ParseUrlResultHint::SourceOnly(_));
 
     // `Vec<Box<[u8]>>` drops automatically on error.
     let source_paths_slice: Option<Vec<Box<[u8]>>> = if !source_only {
-        let mut v: Vec<Box<[u8]>> = Vec::with_capacity(sources_content.items().len());
+        let mut v: Vec<Box<[u8]>> = Vec::with_capacity(sources_paths.items().len());
         for item in sources_paths.items() {
             let Some(s) = item.as_str() else {
                 return Err(crate::Error::InvalidSourceMap);
@@ -1028,9 +1044,9 @@ pub(crate) fn parse_json(source: &[u8], hint: ParseUrlResultHint) -> crate::Resu
     let content_slice: Option<Box<[u8]>> = match source_index {
         Some(idx)
             if !matches!(hint, ParseUrlResultHint::MappingsOnly)
-                && (idx as usize) < sources_content.items().len() =>
+                && (idx as usize) < sources_content.len() =>
         'content: {
-            let item = &sources_content.items()[idx as usize];
+            let item = &sources_content[idx as usize];
             let Some(str) = item.as_str() else {
                 break 'content None;
             };

src/sourcemap_jsc/CodeCoverage.rs

@@ -7,7 +7,8 @@ use bun_collections::VecExt;
 use bun_collections::bit_set::DynamicBitSet;
 use bun_core::{self, Utf8Bytes};
 use bun_jsc::{JSGlobalObject, JSValue, VM, bun_string_jsc};
-use bun_sourcemap::{Ordinal, ParsedSourceMap};
+use bun_sourcemap::chunk::NOT_IN_INPUT_SOURCE_MAP;
+use bun_sourcemap::{Mapping, Ordinal, ParsedSourceMap};
 
 type LinesHits = Vec<u32>;
 type Bitset = DynamicBitSet;
@@ -687,6 +688,8 @@ impl ByteRangeMapping {
                 .as_mut()
                 .source_mappings()
                 .get(source_url)
+                // The lines in the map of a bundle are lines of other files.
+                .filter(|map| !map.is_external() || map.only_source_is(source_url))
         };
 
         let mut blocks: Vec<CountedRange> =
@@ -718,6 +721,9 @@ impl ByteRangeMapping {
         if let Some(source_map) = source_map.as_deref() {
             let mut previous_original = None;
             source_map.for_each_mapping(|mapping| {
+                if is_added_to_the_file(&mapping) {
+                    return;
+                }
                 // The printer repeats a mapping at column 0 of a line that starts without one.
                 let original = (
                     mapping.original.lines.zero_based(),
@@ -752,7 +758,9 @@ impl ByteRangeMapping {
         if let Some(source_map) = source_map.as_deref() {
             functions.retain(|function| {
                 let (line, column) = self.line_and_column_of(function.range.start);
-                source_map.find_mapping(line, column).is_some()
+                source_map
+                    .find_mapping(line, column)
+                    .is_some_and(|mapping| !is_added_to_the_file(&mapping))
             });
         }
 
@@ -827,6 +835,11 @@ impl ByteRangeMapping {
     }
 }
 
+/// Code that a plugin added to the file it rewrote: it has no line in the file.
+fn is_added_to_the_file(mapping: &Mapping) -> bool {
+    mapping.source_index == NOT_IN_INPUT_SOURCE_MAP
+}
+
 /// `ByteRangeMapping::line_starts` and `executable_units`. Lines end where
 /// `bun_sourcemap::Chunk`'s builder ends a generated line.
 fn scan(units: impl ExactSizeIterator<Item = u16>) -> (Vec<u32>, Bitset) {