@optique/core 1.0.0-dev.1467 → 1.0.0-dev.1484

package/dist/doc.cjs

@@ -1,4 +1,5 @@
 const require_message = require('./message.cjs');
+const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
 
 //#region src/doc.ts
@@ -182,9 +183,10 @@ function defaultSectionOrder(a, b) {
 * @param page The documentation page to format
 * @param options Formatting options to customize the output
 * @returns A formatted string representation of the documentation page
-* @throws {TypeError} If `programName` contains a CR or LF character, if
-* any non-empty section's title is empty, whitespace-only, or contains a CR
-* or LF character, or if `maxWidth` is not a finite integer.
+* @throws {TypeError} If `programName` is not a string, is empty,
+* whitespace-only, or contains control characters, if any non-empty
+* section's title is empty, whitespace-only, or contains a CR or LF
+* character, or if `maxWidth` is not a finite integer.
 * @throws {RangeError} If any entry needs a description column and `maxWidth`
 * is too small to fit the minimum layout (less than `termIndent + 4`), or if
 * `showChoices.maxItems` is less than `1`.
@@ -208,7 +210,7 @@ function defaultSectionOrder(a, b) {
 * ```
 */
 function formatDocPage(programName, page, options = {}) {
-	if (/[\r\n]/.test(programName)) throw new TypeError("Program name must not contain newlines.");
+	require_validate.validateProgramName(programName);
 	const termIndent = options.termIndent ?? 2;
 	const termWidth = options.termWidth ?? 26;
 	if (options.maxWidth != null && (!Number.isFinite(options.maxWidth) || !Number.isInteger(options.maxWidth))) throw new TypeError(`maxWidth must be a finite integer, got ${options.maxWidth}.`);
@@ -246,7 +248,7 @@ function formatDocPage(programName, page, options = {}) {
 		const splitEntryMin = termIndent + 2 + Math.max(2, 2 * minDescWidth - 1);
 		const fixedEntryMin = termIndent + 2 + termWidth + minDescWidth;
 		const entryMin = needsDescColumn ? Math.min(splitEntryMin, fixedEntryMin) : hasEntries ? termIndent + 1 : 1;
-		const usageMin = page.usage != null ? 8 + programName.length : 1;
+		const usageMin = page.usage != null ? 7 + Math.max(programName.length, Math.min(maxVisibleAtomicWidth(page.usage), programName.length + 7)) : 1;
 		let sectionMin = 1;
 		if (page.examples != null) sectionMin = Math.max(sectionMin, 9);
 		if (page.author != null) sectionMin = Math.max(sectionMin, 7);
@@ -449,6 +451,54 @@ function formatDocPage(programName, page, options = {}) {
 function indentLines(text$1, indent) {
 	return text$1.split("\n").join("\n" + " ".repeat(indent));
 }
+/**
+* Returns the width of the widest non-breakable segment among visible
+* (non-usage-hidden) terms in a usage tree.  Hidden terms are excluded
+* because they are filtered out before rendering, so they do not
+* contribute to the rendered width.
+*/
+function maxVisibleAtomicWidth(usage) {
+	let max = 0;
+	for (const term of usage) switch (term.type) {
+		case "argument":
+			if (!require_usage.isUsageHidden(term.hidden)) max = Math.max(max, term.metavar.length);
+			break;
+		case "option":
+			if (!require_usage.isUsageHidden(term.hidden) && term.names.length > 0) {
+				for (const name of term.names) max = Math.max(max, name.length);
+				if (term.metavar != null) max = Math.max(max, term.metavar.length);
+			}
+			break;
+		case "command":
+			if (!require_usage.isUsageHidden(term.hidden)) max = Math.max(max, term.name.length);
+			break;
+		case "passthrough":
+			if (!require_usage.isUsageHidden(term.hidden)) max = Math.max(max, 5);
+			break;
+		case "optional":
+			max = Math.max(max, maxVisibleAtomicWidth(term.terms));
+			break;
+		case "multiple": {
+			const innerMax = maxVisibleAtomicWidth(term.terms);
+			if (innerMax > 0) max = Math.max(max, 3, innerMax);
+			break;
+		}
+		case "exclusive":
+			for (const branch of term.terms) {
+				const first = branch[0];
+				if (first?.type === "command" && require_usage.isUsageHidden(first.hidden)) continue;
+				max = Math.max(max, maxVisibleAtomicWidth(branch));
+			}
+			break;
+		case "literal":
+			if (term.value !== "") max = Math.max(max, term.value.length);
+			break;
+		case "ellipsis":
+			max = Math.max(max, 3);
+			break;
+	}
+	return max;
+}
 const ansiEscapeCodeRegex = /\x1B\[[0-9;]*[a-zA-Z]/g;
 function ansiAwareRightPad(text$1, length, char = " ") {
 	const strippedText = text$1.replace(ansiEscapeCodeRegex, "");

package/dist/doc.d.cts

@@ -311,9 +311,10 @@ interface DocPageFormatOptions {
  * @param page The documentation page to format
  * @param options Formatting options to customize the output
  * @returns A formatted string representation of the documentation page
- * @throws {TypeError} If `programName` contains a CR or LF character, if
- * any non-empty section's title is empty, whitespace-only, or contains a CR
- * or LF character, or if `maxWidth` is not a finite integer.
+ * @throws {TypeError} If `programName` is not a string, is empty,
+ * whitespace-only, or contains control characters, if any non-empty
+ * section's title is empty, whitespace-only, or contains a CR or LF
+ * character, or if `maxWidth` is not a finite integer.
  * @throws {RangeError} If any entry needs a description column and `maxWidth`
  * is too small to fit the minimum layout (less than `termIndent + 4`), or if
  * `showChoices.maxItems` is less than `1`.

package/dist/doc.d.ts

@@ -311,9 +311,10 @@ interface DocPageFormatOptions {
  * @param page The documentation page to format
  * @param options Formatting options to customize the output
  * @returns A formatted string representation of the documentation page
- * @throws {TypeError} If `programName` contains a CR or LF character, if
- * any non-empty section's title is empty, whitespace-only, or contains a CR
- * or LF character, or if `maxWidth` is not a finite integer.
+ * @throws {TypeError} If `programName` is not a string, is empty,
+ * whitespace-only, or contains control characters, if any non-empty
+ * section's title is empty, whitespace-only, or contains a CR or LF
+ * character, or if `maxWidth` is not a finite integer.
  * @throws {RangeError} If any entry needs a description column and `maxWidth`
  * is too small to fit the minimum layout (less than `termIndent + 4`), or if
  * `showChoices.maxItems` is less than `1`.

package/dist/doc.js

@@ -1,5 +1,6 @@
 import { cloneMessage, formatMessage, text } from "./message.js";
-import { cloneUsageTerm, formatUsage, formatUsageTerm, isDocHidden } from "./usage.js";
+import { validateProgramName } from "./validate.js";
+import { cloneUsageTerm, formatUsage, formatUsageTerm, isDocHidden, isUsageHidden } from "./usage.js";
 
 //#region src/doc.ts
 /**
@@ -182,9 +183,10 @@ function defaultSectionOrder(a, b) {
 * @param page The documentation page to format
 * @param options Formatting options to customize the output
 * @returns A formatted string representation of the documentation page
-* @throws {TypeError} If `programName` contains a CR or LF character, if
-* any non-empty section's title is empty, whitespace-only, or contains a CR
-* or LF character, or if `maxWidth` is not a finite integer.
+* @throws {TypeError} If `programName` is not a string, is empty,
+* whitespace-only, or contains control characters, if any non-empty
+* section's title is empty, whitespace-only, or contains a CR or LF
+* character, or if `maxWidth` is not a finite integer.
 * @throws {RangeError} If any entry needs a description column and `maxWidth`
 * is too small to fit the minimum layout (less than `termIndent + 4`), or if
 * `showChoices.maxItems` is less than `1`.
@@ -208,7 +210,7 @@ function defaultSectionOrder(a, b) {
 * ```
 */
 function formatDocPage(programName, page, options = {}) {
-	if (/[\r\n]/.test(programName)) throw new TypeError("Program name must not contain newlines.");
+	validateProgramName(programName);
 	const termIndent = options.termIndent ?? 2;
 	const termWidth = options.termWidth ?? 26;
 	if (options.maxWidth != null && (!Number.isFinite(options.maxWidth) || !Number.isInteger(options.maxWidth))) throw new TypeError(`maxWidth must be a finite integer, got ${options.maxWidth}.`);
@@ -246,7 +248,7 @@ function formatDocPage(programName, page, options = {}) {
 		const splitEntryMin = termIndent + 2 + Math.max(2, 2 * minDescWidth - 1);
 		const fixedEntryMin = termIndent + 2 + termWidth + minDescWidth;
 		const entryMin = needsDescColumn ? Math.min(splitEntryMin, fixedEntryMin) : hasEntries ? termIndent + 1 : 1;
-		const usageMin = page.usage != null ? 8 + programName.length : 1;
+		const usageMin = page.usage != null ? 7 + Math.max(programName.length, Math.min(maxVisibleAtomicWidth(page.usage), programName.length + 7)) : 1;
 		let sectionMin = 1;
 		if (page.examples != null) sectionMin = Math.max(sectionMin, 9);
 		if (page.author != null) sectionMin = Math.max(sectionMin, 7);
@@ -449,6 +451,54 @@ function formatDocPage(programName, page, options = {}) {
 function indentLines(text$1, indent) {
 	return text$1.split("\n").join("\n" + " ".repeat(indent));
 }
+/**
+* Returns the width of the widest non-breakable segment among visible
+* (non-usage-hidden) terms in a usage tree.  Hidden terms are excluded
+* because they are filtered out before rendering, so they do not
+* contribute to the rendered width.
+*/
+function maxVisibleAtomicWidth(usage) {
+	let max = 0;
+	for (const term of usage) switch (term.type) {
+		case "argument":
+			if (!isUsageHidden(term.hidden)) max = Math.max(max, term.metavar.length);
+			break;
+		case "option":
+			if (!isUsageHidden(term.hidden) && term.names.length > 0) {
+				for (const name of term.names) max = Math.max(max, name.length);
+				if (term.metavar != null) max = Math.max(max, term.metavar.length);
+			}
+			break;
+		case "command":
+			if (!isUsageHidden(term.hidden)) max = Math.max(max, term.name.length);
+			break;
+		case "passthrough":
+			if (!isUsageHidden(term.hidden)) max = Math.max(max, 5);
+			break;
+		case "optional":
+			max = Math.max(max, maxVisibleAtomicWidth(term.terms));
+			break;
+		case "multiple": {
+			const innerMax = maxVisibleAtomicWidth(term.terms);
+			if (innerMax > 0) max = Math.max(max, 3, innerMax);
+			break;
+		}
+		case "exclusive":
+			for (const branch of term.terms) {
+				const first = branch[0];
+				if (first?.type === "command" && isUsageHidden(first.hidden)) continue;
+				max = Math.max(max, maxVisibleAtomicWidth(branch));
+			}
+			break;
+		case "literal":
+			if (term.value !== "") max = Math.max(max, term.value.length);
+			break;
+		case "ellipsis":
+			max = Math.max(max, 3);
+			break;
+	}
+	return max;
+}
 const ansiEscapeCodeRegex = /\x1B\[[0-9;]*[a-zA-Z]/g;
 function ansiAwareRightPad(text$1, length, char = " ") {
 	const strippedText = text$1.replace(ansiEscapeCodeRegex, "");

package/dist/facade.cjs

@@ -2,12 +2,12 @@ const require_annotations = require('./annotations.cjs');
 const require_message = require('./message.cjs');
 const require_completion = require('./completion.cjs');
 const require_mode_dispatch = require('./mode-dispatch.cjs');
+const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
 const require_doc = require('./doc.cjs');
 const require_constructs = require('./constructs.cjs');
 const require_context = require('./context.cjs');
 const require_modifiers = require('./modifiers.cjs');
-const require_validate = require('./validate.cjs');
 const require_valueparser = require('./valueparser.cjs');
 const require_primitives = require('./primitives.cjs');
 const require_parser = require('./parser.cjs');

package/dist/facade.js

@@ -2,12 +2,12 @@ import { injectAnnotations } from "./annotations.js";
 import { commandLine, formatMessage, lineBreak, message, optionName, text, value } from "./message.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { dispatchByMode } from "./mode-dispatch.js";
+import { validateCommandNames, validateOptionNames } from "./validate.js";
 import { formatUsage } from "./usage.js";
 import { formatDocPage } from "./doc.js";
 import { group, longestMatch, object } from "./constructs.js";
 import { isPlaceholderValue } from "./context.js";
 import { multiple, optional, withDefault } from "./modifiers.js";
-import { validateCommandNames, validateOptionNames } from "./validate.js";
 import { string } from "./valueparser.js";
 import { argument, command, constant, flag, option } from "./primitives.js";
 import { getDocPage, parseAsync, parseSync, suggest, suggestAsync } from "./parser.js";

package/dist/primitives.cjs

@@ -2,10 +2,10 @@ const require_annotations = require('./annotations.cjs');
 const require_message = require('./message.cjs');
 const require_dependency = require('./dependency.cjs');
 const require_mode_dispatch = require('./mode-dispatch.cjs');
+const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
 const require_suggestion = require('./suggestion.cjs');
 const require_usage_internals = require('./usage-internals.cjs');
-const require_validate = require('./validate.cjs');
 const require_valueparser = require('./valueparser.cjs');
 
 //#region src/primitives.ts

package/dist/primitives.js

@@ -2,10 +2,10 @@ import { annotateFreshArray, getAnnotations } from "./annotations.js";
 import { message, metavar, optionName, optionNames, text, valueSet } from "./message.js";
 import { createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, dependencyId, getDefaultValuesFunction, getDependencyIds, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, suggestWithDependency } from "./dependency.js";
 import { dispatchIterableByMode } from "./mode-dispatch.js";
+import { validateOptionNames } from "./validate.js";
 import { extractOptionNames, isDocHidden, isSuggestionHidden } from "./usage.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, findSimilar } from "./suggestion.js";
 import { extractLeadingCommandNames } from "./usage-internals.js";
-import { validateOptionNames } from "./validate.js";
 import { isValueParser } from "./valueparser.js";
 
 //#region src/primitives.ts

package/dist/usage.cjs

@@ -1,3 +1,4 @@
+const require_validate = require('./validate.cjs');
 
 //#region src/usage.ts
 /**
@@ -147,8 +148,11 @@ function extractArgumentMetavars(usage) {
 * @param options Optional formatting options to customize the output.
 *                See {@link UsageFormatOptions} for available options.
 * @returns A formatted string representation of the usage description.
+* @throws {TypeError} If `programName` is not a string, is empty,
+*         whitespace-only, or contains control characters.
 */
 function formatUsage(programName, usage, options = {}) {
+	require_validate.validateProgramName(programName);
 	usage = normalizeUsage(filterUsageForDisplay(usage));
 	if (options.expandCommands) {
 		const lastTerm = usage.at(-1);
@@ -160,13 +164,24 @@ function formatUsage(programName, usage, options = {}) {
 				if (usage.length > 1) command = [...usage.slice(0, -1), ...command];
 				lines.push(formatUsage(programName, command, options));
 			}
-			return lines.join("\n");
+			if (lines.length > 0) return lines.join("\n");
 		}
 	}
-	let output = options.colors ? `\x1b[1m${programName}\x1b[0m ` : `${programName} `;
-	let lineWidth = programName.length + 1;
+	let output = options.colors ? `\x1b[1m${programName}\x1b[0m` : programName;
+	let lineWidth = programName.length;
+	let first = true;
 	for (const { text, width } of formatUsageTerms(usage, options)) {
-		if (options.maxWidth != null && lineWidth + width > options.maxWidth) {
+		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 + width > options.maxWidth) {
+			if (output.endsWith(" ")) output = output.slice(0, -1);
 			output += "\n";
 			lineWidth = 0;
 			if (text === " ") continue;
@@ -404,6 +419,7 @@ function formatUsageTerm(term, options = {}) {
 	let output = "";
 	for (const { text, width } of formatUsageTermInternal(visibleTerms[0], options)) {
 		if (options.maxWidth != null && lineWidth + width > options.maxWidth) {
+			if (output.endsWith(" ")) output = output.slice(0, -1);
 			output += "\n";
 			lineWidth = 0;
 			if (text === " ") continue;

package/dist/usage.d.cts

@@ -325,6 +325,8 @@ interface UsageFormatOptions {
  * @param options Optional formatting options to customize the output.
  *                See {@link UsageFormatOptions} for available options.
  * @returns A formatted string representation of the usage description.
+ * @throws {TypeError} If `programName` is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  */
 declare function formatUsage(programName: string, usage: Usage, options?: UsageFormatOptions): string;
 /**

package/dist/usage.d.ts

@@ -325,6 +325,8 @@ interface UsageFormatOptions {
  * @param options Optional formatting options to customize the output.
  *                See {@link UsageFormatOptions} for available options.
  * @returns A formatted string representation of the usage description.
+ * @throws {TypeError} If `programName` is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  */
 declare function formatUsage(programName: string, usage: Usage, options?: UsageFormatOptions): string;
 /**

package/dist/usage.js

@@ -1,3 +1,5 @@
+import { validateProgramName } from "./validate.js";
+
 //#region src/usage.ts
 /**
 * Returns whether the term should be hidden from usage output.
@@ -146,8 +148,11 @@ function extractArgumentMetavars(usage) {
 * @param options Optional formatting options to customize the output.
 *                See {@link UsageFormatOptions} for available options.
 * @returns A formatted string representation of the usage description.
+* @throws {TypeError} If `programName` is not a string, is empty,
+*         whitespace-only, or contains control characters.
 */
 function formatUsage(programName, usage, options = {}) {
+	validateProgramName(programName);
 	usage = normalizeUsage(filterUsageForDisplay(usage));
 	if (options.expandCommands) {
 		const lastTerm = usage.at(-1);
@@ -159,13 +164,24 @@ function formatUsage(programName, usage, options = {}) {
 				if (usage.length > 1) command = [...usage.slice(0, -1), ...command];
 				lines.push(formatUsage(programName, command, options));
 			}
-			return lines.join("\n");
+			if (lines.length > 0) return lines.join("\n");
 		}
 	}
-	let output = options.colors ? `\x1b[1m${programName}\x1b[0m ` : `${programName} `;
-	let lineWidth = programName.length + 1;
+	let output = options.colors ? `\x1b[1m${programName}\x1b[0m` : programName;
+	let lineWidth = programName.length;
+	let first = true;
 	for (const { text, width } of formatUsageTerms(usage, options)) {
-		if (options.maxWidth != null && lineWidth + width > options.maxWidth) {
+		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 + width > options.maxWidth) {
+			if (output.endsWith(" ")) output = output.slice(0, -1);
 			output += "\n";
 			lineWidth = 0;
 			if (text === " ") continue;
@@ -403,6 +419,7 @@ function formatUsageTerm(term, options = {}) {
 	let output = "";
 	for (const { text, width } of formatUsageTermInternal(visibleTerms[0], options)) {
 		if (options.maxWidth != null && lineWidth + width > options.maxWidth) {
+			if (output.endsWith(" ")) output = output.slice(0, -1);
 			output += "\n";
 			lineWidth = 0;
 			if (text === " ") continue;

package/dist/validate.cjs

@@ -1,6 +1,12 @@
 
 //#region src/validate.ts
 /**
+* Matches Unicode control characters: C0 (U+0000–U+001F), DEL (U+007F),
+* C1 (U+0080–U+009F), and line separators (U+2028, U+2029).
+*/
+const CONTROL_CHAR_RE = /[\x00-\x1f\x7f-\x9f\u2028\u2029]/;
+const CONTROL_CHAR_RE_GLOBAL = new RegExp(CONTROL_CHAR_RE.source, "g");
+/**
 * Escapes control characters in a string for readable error messages.
 *
 * @param value The string to escape.
@@ -8,13 +14,13 @@
 *          sequences.
 */
 function escapeControlChars(value) {
-	return value.replace(/[\x00-\x1f\x7f]/g, (ch) => {
+	return value.replace(CONTROL_CHAR_RE_GLOBAL, (ch) => {
 		const code = ch.charCodeAt(0);
 		switch (code) {
 			case 9: return "\\t";
 			case 10: return "\\n";
 			case 13: return "\\r";
-			default: return `\\x${code.toString(16).padStart(2, "0")}`;
+			default: return code > 255 ? `\\u${code.toString(16).padStart(4, "0")}` : `\\x${code.toString(16).padStart(2, "0")}`;
 		}
 	});
 }
@@ -32,7 +38,7 @@ function validateOptionNames(names, label) {
 	for (const name of names) {
 		if (name === "") throw new TypeError(`${label} name must not be empty.`);
 		if (/^\s+$/.test(name)) throw new TypeError(`${label} name must not be whitespace-only: "${escapeControlChars(name)}".`);
-		if (/[\x00-\x1f\x7f]/.test(name)) throw new TypeError(`${label} name must not contain control characters: "${escapeControlChars(name)}".`);
+		if (CONTROL_CHAR_RE.test(name)) throw new TypeError(`${label} name must not contain control characters: "${escapeControlChars(name)}".`);
 		if (/\s/.test(name)) throw new TypeError(`${label} name must not contain whitespace: "${escapeControlChars(name)}".`);
 		if (!/^(--|[-/+])/.test(name)) throw new TypeError(`${label} name must start with "--", "-", "/", or "+": "${name}".`);
 		if (name === "--") throw new TypeError(`${label} name must not be the options terminator "--".`);
@@ -52,11 +58,28 @@ function validateCommandNames(names, label) {
 	for (const name of names) {
 		if (name === "") throw new TypeError(`${label} name must not be empty.`);
 		if (/^\s+$/.test(name)) throw new TypeError(`${label} name must not be whitespace-only: "${escapeControlChars(name)}".`);
-		if (/[\x00-\x1f\x7f]/.test(name)) throw new TypeError(`${label} name must not contain control characters: "${escapeControlChars(name)}".`);
+		if (CONTROL_CHAR_RE.test(name)) throw new TypeError(`${label} name must not contain control characters: "${escapeControlChars(name)}".`);
 		if (/\s/.test(name)) throw new TypeError(`${label} name must not contain whitespace: "${escapeControlChars(name)}".`);
 	}
 }
+/**
+* Validates a program name at runtime.
+*
+* Program names may contain spaces (e.g., file paths), but must not be empty,
+* whitespace-only, or contain control characters.
+*
+* @param programName The program name to validate.
+* @throws {TypeError} If the value is not a string, is empty,
+*         whitespace-only, or contains control characters.
+*/
+function validateProgramName(programName) {
+	if (typeof programName !== "string") throw new TypeError("Program name must be a string.");
+	if (programName === "") throw new TypeError("Program name must not be empty.");
+	if (/^\s+$/.test(programName)) throw new TypeError(`Program name must not be whitespace-only: "${escapeControlChars(programName)}".`);
+	if (CONTROL_CHAR_RE.test(programName)) throw new TypeError(`Program name must not contain control characters: "${escapeControlChars(programName)}".`);
+}
 
 //#endregion
 exports.validateCommandNames = validateCommandNames;
-exports.validateOptionNames = validateOptionNames;
+exports.validateOptionNames = validateOptionNames;
+exports.validateProgramName = validateProgramName;

package/dist/validate.js

@@ -1,5 +1,11 @@
 //#region src/validate.ts
 /**
+* Matches Unicode control characters: C0 (U+0000–U+001F), DEL (U+007F),
+* C1 (U+0080–U+009F), and line separators (U+2028, U+2029).
+*/
+const CONTROL_CHAR_RE = /[\x00-\x1f\x7f-\x9f\u2028\u2029]/;
+const CONTROL_CHAR_RE_GLOBAL = new RegExp(CONTROL_CHAR_RE.source, "g");
+/**
 * Escapes control characters in a string for readable error messages.
 *
 * @param value The string to escape.
@@ -7,13 +13,13 @@
 *          sequences.
 */
 function escapeControlChars(value) {
-	return value.replace(/[\x00-\x1f\x7f]/g, (ch) => {
+	return value.replace(CONTROL_CHAR_RE_GLOBAL, (ch) => {
 		const code = ch.charCodeAt(0);
 		switch (code) {
 			case 9: return "\\t";
 			case 10: return "\\n";
 			case 13: return "\\r";
-			default: return `\\x${code.toString(16).padStart(2, "0")}`;
+			default: return code > 255 ? `\\u${code.toString(16).padStart(4, "0")}` : `\\x${code.toString(16).padStart(2, "0")}`;
 		}
 	});
 }
@@ -31,7 +37,7 @@ function validateOptionNames(names, label) {
 	for (const name of names) {
 		if (name === "") throw new TypeError(`${label} name must not be empty.`);
 		if (/^\s+$/.test(name)) throw new TypeError(`${label} name must not be whitespace-only: "${escapeControlChars(name)}".`);
-		if (/[\x00-\x1f\x7f]/.test(name)) throw new TypeError(`${label} name must not contain control characters: "${escapeControlChars(name)}".`);
+		if (CONTROL_CHAR_RE.test(name)) throw new TypeError(`${label} name must not contain control characters: "${escapeControlChars(name)}".`);
 		if (/\s/.test(name)) throw new TypeError(`${label} name must not contain whitespace: "${escapeControlChars(name)}".`);
 		if (!/^(--|[-/+])/.test(name)) throw new TypeError(`${label} name must start with "--", "-", "/", or "+": "${name}".`);
 		if (name === "--") throw new TypeError(`${label} name must not be the options terminator "--".`);
@@ -51,10 +57,26 @@ function validateCommandNames(names, label) {
 	for (const name of names) {
 		if (name === "") throw new TypeError(`${label} name must not be empty.`);
 		if (/^\s+$/.test(name)) throw new TypeError(`${label} name must not be whitespace-only: "${escapeControlChars(name)}".`);
-		if (/[\x00-\x1f\x7f]/.test(name)) throw new TypeError(`${label} name must not contain control characters: "${escapeControlChars(name)}".`);
+		if (CONTROL_CHAR_RE.test(name)) throw new TypeError(`${label} name must not contain control characters: "${escapeControlChars(name)}".`);
 		if (/\s/.test(name)) throw new TypeError(`${label} name must not contain whitespace: "${escapeControlChars(name)}".`);
 	}
 }
+/**
+* Validates a program name at runtime.
+*
+* Program names may contain spaces (e.g., file paths), but must not be empty,
+* whitespace-only, or contain control characters.
+*
+* @param programName The program name to validate.
+* @throws {TypeError} If the value is not a string, is empty,
+*         whitespace-only, or contains control characters.
+*/
+function validateProgramName(programName) {
+	if (typeof programName !== "string") throw new TypeError("Program name must be a string.");
+	if (programName === "") throw new TypeError("Program name must not be empty.");
+	if (/^\s+$/.test(programName)) throw new TypeError(`Program name must not be whitespace-only: "${escapeControlChars(programName)}".`);
+	if (CONTROL_CHAR_RE.test(programName)) throw new TypeError(`Program name must not contain control characters: "${escapeControlChars(programName)}".`);
+}
 
 //#endregion
-export { validateCommandNames, validateOptionNames };
+export { validateCommandNames, validateOptionNames, validateProgramName };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1467+daf159c7",
+  "version": "1.0.0-dev.1484+220c0bfd",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",