@emulsify/core 4.2.0 → 4.3.0

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

@@ -0,0 +1,237 @@
+/**
+ * @file Sass logger that feeds the Emulsify develop reporter.
+ *
+ * Dart Sass prints a fully formatted warning — message, source excerpt, caret,
+ * and import chain — for every deprecation it encounters, every time it
+ * encounters it. A project with a handful of legacy `$space/2` divisions in a
+ * shared partial can emit several hundred lines per build, because each entry
+ * that imports the partial re-triggers the same warning.
+ *
+ * Supplying a custom logger replaces that output entirely. Rather than calling
+ * `silenceDeprecations`, which hides the warnings and the fact that they exist,
+ * this logger routes each report into the shared diagnostics collector so the
+ * reporter can print one deduplicated summary with a migration hint. The debt
+ * stays visible; only the repetition goes away.
+ *
+ * @see https://sass-lang.com/documentation/js-api/interfaces/logger/
+ */
+
+import { fileURLToPath } from 'node:url';
+
+/**
+ * What each Sass deprecation means and how to resolve it.
+ *
+ * `fix` is the substitution to make, written as `before → after` so the row
+ * reads as an instruction rather than an identifier. A deprecation ID like
+ * `slash-div` tells a themer nothing on its own; `$a/$b → math.div($a, $b)`
+ * tells them exactly what to type.
+ *
+ * `migrator` names the `sass-migrator` migration that rewrites the code
+ * automatically, and is omitted for deprecations that have to be fixed by hand.
+ * The migrator only ships five migrations, so most IDs here have no entry.
+ *
+ * @type {Record<string, {fix: string, migrator?: string}>}
+ * @see https://sass-lang.com/documentation/cli/migrator/
+ */
+export const DEPRECATION_GUIDE = {
+  'slash-div': {
+    fix: '$a/$b → math.div($a, $b)',
+    migrator: 'division',
+  },
+  'global-builtin': {
+    fix: 'map-get() → map.get()',
+    migrator: 'module',
+  },
+  import: {
+    fix: '@import → @use',
+    migrator: 'module',
+  },
+  'color-functions': {
+    fix: 'lighten()/darken() → color.adjust()',
+    migrator: 'color',
+  },
+  'if-function': {
+    fix: 'if() → CSS if()',
+    migrator: 'if',
+  },
+  'color-4-api': { fix: 'color.red($c) → color.channel($c, "red")' },
+  'legacy-js-api': { fix: 'render() → compile()' },
+  'mixed-decls': { fix: 'move declarations above nested rules' },
+  'strict-unary': { fix: '$a -$b → $a - $b' },
+  'abs-percent': { fix: 'abs(10%) → math.abs(10%)' },
+  'duplicate-var-flags': { fix: 'remove the repeated !default or !global' },
+  'null-alpha': { fix: 'rgb($c, null) → rgb($c)' },
+  'feature-exists': { fix: 'remove meta.feature-exists()' },
+  'moz-document': { fix: 'remove @-moz-document' },
+  'bogus-combinators': { fix: 'remove the dangling combinator' },
+  elseif: { fix: '@elseif → @else if' },
+  'call-string': { fix: 'call($name) → call(get-function($name))' },
+  'new-global': { fix: 'declare the variable before assigning it !global' },
+};
+
+/**
+ * Look up the human-readable fix for a deprecation ID.
+ *
+ * @param {string} id - Sass deprecation ID.
+ * @returns {string|undefined} Fix instruction, when one is known.
+ */
+export function deprecationFix(id) {
+  return DEPRECATION_GUIDE[id]?.fix;
+}
+
+/**
+ * Look up the `sass-migrator` migration that resolves a deprecation ID.
+ *
+ * @param {string} id - Sass deprecation ID.
+ * @returns {string|undefined} Migration name, when one exists.
+ */
+export function deprecationMigrator(id) {
+  return DEPRECATION_GUIDE[id]?.migrator;
+}
+
+/**
+ * Convert a Sass span URL into a readable filesystem path.
+ *
+ * Spans carry a `URL` for on-disk stylesheets, but string URLs and custom
+ * importer schemes both appear in practice, so every branch is guarded.
+ *
+ * @param {URL|string|undefined} url - Span URL.
+ * @returns {string|undefined} Filesystem path, or undefined when unavailable.
+ */
+export function spanUrlToPath(url) {
+  if (!url) return undefined;
+
+  const href = typeof url === 'string' ? url : url.href;
+  if (!href) return undefined;
+  if (!href.startsWith('file:')) return href;
+
+  try {
+    return fileURLToPath(href);
+  } catch {
+    return href;
+  }
+}
+
+/**
+ * Read the 1-based line number from a Sass span.
+ *
+ * Sass reports zero-based line numbers; editors and the rest of the Emulsify
+ * tooling are one-based.
+ *
+ * @param {{start?: {line?: number}}|undefined} span - Sass source span.
+ * @returns {number|undefined} 1-based line number, when available.
+ */
+export function spanLineNumber(span) {
+  const line = span?.start?.line;
+  return typeof line === 'number' ? line + 1 : undefined;
+}
+
+/**
+ * Reduce a multi-line Sass message to its first meaningful line.
+ *
+ * @param {string|undefined} message - Raw Sass message.
+ * @returns {string|undefined} Condensed message.
+ */
+export function condenseMessage(message) {
+  if (typeof message !== 'string') return undefined;
+  const [firstLine] = message.split('\n');
+  return firstLine?.trim() || undefined;
+}
+
+/**
+ * Detect Dart Sass's own truncation notice.
+ *
+ * Without `verbose`, Sass prints at most five instances of each deprecation and
+ * then emits `"N repetitive deprecation warnings omitted."` as a warning with no
+ * span attached. That notice is not a problem in the stylesheet — it is Sass
+ * reporting that it hid some. Recording it would put a locationless row in the
+ * summary and, worse, imply the reporter's totals are complete when they are
+ * short by exactly the number Sass suppressed.
+ *
+ * {@link createSassOptions} sets `verbose` so the notice should never appear,
+ * but a project that overrides `preprocessorOptions` could reintroduce it.
+ *
+ * @param {string|undefined} message - Raw Sass message.
+ * @returns {boolean} TRUE when the message is a truncation notice.
+ */
+export function isRepetitionNotice(message) {
+  if (typeof message !== 'string') return false;
+  return /^\s*\d+\s+repetitive\s+deprecation\s+warnings?\s+omitted\b/i.test(
+    message,
+  );
+}
+
+/**
+ * Create a Sass logger that records into a diagnostics collector.
+ *
+ * @param {ReturnType<import('./diagnostics.js').createDiagnosticsCollector>} collector - Shared collector.
+ * @param {{passthrough?: (message: string, options: object) => void}} [options] - Logger options.
+ * @returns {{warn: Function, debug: Function}} Sass logger.
+ */
+export function createSassLogger(collector, { passthrough } = {}) {
+  return {
+    /**
+     * Record a Sass warning instead of printing it.
+     *
+     * @param {string} message - Warning message.
+     * @param {object} [options] - Sass warning metadata.
+     * @returns {void}
+     */
+    warn(message, options = {}) {
+      // Sass counting its own suppressed warnings is not a finding to report.
+      if (isRepetitionNotice(message)) return;
+
+      const file = spanUrlToPath(options.span?.url);
+      const line = spanLineNumber(options.span);
+
+      if (options.deprecation) {
+        collector.recordDeprecation({
+          id: options.deprecationType?.id,
+          file,
+          line,
+        });
+      } else {
+        collector.recordWarning({
+          message: condenseMessage(message),
+          file,
+          line,
+        });
+      }
+
+      // Projects that want the original firehose back can opt in per build.
+      if (typeof passthrough === 'function') {
+        passthrough(message, options);
+      }
+    },
+
+    /**
+     * Discard Sass debug output.
+     *
+     * `@debug` is a authoring aid and has no place in the develop summary.
+     *
+     * @returns {void}
+     */
+    debug() {},
+  };
+}
+
+/**
+ * Build the Sass preprocessor options used by the develop watcher.
+ *
+ * `verbose` and the custom logger have to travel together. Dart Sass caps each
+ * deprecation at five reported instances by default, so a reporter that counts
+ * what the logger receives would silently undercount — a project with 135 real
+ * occurrences would be told it had 85. Turning `verbose` on hands every
+ * occurrence to the logger, which then deduplicates them properly. The console
+ * stays quiet either way, because the logger prints nothing.
+ *
+ * @param {ReturnType<import('./diagnostics.js').createDiagnosticsCollector>} collector - Shared collector.
+ * @param {{passthrough?: (message: string, options: object) => void}} [options] - Logger options.
+ * @returns {{logger: {warn: Function, debug: Function}, verbose: boolean}} Sass options.
+ */
+export function createSassOptions(collector, options = {}) {
+  return {
+    logger: createSassLogger(collector, options),
+    verbose: true,
+  };
+}

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

@@ -0,0 +1,188 @@
+/**
+ * @file Vite logger wrapper for the Emulsify develop reporter.
+ *
+ * Sass warnings reach the reporter through a Sass logger, but Vite emits its
+ * own diagnostics through `config.logger`. The most common of those in an
+ * Emulsify project is the unresolved CSS asset notice:
+ *
+ *   ../images/bg-lines.png referenced in ../images/bg-lines.png didn't resolve
+ *   at build time, it will remain unchanged to be resolved at runtime
+ *
+ * Vite emits one per `url()` it cannot resolve, mid-build, so they land
+ * interleaved with transform progress and Storybook's startup. The wording is
+ * also unhelpful: the "referenced in" file is frequently identical to the URL
+ * itself, and nothing in the sentence says whether this is a problem.
+ *
+ * This wrapper intercepts those and routes them into the shared diagnostics
+ * collector so they surface once, grouped, in the build summary. Every other
+ * message passes straight through to Vite's own logger untouched.
+ */
+
+/**
+ * Matches Vite's unresolved CSS asset notice.
+ *
+ * @type {RegExp}
+ * @see https://github.com/vitejs/vite - `vite:css` url replacer
+ */
+const UNRESOLVED_ASSET_PATTERN =
+  /^(.+?) referenced in (.+?) didn't resolve at build time/;
+
+/**
+ * Remove ANSI escape sequences so pattern matching sees plain text.
+ *
+ * @param {string} value - Possibly styled text.
+ * @returns {string} Plain text.
+ */
+const stripAnsi = (value) =>
+  // eslint-disable-next-line no-control-regex
+  String(value).replace(/\[[0-9;]*m/g, '');
+
+/**
+ * Matches Rolldown's raw failure dump.
+ *
+ * The dump repeats every error up to three times — message, cause, and stack —
+ * and appends a Dart Sass JS trace that points into `sass.dart.js` rather than
+ * anywhere in the project.
+ *
+ * @type {RegExp}
+ */
+const RAW_BUILD_DUMP =
+  /^\s*(?:Build failed with \d+ error|\[plugin [\w:-]+\]|Error: \[sass\]|\[sass\] )/;
+
+/**
+ * Matches a Dart Sass JS stack frame.
+ *
+ * These point into the compiler bundle rather than the project and are noise
+ * wherever they appear, so their presence alone identifies a raw dump.
+ *
+ * @type {RegExp}
+ */
+const DART_SASS_FRAME = /\bsass\.dart\.js:\d+/;
+
+/**
+ * Detect a message that is nothing but JavaScript stack frames.
+ *
+ * Rolldown emits the trailing stack of a failure as its own log call. Those
+ * frames point into `lightningcss`, `vite`, or `sass` internals rather than
+ * anywhere in the project, so a message made only of them carries nothing once
+ * the failure itself has been reported.
+ *
+ * @param {string} message - Plain-text log message.
+ * @returns {boolean} TRUE when every line is a stack frame.
+ */
+function isBareStackTrace(message) {
+  const lines = message.split('\n').filter((line) => line.trim());
+
+  return lines.length > 0 && lines.every((line) => /^\s*at\s+\S/.test(line));
+}
+
+/**
+ * Determine whether the reporter should stand aside and let Vite speak.
+ *
+ * @param {object} [env] - Environment variables.
+ * @returns {boolean} TRUE when raw output should pass through.
+ */
+export function isVerbose(env = process.env) {
+  return Boolean(env.EMULSIFY_VERBOSE) && env.EMULSIFY_VERBOSE !== '0';
+}
+
+/**
+ * Parse Vite's unresolved CSS asset notice.
+ *
+ * @param {string} message - Raw log message.
+ * @returns {{url: string, importer: string|undefined}|undefined} Parsed notice.
+ */
+export function parseUnresolvedAsset(message) {
+  if (typeof message !== 'string') return undefined;
+
+  const match = UNRESOLVED_ASSET_PATTERN.exec(stripAnsi(message).trim());
+  if (!match) return undefined;
+
+  const [, url, importer] = match;
+
+  return {
+    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,
+  };
+}
+
+/**
+ * Wrap a Vite logger so reportable diagnostics are collected instead of printed.
+ *
+ * The wrapper delegates rather than spreading, because `hasWarned` is a mutable
+ * property that Vite reads back after logging; a spread copy would freeze it.
+ *
+ * @param {ReturnType<import('./diagnostics.js').createDiagnosticsCollector>} collector - Shared collector.
+ * @param {import('vite').Logger} baseLogger - Logger to delegate to.
+ * @returns {import('vite').Logger} Wrapped logger.
+ */
+export function createReporterLogger(collector, baseLogger, { verbose } = {}) {
+  const passRawThrough = verbose === undefined ? isVerbose() : verbose;
+
+  /**
+   * Record a message if it is one the reporter owns.
+   *
+   * @param {string} message - Raw log message.
+   * @returns {boolean} TRUE when the message was captured.
+   */
+  const capture = (message) => {
+    const unresolvedAsset = parseUnresolvedAsset(message);
+    if (!unresolvedAsset) return false;
+
+    collector.recordUnresolvedAsset(unresolvedAsset);
+    return true;
+  };
+
+  /**
+   * Determine whether a failure dump has already been reported in table form.
+   *
+   * Output is only ever dropped once the reporter holds the same information
+   * in a readable shape; an error it failed to parse still reaches the user.
+   *
+   * @param {string} message - Raw log message.
+   * @returns {boolean} TRUE when the dump is redundant.
+   */
+  const isRedundantDump = (message) => {
+    if (passRawThrough) return false;
+    if (!collector.hasCapturedBuildErrors?.()) return false;
+
+    const plain = stripAnsi(String(message));
+
+    return (
+      RAW_BUILD_DUMP.test(plain) ||
+      DART_SASS_FRAME.test(plain) ||
+      isBareStackTrace(plain)
+    );
+  };
+
+  return {
+    get hasWarned() {
+      return baseLogger.hasWarned;
+    },
+
+    set hasWarned(value) {
+      baseLogger.hasWarned = value;
+    },
+
+    info: (message, options) => baseLogger.info(message, options),
+
+    warn(message, options) {
+      if (!capture(message)) baseLogger.warn(message, options);
+    },
+
+    warnOnce(message, options) {
+      if (!capture(message)) baseLogger.warnOnce(message, options);
+    },
+
+    error(message, options) {
+      if (isRedundantDump(message)) return;
+      baseLogger.error(message, options);
+    },
+
+    clearScreen: (type) => baseLogger.clearScreen(type),
+
+    hasErrorLogged: (error) => baseLogger.hasErrorLogged(error),
+  };
+}

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

@@ -0,0 +1,40 @@
+/**
+ * @file Watch-invocation detection for the Emulsify develop reporter.
+ *
+ * The reporter and its quiet Sass logger should only take over output for the
+ * long-running watcher that `npm run develop` starts. Every other command that
+ * loads this Vite config — `npm run build`, `storybook build`, `storybook dev`,
+ * and the release fixture verifications — must keep its current output exactly
+ * as it is today.
+ *
+ * Vite resolves `command: 'build'` for both `vite build` and
+ * `vite build --watch`, so the resolved config cannot distinguish them at the
+ * point where `css.preprocessorOptions` has to be decided. The CLI flag is the
+ * only signal available that early, so it is read directly. The plugin
+ * independently confirms the decision against `config.build.watch` once the
+ * config is resolved, which covers projects that enable watch mode through
+ * their own config patch rather than the flag.
+ */
+
+/**
+ * Flags that put the Vite CLI into watch mode.
+ *
+ * @type {string[]}
+ */
+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.
+ */
+export function isWatchInvocation(argv = process.argv) {
+  if (!Array.isArray(argv)) return false;
+
+  return argv.some(
+    (arg) =>
+      WATCH_FLAGS.includes(arg) ||
+      WATCH_FLAGS.some((flag) => arg.startsWith(`${flag}=`)),
+  );
+}

package/config/vite/plugins/{twig-extension-installers.js → twig/extension-installers.js}

@@ -2,7 +2,7 @@
  * @file Virtual Twig.js extension installer module for Storybook.
  */
 
-import { generateTwigExtensionInstallersModule } from '../twig-extensions.js';
+import { generateTwigExtensionInstallersModule } from './extensions.js';
 
 export const VIRTUAL_TWIG_EXTENSION_INSTALLERS_ID =
   'virtual:emulsify-twig-extension-installers';

package/config/vite/{twig-extensions.js → plugins/twig/extensions.js}

@@ -60,7 +60,7 @@ function normalizeInstaller(moduleValue) {
  * @param {object} [env={}] - Normalized Emulsify environment or Twig options.
  * @returns {object} The provided Twig.js instance.
  */
-export function registerConfiguredTwigExtensions(twig, env = {}) {
+export function installProjectTwigExtensions(twig, env = {}) {
   if (shouldRegisterDrupalTwigFilters(env)) {
     const installer = normalizeInstaller(require('twig-drupal-filters'));
     if (installer) {
@@ -98,7 +98,7 @@ const installers = [${installerNames}].filter(
 
 export const twigExtensionInstallers = installers;
 
-export function registerConfiguredTwigExtensions(Twig) {
+export function installProjectTwigExtensions(Twig) {
   for (const installer of installers) {
     installer(Twig);
   }