@terrazzo/parser 0.4.0 → 0.6.0

package/src/parse/alias.ts

@@ -1,233 +1,369 @@
-import type { AnyNode, ArrayNode, ObjectNode, StringNode } from '@humanwhocodes/momoa';
-import { type TokenNormalized, isAlias, parseAlias } from '@terrazzo/token-tools';
+import type { AnyNode, ArrayNode, ObjectNode } from '@humanwhocodes/momoa';
+import {
+  type BorderTokenNormalized,
+  type GradientTokenNormalized,
+  type ShadowTokenNormalized,
+  type StrokeStyleTokenNormalized,
+  type TokenNormalized,
+  type TokenNormalizedSet,
+  type TransitionTokenNormalized,
+  type TypographyTokenNormalized,
+  isAlias,
+  parseAlias,
+} from '@terrazzo/token-tools';
 import type Logger from '../logger.js';
+import { getObjMembers } from './json.js';
 
-/** Throw error if resolved alias for composite properties doesn’t match expected $type. */
-export const COMPOSITE_TYPE_VALUES = {
-  border: {
-    color: ['color'],
-    width: ['dimension'],
-    strokeStyle: ['strokeStyle'],
-  },
-  gradient: {
-    color: ['color'],
-    position: ['number'],
-  },
-  shadow: {
-    color: ['color'],
-    position: ['dimension'],
-  },
-  strokeStyle: {
-    dashArray: ['dimension'],
-  },
-  transition: {
-    duration: ['duration'],
-    delay: ['duration'],
-    timingFunction: ['cubicBezier'],
-  },
-  typography: {
-    fontFamily: ['fontFamily'],
-    fontSize: ['dimension'],
-    fontWeight: ['fontWeight'],
-    letterSpacing: ['dimension'],
-    lineHeight: ['dimension', 'number'],
-  },
+export interface ApplyAliasOptions {
+  tokensSet: TokenNormalizedSet;
+  filename: URL;
+  src: string;
+  node: ObjectNode;
+  logger: Logger;
+}
+
+export type PreAliased<T extends TokenNormalized> = {
+  $value: T['$value'] | string;
+  mode: Record<string, T['mode'][string] & { $value: T['$value'] | string }>;
 };
 
-/** Resolve alias */
-export function resolveAlias(
+/**
+ * Resolve aliases and update the token nodes.
+ *
+ * Data structures are in an awkward in-between phase, where they have
+ * placeholders for data but we still need to resolve everything. As such,
+ * TypeScript will raise errors expecting the final shape.
+ *
+ * This is also a bit tricky because different token types alias slightly
+ * differently. For example, color tokens and other “primitive” tokens behave
+ * as-expected. But composite tokens like Typography, Gradient, Border, etc. can
+ * either fully- or partially-alias their values. Then we add modes to the mix,
+ * and we have to do the work all over again for each mode declared.
+ *
+ * All that to say, there are a generous amount of TypeScript overrides here rather
+ * than try to codify indeterminate shapes.
+ */
+export default function applyAliases(token: TokenNormalized, options: ApplyAliasOptions): void {
+  // prepopulate default mode (if not set)
+  token.mode['.'] ??= {} as any;
+  token.mode['.'].$value = token.$value;
+  token.mode['.'].originalValue ??= token.originalValue.$value;
+  token.mode['.'].source ??= token.source;
+
+  // resolve root
+  if (typeof token.$value === 'string' && isAlias(token.$value)) {
+    const { aliasChain, resolvedToken } = resolveAlias(token.$value, { ...options, token });
+    token.aliasOf = resolvedToken.id;
+    token.aliasChain = aliasChain;
+    (token as any).$value = resolvedToken.$value;
+  }
+
+  // resolve modes
+  for (const mode of Object.keys(token.mode)) {
+    const modeValue = token.mode[mode]!.$value;
+
+    // if the entire mode value is a simple alias, resolve & continue
+    if (typeof modeValue === 'string' && isAlias(modeValue)) {
+      const expectedType = [token.$type];
+      const { aliasChain, resolvedToken } = resolveAlias(modeValue, {
+        ...options,
+        token,
+        expectedType,
+        node: token.mode[mode]!.source?.node || options.node,
+      });
+      token.mode[mode]!.aliasOf = resolvedToken.id;
+      token.mode[mode]!.aliasChain = aliasChain;
+      (token.mode[mode] as any).$value = resolvedToken.$value;
+      continue;
+    }
+
+    // object types: expand default $value into current mode
+    if (
+      typeof token.$value === 'object' &&
+      typeof token.mode[mode]!.$value === 'object' &&
+      !Array.isArray(token.$value)
+    ) {
+      for (const [k, v] of Object.entries(token.$value)) {
+        if (!(k in token.mode[mode]!.$value)) {
+          (token.mode[mode]!.$value as any)[k] = v;
+        }
+      }
+    }
+
+    // if the mode is an object or array that’s partially aliased, do work per-token type
+    const node = (getObjMembers(options.node).$value as any) || options.node;
+    switch (token.$type) {
+      case 'border': {
+        applyBorderPartialAlias(token, mode, { ...options, node });
+        break;
+      }
+      case 'gradient': {
+        applyGradientPartialAlias(token, mode, { ...options, node });
+        break;
+      }
+      case 'shadow': {
+        applyShadowPartialAlias(token, mode, { ...options, node });
+        break;
+      }
+      case 'strokeStyle': {
+        applyStrokeStylePartialAlias(token, mode, { ...options, node });
+        break;
+      }
+      case 'transition': {
+        applyTransitionPartialAlias(token, mode, { ...options, node });
+        break;
+      }
+      case 'typography': {
+        applyTypographyPartialAlias(token, mode, { ...options, node });
+        break;
+      }
+    }
+  }
+}
+
+const LIST_FORMAT = new Intl.ListFormat('en-us', { type: 'disjunction' });
+
+/**
+ * Resolve alias. Also add info on root node if it’s the root token (has .id)
+ */
+function resolveAlias(alias: string, options: { token: TokenNormalized; expectedType?: string[] } & ApplyAliasOptions) {
+  const baseMessage = {
+    group: 'parser' as const,
+    label: 'alias',
+    node: options?.node,
+    filename: options.filename,
+    src: options.src,
+  };
+  const { logger, token, tokensSet } = options;
+  const shallowAliasID = parseAlias(alias);
+  const { token: resolvedToken, chain } = _resolveAliasInner(shallowAliasID, options);
+
+  // Apply missing $types while resolving
+  if (!tokensSet[token.id]!.$type) {
+    tokensSet[token.id]!.$type = resolvedToken!.$type;
+  }
+
+  // throw error if expectedType differed
+  const expectedType = [...(options.expectedType ?? [])];
+  if (token.$type && !expectedType?.length) {
+    expectedType.push(token.$type);
+  }
+  if (expectedType?.length && !expectedType.includes(resolvedToken!.$type)) {
+    logger.error({
+      ...baseMessage,
+      message: `Invalid alias: expected $type: ${LIST_FORMAT.format(expectedType!)}, received $type: ${resolvedToken!.$type}.`,
+      node: (options.node?.type === 'Object' && getObjMembers(options.node).$value) || baseMessage.node,
+    });
+  }
+
+  // Apply reverse aliases as we’re traversing the graph
+  if (chain?.length && resolvedToken) {
+    let needsSort = false;
+    for (const id of chain) {
+      if (id !== resolvedToken.id && !resolvedToken.aliasedBy?.includes(id)) {
+        resolvedToken.aliasedBy ??= [];
+        resolvedToken.aliasedBy!.push(id);
+        needsSort = true;
+      }
+      if (token && !resolvedToken.aliasedBy?.includes(token.id)) {
+        resolvedToken.aliasedBy ??= [];
+        resolvedToken.aliasedBy!.push(token.id);
+        needsSort = true;
+      }
+    }
+    if (needsSort) {
+      resolvedToken.aliasedBy!.sort((a, b) => a.localeCompare(b, 'en-us', { numeric: true }));
+    }
+  }
+  return { resolvedToken: resolvedToken!, aliasChain: chain };
+}
+
+function _resolveAliasInner(
   alias: string,
   {
-    tokens,
-    logger,
-    filename,
-    src,
-    node,
     scanned = [],
+    ...options
   }: {
-    tokens: Record<string, TokenNormalized>;
+    tokensSet: Record<string, TokenNormalized>;
     logger: Logger;
     filename?: URL;
     src: string;
     node: AnyNode;
     scanned?: string[];
   },
-) {
-  const { id } = parseAlias(alias);
-  if (!tokens[id]) {
-    logger.error({ message: `Alias "${alias}" not found.`, filename, src, node });
+): { token: TokenNormalized; chain: string[] } {
+  const { logger, filename, src, node, tokensSet } = options;
+  const baseMessage = { group: 'parser' as const, label: 'alias', filename, src, node };
+  const id = parseAlias(alias);
+  if (!tokensSet[id]) {
+    logger.error({ ...baseMessage, message: `Alias {${alias}} not found.` });
   }
   if (scanned.includes(id)) {
-    logger.error({ message: `Circular alias detected from "${alias}".`, filename, src, node });
+    logger.error({ ...baseMessage, message: `Circular alias detected from ${alias}.` });
   }
-  const token = tokens[id]!;
-  if (!isAlias(token.$value)) {
-    return id;
+
+  const token = tokensSet[id]!;
+  scanned.push(id);
+
+  // important: use originalValue to trace the full alias path correctly
+  // finish resolution
+  if (typeof token.originalValue.$value !== 'string' || !isAlias(token.originalValue.$value)) {
+    return { token, chain: scanned };
   }
-  return resolveAlias(token.$value as string, { tokens, logger, filename, node, src, scanned: [...scanned, id] });
+
+  // continue resolving
+  return _resolveAliasInner(token.originalValue.$value as string, { ...options, scanned });
 }
 
-/** Resolve aliases, update values, and mutate `token` to add `aliasOf` / `partialAliasOf` */
-export function applyAliases(
-  token: TokenNormalized,
-  {
-    tokens,
-    logger,
-    filename,
-    src,
-    node,
-  }: { tokens: Record<string, TokenNormalized>; logger: Logger; filename?: URL; src: string; node: AnyNode },
-) {
-  const $valueNode =
-    (node.type === 'Object' && node.members.find((m) => (m.name as StringNode).value === '$value')?.value) || node;
-  const expectedAliasTypes =
-    token.$type in COMPOSITE_TYPE_VALUES && COMPOSITE_TYPE_VALUES[token.$type as keyof typeof COMPOSITE_TYPE_VALUES];
-
-  // handle simple aliases
-  if (isAlias(token.$value)) {
-    const aliasOfID = resolveAlias(token.$value as string, { tokens, logger, filename, node, src });
-    const { mode: aliasMode } = parseAlias(token.$value as string);
-    const aliasOf = tokens[aliasOfID]!;
-    token.aliasOf = aliasOfID;
-    token.$value = aliasOf!.mode[aliasMode!]?.$value || aliasOf.$value;
-    if (token.$type && token.$type !== aliasOf.$type) {
-      logger.error({
-        message: `Invalid alias: expected $type: "${token.$type}", received $type: "${aliasOf.$type}".`,
-        node: $valueNode,
-        filename,
-        src,
+function applyBorderPartialAlias(token: BorderTokenNormalized, mode: string, options: ApplyAliasOptions): void {
+  for (const [k, v] of Object.entries(token.mode[mode]!.$value)) {
+    if (typeof v === 'string' && isAlias(v)) {
+      token.mode[mode]!.partialAliasOf ??= {};
+      const node = (getObjMembers(options.node)[k] as any) || options.node;
+      const { resolvedToken } = resolveAlias(v, {
+        ...options,
+        token,
+        expectedType: { color: ['color'], width: ['dimension'], style: ['strokeStyle'] }[k],
+        node,
       });
+      (token.mode[mode]!.partialAliasOf as any)[k] = parseAlias(v);
+      if (mode === '.') {
+        token.partialAliasOf ??= {};
+        (token.partialAliasOf as any)[k] = parseAlias(v);
+      }
+      (token.mode[mode]!.$value as any)[k] = resolvedToken.$value;
     }
-    token.$type = aliasOf.$type;
+  }
+}
 
-    // also update aliased token’s .aliasedBy value
-    if (!tokens[aliasOfID]!.aliasedBy) {
-      tokens[aliasOfID]!.aliasedBy = [];
-    }
-    if (!tokens[aliasOfID]!.aliasedBy.includes(token.id)) {
-      tokens[aliasOfID]!.aliasedBy.push(token.id);
-      tokens[aliasOfID]!.aliasedBy.sort((a, b) => a.localeCompare(b, 'en-us', { numeric: true })); // sort to improve downstream plugins’ determinism
+function applyGradientPartialAlias(token: GradientTokenNormalized, mode: string, options: ApplyAliasOptions): void {
+  for (let i = 0; i < token.mode[mode]!.$value.length; i++) {
+    const step = token.mode[mode]!.$value[i]!;
+    for (const [k, v] of Object.entries(step)) {
+      if (typeof v === 'string' && isAlias(v)) {
+        token.mode[mode]!.partialAliasOf ??= [];
+        (token.mode[mode]!.partialAliasOf as any)[i] ??= {};
+        const expectedType = { color: ['color'], position: ['number'] }[k];
+        let node = ((options.node as unknown as ArrayNode | undefined)?.elements?.[i]?.value as any) || options.node;
+        if (node.type === 'Object') {
+          node = getObjMembers(node)[k] || node;
+        }
+        const { resolvedToken } = resolveAlias(v, { ...options, token, expectedType, node });
+        (token.mode[mode]!.partialAliasOf[i] as any)[k] = parseAlias(v);
+        if (mode === '.') {
+          token.partialAliasOf ??= [];
+          (token.partialAliasOf as any)[i] ??= {};
+          (token.partialAliasOf[i] as any)[k] = parseAlias(v);
+        }
+        (step as any)[k] = resolvedToken.$value;
+      }
     }
   }
+}
+
+function applyShadowPartialAlias(token: ShadowTokenNormalized, mode: string, options: ApplyAliasOptions): void {
+  // shadow-only fix: historically this token type may or may not allow an array
+  // of values, and at this stage in parsing, they all might not have been
+  // normalized yet.
+  if (!Array.isArray(token.mode[mode]!.$value)) {
+    token.mode[mode]!.$value = [token.mode[mode]!.$value];
+  }
 
-  // handle aliases within array values (e.g. cubicBezier, gradient)
-  else if (token.$type === 'cubicBezier' || token.$type === 'gradient' || token.$type === 'shadow') {
-    // some arrays are primitives, some are objects. handle both
-    for (let i = 0; i < token.$value.length; i++) {
-      // @ts-ignore
-      if (isAlias(token.$value[i])) {
-        if (!token.partialAliasOf) {
-          token.partialAliasOf = [];
+  for (let i = 0; i < token.mode[mode]!.$value.length; i++) {
+    const layer = token.mode[mode]!.$value[i]!;
+    for (const [k, v] of Object.entries(layer)) {
+      if (typeof v === 'string' && isAlias(v)) {
+        token.mode[mode]!.partialAliasOf ??= [];
+        token.mode[mode]!.partialAliasOf[i] ??= {};
+        const expectedType = {
+          offsetX: ['dimension'],
+          offsetY: ['dimension'],
+          blur: ['dimension'],
+          spread: ['dimension'],
+          color: ['color'],
+          inset: ['boolean'],
+        }[k];
+        let node = ((options.node as unknown as ArrayNode | undefined)?.elements?.[i] as any) || options.node;
+        if (node.type === 'Object') {
+          node = getObjMembers(node)[k] || node;
         }
-        // @ts-ignore
-        const aliasOfID = resolveAlias(token.$value[i], { tokens, logger, filename, node, src });
-        // @ts-ignore
-        const { id: aliasID, mode: aliasMode } = parseAlias(token.$value[i]);
-        token.partialAliasOf![i] = aliasID;
-        // @ts-ignore
-        token.$value[i] = (aliasMode && tokens[aliasOfID].mode[aliasMode]?.$value) || tokens[aliasOfID].$value;
-      } else if (typeof token.$value[i] === 'object') {
-        for (const [property, subvalue] of Object.entries(token.$value[i]!)) {
-          if (isAlias(subvalue)) {
-            if (!token.partialAliasOf) {
-              token.partialAliasOf = [];
-            }
-            if (!token.partialAliasOf[i]) {
-              token.partialAliasOf[i] = {};
-            }
-            const aliasOfID = resolveAlias(subvalue, { tokens, logger, filename, node, src });
-            const { id: aliasID, mode: aliasMode } = parseAlias(subvalue);
-            const aliasToken = tokens[aliasOfID]!;
-            const possibleTypes: string[] = expectedAliasTypes?.[property as keyof typeof expectedAliasTypes] || [];
-            if (possibleTypes.length && !possibleTypes.includes(aliasToken.$type)) {
-              const elementNode = ($valueNode as ArrayNode).elements[i]!.value;
-              logger.error({
-                message: `Invalid alias: expected $type: "${possibleTypes.join('" or "')}", received $type: "${aliasToken.$type}".`,
-                node: (elementNode as ObjectNode).members.find((m) => (m.name as StringNode).value === property)!.value,
-                filename,
-                src,
-              });
-            }
-
-            // @ts-ignore
-            token.partialAliasOf[i][property] = aliasID; // also keep the shallow alias here, too!
-            // @ts-ignore
-            token.$value[i][property] = (aliasMode && aliasToken.mode[aliasMode]?.$value) || aliasToken.$value;
-          }
+        const { resolvedToken } = resolveAlias(v, { ...options, token, expectedType, node });
+        (token.mode[mode]!.partialAliasOf[i] as any)[k] = parseAlias(v);
+        if (mode === '.') {
+          token.partialAliasOf ??= [];
+          token.partialAliasOf[i] ??= {};
+          (token.partialAliasOf[i] as any)[k] = parseAlias(v);
         }
+        (layer as any)[k] = resolvedToken.$value;
       }
     }
   }
-  // handle aliases within object (composite) values (e.g. border, typography, transition)
-  else if (typeof token.$value === 'object') {
-    for (const [property, subvalue] of Object.entries(token.$value)) {
-      if (!Object.hasOwn(token.$value, property)) {
-        continue;
+}
+
+function applyStrokeStylePartialAlias(
+  token: StrokeStyleTokenNormalized,
+  mode: string,
+  options: ApplyAliasOptions,
+): void {
+  // only dashArray can be aliased
+  if (typeof token.mode[mode]!.$value !== 'object' || !('dashArray' in token.mode[mode]!.$value)) {
+    return;
+  }
+
+  for (let i = 0; i < token.mode[mode]!.$value.dashArray.length; i++) {
+    const dash = token.mode[mode]!.$value.dashArray[i]!;
+    if (typeof dash === 'string' && isAlias(dash)) {
+      let node = (getObjMembers(options.node).dashArray as any) || options.node;
+      if (node.type === 'Array') {
+        node = ((node as unknown as ArrayNode | undefined)?.elements?.[i]?.value as any) || node;
       }
+      const { resolvedToken } = resolveAlias(dash, {
+        ...options,
+        token,
+        expectedType: ['dimension'],
+        node,
+      });
+      (token.mode[mode]!.$value as any).dashArray[i] = resolvedToken.$value;
+    }
+  }
+}
 
-      if (isAlias(subvalue)) {
-        if (!token.partialAliasOf) {
-          token.partialAliasOf = {};
-        }
-        const aliasOfID = resolveAlias(subvalue, { tokens, logger, filename, node, src });
-        const { id: aliasID, mode: aliasMode } = parseAlias(subvalue);
-        // @ts-ignore
-        token.partialAliasOf[property] = aliasID; // keep the shallow alias!
-        const aliasToken = tokens[aliasOfID];
-        // @ts-ignore
-        if (expectedAliasTypes?.[property] && !expectedAliasTypes[property].includes(aliasToken!.$type)) {
-          logger.error({
-            // @ts-ignore
-            message: `Invalid alias: expected $type: "${expectedAliasTypes[property].join('" or "')}", received $type: "${aliasToken.$type}".`,
-            // @ts-ignore
-            node: $valueNode.members.find((m) => m.name.value === property).value,
-            filename,
-            src,
-          });
-        }
-        // @ts-ignore
-        token.$value[property] = aliasToken.mode[aliasMode]?.$value || aliasToken.$value;
+function applyTransitionPartialAlias(token: TransitionTokenNormalized, mode: string, options: ApplyAliasOptions): void {
+  for (const [k, v] of Object.entries(token.mode[mode]!.$value)) {
+    if (typeof v === 'string' && isAlias(v)) {
+      token.mode[mode]!.partialAliasOf ??= {};
+      const expectedType = { duration: ['duration'], delay: ['duration'], timingFunction: ['cubicBezier'] }[k];
+      const node = (getObjMembers(options.node)[k] as any) || options.node;
+      const { resolvedToken } = resolveAlias(v, { ...options, token, expectedType, node });
+      (token.mode[mode]!.partialAliasOf as any)[k] = parseAlias(v);
+      if (mode === '.') {
+        token.partialAliasOf ??= {};
+        (token.partialAliasOf as any)[k] = parseAlias(v);
       }
+      (token.mode[mode]!.$value as any)[k] = resolvedToken.$value;
+    }
+  }
+}
 
-      // strokeStyle has an array within an object
-      // @ts-ignore
-      else if (Array.isArray(token.$value[property])) {
-        // @ts-ignore
-        for (let i = 0; i < token.$value[property].length; i++) {
-          // @ts-ignore
-          if (isAlias(token.$value[property][i])) {
-            // @ts-ignore
-            const aliasOfID = resolveAlias(token.$value[property][i], { tokens, logger, filename, node, src });
-            if (!token.partialAliasOf) {
-              token.partialAliasOf = {};
-            }
-            // @ts-ignore
-            if (!token.partialAliasOf[property]) {
-              // @ts-ignore
-              token.partialAliasOf[property] = [];
-            }
-            // @ts-ignore
-            const { id: aliasID, mode: aliasMode } = parseAlias(token.$value[property][i]);
-            // @ts-ignore
-            token.partialAliasOf[property][i] = aliasID; // keep the shallow alias!
-            const aliasToken = tokens[aliasOfID];
-            // @ts-ignore
-            if (expectedAliasTypes?.[property] && !expectedAliasTypes[property].includes(aliasToken.$type)) {
-              // @ts-ignore
-              const arrayNode = $valueNode.members.find((m) => m.name.value === property).value;
-              logger.error({
-                // @ts-ignore
-                message: `Invalid alias: expected $type: "${expectedAliasTypes[property].join('" or "')}", received $type: "${aliasToken.$type}".`,
-                node: arrayNode.elements[i],
-                filename,
-                src,
-              });
-            }
-            // @ts-ignore
-            token.$value[property][i] = tokens[aliasOfID].mode[aliasMode]?.$value || tokens[aliasOfID].$value;
-          }
-        }
+function applyTypographyPartialAlias(token: TypographyTokenNormalized, mode: string, options: ApplyAliasOptions): void {
+  for (const [k, v] of Object.entries(token.mode[mode]!.$value)) {
+    if (typeof v === 'string' && isAlias(v)) {
+      token.partialAliasOf ??= {};
+      token.mode[mode]!.partialAliasOf ??= {};
+      const expectedType = {
+        fontFamily: ['fontFamily'],
+        fontSize: ['dimension'],
+        fontWeight: ['fontWeight'],
+        letterSpacing: ['dimension'],
+        lineHeight: ['dimension', 'number'],
+      }[k] || ['string'];
+      const node = (getObjMembers(options.node)[k] as any) || options.node;
+      const { resolvedToken } = resolveAlias(v, { ...options, token, expectedType, node });
+      (token.mode[mode]!.partialAliasOf as any)[k] = parseAlias(v);
+      if (mode === '.') {
+        token.partialAliasOf[k] = parseAlias(v);
       }
+      (token.mode[mode]!.$value as any)[k] = resolvedToken.$value;
     }
   }
 }