@terrazzo/parser 0.1.2 → 0.2.0

package/parse/index.js

@@ -1,592 +0,0 @@
-import { evaluate, parse as parseJSON, print } from '@humanwhocodes/momoa';
-import { isAlias, parseAlias, pluralize, splitID } from '@terrazzo/token-tools';
-import lintRunner from '../lint/index.js';
-import Logger from '../logger.js';
-import normalize from './normalize.js';
-import validate from './validate.js';
-import { getObjMembers, injectObjMembers, traverse } from './json.js';
-
-export * from './validate.js';
-
-/** @typedef {import("@humanwhocodes/momoa").DocumentNode} DocumentNode */
-/** @typedef {import("../config.js").Plugin} Plugin */
-/** @typedef {import("../types.js").TokenNormalized} TokenNormalized */
-/**
- * @typedef {object} ParseResult
- * @property {Record<string, TokenNormalized} tokens
- * @property {Object[]} src
- */
-/**
- * @typedef {object} ParseInput
- * @property {string | object} src
- * @property {URL} [filename]
- */
-/**
- * @typedef {object} ParseOptions
- * @property {Logger} logger
- * @property {import("../config.js").Config} config
- * @property {import("yamlToMomoa")} yamlToMomoa
- * @property {boolean} [skipLint=false]
- * @property {boolean} [continueOnError=false]
- */
-/**
- * Parse
- * @param {ParseInput[]} input
- * @param {ParseOptions} [options]
- * @return {Promise<ParseResult>}
- */
-export default async function parse(
-  input,
-  { logger = new Logger(), skipLint = false, config = {}, continueOnError = false, yamlToMomoa } = {},
-) {
-  let tokens = {};
-  // note: only keeps track of sources with locations on disk; in-memory sources are discarded
-  // (it’s only for reporting line numbers, which doesn’t mean as much for dynamic sources)
-  const sources = {};
-
-  if (!Array.isArray(input)) {
-    logger.error({ group: 'parser', task: 'init', message: 'Input must be an array of input objects.' });
-  }
-  for (let i = 0; i < input.length; i++) {
-    if (!input[i] || typeof input[i] !== 'object') {
-      logger.error({ group: 'parser', task: 'init', message: `Input (${i}) must be an object.` });
-    }
-    if (!input[i].src || (typeof input[i].src !== 'string' && typeof input[i].src !== 'object')) {
-      logger.error({
-        group: 'parser',
-        task: 'init',
-        message: `Input (${i}) missing "src" with a JSON/YAML string, or JSON object.`,
-      });
-    }
-    if (input[i].filename && !(input[i].filename instanceof URL)) {
-      logger.error({
-        group: 'parser',
-        task: 'init',
-        message: `Input (${i}) "filename" must be a URL (remote or file URL).`,
-      });
-    }
-
-    const result = await parseSingle(input[i].src, {
-      filename: input[i].filename,
-      logger,
-      config,
-      skipLint,
-      continueOnError,
-      yamlToMomoa,
-    });
-
-    tokens = Object.assign(tokens, result.tokens);
-    if (input[i].filename) {
-      sources[input[i].filename.protocol === 'file:' ? input[i].filename.href : input[i].filename.href] = {
-        filename: input[i].filename,
-        src: result.src,
-        document: result.document,
-      };
-    }
-  }
-
-  const totalStart = performance.now();
-
-  // 5. Resolve aliases and populate groups
-  for (const id in tokens) {
-    if (!Object.hasOwn(tokens, id)) {
-      continue;
-    }
-    const token = tokens[id];
-    applyAliases(token, {
-      tokens,
-      filename: sources[token.source.loc]?.filename,
-      src: sources[token.source.loc]?.src,
-      node: token.source.node,
-      logger,
-    });
-    token.mode['.'].$value = token.$value;
-    if (token.aliasOf) {
-      token.mode['.'].aliasOf = token.aliasOf;
-    }
-    if (token.partialAliasOf) {
-      token.mode['.'].partialAliasOf = token.partialAliasOf;
-    }
-    const { group: parentGroup } = splitID(id);
-    for (const siblingID in tokens) {
-      const { group: siblingGroup } = splitID(siblingID);
-      if (siblingGroup?.startsWith(parentGroup)) {
-        token.group.tokens.push(siblingID);
-      }
-    }
-  }
-
-  // 6. resolve mode aliases
-  const modesStart = performance.now();
-  logger.debug({
-    group: 'parser',
-    task: 'modes',
-    message: 'Start mode resolution',
-  });
-  for (const id in tokens) {
-    if (!Object.hasOwn(tokens, id)) {
-      continue;
-    }
-    for (const mode in tokens[id].mode) {
-      if (mode === '.') {
-        continue; // skip shadow of root value
-      }
-      applyAliases(tokens[id].mode[mode], {
-        tokens,
-        node: tokens[id].mode[mode].source.node,
-        logger,
-        src: sources[tokens[id].source.loc]?.src,
-      });
-    }
-  }
-  logger.debug({
-    group: 'parser',
-    task: 'modes',
-    message: 'Finish token modes',
-    timing: performance.now() - modesStart,
-  });
-
-  logger.debug({
-    group: 'parser',
-    task: 'core',
-    message: 'Finish all parser tasks',
-    timing: performance.now() - totalStart,
-  });
-
-  if (continueOnError) {
-    const { errorCount } = logger.stats();
-    if (errorCount > 0) {
-      logger.error({
-        message: `Parser encountered ${errorCount} ${pluralize(errorCount, 'error', 'errors')}. Exiting.`,
-      });
-    }
-  }
-
-  return {
-    tokens,
-    sources,
-  };
-}
-
-/**
- * Parse a single input
- * @param {string | object} input
- * @param {object} options
- * @param {URL} [options.filename]
- * @param {Logger} [options.logger]
- * @param {import("../config.js").Config} [options.config]
- * @param {boolean} [options.skipLint]
- */
-async function parseSingle(input, { filename, logger, config, skipLint, continueOnError = false, yamlToMomoa }) {
-  // 1. Build AST
-  let src;
-  if (typeof input === 'string') {
-    src = input;
-  }
-  const startParsing = performance.now();
-  logger.debug({ group: 'parser', task: 'parse', message: 'Start tokens parsing' });
-  let document;
-  if (typeof input === 'string' && !maybeJSONString(input)) {
-    if (yamlToMomoa) {
-      try {
-        document = yamlToMomoa(input); // if string, but not JSON, attempt YAML
-      } catch (err) {
-        logger.error({ message: String(err), filename, src: input, continueOnError });
-      }
-    } else {
-      logger.error({
-        group: 'parser',
-        task: 'parse',
-        message: `Install \`yaml-to-momoa\` package to parse YAML, and pass in as option, e.g.:
-
-    import { parse } from '@terrazzo/parser';
-    import yamlToMomoa from 'yaml-to-momoa';
-
-    parse(yamlString, { yamlToMomoa });`,
-        continueOnError: false, // fail here; no point in continuing
-      });
-    }
-  } else {
-    document = parseJSON(
-      typeof input === 'string' ? input : JSON.stringify(input, undefined, 2), // everything else: assert it’s JSON-serializable
-      {
-        mode: 'jsonc',
-      },
-    );
-  }
-  if (!src) {
-    src = print(document, { indent: 2 });
-  }
-  logger.debug({
-    group: 'parser',
-    task: 'parse',
-    message: 'Finish tokens parsing',
-    timing: performance.now() - startParsing,
-  });
-
-  const tokens = {};
-
-  // 2. Walk AST once to validate tokens
-  const startValidation = performance.now();
-  logger.debug({ group: 'parser', task: 'validate', message: 'Start tokens validation' });
-  const $typeInheritance = {};
-  traverse(document, {
-    enter(node, parent, path) {
-      if (node.type === 'Member' && node.value.type === 'Object' && node.value.members) {
-        const members = getObjMembers(node.value);
-
-        // keep track of $types
-        if (members.$type && members.$type.type === 'String' && !members.$value) {
-          $typeInheritance[path.join('.') || '.'] = node.value.members.find((m) => m.name.value === '$type');
-        }
-
-        const id = path.join('.');
-
-        if (members.$value) {
-          const extensions = members.$extensions ? getObjMembers(members.$extensions) : undefined;
-          const sourceNode = structuredClone(node);
-
-          // get parent type by taking the closest-scoped $type (length === closer)
-          let parent$type;
-          let longestPath = '';
-          for (const [k, v] of Object.entries($typeInheritance)) {
-            if (k === '.' || id.startsWith(k)) {
-              if (k.length > longestPath.length) {
-                parent$type = v;
-                longestPath = k;
-              }
-            }
-          }
-          if (parent$type && !members.$type) {
-            sourceNode.value = injectObjMembers(sourceNode.value, [parent$type]);
-          }
-
-          validate(sourceNode, { filename, src, logger });
-
-          const group = { id: splitID(id).group, tokens: [] };
-          if (parent$type) {
-            group.$type = parent$type.value.value;
-          }
-          // note: this will also include sibling tokens, so be selective about only accessing group-specific properties
-          const groupMembers = getObjMembers(parent);
-          if (groupMembers.$description) {
-            group.$description = evaluate(groupMembers.$description);
-          }
-          if (groupMembers.$extensions) {
-            group.$extensions = evaluate(groupMembers.$extensions);
-          }
-          const token = {
-            $type: members.$type?.value ?? parent$type?.value.value,
-            $value: evaluate(members.$value),
-            id,
-            mode: {},
-            originalValue: evaluate(node.value),
-            group,
-            source: {
-              loc: filename ? filename.href : undefined,
-              node: sourceNode.value,
-            },
-          };
-          if (members.$description?.value) {
-            token.$description = members.$description.value;
-          }
-
-          // handle modes
-          // note that circular refs are avoided here, such as not duplicating `modes`
-          const modeValues = extensions?.mode ? getObjMembers(extensions.mode) : {};
-          for (const mode of ['.', ...Object.keys(modeValues)]) {
-            token.mode[mode] = {
-              id: token.id,
-              $type: token.$type,
-              $value: mode === '.' ? token.$value : evaluate(modeValues[mode]),
-              source: {
-                loc: filename ? filename.href : undefined,
-                node: mode === '.' ? structuredClone(token.source.node) : modeValues[mode],
-              },
-            };
-            if (token.$description) {
-              token.mode[mode].$description = token.$description;
-            }
-          }
-
-          tokens[id] = token;
-        } else if (!id.includes('.$value') && members.value) {
-          logger.warn({ message: `Group ${id} has "value". Did you mean "$value"?`, filename, node, src });
-        }
-      }
-
-      // edge case: if $type appears at root of tokens.json, collect it
-      if (node.type === 'Document' && node.body.type === 'Object' && node.body.members) {
-        const members = getObjMembers(node.body);
-        if (members.$type && members.$type.type === 'String' && !members.$value) {
-          $typeInheritance['.'] = node.body.members.find((m) => m.name.value === '$type');
-        }
-      }
-    },
-  });
-  logger.debug({
-    group: 'parser',
-    task: 'validate',
-    message: 'Finish tokens validation',
-    timing: performance.now() - startValidation,
-  });
-
-  // 3. Execute lint runner with loaded plugins
-  if (!skipLint && config?.plugins?.length) {
-    const lintStart = performance.now();
-    logger.debug({
-      group: 'parser',
-      task: 'validate',
-      message: 'Start token linting',
-    });
-    await lintRunner({ document, filename, src, config, logger });
-    logger.debug({
-      group: 'parser',
-      task: 'validate',
-      message: 'Finish token linting',
-      timing: performance.now() - lintStart,
-    });
-  }
-
-  // 4. normalize values
-  const normalizeStart = performance.now();
-  logger.debug({
-    group: 'parser',
-    task: 'normalize',
-    message: 'Start token normalization',
-  });
-  for (const id in tokens) {
-    if (!Object.hasOwn(tokens, id)) {
-      continue;
-    }
-    try {
-      tokens[id].$value = normalize(tokens[id]);
-    } catch (err) {
-      let { node } = tokens[id].source;
-      const members = getObjMembers(node);
-      if (members.$value) {
-        node = members.$value;
-      }
-      logger.error({ message: err.message, filename, src, node, continueOnError });
-    }
-    for (const mode in tokens[id].mode) {
-      if (mode === '.') {
-        continue;
-      }
-      try {
-        tokens[id].mode[mode].$value = normalize(tokens[id].mode[mode]);
-      } catch (err) {
-        let { node } = tokens[id].source;
-        const members = getObjMembers(node);
-        if (members.$value) {
-          node = members.$value;
-        }
-        logger.error({
-          message: err.message,
-          filename,
-          src,
-          node: tokens[id].mode[mode].source.node,
-          continueOnError,
-        });
-      }
-    }
-  }
-  logger.debug({
-    group: 'parser',
-    task: 'normalize',
-    message: 'Finish token normalization',
-    timing: performance.now() - normalizeStart,
-  });
-
-  return { tokens, document, src };
-}
-
-/**
- * Determine if an input is likely a JSON string
- * @param {string} input
- * @return {boolean}
- */
-export function maybeJSONString(input) {
-  return typeof input === 'string' && input.trim().startsWith('{');
-}
-
-/**
- * Resolve alias
- * @param {string} alias
- * @param {Object} options
- * @param {Record<string, TokenNormalized>} options.tokens
- * @param {Logger} options.logger
- * @param {string} [options.filename]
- * @param {AnyNode} [options.node]
- * @param {string} [options.string]
- * @param {string} [options.scanned=[]]
- * @param {string}
- */
-export function resolveAlias(alias, { tokens, logger, filename, src, node, scanned = [] }) {
-  const { id } = parseAlias(alias);
-  if (!tokens[id]) {
-    logger.error({ message: `Alias "${alias}" not found.`, filename, src, node });
-  }
-  if (scanned.includes(id)) {
-    logger.error({ message: `Circular alias detected from "${alias}".`, filename, src, node });
-  }
-  const token = tokens[id];
-  if (!isAlias(token.$value)) {
-    return id;
-  }
-  return resolveAlias(token.$value, { tokens, logger, filename, node, src, scanned: [...scanned, id] });
-}
-
-/** Throw error if resolved alias for composite properties doesn’t match expected $type. */
-const COMPOSITE_TYPE_VALUES = {
-  border: {
-    color: ['color'],
-    width: ['dimension'],
-    strokeStyle: ['strokeStyle'],
-  },
-  gradient: {
-    color: ['color'],
-    position: ['number'],
-  },
-  shadow: {
-    color: ['color'],
-    position: ['dimension'],
-  },
-  strokeStyle: {
-    dashArray: ['dimension'],
-  },
-  transition: {
-    duration: ['duration'],
-    delay: ['duration'],
-    timingFunction: ['cubicBezier'],
-  },
-  typography: {
-    fontFamily: ['fontFamily'],
-    fontSize: ['dimension'],
-    fontWeight: ['fontWeight'],
-    letterSpacing: ['dimension'],
-    lineHeight: ['dimension', 'number'],
-  },
-};
-
-/** Resolve aliases, update values, and mutate `token` to add `aliasOf` / `partialAliasOf` */
-function applyAliases(token, { tokens, logger, filename, src, node }) {
-  const $valueNode = (node.type === 'Object' && node.members.find((m) => m.name.value === '$value')?.value) || node;
-  const expectedAliasTypes = COMPOSITE_TYPE_VALUES[token.$type];
-
-  // handle simple aliases
-  if (isAlias(token.$value)) {
-    const aliasOfID = resolveAlias(token.$value, { tokens, logger, filename, node, src });
-    const { mode: aliasMode } = parseAlias(token.$value);
-    const aliasOf = tokens[aliasOfID];
-    token.aliasOf = aliasOfID;
-    token.$value = aliasOf.mode[aliasMode]?.$value || aliasOf.$value;
-    if (token.$type && token.$type !== aliasOf.$type) {
-      logger.error({
-        message: `Invalid alias: expected $type: "${token.$type}", received $type: "${aliasOf.$type}".`,
-        node: $valueNode,
-        filename,
-        src,
-      });
-    }
-    token.$type = aliasOf.$type;
-  }
-
-  // handle aliases within array values (e.g. cubicBezier, gradient)
-  else if (Array.isArray(token.$value)) {
-    // some arrays are primitives, some are objects. handle both
-    for (let i = 0; i < token.$value.length; i++) {
-      if (isAlias(token.$value[i])) {
-        if (!token.partialAliasOf) {
-          token.partialAliasOf = [];
-        }
-        const aliasOfID = resolveAlias(token.$value[i], { tokens, logger, filename, node, src });
-        const { id: aliasID, mode: aliasMode } = parseAlias(token.$value[i]);
-        token.partialAliasOf[i] = aliasID;
-        token.$value[i] = tokens[aliasOfID].mode[aliasMode]?.$value || tokens[aliasOfID].$value;
-      } else if (typeof token.$value[i] === 'object') {
-        for (const property in token.$value[i]) {
-          if (isAlias(token.$value[i][property])) {
-            if (!token.partialAliasOf) {
-              token.partialAliasOf = [];
-            }
-            if (!token.partialAliasOf[i]) {
-              token.partialAliasOf[i] = {};
-            }
-            const aliasOfID = resolveAlias(token.$value[i][property], { tokens, logger, filename, node, src });
-            const { id: aliasID, mode: aliasMode } = parseAlias(token.$value[i][property]);
-            const aliasToken = tokens[aliasOfID];
-
-            if (expectedAliasTypes?.[property] && !expectedAliasTypes[property].includes(aliasToken.$type)) {
-              const elementNode = $valueNode.elements[i].value;
-              logger.error({
-                message: `Invalid alias: expected $type: "${expectedAliasTypes[property].join('" or "')}", received $type: "${aliasToken.$type}".`,
-                node: elementNode.members.find((m) => m.name.value === property).value,
-                filename,
-                src,
-              });
-            }
-
-            token.partialAliasOf[i][property] = aliasID; // also keep the shallow alias here, too!
-            token.$value[i][property] = aliasToken.mode[aliasMode]?.$value || aliasToken.$value;
-          }
-        }
-      }
-    }
-  }
-  // handle aliases within object (composite) values (e.g. border, typography, transition)
-  else if (typeof token.$value === 'object') {
-    for (const property in token.$value) {
-      if (!Object.hasOwn(token.$value, property)) {
-        continue;
-      }
-
-      if (isAlias(token.$value[property])) {
-        if (!token.partialAliasOf) {
-          token.partialAliasOf = {};
-        }
-        const aliasOfID = resolveAlias(token.$value[property], { tokens, logger, filename, node, src });
-        const { id: aliasID, mode: aliasMode } = parseAlias(token.$value[property]);
-        token.partialAliasOf[property] = aliasID; // keep the shallow alias!
-        const aliasToken = tokens[aliasOfID];
-        if (expectedAliasTypes?.[property] && !expectedAliasTypes[property].includes(aliasToken.$type)) {
-          logger.error({
-            message: `Invalid alias: expected $type: "${expectedAliasTypes[property].join('" or "')}", received $type: "${aliasToken.$type}".`,
-            node: $valueNode.members.find((m) => m.name.value === property).value,
-            filename,
-            src,
-          });
-        }
-        token.$value[property] = aliasToken.mode[aliasMode]?.$value || aliasToken.$value;
-      }
-
-      // strokeStyle has an array within an object
-      else if (Array.isArray(token.$value[property])) {
-        for (let i = 0; i < token.$value[property].length; i++) {
-          if (isAlias(token.$value[property][i])) {
-            const aliasOfID = resolveAlias(token.$value[property][i], { tokens, logger, filename, node, src });
-            if (!token.partialAliasOf) {
-              token.partialAliasOf = {};
-            }
-            if (!token.partialAliasOf[property]) {
-              token.partialAliasOf[property] = [];
-            }
-            const { id: aliasID, mode: aliasMode } = parseAlias(token.$value[property][i]);
-            token.partialAliasOf[property][i] = aliasID; // keep the shallow alias!
-            const aliasToken = tokens[aliasOfID];
-            if (expectedAliasTypes?.[property] && !expectedAliasTypes[property].includes(aliasToken.$type)) {
-              const arrayNode = $valueNode.members.find((m) => m.name.value === property).value;
-              logger.error({
-                message: `Invalid alias: expected $type: "${expectedAliasTypes[property].join('" or "')}", received $type: "${aliasToken.$type}".`,
-                node: arrayNode.elements[i],
-                filename,
-                src,
-              });
-            }
-            token.$value[property][i] = tokens[aliasOfID].mode[aliasMode]?.$value || tokens[aliasOfID].$value;
-          }
-        }
-      }
-    }
-  }
-}

package/parse/json.d.ts

@@ -1,30 +0,0 @@
-import type { AnyNode, MemberNode, ObjectNode, ValueNode } from '@humanwhocodes/momoa';
-
-export interface Visitor {
-  enter?: (node: AnyNode, parent: AnyNode | undefined, path: string[]) => void;
-  exit?: (node: AnyNode, parent: AnyNode | undefined, path: string[]) => void;
-}
-
-declare const CHILD_KEYS: {
-  Document: readonly ['body'];
-  Object: readonly ['members'];
-  Member: readonly ['name', 'value'];
-  Element: readonly ['value'];
-  Array: readonly ['elements'];
-  String: readonly [];
-  Number: readonly [];
-  Boolean: readonly [];
-  Null: readonly [];
-};
-
-/** Determines if a given value is an AST node. */
-export function isNode(value: unknown): boolean;
-
-/** Get ObjectNode members as object */
-export function getObjMembers(node: ObjectNode): Record<string | number, ValueNode | undefined>;
-
-/** Inject members to ObjectNode and return a clone */
-export function injectObjMembers(node: ObjectNode, members: MemberNode[]): ObjectNode;
-
-/** Variation of Momoa’s traverse(), which keeps track of global path */
-export function traverse(root: AnyNode, visitor: Visitor): void;