@toghen/figma 0.0.0-stage → 0.1.0

package/main/engines/batchRunner.ts

@@ -0,0 +1,200 @@
+import type { Operation, OperationResult, OperationSummary } from '../../shared/operations.js';
+import { executeOperation, labelForOperation } from './operationExecutor.js';
+import { SymbolicIdRegistry } from '../utils/symbolicIdRegistry.js';
+import type { SimpleAbortSignal } from '../utils/abortController.js';
+import { dependenciesOf } from '../utils/planSymbols.js';
+import { isAlias } from '../utils/figmaTokenAdapter.js';
+
+export interface BatchRunOptions {
+  onProgress: (completed: number, total: number, label: string) => void;
+  signal?: SimpleAbortSignal;
+}
+
+function resolveOperationIds(op: Operation, registry: SymbolicIdRegistry): Operation {
+  switch (op.kind) {
+    case 'ADD_MODE':
+      return { ...op, collectionId: registry.resolve(op.collectionId) };
+    case 'DELETE_MODE':
+    case 'DELETE_VARIABLE':
+      return op;
+    case 'CREATE_VARIABLE':
+      return { ...op, collectionId: registry.resolve(op.collectionId) };
+    case 'SET_VARIABLE_VALUE':
+      return {
+        ...op,
+        variableId: registry.resolve(op.variableId),
+        modeId: registry.resolve(op.modeId),
+        // An alias may point at a variable this same plan creates.
+        value: isAlias(op.value) ? { ...op.value, id: registry.resolve(op.value.id) } : op.value,
+      };
+    case 'BIND_VARIABLE':
+      return { ...op, variableId: registry.resolve(op.variableId) };
+    case 'RENAME_VARIABLE':
+    case 'SET_CODE_SYNTAX':
+    case 'SET_VARIABLE_SCOPES':
+      return { ...op, variableId: registry.resolve(op.variableId) };
+    case 'UNBIND_VARIABLE':
+    case 'APPLY_TOKEN':
+    case 'STAMP':
+    case 'CREATE_COLLECTION':
+    case 'CREATE_STYLE':
+    case 'UPDATE_STYLE':
+    case 'SKIP':
+    case 'WARNING':
+    case 'BREAKING':
+    case 'NOTE':
+    case 'SWAP_COMPONENT':
+      return op;
+    default: {
+      const _exhaustive: never = op;
+      return _exhaustive;
+    }
+  }
+}
+
+async function registerSymbolicOutputs(originalOp: Operation, figmaId: string | undefined, registry: SymbolicIdRegistry): Promise<void> {
+  if (!figmaId) return;
+
+  if (originalOp.kind === 'CREATE_COLLECTION' && originalOp.symbolicId) {
+    registry.register(originalOp.symbolicId, figmaId);
+
+    const collection = await figma.variables.getVariableCollectionByIdAsync(figmaId);
+    if (collection) {
+      for (const mode of collection.modes) {
+        registry.register(`$mode:${originalOp.name}/${mode.name}`, mode.modeId);
+      }
+    }
+    return;
+  }
+
+  if (originalOp.kind === 'ADD_MODE') {
+    const collection = await figma.variables.getVariableCollectionByIdAsync(figmaId);
+    const mode = collection?.modes.find((m) => m.name === originalOp.modeName);
+    if (collection && mode) {
+      registry.register(`$mode:${collection.name}/${originalOp.modeName}`, mode.modeId);
+    }
+    return;
+  }
+
+  if (originalOp.kind === 'CREATE_VARIABLE' && originalOp.symbolicId) {
+    registry.register(originalOp.symbolicId, figmaId);
+  }
+}
+
+export async function runOperations(ops: Operation[], options: BatchRunOptions): Promise<OperationSummary> {
+  const results: OperationResult[] = [];
+  const startTime = Date.now();
+  const registry = new SymbolicIdRegistry();
+
+  /** The plan's rows that are not skips: carried into the results, and counted by the plan, not as skipped here. */
+  const isCounted = (op: Operation) => op.kind === 'WARNING' || op.kind === 'BREAKING' || op.kind === 'NOTE';
+  const isRow = (op: Operation) => op.kind === 'SKIP' || isCounted(op);
+  const executable = ops.filter((op) => !isRow(op));
+  const skipped = ops.filter(isRow);
+
+  skipped.forEach((op) => {
+    results.push({
+      operation: op,
+      status: 'skipped',
+      reason: op.kind === 'SKIP' ? op.reason : op.message,
+    });
+  });
+
+  // Symbols whose producing operation failed. Everything downstream of one is
+  // reported as a skipped prerequisite rather than as its own failure — a
+  // CREATE_COLLECTION that hits the mode cap used to cascade into hundreds of
+  // identical "Unresolved symbolic ID" errors that said nothing about the cause.
+  const failedSymbols = new Set<string>();
+
+  for (let i = 0; i < executable.length; i += 1) {
+    const operation = executable[i];
+
+    if (options.signal?.aborted) {
+      results.push({
+        operation,
+        status: 'skipped',
+        reason: 'cancelled',
+      });
+      continue;
+    }
+
+    const blockedBy = blockingSymbol(operation, failedSymbols);
+    if (blockedBy) {
+      results.push({
+        operation,
+        status: 'skipped',
+        reason: `prerequisite failed: ${blockedBy}`,
+      });
+      recordFailedSymbol(operation, failedSymbols);
+      continue;
+    }
+
+    let resolvedOperation: Operation;
+    try {
+      resolvedOperation = resolveOperationIds(operation, registry);
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      results.push({
+        operation,
+        status: 'failed',
+        reason,
+      });
+      recordFailedSymbol(operation, failedSymbols);
+      continue;
+    }
+
+    options.onProgress(i + 1, executable.length, labelForOperation(resolvedOperation));
+
+    const opStart = Date.now();
+    try {
+      const figmaId = await executeOperation(resolvedOperation);
+      results.push({
+        operation: resolvedOperation,
+        status: 'applied',
+        figmaId,
+        durationMs: Date.now() - opStart,
+      });
+
+      await registerSymbolicOutputs(operation, figmaId, registry);
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      results.push({
+        operation: resolvedOperation,
+        status: 'failed',
+        reason,
+        durationMs: Date.now() - opStart,
+      });
+      recordFailedSymbol(operation, failedSymbols);
+    }
+  }
+
+  return {
+    total: ops.length,
+    applied: results.filter((r) => r.status === 'applied').length,
+    // A skip, a prerequisite that failed, a cancellation: a warning, a note or a breaking row was counted by the plan under its own name (R14).
+    skipped: results.filter((r) => r.status === 'skipped' && !isCounted(r.operation)).length,
+    failed: results.filter((r) => r.status === 'failed').length,
+    cancelled: results.filter((r) => r.status === 'skipped' && r.reason === 'cancelled').length,
+    durationMs: Date.now() - startTime,
+    results,
+  };
+}
+
+/** The symbolic id an operation produces, if any. */
+function producedSymbol(op: Operation): string | undefined {
+  if (op.kind === 'CREATE_COLLECTION' || op.kind === 'CREATE_VARIABLE') {
+    return op.symbolicId;
+  }
+  return undefined;
+}
+
+/** Records that an operation's output symbol will never resolve. */
+function recordFailedSymbol(op: Operation, failedSymbols: Set<string>): void {
+  const symbol = producedSymbol(op);
+  if (symbol) failedSymbols.add(symbol);
+}
+
+/** The failed symbol an operation depends on, if any. */
+function blockingSymbol(op: Operation, failedSymbols: Set<string>): string | undefined {
+  return dependenciesOf(op).find((dependency) => failedSymbols.has(dependency));
+}

package/main/engines/ioAdapter.ts

@@ -0,0 +1,132 @@
+import type { DesignSystem } from '@toghen/lib';
+import type { Stamp } from '../components/stamp.js';
+import { flattenDesignSystem } from '../utils/flattenDesignSystem.js';
+import { referencePath } from '@toghen/lib';
+
+/** Namespace this plugin owns inside a token's `$extensions`. */
+const NAMESPACE = 'com.toghen.figma';
+
+/** Namespace for facts about the document rather than about one token. */
+const DOCUMENT_NAMESPACE = 'com.toghen';
+
+export interface ExportOptions {
+  includeExtensions: boolean;
+  /** Mode to export. Omitted for a document with a single mode. */
+  mode?: string;
+  /**
+   * The version the design system declares for itself, if it declares one.
+   *
+   * Carried through so the export says which revision it came from. Without it
+   * the provenance stopped at the resolver document: the token file named the
+   * mode in its filename and nothing at all about the system.
+   */
+  documentVersion?: string;
+}
+
+/**
+ * Writes the design system out as DTCG JSON. `stamps` are what the variables and styles of this file carry, by the
+ * token each names: written out under the token's `$extensions` for reading only, since a target's ids and
+ * receipts belong to one file and loading a document never reads them back.
+ */
+export function exportToJSON(ds: DesignSystem, stamps: ReadonlyMap<string, Stamp>, options: ExportOptions): string {
+  const output: Record<string, unknown> = {};
+
+  /*
+   * Provenance first, so it reads at the top of the file.
+   *
+   * §6.3.2: "Groups MAY include an optional `$extensions` property where tools
+   * MAY add proprietary, user-, team- or vendor-specific data." A token file's
+   * root is a group — §6.1 identifies a group as any object without `$value` —
+   * so this is where a fact about the whole document belongs.
+   *
+   * It cannot collide with a token: §5.1 requires that token and group names
+   * MUST NOT begin with `$`.
+   *
+   * Gated on the same switch as per-token extensions. The control says
+   * "Include $extensions", and writing vendor data into a file where the user
+   * asked for none would contradict it.
+   */
+  if (options.includeExtensions && options.documentVersion) {
+    output.$extensions = {
+      [DOCUMENT_NAMESPACE]: { version: options.documentVersion },
+    };
+  }
+
+  for (const { path, token } of flattenDesignSystem(ds, options.mode)) {
+    const tokenObj: Record<string, unknown> = {
+      $value: token.$value,
+      $type: token.$type,
+    };
+
+    if (token.$description) {
+      tokenObj.$description = token.$description;
+    }
+
+    if (options.includeExtensions) {
+      const stamp = stamps.get(path);
+      const existingExtensions = token.$extensions ?? {};
+
+      if (Object.keys(existingExtensions).length > 0 || stamp) {
+        // Merged *into* whatever the token already carries under our namespace,
+        // not over it. Replacing the object wholesale dropped any key another
+        // build had written there.
+        const existingOurs = existingExtensions[NAMESPACE];
+        tokenObj.$extensions = {
+          ...existingExtensions,
+          ...(stamp
+            ? {
+                [NAMESPACE]: {
+                  ...(isPlainObject(existingOurs) ? existingOurs : {}),
+                  stamp,
+                },
+              }
+            : {}),
+        };
+      }
+    }
+
+    // The collection is where the tokens live, not a group of them: without it the
+    // file is a DTCG document again, and loads back as one.
+    setNestedPath(output, referencePath(path), tokenObj);
+  }
+
+  return JSON.stringify(output, null, 2);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Writes `value` at a dotted path, refusing to overwrite anything on the way.
+ *
+ * A backstop, not the enforcement: `Collection.setToken()` rejects a node that
+ * is both a token and a group, so a `DesignSystem` cannot legally hold this
+ * shape. It stays because the old code responded to a collision by replacing
+ * whatever it found with an empty object — the token already written at the
+ * shorter path vanished from the export without a word, and the export is what
+ * a user reloads next session.
+ */
+function setNestedPath(obj: Record<string, unknown>, path: string, value: unknown): void {
+  const parts = path.split('.');
+  let current: Record<string, unknown> = obj;
+
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    const key = parts[i];
+    const next = current[key];
+
+    if (next === undefined) {
+      current[key] = {};
+    } else if (!isPlainObject(next) || '$value' in next) {
+      throw new Error(`Cannot export "${path}": "${parts.slice(0, i + 1).join('.')}" is already a token, so it cannot also be a group.`);
+    }
+
+    current = current[key] as Record<string, unknown>;
+  }
+
+  const leaf = parts[parts.length - 1];
+  if (current[leaf] !== undefined) {
+    throw new Error(`Cannot export "${path}": it is both a token and a group.`);
+  }
+  current[leaf] = value;
+}