@emulsify/core 3.4.1 → 4.0.0

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

@@ -0,0 +1,358 @@
+/**
+ * @file Drupal component mirror plugin.
+ *
+ * Mirrors built `dist/components/**` files back to project-root `components/**`
+ * for Drupal SDC projects that author canonical components under `src/`.
+ */
+
+import {
+  copyFileSync,
+  closeSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readSync,
+  readdirSync,
+  renameSync,
+  rmdirSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'fs';
+import { basename, dirname, join, resolve } from 'path';
+
+import { safeExists, safeReadJson } from '../utils/fs-safe.js';
+import { walkFiles } from './source-file-index.js';
+
+const MIRROR_STATE_FILE = '.emulsify-mirror-state.json';
+const FILE_COMPARE_CHUNK_SIZE = 64 * 1024;
+
+/**
+ * Resolve the installed Core package version without relying on import.meta so
+ * Jest's CommonJS transform can load this Vite plugin module.
+ *
+ * @param {string} projectDir - Project directory running the build.
+ * @returns {string} Emulsify Core package version.
+ */
+const resolvePackageVersion = (projectDir) => {
+  const candidates = [
+    join(projectDir, 'node_modules/@emulsify/core/package.json'),
+    join(process.cwd(), 'node_modules/@emulsify/core/package.json'),
+    join(process.cwd(), 'package.json'),
+  ];
+
+  for (const candidate of candidates) {
+    const candidatePackage = safeReadJson(candidate).data;
+    if (
+      candidatePackage?.name === '@emulsify/core' &&
+      candidatePackage.version
+    ) {
+      return candidatePackage.version;
+    }
+  }
+
+  return '0.0.0';
+};
+
+/**
+ * Remove empty parent directories from a start directory up to, but not including,
+ * a stopping boundary directory.
+ *
+ * @param {string} startDir - Directory to prune from.
+ * @param {string} stopAtDir - Boundary directory.
+ */
+const pruneEmptyDirsUpTo = (startDir, stopAtDir) => {
+  const stopAbs = resolve(stopAtDir);
+  let cursor = resolve(startDir);
+
+  const isEmpty = (dir) => {
+    try {
+      // eslint-disable-next-line security/detect-non-literal-fs-filename
+      return readdirSync(dir).length === 0;
+    } catch {
+      return false;
+    }
+  };
+
+  while (cursor.startsWith(stopAbs)) {
+    if (!isEmpty(cursor)) break;
+
+    try {
+      // eslint-disable-next-line security/detect-non-literal-fs-filename
+      rmdirSync(cursor);
+    } catch {
+      // Stop at the first directory that cannot be removed.
+      break;
+    }
+
+    const parent = dirname(cursor);
+    if (parent === cursor || parent === stopAbs) break;
+    cursor = parent;
+  }
+};
+
+/**
+ * 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 {
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    const sourceStats = statSync(sourceFile);
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    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);
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    const sourceHandle = openSync(sourceFile, 'r');
+    try {
+      // eslint-disable-next-line security/detect-non-literal-fs-filename
+      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.
+ *
+ * @param {string} filePath - File path to inspect.
+ * @returns {boolean} TRUE when the path exists and is a symlink.
+ */
+const isSymlink = (filePath) => {
+  try {
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    return lstatSync(filePath).isSymbolicLink();
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Remove a source file, ignoring races where it was already removed.
+ *
+ * @param {string} sourceFile - Source file path.
+ */
+const removeSourceFile = (sourceFile) => {
+  try {
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    unlinkSync(sourceFile);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+};
+
+/**
+ * Create a temporary path beside the final destination so rename is atomic.
+ *
+ * @param {string} destinationFile - Destination file path.
+ * @returns {string} Adjacent temporary path.
+ */
+const createTempDestination = (destinationFile) =>
+  join(
+    dirname(destinationFile),
+    `.${basename(destinationFile)}.${process.pid}.${Date.now()}.${Math.random()
+      .toString(36)
+      .slice(2)}.tmp`,
+  );
+
+/**
+ * Copy across filesystems or symlink boundaries, then rename into place.
+ *
+ * @param {string} sourceFile - Source file path.
+ * @param {string} destinationFile - Destination file path.
+ */
+const copyFileIntoPlace = (sourceFile, destinationFile) => {
+  const tempDestination = createTempDestination(destinationFile);
+
+  try {
+    copyFileSync(sourceFile, tempDestination);
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    renameSync(tempDestination, destinationFile);
+    removeSourceFile(sourceFile);
+  } catch (error) {
+    try {
+      // eslint-disable-next-line security/detect-non-literal-fs-filename
+      unlinkSync(tempDestination);
+    } catch {
+      /* noop */
+    }
+    throw error;
+  }
+};
+
+/**
+ * Move a mirrored file into place without exposing copy-then-unlink state.
+ *
+ * @param {string} sourceFile - Built file under dist.
+ * @param {string} destinationFile - Mirrored project-root destination.
+ */
+const moveFileIntoPlace = (sourceFile, destinationFile) => {
+  mkdirSync(dirname(destinationFile), { recursive: true });
+
+  if (filesHaveSameBytes(sourceFile, destinationFile)) {
+    removeSourceFile(sourceFile);
+    return;
+  }
+
+  if (isSymlink(sourceFile) || isSymlink(destinationFile)) {
+    copyFileIntoPlace(sourceFile, destinationFile);
+    return;
+  }
+
+  try {
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    renameSync(sourceFile, destinationFile);
+  } catch (error) {
+    if (error?.code !== 'EXDEV') throw error;
+    copyFileIntoPlace(sourceFile, destinationFile);
+  }
+};
+
+/**
+ * Safely read the previous mirror state marker.
+ *
+ * @param {string} markerFile - Marker file path.
+ * @returns {object|undefined} Parsed marker state.
+ */
+const readMirrorState = (markerFile) => {
+  const result = safeReadJson(markerFile);
+  return result.data;
+};
+
+/**
+ * Write a mirror state marker.
+ *
+ * @param {string} markerFile - Marker file path.
+ * @param {{ startedAt: string, completedAt: string|null, version: string }} state - Marker state.
+ */
+const writeMirrorState = (markerFile, state) => {
+  mkdirSync(dirname(markerFile), { recursive: true });
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  writeFileSync(markerFile, `${JSON.stringify(state, null, 2)}\n`);
+};
+
+/**
+ * Warn if the previous mirror pass did not complete.
+ *
+ * @param {string} markerFile - Marker file path.
+ */
+const warnOnInterruptedMirror = (markerFile) => {
+  const previousState = readMirrorState(markerFile);
+  if (previousState?.completedAt !== null) return;
+
+  console.warn(
+    `Previous Emulsify component mirror build was interrupted before completion; stale mirrored files may exist. Marker: ${markerFile}`,
+  );
+};
+
+/**
+ * Mirror built component files to the project root `./components/` directory.
+ *
+ * @param {{ enabled: boolean, projectDir: string }} opts - Plugin options.
+ * @returns {import('vite').PluginOption} Drupal mirror plugin.
+ */
+export function mirrorComponentsToRoot({ enabled, projectDir }) {
+  let outDir = 'dist';
+  return {
+    name: 'emulsify-mirror-components-to-root',
+    apply: 'build',
+    enforce: 'post',
+    configResolved(cfg) {
+      outDir = cfg.build?.outDir || 'dist';
+    },
+    writeBundle() {
+      if (!enabled) return;
+      const markerFile = join(outDir, MIRROR_STATE_FILE);
+      warnOnInterruptedMirror(markerFile);
+
+      const startedAt = new Date().toISOString();
+      const mirrorState = {
+        startedAt,
+        completedAt: null,
+        version: resolvePackageVersion(projectDir),
+      };
+      writeMirrorState(markerFile, mirrorState);
+
+      // Vite has written files by writeBundle, while closeBundle can overlap
+      // with the next watch cycle observing a partially mirrored dist tree.
+      const distComponents = join(outDir, 'components');
+      if (safeExists(distComponents)) {
+        for (const srcFile of walkFiles(distComponents)) {
+          const relFromOutDir = srcFile.slice(join(outDir, '').length);
+          const destFile = join(projectDir, relFromOutDir);
+
+          try {
+            moveFileIntoPlace(srcFile, destFile);
+            pruneEmptyDirsUpTo(dirname(srcFile), distComponents);
+          } catch (e) {
+            console.warn(
+              `Mirror copy failed for ${relFromOutDir}: ${e?.message || e}`,
+            );
+          }
+        }
+
+        pruneEmptyDirsUpTo(distComponents, outDir);
+      }
+
+      writeMirrorState(markerFile, {
+        ...mirrorState,
+        completedAt: new Date().toISOString(),
+      });
+    },
+  };
+}

package/config/vite/plugins/require-context.js

@@ -0,0 +1,311 @@
+/**
+ * @file Webpack require.context compatibility for Vite.
+ *
+ * Some existing Emulsify stories still use Webpack's static
+ * `require.context()` helper to enumerate asset names. Vite does not define
+ * `require` in browser modules, so this plugin rewrites static calls to
+ * equivalent eager `import.meta.glob()` maps before import analysis runs.
+ */
+
+import { existsSync, readdirSync } from 'fs';
+import { dirname, relative, resolve } from 'path';
+import { toPosixPath } from '../utils/paths.js';
+
+const REQUIRE_CONTEXT_PATTERN =
+  /require\.context\(\s*(['"`])([^'"`]+)\1\s*,\s*(true|false)\s*,\s*\/((?:\\.|[^/\\])+)\/([dgimsuvy]*)\s*,?\s*\)/g;
+const STATIC_ASSET_CONTEXT_EXTS = new Set([
+  'avif',
+  'eot',
+  'gif',
+  'ico',
+  'jpeg',
+  'jpg',
+  'otf',
+  'pdf',
+  'png',
+  'svg',
+  'ttf',
+  'webp',
+  'woff',
+  'woff2',
+]);
+
+const REQUIRE_CONTEXT_HELPER = `
+const __emulsifyRequireContext = (modules, basePath, matcher) => {
+  const normalizeKey = (key) => key.startsWith('./') ? key : \`./\${key}\`;
+  const moduleKey = (key) => basePath + normalizeKey(key).slice(2);
+  const context = (key) => modules[moduleKey(key)];
+
+  context.keys = () =>
+    Object.keys(modules)
+      .map((key) => \`./\${key.slice(basePath.length)}\`)
+      .filter((key) => matcher.test(key))
+      .sort();
+  context.resolve = (key) => moduleKey(key);
+  context.id = basePath;
+
+  return context;
+};
+
+const __emulsifyRequireContextFromKeys = (keys, basePath, publicBasePath) => {
+  const normalizedKeys = keys.slice().sort();
+  const keySet = new Set(normalizedKeys);
+  const normalizeKey = (key) => key.startsWith('./') ? key : \`./\${key}\`;
+  const moduleKey = (key) => basePath + normalizeKey(key).slice(2);
+  const publicKey = (key) =>
+    publicBasePath ? publicBasePath + normalizeKey(key).slice(2) : moduleKey(key);
+  const context = (key) => keySet.has(normalizeKey(key)) ? publicKey(key) : undefined;
+
+  context.keys = () => normalizedKeys.slice();
+  context.resolve = (key) => moduleKey(key);
+  context.id = basePath;
+
+  return context;
+};
+`.trim();
+
+/**
+ * Determine whether a request is JavaScript-like source Vite should transform.
+ *
+ * @param {string} id - Vite module id.
+ * @returns {boolean} TRUE when the id is transformable JavaScript source.
+ */
+const isJavaScriptRequest = (id) =>
+  /\.[cm]?[jt]sx?(?:\?|$)/.test(id) && !id.includes('/node_modules/');
+
+/**
+ * Normalize a require.context directory argument for Vite glob keys.
+ *
+ * @param {string} request - Static directory request from require.context.
+ * @returns {string} Directory request with a trailing slash.
+ */
+const normalizeBasePath = (request) => {
+  if (request.endsWith('/')) return request;
+  if (request === '.') return './';
+  return `${request}/`;
+};
+
+/**
+ * Build a focused glob tail for the common extension-only regex shape.
+ *
+ * @param {string} regexSource - Source from a JavaScript regex literal.
+ * @returns {string} Glob tail.
+ */
+const globTailFromRegex = (regexSource) => {
+  const singleExtension = regexSource.match(/^\\\.([A-Za-z0-9]+)\$$/);
+  if (singleExtension) {
+    return `*.${singleExtension[1]}`;
+  }
+
+  const extensionGroup = regexSource.match(/^\\\.\(([-A-Za-z0-9_|]+)\)\$$/);
+  if (extensionGroup) {
+    return `*.{${extensionGroup[1].replaceAll('|', ',')}}`;
+  }
+
+  return '*';
+};
+
+/**
+ * Extract extension names from regexes that can be represented by a file glob.
+ *
+ * @param {string} regexSource - Source from a JavaScript regex literal.
+ * @returns {string[]} Lowercase extension names.
+ */
+const extensionsFromRegex = (regexSource) => {
+  const singleExtension = regexSource.match(/^\\\.([A-Za-z0-9]+)\$$/);
+  if (singleExtension) {
+    return [singleExtension[1].toLowerCase()];
+  }
+
+  const extensionGroup = regexSource.match(/^\\\.\(([-A-Za-z0-9_|]+)\)\$$/);
+  if (extensionGroup) {
+    return extensionGroup[1]
+      .split('|')
+      .filter(Boolean)
+      .map((extension) => extension.toLowerCase());
+  }
+
+  return [];
+};
+
+/**
+ * Remove stateful regex flags so repeated matcher.test() calls stay stable.
+ *
+ * @param {string} flags - Flags from a JavaScript regex literal.
+ * @returns {string} Non-stateful regex flags.
+ */
+const normalizeRegexFlags = (flags) => flags.replace(/[gy]/g, '');
+
+/**
+ * Resolve a static require.context directory against the importing module.
+ *
+ * @param {string} id - Vite module id.
+ * @param {string} request - Static directory request from require.context.
+ * @returns {string} Absolute filesystem directory path.
+ */
+const resolveContextDirectory = (id, request) => {
+  const importer = String(id || '').split('?')[0];
+  if (!importer || importer.includes('/node_modules/')) return '';
+
+  return resolve(dirname(importer), request);
+};
+
+/**
+ * Find files in a context directory and return Webpack-style context keys.
+ *
+ * @param {string} directory - Absolute context directory.
+ * @param {boolean} recursive - Whether nested directories are included.
+ * @param {RegExp} matcher - Context file matcher.
+ * @returns {string[]} Sorted `./file.ext` keys.
+ */
+function contextKeysFromDirectory(directory, recursive, matcher) {
+  const keys = [];
+
+  const visit = (currentDirectory) => {
+    for (const entry of readdirSync(currentDirectory, {
+      withFileTypes: true,
+    })) {
+      const absolutePath = resolve(currentDirectory, entry.name);
+      if (entry.isDirectory()) {
+        if (recursive) visit(absolutePath);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+
+      const key = `./${toPosixPath(relative(directory, absolutePath))}`;
+      if (matcher.test(key)) {
+        keys.push(key);
+      }
+    }
+  };
+
+  visit(directory);
+  return keys.sort();
+}
+
+/**
+ * Resolve a public URL base for root project asset directories.
+ *
+ * @param {string} directory - Absolute context directory.
+ * @returns {string} Public URL base, or an empty string when unknown.
+ */
+const publicBasePathForDirectory = (directory) => {
+  const relativeDirectory = toPosixPath(relative(process.cwd(), directory));
+
+  return relativeDirectory === 'assets' ||
+    relativeDirectory.startsWith('assets/')
+    ? `/${relativeDirectory.replace(/\/?$/, '/')}`
+    : '';
+};
+
+/**
+ * Build a key-only context for static assets to avoid module-importing files
+ * that Storybook may also serve through staticDirs.
+ *
+ * @param {{ id?: string, request: string, recursive: boolean, regexSource: string, regexFlags: string, basePath: string }} options
+ * Context details from the require.context call.
+ * @returns {string|null} Replacement source, or null when the directory cannot be enumerated.
+ */
+function staticAssetContextReplacement({
+  id,
+  request,
+  recursive,
+  regexSource,
+  regexFlags,
+  basePath,
+}) {
+  const extensions = extensionsFromRegex(regexSource);
+  if (
+    !extensions.length ||
+    !extensions.every((extension) => STATIC_ASSET_CONTEXT_EXTS.has(extension))
+  ) {
+    return null;
+  }
+
+  const directory = resolveContextDirectory(id, request);
+  if (!directory || !existsSync(directory)) return null;
+
+  const matcher = new RegExp(regexSource, normalizeRegexFlags(regexFlags));
+  const keys = contextKeysFromDirectory(directory, recursive, matcher);
+  const publicBasePath = publicBasePathForDirectory(directory);
+
+  return (
+    '__emulsifyRequireContextFromKeys(' +
+    `${JSON.stringify(keys)}, ` +
+    `${JSON.stringify(basePath)}, ` +
+    `${JSON.stringify(publicBasePath)}` +
+    ')'
+  );
+}
+
+/**
+ * Transform static require.context calls into Vite import.meta.glob calls.
+ *
+ * @param {string} source - JavaScript source.
+ * @param {string} [id=''] - Vite module id.
+ * @returns {string|null} Transformed source, or null when unchanged.
+ */
+export function transformRequireContext(source, id = '') {
+  const replacements = [];
+  let match;
+
+  REQUIRE_CONTEXT_PATTERN.lastIndex = 0;
+  while ((match = REQUIRE_CONTEXT_PATTERN.exec(source))) {
+    const [, , request, recursive, regexSource, regexFlags] = match;
+    const basePath = normalizeBasePath(request);
+    const globTail = globTailFromRegex(regexSource);
+    const globPattern = `${basePath}${recursive === 'true' ? '**/' : ''}${globTail}`;
+    const matcherFlags = normalizeRegexFlags(regexFlags);
+    const staticAssetReplacement = staticAssetContextReplacement({
+      basePath,
+      id,
+      recursive: recursive === 'true',
+      regexFlags,
+      regexSource,
+      request,
+    });
+    const replacement =
+      staticAssetReplacement ||
+      '__emulsifyRequireContext(' +
+        `import.meta.glob(${JSON.stringify(globPattern)}, { eager: true, import: 'default' }), ` +
+        `${JSON.stringify(basePath)}, ` +
+        `new RegExp(${JSON.stringify(regexSource)}, ${JSON.stringify(matcherFlags)})` +
+        ')';
+
+    replacements.push({
+      end: REQUIRE_CONTEXT_PATTERN.lastIndex,
+      replacement,
+      start: match.index,
+    });
+  }
+
+  if (!replacements.length) return null;
+
+  let transformed = source;
+  for (const { start, end, replacement } of replacements.reverse()) {
+    transformed =
+      transformed.slice(0, start) + replacement + transformed.slice(end);
+  }
+
+  return `${REQUIRE_CONTEXT_HELPER}\n\n${transformed}`;
+}
+
+/**
+ * Rewrite static Webpack require.context calls for Vite-powered stories.
+ *
+ * @returns {import('vite').PluginOption} Vite plugin.
+ */
+export function requireContextCompatPlugin() {
+  return {
+    name: 'emulsify-require-context-compat',
+    enforce: 'pre',
+    transform(source, id) {
+      if (!isJavaScriptRequest(id) || !source.includes('require.context')) {
+        return null;
+      }
+
+      const code = transformRequireContext(source, id);
+      return code ? { code, map: null } : null;
+    },
+  };
+}