@emulsify/core 4.2.1 → 4.3.0

package/scripts/audit/index.js

@@ -0,0 +1,177 @@
+/**
+ * @file Audit orchestration and check registry.
+ */
+
+import { resolve } from 'node:path';
+import { resolveProjectConfig } from '../../config/vite/project-config.js';
+import { safeExists } from '../../config/vite/utils/fs-safe.js';
+import { auditCoreImports } from './checks/core-imports.js';
+import { auditCssAssetReferences } from './checks/css-asset-references.js';
+import { auditDrupalAssumptions } from './checks/drupal-assumptions.js';
+import { auditFilesOutsideRoots } from './checks/files-outside-roots.js';
+import { auditGeneratedPackageScripts } from './checks/generated-package-scripts.js';
+import { auditLegacyTwigStories } from './checks/legacy-twig-stories.js';
+import { auditPackageOverrides } from './checks/package-overrides.js';
+import { auditProjectConfig } from './checks/project-config.js';
+import { auditStoryDiscovery } from './checks/story-discovery.js';
+import { auditTwigReferences } from './checks/twig-references.js';
+import { auditTwigVolume } from './checks/twig-volume.js';
+import { auditWebpackPatterns } from './checks/webpack-patterns.js';
+import {
+  collectRootedProjectFiles,
+  normalizeAuditRoots,
+  resetFileReadCache,
+} from './lib/files.js';
+
+const STORY_GLOB = '**/*.stories.{js,jsx,ts,tsx}';
+const CODE_GLOB = '**/*.{js,jsx,ts,tsx,mjs,cjs}';
+const TWIG_GLOB = '**/*.twig';
+const STYLE_GLOB = '**/*.{css,scss,sass}';
+
+export const DEFAULT_TWIG_THRESHOLD = 250;
+
+export const auditChecks = [
+  auditProjectConfig,
+  auditPackageOverrides,
+  auditGeneratedPackageScripts,
+  auditStoryDiscovery,
+  auditLegacyTwigStories,
+  auditTwigReferences,
+  auditCssAssetReferences,
+  auditWebpackPatterns,
+  auditCoreImports,
+  auditDrupalAssumptions,
+  auditFilesOutsideRoots,
+  auditTwigVolume,
+];
+
+/**
+ * Normalize the project config, retaining any resolution failure.
+ *
+ * @param {string} projectDir - Absolute project root.
+ * @returns {{env: object, configExists: boolean, error?: Error}}
+ */
+function resolveAuditEnvironment(projectDir) {
+  const configExists = safeExists(resolve(projectDir, 'project.emulsify.json'));
+
+  try {
+    return {
+      env: resolveProjectConfig(projectDir, process.env),
+      configExists,
+    };
+  } catch (error) {
+    return {
+      env: {
+        projectDir,
+        platform: 'none',
+        namespaceRoots: {},
+        projectStructure: {},
+      },
+      configExists,
+      error,
+    };
+  }
+}
+
+/**
+ * Build the shared context passed to every audit check.
+ *
+ * @param {{projectDir?: string, twigThreshold?: number}} [options={}] - Options.
+ * @returns {object} Audit context.
+ */
+export function createAuditContext(options = {}) {
+  const projectDir = resolve(options.projectDir || process.cwd());
+  const envResult = resolveAuditEnvironment(projectDir);
+  const structure = envResult.env.projectStructure || {};
+  const sourceRoots = normalizeAuditRoots(
+    projectDir,
+    structure.sourceRoots || [],
+  );
+  const storyRoots = normalizeAuditRoots(
+    projectDir,
+    structure.storyRoots || sourceRoots,
+  );
+  const twigRoots = normalizeAuditRoots(
+    projectDir,
+    structure.twigRoots || sourceRoots,
+  );
+  const storyFiles = collectRootedProjectFiles(
+    projectDir,
+    STORY_GLOB,
+    storyRoots,
+  );
+  const codeFiles = collectRootedProjectFiles(
+    projectDir,
+    CODE_GLOB,
+    sourceRoots,
+  );
+  const twigFiles = collectRootedProjectFiles(projectDir, TWIG_GLOB, twigRoots);
+  const styleFiles = collectRootedProjectFiles(
+    projectDir,
+    STYLE_GLOB,
+    sourceRoots,
+  );
+
+  return {
+    ...envResult,
+    projectDir,
+    sourceRoots,
+    storyRoots,
+    twigRoots,
+    storyFiles,
+    codeFiles,
+    twigFiles,
+    styleFiles,
+    twigThreshold: Number.isFinite(options.twigThreshold)
+      ? options.twigThreshold
+      : DEFAULT_TWIG_THRESHOLD,
+  };
+}
+
+/**
+ * Run all registered checks against a prepared audit context.
+ *
+ * @param {object} context - Audit context.
+ * @returns {object[]} Findings.
+ */
+export function runAuditChecks(context) {
+  return auditChecks.flatMap((check) => check(context));
+}
+
+/**
+ * Run the combined Emulsify audit.
+ *
+ * @param {{projectDir?: string, twigThreshold?: number}} [options={}] - Options.
+ * @returns {{projectDir: string, summary: object, files: object, findings: object[]}} Audit result.
+ */
+export function runAudits(options = {}) {
+  resetFileReadCache();
+
+  const context = createAuditContext(options);
+  const findings = runAuditChecks(context);
+  const summary = findings.reduce(
+    (totals, finding) => ({
+      ...totals,
+      [finding.severity]: (totals[finding.severity] || 0) + 1,
+    }),
+    {
+      error: 0,
+      warn: 0,
+      info: 0,
+    },
+  );
+
+  return {
+    projectDir: context.projectDir,
+    summary,
+    files: {
+      stories: context.storyFiles.length,
+      twig: context.twigFiles.length,
+      code: context.codeFiles.length,
+      styles: context.styleFiles.length,
+    },
+    findings,
+  };
+}
+
+export { runAudits as auditProject };

package/scripts/audit/lib/css.js

@@ -0,0 +1,165 @@
+/**
+ * @file CSS and Sass URL parsing helpers for the project audit.
+ */
+
+import { basename, dirname, resolve } from 'node:path';
+import {
+  compiledAssetOutputPath,
+  storybookStyleOutputPath,
+} from '../../../config/vite/project-structure.js';
+import { lineNumberAt } from '../../lib/text.js';
+
+/**
+ * Extract simple same-file Sass string variables.
+ *
+ * @param {string} source - Stylesheet source.
+ * @returns {Map<string, string>} Variable value map.
+ */
+function findSassStringVariables(source) {
+  const variables = new Map();
+  const pattern = /^\s*\$([\w-]+)\s*:\s*(['"])(.*?)\2\s*;?/gm;
+
+  for (const match of source.matchAll(pattern)) {
+    variables.set(match[1], match[3]);
+  }
+
+  return variables;
+}
+
+/**
+ * Resolve same-file Sass variable interpolation in a URL value.
+ *
+ * This intentionally handles only simple string variables. It is enough to make
+ * common asset roots such as `#{$font-url}/Avenir.woff2` auditable without
+ * pretending to be a Sass compiler.
+ *
+ * @param {string} value - Raw URL value.
+ * @param {Map<string, string>} variables - Sass variable map.
+ * @returns {string} URL value with known interpolations expanded.
+ */
+function resolveSassUrlValue(value, variables) {
+  return value.replace(/#\{\$([\w-]+)\}/g, (match, name) =>
+    variables.has(name) ? variables.get(name) : match,
+  );
+}
+
+/**
+ * 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.
+ *
+ * @param {string} source - Stylesheet source.
+ * @returns {{value: string, raw: string, line: number}[]} URL references.
+ */
+export function findCssUrlReferences(source) {
+  const scanSource = maskStyleComments(source);
+  const variables = findSassStringVariables(scanSource);
+  const references = [];
+  const pattern = /url\(\s*(?:(['"])(.*?)\1|([^'")][^)]*?))\s*\)/g;
+
+  for (const match of scanSource.matchAll(pattern)) {
+    const raw = (match[2] ?? match[3] ?? '').trim();
+    const value = resolveSassUrlValue(raw, variables).trim();
+
+    references.push({
+      value,
+      raw,
+      line: lineNumberAt(source, match.index || 0),
+    });
+  }
+
+  return references;
+}
+
+/**
+ * Determine whether a CSS URL should be skipped by filesystem checks.
+ *
+ * @param {string} value - URL value.
+ * @returns {boolean} TRUE when the URL is not a local relative asset path.
+ */
+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)
+  );
+}
+
+/**
+ * Remove query string and hash suffixes from a URL path.
+ *
+ * @param {string} value - URL value.
+ * @returns {string} Path portion.
+ */
+export function cssUrlPath(value) {
+  return value.split(/[?#]/)[0];
+}
+
+/**
+ * Resolve an emitted CSS output key to the actual CSS file path.
+ *
+ * Vite entry keys use `__style` internally to avoid JS/CSS collisions. The
+ * shared Vite config removes that suffix from emitted CSS file names.
+ *
+ * @param {string} key - Output key without extension.
+ * @returns {string} Emitted CSS file path relative to output root.
+ */
+function emittedCssRelativePath(key) {
+  return `${key.replace(/__style$/i, '')}.css`;
+}
+
+/**
+ * Return possible runtime directories for a style file's emitted CSS.
+ *
+ * @param {string} filePath - Source stylesheet.
+ * @param {object} env - Normalized environment.
+ * @param {string} projectDir - Project root.
+ * @returns {string[]} Absolute runtime directories.
+ */
+export function styleRuntimeDirectories(filePath, env, projectDir) {
+  if (!/\.(scss|sass|css)$/i.test(filePath)) return [];
+  if (basename(filePath).startsWith('_')) return [];
+
+  const structure = env.projectStructure || {};
+  if (!structure.output) return [];
+
+  const ctx = {
+    projectDir,
+    srcDir: env.srcDir || resolve(projectDir, 'src'),
+    SDC: Boolean(env.SDC),
+  };
+  const fileName = basename(filePath);
+  const isStorybookStyle = /^(cl-|sb-)/.test(fileName);
+  const key = isStorybookStyle
+    ? storybookStyleOutputPath(filePath, structure, ctx)
+    : compiledAssetOutputPath(filePath, 'css', structure, ctx);
+
+  if (!key) return [];
+
+  const relCss = emittedCssRelativePath(key);
+  const directories = [dirname(resolve(projectDir, 'dist', relCss))];
+
+  if (structure.mirrorComponentOutput && relCss.startsWith('components/')) {
+    directories.push(dirname(resolve(projectDir, relCss)));
+  }
+
+  return Array.from(new Set(directories));
+}

package/scripts/audit/lib/files.js

@@ -0,0 +1,168 @@
+/**
+ * @file Filesystem helpers for the project audit.
+ */
+
+import { lstatSync } from 'node:fs';
+import { relative, resolve, sep } from 'node:path';
+import { globSync } from 'glob';
+import {
+  safeExists,
+  safeReadFile,
+} from '../../../config/vite/utils/fs-safe.js';
+
+export const DEFAULT_IGNORES = [
+  '**/.coverage/**',
+  '**/.git/**',
+  '**/.github/**',
+  '**/.out/**',
+  '**/dist/**',
+  '**/*.min.css',
+  '**/*.test.{js,jsx,ts,tsx,mjs,cjs}',
+  '**/node_modules/**',
+  '**/scripts/audit.js',
+  '**/vendor/**',
+];
+
+/**
+ * Cache source file reads for one top-level audit run.
+ *
+ * @type {Map<string, string|null>}
+ */
+const fileReadCache = new Map();
+
+/**
+ * Clear the per-run source file read cache.
+ *
+ * @returns {void}
+ */
+export function resetFileReadCache() {
+  fileReadCache.clear();
+}
+
+/**
+ * Read a text source file once per top-level audit run.
+ *
+ * Missing files are cached as null internally but still return an empty string
+ * to preserve safeReadFile() behavior for existing checks.
+ *
+ * @param {string} filePath - Absolute or relative file path.
+ * @returns {string} File contents, or an empty string when unavailable.
+ */
+export function cachedReadFile(filePath) {
+  const absPath = resolve(filePath);
+  if (fileReadCache.has(absPath)) {
+    return fileReadCache.get(absPath) ?? '';
+  }
+
+  const source = safeReadFile(absPath);
+  const cachedSource = source === '' && !safeExists(absPath) ? null : source;
+  fileReadCache.set(absPath, cachedSource);
+
+  return cachedSource ?? '';
+}
+
+/**
+ * Determine whether a candidate is a directory.
+ *
+ * @param {string} filePath - Absolute path.
+ * @returns {boolean} TRUE when the path is a directory.
+ */
+export function safeIsDirectory(filePath) {
+  try {
+    return lstatSync(filePath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Collect files from a project.
+ *
+ * @param {string} projectDir - Absolute project root.
+ * @param {string|string[]} patterns - Glob pattern or patterns.
+ * @returns {string[]} Absolute file paths.
+ */
+export function collectProjectFiles(projectDir, patterns) {
+  return globSync(patterns, {
+    cwd: projectDir,
+    nodir: true,
+    absolute: true,
+    ignore: DEFAULT_IGNORES,
+  })
+    .map((filePath) => resolve(filePath))
+    .sort();
+}
+
+/**
+ * Return a normalized, project-contained root list.
+ *
+ * @param {string} projectDir - Absolute project root.
+ * @param {string[]} roots - Absolute candidate roots.
+ * @returns {string[]} Existing roots inside the project.
+ */
+export function normalizeAuditRoots(projectDir, roots = []) {
+  const resolvedProject = resolve(projectDir);
+
+  return Array.from(
+    new Set(
+      roots
+        .filter(Boolean)
+        .map((root) => resolve(root))
+        .filter(
+          (root) =>
+            isSameOrInside(root, resolvedProject) && safeIsDirectory(root),
+        ),
+    ),
+  ).sort();
+}
+
+/**
+ * Collect files from normalized audit roots only.
+ *
+ * @param {string} projectDir - Absolute project root.
+ * @param {string|string[]} patterns - Glob pattern or patterns.
+ * @param {string[]} roots - Absolute roots to scan.
+ * @returns {string[]} Absolute file paths.
+ */
+export function collectRootedProjectFiles(projectDir, patterns, roots = []) {
+  const files = new Set();
+
+  for (const root of normalizeAuditRoots(projectDir, roots)) {
+    for (const filePath of globSync(patterns, {
+      cwd: root,
+      nodir: true,
+      absolute: true,
+      ignore: DEFAULT_IGNORES,
+    })) {
+      files.add(resolve(filePath));
+    }
+  }
+
+  return Array.from(files).sort();
+}
+
+/**
+ * Determine whether a file is inside one of the roots.
+ *
+ * @param {string} filePath - Absolute file path.
+ * @param {string[]} roots - Absolute roots.
+ * @returns {boolean} TRUE when inside a root.
+ */
+export function isInsideAnyRoot(filePath, roots = []) {
+  return roots.some((root) => {
+    const rel = relative(root, filePath);
+    return Boolean(rel) && !rel.startsWith('..') && !rel.includes(`..${sep}`);
+  });
+}
+
+/**
+ * Determine whether a path is the same as, or inside, a root directory.
+ *
+ * @param {string} filePath - Absolute file path.
+ * @param {string} root - Absolute root path.
+ * @returns {boolean} TRUE when the path is inside or equal to the root.
+ */
+export function isSameOrInside(filePath, root) {
+  const rel = relative(root, filePath);
+  return !rel || (!rel.startsWith('..') && !rel.includes(`..${sep}`));
+}

package/scripts/audit/lib/findings.js

@@ -0,0 +1,31 @@
+/**
+ * @file Finding and report-path helpers for the project audit.
+ */
+
+import { relative } from 'node:path';
+import { toPosixPath } from '../../../config/vite/utils/paths.js';
+
+/**
+ * Return a project-relative path for report output.
+ *
+ * @param {string} projectDir - Absolute project root.
+ * @param {string} filePath - Absolute file path.
+ * @returns {string} Project-relative POSIX path.
+ */
+export function displayPath(projectDir, filePath) {
+  return toPosixPath(relative(projectDir, filePath));
+}
+
+/**
+ * Build a report finding.
+ *
+ * @param {object} finding - Finding details.
+ * @returns {object} Normalized finding.
+ */
+export function makeFinding(finding) {
+  return {
+    severity: 'warn',
+    docs: undefined,
+    ...finding,
+  };
+}

package/scripts/audit/lib/package-json.js

@@ -0,0 +1,65 @@
+/**
+ * @file Package manifest helpers for the project audit.
+ */
+
+/**
+ * Return a nested object value.
+ *
+ * @param {object} obj - Object to inspect.
+ * @param {string[]} pathParts - Nested object path.
+ * @returns {*} Nested value.
+ */
+export function valueAtPath(obj, pathParts) {
+  return pathParts.reduce(
+    (current, key) =>
+      current && typeof current === 'object' ? current[key] : undefined,
+    obj,
+  );
+}
+
+/**
+ * Determine whether a package manifest depends on Emulsify Core.
+ *
+ * @param {object} packageJson - Parsed package.json.
+ * @returns {boolean} TRUE when package.json is Core or consumes Core.
+ */
+export function packageUsesEmulsifyCore(packageJson = {}) {
+  if (packageJson.name === '@emulsify/core') {
+    return true;
+  }
+
+  return [
+    'dependencies',
+    'devDependencies',
+    'peerDependencies',
+    'optionalDependencies',
+  ].some((section) =>
+    Object.prototype.hasOwnProperty.call(
+      packageJson[section] || {},
+      '@emulsify/core',
+    ),
+  );
+}
+
+/**
+ * Determine whether a package manifest is Emulsify Core itself.
+ *
+ * @param {object} packageJson - Parsed package.json.
+ * @returns {boolean} TRUE when package.json is Core.
+ */
+export function packageIsEmulsifyCore(packageJson = {}) {
+  return packageJson.name === '@emulsify/core';
+}
+
+/**
+ * Determine whether a recommended override is already present.
+ *
+ * @param {object} overrides - package.json overrides object.
+ * @param {{paths: string[][]}} recommendation - Override recommendation.
+ * @returns {boolean} TRUE when any equivalent override path exists.
+ */
+export function hasRecommendedOverride(overrides = {}, recommendation) {
+  return recommendation.paths.some(
+    (pathParts) => valueAtPath(overrides, pathParts) !== undefined,
+  );
+}