@terrazzo/parser 0.1.3 → 0.2.0

package/src/lint/plugin-core/rules/required-typography-properties.ts

@@ -0,0 +1,53 @@
+import { isTokenMatch } from '@terrazzo/token-tools';
+import type { LintRule } from '../../../types.js';
+import { docsLink } from '../lib/docs.js';
+
+export const REQUIRED_TYPOGRAPHY_PROPERTIES = 'core/required-typography-properties';
+
+export interface RuleRequiredTypographyPropertiesOptions {
+  /** Required typography properties */
+  properties: string[];
+  /** Token globs to ignore */
+  ignore?: string[];
+}
+
+const rule: LintRule<never, RuleRequiredTypographyPropertiesOptions> = {
+  meta: {
+    docs: {
+      description: 'Enforce typography tokens have required properties.',
+      url: docsLink(REQUIRED_TYPOGRAPHY_PROPERTIES),
+    },
+  },
+  defaultOptions: { properties: [] },
+  create({ tokens, options, report }) {
+    if (!options) {
+      return;
+    }
+
+    if (!options.properties.length) {
+      throw new Error(`"properties" can’t be empty`);
+    }
+
+    for (const t of Object.values(tokens)) {
+      if (options.ignore && isTokenMatch(t.id, options.ignore)) {
+        continue;
+      }
+
+      if (t.$type !== 'typography') {
+        continue;
+      }
+
+      if (t.aliasOf) {
+        continue;
+      }
+
+      for (const p of options.properties) {
+        if (!t.partialAliasOf?.[p] && !(p in t.$value)) {
+          report({ message: `${t.id} missing required typographic property "${p}"`, node: t.source.node });
+        }
+      }
+    }
+  },
+};
+
+export default rule;

package/{logger.js → src/logger.ts}

@@ -1,12 +1,51 @@
+import type { AnyNode } from '@humanwhocodes/momoa';
 import color from 'picocolors';
 import wcmatch from 'wildcard-match';
 import { codeFrameColumns } from './lib/code-frame.js';
 
-export const LOG_ORDER = ['error', 'warn', 'info', 'debug'];
+export const LOG_ORDER = ['error', 'warn', 'info', 'debug'] as const;
+
+export type LogSeverity = 'error' | 'warn' | 'info' | 'debug';
+
+export type LogLevel = LogSeverity | 'silent';
+
+export type LogGroup = 'parser' | 'plugin';
+
+export interface LogEntry {
+  /** Error message to be logged */
+  message: string;
+  /** Prefix message with label */
+  label?: string;
+  /** File in disk */
+  filename?: URL;
+  /**
+   * Continue on error?
+   * @default false
+   */
+  continueOnError?: boolean;
+  /** Show a code frame for the erring node */
+  node?: AnyNode;
+  /** Originator of log message */
+  group?: LogGroup;
+  /** To show a code frame, provide the original source code */
+  src?: string;
+}
+
+export interface DebugEntry {
+  group: LogGroup;
+  /** Error message to be logged */
+  message: string;
+  /** Current subtask or submodule */
+  label?: string;
+  /** Show code below message */
+  codeFrame?: { src: string; line: number; column: number };
+  /** Display performance timing */
+  timing?: number;
+}
 
-const DEBUG_GROUP_COLOR = { core: color.green, plugin: color.magenta };
+const DEBUG_GROUP_COLOR: Record<string, typeof color.red | undefined> = { core: color.green, plugin: color.magenta };
 
-const MESSAGE_COLOR = { error: color.red, warn: color.yellow };
+const MESSAGE_COLOR: Record<string, typeof color.red | undefined> = { error: color.red, warn: color.yellow };
 
 const timeFormatter = new Intl.DateTimeFormat('en-gb', { timeStyle: 'medium' });
 
@@ -15,16 +54,16 @@ const timeFormatter = new Intl.DateTimeFormat('en-gb', { timeStyle: 'medium' });
  * @param {Severity} severity
  * @return {string}
  */
-export function formatMessage(entry, severity) {
+export function formatMessage(entry: LogEntry, severity: LogSeverity) {
   let message = entry.message;
   if (entry.label) {
     message = `${color.bold(`${entry.label}:`)} ${message}`;
   }
   if (severity in MESSAGE_COLOR) {
-    message = MESSAGE_COLOR[severity](message);
+    message = MESSAGE_COLOR[severity]!(message);
   }
   if (entry.src) {
-    const start = entry.node?.loc?.start;
+    const start = entry.node?.loc?.start ?? { line: 0, column: 0 };
     //  strip "file://" protocol, but not href
     const loc = entry.filename
       ? `${entry.filename?.href.replace(/^file:\/\//, '')}:${start?.line ?? 0}:${start?.column ?? 0}\n\n`
@@ -36,14 +75,14 @@ export function formatMessage(entry, severity) {
 }
 
 export default class Logger {
-  level = 'info';
+  level = 'info' as LogLevel;
   debugScope = '*';
   errorCount = 0;
   warnCount = 0;
   infoCount = 0;
   debugCount = 0;
 
-  constructor(options) {
+  constructor(options?: { level?: LogLevel; debugScope?: string }) {
     if (options?.level) {
       this.level = options.level;
     }
@@ -52,12 +91,12 @@ export default class Logger {
     }
   }
 
-  setLevel(level) {
+  setLevel(level: LogLevel) {
     this.level = level;
   }
 
   /** Log an error message (always; can’t be silenced) */
-  error(entry) {
+  error(entry: LogEntry) {
     this.errorCount++;
     const message = formatMessage(entry, 'error');
     if (entry.continueOnError) {
@@ -72,7 +111,7 @@ export default class Logger {
   }
 
   /** Log an info message (if logging level permits) */
-  info(entry) {
+  info(entry: LogEntry) {
     this.infoCount++;
     if (this.level === 'silent' || LOG_ORDER.indexOf(this.level) < LOG_ORDER.indexOf('info')) {
       return;
@@ -82,7 +121,7 @@ export default class Logger {
   }
 
   /** Log a warning message (if logging level permits) */
-  warn(entry) {
+  warn(entry: LogEntry) {
     this.warnCount++;
     if (this.level === 'silent' || LOG_ORDER.indexOf(this.level) < LOG_ORDER.indexOf('warn')) {
       return;
@@ -91,7 +130,7 @@ export default class Logger {
   }
 
   /** Log a diagnostics message (if logging level permits) */
-  debug(entry) {
+  debug(entry: DebugEntry) {
     this.debugCount++;
     if (this.level === 'silent' || LOG_ORDER.indexOf(this.level) < LOG_ORDER.indexOf('debug')) {
       return;
@@ -99,7 +138,7 @@ export default class Logger {
 
     let message = formatMessage(entry, 'debug');
 
-    const debugPrefix = `${entry.group}:${entry.task}`;
+    const debugPrefix = entry.label ? `${entry.group}:${entry.label}` : entry.group;
     if (this.debugScope !== '*' && !wcmatch(this.debugScope)(debugPrefix)) {
       return;
     }
@@ -107,7 +146,7 @@ export default class Logger {
       timeFormatter.format(new Date()),
     )} ${message}`;
     if (typeof entry.timing === 'number') {
-      let timing = Math.round(entry.timing);
+      let timing: string | number = Math.round(entry.timing);
       if (timing < 1_000) {
         timing = `${timing}ms`;
       } else if (timing < 60_000) {
@@ -132,7 +171,7 @@ export default class Logger {
 }
 
 export class TokensJSONError extends Error {
-  constructor(message) {
+  constructor(message: string) {
     super(message);
     this.name = 'TokensJSONError';
   }

package/src/parse/alias.ts

@@ -0,0 +1,224 @@
+import type { AnyNode, ArrayNode, ObjectNode, StringNode } from '@humanwhocodes/momoa';
+import { type TokenNormalized, isAlias, parseAlias } from '@terrazzo/token-tools';
+import type Logger from '../logger.js';
+
+/** Throw error if resolved alias for composite properties doesn’t match expected $type. */
+export const COMPOSITE_TYPE_VALUES = {
+  border: {
+    color: ['color'],
+    width: ['dimension'],
+    strokeStyle: ['strokeStyle'],
+  },
+  gradient: {
+    color: ['color'],
+    position: ['number'],
+  },
+  shadow: {
+    color: ['color'],
+    position: ['dimension'],
+  },
+  strokeStyle: {
+    dashArray: ['dimension'],
+  },
+  transition: {
+    duration: ['duration'],
+    delay: ['duration'],
+    timingFunction: ['cubicBezier'],
+  },
+  typography: {
+    fontFamily: ['fontFamily'],
+    fontSize: ['dimension'],
+    fontWeight: ['fontWeight'],
+    letterSpacing: ['dimension'],
+    lineHeight: ['dimension', 'number'],
+  },
+};
+
+/** Resolve alias */
+export function resolveAlias(
+  alias: string,
+  {
+    tokens,
+    logger,
+    filename,
+    src,
+    node,
+    scanned = [],
+  }: {
+    tokens: Record<string, TokenNormalized>;
+    logger: Logger;
+    filename?: URL;
+    src: string;
+    node: AnyNode;
+    scanned?: string[];
+  },
+) {
+  const { id } = parseAlias(alias);
+  if (!tokens[id]) {
+    logger.error({ message: `Alias "${alias}" not found.`, filename, src, node });
+  }
+  if (scanned.includes(id)) {
+    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 as string, { tokens, logger, filename, node, src, scanned: [...scanned, id] });
+}
+
+/** Resolve aliases, update values, and mutate `token` to add `aliasOf` / `partialAliasOf` */
+export function applyAliases(
+  token: TokenNormalized,
+  {
+    tokens,
+    logger,
+    filename,
+    src,
+    node,
+  }: { tokens: Record<string, TokenNormalized>; logger: Logger; filename?: URL; src: string; node: AnyNode },
+) {
+  const $valueNode =
+    (node.type === 'Object' && node.members.find((m) => (m.name as StringNode).value === '$value')?.value) || node;
+  const expectedAliasTypes =
+    token.$type in COMPOSITE_TYPE_VALUES && COMPOSITE_TYPE_VALUES[token.$type as keyof typeof COMPOSITE_TYPE_VALUES];
+
+  // handle simple aliases
+  if (isAlias(token.$value)) {
+    const aliasOfID = resolveAlias(token.$value as string, { tokens, logger, filename, node, src });
+    const { mode: aliasMode } = parseAlias(token.$value as string);
+    const aliasOf = tokens[aliasOfID]!;
+    token.aliasOf = aliasOfID;
+    token.$value = aliasOf!.mode[aliasMode!]?.$value || aliasOf.$value;
+    if (token.$type && token.$type !== aliasOf.$type) {
+      logger.error({
+        message: `Invalid alias: expected $type: "${token.$type}", received $type: "${aliasOf.$type}".`,
+        node: $valueNode,
+        filename,
+        src,
+      });
+    }
+    token.$type = aliasOf.$type;
+  }
+
+  // handle aliases within array values (e.g. cubicBezier, gradient)
+  else if (token.$type === 'cubicBezier' || token.$type === 'gradient' || token.$type === 'shadow') {
+    // some arrays are primitives, some are objects. handle both
+    for (let i = 0; i < token.$value.length; i++) {
+      // @ts-ignore
+      if (isAlias(token.$value[i])) {
+        if (!token.partialAliasOf) {
+          token.partialAliasOf = [];
+        }
+        // @ts-ignore
+        const aliasOfID = resolveAlias(token.$value[i], { tokens, logger, filename, node, src });
+        // @ts-ignore
+        const { id: aliasID, mode: aliasMode } = parseAlias(token.$value[i]);
+        token.partialAliasOf![i] = aliasID;
+        // @ts-ignore
+        token.$value[i] = (aliasMode && tokens[aliasOfID]!.mode[aliasMode]?.$value) || tokens[aliasOfID]!.$value;
+      } else if (typeof token.$value[i] === 'object') {
+        for (const [property, subvalue] of Object.entries(token.$value[i]!)) {
+          if (isAlias(subvalue)) {
+            if (!token.partialAliasOf) {
+              token.partialAliasOf = [];
+            }
+            if (!token.partialAliasOf[i]) {
+              token.partialAliasOf[i] = {};
+            }
+            const aliasOfID = resolveAlias(subvalue, { tokens, logger, filename, node, src });
+            const { id: aliasID, mode: aliasMode } = parseAlias(subvalue);
+            const aliasToken = tokens[aliasOfID]!;
+            const possibleTypes: string[] = expectedAliasTypes?.[property as keyof typeof expectedAliasTypes] || [];
+            if (possibleTypes.length && !possibleTypes.includes(aliasToken.$type)) {
+              const elementNode = ($valueNode as ArrayNode).elements[i]!.value;
+              logger.error({
+                message: `Invalid alias: expected $type: "${possibleTypes.join('" or "')}", received $type: "${aliasToken.$type}".`,
+                node: (elementNode as ObjectNode).members.find((m) => (m.name as StringNode).value === property)!.value,
+                filename,
+                src,
+              });
+            }
+
+            // @ts-ignore
+            token.partialAliasOf[i]![property] = aliasID; // also keep the shallow alias here, too!
+            // @ts-ignore
+            token.$value[i]![property] = (aliasMode && aliasToken.mode[aliasMode]?.$value) || aliasToken.$value;
+          }
+        }
+      }
+    }
+  }
+  // handle aliases within object (composite) values (e.g. border, typography, transition)
+  else if (typeof token.$value === 'object') {
+    for (const [property, subvalue] of Object.entries(token.$value)) {
+      if (!Object.hasOwn(token.$value, property)) {
+        continue;
+      }
+
+      if (isAlias(subvalue)) {
+        if (!token.partialAliasOf) {
+          token.partialAliasOf = {};
+        }
+        const aliasOfID = resolveAlias(subvalue, { tokens, logger, filename, node, src });
+        const { id: aliasID, mode: aliasMode } = parseAlias(subvalue);
+        // @ts-ignore
+        token.partialAliasOf[property] = aliasID; // keep the shallow alias!
+        const aliasToken = tokens[aliasOfID];
+        // @ts-ignore
+        if (expectedAliasTypes?.[property] && !expectedAliasTypes[property].includes(aliasToken!.$type)) {
+          logger.error({
+            // @ts-ignore
+            message: `Invalid alias: expected $type: "${expectedAliasTypes[property].join('" or "')}", received $type: "${aliasToken.$type}".`,
+            // @ts-ignore
+            node: $valueNode.members.find((m) => m.name.value === property).value,
+            filename,
+            src,
+          });
+        }
+        // @ts-ignore
+        token.$value[property] = aliasToken!.mode[aliasMode]?.$value || aliasToken!.$value;
+      }
+
+      // strokeStyle has an array within an object
+      // @ts-ignore
+      else if (Array.isArray(token.$value[property]!)) {
+        // @ts-ignore
+        for (let i = 0; i < token.$value[property]!.length; i++) {
+          // @ts-ignore
+          if (isAlias(token.$value[property]![i])) {
+            // @ts-ignore
+            const aliasOfID = resolveAlias(token.$value[property][i], { tokens, logger, filename, node, src });
+            if (!token.partialAliasOf) {
+              token.partialAliasOf = {};
+            }
+            // @ts-ignore
+            if (!token.partialAliasOf[property]) {
+              // @ts-ignore
+              token.partialAliasOf[property] = [];
+            }
+            // @ts-ignore
+            const { id: aliasID, mode: aliasMode } = parseAlias(token.$value[property][i]);
+            // @ts-ignore
+            token.partialAliasOf[property][i] = aliasID; // keep the shallow alias!
+            const aliasToken = tokens[aliasOfID];
+            // @ts-ignore
+            if (expectedAliasTypes?.[property] && !expectedAliasTypes[property].includes(aliasToken.$type)) {
+              // @ts-ignore
+              const arrayNode = $valueNode.members.find((m) => m.name.value === property).value;
+              logger.error({
+                // @ts-ignore
+                message: `Invalid alias: expected $type: "${expectedAliasTypes[property].join('" or "')}", received $type: "${aliasToken.$type}".`,
+                node: arrayNode.elements[i],
+                filename,
+                src,
+              });
+            }
+            // @ts-ignore
+            token.$value[property]![i] = tokens[aliasOfID]!.mode[aliasMode]?.$value || tokens[aliasOfID]!.$value;
+          }
+        }
+      }
+    }
+  }
+}