@terrazzo/parser 0.1.3 → 0.2.0

package/src/config.ts

@@ -0,0 +1,280 @@
+import { merge } from 'merge-anything';
+import coreLintPlugin from './lint/plugin-core/index.js';
+import Logger from './logger.js';
+import type { Config, ConfigInit, ConfigOptions, LintRuleSeverity } from './types.js';
+
+const TRAILING_SLASH_RE = /\/*$/;
+
+/**
+ * Validate and normalize a config
+ */
+export default function defineConfig(
+  rawConfig: Config,
+  { logger = new Logger(), cwd }: ConfigOptions = {} as ConfigOptions,
+): ConfigInit {
+  const configStart = performance.now();
+
+  if (!cwd) {
+    logger.error({ label: 'core', message: 'defineConfig() missing `cwd` for JS API' });
+  }
+
+  logger.debug({ group: 'parser', label: 'config', message: 'Start config validation' });
+
+  const config = merge({}, rawConfig) as unknown as ConfigInit;
+
+  // 1. normalize and init
+  normalizeTokens({ rawConfig, config, logger, cwd });
+  normalizeOutDir({ config, cwd, logger });
+  normalizePlugins({ config, logger });
+  normalizeLint({ config, logger });
+  normalizeIgnore({ config, logger });
+
+  // 2. Start build by calling config()
+  for (const plugin of config.plugins) {
+    plugin.config?.({ ...config });
+  }
+
+  // 3. finish
+  logger.debug({
+    group: 'parser',
+    label: 'config',
+    message: 'Finish config validation',
+    timing: performance.now() - configStart,
+  });
+  return config;
+}
+
+/** Normalize config.tokens */
+function normalizeTokens({
+  rawConfig,
+  config,
+  logger,
+  cwd,
+}: { rawConfig: Config; config: ConfigInit; logger: Logger; cwd: URL }) {
+  if (rawConfig.tokens === undefined) {
+    config.tokens = [
+      // @ts-ignore we’ll normalize in next step
+      './tokens.json',
+    ];
+  } else if (typeof rawConfig.tokens === 'string') {
+    config.tokens = [
+      // @ts-ignore we’ll normalize in next step
+      rawConfig.tokens,
+    ];
+  } else if (Array.isArray(rawConfig.tokens)) {
+    config.tokens = [];
+    for (const file of rawConfig.tokens) {
+      if (typeof file === 'string' || (file as URL) instanceof URL) {
+        config.tokens.push(
+          // @ts-ignore we’ll normalize in next step
+          file,
+        );
+      } else {
+        logger.error({
+          label: '[config] tokens',
+          message: `Expected array of strings, encountered ${JSON.stringify(file)}`,
+        });
+      }
+    }
+  } else {
+    logger.error({
+      label: '[config] tokens',
+      message: `Expected string or array of strings, received ${typeof rawConfig.tokens}`,
+    });
+  }
+  for (let i = 0; i < config.tokens!.length; i++) {
+    const filepath = config.tokens[i]!;
+    if (filepath instanceof URL) {
+      continue; // skip if already resolved
+    }
+    try {
+      config.tokens[i] = new URL(filepath, cwd);
+    } catch (err) {
+      logger.error({ label: '[config] tokens', message: `Invalid URL ${filepath}` });
+    }
+  }
+}
+
+/** Normalize config.outDir */
+function normalizeOutDir({ config, cwd, logger }: { config: ConfigInit; logger: Logger; cwd: URL }) {
+  if (config.outDir instanceof URL) {
+    // noop
+  } else if (typeof config.outDir === 'undefined') {
+    config.outDir = new URL('./tokens/', cwd);
+  } else if (typeof config.outDir !== 'string') {
+    logger.error({ label: '[config] outDir', message: `Expected string, received ${JSON.stringify(config.outDir)}` });
+  } else {
+    config.outDir = new URL(config.outDir, cwd);
+    // always add trailing slash so URL treats it as a directory.
+    // do AFTER it has been normalized to POSIX paths with `href` (don’t use Node internals here! This may run in the browser)
+    config.outDir = new URL(config.outDir.href.replace(TRAILING_SLASH_RE, '/'));
+  }
+}
+
+/** Normalize config.plugins */
+function normalizePlugins({ config, logger }: { config: ConfigInit; logger: Logger }) {
+  if (typeof config.plugins === 'undefined') {
+    config.plugins = [];
+  }
+  if (!Array.isArray(config.plugins)) {
+    logger.error({
+      label: '[config] plugins',
+      message: `Expected array of plugins, received ${JSON.stringify(config.plugins)}`,
+    });
+  }
+  config.plugins.push(coreLintPlugin());
+  for (let n = 0; n < config.plugins.length; n++) {
+    const plugin = config.plugins[n];
+    if (typeof plugin !== 'object') {
+      logger.error({ label: `plugin[${n}]`, message: `Expected output plugin, received ${JSON.stringify(plugin)}` });
+    } else if (!plugin.name) {
+      logger.error({ label: `plugin[${n}]`, message: `Missing "name"` });
+    }
+  }
+  // order plugins with "enforce"
+  config.plugins.sort((a, b) => {
+    if (a.enforce === 'pre' && b.enforce !== 'pre') {
+      return -1;
+    } else if (a.enforce === 'post' && b.enforce !== 'post') {
+      return 1;
+    }
+    return 0;
+  });
+}
+
+function normalizeLint({ config, logger }: { config: ConfigInit; logger: Logger }) {
+  if (config.lint !== undefined) {
+    if (config.lint === null || typeof config.lint !== 'object' || Array.isArray(config.lint)) {
+      logger.error({ label: '[config] lint', message: 'Must be an object' });
+    }
+    if (!config.lint.build) {
+      config.lint.build = { enabled: true };
+    }
+    if (config.lint.build.enabled !== undefined) {
+      if (typeof config.lint.build.enabled !== 'boolean') {
+        logger.error({
+          label: '[config] lint › build › enabled',
+          message: `Expected boolean, received ${JSON.stringify(config.lint.build)}`,
+        });
+      }
+    } else {
+      config.lint.build.enabled = true;
+    }
+
+    if (config.lint.rules === undefined) {
+      config.lint.rules = {};
+    } else {
+      if (config.lint.rules === null || typeof config.lint.rules !== 'object' || Array.isArray(config.lint.rules)) {
+        logger.error({
+          label: '[config] lint › rules',
+          message: `Expected object, received ${JSON.stringify(config.lint.rules)}`,
+        });
+        return;
+      }
+
+      const allRules = new Map<string, string>();
+      for (const plugin of config.plugins) {
+        if (typeof plugin.lint !== 'function') {
+          continue;
+        }
+        const pluginRules = plugin.lint();
+        if (!pluginRules || Array.isArray(pluginRules) || typeof pluginRules !== 'object') {
+          logger.error({
+            label: `[config] plugin › ${plugin.name}`,
+            message: `Expected object for lint() received ${JSON.stringify(pluginRules)}`,
+          });
+          continue;
+        }
+        for (const rule of Object.keys(pluginRules)) {
+          // Note: sometimes plugins will be loaded multiple times, in which case it’s expected
+          // they’re register rules again for lint(). Only throw an error if plugin A and plugin B’s
+          // rules conflict.
+
+          if (allRules.get(rule) && allRules.get(rule) !== plugin.name) {
+            logger.error({
+              label: `[config] plugin › ${plugin.name}`,
+              message: `Duplicate rule ${rule} already registered by plugin ${allRules.get(rule)}`,
+            });
+          }
+          allRules.set(rule, plugin.name);
+        }
+      }
+
+      for (const id of Object.keys(config.lint.rules)) {
+        if (!allRules.has(id)) {
+          logger.error({
+            label: `[config] lint › rule › ${id}`,
+            message: 'Unknown rule. Is the plugin installed?',
+          });
+        }
+
+        const value = config.lint.rules[id];
+        let severity: LintRuleSeverity = 'off';
+        let options: any;
+        if (typeof value === 'number' || typeof value === 'string') {
+          severity = value;
+        } else if (Array.isArray(value)) {
+          severity = value[0] as LintRuleSeverity;
+          options = value[1];
+        } else if (value !== undefined) {
+          logger.error({
+            label: `[config] lint › rule › ${id}`,
+            message: `Invalid eyntax. Expected \`string | number | Array\`, received ${JSON.stringify(value)}}`,
+          });
+        }
+        config.lint.rules[id] = [severity, options];
+        if (typeof severity === 'number') {
+          if (severity !== 0 && severity !== 1 && severity !== 2) {
+            logger.error({
+              label: `[config] lint › rule › ${id}`,
+              message: `Invalid number ${severity}. Specify 0 (off), 1 (warn), or 2 (error).`,
+            });
+          }
+          config.lint.rules[id]![0] = (['off', 'warn', 'error'] as const)[severity]!;
+        } else if (typeof severity === 'string') {
+          if (severity !== 'off' && severity !== 'warn' && severity !== 'error') {
+            logger.error({
+              label: `[config] lint › rule › ${id}`,
+              message: `Invalid string ${JSON.stringify(severity)}. Specify "off", "warn", or "error".`,
+            });
+          }
+        } else if (value !== null) {
+          logger.error({
+            label: `[config] lint › rule › ${id}`,
+            message: `Expected string or number, received ${JSON.stringify(value)}`,
+          });
+        }
+      }
+    }
+  } else {
+    config.lint = {
+      build: { enabled: true },
+      rules: {},
+    };
+  }
+}
+
+function normalizeIgnore({ config, logger }: { config: ConfigInit; logger: Logger }) {
+  if (!config.ignore) {
+    config.ignore = {} as typeof config.ignore;
+  }
+  config.ignore.tokens ??= [];
+  config.ignore.deprecated ??= false;
+  if (!Array.isArray(config.ignore.tokens) || config.ignore.tokens.some((x) => typeof x !== 'string')) {
+    logger.error({
+      label: '[config] ignore › tokens',
+      message: `Expected array of strings, received ${JSON.stringify(config.ignore.tokens)}`,
+    });
+  }
+  if (typeof config.ignore.deprecated !== 'boolean') {
+    logger.error({
+      label: '[config] ignore › deprecated',
+      message: `Expected boolean, received ${JSON.stringify(config.ignore.deprecated)}`,
+    });
+  }
+}
+
+/** Merge configs */
+export function mergeConfigs(a: Config, b: Config): Config {
+  return merge(a, b);
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+export { default as build } from './build/index.js';
+export * from './build/index.js';
+
+export { default as defineConfig } from './config.js';
+export * from './config.js';
+
+export { default as lintRunner } from './lint/index.js';
+export * from './lint/index.js';
+
+export { default as Logger } from './logger.js';
+export * from './logger.js';
+
+export { default as parse } from './parse/index.js';
+export * from './parse/index.js';
+
+export * from './types.js';
+
+export * from '@terrazzo/token-tools/dist/types.js';

package/{lib/code-frame.js → src/lib/code-frame.ts}

@@ -25,17 +25,50 @@
 // OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
+export interface Location {
+  line: number;
+  column: number;
+}
+
+export interface NodeLocation {
+  end?: Location;
+  start: Location;
+}
+
+export interface Options {
+  /** Syntax highlight the code as JavaScript for terminals. default: false */
+  highlightCode?: boolean;
+  /**  The number of lines to show above the error. default: 2 */
+  linesAbove?: number;
+  /**  The number of lines to show below the error. default: 3 */
+  linesBelow?: number;
+  /**
+   * Forcibly syntax highlight the code as JavaScript (for non-terminals);
+   * overrides highlightCode.
+   * default: false
+   */
+  forceColor?: boolean;
+  /**
+   * Pass in a string to be displayed inline (if possible) next to the
+   * highlighted location in the code. If it can't be positioned inline,
+   * it will be placed above the code frame.
+   * default: nothing
+   */
+  message?: string;
+}
+
 /**
  * Extract what lines should be marked and highlighted.
  */
-
-function getMarkerLines(loc, source, opts = {}) {
+function getMarkerLines(loc: NodeLocation, source: string[], opts: Options = {} as Options) {
   const startLoc = {
+    // @ts-ignore this is fine
     column: 0,
+    // @ts-ignore this is fine
     line: -1,
     ...loc.start,
-  };
-  const endLoc = {
+  } as Location;
+  const endLoc: Location = {
     ...startLoc,
     ...loc.end,
   };
@@ -57,7 +90,7 @@ function getMarkerLines(loc, source, opts = {}) {
   }
 
   const lineDiff = endLine - startLine;
-  const markerLines = {};
+  const markerLines: Record<string, any> = {};
 
   if (lineDiff) {
     for (let i = 0; i <= lineDiff; i++) {
@@ -66,13 +99,13 @@ function getMarkerLines(loc, source, opts = {}) {
       if (!startColumn) {
         markerLines[lineNumber] = true;
       } else if (i === 0) {
-        const sourceLength = source[lineNumber - 1].length;
+        const sourceLength = source[lineNumber - 1]!.length;
 
         markerLines[lineNumber] = [startColumn, sourceLength - startColumn + 1];
       } else if (i === lineDiff) {
         markerLines[lineNumber] = [0, endColumn];
       } else {
-        const sourceLength = source[lineNumber - i].length;
+        const sourceLength = source[lineNumber - i]!.length;
 
         markerLines[lineNumber] = [0, sourceLength];
       }
@@ -98,7 +131,7 @@ function getMarkerLines(loc, source, opts = {}) {
 
 const NEWLINE = /\r\n|[\n\r\u2028\u2029]/;
 
-export function codeFrameColumns(rawLines, loc, opts = {}) {
+export function codeFrameColumns(rawLines: string, loc: NodeLocation, opts: Options = {} as Options) {
   const lines = rawLines.split(NEWLINE);
   const { start, end, markerLines } = getMarkerLines(loc, lines, opts);
   const hasColumns = loc.start && typeof loc.start.column === 'number';

package/src/lint/index.ts

@@ -0,0 +1,135 @@
+import { type TokenNormalized, pluralize } from '@terrazzo/token-tools';
+import { merge } from 'merge-anything';
+import type { LogEntry, default as Logger } from '../logger.js';
+import type { ConfigInit } from '../types.js';
+
+const listFormat = new Intl.ListFormat('en-us');
+
+export interface LintRunnerOptions {
+  tokens: Record<string, TokenNormalized>;
+  filename?: URL;
+  config: ConfigInit;
+  src: string;
+  logger: Logger;
+}
+
+export default async function lintRunner({
+  tokens,
+  filename,
+  config = {} as ConfigInit,
+  src,
+  logger,
+}: LintRunnerOptions): Promise<void> {
+  const { plugins = [], lint } = config;
+  const unusedLintRules = Object.keys(lint?.rules ?? {});
+
+  for (const plugin of plugins) {
+    if (typeof plugin.lint === 'function') {
+      const s = performance.now();
+
+      logger.debug({ group: 'plugin', label: plugin.name, message: 'Start linting' });
+
+      const linter = plugin.lint();
+      const errors: LogEntry[] = [];
+      const warnings: LogEntry[] = [];
+
+      await Promise.all(
+        Object.entries(linter).map(async ([id, rule]) => {
+          if (!(id in lint.rules) || lint.rules[id] === null) {
+            return;
+          }
+          const [severity, options] = lint.rules[id]!;
+          if (severity === 'off') {
+            return;
+          }
+
+          // note: this usually isn’t a Promise, but it _might_ be!
+          await rule.create({
+            id,
+            report(descriptor) {
+              let message = '';
+              if (!descriptor.message && !descriptor.messageId) {
+                logger.error({
+                  label: `[plugin] ${plugin.name} › lint › ${id}`,
+                  message: 'Unable to report error: missing message or messageId',
+                });
+              }
+
+              // handle message or messageId
+              if (descriptor.message) {
+                message = descriptor.message;
+              } else {
+                if (!(descriptor.messageId! in (rule.meta?.messages ?? {}))) {
+                  logger.error({
+                    label: `[plugin] ${plugin.name} › lint › ${id}`,
+                    message: `messageId "${descriptor.messageId}" does not exist`,
+                  });
+                }
+                message = rule.meta?.messages?.[descriptor.messageId as keyof typeof rule.meta.messages] ?? '';
+              }
+
+              // replace with descriptor.data (if any)
+              if (descriptor.data && typeof descriptor.data === 'object') {
+                for (const [k, v] of Object.entries(descriptor.data)) {
+                  // lazy formatting
+                  const formatted = ['string', 'number', 'boolean'].includes(typeof v) ? String(v) : JSON.stringify(v);
+                  message = message.replace(/{{[^}]+}}/g, (inner) => {
+                    const key = inner.substring(2, inner.length - 2).trim();
+                    return key === k ? formatted : inner;
+                  });
+                }
+              }
+
+              (severity === 'error' ? errors : warnings).push({
+                label: id,
+                message,
+                filename,
+                node: descriptor.node,
+                src: descriptor.source?.src,
+              });
+            },
+            tokens,
+            filename,
+            src,
+            options: merge(
+              rule.meta?.defaultOptions ?? [],
+              rule.defaultOptions ?? [], // Note: is this the correct order to merge in?
+              options,
+            ),
+          });
+          // tick off used rule
+          const unusedLintRuleI = unusedLintRules.indexOf(id);
+          if (unusedLintRuleI !== -1) {
+            unusedLintRules.splice(unusedLintRuleI, 1);
+          }
+        }),
+      );
+
+      for (const error of errors) {
+        logger.error({ ...error, continueOnError: true }); // print out all errors before exiting here
+      }
+      for (const warning of warnings) {
+        logger.warn(warning);
+      }
+
+      logger.debug({ group: 'plugin', label: plugin.name, message: 'Finish linting', timing: performance.now() - s });
+
+      if (errors.length) {
+        const counts = [pluralize(errors.length, 'error', 'errors')];
+        if (warnings.length) {
+          counts.push(pluralize(warnings.length, 'warning', 'warnings'));
+        }
+        logger.error({
+          message: `Lint failed with ${listFormat.format(counts)}`,
+          label: plugin.name,
+          continueOnError: false,
+        });
+      }
+    }
+  }
+
+  // warn user if they have unused lint rules (they might have meant to configure something!)
+  for (const unusedRule of unusedLintRules) {
+    logger.warn({ group: 'parser', label: 'lint', message: `Unknown lint rule "${unusedRule}"` });
+  }
+}

package/src/lint/plugin-core/index.ts

@@ -0,0 +1,47 @@
+// Terrazzo internal plugin that powers lint rules. Always enabled (but all
+// rules are opt-in).
+import type { Plugin } from '../../types.js';
+
+export * from './rules/a11y-min-contrast.js';
+export * from './rules/a11y-min-font-size.js';
+export * from './rules/colorspace.js';
+export * from './rules/consistent-naming.js';
+export * from './rules/descriptions.js';
+export * from './rules/duplicate-values.js';
+export * from './rules/max-gamut.js';
+export * from './rules/required-children.js';
+export * from './rules/required-modes.js';
+export * from './rules/required-typography-properties.js';
+
+import a11yMinContrast, { A11Y_MIN_CONTRAST } from './rules/a11y-min-contrast.js';
+import a11yMinFontSize, { A11Y_MIN_FONT_SIZE } from './rules/a11y-min-font-size.js';
+import colorspace, { COLORSPACE } from './rules/colorspace.js';
+import consistentNaming, { CONSISTENT_NAMING } from './rules/consistent-naming.js';
+import descriptions, { DESCRIPTIONS } from './rules/descriptions.js';
+import duplicateValues, { DUPLICATE_VALUES } from './rules/duplicate-values.js';
+import maxGamut, { MAX_GAMUT } from './rules/max-gamut.js';
+import requiredChidlren, { REQUIRED_CHILDREN } from './rules/required-children.js';
+import requiredModes, { REQUIRED_MODES } from './rules/required-modes.js';
+import requiredTypographyProperties, {
+  REQUIRED_TYPOGRAPHY_PROPERTIES,
+} from './rules/required-typography-properties.js';
+
+export default function coreLintPlugin(): Plugin {
+  return {
+    name: '@terrazzo/plugin-lint-core',
+    lint() {
+      return {
+        [COLORSPACE]: colorspace,
+        [CONSISTENT_NAMING]: consistentNaming,
+        [DESCRIPTIONS]: descriptions,
+        [DUPLICATE_VALUES]: duplicateValues,
+        [MAX_GAMUT]: maxGamut,
+        [REQUIRED_CHILDREN]: requiredChidlren,
+        [REQUIRED_MODES]: requiredModes,
+        [REQUIRED_TYPOGRAPHY_PROPERTIES]: requiredTypographyProperties,
+        [A11Y_MIN_CONTRAST]: a11yMinContrast,
+        [A11Y_MIN_FONT_SIZE]: a11yMinFontSize,
+      };
+    },
+  };
+}

package/src/lint/plugin-core/lib/docs.ts

@@ -0,0 +1,3 @@
+export function docsLink(ruleName: string): string {
+  return `https://terrazzo.app/docs/cli/lint#${ruleName.replaceAll('/', '-')}`;
+}

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

@@ -0,0 +1,91 @@
+import { tokenToCulori } from '@terrazzo/token-tools';
+import { wcagContrast } from 'culori';
+import type { LintRule } from '../../../types.js';
+import { docsLink } from '../lib/docs.js';
+
+export const A11Y_MIN_CONTRAST = 'a11y/min-contrast';
+
+export interface RuleA11yMinContrastOptions {
+  /**
+   * Whether to adhere to AA (minimum) or AAA (enhanced) contrast levels.
+   * @default "AA"
+   */
+  level?: 'AA' | 'AAA';
+  /** Pairs of color tokens (and optionally typography) to test */
+  pairs: ContrastPair[];
+}
+
+export interface ContrastPair {
+  /** The foreground color token ID */
+  foreground: string;
+  /** The background color token ID */
+  background: string;
+  /**
+   * Is this pair for large text? Large text allows a smaller contrast ratio.
+   *
+   * Note: while WCAG has _suggested_ sizes and weights, those are merely
+   * suggestions. It’s always more reliable to determine what constitutes “large
+   * text” for your designs yourself, based on your typographic stack.
+   * @see https://www.w3.org/WAI/WCAG22/quickref/#contrast-minimum
+   */
+  largeText?: boolean;
+}
+
+export const WCAG2_MIN_CONTRAST = {
+  AA: { default: 4.5, large: 3 },
+  AAA: { default: 7, large: 4.5 },
+};
+
+export const ERROR_INSUFFICIENT_CONTRAST = 'INSUFFICIENT_CONTRAST';
+
+const rule: LintRule<typeof ERROR_INSUFFICIENT_CONTRAST, RuleA11yMinContrastOptions> = {
+  meta: {
+    messages: {
+      [ERROR_INSUFFICIENT_CONTRAST]: 'Pair {{ index }} failed; expected {{ expected }}, got {{ actual }} ({{ level }})',
+    },
+    docs: {
+      description: 'Enforce colors meet minimum contrast checks for WCAG 2.',
+      url: docsLink(A11Y_MIN_CONTRAST),
+    },
+  },
+  defaultOptions: { level: 'AA', pairs: [] },
+  create({ tokens, options, report }) {
+    for (let i = 0; i < options.pairs.length; i++) {
+      const { foreground, background, largeText } = options.pairs[i]!;
+      if (!tokens[foreground]) {
+        throw new Error(`Token ${foreground} does not exist`);
+      }
+      if (tokens[foreground].$type !== 'color') {
+        throw new Error(`Token ${foreground} isn’t a color`);
+      }
+      if (!tokens[background]) {
+        throw new Error(`Token ${background} does not exist`);
+      }
+      if (tokens[background].$type !== 'color') {
+        throw new Error(`Token ${background} isn’t a color`);
+      }
+
+      // Note: if these culors were unparseable, they would have already thrown an error before the linter
+      const a = tokenToCulori(tokens[foreground].$value)!;
+      const b = tokenToCulori(tokens[background].$value)!;
+
+      // Note: for the purposes of WCAG 2, foreground and background don’t
+      // matter. But in other contrast algorithms, they do.
+      const contrast = wcagContrast(a, b);
+      const min = WCAG2_MIN_CONTRAST[options.level ?? 'AA'][largeText ? 'large' : 'default'];
+      if (contrast < min) {
+        report({
+          messageId: ERROR_INSUFFICIENT_CONTRAST,
+          data: {
+            index: i + 1,
+            expected: min,
+            actual: Math.round(contrast * 100) / 100,
+            level: options.level,
+          },
+        });
+      }
+    }
+  },
+};
+
+export default rule;