@toghen/figma 0.0.0-stage → 0.1.0

package/main/components/file.ts

@@ -0,0 +1,263 @@
+/**
+ * The one way a component file reaches Figma: its text and its file name.
+ *
+ * The command line sends them, and the Templates pane keeps them in the file and
+ * sends them again; both end here. The plugin reads the KDL, evaluates it with
+ * kdlet once per member, validates, and then snapshots, diffs and applies
+ * (`run.ts`). A problem with the file is a `ComponentRunError` whose reasons are
+ * `<file>:<line>:<column> <message>`, so the person is told where it is, on the
+ * screen or in the terminal.
+ *
+ * The axes a file reads from the tokens (`(modifier)`) and its `tokens=` groups are
+ * answered from the resolver document the plugin has loaded; a file that needs one
+ * with none loaded is refused, naming what it needs (`shared/components/axes.ts`).
+ */
+
+import type { Collection, Part, Resolver } from '@toghen/lib';
+import { readBlueprint, readComponentFile } from '../../shared/components/index.js';
+import type { Blueprint, ComponentFile, Desired, Problem, RunOptions, Step } from '../../shared/components/index.js';
+import type { CompactReport, StepSummary } from '../../shared/components/steps.js';
+import { getState } from '../runtimeState.js';
+import { designSourceOf } from '../utils/designSource.js';
+import { defaultTokenTypeMap } from '../../shared/tokenTypeMap.js';
+import { setUnfolded } from '../utils/folds.js';
+import { figmaCollectionNameFor, resolveSumModes } from '../utils/resolverModes.js';
+import { buildSum, type Sum } from '../utils/sum.js';
+import { ComponentRunError } from './errors.js';
+import { namedComponents, namedTokens } from './resolve.js';
+import { run } from './run.js';
+
+// kdlet reads a record's fields with Object.hasOwn (ES2022), and the plugin sandbox is built for ES2017: make sure it is there.
+const sandbox = Object as { hasOwn?: unknown };
+if (!sandbox.hasOwn) {
+  Object.defineProperty(Object, 'hasOwn', {
+    value: (object: object, key: PropertyKey) => Object.prototype.hasOwnProperty.call(object, key),
+    configurable: true,
+    writable: true,
+  });
+}
+
+/** `<file>:<line>:<column> <message>`, the shape editors and terminals make a link of. */
+export function describe(fileName: string, problem: Problem): string {
+  const place = problem.line !== undefined ? `${fileName}:${problem.line}:${problem.column ?? 1}` : fileName;
+  return `${place} ${problem.severity === 'warning' ? 'warning: ' : ''}${problem.member !== undefined ? `[${problem.member}] ` : ''}${problem.message}`;
+}
+
+/**
+ * Reads a file against the loaded design system, when there is one. An artboard file (an `artboard` node at the top) is
+ * read against `inputs`, the data the command line resolved; a component file takes none.
+ */
+export function readComponentText(
+  text: string,
+  inputs?: Record<string, unknown>,
+  resolver: Resolver | null = getState().resolver,
+): ComponentFile {
+  return readComponentFile(text, resolver ? designSourceOf(resolver) : undefined, inputs);
+}
+
+/** Reads a blueprint as {@link readComponentText} reads a file: each body against the loaded design system and `inputs`. */
+export function readBlueprintText(
+  text: string,
+  inputs?: Record<string, unknown>,
+  resolver: Resolver | null = getState().resolver,
+): Blueprint {
+  return readBlueprint(text, resolver ? designSourceOf(resolver) : undefined, inputs);
+}
+
+/** A file named for one kind that holds the other, which is a mistake the name makes plain. */
+function wrongKind(read: ComponentFile, fileName: string): string | undefined {
+  if (read.artboard && /\.component\.kdl$/.test(fileName)) return `${fileName}: named as a component file, but it holds an artboard`;
+  if (!read.artboard && read.component && /\.artboard\.kdl$/.test(fileName))
+    return `${fileName}: named as an artboard file, but it holds a component`;
+  return undefined;
+}
+
+/** What stops a file from being used: every error, with its place, or why there is no component at all. */
+export function readErrors(read: ComponentFile, fileName: string): string[] {
+  const errors = read.problems.filter((problem) => problem.severity === 'error');
+  const kind = wrongKind(read, fileName);
+  if (kind) return [kind, ...errors.map((problem) => describe(fileName, problem))];
+  if (read.component && read.document && errors.length === 0) return [];
+  return errors.length > 0
+    ? errors.map((problem) => describe(fileName, problem))
+    : [`${fileName}: ${read.artboard ? 'no artboard node' : 'no component node'}`];
+}
+
+/** What the report says of a step: what it did and to what, without the layer it carried. */
+export function summarize(step: Step): StepSummary {
+  const summary: StepSummary = { kind: step.kind };
+  if ('member' in step) summary.member = typeof step.member === 'string' ? step.member : step.member.name;
+  if (step.kind === 'DELETE_MEMBER') summary.member = step.name;
+  if ('layer' in step) summary.address = step.layer.address;
+  if ('address' in step) summary.address = step.address;
+  if ('property' in step) summary.property = step.property.name;
+  if (step.kind === 'DELETE_PROPERTY') summary.property = step.name;
+  if ('changes' in step) summary.changes = step.changes;
+  // A patch names the fields it writes, and the ones whose stamp it only takes again.
+  if (step.kind === 'PATCH_LAYER') summary.changes = [...step.fields, ...(step.restamp ?? []).map((field) => `${field} (restamp)`)];
+  if (step.kind === 'RENAME_AXIS') {
+    summary.from = step.from;
+    summary.to = step.to;
+    summary.message = `axis "${step.from}" is renamed "${step.to}": every member keeps its node, and instances keep their value`;
+  }
+  if (step.kind === 'SWAP_COMPONENT') {
+    summary.from = step.from;
+    summary.to = step.to;
+    const where = step.component === step.member ? `"${step.member}"` : `"${step.component}/${step.member}"`;
+    const from =
+      step.from === ''
+        ? 'a component no longer in the file'
+        : `"${step.from}" ${step.fromLibrary === undefined ? '(this file)' : step.fromLibrary === '' ? '(a library the lock does not name)' : `from library "${step.fromLibrary}"`}`;
+    const to = `"${step.to}" ${step.library === undefined ? '(this file)' : `from library "${step.library}"`}`;
+    summary.message = `"${step.address}" in ${where} swaps from ${from} to ${to}`;
+  }
+  if (step.kind === 'CREATE_SET') summary.members = step.members.length;
+  if ('message' in step) summary.message = step.message;
+  if ('breaks' in step && step.breaks) summary.breaks = step.breaks;
+  return summary;
+}
+
+/** What a file that read asks the engine for: its component, its members, and whether it is an artboard. */
+export function desiredOf(read: ComponentFile): Desired {
+  const { name, description, properties, across } = read.component!;
+  return {
+    component: { name, ...(description !== undefined ? { description } : {}), properties, ...(across !== undefined ? { across } : {}) },
+    members: read.members,
+    ...(read.artboard ? { artboard: true as const } : {}),
+  };
+}
+
+/**
+ * What each file defines and the components it names by name, for the order a run's files go in
+ * (`shared/components/order.ts`). A file that does not read defines and names nothing: the check says why.
+ */
+export function namesOfFiles<T extends { fileName: string; text: string }>(
+  files: readonly T[],
+  inputs: Record<string, unknown> | undefined,
+  resolver: Resolver | null,
+): (T & { defines?: string; names: string[] })[] {
+  return files.map((file) => {
+    const read = readComponentText(file.text, inputs, resolver);
+    if (!read.component || readErrors(read, file.fileName).length > 0) return { ...file, names: [] };
+    return { ...file, ...(read.artboard ? {} : { defines: read.component.name }), names: namedComponents(desiredOf(read)) };
+  });
+}
+
+/** Reads, evaluates and validates one component file, then makes Figma agree with it. */
+export async function runComponentFile(
+  text: string,
+  fileName: string,
+  options: RunOptions = {},
+  inputs?: Record<string, unknown>,
+): Promise<{ component: string; report: CompactReport }> {
+  const read = readComponentText(text, inputs);
+  const errors = readErrors(read, fileName);
+  if (errors.length > 0 || !read.component) {
+    throw new ComponentRunError(
+      `${fileName} does not read: ${errors.length === 1 ? 'one problem' : `${errors.length} problems`}, and nothing was written`,
+      errors,
+    );
+  }
+  const { component } = read;
+  const report = await run(desiredOf(read), options);
+  // What the file warned of, and what inferring bindings from `tokens=` skipped or could not bind.
+  report.notes.push(...(component.notes || []));
+  report.warnings.push(
+    ...read.problems.filter((problem) => problem.severity === 'warning').map((problem) => describe(fileName, problem)),
+    ...(component.warnings || []),
+  );
+  return { component: component.name, report: { ...report, steps: report.steps.map(summarize) } };
+}
+
+/**
+ * Reads every file, and with `names` checks the names each writes against the design system loaded. Returns every
+ * problem of every file: nothing should be written while any file is wrong, since a design half applied is worse than none.
+ * The names are the design system's definition, not Figma's: a variable a sync is about to make is a name that is defined.
+ *
+ * The groups the files lay out as one variable per part (`layout=parts`) are told to the loaded document, so the variable
+ * sync that follows puts those components' variables where the files look for them.
+ */
+export function checkComponentFiles(
+  files: { fileName: string; text: string }[],
+  options: { names: boolean; inputs?: Record<string, unknown> },
+  resolver: Resolver | null = getState().resolver,
+): string[] {
+  return checkComponents(files, options, resolver).errors;
+}
+
+/**
+ * {@link checkComponentFiles}, and the warnings of the files too, each as `<file>:<line>:<column> warning: <message>`. The
+ * plugin's check says the errors; the command with no plugin (`toghen-figma check`) says both. Given the resolver, it reads
+ * nothing from the plugin's state.
+ *
+ * With `names`, a token the parts fold took into its rest's variable (`folds.ts`) is an error that names the rest and the
+ * mode to pin: it has no variable of its own. The sum is built once, after every file's `layout=parts` is known.
+ */
+export function checkComponents(
+  files: { fileName: string; text: string }[],
+  options: { names: boolean; inputs?: Record<string, unknown> },
+  resolver: Resolver | null,
+): { errors: string[]; warnings: string[]; components: string[] } {
+  const problems: string[] = [];
+  const warnings: string[] = [];
+  const unfold: string[] = [];
+  const components: string[] = [];
+  // Every file first: the groups laid out as one variable per part decide which parts fold, and so which names are variables.
+  const reads: { fileName: string; read: ComponentFile }[] = [];
+  for (const { fileName, text } of files) {
+    const read = readComponentText(text, options.inputs, resolver);
+    const errors = readErrors(read, fileName);
+    problems.push(...errors);
+    warnings.push(...read.problems.filter((problem) => problem.severity === 'warning').map((problem) => describe(fileName, problem)));
+    if (read.component?.layout === 'parts' && read.component.tokens !== undefined) unfold.push(read.component.tokens);
+    if (errors.length === 0 && read.component && !read.artboard) components.push(read.component.name);
+    if (errors.length === 0) reads.push({ fileName, read });
+  }
+  if (resolver) setUnfolded(resolver, unfold);
+  if (!options.names || !resolver) return { errors: problems, warnings, components };
+
+  const { ds, dsCollectionName } = resolveSumModes(resolver);
+  const tokens = ds.getCollection(dsCollectionName) as Collection;
+  // The variables the sync makes, as it makes them. A document the sum cannot be built from is the variable sync's to say.
+  let sum: Sum | undefined;
+  try {
+    sum = buildSum(resolver, figmaCollectionNameFor(resolver), defaultTokenTypeMap);
+  } catch {
+    sum = undefined;
+  }
+  // A token the fold took into its rest's variable has none of its own: the part of the axis that folded, if it is one.
+  const foldedPart = (path: string): Part | undefined => {
+    if (!sum || sum.tokenByPath.has(`${sum.dsName}.${path}`)) return undefined;
+    const { parts, component } = tokens.partsOf(path);
+    const axes = sum.layouts.find((layout) => layout.group === component)?.axes ?? [];
+    return parts.find((part) => axes.some((axis) => axis.axis === part.axis && axis.folded));
+  };
+  for (const { fileName, read } of reads) {
+    const named = namedTokens(read.members);
+    for (const [what, names] of [
+      ['token', named.floats],
+      ['token', named.colors],
+      ['token', named.effects],
+      ['token', named.others],
+      ['text style', named.textStyles],
+      ['effect style', named.effectStyles],
+    ] as const) {
+      for (const [path, where] of names) {
+        const place = where.loc ? `${fileName}:${where.loc.line}:${where.loc.column}` : fileName;
+        const via = where.via ? ` (${where.via})` : '';
+        // A token in any mode: the core says what a name is.
+        if (tokens.getNodeKind(path) !== 'token') {
+          problems.push(`${place} ${what} {${path}} is not in the design system "${dsCollectionName}"${via}`);
+          continue;
+        }
+        const part = foldedPart(path);
+        if (part) {
+          problems.push(
+            `${place} ${what} {${path}}${via} is the "${part.key}" part of "${part.twin}", which is one variable with a mode per "${part.axis}": name {${part.twin}}; the member pins the mode (a tokens= axis, or modes ${part.axis}=${part.key})`,
+          );
+        }
+      }
+    }
+  }
+  return { errors: problems, warnings, components };
+}

package/main/components/receipt.ts

@@ -0,0 +1,228 @@
+/**
+ * A layer's receipt: for each field Toghen owns on it, a hash of what Figma reports for it.
+ *
+ * Two readings in one shape. `reportedOf` reads a node: what Figma holds now, which right after a write is the
+ * receipt and on a later run is compared with it (a hand edit shows as a difference). `expectedOf` reads the file:
+ * what Figma would report once the file's value is written, compared with the receipt to tell whether the file moved.
+ * Each field reads as the same plain data from both sides, so the two compare exactly: a bound field as its variable,
+ * a wired field as its property's key, a number as float32, since that is how Figma keeps it.
+ *
+ * Specs, *Identity: what is ours*, says how the two comparisons decide what a run writes.
+ */
+
+import { fieldNames } from '../../shared/components/diff.js';
+import { FIELDS } from '../../shared/components/fields.js';
+import type {
+  ComponentRef,
+  Constraints,
+  FieldValue,
+  GridPlacement,
+  Layer,
+  LayoutGridRecord,
+  SetField,
+  Track,
+  Value,
+} from '../../shared/components/model.js';
+import { BOUND_BY_PARTS, boundIdOf } from '../utils/boundVariables.js';
+import {
+  effectsOf,
+  expectedText,
+  f32,
+  gradientPaint,
+  layoutGridOf,
+  literalBlur,
+  reportedEffect,
+  reportedGrid,
+  reportField,
+  reportedPaint,
+  withAlias,
+} from './fieldWriter.js';
+import type { Resolved } from './resolve.js';
+import { receiptOf, stampOn, updateStamp } from './stamp.js';
+
+/** A layer Toghen wrote in this run, and the fields it wrote: every field it declares when `fields` is absent. */
+export interface Written {
+  node: SceneNode;
+  layer: Layer;
+  fields?: string[];
+}
+
+/** A component as both sides name it: a variant by its set, since a `set` on an artboard's instance picks the variant. */
+const componentId = (component: ComponentNode | null): string | null =>
+  component === null ? null : component.parent?.type === 'COMPONENT_SET' ? component.parent.id : component.id;
+
+const nameOf = (key: string): string => key.split('#')[0];
+
+/** What Figma reports now for each of these fields of a node, by the names `fieldNames` gives them. */
+export async function reportedOf(node: SceneNode, fields: string[]): Promise<Record<string, unknown>> {
+  const read = node as unknown as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  const bound = (node as unknown as { boundVariables?: Record<string, unknown> }).boundVariables ?? {};
+  for (const field of fields) {
+    if (field.startsWith('set ')) {
+      const properties = (node as InstanceNode).componentProperties;
+      const key = Object.keys(properties).find((candidate) => nameOf(candidate) === field.slice(4));
+      // A property bound to a variable is reported on the instance's `boundVariables.componentProperties` (roster, *Instance and component*).
+      const variable = key === undefined ? undefined : (bound.componentProperties as Record<string, VariableAlias> | undefined)?.[key]?.id;
+      out[field] = key === undefined ? null : variable !== undefined ? { variable } : properties[key].value;
+    } else if (FIELDS[field]?.wires !== undefined) {
+      const wired = node.componentPropertyReferences?.[field === 'component' ? 'mainComponent' : (field as 'visible' | 'characters')];
+      const variable = field === 'component' ? undefined : boundIdOf(bound, field);
+      if (field === 'component')
+        out[field] = wired !== undefined ? { property: wired } : componentId(await (node as InstanceNode).getMainComponentAsync());
+      else out[field] = wired !== undefined ? { property: wired, shows: read[field] } : variable !== undefined ? { variable } : read[field];
+    } else if (field === 'modes') {
+      out[field] = node.explicitVariableModes;
+    } else if (field === 'grid') {
+      const cell = node as unknown as GridChildrenMixin;
+      out[field] = {
+        row: cell.gridRowAnchorIndex,
+        column: cell.gridColumnAnchorIndex,
+        rowSpan: cell.gridRowSpan,
+        columnSpan: cell.gridColumnSpan,
+      };
+    } else if (FIELDS[field]?.value === 'tracks') {
+      out[field] = (read[field] as GridTrackSize[]).map((track) => ({
+        type: track.type,
+        value: track.type === 'HUG' ? null : f32(track.value),
+      }));
+    } else {
+      out[field] = reportField(node, field);
+    }
+  }
+  return out;
+}
+
+/** What a wired field reads from the set, by property name: the key the set holds the property under now, and its default, which the field shows. */
+export interface Wiring {
+  keys: Map<string, string>;
+  defaults: Map<string, string | boolean>;
+}
+
+function expectedPaint(resolved: Resolved, paint: Value): unknown {
+  // Unit 4: a gradient reads as the writer would leave it.
+  const composite = paint.kind === 'token' ? resolved.composite(paint.path) : undefined;
+  if (composite?.paint) return reportedPaint(gradientPaint(resolved, composite));
+  // A bound paint by its variable only: its alpha is the variable's, in whatever mode the layer is in (ruling 8a).
+  if (paint.kind === 'token') return { variable: resolved.color(paint.path).id };
+  const hex = String((paint as { value: string }).value);
+  const channel = (at: number): number => parseInt(hex.slice(at, at + 2), 16) / 255;
+  return { color: [channel(1), channel(3), channel(5)].map(f32), opacity: f32(hex.length === 9 ? channel(7) : 1) };
+}
+
+function expectedField(resolved: Resolved, wiring: Wiring, field: string, value: FieldValue): unknown {
+  const scalar = value as Value;
+  if (FIELDS[field]?.token?.bind?.call === 'paint') return (value as Value[]).map((paint) => expectedPaint(resolved, paint));
+  if (FIELDS[field]?.token?.bind?.call === 'text') return expectedText(resolved, field, scalar);
+  // Unit 4: effects and layout grids read as the writer would leave them, each bound part by its variable.
+  if (FIELDS[field]?.value === 'effects') {
+    const effects: Effect[] = [];
+    for (const effect of value as Value[]) {
+      if (effect.kind === 'token') effects.push(...effectsOf(resolved, resolved.composite(effect.path)!, withAlias));
+      else effects.push(literalBlur(Number((effect as { value: number }).value)));
+    }
+    return effects.map(reportedEffect);
+  }
+  if (FIELDS[field]?.value === 'grids')
+    return (value as LayoutGridRecord[]).map((record) => reportedGrid(layoutGridOf(resolved, record, withAlias, () => 0)));
+  if (field === 'textStyle') return resolved.textStyle((value as { path: string }).path).id;
+  if (field === 'effectStyle') return resolved.effectStyle((value as { path: string }).path).id;
+  if (field === 'modes') {
+    const pins: Record<string, string> = {};
+    for (const [collection, mode] of Object.entries(value as Record<string, string>)) {
+      const pin = resolved.mode(collection, mode);
+      pins[pin.collection.id] = pin.modeId;
+    }
+    return pins;
+  }
+  if (field === 'grid') {
+    const cell = value as GridPlacement;
+    return { row: cell.row, column: cell.column, rowSpan: cell.rowSpan ?? 1, columnSpan: cell.columnSpan ?? 1 };
+  }
+  if (FIELDS[field]?.value === 'tracks')
+    return (value as Track[]).map((track) => ({ type: track.type, value: track.type === 'HUG' ? null : f32(track.value) }));
+  // A dash pattern as its lengths, a token's at the defaults; constraints as Figma reports them.
+  if (FIELDS[field]?.value === 'dashes') {
+    const dashes = value as Value[];
+    if (dashes[0]?.kind === 'token') return (resolved.valueOf(dashes[0].path)!.value as number[]).map(f32);
+    return dashes.map((dash) => f32((dash as { value: number }).value));
+  }
+  if (FIELDS[field]?.value === 'constraints') return { ...(value as Constraints) };
+  if (scalar.kind === 'property') {
+    const property = wiring.keys.get(scalar.name) ?? null;
+    const shows = wiring.defaults.get(scalar.name);
+    return field === 'component' ? { property } : { property, shows: field === 'visible' ? Boolean(shows) : String(shows) };
+  }
+  if (field === 'component')
+    return componentId(
+      resolved.component(scalar.kind === 'key' ? { key: scalar.key } : { name: String((scalar as { value: string }).value) }),
+    );
+  if (scalar.kind === 'token')
+    return FIELDS[field]?.token?.bind ? { variable: resolved.variable(scalar.path).id } : f32(resolved.valueOf(scalar.path)?.value);
+  return f32((scalar as { value: unknown }).value);
+}
+
+/** An instance property's value as `componentProperties` reports it: a swap by its component's id. */
+function expectedSet(resolved: Resolved, value: SetField[string]['value']): unknown {
+  if (typeof value === 'object')
+    return 'token' in value ? { variable: resolved.variable(value.token).id } : resolved.component({ key: value.key }).id;
+  if (typeof value !== 'string') return value;
+  // ponytail: a text that is also the name of a component the file swaps in reads as that component, and is written
+  // again on every run; the property's type, which would say, is only known from the instance.
+  try {
+    return resolved.component({ name: value } as ComponentRef).id;
+  } catch (_notAComponent) {
+    return value;
+  }
+}
+
+/**
+ * The receipt the file's value would leave, for each field of a layer. A field whose lookup fails (a name a dry run
+ * only expects) has none, and reads as moved.
+ */
+export function expectedOf(layer: Layer, resolved: Resolved, wiring: Wiring): Record<string, string> {
+  const expected: Record<string, unknown> = {};
+  for (const [field, value] of Object.entries(layer.fields)) {
+    try {
+      if (field === 'set')
+        for (const [name, entry] of Object.entries(value as SetField)) expected[`set ${name}`] = expectedSet(resolved, entry.value);
+      else expected[field] = expectedField(resolved, wiring, field, value);
+    } catch (_unresolved) {
+      // Left out: the field is written.
+    }
+  }
+  // A field bound by its parts (`cornerRadius`, `strokeWeight`) beside a part of its own the file names: the target
+  // reports the field bound only when all four parts end on one variable, else `{ variable: null }` (`boundIdOf`), so
+  // the file's side reads the same; otherwise every run took the file for moved and wrote the field again.
+  for (const [field, parts] of Object.entries(BOUND_BY_PARTS)) {
+    if (!(field in expected) || !parts.some((part) => part in layer.fields)) continue;
+    try {
+      const ids = parts.map((part) => {
+        const value = (layer.fields[part] ?? layer.fields[field]) as Value;
+        return value.kind === 'token' && FIELDS[part]?.token?.bind ? resolved.variable(value.path).id : undefined;
+      });
+      if (ids.some((id) => id !== undefined)) expected[field] = { variable: new Set(ids).size === 1 ? ids[0] : null };
+    } catch (_unresolved) {
+      delete expected[field];
+    }
+  }
+  return receiptOf(expected);
+}
+
+/**
+ * Writes each layer's receipt once the run's writes are done: after a member is in its set, since combining gives its
+ * wired layers the set's keys. A field the run wrote takes the hash of what Figma reports now; one it did not keeps the
+ * hash it had, so a field kept as drift is still drift on the next run. The receipt lists the fields the file declares
+ * now: one it stopped declaring was reported once and leaves it.
+ */
+export async function stampReceipts(written: Written[]): Promise<void> {
+  for (const { node, layer, fields } of written) {
+    if (node.removed) continue;
+    const names = fieldNames(layer);
+    const now = receiptOf(await reportedOf(node, fields ?? names));
+    const held = stampOn(node)?.receipt ?? {};
+    const receipt: Record<string, string> = {};
+    for (const name of names) receipt[name] = now[name] ?? held[name] ?? '';
+    updateStamp(node, { receipt });
+  }
+}