@optique/core 1.3.0-dev.2529 → 1.3.0-dev.2532

package/dist/usage.cjs

@@ -1,4 +1,5 @@
 const require_displaywidth = require('./displaywidth.cjs');
+const require_terminal_internal = require('./terminal-internal.cjs');
 const require_validate = require('./validate.cjs');
 
 //#region src/usage.ts
@@ -182,6 +183,10 @@ function extractArgumentMetavars(usage) {
 *         whitespace-only, or contains control characters.
 */
 function formatUsage(programName, usage, options = {}) {
+	options = {
+		...options,
+		theme: require_terminal_internal.cacheTerminalTheme(options.theme)
+	};
 	require_validate.validateProgramName(programName);
 	usage = normalizeUsage(filterUsageForDisplay(usage));
 	if (options.expandCommands) {
@@ -197,29 +202,23 @@ function formatUsage(programName, usage, options = {}) {
 			if (lines.length > 0) return lines.join("\n");
 		}
 	}
-	let output = options.colors ? `\x1b[1m${programName}\x1b[0m` : programName;
-	let lineWidth = require_displaywidth.getDisplayWidth(programName);
-	let first = true;
-	for (const { text, width } of formatUsageTerms(usage, options)) {
-		if (first) {
-			first = false;
-			if (options.maxWidth != null && lineWidth + 1 + width > options.maxWidth) {
-				output += "\n";
-				lineWidth = 0;
-			} else {
-				output += " ";
-				lineWidth += 1;
-			}
-		} else if (options.maxWidth != null && lineWidth > 0 && lineWidth + width > options.maxWidth) {
-			if (output.endsWith(" ")) output = output.slice(0, -1);
-			output += "\n";
-			lineWidth = 0;
-			if (text === " ") continue;
-		}
-		output += text;
-		lineWidth += width;
-	}
-	return output;
+	const programTokens = layoutUsageTokens(require_terminal_internal.fragmentTokens(require_terminal_internal.formatTerminalTerm({
+		type: "programName",
+		programName
+	}, options.theme)), options);
+	const terms = [...formatUsageTerms(usage, options)];
+	if (terms.length === 0) return require_terminal_internal.serializeTokens(programTokens, options.colors);
+	const width = programTokens.reduce((n, token) => token.width === -1 ? 0 : n + token.width, 0);
+	const separator = options.maxWidth != null && width + 1 + terms[0].width > options.maxWidth ? {
+		text: "\n",
+		width: -1,
+		scopes: []
+	} : {
+		text: " ",
+		width: 1,
+		scopes: []
+	};
+	return require_terminal_internal.serializeTokens([...programTokens, separator], options.colors) + wrapUsageTokens(terms, options, separator.width === -1 ? 0 : width + 1);
 }
 /**
 * Normalizes a usage description by flattening nested exclusive terms,
@@ -454,7 +453,8 @@ function* formatUsageTerms(terms, options) {
 	for (const t of terms) {
 		if (i > 0) yield {
 			text: " ",
-			width: 1
+			width: 1,
+			scopes: []
 		};
 		yield* formatUsageTermInternal(t, options);
 		i++;
@@ -468,141 +468,117 @@ function* formatUsageTerms(terms, options) {
 * @param options Optional formatting options to customize the output.
 *                See {@link UsageTermFormatOptions} for available options.
 * @returns A formatted string representation of the usage term.
+* @throws {RangeError} If a theme supplies an invalid RGB channel or palette
+*                      index, even when colors are disabled.
 */
 function formatUsageTerm(term, options = {}) {
+	options = {
+		...options,
+		theme: require_terminal_internal.cacheTerminalTheme(options.theme)
+	};
 	const hiddenCheck = options.context === "doc" ? isDocHidden : isUsageHidden;
 	const visibleTerms = filterUsageForDisplay([term], hiddenCheck);
 	if (visibleTerms.length < 1) return "";
-	let lineWidth = 0;
-	let output = "";
-	for (const { text, width } of formatUsageTermInternal(visibleTerms[0], options)) {
-		if (options.maxWidth != null && lineWidth > 0 && lineWidth + width > options.maxWidth) {
-			if (output.endsWith(" ")) output = output.slice(0, -1);
-			output += "\n";
+	return wrapUsageTokens(formatUsageTermInternal(visibleTerms[0], options), options);
+}
+function wrapUsageTokens(input, options, initialWidth = 0) {
+	return require_terminal_internal.serializeTokens(layoutUsageTokens(input, options, initialWidth), options.colors);
+}
+function layoutUsageTokens(input, options, initialWidth = 0) {
+	let lineWidth = initialWidth;
+	const output = [];
+	for (const token of input) {
+		if (options.maxWidth != null && lineWidth > 0 && lineWidth + token.width > options.maxWidth) {
+			const last = output.at(-1);
+			if (last?.text.endsWith(" ") && (!options.colors || last.scopes.length === 0)) output[output.length - 1] = {
+				...last,
+				text: last.text.slice(0, -1),
+				width: last.width - 1
+			};
+			output.push({
+				text: "\n",
+				width: -1,
+				scopes: []
+			});
 			lineWidth = 0;
-			if (text === " ") continue;
+			if (token.text === " ") continue;
 		}
-		output += text;
-		lineWidth += width;
+		output.push(token);
+		lineWidth += token.width;
 	}
 	return output;
 }
 function* formatUsageTermInternal(term, options) {
-	const optionsSeparator = options.optionsSeparator ?? "/";
-	if (term.type === "argument") yield {
-		text: options?.colors ? `\x1b[4m${term.metavar}\x1b[0m` : term.metavar,
-		width: require_displaywidth.getDisplayWidth(term.metavar)
+	function leaf(t, usage) {
+		return require_terminal_internal.fragmentTokens(require_terminal_internal.formatTerminalTerm(t, options.theme, false, usage));
+	}
+	function punctuation(punctuation$1, kind) {
+		return leaf({
+			type: "syntaxPunctuation",
+			punctuation: punctuation$1,
+			kind
+		});
+	}
+	const space = {
+		text: " ",
+		width: 1,
+		scopes: []
 	};
-	else if (term.type === "option") if (options?.onlyShortestOptions) {
-		const shortestName = term.names.reduce((a, b) => require_displaywidth.getDisplayWidth(a) <= require_displaywidth.getDisplayWidth(b) ? a : b);
-		yield {
-			text: options?.colors ? `\x1b[3m${shortestName}\x1b[0m` : shortestName,
-			width: require_displaywidth.getDisplayWidth(shortestName)
-		};
-	} else {
-		let i = 0;
-		for (const optionName of term.names) {
-			if (i > 0) yield {
-				text: options?.colors ? `\x1b[2m${optionsSeparator}\x1b[0m` : optionsSeparator,
-				width: require_displaywidth.getDisplayWidth(optionsSeparator)
-			};
-			yield {
-				text: options?.colors ? `\x1b[3m${optionName}\x1b[0m` : optionName,
-				width: require_displaywidth.getDisplayWidth(optionName)
-			};
-			i++;
+	if (term.type === "argument") yield* leaf({
+		type: "metavar",
+		metavar: term.metavar
+	}, "argument");
+	else if (term.type === "option") {
+		const names = options.onlyShortestOptions ? [term.names.reduce((a, b) => require_displaywidth.getDisplayWidth(a) <= require_displaywidth.getDisplayWidth(b) ? a : b)] : term.names;
+		for (let i = 0; i < names.length; i++) {
+			if (i > 0) yield* punctuation(options.optionsSeparator ?? "/", "optionSeparator");
+			yield* leaf({
+				type: "optionName",
+				optionName: names[i]
+			});
 		}
-		if (term.metavar != null) {
-			yield {
-				text: " ",
-				width: 1
-			};
-			yield {
-				text: options?.colors ? `\x1b[4m\x1b[2m${term.metavar}\x1b[0m` : term.metavar,
-				width: require_displaywidth.getDisplayWidth(term.metavar)
-			};
+		if (!options.onlyShortestOptions && term.metavar != null) {
+			yield space;
+			yield* leaf({
+				type: "metavar",
+				metavar: term.metavar
+			}, "optionValue");
 		}
-	}
-	else if (term.type === "command") yield {
-		text: options?.colors ? `\x1b[1m${term.name}\x1b[0m` : term.name,
-		width: require_displaywidth.getDisplayWidth(term.name)
-	};
+	} else if (term.type === "command") yield* leaf({
+		type: "optionName",
+		optionName: term.name
+	}, "command");
 	else if (term.type === "optional") {
-		yield {
-			text: options?.colors ? `\x1b[2m[\x1b[0m` : "[",
-			width: 1
-		};
+		yield* punctuation("[", "optionalOpen");
 		yield* formatUsageTerms(term.terms, options);
-		yield {
-			text: options?.colors ? `\x1b[2m]\x1b[0m` : "]",
-			width: 1
-		};
+		yield* punctuation("]", "optionalClose");
 	} else if (term.type === "exclusive") {
-		yield {
-			text: options?.colors ? `\x1b[2m(\x1b[0m` : "(",
-			width: 1
-		};
-		let i = 0;
-		for (const termGroup of term.terms) {
+		yield* punctuation("(", "groupOpen");
+		for (let i = 0; i < term.terms.length; i++) {
 			if (i > 0) {
-				yield {
-					text: " ",
-					width: 1
-				};
-				yield {
-					text: "|",
-					width: 1
-				};
-				yield {
-					text: " ",
-					width: 1
-				};
+				yield space;
+				yield* punctuation("|", "alternative");
+				yield space;
 			}
-			yield* formatUsageTerms(termGroup, options);
-			i++;
+			yield* formatUsageTerms(term.terms[i], options);
 		}
-		yield {
-			text: options?.colors ? `\x1b[2m)\x1b[0m` : ")",
-			width: 1
-		};
+		yield* punctuation(")", "groupClose");
 	} else if (term.type === "sequence") yield* formatUsageTerms(term.terms, options);
 	else if (term.type === "multiple") {
-		if (term.min < 1) yield {
-			text: options?.colors ? `\x1b[2m[\x1b[0m` : "[",
-			width: 1
-		};
+		if (term.min < 1) yield* punctuation("[", "optionalOpen");
 		for (let i = 0; i < Math.max(1, term.min); i++) {
-			if (i > 0) yield {
-				text: " ",
-				width: 1
-			};
+			if (i > 0) yield space;
 			yield* formatUsageTerms(term.terms, options);
 		}
-		yield {
-			text: options?.colors ? `\x1b[2m...\x1b[0m` : "...",
-			width: 3
-		};
-		if (term.min < 1) yield {
-			text: options?.colors ? `\x1b[2m]\x1b[0m` : "]",
-			width: 1
-		};
-	} else if (term.type === "literal") yield {
-		text: term.value,
-		width: require_displaywidth.getDisplayWidth(term.value)
-	};
-	else if (term.type === "passthrough") {
-		const text = "[...]";
-		yield {
-			text: options?.colors ? `\x1b[2m${text}\x1b[0m` : text,
-			width: 5
-		};
-	} else if (term.type === "ellipsis") {
-		const text = "...";
-		yield {
-			text: options?.colors ? `\x1b[2m${text}\x1b[0m` : text,
-			width: 3
-		};
-	} else throw new TypeError(`Unknown usage term type: ${term["type"]}.`);
+		yield* punctuation("...", "ellipsis");
+		if (term.min < 1) yield* punctuation("]", "optionalClose");
+	} else if (term.type === "literal") yield* leaf({
+		type: "value",
+		value: term.value
+	}, "literal");
+	else if (term.type === "passthrough") yield* punctuation("[...]", "passthrough");
+	else if (term.type === "ellipsis") yield* punctuation("...", "ellipsis");
+	else throw new TypeError(`Unknown usage term type: ${term["type"]}.`);
 }
 
 //#endregion

package/dist/usage.d.cts

@@ -1,4 +1,5 @@
 import { NonEmptyString } from "./nonempty.cjs";
+import { TerminalTheme } from "./terminal.cjs";
 
 //#region src/usage.d.ts
 
@@ -340,6 +341,11 @@ declare function extractArgumentMetavars(usage: Usage): Set<string>;
  * Options for formatting usage descriptions.
  */
 interface UsageFormatOptions {
+  /**
+   * Semantic terminal theme.
+   * @since 1.3.0
+   */
+  readonly theme?: TerminalTheme;
   /**
    * When `true`, expands commands in the usage description
    * to multiple lines, showing each command on a new line.
@@ -477,6 +483,8 @@ interface UsageTermFormatOptions extends UsageFormatOptions {
  * @param options Optional formatting options to customize the output.
  *                See {@link UsageTermFormatOptions} for available options.
  * @returns A formatted string representation of the usage term.
+ * @throws {RangeError} If a theme supplies an invalid RGB channel or palette
+ *                      index, even when colors are disabled.
  */
 declare function formatUsageTerm(term: UsageTerm, options?: UsageTermFormatOptions): string;
 //#endregion

package/dist/usage.d.ts

@@ -1,4 +1,5 @@
 import { NonEmptyString } from "./nonempty.js";
+import { TerminalTheme } from "./terminal.js";
 
 //#region src/usage.d.ts
 
@@ -340,6 +341,11 @@ declare function extractArgumentMetavars(usage: Usage): Set<string>;
  * Options for formatting usage descriptions.
  */
 interface UsageFormatOptions {
+  /**
+   * Semantic terminal theme.
+   * @since 1.3.0
+   */
+  readonly theme?: TerminalTheme;
   /**
    * When `true`, expands commands in the usage description
    * to multiple lines, showing each command on a new line.
@@ -477,6 +483,8 @@ interface UsageTermFormatOptions extends UsageFormatOptions {
  * @param options Optional formatting options to customize the output.
  *                See {@link UsageTermFormatOptions} for available options.
  * @returns A formatted string representation of the usage term.
+ * @throws {RangeError} If a theme supplies an invalid RGB channel or palette
+ *                      index, even when colors are disabled.
  */
 declare function formatUsageTerm(term: UsageTerm, options?: UsageTermFormatOptions): string;
 //#endregion

package/dist/usage.js

@@ -1,4 +1,5 @@
 import { getDisplayWidth } from "./displaywidth.js";
+import { cacheTerminalTheme, formatTerminalTerm, fragmentTokens, serializeTokens } from "./terminal-internal.js";
 import { validateProgramName } from "./validate.js";
 
 //#region src/usage.ts
@@ -182,6 +183,10 @@ function extractArgumentMetavars(usage) {
 *         whitespace-only, or contains control characters.
 */
 function formatUsage(programName, usage, options = {}) {
+	options = {
+		...options,
+		theme: cacheTerminalTheme(options.theme)
+	};
 	validateProgramName(programName);
 	usage = normalizeUsage(filterUsageForDisplay(usage));
 	if (options.expandCommands) {
@@ -197,29 +202,23 @@ function formatUsage(programName, usage, options = {}) {
 			if (lines.length > 0) return lines.join("\n");
 		}
 	}
-	let output = options.colors ? `\x1b[1m${programName}\x1b[0m` : programName;
-	let lineWidth = getDisplayWidth(programName);
-	let first = true;
-	for (const { text, width } of formatUsageTerms(usage, options)) {
-		if (first) {
-			first = false;
-			if (options.maxWidth != null && lineWidth + 1 + width > options.maxWidth) {
-				output += "\n";
-				lineWidth = 0;
-			} else {
-				output += " ";
-				lineWidth += 1;
-			}
-		} else if (options.maxWidth != null && lineWidth > 0 && lineWidth + width > options.maxWidth) {
-			if (output.endsWith(" ")) output = output.slice(0, -1);
-			output += "\n";
-			lineWidth = 0;
-			if (text === " ") continue;
-		}
-		output += text;
-		lineWidth += width;
-	}
-	return output;
+	const programTokens = layoutUsageTokens(fragmentTokens(formatTerminalTerm({
+		type: "programName",
+		programName
+	}, options.theme)), options);
+	const terms = [...formatUsageTerms(usage, options)];
+	if (terms.length === 0) return serializeTokens(programTokens, options.colors);
+	const width = programTokens.reduce((n, token) => token.width === -1 ? 0 : n + token.width, 0);
+	const separator = options.maxWidth != null && width + 1 + terms[0].width > options.maxWidth ? {
+		text: "\n",
+		width: -1,
+		scopes: []
+	} : {
+		text: " ",
+		width: 1,
+		scopes: []
+	};
+	return serializeTokens([...programTokens, separator], options.colors) + wrapUsageTokens(terms, options, separator.width === -1 ? 0 : width + 1);
 }
 /**
 * Normalizes a usage description by flattening nested exclusive terms,
@@ -454,7 +453,8 @@ function* formatUsageTerms(terms, options) {
 	for (const t of terms) {
 		if (i > 0) yield {
 			text: " ",
-			width: 1
+			width: 1,
+			scopes: []
 		};
 		yield* formatUsageTermInternal(t, options);
 		i++;
@@ -468,141 +468,117 @@ function* formatUsageTerms(terms, options) {
 * @param options Optional formatting options to customize the output.
 *                See {@link UsageTermFormatOptions} for available options.
 * @returns A formatted string representation of the usage term.
+* @throws {RangeError} If a theme supplies an invalid RGB channel or palette
+*                      index, even when colors are disabled.
 */
 function formatUsageTerm(term, options = {}) {
+	options = {
+		...options,
+		theme: cacheTerminalTheme(options.theme)
+	};
 	const hiddenCheck = options.context === "doc" ? isDocHidden : isUsageHidden;
 	const visibleTerms = filterUsageForDisplay([term], hiddenCheck);
 	if (visibleTerms.length < 1) return "";
-	let lineWidth = 0;
-	let output = "";
-	for (const { text, width } of formatUsageTermInternal(visibleTerms[0], options)) {
-		if (options.maxWidth != null && lineWidth > 0 && lineWidth + width > options.maxWidth) {
-			if (output.endsWith(" ")) output = output.slice(0, -1);
-			output += "\n";
+	return wrapUsageTokens(formatUsageTermInternal(visibleTerms[0], options), options);
+}
+function wrapUsageTokens(input, options, initialWidth = 0) {
+	return serializeTokens(layoutUsageTokens(input, options, initialWidth), options.colors);
+}
+function layoutUsageTokens(input, options, initialWidth = 0) {
+	let lineWidth = initialWidth;
+	const output = [];
+	for (const token of input) {
+		if (options.maxWidth != null && lineWidth > 0 && lineWidth + token.width > options.maxWidth) {
+			const last = output.at(-1);
+			if (last?.text.endsWith(" ") && (!options.colors || last.scopes.length === 0)) output[output.length - 1] = {
+				...last,
+				text: last.text.slice(0, -1),
+				width: last.width - 1
+			};
+			output.push({
+				text: "\n",
+				width: -1,
+				scopes: []
+			});
 			lineWidth = 0;
-			if (text === " ") continue;
+			if (token.text === " ") continue;
 		}
-		output += text;
-		lineWidth += width;
+		output.push(token);
+		lineWidth += token.width;
 	}
 	return output;
 }
 function* formatUsageTermInternal(term, options) {
-	const optionsSeparator = options.optionsSeparator ?? "/";
-	if (term.type === "argument") yield {
-		text: options?.colors ? `\x1b[4m${term.metavar}\x1b[0m` : term.metavar,
-		width: getDisplayWidth(term.metavar)
+	function leaf(t, usage) {
+		return fragmentTokens(formatTerminalTerm(t, options.theme, false, usage));
+	}
+	function punctuation(punctuation$1, kind) {
+		return leaf({
+			type: "syntaxPunctuation",
+			punctuation: punctuation$1,
+			kind
+		});
+	}
+	const space = {
+		text: " ",
+		width: 1,
+		scopes: []
 	};
-	else if (term.type === "option") if (options?.onlyShortestOptions) {
-		const shortestName = term.names.reduce((a, b) => getDisplayWidth(a) <= getDisplayWidth(b) ? a : b);
-		yield {
-			text: options?.colors ? `\x1b[3m${shortestName}\x1b[0m` : shortestName,
-			width: getDisplayWidth(shortestName)
-		};
-	} else {
-		let i = 0;
-		for (const optionName of term.names) {
-			if (i > 0) yield {
-				text: options?.colors ? `\x1b[2m${optionsSeparator}\x1b[0m` : optionsSeparator,
-				width: getDisplayWidth(optionsSeparator)
-			};
-			yield {
-				text: options?.colors ? `\x1b[3m${optionName}\x1b[0m` : optionName,
-				width: getDisplayWidth(optionName)
-			};
-			i++;
+	if (term.type === "argument") yield* leaf({
+		type: "metavar",
+		metavar: term.metavar
+	}, "argument");
+	else if (term.type === "option") {
+		const names = options.onlyShortestOptions ? [term.names.reduce((a, b) => getDisplayWidth(a) <= getDisplayWidth(b) ? a : b)] : term.names;
+		for (let i = 0; i < names.length; i++) {
+			if (i > 0) yield* punctuation(options.optionsSeparator ?? "/", "optionSeparator");
+			yield* leaf({
+				type: "optionName",
+				optionName: names[i]
+			});
 		}
-		if (term.metavar != null) {
-			yield {
-				text: " ",
-				width: 1
-			};
-			yield {
-				text: options?.colors ? `\x1b[4m\x1b[2m${term.metavar}\x1b[0m` : term.metavar,
-				width: getDisplayWidth(term.metavar)
-			};
+		if (!options.onlyShortestOptions && term.metavar != null) {
+			yield space;
+			yield* leaf({
+				type: "metavar",
+				metavar: term.metavar
+			}, "optionValue");
 		}
-	}
-	else if (term.type === "command") yield {
-		text: options?.colors ? `\x1b[1m${term.name}\x1b[0m` : term.name,
-		width: getDisplayWidth(term.name)
-	};
+	} else if (term.type === "command") yield* leaf({
+		type: "optionName",
+		optionName: term.name
+	}, "command");
 	else if (term.type === "optional") {
-		yield {
-			text: options?.colors ? `\x1b[2m[\x1b[0m` : "[",
-			width: 1
-		};
+		yield* punctuation("[", "optionalOpen");
 		yield* formatUsageTerms(term.terms, options);
-		yield {
-			text: options?.colors ? `\x1b[2m]\x1b[0m` : "]",
-			width: 1
-		};
+		yield* punctuation("]", "optionalClose");
 	} else if (term.type === "exclusive") {
-		yield {
-			text: options?.colors ? `\x1b[2m(\x1b[0m` : "(",
-			width: 1
-		};
-		let i = 0;
-		for (const termGroup of term.terms) {
+		yield* punctuation("(", "groupOpen");
+		for (let i = 0; i < term.terms.length; i++) {
 			if (i > 0) {
-				yield {
-					text: " ",
-					width: 1
-				};
-				yield {
-					text: "|",
-					width: 1
-				};
-				yield {
-					text: " ",
-					width: 1
-				};
+				yield space;
+				yield* punctuation("|", "alternative");
+				yield space;
 			}
-			yield* formatUsageTerms(termGroup, options);
-			i++;
+			yield* formatUsageTerms(term.terms[i], options);
 		}
-		yield {
-			text: options?.colors ? `\x1b[2m)\x1b[0m` : ")",
-			width: 1
-		};
+		yield* punctuation(")", "groupClose");
 	} else if (term.type === "sequence") yield* formatUsageTerms(term.terms, options);
 	else if (term.type === "multiple") {
-		if (term.min < 1) yield {
-			text: options?.colors ? `\x1b[2m[\x1b[0m` : "[",
-			width: 1
-		};
+		if (term.min < 1) yield* punctuation("[", "optionalOpen");
 		for (let i = 0; i < Math.max(1, term.min); i++) {
-			if (i > 0) yield {
-				text: " ",
-				width: 1
-			};
+			if (i > 0) yield space;
 			yield* formatUsageTerms(term.terms, options);
 		}
-		yield {
-			text: options?.colors ? `\x1b[2m...\x1b[0m` : "...",
-			width: 3
-		};
-		if (term.min < 1) yield {
-			text: options?.colors ? `\x1b[2m]\x1b[0m` : "]",
-			width: 1
-		};
-	} else if (term.type === "literal") yield {
-		text: term.value,
-		width: getDisplayWidth(term.value)
-	};
-	else if (term.type === "passthrough") {
-		const text = "[...]";
-		yield {
-			text: options?.colors ? `\x1b[2m${text}\x1b[0m` : text,
-			width: 5
-		};
-	} else if (term.type === "ellipsis") {
-		const text = "...";
-		yield {
-			text: options?.colors ? `\x1b[2m${text}\x1b[0m` : text,
-			width: 3
-		};
-	} else throw new TypeError(`Unknown usage term type: ${term["type"]}.`);
+		yield* punctuation("...", "ellipsis");
+		if (term.min < 1) yield* punctuation("]", "optionalClose");
+	} else if (term.type === "literal") yield* leaf({
+		type: "value",
+		value: term.value
+	}, "literal");
+	else if (term.type === "passthrough") yield* punctuation("[...]", "passthrough");
+	else if (term.type === "ellipsis") yield* punctuation("...", "ellipsis");
+	else throw new TypeError(`Unknown usage term type: ${term["type"]}.`);
 }
 
 //#endregion