@fragments-sdk/cli 0.10.1 → 0.12.1

package/src/viewer/bin.ts

@@ -1,86 +0,0 @@
-#!/usr/bin/env node
-import pc from 'picocolors';
-import { BRAND } from '../core/index.js';
-import { createDevServer } from './server.js';
-import { runCommand } from './cli/index.js';
-
-async function startDevServer(): Promise<void> {
-  const args = process.argv.slice(2);
-  const portArg = args.find((arg) => arg.startsWith('--port='));
-  const port = portArg ? parseInt(portArg.split('=')[1], 10) : 6006;
-  const noOpen = args.includes('--no-open');
-
-  console.log(pc.cyan(`\n${BRAND.name} Dev Server\n`));
-  console.log(pc.dim('Starting development server...\n'));
-
-  try {
-    const server = await createDevServer({
-      port,
-      open: !noOpen,
-    });
-
-    const address = server.httpServer?.address();
-    const actualPort = typeof address === 'object' && address ? address.port : port;
-
-    console.log(pc.green(`✓ Server running at http://localhost:${actualPort}\n`));
-    console.log(pc.dim('Press Ctrl+C to stop\n'));
-  } catch (error) {
-    console.error(pc.red('Failed to start server:'), error);
-    process.exit(1);
-  }
-}
-
-function showHelp(): void {
-  console.log(pc.cyan(`\n${BRAND.name} CLI\n`));
-  console.log(`Usage: ${BRAND.cliCommand} <command> [options]\n`);
-  console.log('Commands:');
-  console.log('  dev              Start the development server (default)');
-  console.log('  scan <dir>       Scan codebase for component usage');
-  console.log('  health           Generate design system health report');
-  console.log('');
-  console.log('Dev Server Options:');
-  console.log('  --port=<port>    Port to run on (default: 6006)');
-  console.log('  --no-open        Don\'t open browser automatically');
-  console.log('');
-  console.log('Scan Options:');
-  console.log('  --format=<fmt>   Output format: table, json (default: table)');
-  console.log('  --component=<n>  Filter to specific component');
-  console.log('  --verbose        Show detailed usage info');
-  console.log('');
-  console.log('Health Options:');
-  console.log('  --format=<fmt>   Output format: table, json, markdown (default: table)');
-  console.log('  --scan=<dir>     Include codebase usage scan');
-  console.log('  --ci             CI mode: exit 1 if score below threshold');
-  console.log('  --threshold=<n>  Minimum score for CI mode (default: 80)');
-  console.log('');
-}
-
-async function main(): Promise<void> {
-  const args = process.argv.slice(2);
-  const command = args[0];
-
-  // Show help
-  if (command === '--help' || command === '-h' || command === 'help') {
-    showHelp();
-    return;
-  }
-
-  // Route to subcommands
-  if (command === 'scan' || command === 'health') {
-    await runCommand(command, args.slice(1));
-    return;
-  }
-
-  // Default: start dev server (handles 'dev' command or no command)
-  if (!command || command === 'dev' || command.startsWith('--')) {
-    await startDevServer();
-    return;
-  }
-
-  // Unknown command
-  console.error(pc.red(`Unknown command: ${command}`));
-  console.log(pc.dim(`Run "${BRAND.cliCommand} --help" for usage information.\n`));
-  process.exit(1);
-}
-
-main();

package/src/viewer/cli/health.ts

@@ -1,256 +0,0 @@
-/**
- * Health Command
- * Generates a comprehensive design system health report
- */
-
-import pc from 'picocolors';
-import fs from 'fs';
-import path from 'path';
-import { BRAND } from '../../core/index.js';
-import { loadConfig } from '../../core/node.js';
-import { scanForUsages } from '../intelligence/usageScanner.js';
-import { generateHealthReport, formatHealthReportAsMarkdown, type HealthReport } from '../intelligence/healthReport.js';
-import {
-  parseArgs,
-  createSpinner,
-  formatScore,
-  printHeader,
-  printKV,
-  printWarning,
-  printSuccess,
-  formatList,
-} from './utils.js';
-
-type OutputFormat = 'table' | 'json' | 'markdown';
-
-interface HealthCommandOptions {
-  format: OutputFormat;
-  scanDir?: string;
-  ci: boolean;
-  threshold: number;
-}
-
-function parseOptions(args: string[]): HealthCommandOptions {
-  const { options } = parseArgs(args);
-
-  return {
-    format: (options.format as OutputFormat) || 'table',
-    scanDir: options.scan as string | undefined,
-    ci: !!options.ci,
-    threshold: options.threshold ? parseInt(options.threshold as string, 10) : 80,
-  };
-}
-
-/**
- * Load fragments from the project
- */
-async function loadFragments(): Promise<Array<{ path: string; fragment: any }>> {
-  const configResult = await loadConfig();
-
-  if (!configResult) {
-    throw new Error('No fragments.config.ts found. Run this command from a Fragments project.');
-  }
-
-  const { config } = configResult;
-
-  // Try to load compiled fragments
-  const fragmentsPath = path.resolve(process.cwd(), config.outFile || `${BRAND.dataDir}/${BRAND.outFile}`);
-
-  if (fs.existsSync(fragmentsPath)) {
-    const data = JSON.parse(fs.readFileSync(fragmentsPath, 'utf-8'));
-    return Object.entries(data.fragments || {}).map(([name, fragment]: [string, any]) => ({
-      path: fragment.filePath || name,
-      fragment: {
-        meta: fragment.meta || { name, description: '', category: '' },
-        usage: fragment.usage || { when: [], whenNot: [] },
-        props: fragment.props || {},
-        variants: fragment.variants || [],
-        relations: fragment.relations,
-        contract: fragment.contract,
-        _generated: fragment._generated,
-        component: () => null, // Placeholder
-      },
-    }));
-  }
-
-  // Fallback: return empty if no compiled fragments
-  console.log(pc.yellow(`No compiled fragments found. Run \`${BRAND.cliCommand} build\` first for complete analysis.`));
-  return [];
-}
-
-function formatGrade(grade: string): string {
-  switch (grade) {
-    case 'A':
-      return pc.green(pc.bold(grade));
-    case 'B':
-      return pc.cyan(grade);
-    case 'C':
-      return pc.yellow(grade);
-    case 'D':
-      return pc.magenta(grade);
-    case 'F':
-      return pc.red(pc.bold(grade));
-    default:
-      return grade;
-  }
-}
-
-function formatTableOutput(report: HealthReport): void {
-  console.log(pc.cyan(`\n${BRAND.name} Health Report\n`));
-  console.log(pc.dim(`Generated: ${new Date(report.generatedAt).toLocaleString()}\n`));
-
-  // Overall score
-  const scoreColor = report.overallScore >= 80 ? pc.green : report.overallScore >= 60 ? pc.yellow : pc.red;
-  console.log(`  ${pc.bold('Overall Score:')} ${scoreColor(pc.bold(`${report.overallScore}%`))}\n`);
-
-  // Grade summary
-  console.log(pc.bold('  Category Grades:\n'));
-  console.log(`    Usage:         ${formatGrade(report.grades.usage)}  (${report.usage.adoptionRate}% adoption)`);
-  console.log(`    Style Drift:   ${formatGrade(report.grades.drift)}  (${report.styleDrift.averageCompliance}% compliance)`);
-  console.log(`    Documentation: ${formatGrade(report.grades.documentation)}  (${report.documentation.documentationRate}% documented)`);
-  console.log(`    Token Usage:   ${formatGrade(report.grades.tokens)}  (${report.tokens.tokenizationRate}% tokenized)`);
-  console.log('');
-
-  // Usage section
-  printHeader('Usage Statistics');
-  printKV('Total Components', report.usage.totalComponents.toString());
-  printKV('Used Components', report.usage.usedComponents.toString());
-  printKV('Adoption Rate', formatScore(report.usage.adoptionRate));
-
-  if (report.usage.mostUsed.length > 0) {
-    console.log(pc.dim('\n  Most Used:'));
-    for (const item of report.usage.mostUsed.slice(0, 5)) {
-      console.log(`    ${pc.cyan(item.component)}: ${item.count} uses`);
-    }
-  }
-
-  if (report.usage.unusedComponents.length > 0 && report.usage.unusedComponents.length <= 5) {
-    console.log(pc.dim('\n  Unused:'));
-    for (const name of report.usage.unusedComponents) {
-      printWarning(name);
-    }
-  } else if (report.usage.unusedComponents.length > 5) {
-    printWarning(`${report.usage.unusedComponents.length} unused components`);
-  }
-
-  // Style Drift section
-  printHeader('Style Drift Analysis');
-  printKV('Components with Drift', report.styleDrift.componentsWithDrift.toString());
-  printKV('Total Drifts', report.styleDrift.totalDrifts.toString());
-  printKV('Average Compliance', formatScore(report.styleDrift.averageCompliance));
-
-  if (report.styleDrift.bySeverity.high > 0) {
-    console.log('');
-    printWarning(`${report.styleDrift.bySeverity.high} high-severity drift(s) - affects brand identity`);
-  }
-
-  if (report.styleDrift.worstOffenders.length > 0) {
-    console.log(pc.dim('\n  Needs Attention:'));
-    for (const item of report.styleDrift.worstOffenders.slice(0, 3)) {
-      console.log(`    ${pc.red('!')} ${item.component} (${item.variant}): ${item.driftCount} drifts`);
-    }
-  }
-
-  // Documentation section
-  printHeader('Documentation Coverage');
-  printKV('Documented', `${report.documentation.documented} components`);
-  printKV('Coverage', formatScore(report.documentation.documentationRate));
-
-  if (report.documentation.missingDescriptions.length > 0) {
-    printWarning(`${report.documentation.missingDescriptions.length} missing descriptions`);
-  }
-
-  if (report.documentation.missingUsage.length > 0) {
-    printWarning(`${report.documentation.missingUsage.length} missing usage guidelines`);
-  }
-
-  // Token section
-  printHeader('Design Token Usage');
-  printKV('Token Compliance', formatScore(report.tokens.complianceScore));
-  printKV('Tokenized Values', report.tokens.tokenizedValues.toString());
-  printKV('Hardcoded Values', report.tokens.hardcodedValues.toString(), report.tokens.hardcodedValues > 0 ? pc.yellow : undefined);
-
-  // Recommendations
-  if (report.recommendations.length > 0) {
-    printHeader('Recommendations');
-    console.log('');
-    for (const rec of report.recommendations) {
-      console.log(`  ${pc.yellow('→')} ${rec}`);
-    }
-  }
-
-  console.log('');
-}
-
-function formatJsonOutput(report: HealthReport): void {
-  console.log(JSON.stringify(report, null, 2));
-}
-
-function formatMarkdownOutput(report: HealthReport): void {
-  console.log(formatHealthReportAsMarkdown(report));
-}
-
-/**
- * Run the health command
- */
-export async function healthCommand(args: string[]): Promise<void> {
-  const options = parseOptions(args);
-
-  const spinner = createSpinner('Analyzing design system health...');
-  spinner.start();
-
-  try {
-    // Load fragments
-    spinner.update('Loading fragments...');
-    const fragments = await loadFragments();
-
-    if (fragments.length === 0) {
-      spinner.stop(false, 'No fragments found');
-      console.log(pc.yellow(`\nNo components to analyze. Create fragment files or run \`${BRAND.cliCommand} build\`.\n`));
-      return;
-    }
-
-    // Run usage scan if directory provided
-    let usageScan;
-    if (options.scanDir) {
-      spinner.update(`Scanning ${options.scanDir} for component usage...`);
-      usageScan = await scanForUsages({ directory: options.scanDir });
-    }
-
-    // Generate report
-    spinner.update('Generating health report...');
-    const report = generateHealthReport({
-      fragments,
-      usageScan,
-      // Note: Drift reports would require running the viewer and extracting styles
-      // For CLI, we focus on what can be statically analyzed
-    });
-
-    spinner.stop(true, 'Health analysis complete');
-
-    // Output
-    switch (options.format) {
-      case 'json':
-        formatJsonOutput(report);
-        break;
-      case 'markdown':
-        formatMarkdownOutput(report);
-        break;
-      default:
-        formatTableOutput(report);
-    }
-
-    // CI mode: exit with error if below threshold
-    if (options.ci) {
-      if (report.overallScore < options.threshold) {
-        console.log(pc.red(`\nCI Check Failed: Score ${report.overallScore}% is below threshold ${options.threshold}%\n`));
-        process.exit(1);
-      } else {
-        console.log(pc.green(`\nCI Check Passed: Score ${report.overallScore}% meets threshold ${options.threshold}%\n`));
-      }
-    }
-  } catch (error) {
-    spinner.stop(false, 'Health analysis failed');
-    throw error;
-  }
-}

package/src/viewer/cli/index.ts

@@ -1,33 +0,0 @@
-/**
- * CLI Command Router
- * Routes subcommands to their respective handlers
- */
-
-import pc from 'picocolors';
-import { scanCommand } from './scan.js';
-import { healthCommand } from './health.js';
-
-export type CommandName = 'scan' | 'health';
-
-/**
- * Run a CLI command with the given arguments
- */
-export async function runCommand(command: CommandName, args: string[]): Promise<void> {
-  try {
-    switch (command) {
-      case 'scan':
-        await scanCommand(args);
-        break;
-      case 'health':
-        await healthCommand(args);
-        break;
-      default:
-        console.error(pc.red(`Unknown command: ${command}`));
-        process.exit(1);
-    }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    console.error(pc.red(`\nError: ${message}\n`));
-    process.exit(1);
-  }
-}

package/src/viewer/cli/scan.ts

@@ -1,124 +0,0 @@
-/**
- * Scan Command
- * Scans a codebase for component usage
- */
-
-import pc from 'picocolors';
-import path from 'path';
-import { scanForUsages, type FullScanResult, type UsageScanResult } from '../intelligence/usageScanner.js';
-import { parseArgs, createSpinner, formatTable, formatDuration, printHeader, printKV } from './utils.js';
-
-type OutputFormat = 'table' | 'json';
-
-interface ScanCommandOptions {
-  format: OutputFormat;
-  component?: string;
-  verbose: boolean;
-}
-
-function parseOptions(args: string[]): { directory: string; options: ScanCommandOptions } {
-  const { positional, options } = parseArgs(args);
-
-  return {
-    directory: positional[0] || '.',
-    options: {
-      format: (options.format as OutputFormat) || 'table',
-      component: options.component as string | undefined,
-      verbose: !!options.verbose || !!options.v,
-    },
-  };
-}
-
-function formatTableOutput(result: FullScanResult, options: ScanCommandOptions): void {
-  const { results, summary } = result;
-
-  printHeader('Component Usage Scan');
-  printKV('Directory scanned', path.resolve(result.results[0]?.usages[0]?.file || '.').split(path.sep).slice(0, -1).join(path.sep) || '.');
-  printKV('Files scanned', summary.totalFiles.toString());
-  printKV('Files with usage', summary.filesWithUsage.toString());
-  printKV('Scan time', formatDuration(summary.scanTimeMs));
-  console.log('');
-
-  if (results.length === 0) {
-    console.log(pc.yellow('  No component usages found.\n'));
-    return;
-  }
-
-  // Summary table
-  const headers = ['Component', 'Files', 'Total Uses'];
-  const rows = results.map((r) => [
-    r.component,
-    String(r.usages.length),
-    String(r.totalUsages),
-  ]);
-
-  console.log(formatTable(headers, rows));
-  console.log('');
-
-  // Verbose: show file details
-  if (options.verbose) {
-    console.log(pc.bold('\nDetailed Usage:\n'));
-
-    for (const r of results) {
-      console.log(pc.cyan(`  ${r.component}`));
-      for (const usage of r.usages) {
-        const relativePath = path.relative(process.cwd(), usage.file);
-        const importIcon = usage.importType === 'named' ? '{}' : usage.importType === 'default' ? '=>' : '*';
-        console.log(pc.dim(`    ${importIcon} ${relativePath}:${usage.line} (${usage.usageCount} uses)`));
-      }
-      console.log('');
-    }
-  }
-
-  // Summary footer
-  console.log(pc.dim('─'.repeat(50)));
-  console.log(`  ${pc.bold(String(summary.totalComponents))} components used ${pc.bold(String(summary.totalUsages))} times across ${pc.bold(String(summary.filesWithUsage))} files`);
-  console.log('');
-}
-
-function formatJsonOutput(result: FullScanResult): void {
-  const output = {
-    summary: result.summary,
-    components: result.results.map((r) => ({
-      name: r.component,
-      totalUsages: r.totalUsages,
-      fileCount: r.usages.length,
-      usages: r.usages.map((u) => ({
-        file: path.relative(process.cwd(), u.file),
-        line: u.line,
-        importType: u.importType,
-        usageCount: u.usageCount,
-      })),
-    })),
-  };
-
-  console.log(JSON.stringify(output, null, 2));
-}
-
-/**
- * Run the scan command
- */
-export async function scanCommand(args: string[]): Promise<void> {
-  const { directory, options } = parseOptions(args);
-
-  const spinner = createSpinner(`Scanning ${directory} for component usage...`);
-  spinner.start();
-
-  try {
-    const result = await scanForUsages({
-      directory,
-      components: options.component ? [options.component] : undefined,
-    });
-
-    spinner.stop(true, `Scanned ${result.summary.totalFiles} files in ${formatDuration(result.summary.scanTimeMs)}`);
-
-    if (options.format === 'json') {
-      formatJsonOutput(result);
-    } else {
-      formatTableOutput(result, options);
-    }
-  } catch (error) {
-    spinner.stop(false, 'Scan failed');
-    throw error;
-  }
-}

package/src/viewer/cli/utils.ts

@@ -1,174 +0,0 @@
-/**
- * Shared CLI Utilities
- * Common helpers for CLI commands
- */
-
-import pc from 'picocolors';
-
-/**
- * Parse command line arguments into options object
- */
-export function parseArgs(args: string[]): {
-  positional: string[];
-  options: Record<string, string | boolean>;
-} {
-  const positional: string[] = [];
-  const options: Record<string, string | boolean> = {};
-
-  for (const arg of args) {
-    if (arg.startsWith('--')) {
-      const [key, value] = arg.slice(2).split('=');
-      options[key] = value ?? true;
-    } else if (arg.startsWith('-')) {
-      const key = arg.slice(1);
-      options[key] = true;
-    } else {
-      positional.push(arg);
-    }
-  }
-
-  return { positional, options };
-}
-
-/**
- * Spinner for async operations
- */
-export function createSpinner(message: string): {
-  start: () => void;
-  stop: (success?: boolean, finalMessage?: string) => void;
-  update: (message: string) => void;
-} {
-  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
-  let frameIndex = 0;
-  let interval: NodeJS.Timeout | null = null;
-  let currentMessage = message;
-
-  return {
-    start() {
-      process.stdout.write('\n');
-      interval = setInterval(() => {
-        process.stdout.write(`\r${pc.cyan(frames[frameIndex])} ${currentMessage}`);
-        frameIndex = (frameIndex + 1) % frames.length;
-      }, 80);
-    },
-    stop(success = true, finalMessage?: string) {
-      if (interval) {
-        clearInterval(interval);
-        interval = null;
-      }
-      const icon = success ? pc.green('✓') : pc.red('✗');
-      process.stdout.write(`\r${icon} ${finalMessage || currentMessage}\n`);
-    },
-    update(message: string) {
-      currentMessage = message;
-    },
-  };
-}
-
-/**
- * Format a table for console output
- */
-export function formatTable(
-  headers: string[],
-  rows: string[][],
-  options: { padding?: number; maxWidth?: number } = {}
-): string {
-  const { padding = 2, maxWidth = 50 } = options;
-
-  // Calculate column widths
-  const widths = headers.map((h, i) => {
-    const columnValues = [h, ...rows.map((r) => r[i] || '')];
-    return Math.min(maxWidth, Math.max(...columnValues.map((v) => v.length)));
-  });
-
-  // Format header
-  const headerLine = headers
-    .map((h, i) => h.padEnd(widths[i] + padding))
-    .join('');
-  const separator = widths.map((w) => '─'.repeat(w + padding)).join('');
-
-  // Format rows
-  const formattedRows = rows.map((row) =>
-    row.map((cell, i) => (cell || '').padEnd(widths[i] + padding)).join('')
-  );
-
-  return [
-    pc.bold(headerLine),
-    pc.dim(separator),
-    ...formattedRows,
-  ].join('\n');
-}
-
-/**
- * Format bytes as human-readable size
- */
-export function formatBytes(bytes: number): string {
-  if (bytes === 0) return '0 B';
-  const k = 1024;
-  const sizes = ['B', 'KB', 'MB', 'GB'];
-  const i = Math.floor(Math.log(bytes) / Math.log(k));
-  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`;
-}
-
-/**
- * Format duration in milliseconds
- */
-export function formatDuration(ms: number): string {
-  if (ms < 1000) return `${ms}ms`;
-  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
-  return `${(ms / 60000).toFixed(1)}m`;
-}
-
-/**
- * Format a score with color based on thresholds
- */
-export function formatScore(score: number, thresholds = { good: 80, warn: 50 }): string {
-  const formatted = `${score}%`;
-  if (score >= thresholds.good) return pc.green(formatted);
-  if (score >= thresholds.warn) return pc.yellow(formatted);
-  return pc.red(formatted);
-}
-
-/**
- * Print a section header
- */
-export function printHeader(title: string): void {
-  console.log(`\n${pc.bold(pc.cyan(title))}`);
-  console.log(pc.dim('─'.repeat(title.length + 4)));
-}
-
-/**
- * Print a key-value pair
- */
-export function printKV(key: string, value: string | number, color?: (s: string) => string): void {
-  const valueStr = String(value);
-  console.log(`  ${pc.dim(key + ':')} ${color ? color(valueStr) : valueStr}`);
-}
-
-/**
- * Print a warning message
- */
-export function printWarning(message: string): void {
-  console.log(pc.yellow(`  ⚠ ${message}`));
-}
-
-/**
- * Print an error message
- */
-export function printError(message: string): void {
-  console.log(pc.red(`  ✗ ${message}`));
-}
-
-/**
- * Print a success message
- */
-export function printSuccess(message: string): void {
-  console.log(pc.green(`  ✓ ${message}`));
-}
-
-/**
- * Format a list for bullet points
- */
-export function formatList(items: string[], bullet = '•'): string {
-  return items.map((item) => `  ${pc.dim(bullet)} ${item}`).join('\n');
-}