@optique/core 1.0.0-dev.1553 → 1.0.0-dev.1561

package/dist/facade.cjs

@@ -563,6 +563,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		args = argsOrOptions;
 		options = optionsParam ?? {};
 	}
+	require_validate.validateProgramName(programName);
 	const { colors, maxWidth, showDefault, showChoices, sectionOrder, aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;

package/dist/facade.d.cts

@@ -272,11 +272,13 @@ interface RunOptions<THelp, TError> {
  * @param options Configuration options for output formatting and callbacks.
  * @returns The parsed result value, or the return value of `onHelp`/`onError`
  *          callbacks.
- * @throws {TypeError} If `options.version.value` is not a non-empty string
- *          without ASCII control characters, or if any meta command/option
- *          name is empty, whitespace-only, contains whitespace or control
- *          characters, or (for option names) lacks a valid prefix (`--`,
- *          `-`, `/`, or `+`).
+ * @throws {TypeError} If `programName` (or `program.metadata.name`) is not
+ *          a string, is empty, is whitespace-only, or contains control
+ *          characters.  Also thrown if `options.version.value` is not a
+ *          non-empty string without ASCII control characters, or if any
+ *          meta command/option name is empty, whitespace-only, contains
+ *          whitespace or control characters, or (for option names) lacks a
+ *          valid prefix (`--`, `-`, `/`, or `+`).
  * @throws {RunParserError} When parsing fails and no `onError` callback is
  *          provided.
  * @since 0.10.0 Added support for {@link Program} objects.

package/dist/facade.d.ts

@@ -272,11 +272,13 @@ interface RunOptions<THelp, TError> {
  * @param options Configuration options for output formatting and callbacks.
  * @returns The parsed result value, or the return value of `onHelp`/`onError`
  *          callbacks.
- * @throws {TypeError} If `options.version.value` is not a non-empty string
- *          without ASCII control characters, or if any meta command/option
- *          name is empty, whitespace-only, contains whitespace or control
- *          characters, or (for option names) lacks a valid prefix (`--`,
- *          `-`, `/`, or `+`).
+ * @throws {TypeError} If `programName` (or `program.metadata.name`) is not
+ *          a string, is empty, is whitespace-only, or contains control
+ *          characters.  Also thrown if `options.version.value` is not a
+ *          non-empty string without ASCII control characters, or if any
+ *          meta command/option name is empty, whitespace-only, contains
+ *          whitespace or control characters, or (for option names) lacks a
+ *          valid prefix (`--`, `-`, `/`, or `+`).
  * @throws {RunParserError} When parsing fails and no `onError` callback is
  *          provided.
  * @since 0.10.0 Added support for {@link Program} objects.

package/dist/facade.js

@@ -2,7 +2,7 @@ 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, validateMetaNameCollisions, validateOptionNames } from "./validate.js";
+import { validateCommandNames, validateMetaNameCollisions, validateOptionNames, validateProgramName } from "./validate.js";
 import { extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage } from "./usage.js";
 import { formatDocPage } from "./doc.js";
 import { group, longestMatch, object } from "./constructs.js";
@@ -563,6 +563,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		args = argsOrOptions;
 		options = optionsParam ?? {};
 	}
+	validateProgramName(programName);
 	const { colors, maxWidth, showDefault, showChoices, sectionOrder, aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;

package/dist/program.cjs

@@ -1,3 +1,4 @@
+const require_validate = require('./validate.cjs');
 
 //#region src/program.ts
 /**
@@ -11,6 +12,8 @@
 * @template T - The type of value produced by the parser.
 * @param program - The program definition with parser and metadata.
 * @returns The same program object with inferred types.
+* @throws {TypeError} If `program.metadata.name` is not a string, is empty,
+*         is whitespace-only, or contains control characters.
 *
 * @example
 * ```typescript
@@ -37,6 +40,7 @@
 * @since 1.0.0
 */
 function defineProgram(program) {
+	require_validate.validateProgramName(program.metadata.name);
 	return program;
 }
 

package/dist/program.d.cts

@@ -94,6 +94,8 @@ interface Program<M extends Mode, T> {
  * @template T - The type of value produced by the parser.
  * @param program - The program definition with parser and metadata.
  * @returns The same program object with inferred types.
+ * @throws {TypeError} If `program.metadata.name` is not a string, is empty,
+ *         is whitespace-only, or contains control characters.
  *
  * @example
  * ```typescript

package/dist/program.d.ts

@@ -94,6 +94,8 @@ interface Program<M extends Mode, T> {
  * @template T - The type of value produced by the parser.
  * @param program - The program definition with parser and metadata.
  * @returns The same program object with inferred types.
+ * @throws {TypeError} If `program.metadata.name` is not a string, is empty,
+ *         is whitespace-only, or contains control characters.
  *
  * @example
  * ```typescript

package/dist/program.js

@@ -1,3 +1,5 @@
+import { validateProgramName } from "./validate.js";
+
 //#region src/program.ts
 /**
 * Defines a CLI program with a parser and metadata.
@@ -10,6 +12,8 @@
 * @template T - The type of value produced by the parser.
 * @param program - The program definition with parser and metadata.
 * @returns The same program object with inferred types.
+* @throws {TypeError} If `program.metadata.name` is not a string, is empty,
+*         is whitespace-only, or contains control characters.
 *
 * @example
 * ```typescript
@@ -36,6 +40,7 @@
 * @since 1.0.0
 */
 function defineProgram(program) {
+	validateProgramName(program.metadata.name);
 	return program;
 }
 

package/dist/usage.cjs

@@ -239,6 +239,9 @@ function formatUsage(programName, usage, options = {}) {
 *    nested exclusive terms into their parent exclusive term to avoid
 *    redundant nesting. For example, an exclusive term containing another
 *    exclusive term will have its nested terms flattened into the parent.
+*    Similarly, nested optional terms are collapsed:
+*    `optional(optional(X))` becomes `optional(X)` when the outer optional
+*    contains only a single inner optional term.
 *
 * 3. *Sorting*: Reorders terms to improve readability by placing:
 *    - Commands (subcommands) first
@@ -251,8 +254,8 @@ function formatUsage(programName, usage, options = {}) {
 *
 * @param usage The usage description to normalize.
 * @returns A normalized usage description with degenerate terms removed,
-*          nested exclusive terms flattened, and remaining terms sorted for
-*          optimal readability.
+*          nested exclusive and optional terms flattened, and remaining
+*          terms sorted for optimal readability.
 */
 function normalizeUsage(usage) {
 	const terms = usage.map(normalizeUsageTerm).filter(isNonDegenerateTerm);
@@ -266,11 +269,14 @@ function normalizeUsage(usage) {
 	return terms;
 }
 function normalizeUsageTerm(term) {
-	if (term.type === "optional") return {
-		type: "optional",
-		terms: normalizeUsage(term.terms)
-	};
-	else if (term.type === "multiple") return {
+	if (term.type === "optional") {
+		const normalized = normalizeUsage(term.terms);
+		if (normalized.length === 1 && normalized[0].type === "optional") return normalized[0];
+		return {
+			type: "optional",
+			terms: normalized
+		};
+	} else if (term.type === "multiple") return {
 		type: "multiple",
 		terms: normalizeUsage(term.terms),
 		min: term.min

package/dist/usage.d.cts

@@ -379,6 +379,9 @@ declare function formatUsage(programName: string, usage: Usage, options?: UsageF
  *    nested exclusive terms into their parent exclusive term to avoid
  *    redundant nesting. For example, an exclusive term containing another
  *    exclusive term will have its nested terms flattened into the parent.
+ *    Similarly, nested optional terms are collapsed:
+ *    `optional(optional(X))` becomes `optional(X)` when the outer optional
+ *    contains only a single inner optional term.
  *
  * 3. *Sorting*: Reorders terms to improve readability by placing:
  *    - Commands (subcommands) first
@@ -391,8 +394,8 @@ declare function formatUsage(programName: string, usage: Usage, options?: UsageF
  *
  * @param usage The usage description to normalize.
  * @returns A normalized usage description with degenerate terms removed,
- *          nested exclusive terms flattened, and remaining terms sorted for
- *          optimal readability.
+ *          nested exclusive and optional terms flattened, and remaining
+ *          terms sorted for optimal readability.
  */
 declare function normalizeUsage(usage: Usage): Usage;
 /**

package/dist/usage.d.ts

@@ -379,6 +379,9 @@ declare function formatUsage(programName: string, usage: Usage, options?: UsageF
  *    nested exclusive terms into their parent exclusive term to avoid
  *    redundant nesting. For example, an exclusive term containing another
  *    exclusive term will have its nested terms flattened into the parent.
+ *    Similarly, nested optional terms are collapsed:
+ *    `optional(optional(X))` becomes `optional(X)` when the outer optional
+ *    contains only a single inner optional term.
  *
  * 3. *Sorting*: Reorders terms to improve readability by placing:
  *    - Commands (subcommands) first
@@ -391,8 +394,8 @@ declare function formatUsage(programName: string, usage: Usage, options?: UsageF
  *
  * @param usage The usage description to normalize.
  * @returns A normalized usage description with degenerate terms removed,
- *          nested exclusive terms flattened, and remaining terms sorted for
- *          optimal readability.
+ *          nested exclusive and optional terms flattened, and remaining
+ *          terms sorted for optimal readability.
  */
 declare function normalizeUsage(usage: Usage): Usage;
 /**

package/dist/usage.js

@@ -239,6 +239,9 @@ function formatUsage(programName, usage, options = {}) {
 *    nested exclusive terms into their parent exclusive term to avoid
 *    redundant nesting. For example, an exclusive term containing another
 *    exclusive term will have its nested terms flattened into the parent.
+*    Similarly, nested optional terms are collapsed:
+*    `optional(optional(X))` becomes `optional(X)` when the outer optional
+*    contains only a single inner optional term.
 *
 * 3. *Sorting*: Reorders terms to improve readability by placing:
 *    - Commands (subcommands) first
@@ -251,8 +254,8 @@ function formatUsage(programName, usage, options = {}) {
 *
 * @param usage The usage description to normalize.
 * @returns A normalized usage description with degenerate terms removed,
-*          nested exclusive terms flattened, and remaining terms sorted for
-*          optimal readability.
+*          nested exclusive and optional terms flattened, and remaining
+*          terms sorted for optimal readability.
 */
 function normalizeUsage(usage) {
 	const terms = usage.map(normalizeUsageTerm).filter(isNonDegenerateTerm);
@@ -266,11 +269,14 @@ function normalizeUsage(usage) {
 	return terms;
 }
 function normalizeUsageTerm(term) {
-	if (term.type === "optional") return {
-		type: "optional",
-		terms: normalizeUsage(term.terms)
-	};
-	else if (term.type === "multiple") return {
+	if (term.type === "optional") {
+		const normalized = normalizeUsage(term.terms);
+		if (normalized.length === 1 && normalized[0].type === "optional") return normalized[0];
+		return {
+			type: "optional",
+			terms: normalized
+		};
+	} else if (term.type === "multiple") return {
 		type: "multiple",
 		terms: normalizeUsage(term.terms),
 		min: term.min

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1553+1e439439",
+  "version": "1.0.0-dev.1561+241c020e",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",