@emulsify/core 4.3.2 → 4.4.0

package/config/vite/plugins/reporter/source-roots.js

@@ -18,6 +18,7 @@ import { gzipSync } from 'node:zlib';
 import { statSync } from 'node:fs';
 
 import { findSourceRoot, relativeFrom } from '../../project-structure.js';
+import { isGeneratedSourceMap } from '../../utils/source-maps.js';
 
 /**
  * Render one source root as a display path.
@@ -303,9 +304,8 @@ export function buildInputRows({
  * Gzipping is the expensive part of a per-file table — it is the whole of
  * Rolldown's `computing gzip size...` pause — so it is spent only where the
  * number means something. Fonts and raster images are already compressed and
- * their gzip figure is noise; sourcemaps compress well but are a diagnostic
- * artifact nobody ships to a browser, and they are among the largest files in a
- * typical `dist/`.
+ * their gzip figure is noise. Source maps are omitted from reporting entirely,
+ * so they never reach this list.
  *
  * @type {string[]}
  */
@@ -321,6 +321,20 @@ const COMPRESSIBLE_EXTENSIONS = [
   '.txt',
 ];
 
+/**
+ * Decide whether a generated file belongs in developer-facing output reports.
+ *
+ * Source maps remain available in watch builds for devtools, but their size is
+ * dominated by debugging metadata and obscures the files a developer can act
+ * on. The production build disables their emission separately.
+ *
+ * @param {string} fileName - Output file name.
+ * @returns {boolean} TRUE when the file should appear in reporter output.
+ */
+export function isReportableOutput(fileName) {
+  return !isGeneratedSourceMap(fileName);
+}
+
 /**
  * Determine whether a file's compressed size is worth computing.
  *
@@ -329,7 +343,7 @@ const COMPRESSIBLE_EXTENSIONS = [
  */
 function isCompressible(fileName) {
   const lower = String(fileName).toLowerCase();
-  if (lower.endsWith('.map')) return false;
+  if (!isReportableOutput(lower)) return false;
 
   return COMPRESSIBLE_EXTENSIONS.some((extension) => lower.endsWith(extension));
 }
@@ -413,7 +427,8 @@ function displayEntry(sourceFile, projectDir) {
 }
 
 /**
- * List every file a build wrote, with its size and, where useful, its gzip size.
+ * List every reportable file a build wrote, with its size and, where useful,
+ * its gzip size. Source maps stay on disk in watch mode but are omitted here.
  *
  * Ordered by size descending. Unlike the input listing, the question here is
  * "what is heavy" — the output row already reports the single largest file, and
@@ -426,21 +441,23 @@ function displayEntry(sourceFile, projectDir) {
 export function buildOutputFileRows(bundle, { gzip = true } = {}) {
   if (!bundle || typeof bundle !== 'object') return [];
 
-  const rows = Object.entries(bundle).map(([fileName, output]) => {
-    const content = outputBuffer(output);
-    const bytes = content ? content.byteLength : 0;
-
-    let gzipBytes;
-    if (gzip && content && isCompressible(fileName)) {
-      try {
-        gzipBytes = gzipSync(content).byteLength;
-      } catch {
-        gzipBytes = undefined;
+  const rows = Object.entries(bundle)
+    .filter(([fileName]) => isReportableOutput(fileName))
+    .map(([fileName, output]) => {
+      const content = outputBuffer(output);
+      const bytes = content ? content.byteLength : 0;
+
+      let gzipBytes;
+      if (gzip && content && isCompressible(fileName)) {
+        try {
+          gzipBytes = gzipSync(content).byteLength;
+        } catch {
+          gzipBytes = undefined;
+        }
       }
-    }
 
-    return { fileName, bytes, gzipBytes };
-  });
+      return { fileName, bytes, gzipBytes };
+    });
 
   return rows.sort(
     (a, b) => b.bytes - a.bytes || a.fileName.localeCompare(b.fileName, 'en'),
@@ -448,7 +465,7 @@ export function buildOutputFileRows(bundle, { gzip = true } = {}) {
 }
 
 /**
- * Fingerprint every file in a bundle by content.
+ * Fingerprint every reportable file in a bundle by content.
  *
  * Rollup regenerates the whole bundle on every watch cycle, so "which files were
  * written" is always "all of them" and says nothing. Comparing content hashes
@@ -464,6 +481,8 @@ export function fingerprintBundle(bundle) {
   if (!bundle || typeof bundle !== 'object') return fingerprints;
 
   for (const [fileName, output] of Object.entries(bundle)) {
+    if (!isReportableOutput(fileName)) continue;
+
     const content = outputBuffer(output);
     if (!content) continue;
 
@@ -507,7 +526,8 @@ export function diffFingerprints(previous = new Map(), current = new Map()) {
  * Raising `logLevel` to quiet the develop loop also discards Rolldown's per-file
  * asset report, which is around seventy lines on a real project. Three of its
  * facts are worth keeping — how many files landed, how much they weigh, and
- * which one is heaviest — and those fit on one line.
+ * which one is heaviest — and those fit on one line. Source maps are excluded
+ * from all three because they are watch-only debugging artifacts.
  *
  * Sizes are computed from the emitted content rather than by reading `dist/`
  * back off disk, so this adds no I/O to the cycle.
@@ -518,7 +538,9 @@ export function diffFingerprints(previous = new Map(), current = new Map()) {
 export function summarizeBundle(bundle) {
   if (!bundle || typeof bundle !== 'object') return undefined;
 
-  const files = Object.entries(bundle);
+  const files = Object.entries(bundle).filter(([fileName]) =>
+    isReportableOutput(fileName),
+  );
   if (files.length === 0) return undefined;
 
   let totalBytes = 0;
@@ -536,6 +558,64 @@ export function summarizeBundle(bundle) {
   return { fileCount: files.length, totalBytes, largest };
 }
 
+/**
+ * Attribute bundle output to the directories that retain it after publishing.
+ *
+ * Rollup writes every file through `outDir`, but Drupal SDC projects then move
+ * `components/**` to the project-root component directory. Partitioning the
+ * in-memory bundle preserves the reporter's no-I/O tally while naming the
+ * directories developers actually inspect after the mirror completes.
+ *
+ * Largest component paths are made relative to `components/`; the directory
+ * row already supplies that prefix, so repeating it would obscure the useful
+ * part of long component paths.
+ *
+ * @param {{
+ *   bundle?: Record<string, {type?: string, code?: string, source?: string|Uint8Array}>,
+ *   outDir?: string,
+ *   mirrorComponentOutput?: boolean,
+ *   componentOutput?: string
+ * }} [options] - Output routing inputs.
+ * @returns {Array<{path: string, write?: {fileCount: number, totalBytes: number, largest?: {fileName: string, bytes: number}}}>} Destination rows.
+ */
+export function buildOutputSummaryRows({
+  bundle,
+  outDir = 'dist',
+  mirrorComponentOutput = false,
+  componentOutput = 'components',
+} = {}) {
+  if (!mirrorComponentOutput) {
+    return [{ path: outDir, write: summarizeBundle(bundle) }];
+  }
+
+  const componentPath = displayRoot(componentOutput);
+  const distBundle = {};
+  const componentBundle = {};
+
+  for (const [fileName, output] of Object.entries(bundle || {})) {
+    const normalizedFileName = fileName.split('\\').join('/');
+
+    if (normalizedFileName.startsWith(componentPath)) {
+      componentBundle[normalizedFileName.slice(componentPath.length)] = output;
+    } else {
+      distBundle[fileName] = output;
+    }
+  }
+
+  const emptyWrite =
+    bundle && typeof bundle === 'object'
+      ? { fileCount: 0, totalBytes: 0 }
+      : undefined;
+
+  return [
+    { path: outDir, write: summarizeBundle(distBundle) || emptyWrite },
+    {
+      path: componentPath,
+      write: summarizeBundle(componentBundle) || emptyWrite,
+    },
+  ];
+}
+
 /**
  * Measure one bundle output in bytes.
  *

package/config/vite/plugins/reporter/strict-mode.js

@@ -0,0 +1,99 @@
+/**
+ * @file Strict asset URL resolution for CI.
+ *
+ * An unresolvable CSS `url()` is a broken image at runtime, but it has never
+ * failed a build — Vite prints one line and exits 0, so the breakage ships. A
+ * project that wants that treated as an error opts in here.
+ *
+ * ## Why an environment variable and not a CLI flag
+ *
+ * `vite build --strict-assets` cannot work: cac rejects unknown options unless
+ * the command opts into `allowUnknownOptions()`, and Storybook's commander is
+ * the same. `verbosity.js` already documents the npm bridge that gets around
+ * that — `npm run build --strict-assets` exports `npm_config_strict_assets`
+ * into the script environment — so both triggers are honored here for the same
+ * reason.
+ */
+
+/**
+ * Strictness levels for CSS asset URL resolution.
+ *
+ * @type {{off: string, unresolved: string, all: string}}
+ */
+export const STRICTNESS = {
+  off: 'off',
+  unresolved: 'unresolved',
+  all: 'all',
+};
+
+/** Values that read as "off" regardless of which trigger set them. */
+const OFF_VALUES = ['', '0', 'false', 'off', 'no'];
+
+/** Values that enable failures only for unresolved URLs. */
+const UNRESOLVED_VALUES = ['1', 'true'];
+
+/** Values that also fail when the build repairs a URL. */
+const ALL_VALUES = ['2', 'all'];
+
+/** Values accepted from either strict-assets environment trigger. */
+const ACCEPTED_VALUES = [
+  ...OFF_VALUES.filter(Boolean),
+  ...UNRESOLVED_VALUES,
+  ...ALL_VALUES,
+];
+
+/** Normalize a possibly-unset environment value for comparison. */
+const normalizeValue = (value) =>
+  String(value ?? '')
+    .toLowerCase()
+    .trim();
+
+/**
+ * Resolve how strictly the build should treat CSS asset URL problems.
+ *
+ * `1` fails on URLs nothing could resolve. `2` also fails on URLs the build had
+ * to repair, for projects that want the canonical form written in source rather
+ * than fixed up at build time.
+ *
+ * @param {{EMULSIFY_STRICT_ASSETS?: string, npm_config_strict_assets?: string}} [env] - Environment variables.
+ * @param {(message: string) => void} [warn] - Warning sink.
+ * @returns {string} One of {@link STRICTNESS}.
+ */
+export function resolveAssetStrictness(env = process.env, warn = console.warn) {
+  const direct = normalizeValue(env?.EMULSIFY_STRICT_ASSETS);
+  const bridged = normalizeValue(env?.npm_config_strict_assets);
+  const requested = direct || bridged;
+
+  if (OFF_VALUES.includes(requested)) return STRICTNESS.off;
+  if (UNRESOLVED_VALUES.includes(requested)) return STRICTNESS.unresolved;
+  if (ALL_VALUES.includes(requested)) return STRICTNESS.all;
+
+  const source = direct ? 'EMULSIFY_STRICT_ASSETS' : 'npm_config_strict_assets';
+  warn(
+    `Emulsify: ${source} has unrecognized value "${requested}". ` +
+      `Accepted values: ${ACCEPTED_VALUES.join(', ')}. ` +
+      'Treating it as level 1 (unresolved URLs only).',
+  );
+
+  return STRICTNESS.unresolved;
+}
+
+/**
+ * Count the asset problems that should fail the build at a strictness level.
+ *
+ * @param {{unresolvedAssets?: object[], assetRebases?: object[]}} snapshot - Diagnostics snapshot.
+ * @param {string} strictness - One of {@link STRICTNESS}.
+ * @returns {number} Failing problem count.
+ */
+export function countStrictAssetFailures(snapshot = {}, strictness) {
+  if (strictness === STRICTNESS.off) return 0;
+
+  const unresolved = snapshot.unresolvedAssets?.length || 0;
+  if (strictness !== STRICTNESS.all) return unresolved;
+
+  const repairFailures = (snapshot.assetRebases || []).filter(
+    (entry) => entry.status === 'rebased' || entry.status === 'ambiguous',
+  ).length;
+
+  return unresolved + repairFailures;
+}

package/config/vite/plugins/reporter/vite-logger.js

@@ -18,6 +18,10 @@
  * message passes straight through to Vite's own logger untouched.
  */
 
+import {
+  isAssetAliasPath,
+  splitUrlSuffix,
+} from '../assets/asset-url-rebase.js';
 import { isQuiet, isVerbose } from './verbosity.js';
 
 // Re-exported because the Vite config and the reporter both branch on it, and
@@ -33,6 +37,18 @@ export { isVerbose };
 const UNRESOLVED_ASSET_PATTERN =
   /^(.+?) referenced in (.+?) didn't resolve at build time/;
 
+/**
+ * Matches Vite's browser-compatibility externalization notice.
+ *
+ * One dependency reaching for a Node builtin emits this once per importing file
+ * on every cycle. It says nothing new after the first build, and in a Twig theme
+ * it is never actionable, so the reporter tallies it rather than reprinting it.
+ *
+ * @type {RegExp}
+ */
+const EXTERNALIZED_MODULE_PATTERN =
+  /Module "(.+?)" has been externalized for browser compatibility(?:, imported by "(.+?)")?/;
+
 /**
  * Remove ANSI escape sequences so pattern matching sees plain text.
  *
@@ -91,6 +107,143 @@ function isBareStackTrace(message) {
  */
 const HMR_UPDATE_PATTERN = /(^|\s)hmr update\s/;
 
+/**
+ * Matches the `File:` line Vite appends to a transform failure.
+ *
+ * `buildErrorMessage` composes a dev-server error as the message, `Plugin:` and
+ * `File:`, the source frame, then `err.stack`. Sass is a special case: its
+ * multiline message already contains the source frame, so the body after
+ * `File:` repeats what was printed before the metadata. Other transformers put
+ * their only caret excerpt after `File:`.
+ *
+ * @type {RegExp}
+ */
+const ERROR_FILE_LINE = /^\s*File:\s/;
+
+/**
+ * Matches a JavaScript stack frame with a source location.
+ *
+ * Requiring a `line:column` suffix keeps ordinary diagnostic prose such as
+ * "at least one value is required" from being mistaken for a stack frame.
+ *
+ * @type {RegExp}
+ */
+const STACK_FRAME =
+  /^\s*at\s+(?:(?:async|new)\s+)?(?:.+\s+\()?[^()\s]+:\d+:\d+\)?\s*$/;
+
+/**
+ * Find the last line matching a pattern.
+ *
+ * A diagnostic's own text can contain a `File:`-looking line. Vite's metadata
+ * follows the diagnostic body, so the final match is the useful anchor.
+ *
+ * @param {string[]} lines - Message lines.
+ * @param {RegExp} pattern - Pattern to match.
+ * @returns {number} Matching index, or -1.
+ */
+function findLastLine(lines, pattern) {
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    if (pattern.test(stripAnsi(lines[index]))) return index;
+  }
+
+  return -1;
+}
+
+/**
+ * Normalize one copy of an error body for duplicate comparison.
+ *
+ * Vite prefixes the first copy with `Internal server error:` and Sass's stack
+ * can prefix the repeated copy with `Error:`. Sass also changes indentation
+ * between the two copies, so only leading/trailing whitespace is discarded.
+ *
+ * @param {string[]} lines - Error-body lines.
+ * @returns {string} Normalized body.
+ */
+function normalizeErrorBody(lines) {
+  const normalized = lines
+    .map((line) => stripAnsi(line).trim())
+    .filter(Boolean);
+
+  if (normalized.length > 0) {
+    normalized[0] = normalized[0]
+      .replace(/^Internal server error:\s*/, '')
+      .replace(/^Error:\s*/, '');
+  }
+
+  return normalized.join('\n');
+}
+
+/**
+ * Determine whether Sass's post-`File:` frame repeats its message.
+ *
+ * Vite assigns Sass's multiline message to `error.frame`. Its first rendered
+ * block therefore already contains the excerpt, while the text after `File:`
+ * repeats that same body from the stack. Other transformers put their only
+ * code frame after `File:`, so those frames must be retained.
+ *
+ * @param {string[]} lines - Complete dev-server error.
+ * @param {number} fileLine - Index of Vite's final `File:` metadata line.
+ * @param {number} firstStackFrame - Index of the first real stack frame.
+ * @returns {boolean} TRUE when the post-file body is a Sass duplicate.
+ */
+function hasDuplicateSassFrame(lines, fileLine, firstStackFrame) {
+  const pluginLine = findLastLine(
+    lines.slice(0, fileLine),
+    /^\s*Plugin:\s+vite:css\s*$/,
+  );
+  if (pluginLine === -1) return false;
+
+  const messageBody = normalizeErrorBody(lines.slice(0, pluginLine));
+  const repeatedBody = normalizeErrorBody(
+    lines.slice(
+      fileLine + 1,
+      firstStackFrame === -1 ? lines.length : firstStackFrame,
+    ),
+  );
+
+  return (
+    messageBody.startsWith('[sass]') &&
+    repeatedBody.startsWith('[sass]') &&
+    messageBody === repeatedBody
+  );
+}
+
+/**
+ * Reduce a dev-server error to the part that names the problem.
+ *
+ * One mistyped semicolon in a stylesheet prints around fifty lines: the Sass
+ * error, the same error again out of `err.stack`, and thirty-odd frames inside
+ * `sass.dart.js` that point at the compiler rather than at the stylesheet. The
+ * first block — message, excerpt, caret, import chain, and the file it came
+ * from — is the whole of what a themer can act on. Other transformers keep
+ * their unique source frame; only the JavaScript stack beneath it is removed.
+ *
+ * The stack is only dropped at a recognizable frame. Sass's post-`File:` body
+ * is dropped earlier only when it is demonstrably a duplicate of the message,
+ * so an error shaped differently than expected is not truncated on a guess.
+ *
+ * @param {string} message - Raw error text.
+ * @returns {string} Message without the repeated body and the stack.
+ */
+export function compactDevServerError(message) {
+  const lines = String(message).split('\n');
+  const fileLine = findLastLine(lines, ERROR_FILE_LINE);
+  const stackSearchStart = fileLine === -1 ? 0 : fileLine + 1;
+  const relativeStackFrame = lines
+    .slice(stackSearchStart)
+    .findIndex((line) => STACK_FRAME.test(stripAnsi(line)));
+  const firstFrame =
+    relativeStackFrame === -1 ? -1 : stackSearchStart + relativeStackFrame;
+
+  if (fileLine !== -1 && hasDuplicateSassFrame(lines, fileLine, firstFrame)) {
+    return lines.slice(0, fileLine + 1).join('\n');
+  }
+
+  if (firstFrame > 0) return lines.slice(0, firstFrame).join('\n').trimEnd();
+
+  return String(message);
+}
+
 /**
  * Wrap the Storybook dev server's logger to drop HMR notices.
  *
@@ -109,6 +262,11 @@ const HMR_UPDATE_PATTERN = /(^|\s)hmr update\s/;
  * processes share one pipe, so these interleave with the build's output and are
  * the last thing making one command look like two.
  *
+ * Transform failures are compacted for the same reason. The dev server prints
+ * the error, then repeats it out of `err.stack`, then lists thirty frames
+ * inside `sass.dart.js`; only the first block names anything in the project.
+ * See {@link compactDevServerError}.
+ *
  * The wrapper delegates to whatever logger is already configured rather than
  * replacing it, so Storybook keeps its own prefixes and styling for every other
  * message. Verbose modes pass everything through, because someone who asked for
@@ -141,7 +299,14 @@ export function createDevServerLogger({ baseLogger, verbose } = {}) {
 
     warn: (message, options) => baseLogger.warn(message, options),
     warnOnce: (message, options) => baseLogger.warnOnce(message, options),
-    error: (message, options) => baseLogger.error(message, options),
+
+    error(message, options) {
+      baseLogger.error(
+        passThrough ? message : compactDevServerError(message),
+        options,
+      );
+    },
+
     clearScreen: (type) => baseLogger.clearScreen(type),
     hasErrorLogged: (error) => baseLogger.hasErrorLogged(error),
   };
@@ -165,7 +330,10 @@ export function parseUnresolvedAsset(message) {
     url,
     // Vite reports the URL as its own importer when the referencing stylesheet
     // is not known. Recording that adds nothing, so it is dropped.
-    importer: importer === url ? undefined : importer,
+    // Vite shadows the stylesheet id while resolving CSS URLs. The value after
+    // `referenced in` is therefore usually the URL itself; for fragments it is
+    // the same URL with the fragment removed. Neither identifies an importer.
+    importer: importer === url.split('#')[0] ? undefined : importer,
   };
 }
 
@@ -179,9 +347,39 @@ export function parseUnresolvedAsset(message) {
  * @param {import('vite').Logger} baseLogger - Logger to delegate to.
  * @returns {import('vite').Logger} Wrapped logger.
  */
+/**
+ * Parse Vite's externalization notice into a module and its importer.
+ *
+ * @param {string} message - Raw log message.
+ * @returns {{module: string, importer: string|undefined}|null} Parsed notice.
+ */
+export function parseExternalizedModule(message) {
+  const match = EXTERNALIZED_MODULE_PATTERN.exec(stripAnsi(String(message)));
+  if (!match) return null;
+
+  return { module: match[1], importer: match[2] || undefined };
+}
+
 export function createReporterLogger(collector, baseLogger, { verbose } = {}) {
   const passRawThrough = verbose === undefined ? isVerbose() : verbose;
 
+  /**
+   * Valid aliases deliberately reach Vite as unresolved literals so Core can
+   * apply configured-root resolution after Sass compilation. Their raw Vite
+   * notice is therefore implementation noise even in verbose mode. Missing or
+   * ambiguous aliases remain in the collector and are reported in Core's final
+   * diagnostic summary.
+   *
+   * @param {string} message - Raw log message.
+   * @returns {boolean} TRUE for an unresolved reserved-alias notice.
+   */
+  const isAssetAliasNotice = (message) => {
+    const unresolved = parseUnresolvedAsset(message);
+    if (!unresolved) return false;
+
+    return isAssetAliasPath(splitUrlSuffix(unresolved.url).path);
+  };
+
   /**
    * Record a message if it is one the reporter owns.
    *
@@ -190,10 +388,18 @@ export function createReporterLogger(collector, baseLogger, { verbose } = {}) {
    */
   const capture = (message) => {
     const unresolvedAsset = parseUnresolvedAsset(message);
-    if (!unresolvedAsset) return false;
-
-    collector.recordUnresolvedAsset(unresolvedAsset);
-    return true;
+    if (unresolvedAsset) {
+      collector.recordUnresolvedAsset(unresolvedAsset);
+      return true;
+    }
+
+    const externalized = parseExternalizedModule(message);
+    if (externalized) {
+      collector.recordExternalizedModule?.(externalized);
+      return true;
+    }
+
+    return false;
   };
 
   /**
@@ -230,11 +436,17 @@ export function createReporterLogger(collector, baseLogger, { verbose } = {}) {
     info: (message, options) => baseLogger.info(message, options),
 
     warn(message, options) {
-      if (!capture(message)) baseLogger.warn(message, options);
+      const captured = capture(message);
+      if (!captured || (passRawThrough && !isAssetAliasNotice(message))) {
+        baseLogger.warn(message, options);
+      }
     },
 
     warnOnce(message, options) {
-      if (!capture(message)) baseLogger.warnOnce(message, options);
+      const captured = capture(message);
+      if (!captured || (passRawThrough && !isAssetAliasNotice(message))) {
+        baseLogger.warnOnce(message, options);
+      }
     },
 
     error(message, options) {

package/config/vite/plugins/reporter/watch-mode.js

@@ -27,7 +27,7 @@ const WATCH_FLAGS = ['--watch', '-w'];
  * Determine whether the current process was invoked as a Vite watch build.
  *
  * @param {string[]} [argv] - Process arguments.
- * @returns {boolean} TRUE when a watch flag is present.
+ * @returns {boolean} TRUE when a watch flag enables watch mode.
  */
 export function isWatchInvocation(argv = process.argv) {
   if (!Array.isArray(argv)) return false;
@@ -35,6 +35,10 @@ export function isWatchInvocation(argv = process.argv) {
   return argv.some(
     (arg) =>
       WATCH_FLAGS.includes(arg) ||
-      WATCH_FLAGS.some((flag) => arg.startsWith(`${flag}=`)),
+      WATCH_FLAGS.some(
+        (flag) =>
+          arg.startsWith(`${flag}=`) &&
+          arg.slice(flag.length + 1).toLowerCase() !== 'false',
+      ),
   );
 }