@sarjallab09/figma-intelligence 1.0.0

package/figma-intelligence-layer/src/tools/phase4-sync/watch-docs/index.ts

@@ -0,0 +1,676 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// figma_watch_docs — Auto-updating documentation
+//
+// Monitors components for changes and regenerates documentation when drift is
+// detected. Produces changelogs, tracks doc freshness, and integrates with
+// the webhook system for real-time updates.
+//
+// Features:
+//   - Compare current component state against last-known spec snapshot
+//   - Detect what changed (variants added, tokens changed, states modified)
+//   - Auto-regenerate component spec when drift is detected
+//   - Generate human-readable changelog entries
+//   - Track doc freshness scores across the entire file
+//   - Register webhook triggers for automated doc updates
+// ─────────────────────────────────────────────────────────────────────────────
+
+import fs from "fs/promises";
+import path from "path";
+import { getBridge } from "../../../shared/figma-bridge.js";
+import { componentSpecHandler } from "../../phase5-governance/component-spec/index.js";
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface WatchDocsArgs {
+  /** Action to perform */
+  action: "check" | "regenerate" | "changelog" | "freshness" | "register-webhook";
+  /** Component node IDs to watch (omit for all components on current page) */
+  nodeIds?: string[];
+  /** Path to store spec snapshots for comparison */
+  snapshotDir?: string;
+  /** Auto-regenerate specs that are stale */
+  autoRegenerate?: boolean;
+  /** Output format for regenerated specs */
+  specFormat?: "json" | "markdown" | "figma-page" | "all";
+  /** Webhook file key (for register-webhook action) */
+  fileKey?: string;
+}
+
+interface ComponentSnapshot {
+  nodeId: string;
+  name: string;
+  timestamp: string;
+  variantCount: number;
+  variantAxes: Array<{ name: string; values: string[] }>;
+  stateCount: number;
+  states: string[];
+  tokenCount: number;
+  tokenNames: string[];
+  properties: Array<{ name: string; type: string }>;
+  description: string;
+  hash: string;
+}
+
+interface DriftEntry {
+  nodeId: string;
+  componentName: string;
+  driftType: "variant-added" | "variant-removed" | "token-changed" | "state-changed" | "property-changed" | "new-component" | "description-changed";
+  field: string;
+  before: string;
+  after: string;
+  severity: "major" | "minor" | "patch";
+}
+
+interface ChangelogEntry {
+  version: string;
+  date: string;
+  component: string;
+  changes: Array<{
+    type: "added" | "changed" | "removed" | "fixed";
+    description: string;
+  }>;
+}
+
+// ─── Snapshot management ───────────────────────────────────────────────────
+
+function defaultSnapshotDir(): string {
+  return path.join(process.cwd(), ".figma-docs-snapshots");
+}
+
+async function ensureSnapshotDir(dir: string): Promise<void> {
+  try {
+    await fs.mkdir(dir, { recursive: true });
+  } catch { /* exists */ }
+}
+
+async function loadSnapshot(dir: string, nodeId: string): Promise<ComponentSnapshot | null> {
+  const filePath = path.join(dir, `${nodeId.replace(/[:/]/g, "_")}.json`);
+  try {
+    const data = await fs.readFile(filePath, "utf-8");
+    return JSON.parse(data);
+  } catch {
+    return null;
+  }
+}
+
+async function saveSnapshot(dir: string, snapshot: ComponentSnapshot): Promise<void> {
+  const filePath = path.join(dir, `${snapshot.nodeId.replace(/[:/]/g, "_")}.json`);
+  await fs.writeFile(filePath, JSON.stringify(snapshot, null, 2), "utf-8");
+}
+
+function hashSnapshot(snap: Omit<ComponentSnapshot, "hash" | "timestamp">): string {
+  const str = JSON.stringify({
+    variantAxes: snap.variantAxes,
+    states: snap.states,
+    tokenNames: snap.tokenNames,
+    properties: snap.properties,
+    description: snap.description,
+  });
+  // Simple hash for change detection
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = ((hash << 5) - hash) + char;
+    hash |= 0;
+  }
+  return Math.abs(hash).toString(36);
+}
+
+// ─── Component scanning ───────────────────────────────────────────────────
+
+async function scanComponents(nodeIds?: string[]): Promise<ComponentSnapshot[]> {
+  const bridge = await getBridge();
+
+  const script = nodeIds?.length
+    ? `
+      (async () => {
+        var results = [];
+        var ids = ${JSON.stringify(nodeIds)};
+        for (var i = 0; i < ids.length; i++) {
+          var node = figma.getNodeById(ids[i]);
+          if (!node) continue;
+          results.push(extractComponent(node));
+        }
+        function extractComponent(node) {
+          var axes = [];
+          var states = [];
+          var tokenNames = [];
+          var props = [];
+
+          if (node.variantGroupProperties) {
+            var vgp = node.variantGroupProperties;
+            for (var key in vgp) {
+              axes.push({ name: key, values: vgp[key].values || [] });
+              if (key.toLowerCase() === 'state') {
+                states = vgp[key].values || [];
+              }
+            }
+          }
+
+          if (node.componentPropertyDefinitions) {
+            var cpd = node.componentPropertyDefinitions;
+            for (var key in cpd) {
+              props.push({ name: key, type: cpd[key].type });
+            }
+          }
+
+          // Scan for tokens
+          function scanTokens(n) {
+            var bound = n.boundVariables || {};
+            for (var prop in bound) {
+              var binding = bound[prop];
+              if (binding && binding.id) {
+                try {
+                  var v = figma.variables.getVariableById(binding.id);
+                  if (v && tokenNames.indexOf(v.name) === -1) tokenNames.push(v.name);
+                } catch (e) {}
+              }
+              if (Array.isArray(binding)) {
+                for (var j = 0; j < binding.length; j++) {
+                  if (binding[j] && binding[j].id) {
+                    try {
+                      var v = figma.variables.getVariableById(binding[j].id);
+                      if (v && tokenNames.indexOf(v.name) === -1) tokenNames.push(v.name);
+                    } catch (e) {}
+                  }
+                }
+              }
+            }
+            if (n.children) {
+              for (var i = 0; i < n.children.length; i++) {
+                scanTokens(n.children[i]);
+              }
+            }
+          }
+          scanTokens(node);
+
+          return {
+            nodeId: node.id,
+            name: node.name,
+            variantCount: node.children ? node.children.length : 0,
+            variantAxes: axes,
+            stateCount: states.length,
+            states: states,
+            tokenCount: tokenNames.length,
+            tokenNames: tokenNames,
+            properties: props,
+            description: node.description || ''
+          };
+        }
+        return results;
+      })();
+    `
+    : `
+      (async () => {
+        var results = [];
+        var page = figma.currentPage;
+        var components = page.findAll(function(n) {
+          return n.type === 'COMPONENT_SET' || (n.type === 'COMPONENT' && !n.parent.type.includes('COMPONENT'));
+        });
+        for (var i = 0; i < Math.min(components.length, 50); i++) {
+          var node = components[i];
+          var axes = [];
+          var states = [];
+          var tokenNames = [];
+          var props = [];
+
+          if (node.variantGroupProperties) {
+            var vgp = node.variantGroupProperties;
+            for (var key in vgp) {
+              axes.push({ name: key, values: vgp[key].values || [] });
+              if (key.toLowerCase() === 'state') states = vgp[key].values || [];
+            }
+          }
+
+          if (node.componentPropertyDefinitions) {
+            var cpd = node.componentPropertyDefinitions;
+            for (var key in cpd) {
+              props.push({ name: key, type: cpd[key].type });
+            }
+          }
+
+          function scanTokens(n, names) {
+            var bound = n.boundVariables || {};
+            for (var prop in bound) {
+              var binding = bound[prop];
+              if (binding && binding.id) {
+                try {
+                  var v = figma.variables.getVariableById(binding.id);
+                  if (v && names.indexOf(v.name) === -1) names.push(v.name);
+                } catch(e) {}
+              }
+              if (Array.isArray(binding)) {
+                for (var j = 0; j < binding.length; j++) {
+                  if (binding[j] && binding[j].id) {
+                    try {
+                      var v = figma.variables.getVariableById(binding[j].id);
+                      if (v && names.indexOf(v.name) === -1) names.push(v.name);
+                    } catch(e) {}
+                  }
+                }
+              }
+            }
+            if (n.children) {
+              for (var c = 0; c < n.children.length; c++) scanTokens(n.children[c], names);
+            }
+          }
+          scanTokens(node, tokenNames);
+
+          results.push({
+            nodeId: node.id,
+            name: node.name,
+            variantCount: node.children ? node.children.length : 0,
+            variantAxes: axes,
+            stateCount: states.length,
+            states: states,
+            tokenCount: tokenNames.length,
+            tokenNames: tokenNames,
+            properties: props,
+            description: node.description || ''
+          });
+        }
+        return results;
+      })();
+    `;
+
+  const result = await bridge.execute(script);
+  if (!result.success || !result.result) {
+    throw new Error(result.error || "Failed to scan components");
+  }
+
+  const rawSnapshots = result.result as Array<Omit<ComponentSnapshot, "hash" | "timestamp">>;
+  const now = new Date().toISOString();
+
+  return rawSnapshots.map((s) => ({
+    ...s,
+    timestamp: now,
+    hash: hashSnapshot(s),
+  }));
+}
+
+// ─── Drift detection ──────────────────────────────────────────────────────
+
+function detectDrift(old: ComponentSnapshot, current: ComponentSnapshot): DriftEntry[] {
+  const drifts: DriftEntry[] = [];
+
+  // Check variant axes
+  for (const axis of current.variantAxes) {
+    const oldAxis = old.variantAxes.find((a) => a.name === axis.name);
+    if (!oldAxis) {
+      drifts.push({
+        nodeId: current.nodeId,
+        componentName: current.name,
+        driftType: "variant-added",
+        field: `variantAxis:${axis.name}`,
+        before: "(none)",
+        after: axis.values.join(", "),
+        severity: "major",
+      });
+    } else {
+      const added = axis.values.filter((v) => !oldAxis.values.includes(v));
+      const removed = oldAxis.values.filter((v) => !axis.values.includes(v));
+      for (const v of added) {
+        drifts.push({
+          nodeId: current.nodeId,
+          componentName: current.name,
+          driftType: "variant-added",
+          field: `${axis.name}:${v}`,
+          before: oldAxis.values.join(", "),
+          after: axis.values.join(", "),
+          severity: "minor",
+        });
+      }
+      for (const v of removed) {
+        drifts.push({
+          nodeId: current.nodeId,
+          componentName: current.name,
+          driftType: "variant-removed",
+          field: `${axis.name}:${v}`,
+          before: oldAxis.values.join(", "),
+          after: axis.values.join(", "),
+          severity: "major",
+        });
+      }
+    }
+  }
+
+  // Check removed axes
+  for (const oldAxis of old.variantAxes) {
+    if (!current.variantAxes.find((a) => a.name === oldAxis.name)) {
+      drifts.push({
+        nodeId: current.nodeId,
+        componentName: current.name,
+        driftType: "variant-removed",
+        field: `variantAxis:${oldAxis.name}`,
+        before: oldAxis.values.join(", "),
+        after: "(removed)",
+        severity: "major",
+      });
+    }
+  }
+
+  // Check states
+  const addedStates = current.states.filter((s) => !old.states.includes(s));
+  const removedStates = old.states.filter((s) => !current.states.includes(s));
+  for (const s of addedStates) {
+    drifts.push({ nodeId: current.nodeId, componentName: current.name, driftType: "state-changed", field: `state:${s}`, before: "(none)", after: s, severity: "minor" });
+  }
+  for (const s of removedStates) {
+    drifts.push({ nodeId: current.nodeId, componentName: current.name, driftType: "state-changed", field: `state:${s}`, before: s, after: "(removed)", severity: "major" });
+  }
+
+  // Check tokens
+  const addedTokens = current.tokenNames.filter((t) => !old.tokenNames.includes(t));
+  const removedTokens = old.tokenNames.filter((t) => !current.tokenNames.includes(t));
+  for (const t of addedTokens) {
+    drifts.push({ nodeId: current.nodeId, componentName: current.name, driftType: "token-changed", field: t, before: "(none)", after: t, severity: "patch" });
+  }
+  for (const t of removedTokens) {
+    drifts.push({ nodeId: current.nodeId, componentName: current.name, driftType: "token-changed", field: t, before: t, after: "(removed)", severity: "minor" });
+  }
+
+  // Check properties
+  const currentPropNames = current.properties.map((p) => p.name);
+  const oldPropNames = old.properties.map((p) => p.name);
+  for (const p of current.properties) {
+    if (!oldPropNames.includes(p.name)) {
+      drifts.push({ nodeId: current.nodeId, componentName: current.name, driftType: "property-changed", field: p.name, before: "(none)", after: `${p.name} (${p.type})`, severity: "minor" });
+    }
+  }
+  for (const p of old.properties) {
+    if (!currentPropNames.includes(p.name)) {
+      drifts.push({ nodeId: current.nodeId, componentName: current.name, driftType: "property-changed", field: p.name, before: `${p.name} (${p.type})`, after: "(removed)", severity: "major" });
+    }
+  }
+
+  // Check description
+  if (old.description !== current.description) {
+    drifts.push({ nodeId: current.nodeId, componentName: current.name, driftType: "description-changed", field: "description", before: old.description.slice(0, 80), after: current.description.slice(0, 80), severity: "patch" });
+  }
+
+  return drifts;
+}
+
+// ─── Changelog generator ──────────────────────────────────────────────────
+
+function generateChangelog(drifts: DriftEntry[]): ChangelogEntry[] {
+  const byComponent = new Map<string, DriftEntry[]>();
+  for (const d of drifts) {
+    const existing = byComponent.get(d.componentName) ?? [];
+    existing.push(d);
+    byComponent.set(d.componentName, existing);
+  }
+
+  const entries: ChangelogEntry[] = [];
+  const today = new Date().toISOString().slice(0, 10);
+
+  for (const [component, componentDrifts] of byComponent) {
+    const changes: ChangelogEntry["changes"] = [];
+
+    for (const d of componentDrifts) {
+      switch (d.driftType) {
+        case "variant-added":
+          changes.push({ type: "added", description: `Added variant ${d.field}: ${d.after}` });
+          break;
+        case "variant-removed":
+          changes.push({ type: "removed", description: `Removed variant ${d.field}` });
+          break;
+        case "state-changed":
+          changes.push({
+            type: d.after === "(removed)" ? "removed" : "added",
+            description: d.after === "(removed)" ? `Removed state: ${d.before}` : `Added state: ${d.after}`,
+          });
+          break;
+        case "token-changed":
+          changes.push({
+            type: d.after === "(removed)" ? "removed" : "changed",
+            description: d.after === "(removed)" ? `Removed token binding: ${d.before}` : `Added token binding: ${d.after}`,
+          });
+          break;
+        case "property-changed":
+          changes.push({
+            type: d.after === "(removed)" ? "removed" : "added",
+            description: d.after === "(removed)" ? `Removed property: ${d.field}` : `Added property: ${d.after}`,
+          });
+          break;
+        case "description-changed":
+          changes.push({ type: "changed", description: `Updated component description` });
+          break;
+      }
+    }
+
+    // Determine version bump
+    const hasMajor = componentDrifts.some((d) => d.severity === "major");
+    const hasMinor = componentDrifts.some((d) => d.severity === "minor");
+    const version = hasMajor ? "major" : hasMinor ? "minor" : "patch";
+
+    entries.push({ version, date: today, component, changes });
+  }
+
+  return entries;
+}
+
+function renderChangelogMarkdown(entries: ChangelogEntry[]): string {
+  const lines: string[] = [];
+  lines.push(`# Component Changelog`);
+  lines.push(`> Auto-generated by \`figma_watch_docs\``);
+  lines.push(``);
+
+  for (const entry of entries) {
+    lines.push(`## ${entry.component} — ${entry.version} (${entry.date})`);
+    lines.push(``);
+    for (const change of entry.changes) {
+      const icon = change.type === "added" ? "➕" : change.type === "removed" ? "➖" : change.type === "fixed" ? "🔧" : "🔄";
+      lines.push(`- ${icon} **${change.type}**: ${change.description}`);
+    }
+    lines.push(``);
+  }
+
+  return lines.join("\n");
+}
+
+// ─── Main handler ──────────────────────────────────────────────────────────
+
+export async function watchDocsHandler(args: WatchDocsArgs): Promise<unknown> {
+  const snapshotDir = args.snapshotDir ?? defaultSnapshotDir();
+  await ensureSnapshotDir(snapshotDir);
+
+  switch (args.action) {
+    case "check": {
+      // Scan current components and compare against snapshots
+      const current = await scanComponents(args.nodeIds);
+      const allDrifts: DriftEntry[] = [];
+      const staleComponents: string[] = [];
+      const freshComponents: string[] = [];
+
+      for (const snap of current) {
+        const old = await loadSnapshot(snapshotDir, snap.nodeId);
+        if (!old) {
+          allDrifts.push({
+            nodeId: snap.nodeId,
+            componentName: snap.name,
+            driftType: "new-component",
+            field: "component",
+            before: "(none)",
+            after: snap.name,
+            severity: "major",
+          });
+          staleComponents.push(snap.name);
+        } else if (old.hash !== snap.hash) {
+          const drifts = detectDrift(old, snap);
+          allDrifts.push(...drifts);
+          if (drifts.length > 0) staleComponents.push(snap.name);
+          else freshComponents.push(snap.name);
+        } else {
+          freshComponents.push(snap.name);
+        }
+      }
+
+      // Auto-regenerate if requested
+      const regenerated: string[] = [];
+      if (args.autoRegenerate && staleComponents.length > 0) {
+        for (const snap of current) {
+          if (!staleComponents.includes(snap.name)) continue;
+          try {
+            await componentSpecHandler({
+              nodeId: snap.nodeId,
+              outputFormat: args.specFormat ?? "markdown",
+            });
+            await saveSnapshot(snapshotDir, snap);
+            regenerated.push(snap.name);
+          } catch { /* skip failed */ }
+        }
+      }
+
+      // Save all current snapshots
+      for (const snap of current) {
+        await saveSnapshot(snapshotDir, snap);
+      }
+
+      const changelog = generateChangelog(allDrifts);
+
+      return {
+        action: "check",
+        totalComponents: current.length,
+        staleCount: staleComponents.length,
+        freshCount: freshComponents.length,
+        staleComponents,
+        freshComponents,
+        drifts: allDrifts,
+        changelog: changelog.length > 0 ? renderChangelogMarkdown(changelog) : null,
+        regenerated: regenerated.length > 0 ? regenerated : undefined,
+        freshness: current.length > 0
+          ? Math.round((freshComponents.length / current.length) * 100)
+          : 100,
+      };
+    }
+
+    case "regenerate": {
+      // Force-regenerate specs for specified components
+      const current = await scanComponents(args.nodeIds);
+      const results: Array<{ name: string; success: boolean; error?: string }> = [];
+
+      for (const snap of current) {
+        try {
+          await componentSpecHandler({
+            nodeId: snap.nodeId,
+            outputFormat: args.specFormat ?? "all",
+          });
+          await saveSnapshot(snapshotDir, snap);
+          results.push({ name: snap.name, success: true });
+        } catch (err) {
+          results.push({ name: snap.name, success: false, error: err instanceof Error ? err.message : String(err) });
+        }
+      }
+
+      return {
+        action: "regenerate",
+        total: results.length,
+        succeeded: results.filter((r) => r.success).length,
+        failed: results.filter((r) => !r.success).length,
+        results,
+      };
+    }
+
+    case "changelog": {
+      // Generate changelog from drift detection
+      const current = await scanComponents(args.nodeIds);
+      const allDrifts: DriftEntry[] = [];
+
+      for (const snap of current) {
+        const old = await loadSnapshot(snapshotDir, snap.nodeId);
+        if (!old) {
+          allDrifts.push({
+            nodeId: snap.nodeId,
+            componentName: snap.name,
+            driftType: "new-component",
+            field: "component",
+            before: "(none)",
+            after: snap.name,
+            severity: "major",
+          });
+        } else if (old.hash !== snap.hash) {
+          allDrifts.push(...detectDrift(old, snap));
+        }
+      }
+
+      const changelog = generateChangelog(allDrifts);
+      const markdown = renderChangelogMarkdown(changelog);
+
+      // Save updated snapshots
+      for (const snap of current) {
+        await saveSnapshot(snapshotDir, snap);
+      }
+
+      return {
+        action: "changelog",
+        entries: changelog,
+        markdown,
+        totalChanges: allDrifts.length,
+      };
+    }
+
+    case "freshness": {
+      // Report documentation freshness across all components
+      const current = await scanComponents(args.nodeIds);
+      const report: Array<{
+        name: string;
+        nodeId: string;
+        fresh: boolean;
+        lastUpdated: string | null;
+        driftCount: number;
+      }> = [];
+
+      for (const snap of current) {
+        const old = await loadSnapshot(snapshotDir, snap.nodeId);
+        if (!old) {
+          report.push({ name: snap.name, nodeId: snap.nodeId, fresh: false, lastUpdated: null, driftCount: -1 });
+        } else {
+          const drifts = old.hash === snap.hash ? [] : detectDrift(old, snap);
+          report.push({
+            name: snap.name,
+            nodeId: snap.nodeId,
+            fresh: drifts.length === 0,
+            lastUpdated: old.timestamp,
+            driftCount: drifts.length,
+          });
+        }
+      }
+
+      const freshCount = report.filter((r) => r.fresh).length;
+      const freshness = report.length > 0 ? Math.round((freshCount / report.length) * 100) : 100;
+
+      return {
+        action: "freshness",
+        totalComponents: report.length,
+        freshCount,
+        staleCount: report.length - freshCount,
+        freshnessScore: freshness,
+        components: report,
+      };
+    }
+
+    case "register-webhook": {
+      // Return webhook configuration for automated doc updates
+      return {
+        action: "register-webhook",
+        message: "Use figma_webhook_listener to register a webhook that triggers doc regeneration on component changes.",
+        suggestedConfig: {
+          events: ["FILE_UPDATE", "LIBRARY_PUBLISH"],
+          triggers: {
+            onComponentChange: "run-audit",
+            onLibraryPublish: "run-health-report",
+          },
+          automatedActions: [
+            "On FILE_UPDATE: run figma_watch_docs(action: 'check', autoRegenerate: true)",
+            "On LIBRARY_PUBLISH: run figma_watch_docs(action: 'changelog') then figma_ci_check(checks: ['all'])",
+          ],
+          fileKey: args.fileKey ?? "(provide your Figma file key)",
+        },
+      };
+    }
+
+    default:
+      return { error: `Unknown action: ${args.action}` };
+  }
+}