@optique/core 1.0.0-dev.1438 → 1.0.0-dev.1442

package/dist/usage.cjs

@@ -181,14 +181,24 @@ function formatUsage(programName, usage, options = {}) {
 * sorting terms for better readability, and ensuring consistent structure
 * throughout the usage tree.
 *
-* This function performs two main operations:
+* This function performs three main operations:
 *
-* 1. *Flattening*: Recursively processes all usage terms and merges any
+* 1. *Stripping*: Removes degenerate terms that would render as empty or
+*    malformed output, such as options with no names, commands with empty
+*    names, arguments with empty metavars, and container terms (`optional`,
+*    `multiple`, `exclusive`) whose top-level terms array is empty after
+*    recursive normalization.  Exclusive branches representing valid
+*    zero-token alternatives (e.g., `conditional()` default branches or
+*    `optional(constant(...))`) and empty-value literals are preserved.
+*    Only branches that become empty because all their content was
+*    malformed are removed.
+*
+* 2. *Flattening*: Recursively processes all usage terms and merges any
 *    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.
 *
-* 2. *Sorting*: Reorders terms to improve readability by placing:
+* 3. *Sorting*: Reorders terms to improve readability by placing:
 *    - Commands (subcommands) first
 *    - Options and other terms in the middle
 *    - Positional arguments last (including optional/multiple wrappers around
@@ -198,11 +208,12 @@ function formatUsage(programName, usage, options = {}) {
 * positional arguments and treats them as arguments for sorting purposes.
 *
 * @param usage The usage description to normalize.
-* @returns A normalized usage description with flattened exclusive terms
-*          and terms sorted for optimal readability.
+* @returns A normalized usage description with degenerate terms removed,
+*          nested exclusive terms flattened, and remaining terms sorted for
+*          optimal readability.
 */
 function normalizeUsage(usage) {
-	const terms = usage.map(normalizeUsageTerm);
+	const terms = usage.map(normalizeUsageTerm).filter(isNonDegenerateTerm);
 	terms.sort((a, b) => {
 		const aCmd = a.type === "command";
 		const bCmd = b.type === "command";
@@ -229,7 +240,7 @@ function normalizeUsageTerm(term) {
 			if (normalized.length >= 1 && normalized[0].type === "exclusive") {
 				const rest = normalized.slice(1);
 				for (const subUsage of normalized[0].terms) terms.push([...subUsage, ...rest]);
-			} else terms.push(normalized);
+			} else if (normalized.length > 0 || !containsMalformedLeaf(usage)) terms.push(normalized);
 		}
 		return {
 			type: "exclusive",
@@ -237,6 +248,27 @@ function normalizeUsageTerm(term) {
 		};
 	} else return term;
 }
+function isNonDegenerateTerm(term) {
+	if (term.type === "option") return term.names.length > 0;
+	if (term.type === "command") return term.name !== "";
+	if (term.type === "argument") return term.metavar.length > 0;
+	if (term.type === "optional" || term.type === "multiple" || term.type === "exclusive") return term.terms.length > 0;
+	return true;
+}
+function containsMalformedLeaf(usage) {
+	for (const term of usage) {
+		if (term.type === "option" && term.names.length === 0) return true;
+		if (term.type === "command" && term.name === "") return true;
+		if (term.type === "argument" && term.metavar.length === 0) return true;
+		if (term.type === "optional" || term.type === "multiple") {
+			if (containsMalformedLeaf(term.terms)) return true;
+		}
+		if (term.type === "exclusive") {
+			for (const branch of term.terms) if (containsMalformedLeaf(branch)) return true;
+		}
+	}
+	return false;
+}
 /**
 * Creates a deep clone of a single {@link UsageTerm}.  Recursive term
 * variants (`optional`, `multiple`, `exclusive`) are cloned recursively.

package/dist/usage.d.cts

@@ -332,14 +332,24 @@ declare function formatUsage(programName: string, usage: Usage, options?: UsageF
  * sorting terms for better readability, and ensuring consistent structure
  * throughout the usage tree.
  *
- * This function performs two main operations:
+ * This function performs three main operations:
  *
- * 1. *Flattening*: Recursively processes all usage terms and merges any
+ * 1. *Stripping*: Removes degenerate terms that would render as empty or
+ *    malformed output, such as options with no names, commands with empty
+ *    names, arguments with empty metavars, and container terms (`optional`,
+ *    `multiple`, `exclusive`) whose top-level terms array is empty after
+ *    recursive normalization.  Exclusive branches representing valid
+ *    zero-token alternatives (e.g., `conditional()` default branches or
+ *    `optional(constant(...))`) and empty-value literals are preserved.
+ *    Only branches that become empty because all their content was
+ *    malformed are removed.
+ *
+ * 2. *Flattening*: Recursively processes all usage terms and merges any
  *    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.
  *
- * 2. *Sorting*: Reorders terms to improve readability by placing:
+ * 3. *Sorting*: Reorders terms to improve readability by placing:
  *    - Commands (subcommands) first
  *    - Options and other terms in the middle
  *    - Positional arguments last (including optional/multiple wrappers around
@@ -349,8 +359,9 @@ declare function formatUsage(programName: string, usage: Usage, options?: UsageF
  * positional arguments and treats them as arguments for sorting purposes.
  *
  * @param usage The usage description to normalize.
- * @returns A normalized usage description with flattened exclusive terms
- *          and terms sorted for optimal readability.
+ * @returns A normalized usage description with degenerate terms removed,
+ *          nested exclusive terms flattened, and remaining terms sorted for
+ *          optimal readability.
  */
 declare function normalizeUsage(usage: Usage): Usage;
 /**

package/dist/usage.d.ts

@@ -332,14 +332,24 @@ declare function formatUsage(programName: string, usage: Usage, options?: UsageF
  * sorting terms for better readability, and ensuring consistent structure
  * throughout the usage tree.
  *
- * This function performs two main operations:
+ * This function performs three main operations:
  *
- * 1. *Flattening*: Recursively processes all usage terms and merges any
+ * 1. *Stripping*: Removes degenerate terms that would render as empty or
+ *    malformed output, such as options with no names, commands with empty
+ *    names, arguments with empty metavars, and container terms (`optional`,
+ *    `multiple`, `exclusive`) whose top-level terms array is empty after
+ *    recursive normalization.  Exclusive branches representing valid
+ *    zero-token alternatives (e.g., `conditional()` default branches or
+ *    `optional(constant(...))`) and empty-value literals are preserved.
+ *    Only branches that become empty because all their content was
+ *    malformed are removed.
+ *
+ * 2. *Flattening*: Recursively processes all usage terms and merges any
  *    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.
  *
- * 2. *Sorting*: Reorders terms to improve readability by placing:
+ * 3. *Sorting*: Reorders terms to improve readability by placing:
  *    - Commands (subcommands) first
  *    - Options and other terms in the middle
  *    - Positional arguments last (including optional/multiple wrappers around
@@ -349,8 +359,9 @@ declare function formatUsage(programName: string, usage: Usage, options?: UsageF
  * positional arguments and treats them as arguments for sorting purposes.
  *
  * @param usage The usage description to normalize.
- * @returns A normalized usage description with flattened exclusive terms
- *          and terms sorted for optimal readability.
+ * @returns A normalized usage description with degenerate terms removed,
+ *          nested exclusive terms flattened, and remaining terms sorted for
+ *          optimal readability.
  */
 declare function normalizeUsage(usage: Usage): Usage;
 /**

package/dist/usage.js

@@ -180,14 +180,24 @@ function formatUsage(programName, usage, options = {}) {
 * sorting terms for better readability, and ensuring consistent structure
 * throughout the usage tree.
 *
-* This function performs two main operations:
+* This function performs three main operations:
 *
-* 1. *Flattening*: Recursively processes all usage terms and merges any
+* 1. *Stripping*: Removes degenerate terms that would render as empty or
+*    malformed output, such as options with no names, commands with empty
+*    names, arguments with empty metavars, and container terms (`optional`,
+*    `multiple`, `exclusive`) whose top-level terms array is empty after
+*    recursive normalization.  Exclusive branches representing valid
+*    zero-token alternatives (e.g., `conditional()` default branches or
+*    `optional(constant(...))`) and empty-value literals are preserved.
+*    Only branches that become empty because all their content was
+*    malformed are removed.
+*
+* 2. *Flattening*: Recursively processes all usage terms and merges any
 *    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.
 *
-* 2. *Sorting*: Reorders terms to improve readability by placing:
+* 3. *Sorting*: Reorders terms to improve readability by placing:
 *    - Commands (subcommands) first
 *    - Options and other terms in the middle
 *    - Positional arguments last (including optional/multiple wrappers around
@@ -197,11 +207,12 @@ function formatUsage(programName, usage, options = {}) {
 * positional arguments and treats them as arguments for sorting purposes.
 *
 * @param usage The usage description to normalize.
-* @returns A normalized usage description with flattened exclusive terms
-*          and terms sorted for optimal readability.
+* @returns A normalized usage description with degenerate terms removed,
+*          nested exclusive terms flattened, and remaining terms sorted for
+*          optimal readability.
 */
 function normalizeUsage(usage) {
-	const terms = usage.map(normalizeUsageTerm);
+	const terms = usage.map(normalizeUsageTerm).filter(isNonDegenerateTerm);
 	terms.sort((a, b) => {
 		const aCmd = a.type === "command";
 		const bCmd = b.type === "command";
@@ -228,7 +239,7 @@ function normalizeUsageTerm(term) {
 			if (normalized.length >= 1 && normalized[0].type === "exclusive") {
 				const rest = normalized.slice(1);
 				for (const subUsage of normalized[0].terms) terms.push([...subUsage, ...rest]);
-			} else terms.push(normalized);
+			} else if (normalized.length > 0 || !containsMalformedLeaf(usage)) terms.push(normalized);
 		}
 		return {
 			type: "exclusive",
@@ -236,6 +247,27 @@ function normalizeUsageTerm(term) {
 		};
 	} else return term;
 }
+function isNonDegenerateTerm(term) {
+	if (term.type === "option") return term.names.length > 0;
+	if (term.type === "command") return term.name !== "";
+	if (term.type === "argument") return term.metavar.length > 0;
+	if (term.type === "optional" || term.type === "multiple" || term.type === "exclusive") return term.terms.length > 0;
+	return true;
+}
+function containsMalformedLeaf(usage) {
+	for (const term of usage) {
+		if (term.type === "option" && term.names.length === 0) return true;
+		if (term.type === "command" && term.name === "") return true;
+		if (term.type === "argument" && term.metavar.length === 0) return true;
+		if (term.type === "optional" || term.type === "multiple") {
+			if (containsMalformedLeaf(term.terms)) return true;
+		}
+		if (term.type === "exclusive") {
+			for (const branch of term.terms) if (containsMalformedLeaf(branch)) return true;
+		}
+	}
+	return false;
+}
 /**
 * Creates a deep clone of a single {@link UsageTerm}.  Recursive term
 * variants (`optional`, `multiple`, `exclusive`) are cloned recursively.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1438+20bfdfd1",
+  "version": "1.0.0-dev.1442+4c1b0441",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",