@terrazzo/parser 2.0.0-alpha.0 → 2.0.0-alpha.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terrazzo/parser",
-  "version": "2.0.0-alpha.0",
+  "version": "2.0.0-alpha.2",
   "description": "Parser/validator for the Design Tokens Community Group (DTCG) standard.",
   "license": "MIT",
   "type": "module",
@@ -42,8 +42,8 @@
     "picocolors": "^1.1.1",
     "scule": "^1.3.0",
     "wildcard-match": "^5.1.4",
-    "@terrazzo/token-tools": "^2.0.0-alpha.0",
-    "@terrazzo/json-schema-tools": "^0.0.1"
+    "@terrazzo/json-schema-tools": "^0.0.1",
+    "@terrazzo/token-tools": "^2.0.0-alpha.2"
   },
   "devDependencies": {
     "yaml-to-momoa": "0.0.6"

package/src/build/index.ts

@@ -9,7 +9,6 @@ export interface BuildRunnerOptions {
   config: ConfigInit;
   logger?: Logger;
 }
-
 export const SINGLE_VALUE = 'SINGLE_VALUE';
 export const MULTI_VALUE = 'MULTI_VALUE';
 
@@ -87,6 +86,7 @@ export default async function build(
   for (const plugin of config.plugins) {
     if (typeof plugin.transform === 'function') {
       await plugin.transform({
+        context: { logger },
         tokens,
         sources,
         getTransforms,
@@ -151,6 +151,7 @@ export default async function build(
       if (typeof plugin.build === 'function') {
         const pluginBuildStart = performance.now();
         await plugin.build({
+          context: { logger },
           tokens,
           sources,
           getTransforms,
@@ -184,7 +185,15 @@ export default async function build(
   // buildEnd()
   const startBuildEnd = performance.now();
   await Promise.all(
-    config.plugins.map(async (plugin) => plugin.buildEnd?.({ outputFiles: structuredClone(result.outputFiles) })),
+    config.plugins.map(async (plugin) =>
+      plugin.buildEnd?.({
+        context: { logger },
+        tokens,
+        getTransforms,
+        sources,
+        outputFiles: structuredClone(result.outputFiles),
+      }),
+    ),
   );
   logger.debug({
     group: 'parser',

package/src/parse/token.ts

@@ -284,7 +284,10 @@ export function graphAliases(refMap: RefMap, { tokens, logger, sources }: GraphA
         }
         // last node: apply partial alias
         if (i === partial.length - 1) {
-          const aliasedID = getTokenRef(refChain.at(-1)!);
+          // important: we want to get only the immediate alias [0], not the final one [.length - 1].
+          // if we resolve this too far, we could get incorrect values especially in plugin-css if a
+          // user is applying cascades to the intermediate aliases but not the final one
+          const aliasedID = getTokenRef(refChain[0]!);
           if (!(aliasedID in tokens)) {
             logger.error({
               group: 'parser',

package/src/types.ts

@@ -3,7 +3,13 @@ import type { TokenNormalized } from '@terrazzo/token-tools';
 import type ytm from 'yaml-to-momoa';
 import type Logger from './logger.js';
 
+export interface PluginHookContext {
+  logger: Logger;
+}
+
 export interface BuildHookOptions {
+  /** Plugin hook context (provides access to shared logger) */
+  context: PluginHookContext;
   /** Map of tokens */
   tokens: Record<string, TokenNormalized>;
   /** Query transformed values */
@@ -19,10 +25,12 @@ export interface BuildHookOptions {
 }
 
 export interface BuildRunnerResult {
-  outputFiles: OutputFile[];
+  outputFiles: OutputFileExpanded[];
 }
 
 export interface BuildEndHookOptions {
+  /** Plugin hook context (provides access to shared logger) */
+  context: PluginHookContext;
   /** Map of tokens */
   tokens: Record<string, TokenNormalized>;
   /** Query transformed values */
@@ -299,17 +307,14 @@ export interface Plugin {
   lint?(): Record<string, LintRule<any, any, any>>;
   transform?(options: TransformHookOptions): Promise<void>;
   build?(options: BuildHookOptions): Promise<void>;
-  buildEnd?(result: BuildRunnerResult): Promise<void>;
+  buildEnd?(options: BuildEndHookOptions): Promise<void>;
 }
 
-/** Transformed token with a single value. Note that this may be any type! */
-export interface TokenTransformedSingleValue {
+interface TokenTransformedBase {
   /** Original Token ID */
   id: string;
   /** ID unique to this format. */
   localID?: string;
-  type: 'SINGLE_VALUE';
-  value: string;
   /**
    * The mode of this value
    * @default "."
@@ -317,23 +322,27 @@ export interface TokenTransformedSingleValue {
   mode: string;
   /** The original token. */
   token: TokenNormalized;
+  /** Arbitrary metadata set by plugins. */
+  meta?: Record<string | number | symbol, unknown> & {
+    /**
+     * Metadata for the token-listing plugin. Plugins can
+     * set this to be the name of a token as it appears in code,
+     * and the token-listing plugin will pick it up and use it.
+     */
+    'token-listing'?: { name: string | undefined };
+  };
+}
+
+/** Transformed token with a single value. Note that this may be any type! */
+export interface TokenTransformedSingleValue extends TokenTransformedBase {
+  type: 'SINGLE_VALUE';
+  value: string;
 }
 
 /** Transformed token with multiple values. Note that this may be any type! */
-export interface TokenTransformedMultiValue {
-  /** Original Token ID */
-  id: string;
-  /** ID unique to this format.*/
-  localID?: string;
+export interface TokenTransformedMultiValue extends TokenTransformedBase {
   type: 'MULTI_VALUE';
   value: Record<string, string>;
-  /**
-   * The mode of this value
-   * @default "."
-   */
-  mode: string;
-  /** The original token */
-  token: TokenNormalized;
 }
 
 export type TokenTransformed = TokenTransformedSingleValue | TokenTransformedMultiValue;
@@ -353,6 +362,8 @@ export interface TransformParams {
 }
 
 export interface TransformHookOptions {
+  /** Plugin hook context (provides access to shared logger) */
+  context: PluginHookContext;
   /** Map of tokens */
   tokens: Record<string, TokenNormalized>;
   /** Query transformed values */
@@ -365,6 +376,7 @@ export interface TransformHookOptions {
       localID?: string;
       value: string | Record<string, string>; // allow looser type for input (`undefined` will just get stripped)
       mode?: string;
+      meta?: TokenTransformedBase['meta'];
     },
   ): void;
   /** Momoa documents */