@terrazzo/parser 2.0.0-alpha.5 → 2.0.0-alpha.7

package/src/resolver/normalize.ts

@@ -1,15 +1,8 @@
 import * as momoa from '@humanwhocodes/momoa';
-import { bundle, getObjMember, getObjMembers, parseRef } from '@terrazzo/json-schema-tools';
+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 {
-  ResolverModifierInline,
-  ResolverModifierNormalized,
-  ResolverSetInline,
-  ResolverSetNormalized,
-  ResolverSourceNormalized,
-} from '../types.js';
-import { validateModifier, validateSet } from './validate.js';
+import type { Group, ReferenceObject, ResolverSourceNormalized } from '../types.js';
 
 export interface NormalizeResolverOptions {
   logger: Logger;
@@ -21,11 +14,46 @@ export interface NormalizeResolverOptions {
 
 /** Normalize resolver (assuming it’s been validated) */
 export async function normalizeResolver(
-  node: momoa.DocumentNode,
-  { filename, req, src, logger, yamlToMomoa }: NormalizeResolverOptions,
+  document: momoa.DocumentNode,
+  { logger, filename, req, src, yamlToMomoa }: NormalizeResolverOptions,
 ): Promise<ResolverSourceNormalized> {
-  const resolverSource = momoa.evaluate(node) as unknown as ResolverSourceNormalized;
-  const resolutionOrder = getObjMember(node.body as momoa.ObjectNode, 'resolutionOrder') as momoa.ArrayNode;
+  // 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,
@@ -33,74 +61,73 @@ export async function normalizeResolver(
     description: resolverSource.description,
     sets: resolverSource.sets,
     modifiers: resolverSource.modifiers,
-    resolutionOrder: await Promise.all(
-      resolutionOrder.elements.map(async (element, i) => {
-        const layer = element.value as momoa.ObjectNode;
-        const members = getObjMembers(layer);
-
-        // If this is an inline set or modifier it’s already been validated; we only need
-        // to resolve & validate $refs here which haven’t yet been parsed
-        let item = layer as unknown as ResolverSetInline | ResolverModifierInline;
-
-        // 1. $ref
-        if (members.$ref) {
-          const entry = { group: 'parser', label: 'init', node: members.$ref, src } as const;
-          const { url, subpath } = parseRef((members.$ref as unknown as momoa.StringNode).value);
-          if (url === '.') {
-            // 1a. local $ref: pull from local document
-            if (!subpath?.[0]) {
-              logger.error({ ...entry, message: '$ref can’t refer to the root document.' });
-            } else if (subpath[0] !== 'sets' && subpath[0] !== 'modifiers') {
-              // Note: technically we could allow $defs, but that’s just unnecessary shenanigans here.
-              logger.error({
-                ...entry,
-                message: 'Local $ref in resolutionOrder must point to either #/sets/[set] or #/modifiers/[modifiers].',
-              });
-            } else {
-              const resolvedItem = resolverSource[subpath[0] as 'sets' | 'modifiers']?.[subpath[1]!];
-              if (!resolvedItem) {
-                logger.error({ ...entry, message: 'Invalid $ref' });
-              } else {
-                item = {
-                  type: subpath[0] === 'sets' ? 'set' : 'modifier',
-                  name: subpath[1],
-                  ...(resolvedItem as any), // Note: as long as this exists, this has already been validated to be correct
-                };
-              }
-            }
-          } else {
-            // 1b. remote $ref: load and validate
-            const result = await bundle(
-              [{ filename: new URL(url, filename), src: resolverSource.resolutionOrder[i]! }],
-              {
-                req,
-                yamlToMomoa,
-              },
-            );
-            if (result.document.body.type === 'Object') {
-              const type = getObjMember(result.document.body, 'type');
-              if (type?.type === 'String' && type.value === 'set') {
-                validateSet(result.document.body as momoa.ObjectNode, true, src);
-                item = momoa.evaluate(result.document.body) as unknown as ResolverSetInline;
-              } else if (type?.type === 'String' && type.value === 'modifier') {
-                validateModifier(result.document.body as momoa.ObjectNode, true, src);
-                item = momoa.evaluate(result.document.body) as unknown as ResolverModifierInline;
-              }
-            }
-            logger.error({ ...entry, message: '$ref did not resolve to a valid Set or Modifier.' });
-          }
-        }
-
-        // 2. resolve inline sources & contexts
-        const finalResult = await bundle([{ filename, src: item }], { req, yamlToMomoa });
-        return momoa.evaluate(finalResult.document.body) as unknown as
-          | ResolverSetNormalized
-          | ResolverModifierNormalized;
-      }),
-    ),
+    resolutionOrder: resolverSource.resolutionOrder,
     _source: {
       filename,
-      node,
+      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;
+}

package/src/types.ts

@@ -377,7 +377,7 @@ export interface ResolverSourceNormalized {
   resolutionOrder: (ResolverSetNormalized | ResolverModifierNormalized)[];
   _source: {
     filename?: URL;
-    node: momoa.DocumentNode;
+    document: momoa.DocumentNode;
   };
 }
 
@@ -459,3 +459,10 @@ export interface TransformHookOptions {
   /** Momoa documents */
   sources: InputSourceWithDocument[];
 }
+
+export interface RefMapEntry {
+  filename: string;
+  refChain: string[];
+}
+
+export type RefMap = Record<string, RefMapEntry>;