@emulsify/core 4.2.0 → 4.3.0

package/scripts/audit/lib/twig.js

@@ -0,0 +1,227 @@
+/**
+ * @file Twig reference parsing and resolution helpers for the project audit.
+ */
+
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { safeExists } from '../../../config/vite/utils/fs-safe.js';
+import { candidateKeysForReference } from '../../../src/storybook/twig/reference-paths.js';
+import { lineNumberAt } from '../../lib/text.js';
+import { isSameOrInside } from './files.js';
+
+const GENERATED_ASSET_ALIASES = new Set(['icons.svg']);
+
+/**
+ * Extract string arguments passed to include() or source().
+ *
+ * @param {string} source - Twig source.
+ * @returns {{type: string, value: string, line: number}[]} References.
+ */
+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)),
+      });
+    }
+  }
+
+  return references;
+}
+
+/**
+ * Extract the first function argument, including array syntax.
+ *
+ * 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.
+ *
+ * @param {string} args - Function argument source.
+ * @returns {string} First argument source.
+ */
+function firstArgumentText(args) {
+  let quote = '';
+  let depth = 0;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const char = args[index];
+    const prev = args[index - 1];
+
+    if (quote) {
+      if (char === quote && prev !== '\\') {
+        quote = '';
+      }
+      continue;
+    }
+
+    if (char === '"' || char.charCodeAt(0) === 39) {
+      quote = char;
+      continue;
+    }
+    if (char === '[' || char === '{' || char === '(') {
+      depth += 1;
+      continue;
+    }
+    if (char === ']' || char === '}' || char === ')') {
+      depth = Math.max(0, depth - 1);
+      continue;
+    }
+    if (char === ',' && depth === 0) {
+      return args.slice(0, index);
+    }
+  }
+
+  return args;
+}
+
+/**
+ * Extract Twig namespace references such as @components/card/card.twig.
+ *
+ * @param {string} source - Twig source.
+ * @returns {{namespace: string, value: string, line: number}[]} Namespace refs.
+ */
+export function findTwigNamespaceReferences(source) {
+  const references = [];
+  const pattern = /@([A-Za-z][\w-]*)\/[A-Za-z0-9_./-]+/g;
+
+  for (const match of source.matchAll(pattern)) {
+    references.push({
+      namespace: match[1],
+      value: match[0],
+      line: lineNumberAt(source, match.index || 0),
+    });
+  }
+
+  return references;
+}
+
+/**
+ * Build candidate paths for a relative Twig reference.
+ *
+ * @param {string} filePath - Referencing file.
+ * @param {string} reference - Twig reference.
+ * @returns {string[]} Absolute candidate paths.
+ */
+function relativeTwigCandidates(filePath, reference) {
+  const base = resolve(dirname(filePath), reference);
+  if (/\.[A-Za-z0-9]+$/.test(reference)) {
+    return [base];
+  }
+
+  return [`${base}.twig`, `${base}.html.twig`];
+}
+
+/**
+ * Convert resolver candidate keys into absolute filesystem paths.
+ *
+ * @param {string[]} keys - Root-relative Vite keys.
+ * @param {object} env - Normalized environment.
+ * @returns {string[]} Absolute candidate paths.
+ */
+function candidateKeysToFiles(keys, env) {
+  const projectDir = env.projectDir || process.cwd();
+
+  return keys.map((key) =>
+    key.startsWith('/') ? resolve(projectDir, key.slice(1)) : resolve(key),
+  );
+}
+
+/**
+ * Resolve an audit asset root using Storybook's root-relative convention.
+ *
+ * @param {string} projectDir - Absolute project root.
+ * @param {string} assetRoot - Configured, absolute, or project-relative root.
+ * @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 filesystem roots that Storybook can use for @assets source() calls.
+ *
+ * @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),
+    ),
+  );
+}
+
+/**
+ * Determine whether an @assets reference resolves through Storybook asset roots.
+ *
+ * @param {string} reference - Twig @assets reference.
+ * @param {object} env - Normalized environment.
+ * @returns {boolean} TRUE when a candidate exists.
+ */
+function resolvesAssetReference(reference, env) {
+  const relAsset = reference.replace(/^@assets\//, '');
+  if (!relAsset) return false;
+  const includeGenerated = GENERATED_ASSET_ALIASES.has(relAsset);
+
+  return auditAssetRoots(env, { includeGenerated }).some((root) => {
+    const candidate = resolve(root, relAsset);
+
+    return isSameOrInside(candidate, root) && safeExists(candidate);
+  });
+}
+
+/**
+ * Determine whether a Twig include/source reference resolves.
+ *
+ * @param {string} reference - Twig reference.
+ * @param {string} filePath - Referencing file path.
+ * @param {object} env - Normalized environment.
+ * @returns {boolean} TRUE when a candidate exists.
+ */
+export function resolvesTwigReference(reference, filePath, env) {
+  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);
+
+  return candidates.some(safeExists);
+}

package/scripts/audit/report.js

@@ -0,0 +1,273 @@
+/**
+ * @file Report formatting for the project audit.
+ */
+
+import { createRequire } from 'node:module';
+import { displayPath } from './lib/findings.js';
+
+const require = createRequire(import.meta.url);
+const corePackage = require('../../package.json');
+const summarySeverities = ['error', 'warn', 'info'];
+const fileCountKeys = ['stories', 'twig', 'code', 'styles'];
+
+export const AUDIT_REPORT_SCHEMA_VERSION = 1;
+
+/**
+ * Format one finding for terminal output.
+ *
+ * @param {object} finding - Finding to format.
+ * @param {string} projectDir - Project root.
+ * @returns {string[]} Output lines.
+ */
+function formatFinding(finding, projectDir) {
+  const location = finding.filePath
+    ? `${displayPath(projectDir, finding.filePath)}${
+        finding.line ? `:${finding.line}` : ''
+      }`
+    : 'project';
+  const lines = [
+    `[${finding.severity}] ${finding.id}`,
+    `  ${location}`,
+    `  ${finding.message}`,
+  ];
+
+  for (const detail of finding.details || []) {
+    lines.push(`  ${detail}`);
+  }
+  if (finding.docs) {
+    lines.push(`  Docs: ${finding.docs}`);
+  }
+
+  return lines;
+}
+
+/**
+ * Format the combined audit report.
+ *
+ * @param {{projectDir: string, summary: object, files: object, findings: object[]}} result
+ * Audit result.
+ * @returns {string} Human-readable report.
+ */
+export function formatAuditReport(result) {
+  const lines = [
+    'Emulsify project audit',
+    `Project: ${result.projectDir}`,
+    `Scanned ${result.files.stories} story file(s), ${result.files.twig} Twig file(s), ${result.files.code} code file(s), and ${result.files.styles} style file(s).`,
+    `Findings: ${result.summary.error} error(s), ${result.summary.warn} warning(s), ${result.summary.info} info item(s).`,
+  ];
+
+  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));
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Count findings by severity for machine-readable reports.
+ *
+ * @param {object[]} [findings=[]] - Findings to summarize.
+ * @param {string} [defaultSeverity='warn'] - Severity for findings without one.
+ * @returns {{error: number, warn: number, info: number}} Summary counts.
+ */
+export function summarizeFindings(findings = [], defaultSeverity = 'warn') {
+  return findings.reduce(
+    (summary, finding) => {
+      const severity = summarySeverities.includes(finding.severity)
+        ? finding.severity
+        : defaultSeverity;
+
+      if (summarySeverities.includes(severity)) {
+        summary[severity] += 1;
+      }
+
+      return summary;
+    },
+    {
+      error: 0,
+      warn: 0,
+      info: 0,
+    },
+  );
+}
+
+/**
+ * Return the package identity recorded in machine-readable audit documents.
+ *
+ * @returns {{name: string, version: string}} Tool identity.
+ */
+function createToolIdentity() {
+  return {
+    name: corePackage.name,
+    version: corePackage.version,
+  };
+}
+
+/**
+ * Remove the scanned absolute root from human-facing finding text.
+ *
+ * Internal checks may retain absolute paths. Machine-readable documents do not.
+ *
+ * @param {*} value - Finding text.
+ * @param {string} projectDir - Absolute scanned root.
+ * @returns {string} Portable text.
+ */
+function normalizeReportText(value, projectDir) {
+  let text = String(value);
+  const rootVariants = new Set([
+    projectDir,
+    projectDir.replaceAll('\\', '/'),
+    projectDir.replaceAll('/', '\\'),
+  ]);
+
+  for (const root of rootVariants) {
+    if (root) {
+      text = text.replaceAll(root, '.');
+    }
+  }
+
+  return text;
+}
+
+/**
+ * Normalize one internal finding for the public JSON contract.
+ *
+ * @param {object} finding - Internal finding.
+ * @param {string} projectDir - Absolute scanned root.
+ * @param {string} defaultSeverity - Severity for unclassified findings.
+ * @returns {object} Machine-readable finding.
+ */
+export function normalizeAuditFinding(
+  finding,
+  projectDir,
+  defaultSeverity = 'warn',
+) {
+  if (typeof finding.id !== 'string' || !finding.id.trim()) {
+    throw new TypeError('Audit finding is missing a non-empty "id".');
+  }
+  if (typeof finding.message !== 'string' || !finding.message.trim()) {
+    throw new TypeError(
+      `Audit finding "${finding.id}" is missing a non-empty "message".`,
+    );
+  }
+
+  const severity = summarySeverities.includes(finding.severity)
+    ? finding.severity
+    : summarySeverities.includes(defaultSeverity)
+      ? defaultSeverity
+      : 'warn';
+  const normalized = {
+    id: finding.id,
+    severity,
+  };
+
+  if (finding.filePath) {
+    normalized.path = displayPath(projectDir, finding.filePath) || '.';
+  }
+  if (Number.isInteger(finding.line) && finding.line > 0) {
+    normalized.line = finding.line;
+  }
+
+  normalized.message = normalizeReportText(finding.message, projectDir);
+
+  if (Array.isArray(finding.details) && finding.details.length) {
+    const details = finding.details
+      .filter((detail) => detail != null)
+      .map((detail) => normalizeReportText(detail, projectDir));
+    if (details.length) {
+      normalized.details = details;
+    }
+  }
+  if (typeof finding.docs === 'string' && finding.docs) {
+    normalized.docs = finding.docs;
+  }
+
+  return normalized;
+}
+
+/**
+ * Normalize scan counts into the fixed schema-v1 shape.
+ *
+ * @param {object} [files={}] - Internal file counts.
+ * @returns {{stories: number, twig: number, code: number, styles: number}}
+ * File counts.
+ */
+function normalizeFileCounts(files = {}) {
+  return Object.fromEntries(
+    fileCountKeys.map((key) => [
+      key,
+      Number.isInteger(files[key]) && files[key] >= 0 ? files[key] : 0,
+    ]),
+  );
+}
+
+/**
+ * Create the machine-readable audit report document.
+ *
+ * @param {{projectDir: string, files: object, findings: object[]}} result
+ * Audit result.
+ * @param {{defaultSeverity?: string}} [options={}] - Formatting options.
+ * @returns {object} JSON report document.
+ */
+export function createAuditJsonReport(result, options = {}) {
+  const findings = (result.findings || []).map((finding) =>
+    normalizeAuditFinding(finding, result.projectDir, options.defaultSeverity),
+  );
+
+  return {
+    schemaVersion: AUDIT_REPORT_SCHEMA_VERSION,
+    tool: createToolIdentity(),
+    root: '.',
+    summary: summarizeFindings(findings),
+    files: normalizeFileCounts(result.files),
+    findings,
+  };
+}
+
+/**
+ * Create a structured machine-readable CLI or audit failure.
+ *
+ * @param {*} error - Failure value.
+ * @param {{code?: string, projectDir?: string}} [options={}] - Error options.
+ * @returns {object} JSON error document.
+ */
+export function createAuditJsonErrorReport(error, options = {}) {
+  const message = error?.message || error;
+
+  return {
+    schemaVersion: AUDIT_REPORT_SCHEMA_VERSION,
+    tool: createToolIdentity(),
+    error: {
+      code: options.code || 'audit-failed',
+      message: normalizeReportText(message, options.projectDir || ''),
+    },
+  };
+}
+
+/**
+ * Format the audit report as machine-readable JSON.
+ *
+ * @param {{projectDir: string, files: object, findings: object[]}} result
+ * Audit result.
+ * @param {{defaultSeverity?: string}} [options={}] - Options.
+ * @returns {string} JSON report.
+ */
+export function formatAuditJsonReport(result, options = {}) {
+  return JSON.stringify(createAuditJsonReport(result, options), null, 2);
+}
+
+/**
+ * Format a CLI or audit failure as machine-readable JSON.
+ *
+ * @param {*} error - Failure value.
+ * @param {{code?: string, projectDir?: string}} [options={}] - Error options.
+ * @returns {string} JSON error document.
+ */
+export function formatAuditJsonErrorReport(error, options = {}) {
+  return JSON.stringify(createAuditJsonErrorReport(error, options), null, 2);
+}