@emulsify/core 4.3.2 → 4.5.0

package/.storybook/main-static-assets.js

@@ -1,6 +1,8 @@
 import fs from 'fs';
 import path from 'path';
 
+import { resolveAssetRoots } from '../config/vite/utils/asset-roots.js';
+
 const projectRoot = process.cwd();
 
 /**
@@ -39,14 +41,9 @@ function existingStaticDirs(staticDirs) {
  * @returns {Array<string|{from: string, to: string}>} Static directory entries.
  */
 export function buildAssetStaticDirs(env) {
-  const configuredAssetRoots = Array.isArray(env.projectStructure?.assetRoots)
-    ? env.projectStructure.assetRoots
-    : [];
-  const assetRoots = [
-    ...configuredAssetRoots,
-    path.resolve(projectRoot, 'assets'),
-    path.resolve(projectRoot, 'src/assets'),
-  ];
+  // One shared list keeps what Storybook serves at /assets identical to what
+  // the Vite build and the audit resolve `/assets/...` against.
+  const assetRoots = resolveAssetRoots(env, { existingOnly: false });
 
   return existingStaticDirs([
     ...assetRoots.map((root) => ({

package/.storybook/main-vite.js

@@ -6,6 +6,7 @@ import {
   mergeReactSingletonResolve,
 } from '../config/vite/utils/react-singleton.js';
 import { createDevServerLogger } from '../config/vite/plugins/reporter/vite-logger.js';
+import { STORYBOOK_VITE_ASSETS_DIR } from '../config/vite/plugins/assets/storybook-output.js';
 import { makeGeneratedDistFilesPlugin } from './main-static-assets.js';
 
 // Twig glob maps are provided by config/vite/plugins/twig/virtual-twig-globs.js.
@@ -29,9 +30,13 @@ const twigRuntimeOptimizeDepsExclude = [
  * keeping generated chunks in a separate folder avoids concurrent writers in
  * `.out/assets`.
  *
+ * Imported rather than repeated: Core plugins read this value back off the
+ * resolved config to tell a Storybook build from a theme build, so the two
+ * must never drift.
+ *
  * @type {string}
  */
-const storybookViteAssetsDir = 'storybook-assets';
+const storybookViteAssetsDir = STORYBOOK_VITE_ASSETS_DIR;
 
 /**
  * Merge Storybook and project optimizeDeps excludes with Core Twig runtime IDs.
@@ -123,7 +128,7 @@ function makeTwigVirtualModuleOptimizerPlugin() {
  * @returns {Function} Storybook `viteFinal` callback.
  */
 export function createViteFinal(resolvedStorybookEnv) {
-  return async function viteFinal(config) {
+  return async function viteFinal(config, { configType } = {}) {
     const { createLogger, mergeConfig } = await import('vite');
     const env = resolvedStorybookEnv;
     const storybookBuildConfig = config?.build || {};
@@ -132,9 +137,12 @@ export function createViteFinal(resolvedStorybookEnv) {
     // has historically consumed that branch, while `mode` still reflects
     // whether Storybook is running in development or production.
     const mode = config?.mode || 'development';
+    const isStorybookBuild = configType
+      ? configType === 'PRODUCTION'
+      : mode === 'production';
     const baseViteConfig =
       typeof viteConfig === 'function'
-        ? await viteConfig({ command: 'serve', mode })
+        ? await viteConfig({ command: 'serve', mode, isStorybookBuild })
         : viteConfig;
     const existingDefine = (config && config.define) || {};
     const viteDefine = (baseViteConfig && baseViteConfig.define) || {};

package/README.md

@@ -35,8 +35,9 @@ implementation details where they belong.
 - Consumers are supported on Node.js 24.13.0 or later. The strictest published
   toolchain dependency, `stylelint-selector-bem-pattern` 5, requires that patch.
 - Contributors should use Node.js 24.18.0, the exact version pinned in `.nvmrc`.
-- CI also uses Node.js 24.18.0 by reading `.nvmrc`, so local development and
-  automated checks share the same recommended runtime.
+- Release-readiness CI runs on both the public 24.13.0 floor and the recommended
+  24.18.0 version. Other CI and release jobs read the exact version from
+  `.nvmrc`.
 
 ## Project Evolution
 
@@ -49,6 +50,11 @@ See [Version Evolution](docs/version-evolution.md) for major-version history
 and the [4.3.0 release notes](docs/releases/4.3.0.md) for the compatibility
 changes and additions in that release.
 
+The [compatibility and support policy](docs/version-evolution.md#compatibility-and-support-policy)
+separates current requirements and the existing 4.x compatibility rule from
+maintenance promises. Pending decisions live in the
+[maintainer register](docs/maintainer-decisions.md).
+
 ## Authoring Models
 
 Emulsify Core supports Twig and React authoring workflows plus a focused
@@ -167,6 +173,7 @@ The documentation is split by task:
 | [Migration To 4.x](docs/migration-4x.md)                  | Upgrading a pre-4.x/Webpack project while preserving existing structures.                                         |
 | [4.3.0 Release Notes](docs/releases/4.3.0.md)             | Reviewing the 4.3.0 scope, compatibility changes, public APIs, limitations, and verification evidence.            |
 | [4.3.1 Release Notes](docs/releases/4.3.1.md)             | Reviewing the 4.3.1 develop reporter changes, verbosity controls, and scope limits.                               |
+| [4.4.0 Release Notes](docs/releases/4.4.0.md)             | Reviewing asset resolution, safer audit fixes, incremental output, reporter changes, and release evidence.        |
 
 ## Known Limitations
 
@@ -184,9 +191,6 @@ package using it.
   while raw Twig and text asset sources load lazily when `source()` requests
   them. Large Twig libraries should still keep Storybook source roots
   intentional. See [Performance](docs/performance.md).
-- Production sourcemaps are enabled by default unless a project overrides Vite
-  config through `config/emulsify-core/vite/plugins.*`. See
-  [Performance](docs/performance.md).
 - Project extensions use the public `config/emulsify-core` directory:
   `config/emulsify-core/vite/plugins.*` for Vite,
   `config/emulsify-core/storybook/...` for Storybook, and
@@ -270,7 +274,11 @@ Do not add comments to JSON files, lockfiles, binary assets, generated output,
 legal documents, or dependency files. Those formats either do not support
 comments or should remain exact artifacts.
 
-Please also follow the issue template and pull request templates provided. See below for the correct places to post issues:
+Please also follow the issue template and pull request templates provided.
+The issue links below are for ordinary bugs and feature requests, not
+confidential vulnerability details. See the
+[security-reporting status](docs/maintainer-decisions.md#security-reporting-for-older-lines)
+before preparing a security report.
 
 1. [Emulsify Drupal](https://github.com/emulsify-ds/emulsify-drupal/issues)
 2. [Emulsify Tools (Drupal module)](https://www.drupal.org/project/issues/emulsify_tools)

package/config/a11y-wcag22.js

@@ -0,0 +1,11 @@
+/**
+ * Optional additions to Pa11y's axe rules for WCAG 2.2 level A and AA.
+ * The reviewed Pa11y axe-core 4.11.4 and Core root axe-core 4.13.0 each expose
+ * target-size as their only wcag22a/wcag22aa rule.
+ * Keep this reviewed list explicit instead of enabling future rules implicitly.
+ */
+export default {
+  pa11y: {
+    rules: ['target-size'],
+  },
+};

package/config/vite/entries.js

@@ -64,12 +64,17 @@ function safeSetKey(map, key, value) {
 const entryPath = (entry) =>
   typeof entry === 'string' ? entry : entry.absPath;
 
-/** Determine whether a file should be compiled as a JS entry. */
+/**
+ * Determine whether a file should be compiled as a JS entry.
+ *
+ * Authoring-only siblings never become build entries: stories, documentation
+ * modules, component metadata, pre-minified bundles, and tests.
+ */
 const isJavaScriptEntry = (entry) => {
   const filePath = entryPath(entry);
   return (
     /\.jsx?$/.test(filePath) &&
-    !/\.(stories|component|min|test)\.jsx?$/.test(filePath)
+    !/\.(stories|docs?|component|min|test)\.jsx?$/.test(filePath)
   );
 };
 

package/config/vite/environment.js

@@ -10,6 +10,8 @@
  *  - `structureOverrides`: true when safe `variant.structureImplementations` exist.
  *  - `structureRoots`: array of directories from `variant.structureImplementations`.
  *  - `assetRoots`: array of directories from safe `assets.roots` config.
+ *  - `assetRebase`: whether unresolved CSS asset URLs are repaired.
+ *  - `selfContainedOutput`: whether project assets remain under `dist/assets`.
  *  - `platformAdapter`: active adapter for platform-specific behavior.
  */
 
@@ -28,6 +30,8 @@ import { resolveProjectConfig } from './project-config.js';
  *   structureRoots: string[],
  *   structureImplementations: Array<{name: string, directory: string}>,
  *   assetRoots: string[],
+ *   assetRebase: boolean,
+ *   selfContainedOutput: boolean,
  *   componentRoots: string[],
  *   globalRoots: string[],
  *   namespaceRoots: Record<string, string>,

package/config/vite/plugins/assets/asset-url-rebase.js

@@ -0,0 +1,241 @@
+/**
+ * @file CSS asset URL rebasing.
+ *
+ * Pure decision logic for repairing CSS `url()` references to project assets.
+ * The Vite wiring lives in `css-asset-rebase.js`; keeping the rules here means
+ * every branch is unit-testable without a build.
+ *
+ * ## The problem
+ *
+ * Emulsify accepts both root-absolute `url('/assets/...')` and the namespaced
+ * `url('@assets/...')` alias (docs/asset-references.md). Two other forms are
+ * common in the wild and both ship broken:
+ *
+ * 1. A relative URL authored against the *emitted* CSS location rather than
+ *    the stylesheet — `url('../../assets/images/x.jpg')`. Vite cannot resolve
+ *    it, leaves it verbatim, and it is then re-anchored to wherever the CSS
+ *    lands. Drupal SDC output sits two levels below the theme root, so the
+ *    depth happens to work there and nowhere else.
+ * 2. The bare `url('assets/images/x.jpg')` form. Vite treats it as a package
+ *    specifier, fails to resolve it, and nothing ever emits the asset.
+ *
+ * A configured `assets.roots` entry hits the same wall: Storybook serves it at
+ * `/assets`, so authors write `/assets/logo.png`, but Vite only resolves that
+ * against the project root.
+ *
+ * ## The rule
+ *
+ * This runs after Vite's own CSS URL resolution, so every non-alias `url()` it
+ * sees is one Vite already declined to resolve. The `@assets/...` namespace is
+ * the intentional exception: Core reserves it before Vite resolution so a
+ * package, project alias, or same-named directory cannot displace the project
+ * asset contract. When the `assets/...` tail names exactly one real file under
+ * a real asset root, the URL is rewritten to the canonical form and the asset
+ * is queued for emit. Anything else is left exactly as it was.
+ */
+
+import { dirname, posix, resolve } from 'path';
+
+import { resolveAssetTail } from '../../utils/asset-roots.js';
+import {
+  isNonFilesystemCssUrl,
+  replaceStylesheetUrlTokens,
+} from '../../utils/css-urls.js';
+import { safeExists } from '../../utils/fs-safe.js';
+import { toPosixPath } from '../../utils/paths.js';
+
+/**
+ * Published prefix every asset root is served under.
+ *
+ * @type {string}
+ */
+export const PUBLIC_ASSET_PREFIX = 'assets';
+
+/** Namespaced authoring alias for the same published asset root. */
+export const ASSET_ALIAS_PREFIX = '@assets';
+
+/**
+ * Raw `url()` matcher retained for compatibility with existing deep imports.
+ *
+ * Internal scanners must use `tokenizeStylesheetUrls` or
+ * `replaceStylesheetUrlTokens`, which add the comment and string context this
+ * expression cannot represent.
+ *
+ * @type {RegExp}
+ */
+export const CSS_URL_RE =
+  /(?<=^|[^\w\-\u0080-\uffff])url\((\s*('[^']*'|"[^"]*")\s*|[^'")]+)\)/gi;
+
+/** Leading `./` and `../` segments — "the tail" is what remains after these. */
+const LEADING_RELATIVE_RE = /^(?:\.{1,2}\/)+/;
+
+/**
+ * Split a URL into its filesystem path and any `?query` / `#hash` suffix.
+ *
+ * @param {string} value - Raw URL value without quotes.
+ * @returns {{path: string, suffix: string}} Split URL.
+ */
+export function splitUrlSuffix(value) {
+  const index = value.search(/[?#]/);
+
+  return index === -1
+    ? { path: value, suffix: '' }
+    : { path: value.slice(0, index), suffix: value.slice(index) };
+}
+
+/**
+ * Reduce a URL to the asset path it is reaching for.
+ *
+ * `../../assets/images/x.jpg`, `assets/images/x.jpg`, and
+ * `@assets/images/x.jpg` all reduce to `images/x.jpg`. Sass may rebase a URL
+ * from an imported partial before this plugin sees it, producing a value such
+ * as `../shared/@assets/images/x.jpg`; the alias remains authoritative in that
+ * form too. Requiring either the published prefix or an exact alias path
+ * segment keeps the repair explainable: a bare `images/x.jpg` is never tried
+ * against the asset roots, because nothing about it says "project asset".
+ *
+ * @param {string} urlPath - URL path without quotes, query, or hash.
+ * @returns {string} Asset path relative to an asset root, or an empty string.
+ */
+export function assetTailFor(urlPath) {
+  const normalized = posix.normalize(toPosixPath(urlPath));
+  const relative = normalized.replace(LEADING_RELATIVE_RE, '');
+
+  // Root-absolute URLs other than `/assets/...` belong to the platform. The
+  // embedded alias form exists only because Sass rebases imported partials to
+  // their entry stylesheet, and that result is always relative.
+  if (!normalized.startsWith('/')) {
+    const parts = relative.split('/');
+    const aliasIndex = parts.indexOf(ASSET_ALIAS_PREFIX);
+
+    if (aliasIndex !== -1 && aliasIndex < parts.length - 1) {
+      return parts.slice(aliasIndex + 1).join('/');
+    }
+  }
+
+  const tail = normalized
+    .replace(/^\/+/, '')
+    .replace(LEADING_RELATIVE_RE, '')
+    .replace(/^\/+/, '');
+
+  if (!tail.startsWith(`${PUBLIC_ASSET_PREFIX}/`)) return '';
+
+  const rest = tail.slice(PUBLIC_ASSET_PREFIX.length + 1);
+
+  return !rest || rest.startsWith('..') ? '' : rest;
+}
+
+/**
+ * Determine whether a URL path uses the reserved Sass/CSS asset alias.
+ *
+ * This includes the relative form Vite creates while rebasing a literal URL
+ * from an imported Sass partial, such as `../shared/@assets/images/x.svg`.
+ *
+ * @param {string} urlPath - URL path without quotes, query, or hash.
+ * @returns {boolean} TRUE when an exact `@assets` segment names a non-empty tail.
+ */
+export function isAssetAliasPath(urlPath) {
+  const normalized = posix.normalize(toPosixPath(urlPath));
+  if (normalized.startsWith('/')) return false;
+
+  const parts = normalized.replace(LEADING_RELATIVE_RE, '').split('/');
+  const aliasIndex = parts.indexOf(ASSET_ALIAS_PREFIX);
+
+  return aliasIndex !== -1 && Boolean(parts.slice(aliasIndex + 1).join('/'));
+}
+
+/**
+ * Decide what a single unresolved CSS `url()` should become.
+ *
+ * @param {string} value - URL value as written, without quotes.
+ * @param {string} importer - Absolute path of the stylesheet being compiled.
+ * @param {string[]} roots - Absolute asset roots, in precedence order.
+ * @param {string} [quote=''] - URL value quote, or an empty string when unquoted.
+ * @returns {{status: 'skipped'|'missing'|'ambiguous'|'aliased'|'rebased'|'publish', url?: string, file?: string, emitAs?: string, candidates?: string[]}} Plan.
+ */
+export function planAssetUrl(value, importer, roots = [], quote = '') {
+  const trimmed = String(value || '').trim();
+  if (isNonFilesystemCssUrl(trimmed, quote)) return { status: 'skipped' };
+
+  const { path: urlPath, suffix } = splitUrlSuffix(trimmed);
+  if (!urlPath) return { status: 'skipped' };
+
+  const isRootAbsolute = urlPath.startsWith('/');
+  const isRelative = LEADING_RELATIVE_RE.test(urlPath);
+  const isBareAssets = urlPath.startsWith(`${PUBLIC_ASSET_PREFIX}/`);
+  const isAssetAlias = isAssetAliasPath(urlPath);
+
+  // A bare specifier that is neither `assets/...` nor the reserved
+  // `@assets/...` alias belongs to Vite: it may resolve through package exports
+  // or another alias, and stealing it would be a regression.
+  if (!isRootAbsolute && !isRelative && !isBareAssets && !isAssetAlias) {
+    return { status: 'skipped' };
+  }
+
+  // Defence in depth. Under this hook Vite has already proven the URL does not
+  // resolve from the stylesheet, but the check keeps the function honest when
+  // called in isolation.
+  if (
+    isRelative &&
+    !isAssetAlias &&
+    importer &&
+    safeExists(resolve(dirname(importer), urlPath))
+  ) {
+    return { status: 'skipped' };
+  }
+
+  const rest = assetTailFor(urlPath);
+  if (!rest) return { status: 'skipped' };
+
+  const hit = resolveAssetTail(rest, roots);
+  if (hit.status !== 'resolved') {
+    return {
+      status: hit.status,
+      originalUrl: trimmed,
+      candidates: hit.candidates,
+    };
+  }
+
+  const canonical = `/${PUBLIC_ASSET_PREFIX}/${rest}`;
+  const emitAs = `${PUBLIC_ASSET_PREFIX}/${rest}`;
+
+  // A URL already in canonical form only needs its asset published; rewriting
+  // it would be a no-op edit that churns the emitted CSS.
+  if (urlPath === canonical) {
+    return { status: 'publish', originalUrl: trimmed, file: hit.file, emitAs };
+  }
+
+  return {
+    status: isAssetAlias ? 'aliased' : 'rebased',
+    originalUrl: trimmed,
+    url: `${canonical}${suffix}`,
+    file: hit.file,
+    emitAs,
+  };
+}
+
+/**
+ * Rewrite every repairable asset URL in one stylesheet.
+ *
+ * @param {string} code - Compiled CSS.
+ * @param {string} importer - Absolute path of the stylesheet.
+ * @param {string[]} roots - Absolute asset roots, in precedence order.
+ * @param {(plan: object, context: {value: string}) => void} [onPlan] - Plan observer.
+ * @returns {{code: string, changed: boolean}} Rewritten CSS.
+ */
+export function rewriteStylesheetUrls(code, importer, roots = [], onPlan) {
+  let changed = false;
+
+  const next = replaceStylesheetUrlTokens(code, ({ match, quote, value }) => {
+    const plan = planAssetUrl(value, importer, roots, quote);
+    if (typeof onPlan === 'function') onPlan(plan, { value });
+
+    if (plan.status !== 'rebased' && plan.status !== 'aliased') return match;
+
+    changed = true;
+
+    return `url(${quote}${plan.url}${quote})`;
+  });
+
+  return { code: changed ? next : code, changed };
+}

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

@@ -5,14 +5,19 @@
  * them, preserving component and global routing semantics.
  */
 
-import { copyFileSync, mkdirSync } from 'fs';
-import { dirname, join } from 'path';
+import { copyFileSync, mkdirSync, statSync } from 'fs';
+import { dirname, isAbsolute, join, resolve } from 'path';
 
 import {
   copiedComponentOutputPath,
   copiedGlobalOutputPath,
   findSourceRoot,
 } from '../../project-structure.js';
+import {
+  filesHaveSameBytes,
+  removeDestinationSymlink,
+  resolveFinalPath,
+} from './output-freshness.js';
 import {
   createSourceFileIndex,
   isStaticSourceAsset,
@@ -21,14 +26,17 @@ import {
 /**
  * Copy non-code assets from source roots to `dist/`.
  *
- * @param {{ structure: object, sourceFileIndex?: object }} opts - Plugin options.
+ * @param {{ structure: object, sourceFileIndex?: object, diagnostics?: object, outputChanges?: Map<string, {kind: 'written'|'removed', bytes?: number}> }} opts - Plugin options.
  * @returns {import('vite').PluginOption} Copy plugin.
  */
 export function copyAllSrcAssetsPlugin({
   structure,
   sourceFileIndex = createSourceFileIndex(structure),
+  diagnostics,
+  outputChanges,
 }) {
   let outDir = 'dist';
+  let projectDir = process.cwd();
   let watching = false;
   /** @type {Array<{absPath: string, relDest: string}>|undefined} */
   let plan;
@@ -38,7 +46,10 @@ export function copyAllSrcAssetsPlugin({
    *
    * Shared by both hooks for the same reason as the Twig copier: watching and
    * copying have to be driven by one list, or a file can end up copied on a full
-   * build and ignored on a save.
+   * build and ignored on a save. Structural events for an individually watched
+   * file refresh the plan, but new files and component-directory changes sit
+   * outside that watch set and require a watcher restart. Previous destinations
+   * are not pruned.
    *
    * @returns {Array<{absPath: string, relDest: string}>} Copy plan.
    */
@@ -78,9 +89,16 @@ export function copyAllSrcAssetsPlugin({
     /** Capture outDir. */
     configResolved(cfg) {
       outDir = cfg.build?.outDir || 'dist';
+      projectDir = cfg.root || process.cwd();
       watching = Boolean(cfg.build?.watch);
     },
 
+    watchChange(_id, { event } = {}) {
+      if (!watching || (event !== 'create' && event !== 'delete')) return;
+      sourceFileIndex.refresh?.();
+      plan = undefined;
+    },
+
     // Static assets are copied rather than compiled, so like Twig they are absent
     // from Rollup's module graph and a save would otherwise go unnoticed. Swapping
     // an SVG or a font left the old bytes in `dist/` until an unrelated rebuild.
@@ -92,29 +110,81 @@ export function copyAllSrcAssetsPlugin({
     /** Copy before the mirror plugin moves dist/components to the project root. */
     writeBundle() {
       for (const { absPath, relDest } of copyPlan()) {
-        copyToOutDir(absPath, relDest);
+        const copyResult = copyToOutDir(absPath, relDest);
+        if (watching && copyResult.status === 'written') {
+          outputChanges?.set(relDest, {
+            kind: 'written',
+            bytes: copyResult.bytes,
+          });
+        }
+        if (copyResult.status === 'failed' && copyResult.error) {
+          const errno = copyResult.error.code ?? 'unknown error';
+          const message = `Unable to copy ${absPath} to ${join(outDir, relDest)} (${errno}): ${copyResult.error.message}`;
+          diagnostics?.recordError?.({
+            message,
+            file: absPath,
+            outputState: 'incomplete',
+          });
+          this.warn?.(message);
+        }
       }
     },
   };
 
+  /**
+   * Resolve the output directory to an absolute path.
+   *
+   * @returns {string} Absolute output directory.
+   */
+  function absoluteOutDir() {
+    return isAbsolute(outDir) ? outDir : resolve(projectDir, outDir);
+  }
+
   /**
    * Copy one file into the output directory.
    *
    * @param {string} absPath - Absolute source path.
    * @param {string} relDest - Destination relative to `outDir`.
-   * @returns {void}
+   * @returns {{status: 'written'|'skipped'|'failed', bytes?: number, error?: Error}} Copy result.
    */
   function copyToOutDir(absPath, relDest) {
-    if (!relDest) return;
+    if (!relDest) return { status: 'failed' };
 
-    // Copied unconditionally; see the note in copy-twig-files.js — `emptyOutDir`
-    // clears the destination on every cycle, so nothing is ever up to date.
     const destPath = join(outDir, relDest);
-    mkdirSync(dirname(destPath), { recursive: true });
     try {
+      // Skip assets whose bytes already match during watch. One-shot builds
+      // continue to copy unconditionally as before.
+      if (
+        watching &&
+        filesHaveSameBytes(
+          absPath,
+          resolveFinalPath(relDest, {
+            outDir: absoluteOutDir(),
+            projectDir,
+            mirrored: structure?.mirrorComponentOutput,
+          }),
+        )
+      ) {
+        return { status: 'skipped' };
+      }
+
+      mkdirSync(dirname(destPath), { recursive: true });
+      removeDestinationSymlink(destPath);
       copyFileSync(absPath, destPath);
-    } catch {
-      /* noop */
+      let bytes;
+      if (watching && outputChanges) {
+        try {
+          bytes = statSync(destPath).size;
+        } catch {
+          // The write still succeeded; size is optional reporting metadata.
+        }
+      }
+      return { status: 'written', bytes };
+    } catch (error) {
+      return {
+        status: 'failed',
+        error,
+      };
     }
   }
 }