@terrazzo/parser 0.1.3 → 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,264 @@
+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[];
+}
+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;
+    };
+}
+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;
+});
+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 */
+    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>;
+        mode?: string;
+    }): void;
+    /** Momoa documents */
+    sources: InputSource[];
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terrazzo/parser",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Parser/validator for the Design Tokens Community Group (DTCG) standard.",
   "type": "module",
   "author": {
@@ -21,7 +21,7 @@
     "linting",
     "lint"
   ],
-  "main": "./index.js",
+  "main": "./dist/index.js",
   "homepage": "https://terrazzoapp.com/docs/cli/api/js",
   "repository": {
     "type": "git",
@@ -37,18 +37,18 @@
     "is-what": "^4.1.16",
     "merge-anything": "^5.1.7",
     "picocolors": "^1.1.1",
+    "scule": "^1.3.0",
     "wildcard-match": "^5.1.3",
-    "yaml": "^2.6.0",
-    "@terrazzo/token-tools": "^0.1.3"
+    "yaml": "^2.6.1",
+    "@terrazzo/token-tools": "^0.2.0"
   },
   "devDependencies": {
     "esbuild": "^0.23.1",
     "yaml-to-momoa": "^0.0.1"
   },
   "scripts": {
+    "build": "tsc -p tsconfig.build.json",
     "lint": "biome check .",
-    "test": "pnpm --filter @terrazzo/parser run \"/^test:.*/\"",
-    "test:js": "vitest run",
-    "test:ts": "tsc --noEmit"
+    "test": "vitest run"
   }
 }

package/{build/index.js → src/build/index.ts}

@@ -1,39 +1,26 @@
-import { isTokenMatch } from '@terrazzo/token-tools';
+import type { DocumentNode } from '@humanwhocodes/momoa';
+import { type TokenNormalized, isTokenMatch } from '@terrazzo/token-tools';
 import wcmatch from 'wildcard-match';
-import Logger from '../logger.js';
+import Logger, { type LogEntry } from '../logger.js';
+import type { BuildRunnerResult, ConfigInit, TokenTransformed, TransformParams } from '../types.js';
 
-/**
- * @typedef {object} BuildRunnerOptions
- * @typedef {Record<string, TokenNormalized>} BuildRunnerOptions.tokens
- * @typedef {Array} BuildRunnerOptions.sources
- * @typedef {ConfigInit} BuildRunnerOptions.config
- * @typedef {Logger} BuildRunnerOptions.logger
- * @typedef {import("@humanwhocodes/momoa").DocumentNode} DocumentNode
- * @typedef {import("../config.js").ConfigInit} ConfigInit
- * @typedef {import("../logger.js")} Logger
- * @typedef {import("../types.js").TokenNormalized} TokenNormalized
- *
- * @typedef {object} BuildRunnerResult
- * @typedef {OutputFile[]} BuildRunnerResult.outputFiles
- * @typedef {object} OutputFile
- * @typedef {string} OutputFile.filename
- * @typedef {string | Buffer} OutputFile.contents
- */
+export interface BuildRunnerOptions {
+  sources: { filename?: URL; src: string; document: DocumentNode }[];
+  config: ConfigInit;
+  logger?: Logger;
+}
 
 export const SINGLE_VALUE = 'SINGLE_VALUE';
 export const MULTI_VALUE = 'MULTI_VALUE';
 
 /** Validate plugin setTransform() calls for immediate feedback */
-function validateTransformParams({ params, token, logger, pluginName }) {
-  const baseEntry = { group: 'plugin', task: pluginName };
+function validateTransformParams({
+  params,
+  logger,
+  pluginName,
+}: { params: TokenTransformed; logger: Logger; pluginName: string }) {
+  const baseEntry: LogEntry = { group: 'plugin', label: pluginName, message: '' };
 
-  // validate ID
-  if (!token) {
-    logger.error({
-      ...baseEntry,
-      message: `setTransform() tried to transform token "${id}" but it doesn’t exist.`,
-    });
-  }
   // validate value is valid for SINGLE_VALUE or MULTI_VALUE
   if (
     !params.value ||
@@ -57,19 +44,20 @@ function validateTransformParams({ params, token, logger, pluginName }) {
 
 /**
  * Run build stage
- * @param {BuildOptions} options
- * @return {Promise<BuildResult>}
  */
-export default async function build(tokens, { sources, logger = new Logger(), config }) {
-  const formats = {};
-  const result = { outputFiles: [] };
+export default async function build(
+  tokens: Record<string, TokenNormalized>,
+  { sources, logger = new Logger(), config }: BuildRunnerOptions,
+) {
+  const formats: Record<string, TokenTransformed[]> = {};
+  const result: BuildRunnerResult = { outputFiles: [] };
 
-  function getTransforms(params) {
+  function getTransforms(params: TransformParams) {
     return (formats[params.format] ?? []).filter((token) => {
       if (params.$type) {
         if (typeof params.$type === 'string' && token.token.$type !== params.$type) {
           return false;
-        } else if (Array.isArray(params.$type) && !params.$type.some(($type) => token.token.type === $type)) {
+        } else if (Array.isArray(params.$type) && !params.$type.some(($type) => token.token.$type === $type)) {
           return false;
         }
       }
@@ -90,7 +78,7 @@ export default async function build(tokens, { sources, logger = new Logger(), co
   // transform()
   let transformsLocked = false; // prevent plugins from transforming after stage has ended
   const startTransform = performance.now();
-  logger.debug({ group: 'parser', task: 'transform', message: 'Start transform' });
+  logger.debug({ group: 'parser', label: 'transform', message: 'Start transform' });
   for (const plugin of config.plugins) {
     if (typeof plugin.transform === 'function') {
       await plugin.transform({
@@ -102,16 +90,17 @@ export default async function build(tokens, { sources, logger = new Logger(), co
             logger.warn({
               message: 'Attempted to call setTransform() after transform step has completed.',
               group: 'plugin',
-              task: plugin.name,
+              label: plugin.name,
             });
             return;
           }
-          const token = tokens[id];
+          const token = tokens[id]!;
 
           // allow `undefined` values, but remove them here
-          const cleanValue = typeof params.value === 'string' ? params.value : { ...params.value };
+          const cleanValue: TokenTransformed['value'] =
+            typeof params.value === 'string' ? params.value : { ...(params.value as Record<string, string>) };
           if (typeof cleanValue === 'object') {
-            for (const k in cleanValue) {
+            for (const k of Object.keys(cleanValue)) {
               if (Object.hasOwn(cleanValue, k)) {
                 if (cleanValue[k] === undefined) {
                   delete cleanValue[k];
@@ -120,30 +109,31 @@ export default async function build(tokens, { sources, logger = new Logger(), co
             }
           }
 
-          validateTransformParams({ token, logger, params: { ...params, value: cleanValue }, pluginName: plugin.name });
+          validateTransformParams({
+            logger,
+            params: { ...(params as any), value: cleanValue },
+            pluginName: plugin.name,
+          });
 
           // upsert
           if (!formats[params.format]) {
             formats[params.format] = [];
           }
-          const foundTokenI = formats[params.format].findIndex(
-            (t) =>
-              id === t.id &&
-              params.localID === t.localID &&
-              (!params.mode || params.mode === t.mode) &&
-              (!params.variant || params.variant === t.variant),
+          const foundTokenI = formats[params.format]!.findIndex(
+            (t) => id === t.id && params.localID === t.localID && (!params.mode || params.mode === t.mode),
           );
           if (foundTokenI === -1) {
-            formats[params.format].push({
+            formats[params.format]!.push({
               ...params,
+              id,
               value: cleanValue,
               type: typeof cleanValue === 'string' ? SINGLE_VALUE : MULTI_VALUE,
               mode: params.mode || '.',
               token: structuredClone(token),
-            });
+            } as TokenTransformed);
           } else {
-            formats[params.format][foundTokenI].value = cleanValue;
-            formats[params.format][foundTokenI].type = typeof cleanValue === 'string' ? SINGLE_VALUE : MULTI_VALUE;
+            formats[params.format]![foundTokenI]!.value = cleanValue;
+            formats[params.format]![foundTokenI]!.type = typeof cleanValue === 'string' ? SINGLE_VALUE : MULTI_VALUE;
           }
         },
       });
@@ -152,14 +142,14 @@ export default async function build(tokens, { sources, logger = new Logger(), co
   transformsLocked = true;
   logger.debug({
     group: 'parser',
-    task: 'transform',
+    label: 'transform',
     message: 'Finish transform',
     timing: performance.now() - startTransform,
   });
 
   // build()
   const startBuild = performance.now();
-  logger.debug({ group: 'parser', task: 'build', message: 'Start build' });
+  logger.debug({ group: 'parser', label: 'build', message: 'Start build' });
   for (const plugin of config.plugins) {
     if (typeof plugin.build === 'function') {
       const pluginBuildStart = performance.now();
@@ -184,28 +174,22 @@ export default async function build(tokens, { sources, logger = new Logger(), co
   }
   logger.debug({
     group: 'parser',
-    task: 'build',
+    label: 'build',
     message: 'Finish build',
     timing: performance.now() - startBuild,
   });
 
   // buildEnd()
   const startBuildEnd = performance.now();
-  logger.debug({ group: 'parser', task: 'build', message: 'Start buildEnd' });
+  logger.debug({ group: 'parser', label: 'build', message: 'Start buildEnd' });
   for (const plugin of config.plugins) {
     if (typeof plugin.buildEnd === 'function') {
-      await plugin.buildEnd({
-        tokens,
-        sources,
-        getTransforms,
-        format: (formatID) => createFormatter(formatID),
-        outputFiles: structruedClone(result.outputFiles),
-      });
+      await plugin.buildEnd({ outputFiles: structuredClone(result.outputFiles) });
     }
   }
   logger.debug({
     group: 'parser',
-    task: 'build',
+    label: 'build',
     message: 'Finish buildEnd',
     timing: performance.now() - startBuildEnd,
   });