@emulsify/core 4.3.2 → 4.5.0

package/scripts/audit/checks/css-asset-references.js

@@ -1,9 +1,21 @@
 /**
  * @file CSS asset reference audit check.
+ *
+ * Emulsify accepts root-absolute `url('/assets/...')` and namespaced
+ * `url('@assets/...')` references. Two other forms are common and both used to
+ * ship broken: a relative URL authored against the emitted CSS location, and
+ * the bare `assets/...` form. The build repairs both when the target is
+ * unambiguous (config/vite/plugins/assets/css-asset-rebase.js), so what this
+ * check reports is (a) references nothing can resolve, and (b) references the
+ * build has to repair, which are worth writing canonically in source.
  */
 
 import { dirname, resolve } from 'node:path';
-import { firstExistingPath } from '../../../config/vite/utils/fs-safe.js';
+import { assetTailFor } from '../../../config/vite/plugins/assets/asset-url-rebase.js';
+import { resolveAssetTail } from '../../../config/vite/utils/asset-roots.js';
+import { isNonFilesystemCssUrl } from '../../../config/vite/utils/css-urls.js';
+import { firstExistingFile } from '../../../config/vite/utils/fs-safe.js';
+import { createAuditFixTargetChecker } from '../fix.js';
 import { displayPath, makeFinding } from '../lib/findings.js';
 import {
   cachedReadFile,
@@ -13,14 +25,188 @@ import {
 } from '../lib/files.js';
 import { auditAssetRoots } from '../lib/twig.js';
 import {
+  classifyCssAssetUrl,
   cssUrlPath,
   findCssUrlReferences,
-  isNonFilesystemCssUrl,
+  isCssAssetAlias,
   styleRuntimeDirectories,
 } from '../lib/css.js';
 
+const ASSET_DOCS =
+  'https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/asset-references.md#sass-and-css';
+
+/**
+ * Build the fix payload an autofix can apply to the authored stylesheet.
+ *
+ * Interpolated URLs are deliberately unfixable: the edit belongs on the
+ * variable declaration, and same-file variable scanning cannot see who else
+ * depends on it.
+ *
+ * @param {string} filePath - Absolute stylesheet path.
+ * @param {{raw: string, start: number, end: number}} ref - URL reference.
+ * @param {string} replacement - Canonical URL.
+ * @param {boolean} fixWritable - Whether audit policy permits a rewrite.
+ * @returns {object|undefined} Fix payload, when safe to apply.
+ */
+function makeUrlFix(filePath, ref, replacement, fixWritable) {
+  if (!fixWritable || ref.raw.includes('#{') || ref.raw === replacement) {
+    return undefined;
+  }
+
+  return {
+    filePath,
+    start: ref.start,
+    end: ref.end,
+    original: ref.raw,
+    replacement,
+  };
+}
+
+/**
+ * Build the finding for a CSS asset URL nothing can resolve.
+ *
+ * @param {object} params - Reference context.
+ * @param {string} params.filePath - Absolute stylesheet path.
+ * @param {string} [params.projectDir] - Absolute project root.
+ * @param {object} params.ref - URL reference.
+ * @param {object} params.resolution - Asset tail resolution.
+ * @returns {object} Finding.
+ */
+function unresolvedFinding({ filePath, projectDir = '', ref, resolution }) {
+  const ambiguous = resolution.status === 'ambiguous';
+
+  return makeFinding({
+    id: 'unresolved-css-asset-reference',
+    severity: 'warn',
+    filePath,
+    line: ref.line,
+    message: ambiguous
+      ? `CSS asset URL "${ref.raw}" matches more than one project asset root.`
+      : `CSS asset URL "${ref.raw}" could not be resolved from the source file or any project asset root.`,
+    details: ambiguous
+      ? [
+          `Candidates: ${resolution.candidates
+            .map((candidate) => displayPath(projectDir, candidate))
+            .join(', ')}.`,
+          'Remove the duplicate, or narrow assets.roots in project.emulsify.json so one file answers to the URL.',
+        ]
+      : [
+          'Reference project assets with url(/assets/...) or url(@assets/...), and keep the file under assets/ or a root declared in project.emulsify.json assets.roots.',
+          'Otherwise check the filename for a typo.',
+        ],
+    docs: ASSET_DOCS,
+  });
+}
+
+/**
+ * Report the Core-only stylesheet alias when its resolver is disabled.
+ *
+ * @param {object} params - Reference context.
+ * @param {string} params.filePath - Absolute stylesheet path.
+ * @param {object} params.ref - URL reference.
+ * @returns {object} Finding.
+ */
+function disabledAliasFinding({ filePath, ref }) {
+  return makeFinding({
+    id: 'unresolved-css-asset-reference',
+    severity: 'warn',
+    filePath,
+    line: ref.line,
+    message: `CSS asset URL "${ref.raw}" uses the @assets stylesheet alias, but assets.rebase is disabled.`,
+    details: [
+      'Enable assets.rebase to use @assets/..., or write a URL that Vite can resolve without the Emulsify asset pipeline.',
+    ],
+    docs: ASSET_DOCS,
+  });
+}
+
+/**
+ * Audit a URL that names the published `assets/` prefix.
+ *
+ * @param {object} params - Reference context.
+ * @param {string} params.assetPath - URL path without query or hash.
+ * @param {string[]} params.assetRoots - Absolute project asset roots.
+ * @param {string} params.filePath - Absolute stylesheet path.
+ * @param {Function} params.canFix - Lazily check whether policy permits a rewrite.
+ * @param {string} params.projectDir - Absolute project root.
+ * @param {object} params.ref - URL reference.
+ * @returns {object[]} Findings.
+ */
+function auditAssetRootReference({
+  assetPath,
+  assetRoots,
+  canFix,
+  filePath,
+  projectDir,
+  ref,
+}) {
+  const tail = assetTailFor(assetPath);
+  const resolution = resolveAssetTail(tail, assetRoots);
+
+  if (resolution.status !== 'resolved') {
+    return [unresolvedFinding({ filePath, projectDir, ref, resolution })];
+  }
+
+  const resolvedSuffix = ref.value.slice(cssUrlPath(ref.value).length);
+  const resolvedCanonical = `/assets/${tail}${resolvedSuffix}`;
+  const resolvedAlias = `@assets/${tail}${resolvedSuffix}`;
+
+  // The scanner expands simple same-file Sass variables in `ref.value` while
+  // retaining the authored interpolation in `ref.raw`. Accept an expansion
+  // that lands exactly on either first-class form before deciding that an
+  // interpolated reference needs manual review.
+  if (ref.value === resolvedCanonical || ref.value === resolvedAlias) return [];
+
+  const interpolated = ref.raw.includes('#{');
+  // A `?v=2` or `#id` suffix is part of the authored URL, not of the asset
+  // path, so it survives the rewrite untouched. Interpolation also begins
+  // with `#`, but it is authored Sass rather than a URL fragment; deriving a
+  // replacement from it would append the complete raw value as a suffix.
+  const canonical = interpolated
+    ? undefined
+    : `/assets/${tail}${ref.raw.slice(cssUrlPath(ref.raw).length)}`;
+  const alias = interpolated
+    ? undefined
+    : `@assets/${tail}${ref.raw.slice(cssUrlPath(ref.raw).length)}`;
+
+  // Both public spellings are accepted authoring forms.
+  if (ref.raw === canonical || ref.raw === alias) return [];
+
+  const fix = canonical
+    ? makeUrlFix(filePath, ref, canonical, canFix())
+    : undefined;
+  const details = [
+    `Resolved asset: ${displayPath(projectDir, resolution.file)}.`,
+  ];
+
+  if (canonical) {
+    details.push(`Rewrite it as url(${canonical}).`);
+  } else {
+    details.push(
+      'This URL contains Sass interpolation, so review its variable declaration instead of rewriting the reference automatically.',
+    );
+  }
+
+  if (fix) {
+    details.push('Run `emulsify-audit --fix` to apply this automatically.');
+  }
+
+  return [
+    makeFinding({
+      id: 'css-runtime-asset-reference',
+      severity: 'info',
+      filePath,
+      line: ref.line,
+      message: `CSS asset URL "${ref.raw}" is not the canonical asset form, so the build has to repair it.`,
+      details,
+      docs: ASSET_DOCS,
+      fix,
+    }),
+  ];
+}
+
 /**
- * Audit local CSS/Sass asset URLs that Vite may leave to runtime resolution.
+ * Audit local CSS/Sass asset URLs against the project's asset roots.
  *
  * @param {object} context - Audit context.
  * @returns {object[]} Findings.
@@ -28,8 +214,16 @@ import {
 export function auditCssAssetReferences(context) {
   const { env, projectDir, styleFiles } = context;
   const findings = [];
-  const projectAssetRoots = auditAssetRoots(env).filter(safeIsDirectory);
-  const styleSourceRoots = env.projectStructure?.sourceRoots || [];
+  const assetRoots = auditAssetRoots(env).filter(safeIsDirectory);
+  const assetAliasEnabled = env.projectStructure?.assetRebase !== false;
+  const sourceRoots = Array.isArray(context.sourceRoots)
+    ? context.sourceRoots
+    : env.projectStructure?.sourceRoots;
+  const styleSourceRoots = sourceRoots || [];
+  const isFixTargetWritable = createAuditFixTargetChecker({
+    projectDir,
+    sourceRoots,
+  });
 
   for (const filePath of styleFiles) {
     if (
@@ -39,43 +233,81 @@ export function auditCssAssetReferences(context) {
       continue;
     }
 
+    let fixWritable;
+    const canFix = () => {
+      fixWritable ??= isFixTargetWritable(filePath);
+      return fixWritable;
+    };
     const source = cachedReadFile(filePath);
     const runtimeDirs = styleRuntimeDirectories(filePath, env, projectDir);
 
     for (const ref of findCssUrlReferences(source)) {
-      if (isNonFilesystemCssUrl(ref.value)) continue;
+      if (isNonFilesystemCssUrl(ref.value, ref.quote)) continue;
 
       const assetPath = cssUrlPath(ref.value);
       if (!assetPath) continue;
 
-      const sourceAsset = firstExistingPath([
-        resolve(dirname(filePath), assetPath),
-      ]);
-      const runtimeAsset = firstExistingPath(
+      if (isCssAssetAlias(assetPath) && !assetAliasEnabled) {
+        findings.push(disabledAliasFinding({ filePath, ref }));
+        continue;
+      }
+
+      // CSS resolves non-absolute URLs from the source stylesheet first. The
+      // build plugin only sees literals Vite already failed to resolve, but the
+      // audit scans authored source and must preserve that precedence itself.
+      // Do not probe `/assets/...` against the filesystem root: it is the
+      // canonical project-asset form, not a source-relative path.
+      const sourceAsset =
+        assetPath.startsWith('/') || isCssAssetAlias(assetPath)
+          ? undefined
+          : firstExistingFile([resolve(dirname(filePath), assetPath)]);
+      const classification = classifyCssAssetUrl(ref.value);
+
+      // Some other absolute URL: the platform serves it, and there is no
+      // project file to check it against.
+      if (classification === 'runtime') continue;
+
+      if (classification === 'asset-root') {
+        // Rewriting a working local reference could select a different file
+        // with the same tail under a project asset root. It needs no repair and
+        // is deliberately ineligible for --fix.
+        if (sourceAsset) continue;
+
+        findings.push(
+          ...auditAssetRootReference({
+            assetPath,
+            assetRoots,
+            canFix,
+            filePath,
+            projectDir,
+            ref,
+          }),
+        );
+        continue;
+      }
+
+      const runtimeAsset = firstExistingFile(
         runtimeDirs.map((directory) => resolve(directory, assetPath)),
       );
       const resolvedAsset = sourceAsset || runtimeAsset;
 
       if (!resolvedAsset) {
         findings.push(
-          makeFinding({
-            id: 'unresolved-css-asset-reference',
-            severity: 'warn',
+          unresolvedFinding({
             filePath,
-            line: ref.line,
-            message: `CSS asset URL "${ref.raw}" could not be resolved from the source file or expected emitted CSS location.`,
-            details: [
-              'Check for a typo, move the asset into a source-root-relative location Vite can resolve, or rewrite the URL to a stable Drupal/theme public path.',
-            ],
-            docs: 'https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/migration-4x.md#css-asset-urls',
+            projectDir,
+            ref,
+            resolution: { status: 'missing' },
           }),
         );
         continue;
       }
 
+      // A relative URL that only resolves once the CSS is emitted is exactly
+      // the shape that breaks when the output shape changes.
       if (
-        projectAssetRoots.some((root) => isSameOrInside(resolvedAsset, root)) &&
-        (!sourceAsset || runtimeAsset || assetPath.startsWith('..'))
+        assetRoots.some((root) => isSameOrInside(resolvedAsset, root)) &&
+        (!sourceAsset || runtimeAsset)
       ) {
         findings.push(
           makeFinding({
@@ -83,12 +315,12 @@ export function auditCssAssetReferences(context) {
             severity: 'info',
             filePath,
             line: ref.line,
-            message: `CSS asset URL "${ref.raw}" resolves to project-level assets and may be left unchanged by Vite for runtime resolution.`,
+            message: `CSS asset URL "${ref.raw}" reaches project assets by a path that only resolves once the CSS is emitted.`,
             details: [
               `Resolved asset: ${displayPath(projectDir, resolvedAsset)}.`,
-              'This is acceptable when Drupal serves the asset at that runtime URL. To make Vite bundle or rebase it, move the asset under a source root and reference it from the authored stylesheet.',
+              'Write it as url(/assets/...) so the same source works in Storybook and in every emitted CSS location.',
             ],
-            docs: 'https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/migration-4x.md#css-asset-urls',
+            docs: ASSET_DOCS,
           }),
         );
       }

package/scripts/audit/checks/twig-references.js

@@ -6,7 +6,7 @@ import { resolve } from 'node:path';
 import { makeFinding } from '../lib/findings.js';
 import { cachedReadFile } from '../lib/files.js';
 import {
-  findTwigIncludeSourceReferences,
+  findTwigReferenceCalls,
   findTwigNamespaceReferences,
   resolvesTwigReference,
 } from '../lib/twig.js';
@@ -23,6 +23,7 @@ export function auditTwigReferences(context) {
   const knownNamespaces = new Set([...Object.keys(namespaceRoots), 'assets']);
   const findings = [];
   const seen = new Set();
+  const componentGroupRootsCache = new Map();
 
   for (const twigFile of twigFiles) {
     const source = cachedReadFile(twigFile);
@@ -46,15 +47,25 @@ export function auditTwigReferences(context) {
       );
     }
 
-    for (const ref of findTwigIncludeSourceReferences(source)) {
-      if (!resolvesTwigReference(ref.value, twigFile, env)) {
+    for (const call of findTwigReferenceCalls(source)) {
+      // Optional or uncertain calls cannot establish a required missing target.
+      if (call.ignoreMissing !== false || call.hasDynamicCandidates) continue;
+      const resolved = call.candidates.some(
+        ({ value }) =>
+          value !== '' &&
+          resolvesTwigReference(value, twigFile, env, componentGroupRootsCache),
+      );
+      if (!resolved) {
+        const description = call.isFallbackArray
+          ? `fallback candidates ${JSON.stringify(call.candidates.map(({ value }) => value))}`
+          : `reference "${call.candidates[0].value}"`;
         findings.push(
           makeFinding({
             id: 'unresolved-twig-reference',
             severity: 'warn',
             filePath: twigFile,
-            line: ref.line,
-            message: `${ref.type}() reference "${ref.value}" could not be resolved from the normalized Twig roots.`,
+            line: call.line,
+            message: `${call.type}() ${description} could not be resolved from the normalized Twig roots.`,
             docs: 'https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/storybook.md#include',
           }),
         );