@optique/core 1.4.0-dev.2708 → 1.4.0-dev.2711

package/dist/usage.cjs

@@ -1,5 +1,6 @@
 const require_displaywidth = require('./displaywidth.cjs');
 const require_terminal_internal = require('./terminal-internal.cjs');
+const require_internal_usage = require('./internal/usage.cjs');
 const require_validate = require('./validate.cjs');
 
 //#region src/usage.ts
@@ -190,16 +191,39 @@ function formatUsage(programName, usage, options = {}) {
 		theme: require_terminal_internal.cacheTerminalTheme(options.theme)
 	};
 	require_validate.validateProgramName(programName);
-	usage = normalizeUsage(filterUsageForDisplay(usage));
+	return formatUsageLines(programName, normalizeUsage(filterUsageForDisplay(require_internal_usage.resolveUsageForDisplay(usage, isUsageHidden))), normalizeUsage(filterUsageForDisplay(require_internal_usage.forgetEmptyInput(usage))), options);
+}
+/**
+* Formats a display-ready usage, expanding a trailing command group into one
+* line per command when requested.
+* @param programName The program name.
+* @param usage The usage to draw, already resolved, filtered and normalized.
+* @param declared The same usage as declared, without empty-input records,
+*                 filtered and normalized.  It tells a group that was drawn
+*                 as optional because it accepts empty input apart from a
+*                 group declared optional.
+* @param options The formatting options.
+* @returns The formatted usage.
+*/
+function formatUsageLines(programName, usage, declared, options) {
 	if (options.expandCommands) {
-		const lastTerm = usage.at(-1);
+		let lastTerm = usage.at(-1);
+		const declaredLast = declared.at(-1);
+		if (lastTerm?.type === "optional" && declaredLast?.type === "exclusive") {
+			if (lastTerm.terms.length === 1 && lastTerm.terms[0].type === "exclusive") lastTerm = lastTerm.terms[0];
+			else if (lastTerm.terms[0]?.type === "command") lastTerm = {
+				type: "exclusive",
+				terms: [lastTerm.terms]
+			};
+		}
 		if (usage.length > 0 && usage.slice(0, -1).every((t) => t.type === "command") && lastTerm.type === "exclusive" && lastTerm.terms.every((t) => t.length > 0 && (t[0].type === "command" || t[0].type === "option" || t[0].type === "argument" || t[0].type === "optional" && t[0].terms.length === 1 && (t[0].terms[0].type === "command" || t[0].terms[0].type === "option" || t[0].terms[0].type === "argument")))) {
+			const declaredBranches = declaredLast?.type === "exclusive" && declaredLast.terms.length === lastTerm.terms.length ? declaredLast.terms : void 0;
 			const lines = [];
-			for (let command of lastTerm.terms) {
+			for (const [index, command] of lastTerm.terms.entries()) {
 				const firstTerm = command[0];
 				if (firstTerm?.type === "command" && isUsageHidden(firstTerm.hidden)) continue;
-				if (usage.length > 1) command = [...usage.slice(0, -1), ...command];
-				lines.push(formatUsage(programName, command, options));
+				const line = normalizeUsage(filterUsageForDisplay([...usage.slice(0, -1), ...command]));
+				lines.push(formatUsageLines(programName, line, declaredBranches == null ? line : normalizeUsage(filterUsageForDisplay([...declared.slice(0, -1), ...declaredBranches[index]])), options));
 			}
 			if (lines.length > 0) return lines.join("\n");
 		}
@@ -277,7 +301,8 @@ function normalizeUsageTerm(term) {
 	} else if (term.type === "multiple") return {
 		type: "multiple",
 		terms: normalizeUsage(term.terms),
-		min: term.min
+		min: term.min,
+		...acceptsEmptyOf(term)
 	};
 	else if (term.type === "sequence") return {
 		type: "sequence",
@@ -287,14 +312,15 @@ function normalizeUsageTerm(term) {
 		const terms = [];
 		for (const usage of term.terms) {
 			const normalized = normalizeUsage(usage);
-			if (normalized.length >= 1 && normalized[0].type === "exclusive") {
+			if (normalized.length >= 1 && normalized[0].type === "exclusive" && normalized[0].acceptsEmpty == null) {
 				const rest = normalized.slice(1);
 				for (const subUsage of normalized[0].terms) terms.push([...subUsage, ...rest]);
 			} else if (normalized.length > 0 || !containsMalformedLeaf(usage)) terms.push(normalized);
 		}
 		return {
 			type: "exclusive",
-			terms
+			terms,
+			...acceptsEmptyOf(term)
 		};
 	} else {
 		if (term.type === "option") return {
@@ -311,10 +337,14 @@ function normalizeUsageTerm(term) {
 		return { ...term };
 	}
 }
+function acceptsEmptyOf(term) {
+	return term.acceptsEmpty == null ? {} : { acceptsEmpty: term.acceptsEmpty };
+}
 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 === "multiple" || term.type === "exclusive") && term.acceptsEmpty != null) return true;
 	if (term.type === "optional" || term.type === "multiple" || term.type === "exclusive" || term.type === "sequence") return term.terms.length > 0;
 	return true;
 }
@@ -370,11 +400,13 @@ function cloneUsageTerm(term) {
 		case "multiple": return {
 			type: "multiple",
 			terms: term.terms.map(cloneUsageTerm),
-			min: term.min
+			min: term.min,
+			...acceptsEmptyOf(term)
 		};
 		case "exclusive": return {
 			type: "exclusive",
-			terms: term.terms.map((u) => u.map(cloneUsageTerm))
+			terms: term.terms.map((u) => u.map(cloneUsageTerm)),
+			...acceptsEmptyOf(term)
 		};
 		case "sequence": return {
 			type: "sequence",
@@ -416,7 +448,8 @@ function filterUsageForDisplay(usage, isHidden = isUsageHidden) {
 			if (filtered.length > 0) terms.push({
 				type: "multiple",
 				terms: filtered,
-				min: term.min
+				min: term.min,
+				...acceptsEmptyOf(term)
 			});
 			continue;
 		}
@@ -428,7 +461,8 @@ function filterUsageForDisplay(usage, isHidden = isUsageHidden) {
 			}).filter((branch) => branch.length > 0);
 			if (filteredBranches.length > 0) terms.push({
 				type: "exclusive",
-				terms: filteredBranches
+				terms: filteredBranches,
+				...acceptsEmptyOf(term)
 			});
 			continue;
 		}
@@ -482,7 +516,7 @@ function formatUsageTerm(term, options = {}) {
 		theme: require_terminal_internal.cacheTerminalTheme(options.theme)
 	};
 	const hiddenCheck = options.context === "doc" ? isDocHidden : isUsageHidden;
-	const visibleTerms = filterUsageForDisplay([term], hiddenCheck);
+	const visibleTerms = filterUsageForDisplay(require_internal_usage.resolveUsageForDisplay([term], hiddenCheck), hiddenCheck);
 	if (visibleTerms.length < 1) return "";
 	return wrapUsageTokens(formatUsageTermInternal(visibleTerms[0], options), options);
 }

package/dist/usage.d.cts

@@ -164,6 +164,16 @@ type UsageTerm =
    * The minimum number of times the term must occur.
    */
   readonly min: number;
+  /**
+   * Whether the parser that produced this group succeeds when it parses an
+   * empty argument list on its own.  Built-in combinators set this when
+   * the outcome is statically known and omit it otherwise.  Usage
+   * formatters use it to decide whether to draw the group as omissible;
+   * it is a declaration for display, not evidence about how any other
+   * parser behaves.
+   * @since 1.4.0
+   */
+  readonly acceptsEmpty?: boolean;
 } |
 /**
 * An exclusive term, which represents a group of terms that are mutually
@@ -180,6 +190,16 @@ type UsageTerm =
    * arguments, options, commands, or other usage terms.
    */
   readonly terms: readonly Usage[];
+  /**
+   * Whether the parser that produced this group succeeds when it parses an
+   * empty argument list on its own.  Built-in combinators set this when
+   * the outcome is statically known and omit it otherwise.  Usage
+   * formatters use it to decide whether to draw the group as omissible;
+   * it is a declaration for display, not evidence about how any other
+   * parser behaves.
+   * @since 1.4.0
+   */
+  readonly acceptsEmpty?: boolean;
 }
 /**
  * A sequence term, which preserves the declaration order of its child

package/dist/usage.d.ts

@@ -164,6 +164,16 @@ type UsageTerm =
    * The minimum number of times the term must occur.
    */
   readonly min: number;
+  /**
+   * Whether the parser that produced this group succeeds when it parses an
+   * empty argument list on its own.  Built-in combinators set this when
+   * the outcome is statically known and omit it otherwise.  Usage
+   * formatters use it to decide whether to draw the group as omissible;
+   * it is a declaration for display, not evidence about how any other
+   * parser behaves.
+   * @since 1.4.0
+   */
+  readonly acceptsEmpty?: boolean;
 } |
 /**
 * An exclusive term, which represents a group of terms that are mutually
@@ -180,6 +190,16 @@ type UsageTerm =
    * arguments, options, commands, or other usage terms.
    */
   readonly terms: readonly Usage[];
+  /**
+   * Whether the parser that produced this group succeeds when it parses an
+   * empty argument list on its own.  Built-in combinators set this when
+   * the outcome is statically known and omit it otherwise.  Usage
+   * formatters use it to decide whether to draw the group as omissible;
+   * it is a declaration for display, not evidence about how any other
+   * parser behaves.
+   * @since 1.4.0
+   */
+  readonly acceptsEmpty?: boolean;
 }
 /**
  * A sequence term, which preserves the declaration order of its child

package/dist/usage.js

@@ -1,5 +1,6 @@
 import { getDisplayWidth } from "./displaywidth.js";
 import { cacheTerminalTheme, formatTerminalLeaf, fragmentTokens, serializeTokens } from "./terminal-internal.js";
+import { forgetEmptyInput, resolveUsageForDisplay } from "./internal/usage.js";
 import { validateProgramName } from "./validate.js";
 
 //#region src/usage.ts
@@ -190,16 +191,39 @@ function formatUsage(programName, usage, options = {}) {
 		theme: cacheTerminalTheme(options.theme)
 	};
 	validateProgramName(programName);
-	usage = normalizeUsage(filterUsageForDisplay(usage));
+	return formatUsageLines(programName, normalizeUsage(filterUsageForDisplay(resolveUsageForDisplay(usage, isUsageHidden))), normalizeUsage(filterUsageForDisplay(forgetEmptyInput(usage))), options);
+}
+/**
+* Formats a display-ready usage, expanding a trailing command group into one
+* line per command when requested.
+* @param programName The program name.
+* @param usage The usage to draw, already resolved, filtered and normalized.
+* @param declared The same usage as declared, without empty-input records,
+*                 filtered and normalized.  It tells a group that was drawn
+*                 as optional because it accepts empty input apart from a
+*                 group declared optional.
+* @param options The formatting options.
+* @returns The formatted usage.
+*/
+function formatUsageLines(programName, usage, declared, options) {
 	if (options.expandCommands) {
-		const lastTerm = usage.at(-1);
+		let lastTerm = usage.at(-1);
+		const declaredLast = declared.at(-1);
+		if (lastTerm?.type === "optional" && declaredLast?.type === "exclusive") {
+			if (lastTerm.terms.length === 1 && lastTerm.terms[0].type === "exclusive") lastTerm = lastTerm.terms[0];
+			else if (lastTerm.terms[0]?.type === "command") lastTerm = {
+				type: "exclusive",
+				terms: [lastTerm.terms]
+			};
+		}
 		if (usage.length > 0 && usage.slice(0, -1).every((t) => t.type === "command") && lastTerm.type === "exclusive" && lastTerm.terms.every((t) => t.length > 0 && (t[0].type === "command" || t[0].type === "option" || t[0].type === "argument" || t[0].type === "optional" && t[0].terms.length === 1 && (t[0].terms[0].type === "command" || t[0].terms[0].type === "option" || t[0].terms[0].type === "argument")))) {
+			const declaredBranches = declaredLast?.type === "exclusive" && declaredLast.terms.length === lastTerm.terms.length ? declaredLast.terms : void 0;
 			const lines = [];
-			for (let command of lastTerm.terms) {
+			for (const [index, command] of lastTerm.terms.entries()) {
 				const firstTerm = command[0];
 				if (firstTerm?.type === "command" && isUsageHidden(firstTerm.hidden)) continue;
-				if (usage.length > 1) command = [...usage.slice(0, -1), ...command];
-				lines.push(formatUsage(programName, command, options));
+				const line = normalizeUsage(filterUsageForDisplay([...usage.slice(0, -1), ...command]));
+				lines.push(formatUsageLines(programName, line, declaredBranches == null ? line : normalizeUsage(filterUsageForDisplay([...declared.slice(0, -1), ...declaredBranches[index]])), options));
 			}
 			if (lines.length > 0) return lines.join("\n");
 		}
@@ -277,7 +301,8 @@ function normalizeUsageTerm(term) {
 	} else if (term.type === "multiple") return {
 		type: "multiple",
 		terms: normalizeUsage(term.terms),
-		min: term.min
+		min: term.min,
+		...acceptsEmptyOf(term)
 	};
 	else if (term.type === "sequence") return {
 		type: "sequence",
@@ -287,14 +312,15 @@ function normalizeUsageTerm(term) {
 		const terms = [];
 		for (const usage of term.terms) {
 			const normalized = normalizeUsage(usage);
-			if (normalized.length >= 1 && normalized[0].type === "exclusive") {
+			if (normalized.length >= 1 && normalized[0].type === "exclusive" && normalized[0].acceptsEmpty == null) {
 				const rest = normalized.slice(1);
 				for (const subUsage of normalized[0].terms) terms.push([...subUsage, ...rest]);
 			} else if (normalized.length > 0 || !containsMalformedLeaf(usage)) terms.push(normalized);
 		}
 		return {
 			type: "exclusive",
-			terms
+			terms,
+			...acceptsEmptyOf(term)
 		};
 	} else {
 		if (term.type === "option") return {
@@ -311,10 +337,14 @@ function normalizeUsageTerm(term) {
 		return { ...term };
 	}
 }
+function acceptsEmptyOf(term) {
+	return term.acceptsEmpty == null ? {} : { acceptsEmpty: term.acceptsEmpty };
+}
 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 === "multiple" || term.type === "exclusive") && term.acceptsEmpty != null) return true;
 	if (term.type === "optional" || term.type === "multiple" || term.type === "exclusive" || term.type === "sequence") return term.terms.length > 0;
 	return true;
 }
@@ -370,11 +400,13 @@ function cloneUsageTerm(term) {
 		case "multiple": return {
 			type: "multiple",
 			terms: term.terms.map(cloneUsageTerm),
-			min: term.min
+			min: term.min,
+			...acceptsEmptyOf(term)
 		};
 		case "exclusive": return {
 			type: "exclusive",
-			terms: term.terms.map((u) => u.map(cloneUsageTerm))
+			terms: term.terms.map((u) => u.map(cloneUsageTerm)),
+			...acceptsEmptyOf(term)
 		};
 		case "sequence": return {
 			type: "sequence",
@@ -416,7 +448,8 @@ function filterUsageForDisplay(usage, isHidden = isUsageHidden) {
 			if (filtered.length > 0) terms.push({
 				type: "multiple",
 				terms: filtered,
-				min: term.min
+				min: term.min,
+				...acceptsEmptyOf(term)
 			});
 			continue;
 		}
@@ -428,7 +461,8 @@ function filterUsageForDisplay(usage, isHidden = isUsageHidden) {
 			}).filter((branch) => branch.length > 0);
 			if (filteredBranches.length > 0) terms.push({
 				type: "exclusive",
-				terms: filteredBranches
+				terms: filteredBranches,
+				...acceptsEmptyOf(term)
 			});
 			continue;
 		}
@@ -482,7 +516,7 @@ function formatUsageTerm(term, options = {}) {
 		theme: cacheTerminalTheme(options.theme)
 	};
 	const hiddenCheck = options.context === "doc" ? isDocHidden : isUsageHidden;
-	const visibleTerms = filterUsageForDisplay([term], hiddenCheck);
+	const visibleTerms = filterUsageForDisplay(resolveUsageForDisplay([term], hiddenCheck), hiddenCheck);
 	if (visibleTerms.length < 1) return "";
 	return wrapUsageTokens(formatUsageTermInternal(visibleTerms[0], options), options);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.4.0-dev.2708",
+  "version": "1.4.0-dev.2711",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -227,6 +227,14 @@
       },
       "import": "./dist/internal/terminal.js",
       "require": "./dist/internal/terminal.cjs"
+    },
+    "./internal/usage": {
+      "types": {
+        "import": "./dist/internal/usage.d.ts",
+        "require": "./dist/internal/usage.d.cts"
+      },
+      "import": "./dist/internal/usage.js",
+      "require": "./dist/internal/usage.cjs"
     }
   },
   "imports": {
@@ -237,7 +245,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.4.0-dev.2708+0119545d",
+    "@optique/env": "1.4.0-dev.2711+fda80c51",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",