@optique/core 1.0.0-dev.1178 → 1.0.0-dev.1189

package/dist/completion.cjs

@@ -47,12 +47,13 @@ function encodeExtensions(extensions) {
 * Replaces control characters that would corrupt shell completion protocols.
 * Shell completion formats use tabs as field delimiters and newlines as record
 * delimiters.  Null bytes are used as delimiters in zsh's format.
-* @param description The description string to sanitize.
-* @returns The sanitized description with control characters replaced by spaces.
+* This is used for both suggestion text and descriptions.
+* @param text The string to sanitize.
+* @returns The sanitized string with control characters replaced by spaces.
 * @internal
 */
-function sanitizeDescription(description) {
-	return description.replace(/[\t\n\r\0]/g, " ");
+function sanitizeForTransport(text) {
+	return text.replace(/[\t\n\r\0]/g, " ");
 }
 /**
 * The Bash shell completion generator.
@@ -287,7 +288,7 @@ complete -F _${programName} -- ${programName}
 		let i = 0;
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
-			if (suggestion.kind === "literal") yield `${suggestion.text}`;
+			if (suggestion.kind === "literal") yield sanitizeForTransport(suggestion.text);
 			else {
 				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
@@ -434,12 +435,12 @@ compdef _${programName.replace(/[^a-zA-Z0-9]/g, "_")} ${programName}
 	},
 	*encodeSuggestions(suggestions) {
 		for (const suggestion of suggestions) if (suggestion.kind === "literal") {
-			const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
-			yield `${suggestion.text}\0${description}\0`;
+			const description = suggestion.description == null ? "" : sanitizeForTransport(require_message.formatMessage(suggestion.description, { colors: false }));
+			yield `${sanitizeForTransport(suggestion.text)}\0${description}\0`;
 		} else {
 			const extensions = encodeExtensions(suggestion.extensions);
 			const hidden = suggestion.includeHidden ? "1" : "0";
-			const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
+			const description = suggestion.description == null ? "" : sanitizeForTransport(require_message.formatMessage(suggestion.description, { colors: false }));
 			const pattern = encodePattern(suggestion.pattern ?? "");
 			yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\0${description}\0`;
 		}
@@ -724,12 +725,12 @@ complete -c ${programName} -f -a '(${functionName})'
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
 			if (suggestion.kind === "literal") {
-				const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
-				yield `${suggestion.text}\t${description}`;
+				const description = suggestion.description == null ? "" : sanitizeForTransport(require_message.formatMessage(suggestion.description, { colors: false }));
+				yield `${sanitizeForTransport(suggestion.text)}\t${description}`;
 			} else {
 				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
-				const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
+				const description = suggestion.description == null ? "" : sanitizeForTransport(require_message.formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
 				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t${description}`;
 			}
@@ -1046,12 +1047,12 @@ ${functionName}-external
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
 			if (suggestion.kind === "literal") {
-				const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
-				yield `${suggestion.text}\t${description}`;
+				const description = suggestion.description == null ? "" : sanitizeForTransport(require_message.formatMessage(suggestion.description, { colors: false }));
+				yield `${sanitizeForTransport(suggestion.text)}\t${description}`;
 			} else {
 				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
-				const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
+				const description = suggestion.description == null ? "" : sanitizeForTransport(require_message.formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
 				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t${description}`;
 			}
@@ -1257,12 +1258,13 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
 			if (suggestion.kind === "literal") {
-				const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
-				yield `${suggestion.text}\t${suggestion.text}\t${description}`;
+				const description = suggestion.description == null ? "" : sanitizeForTransport(require_message.formatMessage(suggestion.description, { colors: false }));
+				const text = sanitizeForTransport(suggestion.text);
+				yield `${text}\t${text}\t${description}`;
 			} else {
 				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
-				const description = suggestion.description == null ? "" : sanitizeDescription(require_message.formatMessage(suggestion.description, { colors: false }));
+				const description = suggestion.description == null ? "" : sanitizeForTransport(require_message.formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
 				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t[file]\t${description}`;
 			}

package/dist/completion.js

@@ -47,12 +47,13 @@ function encodeExtensions(extensions) {
 * Replaces control characters that would corrupt shell completion protocols.
 * Shell completion formats use tabs as field delimiters and newlines as record
 * delimiters.  Null bytes are used as delimiters in zsh's format.
-* @param description The description string to sanitize.
-* @returns The sanitized description with control characters replaced by spaces.
+* This is used for both suggestion text and descriptions.
+* @param text The string to sanitize.
+* @returns The sanitized string with control characters replaced by spaces.
 * @internal
 */
-function sanitizeDescription(description) {
-	return description.replace(/[\t\n\r\0]/g, " ");
+function sanitizeForTransport(text) {
+	return text.replace(/[\t\n\r\0]/g, " ");
 }
 /**
 * The Bash shell completion generator.
@@ -287,7 +288,7 @@ complete -F _${programName} -- ${programName}
 		let i = 0;
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
-			if (suggestion.kind === "literal") yield `${suggestion.text}`;
+			if (suggestion.kind === "literal") yield sanitizeForTransport(suggestion.text);
 			else {
 				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
@@ -434,12 +435,12 @@ compdef _${programName.replace(/[^a-zA-Z0-9]/g, "_")} ${programName}
 	},
 	*encodeSuggestions(suggestions) {
 		for (const suggestion of suggestions) if (suggestion.kind === "literal") {
-			const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
-			yield `${suggestion.text}\0${description}\0`;
+			const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
+			yield `${sanitizeForTransport(suggestion.text)}\0${description}\0`;
 		} else {
 			const extensions = encodeExtensions(suggestion.extensions);
 			const hidden = suggestion.includeHidden ? "1" : "0";
-			const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
+			const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
 			const pattern = encodePattern(suggestion.pattern ?? "");
 			yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\0${description}\0`;
 		}
@@ -724,12 +725,12 @@ complete -c ${programName} -f -a '(${functionName})'
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
 			if (suggestion.kind === "literal") {
-				const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
-				yield `${suggestion.text}\t${description}`;
+				const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
+				yield `${sanitizeForTransport(suggestion.text)}\t${description}`;
 			} else {
 				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
-				const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
+				const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
 				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t${description}`;
 			}
@@ -1046,12 +1047,12 @@ ${functionName}-external
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
 			if (suggestion.kind === "literal") {
-				const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
-				yield `${suggestion.text}\t${description}`;
+				const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
+				yield `${sanitizeForTransport(suggestion.text)}\t${description}`;
 			} else {
 				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
-				const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
+				const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
 				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t${description}`;
 			}
@@ -1257,12 +1258,13 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
 		for (const suggestion of suggestions) {
 			if (i > 0) yield "\n";
 			if (suggestion.kind === "literal") {
-				const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
-				yield `${suggestion.text}\t${suggestion.text}\t${description}`;
+				const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
+				const text = sanitizeForTransport(suggestion.text);
+				yield `${text}\t${text}\t${description}`;
 			} else {
 				const extensions = encodeExtensions(suggestion.extensions);
 				const hidden = suggestion.includeHidden ? "1" : "0";
-				const description = suggestion.description == null ? "" : sanitizeDescription(formatMessage(suggestion.description, { colors: false }));
+				const description = suggestion.description == null ? "" : sanitizeForTransport(formatMessage(suggestion.description, { colors: false }));
 				const pattern = encodePattern(suggestion.pattern ?? "");
 				yield `__FILE__:${suggestion.type}:${extensions}:${pattern}:${hidden}\t[file]\t${description}`;
 			}

package/dist/doc.cjs

@@ -47,8 +47,9 @@ 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` or any non-empty section's title
-* contains a CR or LF character.
+* @throws {TypeError} If `programName` contains a CR or LF character, or if
+* any non-empty section's title is empty, whitespace-only, or contains a CR
+* or LF character.
 *
 * @example
 * ```typescript
@@ -113,7 +114,7 @@ function formatDocPage(programName, page, options = {}) {
 		if (section.entries.length < 1) continue;
 		output += "\n";
 		if (section.title != null) {
-			if (/[\r\n]/.test(section.title)) throw new TypeError("Section title must not contain newlines.");
+			if (section.title.trim() === "" || /[\r\n]/.test(section.title)) throw new TypeError("Section title must not be empty, whitespace-only, or contain newlines.");
 			const sectionLabel = options.colors ? `\x1b[1;2m${section.title}:\x1b[0m\n` : `${section.title}:\n`;
 			output += sectionLabel;
 		}

package/dist/doc.d.cts

@@ -263,8 +263,9 @@ 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` or any non-empty section's title
- * contains a CR or LF character.
+ * @throws {TypeError} If `programName` contains a CR or LF character, or if
+ * any non-empty section's title is empty, whitespace-only, or contains a CR
+ * or LF character.
  *
  * @example
  * ```typescript

package/dist/doc.d.ts

@@ -263,8 +263,9 @@ 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` or any non-empty section's title
- * contains a CR or LF character.
+ * @throws {TypeError} If `programName` contains a CR or LF character, or if
+ * any non-empty section's title is empty, whitespace-only, or contains a CR
+ * or LF character.
  *
  * @example
  * ```typescript

package/dist/doc.js

@@ -47,8 +47,9 @@ 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` or any non-empty section's title
-* contains a CR or LF character.
+* @throws {TypeError} If `programName` contains a CR or LF character, or if
+* any non-empty section's title is empty, whitespace-only, or contains a CR
+* or LF character.
 *
 * @example
 * ```typescript
@@ -113,7 +114,7 @@ function formatDocPage(programName, page, options = {}) {
 		if (section.entries.length < 1) continue;
 		output += "\n";
 		if (section.title != null) {
-			if (/[\r\n]/.test(section.title)) throw new TypeError("Section title must not contain newlines.");
+			if (section.title.trim() === "" || /[\r\n]/.test(section.title)) throw new TypeError("Section title must not be empty, whitespace-only, or contain newlines.");
 			const sectionLabel = options.colors ? `\x1b[1;2m${section.title}:\x1b[0m\n` : `${section.title}:\n`;
 			output += sectionLabel;
 		}

package/dist/valueparser.cjs

@@ -1133,6 +1133,8 @@ function ipv4(options) {
 *
 * @param options - Options for hostname validation.
 * @returns A value parser for hostnames.
+* @throws {TypeError} If `allowWildcard`, `allowUnderscore`, or
+*   `allowLocalhost` is not a boolean.
 * @throws {RangeError} If `maxLength` is not a positive integer.
 * @since 0.10.0
 *
@@ -1153,6 +1155,9 @@ function ipv4(options) {
 function hostname(options) {
 	const metavar = options?.metavar ?? "HOST";
 	require_nonempty.ensureNonEmptyString(metavar);
+	if (options?.allowWildcard !== void 0 && typeof options.allowWildcard !== "boolean") throw new TypeError(`Expected allowWildcard to be a boolean, but got ${typeof options.allowWildcard}: ${String(options.allowWildcard)}.`);
+	if (options?.allowUnderscore !== void 0 && typeof options.allowUnderscore !== "boolean") throw new TypeError(`Expected allowUnderscore to be a boolean, but got ${typeof options.allowUnderscore}: ${String(options.allowUnderscore)}.`);
+	if (options?.allowLocalhost !== void 0 && typeof options.allowLocalhost !== "boolean") throw new TypeError(`Expected allowLocalhost to be a boolean, but got ${typeof options.allowLocalhost}: ${String(options.allowLocalhost)}.`);
 	const allowWildcard = options?.allowWildcard ?? false;
 	const allowUnderscore = options?.allowUnderscore ?? false;
 	const allowLocalhost = options?.allowLocalhost ?? true;
@@ -1868,6 +1873,7 @@ function macAddress(options) {
 * @returns A parser that accepts valid domain names as strings.
 * @throws {RangeError} If `maxLength` is not a positive integer.
 * @throws {RangeError} If `minLabels` is not a positive integer.
+* @throws {TypeError} If `allowSubdomains` or `lowercase` is not a boolean.
 * @throws {TypeError} If any `allowedTlds` entry is not a string, is empty,
 *   contains dots, has leading/trailing whitespace, or is not a valid DNS
 *   label.
@@ -1896,6 +1902,8 @@ function macAddress(options) {
 */
 function domain(options) {
 	const metavar = options?.metavar ?? "DOMAIN";
+	if (options?.allowSubdomains !== void 0 && typeof options.allowSubdomains !== "boolean") throw new TypeError(`Expected allowSubdomains to be a boolean, but got ${typeof options.allowSubdomains}: ${String(options.allowSubdomains)}.`);
+	if (options?.lowercase !== void 0 && typeof options.lowercase !== "boolean") throw new TypeError(`Expected lowercase to be a boolean, but got ${typeof options.lowercase}: ${String(options.lowercase)}.`);
 	const allowSubdomains = options?.allowSubdomains ?? true;
 	const allowedTlds = options?.allowedTlds != null ? Object.freeze([...options.allowedTlds]) : void 0;
 	const labelRegex = /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$/;

package/dist/valueparser.d.cts

@@ -929,6 +929,8 @@ interface HostnameOptions {
  *
  * @param options - Options for hostname validation.
  * @returns A value parser for hostnames.
+ * @throws {TypeError} If `allowWildcard`, `allowUnderscore`, or
+ *   `allowLocalhost` is not a boolean.
  * @throws {RangeError} If `maxLength` is not a positive integer.
  * @since 0.10.0
  *
@@ -1548,6 +1550,7 @@ interface DomainOptions {
  * @returns A parser that accepts valid domain names as strings.
  * @throws {RangeError} If `maxLength` is not a positive integer.
  * @throws {RangeError} If `minLabels` is not a positive integer.
+ * @throws {TypeError} If `allowSubdomains` or `lowercase` is not a boolean.
  * @throws {TypeError} If any `allowedTlds` entry is not a string, is empty,
  *   contains dots, has leading/trailing whitespace, or is not a valid DNS
  *   label.

package/dist/valueparser.d.ts

@@ -929,6 +929,8 @@ interface HostnameOptions {
  *
  * @param options - Options for hostname validation.
  * @returns A value parser for hostnames.
+ * @throws {TypeError} If `allowWildcard`, `allowUnderscore`, or
+ *   `allowLocalhost` is not a boolean.
  * @throws {RangeError} If `maxLength` is not a positive integer.
  * @since 0.10.0
  *
@@ -1548,6 +1550,7 @@ interface DomainOptions {
  * @returns A parser that accepts valid domain names as strings.
  * @throws {RangeError} If `maxLength` is not a positive integer.
  * @throws {RangeError} If `minLabels` is not a positive integer.
+ * @throws {TypeError} If `allowSubdomains` or `lowercase` is not a boolean.
  * @throws {TypeError} If any `allowedTlds` entry is not a string, is empty,
  *   contains dots, has leading/trailing whitespace, or is not a valid DNS
  *   label.

package/dist/valueparser.js

@@ -1133,6 +1133,8 @@ function ipv4(options) {
 *
 * @param options - Options for hostname validation.
 * @returns A value parser for hostnames.
+* @throws {TypeError} If `allowWildcard`, `allowUnderscore`, or
+*   `allowLocalhost` is not a boolean.
 * @throws {RangeError} If `maxLength` is not a positive integer.
 * @since 0.10.0
 *
@@ -1153,6 +1155,9 @@ function ipv4(options) {
 function hostname(options) {
 	const metavar = options?.metavar ?? "HOST";
 	ensureNonEmptyString(metavar);
+	if (options?.allowWildcard !== void 0 && typeof options.allowWildcard !== "boolean") throw new TypeError(`Expected allowWildcard to be a boolean, but got ${typeof options.allowWildcard}: ${String(options.allowWildcard)}.`);
+	if (options?.allowUnderscore !== void 0 && typeof options.allowUnderscore !== "boolean") throw new TypeError(`Expected allowUnderscore to be a boolean, but got ${typeof options.allowUnderscore}: ${String(options.allowUnderscore)}.`);
+	if (options?.allowLocalhost !== void 0 && typeof options.allowLocalhost !== "boolean") throw new TypeError(`Expected allowLocalhost to be a boolean, but got ${typeof options.allowLocalhost}: ${String(options.allowLocalhost)}.`);
 	const allowWildcard = options?.allowWildcard ?? false;
 	const allowUnderscore = options?.allowUnderscore ?? false;
 	const allowLocalhost = options?.allowLocalhost ?? true;
@@ -1868,6 +1873,7 @@ function macAddress(options) {
 * @returns A parser that accepts valid domain names as strings.
 * @throws {RangeError} If `maxLength` is not a positive integer.
 * @throws {RangeError} If `minLabels` is not a positive integer.
+* @throws {TypeError} If `allowSubdomains` or `lowercase` is not a boolean.
 * @throws {TypeError} If any `allowedTlds` entry is not a string, is empty,
 *   contains dots, has leading/trailing whitespace, or is not a valid DNS
 *   label.
@@ -1896,6 +1902,8 @@ function macAddress(options) {
 */
 function domain(options) {
 	const metavar = options?.metavar ?? "DOMAIN";
+	if (options?.allowSubdomains !== void 0 && typeof options.allowSubdomains !== "boolean") throw new TypeError(`Expected allowSubdomains to be a boolean, but got ${typeof options.allowSubdomains}: ${String(options.allowSubdomains)}.`);
+	if (options?.lowercase !== void 0 && typeof options.lowercase !== "boolean") throw new TypeError(`Expected lowercase to be a boolean, but got ${typeof options.lowercase}: ${String(options.lowercase)}.`);
 	const allowSubdomains = options?.allowSubdomains ?? true;
 	const allowedTlds = options?.allowedTlds != null ? Object.freeze([...options.allowedTlds]) : void 0;
 	const labelRegex = /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$/;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1178+6b5574a3",
+  "version": "1.0.0-dev.1189+856a380f",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",