@sarjallab09/figma-intelligence 1.0.0

package/figma-intelligence-layer/src/shared/enrichment-pipeline.ts

@@ -0,0 +1,671 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// P0: Semantic Enrichment Pipeline
+// Transforms raw Figma data into semantically rich, AI-friendly structured data.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { FigmaNode, Token, ComponentSet, RGBA, Paint, TextStyle } from "./types.js";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 1. Style Resolver
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export interface ResolvedStyle {
+  fills: Array<{
+    type: string;
+    hex?: string;
+    semanticName?: string;
+    opacity?: number;
+    variableId?: string;
+  }>;
+  strokes: Array<{
+    type: string;
+    hex?: string;
+    weight?: number;
+  }>;
+  typography?: {
+    family: string;
+    weight: number;
+    size: number;
+    lineHeight: number;
+    letterSpacing: number;
+    category: "heading" | "subheading" | "body" | "caption" | "overline" | "display";
+  };
+  spacing?: {
+    padding: { top: number; right: number; bottom: number; left: number };
+    gap: number;
+    snappedToGrid: boolean;
+    gridBase: number;
+  };
+  radius?: {
+    values: number[];
+    category: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "xxl" | "full";
+    uniform: boolean;
+  };
+  effects: Array<{
+    type: string;
+    category:
+      | "elevation-sm"
+      | "elevation-md"
+      | "elevation-lg"
+      | "blur"
+      | "inner-shadow"
+      | "none";
+  }>;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Convert 0-1 float RGBA to a hex string.
+ * Returns "#RRGGBB" when fully opaque, "#RRGGBBAA" otherwise.
+ */
+export function rgbaToHex(r: number, g: number, b: number, a?: number): string {
+  const clamp = (v: number) => Math.max(0, Math.min(255, Math.round(v * 255)));
+  const rr = clamp(r).toString(16).padStart(2, "0");
+  const gg = clamp(g).toString(16).padStart(2, "0");
+  const bb = clamp(b).toString(16).padStart(2, "0");
+  if (a !== undefined && a < 1) {
+    const aa = clamp(a).toString(16).padStart(2, "0");
+    return `#${rr}${gg}${bb}${aa}`.toUpperCase();
+  }
+  return `#${rr}${gg}${bb}`.toUpperCase();
+}
+
+function euclideanColorDistance(a: RGBA, b: RGBA): number {
+  return Math.sqrt((a.r - b.r) ** 2 + (a.g - b.g) ** 2 + (a.b - b.b) ** 2);
+}
+
+function parseColorTokenValue(value: string | number | boolean): RGBA | null {
+  if (typeof value !== "string") return null;
+  const hex = value.replace(/^#/, "");
+  if (hex.length === 6 || hex.length === 8) {
+    const r = parseInt(hex.slice(0, 2), 16) / 255;
+    const g = parseInt(hex.slice(2, 4), 16) / 255;
+    const b = parseInt(hex.slice(4, 6), 16) / 255;
+    const a = hex.length === 8 ? parseInt(hex.slice(6, 8), 16) / 255 : 1;
+    return { r, g, b, a };
+  }
+  return null;
+}
+
+function findNearestToken(
+  color: RGBA,
+  tokens: Token[]
+): { name: string; distance: number } | null {
+  let best: { name: string; distance: number } | null = null;
+  for (const token of tokens) {
+    if (token.type !== "COLOR") continue;
+    const tokenColor = parseColorTokenValue(token.value);
+    if (!tokenColor) continue;
+    const dist = euclideanColorDistance(color, tokenColor);
+    if (!best || dist < best.distance) {
+      best = { name: token.name, distance: dist };
+    }
+  }
+  return best;
+}
+
+function categorizeTypography(
+  fontSize: number
+): "heading" | "subheading" | "body" | "caption" | "overline" | "display" {
+  if (fontSize >= 48) return "display";
+  if (fontSize >= 28) return "heading";
+  if (fontSize >= 20) return "subheading";
+  if (fontSize >= 14) return "body";
+  if (fontSize >= 10) return "caption";
+  return "overline";
+}
+
+function allMultiplesOf(values: number[], base: number): boolean {
+  return values.every((v) => v % base === 0);
+}
+
+function categorizeRadius(
+  values: number[]
+): "none" | "xs" | "sm" | "md" | "lg" | "xl" | "xxl" | "full" {
+  const max = Math.max(...values);
+  if (max === 0) return "none";
+  if (max <= 2) return "xs";
+  if (max <= 4) return "sm";
+  if (max <= 8) return "md";
+  if (max <= 16) return "lg";
+  if (max <= 24) return "xl";
+  if (max <= 48) return "xxl";
+  return "full";
+}
+
+function categorizeRadiusSingle(
+  value: number
+): "none" | "xs" | "sm" | "md" | "lg" | "xl" | "xxl" | "full" {
+  return categorizeRadius([value]);
+}
+
+function categorizeEffect(
+  type: string,
+  radius?: number
+):
+  | "elevation-sm"
+  | "elevation-md"
+  | "elevation-lg"
+  | "blur"
+  | "inner-shadow"
+  | "none" {
+  if (type === "INNER_SHADOW") return "inner-shadow";
+  if (type === "LAYER_BLUR" || type === "BACKGROUND_BLUR") return "blur";
+  if (type === "DROP_SHADOW") {
+    if (radius === undefined) return "elevation-md";
+    if (radius <= 4) return "elevation-sm";
+    if (radius <= 16) return "elevation-md";
+    return "elevation-lg";
+  }
+  return "none";
+}
+
+// ── Main Resolver ────────────────────────────────────────────────────────────
+
+export function resolveStyles(node: FigmaNode, tokens?: Token[]): ResolvedStyle {
+  const colorTokens = tokens ?? [];
+
+  // Fills
+  const fills: ResolvedStyle["fills"] = (node.fills ?? []).map((paint: Paint) => {
+    const entry: ResolvedStyle["fills"][number] = { type: paint.type };
+    if (paint.color) {
+      entry.hex = rgbaToHex(paint.color.r, paint.color.g, paint.color.b, paint.color.a);
+      entry.opacity = paint.opacity ?? paint.color.a;
+
+      if (colorTokens.length > 0) {
+        const match = findNearestToken(paint.color, colorTokens);
+        if (match && match.distance < 0.05) {
+          entry.semanticName = match.name;
+        }
+      }
+    }
+    if (paint.variableId) {
+      entry.variableId = paint.variableId;
+    }
+    return entry;
+  });
+
+  // Strokes
+  const strokes: ResolvedStyle["strokes"] = (node.strokes ?? []).map((paint: Paint) => {
+    const entry: ResolvedStyle["strokes"][number] = { type: paint.type };
+    if (paint.color) {
+      entry.hex = rgbaToHex(paint.color.r, paint.color.g, paint.color.b, paint.color.a);
+    }
+    return entry;
+  });
+
+  // Typography
+  let typography: ResolvedStyle["typography"] | undefined;
+  if (node.style) {
+    const ts: TextStyle = node.style;
+    typography = {
+      family: ts.fontFamily,
+      weight: ts.fontWeight,
+      size: ts.fontSize,
+      lineHeight: ts.lineHeightPx,
+      letterSpacing: ts.letterSpacing,
+      category: categorizeTypography(ts.fontSize),
+    };
+  }
+
+  // Spacing
+  let spacing: ResolvedStyle["spacing"] | undefined;
+  const hasSpacing =
+    node.paddingTop !== undefined ||
+    node.paddingRight !== undefined ||
+    node.paddingBottom !== undefined ||
+    node.paddingLeft !== undefined ||
+    node.itemSpacing !== undefined;
+  if (hasSpacing) {
+    const top = node.paddingTop ?? 0;
+    const right = node.paddingRight ?? 0;
+    const bottom = node.paddingBottom ?? 0;
+    const left = node.paddingLeft ?? 0;
+    const gap = node.itemSpacing ?? 0;
+    const allValues = [top, right, bottom, left, gap];
+    const snapTo8 = allMultiplesOf(allValues, 8);
+    const snapTo4 = allMultiplesOf(allValues, 4);
+    const gridBase = snapTo8 ? 8 : 4;
+    spacing = {
+      padding: { top, right, bottom, left },
+      gap,
+      snappedToGrid: snapTo8 || snapTo4,
+      gridBase,
+    };
+  }
+
+  // Radius — extract from node if available (corner radii or single)
+  let radius: ResolvedStyle["radius"] | undefined;
+  const nodeAny = node as unknown as Record<string, unknown>;
+  if (nodeAny.cornerRadii && Array.isArray(nodeAny.cornerRadii)) {
+    const values = nodeAny.cornerRadii as number[];
+    radius = {
+      values,
+      category: categorizeRadius(values),
+      uniform: values.every((v) => v === values[0]),
+    };
+  } else if (typeof nodeAny.cornerRadius === "number") {
+    const v = nodeAny.cornerRadius as number;
+    radius = {
+      values: [v, v, v, v],
+      category: categorizeRadius([v]),
+      uniform: true,
+    };
+  }
+
+  // Effects
+  const seenEffects = new Set<string>();
+  const effects: ResolvedStyle["effects"] = [];
+  for (const effect of node.effects ?? []) {
+    if (effect.visible === false) continue;
+    const cat = categorizeEffect(effect.type, effect.radius);
+    const key = `${effect.type}::${cat}`;
+    if (seenEffects.has(key)) continue;
+    seenEffects.add(key);
+    effects.push({ type: effect.type, category: cat });
+  }
+
+  return { fills, strokes, typography, spacing, radius, effects };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 2. Relationship Mapper
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export interface ComponentRelationship {
+  componentId: string;
+  componentName: string;
+  parentSetId?: string;
+  parentSetName?: string;
+  variantSiblings: Array<{
+    id: string;
+    name: string;
+    variantProps: Record<string, string>;
+  }>;
+  instanceCount: number;
+  dependsOn: string[];
+  usedBy: string[];
+}
+
+export interface NodeRelationship {
+  id: string;
+  name: string;
+  type: string;
+  depth: number;
+  parentId?: string;
+  parentName?: string;
+  siblingIndex: number;
+  siblingCount: number;
+  childCount: number;
+  isAutoLayout: boolean;
+  isComponent: boolean;
+  isInstance: boolean;
+}
+
+export function mapRelationships(nodes: FigmaNode[]): NodeRelationship[] {
+  const result: NodeRelationship[] = [];
+
+  function walk(
+    node: FigmaNode,
+    depth: number,
+    parentId: string | undefined,
+    parentName: string | undefined,
+    siblingIndex: number,
+    siblingCount: number
+  ): void {
+    const children = node.children ?? [];
+    result.push({
+      id: node.id,
+      name: node.name,
+      type: node.type,
+      depth,
+      parentId,
+      parentName,
+      siblingIndex,
+      siblingCount,
+      childCount: children.length,
+      isAutoLayout:
+        node.layoutMode !== undefined && node.layoutMode !== "NONE",
+      isComponent:
+        node.type === "COMPONENT" || node.type === "COMPONENT_SET",
+      isInstance: node.type === "INSTANCE",
+    });
+
+    for (let i = 0; i < children.length; i++) {
+      walk(children[i], depth + 1, node.id, node.name, i, children.length);
+    }
+  }
+
+  for (let i = 0; i < nodes.length; i++) {
+    walk(nodes[i], 0, undefined, undefined, i, nodes.length);
+  }
+
+  return result;
+}
+
+export function mapComponentRelationships(
+  componentSets: ComponentSet[],
+  allInstances?: Array<{ id: string; mainComponentId: string }>
+): ComponentRelationship[] {
+  const instances = allInstances ?? [];
+
+  // Build instance count map: mainComponentId → count
+  const instanceCountMap = new Map<string, number>();
+  for (const inst of instances) {
+    instanceCountMap.set(
+      inst.mainComponentId,
+      (instanceCountMap.get(inst.mainComponentId) ?? 0) + 1
+    );
+  }
+
+  // Build usedBy map: nestedComponentId → set of parent component IDs
+  const usedByMap = new Map<string, Set<string>>();
+
+  const relationships: ComponentRelationship[] = [];
+
+  for (const set of componentSets) {
+    const variantSiblings: ComponentRelationship["variantSiblings"] = [];
+    const dependsOn = new Set<string>();
+
+    for (const child of set.children) {
+      // Each child in a component set is a variant
+      variantSiblings.push({
+        id: child.id,
+        name: child.name,
+        variantProps: child.variantProperties ?? {},
+      });
+
+      // Detect nested component references by walking the child tree
+      collectNestedComponentIds(child, dependsOn, child.id);
+    }
+
+    // Remove self-references from dependsOn
+    const childIds = new Set(set.children.map((c) => c.id));
+    const filteredDeps = [...dependsOn].filter(
+      (id) => id !== set.id && !childIds.has(id)
+    );
+
+    // Register usedBy for each dependency
+    for (const depId of filteredDeps) {
+      if (!usedByMap.has(depId)) usedByMap.set(depId, new Set());
+      usedByMap.get(depId)!.add(set.id);
+    }
+
+    // Sum instance counts across all children in the set
+    let totalInstances = 0;
+    for (const child of set.children) {
+      totalInstances += instanceCountMap.get(child.id) ?? 0;
+    }
+
+    relationships.push({
+      componentId: set.id,
+      componentName: set.name,
+      parentSetId: undefined,
+      parentSetName: undefined,
+      variantSiblings,
+      instanceCount: totalInstances,
+      dependsOn: filteredDeps,
+      usedBy: [], // populated in second pass
+    });
+  }
+
+  // Second pass: populate usedBy
+  for (const rel of relationships) {
+    const usedBy = usedByMap.get(rel.componentId);
+    if (usedBy) {
+      rel.usedBy = [...usedBy];
+    }
+  }
+
+  return relationships;
+}
+
+/**
+ * Recursively collects componentId references from a node tree.
+ */
+function collectNestedComponentIds(
+  node: FigmaNode,
+  result: Set<string>,
+  selfId: string
+): void {
+  if (node.componentId && node.componentId !== selfId) {
+    result.add(node.componentId);
+  }
+  for (const child of node.children ?? []) {
+    collectNestedComponentIds(child, result, selfId);
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 3. Data Enricher (main pipeline)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export interface EnrichedDesignSystem {
+  summary: {
+    totalTokens: number;
+    totalComponents: number;
+    totalStyles: number;
+    colorTokenCount: number;
+    spacingTokenCount: number;
+    typographyCount: number;
+    componentSetCount: number;
+  };
+  tokens: {
+    colors: Array<{
+      name: string;
+      hex: string;
+      opacity?: number;
+      semanticGroup?: string;
+      collectionName?: string;
+    }>;
+    spacing: Array<{ name: string; value: number; snappedTo4px: boolean }>;
+    radii: Array<{ name: string; value: number; category: string }>;
+    typography: Array<{ name: string; value: string }>;
+    other: Array<{ name: string; type: string; value: unknown }>;
+  };
+  components: Array<{
+    id: string;
+    name: string;
+    description?: string;
+    variantProperties: string[];
+    variantCount: number;
+    category: string;
+  }>;
+  relationships: ComponentRelationship[];
+}
+
+/**
+ * Infer a semantic group from a slash-separated token name.
+ */
+export function inferSemanticGroup(tokenName: string): string {
+  const lower = tokenName.toLowerCase();
+  const segments = lower.split("/").map((s) => s.trim());
+  const joined = segments.join("/");
+
+  // Color groups
+  if (/primary/.test(joined)) return "color/primary";
+  if (/secondary/.test(joined)) return "color/secondary";
+  if (/tertiary/.test(joined)) return "color/tertiary";
+  if (/neutral|gray|grey/.test(joined)) return "color/neutral";
+  if (/success|green/.test(joined)) return "color/success";
+  if (/warning|yellow|amber/.test(joined)) return "color/warning";
+  if (/error|danger|red|destructive/.test(joined)) return "color/error";
+  if (/info|blue/.test(joined)) return "color/info";
+  if (/background|bg|surface/.test(joined)) return "color/background";
+  if (/text|foreground|fg/.test(joined)) return "color/text";
+  if (/border|stroke|outline/.test(joined)) return "color/border";
+  if (/brand/.test(joined)) return "color/brand";
+  if (/color|col|fill/.test(joined)) return "color/other";
+
+  // Spacing
+  if (/space|spacing|gap|padding|margin/.test(joined)) return "spacing";
+
+  // Radius
+  if (/radius|corner|round/.test(joined)) return "radius";
+
+  // Typography
+  if (/font|typo|text|letter|line-height|line_height/.test(joined)) return "typography";
+
+  // Sizing
+  if (/size|width|height/.test(joined)) return "sizing";
+
+  // Opacity
+  if (/opacity|alpha/.test(joined)) return "opacity";
+
+  // Shadow / elevation
+  if (/shadow|elevation/.test(joined)) return "elevation";
+
+  // Use first segment as fallback
+  if (segments.length > 1) return segments[0];
+  return "other";
+}
+
+const COMPONENT_CATEGORY_RULES: Array<{ pattern: RegExp; category: string }> = [
+  { pattern: /\b(button|btn)\b/i, category: "button" },
+  {
+    pattern: /\b(input|field|select|checkbox|radio|toggle|switch)\b/i,
+    category: "input",
+  },
+  { pattern: /\b(card)\b/i, category: "card" },
+  {
+    pattern: /\b(nav|menu|tab|sidebar|breadcrumb)\b/i,
+    category: "navigation",
+  },
+  {
+    pattern: /\b(alert|toast|snackbar|badge|tag|chip)\b/i,
+    category: "feedback",
+  },
+  {
+    pattern: /\b(container|section|grid|stack|divider)\b/i,
+    category: "layout",
+  },
+  { pattern: /\b(table|list|avatar|icon)\b/i, category: "data-display" },
+  {
+    pattern: /\b(modal|dialog|popover|tooltip|drawer|sheet)\b/i,
+    category: "overlay",
+  },
+];
+
+function inferComponentCategory(name: string): string {
+  for (const rule of COMPONENT_CATEGORY_RULES) {
+    if (rule.pattern.test(name)) return rule.category;
+  }
+  return "other";
+}
+
+function isSpacingToken(name: string): boolean {
+  return /space|spacing|gap|padding|margin/i.test(name);
+}
+
+function isRadiusToken(name: string): boolean {
+  return /radius|corner|round/i.test(name);
+}
+
+export function enrichDesignSystem(
+  tokens: Token[],
+  componentSets: ComponentSet[],
+  instances?: Array<{ id: string; mainComponentId: string }>
+): EnrichedDesignSystem {
+  // ── Categorize tokens ──────────────────────────────────────────────────────
+  const colors: EnrichedDesignSystem["tokens"]["colors"] = [];
+  const spacing: EnrichedDesignSystem["tokens"]["spacing"] = [];
+  const radii: EnrichedDesignSystem["tokens"]["radii"] = [];
+  const typography: EnrichedDesignSystem["tokens"]["typography"] = [];
+  const other: EnrichedDesignSystem["tokens"]["other"] = [];
+
+  for (const token of tokens) {
+    switch (token.type) {
+      case "COLOR": {
+        const colorVal =
+          typeof token.value === "string" ? token.value : String(token.value);
+        const parsed = parseColorTokenValue(colorVal);
+        const hex = parsed
+          ? rgbaToHex(parsed.r, parsed.g, parsed.b, parsed.a)
+          : colorVal;
+        const opacity =
+          parsed && parsed.a < 1 ? parsed.a : undefined;
+        colors.push({
+          name: token.name,
+          hex,
+          opacity,
+          semanticGroup: inferSemanticGroup(token.name),
+          collectionName: token.collectionId,
+        });
+        break;
+      }
+      case "FLOAT": {
+        const numVal =
+          typeof token.value === "number"
+            ? token.value
+            : parseFloat(String(token.value));
+        if (isSpacingToken(token.name)) {
+          spacing.push({
+            name: token.name,
+            value: numVal,
+            snappedTo4px: numVal % 4 === 0,
+          });
+        } else if (isRadiusToken(token.name)) {
+          radii.push({
+            name: token.name,
+            value: numVal,
+            category: categorizeRadiusSingle(numVal),
+          });
+        } else {
+          other.push({ name: token.name, type: token.type, value: token.value });
+        }
+        break;
+      }
+      case "STRING": {
+        // Strings with font/typography semantics
+        if (/font|typo|text/i.test(token.name)) {
+          typography.push({
+            name: token.name,
+            value: String(token.value),
+          });
+        } else {
+          other.push({ name: token.name, type: token.type, value: token.value });
+        }
+        break;
+      }
+      default:
+        other.push({ name: token.name, type: token.type, value: token.value });
+    }
+  }
+
+  // ── Components ─────────────────────────────────────────────────────────────
+  const components: EnrichedDesignSystem["components"] = componentSets.map(
+    (set) => ({
+      id: set.id,
+      name: set.name,
+      description: set.description || undefined,
+      variantProperties: Object.keys(set.variantGroupProperties),
+      variantCount: set.children.length,
+      category: inferComponentCategory(set.name),
+    })
+  );
+
+  // ── Relationships ──────────────────────────────────────────────────────────
+  const relationships = mapComponentRelationships(componentSets, instances);
+
+  // ── Summary ────────────────────────────────────────────────────────────────
+  const summary: EnrichedDesignSystem["summary"] = {
+    totalTokens: tokens.length,
+    totalComponents: componentSets.reduce(
+      (acc, s) => acc + s.children.length,
+      0
+    ),
+    totalStyles: colors.length + typography.length,
+    colorTokenCount: colors.length,
+    spacingTokenCount: spacing.length,
+    typographyCount: typography.length,
+    componentSetCount: componentSets.length,
+  };
+
+  return {
+    summary,
+    tokens: { colors, spacing, radii, typography, other },
+    components,
+    relationships,
+  };
+}