chore: comments

Author: logaretm

packages/esbuild-plugin/src/index.ts

@@ -42,12 +42,16 @@ function esbuildReleaseInjectionPlugin(injectionCode: string): UnpluginOptions {
   };
 }
 
-// Shared set to track entry points that have been wrapped by the metadata plugin.
-// This allows the debug ID plugin to know when an import is coming from a metadata proxy.
+/**
+ * Shared set to track entry points that have been wrapped by the metadata plugin
+ * This allows the debug ID plugin to know when an import is coming from a metadata proxy
+ */
 const metadataProxyEntryPoints = new Set<string>();
 
-// Set to track which paths have already been wrapped with debug ID injection.
-// This prevents the debug ID plugin from wrapping the same module multiple times.
+/**
+ * Set to track which paths have already been wrapped with debug ID injection
+ * This prevents the debug ID plugin from wrapping the same module multiple times
+ */
 const debugIdWrappedPaths = new Set<string>();
 
 function esbuildDebugIdInjectionPlugin(logger: Logger): UnpluginOptions {
@@ -66,15 +70,11 @@ function esbuildDebugIdInjectionPlugin(logger: Logger): UnpluginOptions {
         }
 
         onResolve({ filter: /.*/ }, (args) => {
-          // We want to inject debug IDs into entry points. However, when the module metadata
-          // injection plugin is also active, it intercepts entry points first and creates a
-          // proxy module that re-imports the original entry point. In that case, we need to
-          // also intercept those imports (which have kind === "import-statement") and inject
-          // debug IDs there too.
+          // Inject debug IDs into entry points and into imports from metadata proxy modules
           const isEntryPoint = args.kind === "entry-point";
 
-          // Check if this import is coming from a metadata proxy module.
-          // The metadata plugin registers entry points it wraps in the shared Set.
+          // Check if this import is coming from a metadata proxy module
+          // The metadata plugin registers entry points it wraps in the shared Set
           const isImportFromMetadataProxy =
             args.kind === "import-statement" &&
             args.importer !== undefined &&
@@ -84,8 +84,8 @@ function esbuildDebugIdInjectionPlugin(logger: Logger): UnpluginOptions {
             return;
           }
 
-          // Injected modules via the esbuild `inject` option do also have `kind == "entry-point"`.
-          // We do not want to inject debug IDs into those files because they are already bundled into the entrypoints
+          // Skip injecting debug IDs into modules specified in the esbuild `inject` option
+          // since they're already part of the entry points
           if (initialOptions.inject?.includes(args.path)) {
             return;
           }
@@ -94,10 +94,7 @@ function esbuildDebugIdInjectionPlugin(logger: Logger): UnpluginOptions {
             ? args.path
             : path.join(args.resolveDir, args.path);
 
-          // Check if we've already wrapped this path. This can happen when both the metadata
-          // plugin and debug ID plugin are active - the debug ID proxy imports the original
-          // module, and since its importer path matches the metadata proxy entry point,
-          // we might try to wrap it again. Prevent this by tracking wrapped paths.
+          // Skip injecting debug IDs into paths that have already been wrapped
           if (debugIdWrappedPaths.has(resolvedPath)) {
             return;
           }
@@ -192,8 +189,7 @@ function esbuildModuleMetadataInjectionPlugin(injectionCode: string): UnpluginOp
               : path.join(args.resolveDir, args.path);
 
             // Register this entry point so the debug ID plugin knows to wrap imports from
-            // this proxy module. This is needed because the debug ID plugin runs after us and
-            // needs to know when an import is coming from our proxy module.
+            // this proxy module, this because the debug ID may run after the metadata plugin
             metadataProxyEntryPoints.add(resolvedPath);
 
             return {