chore(core): Cleanup code and JSDocs (#108)

clean up some code, left-over TODOs and adds a few JSDoc improvements

Author: Lms24

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

@@ -23,28 +23,28 @@ import { Hub } from "@sentry/node";
 const RELEASE_INJECTOR_ID = "\0sentry-release-injector";
 
 /**
- * The sentry-unplugin concerns itself with two things:
+ * The sentry bundler plugin concerns itself with two things:
  * - Release injection
  * - Sourcemaps upload
  *
  * Release injection:
  *
- * Per default the sentry-unpugin will inject a global `SENTRY_RELEASE` variable into the entrypoint of all bundles. On
- * a technical level this is done by appending an import (`import "sentry-release-injector;"`) to all entrypoint files
- * of the user code (see `transformInclude` and `transform` hooks). This import is then resolved by the sentry-unplugin
+ * Per default the sentry bundler plugin will inject a global `SENTRY_RELEASE` variable into the entrypoint of all bundles.
+ * On a technical level this is done by appending an import (`import "sentry-release-injector;"`) to all entrypoint files
+ * of the user code (see `transformInclude` and `transform` hooks). This import is then resolved by the sentry plugin
  * to a virtual module that sets the global variable (see `resolveId` and `load` hooks).
  *
  * The resulting output approximately looks like this:
  *
  * ```text
  *                               entrypoint1.js (user file)
- *  ┌───────────────────┐        ┌─────────────────────────────────────────────────┐
- *  │                   │        │  import { myFunction } from "./my-library.js";  │
- *  │  sentry-unplugin  │        │                                                 │
- *  │                   │        │  const myResult = myFunction();                 │
- *  └---------│---------┘        │  export { myResult };                           │
+ *  ┌─────────────────────────┐  ┌─────────────────────────────────────────────────┐
+ *  │                         │  │  import { myFunction } from "./my-library.js";  │
+ *  │  sentry-bundler-plugin  │  │                                                 │
+ *  │                         │  │  const myResult = myFunction();                 │
+ *  └---------│---------------   │  export { myResult };                           │
  *            │                  │                                                 │
- *            │      injects     │  // injected by sentry-unplugin                 │
+ *            │      injects     │  // injected by sentry plugin                   │
  *            ├───────────────────► import "sentry-release-injector"; ─────────────────────┐
  *            │                  └─────────────────────────────────────────────────┘       │
  *            │                                                                            │
@@ -55,24 +55,33 @@ const RELEASE_INJECTOR_ID = "\0sentry-release-injector";
  *            │                  │    return "Hello world!";                       │       │
  *            │                  │  }                                              │       │
  *            │                  │                                                 │       │
- *            │      injects     │  // injected by sentry-unplugin                 │       │
+ *            │      injects     │  // injected by sentry plugin                   │       │
  *            └───────────────────► import "sentry-release-injector"; ─────────────────────┤
  *                               └─────────────────────────────────────────────────┘       │
  *                                                                                         │
  *                                                                                         │
  *                               sentry-release-injector                                   │
  *                               ┌──────────────────────────────────┐                      │
  *                               │                                  │    is resolved       │
- *                               │  global.SENTRY_RELEASE = { ... } │    by unplugin       │
+ *                               │  global.SENTRY_RELEASE = { ... } │    by plugin         │
  *                               │  // + a little more logic        │<─────────────────────┘
  *                               │                                  │    (only once)
  *                               └──────────────────────────────────┘
  * ```
  *
  * Source maps upload:
  *
- * The sentry-unplugin will also take care of uploading source maps to Sentry. This is all done in the `writeBundle` hook.
- * TODO: elaborate a bit on how sourcemaps upload works
+ * The sentry bundler plugin will also take care of uploading source maps to Sentry. This is all done in the
+ * `writeBundle` hook. In this hook the sentry plugin will execute the release creation pipeline:
+ *
+ * 1. Create a new release
+ * 2. Delete already uploaded artifacts for this release (if `cleanArtifacts` is enabled)
+ * 3. Upload sourcemaps based on `include` and source-map-specific options
+ * 4. Associate a range of commits with the release (if `setCommits` is specified)
+ * 5. Finalize the release (unless `finalize` is disabled)
+ * 6. Add deploy information to the release (if `deploy` is specified)
+ *
+ * This release creation pipeline relies on Sentry CLI to execute the different steps.
  */
 const unplugin = createUnplugin<Options>((options, unpluginMetaContext) => {
   const internalOptions = normalizeUserOptions(options);
@@ -188,7 +197,6 @@ const unplugin = createUnplugin<Options>((options, unpluginMetaContext) => {
 
     loadInclude(id) {
       logger.info(`Called "loadInclude": ${JSON.stringify({ id })}`);
-
       return id === RELEASE_INJECTOR_ID;
     },
 
@@ -218,11 +226,11 @@ const unplugin = createUnplugin<Options>((options, unpluginMetaContext) => {
     },
 
     /**
-     * This hook determines whether we want to transform a module. In the unplugin we want to transform every entrypoint
+     * This hook determines whether we want to transform a module. In the sentry bundler plugin we want to transform every entrypoint
      * unless configured otherwise with the `entries` option.
      *
      * @param id Always the absolute (fully resolved) path to the module.
-     * @returns `true` or `false` depending on whether we want to transform the module. For the sentry-unplugin we only
+     * @returns `true` or `false` depending on whether we want to transform the module. For the sentry bundler plugin we only
      * want to transform the release injector file.
      */
     transformInclude(id) {

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

@@ -136,17 +136,11 @@ function normalizeEntries(
 function normalizeInclude(userOptions: UserOptions): InternalIncludeEntry[] {
   return arrayify(userOptions.include)
     .map((includeItem) =>
-      typeof includeItem === "string" ? convertIncludePathToIncludeEntry(includeItem) : includeItem
+      typeof includeItem === "string" ? { paths: [includeItem] } : includeItem
     )
     .map((userIncludeEntry) => normalizeIncludeEntry(userOptions, userIncludeEntry));
 }
 
-function convertIncludePathToIncludeEntry(includePath: string): UserIncludeEntry {
-  return {
-    paths: [includePath],
-  };
-}
-
 /**
  * Besides array-ifying the `ignore` option, this function hoists top level options into the items of the `include`
  * option. This is to simplify the handling of of the `include` items later on.

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

@@ -27,8 +27,6 @@ export function makeSentryClient(
 
     stackParser: defaultStackParser,
     transport: makeNodeTransport,
-
-    debug: true,
   });
 
   const hub = new Hub(client);

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

@@ -63,13 +63,14 @@ export type Options = Omit<IncludeEntry, "paths"> & {
   dist?: string;
 
   /**
-   * Filter for bundle entry points that should contain the provided release. By default, the release will be injected
-   * into all entry points.
+   * Filter for bundle entry points that should contain the provided release.
    *
    * This option takes a string, a regular expression, or an array containing strings, regular expressions, or both.
    * It's also possible to provide a filter function that takes the absolute path of a processed entrypoint and should
    * return `true` if the release should be injected into the entrypoint and `false` otherwise. String values of this
    * option require a full match with the absolute path of the bundle.
+   *
+   * By default, the release will be injected into all entry points.
    */
   entries?: (string | RegExp)[] | RegExp | string | ((filePath: string) => boolean);
 
@@ -85,14 +86,15 @@ export type Options = Omit<IncludeEntry, "paths"> & {
 
   /**
    * One or more paths that Sentry CLI should scan recursively for sources.
-   * It will upload all .map files and match associated .js files.
+   * It will upload all .map files and match associated .js files. Other file
+   * types can be uploaded by using the `ext` option.
    * Each path can be given as a string or an object with path-specific options
    *
    * This is a required field.
    */
   include: string | IncludeEntry | Array<string | IncludeEntry>;
 
-  /* --- other unimportant (for now) stuff- properties: */
+  /* --- other properties: */
 
   /**
    * Version control system remote name.
@@ -112,7 +114,8 @@ export type Options = Omit<IncludeEntry, "paths"> & {
   customHeader?: string;
 
   /**
-   * Attempts a dry run (useful for dev environments).
+   * Attempts a dry run (useful for dev environments), making release creation
+   * a no-op.
    *
    * Defaults to `false`, but may be automatically set to `true` in development environments
    * by some framework integrations (Next.JS, possibly others).
@@ -158,12 +161,12 @@ export type Options = Omit<IncludeEntry, "paths"> & {
   errorHandler?: (err: Error) => void;
 
   /**
-   * Adds commits to Sentry.
+   * Associates the release with its commits in Sentry.
    */
   setCommits?: SetCommitsOptions;
 
   /**
-   * Creates a new release deployment in Sentry.
+   * Adds deployment information to the release in Sentry.
    */
   deploy?: DeployOptions;