@terrazzo/parser 0.1.3 → 0.2.0

package/{parse/validate.js → src/parse/validate.ts}

@@ -1,13 +1,22 @@
-import { print } from '@humanwhocodes/momoa';
+import {
+  type AnyNode,
+  type MemberNode,
+  type ObjectNode,
+  type StringNode,
+  type ValueNode,
+  print,
+} from '@humanwhocodes/momoa';
 import { isAlias } from '@terrazzo/token-tools';
+import type Logger from '../logger.js';
 import { getObjMembers } from './json.js';
 
 const listFormat = new Intl.ListFormat('en-us', { type: 'disjunction' });
 
-/** @typedef {import("@humanwhocodes/momoa").AnyNode} AnyNode */
-/** @typedef {import("@humanwhocodes/momoa").ObjectNode} ObjectNode */
-/** @typedef {import("@humanwhocodes/momoa").ValueNode} ValueNode */
-/** @typedef {import("@babel/code-frame").SourceLocation} SourceLocation */
+export interface ValidateOptions {
+  filename?: URL;
+  src: string;
+  logger: Logger;
+}
 
 export const VALID_COLORSPACES = new Set([
   'adobe-rgb',
@@ -60,30 +69,24 @@ export const STROKE_STYLE_VALUES = new Set([
 ]);
 export const STROKE_STYLE_LINE_CAP_VALUES = new Set(['round', 'butt', 'square']);
 
-/**
- * Distinct from isAlias() in that this accepts malformed aliases
- * @param {AnyNode} node
- * @return {boolean}
- */
-function isMaybeAlias(node) {
+/** Distinct from isAlias() in that this accepts malformed aliases */
+function isMaybeAlias(node: AnyNode) {
   if (node?.type === 'String') {
     return node.value.startsWith('{');
   }
   return false;
 }
 
-/**
- * Assert object members match given types
- * @param {ObjectNode} $value
- * @param {Record<string, { validator: typeof validateAlias; required?: boolean }>} properties
- * @param {AnyNode} node
- * @param {ValidateOptions} options
- * @return {void}
- */
-function validateMembersAs($value, properties, node, { filename, src, logger }) {
+/** Assert object members match given types */
+function validateMembersAs(
+  $value: ObjectNode,
+  properties: Record<string, { validator: typeof validateAliasSyntax; required?: boolean }>,
+  node: AnyNode,
+  { filename, src, logger }: ValidateOptions,
+) {
   const members = getObjMembers($value);
   for (const property in properties) {
-    const { validator, required } = properties[property];
+    const { validator, required } = properties[property]!;
     if (!members[property]) {
       if (required) {
         logger.error({ message: `Missing required property "${property}"`, filename, node: $value, src });
@@ -99,51 +102,33 @@ function validateMembersAs($value, properties, node, { filename, src, logger })
   }
 }
 
-/**
- * Verify an Alias $value is formatted correctly
- * @param {ValueNode} $value
- * @param {AnyNode} node
- * @param {ValidateOptions} options
- * @return {void}
- */
-export function validateAliasSyntax($value, node, { filename, src, logger }) {
+/** Verify an Alias $value is formatted correctly */
+export function validateAliasSyntax($value: ValueNode, _node: AnyNode, { filename, src, logger }: ValidateOptions) {
   if ($value.type !== 'String' || !isAlias($value.value)) {
     logger.error({ message: `Invalid alias: ${print($value)}`, filename, node: $value, src });
   }
 }
 
-/**
- * Verify a Border token is valid
- * @param {ValueNode} $value
- * @param {AnyNode} node
- * @param {ValidateOptions} options
- * @return {void}
- */
-export function validateBorder($value, node, { filename, src, logger }) {
+/** Verify a Border token is valid */
+export function validateBorder($value: ValueNode, node: AnyNode, { filename, src, logger }: ValidateOptions) {
   if ($value.type !== 'Object') {
     logger.error({ message: `Expected object, received ${$value.type}`, filename, node: $value, src });
-    return;
+  } else {
+    validateMembersAs(
+      $value,
+      {
+        color: { validator: validateColor, required: true },
+        style: { validator: validateStrokeStyle, required: true },
+        width: { validator: validateDimension, required: true },
+      },
+      node,
+      { filename, src, logger },
+    );
   }
-  validateMembersAs(
-    $value,
-    {
-      color: { validator: validateColor, required: true },
-      style: { validator: validateStrokeStyle, required: true },
-      width: { validator: validateDimension, required: true },
-    },
-    node,
-    { filename, src, logger },
-  );
 }
 
-/**
- * Verify a Color token is valid
- * @param {ValueNode} $value
- * @param {AnyNode} node
- * @param {ValidateOptions} options
- * @return {void}
- */
-export function validateColor($value, node, { filename, src, logger }) {
+/** Verify a Color token is valid */
+export function validateColor($value: ValueNode, node: AnyNode, { filename, src, logger }: ValidateOptions) {
   if ($value.type === 'String') {
     // TODO: enable when object notation is finalized
     // logger.warn({
@@ -164,34 +149,35 @@ export function validateColor($value, node, { filename, src, logger }) {
             if (v.type !== 'String') {
               logger.error({ message: `Expected string, received ${print(v)}`, filename, node: v, src });
             }
-            if (!VALID_COLORSPACES.has(v.value)) {
+            if (!VALID_COLORSPACES.has((v as StringNode).value)) {
               logger.error({ message: `Unsupported colorspace ${print(v)}`, filename, node: v, src });
             }
           },
           required: true,
         },
         channels: {
-          validator: (v, node) => {
+          validator: (v) => {
             if (v.type !== 'Array') {
               logger.error({ message: `Expected array, received ${print(v)}`, filename, node: v, src });
-            }
-            if (v.elements?.length !== 3) {
-              logger.error({
-                message: `Expected 3 channels, received ${v.elements?.length ?? 0}`,
-                filename,
-                node: v,
-                src,
-              });
-            }
-            for (const element of v.elements) {
-              if (element.value.type !== 'Number') {
+            } else {
+              if (v.elements?.length !== 3) {
                 logger.error({
-                  message: `Expected number, received ${print(element.value)}`,
+                  message: `Expected 3 channels, received ${v.elements?.length ?? 0}`,
                   filename,
-                  node: element,
+                  node: v,
                   src,
                 });
               }
+              for (const element of v.elements) {
+                if (element.value.type !== 'Number') {
+                  logger.error({
+                    message: `Expected number, received ${print(element.value)}`,
+                    filename,
+                    node: element,
+                    src,
+                  });
+                }
+              }
             }
           },
           required: true,
@@ -222,14 +208,8 @@ export function validateColor($value, node, { filename, src, logger }) {
   }
 }
 
-/**
- * Verify a Cubic Bézier token is valid
- * @param {ValueNode} $value
- * @param {AnyNode} node
- * @param {ValidateOptions} options
- * @return {void}
- */
-export function validateCubicBezier($value, node, { filename, src, logger }) {
+/** Verify a Cubic Bézier token is valid */
+export function validateCubicBezier($value: ValueNode, _node: AnyNode, { filename, src, logger }: ValidateOptions) {
   if ($value.type !== 'Array') {
     logger.error({ message: `Expected array of strings, received ${print($value)}`, filename, node: $value, src });
   } else if (
@@ -251,14 +231,8 @@ export function validateCubicBezier($value, node, { filename, src, logger }) {
   }
 }
 
-/**
- * Verify a Dimension token is valid
- * @param {ValueNode} $value
- * @param {AnyNode} node
- * @param {ValidateOptions} options
- * @return {void}
- */
-export function validateDimension($value, node, { filename, src, logger }) {
+/** Verify a Dimension token is valid */
+export function validateDimension($value: ValueNode, _node: AnyNode, { filename, src, logger }: ValidateOptions) {
   if ($value.type === 'Number' && $value.value === 0) {
     return; // `0` is a valid number
   }
@@ -270,12 +244,12 @@ export function validateDimension($value, node, { filename, src, logger }) {
     if (!unit) {
       logger.error({ message: 'Missing required property "unit".', filename, node: $value, src });
     }
-    if (value.type !== 'Number') {
-      logger.error({ message: `Expected number, received ${value.type}`, filename, node: value, src });
+    if (value!.type !== 'Number') {
+      logger.error({ message: `Expected number, received ${value!.type}`, filename, node: value, src });
     }
-    if (!['px', 'em', 'rem'].includes(unit.value)) {
+    if (!['px', 'em', 'rem'].includes((unit as StringNode).value)) {
       logger.error({
-        message: `Expected unit "px", "em", or "rem", received ${print(unit)}`,
+        message: `Expected unit "px", "em", or "rem", received ${print(unit as StringNode)}`,
         filename,
         node: unit,
         src,
@@ -287,30 +261,24 @@ export function validateDimension($value, node, { filename, src, logger }) {
   if ($value.type !== 'String') {
     logger.error({ message: `Expected string, received ${$value.type}`, filename, node: $value, src });
   }
-  const value = $value.value.match(/^-?[0-9.]+/)?.[0];
-  const unit = $value.value.replace(value, '');
-  if ($value.value === '') {
+  const value = ($value as StringNode).value.match(/^-?[0-9.]+/)?.[0];
+  const unit = ($value as StringNode).value.replace(value!, '');
+  if (($value as StringNode).value === '') {
     logger.error({ message: 'Expected dimension, received empty string', filename, node: $value, src });
   } else if (!['px', 'em', 'rem'].includes(unit)) {
     logger.error({
-      message: `Expected unit "px", "em", or "rem", received ${JSON.stringify(unit || $value.value)}`,
+      message: `Expected unit "px", "em", or "rem", received ${JSON.stringify(unit || ($value as StringNode).value)}`,
       filename,
       node: $value,
       src,
     });
-  } else if (!Number.isFinite(Number.parseFloat(value))) {
+  } else if (!Number.isFinite(Number.parseFloat(value!))) {
     logger.error({ message: `Expected dimension with units, received ${print($value)}`, filename, node: $value, src });
   }
 }
 
-/**
- * Verify a Duration token is valid
- * @param {ValueNode} $value
- * @param {AnyNode} node
- * @param {ValidateOptions} options
- * @return {void}
- */
-export function validateDuration($value, node, { filename, src, logger }) {
+/** Verify a Duration token is valid */
+export function validateDuration($value: ValueNode, _node: AnyNode, { filename, src, logger }: ValidateOptions) {
   if ($value.type === 'Number' && $value.value === 0) {
     return; // `0` is a valid number
   }
@@ -322,11 +290,11 @@ export function validateDuration($value, node, { filename, src, logger }) {
     if (!unit) {
       logger.error({ message: 'Missing required property "unit".', filename, node: $value, src });
     }
-    if (value.type !== 'Number') {
-      logger.error({ message: `Expected number, received ${value.type}`, filename, node: value, src });
+    if (value?.type !== 'Number') {
+      logger.error({ message: `Expected number, received ${value?.type}`, filename, node: value, src });
     }
-    if (!['ms', 's'].includes(unit.value)) {
-      logger.error({ message: `Expected unit "ms" or "s", received ${print(unit)}`, filename, node: unit, src });
+    if (!['ms', 's'].includes((unit as StringNode).value)) {
+      logger.error({ message: `Expected unit "ms" or "s", received ${print(unit!)}`, filename, node: unit, src });
     }
     return;
   }
@@ -334,13 +302,13 @@ export function validateDuration($value, node, { filename, src, logger }) {
   if ($value.type !== 'String') {
     logger.error({ message: `Expected string, received ${$value.type}`, filename, node: $value, src });
   }
-  const value = $value.value.match(/^-?[0-9.]+/)?.[0];
-  const unit = $value.value.replace(value, '');
-  if ($value.value === '') {
+  const value = ($value as StringNode).value.match(/^-?[0-9.]+/)?.[0]!;
+  const unit = ($value as StringNode).value.replace(value, '');
+  if (($value as StringNode).value === '') {
     logger.error({ message: 'Expected duration, received empty string', filename, node: $value, src });
   } else if (!['ms', 's'].includes(unit)) {
     logger.error({
-      message: `Expected unit "ms" or "s", received ${JSON.stringify(unit || $value.value)}`,
+      message: `Expected unit "ms" or "s", received ${JSON.stringify(unit || ($value as StringNode).value)}`,
       filename,
       node: $value,
       src,
@@ -350,14 +318,8 @@ export function validateDuration($value, node, { filename, src, logger }) {
   }
 }
 
-/**
- * Verify a Font Family token is valid
- * @param {ValueNode} $value
- * @param {AnyNode} node
- * @param {ValidateOptions} options
- * @return {void}
- */
-export function validateFontFamily($value, node, { filename, src, logger }) {
+/**  Verify a Font Family token is valid */
+export function validateFontFamily($value: ValueNode, _node: AnyNode, { filename, src, logger }: ValidateOptions) {
   if ($value.type !== 'String' && $value.type !== 'Array') {
     logger.error({
       message: `Expected string or array of strings, received ${$value.type}`,
@@ -379,14 +341,8 @@ export function validateFontFamily($value, node, { filename, src, logger }) {
   }
 }
 
-/**
- * Verify a Font Weight token is valid
- * @param {ValueNode} $value
- * @param {AnyNode} node
- * @param {ValidateOptions} options
- * @return {void}
- */
-export function validateFontWeight($value, node, { filename, src, logger }) {
+/** Verify a Font Weight token is valid */
+export function validateFontWeight($value: ValueNode, _node: AnyNode, { filename, src, logger }: ValidateOptions) {
   if ($value.type !== 'String' && $value.type !== 'Number') {
     logger.error({
       message: `Expected a font weight name or number 0–1000, received ${$value.type}`,
@@ -408,14 +364,8 @@ export function validateFontWeight($value, node, { filename, src, logger }) {
   }
 }
 
-/**
- * Verify a Gradient token is valid
- * @param {ValueNode} $value
- * @param {AnyNode} node
- * @param {ValidateOptions} options
- * @return {void}
- */
-export function validateGradient($value, node, { filename, src, logger }) {
+/** Verify a Gradient token is valid */
+export function validateGradient($value: ValueNode, _node: AnyNode, { filename, src, logger }: ValidateOptions) {
   if ($value.type !== 'Array') {
     logger.error({
       message: `Expected array of gradient stops, received ${$value.type}`,
@@ -423,92 +373,68 @@ export function validateGradient($value, node, { filename, src, logger }) {
       node: $value,
       src,
     });
-    return;
-  }
-  for (let i = 0; i < $value.elements.length; i++) {
-    const element = $value.elements[i];
-    if (element.value.type !== 'Object') {
-      logger.error({
-        message: `Stop #${i + 1}: Expected gradient stop, received ${element.value.type}`,
-        filename,
-        node: element,
-        src,
-      });
-      break;
+  } else {
+    for (let i = 0; i < $value.elements.length; i++) {
+      const element = $value.elements[i]!;
+      if (element.value.type !== 'Object') {
+        logger.error({
+          message: `Stop #${i + 1}: Expected gradient stop, received ${element.value.type}`,
+          filename,
+          node: element,
+          src,
+        });
+        break;
+      }
+      validateMembersAs(
+        element.value,
+        {
+          color: { validator: validateColor, required: true },
+          position: { validator: validateNumber, required: true },
+        },
+        element,
+        { filename, src, logger },
+      );
     }
-    validateMembersAs(
-      element.value,
-      {
-        color: { validator: validateColor, required: true },
-        position: { validator: validateNumber, required: true },
-      },
-      element,
-      { filename, src, logger },
-    );
   }
 }
 
-/**
- * Verify a Number token is valid
- * @param {ValueNode} $value
- * @param {AnyNode} node
- * @param {ValidateOptions} options
- * @return {void}
- */
-export function validateNumber($value, node, { filename, src, logger }) {
+/** Verify a Number token is valid */
+export function validateNumber($value: ValueNode, _node: AnyNode, { filename, src, logger }: ValidateOptions) {
   if ($value.type !== 'Number') {
     logger.error({ message: `Expected number, received ${$value.type}`, filename, node: $value, src });
   }
 }
 
-/**
- * Verify a Boolean token is valid
- * @param {ValueNode} $value
- * @param {AnyNode} node
- * @param {ValidateOptions} options
- * @return {void}
- */
-export function validateBoolean($value, node, { filename, src, logger }) {
+/** Verify a Boolean token is valid */
+export function validateBoolean($value: ValueNode, _node: AnyNode, { filename, src, logger }: ValidateOptions) {
   if ($value.type !== 'Boolean') {
     logger.error({ message: `Expected boolean, received ${$value.type}`, filename, node: $value, src });
   }
 }
 
-/**
- * Verify a Shadow token’s value is valid
- * @param {ValueNode} $value
- * @param {AnyNode} node
- * @param {ValidateOptions} options
- * @return {void}
- */
-export function validateShadowLayer($value, node, { filename, src, logger }) {
+/** Verify a Shadow token’s value is valid */
+export function validateShadowLayer($value: ValueNode, node: AnyNode, { filename, src, logger }: ValidateOptions) {
   if ($value.type !== 'Object') {
     logger.error({ message: `Expected Object, received ${$value.type}`, filename, node: $value, src });
-    return;
+  } else {
+    validateMembersAs(
+      $value,
+      {
+        color: { validator: validateColor, required: true },
+        offsetX: { validator: validateDimension, required: true },
+        offsetY: { validator: validateDimension, required: true },
+        blur: { validator: validateDimension },
+        spread: { validator: validateDimension },
+        inset: { validator: validateBoolean },
+      },
+      node,
+      { filename, src, logger },
+    );
   }
-  validateMembersAs(
-    $value,
-    {
-      color: { validator: validateColor, required: true },
-      offsetX: { validator: validateDimension, required: true },
-      offsetY: { validator: validateDimension, required: true },
-      blur: { validator: validateDimension },
-      spread: { validator: validateDimension },
-      inset: { validator: validateBoolean },
-    },
-    node,
-    { filename, src, logger },
-  );
 }
 
-/**
- * Verify a Stroke Style token is valid.
- * @param {ValueNode} $value
- * @param {AnyNode} node
- * @param {ValidateOptions} options
- * @return {void}
- */
-export function validateStrokeStyle($value, node, { filename, src, logger }) {
+/** Verify a Stroke Style token is valid. */
+export function validateStrokeStyle($value: ValueNode, node: AnyNode, { filename, src, logger }: ValidateOptions) {
   // note: strokeStyle’s values are NOT aliasable (unless by string, but that breaks validations)
   if ($value.type === 'String') {
     if (!STROKE_STYLE_VALUES.has($value.value)) {
@@ -531,7 +457,7 @@ export function validateStrokeStyle($value, node, { filename, src, logger }) {
     const { lineCap, dashArray } = strokeMembers;
     if (lineCap?.type !== 'String' || !STROKE_STYLE_LINE_CAP_VALUES.has(lineCap.value)) {
       logger.error({
-        message: `Unknown lineCap value ${print(lineCap)}. Expected one of: ${listFormat.format([
+        message: `Unknown lineCap value ${print(lineCap!)}. Expected one of: ${listFormat.format([
           ...STROKE_STYLE_LINE_CAP_VALUES,
         ])}.`,
       });
@@ -554,62 +480,55 @@ export function validateStrokeStyle($value, node, { filename, src, logger }) {
         }
       }
     } else {
-      logger.error({ message: `Expected array of strings, received ${dashArray.type}`, filename, node: $value, src });
+      logger.error({ message: `Expected array of strings, received ${dashArray!.type}`, filename, node: $value, src });
     }
   } else {
     logger.error({ message: `Expected string or object, received ${$value.type}`, filename, node: $value, src });
   }
 }
 
-/**
- * Verify a Transition token is valid
- * @param {ValueNode} $value
- * @param {AnyNode} node
- * @param {ValidateOptions} options
- * @return {void}
- */
-export function validateTransition($value, node, { filename, src, logger }) {
+/** Verify a Transition token is valid */
+export function validateTransition($value: ValueNode, node: AnyNode, { filename, src, logger }: ValidateOptions) {
   if ($value.type !== 'Object') {
     logger.error({ message: `Expected object, received ${$value.type}`, filename, node: $value, src });
-    return;
+  } else {
+    validateMembersAs(
+      $value,
+      {
+        duration: { validator: validateDuration, required: true },
+        delay: { validator: validateDuration, required: false }, // note: spec says delay is required, but Terrazzo makes delay optional
+        timingFunction: { validator: validateCubicBezier, required: true },
+      },
+      node,
+      { filename, src, logger },
+    );
   }
-  validateMembersAs(
-    $value,
-    {
-      duration: { validator: validateDuration, required: true },
-      delay: { validator: validateDuration, required: false }, // note: spec says delay is required, but Terrazzo makes delay optional
-      timingFunction: { validator: validateCubicBezier, required: true },
-    },
-    node,
-    { filename, src, logger },
-  );
 }
 
 /**
- * Validate a MemberNode (the entire token object, plus its key in the parent object) to see if it’s a valid DTCG token or not.
- * Keeping the parent key really helps in debug messages.
- * @param {AnyNode} node
- * @param {ValidateOptions} options
- * @return {void}
+ * Validate a MemberNode (the entire token object, plus its key in the parent
+ * object) to see if it’s a valid DTCG token or not. Keeping the parent key
+ * really helps in debug messages.
  */
-export default function validate(node, { filename, src, logger }) {
+export default function validate(node: MemberNode, { filename, src, logger }: ValidateOptions) {
   if (node.type !== 'Member' && node.type !== 'Object') {
     logger.error({
-      message: `Expected Object, received ${JSON.stringify(node.type)}`,
+      message: `Expected Object, received ${JSON.stringify(
+        // @ts-ignore Yes, TypeScript, this SHOULD be unexpected. This is why we’re validating.
+        node.type,
+      )}`,
       filename,
       node,
       src,
     });
-    return;
   }
 
   const rootMembers = node.value.type === 'Object' ? getObjMembers(node.value) : {};
-  const $value = rootMembers.$value;
-  const $type = rootMembers.$type;
+  const $value = rootMembers.$value as ValueNode;
+  const $type = rootMembers.$type as StringNode;
 
   if (!$value) {
     logger.error({ message: 'Token missing $value', filename, node, src });
-    return;
   }
   // If top-level value is a valid alias, this is valid (no need for $type)
   // ⚠️ Important: ALL Object and Array nodes below will need to check for aliases within!
@@ -620,7 +539,6 @@ export default function validate(node, { filename, src, logger }) {
 
   if (!$type) {
     logger.error({ message: 'Token missing $type', filename, node, src });
-    return;
   }
 
   switch ($type.value) {