@emulsify/core 4.2.1 → 4.3.1

package/scripts/audit/checks/drupal-assumptions.js

@@ -0,0 +1,48 @@
+/**
+ * @file Drupal assumption audit check.
+ */
+
+import { lineNumberAt } from '../../lib/text.js';
+import { makeFinding } from '../lib/findings.js';
+import { cachedReadFile } from '../lib/files.js';
+
+/**
+ * Audit Drupal assumptions in non-Drupal projects.
+ *
+ * @param {object} context - Audit context.
+ * @returns {object[]} Findings.
+ */
+export function auditDrupalAssumptions(context) {
+  const { codeFiles, env } = context;
+  if (env.platform === 'drupal') return [];
+
+  const findings = [];
+  const patterns = [
+    /\bDrupal\.attachBehaviors\b/,
+    /\bwindow\.Drupal\b/,
+    /\bglobalThis\.Drupal\b/,
+    /['"][^'"]*_drupal\.js['"]/,
+    /['"]twig-drupal-filters['"]/,
+  ];
+
+  for (const filePath of codeFiles) {
+    const source = cachedReadFile(filePath);
+    const match = patterns.map((pattern) => pattern.exec(source)).find(Boolean);
+
+    if (!match) continue;
+
+    findings.push(
+      makeFinding({
+        id: 'drupal-assumption-non-drupal',
+        severity: 'warn',
+        filePath,
+        line: lineNumberAt(source, match.index || 0),
+        message:
+          'Drupal-specific Storybook/runtime code was found, but the active platform is not drupal.',
+        docs: 'https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/platform-adapters.md',
+      }),
+    );
+  }
+
+  return findings;
+}

package/scripts/audit/checks/files-outside-roots.js

@@ -0,0 +1,53 @@
+/**
+ * @file Files outside source roots audit check.
+ */
+
+import { displayPath, makeFinding } from '../lib/findings.js';
+import { isInsideAnyRoot } from '../lib/files.js';
+
+/**
+ * Audit files that look like component Twig files outside source roots.
+ *
+ * @param {object} context - Audit context.
+ * @returns {object[]} Findings.
+ */
+export function auditFilesOutsideRoots(context) {
+  const { env, projectDir, twigFiles } = context;
+  const roots = [
+    ...(env.projectStructure?.twigRoots || []),
+    ...(env.projectStructure?.sourceRoots || []),
+  ];
+
+  if (!roots.length) return [];
+
+  return twigFiles
+    .filter((filePath) => !isInsideAnyRoot(filePath, roots))
+    .map((filePath) =>
+      makeFinding({
+        id: 'twig-file-outside-source-roots',
+        severity: 'info',
+        filePath,
+        message:
+          'Twig file is outside normalized source roots and will not be available to Storybook include()/source() unless another integration loads it.',
+        docs: 'https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/project-structure.md',
+      }),
+    )
+    .filter((finding) => !isNonComponentTwigFile(projectDir, finding.filePath));
+}
+
+/**
+ * Determine whether a Twig file is intentionally outside component roots.
+ *
+ * @param {string} projectDir - Absolute project root.
+ * @param {string} filePath - Absolute Twig file path.
+ * @returns {boolean} TRUE when the file should not be treated as component source.
+ */
+function isNonComponentTwigFile(projectDir, filePath) {
+  const relPath = displayPath(projectDir, filePath);
+
+  return (
+    relPath.startsWith('docs/') ||
+    relPath.startsWith('templates/') ||
+    relPath.includes('/templates/')
+  );
+}

package/scripts/audit/checks/generated-package-scripts.js

@@ -0,0 +1,113 @@
+/**
+ * @file Generated package script audit check.
+ */
+
+import { resolve } from 'node:path';
+import {
+  safeExists,
+  safeReadJson,
+} from '../../../config/vite/utils/fs-safe.js';
+import { makeFinding } from '../lib/findings.js';
+import {
+  packageIsEmulsifyCore,
+  packageUsesEmulsifyCore,
+} from '../lib/package-json.js';
+
+const GENERATED_PACKAGE_SCRIPT_DOCS =
+  'https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/migration-4x.md#manual-packagejson-updates';
+
+/**
+ * Audit generated-theme package scripts that must be updated manually.
+ *
+ * Generated themes copy their root package.json from the starter at creation
+ * time. Whisk updates do not automatically flow into existing themes, so the
+ * audit flags stale Webpack-era scripts and missing Core 4 audit/Vite scripts.
+ *
+ * @param {object} context - Audit context.
+ * @returns {object[]} Findings.
+ */
+export function auditGeneratedPackageScripts(context) {
+  const { env, projectDir } = context;
+  const packagePath = resolve(projectDir, 'package.json');
+
+  if (!safeExists(packagePath)) {
+    return [];
+  }
+
+  const { data: packageJson, error } = safeReadJson(packagePath);
+  if (error || !packageUsesEmulsifyCore(packageJson)) {
+    return [];
+  }
+
+  if (packageIsEmulsifyCore(packageJson)) {
+    return [];
+  }
+
+  const scripts = packageJson.scripts || {};
+  const starterRepository = env.projectConfig?.starter?.repository;
+  const fromGeneratedStarter =
+    typeof starterRepository === 'string' &&
+    /emulsify-(drupal|wordpress|craftcms|starter)|emulsify-ds/i.test(
+      starterRepository,
+    );
+  const usesGeneratedCoreScripts = Object.values(scripts).some(
+    (script) =>
+      typeof script === 'string' &&
+      /node_modules\/@emulsify\/core\/(?:config\/(?:webpack|vite)|scripts\/audit)/.test(
+        script,
+      ),
+  );
+
+  if (!fromGeneratedStarter && !usesGeneratedCoreScripts) {
+    return [];
+  }
+
+  const findings = [];
+  const details = [];
+  const buildScript = scripts.build || '';
+
+  if (/\bwebpack\b|config\/webpack/.test(buildScript)) {
+    details.push('Replace scripts.build with the Vite build command.');
+  } else if (
+    /node_modules\/@emulsify\/core\/config\/vite\/vite\.config\.js/.test(
+      buildScript,
+    ) &&
+    /\bvite\s+(?:--config|-c)\b/.test(buildScript)
+  ) {
+    details.push('Replace scripts.build with the Vite build command.');
+  }
+
+  if (Object.prototype.hasOwnProperty.call(scripts, 'build-dev')) {
+    details.push('Remove scripts.build-dev; the Vite build replaces it.');
+  }
+
+  if (/\bwebpack\b|npm:webpack|config\/webpack/.test(scripts.develop || '')) {
+    details.push('Replace scripts.develop with the Vite/Storybook watcher.');
+  }
+
+  if (Object.prototype.hasOwnProperty.call(scripts, 'webpack')) {
+    details.push('Replace scripts.webpack with scripts.vite.');
+  }
+
+  for (const scriptName of ['audit', 'audit:twig-stories', 'vite']) {
+    if (!Object.prototype.hasOwnProperty.call(scripts, scriptName)) {
+      details.push(`Add scripts.${scriptName}.`);
+    }
+  }
+
+  if (details.length) {
+    findings.push(
+      makeFinding({
+        id: 'generated-package-json-migration-needed',
+        severity: 'warn',
+        filePath: packagePath,
+        message:
+          'package.json does not match the generated-theme scripts expected by Emulsify Core 4.',
+        details,
+        docs: GENERATED_PACKAGE_SCRIPT_DOCS,
+      }),
+    );
+  }
+
+  return findings;
+}

package/scripts/audit/checks/legacy-twig-stories.js

@@ -0,0 +1,33 @@
+/**
+ * @file Legacy Twig story audit check.
+ */
+
+import { analyzeStorySource } from '../../audit-twig-stories.js';
+import { makeFinding } from '../lib/findings.js';
+import { cachedReadFile } from '../lib/files.js';
+
+/**
+ * Add legacy Twig story migration findings.
+ *
+ * @param {object} context - Audit context.
+ * @returns {object[]} Findings.
+ */
+export function auditLegacyTwigStories(context) {
+  const { storyFiles } = context;
+  const findings = storyFiles
+    .map((filePath) => analyzeStorySource(cachedReadFile(filePath), filePath))
+    .filter((result) => result.shouldUpgrade);
+
+  return findings.map((finding) =>
+    makeFinding({
+      id: 'legacy-twig-story',
+      severity: 'warn',
+      filePath: finding.filePath,
+      line: finding.directTemplateReturns[0]?.line,
+      message:
+        'Twig story appears to return an HTML string directly. This remains compatible, but renderTwig() is preferred for active migrations.',
+      details: finding.reasons,
+      docs: 'https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/storybook.md#legacy-twig-story-compatibility',
+    }),
+  );
+}

package/scripts/audit/checks/package-overrides.js

@@ -0,0 +1,91 @@
+/**
+ * @file Package override audit check.
+ */
+
+import { resolve } from 'node:path';
+import {
+  safeExists,
+  safeReadJson,
+} from '../../../config/vite/utils/fs-safe.js';
+import { makeFinding } from '../lib/findings.js';
+import {
+  hasRecommendedOverride,
+  packageUsesEmulsifyCore,
+} from '../lib/package-json.js';
+
+const RECOMMENDED_PACKAGE_OVERRIDES = [
+  {
+    label: 'glob',
+    value: '^13.0.6',
+    paths: [['glob']],
+  },
+  {
+    label: 'locutus',
+    value: '^3.0.36',
+    paths: [['locutus']],
+  },
+  {
+    label: 'minimatch@3.0.x',
+    value: '^3.1.5',
+    paths: [['minimatch@3.0.x']],
+  },
+];
+
+/**
+ * Audit package-level dependency override policy for installed projects.
+ *
+ * npm only applies `overrides` from the root package being installed. When
+ * Emulsify Core is installed into a generated theme, Core's own overrides do
+ * not protect that theme's transitive dependency graph.
+ *
+ * @param {object} context - Audit context.
+ * @returns {object[]} Findings.
+ */
+export function auditPackageOverrides(context) {
+  const { projectDir } = context;
+  const packagePath = resolve(projectDir, 'package.json');
+
+  if (!safeExists(packagePath)) {
+    return [];
+  }
+
+  const { data: packageJson, error } = safeReadJson(packagePath);
+  if (error) {
+    return [
+      makeFinding({
+        id: 'package-json-unreadable',
+        severity: 'warn',
+        filePath: packagePath,
+        message: `Unable to parse package.json: ${error.message || error}`,
+      }),
+    ];
+  }
+
+  if (!packageUsesEmulsifyCore(packageJson)) {
+    return [];
+  }
+
+  const overrides = packageJson.overrides || {};
+  const missing = RECOMMENDED_PACKAGE_OVERRIDES.filter(
+    (recommendation) => !hasRecommendedOverride(overrides, recommendation),
+  );
+
+  if (!missing.length) {
+    return [];
+  }
+
+  return [
+    makeFinding({
+      id: 'recommended-package-overrides-missing',
+      severity: 'warn',
+      filePath: packagePath,
+      message:
+        'package.json is missing recommended root npm overrides for Emulsify Core transitive install warnings.',
+      details: missing.map(
+        (recommendation) =>
+          `Add overrides.${recommendation.label}: ${recommendation.value}.`,
+      ),
+      docs: 'https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/migration-4x.md#install-warning-controls',
+    }),
+  ];
+}

package/scripts/audit/checks/project-config.js

@@ -0,0 +1,71 @@
+/**
+ * @file Project configuration audit check.
+ */
+
+import { resolve } from 'node:path';
+import { displayPath, makeFinding } from '../lib/findings.js';
+import { safeIsDirectory } from '../lib/files.js';
+
+/**
+ * Audit basic project configuration and structure root health.
+ *
+ * @param {object} context - Audit context.
+ * @returns {object[]} Findings.
+ */
+export function auditProjectConfig(context) {
+  const { configExists, env, error, projectDir } = context;
+  const findings = [];
+
+  if (!configExists) {
+    findings.push(
+      makeFinding({
+        id: 'missing-project-config',
+        severity: 'error',
+        message:
+          'project.emulsify.json is missing, so platform and structure defaults may not match the project.',
+        docs: 'https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/project-structure.md',
+      }),
+    );
+  }
+
+  if (error) {
+    findings.push(
+      makeFinding({
+        id: 'project-config-resolution-failed',
+        severity: 'error',
+        message: `Unable to resolve project.emulsify.json: ${error.message || error}`,
+      }),
+    );
+  }
+
+  for (const implementation of env.structureImplementations || []) {
+    if (!safeIsDirectory(implementation.directory)) {
+      findings.push(
+        makeFinding({
+          id: 'missing-structure-implementation',
+          severity: 'error',
+          filePath: resolve(projectDir, 'project.emulsify.json'),
+          message: `Configured structureImplementation "${implementation.name}" does not exist: ${displayPath(
+            projectDir,
+            implementation.directory,
+          )}`,
+          docs: 'https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/project-structure.md',
+        }),
+      );
+    }
+  }
+
+  for (const root of env.ignoredAssetRoots || []) {
+    findings.push(
+      makeFinding({
+        id: 'invalid-asset-root',
+        severity: 'warn',
+        filePath: resolve(projectDir, 'project.emulsify.json'),
+        message: `Configured asset root "${root}" was ignored because it resolves outside the project root.`,
+        docs: 'https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/project-structure.md#asset-roots',
+      }),
+    );
+  }
+
+  return findings;
+}

package/scripts/audit/checks/story-discovery.js

@@ -0,0 +1,35 @@
+/**
+ * @file Story discovery audit check.
+ */
+
+import { collectStoryFiles } from '../../audit-twig-stories.js';
+import { makeFinding } from '../lib/findings.js';
+
+/**
+ * Audit story files that will not be discovered by Storybook.
+ *
+ * @param {object} context - Audit context.
+ * @returns {object[]} Findings.
+ */
+export function auditStoryDiscovery(context) {
+  const { projectDir, storyFiles } = context;
+  const discovered = new Set(collectStoryFiles(projectDir));
+  const findings = [];
+
+  for (const storyFile of storyFiles) {
+    if (discovered.has(storyFile)) continue;
+
+    findings.push(
+      makeFinding({
+        id: 'story-outside-discovered-roots',
+        severity: 'error',
+        filePath: storyFile,
+        message:
+          'Story file is outside the normalized Storybook roots and will not be discovered.',
+        docs: 'https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/project-structure.md',
+      }),
+    );
+  }
+
+  return findings;
+}

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

@@ -0,0 +1,69 @@
+/**
+ * @file Twig reference audit check.
+ */
+
+import { resolve } from 'node:path';
+import { makeFinding } from '../lib/findings.js';
+import { cachedReadFile } from '../lib/files.js';
+import {
+  findTwigIncludeSourceReferences,
+  findTwigNamespaceReferences,
+  resolvesTwigReference,
+} from '../lib/twig.js';
+
+/**
+ * Audit Twig namespace and include/source resolution.
+ *
+ * @param {object} context - Audit context.
+ * @returns {object[]} Findings.
+ */
+export function auditTwigReferences(context) {
+  const { env, projectDir, twigFiles } = context;
+  const namespaceRoots = env.namespaceRoots || {};
+  const knownNamespaces = new Set([...Object.keys(namespaceRoots), 'assets']);
+  const findings = [];
+  const seen = new Set();
+
+  for (const twigFile of twigFiles) {
+    const source = cachedReadFile(twigFile);
+
+    for (const ref of findTwigNamespaceReferences(source)) {
+      if (knownNamespaces.has(ref.namespace)) continue;
+
+      const key = `${twigFile}:${ref.line}:unknown:${ref.namespace}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      findings.push(
+        makeFinding({
+          id: 'unknown-twig-namespace',
+          severity: 'warn',
+          filePath: twigFile,
+          line: ref.line,
+          message: `Twig namespace "@${ref.namespace}" is not configured in the normalized project structure.`,
+          docs: 'https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/project-structure.md#twig-namespaces',
+        }),
+      );
+    }
+
+    for (const ref of findTwigIncludeSourceReferences(source)) {
+      if (!resolvesTwigReference(ref.value, twigFile, env)) {
+        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.`,
+            docs: 'https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/storybook.md#include',
+          }),
+        );
+      }
+    }
+  }
+
+  return findings.map((finding) => ({
+    ...finding,
+    filePath: finding.filePath || resolve(projectDir, 'project.emulsify.json'),
+  }));
+}

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

@@ -0,0 +1,54 @@
+/**
+ * @file Twig volume audit check.
+ */
+
+import { resolve } from 'node:path';
+import { globSync } from 'glob';
+import { directorySize } from '../../lib/fs.js';
+import { makeFinding } from '../lib/findings.js';
+import { DEFAULT_IGNORES, safeIsDirectory } from '../lib/files.js';
+
+const TWIG_GLOB = '**/*.twig';
+
+/**
+ * Audit Twig volume under Storybook roots.
+ *
+ * @param {object} context - Audit context.
+ * @returns {object[]} Findings.
+ */
+export function auditTwigVolume(context) {
+  const { env, twigThreshold } = context;
+  const roots = Array.from(new Set(env.projectStructure?.twigRoots || []));
+  const twigFiles = new Set();
+
+  for (const root of roots) {
+    if (!safeIsDirectory(root)) continue;
+    for (const filePath of globSync(TWIG_GLOB, {
+      cwd: root,
+      absolute: true,
+      nodir: true,
+      ignore: DEFAULT_IGNORES,
+    })) {
+      twigFiles.add(resolve(filePath));
+    }
+  }
+
+  if (twigFiles.size <= twigThreshold) return [];
+
+  const totalBytes = roots.reduce(
+    (total, root) => total + directorySize(root),
+    0,
+  );
+
+  return [
+    makeFinding({
+      id: 'large-twig-storybook-roots',
+      severity: 'info',
+      message: `${twigFiles.size} Twig files are under Storybook Twig roots. Eager Twig imports are reliable but can increase Storybook startup/build cost for large libraries.`,
+      details: [
+        `Approximate Twig root size: ${Math.round(totalBytes / 1024)} KB.`,
+      ],
+      docs: 'https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/performance.md#storybook-twig-imports',
+    }),
+  ];
+}

package/scripts/audit/checks/webpack-patterns.js

@@ -0,0 +1,86 @@
+/**
+ * @file Webpack-era pattern audit check.
+ */
+
+import { resolve } from 'node:path';
+import { safeExists } from '../../../config/vite/utils/fs-safe.js';
+import { lineNumberAt } from '../../lib/text.js';
+import { makeFinding } from '../lib/findings.js';
+import { cachedReadFile, safeIsDirectory } from '../lib/files.js';
+
+/**
+ * Audit Webpack-era files and code patterns.
+ *
+ * @param {object} context - Audit context.
+ * @returns {object[]} Findings.
+ */
+export function auditWebpackPatterns(context) {
+  const { codeFiles, projectDir } = context;
+  const findings = [];
+  const webpackConfig = resolve(projectDir, '.storybook/webpack.config.js');
+  const webpackDir = resolve(projectDir, 'config/webpack');
+
+  if (safeExists(webpackConfig)) {
+    findings.push(
+      makeFinding({
+        id: 'webpack-config-file',
+        severity: 'warn',
+        filePath: webpackConfig,
+        message:
+          'Webpack-specific Storybook config is present and should be migrated to Vite/Storybook overrides.',
+        docs: 'https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/migration-4x.md#vite-customization',
+      }),
+    );
+  }
+
+  if (safeIsDirectory(webpackDir)) {
+    findings.push(
+      makeFinding({
+        id: 'webpack-config-directory',
+        severity: 'warn',
+        filePath: webpackDir,
+        message:
+          'config/webpack exists. Webpack-specific customization should move to Vite plugins or extendConfig().',
+        docs: 'https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/extension-points.md#vite-plugins-and-config-patches',
+      }),
+    );
+  }
+
+  const patterns = [
+    {
+      regex: /\brequire\.context\s*\(/,
+      message: 'require.context() is Webpack-specific and should be migrated.',
+    },
+    {
+      regex:
+        /\b(raw-loader|twig-loader|style-loader|file-loader|sass-loader)\b/,
+      message: 'Webpack loader references should be migrated to Vite plugins.',
+    },
+    {
+      regex: /from\s+['"][^'"]+![^'"]+['"]|import\s+['"][^'"]+![^'"]+['"]/,
+      message: 'Inline Webpack loader import syntax should be removed.',
+    },
+  ];
+
+  for (const filePath of codeFiles) {
+    const source = cachedReadFile(filePath);
+
+    for (const pattern of patterns) {
+      const match = pattern.regex.exec(source);
+      if (!match) continue;
+
+      findings.push(
+        makeFinding({
+          id: 'webpack-era-pattern',
+          severity: 'warn',
+          filePath,
+          line: lineNumberAt(source, match.index || 0),
+          message: pattern.message,
+          docs: 'https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/migration-4x.md#vite-customization',
+        }),
+      );
+    }
+  }
+
+  return findings;
+}