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

package/dist/index.js

@@ -4,7 +4,7 @@ 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, parseRef, replaceNode, traverseAsync } from "@terrazzo/json-schema-tools";
+import { bundle, getObjMember, getObjMembers, isPure$ref, maybeRawJSON, parseRef, replaceNode, traverse } from "@terrazzo/json-schema-tools";
 
 //#region src/lib/code-frame.ts
 /**
@@ -34,10 +34,8 @@ function getMarkerLines(loc, source, opts = {}) {
 	if (lineDiff) for (let i = 0; i <= lineDiff; i++) {
 		const lineNumber = i + startLine;
 		if (!startColumn) markerLines[lineNumber] = true;
-		else if (i === 0) {
-			const sourceLength = source[lineNumber - 1].length;
-			markerLines[lineNumber] = [startColumn, sourceLength - startColumn + 1];
-		} else if (i === lineDiff) markerLines[lineNumber] = [0, endColumn];
+		else if (i === 0) markerLines[lineNumber] = [startColumn, source[lineNumber - 1].length - startColumn + 1];
+		else if (i === lineDiff) markerLines[lineNumber] = [0, endColumn];
 		else markerLines[lineNumber] = [0, source[lineNumber - i].length];
 	}
 	else if (startColumn === endColumn) if (startColumn) markerLines[startLine] = [startColumn, 0];
@@ -55,8 +53,7 @@ function getMarkerLines(loc, source, opts = {}) {
 const NEWLINE = /\r\n|[\n\r\u2028\u2029]/;
 function codeFrameColumns(rawLines, loc, opts = {}) {
 	if (typeof rawLines !== "string") throw new Error(`Expected string, got ${rawLines}`);
-	const lines = rawLines.split(NEWLINE);
-	const { start, end, markerLines } = getMarkerLines(loc, lines, opts);
+	const { start, end, markerLines } = getMarkerLines(loc, rawLines.split(NEWLINE), opts);
 	const hasColumns = loc.start && typeof loc.start.column === "number";
 	const numberMaxWidth = String(end).length;
 	let frame = rawLines.split(NEWLINE, end).slice(start, end).map((line, index) => {
@@ -354,7 +351,7 @@ async function build(tokens, { sources, logger = new Logger(), config }) {
 //#endregion
 //#region src/lint/plugin-core/lib/docs.ts
 function docsLink(ruleName) {
-	return `https://terrazzo.app/docs/cli/lint#${ruleName.replaceAll("/", "")}`;
+	return `https://terrazzo.app/docs/linting#${ruleName.replaceAll("/", "")}`;
 }
 
 //#endregion
@@ -390,9 +387,7 @@ const rule$26 = {
 			if (tokens[foreground].$type !== "color") throw new Error(`Token ${foreground} isn’t a color`);
 			if (!tokens[background]) throw new Error(`Token ${background} does not exist`);
 			if (tokens[background].$type !== "color") throw new Error(`Token ${background} isn’t a color`);
-			const a = tokenToCulori(tokens[foreground].$value);
-			const b = tokenToCulori(tokens[background].$value);
-			const contrast = wcagContrast(a, b);
+			const contrast = wcagContrast(tokenToCulori(tokens[foreground].$value), tokenToCulori(tokens[background].$value));
 			const min = WCAG2_MIN_CONTRAST[options.level ?? "AA"][largeText ? "large" : "default"];
 			if (contrast < min) report({
 				messageId: ERROR_INSUFFICIENT_CONTRAST,
@@ -719,8 +714,7 @@ function isWithinGamut(color, gamut) {
 		"hsl",
 		"hwb"
 	].includes(parsed.mode)) return true;
-	const clamped = clampChroma(parsed, parsed.mode, gamut === "srgb" ? "rgb" : gamut);
-	return isWithinThreshold(parsed, clamped);
+	return isWithinThreshold(parsed, clampChroma(parsed, parsed.mode, gamut === "srgb" ? "rgb" : gamut));
 }
 /** is Color A close enough to Color B? */
 function isWithinThreshold(a, b, tolerance = TOLERANCE) {
@@ -807,36 +801,13 @@ const rule$20 = {
 };
 var max_gamut_default = rule$20;
 
-//#endregion
-//#region src/lint/plugin-core/rules/no-type-on-alias.ts
-const NO_TYPE_ON_ALIAS = "core/no-type-on-alias";
-const ERROR$10 = "ERROR";
-const rule$19 = {
-	meta: {
-		messages: { [ERROR$10]: "Remove $type from aliased value." },
-		docs: {
-			description: "If a $value is aliased it already has a $type defined.",
-			url: docsLink(NO_TYPE_ON_ALIAS)
-		}
-	},
-	defaultOptions: {},
-	create({ tokens, report }) {
-		for (const t of Object.values(tokens)) if (isAlias(t.originalValue.$value) && t.originalValue?.$type) report({
-			messageId: ERROR$10,
-			node: t.source.node,
-			filename: t.source.filename
-		});
-	}
-};
-var no_type_on_alias_default = rule$19;
-
 //#endregion
 //#region src/lint/plugin-core/rules/required-children.ts
 const REQUIRED_CHILDREN = "core/required-children";
 const ERROR_EMPTY_MATCH = "EMPTY_MATCH";
 const ERROR_MISSING_REQUIRED_TOKENS = "MISSING_REQUIRED_TOKENS";
 const ERROR_MISSING_REQUIRED_GROUP = "MISSING_REQUIRED_GROUP";
-const rule$18 = {
+const rule$19 = {
 	meta: {
 		messages: {
 			[ERROR_EMPTY_MATCH]: "No tokens matched {{ matcher }}",
@@ -894,12 +865,12 @@ const rule$18 = {
 		}
 	}
 };
-var required_children_default = rule$18;
+var required_children_default = rule$19;
 
 //#endregion
 //#region src/lint/plugin-core/rules/required-modes.ts
 const REQUIRED_MODES = "core/required-modes";
-const rule$17 = {
+const rule$18 = {
 	meta: { docs: {
 		description: "Enforce certain tokens have specific modes.",
 		url: docsLink(REQUIRED_MODES)
@@ -930,7 +901,30 @@ const rule$17 = {
 		}
 	}
 };
-var required_modes_default = rule$17;
+var required_modes_default = rule$18;
+
+//#endregion
+//#region src/lint/plugin-core/rules/required-type.ts
+const REQUIRED_TYPE = "core/required-type";
+const ERROR$10 = "ERROR";
+const rule$17 = {
+	meta: {
+		messages: { [ERROR$10]: "Token missing $type." },
+		docs: {
+			description: "Requiring every token to have $type, even aliases, simplifies computation.",
+			url: docsLink(REQUIRED_TYPE)
+		}
+	},
+	defaultOptions: {},
+	create({ tokens, report }) {
+		for (const t of Object.values(tokens)) if (!t.originalValue?.$type) report({
+			messageId: ERROR$10,
+			node: t.source.node,
+			filename: t.source.filename
+		});
+	}
+};
+var required_type_default = rule$17;
 
 //#endregion
 //#region src/lint/plugin-core/rules/required-typography-properties.ts
@@ -1340,8 +1334,7 @@ const rule$11 = {
 					break;
 				case "strokeStyle":
 					if (typeof t.originalValue.$value === "object" && Array.isArray(t.originalValue.$value.dashArray)) {
-						const $valueNode = getObjMember(t.source.node, "$value");
-						const dashArray = getObjMember($valueNode, "dashArray");
+						const dashArray = getObjMember(getObjMember(t.source.node, "$value"), "dashArray");
 						for (let i = 0; i < t.originalValue.$value.dashArray.length; i++) {
 							if (isAlias(t.originalValue.$value.dashArray[i])) continue;
 							validateDimension(t.originalValue.$value.dashArray[i], {
@@ -1359,8 +1352,7 @@ const rule$11 = {
 							filename: t.source.filename
 						});
 						if (typeof t.originalValue.$value.style === "object" && Array.isArray(t.originalValue.$value.style.dashArray)) {
-							const style = getObjMember($valueNode, "style");
-							const dashArray = getObjMember(style, "dashArray");
+							const dashArray = getObjMember(getObjMember($valueNode, "style"), "dashArray");
 							for (let i = 0; i < t.originalValue.$value.style.dashArray.length; i++) {
 								if (isAlias(t.originalValue.$value.style.dashArray[i])) continue;
 								validateDimension(t.originalValue.$value.style.dashArray[i], {
@@ -1580,8 +1572,7 @@ const rule$9 = {
 				case "typography":
 					if (typeof t.originalValue.$value === "object" && t.originalValue.$value.fontFamily) {
 						if (t.partialAliasOf?.fontFamily) continue;
-						const $value = getObjMember(t.source.node, "$value");
-						const properties = getObjMembers($value);
+						const properties = getObjMembers(getObjMember(t.source.node, "$value"));
 						validateFontFamily(t.originalValue.$value.fontFamily, {
 							node: properties.fontFamily,
 							filename: t.source.filename
@@ -1643,8 +1634,7 @@ const rule$8 = {
 				case "typography":
 					if (typeof t.originalValue.$value === "object" && t.originalValue.$value.fontWeight) {
 						if (t.partialAliasOf?.fontWeight) continue;
-						const $value = getObjMember(t.source.node, "$value");
-						const properties = getObjMembers($value);
+						const properties = getObjMembers(getObjMember(t.source.node, "$value"));
 						validateFontWeight(t.originalValue.$value.fontWeight, {
 							node: properties.fontWeight,
 							filename: t.source.filename
@@ -2113,9 +2103,9 @@ const ALL_RULES = {
 	[DESCRIPTIONS]: descriptions_default,
 	[DUPLICATE_VALUES]: duplicate_values_default,
 	[MAX_GAMUT]: max_gamut_default,
-	[NO_TYPE_ON_ALIAS]: no_type_on_alias_default,
 	[REQUIRED_CHILDREN]: required_children_default,
 	[REQUIRED_MODES]: required_modes_default,
+	[REQUIRED_TYPE]: required_type_default,
 	[REQUIRED_TYPOGRAPHY_PROPERTIES]: required_typography_properties_default,
 	[A11Y_MIN_CONTRAST]: a11y_min_contrast_default,
 	[A11Y_MIN_FONT_SIZE]: a11y_min_font_size_default
@@ -2145,8 +2135,7 @@ const RECOMMENDED_CONFIG = {
 	[VALID_SHADOW]: ["error", {}],
 	[VALID_GRADIENT]: ["error", {}],
 	[VALID_TYPOGRAPHY]: ["error", {}],
-	[CONSISTENT_NAMING]: ["warn", { format: "kebab-case" }],
-	[NO_TYPE_ON_ALIAS]: ["warn", {}]
+	[CONSISTENT_NAMING]: ["warn", { format: "kebab-case" }]
 };
 
 //#endregion
@@ -2321,7 +2310,7 @@ function normalizeLint({ config, logger }) {
 				});
 				const value = config.lint.rules[id];
 				let severity = "off";
-				let options;
+				let options = {};
 				if (typeof value === "number" || typeof value === "string") severity = value;
 				else if (Array.isArray(value)) {
 					severity = value[0];
@@ -2480,6 +2469,410 @@ 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
+/**
+* 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.name.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 "$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
+				});
+				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 "$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
 /**
@@ -2603,11 +2996,10 @@ function tokenFromNode(node, { groups, path, source, ignore }) {
 	const jsonID = `#/${path.join("/")}`;
 	const id = path.join(".");
 	const originalToken = momoa.evaluate(node);
-	const groupID = `#/${path.slice(0, -1).join("/")}`;
-	const group = groups[groupID];
+	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 = {
@@ -2873,6 +3265,13 @@ function resolveAliases(tokens, { logger, refMap, sources }) {
 		for (const mode of Object.keys(token.mode)) {
 			function resolveInner(alias, refChain) {
 				const nextRef = aliasToRef(alias, mode)?.$ref;
+				if (!nextRef) {
+					logger.error({
+						...aliasEntry,
+						message: `Internal error resolving ${JSON.stringify(refChain)}`
+					});
+					throw new Error("Internal error");
+				}
 				if (refChain.includes(nextRef)) logger.error({
 					...aliasEntry,
 					message: "Circular alias detected."
@@ -2945,67 +3344,20 @@ 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, 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, {
-			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) {
+	const isResolver = isLikelyResolver(rootSource.document);
+	traverse(rootSource.document, { enter(node, _parent, rawPath) {
 		if (node.type !== "Object") return;
+		const path = isResolver ? filterResolverPaths(rawPath) : rawPath;
 		groupFromNode(node, {
 			path,
 			groups
@@ -3014,10 +3366,7 @@ async function loadSources(inputs, { config, logger, continueOnError, yamlToMomo
 			groups,
 			ignore: config.ignore,
 			path,
-			source: {
-				src: artificialSource,
-				document
-			}
+			source: rootSource
 		});
 		if (token) {
 			tokenIDs.push(token.jsonID);
@@ -3030,7 +3379,7 @@ async function loadSources(inputs, { config, logger, continueOnError, yamlToMomo
 		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,
@@ -3087,8 +3436,377 @@ async function loadSources(inputs, { config, logger, continueOnError, yamlToMomo
 		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 {
+		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 {
-		tokens: tokensSorted,
+		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 tokens = processTokens({
+				filename: resolverSource._source.filename,
+				document: toMomoa(src),
+				src
+			}, {
+				config,
+				logger,
+				sourceByFilename: {},
+				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
 	};
 }
@@ -3105,7 +3823,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,
@@ -3138,17 +3858,35 @@ function transformer(transform) {
 //#endregion
 //#region src/parse/index.ts
 /** Parse */
-async function parse(_input, { logger = new Logger(), skipLint = false, config = {}, continueOnError = false, yamlToMomoa, transform } = {}) {
+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 initStart = performance.now();
-	const { tokens, sources } = await loadSources(inputs, {
-		logger,
+	const resolverResult = await loadResolver(inputs, {
 		config,
-		continueOnError,
-		yamlToMomoa,
-		transform
+		logger,
+		req,
+		yamlToMomoa
 	});
+	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",
@@ -3185,10 +3923,27 @@ async function parse(_input, { logger = new Logger(), skipLint = false, config =
 	}
 	return {
 		tokens,
-		sources
+		sources,
+		resolver: resolver || await createSyntheticResolver(tokens, {
+			config,
+			logger,
+			req,
+			sources
+		})
 	};
 }
+let fs;
+/** Fallback req */
+async function defaultReq(src, _origin) {
+	if (src.protocol === "file:") {
+		if (!fs) fs = await import("node:fs/promises");
+		return await fs.readFile(src, "utf8");
+	}
+	const res = await fetch(src);
+	if (!res.ok) throw new Error(`${src} responded with ${res.status}\n${await res.text()}`);
+	return await res.text();
+}
 
 //#endregion
-export { LOG_ORDER, Logger, MULTI_VALUE, RECOMMENDED_CONFIG, SINGLE_VALUE, TokensJSONError, build, defineConfig, formatMessage, lintRunner, mergeConfigs, parse };
+export { LOG_ORDER, Logger, MULTI_VALUE, RECOMMENDED_CONFIG, SINGLE_VALUE, TokensJSONError, build, calculatePermutations, createResolver, defineConfig, formatMessage, isLikelyResolver, lintRunner, loadResolver, mergeConfigs, normalizeResolver, parse, validateModifier, validateResolver, validateSet };
 //# sourceMappingURL=index.js.map