@emulsify/core 3.5.0 → 4.0.0

package/config/vite/project-structure.js

@@ -0,0 +1,447 @@
+/**
+ * @file Shared component structure and output path resolution.
+ *
+ * The helpers here keep source-root discovery, Rollup entry keys, copied asset
+ * destinations, Twig namespaces, and Storybook roots aligned. Resolved
+ * structure objects are memoized by environment object identity for one
+ * process.
+ */
+
+import { basename, relative, resolve, sep } from 'path';
+import { safeExists } from './utils/fs-safe.js';
+import { replaceLastSlash, toPosixPath } from './utils/paths.js';
+import { unique } from './utils/unique.js';
+
+export { replaceLastSlash, toPosixPath };
+
+/**
+ * Cache resolved structures for environment objects without keeping them alive.
+ *
+ * @type {WeakMap<object, object>}
+ */
+let projectStructureCache = new WeakMap();
+
+/** @type {object|null} */
+let defaultProjectStructureCache = null;
+
+/** Strip a JS, JSX, or SCSS extension from an output key. */
+const stripAssetExtension = (filePath) =>
+  filePath.replace(/\.(scss|jsx?)$/i, '');
+
+/** Insert "/css|js" bucket unless SDC=true; strip extension. */
+export function injectBucket(rel, bucket, SDC) {
+  const withoutExt = stripAssetExtension(rel);
+  if (SDC) {
+    return bucket === 'css' ? `${withoutExt}__style` : withoutExt;
+  }
+  return replaceLastSlash(rel, `/${bucket}/`).replace(/\.(scss|jsx?)$/i, '');
+}
+
+/**
+ * Relativize an absolute path from a base directory using POSIX separators.
+ *
+ * @param {string} absPath - Absolute file path.
+ * @param {string} baseDir - Absolute base directory.
+ * @returns {string} POSIX relative path.
+ */
+export function relativeFrom(absPath, baseDir) {
+  return toPosixPath(relative(baseDir, absPath));
+}
+
+/**
+ * Determine whether a file is inside a source root.
+ *
+ * @param {string} absPath - Absolute file path.
+ * @param {string} rootDir - Absolute root path.
+ * @returns {boolean} TRUE when the file is inside the root.
+ */
+function isInsideRoot(absPath, rootDir) {
+  const rel = relative(rootDir, absPath);
+  return Boolean(rel) && !rel.startsWith('..') && !rel.includes(`..${sep}`);
+}
+
+/**
+ * Determine whether a path is the same as a root or inside it.
+ *
+ * @param {string} absPath - Absolute file path.
+ * @param {string} rootDir - Absolute root path.
+ * @returns {boolean} TRUE when the path is inside or equal to the root.
+ */
+function isSameOrInsideRoot(absPath, rootDir) {
+  return absPath === rootDir || isInsideRoot(absPath, rootDir);
+}
+
+/**
+ * Find the first source root containing a file.
+ *
+ * @param {string} absPath - Absolute file path.
+ * @param {{name: string, directory: string}[]} roots - Source root records.
+ * @returns {{name: string, directory: string}|null} Matching root record.
+ */
+export function findSourceRoot(absPath, roots = []) {
+  return roots.find((root) => isInsideRoot(absPath, root.directory)) || null;
+}
+
+/**
+ * Build fallback component roots for non-variant projects.
+ *
+ * The recommended `src/components` root wins when present. If a project has a
+ * `src/` directory but no `src/components`, root `./components` remains a valid
+ * canonical component source for upgrades.
+ *
+ * @param {{projectDir: string, srcDir: string, srcExists: boolean}} env
+ * @returns {{name: string, directory: string}[]} Component source roots.
+ */
+function fallbackComponentRoots({ projectDir, srcDir, srcExists }) {
+  const primary =
+    basename(srcDir) === 'components' ? srcDir : resolve(srcDir, 'components');
+  const rootComponents = resolve(projectDir, 'components');
+  const candidates = unique(
+    [primary, ...(srcExists ? [rootComponents] : []), rootComponents].filter(
+      Boolean,
+    ),
+  );
+  const selected = candidates.find(safeExists) || primary;
+
+  return [{ name: 'components', directory: selected }];
+}
+
+/**
+ * Build fallback global roots for non-variant projects.
+ *
+ * @param {{srcDir: string, srcExists: boolean}} env - Project environment.
+ * @returns {{name: string, directory: string}[]} Global source roots.
+ */
+function fallbackGlobalRoots({ srcDir, srcExists }) {
+  return srcExists ? [{ name: 'global', directory: srcDir }] : [];
+}
+
+/**
+ * Build Twig namespace roots for explicit structure implementations.
+ *
+ * @param {{name: string, directory: string}[]} structureImplementations
+ * @returns {Record<string, string>} Namespace roots.
+ */
+function implementationNamespaceRoots(structureImplementations) {
+  const namespaceRoots = {};
+
+  for (const implementation of structureImplementations) {
+    if (!implementation.name || namespaceRoots[implementation.name]) continue;
+    namespaceRoots[implementation.name] = implementation.directory;
+  }
+
+  if (!namespaceRoots.components && structureImplementations[0]?.directory) {
+    namespaceRoots.components = structureImplementations[0].directory;
+  }
+
+  return namespaceRoots;
+}
+
+/**
+ * Build Twig namespace roots for legacy/non-variant projects.
+ *
+ * @param {{projectDir: string, srcDir: string, srcExists: boolean, componentRootRecords: {name: string, directory: string}[]}} env
+ * @returns {Record<string, string>} Namespace roots.
+ */
+function fallbackNamespaceRoots({
+  projectDir,
+  srcDir,
+  srcExists,
+  componentRootRecords,
+}) {
+  const namespaceRoots = {};
+  const componentRoot = componentRootRecords[0]?.directory;
+
+  if (componentRoot && safeExists(componentRoot)) {
+    namespaceRoots.components = componentRoot;
+  }
+
+  const layoutRoot = unique(
+    [
+      ...(srcExists ? [resolve(srcDir, 'layout')] : []),
+      resolve(projectDir, 'src/layout'),
+      resolve(projectDir, 'layout'),
+    ].filter(Boolean),
+  ).find(safeExists);
+  const tokensRoot = unique(
+    [
+      ...(srcExists ? [resolve(srcDir, 'tokens')] : []),
+      resolve(projectDir, 'src/tokens'),
+      resolve(projectDir, 'tokens'),
+    ].filter(Boolean),
+  ).find(safeExists);
+
+  if (layoutRoot) {
+    namespaceRoots.layout = layoutRoot;
+  }
+  if (tokensRoot) {
+    namespaceRoots.tokens = tokensRoot;
+  }
+
+  return namespaceRoots;
+}
+
+/**
+ * Resolve the serializable project structure model.
+ *
+ * @param {{
+ *   projectDir?: string,
+ *   srcDir?: string,
+ *   srcExists?: boolean,
+ *   SDC?: boolean,
+ *   structureImplementations?: {name: string, directory: string}[],
+ *   platformAdapter?: object
+ * }} [env] - Normalized project environment.
+ * @returns {object} Project structure model.
+ */
+export function resolveProjectStructure(env) {
+  const cacheableEnv = env && typeof env === 'object' ? env : null;
+  if (cacheableEnv?.projectStructure) {
+    return cacheableEnv.projectStructure;
+  }
+  if (cacheableEnv && projectStructureCache.has(cacheableEnv)) {
+    return projectStructureCache.get(cacheableEnv);
+  }
+  if (!cacheableEnv && defaultProjectStructureCache) {
+    return defaultProjectStructureCache;
+  }
+
+  const defaultProjectDir = process.cwd();
+  const defaultSrcDir = resolve(defaultProjectDir, 'src');
+  const resolvedEnv = cacheableEnv || {};
+  const {
+    projectDir = defaultProjectDir,
+    srcDir = defaultSrcDir,
+    srcExists = safeExists(defaultSrcDir),
+    SDC = false,
+    platformAdapter = {},
+  } = resolvedEnv;
+  const structureImplementations =
+    Array.isArray(resolvedEnv.structureImplementations) &&
+    resolvedEnv.structureImplementations.length
+      ? resolvedEnv.structureImplementations
+      : Array.isArray(resolvedEnv.structureRoots) &&
+          resolvedEnv.structureOverrides
+        ? resolvedEnv.structureRoots.map((directory, index) => ({
+            name: index === 0 ? 'components' : `structure-${index + 1}`,
+            directory,
+          }))
+        : [];
+  const structureOverrides = structureImplementations.length > 0;
+  const componentRootRecords = structureOverrides
+    ? structureImplementations
+    : fallbackComponentRoots({ projectDir, srcDir, srcExists });
+  const globalRootRecords = structureOverrides
+    ? []
+    : fallbackGlobalRoots({ srcDir, srcExists });
+  const namespaceRoots = structureOverrides
+    ? implementationNamespaceRoots(structureImplementations)
+    : fallbackNamespaceRoots({
+        projectDir,
+        srcDir,
+        srcExists,
+        componentRootRecords,
+      });
+  const componentRoots = componentRootRecords.map((root) => root.directory);
+  const globalRoots = globalRootRecords.map((root) => root.directory);
+  const namespaceRootValues = Object.values(namespaceRoots);
+  const sourceRoots = unique(
+    [...componentRoots, ...globalRoots].filter(Boolean),
+  );
+  const sourceRootRecords = [...componentRootRecords, ...globalRootRecords];
+  const componentStoryRoots = srcExists
+    ? componentRoots.filter((root) => !isSameOrInsideRoot(root, srcDir))
+    : componentRoots;
+  const storyRoots = structureOverrides
+    ? componentRoots
+    : unique(
+        [...(srcExists ? [srcDir] : []), ...componentStoryRoots].filter(
+          Boolean,
+        ),
+      );
+  const twigRoots = unique(
+    [
+      ...componentRoots,
+      ...namespaceRootValues,
+      ...(structureOverrides ? [] : [srcDir]),
+    ].filter(Boolean),
+  );
+  const mirrorComponentOutput = Boolean(
+    srcExists &&
+    !structureOverrides &&
+    platformAdapter?.build?.mirrorDistComponentsToRoot,
+  );
+
+  const structure = {
+    structureOverrides,
+    componentRootRecords,
+    globalRootRecords,
+    componentRoots,
+    globalRoots,
+    sourceRoots,
+    sourceRootRecords,
+    storyRoots,
+    twigRoots,
+    namespaceRoots,
+    output: {
+      components: 'components',
+      global: 'global',
+      js: 'js',
+      css: 'css',
+      storybook: 'storybook',
+    },
+    outputStrategy: platformAdapter?.outputStrategy || 'dist',
+    outputMode: platformAdapter?.outputStrategy || 'dist',
+    mirrorComponentOutput,
+    SDC: Boolean(SDC),
+  };
+
+  if (cacheableEnv) {
+    projectStructureCache.set(cacheableEnv, structure);
+  } else {
+    defaultProjectStructureCache = structure;
+  }
+
+  return structure;
+}
+
+/**
+ * Clear the process-local project structure memoization cache.
+ *
+ * @returns {void}
+ */
+export function resetProjectStructureCache() {
+  projectStructureCache = new WeakMap();
+  defaultProjectStructureCache = null;
+}
+
+/**
+ * Resolve the legacy relative key used by variant structure entries.
+ *
+ * Existing structure override builds strip the path below the first
+ * `components/` segment when one exists, otherwise they keep the project
+ * relative path. Preserve that behavior for entry-key compatibility.
+ *
+ * @param {string} filePath - Absolute source file path.
+ * @param {object} structure - Project structure model.
+ * @param {string} projectDir - Absolute project root.
+ * @returns {string} Project-relative key segment.
+ */
+function legacyStructureRelative(filePath, structure, projectDir) {
+  const relFromProject = relativeFrom(filePath, projectDir);
+  const componentRoot = findSourceRoot(
+    filePath,
+    structure.componentRootRecords,
+  );
+  if (componentRoot?.name === 'components') {
+    return relativeFrom(filePath, componentRoot.directory);
+  }
+  return relFromProject;
+}
+
+/**
+ * Resolve an output key for compiled JS or CSS.
+ *
+ * @param {string} filePath - Absolute source file path.
+ * @param {'js'|'css'} type - Asset type.
+ * @param {object} structure - Project structure model.
+ * @param {{projectDir: string, srcDir: string, SDC?: boolean}} ctx - Build context.
+ * @returns {string|null} Output key without extension.
+ */
+export function compiledAssetOutputPath(filePath, type, structure, ctx) {
+  const bucket = type === 'css' ? 'css' : 'js';
+  const outputBase =
+    bucket === 'css' ? structure.output.css : structure.output.js;
+
+  if (structure.structureOverrides) {
+    const rel = legacyStructureRelative(filePath, structure, ctx.projectDir);
+    return `${outputBase}/${stripAssetExtension(rel)}`;
+  }
+
+  const componentRoot = findSourceRoot(
+    filePath,
+    structure.componentRootRecords,
+  );
+  if (componentRoot) {
+    const rel = relativeFrom(filePath, componentRoot.directory);
+    return `${structure.output.components}/${injectBucket(
+      `${structure.output.components}/${rel}`,
+      bucket,
+      ctx.SDC,
+    ).replace(/^components\//, '')}`;
+  }
+
+  const globalRoot = findSourceRoot(filePath, structure.globalRootRecords);
+  if (globalRoot) {
+    const rel = relativeFrom(filePath, globalRoot.directory);
+    return `${structure.output.global}/${injectBucket(rel, bucket, ctx.SDC)}`;
+  }
+
+  return null;
+}
+
+/**
+ * Resolve an output key for Storybook/component-library SCSS.
+ *
+ * @param {string} filePath - Absolute source file path.
+ * @param {object} structure - Project structure model.
+ * @param {{projectDir: string, srcDir: string}} ctx - Build context.
+ * @returns {string} Output key without extension.
+ */
+export function storybookStyleOutputPath(filePath, structure, ctx) {
+  const sourceRoot = findSourceRoot(filePath, structure.sourceRootRecords);
+  const relFromSrc = relativeFrom(filePath, ctx.srcDir);
+  const rel =
+    structure.structureOverrides || relFromSrc.startsWith('../')
+      ? structure.structureOverrides
+        ? relativeFrom(filePath, ctx.projectDir)
+        : relativeFrom(filePath, sourceRoot?.directory || ctx.srcDir)
+      : relFromSrc;
+
+  return `${structure.output.storybook}/${rel.replace(/\.scss$/i, '')}`;
+}
+
+/**
+ * Resolve copied component file destination relative to Vite outDir.
+ *
+ * @param {string} filePath - Absolute source file path.
+ * @param {object} structure - Project structure model.
+ * @returns {string|null} OutDir-relative destination.
+ */
+export function copiedComponentOutputPath(filePath, structure) {
+  const componentRoot = findSourceRoot(
+    filePath,
+    structure.componentRootRecords,
+  );
+  if (!componentRoot) return null;
+
+  const rel = relativeFrom(filePath, componentRoot.directory);
+  const base = structure.structureOverrides
+    ? componentRoot.name
+    : structure.output.components;
+  return `${base}/${rel}`;
+}
+
+/**
+ * Resolve copied global file destination relative to Vite outDir.
+ *
+ * @param {string} filePath - Absolute source file path.
+ * @param {object} structure - Project structure model.
+ * @returns {string|null} OutDir-relative destination.
+ */
+export function copiedGlobalOutputPath(filePath, structure) {
+  const globalRoot = findSourceRoot(filePath, structure.globalRootRecords);
+  if (!globalRoot) return null;
+
+  const rel = relativeFrom(filePath, globalRoot.directory);
+  if (
+    rel === 'components' ||
+    rel.startsWith('components/') ||
+    rel === 'util' ||
+    rel.startsWith('util/')
+  ) {
+    return null;
+  }
+
+  return `${structure.output.global}/${rel}`;
+}

package/config/vite/twig-extensions.js

@@ -0,0 +1,109 @@
+/**
+ * @file Optional Twig.js extension resolution for Storybook and Vite Twig rendering.
+ */
+
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+export const DRUPAL_TWIG_FILTERS_MODULE_SPECIFIER =
+  '@emulsify/core/storybook/twig/drupal-filters';
+
+/**
+ * Determine whether Drupal-compatible Twig.js filters should be registered.
+ *
+ * @param {object} [env={}] - Normalized Emulsify environment or Twig options.
+ * @returns {boolean} TRUE when Drupal filter registration is enabled.
+ */
+export function shouldRegisterDrupalTwigFilters(env = {}) {
+  const configuredValue =
+    env?.storybook?.registerDrupalTwigFilters ??
+    env?.projectConfig?.storybook?.registerDrupalTwigFilters;
+
+  if (typeof configuredValue === 'boolean') {
+    return configuredValue;
+  }
+
+  return Boolean(
+    env?.registerDrupalTwigFilters ||
+    env?.platformAdapter?.storybook?.registerDrupalTwigFilters,
+  );
+}
+
+/**
+ * Build browser import specifiers for configured Twig.js extension installers.
+ *
+ * @param {object} [env={}] - Normalized Emulsify environment or Twig options.
+ * @returns {string[]} Import specifiers for extension installer modules.
+ */
+export function twigExtensionModuleSpecifiers(env = {}) {
+  return shouldRegisterDrupalTwigFilters(env)
+    ? [DRUPAL_TWIG_FILTERS_MODULE_SPECIFIER]
+    : [];
+}
+
+/**
+ * Normalize a CommonJS or ESM module into an extension installer function.
+ *
+ * @param {*} moduleValue - Imported or required extension module.
+ * @returns {Function|undefined} Twig.js extension installer.
+ */
+function normalizeInstaller(moduleValue) {
+  const installer = moduleValue?.default ?? moduleValue;
+  return typeof installer === 'function' ? installer : undefined;
+}
+
+/**
+ * Register configured Twig.js extension modules in Node-side Twig instances.
+ *
+ * @param {object} twig - Twig.js instance.
+ * @param {object} [env={}] - Normalized Emulsify environment or Twig options.
+ * @returns {object} The provided Twig.js instance.
+ */
+export function registerConfiguredTwigExtensions(twig, env = {}) {
+  if (shouldRegisterDrupalTwigFilters(env)) {
+    const installer = normalizeInstaller(require('twig-drupal-filters'));
+    if (installer) {
+      installer(twig);
+    }
+  }
+
+  return twig;
+}
+
+/**
+ * Generate the browser virtual module used by Storybook and Twig modules.
+ *
+ * @param {object} [env={}] - Normalized Emulsify environment.
+ * @returns {string} JavaScript module source.
+ */
+export function generateTwigExtensionInstallersModule(env = {}) {
+  const specifiers = twigExtensionModuleSpecifiers(env);
+  const imports = specifiers
+    .map((specifier, index) => {
+      const variableName = `twigExtension${index}`;
+      return `import ${variableName} from ${JSON.stringify(specifier)};`;
+    })
+    .join('\n');
+  const installerNames = specifiers
+    .map((_, index) => `twigExtension${index}`)
+    .join(', ');
+
+  return `
+${imports}
+
+const installers = [${installerNames}].filter(
+  (installer) => typeof installer === 'function',
+);
+
+export const twigExtensionInstallers = installers;
+
+export function registerConfiguredTwigExtensions(Twig) {
+  for (const installer of installers) {
+    installer(Twig);
+  }
+
+  return Twig;
+}
+`;
+}

package/config/vite/utils/fs-safe.js

@@ -0,0 +1,66 @@
+/**
+ * @file Safe filesystem helpers for Vite config and scripts.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+
+/**
+ * Determine whether a path exists without throwing on inaccessible files.
+ *
+ * @param {string} filePath - Absolute or relative filesystem path.
+ * @returns {boolean} TRUE when the path exists.
+ */
+export function safeExists(filePath) {
+  try {
+    return existsSync(filePath);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read a file without throwing when it is missing or inaccessible.
+ *
+ * @param {string} filePath - Absolute or relative filesystem path.
+ * @param {BufferEncoding} [encoding='utf8'] - File encoding.
+ * @returns {string} File contents, or an empty string when unavailable.
+ */
+export function safeReadFile(filePath, encoding = 'utf8') {
+  try {
+    return readFileSync(filePath, encoding);
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Read and parse a JSON file without throwing on missing files.
+ *
+ * Missing or empty files return an empty object. Invalid JSON returns the parse
+ * error so callers that report diagnostics can preserve that behavior.
+ *
+ * @param {string} filePath - Absolute or relative JSON file path.
+ * @returns {{data?: *, error?: Error}} Parsed result or parse error.
+ */
+export function safeReadJson(filePath) {
+  const source = safeReadFile(filePath);
+  if (!source) {
+    return {};
+  }
+
+  try {
+    return { data: JSON.parse(source) };
+  } catch (error) {
+    return { error };
+  }
+}
+
+/**
+ * Return the first existing path from a candidate list.
+ *
+ * @param {string[]} candidates - Candidate filesystem paths.
+ * @returns {string|undefined} First existing path, when found.
+ */
+export function firstExistingPath(candidates = []) {
+  return candidates.filter(Boolean).find((candidate) => safeExists(candidate));
+}

package/config/vite/utils/paths.js

@@ -0,0 +1,40 @@
+/**
+ * @file Shared filesystem path helpers for Vite config and scripts.
+ */
+
+import { sep } from 'path';
+
+/**
+ * Normalize a filesystem path to POSIX separators.
+ *
+ * Splitting on the host separator preserves existing path behavior on Windows,
+ * while the backslash replacement also normalizes Windows-style paths handled
+ * on non-Windows hosts.
+ *
+ * @param {string} filePath - Filesystem path.
+ * @returns {string} Path using forward slashes.
+ */
+export function toPosix(filePath) {
+  return filePath.split(sep).join('/').replace(/\\/g, '/');
+}
+
+/**
+ * Normalize a filesystem path to POSIX separators.
+ *
+ * @param {string} filePath - Filesystem path.
+ * @returns {string} Path using forward slashes.
+ */
+export const toPosixPath = toPosix;
+
+/**
+ * Replace the final slash in a POSIX path with a custom segment.
+ *
+ * @param {string} filePath - POSIX-style path.
+ * @param {string} replacement - Replacement string for the final slash.
+ * @returns {string} Path with the final slash replaced, or the original path.
+ */
+export function replaceLastSlash(filePath, replacement) {
+  const index = filePath.lastIndexOf('/');
+  if (index === -1) return filePath;
+  return filePath.slice(0, index) + replacement + filePath.slice(index + 1);
+}