@emulsify/core 3.4.1 → 4.0.0

package/config/vite/plugins/yaml-module.js

@@ -0,0 +1,133 @@
+/**
+ * @file YAML module plugin for Vite imports.
+ *
+ * This plugin turns YAML imports into ESM modules with default exports and safe
+ * named exports for valid top-level keys.
+ */
+
+import { load as loadYaml } from 'js-yaml';
+
+/**
+ * Remove the Vite query string from a module id.
+ *
+ * @param {string} id - Vite module id.
+ * @returns {string} Filesystem path without query parameters.
+ */
+const stripRequestQuery = (id) => id.split('?')[0];
+
+/**
+ * Determine whether a Vite request should compile as a YAML module.
+ *
+ * @param {string} id - Vite module id, including an optional query string.
+ * @returns {boolean} TRUE when the request is a YAML data import.
+ */
+const isYamlModuleRequest = (id) => {
+  const [filePath, query = ''] = id.split('?');
+  if (!/\.ya?ml$/i.test(filePath)) return false;
+  return !/(^|&)(raw|url)\b/.test(query);
+};
+
+const reservedYamlExportIdentifiers = new Set([
+  'await',
+  'break',
+  'case',
+  'catch',
+  'class',
+  'const',
+  'continue',
+  'debugger',
+  'default',
+  'delete',
+  'do',
+  'else',
+  'export',
+  'extends',
+  'finally',
+  'for',
+  'function',
+  'if',
+  'import',
+  'in',
+  'instanceof',
+  'let',
+  'new',
+  'return',
+  'super',
+  'switch',
+  'this',
+  'throw',
+  'try',
+  'typeof',
+  'var',
+  'void',
+  'while',
+  'with',
+  'yield',
+]);
+
+/**
+ * Determine whether a YAML key can be emitted as a named ESM export.
+ *
+ * @param {string} key - Top-level YAML object key.
+ * @returns {boolean} TRUE when the key is safe to emit as a named export.
+ */
+const isValidYamlExportIdentifier = (key) =>
+  /^[A-Za-z_$][0-9A-Za-z_$]*$/.test(key) &&
+  !key.startsWith('$') &&
+  !reservedYamlExportIdentifiers.has(key);
+
+/**
+ * Determine whether a parsed YAML value is a plain object.
+ *
+ * @param {*} value - Parsed YAML value.
+ * @returns {boolean} TRUE when the value is a plain object.
+ */
+const isPlainObject = (value) =>
+  value !== null &&
+  typeof value === 'object' &&
+  !Array.isArray(value) &&
+  [Object.prototype, null].includes(Object.getPrototypeOf(value));
+
+/**
+ * Transform YAML imports into JavaScript modules.
+ *
+ * @returns {import('vite').PluginOption} YAML module plugin.
+ */
+export function yamlModulePlugin() {
+  return {
+    name: 'emulsify-yaml',
+    enforce: 'pre',
+    transform(source, id) {
+      if (!isYamlModuleRequest(id)) {
+        return null;
+      }
+
+      try {
+        const data = loadYaml(source) ?? null;
+        const namedExports = isPlainObject(data)
+          ? Object.entries(data)
+              .filter(([key]) => isValidYamlExportIdentifier(key))
+              .map(
+                ([key, value]) =>
+                  `export const ${key} = ${JSON.stringify(value)};`,
+              )
+              .join('\n')
+          : '';
+        const defaultExport = `export default ${JSON.stringify(data)};`;
+
+        return {
+          code: `${namedExports}${namedExports ? '\n' : ''}${defaultExport}\n`,
+          map: null,
+        };
+      } catch (error) {
+        this.error(
+          `Unable to parse YAML module ${stripRequestQuery(id)}: ${
+            error?.message || error
+          }`,
+        );
+      }
+
+      return null;
+    },
+  };
+}

package/config/vite/plugins.js

@@ -0,0 +1,12 @@
+/**
+ * @file Public barrel for Emulsify Vite plugin helpers.
+ *
+ * This file preserves the `@emulsify/core/vite/plugins` export path while the
+ * implementation lives in focused internal modules under `config/vite/plugins/`.
+ */
+
+export { makePlugins } from './plugins/index.js';
+export {
+  makeTwigNamespaces,
+  makeTwigPluginOptions,
+} from './plugins/twig-module.js';

package/config/vite/project-config.js

@@ -0,0 +1,192 @@
+/**
+ * @file Normalized project configuration for Emulsify Vite and Storybook.
+ *
+ * This module is the single Node-side reader for `project.emulsify.json`.
+ * Validation is intentionally permissive so existing projects can upgrade
+ * without reshaping older config files. Resolved config objects are memoized
+ * per project directory and relevant environment signature for one process.
+ */
+
+import { normalize, resolve, sep } from 'path';
+import { getPlatformAdapter } from './platforms.js';
+import { resolveProjectStructure } from './project-structure.js';
+import { safeExists, safeReadJson } from './utils/fs-safe.js';
+
+/**
+ * Cache normalized project config by project root and relevant env signature.
+ *
+ * @type {Map<string, Map<string, object>>}
+ */
+const projectConfigCache = new Map();
+
+/**
+ * Ensure an absolute path stays inside the project directory.
+ *
+ * @param {string} projectDir - Absolute project root.
+ * @param {string} candidate - Path to validate (absolute or relative).
+ * @returns {string|null} A safe absolute path, or null if outside projectDir.
+ */
+export function coerceToProjectPath(projectDir, candidate) {
+  if (typeof candidate !== 'string' || !candidate.trim()) return null;
+
+  const absProject = resolve(projectDir);
+  const absCandidate = resolve(projectDir, candidate);
+  const inProject =
+    absCandidate.startsWith(absProject + sep) || absCandidate === absProject;
+  return inProject ? absCandidate : null;
+}
+
+/**
+ * Normalize config strings to lowercase identifiers.
+ *
+ * @param {*} value - Candidate value.
+ * @returns {string} Normalized string.
+ */
+function normalizeIdentifier(value) {
+  return (value || '').toString().toLowerCase().trim();
+}
+
+/**
+ * Build the environment signature for config values that affect resolution.
+ *
+ * @param {NodeJS.ProcessEnv|Record<string,string>} env - Environment values.
+ * @returns {string} Stable cache-key segment.
+ */
+function projectConfigEnvSignature(env = {}) {
+  return JSON.stringify({
+    EMULSIFY_PLATFORM: normalizeIdentifier(env.EMULSIFY_PLATFORM),
+  });
+}
+
+/**
+ * Normalize variant structure implementation declarations.
+ *
+ * @param {string} projectDir - Absolute project root.
+ * @param {Array} implementations - Raw implementation entries.
+ * @returns {{name: string, directory: string}[]} Safe implementation entries.
+ */
+function normalizeStructureImplementations(projectDir, implementations = []) {
+  if (!Array.isArray(implementations)) return [];
+
+  return implementations
+    .map((item, index) => {
+      const rawDirectory =
+        typeof item?.directory === 'string' ? item.directory : null;
+      const directory = rawDirectory
+        ? coerceToProjectPath(projectDir, rawDirectory)
+        : null;
+      if (!directory) return null;
+
+      const name =
+        typeof item?.name === 'string' && item.name.trim()
+          ? normalizeIdentifier(item.name)
+          : `structure-${index + 1}`;
+
+      return {
+        name,
+        directory: normalize(directory),
+      };
+    })
+    .filter(Boolean);
+}
+
+/**
+ * Normalize project config for current tooling consumers.
+ *
+ * @param {string} [projectDir=process.cwd()] - Absolute project root.
+ * @param {NodeJS.ProcessEnv|Record<string,string>} [env=process.env] - Environment values.
+ * @returns {object} Normalized Emulsify environment/config model.
+ */
+export function resolveProjectConfig(
+  projectDir = process.cwd(),
+  env = process.env,
+) {
+  const root = resolve(projectDir);
+  const envSignature = projectConfigEnvSignature(env);
+  const cachedByEnv = projectConfigCache.get(root);
+  if (cachedByEnv?.has(envSignature)) {
+    return cachedByEnv.get(envSignature);
+  }
+
+  const configPath = coerceToProjectPath(root, 'project.emulsify.json');
+  const rawConfigResult = configPath ? safeReadJson(configPath) : {};
+  const rawConfig =
+    rawConfigResult?.data && typeof rawConfigResult.data === 'object'
+      ? rawConfigResult.data
+      : {};
+
+  const srcCandidate = resolve(root, 'src');
+  const srcExists = safeExists(srcCandidate);
+  const srcDir = srcExists ? srcCandidate : resolve(root, 'components');
+
+  const platform =
+    normalizeIdentifier(env.EMULSIFY_PLATFORM) ||
+    normalizeIdentifier(rawConfig?.project?.platform) ||
+    normalizeIdentifier(rawConfig?.variant?.platform) ||
+    'generic';
+  const platformAdapter = getPlatformAdapter(platform);
+
+  const singleDirectoryComponents = Boolean(
+    rawConfig?.project?.singleDirectoryComponents,
+  );
+  const rawStructureImplementations =
+    rawConfig?.variant?.structureImplementations;
+  const structureImplementations = normalizeStructureImplementations(
+    root,
+    rawStructureImplementations,
+  );
+  const structureRoots = structureImplementations.map(
+    (implementation) => implementation.directory,
+  );
+  const projectStructure = resolveProjectStructure({
+    projectDir: root,
+    srcDir,
+    srcExists,
+    SDC: singleDirectoryComponents,
+    structureImplementations,
+    platformAdapter,
+  });
+
+  const config = {
+    projectDir: root,
+    platform,
+    machineName:
+      typeof rawConfig?.project?.machineName === 'string'
+        ? rawConfig.project.machineName
+        : undefined,
+    srcExists,
+    srcDir,
+    singleDirectoryComponents,
+    SDC: singleDirectoryComponents,
+    structureOverrides: projectStructure.structureOverrides,
+    structureImplementations,
+    structureRoots,
+    componentRoots: projectStructure.componentRoots,
+    globalRoots: projectStructure.globalRoots,
+    namespaceRoots: projectStructure.namespaceRoots,
+    outputStrategy: platformAdapter.outputStrategy,
+    outputMode: platformAdapter.outputStrategy,
+    projectStructure,
+    platformAdapter,
+    adapter: platformAdapter,
+    projectConfig: rawConfig,
+  };
+
+  const rootCache = cachedByEnv || new Map();
+  rootCache.set(envSignature, config);
+  projectConfigCache.set(root, rootCache);
+
+  return config;
+}
+
+/**
+ * Clear the process-local project config memoization cache.
+ *
+ * Tests call this to avoid cross-test pollution when they mutate fixture
+ * projects in the same Node process.
+ *
+ * @returns {void}
+ */
+export function resetProjectConfigCache() {
+  projectConfigCache.clear();
+}

package/config/vite/project-extensions.js

@@ -0,0 +1,177 @@
+/**
+ * @file Project-level Vite extension loader.
+ *
+ * Loads optional project-level Vite plugin extensions from:
+ *   config/emulsify-core/vite/plugins.(mjs|js|cjs)
+ *
+ * Supported shapes in that file:
+ *   1) export default [vitePlugin(), ...]
+ *   2) export default (ctx) => [vitePlugin(), ...]
+ *   3) module.exports = [ ... ]
+ *   4) export const extendConfig = (config, ctx) => patchObject
+ */
+
+import { isAbsolute, normalize, relative, resolve } from 'path';
+import { pathToFileURL } from 'url';
+import { createRequire } from 'module';
+import { firstExistingPath } from './utils/fs-safe.js';
+
+const extensionCandidates = [
+  'config/emulsify-core/vite/plugins.mjs',
+  'config/emulsify-core/vite/plugins.js',
+  'config/emulsify-core/vite/plugins.cjs',
+];
+
+/**
+ * Normalize CommonJS module results into an ESM-like shape.
+ *
+ * @param {*} mod - Required module result.
+ * @returns {object} Module namespace-like object.
+ */
+function cjsModule(mod) {
+  return mod && typeof mod === 'object' ? mod : { default: mod };
+}
+
+/**
+ * Determine whether a failed CommonJS load should retry as native ESM.
+ *
+ * @param {Error} error - CommonJS load error.
+ * @returns {boolean} TRUE when native import should handle the module.
+ */
+function shouldImportAsEsm(error) {
+  return (
+    ['ERR_REQUIRE_ESM', 'ERR_REQUIRE_ASYNC_MODULE'].includes(error?.code) ||
+    /Cannot use import statement outside a module|Unexpected token 'export'|Unexpected token export/.test(
+      error?.message || '',
+    )
+  );
+}
+
+/**
+ * Resolve the consuming project root for project-level extensions.
+ *
+ * @param {object} ctx - Context passed to project plugin factories.
+ * @returns {string} Absolute path.
+ */
+function projectRoot(ctx = {}) {
+  return resolve(ctx?.env?.projectDir || process.cwd());
+}
+
+/**
+ * Resolve a path inside the consuming project root.
+ *
+ * @param {string} root - Absolute project root.
+ * @param {string} rel - Project-relative path.
+ * @returns {string} Absolute path.
+ */
+function inProject(root, rel) {
+  return resolve(root, rel);
+}
+
+/**
+ * Determine whether an absolute path stays inside the consuming project root.
+ *
+ * @param {string} root - Absolute project root.
+ * @param {string} abs - Absolute path to inspect.
+ * @returns {boolean} TRUE when the path is under the project root.
+ */
+function insideProject(root, abs) {
+  const target = normalize(abs);
+  const rel = relative(root, target);
+  return Boolean(rel) && !rel.startsWith('..') && !isAbsolute(rel);
+}
+
+/**
+ * Load an ESM or CJS module from an absolute path.
+ *
+ * @param {string|null} absPath - Absolute module path.
+ * @returns {Promise<object|null>} Module namespace or null.
+ */
+async function loadModule(absPath) {
+  if (!absPath) return null;
+  const req = createRequire(absPath);
+
+  if (absPath.endsWith('.cjs')) {
+    return cjsModule(req(absPath));
+  }
+
+  if (absPath.endsWith('.js')) {
+    try {
+      return cjsModule(req(absPath));
+    } catch (error) {
+      if (!shouldImportAsEsm(error)) {
+        throw error;
+      }
+    }
+  }
+
+  return import(pathToFileURL(absPath).href);
+}
+
+/**
+ * Normalize CJS and ESM default export shapes.
+ *
+ * @param {object|null} mod - Loaded module namespace.
+ * @returns {*} Supported default export shape.
+ */
+function defaultExport(mod) {
+  const raw = mod?.default ?? mod;
+  if (
+    raw &&
+    typeof raw === 'object' &&
+    (Array.isArray(raw.default) || typeof raw.default === 'function')
+  ) {
+    return raw.default;
+  }
+  return raw;
+}
+
+/**
+ * Normalize named ESM and CJS object exports for extendConfig.
+ *
+ * @param {object|null} mod - Loaded module namespace.
+ * @returns {Function|undefined} Project config patcher, when present.
+ */
+function extendConfigExport(mod) {
+  if (typeof mod?.extendConfig === 'function') {
+    return mod.extendConfig;
+  }
+  if (typeof mod?.default?.extendConfig === 'function') {
+    return mod.default.extendConfig;
+  }
+  return undefined;
+}
+
+/**
+ * Load user-supplied plugins and an optional config patcher.
+ *
+ * @param {object} ctx - Context passed to project plugin factories.
+ * @returns {Promise<{ projectPlugins: import('vite').PluginOption[], extendConfig?: Function }>}
+ */
+export async function loadProjectExtensions(ctx = {}) {
+  const root = projectRoot(ctx);
+  const candidate =
+    firstExistingPath(
+      extensionCandidates
+        .map((candidatePath) => inProject(root, candidatePath))
+        .filter((candidatePath) => insideProject(root, candidatePath)),
+    ) || null;
+
+  if (!candidate) return { projectPlugins: [] };
+
+  const mod = await loadModule(candidate);
+
+  // Normalize supported default export shapes into a plugin array.
+  let projectPlugins = [];
+  const raw = defaultExport(mod);
+  if (Array.isArray(raw)) {
+    projectPlugins = raw;
+  } else if (typeof raw === 'function') {
+    projectPlugins = raw(ctx) || [];
+  }
+
+  // Named extendConfig export lets projects patch the assembled Vite config.
+  const extendConfig = extendConfigExport(mod);
+
+  return { projectPlugins, extendConfig };
+}