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

package/dist/index.js

@@ -1,42 +1,12 @@
 import wcmatch from "wildcard-match";
 import * as momoa from "@humanwhocodes/momoa";
-import { evaluate } from "@humanwhocodes/momoa";
 import pc from "picocolors";
 import { merge } from "merge-anything";
 import { BORDER_REQUIRED_PROPERTIES, COLORSPACE, FONT_WEIGHTS, GRADIENT_REQUIRED_STOP_PROPERTIES, SHADOW_REQUIRED_PROPERTIES, STROKE_STYLE_LINE_CAP_VALUES, STROKE_STYLE_OBJECT_REQUIRED_PROPERTIES, STROKE_STYLE_STRING_VALUES, TRANSITION_REQUIRED_PROPERTIES, isAlias, parseAlias, parseColor, pluralize, tokenToCulori } from "@terrazzo/token-tools";
 import { clampChroma, wcagContrast } from "culori";
-import { bundle, getObjMember, getObjMembers, isPure$ref, maybeRawJSON, parseRef, replaceNode, traverseAsync } from "@terrazzo/json-schema-tools";
+import { camelCase, kebabCase, pascalCase, snakeCase } from "scule";
+import { bundle, getObjMember, getObjMembers, isPure$ref, maybeRawJSON, parseRef, replaceNode, traverse } from "@terrazzo/json-schema-tools";
 
-//#region rolldown:runtime
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __commonJS = (cb, mod) => function() {
-	return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
-};
-var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") {
-		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-			key = keys[i];
-			if (!__hasOwnProp.call(to, key) && key !== except) {
-				__defProp(to, key, {
-					get: ((k) => from[k]).bind(null, key),
-					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-				});
-			}
-		}
-	}
-	return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
-	value: mod,
-	enumerable: true
-}) : target, mod));
-
-//#endregion
 //#region src/lib/code-frame.ts
 /**
 * Extract what lines should be marked and highlighted.
@@ -146,6 +116,7 @@ function formatMessage(entry, severity) {
 	let message = entry.message;
 	message = `[${entry.group}${entry.label ? `:${entry.label}` : ""}] ${message}`;
 	if (severity in MESSAGE_COLOR) message = MESSAGE_COLOR[severity](message);
+	if (typeof entry.timing === "number") message = `${message} ${formatTiming(entry.timing)}`;
 	if (entry.node) {
 		const start = entry.node?.loc?.start ?? {
 			line: 0,
@@ -211,12 +182,7 @@ var Logger = class {
 			if (this.debugScope !== "*" && !wcmatch(this.debugScope)(debugPrefix)) return;
 			message.replace(/\[config[^\]]+\]/, (match) => pc.green(match)).replace(/\[parser[^\]]+\]/, (match) => pc.magenta(match)).replace(/\[lint[^\]]+\]/, (match) => pc.yellow(match)).replace(/\[plugin[^\]]+\]/, (match) => pc.cyan(match));
 			message = `${pc.dim(timeFormatter.format(performance.now()))} ${message}`;
-			if (typeof entry.timing === "number") {
-				let timing = "";
-				if (entry.timing < 1e3) timing = `${Math.round(entry.timing * 100) / 100}ms`;
-				else if (entry.timing < 6e4) timing = `${Math.round(entry.timing * 100) / 1e5}s`;
-				message = `${message}${timing ? pc.dim(` [${timing}]`) : ""}`;
-			}
+			if (typeof entry.timing === "number") message = `${message} ${formatTiming(entry.timing)}`;
 			console.log(message);
 		}
 	}
@@ -230,6 +196,13 @@ var Logger = class {
 		};
 	}
 };
+function formatTiming(timing) {
+	let output = "";
+	if (timing < 1e3) output = `${Math.round(timing * 100) / 100}ms`;
+	else if (timing < 6e4) output = `${Math.round(timing) / 1e3}s`;
+	else output = `${Math.round(timing / 1e3) / 60}m`;
+	return pc.dim(`[${output}]`);
+}
 var TokensJSONError = class extends Error {
 	constructor(message) {
 		super(message);
@@ -258,7 +231,7 @@ function validateTransformParams({ params, logger, pluginName }) {
 	});
 }
 /** Run build stage */
-async function build(tokens, { sources, logger = new Logger(), config }) {
+async function build(tokens, { resolver, sources, logger = new Logger(), config }) {
 	const formats = {};
 	const result = { outputFiles: [] };
 	function getTransforms(params) {
@@ -321,7 +294,8 @@ async function build(tokens, { sources, logger = new Logger(), config }) {
 				formats[params.format][foundTokenI].value = cleanValue;
 				formats[params.format][foundTokenI].type = typeof cleanValue === "string" ? SINGLE_VALUE : MULTI_VALUE;
 			}
-		}
+		},
+		resolver
 	});
 	transformsLocked = true;
 	logger.debug({
@@ -339,6 +313,7 @@ async function build(tokens, { sources, logger = new Logger(), config }) {
 				tokens,
 				sources,
 				getTransforms,
+				resolver,
 				outputFile(filename, contents) {
 					const resolved = new URL(filename, config.outDir);
 					if (result.outputFiles.some((f) => new URL(f.filename, config.outDir).href === resolved.href)) logger.error({
@@ -546,76 +521,6 @@ const rule$24 = {
 };
 var colorspace_default = rule$24;
 
-//#endregion
-//#region ../../node_modules/.pnpm/scule@1.3.0/node_modules/scule/dist/index.mjs
-const NUMBER_CHAR_RE = /\d/;
-const STR_SPLITTERS = [
-	"-",
-	"_",
-	"/",
-	"."
-];
-function isUppercase(char = "") {
-	if (NUMBER_CHAR_RE.test(char)) return;
-	return char !== char.toLowerCase();
-}
-function splitByCase(str, separators) {
-	const splitters = separators ?? STR_SPLITTERS;
-	const parts = [];
-	if (!str || typeof str !== "string") return parts;
-	let buff = "";
-	let previousUpper;
-	let previousSplitter;
-	for (const char of str) {
-		const isSplitter = splitters.includes(char);
-		if (isSplitter === true) {
-			parts.push(buff);
-			buff = "";
-			previousUpper = void 0;
-			continue;
-		}
-		const isUpper = isUppercase(char);
-		if (previousSplitter === false) {
-			if (previousUpper === false && isUpper === true) {
-				parts.push(buff);
-				buff = char;
-				previousUpper = isUpper;
-				continue;
-			}
-			if (previousUpper === true && isUpper === false && buff.length > 1) {
-				const lastChar = buff.at(-1);
-				parts.push(buff.slice(0, Math.max(0, buff.length - 1)));
-				buff = lastChar + char;
-				previousUpper = isUpper;
-				continue;
-			}
-		}
-		buff += char;
-		previousUpper = isUpper;
-		previousSplitter = isSplitter;
-	}
-	parts.push(buff);
-	return parts;
-}
-function upperFirst(str) {
-	return str ? str[0].toUpperCase() + str.slice(1) : "";
-}
-function lowerFirst(str) {
-	return str ? str[0].toLowerCase() + str.slice(1) : "";
-}
-function pascalCase(str, opts) {
-	return str ? (Array.isArray(str) ? str : splitByCase(str)).map((p) => upperFirst(opts?.normalize ? p.toLowerCase() : p)).join("") : "";
-}
-function camelCase(str, opts) {
-	return lowerFirst(pascalCase(str || "", opts));
-}
-function kebabCase(str, joiner) {
-	return str ? (Array.isArray(str) ? str : splitByCase(str)).map((p) => p.toLowerCase()).join(joiner ?? "-") : "";
-}
-function snakeCase(str) {
-	return kebabCase(str || "", "_");
-}
-
 //#endregion
 //#region src/lint/plugin-core/rules/consistent-naming.ts
 const CONSISTENT_NAMING = "core/consistent-naming";
@@ -2206,7 +2111,7 @@ function defineConfig(rawConfig, { logger = new Logger(), cwd } = {}) {
 		config,
 		logger
 	});
-	for (const plugin of config.plugins) plugin.config?.({ ...config });
+	for (const plugin of config.plugins) plugin.config?.({ ...config }, { logger });
 	logger.debug({
 		group: "parser",
 		label: "config",
@@ -2375,7 +2280,6 @@ function normalizeLint({ config, logger }) {
 					message: `Expected string or number, received ${JSON.stringify(value)}`
 				});
 			}
-			for (const [id, severity] of Object.entries(RECOMMENDED_CONFIG)) if (!(id in config.lint.rules)) config.lint.rules[id] = severity;
 		}
 	} else config.lint = {
 		build: { enabled: true },
@@ -2489,40 +2393,8 @@ async function lintRunner({ tokens, filename, config = {}, sources, logger }) {
 	});
 }
 
-//#endregion
-//#region ../../node_modules/.pnpm/fast-deep-equal@3.1.3/node_modules/fast-deep-equal/index.js
-var require_fast_deep_equal = /* @__PURE__ */ __commonJS({ "../../node_modules/.pnpm/fast-deep-equal@3.1.3/node_modules/fast-deep-equal/index.js": ((exports, module) => {
-	module.exports = function equal(a, b) {
-		if (a === b) return true;
-		if (a && b && typeof a == "object" && typeof b == "object") {
-			if (a.constructor !== b.constructor) return false;
-			var length, i, keys;
-			if (Array.isArray(a)) {
-				length = a.length;
-				if (length != b.length) return false;
-				for (i = length; i-- !== 0;) if (!equal(a[i], b[i])) return false;
-				return true;
-			}
-			if (a.constructor === RegExp) return a.source === b.source && a.flags === b.flags;
-			if (a.valueOf !== Object.prototype.valueOf) return a.valueOf() === b.valueOf();
-			if (a.toString !== Object.prototype.toString) return a.toString() === b.toString();
-			keys = Object.keys(a);
-			length = keys.length;
-			if (length !== Object.keys(b).length) return false;
-			for (i = length; i-- !== 0;) if (!Object.prototype.hasOwnProperty.call(b, keys[i])) return false;
-			for (i = length; i-- !== 0;) {
-				var key = keys[i];
-				if (!equal(a[key], b[key])) return false;
-			}
-			return true;
-		}
-		return a !== a && b !== b;
-	};
-}) });
-
 //#endregion
 //#region src/lib/momoa.ts
-var import_fast_deep_equal = /* @__PURE__ */ __toESM(require_fast_deep_equal(), 1);
 /** Momoa’s default parser, with preferred settings. */
 function toMomoa(srcRaw) {
 	return momoa.parse(typeof srcRaw === "string" ? srcRaw : JSON.stringify(srcRaw, void 0, 2), {
@@ -2532,6 +2404,32 @@ function toMomoa(srcRaw) {
 	});
 }
 
+//#endregion
+//#region src/lib/resolver-utils.ts
+/**
+* If tokens are found inside a resolver, strip out the resolver paths (don’t
+* include "sets"/"modifiers" in the token ID etc.)
+*/
+function filterResolverPaths(path) {
+	switch (path[0]) {
+		case "sets": return path.slice(4);
+		case "modifiers": return path.slice(5);
+		case "resolutionOrder":
+			switch (path[2]) {
+				case "sources": return path.slice(4);
+				case "contexts": return path.slice(5);
+			}
+			break;
+	}
+	return path;
+}
+/**
+* Make a deterministic string from an object
+*/
+function makeInputKey(input) {
+	return JSON.stringify(Object.fromEntries(Object.entries(input).sort((a, b) => a[0].localeCompare(b[0], "en-us", { numeric: true }))));
+}
+
 //#endregion
 //#region src/resolver/validate.ts
 /**
@@ -2550,7 +2448,7 @@ function isLikelyResolver(doc) {
 			case "name":
 			case "description":
 			case "version":
-				if (member.name.type === "String") return true;
+				if (member.value.type === "String") return true;
 				break;
 			case "sets":
 			case "modifiers":
@@ -2685,6 +2583,7 @@ function validateResolver(node, { logger, src }) {
 					node: member.value
 				});
 				break;
+			case "$schema":
 			case "$ref":
 				if (member.value.type !== "String") errors.push({
 					...entry,
@@ -2868,6 +2767,21 @@ function validateModifier(node, isInline = false, { src }) {
 					node: context.value
 				});
 				break;
+			case "default":
+				if (member.value.type !== "String") errors.push({
+					...entry,
+					message: `Expected string`,
+					node: member.value
+				});
+				else {
+					const contexts = getObjMember(node, "contexts");
+					if (!contexts || !getObjMember(contexts, member.value.value)) errors.push({
+						...entry,
+						message: "Invalid default context",
+						node: member.value
+					});
+				}
+				break;
 			case "$defs":
 			case "$extensions":
 				if (member.value.type !== "Object") errors.push({
@@ -2910,204 +2824,6 @@ function validateModifier(node, isInline = false, { src }) {
 	return errors;
 }
 
-//#endregion
-//#region src/resolver/normalize.ts
-/** Normalize resolver (assuming it’s been validated) */
-async function normalizeResolver(node, { filename, req, src, logger, yamlToMomoa }) {
-	const resolverSource = evaluate(node);
-	const resolutionOrder = getObjMember(node.body, "resolutionOrder");
-	return {
-		name: resolverSource.name,
-		version: resolverSource.version,
-		description: resolverSource.description,
-		sets: resolverSource.sets,
-		modifiers: resolverSource.modifiers,
-		resolutionOrder: await Promise.all(resolutionOrder.elements.map(async (element, i) => {
-			const layer = element.value;
-			const members = getObjMembers(layer);
-			let item = layer;
-			if (members.$ref) {
-				const entry = {
-					group: "parser",
-					label: "init",
-					node: members.$ref,
-					src
-				};
-				const { url, subpath } = parseRef(members.$ref.value);
-				if (url === ".") if (!subpath?.[0]) logger.error({
-					...entry,
-					message: "$ref can’t refer to the root document."
-				});
-				else if (subpath[0] !== "sets" && subpath[0] !== "modifiers") logger.error({
-					...entry,
-					message: "Local $ref in resolutionOrder must point to either #/sets/[set] or #/modifiers/[modifiers]."
-				});
-				else {
-					const resolvedItem = resolverSource[subpath[0]]?.[subpath[1]];
-					if (!resolvedItem) logger.error({
-						...entry,
-						message: "Invalid $ref"
-					});
-					else item = {
-						type: subpath[0] === "sets" ? "set" : "modifier",
-						...resolvedItem
-					};
-				}
-				else {
-					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, true, src);
-							item = evaluate(result.document.body);
-						} else if (type?.type === "String" && type.value === "modifier") {
-							validateModifier(result.document.body, true, src);
-							item = evaluate(result.document.body);
-						}
-					}
-					logger.error({
-						...entry,
-						message: "$ref did not resolve to a valid Set or Modifier."
-					});
-				}
-			}
-			return evaluate((await bundle([{
-				filename,
-				src: item
-			}], {
-				req,
-				yamlToMomoa
-			})).document.body);
-		}))
-	};
-}
-
-//#endregion
-//#region src/resolver/load.ts
-/** Quick-parse input sources and find a resolver */
-async function loadResolver(inputs, { logger, req, yamlToMomoa }) {
-	let resolverDoc;
-	const entry = {
-		group: "parser",
-		label: "init"
-	};
-	for (const input of inputs) {
-		let document;
-		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, void 0, 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;
-	}
-	if (resolverDoc) {
-		validateResolver(resolverDoc, {
-			logger,
-			src: inputs[0].src
-		});
-		return createResolver(await normalizeResolver(resolverDoc, {
-			filename: inputs[0].filename,
-			logger,
-			req,
-			src: inputs[0].src,
-			yamlToMomoa
-		}), { logger });
-	}
-}
-/** Create an interface to resolve permutations */
-function createResolver(resolverSource, { logger }) {
-	const inputDefaults = {};
-	const modifierPermutations = [];
-	for (const [name, m] of Object.entries(resolverSource.modifiers ?? {})) {
-		if (typeof m.default === "string") inputDefaults[name] = m.default;
-		modifierPermutations.push([name, Object.keys(m.contexts)]);
-	}
-	for (const m of resolverSource.resolutionOrder) {
-		if (!("type" in m) || m.type !== "modifier") continue;
-		if (typeof m.default === "string") inputDefaults[m.name] = m.default;
-		modifierPermutations.push([m.name, Object.keys(m.contexts)]);
-	}
-	const permutations = calculatePermutations(modifierPermutations);
-	return {
-		apply(inputRaw) {
-			let tokens = {};
-			const input = {
-				...inputDefaults,
-				...inputRaw
-			};
-			for (const item of resolverSource.resolutionOrder) switch (item.type) {
-				case "set":
-					for (const s of item.sources) tokens = merge(tokens, s);
-					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 ?? []) tokens = merge(tokens, s);
-					break;
-				}
-			}
-			return tokens;
-		},
-		source: resolverSource,
-		permutations,
-		isValidInput(inputRaw) {
-			if (!inputRaw || typeof inputRaw !== "object") logger.error({
-				group: "parser",
-				label: "resolver",
-				message: `Invalid input: ${JSON.stringify(inputRaw)}.`
-			});
-			const input = {
-				...inputDefaults,
-				...inputRaw
-			};
-			return permutations.findIndex((p) => (0, import_fast_deep_equal.default)(input, p)) !== -1;
-		}
-	};
-}
-/** Calculate all permutations */
-function calculatePermutations(options) {
-	const permutationCount = [1];
-	for (const [_name, contexts] of options) permutationCount.push(contexts.length * (permutationCount.at(-1) || 1));
-	const permutations = [];
-	for (let i = 0; i < permutationCount.at(-1); i++) {
-		const input = {};
-		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 : [{}];
-}
-
 //#endregion
 //#region src/parse/normalize.ts
 /**
@@ -3227,14 +2943,14 @@ function aliasToRef(alias, mode) {
 }
 /** Generate a TokenNormalized from a Momoa node */
 function tokenFromNode(node, { groups, path, source, ignore }) {
-	if (!(node.type === "Object" && getObjMember(node, "$value") && !path.includes("$extensions"))) return;
+	if (!(node.type === "Object" && !!getObjMember(node, "$value") && !path.includes("$extensions"))) return;
 	const jsonID = `#/${path.join("/")}`;
 	const id = path.join(".");
 	const originalToken = momoa.evaluate(node);
 	const group = groups[`#/${path.slice(0, -1).join("/")}`];
 	if (group?.tokens && !group.tokens.includes(id)) group.tokens.push(id);
 	const nodeSource = {
-		filename: source.filename?.href,
+		filename: source.filename.href,
 		node
 	};
 	const token = {
@@ -3244,6 +2960,7 @@ function tokenFromNode(node, { groups, path, source, ignore }) {
 		$deprecated: originalToken.$deprecated ?? group.$deprecated ?? void 0,
 		$value: originalToken.$value,
 		$extensions: originalToken.$extensions || void 0,
+		$extends: originalToken.$extends || void 0,
 		aliasChain: void 0,
 		aliasedBy: void 0,
 		aliasOf: void 0,
@@ -3271,7 +2988,7 @@ function tokenFromNode(node, { groups, path, source, ignore }) {
 	const $extensions = getObjMember(node, "$extensions");
 	if ($extensions) {
 		const modeNode = getObjMember($extensions, "mode");
-		for (const mode of Object.keys(token.$extensions.mode)) {
+		for (const mode of Object.keys(token.$extensions.mode ?? {})) {
 			const modeValue = token.$extensions.mode[mode];
 			token.mode[mode] = {
 				$value: modeValue,
@@ -3579,80 +3296,28 @@ function resolveAliases(tokens, { logger, refMap, sources }) {
 }
 
 //#endregion
-//#region src/parse/load.ts
-/** Load from multiple entries, while resolving remote files */
-async function loadSources(inputs, { config, logger, req, continueOnError, yamlToMomoa, transform }) {
+//#region src/parse/process.ts
+function processTokens(rootSource, { config, logger, sourceByFilename, refMap }) {
 	const entry = {
 		group: "parser",
 		label: "init"
 	};
-	const firstLoad = performance.now();
-	let document = {};
-	/** The original user inputs, in original order, with parsed ASTs */
-	const sources = inputs.map((input, i) => ({
-		...input,
-		document: {},
-		filename: input.filename || new URL(`virtual:${i}`)
-	}));
-	/** The sources array, indexed by filename */
-	let sourceByFilename = {};
-	/** Mapping of all final $ref resolutions. This will be used to generate the graph later. */
-	let refMap = {};
-	try {
-		const result = await bundle(sources, {
-			req,
-			parse: transform ? transformer(transform) : void 0,
-			yamlToMomoa
-		});
-		document = result.document;
-		sourceByFilename = result.sources;
-		refMap = result.refMap;
-		for (const [filename, source] of Object.entries(result.sources)) {
-			const i = sources.findIndex((s) => s.filename.href === filename);
-			if (i === -1) sources.push(source);
-			else {
-				sources[i].src = source.src;
-				sources[i].document = source.document;
-			}
-		}
-	} catch (err) {
-		let src = sources.find((s) => s.filename.href === err.filename)?.src;
-		if (src && typeof src !== "string") src = JSON.stringify(src, void 0, 2);
-		logger.error({
-			...entry,
-			continueOnError,
-			message: err.message,
-			node: err.node,
-			src
-		});
-	}
-	logger.debug({
-		...entry,
-		message: `JSON loaded`,
-		timing: performance.now() - firstLoad
-	});
-	const artificialSource = {
-		src: momoa.print(document, { indent: 2 }),
-		document
-	};
-	const firstPass = performance.now();
-	const tokens = {};
-	const tokenIDs = [];
-	const groups = {};
-	await traverseAsync(document, { async enter(node, _parent, path) {
-		if (node.type !== "Object") return;
-		groupFromNode(node, {
-			path,
-			groups
+	const firstPass = performance.now();
+	const tokens = {};
+	const tokenIDs = [];
+	const groups = {};
+	const isResolver = isLikelyResolver(rootSource.document);
+	traverse(rootSource.document, { enter(node, _parent, rawPath) {
+		if (node.type !== "Object") return;
+		groupFromNode(node, {
+			path: isResolver ? filterResolverPaths(rawPath) : rawPath,
+			groups
 		});
 		const token = tokenFromNode(node, {
 			groups,
 			ignore: config.ignore,
-			path,
-			source: {
-				src: artificialSource,
-				document
-			}
+			path: isResolver ? filterResolverPaths(rawPath) : rawPath,
+			source: rootSource
 		});
 		if (token) {
 			tokenIDs.push(token.jsonID);
@@ -3665,7 +3330,7 @@ async function loadSources(inputs, { config, logger, req, continueOnError, yamlT
 		timing: performance.now() - firstPass
 	});
 	const secondPass = performance.now();
-	for (const source of Object.values(sourceByFilename)) await traverseAsync(source.document, { async enter(node, _parent, path) {
+	for (const source of Object.values(sourceByFilename)) traverse(source.document, { enter(node, _parent, path) {
 		if (node.type !== "Object") return;
 		const tokenRawValues = tokenRawValuesFromNode(node, {
 			filename: source.filename.href,
@@ -3722,8 +3387,378 @@ async function loadSources(inputs, { config, logger, req, continueOnError, yamlT
 		tokensSorted[id] = tokens[path];
 	}
 	for (const group of Object.values(groups)) group.tokens.sort((a, b) => a.localeCompare(b, "en-us", { numeric: true }));
+	return tokensSorted;
+}
+
+//#endregion
+//#region src/resolver/normalize.ts
+/** Normalize resolver (assuming it’s been validated) */
+async function normalizeResolver(node, { filename, req, src, logger, yamlToMomoa }) {
+	const resolverSource = momoa.evaluate(node);
+	const resolutionOrder = getObjMember(node.body, "resolutionOrder");
 	return {
-		tokens: tokensSorted,
+		name: resolverSource.name,
+		version: resolverSource.version,
+		description: resolverSource.description,
+		sets: resolverSource.sets,
+		modifiers: resolverSource.modifiers,
+		resolutionOrder: await Promise.all(resolutionOrder.elements.map(async (element, i) => {
+			const layer = element.value;
+			const members = getObjMembers(layer);
+			let item = layer;
+			if (members.$ref) {
+				const entry = {
+					group: "parser",
+					label: "init",
+					node: members.$ref,
+					src
+				};
+				const { url, subpath } = parseRef(members.$ref.value);
+				if (url === ".") if (!subpath?.[0]) logger.error({
+					...entry,
+					message: "$ref can’t refer to the root document."
+				});
+				else if (subpath[0] !== "sets" && subpath[0] !== "modifiers") logger.error({
+					...entry,
+					message: "Local $ref in resolutionOrder must point to either #/sets/[set] or #/modifiers/[modifiers]."
+				});
+				else {
+					const resolvedItem = resolverSource[subpath[0]]?.[subpath[1]];
+					if (!resolvedItem) logger.error({
+						...entry,
+						message: "Invalid $ref"
+					});
+					else item = {
+						type: subpath[0] === "sets" ? "set" : "modifier",
+						name: subpath[1],
+						...resolvedItem
+					};
+				}
+				else {
+					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, true, src);
+							item = momoa.evaluate(result.document.body);
+						} else if (type?.type === "String" && type.value === "modifier") {
+							validateModifier(result.document.body, true, src);
+							item = momoa.evaluate(result.document.body);
+						}
+					}
+					logger.error({
+						...entry,
+						message: "$ref did not resolve to a valid Set or Modifier."
+					});
+				}
+			}
+			const finalResult = await bundle([{
+				filename,
+				src: item
+			}], {
+				req,
+				yamlToMomoa
+			});
+			return momoa.evaluate(finalResult.document.body);
+		})),
+		_source: {
+			filename,
+			node
+		}
+	};
+}
+
+//#endregion
+//#region src/resolver/load.ts
+/** Quick-parse input sources and find a resolver */
+async function loadResolver(inputs, { config, logger, req, yamlToMomoa }) {
+	let resolverDoc;
+	let tokens = {};
+	const entry = {
+		group: "parser",
+		label: "init"
+	};
+	for (const input of inputs) {
+		let document;
+		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, void 0, 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;
+	if (resolverDoc) {
+		validateResolver(resolverDoc, {
+			logger,
+			src: inputs[0].src
+		});
+		resolver = createResolver(await normalizeResolver(resolverDoc, {
+			filename: inputs[0].filename,
+			logger,
+			req,
+			src: inputs[0].src,
+			yamlToMomoa
+		}), {
+			config,
+			logger,
+			sources: [{
+				...inputs[0],
+				document: resolverDoc
+			}]
+		});
+		const firstInput = {};
+		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
+		}]
+	};
+}
+/** Create an interface to resolve permutations */
+function createResolver(resolverSource, { config, logger, sources }) {
+	const inputDefaults = {};
+	const validContexts = {};
+	const allPermutations = [];
+	const resolverCache = {};
+	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) {
+			let tokensRaw = {};
+			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);
+					break;
+				case "modifier": {
+					const context = input[item.name];
+					const sources$1 = item.contexts[context];
+					if (!sources$1) logger.error({
+						group: "parser",
+						label: "resolver",
+						message: `Modifier ${item.name} has no context ${JSON.stringify(context)}.`
+					});
+					for (const s of sources$1 ?? []) tokensRaw = merge(tokensRaw, s);
+					break;
+				}
+			}
+			const src = JSON.stringify(tokensRaw, void 0, 2);
+			const rootSource = {
+				filename: resolverSource._source.filename,
+				document: toMomoa(src),
+				src
+			};
+			const tokens = processTokens(rootSource, {
+				config,
+				logger,
+				sourceByFilename: { [resolverSource._source.filename.href]: rootSource },
+				refMap: {},
+				sources
+			});
+			resolverCache[inputKey] = tokens;
+			return tokens;
+		},
+		source: resolverSource,
+		listPermutations() {
+			if (!allPermutations.length) allPermutations.push(...calculatePermutations(Object.entries(validContexts)));
+			return allPermutations;
+		},
+		isValidInput(input) {
+			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;
+			for (const [name, contexts] of Object.entries(validContexts)) if (name in input) {
+				if (!contexts.includes(input[name])) return false;
+			} else if (!(name in inputDefaults)) return false;
+			return true;
+		}
+	};
+}
+/** Calculate all permutations */
+function calculatePermutations(options) {
+	const permutationCount = [1];
+	for (const [_name, contexts] of options) permutationCount.push(contexts.length * (permutationCount.at(-1) || 1));
+	const permutations = [];
+	for (let i = 0; i < permutationCount.at(-1); i++) {
+		const input = {};
+		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 : [{}];
+}
+
+//#endregion
+//#region src/resolver/create-synthetic-resolver.ts
+/**
+* Interop layer upgrading legacy Terrazzo modes to resolvers
+*/
+async function createSyntheticResolver(tokens, { config, logger, req, sources }) {
+	const contexts = {};
+	for (const token of Object.values(tokens)) for (const [mode, value] of Object.entries(token.mode)) {
+		if (mode === ".") continue;
+		if (!(mode in contexts)) contexts[mode] = [{}];
+		addToken(contexts[mode][0], {
+			...token,
+			$value: value.$value
+		}, { logger });
+	}
+	const src = JSON.stringify({
+		name: "Terrazzo",
+		version: "2025.10",
+		resolutionOrder: [{ $ref: "#/sets/allTokens" }, { $ref: "#/modifiers/tzMode" }],
+		sets: { allTokens: { sources: [simpleFlatten(tokens, { logger })] } },
+		modifiers: { tzMode: {
+			description: "Automatically built from $extensions.mode",
+			contexts
+		} }
+	}, void 0, 2);
+	return createResolver(await normalizeResolver(momoa.parse(src), {
+		filename: new URL("file:///virtual:resolver.json"),
+		logger,
+		req,
+		src
+	}), {
+		config,
+		logger,
+		sources
+	});
+}
+/** Add a normalized token back into an arbitrary, hierarchial structure */
+function addToken(structure, token, { logger }) {
+	let node = structure;
+	const parts = token.id.split(".");
+	const localID = parts.pop();
+	for (const part of parts) {
+		if (!(part in node)) node[part] = {};
+		node = node[part];
+	}
+	if (localID in node) logger.error({
+		group: "parser",
+		label: "resolver",
+		message: `${localID} already exists!`
+	});
+	node[localID] = {
+		$type: token.$type,
+		$value: token.$value
+	};
+}
+/** Downconvert normalized tokens back into a simplified, hierarchial shape. This is extremely lossy, and only done to build a resolver. */
+function simpleFlatten(tokens, { logger }) {
+	const group = {};
+	for (const token of Object.values(tokens)) addToken(group, token, { logger });
+	return group;
+}
+
+//#endregion
+//#region src/parse/load.ts
+/** Load from multiple entries, while resolving remote files */
+async function loadSources(inputs, { config, logger, req, continueOnError, yamlToMomoa, transform }) {
+	const entry = {
+		group: "parser",
+		label: "init"
+	};
+	const firstLoad = performance.now();
+	let document = {};
+	/** The original user inputs, in original order, with parsed ASTs */
+	const sources = inputs.map((input, i) => ({
+		...input,
+		document: {},
+		filename: input.filename || new URL(`virtual:${i}`)
+	}));
+	/** The sources array, indexed by filename */
+	let sourceByFilename = {};
+	/** Mapping of all final $ref resolutions. This will be used to generate the graph later. */
+	let refMap = {};
+	try {
+		const result = await bundle(sources, {
+			req,
+			parse: transform ? transformer(transform) : void 0,
+			yamlToMomoa
+		});
+		document = result.document;
+		sourceByFilename = result.sources;
+		refMap = result.refMap;
+		for (const [filename, source] of Object.entries(result.sources)) {
+			const i = sources.findIndex((s) => s.filename.href === filename);
+			if (i === -1) sources.push(source);
+			else {
+				sources[i].src = source.src;
+				sources[i].document = source.document;
+			}
+		}
+	} catch (err) {
+		let src = sources.find((s) => s.filename.href === err.filename)?.src;
+		if (src && typeof src !== "string") src = JSON.stringify(src, void 0, 2);
+		logger.error({
+			...entry,
+			continueOnError,
+			message: err.message,
+			node: err.node,
+			src
+		});
+	}
+	logger.debug({
+		...entry,
+		message: `JSON loaded`,
+		timing: performance.now() - firstLoad
+	});
+	return {
+		tokens: processTokens({
+			filename: sources[0].filename,
+			document,
+			src: momoa.print(document, { indent: 2 })
+		}, {
+			config,
+			logger,
+			refMap,
+			sources,
+			sourceByFilename
+		}),
 		sources
 	};
 }
@@ -3740,7 +3775,9 @@ function transformer(transform) {
 			});
 			if (result) document = result;
 		}
-		await traverseAsync(document, { async enter(node, parent, path) {
+		const isResolver = isLikelyResolver(document);
+		traverse(document, { enter(node, parent, rawPath) {
+			const path = isResolver ? filterResolverPaths(rawPath) : rawPath;
 			if (node.type !== "Object" || !path.length) return;
 			const ctx = {
 				filename,
@@ -3775,21 +3812,33 @@ function transformer(transform) {
 /** Parse */
 async function parse(_input, { logger = new Logger(), req = defaultReq, skipLint = false, config = {}, continueOnError = false, yamlToMomoa, transform } = {}) {
 	const inputs = Array.isArray(_input) ? _input : [_input];
+	let tokens = {};
+	let resolver;
+	let sources = [];
 	const totalStart = performance.now();
-	const resolver = await loadResolver(inputs, {
+	const initStart = performance.now();
+	const resolverResult = await loadResolver(inputs, {
+		config,
 		logger,
 		req,
 		yamlToMomoa
 	});
-	const initStart = performance.now();
-	const { tokens, sources } = await loadSources(inputs, {
-		req,
-		logger,
-		config,
-		continueOnError,
-		yamlToMomoa,
-		transform
-	});
+	if (resolverResult.resolver) {
+		tokens = resolverResult.tokens;
+		sources = resolverResult.sources;
+		resolver = resolverResult.resolver;
+	} else {
+		const tokenResult = await loadSources(inputs, {
+			req,
+			logger,
+			config,
+			continueOnError,
+			yamlToMomoa,
+			transform
+		});
+		tokens = tokenResult.tokens;
+		sources = tokenResult.sources;
+	}
 	logger.debug({
 		message: "Loaded tokens",
 		group: "parser",
@@ -3811,6 +3860,19 @@ async function parse(_input, { logger = new Logger(), req = defaultReq, skipLint
 			timing: performance.now() - lintStart
 		});
 	}
+	const resolverTiming = performance.now();
+	const finalResolver = resolver || await createSyntheticResolver(tokens, {
+		config,
+		logger,
+		req,
+		sources
+	});
+	logger.debug({
+		message: "Resolver finalized",
+		group: "parser",
+		label: "core",
+		timing: performance.now() - resolverTiming
+	});
 	logger.debug({
 		message: "Finish all parser tasks",
 		group: "parser",
@@ -3827,7 +3889,7 @@ async function parse(_input, { logger = new Logger(), req = defaultReq, skipLint
 	return {
 		tokens,
 		sources,
-		resolver
+		resolver: finalResolver
 	};
 }
 let fs;