ref(core): Make various user and internal options optional (#103)

Adjust some user-facing and internal options from being strictly required to being optional. The reason for this change is that with the introduction of Sentry CLI, we can (and for feature parity should) let users either use env variables or specify some values via a `.sentryclirc` config file. 

Note that for release injection to work properly, users have to specify `project`, `org` and `release` either via the options or via env variables. The reason is that the config file which could also hold these options is only later used by Sentry CLI. This behaviour is identical to what we do in the webpack plugin.

Author: Lms24

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

@@ -1,15 +1,11 @@
 import { IncludeEntry as UserIncludeEntry, Options as UserOptions } from "./types";
+import { arrayify } from "./utils";
 
 type RequiredInternalOptions = Required<
   Pick<
     UserOptions,
-    | "org"
-    | "project"
-    | "authToken"
-    | "url"
     | "release"
     | "finalize"
-    | "vcsRemote"
     | "dryRun"
     | "debug"
     | "silent"
@@ -22,7 +18,17 @@ type RequiredInternalOptions = Required<
 type OptionalInternalOptions = Partial<
   Pick<
     UserOptions,
-    "dist" | "errorHandler" | "setCommits" | "deploy" | "configFile" | "customHeader"
+    | "org"
+    | "project"
+    | "authToken"
+    | "url"
+    | "vcsRemote"
+    | "dist"
+    | "errorHandler"
+    | "setCommits"
+    | "deploy"
+    | "configFile"
+    | "customHeader"
   >
 >;
 
@@ -52,59 +58,88 @@ export type InternalIncludeEntry = RequiredInternalIncludeEntry &
   };
 
 export function normalizeUserOptions(userOptions: UserOptions): InternalOptions {
-  let entries: (string | RegExp)[] | ((filePath: string) => boolean) | undefined;
-  if (userOptions.entries === undefined) {
-    entries = undefined;
-  } else if (typeof userOptions.entries === "function" || Array.isArray(userOptions.entries)) {
-    entries = userOptions.entries;
-  } else {
-    entries = [userOptions.entries];
-  }
-
-  let userInclude: UserIncludeEntry[];
-  if (typeof userOptions.include === "string") {
-    userInclude = [convertIncludePathToIncludeEntry(userOptions.include)];
-  } else if (Array.isArray(userOptions.include)) {
-    userInclude = userOptions.include.map((potentialIncludeEntry) => {
-      if (typeof potentialIncludeEntry === "string") {
-        return convertIncludePathToIncludeEntry(potentialIncludeEntry);
-      } else {
-        return potentialIncludeEntry;
-      }
-    });
-  } else {
-    userInclude = [userOptions.include];
-  }
+  return {
+    // include is the only strictly required option
+    // (normalizeInclude needs all userOptions to access top-level include options)
+    include: normalizeInclude(userOptions),
 
-  const include = userInclude.map((userIncludeEntry) =>
-    normalizeIncludeEntry(userOptions, userIncludeEntry)
-  );
+    // These options must be set b/c we need them for release injection.
+    // They can also be set as environment variables. Technically, they
+    // could be set in the config file but this would be too late for
+    // release injection because we only pass the config file path
+    // to the CLI
+    org: userOptions.org ?? process.env["SENTRY_ORG"],
+    project: userOptions.project ?? process.env["SENTRY_PROJECT"],
+    // Falling back to the empty string here b/c at a later point, we use
+    // Sentry CLI to determine a release if none was specified via options
+    // or env vars. In case we don't find one, we'll bail at that point.
+    release: userOptions.release ?? process.env["SENTRY_RELEASE"] ?? "",
 
-  return {
-    org: userOptions.org,
-    project: userOptions.project,
-    authToken: userOptions.authToken,
-    url: userOptions.url ?? "https://sentry.io/",
-    release: userOptions.release ?? "",
+    // Options with default values
     finalize: userOptions.finalize ?? true,
-    vcsRemote: userOptions.vcsRemote ?? "origin",
-    customHeader: userOptions.customHeader,
+    cleanArtifacts: userOptions.cleanArtifacts ?? false,
     dryRun: userOptions.dryRun ?? false,
     debug: userOptions.debug ?? false,
     silent: userOptions.silent ?? false,
-    cleanArtifacts: userOptions.cleanArtifacts ?? false,
     telemetry: userOptions.telemetry ?? true,
-    dist: userOptions.dist,
-    errorHandler: userOptions.errorHandler,
+    injectReleasesMap: userOptions.injectReleasesMap ?? false,
+
+    // These options and can also be set via env variables or the config file.
+    // If they're set in the options, we simply pass them to the CLI constructor.
+    // Sentry CLI will internally query env variables and read its config file if
+    // the passed options are undefined.
+    authToken: userOptions.authToken, // env var: `SENTRY_AUTH_TOKEN`
+    customHeader: userOptions.customHeader, // env var: `CUSTOM_HEADER`
+    url: userOptions.url, // env var: `SENTRY_URL`
+    vcsRemote: userOptions.vcsRemote, // env var: `SENTRY_VSC_REMOTE`
+
+    // Optional options
     setCommits: userOptions.setCommits,
     deploy: userOptions.deploy,
-    entries,
-    include,
+    entries: normalizeEntries(userOptions.entries),
+    dist: userOptions.dist,
+    errorHandler: userOptions.errorHandler,
     configFile: userOptions.configFile,
-    injectReleasesMap: userOptions.injectReleasesMap ?? false,
   };
 }
 
+/**
+ * Converts the user-facing `entries` option to the internal `entries` option
+ */
+function normalizeEntries(
+  userEntries: UserOptions["entries"]
+): (string | RegExp)[] | ((filePath: string) => boolean) | undefined {
+  if (userEntries === undefined) {
+    return undefined;
+  } else if (typeof userEntries === "function") {
+    return userEntries;
+  } else {
+    return arrayify(userEntries);
+  }
+}
+
+/**
+ * Converts the user-facing `include` option to the internal `include` option,
+ * resulting in an array of `InternalIncludeEntry` objects. This later on lets us
+ * work with only one type of include data structure instead of multiple.
+ *
+ * During the process, we hoist top-level include options (e.g. urlPrefix) into each
+ * object if they were not alrady specified in an `IncludeEntry`, making every object
+ * fully self-contained. This is also the reason why we pass the entire options
+ * object and not just `include`.
+ *
+ * @param userOptions the entire user-facing `options` object
+ *
+ * @return an array of `InternalIncludeEntry` objects.
+ */
+function normalizeInclude(userOptions: UserOptions): InternalIncludeEntry[] {
+  return arrayify(userOptions.include)
+    .map((includeItem) =>
+      typeof includeItem === "string" ? convertIncludePathToIncludeEntry(includeItem) : includeItem
+    )
+    .map((userIncludeEntry) => normalizeIncludeEntry(userOptions, userIncludeEntry));
+}
+
 function convertIncludePathToIncludeEntry(includePath: string): UserIncludeEntry {
   return {
     paths: [includePath],

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

@@ -20,9 +20,6 @@ export async function createNewRelease(options: InternalOptions, ctx: BuildConte
   } else if (options.org === undefined) {
     ctx.logger.warn('Missing "org" option. Will not create release.');
     return;
-  } else if (options.url === undefined) {
-    ctx.logger.warn('Missing "url" option. Will not create release.');
-    return;
   } else if (options.project === undefined) {
     ctx.logger.warn('Missing "project" option. Will not create release.');
     return;
@@ -45,9 +42,6 @@ export async function uploadSourceMaps(options: InternalOptions, ctx: BuildConte
   } else if (options.org === undefined) {
     ctx.logger.warn('Missing "org" option. Will not create release.');
     return Promise.resolve();
-  } else if (options.url === undefined) {
-    ctx.logger.warn('Missing "url" option. Will not create release.');
-    return Promise.resolve();
   } else if (options.project === undefined) {
     ctx.logger.warn('Missing "project" option. Will not create release.');
     return Promise.resolve();
@@ -86,9 +80,6 @@ export async function cleanArtifacts(options: InternalOptions, ctx: BuildContext
     } else if (options.org === undefined) {
       ctx.logger.warn('Missing "org" option. Will not clean existing artifacts.');
       return;
-    } else if (options.url === undefined) {
-      ctx.logger.warn('Missing "url" option. Will not clean existing artifacts.');
-      return;
     } else if (options.project === undefined) {
       ctx.logger.warn('Missing "project" option. Will not clean existing artifacts.');
       return;

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

@@ -12,30 +12,32 @@ export type Options = Omit<IncludeEntry, "paths"> & {
   /**
    * The slug of the Sentry organization associated with the app.
    *
-   * This is a required field.
+   * This value can also be set via the `SENTRY_ORG` env variable.
    */
-  org: string;
+  org?: string;
 
   /**
    * The slug of the Sentry project associated with the app.
    *
-   * This is a required field.
+   * This value can also be set via the `SENTRY_PROJECT` env variable.
    */
-  project: string;
+  project?: string;
 
   /**
    * The authentication token to use for all communication with Sentry.
    * Can be obtained from https://sentry.io/settings/account/api/auth-tokens/.
    * Required scopes: project:releases (and org:read if setCommits option is used).
    *
-   * This is a required field.
+   * This value can also be set via the `SENTRY_AUTH_TOKEN` env variable
    */
-  authToken: string;
+  authToken?: string;
 
   /**
    * The base URL of your Sentry instance. Use this if you are using a self-hosted
    * or Sentry instance other than sentry.io.
    *
+   * This value can also be set via the `SENTRY_URL` env variable.
+   *
    * Defaults to https://sentry.io/, which is the correct value for SAAS customers.
    */
   url?: string;
@@ -45,6 +47,8 @@ export type Options = Omit<IncludeEntry, "paths"> & {
   /**
    * Unique identifier for the release.
    *
+   * This value can also be set via the `SENTRY_RELEASE` env variable.
+   *
    * Defaults to the output of the sentry-cli releases propose-version command,
    * which automatically detects values for Cordova, Heroku, AWS CodeBuild, CircleCI,
    * Xcode, and Gradle, and otherwise uses HEAD's commit SHA. (For HEAD option,
@@ -93,13 +97,17 @@ export type Options = Omit<IncludeEntry, "paths"> & {
   /**
    * Version control system remote name.
    *
+   * This value can also be set via the `SENTRY_VSC_REMOTE` env variable.
+   *
    * Defaults to 'origin'.
    */
   vcsRemote?: string;
 
   /**
    * A header added to every outgoing network request.
    * The format should be `header-key: header-value`.
+   *
+   * This value can also be set via the `CUSTOM_HEADER` env variable.
    */
   customHeader?: string;
 

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

@@ -0,0 +1,9 @@
+/**
+ * Checks whether the given input is already an array, and if it isn't, wraps it in one.
+ *
+ * @param maybeArray Input to turn into an array, if necessary
+ * @returns The input, if already an array, or an array with the input as the only element, if not
+ */
+export function arrayify<T = unknown>(maybeArray: T | T[]): T[] {
+  return Array.isArray(maybeArray) ? maybeArray : [maybeArray];
+}

packages/bundler-plugin-core/test/option-mappings.test.ts

@@ -33,8 +33,6 @@ describe("normalizeUserOptions()", () => {
       release: "my-release",
       silent: false,
       telemetry: true,
-      url: "https://sentry.io/",
-      vcsRemote: "origin",
       injectReleasesMap: false,
     });
   });
@@ -77,8 +75,6 @@ describe("normalizeUserOptions()", () => {
       release: "my-release",
       silent: false,
       telemetry: true,
-      url: "https://sentry.io/",
-      vcsRemote: "origin",
       injectReleasesMap: false,
     });
   });