@fragments-sdk/cli 0.7.16 → 0.8.0

package/src/core/performance-presets.ts

@@ -0,0 +1,142 @@
+/**
+ * Performance budget presets and classification utilities.
+ *
+ * ESLint model: global defaults, zero-config, auto-measurement.
+ * Users configure 0-3 numbers. Per-component overrides are the `eslint-disable` equivalent.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PerformanceBudgets {
+  /** Maximum gzipped bundle size in bytes */
+  bundleSize: number;
+}
+
+export interface PerformanceConfig {
+  preset: string;
+  budgets: PerformanceBudgets;
+}
+
+export type ComplexityTier = 'lightweight' | 'moderate' | 'heavy';
+
+export interface PerformanceData {
+  /** Gzipped bundle size in bytes */
+  bundleSize: number;
+  /** Raw (minified, not gzipped) bundle size in bytes */
+  rawSize: number;
+  /** Complexity classification */
+  complexity: ComplexityTier;
+  /** Percentage of budget used (0-100+) */
+  budgetPercent: number;
+  /** Whether the component exceeds its budget */
+  overBudget: boolean;
+  /** ISO timestamp when measured */
+  measuredAt: string;
+}
+
+export interface PerformanceSummary {
+  /** Preset name used */
+  preset: string;
+  /** Budget applied in bytes */
+  budget: number;
+  /** Total components measured */
+  total: number;
+  /** Number of components over budget */
+  overBudget: number;
+  /** Distribution by tier */
+  tiers: Record<ComplexityTier, number>;
+}
+
+// ---------------------------------------------------------------------------
+// Presets
+// ---------------------------------------------------------------------------
+
+const PRESETS: Record<string, PerformanceBudgets> = {
+  strict: { bundleSize: 8 * 1024 },     // 8KB gzipped
+  standard: { bundleSize: 15 * 1024 },   // 15KB gzipped
+  relaxed: { bundleSize: 30 * 1024 },    // 30KB gzipped
+};
+
+export const PRESET_NAMES = Object.keys(PRESETS) as readonly string[];
+
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a performance config from user input.
+ * Accepts a preset name string or a custom config object.
+ */
+export function resolvePerformanceConfig(
+  input: string | { preset?: string; budgets?: Partial<PerformanceBudgets> } | undefined
+): PerformanceConfig {
+  if (!input) {
+    return { preset: 'standard', budgets: PRESETS.standard };
+  }
+
+  if (typeof input === 'string') {
+    const budgets = PRESETS[input];
+    if (!budgets) {
+      throw new Error(
+        `Unknown performance preset "${input}". Available: ${PRESET_NAMES.join(', ')}`
+      );
+    }
+    return { preset: input, budgets };
+  }
+
+  const presetName = input.preset ?? 'standard';
+  const baseBudgets = PRESETS[presetName];
+  if (!baseBudgets) {
+    throw new Error(
+      `Unknown performance preset "${presetName}". Available: ${PRESET_NAMES.join(', ')}`
+    );
+  }
+
+  return {
+    preset: presetName,
+    budgets: {
+      bundleSize: input.budgets?.bundleSize ?? baseBudgets.bundleSize,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Classification
+// ---------------------------------------------------------------------------
+
+/**
+ * Classify a component's complexity based on gzipped bundle size.
+ *
+ * - lightweight: < 5KB — simple, leaf components
+ * - moderate: < 15KB — typical composed components
+ * - heavy: >= 15KB — complex widgets with dependencies
+ */
+export function classifyComplexity(gzipBytes: number): ComplexityTier {
+  if (gzipBytes < 5 * 1024) return 'lightweight';
+  if (gzipBytes < 15 * 1024) return 'moderate';
+  return 'heavy';
+}
+
+// ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Format bytes to a human-readable string (e.g. "2.1KB", "15.3KB").
+ */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  const kb = bytes / 1024;
+  return kb < 10 ? `${kb.toFixed(1)}KB` : `${Math.round(kb)}KB`;
+}
+
+/**
+ * Create a visual budget bar for terminal output.
+ */
+export function budgetBar(percent: number, width = 20): string {
+  const filled = Math.min(Math.round((percent / 100) * width), width);
+  const bar = '█'.repeat(filled) + '░'.repeat(width - filled);
+  return percent > 100 ? `\x1b[31m${bar}\x1b[0m` : `\x1b[32m${bar}\x1b[0m`;
+}

package/src/core/schema.ts

@@ -133,6 +133,7 @@ export const fragmentContractSchema = z.object({
   a11yRules: z.array(z.string()).optional(),
   bans: z.array(fragmentBanSchema).optional(),
   scenarioTags: z.array(z.string()).optional(),
+  performanceBudget: z.number().positive().optional(),
 });
 
 /**
@@ -203,6 +204,15 @@ export const fragmentsConfigSchema = z.object({
     requireFullSnippet: z.boolean().optional(),
     allowedExternalModules: z.array(z.string().min(1)).optional(),
   }).optional(),
+  performance: z.union([
+    z.enum(['strict', 'standard', 'relaxed']),
+    z.object({
+      preset: z.enum(['strict', 'standard', 'relaxed']).optional(),
+      budgets: z.object({
+        bundleSize: z.number().positive().optional(),
+      }).optional(),
+    }),
+  ]).optional(),
 });
 
 /**

package/src/core/types.ts

@@ -303,6 +303,9 @@ export interface FragmentContract {
 
   /** Scenario tags for use-case matching (e.g., "form.submit", "navigation.primary") */
   scenarioTags?: string[];
+
+  /** Per-component performance budget override in bytes (gzipped). Overrides global budget. */
+  performanceBudget?: number;
 }
 
 /**
@@ -493,6 +496,9 @@ export interface FragmentsConfig {
 
   /** Snippet/render policy validation */
   snippets?: SnippetPolicyConfig;
+
+  /** Performance budgets: preset name or custom config */
+  performance?: string | { preset?: string; budgets?: { bundleSize?: number } };
 }
 
 /**

package/src/mcp/server.ts

@@ -1536,6 +1536,83 @@ export function createMcpServer(config: McpServerConfig): Server {
           }
         }
 
+        // ================================================================
+        // PERF — query performance data
+        // ================================================================
+        case TOOL_NAMES.perf: {
+          const data = await loadFragments();
+          const componentName = (args?.component as string) ?? undefined;
+          const sort = (args?.sort as string) ?? 'size';
+          const filter = (args?.filter as string) ?? undefined;
+
+          // Collect components with performance data
+          let entries = Object.entries(data.fragments)
+            .filter(([, f]) => f.performance)
+            .map(([name, f]) => ({
+              name,
+              ...f.performance!,
+            }));
+
+          if (entries.length === 0) {
+            return {
+              content: [{
+                type: 'text' as const,
+                text: JSON.stringify({
+                  total: 0,
+                  components: [],
+                  hint: `No performance data found. Run \`${BRAND.cliCommand} perf\` first to measure bundle sizes.`,
+                }, null, 2),
+              }],
+            };
+          }
+
+          // Filter by specific component
+          if (componentName) {
+            entries = entries.filter(
+              (e) => e.name.toLowerCase() === componentName.toLowerCase()
+            );
+            if (entries.length === 0) {
+              throw new Error(
+                `No performance data for "${componentName}". Run \`${BRAND.cliCommand} perf --component ${componentName}\` first.`
+              );
+            }
+          }
+
+          // Filter by tier or over-budget
+          if (filter) {
+            if (filter === 'over-budget') {
+              entries = entries.filter((e) => e.overBudget);
+            } else {
+              entries = entries.filter((e) => e.complexity === filter);
+            }
+          }
+
+          // Sort
+          switch (sort) {
+            case 'name':
+              entries.sort((a, b) => a.name.localeCompare(b.name));
+              break;
+            case 'budget':
+              entries.sort((a, b) => b.budgetPercent - a.budgetPercent);
+              break;
+            case 'size':
+            default:
+              entries.sort((a, b) => b.bundleSize - a.bundleSize);
+              break;
+          }
+
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify({
+                total: entries.length,
+                summary: data.performanceSummary ?? undefined,
+                components: entries,
+              }, null, 2),
+            }],
+          };
+        }
+
         default:
           throw new Error(`Unknown tool: ${name}`);
       }