@emulsify/core 4.3.2 → 4.5.0

package/scripts/audit/lib/twig.js

@@ -2,8 +2,13 @@
  * @file Twig reference parsing and resolution helpers for the project audit.
  */
 
-import { dirname, isAbsolute, resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
+import {
+  resolveAssetRoots,
+  toAbsoluteAssetRoot,
+} from '../../../config/vite/utils/asset-roots.js';
 import { safeExists } from '../../../config/vite/utils/fs-safe.js';
+import { resolveComponentReference } from '../../../config/vite/utils/twig-component-resolver.js';
 import { candidateKeysForReference } from '../../../src/storybook/twig/reference-paths.js';
 import { lineNumberAt } from '../../lib/text.js';
 import { isSameOrInside } from './files.js';
@@ -11,76 +16,370 @@ import { isSameOrInside } from './files.js';
 const GENERATED_ASSET_ALIASES = new Set(['icons.svg']);
 
 /**
- * Extract string arguments passed to include() or source().
+ * Mask Twig comments without changing offsets or line breaks.
+ *
+ * Quotes inside Twig expressions protect literal comment markers. HTML quotes
+ * do not, because Twig comments can also appear inside HTML attributes.
  *
  * @param {string} source - Twig source.
- * @returns {{type: string, value: string, line: number}[]} References.
+ * @param {boolean} [codeOnly=false] - Also mask quoted strings and non-Twig text.
+ * @returns {string} Source with comment text replaced by whitespace.
  */
-export function findTwigIncludeSourceReferences(source) {
-  const references = [];
-  const callPattern = /\b(include|source)\s*\(([\s\S]*?)\)/g;
-
-  for (const callMatch of source.matchAll(callPattern)) {
-    const type = callMatch[1];
-    const args = firstArgumentText(callMatch[2]);
-    const argsOffset = (callMatch.index || 0) + callMatch[0].indexOf(args);
-    const stringPattern = /['"]([^'"]+)['"]/g;
-
-    for (const stringMatch of args.matchAll(stringPattern)) {
-      references.push({
-        type,
-        value: stringMatch[1],
-        line: lineNumberAt(source, argsOffset + (stringMatch.index || 0)),
-      });
+function maskTwigSource(source, codeOnly = false) {
+  const characters = source.split('');
+  let closingTag = '';
+  let quote = '';
+
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index];
+    const pair = source.slice(index, index + 2);
+    if (codeOnly && (quote || !closingTag) && char !== '\n' && char !== '\r') {
+      characters[index] = ' ';
+    }
+    if (quote) {
+      if (char === '\\') {
+        index += 1;
+        if (
+          codeOnly &&
+          index < source.length &&
+          source[index] !== '\n' &&
+          source[index] !== '\r'
+        ) {
+          characters[index] = ' ';
+        }
+      } else if (char === quote) quote = '';
+    } else if (pair === '{#') {
+      const close = source.indexOf('#}', index + 2);
+      const end = close === -1 ? source.length : close + 2;
+      for (; index < end; index += 1) {
+        if (source[index] !== '\n' && source[index] !== '\r') {
+          characters[index] = ' ';
+        }
+      }
+      index -= 1;
+    } else if (!closingTag && (pair === '{{' || pair === '{%')) {
+      closingTag = pair === '{{' ? '}}' : '%}';
+      index += 1;
+    } else if (closingTag && pair === closingTag) {
+      closingTag = '';
+      index += 1;
+    } else if (closingTag && (char === '"' || char.charCodeAt(0) === 39)) {
+      quote = char;
+      if (codeOnly) characters[index] = ' ';
     }
   }
 
-  return references;
+  return characters.join('');
 }
 
 /**
- * Extract the first function argument, including array syntax.
+ * Read comma-separated call arguments or array elements and their offsets.
  *
- * Twig include()/source() only use the first argument as the template/source
- * reference. Later object values may also be strings, but they are context
- * values and should not be treated as template references.
+ * Nested delimiters and quoted punctuation do not terminate a value. An
+ * incomplete or mismatched list is ignored rather than audited in fragments.
  *
- * @param {string} args - Function argument source.
- * @returns {string} First argument source.
+ * @param {string} source - Comment-masked Twig source.
+ * @param {number} start - Offset immediately after the opening delimiter.
+ * @param {string} closing - Closing delimiter for this list.
+ * @returns {{values: {text: string, offset: number}[], end: number}|null} List.
  */
-function firstArgumentText(args) {
+function readTwigList(source, start, closing) {
+  const values = [];
+  const closings = { '(': ')', '[': ']', '{': '}' };
+  const stack = [];
   let quote = '';
-  let depth = 0;
-
-  for (let index = 0; index < args.length; index += 1) {
-    const char = args[index];
-    const prev = args[index - 1];
+  let offset = start;
 
+  for (let index = start; index < source.length; index += 1) {
+    const char = source[index];
     if (quote) {
-      if (char === quote && prev !== '\\') {
-        quote = '';
-      }
+      if (char === '\\') index += 1;
+      else if (char === quote) quote = '';
       continue;
     }
-
     if (char === '"' || char.charCodeAt(0) === 39) {
       quote = char;
-      continue;
+    } else if (closings[char]) {
+      stack.push(closings[char]);
+    } else if (!stack.length && (char === ',' || char === closing)) {
+      values.push({ text: source.slice(offset, index), offset });
+      if (char === closing) return { values, end: index + 1 };
+      offset = index + 1;
+    } else if (')]}'.includes(char) && stack.pop() !== char) {
+      return null;
     }
-    if (char === '[' || char === '{' || char === '(') {
-      depth += 1;
-      continue;
+  }
+
+  return null;
+}
+
+/**
+ * Return a complete static string literal, excluding Twig interpolation.
+ *
+ * @param {string} expression - One complete argument or array element.
+ * @returns {string|null} Literal value, or null for a dynamic expression.
+ */
+function staticTwigString(expression) {
+  const literal = expression
+    .trim()
+    .match(/^(['"])((?:\\[\s\S]|(?!\1)[^\\])*)\1$/);
+  if (!literal) return null;
+
+  const [, quote, value] = literal;
+  if (quote === '"' && value.replace(/\\[\s\S]/g, '').includes('#{')) {
+    return null;
+  }
+
+  // Match Twig.js's string token decoding without compiling the template.
+  return value
+    .replace(`\\${quote}`, quote)
+    .replace(/\\n/g, '\n')
+    .replace(/\\r/g, '\r');
+}
+
+/**
+ * Read complete literal candidates and retain uncertainty within a fallback list.
+ *
+ * @param {object} argument - Argument text and source offset.
+ * @param {string} source - Comment-masked Twig source.
+ * @param {boolean} [allowArray=true] - Whether the function accepts fallbacks.
+ * @returns {object} Static candidates, array status, and dynamic-candidate flag.
+ */
+function readTwigCandidates(argument, source, allowArray = true) {
+  const result = {
+    candidates: [],
+    isFallbackArray: false,
+    hasDynamicCandidates: false,
+  };
+  if (!argument) return { ...result, hasDynamicCandidates: true };
+  let values = [argument];
+  if (argument.text.trimStart().startsWith('[')) {
+    const arrayStart = argument.offset + argument.text.indexOf('[');
+    const array = readTwigList(source, arrayStart + 1, ']');
+    const argumentEnd = argument.offset + argument.text.length;
+    if (!allowArray || !array || source.slice(array.end, argumentEnd).trim()) {
+      return { ...result, hasDynamicCandidates: true };
     }
-    if (char === ']' || char === '}' || char === ')') {
-      depth = Math.max(0, depth - 1);
+    result.isFallbackArray = true;
+    values = array.values;
+  }
+
+  for (const [index, { text, offset }] of values.entries()) {
+    // An empty array and a trailing comma do not introduce a dynamic candidate.
+    if (result.isFallbackArray && index === values.length - 1 && !text.trim()) {
       continue;
     }
-    if (char === ',' && depth === 0) {
-      return args.slice(0, index);
+    const value = staticTwigString(text);
+    if (value === null) {
+      result.hasDynamicCandidates = true;
+    } else {
+      result.candidates.push({
+        value,
+        line: lineNumberAt(
+          source,
+          offset + text.length - text.trimStart().length,
+        ),
+      });
     }
   }
+  return result;
+}
 
-  return args;
+/**
+ * Recognize literal optionality using Core's JavaScript truthiness coercion.
+ *
+ * @param {object|undefined|null} argument - Argument, absent value, or unknown.
+ * @returns {boolean|null} Static boolean, or null when unknown.
+ */
+function staticTwigBoolean(argument) {
+  if (argument === undefined) return false;
+  const text = argument?.text.trim();
+  if (text === undefined) return null;
+  if (/^(?:true|TRUE)$/.test(text)) return true;
+  if (/^(?:false|FALSE|null|NULL|none|NONE)$/.test(text)) return false;
+  if (/^-?\d+(?:\.\d+)?$/.test(text)) return Boolean(Number(text));
+  const literal = staticTwigString(text);
+  if (literal !== null) return Boolean(literal);
+  return null;
+}
+
+/**
+ * Read an option from a complete object literal in Twig.js property order.
+ *
+ * @param {object|undefined|null} argument - Object argument or unknown value.
+ * @param {string} name - Option key.
+ * @param {string} source - Comment-masked Twig source.
+ * @param {boolean} [isVariablesArgument=false] - Ignore opaque variables bags.
+ * @returns {object|undefined|null} Option expression, absent option, or unknown.
+ */
+function readTwigObjectOption(
+  argument,
+  name,
+  source,
+  isVariablesArgument = false,
+) {
+  if (argument === undefined) return undefined;
+  if (argument === null) return null;
+  const text = argument.text.trim();
+  if (!text.startsWith('{')) {
+    // An opaque variables bag does not declare an ignore-missing option.
+    // Explicit flag expressions and with-context options remain uncertain.
+    if (isVariablesArgument) return undefined;
+    // Core normalizes primitive/array variables to an empty variables object.
+    if (staticTwigBoolean(argument) !== null) {
+      return undefined;
+    }
+    if (text.startsWith('[')) {
+      const start = argument.offset + argument.text.indexOf('[');
+      const array = readTwigList(source, start + 1, ']');
+      if (
+        array &&
+        !source.slice(array.end, argument.offset + argument.text.length).trim()
+      ) {
+        return undefined;
+      }
+    }
+    return null;
+  }
+
+  const start = argument.offset + argument.text.indexOf('{');
+  const object = readTwigList(source, start + 1, '}');
+  if (
+    !object ||
+    source.slice(object.end, argument.offset + argument.text.length).trim()
+  )
+    return isVariablesArgument ? undefined : null;
+  // Twig.js keeps the first value for duplicate object keys. A preceding
+  // computed key may already define this option, so it remains unknown.
+  for (const property of object.values) {
+    if (!property.text.trim()) continue;
+    const key = readTwigList(source, property.offset, ':');
+    if (!key || key.values.length !== 1) return null;
+    const keyText = key.values[0].text.trim();
+    const propertyName = /^(?:[A-Za-z_]\w*|-?\d+(?:\.\d+)?)$/.test(keyText)
+      ? keyText
+      : staticTwigString(keyText);
+    if (propertyName === null) return null;
+    if (propertyName === name) {
+      return {
+        text: source.slice(key.end, property.offset + property.text.length),
+        offset: key.end,
+      };
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Read supported Core optional-missing arguments, including include options.
+ *
+ * @param {string} type - include or source.
+ * @param {object[]} args - Complete arguments with source offsets.
+ * @param {string} source - Comment-masked Twig source.
+ * @returns {boolean|null} Optional, required, or unknown.
+ */
+function readIgnoreMissing(type, args, source) {
+  // Twig.js does not bind native named parameters: colon pairs become positional
+  // tokens and equals syntax does not compile. Do not infer flags from those
+  // accidental positions; keep unsupported calls explicitly unknown.
+  if (args.some(({ text }) => /^\s*[A-Za-z_]\w*\s*[:=]/.test(text)))
+    return null;
+  if (type === 'source') return staticTwigBoolean(args[1]);
+
+  let ignoreMissing = staticTwigBoolean(args[3]);
+  const variableFlag = readTwigObjectOption(
+    args[1],
+    'ignore_missing',
+    source,
+    true,
+  );
+  if (variableFlag !== undefined)
+    ignoreMissing = staticTwigBoolean(variableFlag);
+
+  // This precedence mirrors Core's normalizeIncludeOptions: variables can
+  // replace withContext before a third-argument options object is inspected.
+  const variableContext = readTwigObjectOption(
+    args[1],
+    'with_context',
+    source,
+    true,
+  );
+  const withContext = variableContext === undefined ? args[2] : variableContext;
+  const contextFlag = readTwigObjectOption(
+    withContext,
+    'ignore_missing',
+    source,
+  );
+  if (contextFlag !== undefined) ignoreMissing = staticTwigBoolean(contextFlag);
+  return ignoreMissing;
+}
+
+/**
+ * Scan actual Twig calls while keeping their argument boundaries and locations.
+ *
+ * @param {string} source - Twig source.
+ * @returns {object} Masked source and complete calls.
+ */
+function scanTwigReferenceCalls(source) {
+  const calls = [];
+  const maskedSource = maskTwigSource(source);
+  const callSource = maskTwigSource(source, true);
+  const callPattern = /\b(include|source)\s*\(/g;
+
+  let callMatch;
+  while ((callMatch = callPattern.exec(callSource))) {
+    if (callSource.slice(0, callMatch.index).trimEnd().endsWith('.')) continue;
+    const argsStart = callMatch.index + callMatch[0].length;
+    const call = readTwigList(maskedSource, argsStart, ')');
+    if (!call) continue;
+    const args = [...call.values];
+    if (!args.at(-1)?.text.trim()) args.pop();
+    calls.push({
+      type: callMatch[1],
+      args,
+      line: lineNumberAt(source, callMatch.index),
+    });
+  }
+  return { calls, maskedSource };
+}
+
+/**
+ * Preserve the flat static-reference interface exported by the audit entrypoint.
+ *
+ * This compatibility view intentionally retains individual array literals and
+ * optional references. The audit check uses the richer call view below.
+ *
+ * @param {string} source - Twig source.
+ * @returns {{type: string, value: string, line: number}[]} Static references.
+ */
+export function findTwigIncludeSourceReferences(source) {
+  const { calls, maskedSource } = scanTwigReferenceCalls(source);
+  return calls.flatMap(({ type, args }) =>
+    readTwigCandidates(args[0], maskedSource).candidates.map((candidate) => ({
+      type,
+      ...candidate,
+    })),
+  );
+}
+
+/**
+ * Extract call-level reference semantics without compiling or rendering Twig.
+ *
+ * Candidate lines locate literals; the call line locates a grouped finding.
+ * Source only accepts a scalar name, unlike include's ordered fallback list.
+ * Dynamic candidates or optionality remain explicit internal unknown states.
+ *
+ * @param {string} source - Twig source.
+ * @returns {object[]} Calls, candidates, optionality, and source locations.
+ */
+export function findTwigReferenceCalls(source) {
+  const { calls, maskedSource } = scanTwigReferenceCalls(source);
+  return calls.map(({ type, args, line }) => ({
+    type,
+    line,
+    ...readTwigCandidates(args[0], maskedSource, type === 'include'),
+    ignoreMissing: readIgnoreMissing(type, args, maskedSource),
+  }));
 }
 
 /**
@@ -93,7 +392,7 @@ export function findTwigNamespaceReferences(source) {
   const references = [];
   const pattern = /@([A-Za-z][\w-]*)\/[A-Za-z0-9_./-]+/g;
 
-  for (const match of source.matchAll(pattern)) {
+  for (const match of maskTwigSource(source).matchAll(pattern)) {
     references.push({
       namespace: match[1],
       value: match[0],
@@ -143,45 +442,23 @@ function candidateKeysToFiles(keys, env) {
  * @returns {string} Absolute filesystem path, or an empty string.
  */
 export function resolveAuditAssetRoot(projectDir, assetRoot) {
-  if (typeof assetRoot !== 'string' || !assetRoot.trim()) return '';
-
-  const normalizedProjectDir = resolve(projectDir || process.cwd());
-  const normalizedRoot = assetRoot.trim();
-
-  if (isAbsolute(normalizedRoot)) {
-    const absoluteRoot = resolve(normalizedRoot);
-
-    return safeExists(absoluteRoot)
-      ? absoluteRoot
-      : resolve(normalizedProjectDir, `.${normalizedRoot}`);
-  }
-
-  return resolve(normalizedProjectDir, normalizedRoot);
+  return toAbsoluteAssetRoot(projectDir, assetRoot);
 }
 
 /**
  * Return filesystem roots that Storybook can use for @assets source() calls.
  *
+ * Existence filtering stays off here because callers do their own directory
+ * check, and a configured-but-missing root is worth reporting rather than
+ * silently dropping.
+ *
  * @param {object} env - Normalized environment.
  * @param {object} [options={}] - Asset root options.
  * @param {boolean} [options.includeGenerated=false] - Include generated roots.
  * @returns {string[]} Absolute asset roots.
  */
 export function auditAssetRoots(env = {}, { includeGenerated = false } = {}) {
-  const projectDir = env.projectDir || process.cwd();
-  const configuredRoots = Array.isArray(env?.projectStructure?.assetRoots)
-    ? env.projectStructure.assetRoots
-    : [];
-  const fallbackRoots = ['assets', 'src/assets'];
-  const generatedRoots = includeGenerated ? ['dist/assets'] : [];
-
-  return Array.from(
-    new Set(
-      [...fallbackRoots, ...configuredRoots, ...generatedRoots]
-        .map((root) => resolveAuditAssetRoot(projectDir, root))
-        .filter(Boolean),
-    ),
-  );
+  return resolveAssetRoots(env, { includeGenerated, existingOnly: false });
 }
 
 /**
@@ -209,19 +486,34 @@ function resolvesAssetReference(reference, env) {
  * @param {string} reference - Twig reference.
  * @param {string} filePath - Referencing file path.
  * @param {object} env - Normalized environment.
+ * @param {Map<string, string[]>} [componentGroupRootsCache] - Directory cache shared across one audit pass.
  * @returns {boolean} TRUE when a candidate exists.
  */
-export function resolvesTwigReference(reference, filePath, env) {
+export function resolvesTwigReference(
+  reference,
+  filePath,
+  env,
+  componentGroupRootsCache = new Map(),
+) {
   if (!reference || /^https?:\/\//i.test(reference)) return true;
 
   if (reference.startsWith('@assets/')) {
     return resolvesAssetReference(reference, env);
   }
 
-  const candidates =
-    reference.startsWith('./') || reference.startsWith('../')
-      ? relativeTwigCandidates(filePath, reference)
-      : candidateKeysToFiles(candidateKeysForReference(reference, env), env);
+  const isRelative = reference.startsWith('./') || reference.startsWith('../');
+  const candidates = isRelative
+    ? relativeTwigCandidates(filePath, reference)
+    : candidateKeysToFiles(candidateKeysForReference(reference, env), env);
+
+  if (candidates.some(safeExists)) return true;
+  if (isRelative || !(env.singleDirectoryComponents || env.SDC)) return false;
 
-  return candidates.some(safeExists);
+  return Boolean(
+    resolveComponentReference(
+      reference,
+      env.projectStructure?.namespaceRoots || env.namespaceRoots || {},
+      componentGroupRootsCache,
+    ),
+  );
 }

package/scripts/audit/report.js

@@ -58,16 +58,51 @@ export function formatAuditReport(result) {
 
   if (!result.findings.length) {
     lines.push('No audit findings found.');
-    return lines.join('\n');
   }
 
   for (const finding of result.findings) {
     lines.push('', ...formatFinding(finding, result.projectDir));
   }
 
+  lines.push(...formatFixSection(result.fixes, result.projectDir));
+
   return lines.join('\n');
 }
 
+/**
+ * Format the autofix section appended by `--fix`.
+ *
+ * @param {{dryRun: boolean, applied: object[], skipped: object[]}} [fixes] - Fix result.
+ * @param {string} projectDir - Absolute scanned root.
+ * @returns {string[]} Report lines.
+ */
+function formatFixSection(fixes, projectDir) {
+  if (!fixes) return [];
+
+  const lines = ['', 'Fixes'];
+  const verb = fixes.dryRun ? 'Would apply' : 'Applied';
+
+  if (!fixes.applied.length) {
+    lines.push(`${verb} 0 fix(es).`);
+  } else {
+    lines.push(`${verb} ${fixes.applied.length} fix(es):`);
+    for (const { finding, from, to } of fixes.applied) {
+      const where = `${displayPath(projectDir, finding.filePath)}:${finding.line}`;
+      lines.push(`  ${where}  ${from} -> ${to}`);
+    }
+  }
+
+  if (fixes.skipped.length) {
+    lines.push(`Skipped ${fixes.skipped.length} fixable finding(s):`);
+    for (const { finding, reason } of fixes.skipped) {
+      const where = `${displayPath(projectDir, finding.filePath)}:${finding.line}`;
+      lines.push(`  ${where}  ${reason}`);
+    }
+  }
+
+  return lines;
+}
+
 /**
  * Count findings by severity for machine-readable reports.
  *
@@ -219,7 +254,7 @@ export function createAuditJsonReport(result, options = {}) {
     normalizeAuditFinding(finding, result.projectDir, options.defaultSeverity),
   );
 
-  return {
+  const document = {
     schemaVersion: AUDIT_REPORT_SCHEMA_VERSION,
     tool: createToolIdentity(),
     root: '.',
@@ -227,19 +262,56 @@ export function createAuditJsonReport(result, options = {}) {
     files: normalizeFileCounts(result.files),
     findings,
   };
+
+  // Present only when --fix ran, so the document shape is unchanged for every
+  // existing consumer.
+  if (result.fixes) {
+    document.fixes = normalizeFixes(result.fixes, result.projectDir);
+  }
+
+  return document;
+}
+
+/**
+ * Normalize the autofix result for the machine-readable report.
+ *
+ * @param {{dryRun: boolean, applied: object[], skipped: object[]}} fixes - Fix result.
+ * @param {string} projectDir - Absolute scanned root.
+ * @returns {object} JSON fix block.
+ */
+function normalizeFixes(fixes, projectDir) {
+  const locate = (finding) => ({
+    path: displayPath(projectDir, finding.filePath) || '.',
+    ...(Number.isInteger(finding.line) && finding.line > 0
+      ? { line: finding.line }
+      : {}),
+  });
+
+  return {
+    dryRun: Boolean(fixes.dryRun),
+    applied: fixes.applied.map(({ finding, from, to }) => ({
+      ...locate(finding),
+      from,
+      to,
+    })),
+    skipped: fixes.skipped.map(({ finding, reason }) => ({
+      ...locate(finding),
+      reason: normalizeReportText(reason, projectDir),
+    })),
+  };
 }
 
 /**
  * Create a structured machine-readable CLI or audit failure.
  *
  * @param {*} error - Failure value.
- * @param {{code?: string, projectDir?: string}} [options={}] - Error options.
+ * @param {{code?: string, projectDir?: string, fixes?: object}} [options={}] - Error options.
  * @returns {object} JSON error document.
  */
 export function createAuditJsonErrorReport(error, options = {}) {
   const message = error?.message || error;
 
-  return {
+  const document = {
     schemaVersion: AUDIT_REPORT_SCHEMA_VERSION,
     tool: createToolIdentity(),
     error: {
@@ -247,6 +319,12 @@ export function createAuditJsonErrorReport(error, options = {}) {
       message: normalizeReportText(message, options.projectDir || ''),
     },
   };
+
+  if (options.fixes) {
+    document.fixes = normalizeFixes(options.fixes, options.projectDir || '');
+  }
+
+  return document;
 }
 
 /**
@@ -265,7 +343,7 @@ export function formatAuditJsonReport(result, options = {}) {
  * Format a CLI or audit failure as machine-readable JSON.
  *
  * @param {*} error - Failure value.
- * @param {{code?: string, projectDir?: string}} [options={}] - Error options.
+ * @param {{code?: string, projectDir?: string, fixes?: object}} [options={}] - Error options.
  * @returns {string} JSON error document.
  */
 export function formatAuditJsonErrorReport(error, options = {}) {