@sarjallab09/figma-intelligence 1.1.0 → 1.2.1

package/figma-intelligence-layer/src/tools/phase3-generation/component-archaeologist/index.ts

@@ -1,660 +0,0 @@
-// ─────────────────────────────────────────────────────────────────────────────
-// Component Archaeologist
-// Reverse-engineers an arbitrary Figma node into a named component pattern.
-// Fingerprints the layer tree, snaps hardcoded values to design tokens, and
-// optionally promotes the node to a library component with variable bindings.
-// ─────────────────────────────────────────────────────────────────────────────
-
-import { getBridge } from "../../../shared/figma-bridge.js";
-import { decisionLog } from "../../../shared/decision-log.js";
-import {
-  snapToColorToken,
-  snapToSpacingToken,
-  figmaRgbaToHex,
-} from "../../../shared/token-utils.js";
-import { resolveTokenId } from "../../../shared/token-binder.js";
-import { getConceptForComponent, getAllTokenPaths } from "../../../shared/concept-taxonomy.js";
-import { FigmaNode, Token, TokenRef } from "../../../shared/types.js";
-
-// ─── Public types ─────────────────────────────────────────────────────────────
-
-export interface ComponentArchaeologistArgs {
-  nodeId: string;
-  outputAs: "analysis" | "component" | "both";
-  bindToExisting?: boolean;
-  createLibraryComponent?: boolean;
-  generateDocStub?: boolean;
-}
-
-export interface PatternMatch {
-  pattern: string;
-  candidates: string[];
-  confidence: number;
-  rationale: string;
-}
-
-export interface TokenMapping {
-  property: string;
-  hardcodedValue: string;
-  suggestedToken: string;
-  tokenValue: string | number;
-  delta: number | undefined;
-}
-
-export interface ComponentArchaeologistResult {
-  nodeId: string;
-  nodeName: string;
-  patternMatches: PatternMatch[];
-  bestMatch: string;
-  /** Concept from the taxonomy (e.g. "action", "surface", "field") */
-  concept: string | null;
-  /** Expected token paths for this concept from the taxonomy */
-  expectedTokens: string[];
-  tokenMappings: TokenMapping[];
-  promotedComponentId: string | null;
-  docStub: string | null;
-  layerSummary: LayerSummary;
-  logEntryId: string;
-}
-
-interface LayerSummary {
-  totalLayers: number;
-  depth: number;
-  hasImage: boolean;
-  hasIcon: boolean;
-  hasText: boolean;
-  hasInput: boolean;
-  hasAvatar: boolean;
-  textCount: number;
-  rectangleCount: number;
-  frameCount: number;
-  vectorCount: number;
-  layoutMode: "HORIZONTAL" | "VERTICAL" | "NONE" | undefined;
-  childCount: number;
-}
-
-// ─── Layer fingerprinting ─────────────────────────────────────────────────────
-
-type LayerSignal =
-  | "icon"
-  | "text"
-  | "image"
-  | "input"
-  | "avatar"
-  | "chevron"
-  | "cta"
-  | "title"
-  | "body"
-  | "label"
-  | "subtitle";
-
-function inferSignal(node: FigmaNode): LayerSignal[] {
-  const signals: LayerSignal[] = [];
-  const nameLower = node.name.toLowerCase();
-
-  if (node.type === "TEXT") {
-    signals.push("text");
-    if (/heading|title|h[1-6]/.test(nameLower)) signals.push("title");
-    if (/body|paragraph|description|content/.test(nameLower)) signals.push("body");
-    if (/label|caption|eyebrow|overline/.test(nameLower)) signals.push("label");
-    if (/subtitle|secondary|sub/.test(nameLower)) signals.push("subtitle");
-    if (/button|cta|action|submit|primary/.test(nameLower)) signals.push("cta");
-  }
-
-  if (node.type === "VECTOR" || /icon|ico|glyph|symbol/.test(nameLower)) {
-    signals.push("icon");
-    if (/chevron|arrow|caret/.test(nameLower)) signals.push("chevron");
-  }
-
-  if (node.fills?.some((f) => f.type === "IMAGE")) {
-    signals.push("image");
-    if (/avatar|profile|photo|user|face/.test(nameLower)) signals.push("avatar");
-  }
-
-  if (/input|field|textfield|text-field|textarea/.test(nameLower)) {
-    signals.push("input");
-  }
-
-  return signals;
-}
-
-function collectSignals(node: FigmaNode, depth = 0): LayerSignal[] {
-  const signals = inferSignal(node);
-  if (depth < 6 && node.children) {
-    for (const child of node.children) {
-      signals.push(...collectSignals(child, depth + 1));
-    }
-  }
-  return signals;
-}
-
-function countLayerTypes(node: FigmaNode): LayerSummary {
-  let totalLayers = 0;
-  let maxDepth = 0;
-  let hasImage = false;
-  let hasIcon = false;
-  let hasText = false;
-  let hasInput = false;
-  let hasAvatar = false;
-  let textCount = 0;
-  let rectangleCount = 0;
-  let frameCount = 0;
-  let vectorCount = 0;
-
-  function walk(n: FigmaNode, depth: number) {
-    totalLayers++;
-    if (depth > maxDepth) maxDepth = depth;
-    const nameLower = n.name.toLowerCase();
-
-    if (n.type === "TEXT") {
-      hasText = true;
-      textCount++;
-    }
-    if (n.type === "RECTANGLE") rectangleCount++;
-    if (n.type === "FRAME" || n.type === "GROUP") frameCount++;
-    if (n.type === "VECTOR" || /icon/.test(nameLower)) {
-      hasIcon = true;
-      vectorCount++;
-    }
-    if (n.fills?.some((f) => f.type === "IMAGE")) {
-      hasImage = true;
-      if (/avatar|profile/.test(nameLower)) hasAvatar = true;
-    }
-    if (/input|field/.test(nameLower)) hasInput = true;
-
-    if (n.children) {
-      for (const child of n.children) walk(child, depth + 1);
-    }
-  }
-
-  walk(node, 0);
-
-  return {
-    totalLayers,
-    depth: maxDepth,
-    hasImage,
-    hasIcon,
-    hasText,
-    hasInput,
-    hasAvatar,
-    textCount,
-    rectangleCount,
-    frameCount,
-    vectorCount,
-    layoutMode: node.layoutMode,
-    childCount: node.children?.length ?? 0,
-  };
-}
-
-// ─── Pattern matching ─────────────────────────────────────────────────────────
-
-interface PatternRule {
-  pattern: string;
-  candidates: string[];
-  test: (signals: LayerSignal[], summary: LayerSummary) => boolean;
-  confidence: (signals: LayerSignal[], summary: LayerSummary) => number;
-  rationale: (signals: LayerSignal[], summary: LayerSummary) => string;
-}
-
-const PATTERN_RULES: PatternRule[] = [
-  {
-    pattern: "Icon + Text (horizontal)",
-    candidates: ["Button", "MenuItem", "Breadcrumb", "Tab"],
-    test: (s, summary) =>
-      s.includes("icon") &&
-      s.includes("text") &&
-      summary.layoutMode === "HORIZONTAL" &&
-      !s.includes("chevron"),
-    confidence: (s) => (s.includes("cta") ? 0.92 : 0.78),
-    rationale: (s) =>
-      `Horizontal auto-layout with icon + text signal. ${s.includes("cta") ? "CTA text found — likely Button." : "No CTA signal — could be MenuItem or Tab."}`,
-  },
-  {
-    pattern: "Image + Title + Body + CTA",
-    candidates: ["Card", "FeatureTile"],
-    test: (s) =>
-      s.includes("image") &&
-      s.includes("title") &&
-      s.includes("body") &&
-      s.includes("cta"),
-    confidence: () => 0.89,
-    rationale: () =>
-      "Classic card anatomy: image hero, title heading, body copy, and a call-to-action.",
-  },
-  {
-    pattern: "Label above + Input below",
-    candidates: ["FormField", "TextInput"],
-    test: (s) => s.includes("label") && s.includes("input"),
-    confidence: () => 0.91,
-    rationale: () =>
-      "Label node above an input container — canonical form field pattern.",
-  },
-  {
-    pattern: "Avatar + Name + Subtitle",
-    candidates: ["UserProfile", "CommentHeader"],
-    test: (s) => s.includes("avatar") && s.includes("text") && s.includes("subtitle"),
-    confidence: (s) => (s.includes("subtitle") ? 0.88 : 0.72),
-    rationale: (s) =>
-      `Avatar image with ${s.includes("subtitle") ? "name and subtitle text layers" : "name text layer"} — user identity pattern.`,
-  },
-  {
-    pattern: "Icon + Title + Chevron",
-    candidates: ["ListItem", "NavigationRow"],
-    test: (s) => s.includes("icon") && s.includes("title") && s.includes("chevron"),
-    confidence: () => 0.9,
-    rationale: () =>
-      "Leading icon, title text, and trailing chevron — list item or navigation row.",
-  },
-  {
-    pattern: "N equal-width columns",
-    candidates: ["DataTable", "ComparisonCard"],
-    test: (_, summary) =>
-      summary.layoutMode === "HORIZONTAL" &&
-      summary.childCount >= 3 &&
-      summary.textCount >= 3,
-    confidence: (_, summary) => (summary.childCount >= 4 ? 0.82 : 0.68),
-    rationale: (_, summary) =>
-      `${summary.childCount} equal-width children in horizontal layout — data table or comparison grid.`,
-  },
-  {
-    pattern: "Image + Title",
-    candidates: ["Card", "MediaCard", "ThumbnailItem"],
-    test: (s) => s.includes("image") && s.includes("title") && !s.includes("body"),
-    confidence: () => 0.74,
-    rationale: () =>
-      "Image with title but no body copy — compact media card or thumbnail.",
-  },
-  {
-    pattern: "Text only",
-    candidates: ["Heading", "Paragraph", "Badge", "Label"],
-    test: (s, summary) =>
-      s.includes("text") &&
-      !s.includes("icon") &&
-      !s.includes("image") &&
-      summary.textCount <= 2,
-    confidence: () => 0.6,
-    rationale: () =>
-      "Text-only node — standalone heading, label, badge, or paragraph.",
-  },
-];
-
-function fingerprintPatterns(
-  signals: LayerSignal[],
-  summary: LayerSummary
-): PatternMatch[] {
-  const matches: PatternMatch[] = [];
-
-  for (const rule of PATTERN_RULES) {
-    if (rule.test(signals, summary)) {
-      matches.push({
-        pattern: rule.pattern,
-        candidates: rule.candidates,
-        confidence: rule.confidence(signals, summary),
-        rationale: rule.rationale(signals, summary),
-      });
-    }
-  }
-
-  // Sort descending by confidence
-  matches.sort((a, b) => b.confidence - a.confidence);
-  return matches;
-}
-
-// ─── Token mapping ────────────────────────────────────────────────────────────
-
-function extractTokenMappings(node: FigmaNode, tokens: Token[]): TokenMapping[] {
-  const mappings: TokenMapping[] = [];
-
-  function walkFills(n: FigmaNode, propertyPath: string) {
-    if (n.fills) {
-      for (let i = 0; i < n.fills.length; i++) {
-        const fill = n.fills[i];
-        if (fill.type === "SOLID" && fill.color && !fill.variableId) {
-          const hex = figmaRgbaToHex(fill.color.r, fill.color.g, fill.color.b);
-          const ref: TokenRef = snapToColorToken(hex, tokens);
-          mappings.push({
-            property: `${propertyPath}.fills[${i}]`,
-            hardcodedValue: hex,
-            suggestedToken: ref.tokenName,
-            tokenValue: ref.tokenValue,
-            delta: typeof ref.delta === "number" ? ref.delta : undefined,
-          });
-        }
-      }
-    }
-
-    if (n.strokes) {
-      for (let i = 0; i < n.strokes.length; i++) {
-        const stroke = n.strokes[i];
-        if (stroke.type === "SOLID" && stroke.color && !stroke.variableId) {
-          const hex = figmaRgbaToHex(stroke.color.r, stroke.color.g, stroke.color.b);
-          const ref: TokenRef = snapToColorToken(hex, tokens);
-          mappings.push({
-            property: `${propertyPath}.strokes[${i}]`,
-            hardcodedValue: hex,
-            suggestedToken: ref.tokenName,
-            tokenValue: ref.tokenValue,
-            delta: typeof ref.delta === "number" ? ref.delta : undefined,
-          });
-        }
-      }
-    }
-
-    // Spacing
-    const spacingProps: Array<keyof FigmaNode> = [
-      "paddingLeft",
-      "paddingRight",
-      "paddingTop",
-      "paddingBottom",
-      "itemSpacing",
-    ];
-    for (const prop of spacingProps) {
-      const val = n[prop];
-      if (typeof val === "number" && val > 0) {
-        const ref = snapToSpacingToken(val);
-        if (ref.delta !== 0) {
-          mappings.push({
-            property: `${propertyPath}.${prop}`,
-            hardcodedValue: `${val}px`,
-            suggestedToken: ref.tokenName,
-            tokenValue: ref.tokenValue,
-            delta: ref.delta,
-          });
-        }
-      }
-    }
-
-    if (n.children) {
-      for (const child of n.children) {
-        walkFills(child, `${propertyPath}/${child.name}`);
-      }
-    }
-  }
-
-  walkFills(node, node.name);
-  return mappings;
-}
-
-// ─── Figma script: promote to component + bind variables ─────────────────────
-
-function buildPromoteScript(
-  nodeId: string,
-  componentName: string,
-  mappings: TokenMapping[],
-  tokens: Token[]
-): string {
-  // Resolve actual variable IDs for fill/stroke bindings
-  const resolvedBindings = mappings
-    .filter((m) => m.property.includes("fills") || m.property.includes("strokes"))
-    .slice(0, 20)
-    .map((m) => {
-      const variableId = resolveTokenId(m.suggestedToken, tokens);
-      return { ...m, variableId };
-    })
-    .filter((m) => m.variableId !== null);
-
-  // Generate actual setBoundVariable calls for resolved tokens
-  const bindingLines = resolvedBindings.length > 0
-    ? `
-  // Bind resolved design-system variables
-  const bindNode = async (n) => {
-    if (n.fills) {
-      for (let i = 0; i < n.fills.length; i++) {
-        if (n.fills[i].type === 'SOLID' && !n.fills[i].boundVariables?.color) {
-          const hex = (() => {
-            const c = n.fills[i].color;
-            const toHex = (v) => Math.round(v * 255).toString(16).padStart(2, '0');
-            return '#' + toHex(c.r) + toHex(c.g) + toHex(c.b);
-          })();
-          const mapping = ${JSON.stringify(resolvedBindings.map((m) => ({
-            hex: m.hardcodedValue.toLowerCase(),
-            variableId: m.variableId,
-          })))};
-          const match = mapping.find(m => m.hex === hex.toLowerCase());
-          if (match) {
-            const v = await figma.variables.getVariableByIdAsync(match.variableId);
-            if (v) {
-              const paints = [...n.fills];
-              paints[i] = figma.variables.setBoundVariableForPaint(paints[i], 'color', v);
-              n.fills = paints;
-            }
-          }
-        }
-      }
-    }
-    if (n.children) {
-      for (const child of n.children) await bindNode(child);
-    }
-  };
-  await bindNode(component);`
-    : mappings
-        .filter((m) => m.property.includes("fills"))
-        .slice(0, 20)
-        .map((m) => `  /* bind ${m.property} → ${m.suggestedToken} (${m.hardcodedValue}) — no matching variable found */`)
-        .join("\n");
-
-  return `
-(async () => {
-  const node = await figma.getNodeByIdAsync(${JSON.stringify(nodeId)});
-  if (!node) throw new Error('Node not found: ${nodeId}');
-
-  // Clone to preserve original, then promote clone
-  const clone = node.clone();
-  clone.name = ${JSON.stringify(componentName)};
-  node.parent.appendChild(clone);
-
-  // Promote to main component if not already
-  let component;
-  if (clone.type === 'COMPONENT') {
-    component = clone;
-  } else if (typeof clone.createComponent === 'function') {
-    component = clone.createComponent();
-  } else {
-    // Wrap in a frame-component approach
-    component = figma.createComponent();
-    component.name = ${JSON.stringify(componentName)};
-    component.resize(clone.width || 100, clone.height || 40);
-    node.parent.appendChild(component);
-    const inst = clone;
-    inst.x = 0;
-    inst.y = 0;
-    component.appendChild(inst);
-  }
-
-  // Rename layers to semantic names based on type
-  const renameByType = (n) => {
-    if (n.type === 'TEXT') {
-      const lc = n.name.toLowerCase();
-      if (!lc.includes('title') && !lc.includes('label') && !lc.includes('body')) {
-        if (n.fontSize >= 20) n.name = 'title';
-        else if (n.fontSize >= 14) n.name = 'body';
-        else n.name = 'label';
-      }
-    }
-    if (n.type === 'VECTOR' && !n.name.toLowerCase().includes('icon')) {
-      n.name = 'icon';
-    }
-    if (n.children) n.children.forEach(renameByType);
-  };
-  renameByType(component);
-
-${bindingLines}
-
-  figma.viewport.scrollAndZoomIntoView([component]);
-  return { componentId: component.id, name: component.name };
-})();
-`.trim();
-}
-
-// ─── Doc stub generator ───────────────────────────────────────────────────────
-
-function buildDocStub(
-  nodeName: string,
-  bestMatch: string,
-  candidates: string[],
-  mappings: TokenMapping[]
-): string {
-  const tokenLines = mappings
-    .slice(0, 10)
-    .map((m) => `| \`${m.suggestedToken}\` | \`${m.hardcodedValue}\` | ${m.property} |`)
-    .join("\n");
-
-  return `# ${nodeName}
-
-**Detected pattern:** ${bestMatch}
-**Probable component types:** ${candidates.join(", ")}
-
-## Overview
-Auto-generated documentation stub from Component Archaeologist analysis.
-Review and update the description below to accurately reflect this component's purpose.
-
-> [TODO: Describe what this component does, when to use it, and any important usage notes.]
-
-## Token Bindings
-
-| Token | Hardcoded Value | Property |
-|-------|----------------|----------|
-${tokenLines || "| — | — | No hardcoded values found |"}
-
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| — | — | — | [TODO: Document props] |
-
-## Usage
-
-\`\`\`tsx
-// [TODO: Add usage example]
-import { ${bestMatch.replace(/\s+/g, "")} } from "@ds/components";
-\`\`\`
-
-## Variants
-
-[TODO: Document available variants]
-
-## Accessibility
-
-[TODO: Document keyboard navigation, ARIA roles, and screen reader behaviour]
-
----
-*Generated by Component Archaeologist on ${new Date().toISOString().split("T")[0]}*
-`;
-}
-
-// ─── Main handler ─────────────────────────────────────────────────────────────
-
-export async function componentArchaeologistHandler(
-  args: ComponentArchaeologistArgs
-): Promise<ComponentArchaeologistResult> {
-  const {
-    nodeId,
-    outputAs,
-    createLibraryComponent = false,
-    generateDocStub = false,
-  } = args;
-
-  if (!nodeId) throw new Error("componentArchaeologist: `nodeId` is required.");
-
-  const bridge = await getBridge();
-
-  // 1. Fetch node tree from Figma
-  const node = await bridge.getNode(nodeId);
-  if (!node) throw new Error(`componentArchaeologist: Node "${nodeId}" not found.`);
-
-  // 2. Fetch tokens for snapping — DS tokens are authoritative when selected
-  const dsId = bridge.getActiveDesignSystemId();
-  let tokens: Token[];
-  if (dsId) {
-    const { getDesignSystemTokens } = await import("../../../shared/design-system-tokens.js");
-    tokens = getDesignSystemTokens(dsId);
-  } else {
-    tokens = await bridge.getTokens();
-  }
-
-  // 3. Summarize layers
-  const layerSummary = countLayerTypes(node);
-
-  // 4. Collect signals and fingerprint
-  const signals = collectSignals(node);
-  const patternMatches = fingerprintPatterns(signals, layerSummary);
-
-  const topMatch = patternMatches[0] ?? {
-    pattern: "Unknown",
-    candidates: ["Component"],
-    confidence: 0,
-    rationale: "No pattern matched. Layer structure does not fit known templates.",
-  };
-
-  const bestMatch = topMatch.candidates[0] ?? "Component";
-
-  // 5. Map hardcoded values to tokens
-  const tokenMappings = extractTokenMappings(node, tokens);
-
-  // 6. Optionally promote to component
-  let promotedComponentId: string | null = null;
-  if (
-    (outputAs === "component" || outputAs === "both") &&
-    createLibraryComponent
-  ) {
-    const componentName = `[DS] ${bestMatch} / ${node.name}`;
-    const script = buildPromoteScript(nodeId, componentName, tokenMappings, tokens);
-    const execResult = await bridge.execute(script);
-    if (execResult.success && execResult.result) {
-      const res = execResult.result as { componentId: string };
-      promotedComponentId = res.componentId;
-    } else {
-      console.error(
-        "componentArchaeologist: Promotion failed —",
-        execResult.error
-      );
-    }
-  }
-
-  // 7. Generate doc stub
-  const docStub = generateDocStub
-    ? buildDocStub(
-        node.name,
-        topMatch.pattern,
-        topMatch.candidates,
-        tokenMappings
-      )
-    : null;
-
-  // 8. Log the decision
-  const logEntry = await decisionLog.log({
-    tool: "component-archaeologist",
-    nodeIds: [nodeId, ...(promotedComponentId ? [promotedComponentId] : [])],
-    rationale: `Analysed "${node.name}" (${layerSummary.totalLayers} layers, depth ${layerSummary.depth}). Top pattern: "${topMatch.pattern}" → ${topMatch.candidates.join(", ")} (confidence ${(topMatch.confidence * 100).toFixed(0)}%). Mapped ${tokenMappings.length} hardcoded values to tokens. Promoted: ${!!promotedComponentId}.`,
-    tokens: tokenMappings.map((m) => m.suggestedToken),
-    reversible: true,
-    metadata: {
-      outputAs,
-      createLibraryComponent,
-      generateDocStub,
-      patternCount: patternMatches.length,
-      bestMatch,
-      tokenMappingCount: tokenMappings.length,
-      promotedComponentId,
-    },
-  });
-
-  // Enrich with concept taxonomy metadata
-  const conceptDef = getConceptForComponent(bestMatch);
-  const concept = conceptDef?.id ?? null;
-  const expectedTokens = concept ? getAllTokenPaths(concept) : [];
-
-  return {
-    nodeId,
-    nodeName: node.name,
-    patternMatches,
-    bestMatch,
-    concept,
-    expectedTokens,
-    tokenMappings,
-    promotedComponentId,
-    docStub,
-    layerSummary,
-    logEntryId: logEntry.id,
-  };
-}