@emulsify/core 4.3.2 → 4.5.0

package/config/vite/plugins/assets/storybook-output.js

@@ -0,0 +1,27 @@
+/**
+ * @file Storybook build output markers shared by Core plugins.
+ *
+ * Storybook copies `staticDirs` into `.out/assets` while the preview build
+ * runs, so Vite-generated chunks are routed to a separate directory to avoid
+ * concurrent writers. That directory name doubles as the one deterministic
+ * signal a Core plugin has for "this build is Storybook's, not the theme's" —
+ * no env sniffing, no plugin-name matching, no guessing at `outDir`, which a
+ * consumer can override with `-o`.
+ */
+
+/**
+ * Directory Storybook's Vite build writes generated chunks to.
+ *
+ * @type {string}
+ */
+export const STORYBOOK_VITE_ASSETS_DIR = 'storybook-assets';
+
+/**
+ * Determine whether a resolved Vite config belongs to a Storybook build.
+ *
+ * @param {{build?: {assetsDir?: string}}} config - Resolved Vite config.
+ * @returns {boolean} TRUE when Storybook owns this output directory.
+ */
+export function isStorybookOutput(config) {
+  return config?.build?.assetsDir === STORYBOOK_VITE_ASSETS_DIR;
+}

package/config/vite/plugins/index.js

@@ -12,9 +12,12 @@ import { resolveProjectStructure } from '../project-structure.js';
 import { toPosixPath } from '../utils/paths.js';
 import { copyAllSrcAssetsPlugin } from './assets/copy-src-assets.js';
 import { copyTwigFilesPlugin } from './assets/copy-twig-files.js';
+import { cssAssetRebasePlugin } from './assets/css-asset-rebase.js';
 import { cssAssetUrlRelativizer } from './assets/css-asset-relativizer.js';
+import { developmentCssSourceMapPlugins } from './assets/development-source-maps.js';
 import { mirrorComponentsToRoot } from './assets/mirror-components.js';
 import { createSourceFileIndex } from './assets/source-file-index.js';
+import { stableWatchOutputPlugin } from './assets/stable-watch-output.js';
 import { svgSpriteFilePlugin } from './assets/svg-sprite.js';
 import { developReporterPlugin } from './reporter/index.js';
 import { requireContextCompatPlugin } from './require-context.js';
@@ -37,9 +40,10 @@ import { yamlModulePlugin } from './yaml-module.js';
  *   srcDir: string,
  *   srcExists: boolean,
  *   structureOverrides?: boolean,
+ *   developmentBuild?: boolean,
  *   diagnostics?: object
- * }} env - Project environment. When `diagnostics` is present the develop
- *   reporter is appended; it is supplied only for watch builds.
+ * }} env - Project environment. When `diagnostics` is present the reporter is
+ *   appended for watch summaries and actionable one-shot diagnostics.
  * @returns {import('vite').PluginOption[]} Emulsify Vite plugins.
  */
 export function makePlugins(env) {
@@ -56,6 +60,35 @@ export function makePlugins(env) {
   const sourceFileIndex =
     env.sourceFileIndex || createSourceFileIndex(structure);
 
+  // In lean-output mode, filled by the rebase plugin and read by the
+  // relativizer: published asset path -> where that file actually lives,
+  // relative to the project root. It stays empty for self-contained output.
+  /** @type {Map<string, string>} */
+  const publishedAssetSources = new Map();
+  // The subset above that came from Vite copies. An actual CSS rewrite plus
+  // membership here authorizes the relativizer to remove a redundant copy.
+  /** @type {Set<string>} */
+  const removablePublishedAssets = new Set();
+
+  // Filled by the stable-output plugin, read by the reporter: emitted files it
+  // dropped this cycle because the bytes on disk already match. The reporter
+  // diffs one cycle's bundle against the last, so without this a skipped file
+  // would be listed as a deleted one.
+  /** @type {Set<string>} */
+  const unchangedOutputs = new Set();
+
+  // Filled by the source copy plugins, read and reset by the reporter: copied
+  // files never enter Rollup's bundle, so its fingerprint diff cannot see
+  // them. A Map deduplicates paths when more than one producer touches the
+  // same destination and leaves room for safe pruning to report removals if it
+  // is reintroduced later.
+  /** @type {Map<string, {kind: 'written'|'removed', bytes?: number}>|undefined} */
+  const copiedOutputChanges = env.diagnostics ? new Map() : undefined;
+  const developmentCssMaps = developmentCssSourceMapPlugins({
+    projectDir,
+    developmentBuild: env.developmentBuild,
+  });
+
   const basePlugins = [
     virtualTwigExtensionInstallersPlugin(envWithStructure),
     virtualTwigGlobsPlugin(envWithStructure),
@@ -86,29 +119,82 @@ export function makePlugins(env) {
     // Legacy Storybook stories may still enumerate assets with require.context.
     requireContextCompatPlugin(),
 
-    // Keep CSS asset URLs relative to the emitted CSS location.
-    cssAssetUrlRelativizer({ assetsRoot: 'assets' }),
+    // Capture Vite's combined Sass/PostCSS map before Core changes asset URLs.
+    // Vite's extracted-CSS build path discards this map unless Core retains it.
+    developmentCssMaps.capture,
+
+    // Repair CSS asset URLs Vite could not resolve. Ordering against the
+    // relativizer below is load-bearing: this normalizes URLs to `/assets/...`
+    // and either emits an output asset or records its source-tree location;
+    // only then can the relativizer select and calculate the final target.
+    cssAssetRebasePlugin({
+      env: envWithStructure,
+      diagnostics: env.diagnostics,
+      publishedAssetSources,
+      removablePublishedAssets,
+    }),
+
+    // Point CSS asset URLs at the file each one names, relative to the
+    // stylesheet's own location on disk.
+    cssAssetUrlRelativizer({
+      assetsRoot: 'assets',
+      env: envWithStructure,
+      publishedAssetSources,
+      removablePublishedAssets,
+    }),
+
+    // Pair each direct stylesheet entry with its finalized watch-build asset.
+    // This must run after URL rewriting and before stable-output comparison.
+    developmentCssMaps.emit,
+
+    // Last of the CSS chain: once the text is final, an unchanged stylesheet is
+    // dropped rather than rewritten, so a watch rebuild does not send HMR
+    // updates for stylesheets the edit never touched.
+    stableWatchOutputPlugin({
+      projectDir,
+      mirrorComponentOutput: structure.mirrorComponentOutput,
+      unchangedOutputs,
+    }),
   ];
 
   return [
     ...basePlugins,
 
     // Copy Twig templates and component metadata beside compiled assets.
-    copyTwigFilesPlugin({ structure, sourceFileIndex }),
+    copyTwigFilesPlugin({
+      structure,
+      sourceFileIndex,
+      diagnostics: env.diagnostics,
+      outputChanges: copiedOutputChanges,
+    }),
 
     // Copy every non-code asset under src with the same routing.
-    copyAllSrcAssetsPlugin({ structure, sourceFileIndex }),
+    copyAllSrcAssetsPlugin({
+      structure,
+      sourceFileIndex,
+      diagnostics: env.diagnostics,
+      outputChanges: copiedOutputChanges,
+    }),
 
     // Drupal projects with src mirror dist/components back to ./components.
     mirrorComponentsToRoot({
       enabled: structure.mirrorComponentOutput,
       projectDir,
+      developmentBuild: env.developmentBuild,
+      diagnostics: env.diagnostics,
     }),
 
-    // Summarize the build for `npm run develop`. Present only when the Vite
-    // config supplied a diagnostics collector, which it does for watch builds.
+    // Summarize `npm run develop`, and report actionable diagnostics collected
+    // during one-shot Vite or Storybook builds.
     ...(env.diagnostics
-      ? [developReporterPlugin({ env, diagnostics: env.diagnostics })]
+      ? [
+          developReporterPlugin({
+            env,
+            diagnostics: env.diagnostics,
+            unchangedOutputs,
+            copiedOutputChanges,
+          }),
+        ]
       : []),
   ];
 }

package/config/vite/plugins/reporter/asset-resolver.js

@@ -97,7 +97,7 @@ const lineAt = (source, index) => source.slice(0, index).split('\n').length;
  * @param {{projectDir?: string}} env - Project environment.
  * @returns {{
  *   locate: (url: string) => {status: string, label: string},
- *   references: (url: string) => Array<{file: string, line: number}>
+ *   references: (url: string) => Array<{file: string, sourceFile: string, line: number}>
  * }} Resolver.
  */
 export function createAssetResolver({ projectDir = '' } = {}) {
@@ -246,7 +246,7 @@ export function createAssetResolver({ projectDir = '' } = {}) {
      * Find the stylesheets that write this URL, with line numbers.
      *
      * @param {string} url - Unresolved asset URL.
-     * @returns {Array<{file: string, line: number}>} References, in file order.
+     * @returns {Array<{file: string, sourceFile: string, line: number}>} References, in file order.
      */
     references(url) {
       const files = allFiles();
@@ -257,7 +257,7 @@ export function createAssetResolver({ projectDir = '' } = {}) {
        *
        * @param {string[]} stylesheets - Files to search.
        * @param {(source: string) => Array<number>} findOffsets - Offset finder.
-       * @returns {Array<{file: string, line: number}>} Matches.
+       * @returns {Array<{file: string, sourceFile: string, line: number}>} Matches.
        */
       const scan = (stylesheets, findOffsets) => {
         const found = [];
@@ -265,17 +265,19 @@ export function createAssetResolver({ projectDir = '' } = {}) {
         for (const absPath of stylesheets) {
           const source = read(absPath);
           if (!source) continue;
+          const sourceFile = toProjectPath(absPath, projectDir);
 
           for (const offset of findOffsets(source)) {
             found.push({
-              file: tailSegments(toProjectPath(absPath, projectDir)),
+              file: tailSegments(sourceFile),
+              sourceFile,
               line: lineAt(source, offset),
             });
           }
         }
 
         return found.sort(
-          (a, b) => a.file.localeCompare(b.file) || a.line - b.line,
+          (a, b) => a.sourceFile.localeCompare(b.sourceFile) || a.line - b.line,
         );
       };
 
@@ -514,7 +516,7 @@ export function sharedMissingDirectory(rows, projectDir = '') {
  * every row has to be somewhere to go. A URL written in three stylesheets
  * becomes three rows rather than one row with a repeat count.
  *
- * @param {Array<{url: string}>} assets - Unresolved assets from the collector.
+ * @param {Array<{url: string, importer?: string}>} assets - Unresolved assets from the collector.
  * @param {ReturnType<createAssetResolver>} resolver - Asset resolver.
  * @returns {Array<{where: string, url: string, status: string, label: string}>} Table rows.
  */
@@ -523,6 +525,32 @@ export function buildAssetRows(assets, resolver) {
     const location = resolver.locate(asset.url);
     const references = resolver.references(asset.url);
 
+    if (asset.importer) {
+      const importer = cleanUrl(asset.importer).replaceAll('\\', '/');
+      const matchingReference = references.find((reference) => {
+        const sourceFile = reference.sourceFile || reference.file;
+        return sourceFile === importer || importer.endsWith(`/${sourceFile}`);
+      });
+
+      if (!matchingReference) {
+        return [
+          {
+            where: tailSegments(importer),
+            url: asset.url,
+            ...location,
+          },
+        ];
+      }
+
+      return [
+        {
+          where: `${matchingReference.file}:${matchingReference.line}`,
+          url: asset.url,
+          ...location,
+        },
+      ];
+    }
+
     if (references.length === 0) {
       return [{ where: '—', url: asset.url, ...location }];
     }

package/config/vite/plugins/reporter/build-errors.js

@@ -134,7 +134,7 @@ export function parseCssSyntaxError(error) {
 /**
  * Flatten a rolldown build error into the individual errors it wraps.
  *
- * @param {Error & {errors?: Array<object>}} error - Build error.
+ * @param {Error & {errors?: Array<unknown>}} error - Build error.
  * @returns {Array<object>} Individual errors.
  */
 export function flattenBuildErrors(error) {
@@ -143,7 +143,11 @@ export function flattenBuildErrors(error) {
   const nested = error.errors;
   if (!Array.isArray(nested) || nested.length === 0) return [error];
 
-  return nested.flatMap((entry) => flattenBuildErrors(entry));
+  const flattened = nested.flatMap((entry) => flattenBuildErrors(entry));
+
+  // A malformed aggregate can contain only falsy entries. Keep its wrapper so
+  // the failed hook still records an error instead of turning the cycle green.
+  return flattened.length > 0 ? flattened : [error];
 }
 
 /**
@@ -250,7 +254,7 @@ export function describeBuildError(error) {
  * line, and a path that does not resolve — and because one deleted partial
  * commonly produces a dozen of them.
  *
- * @param {Error & {errors?: Array<object>}} error - Build error.
+ * @param {Error & {errors?: Array<unknown>}} error - Build error.
  * @returns {{
  *   importErrors: Array<object>,
  *   syntaxErrors: Array<object>,

package/config/vite/plugins/reporter/diagnostics.js

@@ -35,6 +35,18 @@ const locationKey = (file, line) =>
 const entryKey = (entry) =>
   `${locationKey(entry.file, entry.line)}|${entry.message || ''}`;
 
+/**
+ * Build the identity of one CSS asset reference site.
+ *
+ * The same URL text in two stylesheets represents two separate edits, while
+ * repeat notices for the same stylesheet and URL are one problem to tally.
+ *
+ * @param {string|undefined} importer - Referencing stylesheet.
+ * @param {string|undefined} url - Referenced asset URL.
+ * @returns {string} Stable asset-reference key.
+ */
+const assetReferenceKey = (importer, url) => `${importer || ''}\0${url || ''}`;
+
 /**
  * Record one occurrence against a location map, incrementing when repeated.
  *
@@ -138,8 +150,10 @@ const groupDeprecationsByFile = (deprecationList) => {
  * @returns {{
  *   recordDeprecation: (entry: {id?: string, file?: string, line?: number}) => void,
  *   recordWarning: (entry: {message?: string, file?: string, line?: number}) => void,
- *   recordError: (entry: {message?: string, file?: string, line?: number}) => void,
+ *   recordError: (entry: {message?: string, file?: string, line?: number, outputState?: 'incomplete'}) => void,
  *   recordUnresolvedAsset: (entry: {url?: string, importer?: string}) => void,
+ *   recordAssetRebase: (entry: {status?: string, url?: string, rewritten?: string, importer?: string, resolvedAsset?: string, candidates?: string[]}) => void,
+ *   recordExternalizedModule: (entry: {module?: string, importer?: string}) => void,
  *   recordImportError: (entry: {file?: string, line?: number, specifier?: string}) => void,
  *   recordSyntaxError: (entry: {minifier?: string, message?: string, declaration?: string}) => void,
  *   hasCapturedBuildErrors: () => boolean,
@@ -147,10 +161,11 @@ const groupDeprecationsByFile = (deprecationList) => {
  *     deprecations: Array<{id: string, occurrences: number, locations: Array<{file: string|undefined, line: number|undefined, count: number}>}>,
  *     deprecationsByFile: Array<{file: string, occurrences: number, entries: Array<{id: string, count: number, lines: number[]}>}>,
  *     unresolvedAssets: Array<{url: string, importer: string|undefined, count: number}>,
+ *     assetRebases: Array<{status: string, url: string, rewritten: string|undefined, importer: string|undefined, resolvedAsset: string|undefined, candidates: string[]|undefined, count: number}>,
  *     importErrors: Array<{file: string|undefined, line: number|undefined, specifier: string, count: number}>,
  *     syntaxErrors: Array<{minifier: string|undefined, message: string, declaration: string|undefined, count: number}>,
  *     warnings: Array<{message: string|undefined, file: string|undefined, line: number|undefined, count: number}>,
- *     errors: Array<{message: string|undefined, file: string|undefined, line: number|undefined, count: number}>,
+ *     errors: Array<{message: string|undefined, file: string|undefined, line: number|undefined, outputState?: 'incomplete', count: number}>,
  *     deprecationTotal: number,
  *     deprecationFileCount: number,
  *     hasProblems: boolean
@@ -168,6 +183,10 @@ export function createDiagnosticsCollector() {
   /** @type {Map<string, {url: string, importer: string|undefined, count: number}>} */
   let unresolvedAssets = new Map();
   /** @type {Map<string, object>} */
+  let assetRebases = new Map();
+  /** @type {Map<string, {module: string, importer: string|undefined, count: number}>} */
+  let externalizedModules = new Map();
+  /** @type {Map<string, object>} */
   let importErrors = new Map();
   /** @type {Map<string, object>} */
   let syntaxErrors = new Map();
@@ -266,8 +285,8 @@ export function createDiagnosticsCollector() {
     /**
      * Record one CSS `url()` that Vite could not resolve at build time.
      *
-     * Keyed by URL, because the same asset referenced from two stylesheets with
-     * different relative paths is two separate things for an author to fix.
+     * Keyed by importer and URL, because the same spelling in two stylesheets
+     * is two separate source sites for an author to fix.
      *
      * @param {{url?: string, importer?: string}} entry - Unresolved asset.
      * @returns {void}
@@ -275,14 +294,76 @@ export function createDiagnosticsCollector() {
     recordUnresolvedAsset({ url, importer } = {}) {
       if (!url) return;
 
-      const existing = unresolvedAssets.get(url);
+      const key = assetReferenceKey(importer, url);
+      const existing = unresolvedAssets.get(key);
+      if (existing) {
+        existing.count += 1;
+        return;
+      }
+
+      unresolvedAssets.set(key, { url, importer, count: 1 });
+    },
+
+    /**
+     * Record one CSS `url()` the build repaired, or could not choose for.
+     *
+     * A separate channel from `recordUnresolvedAsset` on purpose: Vite already
+     * warned about every one of these URLs, and folding them into that map
+     * would double the occurrence count it reports. `snapshot()` subtracts
+     * repaired URLs from the unresolved list instead.
+     *
+     * @param {{status?: string, url?: string, rewritten?: string, importer?: string, resolvedAsset?: string, candidates?: string[]}} entry - Rebase record.
+     * @returns {void}
+     */
+    recordAssetRebase({
+      status = 'rebased',
+      url,
+      rewritten,
+      importer,
+      resolvedAsset,
+      candidates,
+    } = {}) {
+      if (!url) return;
+
+      const key = assetReferenceKey(importer, url);
+      const existing = assetRebases.get(key);
+      if (existing) {
+        existing.count += 1;
+        return;
+      }
+
+      assetRebases.set(key, {
+        status,
+        url,
+        rewritten,
+        importer,
+        resolvedAsset,
+        candidates,
+        count: 1,
+      });
+    },
+
+    /**
+     * Record one module Vite externalized for browser compatibility.
+     *
+     * Vite emits this once per importing file per cycle, so a single dependency
+     * that reaches for a Node builtin prints on every keystroke. The identity
+     * that matters is the module, not the importer, so occurrences are tallied
+     * against the module name.
+     *
+     * @param {{module?: string, importer?: string}} entry - Externalized module.
+     * @returns {void}
+     */
+    recordExternalizedModule({ module, importer } = {}) {
+      if (!module) return;
+
+      const existing = externalizedModules.get(module);
       if (existing) {
         existing.count += 1;
-        existing.importer = existing.importer || importer;
         return;
       }
 
-      unresolvedAssets.set(url, { url, importer, count: 1 });
+      externalizedModules.set(module, { module, importer, count: 1 });
     },
 
     snapshot() {
@@ -306,7 +387,10 @@ export function createDiagnosticsCollector() {
       const errorList = [...errors.values()];
       const warningList = [...warnings.values()];
       const unresolvedAssetList = [...unresolvedAssets.values()].sort(
-        (a, b) => b.count - a.count || a.url.localeCompare(b.url),
+        (a, b) =>
+          b.count - a.count ||
+          a.url.localeCompare(b.url) ||
+          String(a.importer || '').localeCompare(String(b.importer || '')),
       );
 
       const importErrorList = [...importErrors.values()].sort(
@@ -315,10 +399,54 @@ export function createDiagnosticsCollector() {
           (a.line ?? 0) - (b.line ?? 0),
       );
 
+      const assetRebaseList = [...assetRebases.values()];
+      const handledReferences = new Set(
+        assetRebaseList
+          .filter(
+            (entry) => entry.status === 'aliased' || entry.status === 'rebased',
+          )
+          .map((entry) => assetReferenceKey(entry.importer, entry.url)),
+      );
+      const handledUrls = new Set(
+        assetRebaseList
+          .filter(
+            (entry) => entry.status === 'aliased' || entry.status === 'rebased',
+          )
+          .map((entry) => entry.url),
+      );
+      // Vite warns about a URL before the rebase plugin repairs it, so without
+      // this a repaired reference or accepted alias is reported as an
+      // outstanding problem. The importer remains part of the identity:
+      // handling one stylesheet must not hide the same URL spelling in another
+      // stylesheet. When Vite's notice lacks an importer, fall back to URL
+      // matching because it sometimes reports the URL itself in the importer
+      // position.
+      const outstandingAssets = unresolvedAssetList.filter((asset) => {
+        if (
+          handledReferences.has(assetReferenceKey(asset.importer, asset.url))
+        ) {
+          return false;
+        }
+
+        if (!asset.importer) return !handledUrls.has(asset.url);
+        return true;
+      });
+
+      // `@assets/...` is an accepted authoring form. It is tracked internally
+      // only to suppress Vite's pre-normalization unresolved notice and must
+      // not appear as a repair in summaries or strict-mode failures.
+      const reportedAssetRebases = assetRebaseList.filter(
+        (entry) => entry.status !== 'aliased',
+      );
+
       return {
         deprecations: deprecationList,
         deprecationsByFile: groupDeprecationsByFile(deprecationList),
-        unresolvedAssets: unresolvedAssetList,
+        unresolvedAssets: outstandingAssets,
+        assetRebases: reportedAssetRebases,
+        externalizedModules: [...externalizedModules.values()].sort(
+          (a, b) => b.count - a.count || a.module.localeCompare(b.module),
+        ),
         importErrors: importErrorList,
         syntaxErrors: [...syntaxErrors.values()],
         warnings: warningList,
@@ -332,7 +460,7 @@ export function createDiagnosticsCollector() {
           errorList.length > 0 ||
           warningList.length > 0 ||
           deprecationList.length > 0 ||
-          unresolvedAssetList.length > 0 ||
+          outstandingAssets.length > 0 ||
           importErrorList.length > 0 ||
           syntaxErrors.size > 0,
       };
@@ -360,6 +488,8 @@ export function createDiagnosticsCollector() {
       warnings = new Map();
       errors = new Map();
       unresolvedAssets = new Map();
+      assetRebases = new Map();
+      externalizedModules = new Map();
       importErrors = new Map();
       syntaxErrors = new Map();
     },