@emulsify/core 3.5.0 → 4.0.1

package/config/a11y.config.js

@@ -1,14 +1,18 @@
-module.exports = {
+/**
+ * @file Shared accessibility linting configuration.
+ *
+ * These defaults are consumed by the pa11y script and can be extended by
+ * consuming projects through their local Emulsify config.
+ */
+
+export default {
   storybookBuildDir: '../../../../.out',
   pa11y: {
     includeNotices: false,
     includeWarnings: false,
     runners: ['axe'],
   },
-  // A11y linting is done on a component-by-component
-  // basis, which results in the linter reporting some errors that
-  // should be ignored. These codes and descriptions allow for those
-  // errors to be targeted specifically.
+  // Ignore rules that are noisy for isolated component pages.
   ignore: {
     codes: ['landmark-one-main', 'page-has-heading-one'],
     descriptions: ['Ensures all page content is contained by landmarks'],

package/config/babel.config.js

@@ -1,17 +1,12 @@
+/**
+ * @file Babel configuration for test and legacy transpilation paths.
+ */
+
 export default (api) => {
   api.cache(true);
 
-  const presets = [
-    [
-      'minify',
-      {
-        builtIns: false,
-        mangle: {
-          reserved: ['Drupal', 'drupalSettings', 'once'],
-        },
-      },
-    ],
-  ];
+  // Disable Babel's generated comments so minified output stays compact.
+  const presets = [['minify', { builtIns: false }]];
   const comments = false;
 
   return { presets, comments };

package/config/eslint.config.js

@@ -1,19 +1,32 @@
-// Import ESLint Flat Config and required plugins
+/**
+ * @file ESLint flat configuration for Emulsify Core.
+ */
+
 import js from '@eslint/js';
+import babelParser from '@babel/eslint-parser';
+import importPlugin from 'eslint-plugin-import';
 import pluginSecurity from 'eslint-plugin-security';
 import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
 
 export default [
-  // Base ESLint recommended rules
+  // Start with core and plugin recommendations before project overrides.
   js.configs.recommended,
 
-  // Plugin configurations
+  importPlugin.flatConfigs.recommended,
   pluginSecurity.configs.recommended,
   eslintPluginPrettierRecommended,
 
   {
     name: 'emulsify-core-config',
     languageOptions: {
+      parser: babelParser,
+      parserOptions: {
+        requireConfigFile: false,
+        babelOptions: {
+          babelrc: false,
+          configFile: false,
+        },
+      },
       sourceType: 'module',
       ecmaVersion: 'latest',
       globals: {
@@ -28,10 +41,15 @@ export default [
     ignores: ['**/*.min.js', '**/node_modules/**/*'],
 
     rules: {
+      // Keep historical project conventions while warning on risky patterns.
       strict: 0,
       'consistent-return': 'off',
       'no-underscore-dangle': 'off',
       'max-nested-callbacks': ['warn', 3],
+      'import/extensions': 'off',
+      'import/no-unresolved': 'off',
+      'import/no-extraneous-dependencies': 'warn',
+      'import/no-mutable-exports': 'warn',
       'no-plusplus': ['warn', { allowForLoopAfterthoughts: true }],
       'no-param-reassign': 'off',
       'no-prototype-builtins': 'off',
@@ -45,5 +63,15 @@ export default [
       ],
       quotes: ['error', 'single'],
     },
+
+    settings: {
+      'import/ignore': ['\\.(scss|less|css)$'],
+      'import/resolver': {
+        node: {
+          extensions: ['.js', '.jsx'],
+          moduleDirectory: ['src', 'node_modules'],
+        },
+      },
+    },
   },
 ];

package/config/postcss.config.js

@@ -1,5 +1,10 @@
+/**
+ * @file PostCSS plugin configuration.
+ */
+
 import autoPrefixer from 'autoprefixer';
 
 export default {
+  // Autoprefixer keeps compiled CSS compatible with supported browsers.
   plugins: [autoPrefixer()],
 };

package/config/vite/entries.js

@@ -0,0 +1,227 @@
+/**
+ * @file Entries map builder for Vite/Rollup.
+ *
+ * Builds a keyed input map (for `build.rollupOptions.input`) where the map key
+ * encodes the final folder inside the Vite outDir (default `dist/`).
+ *
+ * Modern projects:
+ *   - Global/base assets -> "global/..."
+ *   - Component assets   -> "components/..." (or mirrored to ./components when Drupal)
+ *   - SDC=true removes the injected "/css" or "/js" bucket
+ *
+ * Component Structure Overrides projects (project.emulsify.json: variant.structureImplementations):
+ *   - Only compile JS/SCSS.
+ *   - JS  -> "js/<relative-without-ext>"
+ *   - CSS -> "css/<relative-without-ext>"
+ *   - Twig/assets copying is handled by plugins using the same structure model.
+ *   - cl-* / sb-* SCSS -> "storybook/<path-without-ext>"
+ */
+
+import fs from 'fs';
+import { basename, resolve } from 'path';
+import {
+  compiledAssetOutputPath,
+  resolveProjectStructure,
+  storybookStyleOutputPath,
+} from './project-structure.js';
+import { createSourceFileIndex } from './plugins/source-file-index.js';
+import { replaceLastSlash, toPosix } from './utils/paths.js';
+
+export { replaceLastSlash, toPosix };
+
+/** Remove characters that would confuse Rollup naming or file systems. */
+export const sanitizePath = (s) => s.replace(/[^a-zA-Z0-9/_-]/g, '');
+
+/**
+ * @typedef {Object} BuildContext
+ * @property {string} projectDir
+ * @property {string} srcDir
+ * @property {boolean} srcExists
+ * @property {boolean} isDrupal - kept for downstream logic parity
+ * @property {boolean} SDC
+ * @property {boolean} structureOverrides
+ * @property {string[]} [structureRoots]
+ * @property {object} [sourceFileIndex]
+ */
+
+/* -------------------------------------------------------------------------- */
+/* Utilities                                                                  */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Safe map setter that avoids prototype pollution keys.
+ * @param {Record<string,string>} map
+ * @param {string} key
+ * @param {string} value
+ */
+function safeSetKey(map, key, value) {
+  const forbidden = ['__proto__', 'prototype', 'constructor'];
+  if (!key || forbidden.some((bad) => key.includes(bad))) return;
+  map[key] = value; // eslint-disable-line security/detect-object-injection
+}
+
+/** Return an absolute path from a source index entry or string. */
+const entryPath = (entry) =>
+  typeof entry === 'string' ? entry : entry.absPath;
+
+/** Determine whether a file should be compiled as a JS entry. */
+const isJavaScriptEntry = (entry) => {
+  const filePath = entryPath(entry);
+  return (
+    /\.jsx?$/.test(filePath) &&
+    !/\.(stories|component|min|test)\.jsx?$/.test(filePath)
+  );
+};
+
+/** Determine whether a file should be compiled as a regular SCSS entry. */
+const isScssEntry = (entry) => {
+  const filePath = entryPath(entry);
+  const name = basename(filePath);
+  return (
+    /\.scss$/.test(name) &&
+    !name.startsWith('_') &&
+    !name.startsWith('cl-') &&
+    !name.startsWith('sb-')
+  );
+};
+
+/** Determine whether a file should be emitted under the Storybook style path. */
+const isStorybookScssEntry = (entry) => {
+  const filePath = entryPath(entry);
+  return /\.scss$/.test(filePath) && /(?:cl-|sb-)/.test(basename(filePath));
+};
+
+/* -------------------------------------------------------------------------- */
+/* Inputs builder                                                             */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Build the Rollup/Vite input map.
+ *
+ * Keys are paths **relative to outDir**, without extensions. Examples:
+ *   - "global/layout/css/layout"
+ *   - "components/accordion/js/accordion" (or without "/js" when SDC=true)
+ *
+ * For Component Structure Overrides (variant.structureImplementations present),
+ * only JS/CSS keys are produced under "js/**" and "css/**".
+ *
+ * @param {BuildContext} ctx
+ * @returns {Record<string, string>}
+ */
+export function buildInputs(ctx) {
+  const structure = ctx.projectStructure || resolveProjectStructure(ctx);
+  const sourceFileIndex =
+    ctx.sourceFileIndex || createSourceFileIndex(structure);
+
+  /** @type {Record<string, string>} */
+  const inputs = {};
+
+  /**
+   * Add a key/file pair into the inputs map safely (sanitized + POSIX).
+   * @param {string|null} key
+   * @param {string} abs
+   */
+  const add = (key, abs) => {
+    if (!key) return;
+    const clean = sanitizePath(toPosix(key)).replace(/^\/+/, '');
+    if (!clean) return;
+    safeSetKey(inputs, clean, abs);
+  };
+
+  /* ------------------------------------------------------------------------ */
+  /* STRUCTURE OVERRIDES BRANCH                                               */
+  /* ------------------------------------------------------------------------ */
+  if (structure.structureOverrides) {
+    // Gather JS and SCSS from each declared variant root directory.
+    const componentFiles = sourceFileIndex.componentFiles();
+    const jsFiles = componentFiles.filter(isJavaScriptEntry);
+    const scssFiles = componentFiles.filter(isScssEntry);
+    const storybookScss = componentFiles.filter(isStorybookScssEntry);
+
+    // JS files emit under dist/js using the path below components when possible.
+    for (const entry of jsFiles) {
+      const file = entryPath(entry);
+      add(compiledAssetOutputPath(file, 'js', structure, ctx), file);
+    }
+
+    // SCSS files emit under dist/css using the same relative path rules.
+    for (const entry of scssFiles) {
+      const file = entryPath(entry);
+      add(compiledAssetOutputPath(file, 'css', structure, ctx), file);
+    }
+
+    // Storybook and component-library styles stay under dist/storybook.
+    for (const entry of storybookScss) {
+      const file = entryPath(entry);
+      add(storybookStyleOutputPath(file, structure, ctx), file);
+    }
+
+    return inputs;
+  }
+
+  /* ------------------------------------------------------------------------ */
+  /* MODERN BRANCH (existing behavior preserved)                              */
+  /* ------------------------------------------------------------------------ */
+  const globalFiles = sourceFileIndex.globalFiles();
+  const componentFiles = sourceFileIndex.componentFiles();
+
+  // Global JS
+  for (const entry of globalFiles.filter(isJavaScriptEntry)) {
+    const file = entryPath(entry);
+    add(compiledAssetOutputPath(file, 'js', structure, ctx), file);
+  }
+
+  // Component JS
+  for (const entry of componentFiles.filter(isJavaScriptEntry)) {
+    const file = entryPath(entry);
+    add(compiledAssetOutputPath(file, 'js', structure, ctx), file);
+  }
+
+  // Global SCSS
+  for (const entry of globalFiles.filter(isScssEntry)) {
+    const file = entryPath(entry);
+    add(compiledAssetOutputPath(file, 'css', structure, ctx), file);
+  }
+
+  // Component SCSS
+  for (const entry of componentFiles.filter(isScssEntry)) {
+    const file = entryPath(entry);
+    add(compiledAssetOutputPath(file, 'css', structure, ctx), file);
+  }
+
+  // Storybook/CL SCSS
+  for (const entry of sourceFileIndex.all().filter(isStorybookScssEntry)) {
+    const file = entryPath(entry);
+    add(storybookStyleOutputPath(file, structure, ctx), file);
+  }
+
+  return inputs;
+}
+
+/**
+ * Convenience wrapper that infers `srcDir` and returns an inputs map.
+ * @param {string} projectDir
+ * @param {boolean} [isDrupal=false]
+ * @param {boolean} [SDC=false]
+ * @returns {Record<string,string>}
+ */
+export function buildInputsFromProject(
+  projectDir,
+  isDrupal = false,
+  SDC = false,
+) {
+  const srcPath = resolve(projectDir, 'src');
+  const srcExists = fs.existsSync(srcPath);
+  const srcDir = srcExists ? srcPath : resolve(projectDir, 'components');
+
+  const ctx = {
+    projectDir,
+    srcDir,
+    srcExists,
+    isDrupal,
+    SDC,
+    structureOverrides: false,
+    structureRoots: [],
+  };
+  return buildInputs(ctx);
+}

package/config/vite/environment.js

@@ -0,0 +1,39 @@
+/**
+ * @file Environment resolution for Emulsify + Vite.
+ *
+ * Reads project settings and exposes a normalized "env" object used by
+ * entries, plugins, and the Vite config.
+ *
+ * Highlights:
+ *  - `platform`: from env var or project.emulsify.json (default "generic").
+ *  - `SDC`: boolean from project.emulsify.json `project.singleDirectoryComponents`.
+ *  - `structureOverrides`: true when safe `variant.structureImplementations` exist.
+ *  - `structureRoots`: array of directories from `variant.structureImplementations`.
+ *  - `platformAdapter`: active adapter for platform-specific behavior.
+ */
+
+import { resolveProjectConfig } from './project-config.js';
+
+/**
+ * Resolve environment details for the current project.
+ *
+ * @returns {{
+ *   projectDir: string,
+ *   srcDir: string,
+ *   srcExists: boolean,
+ *   platform: 'drupal' | 'generic' | string,
+ *   SDC: boolean,
+ *   structureOverrides: boolean,
+ *   structureRoots: string[],
+ *   structureImplementations: Array<{name: string, directory: string}>,
+ *   componentRoots: string[],
+ *   globalRoots: string[],
+ *   namespaceRoots: Record<string, string>,
+ *   outputStrategy: string,
+ *   projectStructure: object,
+ *   platformAdapter: object
+ * }}
+ */
+export function resolveEnvironment() {
+  return resolveProjectConfig(process.cwd(), process.env);
+}

package/config/vite/platforms.js

@@ -0,0 +1,70 @@
+/**
+ * @file Platform adapter definitions for Emulsify project behavior.
+ *
+ * Adapters expose platform-specific defaults as serializable data so the same
+ * decisions can be used by Node-side Vite config and Storybook browser code.
+ */
+
+const genericAdapter = {
+  name: 'generic',
+  outputStrategy: 'dist',
+  storybook: {
+    loadDrupalBehaviorShim: false,
+    attachDrupalBehaviors: false,
+    registerDrupalTwigFilters: false,
+    loadMirroredComponentCss: false,
+    allowSyncXhrSource: false,
+  },
+  build: {
+    mirrorDistComponentsToRoot: false,
+  },
+};
+
+const drupalAdapter = {
+  name: 'drupal',
+  outputStrategy: 'drupal-sdc',
+  storybook: {
+    loadDrupalBehaviorShim: true,
+    attachDrupalBehaviors: true,
+    registerDrupalTwigFilters: true,
+    loadMirroredComponentCss: true,
+    allowSyncXhrSource: false,
+  },
+  build: {
+    mirrorDistComponentsToRoot: true,
+  },
+};
+
+const adapters = {
+  generic: genericAdapter,
+  drupal: drupalAdapter,
+};
+
+/**
+ * Deep-clone an adapter so callers can safely serialize or extend it.
+ *
+ * @param {object} adapter - Adapter definition.
+ * @returns {object} Adapter clone.
+ */
+function cloneAdapter(adapter) {
+  return JSON.parse(JSON.stringify(adapter));
+}
+
+/**
+ * Resolve the platform adapter for a normalized platform name.
+ *
+ * Unknown platforms intentionally use generic behavior while preserving the
+ * resolved `platform` string separately on the environment object.
+ *
+ * @param {string} [platform='generic'] - Normalized platform name.
+ * @returns {object} Serializable platform adapter.
+ */
+export function getPlatformAdapter(platform = 'generic') {
+  const key = (platform || 'generic').toString().toLowerCase().trim();
+  if (key === 'drupal') {
+    return cloneAdapter(drupalAdapter);
+  }
+  return cloneAdapter(genericAdapter);
+}
+
+export { adapters };

package/config/vite/plugins/copy-src-assets.js

@@ -0,0 +1,76 @@
+/**
+ * @file Static source asset copy plugin.
+ *
+ * Copies non-code source assets beside the JS/CSS/Twig output that references
+ * them, preserving component and global routing semantics.
+ */
+
+import { copyFileSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+
+import {
+  copiedComponentOutputPath,
+  copiedGlobalOutputPath,
+  findSourceRoot,
+} from '../project-structure.js';
+import {
+  createSourceFileIndex,
+  isStaticSourceAsset,
+} from './source-file-index.js';
+
+/**
+ * Copy non-code assets from source roots to `dist/`.
+ *
+ * @param {{ structure: object, sourceFileIndex?: object }} opts - Plugin options.
+ * @returns {import('vite').PluginOption} Copy plugin.
+ */
+export function copyAllSrcAssetsPlugin({
+  structure,
+  sourceFileIndex = createSourceFileIndex(structure),
+}) {
+  let outDir = 'dist';
+
+  const copyToOutDir = (absPath, relDest) => {
+    if (!relDest) return;
+    const destPath = join(outDir, relDest);
+    mkdirSync(dirname(destPath), { recursive: true });
+    try {
+      copyFileSync(absPath, destPath);
+    } catch {
+      /* noop */
+    }
+  };
+
+  return {
+    name: 'emulsify-copy-all-src-assets',
+    apply: 'build',
+    enforce: 'post',
+
+    /** Capture outDir. */
+    configResolved(cfg) {
+      outDir = cfg.build?.outDir || 'dist';
+    },
+
+    /** Copy before the mirror plugin moves dist/components to the project root. */
+    writeBundle() {
+      for (const file of sourceFileIndex.componentFiles()) {
+        if (!isStaticSourceAsset(file.absPath)) continue;
+        copyToOutDir(
+          file.absPath,
+          copiedComponentOutputPath(file.absPath, structure),
+        );
+      }
+
+      for (const file of sourceFileIndex.globalFiles()) {
+        if (!isStaticSourceAsset(file.absPath)) continue;
+        if (findSourceRoot(file.absPath, structure.componentRootRecords)) {
+          continue;
+        }
+        copyToOutDir(
+          file.absPath,
+          copiedGlobalOutputPath(file.absPath, structure),
+        );
+      }
+    },
+  };
+}

package/config/vite/plugins/copy-twig-files.js

@@ -0,0 +1,84 @@
+/**
+ * @file Twig template and component metadata copy plugin.
+ *
+ * Copies canonical source Twig files and component metadata to the emitted dist
+ * structure using the same routing rules as compiled JS and CSS entries.
+ */
+
+import { copyFileSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+
+import {
+  copiedComponentOutputPath,
+  copiedGlobalOutputPath,
+} from '../project-structure.js';
+import {
+  createSourceFileIndex,
+  isComponentMetadataFile,
+} from './source-file-index.js';
+
+/** Determine whether a Twig file is a partial (filename starts with `_`). */
+const isPartial = (filePath) =>
+  (filePath.split('/')?.pop() || '').trim().startsWith('_');
+
+/**
+ * Copy Twig templates and component metadata to `dist/`.
+ *
+ * @param {{ structure: object, sourceFileIndex?: object }} opts - Plugin options.
+ * @returns {import('vite').PluginOption} Copy plugin.
+ */
+export function copyTwigFilesPlugin({
+  structure,
+  sourceFileIndex = createSourceFileIndex(structure),
+}) {
+  let outDir = 'dist';
+
+  const copyToOutDir = (absPath, relDest) => {
+    if (!relDest) return;
+    const destPath = join(outDir, relDest);
+    mkdirSync(dirname(destPath), { recursive: true });
+    try {
+      copyFileSync(absPath, destPath);
+    } catch {
+      /* noop */
+    }
+  };
+
+  return {
+    name: 'emulsify-copy-twig-files',
+    apply: 'build',
+    enforce: 'post',
+
+    /** Capture the final outDir. */
+    configResolved(cfg) {
+      outDir = cfg.build?.outDir || 'dist';
+    },
+
+    /** Copy before the mirror plugin moves dist/components to the project root. */
+    writeBundle() {
+      for (const file of sourceFileIndex.componentFiles()) {
+        if (file.absPath.endsWith('.twig')) {
+          if (isPartial(file.relPath)) continue;
+          copyToOutDir(
+            file.absPath,
+            copiedComponentOutputPath(file.absPath, structure),
+          );
+        } else if (isComponentMetadataFile(file.absPath)) {
+          copyToOutDir(
+            file.absPath,
+            copiedComponentOutputPath(file.absPath, structure),
+          );
+        }
+      }
+
+      for (const file of sourceFileIndex.globalFiles()) {
+        if (!file.absPath.endsWith('.twig')) continue;
+        if (isPartial(file.relPath)) continue;
+        copyToOutDir(
+          file.absPath,
+          copiedGlobalOutputPath(file.absPath, structure),
+        );
+      }
+    },
+  };
+}

package/config/vite/plugins/css-asset-relativizer.js

@@ -0,0 +1,40 @@
+/**
+ * @file CSS asset URL relativizer plugin.
+ *
+ * Rewrites emitted CSS references to root assets so nested CSS files can keep
+ * resolving copied assets correctly from their final output directories.
+ */
+
+import { posix as pathPosix } from 'path';
+
+/**
+ * Rewrites any `url(assets/...)` found in emitted CSS to a path relative to the
+ * CSS file's directory.
+ *
+ * @param {{ assetsRoot?: string }} [opts] - Plugin options.
+ * @returns {import('vite').PluginOption} CSS asset URL plugin.
+ */
+export function cssAssetUrlRelativizer({ assetsRoot = 'assets' } = {}) {
+  return {
+    name: 'emulsify-css-asset-url-relativizer',
+    apply: 'build',
+    generateBundle(_, bundle) {
+      for (const [fileName, chunk] of Object.entries(bundle)) {
+        if (chunk.type !== 'asset') continue;
+        if (!fileName.endsWith('.css')) continue;
+        if (typeof chunk.source !== 'string') continue;
+
+        const fromDir = pathPosix.dirname(fileName);
+
+        chunk.source = chunk.source.replace(
+          /url\((['"]?)\/?assets\/([^)'"]+)\1\)/g,
+          (match, quote = '', rest) => {
+            const target = pathPosix.join(assetsRoot, rest);
+            const rel = pathPosix.relative(fromDir, target);
+            return `url(${quote}${rel}${quote})`;
+          },
+        );
+      }
+    },
+  };
+}