@emulsify/core 4.3.1 → 4.4.0

package/scripts/audit/index.js

@@ -142,7 +142,7 @@ export function runAuditChecks(context) {
  * Run the combined Emulsify audit.
  *
  * @param {{projectDir?: string, twigThreshold?: number}} [options={}] - Options.
- * @returns {{projectDir: string, summary: object, files: object, findings: object[]}} Audit result.
+ * @returns {{projectDir: string, sourceRoots: string[], summary: object, files: object, findings: object[]}} Audit result.
  */
 export function runAudits(options = {}) {
   resetFileReadCache();
@@ -161,7 +161,7 @@ export function runAudits(options = {}) {
     },
   );
 
-  return {
+  const result = {
     projectDir: context.projectDir,
     summary,
     files: {
@@ -172,6 +172,14 @@ export function runAudits(options = {}) {
     },
     findings,
   };
+
+  // The fix scope is CLI-internal plumbing. Keep raw audit serialization
+  // stable while still sharing the normalized roots with the fix phase.
+  Object.defineProperty(result, 'sourceRoots', {
+    value: context.sourceRoots,
+  });
+
+  return result;
 }
 
 export { runAudits as auditProject };

package/scripts/audit/lib/css.js

@@ -3,6 +3,11 @@
  */
 
 import { basename, dirname, resolve } from 'node:path';
+import {
+  assetTailFor,
+  isAssetAliasPath,
+} from '../../../config/vite/plugins/assets/asset-url-rebase.js';
+import { tokenizeStylesheetUrls } from '../../../config/vite/utils/css-urls.js';
 import {
   compiledAssetOutputPath,
   storybookStyleOutputPath,
@@ -43,40 +48,32 @@ function resolveSassUrlValue(value, variables) {
   );
 }
 
-/**
- * Mask style comments while preserving line and character positions.
- *
- * @param {string} source - Stylesheet source.
- * @returns {string} Source with comments replaced by whitespace.
- */
-function maskStyleComments(source) {
-  const blank = (match) => match.replace(/[^\n]/g, ' ');
-
-  return source
-    .replace(/\/\*[\s\S]*?\*\//g, blank)
-    .replace(/^[\t ]*\/\/.*$/gm, blank);
-}
-
 /**
  * Extract URL references from CSS or Sass source.
  *
+ * `start` and `end` bracket the specifier *without* its quotes, so an autofix
+ * can splice a replacement in without disturbing quote style. The shared
+ * tokenizer preserves original positions, so `source.slice(start, end) === raw`.
+ *
  * @param {string} source - Stylesheet source.
- * @returns {{value: string, raw: string, line: number}[]} URL references.
+ * @returns {{value: string, raw: string, quote: string, line: number, start: number, end: number}[]} URL references.
  */
 export function findCssUrlReferences(source) {
-  const scanSource = maskStyleComments(source);
-  const variables = findSassStringVariables(scanSource);
+  const { urls, sourceWithoutComments } = tokenizeStylesheetUrls(source);
+  const variables = findSassStringVariables(sourceWithoutComments);
   const references = [];
-  const pattern = /url\(\s*(?:(['"])(.*?)\1|([^'")][^)]*?))\s*\)/g;
 
-  for (const match of scanSource.matchAll(pattern)) {
-    const raw = (match[2] ?? match[3] ?? '').trim();
+  for (const token of urls) {
+    const raw = token.value;
     const value = resolveSassUrlValue(raw, variables).trim();
 
     references.push({
       value,
       raw,
-      line: lineNumberAt(source, match.index || 0),
+      quote: token.quote,
+      line: lineNumberAt(source, token.start),
+      start: token.valueStart,
+      end: token.valueEnd,
     });
   }
 
@@ -84,23 +81,32 @@ export function findCssUrlReferences(source) {
 }
 
 /**
- * Determine whether a CSS URL should be skipped by filesystem checks.
+ * Classify how a filesystem-ish CSS URL should be resolved.
+ *
+ * - `asset-root` — `/assets/...`, `@assets/...`, or legacy `assets/...`.
+ *   Resolved against the project asset roots, which is what Storybook serves
+ *   and what the build rebases to.
+ * - `runtime` — some other absolute URL (`/sites/default/files/...`). The
+ *   platform serves it; the audit has nothing to check.
+ * - `relative` — resolved from the stylesheet's own directory.
  *
  * @param {string} value - URL value.
- * @returns {boolean} TRUE when the URL is not a local relative asset path.
+ * @returns {'asset-root'|'runtime'|'relative'} Resolution strategy.
  */
-export function isNonFilesystemCssUrl(value) {
-  return (
-    !value ||
-    value.startsWith('#') ||
-    value.startsWith('/') ||
-    value.startsWith('//') ||
-    value.startsWith('$') ||
-    value.startsWith('#{') ||
-    /^[a-z][a-z0-9+.-]*:/i.test(value) ||
-    /^var\(/i.test(value) ||
-    /^env\(/i.test(value)
-  );
+export function classifyCssAssetUrl(value) {
+  if (assetTailFor(cssUrlPath(value))) return 'asset-root';
+
+  return value.startsWith('/') ? 'runtime' : 'relative';
+}
+
+/**
+ * Determine whether a CSS URL uses the exact namespaced asset alias.
+ *
+ * @param {string} value - URL path without query or hash.
+ * @returns {boolean} TRUE for `@assets/...` paths.
+ */
+export function isCssAssetAlias(value) {
+  return isAssetAliasPath(String(value));
 }
 
 /**

package/scripts/audit/lib/twig.js

@@ -2,7 +2,11 @@
  * @file Twig reference parsing and resolution helpers for the project audit.
  */
 
-import { dirname, isAbsolute, resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
+import {
+  resolveAssetRoots,
+  toAbsoluteAssetRoot,
+} from '../../../config/vite/utils/asset-roots.js';
 import { safeExists } from '../../../config/vite/utils/fs-safe.js';
 import { candidateKeysForReference } from '../../../src/storybook/twig/reference-paths.js';
 import { lineNumberAt } from '../../lib/text.js';
@@ -143,45 +147,23 @@ function candidateKeysToFiles(keys, env) {
  * @returns {string} Absolute filesystem path, or an empty string.
  */
 export function resolveAuditAssetRoot(projectDir, assetRoot) {
-  if (typeof assetRoot !== 'string' || !assetRoot.trim()) return '';
-
-  const normalizedProjectDir = resolve(projectDir || process.cwd());
-  const normalizedRoot = assetRoot.trim();
-
-  if (isAbsolute(normalizedRoot)) {
-    const absoluteRoot = resolve(normalizedRoot);
-
-    return safeExists(absoluteRoot)
-      ? absoluteRoot
-      : resolve(normalizedProjectDir, `.${normalizedRoot}`);
-  }
-
-  return resolve(normalizedProjectDir, normalizedRoot);
+  return toAbsoluteAssetRoot(projectDir, assetRoot);
 }
 
 /**
  * Return filesystem roots that Storybook can use for @assets source() calls.
  *
+ * Existence filtering stays off here because callers do their own directory
+ * check, and a configured-but-missing root is worth reporting rather than
+ * silently dropping.
+ *
  * @param {object} env - Normalized environment.
  * @param {object} [options={}] - Asset root options.
  * @param {boolean} [options.includeGenerated=false] - Include generated roots.
  * @returns {string[]} Absolute asset roots.
  */
 export function auditAssetRoots(env = {}, { includeGenerated = false } = {}) {
-  const projectDir = env.projectDir || process.cwd();
-  const configuredRoots = Array.isArray(env?.projectStructure?.assetRoots)
-    ? env.projectStructure.assetRoots
-    : [];
-  const fallbackRoots = ['assets', 'src/assets'];
-  const generatedRoots = includeGenerated ? ['dist/assets'] : [];
-
-  return Array.from(
-    new Set(
-      [...fallbackRoots, ...configuredRoots, ...generatedRoots]
-        .map((root) => resolveAuditAssetRoot(projectDir, root))
-        .filter(Boolean),
-    ),
-  );
+  return resolveAssetRoots(env, { includeGenerated, existingOnly: false });
 }
 
 /**

package/scripts/audit/report.js

@@ -58,16 +58,51 @@ export function formatAuditReport(result) {
 
   if (!result.findings.length) {
     lines.push('No audit findings found.');
-    return lines.join('\n');
   }
 
   for (const finding of result.findings) {
     lines.push('', ...formatFinding(finding, result.projectDir));
   }
 
+  lines.push(...formatFixSection(result.fixes, result.projectDir));
+
   return lines.join('\n');
 }
 
+/**
+ * Format the autofix section appended by `--fix`.
+ *
+ * @param {{dryRun: boolean, applied: object[], skipped: object[]}} [fixes] - Fix result.
+ * @param {string} projectDir - Absolute scanned root.
+ * @returns {string[]} Report lines.
+ */
+function formatFixSection(fixes, projectDir) {
+  if (!fixes) return [];
+
+  const lines = ['', 'Fixes'];
+  const verb = fixes.dryRun ? 'Would apply' : 'Applied';
+
+  if (!fixes.applied.length) {
+    lines.push(`${verb} 0 fix(es).`);
+  } else {
+    lines.push(`${verb} ${fixes.applied.length} fix(es):`);
+    for (const { finding, from, to } of fixes.applied) {
+      const where = `${displayPath(projectDir, finding.filePath)}:${finding.line}`;
+      lines.push(`  ${where}  ${from} -> ${to}`);
+    }
+  }
+
+  if (fixes.skipped.length) {
+    lines.push(`Skipped ${fixes.skipped.length} fixable finding(s):`);
+    for (const { finding, reason } of fixes.skipped) {
+      const where = `${displayPath(projectDir, finding.filePath)}:${finding.line}`;
+      lines.push(`  ${where}  ${reason}`);
+    }
+  }
+
+  return lines;
+}
+
 /**
  * Count findings by severity for machine-readable reports.
  *
@@ -219,7 +254,7 @@ export function createAuditJsonReport(result, options = {}) {
     normalizeAuditFinding(finding, result.projectDir, options.defaultSeverity),
   );
 
-  return {
+  const document = {
     schemaVersion: AUDIT_REPORT_SCHEMA_VERSION,
     tool: createToolIdentity(),
     root: '.',
@@ -227,19 +262,56 @@ export function createAuditJsonReport(result, options = {}) {
     files: normalizeFileCounts(result.files),
     findings,
   };
+
+  // Present only when --fix ran, so the document shape is unchanged for every
+  // existing consumer.
+  if (result.fixes) {
+    document.fixes = normalizeFixes(result.fixes, result.projectDir);
+  }
+
+  return document;
+}
+
+/**
+ * Normalize the autofix result for the machine-readable report.
+ *
+ * @param {{dryRun: boolean, applied: object[], skipped: object[]}} fixes - Fix result.
+ * @param {string} projectDir - Absolute scanned root.
+ * @returns {object} JSON fix block.
+ */
+function normalizeFixes(fixes, projectDir) {
+  const locate = (finding) => ({
+    path: displayPath(projectDir, finding.filePath) || '.',
+    ...(Number.isInteger(finding.line) && finding.line > 0
+      ? { line: finding.line }
+      : {}),
+  });
+
+  return {
+    dryRun: Boolean(fixes.dryRun),
+    applied: fixes.applied.map(({ finding, from, to }) => ({
+      ...locate(finding),
+      from,
+      to,
+    })),
+    skipped: fixes.skipped.map(({ finding, reason }) => ({
+      ...locate(finding),
+      reason: normalizeReportText(reason, projectDir),
+    })),
+  };
 }
 
 /**
  * Create a structured machine-readable CLI or audit failure.
  *
  * @param {*} error - Failure value.
- * @param {{code?: string, projectDir?: string}} [options={}] - Error options.
+ * @param {{code?: string, projectDir?: string, fixes?: object}} [options={}] - Error options.
  * @returns {object} JSON error document.
  */
 export function createAuditJsonErrorReport(error, options = {}) {
   const message = error?.message || error;
 
-  return {
+  const document = {
     schemaVersion: AUDIT_REPORT_SCHEMA_VERSION,
     tool: createToolIdentity(),
     error: {
@@ -247,6 +319,12 @@ export function createAuditJsonErrorReport(error, options = {}) {
       message: normalizeReportText(message, options.projectDir || ''),
     },
   };
+
+  if (options.fixes) {
+    document.fixes = normalizeFixes(options.fixes, options.projectDir || '');
+  }
+
+  return document;
 }
 
 /**
@@ -265,7 +343,7 @@ export function formatAuditJsonReport(result, options = {}) {
  * Format a CLI or audit failure as machine-readable JSON.
  *
  * @param {*} error - Failure value.
- * @param {{code?: string, projectDir?: string}} [options={}] - Error options.
+ * @param {{code?: string, projectDir?: string, fixes?: object}} [options={}] - Error options.
  * @returns {string} JSON error document.
  */
 export function formatAuditJsonErrorReport(error, options = {}) {

package/scripts/audit.js

@@ -11,11 +11,14 @@ import {
   parseArgs as parseCliArgs,
 } from './lib/cli.js';
 import { DEFAULT_TWIG_THRESHOLD, runAudits } from './audit/index.js';
+import { applyAuditFixes, remainingFindings } from './audit/fix.js';
 import {
   formatAuditJsonErrorReport,
   formatAuditJsonReport,
   formatAuditReport,
+  summarizeFindings,
 } from './audit/report.js';
+import { displayPath } from './audit/lib/findings.js';
 
 export { auditProject, runAudits } from './audit/index.js';
 export {
@@ -27,6 +30,7 @@ export {
   formatAuditReport,
 } from './audit/report.js';
 export { collectProjectFiles } from './audit/lib/files.js';
+export { applyAuditFixes, remainingFindings } from './audit/fix.js';
 export { findCssUrlReferences } from './audit/lib/css.js';
 export {
   findTwigIncludeSourceReferences,
@@ -45,10 +49,12 @@ const cliFailureExitCode = 2;
  */
 function usage() {
   return createUsage(
-    'Usage: emulsify-audit [--root <dir>] [--json] [--fail-on <severity>] [--fail-on-found] [--twig-threshold <count>]',
+    'Usage: emulsify-audit [--root <dir>] [--json] [--fix] [--dry-run] [--fail-on <severity>] [--fail-on-found] [--twig-threshold <count>]',
     [
       '  --root <dir>              Project root to scan. Defaults to the current directory.',
       '  --json                    Print machine-readable JSON.',
+      '  --fix                     Rewrite unambiguous CSS asset URLs to the canonical /assets/... form.',
+      '  --dry-run                 With --fix, report the rewrites without touching files.',
       '  --fail-on <severity>       Exit with code 1 for error, warn, info, or any findings at that threshold.',
       '  --fail-on-found           Compatibility alias for --fail-on any.',
       `  --twig-threshold <count>  Warn when Storybook roots contain more than this many Twig files. Default: ${DEFAULT_TWIG_THRESHOLD}.`,
@@ -70,6 +76,8 @@ function parseArgs(argv) {
       failOn: null,
       json: false,
       help: false,
+      fix: false,
+      dryRun: false,
       twigThreshold: DEFAULT_TWIG_THRESHOLD,
     },
     flags: {
@@ -78,6 +86,8 @@ function parseArgs(argv) {
         value: 'any',
       },
       '--json': 'json',
+      '--fix': 'fix',
+      '--dry-run': 'dryRun',
     },
     options: {
       '--fail-on': {
@@ -167,6 +177,9 @@ export function runCli(argv = process.argv.slice(2)) {
     if (options.help && options.json) {
       throw new Error('--json cannot be combined with --help.');
     }
+    if (options.dryRun && !options.fix) {
+      throw new Error('--dry-run requires --fix.');
+    }
   } catch (error) {
     return reportArgumentFailure(error, jsonRequested);
   }
@@ -178,6 +191,28 @@ export function runCli(argv = process.argv.slice(2)) {
 
   try {
     const result = runAudits(options);
+    let findings = result.findings;
+
+    if (options.fix) {
+      try {
+        result.fixes = applyAuditFixes(findings, {
+          dryRun: options.dryRun,
+          projectDir: result.projectDir,
+          sourceRoots: result.sourceRoots,
+        });
+      } catch (error) {
+        return reportFixFailure(error, options);
+      }
+
+      // A dry run changes nothing on disk, so nothing is subtracted. A real
+      // run removed the findings it fixed from the source, so the threshold
+      // must be judged on what is left.
+      if (!options.dryRun) {
+        result.findings = remainingFindings(findings, result.fixes.applied);
+        result.summary = summarizeFindings(result.findings);
+        findings = result.findings;
+      }
+    }
 
     if (options.json) {
       console.log(formatAuditJsonReport(result));
@@ -185,7 +220,7 @@ export function runCli(argv = process.argv.slice(2)) {
       console.log(formatAuditReport(result));
     }
 
-    return shouldFailAudit(result.findings, options.failOn) ? 1 : 0;
+    return shouldFailAudit(findings, options.failOn) ? 1 : 0;
   } catch (error) {
     if (options.json) {
       console.log(
@@ -202,6 +237,56 @@ export function runCli(argv = process.argv.slice(2)) {
   }
 }
 
+/**
+ * Print a failure that happened while writing fixes.
+ *
+ * @param {*} error - Write failure.
+ * @param {object} options - Parsed CLI options.
+ * @returns {number} Exit code.
+ */
+function reportFixFailure(error, options) {
+  const projectDir = resolve(options.projectDir);
+
+  if (options.json) {
+    console.log(
+      formatAuditJsonErrorReport(error, {
+        code: 'fix-failed',
+        projectDir,
+        fixes: error?.fixes,
+      }),
+    );
+  } else {
+    const lines = [`Audit fix failed: ${error.message || error}`];
+    const applied = error?.fixes?.applied || [];
+    const rewrittenFiles = Array.from(
+      new Set(applied.map(({ finding }) => finding.filePath)),
+    ).sort();
+
+    if (rewrittenFiles.length) {
+      const verb = error?.fixes?.dryRun ? 'Would apply' : 'Applied';
+      lines.push(
+        `${verb} ${applied.length} fix(es) across ${rewrittenFiles.length} file(s) before the failure:`,
+        ...rewrittenFiles.map(
+          (filePath) => `  ${displayPath(projectDir, filePath)}`,
+        ),
+      );
+    }
+
+    const skipped = error?.fixes?.skipped || [];
+    if (skipped.length) {
+      lines.push(`Skipped ${skipped.length} fixable finding(s):`);
+      for (const { finding, reason } of skipped) {
+        const where = `${displayPath(projectDir, finding.filePath)}:${finding.line}`;
+        lines.push(`  ${where}  ${reason}`);
+      }
+    }
+
+    console.error(lines.join('\n'));
+  }
+
+  return cliFailureExitCode;
+}
+
 if (isCliEntrypoint(['audit.js', 'emulsify-audit'])) {
   process.exitCode = runCli();
 }

package/src/storybook/twig/source-function.js

@@ -22,14 +22,15 @@ function getRuntimeEnv() {
   return globalThis.__EMULSIFY_ENV__ || DEFAULT_ENV;
 }
 
-// GitHub Pages serves static assets from a repository-prefixed base path.
-const PUBLIC_ASSET_BASE =
-  typeof window !== 'undefined' &&
-  window.location &&
-  window.location.hostname &&
-  window.location.hostname.endsWith('github.io')
-    ? `/${getRuntimeEnv().machineName || ''}/assets/`
-    : '/assets/';
+// Storybook copies staticDirs beside the preview document, so `iframe.html`
+// and the public `assets/` directory are always siblings in a static build. A
+// document-relative base is resolved against the preview document's own URL:
+// `/iframe.html` at a domain root resolves to `/assets/...`, and
+// `/project/iframe.html` under a deployment subpath resolves to
+// `/project/assets/...`. That covers root deployments, project Pages URLs on
+// any host, custom domains, and arbitrary nested paths without hostname
+// detection or a configured base path.
+const PUBLIC_ASSET_BASE = './assets/';
 
 const pendingSourceLoads = new Set();
 const warnedAssetSources = new Set();
@@ -54,7 +55,10 @@ function normalizeAssetPath(assetPath) {
 /**
  * Read a text asset from Storybook's static server.
  *
- * @param {string} relPath - Public asset path below `/assets`.
+ * The request URL stays relative to the preview document, so the fallback
+ * resolves the same way at a domain root and under a deployment subpath.
+ *
+ * @param {string} relPath - Public asset path below the public asset base.
  * @returns {string|undefined} Fetched text when available.
  */
 function fetchTextAsset(relPath) {
@@ -77,7 +81,7 @@ function fetchTextAsset(relPath) {
 /**
  * Warn once when a text asset cannot use the lazy virtual source map.
  *
- * @param {string} relPath - Public asset path below `/assets`.
+ * @param {string} relPath - Public asset path below the public asset base.
  * @param {string} reason - Short explanation of the missing source.
  */
 function warnTextAssetSource(relPath, reason) {