feat(core): Address resolveSourceMap PR comments

1. Added better debug logging around the `resolveSourceMap` hook invocation
2. Expanded the `resolveSourceMap` doc comment to include more detail and an example use case
3. Added `resolveSourceMap` documentation to `generate-documentation-table.ts`
4. Removed the feature-specific playground test previously added

Author: thecodewarrior

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

@@ -125,7 +125,10 @@ export async function determineSourceMapPathFromBundle(
   const searchLocations: string[] = [];
 
   if (resolveSourceMapHook) {
+    logger.debug(`Calling sourcemaps.resolveSourceMap(${JSON.stringify(bundlePath)}, ${JSON.stringify(sourceMappingUrl)})`);
     const customPath = await resolveSourceMapHook(bundlePath, sourceMappingUrl);
+    logger.debug(`resolveSourceMap hook returned: ${JSON.stringify(customPath)}`);
+
     if (customPath) {
       searchLocations.push(customPath);
     }
@@ -166,7 +169,8 @@ export async function determineSourceMapPathFromBundle(
 
   // This is just a debug message because it can be quite spammy for some frameworks
   logger.debug(
-    `Could not determine source map path for bundle: \`${bundlePath}\`` +
+    `Could not determine source map path for bundle \`${bundlePath}\`` +
+    ` with sourceMappingURL=${sourceMappingUrl === undefined ? "undefined" : `\`${sourceMappingUrl}\``}` +
     ` - Did you turn on source map generation in your bundler?` +
     ` (Attempted paths: ${searchLocations.map(e => `\`${e}\``).join(", ")})`
   );

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

@@ -130,9 +130,20 @@ export interface Options {
      * Hook to customize source map file resolution.
      *
      * The hook is called with the absolute path of the build artifact and the value of the `//# sourceMappingURL=`
-     * comment, if present. The hook should then return an absolute path indicating where to find the artifact's
-     * corresponding `.map` file. If no path is returned or the returned path doesn't exist, the standard source map
-     * resolution process will be used.
+     * comment, if present. The hook should then return an absolute path (or a promise that resolves to one) indicating
+     * where to find the artifact's corresponding source map file. If no path is returned or the returned path doesn't
+     * exist, the standard source map resolution process will be used.
+     *
+     * The standard process first tries to resolve based on the `//# sourceMappingURL=` value (it supports `file://`
+     * urls and absolute/relative paths). If that path doesn't exist, it then looks for a file named
+     * `${artifactName}.map` in the same directory as the artifact.
+     *
+     * Note: This is mostly helpful for complex builds with custom source map generation. For example, if you put source
+     * maps into a separate directory and rewrite the `//# sourceMappingURL=` comment to something other than a relative
+     * directory, sentry will be unable to locate the source maps for a given build artifact. This hook allows you to
+     * implement the resolution process yourself.
+     *
+     * Use the `debug` option to print information about source map resolution.
      */
     resolveSourceMap?: ResolveSourceMapHook;
 

packages/dev-utils/src/generate-documentation-table.ts

@@ -96,6 +96,28 @@ errorHandler: (err) => {
         fullDescription:
           "Hook to rewrite the `sources` field inside the source map before being uploaded to Sentry. Does not modify the actual source map. Effectively, this modifies how files inside the stacktrace will show up in Sentry.\n\nDefaults to making all sources relative to `process.cwd()` while building.",
       },
+      {
+        name: "resolveSourceMap",
+        type: "(artifactPath: string, sourceMappingUrl: string | undefined) => string | undefined | Promise<string | undefined>",
+        fullDescription: `Hook to customize source map file resolution.
+
+The hook is called with the absolute path of the build artifact and the value of the \`//# sourceMappingURL=\`
+comment, if present. The hook should then return an absolute path (or a promise that resolves to one) indicating
+where to find the artifact's corresponding source map file. If no path is returned or the returned path doesn't
+exist, the standard source map resolution process will be used.
+
+The standard process first tries to resolve based on the \`//# sourceMappingURL=\` value (it supports \`file://\`
+urls and absolute/relative paths). If that path doesn't exist, it then looks for a file named
+\`\${artifactName}.map\` in the same directory as the artifact.
+
+Note: This is mostly helpful for complex builds with custom source map generation. For example, if you put source
+maps into a separate directory and rewrite the \`//# sourceMappingURL=\` comment to something other than a relative
+directory, sentry will be unable to locate the source maps for a given build artifact. This hook allows you to 
+implement the resolution process yourself.
+
+Use the \`debug\` option to print information about source map resolution.
+`,
+      },
       {
         name: "filesToDeleteAfterUpload",
         type: "string | string[] | Promise<string | string[]>",

packages/playground/build-webpack-resolveSourceMap.js

@@ -4,12 +4,11 @@
   "license": "MIT",
   "private": true,
   "scripts": {
-    "build:playground": "run-p build:rollup build:vite build:webpack4 build:webpack5 build:webpackResolveSourceMap build:esbuild",
+    "build:playground": "run-p build:rollup build:vite build:webpack4 build:webpack5 build:esbuild",
     "build:rollup": "rollup --config rollup.config.mjs",
     "build:vite": "vite build --config vite.config.js",
     "build:webpack4": "node build-webpack4.js",
     "build:webpack5": "node build-webpack5.js",
-    "build:webpackResolveSourceMap": "node build-webpack-resolveSourceMap.js",
     "build:esbuild": "node build-esbuild.js",
     "build:smallNodeApp": "vite build --config vite.config.smallNodeApp.js",
     "clean": "run-s clean:build",