@fragments-sdk/cli 0.10.1 → 0.12.1

package/src/viewer/intelligence/styleDrift.ts

@@ -1,340 +0,0 @@
-/**
- * Style Drift Detection
- * Analyzes style drift between Figma designs and rendered components
- */
-
-import type { FragmentDefinition, 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

@@ -1,309 +0,0 @@
-/**
- * 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('.fragment.')) {
-        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))];
-}