@emulsify/core 4.4.0 → 4.5.0

package/scripts/audit/lib/story-selection.js

@@ -0,0 +1,190 @@
+/**
+ * @file Select statically readable CSF story exports without executing modules.
+ */
+
+import {
+  identifierName,
+  moduleBody,
+  resolveModuleValue,
+  readStaticProperty,
+  unwrapExpression,
+} from './story-ast.js';
+
+const RESERVED_EXPORTS = new Set([
+  'default',
+  '__esModule',
+  '__namedExportsOrder',
+]);
+
+/**
+ * Recognize literal falsy values used by CSF filter and render defaults.
+ *
+ * @param {object} node - Babel expression.
+ * @param {Map<string, object>} declarations - Module declarations.
+ * @returns {boolean} TRUE only for a statically known falsy value.
+ */
+export function isStaticFalsy(node, declarations) {
+  const value = resolveModuleValue(node, declarations);
+  if (value?.type === 'NullLiteral') return true;
+  if (
+    ['BooleanLiteral', 'NumericLiteral', 'StringLiteral'].includes(value?.type)
+  ) {
+    return !value.value;
+  }
+  return (
+    value?.type === 'Identifier' &&
+    value.name === 'undefined' &&
+    !declarations.has('undefined')
+  );
+}
+
+/**
+ * Decode supported CSF filters; dynamic expressions retain an unknown state.
+ *
+ * @param {object} property - Static property lookup.
+ * @param {Map<string, object>} declarations - Module declarations.
+ * @returns {object} Absent, known array/regex, or unknown filter.
+ */
+function readFilter(property, declarations) {
+  if (property.state !== 'known') return property;
+  const value = resolveModuleValue(property.node, declarations);
+  if (isStaticFalsy(value, declarations)) return { state: 'absent' };
+
+  if (value?.type === 'ArrayExpression') {
+    const elements = value.elements.map(unwrapExpression);
+    if (elements.every((element) => element?.type === 'StringLiteral')) {
+      return {
+        state: 'known',
+        strings: elements.map((element) => element.value),
+      };
+    }
+  }
+  if (value?.type === 'RegExpLiteral') {
+    try {
+      return {
+        state: 'known',
+        regex: new RegExp(value.pattern, value.flags),
+      };
+    } catch {
+      // A newer RegExp syntax may parse but be unsupported by this Node version.
+    }
+  }
+  return { state: 'unknown' };
+}
+
+/**
+ * Match the Storybook CSF array/regex contract, with no shared RegExp cursor.
+ *
+ * @param {string} name - Exported name, rather than a local binding or story name.
+ * @param {object} filter - Decoded static filter.
+ * @returns {boolean|null} Match, mismatch, or unknown.
+ */
+function matchesFilter(name, filter) {
+  if (filter.state === 'unknown') return null;
+  if (filter.strings) return filter.strings.includes(name);
+  // Storybook's isExportStory uses String.match(). A fresh expression also keeps
+  // sticky filters from changing the result when another export was checked.
+  return Boolean(
+    name.match(new RegExp(filter.regex.source, filter.regex.flags)),
+  );
+}
+
+/**
+ * Collect named exports and default metadata before selecting any render paths.
+ *
+ * @param {object} ast - Babel File or Program.
+ * @returns {object} Metadata, candidates, and unresolved re-export state.
+ */
+function collectExports(ast) {
+  let metadata;
+  let hasUnknownExports = false;
+  const candidates = [];
+  for (const statement of moduleBody(ast)) {
+    if (statement.exportKind === 'type') continue;
+    if (statement.type === 'ExportDefaultDeclaration') {
+      metadata = statement.declaration;
+      continue;
+    }
+    if (statement.type === 'ExportAllDeclaration') {
+      hasUnknownExports = true;
+      continue;
+    }
+    if (statement.type !== 'ExportNamedDeclaration') continue;
+    const declaration = statement.declaration;
+    if (declaration?.declare) continue;
+    if (declaration?.type === 'FunctionDeclaration' && declaration.id) {
+      candidates.push({
+        name: declaration.id.name,
+        node: declaration,
+        lineNode: declaration,
+      });
+    } else if (declaration?.type === 'VariableDeclaration') {
+      for (const declarator of declaration.declarations) {
+        if (declarator.id?.type !== 'Identifier') {
+          hasUnknownExports = true;
+          continue;
+        }
+        candidates.push({
+          name: declarator.id.name,
+          node: declarator.init,
+          lineNode: declarator,
+        });
+      }
+    }
+    for (const specifier of statement.specifiers) {
+      if (specifier.exportKind === 'type') continue;
+      const name = identifierName(specifier.exported);
+      if (name === 'default') {
+        metadata = statement.source ? statement : specifier.local;
+      } else if (name) {
+        candidates.push({
+          name,
+          node: statement.source ? null : specifier.local,
+          lineNode: specifier,
+        });
+      }
+    }
+  }
+  return { metadata, candidates, hasUnknownExports };
+}
+
+/**
+ * Apply includeStories and excludeStories before resolving effective renders.
+ *
+ * Unknown filters keep possible stories in the analysis, but a known exclusion
+ * (or a known inclusion mismatch) can still rule a candidate out. No module is
+ * imported and no call, getter, or arbitrary expression is evaluated.
+ *
+ * @param {object} ast - Babel File or Program.
+ * @param {Map<string, object>} declarations - Module declarations.
+ * @returns {object} Selected candidates, default render, and selection certainty.
+ */
+export function selectStoryExports(ast, declarations) {
+  const { metadata, candidates, hasUnknownExports } = collectExports(ast);
+  const include = readFilter(
+    readStaticProperty(metadata, 'includeStories', declarations),
+    declarations,
+  );
+  const exclude = readFilter(
+    readStaticProperty(metadata, 'excludeStories', declarations),
+    declarations,
+  );
+  const stories = [];
+  let hasUnknownSelection = hasUnknownExports;
+  for (const candidate of candidates) {
+    if (RESERVED_EXPORTS.has(candidate.name)) continue;
+    const included =
+      include.state === 'absent' || matchesFilter(candidate.name, include);
+    const excluded =
+      exclude.state !== 'absent' && matchesFilter(candidate.name, exclude);
+    // Storybook requires inclusion and no exclusion; an exclusion always wins.
+    if (included === false || excluded === true) continue;
+    if (included === null || excluded === null) hasUnknownSelection = true;
+    stories.push(candidate);
+  }
+  return {
+    stories,
+    defaultRender: readStaticProperty(metadata, 'render', declarations),
+    hasUnknownSelection,
+  };
+}

package/scripts/audit/lib/twig.js

@@ -8,6 +8,7 @@ import {
   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';
@@ -15,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),
+  }));
 }
 
 /**
@@ -97,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],
@@ -191,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);
 
-  return candidates.some(safeExists);
+  if (candidates.some(safeExists)) return true;
+  if (isRelative || !(env.singleDirectoryComponents || env.SDC)) return false;
+
+  return Boolean(
+    resolveComponentReference(
+      reference,
+      env.projectStructure?.namespaceRoots || env.namespaceRoots || {},
+      componentGroupRootsCache,
+    ),
+  );
 }