@emulsify/core 4.2.1 → 4.3.0

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

@@ -0,0 +1,284 @@
+/**
+ * @file Build error extraction for the Emulsify develop reporter.
+ *
+ * Rolldown reports a failed build as a single wrapper error whose message is
+ * `Build failed with N errors:` followed by every error rendered as text. Read
+ * naively, the reporter shows one error with a message that names a count and
+ * nothing else.
+ *
+ * The individual errors are reachable through the wrapper's `errors` property,
+ * and each one carries a `cause` chain that ends at the original Sass
+ * exception. That exception is fully structured — `span.url`, `span.start.line`
+ * and `span.text` give the file, the line, and the offending statement
+ * verbatim — so nothing has to be scraped out of formatted output.
+ *
+ * @see https://github.com/rolldown/rolldown - aggregateBindingErrorsIntoJsError
+ */
+
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Matches Sass's "missing import" failure.
+ *
+ * @type {RegExp}
+ */
+const MISSING_IMPORT = /Can't find stylesheet to import/i;
+
+/**
+ * Captures the specifier from a `@use`, `@forward`, or `@import` statement.
+ *
+ * @type {RegExp}
+ */
+const IMPORT_SPECIFIER = /@(?:use|forward|import)\s+['"]([^'"]+)['"]/;
+
+/**
+ * Captures a line number and its source from a Sass code frame.
+ *
+ * Used only when the structured span is unavailable.
+ *
+ * @type {RegExp}
+ */
+const FRAME_LINE = /^\s*(\d+)\s*│\s?(.*)$/m;
+
+/**
+ * Maximum depth walked through `cause` chains.
+ *
+ * @type {number}
+ */
+const MAX_CAUSE_DEPTH = 10;
+
+/**
+ * Captures the minifier name Vite prefixes onto a CSS minification failure.
+ *
+ * Both the lightningcss and esbuild paths tag the message this way before
+ * rethrowing, and both attach `loc` and `frame` alongside it.
+ *
+ * @type {RegExp}
+ */
+const MINIFIER_PREFIX = /^\[((?:lightningcss|esbuild css) minify)\]\s*/;
+
+/**
+ * Captures one numbered row of a Vite code frame.
+ *
+ * @type {RegExp}
+ */
+const FRAME_ROW = /^\s*(\d+)\s*\|\s?(.*)$/;
+
+/**
+ * Captures the caret row that follows the offending row of a code frame.
+ *
+ * @type {RegExp}
+ */
+const FRAME_CARET = /^\s*\|\s?(\s*)\^/;
+
+/**
+ * Parse a CSS minifier syntax failure.
+ *
+ * These are unlike every other error the reporter handles: the minifier runs
+ * on the concatenated bundle, so `loc.line` is a line of generated CSS and
+ * points at no file anyone wrote. What is salvageable is the offending
+ * declaration itself, which is enough to search the project for.
+ *
+ * @param {object} error - Individual build error.
+ * @returns {{
+ *   minifier: string,
+ *   message: string,
+ *   bundleLine: number|undefined,
+ *   declaration: string|undefined,
+ *   caretColumn: number|undefined
+ * }|undefined} Parsed syntax error.
+ */
+export function parseCssSyntaxError(error) {
+  const rawMessage = String(error?.message || '');
+  const prefix = MINIFIER_PREFIX.exec(rawMessage);
+  if (!prefix) return undefined;
+
+  const [firstLine] = rawMessage.replace(MINIFIER_PREFIX, '').split('\n');
+  const parsed = {
+    minifier: prefix[1],
+    message: firstLine.trim(),
+    bundleLine:
+      typeof error?.loc?.line === 'number' ? error.loc.line : undefined,
+    declaration: undefined,
+    caretColumn: undefined,
+  };
+
+  const rows = String(error?.frame || '').split('\n');
+
+  for (let index = 0; index < rows.length; index += 1) {
+    const row = FRAME_ROW.exec(rows[index]);
+    if (!row) continue;
+
+    // Without a bundle line, the row carrying a caret beneath it is the one.
+    const isOffending =
+      parsed.bundleLine == null
+        ? FRAME_CARET.test(rows[index + 1] || '')
+        : Number(row[1]) === parsed.bundleLine;
+    if (!isOffending) continue;
+
+    const leading = row[2].length - row[2].trimStart().length;
+    parsed.declaration = row[2].trim();
+
+    const caret = FRAME_CARET.exec(rows[index + 1] || '');
+    if (caret) {
+      // Re-base the caret against the trimmed declaration.
+      parsed.caretColumn = Math.max(0, caret[1].length - leading);
+    }
+
+    break;
+  }
+
+  return parsed;
+}
+
+/**
+ * Flatten a rolldown build error into the individual errors it wraps.
+ *
+ * @param {Error & {errors?: Array<object>}} error - Build error.
+ * @returns {Array<object>} Individual errors.
+ */
+export function flattenBuildErrors(error) {
+  if (!error) return [];
+
+  const nested = error.errors;
+  if (!Array.isArray(nested) || nested.length === 0) return [error];
+
+  return nested.flatMap((entry) => flattenBuildErrors(entry));
+}
+
+/**
+ * Walk an error's `cause` chain looking for an entry with a Sass span.
+ *
+ * @param {object} error - Error to inspect.
+ * @returns {object|undefined} Error carrying a Sass span.
+ */
+function findSpanned(error) {
+  let current = error;
+
+  for (let depth = 0; current && depth < MAX_CAUSE_DEPTH; depth += 1) {
+    if (current.span?.url || current.span?.start) return current;
+    current = current.cause;
+  }
+
+  return undefined;
+}
+
+/**
+ * Convert a Sass span URL to a filesystem path.
+ *
+ * @param {URL|string|undefined} url - Span URL.
+ * @returns {string|undefined} Filesystem path.
+ */
+function spanPath(url) {
+  if (!url) return undefined;
+  const href = typeof url === 'string' ? url : url.href;
+  if (!href?.startsWith('file:')) return href || undefined;
+
+  try {
+    return fileURLToPath(href);
+  } catch {
+    return href;
+  }
+}
+
+/**
+ * Reduce a message to its first line, without the plugin prefix.
+ *
+ * @param {string|undefined} message - Raw message.
+ * @returns {string} Condensed message.
+ */
+function condense(message) {
+  const [first] = String(message || '').split('\n');
+  return first.replace(/^\[[^\]]+\]\s*/, '').trim();
+}
+
+/**
+ * Describe one build error in the terms the reporter renders.
+ *
+ * Prefers the structured Sass span and falls back to the rendered code frame,
+ * which is the only source of a line number when a plugin re-throws without
+ * preserving the original exception.
+ *
+ * @param {object} error - Individual build error.
+ * @returns {{
+ *   message: string,
+ *   file: string|undefined,
+ *   line: number|undefined,
+ *   statement: string|undefined,
+ *   specifier: string|undefined,
+ *   isMissingImport: boolean
+ * }} Description.
+ */
+export function describeBuildError(error) {
+  const spanned = findSpanned(error);
+  const message = condense(spanned?.message || error?.message);
+
+  let file = spanPath(spanned?.span?.url);
+  let line =
+    typeof spanned?.span?.start?.line === 'number'
+      ? spanned.span.start.line + 1
+      : undefined;
+  let statement = spanned?.span?.text?.trim();
+
+  if (!file) file = error?.loc?.file || error?.id || undefined;
+  if (line == null && typeof error?.loc?.line === 'number') {
+    line = error.loc.line;
+  }
+
+  if (!statement && error?.frame) {
+    const framed = FRAME_LINE.exec(error.frame);
+    if (framed) {
+      statement = framed[2].trim();
+      if (line == null) line = Number(framed[1]);
+    }
+  }
+
+  return {
+    message,
+    file,
+    line,
+    statement,
+    specifier: statement ? IMPORT_SPECIFIER.exec(statement)?.[1] : undefined,
+    isMissingImport: MISSING_IMPORT.test(message),
+  };
+}
+
+/**
+ * Split a build failure into missing imports and everything else.
+ *
+ * Missing imports get their own table because they share a shape — a file, a
+ * 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.
+ * @returns {{
+ *   importErrors: Array<object>,
+ *   syntaxErrors: Array<object>,
+ *   otherErrors: Array<object>
+ * }} Classified errors.
+ */
+export function classifyBuildError(error) {
+  const importErrors = [];
+  const syntaxErrors = [];
+  const otherErrors = [];
+
+  for (const entry of flattenBuildErrors(error)) {
+    const syntaxError = parseCssSyntaxError(entry);
+    if (syntaxError) {
+      syntaxErrors.push(syntaxError);
+      continue;
+    }
+
+    const described = describeBuildError(entry);
+
+    // A missing import with no specifier cannot be tabulated, so it falls
+    // through to the general error list rather than showing a blank row.
+    if (described.isMissingImport && described.specifier) {
+      importErrors.push(described);
+    } else {
+      otherErrors.push(described);
+    }
+  }
+
+  return { importErrors, syntaxErrors, otherErrors };
+}

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

@@ -0,0 +1,366 @@
+/**
+ * @file Diagnostic collection for the Emulsify develop reporter.
+ *
+ * Vite, Sass, and Rollup each report problems on their own schedule and in
+ * their own format. A single build cycle can emit the same Sass deprecation
+ * dozens of times, once per entry that transitively imports the offending
+ * partial, which is what makes the default `npm run develop` output unreadable.
+ *
+ * This module collects those reports into one per-cycle model that counts
+ * repeats instead of reprinting them. Deprecations are bucketed by deprecation
+ * ID, then by source location within that ID, so the reporter can say
+ * "slash-div, 20 occurrences across 1 file" rather than emitting 20 stack
+ * traces. Errors and plain warnings are deduplicated on the same key so a
+ * failure surfaced by two channels only reads as one problem.
+ */
+
+const UNKNOWN_DEPRECATION_ID = 'unknown';
+
+/**
+ * Build the deduplication key for a single reported source location.
+ *
+ * @param {string|undefined} file - Source file path, when known.
+ * @param {number|undefined} line - 1-based line number, when known.
+ * @returns {string} Stable location key.
+ */
+const locationKey = (file, line) =>
+  `${file || '<unknown>'}:${line == null ? '?' : line}`;
+
+/**
+ * Build the deduplication key for an error or plain warning.
+ *
+ * @param {{message?: string, file?: string, line?: number}} entry - Reported entry.
+ * @returns {string} Stable entry key.
+ */
+const entryKey = (entry) =>
+  `${locationKey(entry.file, entry.line)}|${entry.message || ''}`;
+
+/**
+ * Record one occurrence against a location map, incrementing when repeated.
+ *
+ * @param {Map<string, {file: string|undefined, line: number|undefined, count: number}>} locations - Location map.
+ * @param {string|undefined} file - Source file path.
+ * @param {number|undefined} line - 1-based line number.
+ * @returns {void}
+ */
+const tallyLocation = (locations, file, line) => {
+  const key = locationKey(file, line);
+  const existing = locations.get(key);
+
+  if (existing) {
+    existing.count += 1;
+    return;
+  }
+
+  locations.set(key, { file, line, count: 1 });
+};
+
+/**
+ * Sort locations by descending occurrence count, then by path for stability.
+ *
+ * @param {{file: string|undefined, line: number|undefined, count: number}} a - First location.
+ * @param {{file: string|undefined, line: number|undefined, count: number}} b - Second location.
+ * @returns {number} Comparator result.
+ */
+const byCountThenPath = (a, b) =>
+  b.count - a.count ||
+  locationKey(a.file, a.line).localeCompare(locationKey(b.file, b.line));
+
+/**
+ * Invert the deprecation buckets into a per-file worklist.
+ *
+ * The collector groups by deprecation ID because that is how Sass reports, but
+ * fixing the debt is a per-file activity: you open one partial and change the
+ * handful of lines inside it. This projection produces that view — each file
+ * with the offending lines beneath it — without disturbing the ID-keyed model
+ * the totals are computed from.
+ *
+ * Within a file the same deprecation is collapsed into one entry carrying every
+ * affected line. Ten `slash-div` hits across ten lines of one partial is one
+ * edit to make, not ten findings to read.
+ *
+ * @param {Array<{id: string, locations: Array<{file: string|undefined, line: number|undefined, count: number}>}>} deprecationList - ID-keyed buckets.
+ * @returns {Array<{file: string, occurrences: number, entries: Array<{id: string, count: number, lines: number[]}>}>} File-keyed worklist.
+ */
+const groupDeprecationsByFile = (deprecationList) => {
+  /** @type {Map<string, {file: string, occurrences: number, entries: Map<string, object>}>} */
+  const files = new Map();
+
+  for (const bucket of deprecationList) {
+    for (const location of bucket.locations) {
+      // A location with no file cannot be opened, so it has no place in a
+      // worklist. Those still count toward the headline totals.
+      if (!location.file) continue;
+
+      let group = files.get(location.file);
+      if (!group) {
+        group = { file: location.file, occurrences: 0, entries: new Map() };
+        files.set(location.file, group);
+      }
+
+      let entry = group.entries.get(bucket.id);
+      if (!entry) {
+        entry = { id: bucket.id, count: 0, lines: [] };
+        group.entries.set(bucket.id, entry);
+      }
+
+      group.occurrences += location.count;
+      entry.count += location.count;
+      if (location.line != null && !entry.lines.includes(location.line)) {
+        entry.lines.push(location.line);
+      }
+    }
+  }
+
+  return [...files.values()]
+    .map((group) => ({
+      file: group.file,
+      occurrences: group.occurrences,
+      entries: [...group.entries.values()]
+        .map((entry) => ({
+          ...entry,
+          lines: [...entry.lines].sort((a, b) => a - b),
+        }))
+        .sort((a, b) => b.count - a.count || a.id.localeCompare(b.id)),
+    }))
+    .sort(
+      (a, b) => b.occurrences - a.occurrences || a.file.localeCompare(b.file),
+    );
+};
+
+/**
+ * Create a per-cycle diagnostic collector.
+ *
+ * The collector is intentionally synchronous and process-local. The Sass logger
+ * and the reporter plugin both run inside the same Vite process, so they can
+ * share one instance directly without any cross-process coordination.
+ *
+ * @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,
+ *   recordUnresolvedAsset: (entry: {url?: string, importer?: string}) => void,
+ *   recordImportError: (entry: {file?: string, line?: number, specifier?: string}) => void,
+ *   recordSyntaxError: (entry: {minifier?: string, message?: string, declaration?: string}) => void,
+ *   hasCapturedBuildErrors: () => boolean,
+ *   snapshot: () => {
+ *     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}>,
+ *     importErrors: Array<{file: string|undefined, line: number|undefined, specifier: string, 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}>,
+ *     deprecationTotal: number,
+ *     deprecationFileCount: number,
+ *     hasProblems: boolean
+ *   },
+ *   reset: () => void
+ * }} Diagnostic collector.
+ */
+export function createDiagnosticsCollector() {
+  /** @type {Map<string, {id: string, occurrences: number, locations: Map<string, object>}>} */
+  let deprecations = new Map();
+  /** @type {Map<string, object>} */
+  let warnings = new Map();
+  /** @type {Map<string, object>} */
+  let errors = new Map();
+  /** @type {Map<string, {url: string, importer: string|undefined, count: number}>} */
+  let unresolvedAssets = new Map();
+  /** @type {Map<string, object>} */
+  let importErrors = new Map();
+  /** @type {Map<string, object>} */
+  let syntaxErrors = new Map();
+
+  /**
+   * Record one deprecation occurrence.
+   *
+   * @param {{id?: string, file?: string, line?: number}} entry - Deprecation details.
+   * @returns {void}
+   */
+  const recordDeprecation = ({ id, file, line } = {}) => {
+    const deprecationId = id || UNKNOWN_DEPRECATION_ID;
+    let bucket = deprecations.get(deprecationId);
+
+    if (!bucket) {
+      bucket = { id: deprecationId, occurrences: 0, locations: new Map() };
+      deprecations.set(deprecationId, bucket);
+    }
+
+    bucket.occurrences += 1;
+    tallyLocation(bucket.locations, file, line);
+  };
+
+  /**
+   * Record one entry against a deduplicating map.
+   *
+   * @param {Map<string, object>} target - Destination map.
+   * @param {{message?: string, file?: string, line?: number}} entry - Entry details.
+   * @returns {void}
+   */
+  const recordEntry = (target, entry = {}) => {
+    const key = entryKey(entry);
+    const existing = target.get(key);
+
+    if (existing) {
+      existing.count += 1;
+      return;
+    }
+
+    target.set(key, { ...entry, count: 1 });
+  };
+
+  return {
+    recordDeprecation,
+
+    recordWarning: (entry) => recordEntry(warnings, entry),
+
+    recordError: (entry) => recordEntry(errors, entry),
+
+    /**
+     * Record one Sass import that could not be resolved.
+     *
+     * Keyed by the importing site and the specifier, because the same missing
+     * partial reported through two entrypoints is one thing to fix.
+     *
+     * @param {{file?: string, line?: number, specifier?: string, statement?: string}} entry - Import error.
+     * @returns {void}
+     */
+    recordImportError(entry = {}) {
+      if (!entry.specifier) return;
+
+      const key = `${entry.file || '?'}:${entry.line ?? '?'}|${entry.specifier}`;
+      const existing = importErrors.get(key);
+
+      if (existing) {
+        existing.count += 1;
+        return;
+      }
+
+      importErrors.set(key, { ...entry, count: 1 });
+    },
+
+    /**
+     * Record one CSS minifier syntax failure.
+     *
+     * Keyed by the offending declaration, since the same broken rule reached
+     * through several entrypoints is one thing to fix.
+     *
+     * @param {{minifier?: string, message?: string, declaration?: string}} entry - Syntax error.
+     * @returns {void}
+     */
+    recordSyntaxError(entry = {}) {
+      if (!entry.message) return;
+
+      const key = `${entry.declaration || ''}|${entry.message}`;
+      const existing = syntaxErrors.get(key);
+
+      if (existing) {
+        existing.count += 1;
+        return;
+      }
+
+      syntaxErrors.set(key, { ...entry, count: 1 });
+    },
+
+    /**
+     * 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.
+     *
+     * @param {{url?: string, importer?: string}} entry - Unresolved asset.
+     * @returns {void}
+     */
+    recordUnresolvedAsset({ url, importer } = {}) {
+      if (!url) return;
+
+      const existing = unresolvedAssets.get(url);
+      if (existing) {
+        existing.count += 1;
+        existing.importer = existing.importer || importer;
+        return;
+      }
+
+      unresolvedAssets.set(url, { url, importer, count: 1 });
+    },
+
+    snapshot() {
+      const deprecationList = [...deprecations.values()]
+        .map((bucket) => ({
+          id: bucket.id,
+          occurrences: bucket.occurrences,
+          locations: [...bucket.locations.values()].sort(byCountThenPath),
+        }))
+        .sort(
+          (a, b) => b.occurrences - a.occurrences || a.id.localeCompare(b.id),
+        );
+
+      const distinctFiles = new Set();
+      for (const bucket of deprecationList) {
+        for (const location of bucket.locations) {
+          if (location.file) distinctFiles.add(location.file);
+        }
+      }
+
+      const errorList = [...errors.values()];
+      const warningList = [...warnings.values()];
+      const unresolvedAssetList = [...unresolvedAssets.values()].sort(
+        (a, b) => b.count - a.count || a.url.localeCompare(b.url),
+      );
+
+      const importErrorList = [...importErrors.values()].sort(
+        (a, b) =>
+          String(a.file).localeCompare(String(b.file)) ||
+          (a.line ?? 0) - (b.line ?? 0),
+      );
+
+      return {
+        deprecations: deprecationList,
+        deprecationsByFile: groupDeprecationsByFile(deprecationList),
+        unresolvedAssets: unresolvedAssetList,
+        importErrors: importErrorList,
+        syntaxErrors: [...syntaxErrors.values()],
+        warnings: warningList,
+        errors: errorList,
+        deprecationTotal: deprecationList.reduce(
+          (total, bucket) => total + bucket.occurrences,
+          0,
+        ),
+        deprecationFileCount: distinctFiles.size,
+        hasProblems:
+          errorList.length > 0 ||
+          warningList.length > 0 ||
+          deprecationList.length > 0 ||
+          unresolvedAssetList.length > 0 ||
+          importErrorList.length > 0 ||
+          syntaxErrors.size > 0,
+      };
+    },
+
+    /**
+     * Whether any build error has been captured this cycle.
+     *
+     * The logger consults this before swallowing Rolldown's raw error dump, so
+     * output is only suppressed once the reporter has something to show in its
+     * place.
+     *
+     * Deliberately covers ordinary errors as well as missing imports. Scoping
+     * it to imports alone meant a failure of any other kind — an undefined
+     * mixin, say — was reported by the summary *and* dumped raw, so the one
+     * error appeared twice.
+     *
+     * @returns {boolean} TRUE when any build error was captured.
+     */
+    hasCapturedBuildErrors: () =>
+      importErrors.size > 0 || errors.size > 0 || syntaxErrors.size > 0,
+
+    reset() {
+      deprecations = new Map();
+      warnings = new Map();
+      errors = new Map();
+      unresolvedAssets = new Map();
+      importErrors = new Map();
+      syntaxErrors = new Map();
+    },
+  };
+}