@sarjallab09/figma-intelligence 1.0.0

package/figma-intelligence-layer/src/tools/phase3-generation/system-drift/index.ts

@@ -0,0 +1,535 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// System Drift
+// Compares design-token variables from a canonical Figma file against one or
+// more target files using the Figma REST API.  Calculates a drift score per
+// file, categorises each deviation, and formats the results as a detailed
+// report, inline Figma annotation JSON, or a PR-comment markdown block.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { DriftReport, TokenDrift } from "../../../shared/types.js";
+import { decisionLog } from "../../../shared/decision-log.js";
+
+// ─── Public types ─────────────────────────────────────────────────────────────
+
+export interface SystemDriftArgs {
+  canonicalFileKey: string;
+  targetFileKeys: string[];
+  tokenTypes?: string[];
+  threshold?: number;
+  outputFormat: "report" | "annotations" | "pr-comment";
+}
+
+export interface DriftSummary {
+  filesChecked: number;
+  healthyFiles: number;
+  warningFiles: number;
+  criticalFiles: number;
+  totalTokensCompared: number;
+  totalDriftingTokens: number;
+  overallDriftScore: number;
+}
+
+export interface SystemDriftResult {
+  reports: DriftReport[];
+  summary: DriftSummary;
+  formattedOutput: string;
+  logEntryId: string;
+}
+
+// ─── Figma REST API types ──────────────────────────────────────────────────────
+
+interface FigmaVariableColor {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+interface FigmaVariableAlias {
+  type: "VARIABLE_ALIAS";
+  id: string;
+}
+
+type FigmaVariableValue =
+  | number
+  | string
+  | boolean
+  | FigmaVariableColor
+  | FigmaVariableAlias;
+
+interface FigmaVariable {
+  id: string;
+  name: string;
+  resolvedType: string;
+  valuesByMode: Record<string, FigmaVariableValue>;
+  description?: string;
+}
+
+interface FigmaVariableCollection {
+  id: string;
+  name: string;
+  modes: Array<{ modeId: string; name: string }>;
+  variableIds: string[];
+  defaultModeId: string;
+}
+
+interface FigmaVariablesResponse {
+  meta: {
+    variables: Record<string, FigmaVariable>;
+    variableCollections: Record<string, FigmaVariableCollection>;
+  };
+}
+
+// ─── Flat token map ───────────────────────────────────────────────────────────
+
+interface FlatToken {
+  name: string;
+  type: string;
+  value: string;
+}
+
+// ─── REST API fetch ───────────────────────────────────────────────────────────
+
+function normalizeVariableValue(value: FigmaVariableValue): string {
+  if (typeof value === "number") {
+    return String(Math.round(value * 1000) / 1000);
+  }
+  if (typeof value === "string") return value;
+  if (typeof value === "boolean") return String(value);
+  if (typeof value === "object" && value !== null) {
+    if ("r" in value && "g" in value && "b" in value) {
+      const r = Math.round((value as FigmaVariableColor).r * 255);
+      const g = Math.round((value as FigmaVariableColor).g * 255);
+      const b = Math.round((value as FigmaVariableColor).b * 255);
+      return `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`;
+    }
+    if ("type" in value && (value as FigmaVariableAlias).type === "VARIABLE_ALIAS") {
+      return `alias:${(value as FigmaVariableAlias).id}`;
+    }
+  }
+  return JSON.stringify(value);
+}
+
+async function fetchFileVariables(fileKey: string): Promise<FlatToken[]> {
+  const token = process.env.FIGMA_ACCESS_TOKEN;
+  if (!token) {
+    throw new Error("systemDrift: FIGMA_ACCESS_TOKEN environment variable is not set.");
+  }
+
+  const response = await fetch(
+    `https://api.figma.com/v1/files/${fileKey}/variables/local`,
+    { headers: { "X-Figma-Token": token } }
+  );
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new Error(
+      `systemDrift: Figma API error for file "${fileKey}" — HTTP ${response.status}: ${body.slice(0, 200)}`
+    );
+  }
+
+  const data = (await response.json()) as FigmaVariablesResponse;
+  const { variables, variableCollections } = data.meta;
+  const flatTokens: FlatToken[] = [];
+
+  for (const variable of Object.values(variables ?? {})) {
+    // Resolve which collection owns this variable to get the default mode
+    let defaultModeId: string | undefined;
+    for (const col of Object.values(variableCollections ?? {})) {
+      if (col.variableIds.includes(variable.id)) {
+        defaultModeId = col.defaultModeId;
+        break;
+      }
+    }
+
+    const rawValue =
+      defaultModeId && variable.valuesByMode[defaultModeId] !== undefined
+        ? variable.valuesByMode[defaultModeId]
+        : Object.values(variable.valuesByMode)[0];
+
+    flatTokens.push({
+      name: variable.name,
+      type: variable.resolvedType,
+      value: rawValue !== undefined ? normalizeVariableValue(rawValue) : "null",
+    });
+  }
+
+  return flatTokens;
+}
+
+// ─── Drift detection ──────────────────────────────────────────────────────────
+
+function hexDistance(a: string, b: string): number {
+  const clean = (s: string) => s.replace(/^#/, "").toLowerCase().padEnd(6, "0");
+  const ca = clean(a);
+  const cb = clean(b);
+  let diff = 0;
+  for (let i = 0; i < Math.max(ca.length, cb.length); i++) {
+    if ((ca[i] ?? "") !== (cb[i] ?? "")) diff++;
+  }
+  return diff;
+}
+
+function isHexColor(value: string): boolean {
+  return /^#[0-9a-fA-F]{3,8}$/.test(value);
+}
+
+function computeInstanceCount(tokenName: string): number {
+  // Heuristic: deeply nested token names imply fewer cross-file usages
+  const depth = (tokenName.match(/\//g) ?? []).length;
+  return Math.max(1, Math.round(30 / (depth + 1)));
+}
+
+function compareTokenSets(
+  canonicalTokens: FlatToken[],
+  targetTokens: FlatToken[],
+  tokenTypeFilter: string[] | undefined
+): TokenDrift[] {
+  const violations: TokenDrift[] = [];
+
+  const shouldInclude = (type: string): boolean => {
+    if (!tokenTypeFilter || tokenTypeFilter.length === 0) return true;
+    return tokenTypeFilter.some((tf) =>
+      type.toLowerCase().includes(tf.toLowerCase())
+    );
+  };
+
+  const canonicalMap = new Map(canonicalTokens.map((t) => [t.name, t]));
+  const targetMap = new Map(targetTokens.map((t) => [t.name, t]));
+
+  // Check canonical tokens against target
+  for (const [name, canonical] of canonicalMap) {
+    if (!shouldInclude(canonical.type)) continue;
+
+    const target = targetMap.get(name);
+    if (!target) {
+      violations.push({
+        tokenName: name,
+        canonicalValue: canonical.value,
+        targetValue: "MISSING",
+        driftType: "missing",
+        severity: "warning",
+        instancesAffected: computeInstanceCount(name),
+      });
+      continue;
+    }
+
+    if (canonical.value === target.value) continue;
+
+    // Hex typo: one character differs
+    if (isHexColor(canonical.value) && isHexColor(target.value)) {
+      const dist = hexDistance(canonical.value, target.value);
+      if (dist === 1) {
+        violations.push({
+          tokenName: name,
+          canonicalValue: canonical.value,
+          targetValue: target.value,
+          driftType: "typo",
+          severity: "warning",
+          instancesAffected: computeInstanceCount(name),
+        });
+        continue;
+      }
+    }
+
+    // Different value, same name → override
+    violations.push({
+      tokenName: name,
+      canonicalValue: canonical.value,
+      targetValue: target.value,
+      driftType: "override",
+      severity: "critical",
+      instancesAffected: computeInstanceCount(name),
+    });
+  }
+
+  // Check target tokens not present in canonical → extra
+  for (const [name, target] of targetMap) {
+    if (!shouldInclude(target.type)) continue;
+    if (!canonicalMap.has(name)) {
+      violations.push({
+        tokenName: name,
+        canonicalValue: "NOT_IN_CANONICAL",
+        targetValue: target.value,
+        driftType: "extra",
+        severity: "warning",
+        instancesAffected: computeInstanceCount(name),
+      });
+    }
+  }
+
+  return violations;
+}
+
+// ─── Score classification ─────────────────────────────────────────────────────
+
+type DriftCategory = "healthy" | "warning" | "critical";
+
+function classifyScore(driftScore: number, threshold: number): DriftCategory {
+  const warningThreshold = Math.min(15, threshold);
+  if (driftScore <= Math.min(5, threshold * 0.33)) return "healthy";
+  if (driftScore <= warningThreshold) return "warning";
+  return "critical";
+}
+
+// ─── Output formatters ────────────────────────────────────────────────────────
+
+function formatAsReport(reports: DriftReport[], summary: DriftSummary, threshold: number): string {
+  const lines: string[] = [];
+  lines.push("# Design System Drift Report");
+  lines.push(`Generated: ${new Date().toISOString()}`);
+  lines.push("");
+  lines.push("## Summary");
+  lines.push(`- Files checked: ${summary.filesChecked}`);
+  lines.push(
+    `- Status: ${summary.healthyFiles} healthy / ${summary.warningFiles} warning / ${summary.criticalFiles} critical`
+  );
+  lines.push(`- Total tokens compared: ${summary.totalTokensCompared}`);
+  lines.push(`- Total drifting tokens: ${summary.totalDriftingTokens}`);
+  lines.push(`- Overall drift score: ${summary.overallDriftScore.toFixed(1)}%`);
+  lines.push(`- Alert threshold: ${threshold}%`);
+  lines.push("");
+
+  for (const report of reports) {
+    const cat = classifyScore(report.driftScore, threshold);
+    const statusLabel =
+      cat === "healthy" ? "[HEALTHY]" : cat === "warning" ? "[WARNING]" : "[CRITICAL]";
+
+    lines.push(`## ${statusLabel} ${report.targetFileKey}`);
+    lines.push(
+      `Drift score: **${report.driftScore.toFixed(1)}%** (${report.driftingTokens}/${report.totalTokens} tokens)`
+    );
+    lines.push("");
+
+    if (report.violations.length === 0) {
+      lines.push("No violations found.");
+    } else {
+      lines.push("| Token | Canonical | Target | Type | Severity | Instances |");
+      lines.push("|-------|-----------|--------|------|----------|-----------|");
+      for (const v of report.violations.slice(0, 30)) {
+        lines.push(
+          `| ${v.tokenName} | \`${v.canonicalValue}\` | \`${v.targetValue}\` | ${v.driftType} | ${v.severity} | ${v.instancesAffected} |`
+        );
+      }
+      if (report.violations.length > 30) {
+        lines.push(`\n...and ${report.violations.length - 30} more violations`);
+      }
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+function formatAsPrComment(reports: DriftReport[], summary: DriftSummary): string {
+  const overallStatus =
+    summary.criticalFiles > 0 ? "CRITICAL" : summary.warningFiles > 0 ? "WARNING" : "HEALTHY";
+
+  const statusBadge =
+    overallStatus === "CRITICAL"
+      ? "[CRITICAL]"
+      : overallStatus === "WARNING"
+      ? "[WARNING]"
+      : "[HEALTHY]";
+
+  const lines: string[] = [];
+  lines.push(`## Design System Drift Check ${statusBadge}`);
+  lines.push("");
+  lines.push(
+    `Compared **${summary.filesChecked}** file(s) against the canonical design system.`
+  );
+  lines.push(
+    `Overall drift: **${summary.overallDriftScore.toFixed(1)}%** (${summary.totalDriftingTokens} of ${summary.totalTokensCompared} tokens)`
+  );
+  lines.push("");
+  lines.push("| File | Drift | Status |");
+  lines.push("|------|-------|--------|");
+  for (const r of reports) {
+    const cat = r.driftScore < 5 ? "HEALTHY" : r.driftScore < 15 ? "WARNING" : "CRITICAL";
+    lines.push(`| \`${r.targetFileKey}\` | ${r.driftScore.toFixed(1)}% | ${cat} |`);
+  }
+  lines.push("");
+
+  const criticalViolations = reports
+    .flatMap((r) => r.violations.filter((v) => v.severity === "critical"))
+    .slice(0, 10);
+
+  if (criticalViolations.length > 0) {
+    lines.push("### Critical violations requiring attention");
+    for (const v of criticalViolations) {
+      lines.push(
+        `- **${v.tokenName}**: canonical \`${v.canonicalValue}\` vs target \`${v.targetValue}\` — affects ~${v.instancesAffected} instance(s)`
+      );
+    }
+    lines.push("");
+  }
+
+  const warnings = reports
+    .flatMap((r) => r.violations.filter((v) => v.severity === "warning"))
+    .slice(0, 8);
+
+  if (warnings.length > 0) {
+    lines.push("<details><summary>Warnings</summary>");
+    lines.push("");
+    for (const v of warnings) {
+      lines.push(
+        `- \`${v.tokenName}\` (${v.driftType}): \`${v.canonicalValue}\` → \`${v.targetValue}\``
+      );
+    }
+    lines.push("</details>");
+    lines.push("");
+  }
+
+  if (overallStatus === "HEALTHY") {
+    lines.push("All tokens are within acceptable drift thresholds. No action required.");
+  }
+
+  return lines.join("\n");
+}
+
+function formatAsAnnotations(reports: DriftReport[]): string {
+  const annotations = reports.flatMap((report) =>
+    report.violations
+      .filter((v) => v.severity === "critical")
+      .map((v) => ({
+        fileKey: report.targetFileKey,
+        tokenName: v.tokenName,
+        message: `[DRIFT] ${v.tokenName}: expected "${v.canonicalValue}" but found "${v.targetValue}" (${v.driftType}, ~${v.instancesAffected} instance(s))`,
+        severity: v.severity,
+        driftType: v.driftType,
+        instancesAffected: v.instancesAffected,
+      }))
+  );
+
+  return JSON.stringify({ annotations }, null, 2);
+}
+
+// ─── Main handler ─────────────────────────────────────────────────────────────
+
+export async function systemDriftHandler(
+  args: SystemDriftArgs
+): Promise<SystemDriftResult> {
+  const {
+    canonicalFileKey,
+    targetFileKeys,
+    tokenTypes,
+    threshold = 15,
+    outputFormat,
+  } = args;
+
+  if (!canonicalFileKey) throw new Error("systemDrift: `canonicalFileKey` is required.");
+  if (!targetFileKeys || targetFileKeys.length === 0) {
+    throw new Error("systemDrift: `targetFileKeys` must be a non-empty array.");
+  }
+
+  // 1. Fetch canonical tokens
+  const canonicalTokens = await fetchFileVariables(canonicalFileKey);
+
+  if (canonicalTokens.length === 0) {
+    throw new Error(
+      `systemDrift: No variables found in canonical file "${canonicalFileKey}". Ensure the file has local variables and the access token has read permission.`
+    );
+  }
+
+  // 2. Compare each target file
+  const reports: DriftReport[] = [];
+
+  for (const targetFileKey of targetFileKeys) {
+    let targetTokens: FlatToken[];
+    try {
+      targetTokens = await fetchFileVariables(targetFileKey);
+    } catch (err) {
+      console.error(
+        `systemDrift: Skipping "${targetFileKey}" — ${err instanceof Error ? err.message : String(err)}`
+      );
+      continue;
+    }
+
+    const violations = compareTokenSets(canonicalTokens, targetTokens, tokenTypes);
+
+    // Count only tokens that match the type filter for the denominator
+    const relevantCanonical = tokenTypes && tokenTypes.length > 0
+      ? canonicalTokens.filter((t) =>
+          tokenTypes.some((tf) => t.type.toLowerCase().includes(tf.toLowerCase()))
+        )
+      : canonicalTokens;
+
+    const totalTokens = relevantCanonical.length;
+    const driftingTokens = violations.filter((v) => v.driftType !== "extra").length;
+    const driftScore = totalTokens > 0 ? (driftingTokens / totalTokens) * 100 : 0;
+
+    reports.push({
+      canonicalFileKey,
+      targetFileKey,
+      totalTokens,
+      driftingTokens,
+      driftScore: Math.round(driftScore * 10) / 10,
+      violations,
+    });
+  }
+
+  // 3. Build summary
+  const healthyFiles = reports.filter(
+    (r) => classifyScore(r.driftScore, threshold) === "healthy"
+  ).length;
+  const warningFiles = reports.filter(
+    (r) => classifyScore(r.driftScore, threshold) === "warning"
+  ).length;
+  const criticalFiles = reports.filter(
+    (r) => classifyScore(r.driftScore, threshold) === "critical"
+  ).length;
+  const totalTokensCompared = reports.reduce((s, r) => s + r.totalTokens, 0);
+  const totalDriftingTokens = reports.reduce((s, r) => s + r.driftingTokens, 0);
+  const overallDriftScore =
+    totalTokensCompared > 0 ? (totalDriftingTokens / totalTokensCompared) * 100 : 0;
+
+  const summary: DriftSummary = {
+    filesChecked: reports.length,
+    healthyFiles,
+    warningFiles,
+    criticalFiles,
+    totalTokensCompared,
+    totalDriftingTokens,
+    overallDriftScore: Math.round(overallDriftScore * 10) / 10,
+  };
+
+  // 4. Format output
+  let formattedOutput: string;
+  switch (outputFormat) {
+    case "report":
+      formattedOutput = formatAsReport(reports, summary, threshold);
+      break;
+    case "pr-comment":
+      formattedOutput = formatAsPrComment(reports, summary);
+      break;
+    case "annotations":
+      formattedOutput = formatAsAnnotations(reports);
+      break;
+    default:
+      formattedOutput = formatAsReport(reports, summary, threshold);
+  }
+
+  // 5. Log the decision
+  const logEntry = await decisionLog.log({
+    tool: "system-drift",
+    nodeIds: [],
+    rationale: `Drift analysis: canonical="${canonicalFileKey}", targets=${targetFileKeys.join(", ")}. Files checked: ${reports.length}. Overall drift: ${summary.overallDriftScore.toFixed(1)}%. Healthy: ${healthyFiles}, Warning: ${warningFiles}, Critical: ${criticalFiles}. Output: ${outputFormat}.`,
+    tokens: [],
+    reversible: false,
+    metadata: {
+      canonicalFileKey,
+      targetFileKeys,
+      tokenTypes,
+      threshold,
+      outputFormat,
+      summary,
+    },
+  });
+
+  return {
+    reports,
+    summary,
+    formattedOutput,
+    logEntryId: logEntry.id,
+  };
+}

package/figma-intelligence-layer/src/tools/phase3-generation/unsplash-search/index.ts

@@ -0,0 +1,84 @@
+import { decisionLog } from "../../../shared/decision-log.js";
+import {
+  searchUnsplashPhotos,
+  trackUnsplashDownload,
+  UnsplashContentFilter,
+  UnsplashOrientation,
+  UnsplashPhotoResult,
+} from "../../../shared/unsplash.js";
+
+export interface FigmaUnsplashSearchArgs {
+  query: string;
+  count?: number;
+  page?: number;
+  orientation?: UnsplashOrientation;
+  contentFilter?: UnsplashContentFilter;
+  color?: string;
+  trackDownloads?: boolean;
+}
+
+export interface FigmaUnsplashSearchResult {
+  query: string;
+  count: number;
+  page: number;
+  total: number;
+  totalPages: number;
+  results: UnsplashPhotoResult[];
+  logEntryId: string;
+}
+
+export async function figmaUnsplashSearchHandler(
+  args: FigmaUnsplashSearchArgs
+): Promise<FigmaUnsplashSearchResult> {
+  const {
+    query,
+    count = 4,
+    page = 1,
+    orientation,
+    contentFilter = "high",
+    color,
+    trackDownloads = false,
+  } = args;
+
+  const search = await searchUnsplashPhotos({
+    query,
+    page,
+    perPage: count,
+    orientation,
+    contentFilter,
+    color,
+  });
+
+  if (trackDownloads) {
+    for (const photo of search.results) {
+      await trackUnsplashDownload(photo.links.downloadLocation);
+    }
+  }
+
+  const logEntry = await decisionLog.log({
+    tool: "figma_unsplash_search",
+    nodeIds: [],
+    rationale: `Searched Unsplash for "${query}" and returned ${search.results.length} image candidates for Figma generation.`,
+    reversible: false,
+    metadata: {
+      query,
+      count,
+      page,
+      orientation,
+      contentFilter,
+      color,
+      trackDownloads,
+      total: search.total,
+    },
+  });
+
+  return {
+    query,
+    count: search.results.length,
+    page,
+    total: search.total,
+    totalPages: search.totalPages,
+    results: search.results,
+    logEntryId: logEntry.id,
+  };
+}