@terrazzo/parser 2.0.0-alpha.7 → 2.0.0-beta.0

package/src/resolver/load.ts

@@ -1,215 +0,0 @@
-import type * as momoa from '@humanwhocodes/momoa';
-import { type InputSource, type InputSourceWithDocument, maybeRawJSON } from '@terrazzo/json-schema-tools';
-import type { TokenNormalizedSet } from '@terrazzo/token-tools';
-import { merge } from 'merge-anything';
-import type yamlToMomoa from 'yaml-to-momoa';
-import { toMomoa } from '../lib/momoa.js';
-import { makeInputKey } from '../lib/resolver-utils.js';
-import type Logger from '../logger.js';
-import { processTokens } from '../parse/process.js';
-import type { ConfigInit, Resolver, ResolverSourceNormalized } from '../types.js';
-import { normalizeResolver } from './normalize.js';
-import { isLikelyResolver, validateResolver } from './validate.js';
-
-export interface LoadResolverOptions {
-  config: ConfigInit;
-  logger: Logger;
-  req: (url: URL, origin: URL) => Promise<string>;
-  yamlToMomoa?: typeof yamlToMomoa;
-}
-
-/** Quick-parse input sources and find a resolver */
-export async function loadResolver(
-  inputs: InputSource[],
-  { config, logger, req, yamlToMomoa }: LoadResolverOptions,
-): Promise<{ resolver: Resolver | undefined; tokens: TokenNormalizedSet; sources: InputSourceWithDocument[] }> {
-  let resolverDoc: momoa.DocumentNode | undefined;
-  let tokens: TokenNormalizedSet = {};
-  const entry = {
-    group: 'parser',
-    label: 'init',
-  } as const;
-
-  for (const input of inputs) {
-    let document: momoa.DocumentNode | undefined;
-    if (typeof input.src === 'string') {
-      if (maybeRawJSON(input.src)) {
-        document = toMomoa(input.src);
-      } else if (yamlToMomoa) {
-        document = yamlToMomoa(input.src);
-      } else {
-        logger.error({
-          ...entry,
-          message: `Install yaml-to-momoa package to parse YAML, and pass in as option, e.g.:
-
-  import { bundle } from '@terrazzo/json-schema-tools';
-  import yamlToMomoa from 'yaml-to-momoa';
-
-  bundle(yamlString, { yamlToMomoa });`,
-        });
-      }
-    } else if (input.src && typeof input.src === 'object') {
-      document = toMomoa(JSON.stringify(input.src, undefined, 2));
-    } else {
-      logger.error({ ...entry, message: `Could not parse ${input.filename}. Is this valid JSON or YAML?` });
-    }
-    if (!document || !isLikelyResolver(document)) {
-      continue;
-    }
-    if (inputs.length > 1) {
-      logger.error({ ...entry, message: `Resolver must be the only input, found ${inputs.length} sources.` });
-    }
-    resolverDoc = document;
-    break;
-  }
-
-  let resolver: Resolver | undefined;
-  if (resolverDoc) {
-    validateResolver(resolverDoc, { logger, src: inputs[0]!.src });
-    const normalized = await normalizeResolver(resolverDoc, {
-      filename: inputs[0]!.filename!,
-      logger,
-      req,
-      src: inputs[0]!.src,
-      yamlToMomoa,
-    });
-    resolver = createResolver(normalized, { config, logger, sources: [{ ...inputs[0]!, document: resolverDoc }] });
-
-    // If a resolver is present, load a single permutation to get a base token set.
-    const firstInput: Record<string, string> = {};
-    for (const m of resolver.source.resolutionOrder) {
-      if (m.type !== 'modifier') {
-        continue;
-      }
-      firstInput[m.name] = typeof m.default === 'string' ? m.default : Object.keys(m.contexts)[0]!;
-    }
-    tokens = resolver.apply(firstInput);
-  }
-
-  return {
-    resolver,
-    tokens,
-    sources: [{ ...inputs[0]!, document: resolverDoc! }],
-  };
-}
-
-export interface CreateResolverOptions {
-  config: ConfigInit;
-  logger: Logger;
-  sources: InputSourceWithDocument[];
-}
-
-/** Create an interface to resolve permutations */
-export function createResolver(
-  resolverSource: ResolverSourceNormalized,
-  { config, logger, sources }: CreateResolverOptions,
-): Resolver {
-  const inputDefaults: Record<string, string> = {};
-  const validContexts: Record<string, string[]> = {};
-  const allPermutations: Record<string, string>[] = [];
-
-  const resolverCache: Record<string, any> = {};
-
-  for (const m of resolverSource.resolutionOrder) {
-    if (m.type === 'modifier') {
-      if (typeof m.default === 'string') {
-        inputDefaults[m.name] = m.default!;
-      }
-      validContexts[m.name] = Object.keys(m.contexts);
-    }
-  }
-
-  return {
-    apply(inputRaw): TokenNormalizedSet {
-      let tokensRaw: TokenNormalizedSet = {};
-      const input = { ...inputDefaults, ...inputRaw };
-      const inputKey = makeInputKey(input);
-
-      if (resolverCache[inputKey]) {
-        return resolverCache[inputKey];
-      }
-
-      for (const item of resolverSource.resolutionOrder) {
-        switch (item.type) {
-          case 'set': {
-            for (const s of item.sources) {
-              tokensRaw = merge(tokensRaw, s) as TokenNormalizedSet;
-            }
-            break;
-          }
-          case 'modifier': {
-            const context = input[item.name]!;
-            const sources = item.contexts[context];
-            if (!sources) {
-              logger.error({
-                group: 'parser',
-                label: 'resolver',
-                message: `Modifier ${item.name} has no context ${JSON.stringify(context)}.`,
-              });
-            }
-            for (const s of sources ?? []) {
-              tokensRaw = merge(tokensRaw, s) as TokenNormalizedSet;
-            }
-            break;
-          }
-        }
-      }
-
-      const src = JSON.stringify(tokensRaw, undefined, 2);
-      const rootSource = { filename: resolverSource._source.filename!, document: toMomoa(src), src };
-      const tokens = processTokens(rootSource, {
-        config,
-        logger,
-        sourceByFilename: { [resolverSource._source.filename!.href]: rootSource },
-        sources,
-      });
-      resolverCache[inputKey] = tokens;
-      return tokens;
-    },
-    source: resolverSource,
-    listPermutations() {
-      // only do work on first call, then cache subsequent work. this could be thousands of possible values!
-      if (!allPermutations.length) {
-        allPermutations.push(...calculatePermutations(Object.entries(validContexts)));
-      }
-      return allPermutations;
-    },
-    isValidInput(input: Record<string, string>) {
-      if (!input || typeof input !== 'object') {
-        logger.error({ group: 'parser', label: 'resolver', message: `Invalid input: ${JSON.stringify(input)}.` });
-      }
-      if (!Object.keys(input).every((k) => k in validContexts)) {
-        return false; // 1. invalid if unknown modifier name
-      }
-      for (const [name, contexts] of Object.entries(validContexts)) {
-        // Note: empty strings are valid! Don’t check for truthiness.
-        if (name in input) {
-          if (!contexts.includes(input[name]!)) {
-            return false; // 2. invalid if unknown context
-          }
-        } else if (!(name in inputDefaults)) {
-          return false; // 3. invalid if omitted, and no default
-        }
-      }
-      return true;
-    },
-  };
-}
-
-/** Calculate all permutations */
-export function calculatePermutations(options: [string, string[]][]) {
-  const permutationCount = [1];
-  for (const [_name, contexts] of options) {
-    permutationCount.push(contexts.length * (permutationCount.at(-1) || 1));
-  }
-  const permutations: Record<string, string>[] = [];
-  for (let i = 0; i < permutationCount.at(-1)!; i++) {
-    const input: Record<string, string> = {};
-    for (let j = 0; j < options.length; j++) {
-      const [name, contexts] = options[j]!;
-      input[name] = contexts[Math.floor(i / permutationCount[j]!) % contexts.length]!;
-    }
-    permutations.push(input);
-  }
-  return permutations.length ? permutations : [{}];
-}

package/src/resolver/normalize.ts

@@ -1,133 +0,0 @@
-import * as momoa from '@humanwhocodes/momoa';
-import { bundle, encodeFragment, parseRef, replaceNode } from '@terrazzo/json-schema-tools';
-import type yamlToMomoa from 'yaml-to-momoa';
-import type Logger from '../logger.js';
-import type { Group, ReferenceObject, ResolverSourceNormalized } from '../types.js';
-
-export interface NormalizeResolverOptions {
-  logger: Logger;
-  yamlToMomoa?: typeof yamlToMomoa;
-  filename: URL;
-  req: (url: URL, origin: URL) => Promise<string>;
-  src?: any;
-}
-
-/** Normalize resolver (assuming it’s been validated) */
-export async function normalizeResolver(
-  document: momoa.DocumentNode,
-  { logger, filename, req, src, yamlToMomoa }: NormalizeResolverOptions,
-): Promise<ResolverSourceNormalized> {
-  // Important note: think about sets, modifiers, and resolutionOrder all
-  // containing their own partial tokens documents. Now think about JSON $refs
-  // inside those. Because we want to treat them all as one _eventual_ document,
-  // we defer resolving $refs until the very last step. In most setups, this has
-  // no effect on the final result, however, in the scenario where remote
-  // documents are loaded and they conflict in unexpected ways, resolving too
-  // early will produce incorrect results.
-  //
-  // To prevent this, we bundle ONCE at the very top level, with the `$defs` at
-  // the top level now containing all partial documents (as opposed to bundling
-  // every sub document individually). So all that said, we are deciding to
-  // choose the “all-in-one“ method for closer support with DTCG aliases, but at
-  // the expense of some edge cases of $refs behaving unexpectedly.
-  const resolverBundle = await bundle([{ filename, src }], { req, yamlToMomoa });
-  const resolverSource = momoa.evaluate(resolverBundle.document) as unknown as ResolverSourceNormalized;
-
-  // Resolve $refs, but in a very different way than everywhere else These are
-  // all _evaluated_, meaning initialized in JS memory. Unlike in the AST, when
-  // we resolve these they’ll share memory points (which isn’t possible in the
-  // AST—values must be duplicated). This code is unique because it’s the only
-  // place where we’re dealing with shared, initialized JS memory.
-  replaceNode(document, resolverBundle.document); // inject $defs into the root document
-  for (const set of Object.values(resolverSource.sets ?? {})) {
-    for (const source of set.sources) {
-      resolvePartials(source, { resolver: resolverSource, logger });
-    }
-  }
-  for (const modifier of Object.values(resolverSource.modifiers ?? {})) {
-    for (const context of Object.values(modifier.contexts)) {
-      for (const source of context) {
-        resolvePartials(source, { resolver: resolverSource, logger });
-      }
-    }
-  }
-  for (const item of resolverSource.resolutionOrder ?? []) {
-    resolvePartials(item, { resolver: resolverSource, logger });
-  }
-
-  return {
-    name: resolverSource.name,
-    version: resolverSource.version,
-    description: resolverSource.description,
-    sets: resolverSource.sets,
-    modifiers: resolverSource.modifiers,
-    resolutionOrder: resolverSource.resolutionOrder,
-    _source: {
-      filename,
-      document,
-    },
-  };
-}
-
-/** Resolve $refs for already-initialized JS */
-function resolvePartials(
-  source: Group | ReferenceObject,
-  {
-    resolver,
-    logger,
-  }: {
-    resolver: any;
-    logger: Logger;
-  },
-) {
-  if (!source) {
-    return;
-  }
-  const entry = { group: 'parser' as const, label: 'resolver' };
-  if (Array.isArray(source)) {
-    for (const item of source) {
-      resolvePartials(item, { resolver, logger });
-    }
-  } else if (typeof source === 'object') {
-    for (const k of Object.keys(source)) {
-      if (k === '$ref') {
-        const $ref = (source as any)[k] as string;
-        const { url, subpath = [] } = parseRef($ref);
-        if (url !== '.' || !subpath.length) {
-          logger.error({ ...entry, message: `Could not load $ref ${JSON.stringify($ref)}` });
-        }
-        const found = findObject(resolver, subpath ?? [], logger);
-        if (subpath[0] === 'sets' || subpath[0] === 'modifiers') {
-          found.type = subpath[0].replace(/s$/, '');
-          found.name = subpath[1];
-        }
-        if (found) {
-          for (const k2 of Object.keys(found)) {
-            (source as any)[k2] = found[k2];
-          }
-          delete (source as any).$ref;
-        } else {
-          logger.error({ ...entry, message: `Could not find ${JSON.stringify($ref)}` });
-        }
-      } else {
-        resolvePartials((source as any)[k], { resolver, logger });
-      }
-    }
-  }
-}
-
-function findObject(dict: Record<string, any>, path: string[], logger: Logger): any {
-  let node = dict;
-  for (const idRaw of path) {
-    const id = idRaw.replace(/~/g, '~0').replace(/\//g, '~1');
-    if (!(id in node)) {
-      logger.error({
-        group: 'parser',
-        label: 'resolver',
-        message: `Could not load $ref ${encodeFragment(path)}`,
-      });
-    }
-    node = node[id];
-  }
-  return node;
-}