@toghen/figma 0.0.0-stage → 0.1.1

package/shared/components/members.ts

@@ -0,0 +1,280 @@
+/**
+ * A component file's document to members.
+ *
+ * A component set is the variant matrix built out: one member per combination of
+ * axis values, minus the combinations `exclude` names. Each combination is one
+ * evaluation of the file's document by kdlet, with the axis values as its inputs;
+ * the tree that comes back is that member's. This file is the Figma vocabulary
+ * kdlet is given, the matrix, and the step from kdlet's tree to the model's layers.
+ *
+ * It runs in the plugin, so it holds no Figma API, no Node API and nothing from
+ * `@toghen/lib`: the checks that need the library's reference grammar are
+ * `check.ts`'s, and are kept apart for that reason.
+ */
+
+import { literalText, referenceTarget } from '@toghen/lib';
+import { defineVocabulary, evaluate } from 'kdlet';
+import type { Document, Json, OutNode, Structure } from 'kdlet';
+import { expandSegments, pinsOf, selectionOf } from './axes.js';
+import type { Expanded } from './axes.js';
+import { applyBindings } from './bindings.js';
+import { FIELDS, LAYER_KINDS, STRUCTURED_FIELDS } from './fields.js';
+import type { Component, FieldValue, Layer, LayerKind, LayoutGridRecord, Member, Modes, Problem, SetField, Track, Value } from './model.js';
+
+/** The tags a value may carry, on top of kdlet's own `input`. */
+export const TAGS = ['literal', 'property', 'key'] as const;
+
+/** The word that fills an instance's slot in an artboard file: `slot Content { … }`. It is no layer, and a component file refuses it. */
+export const SLOT_WORD = 'slot';
+
+/**
+ * What kdlet is told about Figma: the layer kinds, the fields written as child
+ * nodes, the layer's name as its address, and the three tags. Every field
+ * replaces, except `set` (an artboard instance's property values), where a `when` adds
+ * to what the line before it set. `slot` is an element so that its body may hold a
+ * `when` or an `each`; only an artboard file may use it, and `check.ts` refuses it in any other.
+ */
+export const vocabulary = defineVocabulary({
+  elements: [...LAYER_KINDS, SLOT_WORD],
+  childFields: STRUCTURED_FIELDS,
+  adds: ['set'],
+  address: (node) => (typeof node.args[0] === 'string' ? node.args[0] : undefined),
+  tags: TAGS,
+});
+
+/** `Axis=value, Axis=value`, as the set's members are named. */
+export function memberName(combination: Record<string, string>): string {
+  return Object.entries(combination)
+    .map(([axis, value]) => `${axis}=${value}`)
+    .join(', ');
+}
+
+/**
+ * Every combination the set holds, in declared axis order, the last axis varying fastest.
+ *
+ * When the file writes `include`, only the combinations one of its lines matches are
+ * candidates; `exclude` then removes from those. A line names one value for each axis it
+ * mentions, and an axis it does not mention matches any value.
+ */
+export function combinations(component: Component): Record<string, string>[] {
+  let all: Record<string, string>[] = [{}];
+  for (const property of component.properties) {
+    if (property.type !== 'VARIANT') continue;
+    const next: Record<string, string>[] = [];
+    for (const partial of all) {
+      for (const value of property.values) next.push({ ...partial, [property.name]: value });
+    }
+    all = next;
+  }
+  const matches = (line: { combination: Record<string, string> }, combination: Record<string, string>): boolean =>
+    Object.entries(line.combination).every(([axis, value]) => combination[axis] === value);
+  return all.filter(
+    (combination) =>
+      (component.include === undefined || component.include.some((line) => matches(line, combination))) &&
+      !component.exclude.some((exclusion) => matches(exclusion, combination)),
+  );
+}
+
+/** One combination, evaluated: kdlet's tree for it, and what kdlet found wrong. */
+export interface Evaluated {
+  /** The member's name: its combination, or the component's name when there are no axes. */
+  name: string;
+  combination: Record<string, string>;
+  roots: OutNode[];
+  problems: Problem[];
+}
+
+/**
+ * Evaluates the document once per combination, the axis values being its inputs. A reference that takes a path
+ * segment from an axis (`{hue.(input)hue.soft}`) is expanded for the member, so that everything after sees an
+ * ordinary one; kdlet leaves a string as it is written, and the segment is Toghen's.
+ */
+export function evaluateMembers(component: Component, document: Document): Evaluated[] {
+  return combinations(component).map((combination) => {
+    const { tree, problems } = evaluate(document, { vocabulary, inputs: combination });
+    const expanded = expandSegments(tree, combination);
+    return {
+      name: Object.keys(combination).length > 0 ? memberName(combination) : component.name,
+      combination,
+      roots: expanded.roots,
+      problems: [
+        ...problems.map((problem) => ({
+          severity: 'error' as const,
+          message: problem.message,
+          line: problem.line,
+          column: problem.column,
+        })),
+        ...expanded.problems,
+      ],
+    };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// From kdlet's tree to layers
+// ---------------------------------------------------------------------------
+
+/** A value carrying a host tag, as kdlet keeps it. */
+export const tagged = (json: Json | undefined): { tag: string; value: Json } | undefined =>
+  json !== null && typeof json === 'object' && !Array.isArray(json) && 'tag' in json && 'value' in json && typeof json.tag === 'string'
+    ? { tag: json.tag, value: json.value }
+    : undefined;
+
+/** A token reference's path: `"{space.md}"` is `space.md` (lib's `referenceTarget`). The grammar was checked where the file was read. */
+const pathOf = (text: string): string => referenceTarget(text)!;
+
+function toValue(json: Json, field: string): Value {
+  const tag = tagged(json);
+  if (tag) {
+    if (tag.tag === 'literal') return { kind: 'literal', value: tag.value as number | string };
+    if (tag.tag === 'property') return { kind: 'property', name: tag.value as string };
+    return { kind: 'key', key: tag.value as string };
+  }
+  const spec = FIELDS[field];
+  const text =
+    spec.value === 'dimension' ||
+    spec.value === 'size' ||
+    spec.value === 'token' ||
+    spec.value === 'group' ||
+    spec.value === 'paints' ||
+    spec.value === 'dashes' ||
+    spec.value === 'effects' ||
+    spec.value === 'grids';
+  if (text && typeof json === 'string') return { kind: 'token', path: pathOf(json) };
+  // `visible` and `characters` take a token reference too; any other text is plain.
+  if (spec.token && typeof json === 'string' && referenceTarget(json) !== undefined) return { kind: 'token', path: pathOf(json) };
+  // A doubled brace is a literal one, as in a token's value: `"{{size.sm}}"` is the text `{size.sm}`. Both targets read it from here.
+  return { kind: 'plain', value: typeof json === 'string' ? literalText(json) : (json as number | boolean | null) };
+}
+
+function toTrack(track: Structure): Track {
+  if (track.name === 'HUG') return { type: 'HUG' };
+  const [value] = track.args;
+  // A bare FLEX reads as 1.
+  return { type: track.name as 'FLEX' | 'FIXED', value: value === undefined ? 1 : (value as number) };
+}
+
+/** A layout grid's node, `COLUMNS alignment=STRETCH count=12 gutterSize="{space.md}"`, as a record: each property a value. */
+function toLayoutGrid(grid: Structure, field: string): LayoutGridRecord {
+  const record: LayoutGridRecord = { pattern: grid.name as LayoutGridRecord['pattern'] };
+  for (const [key, raw] of Object.entries(grid.props)) {
+    if (key === 'alignment') record.alignment = raw as LayoutGridRecord['alignment'];
+    else record[key as 'count'] = toValue(raw, field);
+  }
+  return record;
+}
+
+function toFieldValue(field: string, json: Json): FieldValue {
+  switch (FIELDS[field].value) {
+    case 'paints':
+    case 'effects':
+      return (json as Json[]).map((paint) => toValue(paint, field));
+    case 'grids':
+      return (json as Structure).children.map((grid) => toLayoutGrid(grid, field));
+    case 'tracks':
+      return (json as Structure).children.map(toTrack);
+    case 'placement': {
+      const { props } = json as Structure;
+      const place: { row: number; column: number; rowSpan?: number; columnSpan?: number } = {
+        row: props.row as number,
+        column: props.column as number,
+      };
+      if (props.rowSpan !== undefined) place.rowSpan = props.rowSpan as number;
+      if (props.columnSpan !== undefined) place.columnSpan = props.columnSpan as number;
+      return place;
+    }
+    case 'modes':
+      return { ...((json as Structure).props as Modes) };
+    // A dash pattern is a list, as paints are: one token, or lengths; none is a solid stroke.
+    case 'dashes':
+      return Array.isArray(json) ? json.map((dash) => toValue(dash, field)) : [];
+    case 'constraints': {
+      const { props } = json as Structure;
+      return { horizontal: props.horizontal as string, vertical: props.vertical as string };
+    }
+    case 'set': {
+      // Every `set` line adds to the ones before it; a later write of one name replaces the earlier.
+      const set: SetField = {};
+      for (const line of json as Structure[]) {
+        for (const [name, raw] of Object.entries(line.props)) {
+          const tag = tagged(raw);
+          // A token reference binds its variable to the property.
+          const token = !tag && typeof raw === 'string' && referenceTarget(raw) !== undefined ? { token: pathOf(raw) } : undefined;
+          set[name] = { value: tag ? { key: tag.value as string } : (token ?? (raw as string | boolean)), loc: line.propLocs[name] };
+        }
+      }
+      return set;
+    }
+    default:
+      return toValue(json, field);
+  }
+}
+
+/** A validated node of kdlet's tree as a layer. Its positions come with it: a problem found later still names the line. */
+export function toLayer(node: OutNode): Layer {
+  const fields: Record<string, FieldValue> = {};
+  for (const [field, json] of Object.entries(node.fields)) fields[field] = toFieldValue(field, json);
+  const layer: Layer = {
+    kind: node.name as LayerKind,
+    address: String(node.args[0]),
+    fields,
+    children: node.children.map(toLayer),
+    loc: node.loc,
+    fieldLoc: { ...node.fieldLocs },
+  };
+  const fromAxes = (node as Expanded).fromAxes;
+  if (fromAxes) layer.fromAxes = fromAxes;
+  return layer;
+}
+
+/**
+ * A validated node of an artboard file's tree as a layer.
+ *
+ * A layer inside an `each` has the keys of the `each`es around it after its name, so that the rows of one
+ * template have addresses of their own: `Row["a"]`, or `Cell["a",2]` inside two. An `INSTANCE`'s `slot`
+ * nodes are flattened: the layers inside one become children of the instance, each marked with its slot.
+ */
+export function toArtboardLayer(node: OutNode, slot?: string): Layer {
+  const fields: Record<string, FieldValue> = {};
+  for (const [field, json] of Object.entries(node.fields)) fields[field] = toFieldValue(field, json);
+  const name = String(node.args[0]);
+  const layer: Layer = {
+    kind: node.name as LayerKind,
+    address: node.identity.keys.length > 0 ? `${name}${JSON.stringify(node.identity.keys)}` : name,
+    fields,
+    children: [],
+    loc: node.loc,
+    fieldLoc: { ...node.fieldLocs },
+  };
+  if (layer.address !== name) layer.name = name;
+  if (slot !== undefined) layer.slot = slot;
+  for (const child of node.children) {
+    if (child.name === SLOT_WORD) {
+      (layer.slots ??= []).push({ name: String(child.args[0]), loc: child.loc });
+      for (const inner of child.children) layer.children.push(toArtboardLayer(inner, String(child.args[0])));
+    } else {
+      layer.children.push(toArtboardLayer(child));
+    }
+  }
+  return layer;
+}
+
+/**
+ * A validated evaluation as a member.
+ *
+ * An axis that takes its values from a modifier pins that modifier's collection on the
+ * member's root to the member's value, with no line in the file: `modes state=hover`. The
+ * file may not write a pin of its own for the same collection (`checkPins`), so two writers
+ * of one pin never disagree here.
+ *
+ * `tokens=` on a layer (and on the component line, for the root) becomes the fields the
+ * group's keys imply, here and not earlier: only the evaluated layer knows which fields a
+ * `when` has already written, and those win. `seen` is told what each layer got.
+ */
+export function toMember(evaluated: Evaluated, component?: Component, seen?: Parameters<typeof applyBindings>[2]): Member {
+  const tree = toLayer(evaluated.roots[0]);
+  if (component) applyBindings(tree, component, seen, selectionOf(component, evaluated.combination));
+  const pins = component ? pinsOf(component, evaluated.combination) : {};
+  if (Object.keys(pins).length > 0) tree.fields.modes = { ...((tree.fields.modes as Modes | undefined) ?? {}), ...pins };
+  return { name: evaluated.name, combination: evaluated.combination, tree };
+}

package/shared/components/model.ts

@@ -0,0 +1,273 @@
+/**
+ * The model a component file reads into.
+ *
+ * The file is a kdlet file: kdlet reads it and evaluates it, and this is what a
+ * member's tree becomes once it is Figma's. Everything downstream (the diff, the
+ * steps, the engine) works on these types and never on KDL, and every type is
+ * plain JSON. The file format
+ * itself is owned by `reference.md`, *Component files*.
+ *
+ * Positions are kept beside the data they describe (`loc`, `fieldLoc`) rather
+ * than in a side table, so a problem found in a member after a `when` wrote the
+ * offending field still points at the line of that `when`.
+ */
+
+/** A position in the file, one-based, as an editor shows it. */
+export interface Loc {
+  line: number;
+  column: number;
+}
+
+export interface Problem {
+  severity: 'error' | 'warning';
+  /** In the file's own words: names the layer, field or property it is about. */
+  message: string;
+  line?: number;
+  column?: number;
+  /** The member the problem was found in, for problems that only exist after expansion. */
+  member?: string;
+}
+
+/**
+ * What a field holds. `plain` is an enum, a boolean, a string, or `null` (`#null`,
+ * which clears a size and is distinct from a field that was never written).
+ */
+export type Value =
+  /** `"{space.md}"`: the path without braces. */
+  | { kind: 'token'; path: string }
+  /** `(literal)8`, `(literal)"#ffffff00"`: a value that says it is on purpose. On a wirable field (`characters=(literal)"Ready"`) it takes the field off its property. */
+  | { kind: 'literal'; value: number | string | boolean }
+  /** `(property)"Show Nav"`: wired to a component property. */
+  | { kind: 'property'; name: string }
+  /** `(key)"…"`: a published component key. Accepted only where a component is named. */
+  | { kind: 'key'; key: string }
+  | { kind: 'plain'; value: string | number | boolean | null };
+
+export interface Track {
+  type: 'FLEX' | 'FIXED' | 'HUG';
+  /** Present for `FLEX` (a bare `FLEX` reads as 1) and `FIXED`. */
+  value?: number;
+}
+
+export interface GridPlacement {
+  row: number;
+  column: number;
+  rowSpan?: number;
+  columnSpan?: number;
+}
+
+/** `modes Scale=small`: collection name to mode name. */
+export type Modes = Record<string, string>;
+
+/**
+ * `set Name=value …` on an instance: the values of the instance's properties, by the display
+ * name the component declares. A text or a variant value is a string, a boolean is a boolean, and an
+ * instance swap is a component's name or `(key)"…"`. A token reference (`"{copy.title}"`) is `{ token }`, its path: a
+ * `string` or `boolean` token whose variable is bound to a `TEXT` or `BOOLEAN` property. `loc` is the line the value was
+ * written at.
+ */
+export type SetField = Record<string, { value: string | boolean | { key: string } | { token: string }; loc?: Loc }>;
+
+/**
+ * One layout grid of `layoutGrids` (unit 4): `COLUMNS` and `ROWS` with an alignment, or a square `GRID`. Each field holds
+ * a token, a `(literal)` (a dimension, or a colour as `#rrggbbaa`) or, for `count`, a plain whole number; a field the
+ * grid's alignment does not take is refused when the file is read (`GRID_FIELDS`).
+ */
+export interface LayoutGridRecord {
+  pattern: 'COLUMNS' | 'ROWS' | 'GRID';
+  alignment?: 'MIN' | 'MAX' | 'STRETCH' | 'CENTER';
+  count?: Value;
+  gutterSize?: Value;
+  offset?: Value;
+  sectionSize?: Value;
+  color?: Value;
+}
+
+/** `constraints horizontal=MIN vertical=STRETCH`: Figma's `Constraints`, both axes given. */
+export interface Constraints {
+  horizontal: string;
+  vertical: string;
+}
+
+/** Which shape a field's value has follows from the field's name: see `fields.ts`. `dashPattern` is a `Value[]`, as `fills` is. */
+export type FieldValue = Value | Value[] | Track[] | GridPlacement | Modes | SetField | Constraints | LayoutGridRecord[];
+
+export type LayerKind = 'FRAME' | 'SLOT' | 'TEXT' | 'INSTANCE' | 'LINE';
+
+export interface Layer {
+  kind: LayerKind;
+  /**
+   * The layer's name, and the key rules and stamps find it by. For a `SLOT`, the slot property's name.
+   * In an artboard file the keys of the `each`es around a layer follow its name (`Row["a"]`), so a repeated
+   * layer has an address of its own; `name` is then what Figma shows.
+   */
+  address: string;
+  /** In an artboard file, the layer's name as written, when the address carries keys after it. */
+  name?: string;
+  /** In an artboard file, the slot of the enclosing `INSTANCE` this layer fills; it is one of that instance's `children`. */
+  slot?: string;
+  /** In an artboard file, the slots an `INSTANCE` fills, even those it fills with nothing. */
+  slots?: { name: string; loc?: Loc }[];
+  fields: Record<string, FieldValue>;
+  children: Layer[];
+  loc?: Loc;
+  /** Where each field was last written: on the layer's own line or body, or in the `when` that wrote it. */
+  fieldLoc?: Record<string, Loc>;
+  /** The axes a field's reference took a path segment from (`{hue.(input)hue.soft}`), by field: so a message can name the value that made it. Absent when none did. */
+  fromAxes?: Record<string, string[]>;
+}
+
+/**
+ * A component offered first by an `INSTANCE_SWAP` or a `SLOT`: by its published key, or by its name, which the locator
+ * answers as it answers an instance swap's default (the file, or a declared library). `loc` is the `preferred` line.
+ */
+export type PreferredValue =
+  | { type: 'COMPONENT' | 'COMPONENT_SET'; key: string }
+  | { type: 'COMPONENT' | 'COMPONENT_SET'; name: string; loc?: Loc };
+
+/** Either a component named in the file's document, or a published key. */
+export type ComponentRef = { name: string } | { key: string };
+
+export interface SlotSettings {
+  minChildren?: number;
+  maxChildren?: number;
+  allowPreferredValuesOnly?: boolean;
+  stretchChildOnInsert?: boolean;
+  displayEmptyByDefault?: boolean;
+}
+
+export type Property =
+  /**
+   * `modifier` is set for an axis that takes its values from a modifier of the design
+   * system (`VARIANT State (modifier)"state"`), or that was inferred from the tokens:
+   * `values` are then the modifier's contexts, default first, and each member pins the
+   * modifier's collection to its value (`modes state=hover`) on its root layer. `leftOut` are the
+   * contexts of that modifier Figma does not get (its `figma.include`): not values, and said so when a file names one.
+   *
+   * `part` is set for an axis that `tokens=` took from the parts vocabulary: `values` are `rest` and the part keys.
+   * A folded one also has `modifier`, the collection named after the axis; one left in the path pins nothing, and
+   * its value selects the part group the member's layers bind.
+   *
+   * `from` is set for an axis that takes its values from a token group (`VARIANT hue from="{hue}"`): the group's
+   * path without braces. `values` are then the names of its children, in the document's order.
+   */
+  (
+    | { type: 'VARIANT'; name: string; values: string[]; modifier?: string; leftOut?: string[]; from?: string; part?: true }
+    /** A default that is a token reference (`default="{flag.on}"`) is `{ token }`, its path: the token's variable is bound to it. */
+    | { type: 'BOOLEAN'; name: string; default: boolean | { token: string } }
+    | { type: 'TEXT'; name: string; default: string | { token: string } }
+    | { type: 'INSTANCE_SWAP'; name: string; default: ComponentRef; preferredValues?: PreferredValue[] }
+    | {
+        type: 'SLOT';
+        name: string;
+        description?: string;
+        preferredValues?: PreferredValue[];
+        slotSettings?: SlotSettings;
+      }
+  ) & { loc?: Loc };
+
+/**
+ * A combination that is never built (`exclude`), or the only ones that are built
+ * (`include`): one value for each axis it names, an axis it does not name matching any value.
+ */
+export interface Exclusion {
+  combination: Record<string, string>;
+  loc?: Loc;
+}
+
+/**
+ * What a component file says apart from its layers: the set's name, description and
+ * properties, and the combinations never built. The layers are the file's
+ * document, which `members.ts` evaluates once per combination.
+ */
+export interface Component {
+  name: string;
+  description?: string;
+  properties: Property[];
+  exclude: Exclusion[];
+  /**
+   * When present, only the combinations one of these matches are built, and `exclude`
+   * then removes from those. Absent when the file writes none: every combination is a candidate.
+   */
+  include?: Exclusion[];
+  /**
+   * The token group the component names (`tokens="{button}"`), without the braces. Every
+   * axis of the parts vocabulary the group's subgroups use is an axis, after the declared ones.
+   */
+  tokens?: string;
+  /** `parts` (`layout=parts` on the component line): every axis of the component stays in the path, one variable per part. */
+  layout?: 'parts';
+  /**
+   * The axes that go across on the set's board (`across="a, b"` on the component line), by name; the others go down.
+   * Absent, the board balances itself (`memberBoard`).
+   */
+  across?: string[];
+  /** Where `across=` was written, for the refusal that names an axis the component does not have. */
+  acrossLoc?: Loc;
+  /**
+   * What each token group the component's layers name with `tokens=` (and the group the component
+   * line names) binds, by the group's path. Filled in by the reader from the design system, so the
+   * engine, which asks no design system, infers the same bindings from it. A member that selects part groups
+   * (`variant=primary`) has its own plan, stored under `planKey(group, selection)`.
+   */
+  groups?: Record<string, GroupPlan>;
+  /**
+   * What the reader found while inferring bindings, for the run's report: keys with no field on the
+   * layer that names them (notes), and what could not be bound (warnings). Said once per key and layer.
+   */
+  notes?: string[];
+  warnings?: string[];
+}
+
+/**
+ * What a group binds, worked out from its keys by the reader (`groups.ts`) so that the engine only
+ * has to lay it over the evaluated layers (`bindings.ts`). Plain JSON, and small: it travels in the script.
+ */
+export interface GroupPlan {
+  /** For a `TEXT`. */
+  TEXT: Laid;
+  /** For a `FRAME` or `SLOT`, whatever its layout. */
+  box: Laid;
+  /**
+   * Laid over `box` by the layer's `layoutMode` (a layer with none is `NONE`), present only where the group has
+   * a gap: it is `itemSpacing` in a flow, the two grid gaps in a grid, and nothing otherwise.
+   */
+  NONE?: Laid;
+  HORIZONTAL?: Laid;
+  VERTICAL?: Laid;
+  GRID?: Laid;
+}
+
+/** What one kind of layer gets from a group. */
+export interface Laid {
+  /** Figma field to the path of the token it binds to. */
+  set: Record<string, string>;
+  /** Keys with no field here, said in the run's notes, one line each. */
+  notes?: string[];
+  /** What the group could not bind here, said as warnings: a composite border's literal members. */
+  warnings?: string[];
+}
+
+/** The tokens one level down in a group, as the design system gives them: what a `GroupPlan` is worked out from. */
+export interface GroupInfo {
+  /** The keys of the tokens directly in the group (`backgroundColor`), in the document's order. */
+  keys: string[];
+  /** For a key whose token is in a part group the selection chose, the token's path; every other key is `<group>.<key>`. */
+  paths?: Record<string, string>;
+  /**
+   * For a key whose token is a composite `border`: the tokens its `color` and `width` members
+   * refer to, as paths. A member that is not here is a literal. `unsolid` is set when its style
+   * is anything but `solid`, which the reader refuses.
+   */
+  borders?: Record<string, { color?: string; width?: string; unsolid?: true }>;
+  /** The keys, among those the table asks the type of (`background`), whose token is a colour in every context. */
+  colors?: string[];
+}
+
+/** One component of the set: a combination of variant values and the tree it builds. */
+export interface Member {
+  /** `Axis=value, Axis=value` in declared axis order; the component's name when there are no axes. */
+  name: string;
+  combination: Record<string, string>;
+  tree: Layer;
+}

package/shared/components/order.ts

@@ -0,0 +1,53 @@
+/**
+ * The order a run's files go in: each file after every file that defines a component it names.
+ *
+ * A file that names a component a later file defines would find nothing, since that set is not built yet. So files
+ * are sorted by what they define and name; ties keep the order they were typed in, so only a file with a dependency
+ * moves. A name a declared library defines resolves there, and is no dependency on a file. A cycle is refused, naming
+ * its files. An artboard defines nothing, so it never comes before a component file it could follow.
+ */
+
+export interface FileNames {
+  fileName: string;
+  /** The component the file defines; none for an artboard, or a file that does not read. */
+  defines?: string;
+  /** The components it names by name. */
+  names: readonly string[];
+}
+
+/** `files` in the order to run them. Throws when they name each other in a cycle, with the files of the cycle in order. */
+export function orderFiles<T extends FileNames>(files: readonly T[], fromLibraries: ReadonlySet<string> = new Set()): T[] {
+  const definer = new Map<string, number>();
+  files.forEach((file, i) => {
+    if (file.defines !== undefined && !definer.has(file.defines)) definer.set(file.defines, i);
+  });
+  const after = files.map((file, i) => {
+    const on = new Set<number>();
+    for (const name of file.names) {
+      const at = definer.get(name);
+      if (at !== undefined && at !== i && !fromLibraries.has(name)) on.add(at);
+    }
+    return [...on];
+  });
+
+  const done = new Set<number>();
+  const ordered: T[] = [];
+  while (ordered.length < files.length) {
+    // The first file typed whose every dependency has run: what keeps the typed order among ties.
+    const next = files.findIndex((_, i) => !done.has(i) && after[i].every((at) => done.has(at)));
+    if (next === -1) {
+      // Every file left waits on another left: follow the waits from one until a file comes round again.
+      const path: number[] = [];
+      let at = files.findIndex((_, i) => !done.has(i));
+      while (!path.includes(at)) {
+        path.push(at);
+        at = after[at].find((dependency) => !done.has(dependency))!;
+      }
+      const cycle = [...path.slice(path.indexOf(at)), at].map((i) => files[i].fileName);
+      throw new Error(`the component files name each other in a cycle, so none of them can be built first: ${cycle.join(' → ')}`);
+    }
+    done.add(next);
+    ordered.push(files[next]);
+  }
+  return ordered;
+}