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

package/dist/index.js

@@ -230,29 +230,35 @@ function validateTransformParams({ params, logger, pluginName }) {
 		message: "setTransform() value expected object of strings, received some non-string values"
 	});
 }
+const FALLBACK_PERMUTATION_ID = JSON.stringify({ tzMode: "*" });
 /** Run build stage */
 async function build(tokens, { resolver, sources, logger = new Logger(), config }) {
 	const formats = {};
 	const result = { outputFiles: [] };
-	function getTransforms(params) {
-		if (!params?.format) {
-			logger.warn({
-				group: "plugin",
-				message: "\"format\" missing from getTransforms(), no tokens returned."
-			});
-			return [];
-		}
-		const tokenMatcher = params.id ? wcmatch(Array.isArray(params.id) ? params.id : [params.id]) : null;
-		const modeMatcher = params.mode ? wcmatch(params.mode) : null;
-		return (formats[params.format] ?? []).filter((token) => {
-			if (params.$type) {
-				if (typeof params.$type === "string" && token.token.$type !== params.$type) return false;
-				else if (Array.isArray(params.$type) && !params.$type.some(($type) => token.token.$type === $type)) return false;
+	function getTransforms(plugin) {
+		return function getTransforms$1(params) {
+			if (!params?.format) {
+				logger.warn({
+					group: "plugin",
+					label: plugin,
+					message: "\"format\" missing from getTransforms(), no tokens returned."
+				});
+				return [];
 			}
-			if (params.id && params.id !== "*" && tokenMatcher && !tokenMatcher(token.token.id)) return false;
-			if (modeMatcher && !modeMatcher(token.mode)) return false;
-			return true;
-		});
+			const tokenMatcher = params.id && params.id !== "*" ? wcmatch(params.id) : null;
+			const modeMatcher = params.mode ? wcmatch(params.mode) : null;
+			const permutationID = params.input ? resolver.getPermutationID(params.input) : JSON.stringify({ tzMode: "*" });
+			return (formats[params.format]?.[permutationID] ?? []).filter((token) => {
+				if (params.$type) {
+					if (typeof params.$type === "string" && token.token.$type !== params.$type) return false;
+					else if (Array.isArray(params.$type) && !params.$type.some(($type) => token.token.$type === $type)) return false;
+				}
+				if (tokenMatcher && !tokenMatcher(token.token.id)) return false;
+				if (params.input && token.permutationID !== resolver.getPermutationID(params.input)) return false;
+				if (modeMatcher && !modeMatcher(token.mode)) return false;
+				return true;
+			});
+		};
 	}
 	let transformsLocked = false;
 	const startTransform = performance.now();
@@ -260,7 +266,7 @@ async function build(tokens, { resolver, sources, logger = new Logger(), config
 		context: { logger },
 		tokens,
 		sources,
-		getTransforms,
+		getTransforms: getTransforms(plugin.name),
 		setTransform(id, params) {
 			if (transformsLocked) {
 				logger.warn({
@@ -271,6 +277,7 @@ async function build(tokens, { resolver, sources, logger = new Logger(), config
 				return;
 			}
 			const token = tokens[id];
+			const permutationID = params.input ? resolver.getPermutationID(params.input) : FALLBACK_PERMUTATION_ID;
 			const cleanValue = typeof params.value === "string" ? params.value : { ...params.value };
 			validateTransformParams({
 				logger,
@@ -280,19 +287,27 @@ async function build(tokens, { resolver, sources, logger = new Logger(), config
 				},
 				pluginName: plugin.name
 			});
-			if (!formats[params.format]) formats[params.format] = [];
-			const foundTokenI = formats[params.format].findIndex((t) => id === t.id && (!params.localID || params.localID === t.localID) && (!params.mode || params.mode === t.mode));
-			if (foundTokenI === -1) formats[params.format].push({
+			if (!formats[params.format]) formats[params.format] = {};
+			if (!formats[params.format][permutationID]) formats[params.format][permutationID] = [];
+			let foundTokenI = -1;
+			if (params.mode) foundTokenI = formats[params.format][permutationID].findIndex((t) => id === t.id && (!params.localID || params.localID === t.localID) && params.mode === t.mode);
+			else if (params.input) {
+				if (!formats[params.format][permutationID]) formats[params.format][permutationID] = [];
+				foundTokenI = formats[params.format][permutationID].findIndex((t) => id === t.id && (!params.localID || params.localID === t.localID) && permutationID === t.permutationID);
+			} else foundTokenI = formats[params.format][permutationID].findIndex((t) => id === t.id && (!params.localID || params.localID === t.localID));
+			if (foundTokenI === -1) formats[params.format][permutationID].push({
 				...params,
 				id,
 				value: cleanValue,
 				type: typeof cleanValue === "string" ? SINGLE_VALUE : MULTI_VALUE,
 				mode: params.mode || ".",
-				token: structuredClone(token)
+				token: structuredClone(token),
+				permutationID,
+				input: JSON.parse(permutationID)
 			});
 			else {
-				formats[params.format][foundTokenI].value = cleanValue;
-				formats[params.format][foundTokenI].type = typeof cleanValue === "string" ? SINGLE_VALUE : MULTI_VALUE;
+				formats[params.format][permutationID][foundTokenI].value = cleanValue;
+				formats[params.format][permutationID][foundTokenI].type = typeof cleanValue === "string" ? SINGLE_VALUE : MULTI_VALUE;
 			}
 		},
 		resolver
@@ -312,7 +327,7 @@ async function build(tokens, { resolver, sources, logger = new Logger(), config
 				context: { logger },
 				tokens,
 				sources,
-				getTransforms,
+				getTransforms: getTransforms(plugin.name),
 				resolver,
 				outputFile(filename, contents) {
 					const resolved = new URL(filename, config.outDir);
@@ -341,7 +356,7 @@ async function build(tokens, { resolver, sources, logger = new Logger(), config
 	await Promise.all(config.plugins.map(async (plugin) => plugin.buildEnd?.({
 		context: { logger },
 		tokens,
-		getTransforms,
+		getTransforms: getTransforms(plugin.name),
 		sources,
 		outputFiles: structuredClone(result.outputFiles)
 	})));
@@ -2150,6 +2165,7 @@ function normalizeTokens({ rawConfig, config, logger, cwd }) {
 			});
 		}
 	}
+	config.alphabetize = rawConfig.alphabetize ?? true;
 }
 /** Normalize config.outDir */
 function normalizeOutDir({ config, cwd, logger }) {
@@ -2423,449 +2439,66 @@ function filterResolverPaths(path) {
 	}
 	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 }))));
+/** Make a deterministic string from an object */
+function getPermutationID(input) {
+	const keys = Object.keys(input).sort((a, b) => a.localeCompare(b, "en-us", { numeric: true }));
+	return JSON.stringify(Object.fromEntries(keys.map((k) => [k, input[k]])));
 }
 
 //#endregion
-//#region src/resolver/validate.ts
-/**
-* 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.
-*/
-function isLikelyResolver(doc) {
-	if (doc.body.type !== "Object") return false;
-	for (const member of doc.body.members) {
-		if (member.name.type !== "String") continue;
-		switch (member.name.value) {
-			case "name":
-			case "description":
-			case "version":
-				if (member.value.type === "String") return true;
-				break;
-			case "sets":
-			case "modifiers":
-				if (member.value.type !== "Object") continue;
-				if (getObjMember(member.value, "description")?.type === "String") return true;
-				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")) return true;
-				}
-				break;
-			case "resolutionOrder":
-				if (member.value.type === "Array") return true;
-				break;
-		}
-	}
-	return false;
+//#region src/parse/assert.ts
+function assert(value, logger, entry) {
+	if (!value) logger.error(entry);
 }
-const MESSAGE_EXPECTED = {
-	STRING: "Expected string.",
-	OBJECT: "Expected object.",
-	ARRAY: "Expected array."
-};
+function assertStringNode(value, logger, entry) {
+	assert(value?.type === "String", logger, entry);
+}
+function assertObjectNode(value, logger, entry) {
+	assert(value?.type === "Object", logger, entry);
+}
+
+//#endregion
+//#region src/parse/normalize.ts
 /**
-* Validate a resolver document.
-* There’s a ton of boilerplate here, only to surface detailed code frames. Is there a better abstraction?
+* Normalize token value.
+* The reason for the “any” typing is this aligns various user-provided inputs to the type
 */
-function validateResolver(node, { logger, src }) {
+function normalize(token, { logger, src }) {
 	const entry = {
 		group: "parser",
-		label: "resolver",
+		label: "init",
 		src
 	};
-	if (node.body.type !== "Object") logger.error({
-		...entry,
-		message: MESSAGE_EXPECTED.OBJECT,
-		node
-	});
-	const errors = [];
-	let hasVersion = false;
-	let hasResolutionOrder = false;
-	for (const member of node.body.members) {
-		if (member.name.type !== "String") continue;
-		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;
-					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
-					});
-					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
-					});
-				}
-				break;
-			case "$defs":
-			case "$extensions":
-				if (member.value.type !== "Object") errors.push({
-					...entry,
-					message: `Expected object`,
-					node: member.value
-				});
-				break;
-			case "$schema":
-			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;
+	function normalizeFontFamily(value) {
+		return typeof value === "string" ? [value] : value;
+	}
+	function normalizeFontWeight(value) {
+		return typeof value === "string" && FONT_WEIGHTS[value] || value;
+	}
+	function normalizeColor(value, node) {
+		if (typeof value === "string" && !isAlias(value)) {
+			logger.warn({
+				...entry,
+				node,
+				message: `${token.id}: string colors will be deprecated in a future version. Please update to object notation`
+			});
+			try {
+				return parseColor(value);
+			} catch {
+				return {
+					colorSpace: "srgb",
+					components: [
+						0,
+						0,
+						0
+					],
+					alpha: 1
+				};
+			}
+		} else if (value && typeof value === "object") {
+			if (value.alpha === void 0) value.alpha = 1;
 		}
-	}
-	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);
-}
-function validateSet(node, isInline = false, { src }) {
-	const entry = {
-		group: "parser",
-		label: "resolver",
-		src
-	};
-	const errors = [];
-	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;
-		}
-	}
-	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;
-}
-function validateModifier(node, isInline = false, { src }) {
-	const errors = [];
-	const entry = {
-		group: "parser",
-		label: "resolver",
-		src
-	};
-	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 "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({
-					...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;
-		}
-	}
-	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;
-}
-
-//#endregion
-//#region src/parse/normalize.ts
-/**
-* Normalize token value.
-* The reason for the “any” typing is this aligns various user-provided inputs to the type
-*/
-function normalize(token, { logger, src }) {
-	const entry = {
-		group: "parser",
-		label: "init",
-		src
-	};
-	function normalizeFontFamily(value) {
-		return typeof value === "string" ? [value] : value;
-	}
-	function normalizeFontWeight(value) {
-		return typeof value === "string" && FONT_WEIGHTS[value] || value;
-	}
-	function normalizeColor(value, node) {
-		if (typeof value === "string" && !isAlias(value)) {
-			logger.warn({
-				...entry,
-				node,
-				message: `${token.id}: string colors will be deprecated in a future version. Please update to object notation`
-			});
-			try {
-				return parseColor(value);
-			} catch {
-				return {
-					colorSpace: "srgb",
-					components: [
-						0,
-						0,
-						0
-					],
-					alpha: 1
-				};
-			}
-		} else if (value && typeof value === "object") {
-			if (value.alpha === void 0) value.alpha = 1;
-		}
-		return value;
+		return value;
 	}
 	switch (token.$type) {
 		case "color":
@@ -2951,7 +2584,7 @@ function aliasToTokenRef(alias, mode) {
 function tokenFromNode(node, { groups, path, source, ignore }) {
 	if (!(node.type === "Object" && !!getObjMember(node, "$value") && !path.includes("$extensions"))) return;
 	const jsonID = encodeFragment(path);
-	const id = path.join(".");
+	const id = path.join(".").replace(/\.\$root$/, "");
 	const originalToken = momoa.evaluate(node);
 	const group = groups[encodeFragment(path.slice(0, -1))];
 	if (group?.tokens && !group.tokens.includes(id)) group.tokens.push(id);
@@ -3176,7 +2809,7 @@ function refToTokenID($ref) {
 	if (typeof path !== "string") return;
 	const { subpath } = parseRef(path);
 	if (subpath?.[0] === "$defs") subpath.splice(0, 2);
-	return subpath?.length && subpath.join(".").replace(/\.(\$value|\$extensions).*$/, "") || void 0;
+	return subpath?.length && subpath.join(".").replace(/\.(\$root|\$value|\$extensions).*$/, "") || void 0;
 }
 const EXPECTED_NESTED_ALIAS = {
 	border: {
@@ -3304,7 +2937,7 @@ function resolveAliases(tokens, { logger, refMap, sources }) {
 
 //#endregion
 //#region src/parse/process.ts
-function processTokens(rootSource, { config, logger, sourceByFilename }) {
+function processTokens(rootSource, { config, logger, sourceByFilename, isResolver }) {
 	const entry = {
 		group: "parser",
 		label: "init"
@@ -3312,13 +2945,19 @@ function processTokens(rootSource, { config, logger, sourceByFilename }) {
 	const refMap = {};
 	function resolveRef(node, chain) {
 		const { subpath } = parseRef(node.value);
-		if (!subpath) logger.error({
+		assert(subpath, logger, {
 			...entry,
 			message: "Can’t resolve $ref",
 			node,
 			src: rootSource.src
 		});
 		const next = findNode(rootSource.document, subpath);
+		assert(next, logger, {
+			...entry,
+			message: "Can't find $ref",
+			node,
+			src: rootSource.src
+		});
 		if (next?.type === "Object") {
 			const next$ref = getObjMember(next, "$ref");
 			if (next$ref && next$ref.type === "String") {
@@ -3339,7 +2978,7 @@ function processTokens(rootSource, { config, logger, sourceByFilename }) {
 		if (rawPath.includes("$extensions") || node.type !== "Object") return;
 		const $ref = node.type === "Object" ? getObjMember(node, "$ref") : void 0;
 		if (!$ref) return;
-		if ($ref.type !== "String") logger.error({
+		assertStringNode($ref, logger, {
 			...entry,
 			message: "Invalid $ref. Expected string.",
 			node: $ref,
@@ -3363,10 +3002,9 @@ function processTokens(rootSource, { config, logger, sourceByFilename }) {
 	});
 	function flatten$extends(node, chain) {
 		const memberKeys = node.members.map((m) => m.name.type === "String" && m.name.value).filter(Boolean);
-		let extended;
 		if (memberKeys.includes("$extends")) {
 			const $extends = getObjMember(node, "$extends");
-			if ($extends.type !== "String") logger.error({
+			assertStringNode($extends, logger, {
 				...entry,
 				message: "$extends must be a string",
 				node: $extends,
@@ -3379,7 +3017,7 @@ function processTokens(rootSource, { config, logger, sourceByFilename }) {
 				src: rootSource.src
 			});
 			const next = isAlias($extends.value) ? aliasToGroupRef($extends.value) : void 0;
-			if (!next) logger.error({
+			assert(next, logger, {
 				...entry,
 				message: "$extends must be a valid alias",
 				node: $extends,
@@ -3392,14 +3030,14 @@ function processTokens(rootSource, { config, logger, sourceByFilename }) {
 				src: rootSource.src
 			});
 			chain.push(next.$ref);
-			extended = findNode(rootSource.document, parseRef(next.$ref).subpath ?? []);
-			if (!extended) logger.error({
+			const extended = findNode(rootSource.document, parseRef(next.$ref).subpath ?? []);
+			assert(extended, logger, {
 				...entry,
 				message: "Could not resolve $extends",
 				node: $extends,
 				src: rootSource.src
 			});
-			if (extended.type !== "Object") logger.error({
+			assertObjectNode(extended, logger, {
 				...entry,
 				message: "$extends must resolve to a group of tokens",
 				node
@@ -3422,7 +3060,6 @@ function processTokens(rootSource, { config, logger, sourceByFilename }) {
 	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, {
@@ -3495,6 +3132,7 @@ function processTokens(rootSource, { config, logger, sourceByFilename }) {
 		message: "Normalized values",
 		timing: performance.now() - normalizeStart
 	});
+	if (config.alphabetize === false) return tokens;
 	const sortStart = performance.now();
 	const tokensSorted = {};
 	tokenIDs.sort((a, b) => a.localeCompare(b, "en-us", { numeric: true }));
@@ -3599,36 +3237,440 @@ function findObject(dict, path, logger) {
 }
 
 //#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,
+//#region src/resolver/validate.ts
+/**
+* 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.
+*/
+function isLikelyResolver(doc) {
+	if (doc.body.type !== "Object") return false;
+	for (const member of doc.body.members) {
+		if (member.name.type !== "String") continue;
+		switch (member.name.value) {
+			case "name":
+			case "description":
+			case "version":
+				if (member.value.type === "String") return true;
+				break;
+			case "sets":
+			case "modifiers":
+				if (member.value.type !== "Object") continue;
+				if (getObjMember(member.value, "description")?.type === "String") return true;
+				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")) return true;
+				}
+				break;
+			case "resolutionOrder":
+				if (member.value.type === "Array") return true;
+				break;
+		}
+	}
+	return false;
+}
+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?
+*/
+function validateResolver(node, { logger, src }) {
+	const entry = {
+		group: "parser",
+		label: "resolver",
+		src
+	};
+	if (node.body.type !== "Object") logger.error({
+		...entry,
+		message: MESSAGE_EXPECTED.OBJECT,
+		node
+	});
+	const errors = [];
+	let hasVersion = false;
+	let hasResolutionOrder = false;
+	for (const member of node.body.members) {
+		if (member.name.type !== "String") continue;
+		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;
+					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
+					});
+					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
+					});
+				}
+				break;
+			case "$defs":
+			case "$extensions":
+				if (member.value.type !== "Object") errors.push({
+					...entry,
+					message: `Expected object`,
+					node: member.value
+				});
+				break;
+			case "$schema":
+			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;
+		}
+	}
+	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);
+}
+function validateSet(node, isInline = false, { src }) {
+	const entry = {
+		group: "parser",
+		label: "resolver",
+		src
+	};
+	const errors = [];
+	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
+				});
+				else for (const source of member.value.elements) if (source.value.type !== "Object") errors.push({
+					...entry,
+					message: MESSAGE_EXPECTED.OBJECT,
+					node: source.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;
+		}
+	}
+	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;
+}
+function validateModifier(node, isInline = false, { src }) {
+	const errors = [];
+	const entry = {
+		group: "parser",
+		label: "resolver",
+		src
+	};
+	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
+				});
+				else for (const source of context.value.elements) if (source.value.type !== "Object") errors.push({
+					...entry,
+					message: MESSAGE_EXPECTED.OBJECT,
+					node: source.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({
+					...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;
+		}
+	}
+	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;
+}
+
+//#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;
@@ -3687,8 +3729,8 @@ function createResolver(resolverSource, { config, logger, sources }) {
 				...inputDefaults,
 				...inputRaw
 			};
-			const inputKey = makeInputKey(input);
-			if (resolverCache[inputKey]) return resolverCache[inputKey];
+			const permutationID = getPermutationID(input);
+			if (resolverCache[permutationID]) return resolverCache[permutationID];
 			for (const item of resolverSource.resolutionOrder) switch (item.type) {
 				case "set":
 					for (const s of item.sources) tokensRaw = merge(tokensRaw, s);
@@ -3697,8 +3739,7 @@ function createResolver(resolverSource, { config, logger, sources }) {
 					const context = input[item.name];
 					const sources$1 = item.contexts[context];
 					if (!sources$1) logger.error({
-						group: "parser",
-						label: "resolver",
+						group: "resolver",
 						message: `Modifier ${item.name} has no context ${JSON.stringify(context)}.`
 					});
 					for (const s of sources$1 ?? []) tokensRaw = merge(tokensRaw, s);
@@ -3715,9 +3756,10 @@ function createResolver(resolverSource, { config, logger, sources }) {
 				config,
 				logger,
 				sourceByFilename: { [resolverSource._source.filename.href]: rootSource },
+				isResolver: true,
 				sources
 			});
-			resolverCache[inputKey] = tokens;
+			resolverCache[permutationID] = tokens;
 			return tokens;
 		},
 		source: resolverSource,
@@ -3725,17 +3767,41 @@ function createResolver(resolverSource, { config, logger, sources }) {
 			if (!allPermutations.length) allPermutations.push(...calculatePermutations(Object.entries(validContexts)));
 			return allPermutations;
 		},
-		isValidInput(input) {
+		isValidInput(input, throwError = false) {
 			if (!input || typeof input !== "object") logger.error({
-				group: "parser",
-				label: "resolver",
+				group: "resolver",
 				message: `Invalid input: ${JSON.stringify(input)}.`
 			});
-			if (!Object.keys(input).every((k) => k in validContexts)) return false;
+			for (const k of Object.keys(input)) if (!(k in validContexts)) {
+				if (throwError) logger.error({
+					group: "resolver",
+					message: `No such modifier ${JSON.stringify(k)}`
+				});
+				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;
+				if (!contexts.includes(input[name])) {
+					if (throwError) logger.error({
+						group: "resolver",
+						message: `Modifier "${name}" has no context ${JSON.stringify(input[name])}.`
+					});
+					return false;
+				}
+			} else if (!(name in inputDefaults)) {
+				if (throwError) logger.error({
+					group: "resolver",
+					message: `Modifier "${name}" missing value (no default set).`
+				});
+				return false;
+			}
 			return true;
+		},
+		getPermutationID(input) {
+			this.isValidInput(input, true);
+			return getPermutationID({
+				...inputDefaults,
+				...input
+			});
 		}
 	};
 }