@emulsify/core 3.5.0 → 4.0.1

package/scripts/a11y.js

@@ -5,25 +5,74 @@
  * and reports issues.
  */
 
-const R = require('ramda');
-const path = require('path');
-const pa11y = require('pa11y');
+import { existsSync } from 'fs';
+import path from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+import * as R from 'ramda';
+import pa11y from 'pa11y';
 
-const {
-  storybookBuildDir,
-  pa11y: pa11yConfig,
-} = require('../config/a11y.config.js');
+import a11yConfig from '../config/a11y.config.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const { storybookBuildDir, pa11y: pa11yConfig } = a11yConfig;
 
 // Project-specific configuration.
-const {
-  ignore,
-  components,
-} = require('../../../config/emulsify-core/a11y.config.js');
+let { ignore = {}, components = [] } = a11yConfig;
 
 /** Absolute path to Storybook build directory. */
 const STORYBOOK_BUILD_DIR = path.resolve(__dirname, '../', storybookBuildDir);
 /** Absolute path to Storybook iframe file used for per-story rendering. */
 const STORYBOOK_IFRAME = path.join(STORYBOOK_BUILD_DIR, 'iframe.html');
+/** Project-specific accessibility config path used by generated themes. */
+const PROJECT_A11Y_CONFIG = path.resolve(
+  __dirname,
+  '../../../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)) {
+    return {};
+  }
+
+  const configModule = await import(pathToFileURL(PROJECT_A11Y_CONFIG).href);
+  return configModule.default || configModule;
+};
+
+/**
+ * Apply project-specific a11y config values over shared defaults.
+ *
+ * @param {{ignore?: object, components?: string[]}} config - Project config.
+ * @returns {void}
+ */
+const applyProjectA11yConfig = (config = {}) => {
+  ignore = config.ignore || ignore;
+  components = config.components || components;
+};
+
+/**
+ * Print CLI help.
+ *
+ * @returns {void}
+ */
+const printHelp = () => {
+  // eslint-disable-next-line no-console
+  console.log(
+    [
+      'Usage: node scripts/a11y.js [options]',
+      '',
+      'Options:',
+      '  -r           Run pa11y against configured Storybook component IDs.',
+      '  -h, --help   Print this help text.',
+    ].join('\n'),
+  );
+};
 
 /**
  * Map pa11y/axe severity to a label (historically a color name).
@@ -56,7 +105,8 @@ const severityToColor = R.cond([
 const issueIsValid = (issue) => {
   const code = issue?.code;
   const description = issue?.runnerExtras?.description;
-  const codeIgnored = Array.isArray(ignore?.codes) && ignore.codes.includes(code);
+  const codeIgnored =
+    Array.isArray(ignore?.codes) && ignore.codes.includes(code);
   const descIgnored =
     description &&
     Array.isArray(ignore?.descriptions) &&
@@ -137,12 +187,16 @@ const lintReportAndExit = R.pipe(
 
 // Only perform linting/reporting when instructed via "-r".
 /* istanbul ignore next */
-if (R.pathEq(['argv', 2], '-r')(process)) {
-  // eslint-disable-next-line promise/catch-or-return
-  lintReportAndExit(components);
+if (R.includes(process.argv[2], ['-h', '--help'])) {
+  printHelp();
+} else if (R.pathEq(['argv', 2], '-r')(process)) {
+  loadProjectA11yConfig().then((projectConfig) => {
+    applyProjectA11yConfig(projectConfig);
+    return lintReportAndExit(components);
+  });
 }
 
-module.exports = {
+export {
   severityToColor,
   issueIsValid,
   logIssue,

package/scripts/audit-twig-stories.js

@@ -0,0 +1,378 @@
+#!/usr/bin/env node
+
+/**
+ * @file Report legacy Twig Storybook stories that should migrate to renderTwig().
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { relative, resolve } from 'node:path';
+import { globSync } from 'glob';
+import { resolveProjectConfig } from '../config/vite/project-config.js';
+import { toPosixPath } from '../config/vite/utils/paths.js';
+
+const STORY_GLOB = '**/*.stories.{js,jsx,ts,tsx}';
+const IDENTIFIER_PATTERN = '[A-Za-z_$][\\w$]*';
+const DEFAULT_IGNORES = [
+  '**/node_modules/**',
+  '**/dist/**',
+  '**/.out/**',
+  '**/.coverage/**',
+];
+
+/**
+ * Escape a string for use inside a regular expression.
+ *
+ * @param {string} value - Raw string.
+ * @returns {string} Escaped string.
+ */
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Find the 1-based line number for a character index.
+ *
+ * @param {string} source - File source.
+ * @param {number} index - Character index.
+ * @returns {number} 1-based line number.
+ */
+function lineNumberAt(source, index) {
+  return source.slice(0, index).split('\n').length;
+}
+
+/**
+ * Find imported Twig template identifiers.
+ *
+ * @param {string} source - Story source.
+ * @returns {{name: string, specifier: string, line: number}[]} Twig imports.
+ */
+export function findTwigImports(source) {
+  const imports = [];
+  const patterns = [
+    new RegExp(
+      `import\\s+(${IDENTIFIER_PATTERN})\\s+from\\s+['"]([^'"]+\\.twig(?:\\?[^'"]*)?)['"]`,
+      'g',
+    ),
+    new RegExp(
+      `(?:const|let|var)\\s+(${IDENTIFIER_PATTERN})\\s*=\\s*require\\(\\s*['"]([^'"]+\\.twig(?:\\?[^'"]*)?)['"]\\s*\\)`,
+      'g',
+    ),
+  ];
+
+  for (const pattern of patterns) {
+    for (const match of source.matchAll(pattern)) {
+      imports.push({
+        name: match[1],
+        specifier: match[2],
+        line: lineNumberAt(source, match.index || 0),
+      });
+    }
+  }
+
+  return imports;
+}
+
+/**
+ * Determine whether a story imports renderTwig from Emulsify Core.
+ *
+ * @param {string} source - Story source.
+ * @returns {boolean} TRUE when renderTwig is imported from the public helper.
+ */
+export function importsRenderTwig(source) {
+  return (
+    /\brenderTwig\b/.test(source) &&
+    /from\s+['"]@emulsify\/core\/storybook['"]/.test(source)
+  );
+}
+
+/**
+ * Find likely direct returns of imported Twig template functions.
+ *
+ * @param {string} source - Story source.
+ * @param {string[]} templateNames - Imported Twig template identifiers.
+ * @returns {{name: string, line: number}[]} Direct template calls.
+ */
+export function findDirectTemplateReturns(source, templateNames = []) {
+  const calls = [];
+
+  for (const templateName of templateNames) {
+    const pattern = new RegExp(
+      `(?:return\\s+|=>\\s*(?:\\(\\s*)?)${escapeRegExp(templateName)}\\s*\\(`,
+      'g',
+    );
+
+    for (const match of source.matchAll(pattern)) {
+      calls.push({
+        name: templateName,
+        line: lineNumberAt(source, match.index || 0),
+      });
+    }
+  }
+
+  return calls;
+}
+
+/**
+ * Analyze one Storybook story source string.
+ *
+ * @param {string} source - Story source.
+ * @param {string} [filePath=''] - Story file path.
+ * @returns {object} Story analysis.
+ */
+export function analyzeStorySource(source, filePath = '') {
+  const twigImports = findTwigImports(source);
+  const templateNames = twigImports.map((item) => item.name);
+  const hasRenderTwig = importsRenderTwig(source);
+  const directTemplateReturns = findDirectTemplateReturns(
+    source,
+    templateNames,
+  );
+  const reasons = [];
+
+  if (!twigImports.length) {
+    return {
+      filePath,
+      twigImports,
+      hasRenderTwig,
+      directTemplateReturns,
+      reasons,
+      shouldUpgrade: false,
+    };
+  }
+
+  if (!hasRenderTwig) {
+    reasons.push('imports Twig templates without renderTwig()');
+  }
+
+  if (directTemplateReturns.length) {
+    reasons.push('appears to return Twig HTML strings directly');
+  }
+
+  return {
+    filePath,
+    twigImports,
+    hasRenderTwig,
+    directTemplateReturns,
+    reasons,
+    shouldUpgrade: reasons.length > 0,
+  };
+}
+
+/**
+ * Resolve Storybook source roots for the project.
+ *
+ * @param {string} projectDir - Absolute project root.
+ * @returns {string[]} Absolute story roots.
+ */
+export function resolveStoryRoots(projectDir) {
+  try {
+    const env = resolveProjectConfig(projectDir, process.env);
+    const storyRoots = env.projectStructure?.storyRoots;
+    if (Array.isArray(storyRoots) && storyRoots.length) {
+      return storyRoots;
+    }
+  } catch {
+    // Fall back to conventional roots when project config is absent or invalid.
+  }
+
+  return [resolve(projectDir, 'src'), resolve(projectDir, 'components')];
+}
+
+/**
+ * Collect Storybook story files from normalized project roots.
+ *
+ * @param {string} projectDir - Absolute project root.
+ * @returns {string[]} Absolute story file paths.
+ */
+export function collectStoryFiles(projectDir) {
+  const files = new Set();
+
+  for (const root of resolveStoryRoots(projectDir)) {
+    if (!existsSync(root)) continue;
+
+    for (const match of globSync(STORY_GLOB, {
+      cwd: root,
+      nodir: true,
+      absolute: true,
+      ignore: DEFAULT_IGNORES,
+    })) {
+      files.add(resolve(match));
+    }
+  }
+
+  return Array.from(files).sort();
+}
+
+/**
+ * Analyze all discovered story files in a project.
+ *
+ * @param {{projectDir?: string}} [options={}] - Audit options.
+ * @returns {{projectDir: string, files: string[], findings: object[]}} Results.
+ */
+export function auditTwigStories(options = {}) {
+  const projectDir = resolve(options.projectDir || process.cwd());
+  const files = collectStoryFiles(projectDir);
+  const findings = files
+    .map((filePath) => {
+      const source = readFileSync(filePath, 'utf8');
+      return analyzeStorySource(source, filePath);
+    })
+    .filter((result) => result.shouldUpgrade);
+
+  return {
+    projectDir,
+    files,
+    findings,
+  };
+}
+
+/**
+ * Format audit findings for terminal output.
+ *
+ * @param {{projectDir: string, files: string[], findings: object[]}} result
+ * Audit result.
+ * @returns {string} Human-readable report.
+ */
+export function formatAuditReport(result) {
+  const lines = [
+    'Twig story migration audit',
+    `Scanned ${result.files.length} story file(s).`,
+  ];
+
+  if (!result.findings.length) {
+    lines.push('No legacy Twig story candidates found.');
+    return lines.join('\n');
+  }
+
+  lines.push(
+    `Found ${result.findings.length} story file(s) that should be reviewed:`,
+  );
+
+  for (const finding of result.findings) {
+    const relPath = toPosixPath(relative(result.projectDir, finding.filePath));
+    const importNames = finding.twigImports.map((item) => item.name).join(', ');
+
+    lines.push('', `- ${relPath}`);
+    lines.push(`  Twig imports: ${importNames}`);
+    for (const reason of finding.reasons) {
+      lines.push(`  Reason: ${reason}.`);
+    }
+    for (const call of finding.directTemplateReturns) {
+      lines.push(
+        `  Line ${call.line}: ${call.name}() appears to be returned directly.`,
+      );
+    }
+  }
+
+  lines.push(
+    '',
+    'Suggested migration: import { renderTwig } from "@emulsify/core/storybook" and move any argument mapping into renderTwig(template, { context }).',
+  );
+
+  return lines.join('\n');
+}
+
+/**
+ * Parse command-line arguments.
+ *
+ * @param {string[]} argv - CLI arguments.
+ * @returns {{projectDir: string, failOnFound: boolean, json: boolean, help: boolean}}
+ * Parsed options.
+ */
+function parseArgs(argv) {
+  const options = {
+    projectDir: process.cwd(),
+    failOnFound: false,
+    json: false,
+    help: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+      continue;
+    }
+    if (arg === '--fail-on-found') {
+      options.failOnFound = true;
+      continue;
+    }
+    if (arg === '--json') {
+      options.json = true;
+      continue;
+    }
+    if (arg === '--root') {
+      const value = argv[index + 1];
+      if (!value || value.startsWith('--')) {
+        throw new Error('--root requires a project directory.');
+      }
+      options.projectDir = value;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith('--root=')) {
+      options.projectDir = arg.slice('--root='.length);
+      continue;
+    }
+
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  return options;
+}
+
+/**
+ * CLI usage text.
+ *
+ * @returns {string} Usage text.
+ */
+function usage() {
+  return [
+    'Usage: emulsify-audit-twig-stories [--root <dir>] [--json] [--fail-on-found]',
+    '',
+    'Options:',
+    '  --root <dir>      Project root to scan. Defaults to the current directory.',
+    '  --json            Print machine-readable JSON.',
+    '  --fail-on-found   Exit with code 1 when migration candidates are found.',
+    '  --help            Print this help text.',
+  ].join('\n');
+}
+
+/**
+ * Run the CLI.
+ *
+ * @param {string[]} argv - CLI arguments.
+ * @returns {number} Process exit code.
+ */
+export function runCli(argv = process.argv.slice(2)) {
+  const options = parseArgs(argv);
+
+  if (options.help) {
+    console.log(usage());
+    return 0;
+  }
+
+  const result = auditTwigStories({
+    projectDir: options.projectDir,
+  });
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatAuditReport(result));
+  }
+
+  return options.failOnFound && result.findings.length ? 1 : 0;
+}
+
+if (process.argv[1]?.split(/[\\/]/).pop() === 'audit-twig-stories.js') {
+  try {
+    process.exitCode = runCli();
+  } catch (error) {
+    console.error(error.message || error);
+    console.error('');
+    console.error(usage());
+    process.exitCode = 1;
+  }
+}