@emulsify/core 4.3.2 → 4.5.0

package/scripts/audit-twig-stories.js

@@ -18,6 +18,12 @@ import {
   formatAuditJsonErrorReport,
   formatAuditJsonReport,
 } from './audit/report.js';
+import {
+  findRenderTwigBindings,
+  findTwigTemplateBindings,
+  parseStoryModule,
+} from './audit/lib/story-ast.js';
+import { classifyStoryRenderPaths } from './audit/lib/story-render-paths.js';
 import { lineNumberAt } from './lib/text.js';
 
 const STORY_GLOB = '**/*.stories.{js,jsx,ts,tsx}';
@@ -115,13 +121,13 @@ export function findDirectTemplateReturns(source, templateNames = []) {
 }
 
 /**
- * Analyze one Storybook story source string.
+ * Analyze one Storybook story with the legacy regex implementation.
  *
  * @param {string} source - Story source.
- * @param {string} [filePath=''] - Story file path.
+ * @param {string} filePath - Story file path.
  * @returns {object} Story analysis.
  */
-export function analyzeStorySource(source, filePath = '') {
+function analyzeStorySourceWithRegex(source, filePath) {
   const twigImports = findTwigImports(source);
   const templateNames = twigImports.map((item) => item.name);
   const hasRenderTwig = importsRenderTwig(source);
@@ -160,6 +166,70 @@ export function analyzeStorySource(source, filePath = '') {
   };
 }
 
+/**
+ * Analyze one Storybook story source string.
+ *
+ * @param {string} source - Story source.
+ * @param {string} [filePath=''] - Story file path.
+ * @returns {object} Story analysis.
+ */
+export function analyzeStorySource(source, filePath = '') {
+  const parsed = parseStoryModule(source, filePath);
+  if (!parsed) return analyzeStorySourceWithRegex(source, filePath);
+
+  const twigImports = findTwigTemplateBindings(parsed.ast);
+  const renderTwigNames = findRenderTwigBindings(parsed.ast);
+  const hasRenderTwig = renderTwigNames.size > 0;
+  const reasons = [];
+
+  if (!twigImports.length) {
+    return {
+      filePath,
+      twigImports,
+      hasRenderTwig,
+      directTemplateReturns: [],
+      reasons,
+      shouldUpgrade: false,
+    };
+  }
+
+  const classification = classifyStoryRenderPaths(parsed.ast, {
+    templateNames: twigImports.map((item) => item.name),
+    renderTwigNames,
+  });
+  const fallbackLine = Number.isInteger(twigImports[0]?.line)
+    ? twigImports[0].line
+    : 1;
+  const directTemplateReturns = classification.legacy.map((item) => ({
+    name: item.name || twigImports[0].name,
+    line: Number.isInteger(item.line) ? item.line : fallbackLine,
+  }));
+
+  if (!hasRenderTwig && classification.legacy.length) {
+    reasons.push('imports Twig templates without renderTwig()');
+  }
+
+  if (classification.legacy.length) {
+    reasons.push('appears to return Twig HTML strings directly');
+  }
+
+  if (reasons.length && !directTemplateReturns.length) {
+    directTemplateReturns.push({
+      name: twigImports[0].name,
+      line: fallbackLine,
+    });
+  }
+
+  return {
+    filePath,
+    twigImports,
+    hasRenderTwig,
+    directTemplateReturns,
+    reasons,
+    shouldUpgrade: reasons.length > 0,
+  };
+}
+
 /**
  * Resolve Storybook source roots for the project.
  *

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) {