@terrazzo/parser 0.1.2 → 0.2.0

package/src/types.ts

@@ -0,0 +1,310 @@
+import type { AnyNode, DocumentNode } from '@humanwhocodes/momoa';
+import type { TokenNormalized } from '@terrazzo/token-tools';
+import type Logger from './logger.js';
+
+export interface BuildHookOptions {
+  /** Map of tokens */
+  tokens: Record<string, TokenNormalized>;
+  /** Query transformed values */
+  getTransforms(params: TransformParams): TokenTransformed[];
+  /** Momoa documents */
+  sources: InputSource[];
+  outputFile: (
+    /** Filename to output (relative to outDir) */
+    filename: string,
+    /** Contents to write to file */
+    contents: string | Buffer,
+  ) => void;
+}
+
+export interface BuildRunnerResult {
+  outputFiles: OutputFile[];
+}
+
+export interface BuildEndHookOptions {
+  /** Map of tokens */
+  tokens: Record<string, TokenNormalized>;
+  /** Query transformed values */
+  getTransforms(params: TransformParams): TokenTransformed[];
+  /** Momoa documents */
+  sources: InputSource[];
+  /** Final files to be written */
+  outputFiles: OutputFileExpanded[];
+}
+
+// loosey-goosey user-defined config
+export interface Config {
+  /**
+   * Path to tokens.json
+   * @default "./tokens.json"
+   */
+  tokens?: string | string[];
+  /**
+   * Output directory
+   * @default "./tokens/"
+   */
+  outDir?: string;
+  /** Specify plugins */
+  plugins?: Plugin[];
+  /** Specify linting settings */
+  lint?: {
+    /** Configure build behavior */
+    build?: {
+      /**
+       * Should linters run with `tz build`?
+       * @default true
+       */
+      enabled?: boolean;
+    };
+    /** Configure lint rules */
+    rules?: Record<string, LintRuleShorthand | LintRuleLonghand>;
+  };
+  /** Ignore token groups */
+  ignore?: {
+    /** Token patterns to ignore. Accepts globs. */
+    tokens?: string[];
+    /** Ignore deprecated tokens */
+    deprecated?: boolean;
+  };
+}
+
+// normalized, finalized config
+export interface ConfigInit {
+  tokens: URL[];
+  outDir: URL;
+  plugins: Plugin[];
+  lint: {
+    build: NonNullable<NonNullable<Config['lint']>['build']>;
+    rules: Record<string, [LintRuleSeverity, any]>;
+  };
+  ignore: {
+    tokens: string[];
+    deprecated: boolean;
+  };
+}
+
+export interface ConfigOptions {
+  logger?: Logger;
+  /** @terrazzo/parser needs cwd so this can be run without Node.js. Importing defineConfig from @terrazzo/cli doesn’t need this. */
+  cwd: URL;
+}
+
+export interface InputSource {
+  filename?: URL;
+  src: string;
+  document: DocumentNode;
+}
+
+export interface LintNotice {
+  /** Lint message shown to the user */
+  message: string;
+  /** Erring node (used to point to a specific line) */
+  node?: AnyNode;
+}
+
+export type LintRuleSeverity = 'error' | 'warn' | 'off';
+export type LintRuleShorthand = LintRuleSeverity | 0 | 1 | 2;
+export type LintRuleLonghand = [LintRuleSeverity | 0 | 1 | 2, any];
+
+export interface LintRuleNormalized<O = any> {
+  id: string;
+  severity: LintRuleSeverity;
+  options?: O;
+}
+
+export type LintReportDescriptor<MessageIds extends string> = {
+  /** To error on a specific token source file, provide an erring node */
+  node?: AnyNode;
+  /** To error on a specific token source file, also provide the source */
+  source?: InputSource;
+  /** Provide data for messages */
+  data?: Record<string, unknown>;
+} & (
+  | {
+      /** Provide the error message to display */
+      message: string;
+      messageId?: never;
+    }
+  | {
+      message?: never;
+      /** Provide the error message ID */
+      messageId: MessageIds;
+    }
+);
+
+// Note: lint types intentionally steal the API from ESLint. Options were
+// omitted where they don’t make sense (or were deprecated from ESLint—we don’t
+// need to worry about backwards compat). The types also leave room in the
+// future to be expanded easily if needed.
+
+export interface LintRule<
+  MessageIds extends string,
+  LintRuleOptions extends object | undefined = undefined,
+  LintRuleDocs = unknown,
+> {
+  meta?: LintRuleMetaData<MessageIds, LintRuleOptions, LintRuleDocs>;
+  /**
+   * Function which returns an object with methods that ESLint calls to “visit”
+   * nodes while traversing the abstract syntax tree.
+   */
+  create(context: Readonly<LintRuleContext<MessageIds, LintRuleOptions>>): void | Promise<void>;
+  /**
+   * Default options the rule will be run with
+   */
+  defaultOptions: LintRuleOptions;
+}
+
+export interface LintRuleContext<MessageIds extends string, LintRuleOptions extends object | undefined = undefined> {
+  /** The rule ID. */
+  id: string;
+  /**
+   * An array of the configured options for this rule. This array does not
+   * include the rule severity.
+   */
+  options: LintRuleOptions;
+  /** The current working directory. */
+  cwd?: URL;
+  /** Source file the token came from. */
+  src: string;
+  /** Source file location. */
+  filename?: URL;
+  /** ID:Token map of all tokens. */
+  tokens: Record<string, TokenNormalized>;
+  /** Reports a problem in the code. */
+  report(descriptor: LintReportDescriptor<MessageIds>): void;
+}
+
+export interface LintRuleMetaData<
+  MessageIds extends string,
+  LintRuleOptions extends object | undefined = undefined,
+  LintRuleDocs = unknown,
+> {
+  /**
+   * Documentation for the rule
+   */
+  docs?: LintRuleDocs & LintRuleMetaDataDocs;
+  /**
+   * A map of messages which the rule can report. The key is the messageId, and
+   * the string is the parameterised error string.
+   */
+  messages?: Record<MessageIds, string>;
+  /**
+   * Specifies default options for the rule. If present, any user-provided
+   * options in their config will be merged on top of them recursively. This
+   * merging will be applied directly to `context.options`.
+   */
+  defaultOptions?: LintRuleOptions;
+}
+
+export interface LintRuleMetaDataDocs {
+  /** Concise description of the rule. */
+  description: string;
+  /** The URL of the rule's docs. */
+  url?: string;
+}
+
+export interface OutputFile {
+  /** Filename, relative to outDir */
+  filename: string;
+  /** File contents */
+  contents: string | Buffer;
+  /** Plugin name that generated the file */
+  plugin?: string;
+  /** Time taken to generate file */
+  time?: number;
+}
+
+export interface OutputFileExpanded extends OutputFile {
+  /** The `name` of the plugin that produced this file. */
+  plugin: string;
+  /** How long this output took to make. */
+  time: number;
+}
+
+export interface Plugin {
+  name: string;
+  /** Read config, and optionally modify */
+  // biome-ignore lint/suspicious/noConfusingVoidType format: this helps plugins be a little looser on their typing
+  config?(config: ConfigInit): void | ConfigInit | undefined;
+  /**
+   * Declare:
+   * - `"pre"`: run this plugin BEFORE all others
+   * - `"post"`: run this plugin AFTER all others
+   * - (default) run this plugin in default order (array order)
+   */
+  enforce?: 'pre' | 'post';
+  /** Throw lint errors/warnings */
+  lint?(): Record<string, LintRule<any, any, any>>;
+  transform?(options: TransformHookOptions): Promise<void>;
+  build?(options: BuildHookOptions): Promise<void>;
+  buildEnd?(result: BuildRunnerResult): Promise<void>;
+}
+
+/** Transformed token with a single value. Note that this may be any type! */
+export interface TokenTransformedSingleValue {
+  /** Original Token ID */
+  id: string;
+  /** ID unique to this format. */
+  localID?: string;
+  type: 'SINGLE_VALUE';
+  value: string;
+  /**
+   * The mode of this value
+   * @default "."
+   */
+  mode: string;
+  /** The original token. */
+  token: TokenNormalized;
+}
+
+/** Transformed token with multiple values. Note that this may be any type! */
+export interface TokenTransformedMultiValue {
+  /** Original Token ID */
+  id: string;
+  /** ID unique to this format.*/
+  localID?: string;
+  type: 'MULTI_VALUE';
+  value: Record<string, string>;
+  /**
+   * The mode of this value
+   * @default "."
+   */
+  mode: string;
+  /** The original token */
+  token: TokenNormalized;
+}
+
+export type TokenTransformed = TokenTransformedSingleValue | TokenTransformedMultiValue;
+
+export interface TransformParams {
+  /** ID of an existing format */
+  format: string;
+  /** Glob of tokens to select (e.g. `"color.*"` to select all tokens starting with `"color."`) */
+  id?: string | string[];
+  /** $type(s) to filter for */
+  $type?: string | string[];
+  /**
+   * Mode name, if selecting a mode
+   * @default "."
+   */
+  mode?: string | string[];
+}
+
+export interface TransformHookOptions {
+  /** Map of tokens */
+  tokens: Record<string, TokenNormalized>;
+  /** Query transformed values */
+  getTransforms(params: TransformParams): TokenTransformed[];
+  /** Update transformed values */
+  setTransform(
+    id: string,
+    params: {
+      format: string;
+      localID?: string;
+      value: string | Record<string, string>; // allow looser type for input (`undefined` will just get stripped)
+      mode?: string;
+    },
+  ): void;
+  /** Momoa documents */
+  sources: InputSource[];
+}

package/build/index.d.ts

@@ -1,113 +0,0 @@
-import type { DocumentNode } from '@humanwhocodes/momoa';
-import type { TokenNormalized } from '@terrazzo/token-tools';
-import type { ConfigInit } from '../config.js';
-import type Logger from '../logger.js';
-
-export interface BuildRunnerOptions {
-  sources: { filename?: URL; src: string; document: DocumentNode }[];
-  config: ConfigInit;
-  logger?: Logger;
-}
-
-export interface OutputFile {
-  filename: string;
-  contents: string | Buffer;
-}
-
-export interface OutputFileExpanded extends OutputFile {
-  /** The `name` of the plugin that produced this file. */
-  plugin: string;
-  /** How long this output took to make. */
-  time: number;
-}
-
-/** Transformed token with a single value. Note that this may be any type! */
-export interface TokenTransformedSingleValue {
-  /** ID unique to this format. If missing, use `token.id`. */
-  localID?: string;
-  type: 'SINGLE_VALUE';
-  value: string;
-  /** The mode of this value (default: `"."`) */
-  mode: string;
-  /** The original token */
-  token: TokenNormalized;
-}
-
-/** Transformed token with multiple values. Note that this may be any type! */
-export interface TokenTransformedMultiValue {
-  /** ID unique to this format. If missing, use `token.id` */
-  localID?: string;
-  type: 'MULTI_VALUE';
-  value: Record<string, string>;
-  /** The mode of this value (default: `"."`) */
-  mode: string;
-  /** The original token */
-  token: TokenNormalized;
-}
-
-export type TokenTransformed = TokenTransformedSingleValue | TokenTransformedMultiValue;
-
-export interface TransformParams {
-  /** ID of an existing format */
-  format: string;
-  /** Glob of tokens to select (e.g. `"color.*"` to select all tokens starting with `"color."`) */
-  id?: string | string[];
-  /** $type(s) to filter for */
-  $type?: string | string[];
-  /** Mode name, if selecting a mode (default: `"."`) */
-  mode?: string | string[];
-}
-
-export interface TransformHookOptions {
-  /** Map of tokens */
-  tokens: Record<string, TokenNormalized>;
-  /** Query transformed values */
-  getTransforms(params: TransformParams): TokenTransformed[];
-  /** Update transformed values */
-  setTransform(
-    id: string,
-    params: {
-      format: string;
-      localID?: string;
-      value: string | Record<string, string | undefined>; // allow looser type for input (`undefined` will just get stripped)
-      mode?: string;
-    },
-  ): void;
-  /** Momoa documents */
-  sources: { filename?: URL; src: string; document: DocumentNode }[];
-}
-
-export interface BuildHookOptions {
-  /** Map of tokens */
-  tokens: Record<string, TokenNormalized>;
-  /** Query transformed values */
-  getTransforms(params: TransformParams): TokenTransformed[];
-  /** Momoa documents */
-  sources: { filename?: URL; src: string; document: DocumentNode }[];
-  outputFile: (
-    /** Filename to output (relative to outDir) */
-    filename: string,
-    /** Contents to write to file */
-    contents: string | Buffer,
-  ) => void;
-}
-
-export interface BuildRunnerResult {
-  outputFiles: OutputFile[];
-}
-
-export interface BuildEndHookOptions {
-  /** Map of tokens */
-  tokens: Record<string, TokenNormalized>;
-  /** Query transformed values */
-  getTransforms(params: TransformParams): TokenTransformed[];
-  /** Momoa documents */
-  sources: { filename?: URL; src: string; document: DocumentNode }[];
-  /** Final files to be written */
-  outputFiles: OutputFileExpanded[];
-}
-
-export default function build(
-  tokens: Record<string, TokenNormalized>,
-  options: BuildRunnerOptions,
-): Promise<BuildRunnerResult>;

package/config.d.ts

@@ -1,64 +0,0 @@
-import type { BuildHookOptions, BuildRunnerResult, TransformHookOptions } from './build/index.js';
-import type { LintRuleShorthand, LintRuleLonghand, Linter } from './lint/index.js';
-import type Logger from './logger.js';
-
-export interface Config {
-  /** Path to tokens.json (default: "./tokens.json") */
-  tokens?: string | string[];
-  /** Output directory (default: "./tokens/") */
-  outDir?: string;
-  /** Specify plugins */
-  plugins?: Plugin[];
-  /** Specify linting settings */
-  lint?: {
-    /** Configure build behavior */
-    build?: {
-      /** Should linters run with `tz build`? (default: true) */
-      enabled?: boolean;
-    };
-    /** Configure lint rules */
-    rules?: Record<string, LintRuleShorthand | LintRuleLonghand>;
-  };
-}
-
-export interface ConfigInit {
-  tokens: URL[];
-  outDir: URL;
-  plugins: Plugin[];
-  lint: {
-    build: NonNullable<NonNullable<Config['lint']>['build']>;
-    rules: Record<string, LintRuleLonghand>;
-  };
-}
-
-export interface Plugin {
-  name: string;
-  /** Read config, and optionally modify */
-  // biome-ignore lint/suspicious/noConfusingVoidType format: this helps plugins be a little looser on their typing
-  config?(config: ConfigInit): void | ConfigInit | undefined;
-  /**
-   * Declare:
-   * - `"pre"`: run this plugin BEFORE all others
-   * - `"post"`: run this plugin AFTER all others
-   * - (default) run this plugin in default order (array order)
-   */
-  enforce?: 'pre' | 'post';
-  /** Throw lint errors/warnings */
-  lint?(): Record<string, Linter>;
-  transform?(options: TransformHookOptions): Promise<void>;
-  build?(options: BuildHookOptions): Promise<void>;
-  buildEnd?(result: BuildRunnerResult): Promise<void>;
-}
-
-export interface ConfigOptions {
-  logger?: Logger;
-  /** @terrazzo/parser needs cwd so this can be run without Node.js. Importing defineConfig from @terrazzo/cli doesn’t need this. */
-  cwd: URL;
-}
-
-/**
- * Validate and normalize a config
- */
-export default function defineConfig(rawConfig: Config, options: ConfigOptions): ConfigInit;
-
-export function mergeConfigs(a: Config, b: Config): Config;

package/config.js

@@ -1,206 +0,0 @@
-import { merge } from 'merge-anything';
-import coreLintPlugin from './lint/plugin-core/index.js';
-import Logger from './logger.js';
-
-const TRAILING_SLASH_RE = /\/*$/;
-
-/**
- * Validate and normalize a config
- * @param {Config} rawConfig
- * @param {object} options
- * @param {Logger} options.logger
- * @param {URL} options.cwd
- */
-export default function defineConfig(rawConfig, { logger = new Logger(), cwd } = {}) {
-  const configStart = performance.now();
-
-  if (!cwd) {
-    logger.error({ label: 'core', message: 'defineConfig() missing `cwd` for JS API' });
-  }
-
-  logger.debug({ group: 'parser', task: 'config', message: 'Start config validation' });
-
-  const config = merge({}, rawConfig);
-
-  // config.tokens
-  if (rawConfig.tokens === undefined) {
-    config.tokens = ['./tokens.json']; // will be normalized in next step
-  } else if (typeof rawConfig.tokens === 'string') {
-    config.tokens = [rawConfig.tokens]; // will be normalized in next step
-  } else if (Array.isArray(rawConfig.tokens)) {
-    config.tokens = [];
-    for (const file of rawConfig.tokens) {
-      if (typeof file === 'string' || file instanceof URL) {
-        config.tokens.push(file); // will be normalized in next step
-      } 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}` });
-    }
-  }
-
-  // config.outDir
-  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, '/'));
-  }
-
-  // config.plugins
-  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;
-  });
-
-  // config.lint
-  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' });
-      return config;
-    }
-    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)}`,
-        });
-      }
-      for (const id in config.lint.rules) {
-        if (!Object.hasOwn(config.lint.rules, id)) {
-          continue;
-        }
-        if (typeof id !== 'string') {
-          logger.error({ label: 'config.lint.rules', message: `Expects string keys, received ${JSON.stringify(id)}` });
-        }
-        const value = config.lint.rules[id];
-        let severity = 'off';
-        let options;
-        if (typeof value === 'number' || typeof value === 'string') {
-          severity = value;
-        } else if (Array.isArray(value)) {
-          severity = value[0];
-          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] = { 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).`,
-            });
-            return config;
-          }
-          config.lint.rules[id].severity = ['off', 'warn', 'error'][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: {},
-    };
-  }
-
-  // call plugin.config()
-  for (const plugin of config.plugins) {
-    plugin.config?.({ ...config });
-  }
-
-  logger.debug({
-    group: 'parser',
-    task: 'config',
-    message: 'Finish config validation',
-    timing: performance.now() - configStart,
-  });
-
-  return config;
-}
-
-/**
- * @param {object} a
- * @param {object} b
- * @return {object}
- */
-export function mergeConfigs(a, b) {
-  return merge(a, b);
-}