fix(bundler-plugins): Stamp debug IDs onto emitted source maps when disable-upload is set

Author: msonnb

packages/bundler-plugins/src/core/debug-id-upload.ts

@@ -93,7 +93,7 @@ export async function prepareBundleForDebugIdUpload(
  *
  * The string pattern is injected via the debug ID injection snipped.
  */
-function determineDebugIdFromBundleSource(code: string): string | undefined {
+export function determineDebugIdFromBundleSource(code: string): string | undefined {
   const match = code.match(
     /sentry-dbid-([0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12})/,
   );
@@ -119,6 +119,95 @@ function addDebugIdToBundleSource(bundleSource: string, debugId: string): string
   }
 }
 
+function setDebugIdOnSourceMap(map: Record<string, unknown>, debugId: string): void {
+  // For now we write both fields until we know what will become the standard - if ever.
+  map['debug_id'] = debugId;
+  map['debugId'] = debugId;
+}
+
+/**
+ * Stamps the debug ID injected into `bundleSource` into the given source map.
+ *
+ * This exists for `sourcemaps.disable: "disable-upload"`: the regular upload path only stamps
+ * temporary copies of the artifacts (see `prepareBundleForDebugIdUpload`), so without this the
+ * emitted map would carry no debug ID and a later manual upload could not match it to the bundle.
+ * Only the map is touched. The bundle's bytes stay as emitted so subresource integrity hashes
+ * computed on them remain valid.
+ *
+ * @returns the stamped source map, or `undefined` if the bundle carries no debug ID or the map
+ * isn't valid JSON.
+ */
+export function addDebugIdToSourceMap(bundleSource: string, sourceMapSource: string): string | undefined {
+  const debugId = determineDebugIdFromBundleSource(bundleSource);
+  if (debugId === undefined) {
+    return undefined;
+  }
+
+  let map: unknown;
+  try {
+    map = JSON.parse(sourceMapSource);
+  } catch {
+    return undefined;
+  }
+
+  if (!map || typeof map !== 'object') {
+    return undefined;
+  }
+
+  setDebugIdOnSourceMap(map as Record<string, unknown>, debugId);
+  return JSON.stringify(map);
+}
+
+/**
+ * Stamps the debug ID of an emitted bundle into its source map file on disk.
+ *
+ * Used by bundlers that offer no hook to modify assets before they are written (esbuild).
+ * Rewrites only the map; the bundle itself is never modified.
+ */
+export async function addDebugIdToEmittedSourceMap(
+  bundleFilePath: string,
+  logger: Logger,
+  resolveSourceMapHook: ResolveSourceMapHook | undefined,
+): Promise<void> {
+  let bundleSource: string;
+  try {
+    bundleSource = await fs.promises.readFile(bundleFilePath, 'utf8');
+  } catch (e) {
+    logger.error(`Could not read bundle to stamp debug ID into its source map: ${bundleFilePath}`, e);
+    return;
+  }
+
+  const sourceMapPath = await determineSourceMapPathFromBundle(
+    bundleFilePath,
+    bundleSource,
+    logger,
+    resolveSourceMapHook,
+  );
+  if (!sourceMapPath) {
+    return;
+  }
+
+  let sourceMapSource: string;
+  try {
+    sourceMapSource = await fs.promises.readFile(sourceMapPath, 'utf8');
+  } catch (e) {
+    logger.error(`Could not read source map to stamp debug ID: ${sourceMapPath}`, e);
+    return;
+  }
+
+  const stampedSourceMap = addDebugIdToSourceMap(bundleSource, sourceMapSource);
+  if (stampedSourceMap === undefined) {
+    logger.debug(`Could not stamp debug ID into source map (no debug ID in bundle or invalid map): ${sourceMapPath}`);
+    return;
+  }
+
+  try {
+    await fs.promises.writeFile(sourceMapPath, stampedSourceMap, 'utf8');
+  } catch (e) {
+    logger.error(`Could not write debug ID into source map: ${sourceMapPath}`, e);
+  }
+}
+
 /**
  * Whether the bundle carries its source map inlined as `sourceMappingURL=data:`
  * URI, rather than referencing a separate `.map` file. Such bundles must still
@@ -223,9 +312,7 @@ async function prepareSourceMapForDebugIdUpload(
   let map: Record<string, unknown>;
   try {
     map = JSON.parse(sourceMapFileContent) as { sources: unknown; [key: string]: unknown };
-    // For now we write both fields until we know what will become the standard - if ever.
-    map['debug_id'] = debugId;
-    map['debugId'] = debugId;
+    setDebugIdOnSourceMap(map, debugId);
   } catch {
     logger.error(`Failed to parse source map for debug ID upload: ${sourceMapPath}`);
     return;

packages/bundler-plugins/src/core/index.ts

@@ -147,4 +147,4 @@ export {
   generateModuleMetadataInjectorCode,
 } from './utils';
 export { createSentryBuildPluginManager } from './build-plugin-manager';
-export { createDebugIdUploadFunction } from './debug-id-upload';
+export { createDebugIdUploadFunction, addDebugIdToSourceMap, addDebugIdToEmittedSourceMap } from './debug-id-upload';

packages/bundler-plugins/src/core/types.ts

@@ -114,8 +114,13 @@ export interface Options {
     /**
      * Disables all functionality related to sourcemaps if set to `true`.
      *
-     * If set to `"disable-upload"`, the plugin will not upload sourcemaps to Sentry, but will inject debug IDs into the build artifacts.
-     * This is useful if you want to manually upload sourcemaps to Sentry at a later point in time.
+     * If set to `"disable-upload"`, the plugin will not upload sourcemaps to Sentry, but will still inject debug IDs
+     * into the build artifacts: the bundles receive the runtime debug ID snippet and the emitted source maps receive
+     * the matching `debug_id` field. Bundles are not modified beyond the snippet (no `//# debugId=` comment is
+     * appended), so their bytes stay stable for subresource integrity hashes.
+     *
+     * This is useful if you want to manually upload sourcemaps to Sentry at a later point in time, e.g. with
+     * `sentry sourcemap upload`.
      *
      * @default false
      */

packages/bundler-plugins/src/esbuild/index.ts

@@ -6,6 +6,8 @@ import {
   getDebugIdSnippet,
   createDebugIdUploadFunction,
   CodeInjection,
+  addDebugIdToEmittedSourceMap,
+  isJsFile,
 } from '../core';
 import * as path from 'node:path';
 import { createRequire } from 'node:module';
@@ -51,6 +53,8 @@ interface EsbuildInitialOptions {
   inject?: string[];
   metafile?: boolean;
   define?: Record<string, string>;
+  write?: boolean;
+  absWorkingDir?: string;
 }
 
 interface EsbuildPluginBuild {
@@ -283,9 +287,32 @@ export function sentryEsbuildPlugin(userOptions: Options = {}): any {
         try {
           await sentryBuildPluginManager.createRelease();
 
-          if (sourcemapsEnabled && options.sourcemaps?.disable !== 'disable-upload') {
+          if (sourcemapsEnabled) {
             const buildArtifacts = result.metafile ? Object.keys(result.metafile.outputs) : [];
-            await upload(buildArtifacts);
+
+            if (options.sourcemaps?.disable !== 'disable-upload') {
+              await upload(buildArtifacts);
+            } else if (initialOptions.write === false) {
+              logger.debug(
+                'Build output is not written to disk. Skipping debug ID injection into emitted source maps.',
+              );
+            } else {
+              // The upload routine (which stamps debug IDs into temp copies of the source maps) is
+              // skipped with `disable-upload`. esbuild has no hook to modify outputs before they are
+              // written, so the emitted maps get stamped on disk instead.
+              const outputDir = initialOptions.absWorkingDir ?? process.cwd();
+              await Promise.all(
+                buildArtifacts
+                  .filter(isJsFile)
+                  .map(artifact =>
+                    addDebugIdToEmittedSourceMap(
+                      path.resolve(outputDir, artifact),
+                      logger,
+                      options.sourcemaps?.resolveSourceMap,
+                    ),
+                  ),
+              );
+            }
           }
         } finally {
           freeGlobalDependencyOnBuildArtifacts();

packages/bundler-plugins/src/rollup/index.ts

@@ -13,6 +13,7 @@ import {
   createComponentNameAnnotateHooks,
   replaceBooleanFlagsInCode,
   CodeInjection,
+  addDebugIdToSourceMap,
 } from '../core';
 import type {
   ComponentAnnotationTransformMeta,
@@ -28,6 +29,13 @@ import { createRequire } from 'node:module';
 // because `rollup` is an optional dependency.
 type TransformResult = { code: string; map?: SourceMap | string | { mappings: string } | null } | null | undefined;
 
+// The subset of Rollup's `OutputBundle` this plugin's `generateBundle` hook reads.
+type OutputBundle = Record<
+  string,
+  | { type: 'chunk'; fileName: string; code: string; sourcemapFileName?: string | null }
+  | { type: 'asset'; fileName: string; source: string | Uint8Array }
+>;
+
 type ViteModule = {
   parseAstAsync?: (code: string, options: { lang: 'jsx' | 'tsx' }) => Promise<unknown>;
 };
@@ -284,6 +292,27 @@ export function _rollupPluginInternal(
     };
   }
 
+  // The upload routine (which stamps debug IDs into temp copies of the source maps) is skipped
+  // with `disable-upload`, so the emitted maps get stamped before being written instead.
+  // Only the map is modified; the chunk's bytes stay untouched so subresource integrity hashes stay valid.
+  function generateBundle(_outputOptions: unknown, bundle: OutputBundle): void {
+    for (const output of Object.values(bundle)) {
+      if (output.type !== 'chunk' || !isJsFile(output.fileName)) {
+        continue;
+      }
+
+      const sourceMap = bundle[output.sourcemapFileName ?? `${output.fileName}.map`];
+      if (sourceMap?.type !== 'asset' || typeof sourceMap.source !== 'string') {
+        continue;
+      }
+
+      const stampedSourceMap = addDebugIdToSourceMap(output.code, sourceMap.source);
+      if (stampedSourceMap !== undefined) {
+        sourceMap.source = stampedSourceMap;
+      }
+    }
+  }
+
   async function writeBundle(
     outputOptions: { dir?: string; file?: string },
     bundle: { [fileName: string]: unknown },
@@ -318,29 +347,21 @@ export function _rollupPluginInternal(
   }
 
   const name = `sentry-${buildTool}-plugin`;
-
-  if (shouldTransform) {
-    const transformHook =
-      buildTool === 'vite'
-        ? {
-            filter: { id: JS_MODULE_ID_FILTER },
-            handler: transform,
-          }
-        : transform;
-
-    return {
-      name,
-      buildStart,
-      transform: transformHook,
-      renderChunk,
-      writeBundle,
-    };
-  }
+  const stampEmittedSourceMaps = sourcemapsEnabled && options.sourcemaps?.disable === 'disable-upload';
+  const transformHook =
+    buildTool === 'vite'
+      ? {
+          filter: { id: JS_MODULE_ID_FILTER },
+          handler: transform,
+        }
+      : transform;
 
   return {
     name,
     buildStart,
+    ...(shouldTransform ? { transform: transformHook } : {}),
     renderChunk,
+    ...(stampEmittedSourceMaps ? { generateBundle } : {}),
     writeBundle,
   };
 }