@terrazzo/parser 0.10.2 → 0.10.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terrazzo/parser",
-  "version": "0.10.2",
+  "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.2"
+    "@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/parse/index.ts

@@ -7,7 +7,7 @@ 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, { getInheritedType, type Visitors } from './validate.js';
+import validateTokenNode, { computeInheritedProperty, isGroupNode, type Visitors } from './validate.js';
 
 export * from './alias.js';
 export * from './json.js';
@@ -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/validate.ts

@@ -1,5 +1,6 @@
 import {
   type AnyNode,
+  type BooleanNode,
   evaluate,
   type MemberNode,
   type ObjectNode,
@@ -771,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;
@@ -812,6 +832,7 @@ export interface ValidateTokenNodeOptions {
   logger: Logger;
   parent: AnyNode | undefined;
   transform?: Visitors;
+  inheritedDeprecatedNode?: MemberNode;
   inheritedTypeNode?: MemberNode;
 }
 
@@ -822,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') {
@@ -850,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;
   }
@@ -881,6 +927,7 @@ export default function validateTokenNode(
   const token = {
     $type,
     $value,
+    $deprecated,
     id,
     mode: {},
     originalValue: evaluate(node.value),