@terrazzo/parser 2.0.0-alpha.2 → 2.0.0-alpha.3

package/src/resolver/validate.ts

@@ -0,0 +1,359 @@
+import type { DocumentNode, ObjectNode } from '@humanwhocodes/momoa';
+import { getObjMember, getObjMembers } from '@terrazzo/json-schema-tools';
+import type { LogEntry, default as Logger } from '../logger.js';
+
+/**
+ * Determine whether this is likely a resolver
+ * We use terms the word “likely” because this occurs before validation. Since
+ * we may be dealing with a doc _intended_ to be a resolver, but may be lacking
+ * some critical information, how can we determine intent? There’s a bit of
+ * guesswork here, but we try and find a reasonable edge case where we sniff out
+ * invalid DTCG syntax that a resolver doc would have.
+ */
+export function isLikelyResolver(doc: DocumentNode): boolean {
+  if (doc.body.type !== 'Object') {
+    return false;
+  }
+  // This is a resolver if…
+  for (const member of doc.body.members) {
+    if (member.name.type !== 'String') {
+      continue;
+    }
+    switch (member.name.value) {
+      case 'name':
+      case 'description':
+      case 'version': {
+        // 1. name, description, or version are a string
+        if (member.name.type === 'String') {
+          return true;
+        }
+        break;
+      }
+      case 'sets':
+      case 'modifiers': {
+        if (member.value.type !== 'Object') {
+          continue;
+        }
+        // 2. sets.description or modifiers.description is a string
+        if (getObjMember(member.value, 'description')?.type === 'String') {
+          return true;
+        }
+        // 3. sets.sources is an array
+        if (member.name.value === 'sets' && getObjMember(member.value, 'sources')?.type === 'Array') {
+          return true;
+        } else if (member.name.value === 'modifiers') {
+          const contexts = getObjMember(member.value, 'contexts');
+          if (contexts?.type === 'Object' && contexts.members.some((m) => m.value.type === 'Array')) {
+            // 4. contexts[key] is an array
+            // (note: modifiers.contexts as an object is technically valid token format! We need to check for the array)
+            return true;
+          }
+        }
+        break;
+      }
+      case 'resolutionOrder': {
+        // 4. resolutionOrder is an array
+        if (member.value.type === 'Array') {
+          return true;
+        }
+        break;
+      }
+    }
+  }
+
+  return false;
+}
+
+export interface ValidateResolverOptions {
+  logger: Logger;
+  src: string;
+}
+
+const MESSAGE_EXPECTED = {
+  STRING: 'Expected string.',
+  OBJECT: 'Expected object.',
+  ARRAY: 'Expected array.',
+};
+
+/**
+ * Validate a resolver document.
+ * There’s a ton of boilerplate here, only to surface detailed code frames. Is there a better abstraction?
+ */
+export function validateResolver(node: DocumentNode, { logger, src }: ValidateResolverOptions) {
+  const entry = { group: 'parser', label: 'resolver', src } as const;
+  if (node.body.type !== 'Object') {
+    logger.error({ ...entry, message: MESSAGE_EXPECTED.OBJECT, node });
+  }
+  const errors: LogEntry[] = [];
+
+  let hasVersion = false;
+  let hasResolutionOrder = false;
+
+  for (const member of (node.body as ObjectNode).members) {
+    if (member.name.type !== 'String') {
+      continue; // IDK, don’t ask
+    }
+
+    switch (member.name.value) {
+      case 'name':
+      case 'description': {
+        if (member.value.type !== 'String') {
+          errors.push({ ...entry, message: MESSAGE_EXPECTED.STRING });
+        }
+        break;
+      }
+
+      case 'version': {
+        hasVersion = true;
+        if (member.value.type !== 'String' || member.value.value !== '2025.10') {
+          errors.push({ ...entry, message: `Expected "version" to be "2025.10".`, node: member.value });
+        }
+        break;
+      }
+
+      case 'sets':
+      case 'modifiers': {
+        if (member.value.type !== 'Object') {
+          errors.push({ ...entry, message: MESSAGE_EXPECTED.OBJECT, node: member.value });
+        } else {
+          for (const item of member.value.members) {
+            if (item.value.type !== 'Object') {
+              errors.push({ ...entry, message: MESSAGE_EXPECTED.OBJECT, node: item.value });
+            } else {
+              const validator = member.name.value === 'sets' ? validateSet : validateModifier;
+              errors.push(...validator(item.value, false, { logger, src }));
+            }
+          }
+        }
+        break;
+      }
+
+      case 'resolutionOrder': {
+        hasResolutionOrder = true;
+        if (member.value.type !== 'Array') {
+          errors.push({ ...entry, message: MESSAGE_EXPECTED.ARRAY, node: member.value });
+        } else if (member.value.elements.length === 0) {
+          errors.push({ ...entry, message: `"resolutionOrder" can’t be empty array.`, node: member.value });
+        } else {
+          for (const item of member.value.elements) {
+            if (item.value.type !== 'Object') {
+              errors.push({ ...entry, message: MESSAGE_EXPECTED.OBJECT, node: item.value });
+            } else {
+              const itemMembers = getObjMembers(item.value);
+              if (itemMembers.$ref?.type === 'String') {
+                continue; // we can’t validate this just yet, assume it’s correct
+              }
+              // Validate "type"
+              if (itemMembers.type?.type === 'String') {
+                if (itemMembers.type.value === 'set') {
+                  validateSet(item.value, true, { logger, src });
+                } else if (itemMembers.type.value === 'modifier') {
+                  validateModifier(item.value, true, { logger, src });
+                } else {
+                  errors.push({
+                    ...entry,
+                    message: `Unknown type ${JSON.stringify(itemMembers.type.value)}`,
+                    node: itemMembers.type,
+                  });
+                }
+              }
+              // validate sets & modifiers if they’re missing "type"
+              if (itemMembers.sources?.type === 'Array') {
+                validateSet(item.value, true, { logger, src });
+              } else if (itemMembers.contexts?.type === 'Object') {
+                validateModifier(item.value, true, { logger, src });
+              } else if (itemMembers.name?.type === 'String' || itemMembers.description?.type === 'String') {
+                validateSet(item.value, true, { logger, src }); // if this has a "name" or "description", guess set
+              }
+            }
+          }
+        }
+        break;
+      }
+      case '$defs':
+      case '$extensions':
+        if (member.value.type !== 'Object') {
+          errors.push({ ...entry, message: `Expected object`, node: member.value });
+        }
+        break;
+      case '$ref': {
+        if (member.value.type !== 'String') {
+          errors.push({ ...entry, message: `Expected string`, node: member.value });
+        }
+        break;
+      }
+      default: {
+        errors.push({ ...entry, message: `Unknown key ${JSON.stringify(member.name.value)}`, node: member.name, src });
+        break;
+      }
+    }
+  }
+
+  // handle required keys
+  if (!hasVersion) {
+    errors.push({ ...entry, message: `Missing "version".`, node, src });
+  }
+  if (!hasResolutionOrder) {
+    errors.push({ ...entry, message: `Missing "resolutionOrder".`, node, src });
+  }
+
+  if (errors.length) {
+    logger.error(...errors);
+  }
+}
+
+export function validateSet(node: ObjectNode, isInline = false, { src }: ValidateResolverOptions): LogEntry[] {
+  const entry = { group: 'parser', label: 'resolver', src } as const;
+  const errors: LogEntry[] = [];
+  let hasName = !isInline;
+  let hasType = !isInline;
+  let hasSources = false;
+  for (const member of node.members) {
+    if (member.name.type !== 'String') {
+      continue;
+    }
+    switch (member.name.value) {
+      case 'name': {
+        hasName = true;
+        if (member.value.type !== 'String') {
+          errors.push({ ...entry, message: MESSAGE_EXPECTED.STRING, node: member.value });
+        }
+        break;
+      }
+      case 'description': {
+        if (member.value.type !== 'String') {
+          errors.push({ ...entry, message: MESSAGE_EXPECTED.STRING, node: member.value });
+        }
+        break;
+      }
+      case 'type': {
+        hasType = true;
+        if (member.value.type !== 'String') {
+          errors.push({ ...entry, message: MESSAGE_EXPECTED.STRING, node: member.value });
+        } else if (member.value.value !== 'set') {
+          errors.push({ ...entry, message: '"type" must be "set".' });
+        }
+        break;
+      }
+      case 'sources': {
+        hasSources = true;
+        if (member.value.type !== 'Array') {
+          errors.push({ ...entry, message: MESSAGE_EXPECTED.ARRAY, node: member.value });
+        } else if (member.value.elements.length === 0) {
+          errors.push({ ...entry, message: `"sources" can’t be empty array.`, node: member.value });
+        }
+        break;
+      }
+      case '$defs':
+      case '$extensions':
+        if (member.value.type !== 'Object') {
+          errors.push({ ...entry, message: `Expected object`, node: member.value });
+        }
+        break;
+      case '$ref': {
+        if (member.value.type !== 'String') {
+          errors.push({ ...entry, message: `Expected string`, node: member.value });
+        }
+        break;
+      }
+      default: {
+        errors.push({ ...entry, message: `Unknown key ${JSON.stringify(member.name.value)}`, node: member.name });
+        break;
+      }
+    }
+  }
+
+  // handle required keys
+  if (!hasName) {
+    errors.push({ ...entry, message: `Missing "name".`, node });
+  }
+  if (!hasType) {
+    errors.push({ ...entry, message: `"type": "set" missing.`, node });
+  }
+  if (!hasSources) {
+    errors.push({ ...entry, message: `Missing "sources".`, node });
+  }
+
+  return errors;
+}
+
+export function validateModifier(node: ObjectNode, isInline = false, { src }: ValidateResolverOptions): LogEntry[] {
+  const errors: LogEntry[] = [];
+  const entry = { group: 'parser', label: 'resolver', src } as const;
+  let hasName = !isInline;
+  let hasType = !isInline;
+  let hasContexts = false;
+  for (const member of node.members) {
+    if (member.name.type !== 'String') {
+      continue;
+    }
+    switch (member.name.value) {
+      case 'name': {
+        hasName = true;
+        if (member.value.type !== 'String') {
+          errors.push({ ...entry, message: MESSAGE_EXPECTED.STRING, node: member.value });
+        }
+        break;
+      }
+      case 'description': {
+        if (member.value.type !== 'String') {
+          errors.push({ ...entry, message: MESSAGE_EXPECTED.STRING, node: member.value });
+        }
+        break;
+      }
+      case 'type': {
+        hasType = true;
+        if (member.value.type !== 'String') {
+          errors.push({ ...entry, message: MESSAGE_EXPECTED.STRING, node: member.value });
+        } else if (member.value.value !== 'modifier') {
+          errors.push({ ...entry, message: '"type" must be "modifier".' });
+        }
+        break;
+      }
+      case 'contexts': {
+        hasContexts = true;
+        if (member.value.type !== 'Object') {
+          errors.push({ ...entry, message: MESSAGE_EXPECTED.OBJECT, node: member.value });
+        } else if (member.value.members.length === 0) {
+          errors.push({ ...entry, message: `"contexts" can’t be empty object.`, node: member.value });
+        } else {
+          for (const context of member.value.members) {
+            if (context.value.type !== 'Array') {
+              errors.push({ ...entry, message: MESSAGE_EXPECTED.ARRAY, node: context.value });
+            }
+          }
+        }
+        break;
+      }
+      case '$defs':
+      case '$extensions':
+        if (member.value.type !== 'Object') {
+          errors.push({ ...entry, message: `Expected object`, node: member.value });
+        }
+        break;
+      case '$ref': {
+        if (member.value.type !== 'String') {
+          errors.push({ ...entry, message: `Expected string`, node: member.value });
+        }
+        break;
+      }
+      default: {
+        errors.push({ ...entry, message: `Unknown key ${JSON.stringify(member.name.value)}`, node: member.name });
+        break;
+      }
+    }
+  }
+
+  // handle required keys
+  if (!hasName) {
+    errors.push({ ...entry, message: `Missing "name".`, node });
+  }
+  if (!hasType) {
+    errors.push({ ...entry, message: `"type": "modifier" missing.`, node });
+  }
+  if (!hasContexts) {
+    errors.push({ ...entry, message: `Missing "contexts".`, node });
+  }
+
+  return errors;
+}

package/src/types.ts

@@ -1,8 +1,23 @@
 import type * as momoa from '@humanwhocodes/momoa';
-import type { TokenNormalized } from '@terrazzo/token-tools';
+import type {
+  Group,
+  TokenNormalized,
+  TokenNormalizedSet,
+  TokenTransformed,
+  TokenTransformedBase,
+} from '@terrazzo/token-tools';
 import type ytm from 'yaml-to-momoa';
 import type Logger from './logger.js';
 
+// Export some types as a convenience, because they originally came from this package
+export type {
+  Group,
+  TokenNormalized,
+  TokenNormalizedSet,
+  TokenTransformed,
+  TokenTransformedBase,
+} from '@terrazzo/token-tools';
+
 export interface PluginHookContext {
   logger: Logger;
 }
@@ -231,7 +246,7 @@ export interface LintRuleMetaData<
   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.
+   * the string is the parameterized error string.
    */
   messages?: Record<MessageIds, string>;
   /**
@@ -270,6 +285,12 @@ export interface OutputFileExpanded extends OutputFile {
 export interface ParseOptions {
   logger?: Logger;
   config: ConfigInit;
+  /**
+   * Handle requests to loading remote files, either from a remote URL or on the filesystem.
+   * - Remote requests will have an "https:' protocol
+   * - Filesystem files will have a "file:" protocol
+   */
+  req?: (src: URL, origin: URL) => Promise<string>;
   /**
    * Skip lint step
    * @default false
@@ -310,42 +331,95 @@ export interface Plugin {
   buildEnd?(options: BuildEndHookOptions): Promise<void>;
 }
 
-interface TokenTransformedBase {
-  /** Original Token ID */
-  id: string;
-  /** ID unique to this format. */
-  localID?: string;
+export interface ReferenceObject {
+  $ref: string;
+}
+
+export interface Resolver<
+  Inputs extends Record<string, string[]> = Record<string, string[]>,
+  Input = Record<keyof Inputs, Inputs[keyof Inputs][number]>,
+> {
+  /** Supply values to modifiers to produce a final tokens set */
+  apply: (input: Partial<Input>) => TokenNormalizedSet;
+  /** List all possible valid input combinations. Ignores default values, as they would duplicate some other permutations. */
+  permutations: Input[];
+  /** The original resolver document, simplified */
+  source: ResolverSourceNormalized;
+  /** Helper function for permutations—see if a particular input is valid. Automatically applies default values. */
+  isValidInput: (input: Input) => boolean;
+}
+
+export interface ResolverSource {
+  /** Human-friendly name of this resolver */
+  name?: string;
+  /** DTCG version */
+  version: '2025.10';
+  /** Description of this resolver */
+  description?: string;
+  /** Mapping of sets */
+  sets?: Record<string, ResolverSet>;
+  /** Mapping of modifiers */
+  modifiers?: Record<string, ResolverModifier>;
+  resolutionOrder: (ResolverSetInline | ResolverModifierInline | ReferenceObject)[];
+  $extensions?: Record<string, unknown>;
+  $defs?: Record<string, unknown>;
+}
+
+/** Resolver where all tokens are loaded and flattened in-memory, so only the final merging is left */
+export interface ResolverSourceNormalized {
+  name: string | undefined;
+  version: '2025.10';
+  description: string | undefined;
+  sets: Record<string, ResolverSet> | undefined;
+  modifiers: Record<string, ResolverModifier> | undefined;
   /**
-   * The mode of this value
-   * @default "."
+   * Array of all sets and modifiers that have been converted to inline,
+   * regardless of original declaration. In a normalized resolver, only a single
+   * pass over the resolutionOrder array is needed.
    */
-  mode: string;
-  /** The original token. */
-  token: TokenNormalized;
-  /** Arbitrary metadata set by plugins. */
-  meta?: Record<string | number | symbol, unknown> & {
-    /**
-     * Metadata for the token-listing plugin. Plugins can
-     * set this to be the name of a token as it appears in code,
-     * and the token-listing plugin will pick it up and use it.
-     */
-    'token-listing'?: { name: string | undefined };
-  };
+  resolutionOrder: (ResolverSetNormalized | ResolverModifierNormalized)[];
 }
 
-/** Transformed token with a single value. Note that this may be any type! */
-export interface TokenTransformedSingleValue extends TokenTransformedBase {
-  type: 'SINGLE_VALUE';
-  value: string;
+export interface ResolverModifier<Context extends string = string> {
+  description?: string;
+  contexts: Record<Context, (Group | ReferenceObject)[]>;
+  default?: Context;
+  $extensions?: Record<string, unknown>;
+  $defs?: Record<string, unknown>;
 }
 
-/** Transformed token with multiple values. Note that this may be any type! */
-export interface TokenTransformedMultiValue extends TokenTransformedBase {
-  type: 'MULTI_VALUE';
-  value: Record<string, string>;
+export type ResolverModifierInline<Context extends string = string> = ResolverModifier<Context> & {
+  name: string;
+  type: 'modifier';
+};
+
+export interface ResolverModifierNormalized {
+  name: string;
+  type: 'modifier';
+  description: string | undefined;
+  contexts: Record<string, Group[]>;
+  default: string | undefined;
+  $extensions: Record<string, unknown> | undefined;
+  $defs: Record<string, unknown> | undefined;
 }
 
-export type TokenTransformed = TokenTransformedSingleValue | TokenTransformedMultiValue;
+export interface ResolverSet {
+  description?: string;
+  sources: (Group | ReferenceObject)[];
+  $extensions?: Record<string, unknown>;
+  $defs?: Record<string, unknown>;
+}
+
+export type ResolverSetInline = ResolverSet & { name: string; type: 'set' };
+
+export interface ResolverSetNormalized {
+  name: string;
+  type: 'set';
+  description: string | undefined;
+  sources: Group[];
+  $extensions: Record<string, unknown> | undefined;
+  $defs: Record<string, unknown> | undefined;
+}
 
 export interface TransformParams {
   /** ID of an existing format */
@@ -382,7 +456,3 @@ export interface TransformHookOptions {
   /** Momoa documents */
   sources: InputSource[];
 }
-
-export interface ReferenceObject {
-  $ref: string;
-}