@servicetitan/hammer-token 2.5.1 → 3.0.0

package/src/utils/figma/token-resolution.js

@@ -0,0 +1,569 @@
+#!/usr/bin/env node
+
+/**
+ * Token Resolution Utilities
+ *
+ * Functions for resolving token references and dependencies.
+ */
+
+const { isPrimitiveToken } = require("./token-parsing");
+
+/**
+ * Check if a value is a reference string
+ * A valid reference is a string that contains exactly one reference: "{token.path}"
+ * Strings with multiple references or other content are not considered references
+ * @param {any} value - Value to check
+ * @returns {boolean} True if value is a reference
+ */
+function isReference(value) {
+  if (typeof value !== "string") return false;
+  // Must start with { and end with }
+  if (!value.startsWith("{") || !value.endsWith("}")) return false;
+  // Must contain exactly one reference (no spaces or other content outside the braces)
+  // This excludes strings like "{size.0} {size.0} {size.0}" which have multiple references
+  const trimmed = value.trim();
+  if (trimmed.length < 3) return false; // At least "{x}"
+  // Check that there's only one set of braces and no content outside them
+  const innerContent = trimmed.slice(1, -1);
+  // If there are any braces or spaces in the middle, it's not a single reference
+  if (
+    innerContent.includes("{") ||
+    innerContent.includes("}") ||
+    trimmed !== value
+  ) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Check if a value is a composite color with a reference in the color property
+ * @param {any} value - Value to check
+ * @returns {boolean} True if value is a composite color with reference
+ */
+function isCompositeColorWithReference(value) {
+  return (
+    value &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    value.color &&
+    typeof value.color === "string" &&
+    isReference(value.color) &&
+    (value.alpha !== undefined || value.a !== undefined)
+  );
+}
+
+/**
+ * Extract reference path from reference string
+ * @param {string} refString - Reference string like "{token.path}"
+ * @returns {string|null} Reference path or null if not a valid reference
+ */
+function extractReferencePath(refString) {
+  if (!isReference(refString)) return null;
+  return refString.slice(1, -1); // Remove { and }
+}
+
+/**
+ * Resolve all references in a string that contains multiple space-separated references
+ * Example: "{size.0} {size.0} {size.0}" -> "0rem 0rem 0rem"
+ * @param {string} value - String that may contain multiple references like "{token.path} {other.token}"
+ * @param {Map} resolvedTokens - Map of resolved tokens
+ * @param {boolean} isDark - Whether to use dark mode values
+ * @returns {string} String with all references resolved to their actual values
+ */
+function escapeForRegExp(str) {
+  // Escape all characters that have special meaning in regular expressions
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function resolveMultipleReferences(value, resolvedTokens, isDark = false) {
+  if (typeof value !== "string") return value;
+
+  // Find all references in the string using regex
+  const referencePattern = /\{([^}]+)\}/g;
+  let result = value;
+  const seenReferences = new Map(); // Cache resolved values to avoid duplicate work
+
+  // Process all matches
+  let match;
+  while ((match = referencePattern.exec(value)) !== null) {
+    const fullMatch = match[0]; // e.g., "{size.0}"
+    const refPath = match[1]; // e.g., "size.0"
+
+    // Skip if we've already processed this reference
+    if (seenReferences.has(fullMatch)) {
+      continue;
+    }
+
+    // Resolve the reference path to a token path
+    const resolvedPath = resolveReferencePath(refPath, resolvedTokens);
+    const tokenData = resolvedTokens.get(resolvedPath);
+
+    if (tokenData) {
+      // Get the resolved value (use dark if specified, otherwise light)
+      let resolvedValue = isDark
+        ? tokenData.resolvedDark
+        : tokenData.resolvedLight;
+
+      // If it's a reference string, try to resolve it further (recursive)
+      if (typeof resolvedValue === "string" && isReference(resolvedValue)) {
+        resolvedValue = resolveValue(resolvedValue, resolvedTokens, isDark);
+      }
+
+      // If the resolved value is an object (dimension or other), convert to string
+      if (
+        resolvedValue &&
+        typeof resolvedValue === "object" &&
+        !Array.isArray(resolvedValue)
+      ) {
+        if (resolvedValue.value !== undefined) {
+          // Dimension object: {value: 0, unit: "rem"}
+          resolvedValue = `${resolvedValue.value}${resolvedValue.unit || ""}`;
+        } else {
+          // Other object types - convert to string representation
+          resolvedValue = String(resolvedValue);
+        }
+      }
+
+      // Convert to string if needed and cache it
+      if (resolvedValue !== null && resolvedValue !== undefined) {
+        const stringValue = String(resolvedValue);
+        seenReferences.set(fullMatch, stringValue);
+      }
+    }
+  }
+
+  // Replace all references with their resolved values
+  for (const [reference, resolvedValue] of seenReferences.entries()) {
+    const escapedReference = escapeForRegExp(reference);
+    result = result.replace(new RegExp(escapedReference, "g"), resolvedValue);
+  }
+
+  return result;
+}
+
+// Cache for resolved reference paths to avoid redundant lookups
+// Key: refPath, Value: resolved token path
+const referencePathCache = new Map();
+
+/**
+ * Resolve a reference to a token path
+ * Optimized with caching to avoid redundant path resolution
+ * @param {string} refPath - Reference path (e.g., "color.blue.500")
+ * @param {Map} tokenRegistry - Token registry map
+ * @returns {string} Resolved token path
+ */
+function resolveReferencePath(refPath, tokenRegistry) {
+  // Check cache first (use registry size as cache key to invalidate when registry changes)
+  const cacheKey = `${refPath}:${tokenRegistry.size}`;
+  if (referencePathCache.has(cacheKey)) {
+    const cached = referencePathCache.get(cacheKey);
+    // Verify the cached path still exists in registry
+    if (tokenRegistry.has(cached)) {
+      return cached;
+    }
+    // Cache invalid, remove it
+    referencePathCache.delete(cacheKey);
+  }
+
+  // Convert reference path (e.g., "color.blue.500") to token path
+  // First try exact match by converting dots to slashes
+  const pathWithSlashes = refPath.split(".").join("/");
+
+  if (tokenRegistry.has(pathWithSlashes)) {
+    referencePathCache.set(cacheKey, pathWithSlashes);
+    return pathWithSlashes;
+  }
+
+  // Try with $root appended (for group references)
+  const withRoot = `${pathWithSlashes}/$root`;
+  if (tokenRegistry.has(withRoot)) {
+    referencePathCache.set(cacheKey, withRoot);
+    return withRoot;
+  }
+
+  // Try finding by matching path segments
+  // Optimize: Build a lookup map for segment-based matching if registry is large
+  let resolvedPath = null;
+  if (tokenRegistry.size > 100) {
+    // For large registries, build a segment-based index
+    const segmentIndex = new Map();
+    for (const [tokenPath] of tokenRegistry.entries()) {
+      const segments = tokenPath.split("/");
+      const key = `${segments.length}:${segments.join(":")}`;
+      if (!segmentIndex.has(key)) {
+        segmentIndex.set(key, tokenPath);
+      }
+    }
+
+    const refSegments = refPath.split(".");
+    const searchKey = `${refSegments.length}:${refSegments.join(":")}`;
+    resolvedPath = segmentIndex.get(searchKey) || null;
+  } else {
+    // For small registries, linear search is fine
+    for (const [tokenPath] of tokenRegistry.entries()) {
+      const pathArray = tokenPath.split("/");
+      const refSegments = refPath.split(".");
+
+      if (pathArray.length === refSegments.length) {
+        let matches = true;
+        for (let i = 0; i < refSegments.length; i++) {
+          if (pathArray[i] !== refSegments[i]) {
+            matches = false;
+            break;
+          }
+        }
+        if (matches) {
+          resolvedPath = tokenPath;
+          break;
+        }
+      }
+    }
+  }
+
+  // Use resolved path or fallback
+  const result = resolvedPath || pathWithSlashes;
+  referencePathCache.set(cacheKey, result);
+  return result;
+}
+
+/**
+ * Clear the reference path cache (useful for testing or when token registry changes significantly)
+ */
+function clearReferencePathCache() {
+  referencePathCache.clear();
+}
+
+/**
+ * Resolve token references recursively
+ * @param {any} value - Value that may be a reference
+ * @param {Map} tokenRegistry - Token registry map
+ * @param {boolean} isDark - Whether to use dark mode
+ * @param {Set} visited - Set of visited paths to prevent cycles
+ * @returns {any} Resolved value
+ */
+function resolveValue(
+  value,
+  tokenRegistry,
+  isDark = false,
+  visited = new Set(),
+) {
+  if (!isReference(value)) {
+    return value;
+  }
+
+  const refPath = extractReferencePath(value);
+  const resolvedPath = resolveReferencePath(refPath, tokenRegistry);
+
+  // Prevent infinite loops
+  if (visited.has(resolvedPath)) {
+    return value;
+  }
+  visited.add(resolvedPath);
+
+  const refTokenData = tokenRegistry.get(resolvedPath);
+  if (!refTokenData) {
+    return value; // Can't resolve, return original
+  }
+
+  const { token } = refTokenData;
+  let refValue = token.$value;
+
+  // Handle appearance variants
+  if (isDark && token.$extensions?.appearance?.dark?.$value !== undefined) {
+    refValue = token.$extensions.appearance.dark.$value;
+  } else if (
+    !isDark &&
+    token.$extensions?.appearance?.light?.$value !== undefined
+  ) {
+    refValue = token.$extensions.appearance.light.$value;
+  }
+
+  // If the referenced value is also a reference, resolve it
+  if (isReference(refValue)) {
+    return resolveValue(refValue, tokenRegistry, isDark, visited);
+  }
+
+  return refValue;
+}
+
+/**
+ * Resolve token references to actual values
+ * @param {Map} tokenRegistry - Token registry map
+ * @returns {Map} Map of resolved tokens
+ */
+function resolvePrimitiveReferences(tokenRegistry) {
+  const resolved = new Map();
+
+  for (const [tokenPath, tokenData] of tokenRegistry.entries()) {
+    const { token, sourceFilePath } = tokenData;
+
+    // Get light value
+    let lightValue = token.$value;
+    if (token.$extensions?.appearance?.light?.$value !== undefined) {
+      lightValue = token.$extensions.appearance.light.$value;
+    }
+
+    // Get dark value
+    let darkValue = token.$extensions?.appearance?.dark?.$value;
+    if (darkValue === undefined) {
+      darkValue = lightValue; // Fallback to light value
+    }
+
+    // Determine if this is a primitive token dynamically based on source file path
+    const isPrimitive = isPrimitiveToken(sourceFilePath);
+
+    // Only resolve references for primitive tokens, keep references for semantic/component tokens
+    if (isPrimitive && isReference(lightValue)) {
+      lightValue = resolveValue(lightValue, tokenRegistry, false);
+    }
+
+    if (isPrimitive && isReference(darkValue)) {
+      darkValue = resolveValue(darkValue, tokenRegistry, true);
+    }
+
+    resolved.set(tokenPath, {
+      ...tokenData,
+      resolvedLight: lightValue,
+      resolvedDark: darkValue,
+      isPrimitive,
+    });
+  }
+
+  return resolved;
+}
+
+/**
+ * Topologically sort semantic tokens based on their dependencies
+ * Returns tokens in dependency order (dependencies first)
+ * @param {Array} semanticTokens - Array of [tokenPath, tokenData] tuples
+ * @param {Map} resolvedTokens - Map of resolved tokens
+ * @returns {Array} Sorted array of [tokenPath, tokenData] tuples
+ */
+function topologicalSortSemanticTokens(semanticTokens, resolvedTokens) {
+  // Build dependency graph
+  const dependencies = new Map(); // tokenPath -> Set of tokenPaths it depends on
+  const dependents = new Map(); // tokenPath -> Set of tokenPaths that depend on it
+
+  for (const [tokenPath, tokenData] of semanticTokens) {
+    dependencies.set(tokenPath, new Set());
+    dependents.set(tokenPath, new Set());
+
+    const { resolvedLight, resolvedDark } = tokenData;
+
+    // Check light value dependencies
+    if (isReference(resolvedLight)) {
+      const refPath = extractReferencePath(resolvedLight);
+      const targetPath = resolveReferencePath(refPath, resolvedTokens);
+      // Only track dependencies on other semantic tokens (not primitives)
+      if (
+        resolvedTokens.has(targetPath) &&
+        !resolvedTokens.get(targetPath).isPrimitive
+      ) {
+        dependencies.get(tokenPath).add(targetPath);
+        if (!dependents.has(targetPath)) {
+          dependents.set(targetPath, new Set());
+        }
+        dependents.get(targetPath).add(tokenPath);
+      }
+    }
+
+    // Check dark value dependencies
+    if (isReference(resolvedDark)) {
+      const refPath = extractReferencePath(resolvedDark);
+      const targetPath = resolveReferencePath(refPath, resolvedTokens);
+      // Only track dependencies on other semantic tokens (not primitives)
+      if (
+        resolvedTokens.has(targetPath) &&
+        !resolvedTokens.get(targetPath).isPrimitive
+      ) {
+        dependencies.get(tokenPath).add(targetPath);
+        if (!dependents.has(targetPath)) {
+          dependents.set(targetPath, new Set());
+        }
+        dependents.get(targetPath).add(tokenPath);
+      }
+    }
+  }
+
+  // Topological sort using Kahn's algorithm
+  const sorted = [];
+  const queue = [];
+  const inDegree = new Map();
+
+  // Initialize in-degree count
+  for (const [tokenPath] of semanticTokens) {
+    inDegree.set(tokenPath, dependencies.get(tokenPath).size);
+    if (inDegree.get(tokenPath) === 0) {
+      queue.push(tokenPath);
+    }
+  }
+
+  // Process nodes with no dependencies
+  while (queue.length > 0) {
+    const tokenPath = queue.shift();
+    sorted.push(tokenPath);
+
+    // Reduce in-degree for dependents
+    for (const dependent of dependents.get(tokenPath) || []) {
+      inDegree.set(dependent, inDegree.get(dependent) - 1);
+      if (inDegree.get(dependent) === 0) {
+        queue.push(dependent);
+      }
+    }
+  }
+
+  // If we couldn't sort all tokens, there might be a cycle
+  // In that case, return the original order for the unsorted ones
+  if (sorted.length < semanticTokens.length) {
+    const sortedSet = new Set(sorted);
+    for (const [tokenPath] of semanticTokens) {
+      if (!sortedSet.has(tokenPath)) {
+        sorted.push(tokenPath);
+      }
+    }
+  }
+
+  // Return tokens in sorted order
+  const tokenMap = new Map(semanticTokens);
+  return sorted.map((tokenPath) => [tokenPath, tokenMap.get(tokenPath)]);
+}
+
+/**
+ * Formats an alpha value (0–1) as a percentage string, e.g. 0.08 → "8%".
+ * @param {number} alpha
+ * @returns {string}
+ */
+function formatAlpha(alpha) {
+  return `${Math.round((alpha ?? 1) * 100)}%`;
+}
+
+/**
+ * Builds a reference chain string by following token references through the registry
+ * until reaching a terminal (non-reference) value.
+ * Composite colors (with alpha) are rendered as "chain (N% opacity)".
+ * Example: "{semantic.color.primary}" → "semantic/color/primary → color/blue/500 → #0066cc"
+ * Example: "{shadow.color.default}" → "shadow/color/default → color/neutral/900 → #1a1a1a (8% opacity)"
+ * @param {string} refValue - Reference string like "{token.path}"
+ * @param {Map} tokenRegistry - Map of resolved tokens
+ * @param {Set<string>} [visited] - Visited paths to prevent cycles
+ * @returns {string|null} Chain string or null if path cannot be resolved
+ */
+function buildReferenceChain(refValue, tokenRegistry, visited = new Set()) {
+  const refPath = extractReferencePath(refValue);
+  if (!refPath) return null;
+
+  const varPath = refPath.replace(/\./g, "/");
+  if (visited.has(varPath)) return varPath;
+  visited.add(varPath);
+
+  const tokenData = tokenRegistry?.get(varPath);
+  if (!tokenData) return varPath;
+
+  const nextValue = tokenData.token?.$value;
+
+  // Follow plain reference chain
+  if (nextValue && isReference(nextValue)) {
+    const rest = buildReferenceChain(nextValue, tokenRegistry, visited);
+    return rest ? `${varPath} → ${rest}` : varPath;
+  }
+
+  // Terminal is a composite color with a reference — show ref at opacity → hex at opacity
+  if (nextValue && isCompositeColorWithReference(nextValue)) {
+    const refPath = extractReferencePath(nextValue.color);
+    const colorPath = refPath ? refPath.replace(/\./g, "/") : null;
+    const opacity = formatAlpha(nextValue.alpha ?? nextValue.a);
+    const baseHex = colorPath && tokenRegistry?.get(colorPath)?.resolvedLight;
+    const hexStr =
+      baseHex && typeof baseHex === "string" ? baseHex.toUpperCase() : null;
+    const tail = hexStr
+      ? `${colorPath} at ${opacity} opacity → ${hexStr} at ${opacity} opacity`
+      : colorPath
+        ? `${colorPath} at ${opacity} opacity`
+        : null;
+    return tail ? `${varPath} → ${tail}` : varPath;
+  }
+
+  // Terminal node: append the final resolved value (string or dimension object)
+  const finalValue = tokenData.resolvedLight;
+  if (finalValue && typeof finalValue === "string") {
+    return `${varPath} → ${finalValue}`;
+  }
+  if (
+    finalValue &&
+    typeof finalValue === "object" &&
+    finalValue.value !== undefined &&
+    finalValue.unit !== undefined
+  ) {
+    const { value: dimVal, unit } = finalValue;
+    const formatted =
+      unit === "rem" && dimVal !== 0
+        ? `${dimVal}rem (${dimVal * 16}px)`
+        : `${dimVal}${unit}`;
+    return `${varPath} → ${formatted}`;
+  }
+
+  return varPath;
+}
+
+/**
+ * Returns a default description for a token derived from its reference value.
+ * Follows the full reference chain to the terminal value (e.g. hex for colors).
+ * Used when a token has no explicit $description.
+ * @param {Object} token - The token object
+ * @param {Map} [tokenRegistry] - Map of resolved tokens for chain following
+ * @returns {string} Default description or empty string
+ */
+function getDefaultDescription(token, tokenRegistry) {
+  const value = token.$value;
+  if (!value) return "";
+
+  if (isReference(value)) {
+    return buildReferenceChain(value, tokenRegistry) || "";
+  }
+
+  if (isCompositeColorWithReference(value)) {
+    const refPath = extractReferencePath(value.color);
+    const colorPath = refPath ? refPath.replace(/\./g, "/") : null;
+    const opacity = formatAlpha(value.alpha ?? value.a);
+    const baseHex = colorPath && tokenRegistry?.get(colorPath)?.resolvedLight;
+    const hexStr =
+      baseHex && typeof baseHex === "string" ? baseHex.toUpperCase() : null;
+    if (!colorPath) return "";
+    return hexStr
+      ? `${colorPath} at ${opacity} opacity → ${hexStr} at ${opacity} opacity`
+      : `${colorPath} at ${opacity} opacity`;
+  }
+
+  return "";
+}
+
+/**
+ * Returns the token's description with the reference chain always appended.
+ * If the token has an explicit $description, the chain is appended on a new line.
+ * If there is no $description, only the chain is returned.
+ * @param {Object} token - The token object
+ * @param {Map} [tokenRegistry] - Map of resolved tokens for chain following
+ * @returns {string} Description string
+ */
+function getTokenDescription(token, tokenRegistry) {
+  const description = token.$description || "";
+  const chain = getDefaultDescription(token, tokenRegistry);
+  if (description && chain) return `${description}\n${chain}`;
+  return description || chain;
+}
+
+module.exports = {
+  isReference,
+  isCompositeColorWithReference,
+  extractReferencePath,
+  resolveMultipleReferences,
+  resolveReferencePath,
+  resolveValue,
+  resolvePrimitiveReferences,
+  topologicalSortSemanticTokens,
+  clearReferencePathCache,
+  buildReferenceChain,
+  getDefaultDescription,
+  getTokenDescription,
+};