@fragments-sdk/cli 0.7.17 → 0.8.0

package/src/commands/perf.ts

@@ -0,0 +1,249 @@
+/**
+ * `fragments perf` — Component performance profiling command.
+ *
+ * Measures bundle sizes for all components, classifies complexity,
+ * compares against budgets, and optionally writes results to fragments.json.
+ */
+
+import pc from 'picocolors';
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { loadConfig } from '../core/node.js';
+import { BRAND } from '../core/index.js';
+import {
+  resolvePerformanceConfig,
+  formatBytes,
+  budgetBar,
+  type PerformanceConfig,
+  type ComplexityTier,
+} from '../core/performance-presets.js';
+import {
+  measureBundleSizes,
+  toPerformanceData,
+} from '../core/bundle-measurer.js';
+import type {
+  CompiledFragmentsFile,
+  PerformanceData,
+  PerformanceSummary,
+} from '@fragments-sdk/context/types';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface PerfOptions {
+  config?: string;
+  json?: boolean;
+  component?: string;
+  write?: boolean;
+  concurrency?: number;
+  detail?: boolean;
+}
+
+interface PerfResult {
+  success: boolean;
+  total: number;
+  overBudget: number;
+}
+
+// ---------------------------------------------------------------------------
+// Command implementation
+// ---------------------------------------------------------------------------
+
+export async function perf(options: PerfOptions): Promise<PerfResult> {
+  const { config: configPath, json, component, concurrency, detail } = options;
+  const shouldWrite = options.write !== false; // default true
+
+  // Load config
+  const { config, configDir } = await loadConfig(configPath);
+  const perfConfig = resolvePerformanceConfig(config.performance ?? 'standard');
+
+  // Load fragments.json
+  const outFile = resolve(configDir, config.outFile ?? BRAND.outFile);
+  let data: CompiledFragmentsFile;
+  try {
+    data = JSON.parse(await readFile(outFile, 'utf-8'));
+  } catch {
+    throw new Error(
+      `Could not read ${BRAND.outFile}. Run \`${BRAND.cliCommand} build\` first.`
+    );
+  }
+
+  // Filter to specific component if requested
+  let fragments = data.fragments;
+  if (component) {
+    const match = Object.entries(fragments).find(
+      ([name]) => name.toLowerCase() === component.toLowerCase()
+    );
+    if (!match) {
+      throw new Error(
+        `Component "${component}" not found in ${BRAND.outFile}.`
+      );
+    }
+    fragments = { [match[0]]: match[1] };
+  }
+
+  if (!json) {
+    console.log(pc.cyan(`\n${BRAND.name} Performance Profiler\n`));
+    console.log(pc.dim(`Preset: ${perfConfig.preset} (${formatBytes(perfConfig.budgets.bundleSize)} budget)`));
+    console.log(pc.dim(`Measuring ${Object.keys(fragments).length} component(s)...\n`));
+  }
+
+  // Measure
+  const result = await measureBundleSizes(fragments, configDir, {
+    concurrency: concurrency ?? 4,
+    perfConfig,
+    onProgress: !json ? (done, total, name) => {
+      process.stdout.write(`\r${pc.dim(`[${done}/${total}]`)} ${name}`);
+    } : undefined,
+  });
+
+  if (!json) {
+    // Clear progress line
+    process.stdout.write('\r' + ' '.repeat(80) + '\r');
+  }
+
+  // Build performance data for each component
+  const perfResults: Array<{
+    name: string;
+    data: PerformanceData;
+  }> = [];
+
+  for (const [name, measurement] of result.measurements) {
+    const fragment = fragments[name];
+    const contractBudget = fragment?.contract?.performanceBudget as number | undefined;
+    const perfData = toPerformanceData(measurement, perfConfig, contractBudget);
+    perfResults.push({ name, data: perfData });
+  }
+
+  // Sort by gzip size descending
+  perfResults.sort((a, b) => b.data.bundleSize - a.data.bundleSize);
+
+  // Summary stats
+  const tiers: Record<ComplexityTier, number> = { lightweight: 0, moderate: 0, heavy: 0 };
+  let overBudgetCount = 0;
+  for (const { data: d } of perfResults) {
+    tiers[d.complexity]++;
+    if (d.overBudget) overBudgetCount++;
+  }
+
+  if (json) {
+    // JSON output mode
+    const output = {
+      preset: perfConfig.preset,
+      budget: perfConfig.budgets.bundleSize,
+      total: perfResults.length,
+      overBudget: overBudgetCount,
+      tiers,
+      components: perfResults.map(({ name, data: d }) => ({
+        name,
+        ...d,
+      })),
+      errors: result.errors,
+      elapsed: result.elapsed,
+    };
+    console.log(JSON.stringify(output, null, 2));
+  } else {
+    // Table output
+    const nameWidth = Math.max(20, ...perfResults.map(r => r.name.length)) + 2;
+
+    console.log(
+      pc.bold(
+        'Component'.padEnd(nameWidth) +
+        'Gzip'.padStart(8) +
+        'Raw'.padStart(10) +
+        'Budget'.padStart(8) +
+        'Tier'.padStart(14) +
+        '  Bar'
+      )
+    );
+    console.log(pc.dim('─'.repeat(nameWidth + 60)));
+
+    for (const { name, data: d } of perfResults) {
+      const tierColor = d.complexity === 'lightweight' ? pc.green
+        : d.complexity === 'moderate' ? pc.yellow
+        : pc.red;
+      const budgetColor = d.overBudget ? pc.red : pc.green;
+
+      console.log(
+        name.padEnd(nameWidth) +
+        formatBytes(d.bundleSize).padStart(8) +
+        formatBytes(d.rawSize).padStart(10) +
+        budgetColor(`${d.budgetPercent}%`.padStart(8)) +
+        tierColor(d.complexity.padStart(14)) +
+        '  ' + budgetBar(d.budgetPercent)
+      );
+
+      // Show import breakdown for over-budget components or when --detail is set
+      if (d.imports?.length && (detail || d.overBudget)) {
+        for (const imp of d.imports.slice(0, 5)) {
+          const barWidth = Math.max(1, Math.round(imp.percent / 5));
+          const impBar = pc.dim('█'.repeat(barWidth));
+          console.log(
+            pc.dim('  └── ') +
+            pc.dim(imp.path.length > 50 ? '…' + imp.path.slice(-49) : imp.path) +
+            pc.dim(` → ${formatBytes(imp.bytes)} (${imp.percent}%) `) +
+            impBar
+          );
+        }
+        if (d.imports.length > 5) {
+          console.log(pc.dim(`  └── … and ${d.imports.length - 5} more files`));
+        }
+      }
+    }
+
+    console.log(pc.dim('─'.repeat(nameWidth + 60)));
+
+    // Error summary
+    if (result.errors.length > 0) {
+      console.log(pc.yellow(`\n${result.errors.length} component(s) could not be measured:`));
+      for (const err of result.errors.slice(0, 5)) {
+        console.log(pc.dim(`  ${err.name}: ${err.error}`));
+      }
+      if (result.errors.length > 5) {
+        console.log(pc.dim(`  ... and ${result.errors.length - 5} more`));
+      }
+    }
+
+    // Summary
+    console.log(`\n${pc.bold('Summary')}`);
+    console.log(`  Total: ${perfResults.length} components measured in ${(result.elapsed / 1000).toFixed(1)}s`);
+    console.log(`  Tiers: ${pc.green(`${tiers.lightweight} lightweight`)} · ${pc.yellow(`${tiers.moderate} moderate`)} · ${pc.red(`${tiers.heavy} heavy`)}`);
+
+    if (overBudgetCount > 0) {
+      console.log(pc.red(`  Over budget: ${overBudgetCount} component(s) exceed ${formatBytes(perfConfig.budgets.bundleSize)} budget`));
+    } else {
+      console.log(pc.green('  All components within budget'));
+    }
+    console.log('');
+  }
+
+  // Write results back to fragments.json
+  if (shouldWrite && perfResults.length > 0) {
+    for (const { name, data: d } of perfResults) {
+      if (data.fragments[name]) {
+        data.fragments[name].performance = d;
+      }
+    }
+
+    data.performanceSummary = {
+      preset: perfConfig.preset,
+      budget: perfConfig.budgets.bundleSize,
+      total: perfResults.length,
+      overBudget: overBudgetCount,
+      tiers,
+    };
+
+    await writeFile(outFile, JSON.stringify(data));
+
+    if (!json) {
+      console.log(pc.dim(`Results written to ${BRAND.outFile}`));
+    }
+  }
+
+  return {
+    success: overBudgetCount === 0,
+    total: perfResults.length,
+    overBudget: overBudgetCount,
+  };
+}

package/src/core/bundle-measurer.ts

@@ -0,0 +1,421 @@
+/**
+ * Bundle size measurement for individual components.
+ *
+ * Uses esbuild to create single-entry bundles per component,
+ * then measures minified + gzipped size. CSS/SCSS/SVG are stubbed
+ * out since we only measure the JS bundle.
+ */
+
+import { build, type Metafile } from 'esbuild';
+import { gzipSync } from 'node:zlib';
+import { resolve, dirname, join, basename } from 'node:path';
+import { existsSync } from 'node:fs';
+import type { CompiledFragment } from '@fragments-sdk/context/types';
+import {
+  resolvePerformanceConfig,
+  classifyComplexity,
+  type PerformanceConfig,
+  type PerformanceData,
+} from './performance-presets.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface BundleImport {
+  path: string;
+  bytes: number;
+}
+
+export interface BundleMeasurement {
+  name: string;
+  rawBytes: number;
+  gzipBytes: number;
+  /** Per-file byte breakdown from esbuild metafile */
+  imports?: BundleImport[];
+}
+
+export interface MeasureOptions {
+  /** Max concurrent esbuild invocations (default: 4) */
+  concurrency?: number;
+  /** Performance config for budget calculation */
+  perfConfig?: PerformanceConfig;
+  /** Callback for progress reporting */
+  onProgress?: (completed: number, total: number, name: string) => void;
+}
+
+export interface MeasureResult {
+  measurements: Map<string, BundleMeasurement>;
+  errors: Array<{ name: string; error: string }>;
+  elapsed: number;
+}
+
+// ---------------------------------------------------------------------------
+// Entry point resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the component entry point from a fragment file path.
+ * Fragments are colocated: `Button/Button.fragment.tsx` → `Button/index.tsx`
+ */
+export function resolveEntryPoint(fragmentFilePath: string, configDir: string): string | null {
+  const absPath = resolve(configDir, fragmentFilePath);
+  const dir = dirname(absPath);
+
+  // Try sibling index files
+  const candidates = ['index.tsx', 'index.ts', 'index.jsx', 'index.js'];
+  for (const candidate of candidates) {
+    const path = join(dir, candidate);
+    if (existsSync(path)) return path;
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Import graph grouping
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize an esbuild metafile path to a human-friendly label.
+ * Local files → "Markdown" (component name)
+ * node_modules → "react-markdown" (package name only)
+ */
+function labelForPath(filePath: string): string {
+  // node_modules: extract package name from the LAST node_modules/ segment
+  // (pnpm store paths have multiple: .pnpm/pkg@ver/node_modules/pkg/...)
+  const lastNmIdx = filePath.lastIndexOf('node_modules/');
+  if (lastNmIdx >= 0) {
+    const afterNm = filePath.slice(lastNmIdx + 'node_modules/'.length);
+    // Scoped package: @scope/name, otherwise just name
+    if (afterNm.startsWith('@')) {
+      const parts = afterNm.split('/');
+      return parts.slice(0, 2).join('/');
+    }
+    return afterNm.split('/')[0];
+  }
+  // Local component: extract component name from path
+  const componentsIdx = filePath.indexOf('components/');
+  if (componentsIdx >= 0) {
+    const afterComponents = filePath.slice(componentsIdx + 'components/'.length);
+    const componentName = afterComponents.split('/')[0];
+    return componentName;
+  }
+  const srcIdx = filePath.indexOf('src/');
+  if (srcIdx >= 0) return filePath.slice(srcIdx);
+  return filePath;
+}
+
+/**
+ * Trace the import graph from the entry point's direct imports.
+ * Groups all transitive dependencies under each direct import,
+ * so "Markdown → 49KB" instead of 10 individual micromark packages.
+ */
+function groupImportsByDirectDep(
+  metafile: Metafile,
+  entryPoint: string,
+): BundleImport[] {
+  const inputs = metafile.inputs;
+  const outputKey = Object.keys(metafile.outputs)[0];
+  const outputMeta = outputKey ? metafile.outputs[outputKey] : undefined;
+  if (!outputMeta?.inputs) return [];
+
+  // Map of file → bytesInOutput
+  const bytesMap = new Map<string, number>();
+  for (const [path, info] of Object.entries(outputMeta.inputs)) {
+    if (info.bytesInOutput > 0) {
+      bytesMap.set(path, info.bytesInOutput);
+    }
+  }
+
+  // Find the entry point key in metafile inputs (esbuild may use relative paths)
+  let entryKey: string | undefined;
+  for (const key of Object.keys(inputs)) {
+    if (key === entryPoint || entryPoint.endsWith(key) || key.endsWith(basename(entryPoint))) {
+      // Match by suffix — esbuild paths are relative to cwd
+      const entryDir = dirname(entryPoint);
+      if (key.includes(basename(entryDir))) {
+        entryKey = key;
+        break;
+      }
+    }
+  }
+  // Fallback: try exact match or find by component name
+  if (!entryKey) {
+    const entryBasename = basename(dirname(entryPoint)); // e.g., "Message"
+    for (const key of Object.keys(inputs)) {
+      if (key.includes(`/${entryBasename}/index.`)) {
+        entryKey = key;
+        break;
+      }
+    }
+  }
+
+  if (!entryKey || !inputs[entryKey]) {
+    // Fallback: return flat list grouped by npm package
+    return groupByPackage(bytesMap);
+  }
+
+  // Get direct imports of the entry point
+  const directImports = inputs[entryKey].imports
+    .map((imp) => imp.path)
+    .filter((p) => inputs[p]); // Only resolved inputs
+
+  // BFS from each direct import to find its transitive closure
+  const claimed = new Set<string>();
+  claimed.add(entryKey); // Don't count entry in any group
+
+  const groupMap = new Map<string, BundleImport>();
+
+  for (const directPath of directImports) {
+    if (claimed.has(directPath)) continue;
+
+    // BFS to find all files reachable from this direct import
+    const queue = [directPath];
+    const reachable = new Set<string>();
+    while (queue.length > 0) {
+      const current = queue.pop()!;
+      if (reachable.has(current) || claimed.has(current)) continue;
+      reachable.add(current);
+      claimed.add(current);
+
+      const entry = inputs[current];
+      if (entry?.imports) {
+        for (const imp of entry.imports) {
+          if (inputs[imp.path] && !claimed.has(imp.path)) {
+            queue.push(imp.path);
+          }
+        }
+      }
+    }
+
+    // Sum bytes for all reachable files
+    let totalBytes = 0;
+    for (const path of reachable) {
+      totalBytes += bytesMap.get(path) ?? 0;
+    }
+
+    if (totalBytes > 0) {
+      const label = labelForPath(directPath);
+      // Merge with existing group if same label (e.g., two files from same package)
+      const existing = groupMap.get(label);
+      if (existing) {
+        existing.bytes += totalBytes;
+      } else {
+        const entry = { path: label, bytes: totalBytes };
+        groupMap.set(label, entry);
+      }
+    }
+  }
+
+  // Add entry point's own bytes + merge any same-component imports into (self)
+  const entryLabel = labelForPath(entryKey);
+  const selfLabel = entryLabel + ' (self)';
+  let selfBytes = bytesMap.get(entryKey) ?? 0;
+
+  // Merge sibling files (e.g., .module.scss) that resolved to same component name
+  const siblingGroup = groupMap.get(entryLabel);
+  if (siblingGroup) {
+    selfBytes += siblingGroup.bytes;
+    groupMap.delete(entryLabel);
+  }
+
+  if (selfBytes > 0) {
+    groupMap.set(selfLabel, { path: selfLabel, bytes: selfBytes });
+  }
+
+  // Add any unclaimed files (shouldn't happen often)
+  let unclaimedBytes = 0;
+  for (const [path, bytes] of bytesMap) {
+    if (!claimed.has(path)) unclaimedBytes += bytes;
+  }
+  if (unclaimedBytes > 0) {
+    groupMap.set('(other)', { path: '(other)', bytes: unclaimedBytes });
+  }
+
+  return [...groupMap.values()].sort((a, b) => b.bytes - a.bytes);
+}
+
+/**
+ * Fallback: group flat file list by npm package name.
+ */
+function groupByPackage(bytesMap: Map<string, number>): BundleImport[] {
+  const groups = new Map<string, number>();
+  for (const [path, bytes] of bytesMap) {
+    const label = labelForPath(path);
+    // For node_modules, just use package name; for local files, use full label
+    const key = label.includes('/') && !label.startsWith('components/')
+      ? label.split('/').slice(0, label.startsWith('@') ? 2 : 1).join('/')
+      : label;
+    groups.set(key, (groups.get(key) ?? 0) + bytes);
+  }
+  return [...groups.entries()]
+    .map(([path, bytes]) => ({ path, bytes }))
+    .sort((a, b) => b.bytes - a.bytes);
+}
+
+// ---------------------------------------------------------------------------
+// Single component measurement
+// ---------------------------------------------------------------------------
+
+/**
+ * Measure the bundle size of a single component entry point.
+ */
+export async function measureSingleComponent(
+  entryPoint: string,
+  name: string
+): Promise<BundleMeasurement> {
+  const result = await build({
+    entryPoints: [entryPoint],
+    bundle: true,
+    write: false,
+    minify: true,
+    metafile: true,
+    format: 'esm',
+    target: 'es2020',
+    platform: 'browser',
+    treeShaking: true,
+    external: [
+      'react',
+      'react-dom',
+      'react/jsx-runtime',
+      'react/jsx-dev-runtime',
+      // Optional peer deps — excluded from measurement
+      'recharts',
+      'shiki',
+      'react-day-picker',
+      '@tanstack/react-table',
+      'date-fns',
+      '@base-ui-components/*',
+      '@base-ui/react/*',
+    ],
+    loader: {
+      '.scss': 'empty',
+      '.css': 'empty',
+      '.svg': 'empty',
+      '.png': 'empty',
+      '.jpg': 'empty',
+      '.gif': 'empty',
+      '.woff': 'empty',
+      '.woff2': 'empty',
+      '.ttf': 'empty',
+      '.eot': 'empty',
+    },
+    logLevel: 'silent',
+  });
+
+  const output = result.outputFiles[0];
+  const rawBytes = output.contents.byteLength;
+  const gzipBytes = gzipSync(output.contents).byteLength;
+
+  // Group imports by the entry point's direct dependencies
+  const imports = result.metafile
+    ? groupImportsByDirectDep(result.metafile, entryPoint)
+    : undefined;
+
+  return { name, rawBytes, gzipBytes, imports };
+}
+
+// ---------------------------------------------------------------------------
+// Batch measurement with concurrency control
+// ---------------------------------------------------------------------------
+
+/**
+ * Measure bundle sizes for all fragments with concurrency control.
+ */
+export async function measureBundleSizes(
+  fragments: Record<string, CompiledFragment>,
+  configDir: string,
+  options: MeasureOptions = {}
+): Promise<MeasureResult> {
+  const concurrency = options.concurrency ?? 4;
+  const measurements = new Map<string, BundleMeasurement>();
+  const errors: MeasureResult['errors'] = [];
+  const start = Date.now();
+
+  // Resolve all entry points first
+  const entries: Array<{ name: string; entryPoint: string }> = [];
+  for (const [name, fragment] of Object.entries(fragments)) {
+    const entryPoint = resolveEntryPoint(fragment.filePath, configDir);
+    if (entryPoint) {
+      entries.push({ name, entryPoint });
+    } else {
+      errors.push({
+        name,
+        error: `Could not resolve entry point from ${fragment.filePath}`,
+      });
+    }
+  }
+
+  // Process in batches
+  let completed = 0;
+  for (let i = 0; i < entries.length; i += concurrency) {
+    const batch = entries.slice(i, i + concurrency);
+    const results = await Promise.allSettled(
+      batch.map(({ name, entryPoint }) =>
+        measureSingleComponent(entryPoint, name)
+      )
+    );
+
+    for (let j = 0; j < results.length; j++) {
+      const result = results[j];
+      const { name } = batch[j];
+      completed++;
+
+      if (result.status === 'fulfilled') {
+        measurements.set(name, result.value);
+      } else {
+        errors.push({
+          name,
+          error: result.reason instanceof Error
+            ? result.reason.message
+            : String(result.reason),
+        });
+      }
+
+      options.onProgress?.(completed, entries.length, name);
+    }
+  }
+
+  return {
+    measurements,
+    errors,
+    elapsed: Date.now() - start,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Convert to PerformanceData
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a raw measurement into a PerformanceData object.
+ * Uses per-component budget override if set in the fragment's contract.
+ */
+export function toPerformanceData(
+  measurement: BundleMeasurement,
+  config: PerformanceConfig,
+  contractBudget?: number
+): PerformanceData {
+  const budget = contractBudget ?? config.budgets.bundleSize;
+  const budgetPercent = Math.round((measurement.gzipBytes / budget) * 100);
+
+  // Build top imports list (top 10, with percentage)
+  const imports = measurement.imports
+    ?.slice(0, 10)
+    .map((imp) => ({
+      path: imp.path,
+      bytes: imp.bytes,
+      percent: Math.round((imp.bytes / measurement.rawBytes) * 100),
+    }));
+
+  return {
+    bundleSize: measurement.gzipBytes,
+    rawSize: measurement.rawBytes,
+    complexity: classifyComplexity(measurement.gzipBytes),
+    budgetPercent,
+    overBudget: budgetPercent > 100,
+    measuredAt: new Date().toISOString(),
+    ...(imports && imports.length > 0 ? { imports } : {}),
+  };
+}

package/src/core/index.ts

@@ -64,6 +64,22 @@ export type {
   CompiledTokenData,
 } from "./types.js";
 
+// Performance presets
+export {
+  resolvePerformanceConfig,
+  classifyComplexity,
+  formatBytes,
+  budgetBar,
+  PRESET_NAMES,
+} from "./performance-presets.js";
+export type {
+  PerformanceBudgets,
+  PerformanceConfig,
+  ComplexityTier,
+  PerformanceData as PerfData,
+  PerformanceSummary as PerfSummary,
+} from "./performance-presets.js";
+
 // Token types
 export type {
   TokenCategory,