@terrazzo/parser 0.7.1 → 0.7.3

package/src/parse/json.ts

@@ -3,15 +3,16 @@ import {
   type DocumentNode,
   type MemberNode,
   type ObjectNode,
+  type ParseOptions,
   type ValueNode,
-  parse as parseJSON,
+  parse as momoaParse,
   print,
 } from '@humanwhocodes/momoa';
 import type yamlToMomoa from 'yaml-to-momoa';
 import type Logger from '../logger.js';
 import type { InputSource } from '../types.js';
 
-export interface Visitor {
+export interface JSONVisitor {
   enter?: (node: AnyNode, parent: AnyNode | undefined, path: string[]) => void;
   exit?: (node: AnyNode, parent: AnyNode | undefined, path: string[]) => void;
 }
@@ -54,11 +55,7 @@ export function getObjMembers(node: ObjectNode): Record<string | number, ValueNo
   return members;
 }
 
-/**
- * Inject members to ObjectNode
- * @param {ObjectNode} node
- * @param {MemberNode[]} members
- */
+/** Inject members to ObjectNode */
 export function injectObjMembers(node: ObjectNode, members: MemberNode[] = []) {
   if (node.type !== 'Object') {
     return;
@@ -66,11 +63,16 @@ export function injectObjMembers(node: ObjectNode, members: MemberNode[] = []) {
   node.members.push(...members);
 }
 
+/** Replace an ObjectNode’s contents outright with another */
+export function replaceObjMembers(a: ObjectNode, b: DocumentNode | ObjectNode) {
+  a.members = (b.type === 'Document' && (b.body as ObjectNode)?.members) || (b as ObjectNode).members;
+}
+
 /**
  * Variation of Momoa’s traverse(), which keeps track of global path.
  * Allows mutation of AST (along with any consequences)
  */
-export function traverse(root: AnyNode, visitor: Visitor) {
+export function traverse(root: AnyNode, visitor: JSONVisitor) {
   /**
    * Recursively visits a node.
    * @param {AnyNode} node The node to visit.
@@ -89,20 +91,15 @@ export function traverse(root: AnyNode, visitor: Visitor) {
     const childNode = CHILD_KEYS[node.type];
     for (const key of childNode ?? []) {
       const value = node[key as keyof typeof node];
-
-      if (value && typeof value === 'object') {
-        if (Array.isArray(value)) {
-          for (let i = 0; i < value.length; i++) {
-            visitNode(
-              // @ts-expect-error this is safe
-              value[i],
-              node,
-              key === 'elements' ? [...nextPath, String(i)] : nextPath,
-            );
-          }
-        } else if (isNode(value)) {
-          visitNode(value as unknown as AnyNode, node, nextPath);
+      if (!value) {
+        continue;
+      }
+      if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+          visitNode(value[i] as unknown as AnyNode, node, key === 'elements' ? [...nextPath, String(i)] : nextPath);
         }
+      } else if (isNode(value)) {
+        visitNode(value as unknown as AnyNode, node, nextPath);
       }
     }
 
@@ -189,17 +186,26 @@ export function toMomoa(
       });
     }
   } else {
-    document = parseJSON(
-      typeof input === 'string' ? input : JSON.stringify(input, undefined, 2), // everything else: assert it’s JSON-serializable
-      {
-        mode: 'jsonc',
-        ranges: true,
-        tokens: true,
-      },
-    );
+    document = parseJSON(input);
   }
   if (!src) {
     src = print(document, { indent: 2 });
   }
   return { src, document };
 }
+
+/** Momoa, just with default options pre-set */
+export function parseJSON(input: string | Record<string, any>, options?: ParseOptions): any {
+  return momoaParse(
+    // note: it seems silly, at first glance, to have JSON.stringify() inside an actual JSON parser. But
+    // this provides a common interface to generate a Momoa AST for JSON created in-memory, which we already
+    // know is 100% valid because it’s already deserialized.
+    typeof input === 'string' ? input : JSON.stringify(input, undefined, 2),
+    {
+      mode: 'jsonc',
+      ranges: true,
+      tokens: true,
+      ...options,
+    },
+  );
+}

package/src/parse/normalize.ts

@@ -34,9 +34,6 @@ export const FONT_WEIGHT_MAP = {
   'ultra-black': 950,
 };
 
-// Note: because we’re handling a lot of input values, the type inference gets lost.
-// This file is expected to have a lot of `@ts-ignore` comments.
-
 const NUMBER_WITH_UNIT_RE = /(-?\d*\.?\d+)(.*)/;
 
 /** Fill in defaults, and return predictable shapes for tokens */
@@ -140,14 +137,10 @@ export default function normalizeValue<T extends Token>(token: T): T['$value'] {
         (layer) =>
           ({
             color: normalizeValue({ $type: 'color', $value: layer.color }),
-            // @ts-ignore
-            offsetX: normalizeValue({ $type: 'dimension', $value: layer.offsetX ?? 0 }),
-            // @ts-ignore
-            offsetY: normalizeValue({ $type: 'dimension', $value: layer.offsetY ?? 0 }),
-            // @ts-ignore
-            blur: normalizeValue({ $type: 'dimension', $value: layer.blur ?? 0 }),
-            // @ts-ignore
-            spread: normalizeValue({ $type: 'dimension', $value: layer.spread ?? 0 }),
+            offsetX: normalizeValue({ $type: 'dimension', $value: layer.offsetX ?? { value: 0, unit: 'px' } }),
+            offsetY: normalizeValue({ $type: 'dimension', $value: layer.offsetY ?? { value: 0, unit: 'px' } }),
+            blur: normalizeValue({ $type: 'dimension', $value: layer.blur ?? { value: 0, unit: 'px' } }),
+            spread: normalizeValue({ $type: 'dimension', $value: layer.spread ?? { value: 0, unit: 'px' } }),
             inset: layer.inset === true,
           }) as ShadowValueNormalized,
       );
@@ -163,11 +156,8 @@ export default function normalizeValue<T extends Token>(token: T): T['$value'] {
         return token.$value;
       }
       return {
-        // @ts-ignore
         duration: normalizeValue({ $type: 'duration', $value: token.$value.duration ?? 0 }),
-        // @ts-ignore
         delay: normalizeValue({ $type: 'duration', $value: token.$value.delay ?? 0 }),
-        // @ts-ignore
         timingFunction: normalizeValue({ $type: 'cubicBezier', $value: token.$value.timingFunction }),
       } as TransitionValue;
     }

package/src/parse/validate.ts

@@ -20,6 +20,29 @@ export interface ValidateOptions {
   logger: Logger;
 }
 
+export interface Visitors {
+  color?: Visitor;
+  dimension?: Visitor;
+  fontFamily?: Visitor;
+  fontWeight?: Visitor;
+  duration?: Visitor;
+  cubicBezier?: Visitor;
+  number?: Visitor;
+  link?: Visitor;
+  boolean?: Visitor;
+  strokeStyle?: Visitor;
+  border?: Visitor;
+  transition?: Visitor;
+  shadow?: Visitor;
+  gradient?: Visitor;
+  typography?: Visitor;
+  root?: Visitor;
+  group?: Visitor;
+  [key: string]: Visitor | undefined;
+}
+
+export type Visitor = (json: any, path: string, ast: AnyNode) => any | undefined | null;
+
 export const VALID_COLORSPACES = new Set([
   'adobe-rgb',
   'display-p3',
@@ -587,10 +610,7 @@ export function validateTokenMemberNode(node: MemberNode, { filename, src, logge
   if (node.type !== 'Member' && node.type !== 'Object') {
     logger.error({
       ...baseMessage,
-      message: `Expected Object, received ${JSON.stringify(
-        // @ts-ignore Yes, TypeScript, this SHOULD be unexpected. This is why we’re validating.
-        node.type,
-      )}`,
+      message: `Expected Object, received ${JSON.stringify(node.type)}`,
     });
   }
 
@@ -748,14 +768,48 @@ export function validateTokenMemberNode(node: MemberNode, { filename, src, logge
   }
 }
 
+/** Return any token node with its inherited $type */
+export function getInheritedType(
+  node: MemberNode,
+  { subpath, $typeInheritance }: { subpath: string[]; $typeInheritance?: Record<string, MemberNode> },
+): MemberNode | undefined {
+  if (node.value.type !== 'Object') {
+    return;
+  }
+
+  // keep track of $types
+  const $type = node.value.members.find((m) => m.name.type === 'String' && m.name.value === '$type');
+  const $value = node.value.members.find((m) => m.name.type === 'String' && m.name.value === '$value');
+  if ($typeInheritance && $type && !$value) {
+    $typeInheritance[subpath.join('.') || '.'] = $type;
+  }
+
+  const id = subpath.join('.');
+
+  // get parent type by taking the closest-scoped $type (length === closer)
+  let parent$type: MemberNode | undefined;
+  let longestPath = '';
+  for (const [k, v] of Object.entries($typeInheritance ?? {})) {
+    if (k === '.' || id.startsWith(k)) {
+      if (k.length > longestPath.length) {
+        parent$type = v;
+        longestPath = k;
+      }
+    }
+  }
+
+  return parent$type;
+}
+
 export interface ValidateTokenNodeOptions {
   subpath: string[];
   src: string;
   filename: URL;
   config: ConfigInit;
   logger: Logger;
-  parent?: AnyNode;
-  $typeInheritance?: Record<string, Token['$type']>;
+  parent: AnyNode | undefined;
+  transform?: Visitors;
+  inheritedTypeNode?: MemberNode;
 }
 
 /**
@@ -765,10 +819,8 @@ export interface ValidateTokenNodeOptions {
  */
 export default function validateTokenNode(
   node: MemberNode,
-  { config, filename, logger, parent, src, subpath, $typeInheritance }: ValidateTokenNodeOptions,
+  { config, filename, logger, parent, inheritedTypeNode, src, subpath }: ValidateTokenNodeOptions,
 ): TokenNormalized | undefined {
-  // const start = performance.now();
-
   // don’t validate $value
   if (subpath.includes('$value') || node.value.type !== 'Object') {
     return;
@@ -776,12 +828,6 @@ export default function validateTokenNode(
 
   const members = getObjMembers(node.value);
 
-  // keep track of $types
-  if ($typeInheritance && members.$type && members.$type.type === 'String' && !members.$value) {
-    // @ts-ignore
-    $typeInheritance[subpath.join('.') || '.'] = node.value.members.find((m) => m.name.value === '$type');
-  }
-
   // don’t validate $extensions or $defs
   if (!members.$value || subpath.includes('$extensions') || subpath.includes('$deps')) {
     return;
@@ -800,29 +846,13 @@ export default function validateTokenNode(
     });
   }
 
-  const extensions = members.$extensions ? getObjMembers(members.$extensions as ObjectNode) : undefined;
-  const sourceNode = structuredClone(node);
-
-  // get parent type by taking the closest-scoped $type (length === closer)
-  let parent$type: Token['$type'] | undefined;
-  let longestPath = '';
-  for (const [k, v] of Object.entries($typeInheritance ?? {})) {
-    if (k === '.' || id.startsWith(k)) {
-      if (k.length > longestPath.length) {
-        parent$type = v;
-        longestPath = k;
-      }
-    }
-  }
-  if (parent$type && !members.$type) {
-    injectObjMembers(
-      // @ts-ignore
-      sourceNode.value,
-      [parent$type],
-    );
+  const nodeWithType = structuredClone(node);
+  let $type = (members.$type?.type === 'String' && members.$type.value) || undefined;
+  if (inheritedTypeNode && !members.$type) {
+    injectObjMembers(nodeWithType.value as ObjectNode, [inheritedTypeNode]);
+    $type = (inheritedTypeNode.value as StringNode).value;
   }
-
-  validateTokenMemberNode(sourceNode, { filename, src, logger });
+  validateTokenMemberNode(nodeWithType, { filename, src, logger });
 
   // All tokens must be valid, so we want to validate it up till this
   // point. However, if we are ignoring this token (or respecting
@@ -833,47 +863,37 @@ export default function validateTokenNode(
   }
 
   const group: TokenNormalized['group'] = { id: splitID(id).group!, tokens: [] };
-  if (parent$type) {
-    group.$type =
-      // @ts-ignore
-      parent$type.value.value;
+  if (inheritedTypeNode && inheritedTypeNode.value.type === 'String') {
+    group.$type = inheritedTypeNode.value.value as Token['$type'];
   }
   // note: this will also include sibling tokens, so be selective about only accessing group-specific properties
-  const groupMembers = getObjMembers(
-    // @ts-ignore
-    parent,
-  );
+  const groupMembers = getObjMembers(parent as ObjectNode);
   if (groupMembers.$description) {
     group.$description = evaluate(groupMembers.$description) as string;
   }
   if (groupMembers.$extensions) {
     group.$extensions = evaluate(groupMembers.$extensions) as Record<string, unknown>;
   }
-  const token: TokenNormalized = {
-    // @ts-ignore
-    $type: members.$type?.value ?? parent$type?.value.value,
-    // @ts-ignore
-    $value: evaluate(members.$value),
+  const $value = evaluate(members.$value!);
+  const token = {
+    $type,
+    $value,
     id,
-    // @ts-ignore
     mode: {},
-    // @ts-ignore
     originalValue: evaluate(node.value),
     group,
     source: {
-      loc: filename ? filename.href : undefined,
-      // @ts-ignore
-      node: sourceNode.value,
+      loc: filename?.href,
+      node: nodeWithType.value as ObjectNode,
     },
-  };
-  // @ts-ignore
-  if (members.$description?.value) {
-    // @ts-ignore
+  } as unknown as TokenNormalized;
+  if (members.$description?.type === 'String' && members.$description.value) {
     token.$description = members.$description.value;
   }
 
   // handle modes
   // note that circular refs are avoided here, such as not duplicating `modes`
+  const extensions = members.$extensions ? getObjMembers(members.$extensions as ObjectNode) : undefined;
   const modeValues = extensions?.mode ? getObjMembers(extensions.mode as any) : {};
   for (const mode of ['.', ...Object.keys(modeValues)]) {
     const modeValue = mode === '.' ? token.$value : (evaluate((modeValues as any)[mode]) as any);
@@ -881,18 +901,11 @@ export default function validateTokenNode(
       $value: modeValue,
       originalValue: modeValue,
       source: {
-        loc: filename ? filename.href : undefined,
-        // @ts-ignore
-        node: modeValues[mode],
+        loc: filename?.href,
+        node: modeValues[mode] as ObjectNode,
       },
     };
   }
 
-  // logger.debug({
-  //   message: `${token.id}: validateTokenNode`,
-  //   group: 'parser', label: 'validate',
-  //   label: 'validate',
-  //   timing: performance.now() - start,
-  // });
   return token;
 }