@emulsify/core 4.3.2 → 4.4.0

package/config/vite/plugins/assets/mirror-components.js

@@ -7,16 +7,12 @@
 
 import {
   copyFileSync,
-  closeSync,
   lstatSync,
   mkdirSync,
-  openSync,
   readFileSync,
-  readSync,
   readdirSync,
   renameSync,
   rmdirSync,
-  statSync,
   unlinkSync,
   writeFileSync,
 } from 'fs';
@@ -24,10 +20,14 @@ import { basename, dirname, join, resolve } from 'path';
 
 import { safeExists, safeReadJson } from '../../utils/fs-safe.js';
 import { resolvePackageVersion } from '../../utils/package-version.js';
+import {
+  isGeneratedSourceMap,
+  rebaseSourceMapForMove,
+} from '../../utils/source-maps.js';
+import { bytesAlreadyOnDisk, filesHaveSameBytes } from './output-freshness.js';
 import { walkFiles } from './source-file-index.js';
 
 const MIRROR_STATE_FILE = '.emulsify-mirror-state.json';
-const FILE_COMPARE_CHUNK_SIZE = 64 * 1024;
 
 /**
  * Remove empty parent directories from a start directory up to, but not including,
@@ -64,77 +64,6 @@ const pruneEmptyDirsUpTo = (startDir, stopAtDir) => {
   }
 };
 
-/**
- * Determine whether two files already contain the same bytes.
- * Small files are read directly; larger files are compared in fixed-size chunks
- * so the mirror phase does not transiently allocate both complete file bodies.
- *
- * @param {string} sourceFile - Source file path.
- * @param {string} destinationFile - Destination file path.
- * @returns {boolean} TRUE when both files have identical bytes.
- */
-export const filesHaveSameBytes = (sourceFile, destinationFile) => {
-  try {
-    const sourceStats = statSync(sourceFile);
-    const destinationStats = statSync(destinationFile);
-    if (!destinationStats.isFile()) return false;
-    if (sourceStats.size !== destinationStats.size) return false;
-    if (sourceStats.size === 0) return true;
-
-    if (sourceStats.size < FILE_COMPARE_CHUNK_SIZE) {
-      return readFileSync(sourceFile).equals(readFileSync(destinationFile));
-    }
-
-    const sourceBuffer = Buffer.allocUnsafe(FILE_COMPARE_CHUNK_SIZE);
-    const destinationBuffer = Buffer.allocUnsafe(FILE_COMPARE_CHUNK_SIZE);
-    const sourceHandle = openSync(sourceFile, 'r');
-    try {
-      const destinationHandle = openSync(destinationFile, 'r');
-      try {
-        let position = 0;
-        while (position < sourceStats.size) {
-          const bytesToRead = Math.min(
-            FILE_COMPARE_CHUNK_SIZE,
-            sourceStats.size - position,
-          );
-          const sourceBytesRead = readSync(
-            sourceHandle,
-            sourceBuffer,
-            0,
-            bytesToRead,
-            position,
-          );
-          const destinationBytesRead = readSync(
-            destinationHandle,
-            destinationBuffer,
-            0,
-            bytesToRead,
-            position,
-          );
-
-          if (sourceBytesRead !== destinationBytesRead) return false;
-          if (sourceBytesRead === 0) return false;
-          if (
-            !sourceBuffer
-              .subarray(0, sourceBytesRead)
-              .equals(destinationBuffer.subarray(0, destinationBytesRead))
-          ) {
-            return false;
-          }
-          position += sourceBytesRead;
-        }
-        return true;
-      } finally {
-        closeSync(destinationHandle);
-      }
-    } finally {
-      closeSync(sourceHandle);
-    }
-  } catch {
-    return false;
-  }
-};
-
 /**
  * Determine whether a filesystem path is a symbolic link.
  *
@@ -226,6 +155,40 @@ const moveFileIntoPlace = (sourceFile, destinationFile) => {
   }
 };
 
+/**
+ * Write transformed output bytes atomically, then remove the transient source.
+ *
+ * Source maps need their relative paths changed before mirroring, so they
+ * cannot use the rename-only path above. The destination comparison still
+ * preserves stable mtimes when the rebased bytes match the previous cycle.
+ *
+ * @param {string} sourceFile - Built file under dist.
+ * @param {string} destinationFile - Mirrored project-root destination.
+ * @param {string} contents - Final destination contents.
+ */
+const writeContentsIntoPlace = (sourceFile, destinationFile, contents) => {
+  mkdirSync(dirname(destinationFile), { recursive: true });
+
+  if (bytesAlreadyOnDisk(destinationFile, contents)) {
+    removeSourceFile(sourceFile);
+    return;
+  }
+
+  const tempDestination = createTempDestination(destinationFile);
+  try {
+    writeFileSync(tempDestination, contents);
+    renameSync(tempDestination, destinationFile);
+    removeSourceFile(sourceFile);
+  } catch (error) {
+    try {
+      unlinkSync(tempDestination);
+    } catch {
+      /* noop */
+    }
+    throw error;
+  }
+};
+
 /**
  * Safely read the previous mirror state marker.
  *
@@ -265,17 +228,24 @@ const warnOnInterruptedMirror = (markerFile) => {
 /**
  * Mirror built component files to the project root `./components/` directory.
  *
- * @param {{ enabled: boolean, projectDir: string }} opts - Plugin options.
+ * @param {{ enabled: boolean, projectDir: string, developmentBuild?: boolean, diagnostics?: object }} opts - Plugin options.
  * @returns {import('vite').PluginOption} Drupal mirror plugin.
  */
-export function mirrorComponentsToRoot({ enabled, projectDir }) {
+export function mirrorComponentsToRoot({
+  enabled,
+  projectDir,
+  developmentBuild = false,
+  diagnostics,
+}) {
   let outDir = 'dist';
+  let watching = Boolean(developmentBuild);
   return {
     name: 'emulsify-mirror-components-to-root',
     apply: 'build',
     enforce: 'post',
     configResolved(cfg) {
       outDir = cfg.build?.outDir || 'dist';
+      watching = Boolean(developmentBuild || cfg.build?.watch);
     },
     writeBundle() {
       if (!enabled) return;
@@ -299,18 +269,64 @@ export function mirrorComponentsToRoot({ enabled, projectDir }) {
           const destFile = join(projectDir, relFromOutDir);
 
           try {
-            moveFileIntoPlace(srcFile, destFile);
+            if (isGeneratedSourceMap(srcFile)) {
+              const sourceMap = readFileSync(srcFile, 'utf8');
+              writeContentsIntoPlace(
+                srcFile,
+                destFile,
+                rebaseSourceMapForMove(sourceMap, srcFile, destFile),
+              );
+            } else {
+              moveFileIntoPlace(srcFile, destFile);
+            }
             pruneEmptyDirsUpTo(dirname(srcFile), distComponents);
           } catch (e) {
-            console.warn(
-              `Mirror copy failed for ${relFromOutDir}: ${e?.message || e}`,
-            );
+            const message = `Mirror copy failed for ${relFromOutDir}: ${e?.message || e}`;
+            diagnostics?.recordError?.({
+              message,
+              file: destFile,
+              outputState: 'incomplete',
+            });
+            // One-shot builds do not render the watch-cycle failure summary,
+            // so preserve their immediate warning through Rollup's logger.
+            if (typeof this.warn === 'function') this.warn(message);
+            else console.warn(message);
           }
         }
 
         pruneEmptyDirsUpTo(distComponents, outDir);
       }
 
+      // Watch builds intentionally publish source maps for browser debugging.
+      // A later production build cleans dist/ but not the mirrored root, so
+      // remove maps left under components/ by an earlier watch session.
+      if (!watching) {
+        const rootComponents = join(projectDir, 'components');
+        for (const sourceMap of walkFiles(rootComponents).filter(
+          isGeneratedSourceMap,
+        )) {
+          try {
+            unlinkSync(sourceMap);
+            const parentDir = dirname(sourceMap);
+            if (resolve(parentDir) !== resolve(rootComponents)) {
+              pruneEmptyDirsUpTo(parentDir, rootComponents);
+            }
+          } catch (e) {
+            const relativeSourceMap = sourceMap.slice(
+              join(projectDir, '').length,
+            );
+            const message = `Production source-map cleanup failed for ${relativeSourceMap}: ${e?.message || e}`;
+            diagnostics?.recordError?.({
+              message,
+              file: sourceMap,
+              outputState: 'incomplete',
+            });
+            if (typeof this.warn === 'function') this.warn(message);
+            else console.warn(message);
+          }
+        }
+      }
+
       writeMirrorState(markerFile, {
         ...mirrorState,
         completedAt: new Date().toISOString(),

package/config/vite/plugins/assets/output-freshness.js

@@ -0,0 +1,235 @@
+/**
+ * @file Where a built file lands, and whether it is already there.
+ *
+ * Shared by every plugin that writes into the output tree during a watch build.
+ * Vite used to empty that tree at the start of each rebuild, so nothing was
+ * ever up to date and each of these plugins wrote unconditionally;
+ * `stableWatchOutputPlugin` stops the emptying after the first cycle, which is
+ * what makes a freshness check meaningful at all.
+ */
+
+import {
+  closeSync,
+  lstatSync,
+  openSync,
+  readFileSync,
+  readSync,
+  statSync,
+  unlinkSync,
+} from 'fs';
+import { join } from 'path';
+
+const FILE_COMPARE_CHUNK_SIZE = 64 * 1024;
+
+/**
+ * Remove a destination symlink without following it.
+ *
+ * A stale output symlink must never survive until a copy: `copyFileSync` follows
+ * its destination and would overwrite the link target. Missing destinations
+ * are safe; inspection or unlink failures propagate so callers cannot proceed
+ * with an unsafe write.
+ *
+ * @param {string} filePath - Destination path to inspect.
+ * @returns {boolean} TRUE when a symlink was removed.
+ */
+export const removeDestinationSymlink = (filePath) => {
+  let stats;
+
+  try {
+    stats = lstatSync(filePath);
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return false;
+    throw error;
+  }
+
+  if (stats.isSymbolicLink()) {
+    unlinkSync(filePath);
+    return true;
+  }
+
+  return false;
+};
+
+/**
+ * Inspect a destination without following symlinks.
+ *
+ * @param {string} filePath - Destination path to inspect.
+ * @returns {import('fs').Stats|null} Destination stats, or null when absent or removed.
+ */
+const destinationStatsForComparison = (filePath) => {
+  if (removeDestinationSymlink(filePath)) return null;
+
+  try {
+    return lstatSync(filePath);
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return null;
+    throw error;
+  }
+};
+
+/**
+ * Determine whether two files already contain the same bytes.
+ *
+ * Small files are read directly; larger files are compared in fixed-size chunks
+ * so a build phase does not transiently allocate both complete file bodies.
+ *
+ * @param {string} sourceFile - Source file path.
+ * @param {string} destinationFile - Destination file path.
+ * @returns {boolean} TRUE when both files have identical bytes.
+ */
+export const filesHaveSameBytes = (sourceFile, destinationFile) => {
+  const destinationStats = destinationStatsForComparison(destinationFile);
+  if (!destinationStats?.isFile()) return false;
+
+  try {
+    const sourceStats = statSync(sourceFile);
+    if (sourceStats.size !== destinationStats.size) return false;
+    if (sourceStats.size === 0) return true;
+
+    if (sourceStats.size < FILE_COMPARE_CHUNK_SIZE) {
+      return readFileSync(sourceFile).equals(readFileSync(destinationFile));
+    }
+
+    const sourceBuffer = Buffer.allocUnsafe(FILE_COMPARE_CHUNK_SIZE);
+    const destinationBuffer = Buffer.allocUnsafe(FILE_COMPARE_CHUNK_SIZE);
+    const sourceHandle = openSync(sourceFile, 'r');
+    try {
+      const destinationHandle = openSync(destinationFile, 'r');
+      try {
+        let position = 0;
+        while (position < sourceStats.size) {
+          const bytesToRead = Math.min(
+            FILE_COMPARE_CHUNK_SIZE,
+            sourceStats.size - position,
+          );
+          const sourceBytesRead = readSync(
+            sourceHandle,
+            sourceBuffer,
+            0,
+            bytesToRead,
+            position,
+          );
+          const destinationBytesRead = readSync(
+            destinationHandle,
+            destinationBuffer,
+            0,
+            bytesToRead,
+            position,
+          );
+
+          if (sourceBytesRead !== destinationBytesRead) return false;
+          if (sourceBytesRead === 0) return false;
+          if (
+            !sourceBuffer
+              .subarray(0, sourceBytesRead)
+              .equals(destinationBuffer.subarray(0, destinationBytesRead))
+          ) {
+            return false;
+          }
+          position += sourceBytesRead;
+        }
+        return true;
+      } finally {
+        closeSync(destinationHandle);
+      }
+    } finally {
+      closeSync(sourceHandle);
+    }
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Read an emitted asset source as a buffer.
+ *
+ * @param {string|Uint8Array} source - Emitted asset source.
+ * Uint8Array sources are returned directly: Buffer comparisons accept them,
+ * so copying the complete asset would only add transient memory pressure.
+ *
+ * @returns {Buffer|Uint8Array} Asset bytes.
+ */
+const toBytes = (source) =>
+  typeof source === 'string' ? Buffer.from(source, 'utf8') : source;
+
+/**
+ * Determine whether an in-memory source already exists on disk unchanged.
+ *
+ * @param {string} filePath - Absolute path the bytes would occupy.
+ * @param {string|Uint8Array} source - Bytes about to be written.
+ * @returns {boolean} TRUE when writing would be a no-op.
+ */
+export function bytesAlreadyOnDisk(filePath, source) {
+  const destinationStats = destinationStatsForComparison(filePath);
+  if (!destinationStats?.isFile()) return false;
+
+  const sourceBytes = toBytes(source);
+  if (destinationStats.size !== sourceBytes.byteLength) return false;
+  if (destinationStats.size === 0) return true;
+
+  let handle;
+
+  try {
+    handle = openSync(filePath, 'r');
+    const destinationBuffer = Buffer.allocUnsafe(FILE_COMPARE_CHUNK_SIZE);
+    let position = 0;
+
+    while (position < destinationStats.size) {
+      const bytesToRead = Math.min(
+        FILE_COMPARE_CHUNK_SIZE,
+        destinationStats.size - position,
+      );
+      const bytesRead = readSync(
+        handle,
+        destinationBuffer,
+        0,
+        bytesToRead,
+        position,
+      );
+
+      if (bytesRead === 0) return false;
+      if (
+        !destinationBuffer
+          .subarray(0, bytesRead)
+          .equals(sourceBytes.subarray(position, position + bytesRead))
+      ) {
+        return false;
+      }
+      position += bytesRead;
+    }
+
+    return true;
+  } catch {
+    return false;
+  } finally {
+    if (handle !== undefined) {
+      try {
+        closeSync(handle);
+      } catch {
+        /* noop */
+      }
+    }
+  }
+}
+
+/**
+ * Resolve where an output-relative file ends up once the build finishes.
+ *
+ * Drupal projects that author under `src/` have their component output moved
+ * out of `dist/` by `mirrorComponentsToRoot`, so the previous cycle's copy is
+ * not in the output directory to compare against — it is one directory level
+ * up, beside the theme's other components. Comparing against the wrong location
+ * makes every component file look new, which both defeats the freshness check
+ * and leaves the transient write-then-move churn in place.
+ *
+ * @param {string} relPath - Path relative to the output directory.
+ * @param {{outDir: string, projectDir: string, mirrored?: boolean}} paths - Resolved locations.
+ * @returns {string} Absolute path the file occupies after the build.
+ */
+export function resolveFinalPath(relPath, { outDir, projectDir, mirrored }) {
+  if (mirrored && relPath.startsWith('components/')) {
+    return join(projectDir, relPath);
+  }
+
+  return join(outDir, relPath);
+}

package/config/vite/plugins/assets/source-file-index.js

@@ -131,7 +131,8 @@ const globalTraversalSkipRoots = (globalRoot, componentRoots) => {
  * @returns {{
  *   all: () => Array<object>,
  *   componentFiles: () => Array<object>,
- *   globalFiles: () => Array<object>
+ *   globalFiles: () => Array<object>,
+ *   refresh: () => void
  * }} Indexed file accessors.
  */
 export function createSourceFileIndex(structure) {
@@ -179,5 +180,10 @@ export function createSourceFileIndex(structure) {
       build();
       return globalFilesArr;
     },
+    refresh: () => {
+      indexedFiles = null;
+      componentFilesArr = null;
+      globalFilesArr = null;
+    },
   };
 }

package/config/vite/plugins/assets/stable-watch-output.js

@@ -0,0 +1,165 @@
+/**
+ * @file Keep `vite build --watch` output stable between rebuilds.
+ *
+ * ## The problem
+ *
+ * Saving one component during `npm run develop` used to rewrite every file in
+ * the output tree. Measured on a real theme, one edit produced:
+ *
+ *     [vite] hot updated: /dist/global/layout/layout.css
+ *     [vite] hot updated: /dist/storybook/components/atoms/textures/cl-textures.css
+ *
+ * Neither file was touched by the edit, and the edited component's own
+ * stylesheet is not in the list. Storybook then reloaded the preview iframe
+ * instead of swapping the stylesheet in place.
+ *
+ * ## Why every file changed
+ *
+ * Two independent causes, and both have to be removed or the churn remains.
+ *
+ * 1. Vite empties the output directory on **every** watch rebuild, not just the
+ *    first. The emptying runs from a `renderStart` hook guarded by a
+ *    "already prepared this environment" set, and Vite's `watchChange` hook
+ *    clears that set, so the guard is re-armed before each cycle. Every
+ *    stylesheet is therefore deleted and recreated per keystroke. Deleting a
+ *    file that Storybook reached through an eager `import.meta.glob` changes
+ *    the glob's module set, which is a full-reload invalidation rather than a
+ *    CSS swap — the flash.
+ *
+ * 2. Rollup regenerates and rewrites the whole bundle each cycle regardless.
+ *    Even with the directory left alone, every stylesheet would get a fresh
+ *    mtime and every watcher would fire.
+ *
+ * ## What this plugin does
+ *
+ * Turns off the per-rebuild emptying once the first cycle has had its clean
+ * tree, then drops bytes-identical stylesheets from the bundle so Rollup never
+ * rewrites them. The first cycle still empties, through Vite's own code and its
+ * own guards, so a develop session starts exactly as it does today.
+ *
+ * A dropped asset leaves the existing file untouched, so no watcher event
+ * fires and no HMR update is sent for a stylesheet the edit could not have
+ * affected. This mirrors what `mirror-components.js` already does for mirrored
+ * component output, where `filesHaveSameBytes` skips the move; plain output had
+ * no equivalent.
+ *
+ * Scoped to emitted assets, not JavaScript chunks: a chunk travels with a
+ * sourcemap and a hashed name graph, and skipping one of a pair is a harder
+ * claim to make. CSS is where the cost lands anyway, because stylesheets are
+ * what the preview enumerates by glob.
+ *
+ * Stylesheets are not the only churn source. Twig templates and static assets
+ * are copied straight to disk rather than emitted through the bundle, so they
+ * carry the same freshness check in their own plugins; a rewritten `.twig` in
+ * the output tree is a full preview reload rather than a style swap.
+ *
+ * One-shot builds are untouched: `npm run build`, `storybook build`, and the
+ * release fixture verifications all start from an emptied directory and write
+ * every file unconditionally.
+ */
+
+import { isAbsolute, resolve } from 'path';
+
+import { bytesAlreadyOnDisk, resolveFinalPath } from './output-freshness.js';
+
+/**
+ * Keep watch-build output stable so unchanged stylesheets are not rewritten.
+ *
+ * @param {{
+ *   projectDir?: string,
+ *   mirrorComponentOutput?: boolean,
+ *   unchangedOutputs?: Set<string>
+ * }} [opts={}] - Plugin options. `unchangedOutputs` is shared with the develop
+ *   reporter so a skipped file is not reported as a deleted one.
+ * @returns {import('vite').PluginOption} Stable watch output plugin.
+ */
+export function stableWatchOutputPlugin({
+  projectDir = process.cwd(),
+  mirrorComponentOutput = false,
+  unchangedOutputs = new Set(),
+} = {}) {
+  let outDir = 'dist';
+  let watching = false;
+  let completedCycles = 0;
+
+  return {
+    name: 'emulsify-stable-watch-output',
+    apply: 'build',
+
+    // Runs after the plugins that rewrite CSS text, or an asset would be
+    // compared before its URLs were finalized and always look changed.
+    enforce: 'post',
+
+    configResolved(config) {
+      const configured = config?.build?.outDir || 'dist';
+      outDir = isAbsolute(configured)
+        ? configured
+        : resolve(projectDir, configured);
+      watching = Boolean(config?.build?.watch);
+    },
+
+    buildStart() {
+      unchangedOutputs.clear();
+      if (!watching) return;
+
+      // Leave the first successfully completed cycle entirely to Vite,
+      // including its refusal to empty an output directory outside the project
+      // root. On later cycles this hook runs before Vite's `renderStart`
+      // emptying hook, so the flag is disabled before Vite decides whether to
+      // clear the tree. A failed initial cycle never reaches `writeBundle`, so
+      // its retry still starts clean.
+      if (completedCycles === 0) return;
+
+      // The flag has to be set on `this.environment.config`: the config object
+      // `configResolved` receives is a different one, and mutating that has no
+      // effect on what Vite reads per cycle.
+      const buildOptions = this.environment?.config?.build;
+      if (!buildOptions) {
+        this.warn(
+          'Unable to keep watch output stable because ' +
+            'this.environment.config.build is unavailable; Vite may empty ' +
+            'the output directory on this rebuild.',
+        );
+        return;
+      }
+
+      buildOptions.emptyOutDir = false;
+    },
+
+    // Count only cycles that made it through all normal output writers. Using
+    // buildStart here would mistake a transform or render failure for a
+    // completed first cycle and suppress cleaning on the retry.
+    writeBundle: {
+      order: 'post',
+      handler() {
+        if (watching) completedCycles += 1;
+      },
+    },
+
+    generateBundle(_options, bundle) {
+      // A one-shot build always starts from an emptied directory, so nothing
+      // would match; leaving it alone keeps release output byte for byte.
+      if (!watching) return;
+
+      for (const [fileName, output] of Object.entries(bundle)) {
+        // Assets only. A JavaScript chunk travels with a sourcemap and a hashed
+        // name graph, and skipping one of a pair is a harder claim to make;
+        // nothing in the preview enumerates chunks by glob, so there is no
+        // reload to win back.
+        if (output.type !== 'asset') continue;
+        if (output.source == null) continue;
+
+        const finalPath = resolveFinalPath(fileName, {
+          outDir,
+          projectDir,
+          mirrored: mirrorComponentOutput,
+        });
+
+        if (bytesAlreadyOnDisk(finalPath, output.source)) {
+          unchangedOutputs.add(fileName);
+          delete bundle[fileName];
+        }
+      }
+    },
+  };
+}

package/config/vite/plugins/assets/storybook-output.js

@@ -0,0 +1,27 @@
+/**
+ * @file Storybook build output markers shared by Core plugins.
+ *
+ * Storybook copies `staticDirs` into `.out/assets` while the preview build
+ * runs, so Vite-generated chunks are routed to a separate directory to avoid
+ * concurrent writers. That directory name doubles as the one deterministic
+ * signal a Core plugin has for "this build is Storybook's, not the theme's" —
+ * no env sniffing, no plugin-name matching, no guessing at `outDir`, which a
+ * consumer can override with `-o`.
+ */
+
+/**
+ * Directory Storybook's Vite build writes generated chunks to.
+ *
+ * @type {string}
+ */
+export const STORYBOOK_VITE_ASSETS_DIR = 'storybook-assets';
+
+/**
+ * Determine whether a resolved Vite config belongs to a Storybook build.
+ *
+ * @param {{build?: {assetsDir?: string}}} config - Resolved Vite config.
+ * @returns {boolean} TRUE when Storybook owns this output directory.
+ */
+export function isStorybookOutput(config) {
+  return config?.build?.assetsDir === STORYBOOK_VITE_ASSETS_DIR;
+}