@terrazzo/parser 2.0.0-alpha.7 → 2.0.0-beta.0

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

@@ -1,108 +0,0 @@
-import type { ColorValueNormalized } from '@terrazzo/token-tools';
-import wcmatch from 'wildcard-match';
-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;
-    }
-
-    const shouldIgnore = options.ignore ? wcmatch(options.ignore) : null;
-
-    for (const t of Object.values(tokens)) {
-      // skip ignored tokens
-      if (shouldIgnore?.(t.id)) {
-        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,
-              filename: t.source.filename,
-            });
-          }
-          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,
-              filename: t.source.filename,
-            });
-          }
-          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,
-                filename: t.source.filename,
-              });
-            }
-          }
-          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,
-                filename: t.source.filename,
-              });
-            }
-          }
-          break;
-        }
-      }
-    }
-  },
-};
-
-export default rule;

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

@@ -1,65 +0,0 @@
-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

@@ -1,43 +0,0 @@
-import wcmatch from 'wildcard-match';
-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 }) {
-    const shouldIgnore = options.ignore ? wcmatch(options.ignore) : null;
-
-    for (const t of Object.values(tokens)) {
-      if (shouldIgnore?.(t.id)) {
-        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

@@ -1,85 +0,0 @@
-import { isAlias } from '@terrazzo/token-tools';
-import wcmatch from 'wildcard-match';
-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>> = {};
-
-    const shouldIgnore = options.ignore ? wcmatch(options.ignore) : null;
-
-    for (const t of Object.values(tokens)) {
-      // skip ignored tokens
-      if (shouldIgnore?.(t.id)) {
-        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 (typeof t.aliasOf === 'string' && isAlias(t.aliasOf)) {
-          continue;
-        }
-
-        if (values[t.$type]?.has(t.$value)) {
-          report({
-            messageId: ERROR_DUPLICATE_VALUE,
-            data: { id: t.id },
-            node: t.source.node,
-            filename: t.source.filename,
-          });
-        }
-
-        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,
-              filename: t.source.filename,
-            });
-            break;
-          }
-        }
-        values[t.$type]!.add(t.$value);
-      }
-    }
-  },
-};
-
-export default rule;

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

@@ -1,144 +0,0 @@
-import { type ColorValueNormalized, tokenToCulori } from '@terrazzo/token-tools';
-import { type Color, clampChroma } from 'culori';
-import wcmatch from 'wildcard-match';
-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', '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"`);
-    }
-
-    const shouldIgnore = options.ignore ? wcmatch(options.ignore) : null;
-
-    for (const t of Object.values(tokens)) {
-      // skip ignored tokens
-      if (shouldIgnore?.(t.id)) {
-        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,
-              filename: t.source.filename,
-            });
-          }
-          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,
-              filename: t.source.filename,
-            });
-          }
-          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,
-                filename: t.source.filename,
-              });
-            }
-          }
-          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,
-                filename: t.source.filename,
-              });
-            }
-          }
-          break;
-        }
-      }
-    }
-  },
-};
-
-export default rule;

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

@@ -1,106 +0,0 @@
-import wcmatch from 'wildcard-match';
-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 matcher = wcmatch(match);
-
-      const matchGroups: string[] = [];
-      const matchTokens: string[] = [];
-      let tokensMatched = false;
-      for (const t of Object.values(tokens)) {
-        if (!matcher(t.id)) {
-          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

@@ -1,75 +0,0 @@
-import wcmatch from 'wildcard-match';
-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: […]\``);
-      }
-
-      const matcher = wcmatch(match);
-
-      let tokensMatched = false;
-      for (const t of Object.values(tokens)) {
-        if (!matcher(t.id)) {
-          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,
-              filename: t.source.filename,
-            });
-          }
-        }
-
-        if (!tokensMatched) {
-          report({
-            message: `Match "${matchI}": no tokens matched ${JSON.stringify(match)}`,
-            node: t.source.node,
-            filename: t.source.filename,
-          });
-        }
-      }
-    }
-  },
-};
-
-export default rule;

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

@@ -1,28 +0,0 @@
-import type { LintRule } from '../../../types.js';
-import { docsLink } from '../lib/docs.js';
-
-export const REQUIRED_TYPE = 'core/required-type';
-
-export const ERROR = 'ERROR';
-
-const rule: LintRule<typeof ERROR> = {
-  meta: {
-    messages: {
-      [ERROR]: 'Token missing $type.',
-    },
-    docs: {
-      description: 'Requiring every token to have $type, even aliases, simplifies computation.',
-      url: docsLink(REQUIRED_TYPE),
-    },
-  },
-  defaultOptions: {},
-  create({ tokens, report }) {
-    for (const t of Object.values(tokens)) {
-      if (!t.originalValue?.$type) {
-        report({ messageId: ERROR, node: t.source.node, filename: t.source.filename });
-      }
-    }
-  },
-};
-
-export default rule;