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

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}.`);

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,4 +1,5 @@
 import { cloneMessage, formatMessage, text } from "./message.js";
+import { validateProgramName } from "./validate.js";
 import { cloneUsageTerm, formatUsage, formatUsageTerm, isDocHidden } 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}.`);

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);

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);

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.1470+e7499369",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",