@emulsify/core 4.2.1 → 4.3.0

package/scripts/lib/cli.js

@@ -0,0 +1,179 @@
+/**
+ * @file Shared CLI argument helpers.
+ */
+
+/**
+ * Format standard command usage text.
+ *
+ * @param {string} usageLine - Usage line.
+ * @param {string[]} optionLines - Option lines.
+ * @returns {string} Usage text.
+ */
+export function createUsage(usageLine, optionLines) {
+  return [usageLine, '', 'Options:', ...optionLines].join('\n');
+}
+
+/**
+ * Determine whether a script is running as a CLI entrypoint.
+ *
+ * npm package bins run through symlinks, so argv[1] may be either the source
+ * script filename or the published bin name.
+ *
+ * @param {string[]} names - Accepted script or bin basenames.
+ * @param {string[]} [argv=process.argv] - Process arguments.
+ * @returns {boolean} TRUE when argv[1] matches one of the names.
+ */
+export function isCliEntrypoint(names, argv = process.argv) {
+  const entryName = argv[1]?.split(/[\\/]/).pop();
+  return names.includes(entryName);
+}
+
+/**
+ * Clone default option values without sharing arrays between parses.
+ *
+ * @param {object} defaults - Default values.
+ * @returns {object} Parsed option seed.
+ */
+function cloneDefaults(defaults) {
+  return Object.fromEntries(
+    Object.entries(defaults).map(([key, value]) => [
+      key,
+      Array.isArray(value) ? [...value] : value,
+    ]),
+  );
+}
+
+/**
+ * Normalize a boolean flag configuration.
+ *
+ * @param {string|object} spec - Flag config.
+ * @returns {{key: string, value: *}} Normalized flag config.
+ */
+function normalizeFlagSpec(spec) {
+  if (typeof spec === 'string') {
+    return { key: spec, value: true };
+  }
+
+  return {
+    value: true,
+    ...spec,
+  };
+}
+
+/**
+ * Read the next argv value for an option.
+ *
+ * @param {string[]} argv - CLI arguments.
+ * @param {number} index - Current option index.
+ * @param {object} spec - Option config.
+ * @returns {string} Raw value.
+ */
+function readNextValue(argv, index, spec) {
+  const value = argv[index + 1];
+
+  if (
+    value === undefined ||
+    (value === '' && spec.rejectEmptyValue !== false) ||
+    (spec.rejectOptionLikeValue !== false && value.startsWith('--'))
+  ) {
+    throw new Error(spec.missingMessage);
+  }
+
+  return value;
+}
+
+/**
+ * Parse and assign one option value.
+ *
+ * @param {object} parsed - Parsed options.
+ * @param {object} spec - Option config.
+ * @param {string} value - Raw option value.
+ * @returns {void}
+ */
+function assignOptionValue(parsed, spec, value) {
+  const nextValue = spec.parse ? spec.parse(value) : value;
+
+  if (spec.validate && !spec.validate(nextValue)) {
+    throw new Error(spec.invalidMessage || spec.missingMessage);
+  }
+
+  if (spec.append) {
+    const values = Array.isArray(nextValue) ? nextValue : [nextValue];
+    parsed[spec.key].push(...values);
+    return;
+  }
+
+  parsed[spec.key] = nextValue;
+}
+
+/**
+ * Parse common CLI flags.
+ *
+ * @param {string[]} argv - CLI arguments.
+ * @param {object} [config={}] - Parser configuration.
+ * @param {object} [config.defaults={}] - Default option values.
+ * @param {object} [config.flags={}] - Boolean flag map.
+ * @param {object} [config.options={}] - Value option map.
+ * @param {boolean} [config.allowPositionalProjectDir=false] - Allow one root.
+ * @returns {object} Parsed options.
+ */
+export function parseArgs(argv, config = {}) {
+  const {
+    defaults = {},
+    flags = {},
+    options = {},
+    allowPositionalProjectDir = false,
+  } = config;
+  const parsed = cloneDefaults(defaults);
+  let positionalProjectDirFound = false;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === '--help' || arg === '-h') {
+      parsed.help = true;
+      continue;
+    }
+
+    if (Object.prototype.hasOwnProperty.call(flags, arg)) {
+      const spec = normalizeFlagSpec(flags[arg]);
+      parsed[spec.key] = spec.value;
+      continue;
+    }
+
+    const [inlineName, inlineValue] = arg.startsWith('--')
+      ? arg.split(/=(.*)/s, 2)
+      : [arg, undefined];
+    const optionName = Object.prototype.hasOwnProperty.call(options, arg)
+      ? arg
+      : inlineValue !== undefined && options[inlineName]
+        ? inlineName
+        : undefined;
+
+    if (optionName) {
+      const spec = options[optionName];
+      const value =
+        inlineValue === undefined
+          ? readNextValue(argv, index, spec)
+          : inlineValue;
+      assignOptionValue(parsed, spec, value);
+      if (inlineValue === undefined) {
+        index += 1;
+      }
+      continue;
+    }
+
+    if (allowPositionalProjectDir && !arg.startsWith('--')) {
+      if (positionalProjectDirFound) {
+        throw new Error(`Unknown option: ${arg}`);
+      }
+      parsed.projectDir = arg;
+      positionalProjectDirFound = true;
+      continue;
+    }
+
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  return parsed;
+}

package/scripts/lib/fs.js

@@ -0,0 +1,31 @@
+/**
+ * @file Shared filesystem helpers for CLI scripts.
+ */
+
+import { readdirSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+/**
+ * Recursively measure a directory size.
+ *
+ * Unreadable directories contribute only the bytes already counted before the
+ * filesystem error, matching the audit script's historical safe behavior.
+ *
+ * @param {string} directory - Directory path.
+ * @returns {number} Size in bytes.
+ */
+export function directorySize(directory) {
+  let total = 0;
+
+  try {
+    for (const entry of readdirSync(directory)) {
+      const entryPath = resolve(directory, entry);
+      const stats = statSync(entryPath);
+      total += stats.isDirectory() ? directorySize(entryPath) : stats.size;
+    }
+  } catch {
+    return total;
+  }
+
+  return total;
+}

package/scripts/lib/proc.js

@@ -0,0 +1,78 @@
+/**
+ * @file Shared process helpers for CLI scripts.
+ */
+
+import { execFileSync, spawnSync } from 'node:child_process';
+
+/**
+ * Build a default failed-command message.
+ *
+ * @param {object} context - Failed command context.
+ * @param {string} context.command - Command name.
+ * @param {string[]} context.args - Command arguments.
+ * @param {string} [context.cwd] - Working directory.
+ * @param {number|null} [context.status] - Exit status.
+ * @returns {string} Failure message.
+ */
+function defaultFailureMessage({ command, args, cwd, status }) {
+  const location = cwd ? ` in ${cwd}` : '';
+  return `${command} ${args.join(' ')} failed${location} with exit ${status}`;
+}
+
+/**
+ * Run a child process.
+ *
+ * By default this uses spawnSync and returns the full result. Pass
+ * `{ mode: 'exec' }` for execFileSync behavior, which returns stdout.
+ *
+ * @param {string} command - Command name or path.
+ * @param {string[]} [args=[]] - Command arguments.
+ * @param {object} [options={}] - Child process options.
+ * @param {'spawn'|'exec'} [options.mode='spawn'] - Process API to use.
+ * @param {boolean} [options.echoOutputOnFailure=false] - Echo captured output.
+ * @param {string|Function} [options.failureMessage] - Error message override.
+ * @returns {*} spawnSync result or execFileSync stdout.
+ */
+export function run(command, args = [], options = {}) {
+  const {
+    mode = 'spawn',
+    echoOutputOnFailure = false,
+    failureMessage,
+    ...processOptions
+  } = options;
+
+  if (mode === 'exec') {
+    return execFileSync(command, args, {
+      encoding: 'utf8',
+      ...processOptions,
+    });
+  }
+
+  const result = spawnSync(command, args, {
+    encoding: 'utf8',
+    ...processOptions,
+  });
+
+  if (result.status !== 0) {
+    if (echoOutputOnFailure) {
+      process.stdout.write(result.stdout || '');
+      process.stderr.write(result.stderr || '');
+    }
+
+    const context = {
+      args,
+      command,
+      cwd: processOptions.cwd,
+      status: result.status,
+      result,
+    };
+    const message =
+      typeof failureMessage === 'function'
+        ? failureMessage(context)
+        : failureMessage || defaultFailureMessage(context);
+
+    throw new Error(message);
+  }
+
+  return result;
+}

package/scripts/lib/text.js

@@ -0,0 +1,14 @@
+/**
+ * @file Shared text helpers for CLI scripts.
+ */
+
+/**
+ * Find the 1-based line number for a character index.
+ *
+ * @param {string} source - Source text.
+ * @param {number} index - Character index.
+ * @returns {number} 1-based line number.
+ */
+export function lineNumberAt(source, index) {
+  return source.slice(0, index).split('\n').length;
+}

package/scripts/loadYaml.js

@@ -4,7 +4,7 @@
 
 import { resolve } from 'path';
 import { readFileSync } from 'fs';
-import { parse } from 'yaml';
+import { load as parseYaml } from 'js-yaml';
 
 /**
  * Small utility function that loads a yaml file and parses it synchronously.
@@ -17,5 +17,5 @@ import { parse } from 'yaml';
 export default function loadYaml(relativePath) {
   // Resolve from this script directory so tests can pass stable relative paths.
   const fullPath = resolve(__dirname, relativePath);
-  return parse(readFileSync(fullPath, 'utf8'));
+  return parseYaml(readFileSync(fullPath, 'utf8'));
 }

package/src/extensions/shared/attributes.js

@@ -4,7 +4,7 @@
  */
 
 import { escapeAttributeValue, isSafeAttributeName } from './html.js';
-import { flattenList, uniqueList } from './lists.js';
+import { flattenList, unique } from './lists.js';
 import { isPlainObject } from './object.js';
 
 /**
@@ -59,7 +59,7 @@ export function classTokensFromValue(value) {
     return value.getClassList();
   }
 
-  return uniqueList(
+  return unique(
     flattenList(value)
       .flatMap((item) => String(item || '').split(/\s+/))
       .map((item) => cleanClassToken(item))
@@ -181,7 +181,7 @@ export class AttributeBag {
     if (!tokens.length) return this;
 
     const existing = this.attributes.get('class') || [];
-    this.attributes.set('class', uniqueList([...existing, ...tokens]));
+    this.attributes.set('class', unique([...existing, ...tokens]));
     return this;
   }
 

package/src/extensions/shared/lists.js

@@ -3,10 +3,6 @@
  * @module extensions/shared/lists
  */
 
-import { unique } from '../../../config/vite/utils/unique.js';
-
-export { unique };
-
 /**
  * Convert scalar or nested array values into a flat list.
  *
@@ -32,7 +28,7 @@ export function flattenList(value) {
  * @param {*[]} values - Values to deduplicate.
  * @returns {*[]} Unique values.
  */
-export function uniqueList(values) {
+export function unique(values = []) {
   // Preserve first-seen order; class order can affect utility CSS output.
-  return unique(values);
+  return Array.from(new Set(values));
 }

package/src/extensions/shared/root-relative.js

@@ -0,0 +1,38 @@
+/**
+ * @file Browser-safe root-relative path helpers shared by Vite and Storybook.
+ */
+
+const normalizeProjectPath = (filePath) => {
+  const normalized = String(filePath || '')
+    .replace(/\\/g, '/')
+    .replace(/\/{2,}/g, '/');
+
+  return normalized === '/' ? normalized : normalized.replace(/\/+$/, '');
+};
+
+/**
+ * Convert an absolute project path to a Vite root-relative key.
+ *
+ * @param {string} projectDir - Absolute project root.
+ * @param {string} absolutePath - Absolute file or directory path.
+ * @returns {string} Root-relative path with a leading slash.
+ */
+export function toRootRelativePath(projectDir, absolutePath) {
+  if (!absolutePath) return '';
+
+  const normalizedProjectDir = normalizeProjectPath(projectDir);
+  const normalizedPath = normalizeProjectPath(absolutePath);
+
+  if (normalizedProjectDir && normalizedPath === normalizedProjectDir) {
+    return '/';
+  }
+
+  if (
+    normalizedProjectDir &&
+    normalizedPath.startsWith(`${normalizedProjectDir}/`)
+  ) {
+    return `/${normalizedPath.slice(normalizedProjectDir.length + 1)}`;
+  }
+
+  return `/${normalizedPath.replace(/^\/+/, '')}`;
+}

package/src/storybook/index.js

@@ -12,3 +12,7 @@ export {
   TwigHtmlStory,
   TwigStory,
 } from './render-twig.js';
+export {
+  defineCustomElement,
+  renderWebComponent,
+} from './render-web-component.js';

package/src/storybook/render-twig.js

@@ -7,7 +7,7 @@ import {
   attachStorybookBehaviors,
   normalizeStorybookPlatformAdapter,
 } from './platform-behaviors.js';
-import { TWIG_SOURCE_LOADED_EVENT } from './twig/source-events.js';
+import { TWIG_SOURCE_LOADED_EVENT } from './twig/constants.js';
 
 /**
  * Read the normalized Emulsify environment injected by Storybook's Vite config.