@emulsify/core 4.2.1 → 4.3.1

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@emulsify/core",
-  "version": "4.2.1",
+  "version": "4.3.1",
   "description": "Bundled tooling for Storybook development + Vite Build",
   "keywords": [
     "component library",
     "craftcms",
+    "custom elements",
     "design system",
     "drupal",
     "pattern library",
@@ -12,17 +13,19 @@
     "styleguide",
     "twig",
     "vite",
+    "web components",
     "wordpress"
   ],
   "author": "Four Kitchens <shout@fourkitchens.com>",
   "license": "GPL-2.0",
   "engines": {
-    "node": ">=24"
+    "node": ">=24.13.0"
   },
   "type": "module",
   "bin": {
     "emulsify-audit": "./scripts/audit.js",
-    "emulsify-audit-twig-stories": "./scripts/audit-twig-stories.js"
+    "emulsify-audit-twig-stories": "./scripts/audit-twig-stories.js",
+    "emulsify-inspect-components": "./scripts/inspect-components.js"
   },
   "repository": {
     "type": "git",
@@ -44,6 +47,7 @@
     ".storybook/manager-head.css",
     ".storybook/manager.js",
     ".storybook/preview.js",
+    ".storybook/ready-reporter.js",
     ".storybook/utils.js",
     "assets/**/*",
     "config/.prettierrc.json",
@@ -55,34 +59,55 @@
     "config/vite/entries.js",
     "config/vite/environment.js",
     "config/vite/platforms.js",
-    "config/vite/plugins/copy-src-assets.js",
-    "config/vite/plugins/copy-twig-files.js",
-    "config/vite/plugins/css-asset-relativizer.js",
+    "config/vite/plugins/assets/copy-src-assets.js",
+    "config/vite/plugins/assets/copy-twig-files.js",
+    "config/vite/plugins/assets/css-asset-relativizer.js",
+    "config/vite/plugins/assets/mirror-components.js",
+    "config/vite/plugins/assets/source-file-index.js",
+    "config/vite/plugins/assets/svg-sprite.js",
     "config/vite/plugins/index.js",
-    "config/vite/plugins/mirror-components.js",
+    "config/vite/plugins/reporter/asset-resolver.js",
+    "config/vite/plugins/reporter/build-errors.js",
+    "config/vite/plugins/reporter/diagnostics.js",
+    "config/vite/plugins/reporter/format.js",
+    "config/vite/plugins/reporter/index.js",
+    "config/vite/plugins/reporter/render.js",
+    "config/vite/plugins/reporter/sass-logger.js",
+    "config/vite/plugins/reporter/source-roots.js",
+    "config/vite/plugins/reporter/verbosity.js",
+    "config/vite/plugins/reporter/vite-logger.js",
+    "config/vite/plugins/reporter/watch-mode.js",
     "config/vite/plugins/require-context.js",
-    "config/vite/plugins/source-file-index.js",
-    "config/vite/plugins/svg-sprite.js",
-    "config/vite/plugins/twig-extension-installers.js",
-    "config/vite/plugins/twig-module.js",
-    "config/vite/plugins/virtual-twig-asset-sources.js",
-    "config/vite/plugins/virtual-twig-globs.js",
-    "config/vite/plugins/vituum-patch.js",
+    "config/vite/plugins/twig/extension-installers.js",
+    "config/vite/plugins/twig/extensions.js",
+    "config/vite/plugins/twig/twig-module.js",
+    "config/vite/plugins/twig/virtual-twig-asset-sources.js",
+    "config/vite/plugins/twig/virtual-twig-globs.js",
+    "config/vite/plugins/twig/vituum-patch.js",
     "config/vite/plugins/yaml-module.js",
     "config/vite/plugins.js",
     "config/vite/project-config.js",
     "config/vite/project-extensions.js",
     "config/vite/project-structure.js",
-    "config/vite/twig-extensions.js",
     "config/vite/utils/fs-safe.js",
+    "config/vite/utils/lru.js",
+    "config/vite/utils/package-version.js",
     "config/vite/utils/paths.js",
     "config/vite/utils/react-singleton.js",
-    "config/vite/utils/unique.js",
     "config/vite/vite.config.js",
     "scripts/a11y.js",
     "scripts/audit.js",
+    "scripts/audit/**/*.js",
+    "!scripts/audit/**/*.test.js",
+    "!scripts/audit/**/__snapshots__/**",
+    "!scripts/audit/test-utils.js",
     "scripts/audit-twig-stories.js",
     "scripts/check-node-version.js",
+    "scripts/inspect-components.js",
+    "scripts/lib/cli.js",
+    "scripts/lib/fs.js",
+    "scripts/lib/proc.js",
+    "scripts/lib/text.js",
     "scripts/loadYaml.js",
     "src/extensions/index.js",
     "src/extensions/react/index.js",
@@ -91,6 +116,7 @@
     "src/extensions/shared/html.js",
     "src/extensions/shared/lists.js",
     "src/extensions/shared/object.js",
+    "src/extensions/shared/root-relative.js",
     "src/extensions/twig/function-map.js",
     "src/extensions/twig/functions/add-attributes.js",
     "src/extensions/twig/functions/bem.js",
@@ -104,14 +130,14 @@
     "src/storybook/preview-decorator.js",
     "src/storybook/preview-parameters.js",
     "src/storybook/render-twig.js",
-    "src/storybook/twig/include-function.js",
-    "src/storybook/twig/include.js",
+    "src/storybook/render-web-component.js",
+    "src/storybook/twig/asset-source-runtime.js",
+    "src/storybook/twig/constants.js",
     "src/storybook/twig/drupal-filters.js",
+    "src/storybook/twig/include-function.js",
     "src/storybook/twig/reference-paths.js",
     "src/storybook/twig/resolver.js",
     "src/storybook/twig/setup.js",
-    "src/storybook/twig/source-events.js",
-    "src/storybook/twig/source-extensions.js",
     "src/storybook/twig/source-function.js",
     "src/storybook/twig/source.js"
   ],
@@ -142,17 +168,23 @@
     "audit:twig-stories": "npm run check-node-version && node scripts/audit-twig-stories.js",
     "coverage": "npm run check-node-version && npm run test && open-cli .coverage/lcov-report/index.html",
     "format": "npm run check-node-version && npm run lint-fix && npm run prettier-fix",
+    "fixtures:consumer": "npm run check-node-version && node scripts/consumer-fixtures.js",
+    "fixtures:consumer:list": "npm run check-node-version && node scripts/consumer-fixtures.js --list",
     "fixtures:release": "npm run check-node-version && node scripts/release-fixtures.js",
     "fixtures:release:list": "npm run check-node-version && node scripts/release-fixtures.js --list",
     "husky:commit-msg": "npm run check-node-version && commitlint --edit $1",
     "husky:pre-commit": "npm run check-node-version && npm run lint",
+    "inspect:components": "npm run check-node-version && node scripts/inspect-components.js",
     "lint": "npm run check-node-version && npm run lint-js && npm run prettier",
     "lint-fix": "npm run check-node-version && npm run lint-js -- --fix",
     "lint-js": "npm run check-node-version && eslint --config config/eslint.config.js ./.cli ./.storybook ./config ./scripts ./src",
     "lint-staged": "npm run check-node-version && lint-staged",
+    "pack:dry-run": "npm run check-node-version && npm pack --dry-run --ignore-scripts --json",
     "prepare": "npm run check-node-version && husky",
     "prettier": "npm run check-node-version && prettier --check --config config/.prettierrc.json --ignore-unknown \"**/*.{js,mjs,cjs,jsx,json,yml,yaml,scss,md,twig}\"",
     "prettier-fix": "npm run check-node-version && prettier --config config/.prettierrc.json --write --ignore-unknown \"**/*.{js,mjs,cjs,jsx,json,yml,yaml,scss,md,twig}\"",
+    "release:analyze": "npm run check-node-version && node scripts/verify-release-analysis.js",
+    "release:verify": "npm run check-node-version && npm run lint && npm test && npm run storybook-build && npm run fixtures:release && npm run fixtures:consumer && npm run pack:dry-run && npm run smoke:pack && npm run release:analyze",
     "semantic-release": "npm run check-node-version && semantic-release --config ./release.config.cjs",
     "smoke:pack": "npm run check-node-version && node scripts/smoke-pack.js",
     "version:develop": "npm run check-node-version && node scripts/bump-version-from-commits.js",
@@ -164,64 +196,62 @@
   },
   "dependencies": {
     "@babel/core": "^7.29.7",
-    "@babel/eslint-parser": "^7.28.6",
-    "@babel/preset-env": "^7.28.3",
+    "@babel/eslint-parser": "^7.29.7",
+    "@babel/preset-env": "^7.29.7",
     "@emulsify/cli": "^2.2.0",
-    "@eslint/js": "^9.39.4",
-    "@storybook/addon-a11y": "^10.1.4",
-    "@storybook/addon-links": "^10.1.4",
-    "@storybook/addon-themes": "^10.1.4",
-    "@storybook/react": "^10.1.4",
-    "@storybook/react-vite": "^10.1.4",
-    "@vituum/vite-plugin-twig": "^1.1.0",
-    "autoprefixer": "^10.5.2",
-    "axe-core": "^4.11.4",
+    "@eslint/js": "^9.39.5",
+    "@mlnop/vite-plugin-sass-glob-import": "^6.2.0",
+    "@storybook/addon-a11y": "^10.5.4",
+    "@storybook/addon-links": "^10.5.4",
+    "@storybook/addon-themes": "^10.5.4",
+    "@storybook/react": "^10.5.4",
+    "@storybook/react-vite": "^10.5.4",
+    "@vituum/vite-plugin-twig": "^2.0.1",
+    "autoprefixer": "^10.5.4",
+    "axe-core": "^4.12.1",
     "babel-preset-minify": "^0.5.2",
-    "concurrently": "^9.2.3",
-    "eslint": "^9.39.4",
+    "concurrently": "^10.0.4",
+    "eslint": "^9.39.5",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-jest": "^29.15.4",
-    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-jest": "^29.16.0",
+    "eslint-plugin-prettier": "^5.5.6",
     "eslint-plugin-security": "^4.0.1",
-    "eslint-plugin-storybook": "^10.4.6",
+    "eslint-plugin-storybook": "^10.5.4",
     "glob": "^13.0.6",
-    "jest": "^30.2.0",
-    "jest-environment-jsdom": "^30.2.0",
-    "js-yaml": "^4.1.0",
+    "jest": "^30.4.2",
+    "jest-environment-jsdom": "^30.4.1",
+    "js-yaml": "^5.2.2",
     "normalize.css": "^8.0.1",
     "open-cli": "^9.0.0",
-    "pa11y": "^9.0.1",
-    "postcss": "^8.5.16",
+    "pa11y": "^9.1.1",
+    "postcss": "^8.5.23",
     "postcss-scss": "^4.0.9",
-    "sass": "^1.101.0",
-    "storybook": "^10.1.4",
-    "stylelint": "^17.12.0",
+    "sass": "^1.102.0",
+    "storybook": "^10.5.4",
+    "stylelint": "^17.14.1",
     "stylelint-config-standard-scss": "^17.0.0",
     "stylelint-prettier": "^5.0.3",
     "stylelint-selector-bem-pattern": "^5.0.0",
     "twig": "^3.0.0",
     "twig-drupal-filters": "^3.2.0",
-    "vite": "^7.3.5",
-    "vite-plugin-sass-glob-import": "^6.0.0",
-    "vite-plugin-static-copy": "^4.1.0",
-    "vite-plugin-svg-sprite": "^0.7.0",
-    "yaml": "^2.8.1"
+    "vite": "^8.1.5"
   },
   "devDependencies": {
-    "@commitlint/cli": "^21.2.0",
+    "@commitlint/cli": "^21.2.1",
     "@commitlint/config-conventional": "^21.2.0",
-    "@semantic-release/changelog": "^6.0.2",
+    "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/commit-analyzer": "^13.0.1",
-    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/git": "^11.0.1",
     "@semantic-release/github": "^12.0.9",
     "@semantic-release/npm": "^13.1.5",
-    "@semantic-release/release-notes-generator": "^14.1.0",
+    "@semantic-release/release-notes-generator": "^14.1.1",
     "husky": "^9.1.7",
-    "lint-staged": "^17.0.8",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
-    "semantic-release": "^25.0.3"
+    "lint-staged": "^17.2.0",
+    "puppeteer": "^25.3.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "semantic-release": "^25.0.8"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
@@ -231,5 +261,13 @@
     "glob": "^13.0.6",
     "locutus": "^3.0.36",
     "minimatch@3.0.x": "^3.1.5"
+  },
+  "allowScripts": {
+    "@parcel/watcher@2.6.0": true,
+    "esbuild@0.28.1": true,
+    "fsevents@2.3.3": true,
+    "puppeteer@24.43.1": true,
+    "unrs-resolver@1.12.2": true,
+    "puppeteer@25.4.0": true
   }
 }

package/scripts/a11y.js

@@ -5,16 +5,14 @@
  * and reports issues.
  */
 
-import { existsSync, readFileSync } from 'fs';
+import { createReadStream, existsSync, readFileSync, statSync } from 'fs';
+import { createServer } from 'http';
 import path from 'path';
-import { fileURLToPath, pathToFileURL } from 'url';
+import { pathToFileURL } from 'url';
 import pa11y from 'pa11y';
 
 import a11yConfig from '../config/a11y.config.js';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
 // Project-specific configuration.
 let {
   ignore = {},
@@ -24,23 +22,27 @@ let {
   pa11y: pa11yConfig = {},
 } = a11yConfig;
 
-/** Project-specific accessibility config path used by generated themes. */
-const PROJECT_A11Y_CONFIG = path.resolve(
-  __dirname,
-  '../../../config/emulsify-core/a11y.config.js',
-);
+/**
+ * Resolve the project-specific accessibility config used by generated themes.
+ *
+ * @param {string} [projectDir=process.cwd()] - Consuming project root.
+ * @returns {string} Absolute project config path.
+ */
+const resolveProjectA11yConfig = (projectDir = process.cwd()) =>
+  path.resolve(projectDir, 'config/emulsify-core/a11y.config.js');
 
 /**
  * Load project-specific accessibility config when a consuming project provides one.
  *
  * @returns {Promise<object>} Project accessibility config, when present.
  */
-const loadProjectA11yConfig = async () => {
-  if (!existsSync(PROJECT_A11Y_CONFIG)) {
+const loadProjectA11yConfig = async (projectDir = process.cwd()) => {
+  const configPath = resolveProjectA11yConfig(projectDir);
+  if (!existsSync(configPath)) {
     return {};
   }
 
-  const configModule = await import(pathToFileURL(PROJECT_A11Y_CONFIG).href);
+  const configModule = await import(pathToFileURL(configPath).href);
   return configModule.default || configModule;
 };
 
@@ -90,10 +92,13 @@ const printHelp = () => {
  * Resolve the configured Storybook build directory.
  *
  * @param {string} [buildDir=storybookBuildDir] - Configured build directory.
+ * @param {string} [projectDir=process.cwd()] - Consuming project root.
  * @returns {string} Absolute Storybook build directory.
  */
-const resolveStorybookBuildDir = (buildDir = storybookBuildDir) =>
-  path.resolve(__dirname, '../', buildDir);
+const resolveStorybookBuildDir = (
+  buildDir = storybookBuildDir,
+  projectDir = process.cwd(),
+) => path.resolve(projectDir, buildDir);
 
 /**
  * Resolve Storybook's iframe file used for per-story rendering.
@@ -104,6 +109,75 @@ const resolveStorybookBuildDir = (buildDir = storybookBuildDir) =>
 const resolveStorybookIframe = (buildDir = storybookBuildDir) =>
   path.join(resolveStorybookBuildDir(buildDir), 'iframe.html');
 
+const contentTypes = {
+  '.css': 'text/css; charset=utf-8',
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+};
+
+/**
+ * Start a loopback-only server for a built Storybook.
+ *
+ * Storybook's module graph cannot run reliably from a file URL, so generated
+ * consumers need an HTTP origin before Pa11y evaluates a story.
+ *
+ * @param {string} [buildDir=storybookBuildDir] - Storybook build directory.
+ * @returns {Promise<{baseUrl: string, close: Function}>} Server controls.
+ */
+const startStorybookServer = (buildDir = storybookBuildDir) =>
+  new Promise((resolve, reject) => {
+    const root = resolveStorybookBuildDir(buildDir);
+    const server = createServer((request, response) => {
+      try {
+        const requestUrl = new URL(request.url || '/', 'http://127.0.0.1');
+        const requestedPath =
+          decodeURIComponent(requestUrl.pathname) === '/'
+            ? 'index.html'
+            : decodeURIComponent(requestUrl.pathname).replace(/^\/+/, '');
+        const filePath = path.resolve(root, requestedPath);
+        const relativePath = path.relative(root, filePath);
+
+        if (
+          !relativePath ||
+          relativePath.startsWith('..') ||
+          path.isAbsolute(relativePath) ||
+          !existsSync(filePath) ||
+          !statSync(filePath).isFile()
+        ) {
+          response.writeHead(404);
+          response.end('Not found');
+          return;
+        }
+
+        response.writeHead(200, {
+          'Content-Type':
+            contentTypes[path.extname(filePath)] || 'application/octet-stream',
+        });
+        createReadStream(filePath).pipe(response);
+      } catch {
+        response.writeHead(400);
+        response.end('Bad request');
+      }
+    });
+
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      resolve({
+        baseUrl: `http://127.0.0.1:${address.port}`,
+        close: () =>
+          new Promise((closeResolve, closeReject) => {
+            server.close((error) =>
+              error ? closeReject(error) : closeResolve(),
+            );
+          }),
+      });
+    });
+  });
+
 /**
  * Return unique non-empty Storybook IDs in first-seen order.
  *
@@ -282,10 +356,11 @@ const logReport = ({ issues, pageUrl }) => {
 /**
  * Run pa11y on a single Storybook story by its ID.
  * @param {string} name - Story ID (e.g., "components-button--primary").
+ * @param {{baseUrl?: string}} [options={}] - Storybook origin options.
  * @returns {Promise<{ issues: Pa11yIssue[], pageUrl: string }>} Pa11y result.
  */
-const lintComponent = async (name) =>
-  pa11y(`${resolveStorybookIframe()}?id=${name}`, {
+const lintComponent = async (name, { baseUrl } = {}) =>
+  pa11y(`${baseUrl || resolveStorybookIframe()}?id=${name}`, {
     includeNotices: true,
     includeWarnings: true,
     runners: ['axe'],
@@ -295,10 +370,13 @@ const lintComponent = async (name) =>
 /**
  * Lint a list of components, log reports, and exit(1) if any have issues.
  * @param {string[]} names - List of Storybook story IDs.
+ * @param {{baseUrl?: string}} [options={}] - Storybook origin options.
  * @returns {Promise<void>}
  */
-const lintReportAndExit = async (names) => {
-  const results = await Promise.all(names.map(lintComponent));
+const lintReportAndExit = async (names, options = {}) => {
+  const results = await Promise.all(
+    names.map((name) => lintComponent(name, options)),
+  );
   const hasIssues = results.map(logReport).some(Boolean);
 
   if (hasIssues) {
@@ -311,10 +389,22 @@ const lintReportAndExit = async (names) => {
 if (['-h', '--help'].includes(process.argv[2])) {
   printHelp();
 } else if (process.argv[2] === '-r') {
-  loadProjectA11yConfig().then((projectConfig) => {
-    applyProjectA11yConfig(projectConfig);
-    return lintReportAndExit(resolvePa11yStoryIds());
-  });
+  loadProjectA11yConfig()
+    .then(async (projectConfig) => {
+      applyProjectA11yConfig(projectConfig);
+      const storybookServer = await startStorybookServer();
+      try {
+        await lintReportAndExit(resolvePa11yStoryIds(), {
+          baseUrl: `${storybookServer.baseUrl}/iframe.html`,
+        });
+      } finally {
+        await storybookServer.close();
+      }
+    })
+    .catch((error) => {
+      console.error(error?.stack || error);
+      process.exitCode = 1;
+    });
 }
 
 export {
@@ -328,7 +418,9 @@ export {
   lintReportAndExit,
   normalizeStoryIds,
   resolvePa11yStoryIds,
+  resolveProjectA11yConfig,
   resolveStorybookBuildDir,
   resolveStorybookIframe,
+  startStorybookServer,
   storyIdsFromStorybookIndex,
 };

package/scripts/audit/checks/core-imports.js

@@ -0,0 +1,78 @@
+/**
+ * @file Core import audit check.
+ */
+
+import { lineNumberAt } from '../../lib/text.js';
+import { makeFinding } from '../lib/findings.js';
+import { cachedReadFile } from '../lib/files.js';
+
+const PUBLIC_CORE_IMPORTS = new Set([
+  '@emulsify/core',
+  '@emulsify/core/extensions',
+  '@emulsify/core/extensions/react',
+  '@emulsify/core/extensions/twig',
+  '@emulsify/core/package.json',
+  '@emulsify/core/storybook',
+  '@emulsify/core/vite',
+  '@emulsify/core/vite/plugins',
+]);
+
+/**
+ * Extract import specifiers from JavaScript source.
+ *
+ * @param {string} source - JavaScript source.
+ * @returns {{specifier: string, index: number}[]} Import specifiers.
+ */
+function findImportSpecifiers(source) {
+  const imports = [];
+  const patterns = [
+    /(?:import|export)\s+(?:[^'"]+\s+from\s+)?['"]([^'"]+)['"]/g,
+    /import\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+    /require\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  ];
+
+  for (const pattern of patterns) {
+    for (const match of source.matchAll(pattern)) {
+      imports.push({
+        specifier: match[1],
+        index: match.index || 0,
+      });
+    }
+  }
+
+  return imports;
+}
+
+/**
+ * Audit direct imports of Emulsify Core internals.
+ *
+ * @param {object} context - Audit context.
+ * @returns {object[]} Findings.
+ */
+export function auditCoreImports(context) {
+  const { codeFiles } = context;
+  const findings = [];
+
+  for (const filePath of codeFiles) {
+    const source = cachedReadFile(filePath);
+
+    for (const item of findImportSpecifiers(source)) {
+      const { specifier } = item;
+      if (!specifier.startsWith('@emulsify/core/')) continue;
+      if (PUBLIC_CORE_IMPORTS.has(specifier)) continue;
+
+      findings.push(
+        makeFinding({
+          id: 'internal-core-import',
+          severity: 'warn',
+          filePath,
+          line: lineNumberAt(source, item.index),
+          message: `Import "${specifier}" uses an internal Emulsify Core path. Prefer a public package export.`,
+          docs: 'https://github.com/emulsify-ds/emulsify-core/blob/4.x/README.md#public-imports',
+        }),
+      );
+    }
+  }
+
+  return findings;
+}

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

@@ -0,0 +1,99 @@
+/**
+ * @file CSS asset reference audit check.
+ */
+
+import { dirname, resolve } from 'node:path';
+import { firstExistingPath } from '../../../config/vite/utils/fs-safe.js';
+import { displayPath, makeFinding } from '../lib/findings.js';
+import {
+  cachedReadFile,
+  isInsideAnyRoot,
+  isSameOrInside,
+  safeIsDirectory,
+} from '../lib/files.js';
+import { auditAssetRoots } from '../lib/twig.js';
+import {
+  cssUrlPath,
+  findCssUrlReferences,
+  isNonFilesystemCssUrl,
+  styleRuntimeDirectories,
+} from '../lib/css.js';
+
+/**
+ * Audit local CSS/Sass asset URLs that Vite may leave to runtime resolution.
+ *
+ * @param {object} context - Audit context.
+ * @returns {object[]} Findings.
+ */
+export function auditCssAssetReferences(context) {
+  const { env, projectDir, styleFiles } = context;
+  const findings = [];
+  const projectAssetRoots = auditAssetRoots(env).filter(safeIsDirectory);
+  const styleSourceRoots = env.projectStructure?.sourceRoots || [];
+
+  for (const filePath of styleFiles) {
+    if (
+      styleSourceRoots.length &&
+      !isInsideAnyRoot(filePath, styleSourceRoots)
+    ) {
+      continue;
+    }
+
+    const source = cachedReadFile(filePath);
+    const runtimeDirs = styleRuntimeDirectories(filePath, env, projectDir);
+
+    for (const ref of findCssUrlReferences(source)) {
+      if (isNonFilesystemCssUrl(ref.value)) continue;
+
+      const assetPath = cssUrlPath(ref.value);
+      if (!assetPath) continue;
+
+      const sourceAsset = firstExistingPath([
+        resolve(dirname(filePath), assetPath),
+      ]);
+      const runtimeAsset = firstExistingPath(
+        runtimeDirs.map((directory) => resolve(directory, assetPath)),
+      );
+      const resolvedAsset = sourceAsset || runtimeAsset;
+
+      if (!resolvedAsset) {
+        findings.push(
+          makeFinding({
+            id: 'unresolved-css-asset-reference',
+            severity: 'warn',
+            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',
+          }),
+        );
+        continue;
+      }
+
+      if (
+        projectAssetRoots.some((root) => isSameOrInside(resolvedAsset, root)) &&
+        (!sourceAsset || runtimeAsset || assetPath.startsWith('..'))
+      ) {
+        findings.push(
+          makeFinding({
+            id: 'css-runtime-asset-reference',
+            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.`,
+            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.',
+            ],
+            docs: 'https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/migration-4x.md#css-asset-urls',
+          }),
+        );
+      }
+    }
+  }
+
+  return findings;
+}