@terrazzo/parser 0.1.3 → 0.2.0

package/src/lint/plugin-core/rules/a11y-min-font-size.ts

@@ -0,0 +1,64 @@
+import { isTokenMatch } from '@terrazzo/token-tools';
+import type { LintRule } from '../../../types.js';
+import { docsLink } from '../lib/docs.js';
+
+export const A11Y_MIN_FONT_SIZE = 'a11y/min-font-size';
+
+export interface RuleA11yMinFontSizeOptions {
+  /** Minimum font size (pixels) */
+  minSizePx?: number;
+  /** Minimum font size (rems) */
+  minSizeRem?: number;
+  /** Token IDs to ignore. Accepts globs. */
+  ignore?: string[];
+}
+
+export const ERROR_TOO_SMALL = 'TOO_SMALL';
+
+const rule: LintRule<typeof ERROR_TOO_SMALL, RuleA11yMinFontSizeOptions> = {
+  meta: {
+    messages: {
+      [ERROR_TOO_SMALL]: '{{ id }} font size too small. Expected minimum of {{ min }}',
+    },
+    docs: {
+      description: 'Enforce font sizes are no smaller than the given value.',
+      url: docsLink(A11Y_MIN_FONT_SIZE),
+    },
+  },
+  defaultOptions: {},
+  create({ tokens, options, report }) {
+    if (!options.minSizePx && !options.minSizeRem) {
+      throw new Error('Must specify at least one of minSizePx or minSizeRem');
+    }
+
+    for (const t of Object.values(tokens)) {
+      if (options.ignore && isTokenMatch(t.id, options.ignore)) {
+        continue;
+      }
+
+      // skip aliases
+      if (t.aliasOf) {
+        continue;
+      }
+
+      if (t.$type === 'typography' && 'fontSize' in t.$value) {
+        const fontSize = t.$value.fontSize!;
+
+        if (
+          (fontSize.unit === 'px' && options.minSizePx && fontSize.value < options.minSizePx) ||
+          (fontSize.unit === 'rem' && options.minSizeRem && fontSize.value < options.minSizeRem)
+        ) {
+          report({
+            messageId: ERROR_TOO_SMALL,
+            data: {
+              id: t.id,
+              min: options.minSizePx ? `${options.minSizePx}px` : `${options.minSizeRem}rem`,
+            },
+          });
+        }
+      }
+    }
+  },
+};
+
+export default rule;

package/src/lint/plugin-core/rules/colorspace.ts

@@ -0,0 +1,101 @@
+import { type ColorValueNormalized, isTokenMatch } from '@terrazzo/token-tools';
+import type { LintRule } from '../../../types.js';
+import { docsLink } from '../lib/docs.js';
+
+export const COLORSPACE = 'core/colorspace';
+
+export interface RuleColorspaceOptions {
+  colorSpace: ColorValueNormalized['colorSpace'];
+  /** (optional) Token IDs to ignore. Supports globs (`*`). */
+  ignore?: string[];
+}
+
+const ERROR_COLOR = 'COLOR';
+const ERROR_BORDER = 'BORDER';
+const ERROR_GRADIENT = 'GRADIENT';
+const ERROR_SHADOW = 'SHADOW';
+
+const rule: LintRule<
+  typeof ERROR_COLOR | typeof ERROR_BORDER | typeof ERROR_GRADIENT | typeof ERROR_SHADOW,
+  RuleColorspaceOptions
+> = {
+  meta: {
+    messages: {
+      [ERROR_COLOR]: 'Color {{ id }} not in colorspace {{ colorSpace }}',
+      [ERROR_BORDER]: 'Border {{ id }} not in colorspace {{ colorSpace }}',
+      [ERROR_GRADIENT]: 'Gradient {{ id }} not in colorspace {{ colorSpace }}',
+      [ERROR_SHADOW]: 'Shadow {{ id }} not in colorspace {{ colorSpace }}',
+    },
+    docs: {
+      description: 'Enforce that all colors are in a specific colorspace.',
+      url: docsLink(COLORSPACE),
+    },
+  },
+  defaultOptions: { colorSpace: 'srgb' },
+  create({ tokens, options, report }) {
+    if (!options.colorSpace) {
+      return;
+    }
+
+    for (const t of Object.values(tokens)) {
+      // skip ignored tokens
+      if (options?.ignore && isTokenMatch(t.id, options.ignore)) {
+        continue;
+      }
+
+      // skip aliases
+      if (t.aliasOf) {
+        continue;
+      }
+
+      switch (t.$type) {
+        case 'color': {
+          if (t.$value.colorSpace !== options.colorSpace) {
+            report({
+              messageId: ERROR_COLOR,
+              data: { id: t.id, colorSpace: options.colorSpace },
+              node: t.source.node,
+            });
+          }
+          break;
+        }
+        case 'border': {
+          if (!t.partialAliasOf?.color && t.$value.color.colorSpace !== options.colorSpace) {
+            report({
+              messageId: ERROR_BORDER,
+              data: { id: t.id, colorSpace: options.colorSpace },
+              node: t.source.node,
+            });
+          }
+          break;
+        }
+        case 'gradient': {
+          for (let stopI = 0; stopI < t.$value.length; stopI++) {
+            if (!t.partialAliasOf?.[stopI]?.color && t.$value[stopI]!.color.colorSpace !== options.colorSpace) {
+              report({
+                messageId: ERROR_GRADIENT,
+                data: { id: t.id, colorSpace: options.colorSpace },
+                node: t.source.node,
+              });
+            }
+          }
+          break;
+        }
+        case 'shadow': {
+          for (let shadowI = 0; shadowI < t.$value.length; shadowI++) {
+            if (!t.partialAliasOf?.[shadowI]?.color && t.$value[shadowI]!.color.colorSpace !== options.colorSpace) {
+              report({
+                messageId: ERROR_SHADOW,
+                data: { id: t.id, colorSpace: options.colorSpace },
+                node: t.source.node,
+              });
+            }
+          }
+          break;
+        }
+      }
+    }
+  },
+};
+
+export default rule;

package/src/lint/plugin-core/rules/consistent-naming.ts

@@ -0,0 +1,65 @@
+import { camelCase, kebabCase, pascalCase, snakeCase } from 'scule';
+import type { LintRule } from '../../../types.js';
+import { docsLink } from '../lib/docs.js';
+
+export const CONSISTENT_NAMING = 'core/consistent-naming';
+export const ERROR_WRONG_FORMAT = 'ERROR_WRONG_FORMAT';
+
+export interface RuleConsistentNamingOptions {
+  /** Specify format, or custom naming validator */
+  format:
+    | 'kebab-case'
+    | 'camelCase'
+    | 'PascalCase'
+    | 'snake_case'
+    | 'SCREAMING_SNAKE_CASE'
+    | ((tokenID: string) => boolean);
+  /** Token IDs to ignore. Supports globs (`*`). */
+  ignore?: string[];
+}
+
+const rule: LintRule<typeof ERROR_WRONG_FORMAT, RuleConsistentNamingOptions> = {
+  meta: {
+    messages: {
+      [ERROR_WRONG_FORMAT]: '{{ id }} doesn’t match format {{ format }}',
+    },
+    docs: {
+      description: 'Enforce consistent naming for tokens.',
+      url: docsLink(CONSISTENT_NAMING),
+    },
+  },
+  defaultOptions: { format: 'kebab-case' },
+  create({ tokens, options, report }) {
+    const basicFormatter = {
+      'kebab-case': kebabCase,
+      camelCase,
+      PascalCase: pascalCase,
+      snake_case: snakeCase,
+      SCREAMING_SNAKE_CASE: (name: string) => snakeCase(name).toLocaleUpperCase(),
+    }[String(options.format)];
+
+    for (const t of Object.values(tokens)) {
+      if (basicFormatter) {
+        const parts = t.id.split('.');
+        if (!parts.every((part) => basicFormatter(part) === part)) {
+          report({
+            messageId: ERROR_WRONG_FORMAT,
+            data: { id: t.id, format: options.format },
+            node: t.source.node,
+          });
+        }
+      } else if (typeof options.format === 'function') {
+        const result = options.format(t.id);
+        if (result) {
+          report({
+            messageId: ERROR_WRONG_FORMAT,
+            data: { id: t.id, format: '(custom)' },
+            node: t.source.node,
+          });
+        }
+      }
+    }
+  },
+};
+
+export default rule;

package/src/lint/plugin-core/rules/descriptions.ts

@@ -0,0 +1,41 @@
+import { isTokenMatch } from '@terrazzo/token-tools';
+import type { LintRule } from '../../../types.js';
+import { docsLink } from '../lib/docs.js';
+
+export const DESCRIPTIONS = 'core/descriptions';
+
+export interface RuleDescriptionsOptions {
+  /** Token IDs to ignore. Supports globs (`*`). */
+  ignore?: string[];
+}
+
+const ERROR_MISSING_DESCRIPTION = 'MISSING_DESCRIPTION';
+
+const rule: LintRule<typeof ERROR_MISSING_DESCRIPTION, RuleDescriptionsOptions> = {
+  meta: {
+    messages: {
+      [ERROR_MISSING_DESCRIPTION]: '{{ id }} missing description',
+    },
+    docs: {
+      description: 'Enforce tokens have descriptions.',
+      url: docsLink(DESCRIPTIONS),
+    },
+  },
+  defaultOptions: {},
+  create({ tokens, options, report }) {
+    for (const t of Object.values(tokens)) {
+      if (options.ignore && isTokenMatch(t.id, options.ignore)) {
+        continue;
+      }
+      if (!t.$description) {
+        report({
+          messageId: ERROR_MISSING_DESCRIPTION,
+          data: { id: t.id },
+          node: t.source.node,
+        });
+      }
+    }
+  },
+};
+
+export default rule;

package/src/lint/plugin-core/rules/duplicate-values.ts

@@ -0,0 +1,80 @@
+import { isAlias, isTokenMatch } from '@terrazzo/token-tools';
+import type { LintRule } from '../../../types.js';
+import { docsLink } from '../lib/docs.js';
+
+export const DUPLICATE_VALUES = 'core/duplicate-values';
+
+export interface RuleDuplicateValueOptions {
+  /** Token IDs to ignore. Supports globs (`*`). */
+  ignore?: string[];
+}
+
+const ERROR_DUPLICATE_VALUE = 'ERROR_DUPLICATE_VALUE';
+
+const rule: LintRule<typeof ERROR_DUPLICATE_VALUE, RuleDuplicateValueOptions> = {
+  meta: {
+    messages: {
+      [ERROR_DUPLICATE_VALUE]: '{{ id }} declared a duplicate value',
+    },
+    docs: {
+      description: 'Enforce tokens can’t redeclare the same value (excludes aliases).',
+      url: docsLink(DUPLICATE_VALUES),
+    },
+  },
+  defaultOptions: {},
+  create({ report, tokens, options }) {
+    const values: Record<string, Set<any>> = {};
+
+    for (const t of Object.values(tokens)) {
+      // skip ignored tokens
+      if (options.ignore && isTokenMatch(t.id, options.ignore)) {
+        continue;
+      }
+
+      if (!values[t.$type]) {
+        values[t.$type] = new Set();
+      }
+
+      // primitives: direct comparison is easy
+      if (
+        t.$type === 'boolean' ||
+        t.$type === 'duration' ||
+        t.$type === 'fontWeight' ||
+        t.$type === 'link' ||
+        t.$type === 'number' ||
+        t.$type === 'string'
+      ) {
+        // skip aliases (note: $value will be resolved)
+        if (isAlias(t.aliasOf)) {
+          continue;
+        }
+
+        if (values[t.$type]?.has(t.$value)) {
+          report({
+            messageId: ERROR_DUPLICATE_VALUE,
+            data: { id: t.id },
+            node: t.source.node,
+          });
+        }
+
+        values[t.$type]?.add(t.$value);
+      } else {
+        // everything else: use deepEqual
+        for (const v of values[t.$type]!.values() ?? []) {
+          // TODO: don’t JSON.stringify
+          if (JSON.stringify(t.$value) === JSON.stringify(v)) {
+            report({
+              messageId: ERROR_DUPLICATE_VALUE,
+              data: { id: t.id },
+              node: t.source.node,
+            });
+            break;
+          }
+        }
+        values[t.$type]!.add(t.$value);
+      }
+    }
+  },
+};
+
+export default rule;

package/src/lint/plugin-core/rules/max-gamut.ts

@@ -0,0 +1,121 @@
+import { type ColorValueNormalized, isTokenMatch, tokenToCulori } from '@terrazzo/token-tools';
+import { type Color, clampChroma } from 'culori';
+import type { LintRule } from '../../../types.js';
+import { docsLink } from '../lib/docs.js';
+
+export const MAX_GAMUT = 'core/max-gamut';
+
+export interface RuleMaxGamutOptions {
+  /** Gamut to constrain color tokens to. */
+  gamut: 'srgb' | 'p3' | 'rec2020';
+  /** (optional) Token IDs to ignore. Supports globs (`*`). */
+  ignore?: string[];
+}
+
+const TOLERANCE = 0.000001; // threshold above which it counts as an error (take rounding errors into account)
+
+/** is a Culori-parseable color within the specified gamut? */
+function isWithinGamut(color: ColorValueNormalized, gamut: RuleMaxGamutOptions['gamut']): boolean {
+  const parsed = tokenToCulori(color);
+  if (!parsed) {
+    return false;
+  }
+  if (['rgb', 'hsl', 'hsv', 'hwb'].includes(parsed.mode)) {
+    return true;
+  }
+  const clamped = clampChroma(parsed, parsed.mode, gamut === 'srgb' ? 'rgb' : gamut);
+  return isWithinThreshold(parsed, clamped);
+}
+
+/** is Color A close enough to Color B? */
+function isWithinThreshold(a: Color, b: Color, tolerance = TOLERANCE) {
+  for (const k in a) {
+    if (k === 'mode' || k === 'alpha') {
+      continue;
+    }
+    if (!(k in b)) {
+      throw new Error(`Can’t compare ${a.mode} to ${b.mode}`);
+    }
+    if (Math.abs((a as any)[k] - (b as any)[k]) > tolerance) {
+      return false;
+    }
+  }
+  return true;
+}
+
+const ERROR_COLOR = 'COLOR';
+const ERROR_BORDER = 'BORDER';
+const ERROR_GRADIENT = 'GRADIENT';
+const ERROR_SHADOW = 'SHADOW';
+
+const rule: LintRule<
+  typeof ERROR_COLOR | typeof ERROR_BORDER | typeof ERROR_GRADIENT | typeof ERROR_SHADOW,
+  RuleMaxGamutOptions
+> = {
+  meta: {
+    messages: {
+      [ERROR_COLOR]: 'Color {{ id }} is outside {{ gamut }} gamut',
+      [ERROR_BORDER]: 'Border {{ id }} is outside {{ gamut }} gamut',
+      [ERROR_GRADIENT]: 'Gradient {{ id }} is outside {{ gamut }} gamut',
+      [ERROR_SHADOW]: 'Shadow {{ id }} is outside {{ gamut }} gamut',
+    },
+    docs: {
+      description: 'Enforce colors are within the specified gamut.',
+      url: docsLink(MAX_GAMUT),
+    },
+  },
+  defaultOptions: { gamut: 'rec2020' },
+  create({ tokens, options, report }) {
+    if (!options?.gamut) {
+      return;
+    }
+    if (options.gamut !== 'srgb' && options.gamut !== 'p3' && options.gamut !== 'rec2020') {
+      throw new Error(`Unknown gamut "${options.gamut}". Options are "srgb", "p3", or "rec2020"`);
+    }
+
+    for (const t of Object.values(tokens)) {
+      // skip ignored tokens
+      if (options.ignore && isTokenMatch(t.id, options.ignore)) {
+        continue;
+      }
+
+      // skip aliases
+      if (t.aliasOf) {
+        continue;
+      }
+
+      switch (t.$type) {
+        case 'color': {
+          if (!isWithinGamut(t.$value, options.gamut)) {
+            report({ messageId: ERROR_COLOR, data: { id: t.id, gamut: options.gamut }, node: t.source.node });
+          }
+          break;
+        }
+        case 'border': {
+          if (!t.partialAliasOf?.color && !isWithinGamut(t.$value.color, options.gamut)) {
+            report({ messageId: ERROR_BORDER, data: { id: t.id, gamut: options.gamut }, node: t.source.node });
+          }
+          break;
+        }
+        case 'gradient': {
+          for (let stopI = 0; stopI < t.$value.length; stopI++) {
+            if (!t.partialAliasOf?.[stopI]?.color && !isWithinGamut(t.$value[stopI]!.color, options.gamut)) {
+              report({ messageId: ERROR_GRADIENT, data: { id: t.id, gamut: options.gamut }, node: t.source.node });
+            }
+          }
+          break;
+        }
+        case 'shadow': {
+          for (let shadowI = 0; shadowI < t.$value.length; shadowI++) {
+            if (!t.partialAliasOf?.[shadowI]?.color && !isWithinGamut(t.$value[shadowI]!.color, options.gamut)) {
+              report({ messageId: ERROR_SHADOW, data: { id: t.id, gamut: options.gamut }, node: t.source.node });
+            }
+          }
+          break;
+        }
+      }
+    }
+  },
+};
+
+export default rule;

package/src/lint/plugin-core/rules/required-children.ts

@@ -0,0 +1,104 @@
+import { isTokenMatch } from '@terrazzo/token-tools';
+import type { LintRule } from '../../../types.js';
+import { docsLink } from '../lib/docs.js';
+
+export const REQUIRED_CHILDREN = 'core/required-children';
+
+export interface RequiredChildrenMatch {
+  /** Glob of tokens/groups to match */
+  match: string[];
+  /** Required token IDs to match (this only looks at the very last segment of a token ID!) */
+  requiredTokens?: string[];
+  /** Required groups to match (this only looks at the beginning/middle segments of a token ID!) */
+  requiredGroups?: string[];
+}
+
+export interface RuleRequiredChildrenOptions {
+  matches: RequiredChildrenMatch[];
+}
+
+export const ERROR_EMPTY_MATCH = 'EMPTY_MATCH';
+export const ERROR_MISSING_REQUIRED_TOKENS = 'MISSING_REQUIRED_TOKENS';
+export const ERROR_MISSING_REQUIRED_GROUP = 'MISSING_REQUIRED_GROUP';
+
+const rule: LintRule<
+  typeof ERROR_EMPTY_MATCH | typeof ERROR_MISSING_REQUIRED_TOKENS | typeof ERROR_MISSING_REQUIRED_GROUP,
+  RuleRequiredChildrenOptions
+> = {
+  meta: {
+    messages: {
+      [ERROR_EMPTY_MATCH]: 'No tokens matched {{ matcher }}',
+      [ERROR_MISSING_REQUIRED_TOKENS]: 'Match {{ index }}: some groups missing required token "{{ token }}"',
+      [ERROR_MISSING_REQUIRED_GROUP]: 'Match {{ index }}: some tokens missing required group "{{ group }}"',
+    },
+    docs: {
+      description: 'Enforce token groups have specific children, whether tokens and/or groups.',
+      url: docsLink(REQUIRED_CHILDREN),
+    },
+  },
+  defaultOptions: { matches: [] },
+  create({ tokens, options, report }) {
+    if (!options.matches?.length) {
+      throw new Error('Invalid config. Missing `matches: […]`');
+    }
+
+    // note: in many other rules, the operation can be completed in one iteration through all tokens
+    // in this rule, however, we have to scan all tokens every time per-match, because they may overlap
+
+    for (let matchI = 0; matchI < options.matches.length; matchI++) {
+      const { match, requiredTokens, requiredGroups } = options.matches[matchI]!;
+
+      // validate
+      if (!match.length) {
+        throw new Error(`Match ${matchI}: must declare \`match: […]\``);
+      }
+      if (!requiredTokens?.length && !requiredGroups?.length) {
+        throw new Error(`Match ${matchI}: must declare either \`requiredTokens: […]\` or \`requiredGroups: […]\``);
+      }
+
+      const matchGroups: string[] = [];
+      const matchTokens: string[] = [];
+      let tokensMatched = false;
+      for (const t of Object.values(tokens)) {
+        if (!isTokenMatch(t.id, match)) {
+          continue;
+        }
+        tokensMatched = true;
+        const groups = t.id.split('.');
+        matchTokens.push(groups.pop()!);
+        matchGroups.push(...groups);
+      }
+
+      if (!tokensMatched) {
+        report({
+          messageId: ERROR_EMPTY_MATCH,
+          data: { matcher: JSON.stringify(match) },
+        });
+        continue;
+      }
+
+      if (requiredTokens) {
+        for (const id of requiredTokens) {
+          if (!matchTokens.includes(id)) {
+            report({
+              messageId: ERROR_MISSING_REQUIRED_TOKENS,
+              data: { index: matchI, token: id },
+            });
+          }
+        }
+      }
+      if (requiredGroups) {
+        for (const groupName of requiredGroups) {
+          if (!matchGroups.includes(groupName)) {
+            report({
+              messageId: ERROR_MISSING_REQUIRED_GROUP,
+              data: { index: matchI, group: groupName },
+            });
+          }
+        }
+      }
+    }
+  },
+};
+
+export default rule;

package/src/lint/plugin-core/rules/required-modes.ts

@@ -0,0 +1,71 @@
+import { isTokenMatch } from '@terrazzo/token-tools';
+import type { LintRule } from '../../../types.js';
+import { docsLink } from '../lib/docs.js';
+
+export const REQUIRED_MODES = 'core/required-modes';
+
+export type RequiredModesMatch = {
+  /** Glob of tokens/groups to match */
+  match: string[];
+  /** Required modes */
+  modes: string[];
+};
+
+export interface RuleRequiredModesOptions {
+  matches: RequiredModesMatch[];
+}
+
+const rule: LintRule<never, RuleRequiredModesOptions> = {
+  meta: {
+    docs: {
+      description: 'Enforce certain tokens have specific modes.',
+      url: docsLink(REQUIRED_MODES),
+    },
+  },
+  defaultOptions: { matches: [] },
+  create({ tokens, options, report }) {
+    if (!options?.matches?.length) {
+      throw new Error('Invalid config. Missing `matches: […]`');
+    }
+
+    // note: in many other rules, the operation can be completed in one iteration through all tokens
+    // in this rule, however, we have to scan all tokens every time per-match, because they may overlap
+    for (let matchI = 0; matchI < options.matches.length; matchI++) {
+      const { match, modes } = options.matches[matchI]!;
+
+      // validate
+      if (!match.length) {
+        throw new Error(`Match ${matchI}: must declare \`match: […]\``);
+      }
+      if (!modes?.length) {
+        throw new Error(`Match ${matchI}: must declare \`modes: […]\``);
+      }
+
+      let tokensMatched = false;
+      for (const t of Object.values(tokens)) {
+        if (!isTokenMatch(t.id, match)) {
+          continue;
+        }
+        tokensMatched = true;
+
+        for (const mode of modes) {
+          if (!t.mode?.[mode]) {
+            report({
+              message: `Token ${t.id}: missing required mode "${mode}"`,
+              node: t.source.node,
+            });
+          }
+        }
+
+        if (!tokensMatched) {
+          report({
+            message: `Match "${matchI}": no tokens matched ${JSON.stringify(match)}`,
+            node: t.source.node,
+          });
+        }
+      }
+    }
+  },
+};
+
+export default rule;