feat: Promote debug ID uploading to stable via sourcemaps option (#204)

Co-authored-by: Abhijeet Prasad <[email protected]>

Author: Luca Forstner

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

@@ -20,7 +20,7 @@ import {
 } from "./sentry/telemetry";
 import { Span, Transaction } from "@sentry/types";
 import { createLogger, Logger } from "./sentry/logger";
-import { InternalOptions, normalizeUserOptions, validateOptions } from "./options-mapping";
+import { NormalizedOptions, normalizeUserOptions, validateOptions } from "./options-mapping";
 import { getSentryCli } from "./sentry/cli";
 import { makeMain } from "@sentry/node";
 import os from "os";
@@ -70,18 +70,18 @@ const esbuildDebugIdInjectionFilePath = require.resolve(
  *
  * This release creation pipeline relies on Sentry CLI to execute the different steps.
  */
-const unplugin = createUnplugin<Options, true>((options, unpluginMetaContext) => {
-  const internalOptions = normalizeUserOptions(options);
+const unplugin = createUnplugin<Options, true>((userOptions, unpluginMetaContext) => {
+  const options = normalizeUserOptions(userOptions);
 
-  const allowedToSendTelemetryPromise = shouldSendTelemetry(internalOptions);
+  const allowedToSendTelemetryPromise = shouldSendTelemetry(options);
 
   const { sentryHub, sentryClient } = makeSentryClient(
     "https://[email protected]/6690737",
     allowedToSendTelemetryPromise,
-    internalOptions.project
+    options.project
   );
 
-  addPluginOptionInformationToHub(internalOptions, sentryHub, unpluginMetaContext.framework);
+  addPluginOptionInformationToHub(options, sentryHub, unpluginMetaContext.framework);
 
   //TODO: This call is problematic because as soon as we set our hub as the current hub
   //      we might interfere with other plugins that use Sentry. However, for now, we'll
@@ -92,23 +92,23 @@ const unplugin = createUnplugin<Options, true>((options, unpluginMetaContext) =>
 
   const logger = createLogger({
     prefix: `[sentry-${unpluginMetaContext.framework}-plugin]`,
-    silent: internalOptions.silent,
-    debug: internalOptions.debug,
+    silent: options.silent,
+    debug: options.debug,
   });
 
-  if (!validateOptions(internalOptions, logger)) {
+  if (!validateOptions(options, logger)) {
     handleError(
       new Error("Options were not set correctly. See output above for more details."),
       logger,
-      internalOptions.errorHandler
+      options.errorHandler
     );
   }
 
-  const cli = getSentryCli(internalOptions, logger);
+  const cli = getSentryCli(options, logger);
 
   const releaseNamePromise = new Promise<string>((resolve) => {
-    if (options.release) {
-      resolve(options.release);
+    if (userOptions.release) {
+      resolve(userOptions.release);
     } else {
       resolve(cli.releases.proposeVersion());
     }
@@ -156,7 +156,7 @@ const unplugin = createUnplugin<Options, true>((options, unpluginMetaContext) =>
             "Unable to determine a release name. Make sure to set the `release` option or use an environment that supports auto-detection https://docs.sentry.io/cli/releases/#creating-releases`"
           ),
           logger,
-          internalOptions.errorHandler
+          options.errorHandler
         );
       }
 
@@ -211,13 +211,13 @@ const unplugin = createUnplugin<Options, true>((options, unpluginMetaContext) =>
       // a windows style path to `releaseInjectionTargets`
       const normalizedId = path.normalize(id);
 
-      if (internalOptions.releaseInjectionTargets) {
+      if (options.releaseInjectionTargets) {
         // If there's an `releaseInjectionTargets` option transform (ie. inject the release varible) when the file path matches the option.
-        if (typeof internalOptions.releaseInjectionTargets === "function") {
-          return internalOptions.releaseInjectionTargets(normalizedId);
+        if (typeof options.releaseInjectionTargets === "function") {
+          return options.releaseInjectionTargets(normalizedId);
         }
 
-        return internalOptions.releaseInjectionTargets.some((entry) => {
+        return options.releaseInjectionTargets.some((entry) => {
           if (entry instanceof RegExp) {
             return entry.test(normalizedId);
           } else {
@@ -247,7 +247,7 @@ const unplugin = createUnplugin<Options, true>((options, unpluginMetaContext) =>
     async transform(code, id) {
       logger.debug('Called "transform":', { id });
 
-      if (!internalOptions.injectRelease) {
+      if (!options.injectRelease) {
         return;
       }
 
@@ -259,10 +259,10 @@ const unplugin = createUnplugin<Options, true>((options, unpluginMetaContext) =>
         ms.append(
           generateGlobalInjectorCode({
             release: await releaseNamePromise,
-            injectReleasesMap: internalOptions.injectReleasesMap,
-            injectBuildInformation: internalOptions._experiments.injectBuildInformation || false,
-            org: internalOptions.org,
-            project: internalOptions.project,
+            injectReleasesMap: options.injectReleasesMap,
+            injectBuildInformation: options._experiments.injectBuildInformation || false,
+            org: options.org,
+            project: options.project,
           })
         );
       } else {
@@ -314,12 +314,12 @@ const unplugin = createUnplugin<Options, true>((options, unpluginMetaContext) =>
 
       try {
         if (!unpluginMetaContext.watchMode) {
-          if (internalOptions._experiments.debugIdUpload) {
+          if (options.sourcemaps?.assets) {
             const debugIdChunkFilePaths = (
-              await glob(internalOptions._experiments.debugIdUpload.include, {
+              await glob(options.sourcemaps.assets, {
                 absolute: true,
                 nodir: true,
-                ignore: internalOptions._experiments.debugIdUpload.ignore,
+                ignore: options.sourcemaps.ignore,
               })
             ).filter((p) => p.endsWith(".js") || p.endsWith(".mjs") || p.endsWith(".cjs"));
 
@@ -363,15 +363,15 @@ const unplugin = createUnplugin<Options, true>((options, unpluginMetaContext) =>
             );
 
             tmpUploadFolder = await sourceFileUploadFolderPromise;
-            await uploadDebugIdSourcemaps(internalOptions, ctx, tmpUploadFolder, releaseName);
+            await uploadDebugIdSourcemaps(options, ctx, tmpUploadFolder, releaseName);
           }
 
-          await createNewRelease(internalOptions, ctx, releaseName);
-          await cleanArtifacts(internalOptions, ctx, releaseName);
-          await uploadSourceMaps(internalOptions, ctx, releaseName);
-          await setCommits(internalOptions, ctx, releaseName);
-          await finalizeRelease(internalOptions, ctx, releaseName);
-          await addDeploy(internalOptions, ctx, releaseName);
+          await createNewRelease(options, ctx, releaseName);
+          await cleanArtifacts(options, ctx, releaseName);
+          await uploadSourceMaps(options, ctx, releaseName);
+          await setCommits(options, ctx, releaseName);
+          await finalizeRelease(options, ctx, releaseName);
+          await addDeploy(options, ctx, releaseName);
         }
         transaction?.setStatus("ok");
       } catch (e: unknown) {
@@ -380,7 +380,7 @@ const unplugin = createUnplugin<Options, true>((options, unpluginMetaContext) =>
           level: "error",
           message: "Error during writeBundle",
         });
-        handleError(e, logger, internalOptions.errorHandler);
+        handleError(e, logger, options.errorHandler);
       } finally {
         if (tmpUploadFolder) {
           fs.rm(tmpUploadFolder, { recursive: true, force: true }, () => {
@@ -402,7 +402,7 @@ const unplugin = createUnplugin<Options, true>((options, unpluginMetaContext) =>
     rollup: {
       renderChunk(code, chunk) {
         if (
-          options._experiments?.debugIdUpload &&
+          options.sourcemaps?.assets &&
           [".js", ".mjs", ".cjs"].some((ending) => chunk.fileName.endsWith(ending)) // chunks could be any file (html, md, ...)
         ) {
           return injectDebugIdSnippetIntoChunk(code);
@@ -414,7 +414,7 @@ const unplugin = createUnplugin<Options, true>((options, unpluginMetaContext) =>
     vite: {
       renderChunk(code, chunk) {
         if (
-          options._experiments?.debugIdUpload &&
+          options.sourcemaps?.assets &&
           [".js", ".mjs", ".cjs"].some((ending) => chunk.fileName.endsWith(ending)) // chunks could be any file (html, md, ...)
         ) {
           return injectDebugIdSnippetIntoChunk(code);
@@ -424,7 +424,7 @@ const unplugin = createUnplugin<Options, true>((options, unpluginMetaContext) =>
       },
     },
     webpack(compiler) {
-      if (options._experiments?.debugIdUpload) {
+      if (options.sourcemaps?.assets) {
         // Cache inspired by https://github.com/webpack/webpack/pull/15454
         const cache = new WeakMap<sources.Source, sources.Source>();
 
@@ -488,7 +488,7 @@ const unplugin = createUnplugin<Options, true>((options, unpluginMetaContext) =>
   });
 
   if (unpluginMetaContext.framework === "esbuild") {
-    if (internalOptions._experiments.debugIdUpload) {
+    if (options.sourcemaps?.assets) {
       plugins.push({
         name: "sentry-esbuild-debug-id-plugin",
         esbuild: {
@@ -507,7 +507,7 @@ const unplugin = createUnplugin<Options, true>((options, unpluginMetaContext) =>
 function handleError(
   unknownError: unknown,
   logger: Logger,
-  errorHandler: InternalOptions["errorHandler"]
+  errorHandler: NormalizedOptions["errorHandler"]
 ) {
   if (unknownError instanceof Error) {
     logger.error(unknownError.message);

packages/bundler-plugin-core/src/options-mapping.ts

@@ -32,6 +32,7 @@ type OptionalInternalOptions = Partial<
     | "deploy"
     | "configFile"
     | "headers"
+    | "sourcemaps"
   >
 >;
 
@@ -40,7 +41,7 @@ type NormalizedInternalOptions = {
   include: InternalIncludeEntry[];
 };
 
-export type InternalOptions = RequiredInternalOptions &
+export type NormalizedOptions = RequiredInternalOptions &
   OptionalInternalOptions &
   NormalizedInternalOptions;
 
@@ -62,7 +63,7 @@ export type InternalIncludeEntry = RequiredInternalIncludeEntry &
 
 export const SENTRY_SAAS_URL = "https://sentry.io";
 
-export function normalizeUserOptions(userOptions: UserOptions): InternalOptions {
+export function normalizeUserOptions(userOptions: UserOptions) {
   const options = {
     // include is the only strictly required option
     // (normalizeInclude needs all userOptions to access top-level include options)
@@ -94,6 +95,7 @@ export function normalizeUserOptions(userOptions: UserOptions): InternalOptions
     injectReleasesMap: userOptions.injectReleasesMap ?? false,
     injectRelease: userOptions.injectRelease ?? true,
     uploadSourceMaps: userOptions.uploadSourceMaps ?? true,
+    sourcemaps: userOptions.sourcemaps,
     _experiments: userOptions._experiments ?? {},
 
     // These options and can also be set via env variables or the config file.
@@ -149,6 +151,10 @@ function normalizeReleaseInjectionTargets(
  * @return an array of `InternalIncludeEntry` objects.
  */
 function normalizeInclude(userOptions: UserOptions): InternalIncludeEntry[] {
+  if (!userOptions.include) {
+    return [];
+  }
+
   return arrayify(userOptions.include)
     .map((includeItem) =>
       typeof includeItem === "string" ? { paths: [includeItem] } : includeItem
@@ -198,7 +204,7 @@ function normalizeIncludeEntry(
  *
  * @returns `true` if the options are valid, `false` otherwise
  */
-export function validateOptions(options: InternalOptions, logger: Logger): boolean {
+export function validateOptions(options: NormalizedOptions, logger: Logger): boolean {
   if (options.injectReleasesMap && !options.org) {
     logger.error(
       "The `injectReleasesMap` option was set but it is only supported when the `org` option is also specified.",

packages/bundler-plugin-core/src/sentry/cli.ts

@@ -1,5 +1,5 @@
 import SentryCli, { SentryCliReleases } from "@sentry/cli";
-import { InternalOptions } from "../options-mapping";
+import { NormalizedOptions } from "../options-mapping";
 import { Logger } from "./logger";
 
 type SentryDryRunCLI = {
@@ -14,7 +14,7 @@ export type SentryCLILike = SentryCli | SentryDryRunCLI;
  * In case, users selected the `dryRun` options, this returns a stub
  * that makes no-ops out of most CLI operations
  */
-export function getSentryCli(internalOptions: InternalOptions, logger: Logger): SentryCLILike {
+export function getSentryCli(internalOptions: NormalizedOptions, logger: Logger): SentryCLILike {
   const { silent, org, project, authToken, url, vcsRemote, headers } = internalOptions;
   const cli = new SentryCli(internalOptions.configFile, {
     url,

packages/bundler-plugin-core/src/sentry/releasePipeline.ts

@@ -7,12 +7,12 @@
 //           - unnecessary functionality
 
 import { logger } from "@sentry/utils";
-import { InternalOptions } from "../options-mapping";
+import { NormalizedOptions } from "../options-mapping";
 import { BuildContext } from "../types";
 import { addSpanToTransaction } from "./telemetry";
 
 export async function createNewRelease(
-  options: InternalOptions,
+  options: NormalizedOptions,
   ctx: BuildContext,
   releaseName: string
 ): Promise<void> {
@@ -32,7 +32,7 @@ export async function createNewRelease(
 }
 
 export async function cleanArtifacts(
-  options: InternalOptions,
+  options: NormalizedOptions,
   ctx: BuildContext,
   releaseName: string
 ): Promise<void> {
@@ -57,7 +57,7 @@ export async function cleanArtifacts(
 }
 
 export async function uploadSourceMaps(
-  options: InternalOptions,
+  options: NormalizedOptions,
   ctx: BuildContext,
   releaseName: string
 ): Promise<void> {
@@ -88,7 +88,7 @@ export async function uploadSourceMaps(
 }
 
 export async function uploadDebugIdSourcemaps(
-  options: InternalOptions,
+  options: NormalizedOptions,
   ctx: BuildContext,
   folderPathToUpload: string,
   releaseName: string
@@ -121,7 +121,7 @@ export async function uploadDebugIdSourcemaps(
 }
 
 export async function setCommits(
-  options: InternalOptions,
+  options: NormalizedOptions,
   ctx: BuildContext,
   releaseName: string
 ): Promise<void> {
@@ -154,7 +154,7 @@ export async function setCommits(
 }
 
 export async function finalizeRelease(
-  options: InternalOptions,
+  options: NormalizedOptions,
   ctx: BuildContext,
   releaseName: string
 ): Promise<void> {
@@ -180,7 +180,7 @@ export async function finalizeRelease(
 }
 
 export async function addDeploy(
-  options: InternalOptions,
+  options: NormalizedOptions,
   ctx: BuildContext,
   releaseName: string
 ): Promise<void> {

packages/bundler-plugin-core/src/sentry/telemetry.ts

@@ -1,6 +1,6 @@
 import SentryCli from "@sentry/cli";
 import { defaultStackParser, Hub, makeNodeTransport, NodeClient, Span } from "@sentry/node";
-import { InternalOptions, SENTRY_SAAS_URL } from "../options-mapping";
+import { NormalizedOptions, SENTRY_SAAS_URL } from "../options-mapping";
 import { BuildContext } from "../types";
 
 const SENTRY_SAAS_HOSTNAME = "sentry.io";
@@ -81,7 +81,7 @@ export function addSpanToTransaction(
 }
 
 export function addPluginOptionInformationToHub(
-  options: InternalOptions,
+  options: NormalizedOptions,
   hub: Hub,
   bundler: "rollup" | "webpack" | "vite" | "esbuild"
 ) {
@@ -96,7 +96,7 @@ export function addPluginOptionInformationToHub(
     errorHandler,
     deploy,
     include,
-    _experiments,
+    sourcemaps,
   } = options;
 
   hub.setTag("include", include.length > 1 ? "multiple-entries" : "single-entry");
@@ -125,7 +125,7 @@ export function addPluginOptionInformationToHub(
   if (errorHandler) {
     hub.setTag("error-handler", "custom");
   }
-  if (_experiments.debugIdUpload) {
+  if (sourcemaps?.assets) {
     hub.setTag("debug-id-upload", true);
   }
 
@@ -140,7 +140,7 @@ export function addPluginOptionInformationToHub(
   hub.setUser({ id: org });
 }
 
-export async function shouldSendTelemetry(options: InternalOptions): Promise<boolean> {
+export async function shouldSendTelemetry(options: NormalizedOptions): Promise<boolean> {
   const { silent, org, project, authToken, url, vcsRemote, headers, telemetry, dryRun } = options;
 
   // `options.telemetry` defaults to true