@optique/core 1.0.15 → 1.0.16-dev.2975

package/dist/completion.cjs

@@ -1451,7 +1451,7 @@ const fish = {
 	name: "fish",
 	generateScript(programName, args = []) {
 		validateProgramName(programName);
-		const escapedArgs = args.map((arg) => `'${arg.replace(/'/g, "\\'")}'`).join(" ");
+		const escapedArgs = args.map((arg) => `'${arg.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`).join(" ");
 		const functionName = `__${programName}_complete`;
 		return `
 function ${functionName}

package/dist/completion.js

@@ -1451,7 +1451,7 @@ const fish = {
 	name: "fish",
 	generateScript(programName, args = []) {
 		validateProgramName(programName);
-		const escapedArgs = args.map((arg) => `'${arg.replace(/'/g, "\\'")}'`).join(" ");
+		const escapedArgs = args.map((arg) => `'${arg.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`).join(" ");
 		const functionName = `__${programName}_complete`;
 		return `
 function ${functionName}

package/dist/constructs.cjs

@@ -1,5 +1,6 @@
 const require_annotations = require('./internal/annotations.cjs');
 const require_message = require('./message.cjs');
+const require_command_usage = require('./internal/command-usage.cjs');
 const require_command_doc_metadata = require('./internal/command-doc-metadata.cjs');
 const require_passthrough = require('./internal/passthrough.cjs');
 const require_validate = require('./validate.cjs');
@@ -382,10 +383,10 @@ function applyHiddenToUsageTerm(term, hidden) {
 		type: "exclusive",
 		terms: term.terms.map((u) => applyHiddenToUsage(u, hidden))
 	};
-	if (term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") return {
+	if (term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") return require_command_usage.copyCommandUsageId(term, {
 		...term,
 		hidden: require_usage.mergeHidden(term.hidden, hidden)
-	};
+	});
 	return term;
 }
 function applyHiddenToUsage(usage, hidden) {
@@ -1252,6 +1253,7 @@ function or(...args) {
 			success: false
 		};
 	};
+	const commandUsageScopes = parsers.map(() => /* @__PURE__ */ new WeakMap());
 	const singleResult = {
 		mode: combinedMode,
 		$valueType: [],
@@ -1259,7 +1261,7 @@ function or(...args) {
 		priority: Math.max(...parsers.map((p) => p.priority)),
 		usage: [{
 			type: "exclusive",
-			terms: parsers.map((p) => p.usage)
+			terms: parsers.map((p, i) => require_command_usage.scopeCommandUsage(p.usage, commandUsageScopes[i]))
 		}],
 		leadingNames: unionLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
@@ -1289,7 +1291,7 @@ function or(...args) {
 					state: parserResult.next.state
 				} : { kind: "unavailable" };
 				const docFragments = parsers[index].getDocFragments(innerState, void 0);
-				commandMetadata = require_command_doc_metadata.getCommandDocMetadata(docFragments);
+				commandMetadata = require_command_doc_metadata.scopeCommandDocMetadata(require_command_doc_metadata.getCommandDocMetadata(docFragments), commandUsageScopes[index]);
 				brief = docFragments.brief;
 				description = docFragments.description;
 				footer = docFragments.footer;
@@ -1480,6 +1482,7 @@ function longestMatch(...args) {
 			success: false
 		};
 	};
+	const commandUsageScopes = parsers.map(() => /* @__PURE__ */ new WeakMap());
 	const multiResult = {
 		mode: combinedMode,
 		$valueType: [],
@@ -1487,7 +1490,7 @@ function longestMatch(...args) {
 		priority: Math.max(...parsers.map((p) => p.priority)),
 		usage: [{
 			type: "exclusive",
-			terms: parsers.map((p) => p.usage)
+			terms: parsers.map((p, i) => require_command_usage.scopeCommandUsage(p.usage, commandUsageScopes[i]))
 		}],
 		leadingNames: unionLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
@@ -1520,7 +1523,7 @@ function longestMatch(...args) {
 						kind: "available",
 						state: result.next.state
 					});
-					commandMetadata = require_command_doc_metadata.getCommandDocMetadata(docResult);
+					commandMetadata = require_command_doc_metadata.scopeCommandDocMetadata(require_command_doc_metadata.getCommandDocMetadata(docResult), commandUsageScopes[i]);
 					brief = docResult.brief;
 					description = docResult.description;
 					footer = docResult.footer;
@@ -2231,13 +2234,14 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			success: false
 		};
 	};
+	const commandUsageScopes = new Map(parserPairs.map(([field]) => [field, /* @__PURE__ */ new WeakMap()]));
 	const objectParser = {
 		mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		[fieldParsersKey]: parserPairs,
 		priority: Math.max(...parserKeys.map((k) => parsers[k].priority)),
-		usage: applyHiddenToUsage(parserPairs.flatMap(([_, p]) => p.usage), options.hidden),
+		usage: applyHiddenToUsage(parserPairs.flatMap(([field, p]) => require_command_usage.scopeCommandUsage(p.usage, commandUsageScopes.get(field))), options.hidden),
 		leadingNames: sharedBufferLeadingNames(parserPairs.map(([_, p]) => p)),
 		acceptingAnyToken: parserPairs.some(([_, p]) => p.acceptingAnyToken),
 		get initialState() {
@@ -2489,7 +2493,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					state: state.state[field]
 				};
 				const docs = p.getDocFragments(fieldState, defaultValue?.[field]);
-				commandMetadata = require_command_doc_metadata.collectCommandDocMetadata(commandMetadata, docs);
+				commandMetadata = require_command_doc_metadata.collectCommandDocMetadata(commandMetadata, docs, false, commandUsageScopes.get(field));
 				return docs.fragments;
 			});
 			const hiddenAwareFragments = applyHiddenToDocFragments(fragments, options.hidden);
@@ -2946,12 +2950,16 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			consumed: allConsumed
 		};
 	};
+	const commandUsageScopes = parsers.map(() => /* @__PURE__ */ new WeakMap());
 	const tupleParser = {
 		mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		[fieldParsersKey]: parsers.map((parser, index) => [String(index), parser]),
-		usage: parsers.toSorted((a, b) => b.priority - a.priority).flatMap((p) => p.usage),
+		usage: parsers.map((p, i) => ({
+			p,
+			i
+		})).toSorted((a, b) => b.p.priority - a.p.priority).flatMap(({ p, i }) => require_command_usage.scopeCommandUsage(p.usage, commandUsageScopes[i])),
 		leadingNames: sharedBufferLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		priority: parsers.length > 0 ? Math.max(...parsers.map((p) => p.priority)) : 0,
@@ -3144,7 +3152,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					state: state.state[i]
 				};
 				const docs = p.getDocFragments(indexState, defaultValue?.[i]);
-				commandMetadata = require_command_doc_metadata.collectCommandDocMetadata(commandMetadata, docs);
+				commandMetadata = require_command_doc_metadata.collectCommandDocMetadata(commandMetadata, docs, false, commandUsageScopes[i]);
 				return docs.fragments;
 			});
 			const entries = fragments.filter((d) => d.type === "entry");
@@ -3638,13 +3646,14 @@ function merge(...args) {
 			consumed: allConsumed
 		};
 	};
+	const commandUsageScopes = parsers.map(() => /* @__PURE__ */ new WeakMap());
 	const mergeParser = {
 		mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		[fieldParsersKey]: mergedFieldParsers,
 		priority: Math.max(...mergeParseLanes.map((lane) => lane.priority)),
-		usage: applyHiddenToUsage(parsers.flatMap((p) => p.usage), options.hidden),
+		usage: applyHiddenToUsage(parsers.flatMap((p, i) => require_command_usage.scopeCommandUsage(p.usage, commandUsageScopes[i])), options.hidden),
 		leadingNames: sharedBufferLeadingNames(mergeParseLanes),
 		acceptingAnyToken: mergeParseLanes.some((lane) => lane.acceptingAnyToken),
 		initialState,
@@ -4073,7 +4082,7 @@ function merge(...args) {
 					state: state.state
 				};
 				const docFragments = p.getDocFragments(parserState, void 0);
-				commandMetadata = require_command_doc_metadata.collectCommandDocMetadata(commandMetadata, docFragments, true);
+				commandMetadata = require_command_doc_metadata.collectCommandDocMetadata(commandMetadata, docFragments, true, commandUsageScopes[i]);
 				brief ??= docFragments.brief;
 				description ??= docFragments.description;
 				footer ??= docFragments.footer;
@@ -4610,12 +4619,13 @@ function concat(...parsers) {
 			} : {}
 		};
 	};
+	const commandUsageScopes = parsers.map(() => /* @__PURE__ */ new WeakMap());
 	const concatParser = {
 		mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		priority: parsers.length > 0 ? Math.max(...parsers.map((p) => p.priority)) : 0,
-		usage: parsers.flatMap((p) => p.usage),
+		usage: parsers.flatMap((p, i) => require_command_usage.scopeCommandUsage(p.usage, commandUsageScopes[i])),
 		leadingNames: sharedBufferLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState,
@@ -4733,7 +4743,7 @@ function concat(...parsers) {
 					state: state.state[index]
 				};
 				const docs = p.getDocFragments(indexState, void 0);
-				commandMetadata = require_command_doc_metadata.collectCommandDocMetadata(commandMetadata, docs);
+				commandMetadata = require_command_doc_metadata.collectCommandDocMetadata(commandMetadata, docs, false, commandUsageScopes[index]);
 				return docs.fragments;
 			});
 			const entries = fragments.filter((f) => f.type === "entry");
@@ -4944,8 +4954,12 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		else result.push(term);
 		return result;
 	}
-	const branchUsages = branchParsers.map(([key, p]) => [...appendLiteralToUsage(discriminator.usage, key), ...p.usage]);
-	if (defaultBranch) branchUsages.push(defaultBranch.usage);
+	const discriminatorUsageScope = /* @__PURE__ */ new WeakMap();
+	const branchUsageScope = /* @__PURE__ */ new WeakMap();
+	const commandUsageScopes = new Map(branchParsers.map(([key]) => [key, /* @__PURE__ */ new WeakMap()]));
+	const defaultUsageScope = /* @__PURE__ */ new WeakMap();
+	const branchUsages = branchParsers.map(([key, p]) => require_command_usage.scopeCommandUsage([...appendLiteralToUsage(require_command_usage.scopeCommandUsage(discriminator.usage, discriminatorUsageScope), key), ...require_command_usage.scopeCommandUsage(p.usage, branchUsageScope)], commandUsageScopes.get(key)));
+	if (defaultBranch) branchUsages.push(require_command_usage.scopeCommandUsage(defaultBranch.usage, defaultUsageScope));
 	const usage = branchUsages.length > 1 ? [{
 		type: "exclusive",
 		terms: branchUsages
@@ -5795,7 +5809,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			if (isAsync) return suggestAsync(context, prefix);
 			return suggestSync(context, prefix);
 		},
-		getDocFragments(_state, _defaultValue) {
+		getDocFragments(state, _defaultValue) {
 			const fragments = [];
 			const discriminatorFragments = discriminator.getDocFragments({ kind: "unavailable" }, void 0);
 			fragments.push(...discriminatorFragments.fragments);
@@ -5819,7 +5833,27 @@ function conditional(discriminator, branches, defaultBranch, options) {
 					entries
 				});
 			}
-			return { fragments };
+			let selected = require_command_doc_metadata.getSelectedCommandUsage(void 0);
+			if (state.kind === "available" && state.state.selectedBranch != null) {
+				const selection = state.state.selectedBranch;
+				const branch = selection.kind === "default" ? defaultBranch : branches[selection.key];
+				if (branch != null) {
+					const docs = branch.getDocFragments({
+						kind: "available",
+						state: require_annotation_state.getWrappedChildState(state.state, state.state.branchState, branch)
+					}, void 0);
+					if (selection.kind === "default") selected = require_command_doc_metadata.getSelectedCommandUsage(require_command_doc_metadata.scopeCommandDocMetadata(require_command_doc_metadata.getCommandDocMetadata(docs), defaultUsageScope));
+					else {
+						const discriminatorDocs = discriminator.getDocFragments({
+							kind: "available",
+							state: require_annotation_state.getWrappedChildState(state.state, state.state.discriminatorState, discriminator)
+						}, void 0);
+						const metadata = require_command_doc_metadata.collectCommandDocMetadata(require_command_doc_metadata.scopeCommandDocMetadata(require_command_doc_metadata.getCommandDocMetadata(discriminatorDocs), discriminatorUsageScope), docs, false, branchUsageScope);
+						selected = require_command_doc_metadata.getSelectedCommandUsage(require_command_doc_metadata.scopeCommandDocMetadata(metadata, commandUsageScopes.get(selection.key)));
+					}
+				}
+			}
+			return require_command_doc_metadata.withCommandDocMetadata({ fragments }, require_command_doc_metadata.withSelectedCommandUsage({}, selected));
 		}
 	};
 	require_parser.defineInheritedAnnotationParser(conditionalParser);

package/dist/constructs.js

@@ -1,6 +1,7 @@
 import { annotateFreshArray, getAnnotations, inheritAnnotations } from "./internal/annotations.js";
 import { message, optionName, text, values } from "./message.js";
-import { collectCommandDocMetadata, getCommandDocMetadata, withCommandDocMetadata } from "./internal/command-doc-metadata.js";
+import { copyCommandUsageId, scopeCommandUsage } from "./internal/command-usage.js";
+import { collectCommandDocMetadata, getCommandDocMetadata, getSelectedCommandUsage, scopeCommandDocMetadata, withCommandDocMetadata, withSelectedCommandUsage } from "./internal/command-doc-metadata.js";
 import { combineOptionMatches, combinePassThroughPriorities, defineOptionMatch, definePassThroughPriority, delegateKnownCompletion, getKnownCompletion, getOptionMatch, getPassThroughFailureHint, getPassThroughPriority, hasPassThroughUsage, matchesOptionToken, retainConsumingFailure, retainConsumingFailureHint, withPassThroughFailure } from "./internal/passthrough.js";
 import { validateLabel } from "./validate.js";
 import { extractArgumentMetavars, extractCommandNames, extractOptionNames, isDocHidden, mergeHidden } from "./usage.js";
@@ -382,10 +383,10 @@ function applyHiddenToUsageTerm(term, hidden) {
 		type: "exclusive",
 		terms: term.terms.map((u) => applyHiddenToUsage(u, hidden))
 	};
-	if (term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") return {
+	if (term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") return copyCommandUsageId(term, {
 		...term,
 		hidden: mergeHidden(term.hidden, hidden)
-	};
+	});
 	return term;
 }
 function applyHiddenToUsage(usage, hidden) {
@@ -1252,6 +1253,7 @@ function or(...args) {
 			success: false
 		};
 	};
+	const commandUsageScopes = parsers.map(() => /* @__PURE__ */ new WeakMap());
 	const singleResult = {
 		mode: combinedMode,
 		$valueType: [],
@@ -1259,7 +1261,7 @@ function or(...args) {
 		priority: Math.max(...parsers.map((p) => p.priority)),
 		usage: [{
 			type: "exclusive",
-			terms: parsers.map((p) => p.usage)
+			terms: parsers.map((p, i) => scopeCommandUsage(p.usage, commandUsageScopes[i]))
 		}],
 		leadingNames: unionLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
@@ -1289,7 +1291,7 @@ function or(...args) {
 					state: parserResult.next.state
 				} : { kind: "unavailable" };
 				const docFragments = parsers[index].getDocFragments(innerState, void 0);
-				commandMetadata = getCommandDocMetadata(docFragments);
+				commandMetadata = scopeCommandDocMetadata(getCommandDocMetadata(docFragments), commandUsageScopes[index]);
 				brief = docFragments.brief;
 				description = docFragments.description;
 				footer = docFragments.footer;
@@ -1480,6 +1482,7 @@ function longestMatch(...args) {
 			success: false
 		};
 	};
+	const commandUsageScopes = parsers.map(() => /* @__PURE__ */ new WeakMap());
 	const multiResult = {
 		mode: combinedMode,
 		$valueType: [],
@@ -1487,7 +1490,7 @@ function longestMatch(...args) {
 		priority: Math.max(...parsers.map((p) => p.priority)),
 		usage: [{
 			type: "exclusive",
-			terms: parsers.map((p) => p.usage)
+			terms: parsers.map((p, i) => scopeCommandUsage(p.usage, commandUsageScopes[i]))
 		}],
 		leadingNames: unionLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
@@ -1520,7 +1523,7 @@ function longestMatch(...args) {
 						kind: "available",
 						state: result.next.state
 					});
-					commandMetadata = getCommandDocMetadata(docResult);
+					commandMetadata = scopeCommandDocMetadata(getCommandDocMetadata(docResult), commandUsageScopes[i]);
 					brief = docResult.brief;
 					description = docResult.description;
 					footer = docResult.footer;
@@ -2231,13 +2234,14 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			success: false
 		};
 	};
+	const commandUsageScopes = new Map(parserPairs.map(([field]) => [field, /* @__PURE__ */ new WeakMap()]));
 	const objectParser = {
 		mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		[fieldParsersKey]: parserPairs,
 		priority: Math.max(...parserKeys.map((k) => parsers[k].priority)),
-		usage: applyHiddenToUsage(parserPairs.flatMap(([_, p]) => p.usage), options.hidden),
+		usage: applyHiddenToUsage(parserPairs.flatMap(([field, p]) => scopeCommandUsage(p.usage, commandUsageScopes.get(field))), options.hidden),
 		leadingNames: sharedBufferLeadingNames(parserPairs.map(([_, p]) => p)),
 		acceptingAnyToken: parserPairs.some(([_, p]) => p.acceptingAnyToken),
 		get initialState() {
@@ -2489,7 +2493,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					state: state.state[field]
 				};
 				const docs = p.getDocFragments(fieldState, defaultValue?.[field]);
-				commandMetadata = collectCommandDocMetadata(commandMetadata, docs);
+				commandMetadata = collectCommandDocMetadata(commandMetadata, docs, false, commandUsageScopes.get(field));
 				return docs.fragments;
 			});
 			const hiddenAwareFragments = applyHiddenToDocFragments(fragments, options.hidden);
@@ -2946,12 +2950,16 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			consumed: allConsumed
 		};
 	};
+	const commandUsageScopes = parsers.map(() => /* @__PURE__ */ new WeakMap());
 	const tupleParser = {
 		mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		[fieldParsersKey]: parsers.map((parser, index) => [String(index), parser]),
-		usage: parsers.toSorted((a, b) => b.priority - a.priority).flatMap((p) => p.usage),
+		usage: parsers.map((p, i) => ({
+			p,
+			i
+		})).toSorted((a, b) => b.p.priority - a.p.priority).flatMap(({ p, i }) => scopeCommandUsage(p.usage, commandUsageScopes[i])),
 		leadingNames: sharedBufferLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		priority: parsers.length > 0 ? Math.max(...parsers.map((p) => p.priority)) : 0,
@@ -3144,7 +3152,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					state: state.state[i]
 				};
 				const docs = p.getDocFragments(indexState, defaultValue?.[i]);
-				commandMetadata = collectCommandDocMetadata(commandMetadata, docs);
+				commandMetadata = collectCommandDocMetadata(commandMetadata, docs, false, commandUsageScopes[i]);
 				return docs.fragments;
 			});
 			const entries = fragments.filter((d) => d.type === "entry");
@@ -3638,13 +3646,14 @@ function merge(...args) {
 			consumed: allConsumed
 		};
 	};
+	const commandUsageScopes = parsers.map(() => /* @__PURE__ */ new WeakMap());
 	const mergeParser = {
 		mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		[fieldParsersKey]: mergedFieldParsers,
 		priority: Math.max(...mergeParseLanes.map((lane) => lane.priority)),
-		usage: applyHiddenToUsage(parsers.flatMap((p) => p.usage), options.hidden),
+		usage: applyHiddenToUsage(parsers.flatMap((p, i) => scopeCommandUsage(p.usage, commandUsageScopes[i])), options.hidden),
 		leadingNames: sharedBufferLeadingNames(mergeParseLanes),
 		acceptingAnyToken: mergeParseLanes.some((lane) => lane.acceptingAnyToken),
 		initialState,
@@ -4073,7 +4082,7 @@ function merge(...args) {
 					state: state.state
 				};
 				const docFragments = p.getDocFragments(parserState, void 0);
-				commandMetadata = collectCommandDocMetadata(commandMetadata, docFragments, true);
+				commandMetadata = collectCommandDocMetadata(commandMetadata, docFragments, true, commandUsageScopes[i]);
 				brief ??= docFragments.brief;
 				description ??= docFragments.description;
 				footer ??= docFragments.footer;
@@ -4610,12 +4619,13 @@ function concat(...parsers) {
 			} : {}
 		};
 	};
+	const commandUsageScopes = parsers.map(() => /* @__PURE__ */ new WeakMap());
 	const concatParser = {
 		mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		priority: parsers.length > 0 ? Math.max(...parsers.map((p) => p.priority)) : 0,
-		usage: parsers.flatMap((p) => p.usage),
+		usage: parsers.flatMap((p, i) => scopeCommandUsage(p.usage, commandUsageScopes[i])),
 		leadingNames: sharedBufferLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState,
@@ -4733,7 +4743,7 @@ function concat(...parsers) {
 					state: state.state[index]
 				};
 				const docs = p.getDocFragments(indexState, void 0);
-				commandMetadata = collectCommandDocMetadata(commandMetadata, docs);
+				commandMetadata = collectCommandDocMetadata(commandMetadata, docs, false, commandUsageScopes[index]);
 				return docs.fragments;
 			});
 			const entries = fragments.filter((f) => f.type === "entry");
@@ -4944,8 +4954,12 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		else result.push(term);
 		return result;
 	}
-	const branchUsages = branchParsers.map(([key, p]) => [...appendLiteralToUsage(discriminator.usage, key), ...p.usage]);
-	if (defaultBranch) branchUsages.push(defaultBranch.usage);
+	const discriminatorUsageScope = /* @__PURE__ */ new WeakMap();
+	const branchUsageScope = /* @__PURE__ */ new WeakMap();
+	const commandUsageScopes = new Map(branchParsers.map(([key]) => [key, /* @__PURE__ */ new WeakMap()]));
+	const defaultUsageScope = /* @__PURE__ */ new WeakMap();
+	const branchUsages = branchParsers.map(([key, p]) => scopeCommandUsage([...appendLiteralToUsage(scopeCommandUsage(discriminator.usage, discriminatorUsageScope), key), ...scopeCommandUsage(p.usage, branchUsageScope)], commandUsageScopes.get(key)));
+	if (defaultBranch) branchUsages.push(scopeCommandUsage(defaultBranch.usage, defaultUsageScope));
 	const usage = branchUsages.length > 1 ? [{
 		type: "exclusive",
 		terms: branchUsages
@@ -5795,7 +5809,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			if (isAsync) return suggestAsync(context, prefix);
 			return suggestSync(context, prefix);
 		},
-		getDocFragments(_state, _defaultValue) {
+		getDocFragments(state, _defaultValue) {
 			const fragments = [];
 			const discriminatorFragments = discriminator.getDocFragments({ kind: "unavailable" }, void 0);
 			fragments.push(...discriminatorFragments.fragments);
@@ -5819,7 +5833,27 @@ function conditional(discriminator, branches, defaultBranch, options) {
 					entries
 				});
 			}
-			return { fragments };
+			let selected = getSelectedCommandUsage(void 0);
+			if (state.kind === "available" && state.state.selectedBranch != null) {
+				const selection = state.state.selectedBranch;
+				const branch = selection.kind === "default" ? defaultBranch : branches[selection.key];
+				if (branch != null) {
+					const docs = branch.getDocFragments({
+						kind: "available",
+						state: getWrappedChildState(state.state, state.state.branchState, branch)
+					}, void 0);
+					if (selection.kind === "default") selected = getSelectedCommandUsage(scopeCommandDocMetadata(getCommandDocMetadata(docs), defaultUsageScope));
+					else {
+						const discriminatorDocs = discriminator.getDocFragments({
+							kind: "available",
+							state: getWrappedChildState(state.state, state.state.discriminatorState, discriminator)
+						}, void 0);
+						const metadata = collectCommandDocMetadata(scopeCommandDocMetadata(getCommandDocMetadata(discriminatorDocs), discriminatorUsageScope), docs, false, branchUsageScope);
+						selected = getSelectedCommandUsage(scopeCommandDocMetadata(metadata, commandUsageScopes.get(selection.key)));
+					}
+				}
+			}
+			return withCommandDocMetadata({ fragments }, withSelectedCommandUsage({}, selected));
 		}
 	};
 	defineInheritedAnnotationParser(conditionalParser);

package/dist/internal/command-doc-metadata.cjs

@@ -1,7 +1,24 @@
+const require_command_usage = require('./command-usage.cjs');
 
 //#region src/internal/command-doc-metadata.ts
+const selectedCommandUsage = /* @__PURE__ */ new WeakMap();
+/** Reads command occurrences selected by final parser state. @internal */
+function getSelectedCommandUsage(metadata) {
+	return metadata == null ? [] : selectedCommandUsage.get(metadata) ?? [];
+}
+/** Attaches selection without adding public metadata properties. @internal */
+function withSelectedCommandUsage(metadata, selected) {
+	const result = withOrigin(metadata ?? {}, metadata?.origin ?? "entry");
+	selectedCommandUsage.set(result, selected);
+	return result;
+}
+/** Maps selected commands to the same child scope as its usage. @internal */
+function scopeCommandDocMetadata(metadata, scope) {
+	return metadata == null ? void 0 : withSelectedCommandUsage(metadata, getSelectedCommandUsage(metadata).map((id) => require_command_usage.scopeCommandUsageId(scope, id)));
+}
 function withOrigin(metadata, origin) {
 	const result = { ...metadata };
+	selectedCommandUsage.set(result, getSelectedCommandUsage(metadata));
 	Object.defineProperty(result, "origin", {
 		value: origin,
 		enumerable: false
@@ -23,11 +40,11 @@ function getCommandDocMetadata(docs) {
 		const customPage = origin === "entry" && (docs.brief !== carrier.brief || docs.footer !== carrier.footer);
 		const description = origin === "entry" && !customPage || docs.description === carrier.description ? carrier.metadata.description : docs.description;
 		const footer = docs.footer === carrier.footer ? carrier.metadata.footer : docs.footer;
-		return withOrigin({
+		return withSelectedCommandUsage(withOrigin({
 			...brief == null ? {} : { brief },
 			...description == null ? {} : { description },
 			...footer == null ? {} : { footer }
-		}, customPage ? "custom" : origin);
+		}, customPage ? "custom" : origin), getSelectedCommandUsage(carrier.metadata));
 	}
 	const metadata = docs[commandDocMetadata];
 	if (metadata != null) return metadata;
@@ -67,7 +84,7 @@ function withCommandDocMetadata(docs, metadata) {
 * @param includeCustom Whether to retain custom page fields inside merge().
 * @returns The first defined value from children with the same origin.
 */
-function collectCommandDocMetadata(current, docs, includeCustom = false) {
+function collectCommandPageMetadata(current, docs, includeCustom = false) {
 	const next = getCommandDocMetadata(docs);
 	if (next == null) return current;
 	const origin = next.origin ?? "entry";
@@ -83,8 +100,19 @@ function collectCommandDocMetadata(current, docs, includeCustom = false) {
 		...footer == null ? {} : { footer }
 	}, origin);
 }
+/** Collects page fields and all selected command occurrences. @internal */
+function collectCommandDocMetadata(current, docs, includeCustom = false, scope) {
+	const next = getCommandDocMetadata(docs);
+	const selected = getSelectedCommandUsage(next);
+	const result = collectCommandPageMetadata(current, docs, includeCustom);
+	const combined = [...getSelectedCommandUsage(current), ...scope == null ? selected : selected.map((id) => require_command_usage.scopeCommandUsageId(scope, id))];
+	return combined.length === 0 ? result : withSelectedCommandUsage(result, combined);
+}
 
 //#endregion
 exports.collectCommandDocMetadata = collectCommandDocMetadata;
 exports.getCommandDocMetadata = getCommandDocMetadata;
-exports.withCommandDocMetadata = withCommandDocMetadata;
+exports.getSelectedCommandUsage = getSelectedCommandUsage;
+exports.scopeCommandDocMetadata = scopeCommandDocMetadata;
+exports.withCommandDocMetadata = withCommandDocMetadata;
+exports.withSelectedCommandUsage = withSelectedCommandUsage;

package/dist/internal/command-doc-metadata.js

@@ -1,6 +1,24 @@
+import { scopeCommandUsageId } from "./command-usage.js";
+
 //#region src/internal/command-doc-metadata.ts
+const selectedCommandUsage = /* @__PURE__ */ new WeakMap();
+/** Reads command occurrences selected by final parser state. @internal */
+function getSelectedCommandUsage(metadata) {
+	return metadata == null ? [] : selectedCommandUsage.get(metadata) ?? [];
+}
+/** Attaches selection without adding public metadata properties. @internal */
+function withSelectedCommandUsage(metadata, selected) {
+	const result = withOrigin(metadata ?? {}, metadata?.origin ?? "entry");
+	selectedCommandUsage.set(result, selected);
+	return result;
+}
+/** Maps selected commands to the same child scope as its usage. @internal */
+function scopeCommandDocMetadata(metadata, scope) {
+	return metadata == null ? void 0 : withSelectedCommandUsage(metadata, getSelectedCommandUsage(metadata).map((id) => scopeCommandUsageId(scope, id)));
+}
 function withOrigin(metadata, origin) {
 	const result = { ...metadata };
+	selectedCommandUsage.set(result, getSelectedCommandUsage(metadata));
 	Object.defineProperty(result, "origin", {
 		value: origin,
 		enumerable: false
@@ -22,11 +40,11 @@ function getCommandDocMetadata(docs) {
 		const customPage = origin === "entry" && (docs.brief !== carrier.brief || docs.footer !== carrier.footer);
 		const description = origin === "entry" && !customPage || docs.description === carrier.description ? carrier.metadata.description : docs.description;
 		const footer = docs.footer === carrier.footer ? carrier.metadata.footer : docs.footer;
-		return withOrigin({
+		return withSelectedCommandUsage(withOrigin({
 			...brief == null ? {} : { brief },
 			...description == null ? {} : { description },
 			...footer == null ? {} : { footer }
-		}, customPage ? "custom" : origin);
+		}, customPage ? "custom" : origin), getSelectedCommandUsage(carrier.metadata));
 	}
 	const metadata = docs[commandDocMetadata];
 	if (metadata != null) return metadata;
@@ -66,7 +84,7 @@ function withCommandDocMetadata(docs, metadata) {
 * @param includeCustom Whether to retain custom page fields inside merge().
 * @returns The first defined value from children with the same origin.
 */
-function collectCommandDocMetadata(current, docs, includeCustom = false) {
+function collectCommandPageMetadata(current, docs, includeCustom = false) {
 	const next = getCommandDocMetadata(docs);
 	if (next == null) return current;
 	const origin = next.origin ?? "entry";
@@ -82,6 +100,14 @@ function collectCommandDocMetadata(current, docs, includeCustom = false) {
 		...footer == null ? {} : { footer }
 	}, origin);
 }
+/** Collects page fields and all selected command occurrences. @internal */
+function collectCommandDocMetadata(current, docs, includeCustom = false, scope) {
+	const next = getCommandDocMetadata(docs);
+	const selected = getSelectedCommandUsage(next);
+	const result = collectCommandPageMetadata(current, docs, includeCustom);
+	const combined = [...getSelectedCommandUsage(current), ...scope == null ? selected : selected.map((id) => scopeCommandUsageId(scope, id))];
+	return combined.length === 0 ? result : withSelectedCommandUsage(result, combined);
+}
 
 //#endregion
-export { collectCommandDocMetadata, getCommandDocMetadata, withCommandDocMetadata };
+export { collectCommandDocMetadata, getCommandDocMetadata, getSelectedCommandUsage, scopeCommandDocMetadata, withCommandDocMetadata, withSelectedCommandUsage };

package/dist/internal/command-usage.cjs

@@ -0,0 +1,52 @@
+
+//#region src/internal/command-usage.ts
+const commandUsageIds = /* @__PURE__ */ new WeakMap();
+/** Associates a command usage leaf with its parser occurrence. @internal */
+function identifyCommandUsage(term, id) {
+	commandUsageIds.set(term, id);
+	return term;
+}
+/** Reads a command usage leaf's private identity. @internal */
+function getCommandUsageId(term) {
+	return commandUsageIds.get(term);
+}
+/** Preserves private identity when cloning a usage leaf. @internal */
+function copyCommandUsageId(source, target) {
+	const id = commandUsageIds.get(source);
+	if (id != null) commandUsageIds.set(target, id);
+	return target;
+}
+/** Distinguishes repeated uses of one parser in different children. @internal */
+function scopeCommandUsageId(scope, id) {
+	let scoped = scope.get(id);
+	if (scoped == null) {
+		scoped = {};
+		scope.set(id, scoped);
+	}
+	return scoped;
+}
+/** Copies usage with identities scoped to this child occurrence. @internal */
+function scopeCommandUsage(usage, scope) {
+	return usage.map((term) => {
+		if (term.type === "command") {
+			const id = getCommandUsageId(term);
+			return id == null ? term : identifyCommandUsage({ ...term }, scopeCommandUsageId(scope, id));
+		}
+		if (term.type === "optional" || term.type === "multiple") return {
+			...term,
+			terms: scopeCommandUsage(term.terms, scope)
+		};
+		if (term.type === "exclusive") return {
+			...term,
+			terms: term.terms.map((branch) => scopeCommandUsage(branch, scope))
+		};
+		return term;
+	});
+}
+
+//#endregion
+exports.copyCommandUsageId = copyCommandUsageId;
+exports.getCommandUsageId = getCommandUsageId;
+exports.identifyCommandUsage = identifyCommandUsage;
+exports.scopeCommandUsage = scopeCommandUsage;
+exports.scopeCommandUsageId = scopeCommandUsageId;