@emulsify/core 4.2.1 → 4.3.0

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

@@ -0,0 +1,199 @@
+/**
+ * @file Presentation helpers for the Emulsify develop reporter.
+ *
+ * `npm run develop` runs Vite and Storybook under `concurrently`, which means
+ * this process writes to a pipe rather than a terminal. Two consequences shape
+ * everything here:
+ *
+ *  1. Cursor control is unavailable. Anything that rewrites a line in place
+ *     degrades into concatenated garbage — that is the cause of the
+ *     `pages.scssDeprecation Warning` collisions in the default output. Every
+ *     helper below produces complete, append-only lines.
+ *  2. Color is auto-disabled by Node when the stream is not a TTY. Since the
+ *     pipe is an implementation detail of the task runner rather than a signal
+ *     that the human cannot see color, color support is resolved explicitly
+ *     from the environment and applied with stream validation turned off.
+ */
+
+import { styleText } from 'node:util';
+
+/**
+ * Human-facing names for platforms whose casing is not a simple capitalization.
+ *
+ * @type {Record<string, string>}
+ */
+const PLATFORM_LABELS = {
+  drupal: 'Drupal',
+  wordpress: 'WordPress',
+  none: 'none',
+};
+
+/**
+ * Status glyphs. Deliberately ASCII-adjacent so they survive any terminal font.
+ *
+ * @type {Record<string, string>}
+ */
+export const SYMBOLS = {
+  ok: '\u2713',
+  error: '\u2717',
+  warning: '!',
+  change: '~',
+};
+
+/**
+ * Decide whether ANSI color should be emitted.
+ *
+ * Honors the `NO_COLOR` and `FORCE_COLOR` conventions before falling back to
+ * TTY detection, so piping through `concurrently` does not silently strip the
+ * formatting that makes the summary scannable.
+ *
+ * @param {{NO_COLOR?: string, FORCE_COLOR?: string}} [env] - Environment variables.
+ * @param {{isTTY?: boolean}} [stream] - Destination stream.
+ * @returns {boolean} TRUE when color should be emitted.
+ * @see https://no-color.org/
+ */
+export function supportsColor(env = process.env, stream = process.stdout) {
+  if (env.NO_COLOR) return false;
+  if (env.FORCE_COLOR !== undefined) return env.FORCE_COLOR !== '0';
+  return Boolean(stream?.isTTY);
+}
+
+/**
+ * Decide whether block-drawing characters will render correctly.
+ *
+ * The banner wordmark is built from half-block glyphs. On a terminal without a
+ * UTF-8 locale those degrade into replacement characters, which looks broken
+ * rather than branded, so the reporter falls back to plain text instead.
+ *
+ * Windows consoles are excluded unless running under Windows Terminal or the
+ * VS Code integrated terminal, which are the two that handle these glyphs
+ * reliably.
+ *
+ * @param {object} [env] - Environment variables.
+ * @param {string} [platform] - Node platform identifier.
+ * @returns {boolean} TRUE when block glyphs are safe to emit.
+ */
+export function supportsUnicode(
+  env = process.env,
+  platform = process.platform,
+) {
+  if (env.EMULSIFY_NO_UNICODE) return false;
+
+  if (platform === 'win32') {
+    return Boolean(env.WT_SESSION) || env.TERM_PROGRAM === 'vscode';
+  }
+
+  if (env.TERM === 'linux' || env.TERM === 'dumb') return false;
+
+  const locale = env.LC_ALL || env.LC_CTYPE || env.LANG || '';
+  return /UTF-?8$/i.test(locale);
+}
+
+/**
+ * Create a styling function that respects the resolved color support.
+ *
+ * @param {boolean} enabled - Whether color is enabled.
+ * @returns {(format: string|string[], text: string) => string} Styling function.
+ */
+export function createStyler(enabled) {
+  return (format, text) => {
+    if (!enabled || !format) return text;
+
+    try {
+      return styleText(format, text, { validateStream: false });
+    } catch {
+      // An unrecognized format name should never break a build.
+      return text;
+    }
+  };
+}
+
+/**
+ * Render a platform identifier as a display label.
+ *
+ * @param {string|undefined} platform - Platform identifier.
+ * @returns {string} Display label.
+ */
+export function platformLabel(platform) {
+  if (!platform) return 'none';
+  const normalized = String(platform).toLowerCase();
+
+  return (
+    PLATFORM_LABELS[normalized] ||
+    normalized.charAt(0).toUpperCase() + normalized.slice(1)
+  );
+}
+
+/**
+ * Format a duration for display.
+ *
+ * @param {number} milliseconds - Elapsed milliseconds.
+ * @returns {string} Formatted duration.
+ */
+export function formatDuration(milliseconds) {
+  if (!Number.isFinite(milliseconds) || milliseconds < 0) return '0ms';
+  if (milliseconds < 1000) return `${Math.round(milliseconds)}ms`;
+  return `${(milliseconds / 1000).toFixed(2)}s`;
+}
+
+/**
+ * Format a wall-clock timestamp for rebuild lines.
+ *
+ * @param {Date} [date] - Date to format.
+ * @returns {string} `HH:MM:SS` timestamp.
+ */
+export function formatClockTime(date = new Date()) {
+  const pad = (value) => String(value).padStart(2, '0');
+  return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+
+/**
+ * Shorten an absolute path for display relative to the project root.
+ *
+ * Paths outside the project — most often inside `node_modules` — keep only
+ * their trailing segments so the line stays readable.
+ *
+ * @param {string|undefined} filePath - Path to shorten.
+ * @param {string} [projectDir] - Project root.
+ * @returns {string} Display path.
+ */
+export function displayPath(filePath, projectDir) {
+  if (!filePath) return '<unknown>';
+
+  const normalized = filePath.split('\\').join('/');
+  const root = projectDir
+    ? projectDir.split('\\').join('/').replace(/\/$/, '')
+    : '';
+
+  if (root && normalized.startsWith(`${root}/`)) {
+    return normalized.slice(root.length + 1);
+  }
+
+  const segments = normalized.split('/');
+  return segments.length > 3 ? segments.slice(-3).join('/') : normalized;
+}
+
+/**
+ * Append a line reference to a display path when the line is known.
+ *
+ * @param {string|undefined} filePath - Path to render.
+ * @param {number|undefined} line - 1-based line number.
+ * @param {string} [projectDir] - Project root.
+ * @returns {string} Path with optional line suffix.
+ */
+export function displayLocation(filePath, line, projectDir) {
+  const base = displayPath(filePath, projectDir);
+  return line == null ? base : `${base}:${line}`;
+}
+
+/**
+ * Pluralize a noun against a count.
+ *
+ * @param {number} count - Item count.
+ * @param {string} singular - Singular noun.
+ * @param {string} [plural] - Explicit plural form.
+ * @returns {string} Count and correctly inflected noun.
+ */
+export function pluralize(count, singular, plural = `${singular}s`) {
+  return `${count} ${count === 1 ? singular : plural}`;
+}

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

@@ -0,0 +1,308 @@
+/**
+ * @file Develop reporter plugin for Emulsify.
+ *
+ * Replaces the interleaved Vite/Sass output of `npm run develop` with a short
+ * banner, one summary per build cycle, and a single line per rebuild.
+ *
+ * ## Why this plugin is scoped so narrowly
+ *
+ * `makePlugins()` is consumed twice during `npm run develop`: once by the Vite
+ * watcher, and once by Storybook, whose `viteFinal` spreads the shared plugin
+ * array into its own config. A reporter that printed unconditionally would emit
+ * its banner from both processes.
+ *
+ * Two guards prevent that:
+ *
+ *  - `apply: 'build'` excludes Storybook's dev server, which resolves with
+ *    `command: 'serve'`. This mirrors the existing guard on the component
+ *    mirror plugin.
+ *  - A `config.build.watch` check excludes `storybook build`, `npm run build`,
+ *    and every fixture verification, all of which run a one-shot production
+ *    build where `--watch` is absent. Those commands keep their current output
+ *    byte for byte.
+ *
+ * The net effect is that the reporter only speaks for the long-running watcher
+ * started by `develop`, and Storybook keeps printing its own ready box.
+ */
+
+import { join, relative } from 'node:path';
+
+import { existsSync } from 'node:fs';
+
+import {
+  buildAssetRows,
+  buildImportRows,
+  createAssetResolver,
+  findLikelySource,
+  sharedMissingDirectory,
+} from './asset-resolver.js';
+import { classifyBuildError } from './build-errors.js';
+import { renderBanner, renderRebuild, renderSummary } from './render.js';
+import { createStyler, supportsColor, supportsUnicode } from './format.js';
+import { resolvePackageVersion } from '../../utils/package-version.js';
+
+/**
+ * Build the stylesheet glob handed to `sass-migrator`.
+ *
+ * The migrator takes entrypoints and the docs recommend passing every
+ * stylesheet in the package, so a glob rooted at the project's source
+ * directory is both valid and copy-pasteable. Falling back to `src` keeps the
+ * command sensible when the source directory cannot be resolved.
+ *
+ * @param {{projectDir?: string, srcDir?: string}} env - Project environment.
+ * @returns {string} Glob relative to the project root.
+ */
+export function resolveSourceGlob({ projectDir, srcDir } = {}) {
+  if (!projectDir || !srcDir) return 'src/**/*.scss';
+
+  const relativeSrc = relative(projectDir, srcDir).split('\\').join('/');
+  if (!relativeSrc || relativeSrc.startsWith('..')) return 'src/**/*.scss';
+
+  return `${relativeSrc}/**/*.scss`;
+}
+
+/**
+ * Count the entries in a resolved Rollup input option.
+ *
+ * @param {string|string[]|Record<string, string>|undefined} input - Rollup input.
+ * @returns {number|undefined} Entry count, when determinable.
+ */
+export function countEntries(input) {
+  if (!input) return undefined;
+  if (typeof input === 'string') return 1;
+  if (Array.isArray(input)) return input.length;
+  if (typeof input === 'object') return Object.keys(input).length;
+  return undefined;
+}
+
+/**
+ * Create the Emulsify develop reporter plugin.
+ *
+ * @param {{
+ *   env: {projectDir?: string, platform?: string},
+ *   diagnostics: ReturnType<import('./diagnostics.js').createDiagnosticsCollector>,
+ *   write?: (line: string) => void,
+ *   now?: () => number,
+ *   clock?: () => Date,
+ *   colorEnabled?: boolean,
+ *   version?: string
+ * }} options - Plugin options.
+ * @returns {import('vite').PluginOption} Develop reporter plugin.
+ */
+export function developReporterPlugin({
+  env = {},
+  diagnostics,
+  write = (line) => process.stdout.write(`${line}\n`),
+  now = () => Date.now(),
+  clock = () => new Date(),
+  colorEnabled,
+  unicodeEnabled,
+  version,
+} = {}) {
+  const styler = createStyler(
+    colorEnabled === undefined ? supportsColor() : colorEnabled,
+  );
+  const unicode =
+    unicodeEnabled === undefined ? supportsUnicode() : unicodeEnabled;
+
+  let watching = false;
+  let outDir = 'dist';
+  let entryCount;
+  let cycleStart = 0;
+  let cyclePrinted = true;
+  let firstCycleComplete = false;
+  let changedFiles = [];
+
+  /**
+   * Write an array of finished lines to the destination stream.
+   *
+   * @param {string[]} lines - Lines to emit.
+   * @returns {void}
+   */
+  const emit = (lines) => lines.forEach((line) => write(line));
+
+  /**
+   * Unpack a build failure and record everything it contains.
+   *
+   * Rolldown wraps every failure of a cycle into one error whose message is
+   * just a count, so it has to be opened up before anything useful can be
+   * reported. Shared by the build and generate phases, which fail through
+   * different hooks but produce the same shapes.
+   *
+   * @param {Error} error - Build or render error.
+   * @returns {void}
+   */
+  const captureFailure = (error) => {
+    const { importErrors, syntaxErrors, otherErrors } =
+      classifyBuildError(error);
+
+    for (const importError of importErrors) {
+      diagnostics.recordImportError(importError);
+    }
+
+    for (const syntaxError of syntaxErrors) {
+      diagnostics.recordSyntaxError(syntaxError);
+    }
+
+    const detailed = importErrors.length > 0 || syntaxErrors.length > 0;
+
+    for (const other of otherErrors) {
+      // The aggregate wrapper carries no location and would only add a row
+      // reading "Build failed with N errors" above the detail it wraps.
+      if (detailed && /^Build failed with \d+ error/.test(other.message)) {
+        continue;
+      }
+      diagnostics.recordError(other);
+    }
+  };
+
+  /**
+   * Print the summary or rebuild line for the cycle that just finished.
+   *
+   * Guarded so the cycle reports exactly once regardless of whether Rollup
+   * reaches `writeBundle`, `closeBundle`, or neither after a failure.
+   *
+   * @returns {void}
+   */
+  const reportCycle = () => {
+    if (!watching || cyclePrinted) return;
+    cyclePrinted = true;
+
+    const snapshot = diagnostics.snapshot();
+    const durationMs = now() - cycleStart;
+
+    if (firstCycleComplete) {
+      emit(
+        renderRebuild({
+          snapshot,
+          durationMs,
+          changedFiles,
+          projectDir: env.projectDir,
+          styler,
+          now: clock(),
+        }),
+      );
+    } else {
+      firstCycleComplete = true;
+      // Enriching costs a filesystem read per stylesheet, so it only runs when
+      // the build actually produced unresolved URLs. A resolver is built per
+      // cycle so its read cache never serves stale contents after an edit.
+      const needsResolver =
+        snapshot.unresolvedAssets.length > 0 ||
+        snapshot.importErrors.length > 0 ||
+        snapshot.syntaxErrors.length > 0;
+      const resolver = needsResolver ? createAssetResolver(env) : undefined;
+
+      const assetRows = resolver
+        ? buildAssetRows(snapshot.unresolvedAssets, resolver)
+        : [];
+
+      const importRows = resolver
+        ? buildImportRows(snapshot.importErrors, resolver, env.projectDir)
+        : [];
+      const sharedDirectory = sharedMissingDirectory(
+        importRows,
+        env.projectDir,
+      );
+
+      // The minifier reports against generated CSS, so the only route back to
+      // a source file is searching for the literals in the offending rule.
+      const syntaxErrors = resolver
+        ? snapshot.syntaxErrors.map((error) => ({
+            ...error,
+            lead: findLikelySource(error.declaration, resolver),
+          }))
+        : snapshot.syntaxErrors;
+
+      emit(
+        renderSummary({
+          snapshot,
+          durationMs,
+          outDir,
+          projectDir: env.projectDir,
+          sourceGlob: resolveSourceGlob(env),
+          assetRows,
+          syntaxErrors,
+          importErrors: {
+            rows: importRows,
+            sharedDirectory,
+            directoryExists: Boolean(
+              sharedDirectory &&
+              env.projectDir &&
+              existsSync(join(env.projectDir, sharedDirectory)),
+            ),
+          },
+          styler,
+        }),
+      );
+    }
+
+    changedFiles = [];
+  };
+
+  return {
+    name: 'emulsify-develop-reporter',
+
+    // Storybook's dev server resolves as `serve`, so this keeps the reporter
+    // out of the Storybook process entirely.
+    apply: 'build',
+
+    // Report after the plugins that actually produce diagnostics have run.
+    enforce: 'post',
+
+    configResolved(config) {
+      watching = Boolean(config.build?.watch);
+      if (!watching) return;
+
+      outDir = config.build?.outDir || 'dist';
+      entryCount = countEntries(config.build?.rollupOptions?.input);
+
+      emit(
+        renderBanner({
+          version: version || resolvePackageVersion(env.projectDir),
+          platform: env.platform,
+          entryCount,
+          unicode,
+          styler,
+        }),
+      );
+    },
+
+    buildStart() {
+      if (!watching) return;
+      diagnostics.reset();
+      cycleStart = now();
+      cyclePrinted = false;
+    },
+
+    watchChange(id) {
+      if (!watching) return;
+      changedFiles.push(id);
+    },
+
+    buildEnd(error) {
+      if (!watching || !error) return;
+      captureFailure(error);
+      // A failed cycle never reaches writeBundle, so report from here instead.
+      reportCycle();
+    },
+
+    // Failures while generating output — CSS minification among them — occur
+    // after `buildEnd` and abort before `writeBundle`, so without this hook a
+    // broken build produced no summary at all. It also stops a later
+    // `closeBundle` from reporting success over a build that failed.
+    renderError(error) {
+      if (!watching || !error) return;
+      captureFailure(error);
+      reportCycle();
+    },
+
+    writeBundle() {
+      reportCycle();
+    },
+
+    closeBundle() {
+      reportCycle();
+    },
+  };
+}