@terrazzo/parser 0.0.11 → 0.0.12

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# @terrazzo/parser
+
+## 0.0.12
+
+### Patch Changes
+
+- [#285](https://github.com/terrazzoapp/terrazzo/pull/285) [`e8a0df1`](https://github.com/terrazzoapp/terrazzo/commit/e8a0df1f3b50cf7cb292bcc475aae271feae4569) Thanks [@drwpow](https://github.com/drwpow)! - Add support for multiple token files
+
+- Updated dependencies [[`e8a0df1`](https://github.com/terrazzoapp/terrazzo/commit/e8a0df1f3b50cf7cb292bcc475aae271feae4569)]:
+  - @terrazzo/token-tools@0.0.6

package/build/index.d.ts

@@ -4,7 +4,7 @@ import type { ConfigInit } from '../config.js';
 import type Logger from '../logger.js';
 
 export interface BuildRunnerOptions {
-  ast: DocumentNode;
+  sources: { filename?: URL; src: string; document: DocumentNode }[];
   config: ConfigInit;
   logger?: Logger;
 }
@@ -73,8 +73,8 @@ export interface TransformHookOptions {
       mode?: string;
     },
   ): void;
-  /** Momoa document */
-  ast: DocumentNode;
+  /** Momoa documents */
+  sources: { filename?: URL; src: string; document: DocumentNode }[];
 }
 
 export interface BuildHookOptions {
@@ -82,8 +82,8 @@ export interface BuildHookOptions {
   tokens: Record<string, TokenNormalized>;
   /** Query transformed values */
   getTransforms(params: TransformParams): TokenTransformed[];
-  /** Momoa document */
-  ast: DocumentNode;
+  /** Momoa documents */
+  sources: { filename?: URL; src: string; document: DocumentNode }[];
   outputFile: (
     /** Filename to output (relative to outDir) */
     filename: string,
@@ -101,8 +101,8 @@ export interface BuildEndHookOptions {
   tokens: Record<string, TokenNormalized>;
   /** Query transformed values */
   getTransforms(params: TransformParams): TokenTransformed[];
-  /** Momoa document */
-  ast: DocumentNode;
+  /** Momoa documents */
+  sources: { filename?: URL; src: string; document: DocumentNode }[];
   /** Final files to be written */
   outputFiles: OutputFileExpanded[];
 }

package/build/index.js

@@ -5,7 +5,7 @@ import Logger from '../logger.js';
 /**
  * @typedef {object} BuildRunnerOptions
  * @typedef {Record<string, TokenNormalized>} BuildRunnerOptions.tokens
- * @typedef {DocumentNode} BuildRunnerOptions.ast
+ * @typedef {Array} BuildRunnerOptions.sources
  * @typedef {ConfigInit} BuildRunnerOptions.config
  * @typedef {Logger} BuildRunnerOptions.logger
  * @typedef {import("@humanwhocodes/momoa").DocumentNode} DocumentNode
@@ -60,7 +60,7 @@ function validateTransformParams({ params, token, logger, pluginName }) {
  * @param {BuildOptions} options
  * @return {Promise<BuildResult>}
  */
-export default async function build(tokens, { ast, logger = new Logger(), config }) {
+export default async function build(tokens, { sources, logger = new Logger(), config }) {
   const formats = {};
   const result = { outputFiles: [] };
 
@@ -95,7 +95,7 @@ export default async function build(tokens, { ast, logger = new Logger(), config
     if (typeof plugin.transform === 'function') {
       await plugin.transform({
         tokens,
-        ast,
+        sources,
         getTransforms,
         setTransform(id, params) {
           if (transformsLocked) {
@@ -165,7 +165,7 @@ export default async function build(tokens, { ast, logger = new Logger(), config
       const pluginBuildStart = performance.now();
       await plugin.build({
         tokens,
-        ast,
+        sources,
         getTransforms,
         outputFile(filename, contents) {
           const resolved = new URL(filename, config.outDir);
@@ -196,7 +196,7 @@ export default async function build(tokens, { ast, logger = new Logger(), config
     if (typeof plugin.buildEnd === 'function') {
       await plugin.buildEnd({
         tokens,
-        ast,
+        sources,
         getTransforms,
         format: (formatID) => createFormatter(formatID),
         outputFiles: structruedClone(result.outputFiles),

package/lint/index.d.ts

@@ -26,7 +26,8 @@ export interface LinterOptions<O = any> {
     id: string;
     severity: LintRuleSeverity;
   };
-  ast: DocumentNode;
+  document: DocumentNode;
+  filename?: URL;
   source?: string;
   /** Any options the user has declared for this plugin */
   options?: O;
@@ -34,7 +35,8 @@ export interface LinterOptions<O = any> {
 export type Linter = (options: LinterOptions) => Promise<LintNotice[] | undefined>;
 
 export interface LintRunnerOptions {
-  ast: DocumentNode;
+  document: DocumentNode;
+  filename?: URL;
   config: ConfigInit;
   logger: Logger;
 }

package/logger.d.ts

@@ -13,12 +13,14 @@ export interface LogEntry {
   message: string;
   /** (optional) Prefix message with label */
   label?: string;
+  /** (optional) File in disk */
+  filename?: URL;
   /** Continue on error? (default: false) */
   continueOnError?: boolean;
   /** (optional) Show a code frame for the erring node */
   node?: AnyNode;
   /** (optional) To show a code frame, provide the original source code */
-  source?: string;
+  src?: string;
 }
 
 export interface DebugEntry {
@@ -29,7 +31,7 @@ export interface DebugEntry {
   /** Error message to be logged */
   message: string;
   /** (optional) Show code below message */
-  codeFrame?: { source: string; line: number; column: number };
+  codeFrame?: { src: string; line: number; column: number };
   /** (optional) Display performance timing */
   timing?: number;
 }

package/logger.js

@@ -1,5 +1,6 @@
 import { codeFrameColumns } from '@babel/code-frame';
 import color from 'picocolors';
+import { fileURLToPath } from 'node:url';
 import wcmatch from 'wildcard-match';
 
 export const LOG_ORDER = ['error', 'warn', 'info', 'debug'];
@@ -23,8 +24,9 @@ export function formatMessage(entry, severity) {
   if (severity in MESSAGE_COLOR) {
     message = MESSAGE_COLOR[severity](message);
   }
-  if (entry.source) {
-    message = `${message}\n\n${codeFrameColumns(entry.source, { start: entry.node?.loc?.start })}`;
+  if (entry.src) {
+    const start = entry.node?.loc?.start;
+    message = `${message}\n\n${entry.filename ? `${fileURLToPath(entry.filename)}:${start?.line ?? 0}:${start?.column ?? 0}\n\n` : ''}${codeFrameColumns(entry.src, { start })}`;
   }
   return message;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terrazzo/parser",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "Parser/validator for the Design Tokens Community Group (DTCG) standard.",
   "type": "module",
   "author": {
@@ -42,7 +42,7 @@
     "picocolors": "^1.0.1",
     "wildcard-match": "^5.1.3",
     "yaml": "^2.4.5",
-    "@terrazzo/token-tools": "^0.0.4"
+    "@terrazzo/token-tools": "^0.0.6"
   },
   "scripts": {
     "lint": "biome check .",

package/parse/index.d.ts

@@ -5,24 +5,32 @@ import type Logger from '../logger.js';
 
 export * from './validate.js';
 
+export interface ParseInput {
+  /** Source filename (if read from disk) */
+  filename?: URL;
+  /** JSON/YAML string, or JSON-serializable object (if already in memory) */
+  src: string | object;
+}
+
 export interface ParseOptions {
   logger?: Logger;
+  config: ConfigInit;
   /** Skip lint step (default: false) */
   skipLint?: boolean;
-  config: ConfigInit;
   /** Continue on error? (Useful for `tz check`) (default: false) */
   continueOnError?: boolean;
 }
 
 export interface ParseResult {
   tokens: Record<string, TokenNormalized>;
-  ast: DocumentNode;
+  /** ASTs are returned in order of input array */
+  sources: { filename?: URL; src: string; document: DocumentNode }[];
 }
 
 /**
  * Parse and validate Tokens JSON, and lint it
  */
-export default function parse(input: string | object, options?: ParseOptions): Promise<ParseResult>;
+export default function parse(input: ParseInput[], options?: ParseOptions): Promise<ParseResult>;
 
 /** Determine if an input is likely a JSON string */
 export function maybeJSONString(input: unknown): boolean;

package/parse/index.js

@@ -1,5 +1,6 @@
 import { evaluate, parse as parseJSON, print } from '@humanwhocodes/momoa';
 import { isAlias, parseAlias, pluralize, splitID } from '@terrazzo/token-tools';
+import { fileURLToPath } from 'node:url';
 import lintRunner from '../lint/index.js';
 import Logger from '../logger.js';
 import normalize from './normalize.js';
@@ -9,50 +10,189 @@ import { getObjMembers, injectObjMembers, traverse } from './json.js';
 
 export * from './validate.js';
 
+/** @typedef {import("@humanwhocodes/momoa").DocumentNode} DocumentNode */
+/** @typedef {import("../config.js").Plugin} Plugin */
+/** @typedef {import("../types.js").TokenNormalized} TokenNormalized */
 /**
- * @typedef {import("@humanwhocodes/momoa").DocumentNode} DocumentNode
- * @typedef {import("../config.js").Plugin} Plugin
- * @typedef {import("../types.js").TokenNormalized} TokenNormalized
- * @typedef {object} ParseOptions
- * @typedef {Logger} ParseOptions.logger
- * @typedef {boolean=false} ParseOptions.skipLint
- * @typedef {Plugin[]} ParseOptions.plugins
  * @typedef {object} ParseResult
- * @typedef {Record<string, TokenNormalized} ParseResult.tokens
- * @typedef {DocumentNode} ParseResult.ast
+ * @property {Record<string, TokenNormalized} tokens
+ * @property {Object[]} src
+ */
+/**
+ * @typedef {object} ParseInput
+ * @property {string | object} src
+ * @property {URL} [filename]
+ */
+/**
+ * @typedef {object} ParseOptions
+ * @property {Logger} logger
+ * @property {import("../config.js").Config} config
+ * @property {boolean} [skipLint=false]
+ * @property {boolean} [continueOnError=false]
  */
-
 /**
  * Parse
- * @param {string | object} input
- * @param {ParseOptions} options
+ * @param {ParseInput[]} input
+ * @param {ParseOptions} [options]
  * @return {Promise<ParseResult>}
  */
 export default async function parse(
   input,
-  { logger = new Logger(), skipLint = false, config, continueOnError = false } = {},
+  { logger = new Logger(), skipLint = false, config = {}, continueOnError = false } = {},
 ) {
-  const { plugins } = config;
+  let tokens = {};
+  // note: only keeps track of sources with locations on disk; in-memory sources are discarded
+  // (it’s only for reporting line numbers, which doesn’t mean as much for dynamic sources)
+  const sources = {};
+
+  if (!Array.isArray(input)) {
+    logger.error({ group: 'parser', task: 'init', message: 'Input must be an array of input objects.' });
+  }
+  for (let i = 0; i < input.length; i++) {
+    if (!input[i] || typeof input[i] !== 'object') {
+      logger.error({ group: 'parser', task: 'init', message: `Input (${i}) must be an object.` });
+    }
+    if (!input[i].src || (typeof input[i].src !== 'string' && typeof input[i].src !== 'object')) {
+      logger.error({
+        group: 'parser',
+        task: 'init',
+        message: `Input (${i}) missing "src" with a JSON/YAML string, or JSON object.`,
+      });
+    }
+    if (input[i].filename && !(input[i].filename instanceof URL)) {
+      logger.error({
+        group: 'parser',
+        task: 'init',
+        message: `Input (${i}) "filename" must be a URL (remote or file URL).`,
+      });
+    }
+
+    const result = await parseSingle(input[i].src, {
+      filename: input[i].filename,
+      logger,
+      config,
+      skipLint,
+      continueOnError,
+    });
+
+    tokens = Object.assign(tokens, result.tokens);
+    if (input[i].filename) {
+      sources[input[i].filename.protocol === 'file:' ? fileURLToPath(input[i].filename) : input[i].filename.href] = {
+        filename: input[i].filename,
+        src: result.src,
+        document: result.document,
+      };
+    }
+  }
 
   const totalStart = performance.now();
 
+  // 5. Resolve aliases and populate groups
+  for (const id in tokens) {
+    if (!Object.hasOwn(tokens, id)) {
+      continue;
+    }
+    const token = tokens[id];
+    applyAliases(token, {
+      tokens,
+      filename: sources[token.source.loc]?.filename,
+      src: sources[token.source.loc]?.src,
+      node: token.source.node,
+      logger,
+    });
+    token.mode['.'].$value = token.$value;
+    if (token.aliasOf) {
+      token.mode['.'].aliasOf = token.aliasOf;
+    }
+    if (token.partialAliasOf) {
+      token.mode['.'].partialAliasOf = token.partialAliasOf;
+    }
+    const { group: parentGroup } = splitID(id);
+    for (const siblingID in tokens) {
+      const { group: siblingGroup } = splitID(siblingID);
+      if (siblingGroup?.startsWith(parentGroup)) {
+        token.group.tokens.push(siblingID);
+      }
+    }
+  }
+
+  // 6. resolve mode aliases
+  const modesStart = performance.now();
+  logger.debug({
+    group: 'parser',
+    task: 'modes',
+    message: 'Start mode resolution',
+  });
+  for (const id in tokens) {
+    if (!Object.hasOwn(tokens, id)) {
+      continue;
+    }
+    for (const mode in tokens[id].mode) {
+      if (mode === '.') {
+        continue; // skip shadow of root value
+      }
+      applyAliases(tokens[id].mode[mode], { tokens, node: tokens[id].mode[mode].source.node, logger });
+    }
+  }
+  logger.debug({
+    group: 'parser',
+    task: 'modes',
+    message: 'Finish token modes',
+    timing: performance.now() - modesStart,
+  });
+
+  logger.debug({
+    group: 'parser',
+    task: 'core',
+    message: 'Finish all parser tasks',
+    timing: performance.now() - totalStart,
+  });
+
+  if (continueOnError) {
+    const { errorCount } = logger.stats();
+    if (errorCount > 0) {
+      logger.error({
+        message: `Parser encountered ${errorCount} ${pluralize(errorCount, 'error', 'errors')}. Exiting.`,
+      });
+    }
+  }
+
+  return {
+    tokens,
+    sources,
+  };
+}
+
+/**
+ * Parse a single input
+ * @param {string | object} input
+ * @param {object} options
+ * @param {URL} [options.filename]
+ * @param {Logger} [options.logger]
+ * @param {import("../config.js").Config} [options.config]
+ * @param {boolean} [options.skipLint]
+ */
+async function parseSingle(input, { filename, logger, config, skipLint, continueOnError = false }) {
   // 1. Build AST
-  let source;
+  let src;
   if (typeof input === 'string') {
-    source = input;
+    src = input;
   }
   const startParsing = performance.now();
   logger.debug({ group: 'parser', task: 'parse', message: 'Start tokens parsing' });
-  let ast;
+  let document;
   if (typeof input === 'string' && !maybeJSONString(input)) {
-    ast = parseYAML(input, { logger }); // if string, but not JSON, attempt YAML
+    document = parseYAML(input, { logger }); // if string, but not JSON, attempt YAML
   } else {
-    ast = parseJSON(typeof input === 'string' ? input : JSON.stringify(input, undefined, 2), {
-      mode: 'jsonc',
-    }); // everything else: assert it’s JSON-serializable
+    document = parseJSON(
+      typeof input === 'string' ? input : JSON.stringify(input, undefined, 2), // everything else: assert it’s JSON-serializable
+      {
+        mode: 'jsonc',
+      },
+    );
   }
-  if (!source) {
-    source = print(ast, { indent: 2 });
+  if (!src) {
+    src = print(document, { indent: 2 });
   }
   logger.debug({
     group: 'parser',
@@ -67,7 +207,7 @@ export default async function parse(
   const startValidation = performance.now();
   logger.debug({ group: 'parser', task: 'validate', message: 'Start tokens validation' });
   const $typeInheritance = {};
-  traverse(ast, {
+  traverse(document, {
     enter(node, parent, path) {
       if (node.type === 'Member' && node.value.type === 'Object' && node.value.members) {
         const members = getObjMembers(node.value);
@@ -96,7 +236,8 @@ export default async function parse(
           if (parent$type && !members.$type) {
             sourceNode.value = injectObjMembers(sourceNode.value, [parent$type]);
           }
-          validate(sourceNode, { source, logger });
+
+          validate(sourceNode, { filename, src, logger });
 
           const group = { id: splitID(id).group, tokens: [] };
           if (parent$type) {
@@ -117,7 +258,10 @@ export default async function parse(
             mode: {},
             originalValue: evaluate(node.value),
             group,
-            sourceNode: sourceNode.value,
+            source: {
+              loc: filename ? fileURLToPath(filename) : undefined,
+              node: sourceNode.value,
+            },
           };
           if (members.$description?.value) {
             token.$description = members.$description.value;
@@ -131,7 +275,10 @@ export default async function parse(
               id: token.id,
               $type: token.$type,
               $value: mode === '.' ? token.$value : evaluate(modeValues[mode]),
-              sourceNode: mode === '.' ? structuredClone(token.sourceNode) : modeValues[mode],
+              source: {
+                loc: filename ? fileURLToPath(filename) : undefined,
+                node: mode === '.' ? structuredClone(token.source.node) : modeValues[mode],
+              },
             };
             if (token.$description) {
               token.mode[mode].$description = token.$description;
@@ -140,7 +287,7 @@ export default async function parse(
 
           tokens[id] = token;
         } else if (members.value) {
-          logger.warn({ message: `Group ${id} has "value". Did you mean "$value"?`, node, source });
+          logger.warn({ message: `Group ${id} has "value". Did you mean "$value"?`, filename, node, src });
         }
       }
 
@@ -161,14 +308,14 @@ export default async function parse(
   });
 
   // 3. Execute lint runner with loaded plugins
-  if (!skipLint && plugins?.length) {
+  if (!skipLint && config?.plugins?.length) {
     const lintStart = performance.now();
     logger.debug({
       group: 'parser',
       task: 'validate',
       message: 'Start token linting',
     });
-    await lintRunner({ ast, source, config, logger });
+    await lintRunner({ document, filename, src, config, logger });
     logger.debug({
       group: 'parser',
       task: 'validate',
@@ -191,12 +338,12 @@ export default async function parse(
     try {
       tokens[id].$value = normalize(tokens[id]);
     } catch (err) {
-      let node = tokens[id].sourceNode;
+      let { node } = tokens[id].source;
       const members = getObjMembers(node);
       if (members.$value) {
         node = members.$value;
       }
-      logger.error({ message: err.message, source, node, continueOnError });
+      logger.error({ message: err.message, filename, src, node, continueOnError });
     }
     for (const mode in tokens[id].mode) {
       if (mode === '.') {
@@ -205,12 +352,18 @@ export default async function parse(
       try {
         tokens[id].mode[mode].$value = normalize(tokens[id].mode[mode]);
       } catch (err) {
-        let node = tokens[id].sourceNode;
+        let { node } = tokens[id].source;
         const members = getObjMembers(node);
         if (members.$value) {
           node = members.$value;
         }
-        logger.error({ message: err.message, source, node: tokens[id].mode[mode].sourceNode, continueOnError });
+        logger.error({
+          message: err.message,
+          filename,
+          src,
+          node: tokens[id].mode[mode].source.node,
+          continueOnError,
+        });
       }
     }
   }
@@ -221,74 +374,7 @@ export default async function parse(
     timing: performance.now() - normalizeStart,
   });
 
-  // 5. Resolve aliases and populate groups
-  for (const id in tokens) {
-    if (!Object.hasOwn(tokens, id)) {
-      continue;
-    }
-    const token = tokens[id];
-    applyAliases(token, { tokens, source, node: token.sourceNode, logger });
-    token.mode['.'].$value = token.$value;
-    if (token.aliasOf) {
-      token.mode['.'].aliasOf = token.aliasOf;
-    }
-    if (token.partialAliasOf) {
-      token.mode['.'].partialAliasOf = token.partialAliasOf;
-    }
-    const { group: parentGroup } = splitID(id);
-    for (const siblingID in tokens) {
-      const { group: siblingGroup } = splitID(siblingID);
-      if (siblingGroup?.startsWith(parentGroup)) {
-        token.group.tokens.push(siblingID);
-      }
-    }
-  }
-
-  // 6. resolve mode aliases
-  const modesStart = performance.now();
-  logger.debug({
-    group: 'parser',
-    task: 'modes',
-    message: 'Start mode resolution',
-  });
-  for (const id in tokens) {
-    if (!Object.hasOwn(tokens, id)) {
-      continue;
-    }
-    for (const mode in tokens[id].mode) {
-      if (mode === '.') {
-        continue; // skip shadow of root value
-      }
-      applyAliases(tokens[id].mode[mode], { tokens, source, node: tokens[id].mode[mode].sourceNode, logger });
-    }
-  }
-  logger.debug({
-    group: 'parser',
-    task: 'modes',
-    message: 'Finish token modes',
-    timing: performance.now() - modesStart,
-  });
-
-  logger.debug({
-    group: 'parser',
-    task: 'core',
-    message: 'Finish all parser tasks',
-    timing: performance.now() - totalStart,
-  });
-
-  if (continueOnError) {
-    const { errorCount } = logger.stats();
-    if (errorCount > 0) {
-      logger.error({
-        message: `Parser encountered ${errorCount} ${pluralize(errorCount, 'error', 'errors')}. Exiting.`,
-      });
-    }
-  }
-
-  return {
-    tokens,
-    ast,
-  };
+  return { tokens, document, src };
 }
 
 /**
@@ -306,31 +392,32 @@ export function maybeJSONString(input) {
  * @param {Object} options
  * @param {Record<string, TokenNormalized>} options.tokens
  * @param {Logger} options.logger
+ * @param {string} [options.filename]
  * @param {AnyNode} [options.node]
  * @param {string} [options.string]
- * @param {string[]=[]} options.scanned
+ * @param {string} [options.scanned=[]]
  * @param {string}
  */
-export function resolveAlias(alias, { tokens, logger, source, node, scanned = [] }) {
+export function resolveAlias(alias, { tokens, logger, filename, src, node, scanned = [] }) {
   const { id } = parseAlias(alias);
   if (!tokens[id]) {
-    logger.error({ message: `Alias "${alias}" not found`, source, node });
+    logger.error({ message: `Alias "${alias}" not found`, filename, src, node });
   }
   if (scanned.includes(id)) {
-    logger.error({ message: `Circular alias detected from "${alias}"`, source, node });
+    logger.error({ message: `Circular alias detected from "${alias}"`, filename, src, node });
   }
   const token = tokens[id];
   if (!isAlias(token.$value)) {
     return id;
   }
-  return resolveAlias(token.$value, { tokens, logger, node, source, scanned: [...scanned, id] });
+  return resolveAlias(token.$value, { tokens, logger, filename, node, src, scanned: [...scanned, id] });
 }
 
 /** Resolve aliases, update values, and mutate `token` to add `aliasOf` / `partialAliasOf` */
-function applyAliases(token, { tokens, logger, source, node }) {
+function applyAliases(token, { tokens, logger, filename, src, node }) {
   // handle simple aliases
   if (isAlias(token.$value)) {
-    const aliasOfID = resolveAlias(token.$value, { tokens, logger, node, source });
+    const aliasOfID = resolveAlias(token.$value, { tokens, logger, filename, node, src });
     const { mode: aliasMode } = parseAlias(token.$value);
     const aliasOf = tokens[aliasOfID];
     token.aliasOf = aliasOfID;
@@ -353,7 +440,7 @@ function applyAliases(token, { tokens, logger, source, node }) {
         if (!token.partialAliasOf) {
           token.partialAliasOf = [];
         }
-        const aliasOfID = resolveAlias(token.$value[i], { tokens, logger, node, source });
+        const aliasOfID = resolveAlias(token.$value[i], { tokens, logger, filename, node, src });
         const { mode: aliasMode } = parseAlias(token.$value[i]);
         token.partialAliasOf[i] = aliasOfID;
         token.$value[i] = tokens[aliasOfID].mode[aliasMode]?.$value || tokens[aliasOfID].$value;
@@ -366,7 +453,7 @@ function applyAliases(token, { tokens, logger, source, node }) {
             if (!token.partialAliasOf[i]) {
               token.partialAliasOf[i] = {};
             }
-            const aliasOfID = resolveAlias(token.$value[i][property], { tokens, logger, node, source });
+            const aliasOfID = resolveAlias(token.$value[i][property], { tokens, logger, filename, node, src });
             const { mode: aliasMode } = parseAlias(token.$value[i][property]);
             token.$value[i][property] = tokens[aliasOfID].mode[aliasMode]?.$value || tokens[aliasOfID].$value;
             token.partialAliasOf[i][property] = aliasOfID;
@@ -386,7 +473,7 @@ function applyAliases(token, { tokens, logger, source, node }) {
         if (!token.partialAliasOf) {
           token.partialAliasOf = {};
         }
-        const aliasOfID = resolveAlias(token.$value[property], { tokens, logger, node, source });
+        const aliasOfID = resolveAlias(token.$value[property], { tokens, logger, filename, node, src });
         const { mode: aliasMode } = parseAlias(token.$value[property]);
         token.partialAliasOf[property] = aliasOfID;
         token.$value[property] = tokens[aliasOfID].mode[aliasMode]?.$value || tokens[aliasOfID].$value;
@@ -395,7 +482,7 @@ function applyAliases(token, { tokens, logger, source, node }) {
       else if (Array.isArray(token.$value[property])) {
         for (let i = 0; i < token.$value[property].length; i++) {
           if (isAlias(token.$value[property][i])) {
-            const aliasOfID = resolveAlias(token.$value[property][i], { tokens, logger, node, source });
+            const aliasOfID = resolveAlias(token.$value[property][i], { tokens, logger, filename, node, src });
             if (!token.partialAliasOf) {
               token.partialAliasOf = {};
             }

package/parse/validate.d.ts

@@ -7,7 +7,8 @@ declare const STROKE_STYLE_VALUES: Set<string>;
 declare const STROKE_STYLE_LINE_CAP_VALUES: Set<string>;
 
 export interface ValidateOptions {
-  source: string;
+  filename?: URL;
+  src: string;
   logger: Logger;
 }
 

package/parse/validate.js

@@ -4,12 +4,10 @@ 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
- */
+/** @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 const VALID_COLORSPACES = new Set([
   'adobe-rgb',
@@ -82,21 +80,21 @@ function isMaybeAlias(node) {
  * @param {ValidateOptions} options
  * @return {void}
  */
-function validateMembersAs($value, properties, node, { source, logger }) {
+function validateMembersAs($value, properties, node, { filename, src, logger }) {
   const members = getObjMembers($value);
   for (const property in properties) {
     const { validator, required } = properties[property];
     if (!members[property]) {
       if (required) {
-        logger.error({ message: `Missing required property "${property}"`, node: $value, source });
+        logger.error({ message: `Missing required property "${property}"`, filename, node: $value, src });
       }
       continue;
     }
     const value = members[property];
     if (isMaybeAlias(value)) {
-      validateAlias(value, node, { source, logger });
+      validateAlias(value, node, { filename, src, logger });
     } else {
-      validator(value, node, { source, logger });
+      validator(value, node, { filename, src, logger });
     }
   }
 }
@@ -108,9 +106,9 @@ function validateMembersAs($value, properties, node, { source, logger }) {
  * @param {ValidateOptions} options
  * @return {void}
  */
-export function validateAlias($value, node, { source, logger }) {
+export function validateAlias($value, node, { filename, src, logger }) {
   if ($value.type !== 'String' || !isAlias($value.value)) {
-    logger.error({ message: `Invalid alias: ${print($value)}`, node: $value, source });
+    logger.error({ message: `Invalid alias: ${print($value)}`, filename, node: $value, src });
   }
 }
 
@@ -121,9 +119,9 @@ export function validateAlias($value, node, { source, logger }) {
  * @param {ValidateOptions} options
  * @return {void}
  */
-export function validateBorder($value, node, { source, logger }) {
+export function validateBorder($value, node, { filename, src, logger }) {
   if ($value.type !== 'Object') {
-    logger.error({ message: `Expected object, received ${$value.type}`, node: $value, source });
+    logger.error({ message: `Expected object, received ${$value.type}`, filename, node: $value, src });
     return;
   }
   validateMembersAs(
@@ -134,7 +132,7 @@ export function validateBorder($value, node, { source, logger }) {
       width: { validator: validateDimension, required: true },
     },
     node,
-    { source, logger },
+    { filename, src, logger },
   );
 }
 
@@ -145,16 +143,17 @@ export function validateBorder($value, node, { source, logger }) {
  * @param {ValidateOptions} options
  * @return {void}
  */
-export function validateColor($value, node, { source, logger }) {
+export function validateColor($value, node, { filename, src, logger }) {
   if ($value.type === 'String') {
     // TODO: enable when object notation is finalized
     // logger.warn({
+    //   filename,
     //   message: 'String colors are no longer recommended; please use the object notation instead.',
     //   node: $value,
-    //   source,
+    //   src,
     // });
     if ($value.value === '') {
-      logger.error({ message: 'Expected color, received empty string', node: $value, source });
+      logger.error({ message: 'Expected color, received empty string', filename, node: $value, src });
     }
   } else if ($value.type === 'Object') {
     validateMembersAs(
@@ -163,10 +162,10 @@ export function validateColor($value, node, { source, logger }) {
         colorSpace: {
           validator: (v) => {
             if (v.type !== 'String') {
-              logger.error({ message: `Expected string, received ${print(v)}`, node: v, source });
+              logger.error({ message: `Expected string, received ${print(v)}`, filename, node: v, src });
             }
             if (!VALID_COLORSPACES.has(v.value)) {
-              logger.error({ message: `Unsupported colorspace ${print(v)}`, node: v, source });
+              logger.error({ message: `Unsupported colorspace ${print(v)}`, filename, node: v, src });
             }
           },
           required: true,
@@ -174,14 +173,24 @@ export function validateColor($value, node, { source, logger }) {
         channels: {
           validator: (v, node) => {
             if (v.type !== 'Array') {
-              logger.error({ message: `Expected array, received ${print(v)}`, node: v, source });
+              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}`, node: v, source });
+              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') {
-                logger.error({ message: `Expected number, received ${print(element.value)}`, node: element, source });
+                logger.error({
+                  message: `Expected number, received ${print(element.value)}`,
+                  filename,
+                  node: element,
+                  src,
+                });
               }
             }
           },
@@ -199,17 +208,17 @@ export function validateColor($value, node, { source, logger }) {
               v.value.length === 7 + 1 ||
               !/^#[a-f0-9]{3,8}$/i.test(v.value)
             ) {
-              logger.error({ message: `Invalid hex color ${print(v)}`, node: v, source });
+              logger.error({ message: `Invalid hex color ${print(v)}`, filename, node: v, src });
             }
           },
         },
         alpha: { validator: validateNumber },
       },
       node,
-      { source, logger },
+      { filename, src, logger },
     );
   } else {
-    logger.error({ message: `Expected object, received ${$value.type}`, node: $value, source });
+    logger.error({ message: `Expected object, received ${$value.type}`, filename, node: $value, src });
   }
 }
 
@@ -220,22 +229,24 @@ export function validateColor($value, node, { source, logger }) {
  * @param {ValidateOptions} options
  * @return {void}
  */
-export function validateCubicBezier($value, node, { source, logger }) {
+export function validateCubicBezier($value, node, { filename, src, logger }) {
   if ($value.type !== 'Array') {
-    logger.error({ message: `Expected array of strings, received ${print($value)}`, node: $value, source });
+    logger.error({ message: `Expected array of strings, received ${print($value)}`, filename, node: $value, src });
   } else if (
     !$value.elements.every((e) => e.value.type === 'Number' || (e.value.type === 'String' && isAlias(e.value.value)))
   ) {
     logger.error({
       message: 'Expected an array of 4 numbers, received some non-numbers',
+      filename,
       node: $value,
-      source,
+      src,
     });
   } else if ($value.elements.length !== 4) {
     logger.error({
       message: `Expected an array of 4 numbers, received ${$value.elements.length}`,
+      filename,
       node: $value,
-      source,
+      src,
     });
   }
 }
@@ -247,18 +258,18 @@ export function validateCubicBezier($value, node, { source, logger }) {
  * @param {ValidateOptions} options
  * @return {void}
  */
-export function validateDimension($value, node, { source, logger }) {
+export function validateDimension($value, node, { filename, src, logger }) {
   if ($value.type === 'Number' && $value.value === 0) {
     return; // `0` is a valid number
   }
   if ($value.type !== 'String') {
-    logger.error({ message: `Expected string, received ${$value.type}`, node: $value, source });
+    logger.error({ message: `Expected string, received ${$value.type}`, filename, node: $value, src });
   } else if ($value.value === '') {
-    logger.error({ message: 'Expected dimension, received empty string', node: $value, source });
+    logger.error({ message: 'Expected dimension, received empty string', filename, node: $value, src });
   } else if (String(Number($value.value)) === $value.value) {
-    logger.error({ message: 'Missing units', node: $value, source });
+    logger.error({ message: 'Missing units', filename, node: $value, src });
   } else if (!/^[0-9]+/.test($value.value)) {
-    logger.error({ message: `Expected dimension with units, received ${print($value)}`, node: $value, source });
+    logger.error({ message: `Expected dimension with units, received ${print($value)}`, filename, node: $value, src });
   }
 }
 
@@ -269,18 +280,23 @@ export function validateDimension($value, node, { source, logger }) {
  * @param {ValidateOptions} options
  * @return {void}
  */
-export function validateDuration($value, node, { source, logger }) {
+export function validateDuration($value, node, { filename, src, logger }) {
   if ($value.type === 'Number' && $value.value === 0) {
     return; // `0` is a valid number
   }
   if ($value.type !== 'String') {
-    logger.error({ message: `Expected string, received ${$value.type}`, node: $value, source });
+    logger.error({ message: `Expected string, received ${$value.type}`, filename, node: $value, src });
   } else if ($value.value === '') {
-    logger.error({ message: 'Expected duration, received empty string', node: $value, source });
+    logger.error({ message: 'Expected duration, received empty string', filename, node: $value, src });
   } else if (!/m?s$/.test($value.value)) {
-    logger.error({ message: 'Missing unit "ms" or "s"', node: $value, source });
+    logger.error({ message: 'Missing unit "ms" or "s"', filename, node: $value, src });
   } else if (!/^[0-9]+/.test($value.value)) {
-    logger.error({ message: `Expected duration in \`ms\` or \`s\`, received ${print($value)}`, node: $value, source });
+    logger.error({
+      message: `Expected duration in \`ms\` or \`s\`, received ${print($value)}`,
+      filename,
+      node: $value,
+      src,
+    });
   }
 }
 
@@ -291,18 +307,24 @@ export function validateDuration($value, node, { source, logger }) {
  * @param {ValidateOptions} options
  * @return {void}
  */
-export function validateFontFamily($value, node, { source, logger }) {
+export function validateFontFamily($value, node, { filename, src, logger }) {
   if ($value.type !== 'String' && $value.type !== 'Array') {
-    logger.error({ message: `Expected string or array of strings, received ${$value.type}`, node: $value, source });
+    logger.error({
+      message: `Expected string or array of strings, received ${$value.type}`,
+      filename,
+      node: $value,
+      src,
+    });
   }
   if ($value.type === 'String' && $value.value === '') {
-    logger.error({ message: 'Expected font family name, received empty string', node: $value, source });
+    logger.error({ message: 'Expected font family name, received empty string', filename, node: $value, src });
   }
   if ($value.type === 'Array' && !$value.elements.every((e) => e.value.type === 'String' && e.value.value !== '')) {
     logger.error({
       message: 'Expected an array of strings, received some non-strings or empty strings',
+      filename,
       node: $value,
-      source,
+      src,
     });
   }
 }
@@ -314,23 +336,25 @@ export function validateFontFamily($value, node, { source, logger }) {
  * @param {ValidateOptions} options
  * @return {void}
  */
-export function validateFontWeight($value, node, { source, logger }) {
+export function validateFontWeight($value, node, { filename, src, logger }) {
   if ($value.type !== 'String' && $value.type !== 'Number') {
     logger.error({
       message: `Expected a font weight name or number 0–1000, received ${$value.type}`,
+      filename,
       node: $value,
-      source,
+      src,
     });
   }
   if ($value.type === 'String' && !FONT_WEIGHT_VALUES.has($value.value)) {
     logger.error({
       message: `Unknown font weight ${print($value)}. Expected one of: ${listFormat.format([...FONT_WEIGHT_VALUES])}.`,
+      filename,
       node: $value,
-      source,
+      src,
     });
   }
   if ($value.type === 'Number' && ($value.value < 0 || $value.value > 1000)) {
-    logger.error({ message: `Expected number 0–1000, received ${print($value)}`, node: $value, source });
+    logger.error({ message: `Expected number 0–1000, received ${print($value)}`, filename, node: $value, src });
   }
 }
 
@@ -341,9 +365,14 @@ export function validateFontWeight($value, node, { source, logger }) {
  * @param {ValidateOptions} options
  * @return {void}
  */
-export function validateGradient($value, node, { source, logger }) {
+export function validateGradient($value, node, { filename, src, logger }) {
   if ($value.type !== 'Array') {
-    logger.error({ message: `Expected array of gradient stops, received ${$value.type}`, node: $value, source });
+    logger.error({
+      message: `Expected array of gradient stops, received ${$value.type}`,
+      filename,
+      node: $value,
+      src,
+    });
     return;
   }
   for (let i = 0; i < $value.elements.length; i++) {
@@ -351,8 +380,9 @@ export function validateGradient($value, node, { source, logger }) {
     if (element.value.type !== 'Object') {
       logger.error({
         message: `Stop #${i + 1}: Expected gradient stop, received ${element.value.type}`,
+        filename,
         node: element,
-        source,
+        src,
       });
       break;
     }
@@ -363,7 +393,7 @@ export function validateGradient($value, node, { source, logger }) {
         position: { validator: validateNumber, required: true },
       },
       element,
-      { source, logger },
+      { filename, src, logger },
     );
   }
 }
@@ -375,9 +405,9 @@ export function validateGradient($value, node, { source, logger }) {
  * @param {ValidateOptions} options
  * @return {void}
  */
-export function validateNumber($value, node, { source, logger }) {
+export function validateNumber($value, node, { filename, src, logger }) {
   if ($value.type !== 'Number') {
-    logger.error({ message: `Expected number, received ${$value.type}`, node: $value, source });
+    logger.error({ message: `Expected number, received ${$value.type}`, filename, node: $value, src });
   }
 }
 
@@ -388,9 +418,9 @@ export function validateNumber($value, node, { source, logger }) {
  * @param {ValidateOptions} options
  * @return {void}
  */
-export function validateShadowLayer($value, node, { source, logger }) {
+export function validateShadowLayer($value, node, { filename, src, logger }) {
   if ($value.type !== 'Object') {
-    logger.error({ message: `Expected Object, received ${$value.type}`, node: $value, source });
+    logger.error({ message: `Expected Object, received ${$value.type}`, filename, node: $value, src });
     return;
   }
   validateMembersAs(
@@ -403,7 +433,7 @@ export function validateShadowLayer($value, node, { source, logger }) {
       spread: { validator: validateDimension },
     },
     node,
-    { source, logger },
+    { filename, src, logger },
   );
 }
 
@@ -414,7 +444,7 @@ export function validateShadowLayer($value, node, { source, logger }) {
  * @param {ValidateOptions} options
  * @return {void}
  */
-export function validateStrokeStyle($value, node, { source, logger }) {
+export function validateStrokeStyle($value, node, { filename, src, logger }) {
   // 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)) {
@@ -422,19 +452,16 @@ export function validateStrokeStyle($value, node, { source, logger }) {
         message: `Unknown stroke style ${print($value)}. Expected one of: ${listFormat.format([
           ...STROKE_STYLE_VALUES,
         ])}.`,
+        filename,
         node: $value,
-        source,
+        src,
       });
     }
   } else if ($value.type === 'Object') {
     const strokeMembers = getObjMembers($value);
     for (const property of ['dashArray', 'lineCap']) {
       if (!strokeMembers[property]) {
-        logger.error({
-          message: `Missing required property "${property}"`,
-          node: $value,
-          source,
-        });
+        logger.error({ message: `Missing required property "${property}"`, filename, node: $value, src });
       }
     }
     const { lineCap, dashArray } = strokeMembers;
@@ -449,31 +476,24 @@ export function validateStrokeStyle($value, node, { source, logger }) {
       for (const element of dashArray.elements) {
         if (element.value.type === 'String' && element.value.value !== '') {
           if (isMaybeAlias(element.value)) {
-            validateAlias(element.value, node, { logger, source });
+            validateAlias(element.value, node, { logger, src });
           } else {
-            validateDimension(element.value, node, { logger, source });
+            validateDimension(element.value, node, { logger, src });
           }
         } else {
           logger.error({
             message: 'Expected array of strings, recieved some non-strings or empty strings.',
+            filename,
             node: element,
-            source,
+            src,
           });
         }
       }
     } else {
-      logger.error({
-        message: `Expected array of strings, received ${dashArray.type}`,
-        node: $value,
-        source,
-      });
+      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}`,
-      node: $value,
-      source,
-    });
+    logger.error({ message: `Expected string or object, received ${$value.type}`, filename, node: $value, src });
   }
 }
 
@@ -484,9 +504,9 @@ export function validateStrokeStyle($value, node, { source, logger }) {
  * @param {ValidateOptions} options
  * @return {void}
  */
-export function validateTransition($value, node, { source, logger }) {
+export function validateTransition($value, node, { filename, src, logger }) {
   if ($value.type !== 'Object') {
-    logger.error({ message: `Expected object, received ${$value.type}`, node: $value, source });
+    logger.error({ message: `Expected object, received ${$value.type}`, filename, node: $value, src });
     return;
   }
   validateMembersAs(
@@ -497,7 +517,7 @@ export function validateTransition($value, node, { source, logger }) {
       timingFunction: { validator: validateCubicBezier, required: true },
     },
     node,
-    { source, logger },
+    { filename, src, logger },
   );
 }
 
@@ -508,12 +528,13 @@ export function validateTransition($value, node, { source, logger }) {
  * @param {ValidateOptions} options
  * @return {void}
  */
-export default function validate(node, { source, logger }) {
+export default function validate(node, { filename, src, logger }) {
   if (node.type !== 'Member' && node.type !== 'Object') {
     logger.error({
       message: `Expected Object, received ${JSON.stringify(node.type)}`,
+      filename,
       node,
-      source,
+      src,
     });
     return;
   }
@@ -523,62 +544,63 @@ export default function validate(node, { source, logger }) {
   const $type = rootMembers.$type;
 
   if (!$value) {
-    logger.error({ message: 'Token missing $value', node, source });
+    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!
   if (isMaybeAlias($value)) {
-    validateAlias($value, node, { logger, source });
+    validateAlias($value, node, { logger, src });
     return;
   }
 
   if (!$type) {
-    logger.error({ message: 'Token missing $type', node, source });
+    logger.error({ message: 'Token missing $type', filename, node, src });
     return;
   }
 
   switch ($type.value) {
     case 'color': {
-      validateColor($value, node, { logger, source });
+      validateColor($value, node, { logger, src });
       break;
     }
     case 'cubicBezier': {
-      validateCubicBezier($value, node, { logger, source });
+      validateCubicBezier($value, node, { logger, src });
       break;
     }
     case 'dimension': {
-      validateDimension($value, node, { logger, source });
+      validateDimension($value, node, { logger, src });
       break;
     }
     case 'duration': {
-      validateDuration($value, node, { logger, source });
+      validateDuration($value, node, { logger, src });
       break;
     }
     case 'fontFamily': {
-      validateFontFamily($value, node, { logger, source });
+      validateFontFamily($value, node, { logger, src });
       break;
     }
     case 'fontWeight': {
-      validateFontWeight($value, node, { logger, source });
+      validateFontWeight($value, node, { logger, src });
       break;
     }
     case 'number': {
-      validateNumber($value, node, { logger, source });
+      validateNumber($value, node, { logger, src });
       break;
     }
     case 'shadow': {
       if ($value.type === 'Object') {
-        validateShadowLayer($value, node, { logger, source });
+        validateShadowLayer($value, node, { logger, src });
       } else if ($value.type === 'Array') {
         for (const element of $value.elements) {
-          validateShadowLayer(element.value, $value, { logger, source });
+          validateShadowLayer(element.value, $value, { logger, src });
         }
       } else {
         logger.error({
           message: `Expected shadow object or array of shadow objects, received ${$value.type}`,
+          filename,
           node: $value,
-          source,
+          src,
         });
       }
       break;
@@ -587,49 +609,54 @@ export default function validate(node, { source, logger }) {
     // extensions
     case 'boolean': {
       if ($value.type !== 'Boolean') {
-        logger.error({ message: `Expected boolean, received ${$value.type}`, node: $value, source });
+        logger.error({ message: `Expected boolean, received ${$value.type}`, filename, node: $value, src });
       }
       break;
     }
     case 'link': {
       if ($value.type !== 'String') {
-        logger.error({ message: `Expected string, received ${$value.type}`, node: $value, source });
+        logger.error({ message: `Expected string, received ${$value.type}`, filename, node: $value, src });
       } else if ($value.value === '') {
-        logger.error({ message: 'Expected URL, received empty string', node: $value, source });
+        logger.error({ message: 'Expected URL, received empty string', filename, node: $value, src });
       }
       break;
     }
     case 'string': {
       if ($value.type !== 'String') {
-        logger.error({ message: `Expected string, received ${$value.type}`, node: $value, source });
+        logger.error({ message: `Expected string, received ${$value.type}`, filename, node: $value, src });
       }
       break;
     }
 
     // composite types
     case 'border': {
-      validateBorder($value, node, { source, logger });
+      validateBorder($value, node, { filename, src, logger });
       break;
     }
     case 'gradient': {
-      validateGradient($value, node, { source, logger });
+      validateGradient($value, node, { filename, src, logger });
       break;
     }
     case 'strokeStyle': {
-      validateStrokeStyle($value, node, { source, logger });
+      validateStrokeStyle($value, node, { filename, src, logger });
       break;
     }
     case 'transition': {
-      validateTransition($value, node, { source, logger });
+      validateTransition($value, node, { filename, src, logger });
       break;
     }
     case 'typography': {
       if ($value.type !== 'Object') {
-        logger.error({ message: `Expected object, received ${$value.type}`, node: $value, source });
+        logger.error({ message: `Expected object, received ${$value.type}`, filename, node: $value, src });
         break;
       }
       if ($value.members.length === 0) {
-        logger.error({ message: 'Empty typography token. Must contain at least 1 property.', node: $value, source });
+        logger.error({
+          message: 'Empty typography token. Must contain at least 1 property.',
+          filename,
+          node: $value,
+          src,
+        });
       }
       validateMembersAs(
         $value,
@@ -638,7 +665,7 @@ export default function validate(node, { source, logger }) {
           fontWeight: { validator: validateFontWeight },
         },
         node,
-        { source, logger },
+        { filename, src, logger },
       );
       break;
     }