@servicetitan/hammer-token 2.5.0 → 3.0.0

package/src/utils/figma/sync-orchestration.js

@@ -0,0 +1,683 @@
+#!/usr/bin/env node
+
+/**
+ * Sync Orchestration
+ *
+ * Main orchestration logic for syncing themes to Figma.
+ */
+
+const {
+  loadThemeTokenFiles,
+  parseTokenFile,
+  flattenTokenTree,
+  pathToVariableName,
+  isComponentToken,
+} = require("./token-parsing");
+const { resolvePrimitiveReferences } = require("./token-resolution");
+const { figmaRequest } = require("./figma-api");
+const { tokenValuesDiffer } = require("./figma-api");
+const { isShadowSizeToken } = require("./token-conversion");
+const { buildPrimitiveVariableRequest } = require("./sync-primitives");
+const { buildSemanticVariableRequest } = require("./sync-semantic");
+const { buildComponentVariableRequest } = require("./sync-components");
+const {
+  getOrCreateCollection,
+  getOrCreateExtendedCollection,
+  getOrCreateModes,
+} = require("./figma-api");
+
+/**
+ * Sync a single theme to Figma
+ * @param {Object} config - Configuration object
+ * @param {string} themeName - Theme name (e.g., "core", "test")
+ * @param {Map} coreTokens - Core theme tokens for comparison (null for core theme)
+ * @param {string} collectionName - Collection name to use
+ * @param {Object} [options] - Sync options
+ * @param {boolean} [options.dryRun=false] - If true, validate without making changes
+ * @param {boolean} [options.verbose=false] - Enable verbose logging
+ * @returns {Promise<Object>} Stats object
+ */
+async function syncTheme(
+  config,
+  themeName,
+  coreTokens = null,
+  collectionName = null,
+  options = {},
+) {
+  const { dryRun = false, verbose = false } = options;
+  const isExtended = themeName !== "core" && coreTokens !== null;
+  const actualCollectionName = collectionName || config.collectionName;
+
+  if (isExtended) {
+    console.log(`\n🎨 Processing extended theme: ${themeName}`);
+    console.log(`📦 Collection: ${actualCollectionName}\n`);
+  }
+
+  // Load token files for this theme
+  const tokenFiles = loadThemeTokenFiles(themeName);
+  if (tokenFiles.length === 0) {
+    console.log(`   ⚠️  No token files found for theme "${themeName}"`);
+    return { created: 0, updated: 0, skipped: 0, errors: 0, errorMessages: [] };
+  }
+
+  // Parse tokens
+  const allTokens = [];
+  for (const filePath of tokenFiles) {
+    const tokenData = parseTokenFile(filePath);
+    const flattened = flattenTokenTree(tokenData, [], [], filePath);
+    allTokens.push(...flattened);
+  }
+
+  // Build token registry
+  const tokenRegistry = new Map();
+  for (const tokenData of allTokens) {
+    const variableName = pathToVariableName(tokenData.path);
+    tokenRegistry.set(variableName, {
+      ...tokenData,
+      variableName,
+    });
+  }
+
+  // Resolve primitive references
+  const resolvedTokens = resolvePrimitiveReferences(tokenRegistry);
+
+  // Filter tokens for extended themes (only keep ones that differ from core)
+  let tokensToSync = resolvedTokens;
+  if (isExtended) {
+    const filteredTokens = new Map();
+    for (const [tokenPath, tokenData] of resolvedTokens.entries()) {
+      const coreToken = coreTokens.get(tokenPath);
+      if (!coreToken) {
+        // Token doesn't exist in core - include it
+        filteredTokens.set(tokenPath, tokenData);
+      } else {
+        // Compare values
+        const lightDiffers = tokenValuesDiffer(
+          tokenData.resolvedLight,
+          coreToken.resolvedLight,
+        );
+        const darkDiffers = tokenValuesDiffer(
+          tokenData.resolvedDark,
+          coreToken.resolvedDark,
+        );
+
+        if (lightDiffers || darkDiffers) {
+          filteredTokens.set(tokenPath, tokenData);
+        }
+      }
+    }
+    tokensToSync = filteredTokens;
+    console.log(
+      `   Found ${tokensToSync.size} tokens that differ from core (out of ${resolvedTokens.size} total)\n`,
+    );
+  }
+
+  // Get or create collection
+  // Optimize: Cache variables data to avoid redundant API calls
+  let collection;
+  let coreCollectionId = null;
+  let cachedVariablesData = null;
+
+  if (isExtended) {
+    // For extended themes, create an extended collection
+    // First, we need the core collection ID
+    cachedVariablesData = await figmaRequest(config, "/variables/local");
+    const collections = cachedVariablesData.meta?.variableCollections
+      ? Object.values(cachedVariablesData.meta.variableCollections)
+      : [];
+    const coreCollection = collections.find(
+      (coll) => coll.name === config.collectionName && !coll.isExtension,
+    );
+
+    if (!coreCollection) {
+      throw new Error(
+        `Core collection "${config.collectionName}" not found. Please sync core theme first.`,
+      );
+    }
+
+    coreCollectionId = coreCollection.id;
+    collection = await getOrCreateExtendedCollection(
+      config,
+      coreCollectionId,
+      actualCollectionName,
+    );
+  } else {
+    // For core theme, create regular collection
+    const collectionConfig = {
+      ...config,
+      collectionName: actualCollectionName,
+    };
+    console.log("   📥 Loading collection and variables...");
+    collection = await getOrCreateCollection(collectionConfig);
+  }
+
+  // Get or create modes (extended collections inherit modes from parent)
+  const modes = await getOrCreateModes(
+    { ...config, collectionName: actualCollectionName },
+    collection.id,
+  );
+
+  // Get existing variables (reuse cached data if available, otherwise fetch)
+  if (!cachedVariablesData) {
+    cachedVariablesData = await figmaRequest(config, "/variables/local");
+  }
+  const allExistingVariables = cachedVariablesData.meta?.variables
+    ? Object.values(cachedVariablesData.meta.variables)
+    : [];
+
+  // For extended collections, get variables from parent collection (they inherit)
+  // For core collections, get variables from the collection itself
+  let existingVariables;
+  if (isExtended && coreCollectionId) {
+    // Extended collections inherit variables from parent - get parent's variables
+    existingVariables = allExistingVariables.filter(
+      (v) => v.variableCollectionId === coreCollectionId,
+    );
+  } else {
+    // Core collection - get its own variables
+    existingVariables = allExistingVariables.filter(
+      (v) => v.variableCollectionId === collection.id,
+    );
+  }
+
+  // For extended collections, we only create variable mode value overrides (not new variables)
+  // For core collections, we create both variables and values
+  if (isExtended) {
+    // Extended collection: only create overrides for tokens that differ
+    // Variables are inherited from parent, so we only need variableModeValues
+    // Use parent collection's variables but target the extended collection for overrides
+    const tempIdMapForOverrides = new Map();
+
+    // Build semantic variable request - it will find existing variables from parent
+    // Note: For extended collections, we only want to create overrides, not new variables
+    // So we filter tokensToSync to only include tokens that have corresponding variables in parent
+    // Separate semantic and component tokens
+    const semanticTokensWithParent = new Map();
+    const componentTokensWithParent = new Map();
+
+    // Optimize: Create a Map for O(1) variable lookups
+    const variableNameMap = new Map();
+    for (const v of existingVariables) {
+      if (v.name) variableNameMap.set(v.name, v);
+      if (v.key && v.key !== v.name) variableNameMap.set(v.key, v);
+    }
+
+    for (const [tokenPath, tokenData] of tokensToSync.entries()) {
+      const isComponent = isComponentToken(tokenData.sourceFilePath);
+      const variableName = isComponent
+        ? `component/${tokenPath}`
+        : `semantic/${tokenPath}`;
+
+      // Check if variable exists in parent (including shadow size components)
+      // Optimize: Use Map lookup instead of array find
+      const parentVar =
+        variableNameMap.get(variableName) || variableNameMap.get(tokenPath);
+
+      // For shadow size tokens, check for x, y, blur components
+      if (!parentVar && isShadowSizeToken(tokenPath) && !isComponent) {
+        const hasX = variableNameMap.get(`${variableName}/x`);
+        const hasY = variableNameMap.get(`${variableName}/y`);
+        const hasBlur = variableNameMap.get(`${variableName}/blur`);
+        if (hasX && hasY && hasBlur) {
+          semanticTokensWithParent.set(tokenPath, tokenData);
+          continue;
+        }
+      }
+
+      if (parentVar) {
+        if (isComponent) {
+          componentTokensWithParent.set(tokenPath, tokenData);
+        } else {
+          semanticTokensWithParent.set(tokenPath, tokenData);
+        }
+      }
+    }
+
+    // Use semantic tokens for semantic request
+    const tokensWithParentVariables = semanticTokensWithParent;
+
+    if (
+      tokensWithParentVariables.size === 0 &&
+      componentTokensWithParent.size === 0
+    ) {
+      console.log(
+        `   ℹ️  No tokens to override (all match core or variables not found in parent)\n`,
+      );
+      return {
+        created: 0,
+        updated: 0,
+        skipped: 0,
+        errors: 0,
+        errorMessages: [],
+      };
+    }
+
+    // For extended themes, merge core tokens with extended tokens for reference resolution
+    // Extended tokens may reference primitives from core theme
+    const allTokensForRefs = new Map(coreTokens);
+    for (const [tokenPath, tokenData] of resolvedTokens.entries()) {
+      allTokensForRefs.set(tokenPath, tokenData);
+    }
+
+    const semanticRequest = buildSemanticVariableRequest(
+      tokensWithParentVariables,
+      existingVariables, // Parent collection variables (inherited)
+      collection.id, // Extended collection ID (for overrides)
+      modes,
+      tempIdMapForOverrides,
+      allTokensForRefs, // Full resolved tokens (core + extended) for reference resolution
+    );
+
+    // For extended collections, only send variableModeValues (overrides), not variable creation
+    // Extended collections inherit variables, so we can't create new ones
+    // Filter out any variableChanges (shouldn't happen, but just in case)
+    if (semanticRequest.variableChanges.length > 0) {
+      console.warn(
+        `   ⚠️  Warning: ${semanticRequest.variableChanges.length} variable creation requests filtered out (extended collections inherit variables)`,
+      );
+    }
+
+    if (semanticRequest.variableModeValues.length > 0) {
+      if (dryRun) {
+        if (verbose) {
+          console.log(
+            `   [DRY RUN] Would update ${semanticRequest.variableModeValues.length} variable mode values`,
+          );
+        }
+      } else {
+        await figmaRequest(config, "/variables", {
+          method: "POST",
+          body: JSON.stringify({
+            variableModeValues: semanticRequest.variableModeValues,
+          }),
+        });
+      }
+    }
+
+    // Also handle component tokens for extended collections (only overrides)
+    if (componentTokensWithParent.size > 0) {
+      // For extended themes, merge core tokens with extended tokens for reference resolution
+      // Extended tokens may reference primitives from core theme
+      const allTokensForRefs = new Map(coreTokens);
+      for (const [tokenPath, tokenData] of resolvedTokens.entries()) {
+        allTokensForRefs.set(tokenPath, tokenData);
+      }
+
+      const componentRequest = buildComponentVariableRequest(
+        componentTokensWithParent,
+        existingVariables, // Parent collection variables
+        collection.id, // Extended collection ID
+        modes,
+        tempIdMapForOverrides,
+        allTokensForRefs, // Full resolved tokens (core + extended) for reference resolution
+      );
+
+      // Only send overrides, not variable creation
+      if (componentRequest.variableChanges.length > 0) {
+        console.warn(
+          `   ⚠️  Warning: ${componentRequest.variableChanges.length} component variable creation requests filtered out (extended collections inherit variables)`,
+        );
+      }
+
+      if (componentRequest.variableModeValues.length > 0) {
+        if (dryRun) {
+          if (verbose) {
+            console.log(
+              `   [DRY RUN] Would update ${componentRequest.variableModeValues.length} component variable mode values`,
+            );
+          }
+        } else {
+          await figmaRequest(config, "/variables", {
+            method: "POST",
+            body: JSON.stringify({
+              variableModeValues: componentRequest.variableModeValues,
+            }),
+          });
+        }
+      }
+
+      const totalErrors =
+        semanticRequest.stats.errors + componentRequest.stats.errors;
+
+      return {
+        created: 0, // Extended collections don't create new variables
+        updated: semanticRequest.stats.updated + componentRequest.stats.updated,
+        skipped: semanticRequest.stats.skipped + componentRequest.stats.skipped,
+        deleted: semanticRequest.stats.deleted + componentRequest.stats.deleted,
+        errors: totalErrors,
+        errorMessages: [
+          ...(semanticRequest.errors || []),
+          ...(componentRequest.errors || []),
+        ],
+      };
+    }
+
+    return {
+      created: 0, // Extended collections don't create new variables
+      updated: semanticRequest.stats.updated,
+      skipped: semanticRequest.stats.skipped,
+      deleted: semanticRequest.stats.deleted,
+      errors: semanticRequest.stats.errors,
+      errorMessages: semanticRequest.errors || [],
+    };
+  } else {
+    // Core collection: create variables and values normally
+    // Filter existing variables to this collection
+    const collectionVariables = existingVariables.filter(
+      (v) => v.variableCollectionId === collection.id,
+    );
+
+    // Build and send primitive variables
+    const tempIdMap = new Map();
+    const primitiveRequest = buildPrimitiveVariableRequest(
+      tokensToSync,
+      collectionVariables,
+      collection.id,
+      modes,
+      tempIdMap,
+    );
+
+    // Declare response in outer scope so it's accessible later
+    let response = null;
+
+    if (
+      primitiveRequest.variableChanges.length > 0 ||
+      primitiveRequest.variableModeValues.length > 0
+    ) {
+      const requestBody = {};
+      if (primitiveRequest.variableChanges.length > 0) {
+        requestBody.variables = primitiveRequest.variableChanges;
+      }
+      if (primitiveRequest.variableModeValues.length > 0) {
+        requestBody.variableModeValues = primitiveRequest.variableModeValues;
+      }
+
+      if (dryRun) {
+        if (verbose) {
+          console.log(
+            `   [DRY RUN] Would ${primitiveRequest.variableChanges.length > 0 ? `create/update/delete ${primitiveRequest.variableChanges.length} variables` : ""}${primitiveRequest.stats.deleted > 0 ? ` (${primitiveRequest.stats.deleted} deleted)` : ""} ${primitiveRequest.variableModeValues.length > 0 ? `update ${primitiveRequest.variableModeValues.length} mode values` : ""}`,
+          );
+        }
+      } else {
+        console.log("   🔄 Syncing primitives...");
+        response = await figmaRequest(config, "/variables", {
+          method: "POST",
+          body: JSON.stringify(requestBody),
+        });
+
+        // Update tempIdMap with real IDs from Figma's response
+        // Figma returns tempIdToRealId mapping for variables that were created
+        if (
+          response.meta?.tempIdToRealId &&
+          primitiveRequest.variableChanges.length > 0
+        ) {
+          const tempIdToRealId = response.meta.tempIdToRealId;
+
+          // Update tempIdMap: replace temp IDs with real IDs for all entries
+          for (const [key, tempId] of tempIdMap.entries()) {
+            if (tempIdToRealId[tempId]) {
+              const realId = tempIdToRealId[tempId];
+              tempIdMap.set(key, realId);
+            }
+          }
+        }
+      }
+    }
+
+    // Reload variables for semantic token references (only if primitives were created/updated)
+    // Optimize: Only reload if we actually created/updated variables
+    let updatedCollectionVariables = collectionVariables;
+    if (primitiveRequest.variableChanges.length > 0 && !dryRun) {
+      const updatedVariablesData = await figmaRequest(
+        config,
+        "/variables/local",
+      );
+      const updatedExistingVariables = updatedVariablesData.meta?.variables
+        ? Object.values(updatedVariablesData.meta.variables)
+        : [];
+      updatedCollectionVariables = updatedExistingVariables.filter(
+        (v) => v.variableCollectionId === collection.id,
+      );
+
+      // Fallback: If tempIdToRealId wasn't in response, update tempIdMap from reloaded variables
+      // Match variables by name to find real IDs for temp IDs
+      if (
+        !response?.meta?.tempIdToRealId ||
+        Object.keys(response?.meta?.tempIdToRealId || {}).length === 0
+      ) {
+        // Create a map of variable names to IDs from reloaded variables
+        const varNameToIdMap = new Map();
+        for (const v of updatedCollectionVariables) {
+          if (v.name) varNameToIdMap.set(v.name, v.id);
+          if (v.key && v.key !== v.name) varNameToIdMap.set(v.key, v.id);
+        }
+
+        // Update tempIdMap: find variables by name and replace temp IDs with real IDs
+        // Also update entries keyed by token path (without prefix) by looking up the variable name
+        for (const [key, tempId] of tempIdMap.entries()) {
+          if (tempId.startsWith("temp_var_")) {
+            let realId = null;
+
+            // Check if key is a variable name (starts with primitive/, semantic/, component/)
+            if (
+              key.includes("/") &&
+              (key.startsWith("primitive/") ||
+                key.startsWith("semantic/") ||
+                key.startsWith("component/"))
+            ) {
+              realId = varNameToIdMap.get(key);
+            } else {
+              // Key might be a token path (without prefix) - try to find it by constructing variable names
+              // Try primitive/ prefix first (for primitive tokens)
+              const primitiveVarName = `primitive/${key}`;
+              realId = varNameToIdMap.get(primitiveVarName);
+              if (!realId) {
+                // Try semantic/ prefix
+                const semanticVarName = `semantic/${key}`;
+                realId = varNameToIdMap.get(semanticVarName);
+              }
+              if (!realId) {
+                // Try component/ prefix
+                const componentVarName = `component/${key}`;
+                realId = varNameToIdMap.get(componentVarName);
+              }
+            }
+
+            if (realId) {
+              tempIdMap.set(key, realId);
+            }
+          }
+        }
+      }
+    }
+
+    // Build and send semantic variables
+    const semanticRequest = buildSemanticVariableRequest(
+      tokensToSync,
+      updatedCollectionVariables,
+      collection.id,
+      modes,
+      tempIdMap,
+      resolvedTokens, // Full resolved tokens for reference resolution
+    );
+
+    let semanticResponse = null;
+    if (
+      semanticRequest.variableChanges.length > 0 ||
+      semanticRequest.variableModeValues.length > 0
+    ) {
+      const requestBody = {};
+      if (semanticRequest.variableChanges.length > 0) {
+        requestBody.variables = semanticRequest.variableChanges;
+      }
+      if (semanticRequest.variableModeValues.length > 0) {
+        requestBody.variableModeValues = semanticRequest.variableModeValues;
+      }
+
+      if (dryRun) {
+        if (verbose) {
+          console.log(
+            `   [DRY RUN] Would ${semanticRequest.variableChanges.length > 0 ? `create/update/delete ${semanticRequest.variableChanges.length} semantic variables` : ""}${semanticRequest.stats.deleted > 0 ? ` (${semanticRequest.stats.deleted} deleted)` : ""} ${semanticRequest.variableModeValues.length > 0 ? `update ${semanticRequest.variableModeValues.length} mode values` : ""}`,
+          );
+        }
+      } else {
+        console.log("   🔄 Syncing semantic tokens...");
+        semanticResponse = await figmaRequest(config, "/variables", {
+          method: "POST",
+          body: JSON.stringify(requestBody),
+        });
+
+        // Update tempIdMap with real IDs from Figma's response for semantic variables
+        if (
+          semanticResponse.meta?.tempIdToRealId &&
+          semanticRequest.variableChanges.length > 0
+        ) {
+          const tempIdToRealId = semanticResponse.meta.tempIdToRealId;
+
+          // Update tempIdMap: replace temp IDs with real IDs for all entries
+          for (const [key, tempId] of tempIdMap.entries()) {
+            if (tempIdToRealId[tempId]) {
+              const realId = tempIdToRealId[tempId];
+              tempIdMap.set(key, realId);
+            }
+          }
+        }
+      }
+    }
+
+    // Reload variables again for component token references (only if semantic variables were created/updated)
+    // Optimize: Only reload if we actually created/updated variables
+    let finalCollectionVariables = updatedCollectionVariables;
+    if (semanticRequest.variableChanges.length > 0 && !dryRun) {
+      console.log("   📥 Reloading variables...");
+      const finalVariablesData = await figmaRequest(config, "/variables/local");
+      const finalExistingVariables = finalVariablesData.meta?.variables
+        ? Object.values(finalVariablesData.meta.variables)
+        : [];
+      finalCollectionVariables = finalExistingVariables.filter(
+        (v) => v.variableCollectionId === collection.id,
+      );
+
+      // Fallback: If tempIdToRealId wasn't in response, update tempIdMap from reloaded variables
+      if (
+        !semanticResponse?.meta?.tempIdToRealId ||
+        Object.keys(semanticResponse.meta.tempIdToRealId).length === 0
+      ) {
+        // Create a map of variable names to IDs from reloaded variables
+        const varNameToIdMap = new Map();
+        for (const v of finalCollectionVariables) {
+          if (v.name) varNameToIdMap.set(v.name, v.id);
+          if (v.key && v.key !== v.name) varNameToIdMap.set(v.key, v.id);
+        }
+
+        // Update tempIdMap: find variables by name and replace temp IDs with real IDs
+        // Also update entries keyed by token path (without prefix) by looking up the variable name
+        for (const [key, tempId] of tempIdMap.entries()) {
+          if (tempId.startsWith("temp_var_")) {
+            let realId = null;
+
+            // Check if key is a variable name (starts with semantic/, component/, primitive/)
+            if (
+              key.includes("/") &&
+              (key.startsWith("semantic/") ||
+                key.startsWith("component/") ||
+                key.startsWith("primitive/"))
+            ) {
+              realId = varNameToIdMap.get(key);
+            } else {
+              // Key might be a token path (without prefix) - try to find it by constructing variable names
+              // Try semantic/ prefix first (most common for component token references)
+              const semanticVarName = `semantic/${key}`;
+              realId = varNameToIdMap.get(semanticVarName);
+              if (!realId) {
+                // Try component/ prefix
+                const componentVarName = `component/${key}`;
+                realId = varNameToIdMap.get(componentVarName);
+              }
+              if (!realId) {
+                // Try primitive/ prefix
+                const primitiveVarName = `primitive/${key}`;
+                realId = varNameToIdMap.get(primitiveVarName);
+              }
+            }
+
+            if (realId) {
+              tempIdMap.set(key, realId);
+            }
+          }
+        }
+      }
+    }
+
+    // Build and send component variables
+    const componentRequest = buildComponentVariableRequest(
+      tokensToSync,
+      finalCollectionVariables,
+      collection.id,
+      modes,
+      tempIdMap,
+      resolvedTokens, // Full resolved tokens for reference resolution
+    );
+
+    if (
+      componentRequest.variableChanges.length > 0 ||
+      componentRequest.variableModeValues.length > 0
+    ) {
+      const requestBody = {};
+      if (componentRequest.variableChanges.length > 0) {
+        requestBody.variables = componentRequest.variableChanges;
+      }
+      if (componentRequest.variableModeValues.length > 0) {
+        requestBody.variableModeValues = componentRequest.variableModeValues;
+      }
+
+      if (dryRun) {
+        if (verbose) {
+          console.log(
+            `   [DRY RUN] Would ${componentRequest.variableChanges.length > 0 ? `create/update/delete ${componentRequest.variableChanges.length} component variables` : ""}${componentRequest.stats.deleted > 0 ? ` (${componentRequest.stats.deleted} deleted)` : ""} ${componentRequest.variableModeValues.length > 0 ? `update ${componentRequest.variableModeValues.length} mode values` : ""}`,
+          );
+        }
+      } else {
+        console.log("   🔄 Syncing component tokens...");
+        await figmaRequest(config, "/variables", {
+          method: "POST",
+          body: JSON.stringify(requestBody),
+        });
+      }
+    }
+
+    const totalErrors =
+      primitiveRequest.stats.errors +
+      semanticRequest.stats.errors +
+      componentRequest.stats.errors;
+
+    return {
+      created:
+        primitiveRequest.stats.created +
+        semanticRequest.stats.created +
+        componentRequest.stats.created,
+      updated:
+        primitiveRequest.stats.updated +
+        semanticRequest.stats.updated +
+        componentRequest.stats.updated,
+      skipped:
+        primitiveRequest.stats.skipped +
+        semanticRequest.stats.skipped +
+        componentRequest.stats.skipped,
+      deleted:
+        primitiveRequest.stats.deleted +
+        semanticRequest.stats.deleted +
+        componentRequest.stats.deleted,
+      errors: totalErrors,
+      errorMessages: [
+        ...(primitiveRequest.errors || []),
+        ...(semanticRequest.errors || []),
+        ...(componentRequest.errors || []),
+      ],
+    };
+  }
+}
+
+module.exports = {
+  syncTheme,
+};