@fragments-sdk/cli 0.2.2

package/src/service/token-registry.ts

@@ -0,0 +1,721 @@
+/**
+ * Token Registry
+ *
+ * Manages design tokens in memory with fast lookup capabilities:
+ * - By name: O(1) lookup
+ * - By value (reverse): O(1) lookup
+ * - By theme: O(1) lookup
+ * - By category: O(1) lookup
+ */
+
+import type {
+  DesignToken,
+  TokenRegistry,
+  TokenRegistryMeta,
+  TokenCategory,
+  TokenConfig,
+  TokenMatchRequest,
+  TokenMatchResult,
+  EnhancedStyleDiffItem,
+  TokenUsageSummary,
+} from "../core/index.js";
+import { parseTokenFiles, normalizeColor, hexToRgb, parseRgb } from "./token-parser.js";
+
+/**
+ * Token Registry Manager
+ *
+ * Singleton-style manager for design tokens with initialization,
+ * lookup, and matching capabilities.
+ */
+export class TokenRegistryManager {
+  private registry: TokenRegistry | null = null;
+  private initPromise: Promise<void> | null = null;
+
+  /**
+   * Initialize the registry by parsing token files
+   */
+  async initialize(
+    config: TokenConfig,
+    projectRoot: string
+  ): Promise<TokenRegistry> {
+    // If already initializing, wait for that
+    if (this.initPromise) {
+      await this.initPromise;
+      return this.registry!;
+    }
+
+    // If already initialized, return existing
+    if (this.registry) {
+      return this.registry;
+    }
+
+    this.initPromise = this.doInitialize(config, projectRoot);
+    await this.initPromise;
+    this.initPromise = null;
+
+    return this.registry!;
+  }
+
+  private async doInitialize(
+    config: TokenConfig,
+    projectRoot: string
+  ): Promise<void> {
+    const startTime = performance.now();
+
+    // Parse all token files
+    const result = await parseTokenFiles(config, projectRoot);
+
+    // Build the registry
+    const byName = new Map<string, DesignToken>();
+    const byValue = new Map<string, string[]>();
+    const byTheme = new Map<string, DesignToken[]>();
+    const byCategory = new Map<TokenCategory, DesignToken[]>();
+
+    let circularRefs = 0;
+    let unresolvedRefs = 0;
+
+    for (const token of result.tokens) {
+      // Index by name
+      byName.set(token.name, token);
+
+      // Index by resolved value (reverse lookup)
+      const normalizedValue = this.normalizeForLookup(token.resolvedValue);
+      const existingTokens = byValue.get(normalizedValue) || [];
+      existingTokens.push(token.name);
+      byValue.set(normalizedValue, existingTokens);
+
+      // Index by theme
+      const themeTokens = byTheme.get(token.theme) || [];
+      themeTokens.push(token);
+      byTheme.set(token.theme, themeTokens);
+
+      // Index by category
+      const categoryTokens = byCategory.get(token.category) || [];
+      categoryTokens.push(token);
+      byCategory.set(token.category, categoryTokens);
+    }
+
+    // Count issues from warnings
+    for (const warning of result.warnings) {
+      if (warning.includes("Circular")) circularRefs++;
+      if (warning.includes("Unresolved")) unresolvedRefs++;
+    }
+
+    const meta: TokenRegistryMeta = {
+      discoveredAt: new Date(),
+      sourceFiles: config.include,
+      totalTokens: result.tokens.length,
+      parseTimeMs: performance.now() - startTime,
+      circularRefs,
+      unresolvedRefs,
+    };
+
+    this.registry = {
+      byName,
+      byValue,
+      byTheme,
+      byCategory,
+      meta,
+    };
+  }
+
+  /**
+   * Get the current registry (throws if not initialized)
+   */
+  getRegistry(): TokenRegistry {
+    if (!this.registry) {
+      throw new Error("Token registry not initialized. Call initialize() first.");
+    }
+    return this.registry;
+  }
+
+  /**
+   * Check if registry is initialized
+   */
+  isInitialized(): boolean {
+    return this.registry !== null;
+  }
+
+  /**
+   * Clear the registry (for re-initialization)
+   */
+  clear(): void {
+    this.registry = null;
+    this.initPromise = null;
+  }
+
+  /**
+   * Get a token by name
+   */
+  getToken(name: string): DesignToken | undefined {
+    return this.registry?.byName.get(name);
+  }
+
+  /**
+   * Find tokens by resolved value (reverse lookup)
+   *
+   * This is the key feature: given a computed value like "#0051c2",
+   * find which design token(s) resolve to that value.
+   */
+  findByValue(value: string, theme?: string): string[] {
+    if (!this.registry) return [];
+
+    const normalizedValue = this.normalizeForLookup(value);
+    const tokenNames = this.registry.byValue.get(normalizedValue) || [];
+
+    // Filter by theme if specified
+    if (theme && tokenNames.length > 0) {
+      return tokenNames.filter((name) => {
+        const token = this.registry!.byName.get(name);
+        return token?.theme === theme || token?.theme === "default";
+      });
+    }
+
+    return tokenNames;
+  }
+
+  /**
+   * Match a value to tokens with similarity scoring
+   */
+  matchValue(request: TokenMatchRequest): TokenMatchResult {
+    const { value, propertyType, theme } = request;
+    const exactMatches: DesignToken[] = [];
+    const closeMatches: Array<{ token: DesignToken; similarity: number }> = [];
+
+    if (!this.registry) {
+      return { exactMatches, closeMatches, found: false };
+    }
+
+    const normalizedValue = this.normalizeForLookup(value);
+
+    // Find exact matches
+    const exactNames = this.registry.byValue.get(normalizedValue) || [];
+    for (const name of exactNames) {
+      const token = this.registry.byName.get(name);
+      if (token) {
+        // Filter by theme if specified
+        if (!theme || token.theme === theme || token.theme === "default") {
+          exactMatches.push(token);
+        }
+      }
+    }
+
+    // For colors, find close matches
+    if (propertyType === "color" || this.looksLikeColor(value)) {
+      const targetRgb = this.parseColorToRgb(value);
+      if (targetRgb) {
+        // Get all color tokens
+        const colorTokens = this.registry.byCategory.get("color") || [];
+
+        for (const token of colorTokens) {
+          // Skip if already an exact match
+          if (exactMatches.includes(token)) continue;
+
+          // Filter by theme
+          if (theme && token.theme !== theme && token.theme !== "default") {
+            continue;
+          }
+
+          const tokenRgb = this.parseColorToRgb(token.resolvedValue);
+          if (tokenRgb) {
+            const similarity = this.colorSimilarity(targetRgb, tokenRgb);
+            if (similarity > 0.9) {
+              // 90% similar
+              closeMatches.push({ token, similarity });
+            }
+          }
+        }
+
+        // Sort by similarity descending
+        closeMatches.sort((a, b) => b.similarity - a.similarity);
+      }
+    }
+
+    return {
+      exactMatches,
+      closeMatches: closeMatches.slice(0, 5), // Top 5 close matches
+      found: exactMatches.length > 0 || closeMatches.length > 0,
+    };
+  }
+
+  /**
+   * Get all tokens for a theme
+   */
+  getTokensByTheme(theme: string): DesignToken[] {
+    return this.registry?.byTheme.get(theme) || [];
+  }
+
+  /**
+   * Get all tokens in a category
+   */
+  getTokensByCategory(category: TokenCategory): DesignToken[] {
+    return this.registry?.byCategory.get(category) || [];
+  }
+
+  /**
+   * Get all tokens
+   */
+  getAllTokens(): DesignToken[] {
+    if (!this.registry) return [];
+    return Array.from(this.registry.byName.values());
+  }
+
+  /**
+   * Get registry metadata
+   */
+  getMeta(): TokenRegistryMeta | undefined {
+    return this.registry?.meta;
+  }
+
+  /**
+   * Enhance a style diff with token information
+   */
+  enhanceStyleDiff(
+    figmaValue: string,
+    renderedValue: string,
+    property: string,
+    theme = "default"
+  ): Partial<EnhancedStyleDiffItem> {
+    const figmaTokens = this.findByValue(figmaValue, theme);
+    const renderedTokens = this.findByValue(renderedValue, theme);
+
+    const figmaToken = figmaTokens.length > 0 ? figmaTokens[0] : undefined;
+    const renderedToken = renderedTokens.length > 0 ? renderedTokens[0] : undefined;
+
+    // Determine if this is a hardcoded value
+    // Hardcoded = Figma matches a token, but rendered doesn't use a token
+    const isHardcoded = !!figmaToken && !renderedToken;
+
+    let suggestedFix: EnhancedStyleDiffItem["suggestedFix"] | undefined;
+
+    if (isHardcoded && figmaToken) {
+      const token = this.getToken(figmaToken);
+      if (token) {
+        const cssProperty = this.toCssProperty(property);
+        suggestedFix = {
+          tokenName: figmaToken,
+          tokenValue: token.resolvedValue,
+          codeFix: `${cssProperty}: var(${figmaToken});`,
+          confidence: 0.9,
+          reason: `Figma uses token ${figmaToken} (${token.resolvedValue}). Replace hardcoded value with token for consistency.`,
+        };
+      }
+    }
+
+    return {
+      figmaToken,
+      renderedToken,
+      isHardcoded,
+      suggestedFix,
+    };
+  }
+
+  /**
+   * Calculate token usage summary for a set of style comparisons
+   */
+  calculateUsageSummary(
+    styleDiffs: Array<{
+      property: string;
+      figma: string;
+      rendered: string;
+      match: boolean;
+    }>,
+    theme = "default"
+  ): TokenUsageSummary {
+    const hardcodedProperties: EnhancedStyleDiffItem[] = [];
+    let usingTokens = 0;
+    let hardcoded = 0;
+    let implicitMatches = 0;
+
+    for (const diff of styleDiffs) {
+      const enhanced = this.enhanceStyleDiff(
+        diff.figma,
+        diff.rendered,
+        diff.property,
+        theme
+      );
+
+      if (enhanced.renderedToken) {
+        usingTokens++;
+      } else if (enhanced.isHardcoded) {
+        hardcoded++;
+        hardcodedProperties.push({
+          ...diff,
+          ...enhanced,
+          isHardcoded: true,
+        } as EnhancedStyleDiffItem);
+      } else if (diff.match && enhanced.figmaToken) {
+        // Values match and Figma uses a token, but rendered doesn't explicitly use token
+        implicitMatches++;
+      }
+    }
+
+    const totalProperties = styleDiffs.length;
+    const compliancePercent =
+      totalProperties > 0
+        ? Math.round(((usingTokens + implicitMatches) / totalProperties) * 100)
+        : 100;
+
+    return {
+      totalProperties,
+      usingTokens,
+      hardcoded,
+      implicitMatches,
+      compliancePercent,
+      hardcodedProperties,
+    };
+  }
+
+  /**
+   * Find closest matching tokens for a value that doesn't match exactly
+   *
+   * @param value - The value to find close matches for
+   * @param category - Optional category to filter by (color, spacing, sizing, etc.)
+   * @param options - Matching options
+   * @returns Array of close matches sorted by distance with confidence scores
+   */
+  findClosestToken(
+    value: string,
+    category?: TokenCategory,
+    options: {
+      /** Maximum numeric difference for spacing/sizing (default: 4px) */
+      numericThreshold?: number;
+      /** Maximum color difference using Delta E (default: 5) */
+      colorDeltaE?: number;
+      /** Maximum results to return (default: 5) */
+      limit?: number;
+      /** Theme to filter by */
+      theme?: string;
+    } = {}
+  ): Array<{ token: DesignToken; distance: number; confidence: number }> {
+    if (!this.registry) return [];
+
+    const {
+      numericThreshold = 4,
+      colorDeltaE = 5,
+      limit = 5,
+      theme,
+    } = options;
+
+    const results: Array<{ token: DesignToken; distance: number; confidence: number }> = [];
+
+    // Determine value type
+    const isColor = this.looksLikeColor(value);
+    const numericValue = this.parseNumericValue(value);
+    const isNumeric = numericValue !== null;
+
+    // Get tokens to search through
+    let candidates: DesignToken[];
+    if (category) {
+      candidates = this.registry.byCategory.get(category) || [];
+    } else if (isColor) {
+      candidates = this.registry.byCategory.get("color") || [];
+    } else if (isNumeric) {
+      // Search through spacing, sizing, and radius tokens
+      candidates = [
+        ...(this.registry.byCategory.get("spacing") || []),
+        ...(this.registry.byCategory.get("sizing") || []),
+        ...(this.registry.byCategory.get("radius") || []),
+      ];
+    } else {
+      // Search all tokens
+      candidates = Array.from(this.registry.byName.values());
+    }
+
+    // Filter by theme if specified
+    if (theme) {
+      candidates = candidates.filter(
+        (t) => t.theme === theme || t.theme === "default"
+      );
+    }
+
+    // Calculate distances
+    if (isColor) {
+      const targetRgb = this.parseColorToRgb(value);
+      if (targetRgb) {
+        for (const token of candidates) {
+          const tokenRgb = this.parseColorToRgb(token.resolvedValue);
+          if (!tokenRgb) continue;
+
+          // Calculate Delta E (CIE76 approximation using RGB)
+          const deltaE = this.calculateDeltaE(targetRgb, tokenRgb);
+
+          if (deltaE <= colorDeltaE) {
+            // Confidence inversely proportional to deltaE
+            const confidence = Math.max(0, 1 - deltaE / colorDeltaE);
+            results.push({ token, distance: deltaE, confidence });
+          }
+        }
+      }
+    } else if (isNumeric) {
+      for (const token of candidates) {
+        const tokenNumeric = this.parseNumericValue(token.resolvedValue);
+        if (tokenNumeric === null) continue;
+
+        const distance = Math.abs(numericValue - tokenNumeric);
+
+        if (distance <= numericThreshold) {
+          // Confidence inversely proportional to distance
+          const confidence = Math.max(0, 1 - distance / numericThreshold);
+          results.push({ token, distance, confidence });
+        }
+      }
+    }
+
+    // Sort by distance ascending (closest first)
+    results.sort((a, b) => a.distance - b.distance);
+
+    return results.slice(0, limit);
+  }
+
+  /**
+   * Serialize registry for JSON export
+   */
+  toJSON(): {
+    tokens: DesignToken[];
+    meta: TokenRegistryMeta;
+  } {
+    if (!this.registry) {
+      return { tokens: [], meta: this.createEmptyMeta() };
+    }
+
+    return {
+      tokens: Array.from(this.registry.byName.values()),
+      meta: this.registry.meta,
+    };
+  }
+
+  // ----- Private helpers -----
+
+  /**
+   * Normalize a value for consistent lookup
+   */
+  private normalizeForLookup(value: string): string {
+    // Lowercase
+    let normalized = value.toLowerCase().trim();
+
+    // Normalize color formats
+    if (this.looksLikeColor(normalized)) {
+      const rgb = this.parseColorToRgb(value);
+      if (rgb) {
+        // Convert to lowercase hex for consistent lookup
+        normalized = `#${[rgb.r, rgb.g, rgb.b]
+          .map((x) => x.toString(16).padStart(2, "0"))
+          .join("")}`;
+      }
+    }
+
+    // Normalize whitespace
+    normalized = normalized.replace(/\s+/g, " ");
+
+    return normalized;
+  }
+
+  /**
+   * Check if a value looks like a color
+   */
+  private looksLikeColor(value: string): boolean {
+    return (
+      value.startsWith("#") ||
+      value.startsWith("rgb") ||
+      value.startsWith("hsl") ||
+      /^(transparent|white|black|red|blue|green|yellow|orange|purple|pink|gray|grey)$/i.test(
+        value
+      )
+    );
+  }
+
+  /**
+   * Parse any color format to RGB
+   */
+  private parseColorToRgb(
+    color: string
+  ): { r: number; g: number; b: number } | null {
+    // Handle named colors
+    const namedColors: Record<string, { r: number; g: number; b: number }> = {
+      white: { r: 255, g: 255, b: 255 },
+      black: { r: 0, g: 0, b: 0 },
+      transparent: { r: 0, g: 0, b: 0 },
+      red: { r: 255, g: 0, b: 0 },
+      green: { r: 0, g: 128, b: 0 },
+      blue: { r: 0, g: 0, b: 255 },
+    };
+
+    const lower = color.toLowerCase().trim();
+    if (namedColors[lower]) {
+      return namedColors[lower];
+    }
+
+    // Handle hex
+    if (color.startsWith("#")) {
+      return hexToRgb(color);
+    }
+
+    // Handle rgb/rgba
+    if (color.startsWith("rgb")) {
+      const parsed = parseRgb(color);
+      if (parsed) {
+        return { r: parsed.r, g: parsed.g, b: parsed.b };
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Calculate color similarity (0-1)
+   */
+  private colorSimilarity(
+    c1: { r: number; g: number; b: number },
+    c2: { r: number; g: number; b: number }
+  ): number {
+    // Use simple Euclidean distance in RGB space
+    const maxDist = Math.sqrt(255 ** 2 * 3);
+    const dist = Math.sqrt(
+      (c1.r - c2.r) ** 2 + (c1.g - c2.g) ** 2 + (c1.b - c2.b) ** 2
+    );
+
+    return 1 - dist / maxDist;
+  }
+
+  /**
+   * Convert camelCase property to kebab-case CSS property
+   */
+  private toCssProperty(prop: string): string {
+    return prop.replace(/([A-Z])/g, "-$1").toLowerCase();
+  }
+
+  /**
+   * Create empty metadata
+   */
+  private createEmptyMeta(): TokenRegistryMeta {
+    return {
+      discoveredAt: new Date(),
+      sourceFiles: [],
+      totalTokens: 0,
+      parseTimeMs: 0,
+      circularRefs: 0,
+      unresolvedRefs: 0,
+    };
+  }
+
+  /**
+   * Parse a numeric value from a CSS value string
+   * Handles px, rem, em, % and bare numbers
+   */
+  private parseNumericValue(value: string): number | null {
+    const trimmed = value.trim().toLowerCase();
+
+    // Match numeric values with optional units
+    const match = trimmed.match(/^(-?\d*\.?\d+)(px|rem|em|%)?$/);
+    if (!match) return null;
+
+    const num = parseFloat(match[1]);
+    const unit = match[2];
+
+    // Convert to px for comparison
+    switch (unit) {
+      case "rem":
+        return num * 16; // Assume 16px base
+      case "em":
+        return num * 16; // Approximate
+      case "%":
+        return null; // Percentages are relative, skip
+      case "px":
+      default:
+        return num;
+    }
+  }
+
+  /**
+   * Calculate Delta E (CIE76) color difference
+   * Uses simplified RGB to Lab approximation
+   * Lower values = more similar (0 = identical, >5 = noticeably different)
+   */
+  private calculateDeltaE(
+    c1: { r: number; g: number; b: number },
+    c2: { r: number; g: number; b: number }
+  ): number {
+    // Convert RGB to Lab (simplified)
+    const lab1 = this.rgbToLab(c1);
+    const lab2 = this.rgbToLab(c2);
+
+    // CIE76 Delta E formula
+    return Math.sqrt(
+      Math.pow(lab2.l - lab1.l, 2) +
+      Math.pow(lab2.a - lab1.a, 2) +
+      Math.pow(lab2.b - lab1.b, 2)
+    );
+  }
+
+  /**
+   * Convert RGB to Lab color space (simplified approximation)
+   */
+  private rgbToLab(rgb: { r: number; g: number; b: number }): { l: number; a: number; b: number } {
+    // Normalize RGB values
+    let r = rgb.r / 255;
+    let g = rgb.g / 255;
+    let b = rgb.b / 255;
+
+    // Apply gamma correction
+    r = r > 0.04045 ? Math.pow((r + 0.055) / 1.055, 2.4) : r / 12.92;
+    g = g > 0.04045 ? Math.pow((g + 0.055) / 1.055, 2.4) : g / 12.92;
+    b = b > 0.04045 ? Math.pow((b + 0.055) / 1.055, 2.4) : b / 12.92;
+
+    // Convert to XYZ
+    let x = (r * 0.4124564 + g * 0.3575761 + b * 0.1804375) / 0.95047;
+    let y = (r * 0.2126729 + g * 0.7151522 + b * 0.0721750);
+    let z = (r * 0.0193339 + g * 0.1191920 + b * 0.9503041) / 1.08883;
+
+    // Convert to Lab
+    x = x > 0.008856 ? Math.pow(x, 1/3) : (7.787 * x) + 16/116;
+    y = y > 0.008856 ? Math.pow(y, 1/3) : (7.787 * y) + 16/116;
+    z = z > 0.008856 ? Math.pow(z, 1/3) : (7.787 * z) + 16/116;
+
+    return {
+      l: (116 * y) - 16,
+      a: 500 * (x - y),
+      b: 200 * (y - z),
+    };
+  }
+}
+
+/**
+ * Shared singleton instance
+ */
+let sharedRegistry: TokenRegistryManager | null = null;
+
+/**
+ * Get or create the shared token registry
+ */
+export function getSharedTokenRegistry(): TokenRegistryManager {
+  if (!sharedRegistry) {
+    sharedRegistry = new TokenRegistryManager();
+  }
+  return sharedRegistry;
+}
+
+/**
+ * Initialize the shared registry
+ */
+export async function initializeSharedRegistry(
+  config: TokenConfig,
+  projectRoot: string
+): Promise<TokenRegistry> {
+  return getSharedTokenRegistry().initialize(config, projectRoot);
+}
+
+/**
+ * Clear the shared registry
+ */
+export function clearSharedRegistry(): void {
+  sharedRegistry?.clear();
+  sharedRegistry = null;
+}
+
+/**
+ * Create a standalone registry (not shared)
+ */
+export function createTokenRegistry(): TokenRegistryManager {
+  return new TokenRegistryManager();
+}