@terrazzo/parser 0.10.1 → 0.10.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terrazzo/parser",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "description": "Parser/validator for the Design Tokens Community Group (DTCG) standard.",
   "license": "MIT",
   "type": "module",
@@ -42,14 +42,14 @@
     "picocolors": "^1.1.1",
     "scule": "^1.3.0",
     "wildcard-match": "^5.1.4",
-    "@terrazzo/token-tools": "^0.10.1"
+    "@terrazzo/token-tools": "^0.10.3"
   },
   "devDependencies": {
     "yaml-to-momoa": "^0.0.3"
   },
   "scripts": {
     "build": "rolldown -c && attw --profile esm-only --pack .",
-    "dev": "pnpm run build --watch",
+    "dev": "rolldown -w -c",
     "lint": "pnpm --filter @terrazzo/parser run \"/^lint:(js|ts)/\"",
     "lint:js": "biome check .",
     "lint:ts": "tsc --noEmit",

package/src/build/index.ts

@@ -18,7 +18,11 @@ function validateTransformParams({
   params,
   logger,
   pluginName,
-}: { params: TokenTransformed; logger: Logger; pluginName: string }): void {
+}: {
+  params: TokenTransformed;
+  logger: Logger;
+  pluginName: string;
+}): void {
   const baseMessage: LogEntry = { group: 'plugin', label: pluginName, message: '' };
 
   // validate value is valid for SINGLE_VALUE or MULTI_VALUE

package/src/config.ts

@@ -48,7 +48,12 @@ function normalizeTokens({
   config,
   logger,
   cwd,
-}: { rawConfig: Config; config: ConfigInit; logger: Logger; cwd: URL }) {
+}: {
+  rawConfig: Config;
+  config: ConfigInit;
+  logger: Logger;
+  cwd: URL;
+}) {
   if (rawConfig.tokens === undefined) {
     config.tokens = [
       // @ts-ignore we’ll normalize in next step
@@ -89,7 +94,7 @@ function normalizeTokens({
     }
     try {
       config.tokens[i] = new URL(filepath, cwd);
-    } catch (err) {
+    } catch {
       logger.error({ group: 'config', label: 'tokens', message: `Invalid URL ${filepath}` });
     }
   }

package/src/index.ts

@@ -1,20 +1,3 @@
-export { default as build } from './build/index.js';
-export * from './build/index.js';
-
-export { default as defineConfig } from './config.js';
-export * from './config.js';
-
-export { default as lintRunner } from './lint/index.js';
-export * from './lint/index.js';
-
-export { default as Logger } from './logger.js';
-export * from './logger.js';
-
-export { default as parse } from './parse/index.js';
-export * from './parse/index.js';
-
-export * from './types.js';
-
 export type {
   AliasToken,
   AliasValue,
@@ -91,3 +74,20 @@ export type {
   TypographyValue,
   TypographyValueNormalized,
 } from '@terrazzo/token-tools';
+
+export * from './build/index.js';
+export { default as build } from './build/index.js';
+
+export * from './config.js';
+export { default as defineConfig } from './config.js';
+
+export * from './lint/index.js';
+export { default as lintRunner } from './lint/index.js';
+
+export * from './logger.js';
+export { default as Logger } from './logger.js';
+
+export * from './parse/index.js';
+export { default as parse } from './parse/index.js';
+
+export * from './types.js';

package/src/lint/index.ts

@@ -1,4 +1,4 @@
-import { type TokenNormalized, pluralize } from '@terrazzo/token-tools';
+import { pluralize, type TokenNormalized } from '@terrazzo/token-tools';
 import { merge } from 'merge-anything';
 import type { LogEntry, default as Logger } from '../logger.js';
 import type { ConfigInit } from '../types.js';

package/src/parse/alias.ts

@@ -2,14 +2,14 @@ import type { AnyNode, ArrayNode, ObjectNode } from '@humanwhocodes/momoa';
 import {
   type BorderTokenNormalized,
   type GradientTokenNormalized,
+  isAlias,
+  parseAlias,
   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';

package/src/parse/index.ts

@@ -1,5 +1,5 @@
-import { type DocumentNode, type MemberNode, type ObjectNode, evaluate } from '@humanwhocodes/momoa';
-import { type Token, type TokenNormalized, pluralize, splitID } from '@terrazzo/token-tools';
+import { type DocumentNode, evaluate, type MemberNode, type ObjectNode } from '@humanwhocodes/momoa';
+import { pluralize, splitID, type Token, type TokenNormalized } from '@terrazzo/token-tools';
 import type ytm from 'yaml-to-momoa';
 import lintRunner from '../lint/index.js';
 import Logger from '../logger.js';
@@ -7,11 +7,11 @@ import type { ConfigInit, InputSource } from '../types.js';
 import applyAliases from './alias.js';
 import { getObjMembers, parseJSON, replaceObjMembers, toMomoa, traverse } from './json.js';
 import normalize from './normalize.js';
-import validateTokenNode, { type Visitors, getInheritedType } from './validate.js';
+import validateTokenNode, { computeInheritedProperty, isGroupNode, type Visitors } from './validate.js';
 
 export * from './alias.js';
-export * from './normalize.js';
 export * from './json.js';
+export * from './normalize.js';
 export * from './validate.js';
 export { normalize, validateTokenNode };
 
@@ -210,16 +210,24 @@ async function parseSingle(
   // 2. Walk AST to validate tokens
   let tokenCount = 0;
   const startValidate = performance.now();
+  // $type and $deprecated can be applied at group level to target all child tokens,
+  // these two objects keep track of inherited prop values as we traverse the token tree
   const $typeInheritance: Record<string, MemberNode> = {};
+  const $deprecatedInheritance: Record<string, MemberNode> = {};
   traverse(document, {
     enter(node, parent, subpath) {
       // if $type appears at root of tokens.json, collect it
       if (node.type === 'Document' && node.body.type === 'Object' && node.body.members) {
         const { members: rootMembers } = node.body;
-        const root$type = rootMembers.find((m) => m.name.type === 'String' && m.name.value === '$type');
-        const root$value = rootMembers.find((m) => m.name.type === 'String' && m.name.value === '$value');
-        if (root$type && !root$value) {
-          $typeInheritance['.'] = root$type;
+        if (isGroupNode(node.body)) {
+          const root$type = rootMembers.find((m) => m.name.type === 'String' && m.name.value === '$type');
+          if (root$type) {
+            $typeInheritance['.'] = root$type;
+          }
+          const root$deprecated = rootMembers.find((m) => m.name.type === 'String' && m.name.value === '$deprecated');
+          if (root$deprecated) {
+            $deprecatedInheritance['.'] = root$deprecated;
+          }
         }
       }
 
@@ -241,13 +249,15 @@ async function parseSingle(
 
       // handle tokens
       if (node.type === 'Member') {
-        const inheritedTypeNode = getInheritedType(node, { subpath, $typeInheritance });
+        const inheritedDeprecatedNode = computeInheritedProperty(node, '$deprecated', {
+          subpath,
+          inherited: $deprecatedInheritance,
+        });
+        const inheritedTypeNode = computeInheritedProperty(node, '$type', { subpath, inherited: $typeInheritance });
         if (node.value.type === 'Object') {
-          const $type =
-            node.value.members.find((m) => m.name.type === 'String' && m.name.value === '$type') || inheritedTypeNode;
           const $value = node.value.members.find((m) => m.name.type === 'String' && m.name.value === '$value');
-          if ($value && $type?.value.type === 'String' && transform?.[$type.value.value]) {
-            const result = transform[$type.value.value]?.(evaluate(node.value), subpath.join('.'), node);
+          if ($value && inheritedTypeNode?.value.type === 'String' && transform?.[inheritedTypeNode.value.value]) {
+            const result = transform[inheritedTypeNode.value.value]?.(evaluate(node.value), subpath.join('.'), node);
             if (result) {
               node.value = parseJSON(result).body;
             }
@@ -261,6 +271,7 @@ async function parseSingle(
             parent,
             subpath,
             transform,
+            inheritedDeprecatedNode,
             inheritedTypeNode,
           });
           if (token) {

package/src/parse/json.ts

@@ -2,11 +2,11 @@ import {
   type AnyNode,
   type DocumentNode,
   type MemberNode,
+  parse as momoaParse,
   type ObjectNode,
   type ParseOptions,
-  type ValueNode,
-  parse as momoaParse,
   print,
+  type ValueNode,
 } from '@humanwhocodes/momoa';
 import type yamlToMomoa from 'yaml-to-momoa';
 import type Logger from '../logger.js';

package/src/parse/normalize.ts

@@ -5,12 +5,12 @@ import {
   type FontFamilyValue,
   type GradientStopNormalized,
   type GradientValueNormalized,
+  isAlias,
+  parseColor,
   type ShadowValueNormalized,
   type Token,
   type TransitionValue,
   type TypographyValueNormalized,
-  isAlias,
-  parseColor,
 } from '@terrazzo/token-tools';
 
 export const FONT_WEIGHT_MAP = {

package/src/parse/validate.ts

@@ -1,13 +1,14 @@
 import {
   type AnyNode,
+  type BooleanNode,
+  evaluate,
   type MemberNode,
   type ObjectNode,
+  print,
   type StringNode,
   type ValueNode,
-  evaluate,
-  print,
 } from '@humanwhocodes/momoa';
-import { type Token, type TokenNormalized, isAlias, splitID } from '@terrazzo/token-tools';
+import { isAlias, splitID, type Token, type TokenNormalized } from '@terrazzo/token-tools';
 import wcmatch from 'wildcard-match';
 import type Logger from '../logger.js';
 import type { ConfigInit } from '../types.js';
@@ -559,10 +560,12 @@ export function validateStrokeStyle($value: ValueNode, node: AnyNode, { filename
           } else {
             validateDimension(element.value, node, { logger, src });
           }
+        } else if (element.value.type === 'Object') {
+          validateDimension(element.value, node, { logger, src });
         } else {
           logger.error({
             ...baseMessage,
-            message: 'Expected array of strings, recieved some non-strings or empty strings.',
+            message: `Expected array of dimensions, received ${element.value.type}.`,
             node: element,
           });
         }
@@ -769,28 +772,47 @@ export function validateTokenMemberNode(node: MemberNode, { filename, src, logge
   }
 }
 
-/** Return any token node with its inherited $type */
-export function getInheritedType(
+/** Return whether a MemberNode is a group (has no `$value`).
+ * Groups can have properties that their child nodes will inherit. */
+export function isGroupNode(node: ObjectNode): boolean {
+  if (node.type !== 'Object') {
+    return false;
+  }
+
+  // check for $value
+  const has$value = node.members.some((m) => m.name.type === 'String' && m.name.value === '$value');
+  return !has$value;
+}
+
+/** Check if a token node has the specified property name, and if it does, stores
+ * the value in the `inherited` object as a side effect for future use. If not,
+ * traverses the `inherited` object to find the closest parent that has the property.
+ *
+ * Returns the property value if found locally or in a parent, otherwise undefined. */
+export function computeInheritedProperty(
   node: MemberNode,
-  { subpath, $typeInheritance }: { subpath: string[]; $typeInheritance?: Record<string, MemberNode> },
+  propertyName: string,
+  { subpath, inherited }: { subpath: string[]; inherited?: 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;
-  }
+  // if property exists locally in the token node, add it to the inherited tree
+  const property = node.value.members.find((m) => m.name.type === 'String' && m.name.value === propertyName);
+  if (inherited && property && isGroupNode(node.value)) {
+    // this is where the side effect occurs
+    inherited[subpath.join('.') || '.'] = property;
 
-  const id = subpath.join('.');
+    // We know this is the closest property, so return early
+    return property;
+  }
 
   // get parent type by taking the closest-scoped $type (length === closer)
+  const id = subpath.join('.');
   let parent$type: MemberNode | undefined;
   let longestPath = '';
-  for (const [k, v] of Object.entries($typeInheritance ?? {})) {
+  for (const [k, v] of Object.entries(inherited ?? {})) {
     if (k === '.' || id.startsWith(k)) {
       if (k.length > longestPath.length) {
         parent$type = v;
@@ -810,6 +832,7 @@ export interface ValidateTokenNodeOptions {
   logger: Logger;
   parent: AnyNode | undefined;
   transform?: Visitors;
+  inheritedDeprecatedNode?: MemberNode;
   inheritedTypeNode?: MemberNode;
 }
 
@@ -820,7 +843,16 @@ export interface ValidateTokenNodeOptions {
  */
 export default function validateTokenNode(
   node: MemberNode,
-  { config, filename, logger, parent, inheritedTypeNode, src, subpath }: ValidateTokenNodeOptions,
+  {
+    config,
+    filename,
+    logger,
+    parent,
+    inheritedDeprecatedNode,
+    inheritedTypeNode,
+    src,
+    subpath,
+  }: ValidateTokenNodeOptions,
 ): TokenNormalized | undefined {
   // don’t validate $value
   if (subpath.includes('$value') || node.value.type !== 'Object') {
@@ -848,17 +880,33 @@ export default function validateTokenNode(
   }
 
   const nodeWithType = structuredClone(node);
+  // inject $type that can be inherited in the DTCG format
   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;
   }
+
+  // inject $deprecated that can also be inherited
+  let $deprecated = members.$deprecated
+    ? members.$deprecated?.type === 'String'
+      ? (members.$deprecated as StringNode).value
+      : (members.$deprecated as BooleanNode).value
+    : undefined;
+  if (inheritedDeprecatedNode && !members.$deprecated) {
+    injectObjMembers(nodeWithType.value as ObjectNode, [inheritedDeprecatedNode]);
+    $deprecated =
+      inheritedDeprecatedNode.value.type === 'String'
+        ? (inheritedDeprecatedNode.value as StringNode).value
+        : (inheritedDeprecatedNode.value as BooleanNode).value;
+  }
+
+  // validate once after injecting all inherited properties
   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
   // $deprecated, we can omit it from the output.
-  const $deprecated = members.$deprecated && (evaluate(members.$deprecated) as string | boolean | undefined);
   if ((config.ignore.deprecated && $deprecated) || (config.ignore.tokens && wcmatch(config.ignore.tokens)(id))) {
     return;
   }
@@ -879,6 +927,7 @@ export default function validateTokenNode(
   const token = {
     $type,
     $value,
+    $deprecated,
     id,
     mode: {},
     originalValue: evaluate(node.value),