@adobe-commerce/elsie 1.9.0-beta.2 → 1.9.0-beta.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @adobe-commerce/elsie
 
+## 1.9.0-beta.3
+
+### Patch Changes
+
+- 5c64620: Implement a new `fragment-import-redirect` build plugin that automatically detects and redirects any dropin source file that directly imports a fragment source file (bypassing the barrel). The import is silently redirected to the fragments barrel at build time and a warning is emitted identifying the file so it can be corrected in source. This ensures fragment constants always appear as local declarations in `fragments.js` regardless of how dropin source code references them.
+
 ## 1.9.0-beta.2
 
 ### Patch Changes

package/config/vite.mjs

@@ -55,7 +55,7 @@ const paths = {
       )
     : undefined,
 
-  components: elsieConfig.components?.map((component) => 
+  components: elsieConfig.components?.map((component) =>
     path.resolve(process.cwd(), component.root)
   ),
 };
@@ -93,6 +93,19 @@ if (paths.fragments) {
   input.fragments = path.resolve(paths.fragments);
 }
 
+/**
+ * Recursively walks the Rollup importer graph upward to determine whether
+ * `id` is reachable from `targetPath` at any depth.
+ *
+ * Used by `manualChunks` to exclude fragment source files from the api chunk:
+ * any module that is (transitively) imported by the fragments barrel must stay
+ * in the fragments output so the gql-extend override mechanism can replace it
+ * independently of api.js.
+ *
+ * A `visited` Set is threaded through each recursive call to short-circuit
+ * cycles in the module graph. It is created fresh per `manualChunks` invocation
+ * so no state leaks between module evaluations.
+ */
 function isReachableFrom(targetPath, id, getModuleInfo, visited = new Set()) {
   if (visited.has(id)) return false;
   visited.add(id);
@@ -102,6 +115,223 @@ function isReachableFrom(targetPath, id, getModuleInfo, visited = new Set()) {
   );
 }
 
+/**
+ * Vite plugin that enforces the fragments barrel import contract at build time.
+ *
+ * Fragment source files (those re-exported by the fragments barrel) must be
+ * imported exclusively through the barrel. This guarantees Rollup emits their
+ * GraphQL string constants as local `const` declarations inside `fragments.js`.
+ * The gql-extend tool reads and rewrites those declarations at boilerplate build
+ * time; if the constants end up in `api.js` instead, the override mechanism
+ * silently produces incorrect output.
+ *
+ * When a dropin source file imports a fragment file directly (bypassing the
+ * barrel), this plugin:
+ *   1. Transparently redirects the import to the barrel at resolve time, so the
+ *      build output is always correct regardless of dropin source conventions.
+ *   2. Emits a build warning per offending file listing every direct importer,
+ *      so project maintainers know exactly which imports to correct in source.
+ *
+ * IMPORTANT — placement: this plugin must be listed BEFORE tsconfigPaths() in
+ * the plugins array. Both use `enforce: 'pre'`; within that group Vite respects
+ * array order. Being first ensures our resolveId hook intercepts the alias-form
+ * import before tsconfigPaths claims it — once tsconfigPaths resolves the alias
+ * and returns, our hook is never reached.
+ */
+function fragmentImportRedirectPlugin(paths, elsieConfig) {
+  // Per-build state. Both are cleared in buildStart so watch-mode rebuilds
+  // always start from a clean slate.
+  const fragmentSourceFiles = new Set();
+  const fragmentViolations = new Map(); // fragment file → [direct importers]
+
+  // Pre-compute alias info once so buildStart and buildEnd share the same
+  // values without re-reading elsieConfig and without unsafe property access
+  // inside hook callbacks (where elsieConfig.api could be undefined).
+  const apiAliasRoot = elsieConfig.api?.importAliasRoot;
+  const apiRoot = path.resolve(process.cwd(), elsieConfig.api?.root ?? 'src/api');
+  // Alias specifier for the barrel itself, e.g. '@/cart/api/fragments'
+  const barrelAlias = apiAliasRoot
+    ? `${apiAliasRoot}/${path.basename(paths.fragments, path.extname(paths.fragments))}`
+    : path.relative(process.cwd(), paths.fragments);
+
+  return {
+    name: 'fragment-import-redirect',
+    enforce: 'pre',
+
+    buildStart() {
+      fragmentSourceFiles.clear();
+      fragmentViolations.clear();
+
+      // Read the barrel and resolve each re-exported specifier to an absolute
+      // path. The resulting set is what resolveId checks against.
+      const barrelContent = fs.readFileSync(paths.fragments, 'utf-8');
+      const barrelDir = path.dirname(paths.fragments);
+      const importRegex = /from\s+['"]([^'"]+)['"]/g;
+      let match;
+
+      while ((match = importRegex.exec(barrelContent)) !== null) {
+        let specifier = match[1];
+
+        // Resolve alias-prefixed specifiers (e.g. '@/cart/api/graphql/CartFragment')
+        // using the dropin's importAliasRoot config before probing the filesystem.
+        if (apiAliasRoot && specifier.startsWith(`${apiAliasRoot}/`)) {
+          specifier = path.join(apiRoot, specifier.slice(apiAliasRoot.length + 1));
+        } else if (specifier.startsWith('.')) {
+          specifier = path.resolve(barrelDir, specifier);
+        } else {
+          continue; // skip bare specifiers (node_modules re-exports)
+        }
+
+        // Barrel specifiers rarely include file extensions; probe common ones.
+        for (const ext of ['', '.ts', '.tsx', '.js']) {
+          const candidate = specifier + ext;
+          if (fs.existsSync(candidate)) {
+            fragmentSourceFiles.add(candidate);
+            break;
+          }
+        }
+      }
+    },
+
+    async resolveId(source, importer) {
+      if (!importer || fragmentSourceFiles.size === 0) return null;
+      // Allow the barrel to import fragment files (its own re-exports) and
+      // allow fragment files to import each other (shared helper fragments).
+      if (importer === paths.fragments || fragmentSourceFiles.has(importer)) return null;
+
+      // Delegate to subsequent plugins (including tsconfigPaths) so alias
+      // specifiers are fully resolved to an absolute path before we check.
+      // skipSelf prevents infinite recursion back into this hook.
+      const resolved = await this.resolve(source, importer, { skipSelf: true });
+      if (!resolved || !fragmentSourceFiles.has(resolved.id)) return null;
+
+      // Track the violation for the buildEnd warning.
+      if (!fragmentViolations.has(resolved.id)) fragmentViolations.set(resolved.id, []);
+      fragmentViolations.get(resolved.id).push(importer);
+
+      // Redirect to the barrel. Rollup treats the barrel as the resolved module,
+      // so the fragment constants become local declarations in fragments.js.
+      return { id: paths.fragments };
+    },
+
+    buildEnd() {
+      for (const [fragmentFile, importers] of fragmentViolations) {
+        // Derive the wrong specifier from the actual fragment file path so the
+        // suggestion shows the real import, not a generic placeholder.
+        const relFragment = path.relative(apiRoot, fragmentFile).replace(/\.(ts|tsx|js)$/, '');
+        const wrongSpecifier = apiAliasRoot ? `${apiAliasRoot}/${relFragment}` : relFragment;
+
+        this.warn(
+          `\n"${path.relative(process.cwd(), fragmentFile)}" belongs to the fragments barrel ` +
+          `but was directly imported by:\n${ 
+          importers.map((imp) => `    - ${path.relative(process.cwd(), imp)}`).join('\n') 
+          }\n\nThe import was automatically redirected through the fragments barrel. ` +
+          `\nUpdate the import in source to silence this warning: '${wrongSpecifier}' → '${barrelAlias}'\n`
+        );
+      }
+    },
+  };
+}
+
+/**
+ * Vite plugin that rewrites relative `../src/` paths in generated sourcemaps
+ * to package-qualified paths (e.g. `../../src/foo.ts` → `/@scope/pkg/src/foo.ts`).
+ *
+ * Predictable, package-namespaced paths let browser devtools and error-tracking
+ * services (Sentry, Datadog, etc.) resolve source files back to the correct
+ * package across CDN-delivered builds where multiple dropin sourcemaps are
+ * loaded in the same session.
+ */
+function rewriteSourcemapSourcesPlugin(packageJSON) {
+  return {
+    name: 'rewrite-sourcemap-sources',
+    generateBundle(options, bundle) {
+      for (const fileName in bundle) {
+        const chunk = bundle[fileName];
+
+        // Process both standalone .map asset files and inline chunk maps.
+        if (
+          (chunk.type === 'asset' && fileName.endsWith('.map')) ||
+          (chunk.type === 'chunk' && chunk.map)
+        ) {
+          try {
+            const map =
+              chunk.type === 'asset' ? JSON.parse(chunk.source) : chunk.map;
+
+            if (map.sources) {
+              map.sources = map.sources.map((input) => {
+                // Replace any leading `../src/` or `../../src/` traversal with
+                // the package name so the path is stable and globally unique.
+                return input.replace(
+                  /(?:\.\.?\/)+src\//,
+                  `/${packageJSON.name}/src/`
+                );
+              });
+
+              if (chunk.type === 'asset') {
+                chunk.source = JSON.stringify(map);
+              } else {
+                chunk.map = map;
+              }
+            }
+          } catch (e) {
+            console.error('Error transforming sourcemap:', e);
+          }
+        }
+      }
+    },
+  };
+}
+
+/**
+ * Vite plugin that emits a minimal `package.json`, `LICENSE.md`, and
+ * `CHANGELOG.md` into the `dist/` directory alongside the compiled output.
+ *
+ * The minimal package.json carries only `name`, `version`, and `license` so
+ * CDN consumers and package tooling can identify a build artifact without
+ * pulling in the full development-time manifest (devDependencies, scripts, etc.).
+ * LICENSE.md is required; the build fails early if it is missing.
+ */
+function generateDistPackageJsonPlugin(packageJSON) {
+  return {
+    name: 'generate-dist-package-json',
+    generateBundle() {
+      this.emitFile({
+        type: 'asset',
+        fileName: 'package.json',
+        source: JSON.stringify(
+          {
+            name: packageJSON.name,
+            version: packageJSON.version,
+            license: packageJSON.license,
+          },
+          null,
+          2
+        ),
+      });
+
+      const licensePath = path.resolve(process.cwd(), 'LICENSE.md');
+      if (!fs.existsSync(licensePath)) {
+        this.error(`LICENSE.md not found at ${licensePath}`);
+      }
+      this.emitFile({
+        type: 'asset',
+        fileName: 'LICENSE.md',
+        source: fs.readFileSync(licensePath, 'utf-8'),
+      });
+
+      const changelogPath = path.resolve(process.cwd(), 'CHANGELOG.md');
+      if (fs.existsSync(changelogPath)) {
+        this.emitFile({
+          type: 'asset',
+          fileName: 'CHANGELOG.md',
+          source: fs.readFileSync(changelogPath, 'utf-8'),
+        });
+      }
+    },
+  };
+}
+
 export default {
   preview: {
     host: true,
@@ -221,6 +451,9 @@ export default {
   plugins: [
     banner(`Copyright ${currentYear} Adobe\nAll Rights Reserved.`),
 
+    // Must come before tsconfigPaths — see fragmentImportRedirectPlugin for why.
+    paths.fragments ? fragmentImportRedirectPlugin(paths, elsieConfig) : null,
+
     tsconfigPaths(),
 
     cssInjectedByJsPlugin({
@@ -320,82 +553,9 @@ export default {
       },
     }),
 
-    {
-      name: 'rewrite-sourcemap-sources',
-      generateBundle(options, bundle) {
-        for (const fileName in bundle) {
-          const chunk = bundle[fileName];
-
-          // Process both .map files and JS/TS files with sourcemaps
-          if (
-            (chunk.type === 'asset' && fileName.endsWith('.map')) ||
-            (chunk.type === 'chunk' && chunk.map)
-          ) {
-            try {
-              // Get the sourcemap object - either from the asset source or the chunk's map
-              const map =
-                chunk.type === 'asset' ? JSON.parse(chunk.source) : chunk.map;
-
-              if (map.sources) {
-                map.sources = map.sources.map((input) => {
-                  return input.replace(
-                    /(?:\.\.?\/)+src\//,
-                    `/${packageJSON.name}/src/`
-                  );
-                });
-
-                // Update the sourcemap in the appropriate place
-                if (chunk.type === 'asset') {
-                  chunk.source = JSON.stringify(map);
-                } else {
-                  chunk.map = map;
-                }
-              }
-            } catch (e) {
-              console.error('Error transforming sourcemap:', e);
-            }
-          }
-        }
-      },
-    },
-
-    {
-      name: 'generate-dist-package-json',
-      generateBundle() {
-        this.emitFile({
-          type: 'asset',
-          fileName: 'package.json',
-          source: JSON.stringify(
-            {
-              name: packageJSON.name,
-              version: packageJSON.version,
-              license: packageJSON.license,
-            },
-            null,
-            2
-          ),
-        });
+    rewriteSourcemapSourcesPlugin(packageJSON),
 
-        const licensePath = path.resolve(process.cwd(), 'LICENSE.md');
-        if (!fs.existsSync(licensePath)) {
-          this.error(`LICENSE.md not found at ${licensePath}`);
-        }
-        this.emitFile({
-          type: 'asset',
-          fileName: 'LICENSE.md',
-          source: fs.readFileSync(licensePath, 'utf-8'),
-        });
-
-        const changelogPath = path.resolve(process.cwd(), 'CHANGELOG.md');
-        if (fs.existsSync(changelogPath)) {
-          this.emitFile({
-            type: 'asset',
-            fileName: 'CHANGELOG.md',
-            source: fs.readFileSync(changelogPath, 'utf-8'),
-          });
-        }
-      },
-    },
+    generateDistPackageJsonPlugin(packageJSON),
 
     process.env.ANALYZE
       ? visualizer({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe-commerce/elsie",
-  "version": "1.9.0-beta.2",
+  "version": "1.9.0-beta.3",
   "license": "SEE LICENSE IN LICENSE.md",
   "description": "Domain Package SDK",
   "engines": {