@terrazzo/parser 0.4.0 → 0.5.0

package/src/parse/alias.ts

@@ -34,7 +34,12 @@ export const COMPOSITE_TYPE_VALUES = {
   },
 };
 
-/** Resolve alias */
+/**
+ * Resolve alias
+ * Note: to save work during resolution (and reduce memory), this will inject
+ * `aliasedBy` while it traverses. Resolution isn’t normally associated with
+ * mutation, but for our usecase it is preferable.
+ */
 export function resolveAlias(
   alias: string,
   {
@@ -52,19 +57,34 @@ export function resolveAlias(
     node: AnyNode;
     scanned?: string[];
   },
-) {
+): { id: string; chain: string[] } {
   const { id } = parseAlias(alias);
   if (!tokens[id]) {
-    logger.error({ message: `Alias "${alias}" not found.`, filename, src, node });
+    logger.error({ group: 'parser', label: 'alias', message: `Alias "${alias}" not found.`, filename, src, node });
   }
   if (scanned.includes(id)) {
-    logger.error({ message: `Circular alias detected from "${alias}".`, filename, src, node });
+    logger.error({
+      group: 'parser',
+      label: 'alias',
+      message: `Circular alias detected from "${alias}".`,
+      filename,
+      src,
+      node,
+    });
   }
   const token = tokens[id]!;
-  if (!isAlias(token.$value)) {
-    return id;
+  // important: use originalValue to trace the full alias path correctly
+  if (!isAlias(token.originalValue.$value)) {
+    return { id, chain: scanned.concat(id) };
   }
-  return resolveAlias(token.$value as string, { tokens, logger, filename, node, src, scanned: [...scanned, id] });
+  return resolveAlias(token.originalValue.$value as string, {
+    tokens,
+    logger,
+    filename,
+    node,
+    src,
+    scanned: scanned.concat(id),
+  });
 }
 
 /** Resolve aliases, update values, and mutate `token` to add `aliasOf` / `partialAliasOf` */
@@ -76,8 +96,37 @@ export function applyAliases(
     filename,
     src,
     node,
-  }: { tokens: Record<string, TokenNormalized>; logger: Logger; filename?: URL; src: string; node: AnyNode },
+    skipReverseAlias,
+  }: {
+    tokens: Record<string, TokenNormalized>;
+    logger: Logger;
+    filename?: URL;
+    src: string;
+    node: AnyNode;
+    skipReverseAlias?: boolean;
+  },
 ) {
+  /**
+   * Add reverse alias lookups. Note this intentionally mutates the root
+   * references in `tokens` to save work.  This is essential to doing everything
+   * in one pass while still being accurate.
+   */
+  function addReverseAliases(resolvedID: string, ids: string[]) {
+    if (skipReverseAlias || !tokens[resolvedID]) {
+      return;
+    }
+
+    // populate entire chain of aliases, so we can redeclare tokens when needed
+    if (!tokens[resolvedID]!.aliasedBy) {
+      tokens[resolvedID]!.aliasedBy = [];
+    }
+    for (const link of [token.id, ...ids]) {
+      if (link !== resolvedID && !tokens[resolvedID]!.aliasedBy!.includes(link)) {
+        tokens[resolvedID]!.aliasedBy.push(link);
+      }
+    }
+  }
+
   const $valueNode =
     (node.type === 'Object' && node.members.find((m) => (m.name as StringNode).value === '$value')?.value) || node;
   const expectedAliasTypes =
@@ -85,29 +134,28 @@ export function applyAliases(
 
   // handle simple aliases
   if (isAlias(token.$value)) {
-    const aliasOfID = resolveAlias(token.$value as string, { tokens, logger, filename, node, src });
+    const { id: deepAliasID, chain } = 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) {
+    const resolvedToken = tokens[deepAliasID]!;
+
+    // resolve value in root token, and add aliasOf
+    token.aliasOf = deepAliasID;
+    token.aliasChain = chain;
+    token.$value = resolvedToken!.mode[aliasMode!]?.$value || resolvedToken.$value;
+
+    addReverseAliases(deepAliasID, chain);
+
+    if (token.$type && token.$type !== resolvedToken.$type) {
       logger.error({
-        message: `Invalid alias: expected $type: "${token.$type}", received $type: "${aliasOf.$type}".`,
+        group: 'parser',
+        label: 'alias',
+        message: `Invalid alias: expected $type: "${token.$type}", received $type: "${resolvedToken.$type}".`,
         node: $valueNode,
         filename,
         src,
       });
     }
-    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
-    }
+    token.$type = resolvedToken.$type;
   }
 
   // handle aliases within array values (e.g. cubicBezier, gradient)
@@ -120,12 +168,12 @@ export function applyAliases(
           token.partialAliasOf = [];
         }
         // @ts-ignore
-        const aliasOfID = resolveAlias(token.$value[i], { tokens, logger, filename, node, src });
+        const { id: deepAliasID } = 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;
+        token.$value[i] = (aliasMode && tokens[deepAliasID].mode[aliasMode]?.$value) || tokens[deepAliasID].$value;
       } else if (typeof token.$value[i] === 'object') {
         for (const [property, subvalue] of Object.entries(token.$value[i]!)) {
           if (isAlias(subvalue)) {
@@ -135,14 +183,19 @@ export function applyAliases(
             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 { id: deepAliasID, chain } = resolveAlias(subvalue, { tokens, logger, filename, node, src });
+            const { id: shallowAliasID, mode: aliasMode } = parseAlias(subvalue);
+            const resolvedToken = tokens[deepAliasID]!;
+
+            addReverseAliases(deepAliasID, chain);
+
             const possibleTypes: string[] = expectedAliasTypes?.[property as keyof typeof expectedAliasTypes] || [];
-            if (possibleTypes.length && !possibleTypes.includes(aliasToken.$type)) {
+            if (possibleTypes.length && !possibleTypes.includes(resolvedToken.$type)) {
               const elementNode = ($valueNode as ArrayNode).elements[i]!.value;
               logger.error({
-                message: `Invalid alias: expected $type: "${possibleTypes.join('" or "')}", received $type: "${aliasToken.$type}".`,
+                group: 'parser',
+                label: 'alias',
+                message: `Invalid alias: expected $type: "${possibleTypes.join('" or "')}", received $type: "${resolvedToken.$type}".`,
                 node: (elementNode as ObjectNode).members.find((m) => (m.name as StringNode).value === property)!.value,
                 filename,
                 src,
@@ -150,9 +203,9 @@ export function applyAliases(
             }
 
             // @ts-ignore
-            token.partialAliasOf[i][property] = aliasID; // also keep the shallow alias here, too!
+            token.partialAliasOf[i][property] = shallowAliasID; // also keep the shallow alias here, too!
             // @ts-ignore
-            token.$value[i][property] = (aliasMode && aliasToken.mode[aliasMode]?.$value) || aliasToken.$value;
+            token.$value[i][property] = (aliasMode && resolvedToken.mode[aliasMode]?.$value) || resolvedToken.$value;
           }
         }
       }
@@ -169,16 +222,21 @@ export function applyAliases(
         if (!token.partialAliasOf) {
           token.partialAliasOf = {};
         }
-        const aliasOfID = resolveAlias(subvalue, { tokens, logger, filename, node, src });
-        const { id: aliasID, mode: aliasMode } = parseAlias(subvalue);
+        const { id: deepAliasID, chain } = resolveAlias(subvalue, { tokens, logger, filename, node, src });
+        const { id: shallowAliasID, mode: aliasMode } = parseAlias(subvalue);
+
+        addReverseAliases(deepAliasID, chain);
+
         // @ts-ignore
-        token.partialAliasOf[property] = aliasID; // keep the shallow alias!
-        const aliasToken = tokens[aliasOfID];
+        token.partialAliasOf[property] = shallowAliasID; // keep the shallow alias!
+        const resolvedToken = tokens[deepAliasID];
         // @ts-ignore
-        if (expectedAliasTypes?.[property] && !expectedAliasTypes[property].includes(aliasToken!.$type)) {
+        if (expectedAliasTypes?.[property] && !expectedAliasTypes[property].includes(resolvedToken!.$type)) {
           logger.error({
+            group: 'parser',
+            label: 'alias',
             // @ts-ignore
-            message: `Invalid alias: expected $type: "${expectedAliasTypes[property].join('" or "')}", received $type: "${aliasToken.$type}".`,
+            message: `Invalid alias: expected $type: "${expectedAliasTypes[property].join('" or "')}", received $type: "${resolvedToken.$type}".`,
             // @ts-ignore
             node: $valueNode.members.find((m) => m.name.value === property).value,
             filename,
@@ -186,7 +244,7 @@ export function applyAliases(
           });
         }
         // @ts-ignore
-        token.$value[property] = aliasToken.mode[aliasMode]?.$value || aliasToken.$value;
+        token.$value[property] = resolvedToken.mode[aliasMode]?.$value || resolvedToken.$value;
       }
 
       // strokeStyle has an array within an object
@@ -197,7 +255,16 @@ export function applyAliases(
           // @ts-ignore
           if (isAlias(token.$value[property][i])) {
             // @ts-ignore
-            const aliasOfID = resolveAlias(token.$value[property][i], { tokens, logger, filename, node, src });
+            const { id: deepAliasID, chain } = resolveAlias(token.$value[property][i], {
+              tokens,
+              logger,
+              filename,
+              node,
+              src,
+            });
+
+            addReverseAliases(deepAliasID, chain);
+
             if (!token.partialAliasOf) {
               token.partialAliasOf = {};
             }
@@ -210,21 +277,23 @@ export function applyAliases(
             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];
+            const resolvedToken = tokens[deepAliasID];
             // @ts-ignore
-            if (expectedAliasTypes?.[property] && !expectedAliasTypes[property].includes(aliasToken.$type)) {
+            if (expectedAliasTypes?.[property] && !expectedAliasTypes[property].includes(resolvedToken.$type)) {
               // @ts-ignore
               const arrayNode = $valueNode.members.find((m) => m.name.value === property).value;
               logger.error({
+                group: 'parser',
+                label: 'alias',
                 // @ts-ignore
-                message: `Invalid alias: expected $type: "${expectedAliasTypes[property].join('" or "')}", received $type: "${aliasToken.$type}".`,
+                message: `Invalid alias: expected $type: "${expectedAliasTypes[property].join('" or "')}", received $type: "${resolvedToken.$type}".`,
                 node: arrayNode.elements[i],
                 filename,
                 src,
               });
             }
             // @ts-ignore
-            token.$value[property][i] = tokens[aliasOfID].mode[aliasMode]?.$value || tokens[aliasOfID].$value;
+            token.$value[property][i] = tokens[deepAliasID].mode[aliasMode]?.$value || tokens[deepAliasID].$value;
           }
         }
       }

package/src/parse/index.ts

@@ -105,6 +105,8 @@ export default async function parse(
   const totalStart = performance.now();
 
   // 5. Resolve aliases and populate groups
+  const aliasesStart = performance.now();
+  let aliasCount = 0;
   for (const [id, token] of Object.entries(tokens)) {
     if (!Object.hasOwn(tokens, id)) {
       continue;
@@ -116,13 +118,21 @@ export default async function parse(
       node: token.source.node,
       logger,
     });
+    token.mode['.']!.$type = token.$type;
     token.mode['.']!.$value = token.$value;
     if (token.aliasOf) {
       token.mode['.']!.aliasOf = token.aliasOf;
     }
+    if (token.aliasChain) {
+      token.mode['.']!.aliasChain = token.aliasChain;
+    }
+    if (token.aliasedBy) {
+      token.mode['.']!.aliasedBy = token.aliasedBy;
+    }
     if (token.partialAliasOf) {
       token.mode['.']!.partialAliasOf = token.partialAliasOf;
     }
+    aliasCount++;
     const { group: parentGroup } = splitID(id);
     if (parentGroup) {
       for (const siblingID of Object.keys(tokens)) {
@@ -133,14 +143,16 @@ export default async function parse(
       }
     }
   }
-
-  // 6. resolve mode aliases
-  const modesStart = performance.now();
   logger.debug({
-    message: 'Start mode resolution',
+    message: `Resolved ${aliasCount} aliases`,
     group: 'parser',
-    label: 'modes',
+    label: 'alias',
+    timing: performance.now() - aliasesStart,
   });
+
+  // 7. resolve mode aliases
+  const modesStart = performance.now();
+  let modeAliasCount = 0;
   for (const [id, token] of Object.entries(tokens)) {
     if (!Object.hasOwn(tokens, id)) {
       continue;
@@ -149,18 +161,20 @@ export default async function parse(
       if (mode === '.') {
         continue; // skip shadow of root value
       }
+      modeAliasCount++;
       applyAliases(modeValue, {
         tokens,
         node: modeValue.source.node,
         logger,
         src: _sources[token.source.loc!]?.src as string,
+        skipReverseAlias: true,
       });
     }
   }
   logger.debug({
+    message: `Resolved ${modeAliasCount} mode aliases`,
     group: 'parser',
-    label: 'modes',
-    message: 'Finish token modes',
+    label: 'alias',
     timing: performance.now() - modesStart,
   });
 
@@ -175,6 +189,7 @@ export default async function parse(
     const { errorCount } = logger.stats();
     if (errorCount > 0) {
       logger.error({
+        group: 'parser',
         message: `Parser encountered ${errorCount} ${pluralize(errorCount, 'error', 'errors')}. Exiting.`,
       });
     }
@@ -207,20 +222,19 @@ async function parseSingle(
 ): Promise<{ tokens: Record<string, Token>; document: DocumentNode; src?: string }> {
   // 1. Build AST
   const startParsing = performance.now();
-  logger.debug({ group: 'parser', label: 'parse', message: 'Start JSON parsing' });
   const { src, document } = toMomoa(input, { filename, logger, continueOnError, yamlToMomoa });
   logger.debug({
     group: 'parser',
-    label: 'parse',
+    label: 'json',
     message: 'Finish JSON parsing',
     timing: performance.now() - startParsing,
   });
   const tokens: Record<string, TokenNormalized> = {};
 
   // 2. Walk AST to validate tokens
+  let tokenCount = 0;
   const startValidate = performance.now();
   const $typeInheritance: Record<string, Token['$type']> = {};
-  logger.debug({ message: 'Start token validation', group: 'parser', label: 'validate' });
   traverse(document, {
     enter(node, parent, subpath) {
       // if $type appears at root of tokens.json, collect it
@@ -237,19 +251,20 @@ async function parseSingle(
         const token = validateTokenNode(node, { filename, src, config, logger, parent, subpath, $typeInheritance });
         if (token) {
           tokens[token.id] = token;
+          tokenCount++;
         }
       }
     },
   });
-  logger.debug({ message: 'Finish token validation', group: 'parser', label: 'validate', timing: startValidate });
-
-  // 3. normalize values
-  const normalizeStart = performance.now();
   logger.debug({
-    message: 'Start token normalization',
+    message: `Validated ${tokenCount} tokens`,
     group: 'parser',
-    label: 'normalize',
+    label: 'validate',
+    timing: performance.now() - startValidate,
   });
+
+  // 3. normalize values
+  const normalizeStart = performance.now();
   for (const [id, token] of Object.entries(tokens)) {
     try {
       tokens[id]!.$value = normalize(token);
@@ -259,7 +274,15 @@ async function parseSingle(
       if (members.$value) {
         node = members.$value as ObjectNode;
       }
-      logger.error({ message: (err as Error).message, filename, src, node, continueOnError });
+      logger.error({
+        group: 'parser',
+        label: 'normalize',
+        message: (err as Error).message,
+        filename,
+        src,
+        node,
+        continueOnError,
+      });
     }
     for (const [mode, modeValue] of Object.entries(token.mode)) {
       if (mode === '.') {
@@ -273,31 +296,39 @@ async function parseSingle(
         if (members.$value) {
           node = members.$value as ObjectNode;
         }
-        logger.error({ message: (err as Error).message, filename, src, node: modeValue.source.node, continueOnError });
+        logger.error({
+          group: 'parser',
+          label: 'normalize',
+          message: (err as Error).message,
+          filename,
+          src,
+          node: modeValue.source.node,
+          continueOnError,
+        });
       }
     }
   }
+  logger.debug({
+    message: `Normalized ${tokenCount} tokens`,
+    group: 'parser',
+    label: 'normalize',
+    timing: performance.now() - normalizeStart,
+  });
 
   // 4. Execute lint runner with loaded plugins
   if (!skipLint && config?.plugins?.length) {
     const lintStart = performance.now();
-    logger.debug({ message: 'Start token linting', group: 'parser', label: 'validate' });
     await lintRunner({ tokens, src, config, logger });
     logger.debug({
-      message: 'Finish token linting',
+      message: `Linted ${tokenCount} tokens`,
       group: 'parser',
-      label: 'validate',
+      label: 'lint',
       timing: performance.now() - lintStart,
     });
+  } else {
+    logger.debug({ message: 'Linting skipped', group: 'parser', label: 'lint' });
   }
 
-  logger.debug({
-    message: 'Finish token normalization',
-    group: 'parser',
-    label: 'normalize',
-    timing: performance.now() - normalizeStart,
-  });
-
   return {
     tokens,
     document,

package/src/parse/json.ts

@@ -55,18 +55,15 @@ export function getObjMembers(node: ObjectNode): Record<string | number, ValueNo
 }
 
 /**
- * Inject members to ObjectNode and return a clone
+ * Inject members to ObjectNode
  * @param {ObjectNode} node
  * @param {MemberNode[]} members
- * @return {ObjectNode}
  */
-export function injectObjMembers(node: ObjectNode, members: MemberNode[] = []): ObjectNode {
+export function injectObjMembers(node: ObjectNode, members: MemberNode[] = []) {
   if (node.type !== 'Object') {
-    return node;
+    return;
   }
-  const newNode = structuredClone(node);
-  newNode.members.push(...members);
-  return newNode;
+  node.members.push(...members);
 }
 
 /**
@@ -176,11 +173,12 @@ export function toMomoa(
       try {
         document = yamlToMomoa(input); // if string, but not JSON, attempt YAML
       } catch (err) {
-        logger.error({ message: String(err), filename, src: input, continueOnError });
+        logger.error({ group: 'parser', label: 'json', message: String(err), filename, src: input, continueOnError });
       }
     } else {
       logger.error({
         group: 'parser',
+        label: 'yaml',
         message: `Install \`yaml-to-momoa\` package to parse YAML, and pass in as option, e.g.:
 
     import { parse } from '@terrazzo/parser';

package/src/parse/normalize.ts

@@ -110,7 +110,7 @@ export default function normalizeValue<T extends Token>(token: T): T['$value'] {
       }
       const output: GradientValueNormalized = [];
       for (let i = 0; i < token.$value.length; i++) {
-        const stop = { ...(token.$value[i] as GradientStopNormalized) };
+        const stop = structuredClone(token.$value[i] as GradientStopNormalized);
         stop.color = normalizeValue({ $type: 'color', $value: stop.color! });
         if (stop.position === undefined) {
           stop.position = i / (token.$value.length - 1);
@@ -166,22 +166,24 @@ export default function normalizeValue<T extends Token>(token: T): T['$value'] {
         return token.$value;
       }
       const output: TypographyValueNormalized = {};
-      for (const k in token.$value) {
+      for (const [k, $value] of Object.entries(token.$value)) {
         switch (k) {
           case 'fontSize':
           case 'letterSpacing': {
-            output[k] = normalizeValue({ $type: 'dimension', $value: token.$value[k] as DimensionValue });
+            output[k] = normalizeValue({ $type: 'dimension', $value: $value as DimensionValue });
             break;
           }
           case 'lineHeight': {
             output[k] = normalizeValue({
               $type: typeof token.$value === 'number' ? 'number' : 'dimension',
-              $value: token.$value[k] as any,
+              $value: $value as any,
             });
             break;
           }
-          default:
-            output[k] = token.$value[k];
+          default: {
+            output[k] = $value;
+            break;
+          }
         }
       }
       return output;