@fragments-sdk/cli 0.2.2

package/src/viewer/intelligence/styleDrift.ts

@@ -0,0 +1,340 @@
+/**
+ * Style Drift Detection
+ * Analyzes style drift between Figma designs and rendered components
+ */
+
+import type { SegmentDefinition, DesignToken } from '../../core/index.js';
+
+export type DriftSeverity = 'high' | 'medium' | 'low';
+
+export interface StyleDrift {
+  property: string;
+  expected: string;
+  actual: string;
+  expectedToken?: string;
+  severity: DriftSeverity;
+  suggestion?: string;
+}
+
+export interface DriftReport {
+  component: string;
+  variant: string;
+  figmaUrl?: string;
+  drifts: StyleDrift[];
+  complianceScore: number;
+  totalProperties: number;
+  matchingProperties: number;
+}
+
+export interface DriftScanOptions {
+  /** Filter to specific components */
+  components?: string[];
+  /** Filter to specific CSS properties */
+  properties?: string[];
+  /** Minimum compliance score to report (0-100) */
+  threshold?: number;
+}
+
+export interface DriftSummary {
+  totalComponents: number;
+  componentsWithDrift: number;
+  totalDrifts: number;
+  averageCompliance: number;
+  byProperty: Record<string, number>;
+  bySeverity: Record<DriftSeverity, number>;
+}
+
+export interface FullDriftResult {
+  reports: DriftReport[];
+  summary: DriftSummary;
+}
+
+/**
+ * Severity rules for different CSS properties
+ * High: Brand-critical properties
+ * Medium: Layout properties
+ * Low: Decorative properties
+ */
+const PROPERTY_SEVERITY: Record<string, DriftSeverity> = {
+  // High severity - brand critical
+  color: 'high',
+  backgroundColor: 'high',
+  borderColor: 'high',
+  fontFamily: 'high',
+  fontSize: 'high',
+  fontWeight: 'high',
+
+  // Medium severity - layout
+  padding: 'medium',
+  margin: 'medium',
+  gap: 'medium',
+  borderRadius: 'medium',
+  borderWidth: 'medium',
+  lineHeight: 'medium',
+  letterSpacing: 'medium',
+
+  // Low severity - decorative
+  boxShadow: 'low',
+  opacity: 'low',
+  transition: 'low',
+  textAlign: 'low',
+};
+
+/**
+ * Get severity for a CSS property
+ */
+export function getPropertySeverity(property: string): DriftSeverity {
+  return PROPERTY_SEVERITY[property] || 'low';
+}
+
+/**
+ * Normalize a CSS value for comparison
+ */
+function normalizeValue(value: string): string {
+  if (!value) return '';
+
+  const trimmed = value.toLowerCase().trim();
+
+  // Normalize hex colors
+  if (trimmed.match(/^#[0-9a-f]{3}$/i)) {
+    const [r, g, b] = trimmed.slice(1).split('');
+    return `#${r}${r}${g}${g}${b}${b}`;
+  }
+
+  // Normalize rgb to hex
+  const rgbMatch = value.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/);
+  if (rgbMatch) {
+    const r = parseInt(rgbMatch[1], 10).toString(16).padStart(2, '0');
+    const g = parseInt(rgbMatch[2], 10).toString(16).padStart(2, '0');
+    const b = parseInt(rgbMatch[3], 10).toString(16).padStart(2, '0');
+    return `#${r}${g}${b}`;
+  }
+
+  return trimmed;
+}
+
+/**
+ * Compare two style values with tolerance for numeric values
+ */
+function valuesMatch(property: string, expected: string, actual: string): boolean {
+  if (expected === actual) return true;
+  if (!expected || !actual) return false;
+
+  const normalizedExpected = normalizeValue(expected);
+  const normalizedActual = normalizeValue(actual);
+
+  if (normalizedExpected === normalizedActual) return true;
+
+  // Numeric comparison with tolerance
+  const expectedNum = parseFloat(expected);
+  const actualNum = parseFloat(actual);
+
+  if (!isNaN(expectedNum) && !isNaN(actualNum)) {
+    return Math.abs(expectedNum - actualNum) <= 1;
+  }
+
+  return false;
+}
+
+/**
+ * Find a token that matches a value
+ */
+function findMatchingToken(
+  value: string,
+  tokens: DesignToken[],
+  property: string
+): DesignToken | null {
+  const normalized = normalizeValue(value);
+
+  // Property-to-category mapping
+  const categoryMap: Record<string, string[]> = {
+    color: ['color'],
+    backgroundColor: ['color'],
+    borderColor: ['color'],
+    fontSize: ['typography'],
+    fontWeight: ['typography'],
+    fontFamily: ['typography'],
+    padding: ['spacing'],
+    margin: ['spacing'],
+    gap: ['spacing'],
+    borderRadius: ['radius'],
+    borderWidth: ['border'],
+  };
+
+  const expectedCategories = categoryMap[property];
+
+  for (const token of tokens) {
+    const tokenNormalized = normalizeValue(token.resolvedValue);
+    if (tokenNormalized === normalized) {
+      // If we have expected categories, check for match
+      if (expectedCategories && expectedCategories.includes(token.category)) {
+        return token;
+      }
+      // If no expected categories, accept any match
+      if (!expectedCategories) {
+        return token;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Generate a fix suggestion for a drift
+ */
+function generateSuggestion(property: string, token: DesignToken | null): string | undefined {
+  if (!token) return undefined;
+
+  const cssProperty = property.replace(/([A-Z])/g, '-$1').toLowerCase();
+  return `${cssProperty}: var(${token.name});`;
+}
+
+/**
+ * Analyze drift for a single component/variant
+ */
+export function analyzeVariantDrift(
+  figmaStyles: Record<string, string>,
+  renderedStyles: Record<string, string>,
+  tokens: DesignToken[] = [],
+  options: DriftScanOptions = {}
+): { drifts: StyleDrift[]; complianceScore: number; totalProperties: number; matchingProperties: number } {
+  const allProps = new Set([...Object.keys(figmaStyles), ...Object.keys(renderedStyles)]);
+  const propertyFilter = options.properties ? new Set(options.properties) : null;
+
+  const drifts: StyleDrift[] = [];
+  let matchingCount = 0;
+  let totalCount = 0;
+
+  for (const property of allProps) {
+    // Apply property filter if specified
+    if (propertyFilter && !propertyFilter.has(property)) continue;
+
+    const expected = figmaStyles[property] || '';
+    const actual = renderedStyles[property] || '';
+
+    // Skip if both are empty
+    if (!expected && !actual) continue;
+
+    totalCount++;
+
+    if (valuesMatch(property, expected, actual)) {
+      matchingCount++;
+      continue;
+    }
+
+    // Find token for expected value
+    const expectedToken = findMatchingToken(expected, tokens, property);
+    const severity = getPropertySeverity(property);
+
+    drifts.push({
+      property,
+      expected: expected || '(not set)',
+      actual: actual || '(not set)',
+      expectedToken: expectedToken?.name,
+      severity,
+      suggestion: generateSuggestion(property, expectedToken),
+    });
+  }
+
+  const complianceScore = totalCount > 0 ? Math.round((matchingCount / totalCount) * 100) : 100;
+
+  return {
+    drifts,
+    complianceScore,
+    totalProperties: totalCount,
+    matchingProperties: matchingCount,
+  };
+}
+
+/**
+ * Create a drift report for a component/variant
+ */
+export function createDriftReport(
+  component: string,
+  variant: string,
+  figmaStyles: Record<string, string>,
+  renderedStyles: Record<string, string>,
+  tokens: DesignToken[] = [],
+  figmaUrl?: string,
+  options: DriftScanOptions = {}
+): DriftReport {
+  const analysis = analyzeVariantDrift(figmaStyles, renderedStyles, tokens, options);
+
+  return {
+    component,
+    variant,
+    figmaUrl,
+    drifts: analysis.drifts,
+    complianceScore: analysis.complianceScore,
+    totalProperties: analysis.totalProperties,
+    matchingProperties: analysis.matchingProperties,
+  };
+}
+
+/**
+ * Aggregate drift reports into a summary
+ */
+export function aggregateDriftReports(reports: DriftReport[]): DriftSummary {
+  const byProperty: Record<string, number> = {};
+  const bySeverity: Record<DriftSeverity, number> = { high: 0, medium: 0, low: 0 };
+
+  let totalDrifts = 0;
+  let componentsWithDrift = 0;
+  let totalCompliance = 0;
+
+  for (const report of reports) {
+    if (report.drifts.length > 0) {
+      componentsWithDrift++;
+    }
+
+    totalCompliance += report.complianceScore;
+
+    for (const drift of report.drifts) {
+      totalDrifts++;
+      byProperty[drift.property] = (byProperty[drift.property] || 0) + 1;
+      bySeverity[drift.severity]++;
+    }
+  }
+
+  return {
+    totalComponents: reports.length,
+    componentsWithDrift,
+    totalDrifts,
+    averageCompliance: reports.length > 0 ? Math.round(totalCompliance / reports.length) : 100,
+    byProperty,
+    bySeverity,
+  };
+}
+
+/**
+ * Get the worst offenders (components with most/worst drift)
+ */
+export function getWorstOffenders(reports: DriftReport[], limit = 5): DriftReport[] {
+  // Sort by: 1) High severity count, 2) Total drifts, 3) Compliance (ascending)
+  return [...reports]
+    .filter((r) => r.drifts.length > 0)
+    .sort((a, b) => {
+      const aHigh = a.drifts.filter((d) => d.severity === 'high').length;
+      const bHigh = b.drifts.filter((d) => d.severity === 'high').length;
+
+      if (aHigh !== bHigh) return bHigh - aHigh;
+      if (a.drifts.length !== b.drifts.length) return b.drifts.length - a.drifts.length;
+      return a.complianceScore - b.complianceScore;
+    })
+    .slice(0, limit);
+}
+
+/**
+ * Generate fix suggestions for all drifts in a report
+ */
+export function generateAllFixes(report: DriftReport): string {
+  const fixes = report.drifts
+    .filter((d) => d.suggestion)
+    .map((d) => `/* ${d.property}: ${d.expected} -> ${d.actual} */\n${d.suggestion}`)
+    .join('\n\n');
+
+  if (!fixes) return '';
+
+  return `/* Fixes for ${report.component} - ${report.variant} */\n\n${fixes}`;
+}

package/src/viewer/intelligence/usageScanner.ts

@@ -0,0 +1,309 @@
+/**
+ * Component Usage Scanner
+ * Scans a codebase for design system component imports and usage
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+export interface UsageLocation {
+  file: string;
+  line: number;
+  importType: 'named' | 'default' | 'namespace';
+  usageCount: number;
+}
+
+export interface UsageScanResult {
+  component: string;
+  usages: UsageLocation[];
+  totalUsages: number;
+}
+
+export interface ScanOptions {
+  /** Directory to scan */
+  directory: string;
+  /** Glob patterns to include */
+  include?: string[];
+  /** Glob patterns to exclude */
+  exclude?: string[];
+  /** Filter to specific components */
+  components?: string[];
+  /** Package names to look for */
+  packagePatterns?: string[];
+}
+
+export interface ScanSummary {
+  totalFiles: number;
+  filesWithUsage: number;
+  totalComponents: number;
+  totalUsages: number;
+  scanTimeMs: number;
+}
+
+export interface FullScanResult {
+  results: UsageScanResult[];
+  summary: ScanSummary;
+}
+
+const DEFAULT_EXCLUDE = [
+  'node_modules',
+  'dist',
+  '.git',
+  'build',
+  'coverage',
+  '.next',
+  '.cache',
+  '__tests__',
+];
+
+const DEFAULT_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js'];
+
+/**
+ * Recursively find all files matching criteria
+ */
+function findFiles(
+  dir: string,
+  exclude: string[],
+  extensions: string[],
+  files: string[] = []
+): string[] {
+  if (!fs.existsSync(dir)) {
+    return files;
+  }
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+
+    // Check exclusions
+    const shouldExclude = exclude.some((pattern) => {
+      if (pattern.includes('*')) {
+        const regex = new RegExp(pattern.replace(/\./g, '\\.').replace(/\*/g, '.*'));
+        return regex.test(entry.name);
+      }
+      return entry.name === pattern;
+    });
+
+    if (shouldExclude) {
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      findFiles(fullPath, exclude, extensions, files);
+    } else if (entry.isFile() && extensions.some((ext) => entry.name.endsWith(ext))) {
+      // Skip test and story files
+      if (entry.name.includes('.test.') || entry.name.includes('.spec.') ||
+          entry.name.includes('.stories.') || entry.name.includes('.segment.')) {
+        continue;
+      }
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Parse a file for component imports from design system packages
+ */
+function parseFileForUsage(
+  filePath: string,
+  packagePatterns: string[]
+): Map<string, UsageLocation> {
+  const results = new Map<string, UsageLocation>();
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n');
+
+    // Build regex patterns for package matching
+    const packageRegexStr = packagePatterns
+      .map((p) => p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+      .join('|');
+
+    // Named import pattern: import { Button, Card } from '@fragments/react'
+    const namedImportRegex = new RegExp(
+      `import\\s*\\{([^}]+)\\}\\s*from\\s*['"](?:${packageRegexStr})[^'"]*['"]`,
+      'g'
+    );
+
+    // Default import pattern: import Button from '@fragments/react/Button'
+    const defaultImportRegex = new RegExp(
+      `import\\s+(\\w+)\\s+from\\s*['"](?:${packageRegexStr})[^'"]*['"]`,
+      'g'
+    );
+
+    // Namespace import pattern: import * as UI from '@fragments/react'
+    const namespaceImportRegex = new RegExp(
+      `import\\s*\\*\\s*as\\s+(\\w+)\\s+from\\s*['"](?:${packageRegexStr})[^'"]*['"]`,
+      'g'
+    );
+
+    lines.forEach((line, index) => {
+      // Named imports
+      let match: RegExpExecArray | null;
+      namedImportRegex.lastIndex = 0;
+
+      while ((match = namedImportRegex.exec(line)) !== null) {
+        const componentNames = match[1].split(',').map((c) => {
+          // Handle "Component as Alias" syntax
+          const parts = c.trim().split(/\s+as\s+/);
+          return parts[0].trim();
+        }).filter((c) => c && /^[A-Z]/.test(c));
+
+        for (const component of componentNames) {
+          if (!results.has(component)) {
+            results.set(component, {
+              file: filePath,
+              line: index + 1,
+              importType: 'named',
+              usageCount: 0,
+            });
+          }
+        }
+      }
+
+      // Default imports (only if PascalCase - likely a component)
+      defaultImportRegex.lastIndex = 0;
+      while ((match = defaultImportRegex.exec(line)) !== null) {
+        const component = match[1].trim();
+        if (/^[A-Z]/.test(component)) {
+          if (!results.has(component)) {
+            results.set(component, {
+              file: filePath,
+              line: index + 1,
+              importType: 'default',
+              usageCount: 0,
+            });
+          }
+        }
+      }
+
+      // Namespace imports
+      namespaceImportRegex.lastIndex = 0;
+      while ((match = namespaceImportRegex.exec(line)) !== null) {
+        const namespace = match[1].trim();
+        if (!results.has(namespace)) {
+          results.set(namespace, {
+            file: filePath,
+            line: index + 1,
+            importType: 'namespace',
+            usageCount: 0,
+          });
+        }
+      }
+    });
+
+    // Count component usages in JSX
+    for (const [component, location] of results) {
+      if (location.importType === 'namespace') {
+        const nsUsageRegex = new RegExp(`<${component}\\.\\w+`, 'g');
+        const matches = content.match(nsUsageRegex);
+        location.usageCount = matches ? matches.length : 0;
+      } else {
+        const jsxOpenRegex = new RegExp(`<${component}(?:\\s|>|\\/)`, 'g');
+        const matches = content.match(jsxOpenRegex);
+        location.usageCount = matches ? matches.length : 0;
+      }
+    }
+
+    return results;
+  } catch {
+    return results;
+  }
+}
+
+/**
+ * Scan a directory for component usage
+ */
+export async function scanForUsages(options: ScanOptions): Promise<FullScanResult> {
+  const startTime = Date.now();
+
+  const {
+    directory,
+    exclude = DEFAULT_EXCLUDE,
+    components,
+    packagePatterns = ['@fragments'],
+  } = options;
+
+  const resolvedDir = path.resolve(directory);
+  const files = findFiles(resolvedDir, exclude, DEFAULT_EXTENSIONS);
+
+  const componentMap = new Map<string, UsageLocation[]>();
+  let filesWithUsage = 0;
+
+  for (const file of files) {
+    const fileResults = parseFileForUsage(file, packagePatterns);
+
+    if (fileResults.size > 0) {
+      filesWithUsage++;
+    }
+
+    for (const [component, location] of fileResults) {
+      if (components && !components.includes(component)) {
+        continue;
+      }
+
+      if (!componentMap.has(component)) {
+        componentMap.set(component, []);
+      }
+      componentMap.get(component)!.push(location);
+    }
+  }
+
+  const results: UsageScanResult[] = [];
+
+  for (const [component, usages] of componentMap) {
+    const totalUsages = usages.reduce((sum, u) => sum + u.usageCount, 0);
+    results.push({
+      component,
+      usages,
+      totalUsages,
+    });
+  }
+
+  results.sort((a, b) => b.totalUsages - a.totalUsages);
+
+  const scanTimeMs = Date.now() - startTime;
+
+  return {
+    results,
+    summary: {
+      totalFiles: files.length,
+      filesWithUsage,
+      totalComponents: results.length,
+      totalUsages: results.reduce((sum, r) => sum + r.totalUsages, 0),
+      scanTimeMs,
+    },
+  };
+}
+
+/**
+ * Get a simple usage count map for a quick summary
+ */
+export function getUsageCounts(results: UsageScanResult[]): Map<string, number> {
+  return new Map(results.map((r) => [r.component, r.totalUsages]));
+}
+
+/**
+ * Find components that are imported but never used in JSX
+ */
+export function findUnusedImports(results: UsageScanResult[]): string[] {
+  return results
+    .filter((r) => r.totalUsages === 0)
+    .map((r) => r.component);
+}
+
+/**
+ * Get files using a specific component
+ */
+export function getFilesUsingComponent(
+  results: UsageScanResult[],
+  componentName: string
+): string[] {
+  const result = results.find((r) => r.component === componentName);
+  if (!result) return [];
+
+  return [...new Set(result.usages.map((u) => u.file))];
+}