@optique/core 1.0.16-dev.2947 → 1.0.16-dev.2975

package/dist/internal/command-usage.js

@@ -0,0 +1,47 @@
+//#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
+export { copyCommandUsageId, getCommandUsageId, identifyCommandUsage, scopeCommandUsage, scopeCommandUsageId };

package/dist/internal/parser.cjs

@@ -1,5 +1,7 @@
 const require_annotations = require('./annotations.cjs');
 const require_message = require('../message.cjs');
+const require_command_usage = require('./command-usage.cjs');
+const require_command_doc_metadata = require('./command-doc-metadata.cjs');
 const require_usage = require('../usage.cjs');
 const require_doc = require('../doc.cjs');
 const require_mode_dispatch = require('./mode-dispatch.cjs');
@@ -527,20 +529,66 @@ function suggest(parser, args, options) {
 *
 * @param term The usage term to search in
 * @param commandName The command name to find
+* @param selectedCommandUsage The command occurrences selected by parser state
 * @returns The expanded usage terms if found, null otherwise
 */
-function findCommandInExclusive(term, commandName) {
+function findCommandInExclusive(term, commandName, selectedCommandUsage) {
+	return findCommandInExclusiveMatching(term, commandName, selectedCommandUsage) ?? findCommandInExclusiveMatching(term, commandName, selectedCommandUsage, false);
+}
+function findCommandInExclusiveMatching(term, commandName, selectedCommandUsage, requireSelectedIdentity = true) {
 	if (term.type !== "exclusive") return null;
 	for (const termGroup of term.terms) {
 		const firstTerm = termGroup[0];
-		if (firstTerm?.type === "command" && firstTerm.name === commandName) return termGroup;
+		if (firstTerm?.type === "command" && firstTerm.name === commandName) {
+			const id = require_command_usage.getCommandUsageId(firstTerm);
+			if (id == null ? !requireSelectedIdentity : selectedCommandUsage.has(id)) return termGroup;
+		}
+		if (requireSelectedIdentity && (firstTerm?.type === "optional" || firstTerm?.type === "multiple") && hasSelectedLeadingCommand(firstTerm.terms, commandName, selectedCommandUsage)) return termGroup;
 		if (firstTerm?.type === "exclusive") {
-			const found = findCommandInExclusive(firstTerm, commandName);
+			const found = findCommandInExclusiveMatching(firstTerm, commandName, selectedCommandUsage, requireSelectedIdentity);
 			if (found) return [...found, ...termGroup.slice(1)];
 		}
 	}
 	return null;
 }
+function hasSelectedLeadingCommand(usage, commandName, selectedCommandUsage) {
+	const first = usage[0];
+	if (first?.type === "command") {
+		const id = require_command_usage.getCommandUsageId(first);
+		return first.name === commandName && id != null && selectedCommandUsage.has(id);
+	}
+	if (first?.type === "optional" || first?.type === "multiple") return hasSelectedLeadingCommand(first.terms, commandName, selectedCommandUsage);
+	return first?.type === "exclusive" && first.terms.some((branch) => hasSelectedLeadingCommand(branch, commandName, selectedCommandUsage));
+}
+function applyWrappedCommandUsageLine(term, commandName, selectedCommandUsage) {
+	const candidates = [];
+	const visit = (terms, rebuild) => {
+		const first = terms[0];
+		if (first?.type === "command") {
+			const id = require_command_usage.getCommandUsageId(first);
+			if (first.name === commandName && id != null && selectedCommandUsage.has(id)) candidates.push({
+				command: first,
+				tail: terms.slice(1),
+				replace: (tail$1) => rebuild([first, ...tail$1])
+			});
+		} else if (first?.type === "optional" || first?.type === "multiple") visit(first.terms, (children) => rebuild([{
+			...first,
+			terms: children
+		}, ...terms.slice(1)]));
+		else if (first?.type === "exclusive") first.terms.forEach((branch, index) => {
+			visit(branch, (children) => rebuild([{
+				...first,
+				terms: first.terms.map((other, otherIndex) => otherIndex === index ? children : other)
+			}, ...terms.slice(1)]));
+		});
+	};
+	visit([term], (terms) => terms[0]);
+	if (candidates.length !== 1) return term;
+	const { command, tail, replace } = candidates[0];
+	if (command.usageLine == null) return term;
+	const customUsageLine = typeof command.usageLine === "function" ? command.usageLine(require_usage.cloneUsage(tail)) : command.usageLine;
+	return replace(require_usage.normalizeUsage(customUsageLine));
+}
 /**
 * Generates a documentation page for a synchronous parser.
 *
@@ -651,10 +699,13 @@ async function getDocPageAsyncImpl(parser, args, options) {
 */
 function buildDocPage(parser, context, args) {
 	let effectiveArgs = args;
-	let { brief, description, fragments, footer } = parser.getDocFragments({
+	let matchedCommandPath = context.exec?.commandPath ?? [];
+	const docs = parser.getDocFragments({
 		kind: "available",
 		state: context.state
 	}, void 0);
+	let selectedCommandUsage = require_command_doc_metadata.getSelectedCommandUsage(require_command_doc_metadata.getCommandDocMetadata(docs));
+	let { brief, description, fragments, footer } = docs;
 	if (args.length === 0 && Reflect.get(parser, Symbol.for("@optique/core/commandParser")) === true && fragments.length === 1 && fragments[0].type === "entry" && fragments[0].term.type === "command") {
 		const cmdName = fragments[0].term.name;
 		const matchedState = require_annotations.inheritAnnotations(context.state, ["matched", cmdName]);
@@ -663,7 +714,9 @@ function buildDocPage(parser, context, args) {
 			state: matchedState
 		}, void 0);
 		({brief, description, fragments, footer} = matched);
+		selectedCommandUsage = require_command_doc_metadata.getSelectedCommandUsage(require_command_doc_metadata.getCommandDocMetadata(matched));
 		effectiveArgs = [cmdName];
+		matchedCommandPath = [cmdName];
 	}
 	const buildingSections = [];
 	let untitledSection = null;
@@ -698,9 +751,15 @@ function buildDocPage(parser, context, args) {
 		}
 	}
 	const sections = buildingSections;
+	const selectedCommandUsageIds = new Set(selectedCommandUsage);
 	const usage = [...require_usage.normalizeUsage(parser.usage)];
 	const maybeApplyCommandUsageLine = (term, arg, isLastArg, usageIndex) => {
-		if (term?.type !== "command" || term.name !== arg || !isLastArg || term.usageLine == null) return;
+		if (!isLastArg) return;
+		if (term?.type === "optional" || term?.type === "multiple" || term?.type === "exclusive") {
+			usage[usageIndex] = applyWrappedCommandUsageLine(term, arg, selectedCommandUsageIds);
+			return;
+		}
+		if (term?.type !== "command" || term.name !== arg || term.usageLine == null) return;
 		const defaultUsageLine = require_usage.cloneUsage(usage.slice(usageIndex + 1));
 		const customUsageLine = typeof term.usageLine === "function" ? term.usageLine(defaultUsageLine) : term.usageLine;
 		const normalizedCustomUsageLine = require_usage.normalizeUsage(customUsageLine);
@@ -712,7 +771,7 @@ function buildDocPage(parser, context, args) {
 		if (i >= usage.length) break;
 		let term = usage[i];
 		if (term.type === "exclusive") {
-			const found = findCommandInExclusive(term, arg);
+			const found = findCommandInExclusive(term, arg, selectedCommandUsageIds);
 			if (found) {
 				usage.splice(i, 1, ...found);
 				term = usage[i];
@@ -731,13 +790,58 @@ function buildDocPage(parser, context, args) {
 		}
 	}
 	return {
-		usage,
+		usage: revealMatchedCommandUsage(usage, matchedCommandPath, selectedCommandUsageIds),
 		sections,
 		...brief != null && { brief: require_message.cloneMessage(brief) },
 		...description != null && { description: require_message.cloneMessage(description) },
 		...footer != null && { footer: require_message.cloneMessage(footer) }
 	};
 }
+function revealMatchedCommandUsage(usage, matchedCommandPath, selectedCommandUsage) {
+	return revealMatchedCommandUsageTerms(usage, matchedCommandPath, 0, selectedCommandUsage)[0];
+}
+function revealMatchedCommandUsageTerms(usage, matchedCommandPath, pathIndex, selectedCommandUsage, allowNameFallback = true) {
+	const terms = [];
+	let nextPathIndex = pathIndex;
+	let nameFallbackEnabled = allowNameFallback;
+	for (let index = 0; index < usage.length; index++) {
+		const term = usage[index];
+		if (term.type === "command") {
+			const id = require_command_usage.getCommandUsageId(term);
+			if (id != null) {
+				if (selectedCommandUsage.has(id)) {
+					const { hidden: _hidden$1,...revealed$1 } = term;
+					terms.push(revealed$1);
+					if (term.name === matchedCommandPath[nextPathIndex]) nextPathIndex++;
+				} else terms.push(term);
+				continue;
+			}
+			if (!nameFallbackEnabled || term.name !== matchedCommandPath[nextPathIndex]) {
+				nameFallbackEnabled = false;
+				terms.push(term);
+				continue;
+			}
+			const { hidden: _hidden,...revealed } = term;
+			terms.push(revealed);
+			nextPathIndex++;
+		} else if (term.type === "optional" || term.type === "multiple") {
+			const [nested, afterTerm] = revealMatchedCommandUsageTerms(term.terms, matchedCommandPath, nextPathIndex, selectedCommandUsage, nameFallbackEnabled);
+			terms.push({
+				...term,
+				terms: nested
+			});
+			nextPathIndex = afterTerm;
+		} else if (term.type === "exclusive") {
+			const branches = term.terms.map((branch) => revealMatchedCommandUsageTerms(branch, matchedCommandPath, nextPathIndex, selectedCommandUsage, nameFallbackEnabled));
+			terms.push({
+				...term,
+				terms: branches.map(([branch]) => branch)
+			});
+			nextPathIndex = Math.max(nextPathIndex, ...branches.map(([, afterBranch]) => afterBranch));
+		} else terms.push(term);
+	}
+	return [terms, nextPathIndex];
+}
 
 //#endregion
 exports.annotationWrapperRequiresSourceBindingKey = annotationWrapperRequiresSourceBindingKey;

package/dist/internal/parser.js

@@ -1,5 +1,7 @@
 import { hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
 import { cloneMessage, message } from "../message.js";
+import { getCommandUsageId } from "./command-usage.js";
+import { getCommandDocMetadata, getSelectedCommandUsage } from "./command-doc-metadata.js";
 import { cloneUsage, normalizeUsage } from "../usage.js";
 import { cloneDocEntry, isDocEntryHidden } from "../doc.js";
 import { dispatchByMode } from "./mode-dispatch.js";
@@ -527,20 +529,66 @@ function suggest(parser, args, options) {
 *
 * @param term The usage term to search in
 * @param commandName The command name to find
+* @param selectedCommandUsage The command occurrences selected by parser state
 * @returns The expanded usage terms if found, null otherwise
 */
-function findCommandInExclusive(term, commandName) {
+function findCommandInExclusive(term, commandName, selectedCommandUsage) {
+	return findCommandInExclusiveMatching(term, commandName, selectedCommandUsage) ?? findCommandInExclusiveMatching(term, commandName, selectedCommandUsage, false);
+}
+function findCommandInExclusiveMatching(term, commandName, selectedCommandUsage, requireSelectedIdentity = true) {
 	if (term.type !== "exclusive") return null;
 	for (const termGroup of term.terms) {
 		const firstTerm = termGroup[0];
-		if (firstTerm?.type === "command" && firstTerm.name === commandName) return termGroup;
+		if (firstTerm?.type === "command" && firstTerm.name === commandName) {
+			const id = getCommandUsageId(firstTerm);
+			if (id == null ? !requireSelectedIdentity : selectedCommandUsage.has(id)) return termGroup;
+		}
+		if (requireSelectedIdentity && (firstTerm?.type === "optional" || firstTerm?.type === "multiple") && hasSelectedLeadingCommand(firstTerm.terms, commandName, selectedCommandUsage)) return termGroup;
 		if (firstTerm?.type === "exclusive") {
-			const found = findCommandInExclusive(firstTerm, commandName);
+			const found = findCommandInExclusiveMatching(firstTerm, commandName, selectedCommandUsage, requireSelectedIdentity);
 			if (found) return [...found, ...termGroup.slice(1)];
 		}
 	}
 	return null;
 }
+function hasSelectedLeadingCommand(usage, commandName, selectedCommandUsage) {
+	const first = usage[0];
+	if (first?.type === "command") {
+		const id = getCommandUsageId(first);
+		return first.name === commandName && id != null && selectedCommandUsage.has(id);
+	}
+	if (first?.type === "optional" || first?.type === "multiple") return hasSelectedLeadingCommand(first.terms, commandName, selectedCommandUsage);
+	return first?.type === "exclusive" && first.terms.some((branch) => hasSelectedLeadingCommand(branch, commandName, selectedCommandUsage));
+}
+function applyWrappedCommandUsageLine(term, commandName, selectedCommandUsage) {
+	const candidates = [];
+	const visit = (terms, rebuild) => {
+		const first = terms[0];
+		if (first?.type === "command") {
+			const id = getCommandUsageId(first);
+			if (first.name === commandName && id != null && selectedCommandUsage.has(id)) candidates.push({
+				command: first,
+				tail: terms.slice(1),
+				replace: (tail$1) => rebuild([first, ...tail$1])
+			});
+		} else if (first?.type === "optional" || first?.type === "multiple") visit(first.terms, (children) => rebuild([{
+			...first,
+			terms: children
+		}, ...terms.slice(1)]));
+		else if (first?.type === "exclusive") first.terms.forEach((branch, index) => {
+			visit(branch, (children) => rebuild([{
+				...first,
+				terms: first.terms.map((other, otherIndex) => otherIndex === index ? children : other)
+			}, ...terms.slice(1)]));
+		});
+	};
+	visit([term], (terms) => terms[0]);
+	if (candidates.length !== 1) return term;
+	const { command, tail, replace } = candidates[0];
+	if (command.usageLine == null) return term;
+	const customUsageLine = typeof command.usageLine === "function" ? command.usageLine(cloneUsage(tail)) : command.usageLine;
+	return replace(normalizeUsage(customUsageLine));
+}
 /**
 * Generates a documentation page for a synchronous parser.
 *
@@ -651,10 +699,13 @@ async function getDocPageAsyncImpl(parser, args, options) {
 */
 function buildDocPage(parser, context, args) {
 	let effectiveArgs = args;
-	let { brief, description, fragments, footer } = parser.getDocFragments({
+	let matchedCommandPath = context.exec?.commandPath ?? [];
+	const docs = parser.getDocFragments({
 		kind: "available",
 		state: context.state
 	}, void 0);
+	let selectedCommandUsage = getSelectedCommandUsage(getCommandDocMetadata(docs));
+	let { brief, description, fragments, footer } = docs;
 	if (args.length === 0 && Reflect.get(parser, Symbol.for("@optique/core/commandParser")) === true && fragments.length === 1 && fragments[0].type === "entry" && fragments[0].term.type === "command") {
 		const cmdName = fragments[0].term.name;
 		const matchedState = inheritAnnotations(context.state, ["matched", cmdName]);
@@ -663,7 +714,9 @@ function buildDocPage(parser, context, args) {
 			state: matchedState
 		}, void 0);
 		({brief, description, fragments, footer} = matched);
+		selectedCommandUsage = getSelectedCommandUsage(getCommandDocMetadata(matched));
 		effectiveArgs = [cmdName];
+		matchedCommandPath = [cmdName];
 	}
 	const buildingSections = [];
 	let untitledSection = null;
@@ -698,9 +751,15 @@ function buildDocPage(parser, context, args) {
 		}
 	}
 	const sections = buildingSections;
+	const selectedCommandUsageIds = new Set(selectedCommandUsage);
 	const usage = [...normalizeUsage(parser.usage)];
 	const maybeApplyCommandUsageLine = (term, arg, isLastArg, usageIndex) => {
-		if (term?.type !== "command" || term.name !== arg || !isLastArg || term.usageLine == null) return;
+		if (!isLastArg) return;
+		if (term?.type === "optional" || term?.type === "multiple" || term?.type === "exclusive") {
+			usage[usageIndex] = applyWrappedCommandUsageLine(term, arg, selectedCommandUsageIds);
+			return;
+		}
+		if (term?.type !== "command" || term.name !== arg || term.usageLine == null) return;
 		const defaultUsageLine = cloneUsage(usage.slice(usageIndex + 1));
 		const customUsageLine = typeof term.usageLine === "function" ? term.usageLine(defaultUsageLine) : term.usageLine;
 		const normalizedCustomUsageLine = normalizeUsage(customUsageLine);
@@ -712,7 +771,7 @@ function buildDocPage(parser, context, args) {
 		if (i >= usage.length) break;
 		let term = usage[i];
 		if (term.type === "exclusive") {
-			const found = findCommandInExclusive(term, arg);
+			const found = findCommandInExclusive(term, arg, selectedCommandUsageIds);
 			if (found) {
 				usage.splice(i, 1, ...found);
 				term = usage[i];
@@ -731,13 +790,58 @@ function buildDocPage(parser, context, args) {
 		}
 	}
 	return {
-		usage,
+		usage: revealMatchedCommandUsage(usage, matchedCommandPath, selectedCommandUsageIds),
 		sections,
 		...brief != null && { brief: cloneMessage(brief) },
 		...description != null && { description: cloneMessage(description) },
 		...footer != null && { footer: cloneMessage(footer) }
 	};
 }
+function revealMatchedCommandUsage(usage, matchedCommandPath, selectedCommandUsage) {
+	return revealMatchedCommandUsageTerms(usage, matchedCommandPath, 0, selectedCommandUsage)[0];
+}
+function revealMatchedCommandUsageTerms(usage, matchedCommandPath, pathIndex, selectedCommandUsage, allowNameFallback = true) {
+	const terms = [];
+	let nextPathIndex = pathIndex;
+	let nameFallbackEnabled = allowNameFallback;
+	for (let index = 0; index < usage.length; index++) {
+		const term = usage[index];
+		if (term.type === "command") {
+			const id = getCommandUsageId(term);
+			if (id != null) {
+				if (selectedCommandUsage.has(id)) {
+					const { hidden: _hidden$1,...revealed$1 } = term;
+					terms.push(revealed$1);
+					if (term.name === matchedCommandPath[nextPathIndex]) nextPathIndex++;
+				} else terms.push(term);
+				continue;
+			}
+			if (!nameFallbackEnabled || term.name !== matchedCommandPath[nextPathIndex]) {
+				nameFallbackEnabled = false;
+				terms.push(term);
+				continue;
+			}
+			const { hidden: _hidden,...revealed } = term;
+			terms.push(revealed);
+			nextPathIndex++;
+		} else if (term.type === "optional" || term.type === "multiple") {
+			const [nested, afterTerm] = revealMatchedCommandUsageTerms(term.terms, matchedCommandPath, nextPathIndex, selectedCommandUsage, nameFallbackEnabled);
+			terms.push({
+				...term,
+				terms: nested
+			});
+			nextPathIndex = afterTerm;
+		} else if (term.type === "exclusive") {
+			const branches = term.terms.map((branch) => revealMatchedCommandUsageTerms(branch, matchedCommandPath, nextPathIndex, selectedCommandUsage, nameFallbackEnabled));
+			terms.push({
+				...term,
+				terms: branches.map(([branch]) => branch)
+			});
+			nextPathIndex = Math.max(nextPathIndex, ...branches.map(([, afterBranch]) => afterBranch));
+		} else terms.push(term);
+	}
+	return [terms, nextPathIndex];
+}
 
 //#endregion
 export { annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createParserContext, defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getOwnParseLanes, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker };

package/dist/message.cjs

@@ -306,7 +306,8 @@ function formatMessage(msg, options = {}) {
 			const isAfterLineBreak = prevWasLineBreak;
 			prevWasLineBreak = false;
 			if (term.type === "text") {
-				const rawText = isAfterLineBreak ? term.text.replace(/^\n(?!\n)/, "") : term.text;
+				const textWithLf = term.text.replace(/\r\n?/g, "\n");
+				const rawText = isAfterLineBreak ? textWithLf.replace(/^\n(?!\n)/, "") : textWithLf;
 				if (rawText.includes("\n\n")) {
 					const paragraphs = rawText.split(/\n\n+/);
 					for (let paragraphIndex = 0; paragraphIndex < paragraphs.length; paragraphIndex++) {
@@ -332,8 +333,8 @@ function formatMessage(msg, options = {}) {
 				} else {
 					const normalizedText = rawText.replace(/\n/g, " ");
 					if (normalizedText.trim() === "" && normalizedText.length > 0) yield {
-						text: " ",
-						width: 1,
+						text: normalizedText,
+						width: require_displaywidth.getDisplayWidth(normalizedText),
 						trimOnWrap: true
 					};
 					else {

package/dist/message.js

@@ -306,7 +306,8 @@ function formatMessage(msg, options = {}) {
 			const isAfterLineBreak = prevWasLineBreak;
 			prevWasLineBreak = false;
 			if (term.type === "text") {
-				const rawText = isAfterLineBreak ? term.text.replace(/^\n(?!\n)/, "") : term.text;
+				const textWithLf = term.text.replace(/\r\n?/g, "\n");
+				const rawText = isAfterLineBreak ? textWithLf.replace(/^\n(?!\n)/, "") : textWithLf;
 				if (rawText.includes("\n\n")) {
 					const paragraphs = rawText.split(/\n\n+/);
 					for (let paragraphIndex = 0; paragraphIndex < paragraphs.length; paragraphIndex++) {
@@ -332,8 +333,8 @@ function formatMessage(msg, options = {}) {
 				} else {
 					const normalizedText = rawText.replace(/\n/g, " ");
 					if (normalizedText.trim() === "" && normalizedText.length > 0) yield {
-						text: " ",
-						width: 1,
+						text: normalizedText,
+						width: getDisplayWidth(normalizedText),
 						trimOnWrap: true
 					};
 					else {

package/dist/modifiers.cjs

@@ -8,6 +8,7 @@ const require_parser = require('./internal/parser.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
 const require_execution_context = require('./execution-context.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
+const require_extension = require('./extension.cjs');
 const require_dependency_metadata = require('./dependency-metadata.cjs');
 
 //#region src/modifiers.ts
@@ -828,6 +829,7 @@ function map(parser, transform) {
 		}
 	};
 	require_parser.defineParseLanes(mappedParser, require_parser.getOwnParseLanes(parser));
+	require_extension.defineTraits(mappedParser, require_extension.getTraits(parser));
 	delete mappedParser.normalizeValue;
 	delete mappedParser.validateValue;
 	if ("placeholder" in parser) Object.defineProperty(mappedParser, "placeholder", {
@@ -1346,7 +1348,19 @@ function multiple(parser, options = {}) {
 				kind: "available",
 				state: latestInnerState
 			} : { kind: "unavailable" };
-			return syncParser.getDocFragments(innerState, defaultValue != null && defaultValue.length > 0 ? defaultValue[0] : void 0);
+			const docs = syncParser.getDocFragments(innerState, defaultValue != null && defaultValue.length > 0 ? defaultValue[0] : void 0);
+			if (state.kind === "unavailable" || state.state.length < 2) return docs;
+			const metadata = require_command_doc_metadata.getCommandDocMetadata(docs);
+			const selected = [...require_command_doc_metadata.getSelectedCommandUsage(metadata)];
+			for (const itemState of state.state.slice(0, -1)) {
+				const itemInnerState = itemState != null && require_annotations.isInjectedAnnotationWrapper(itemState) ? unwrapInjectedWrapper(itemState) : itemState;
+				const itemDocs = syncParser.getDocFragments(itemInnerState === void 0 ? { kind: "unavailable" } : {
+					kind: "available",
+					state: itemInnerState
+				}, defaultValue != null && defaultValue.length > 0 ? defaultValue[0] : void 0);
+				selected.push(...require_command_doc_metadata.getSelectedCommandUsage(require_command_doc_metadata.getCommandDocMetadata(itemDocs)));
+			}
+			return require_command_doc_metadata.withCommandDocMetadata(docs, require_command_doc_metadata.withSelectedCommandUsage(metadata, selected));
 		}
 	};
 	function validateMultipleResult(result, deferredIndices, hasDeferred = false) {

package/dist/modifiers.js

@@ -1,13 +1,14 @@
 import { annotateFreshArray, annotationKey, getAnnotations, inheritAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./internal/annotations.js";
 import { mergeJoinedFileSuggestions } from "./internal/joined-file-suggestion.js";
 import { formatMessage, message, text } from "./message.js";
-import { getCommandDocMetadata, withCommandDocMetadata } from "./internal/command-doc-metadata.js";
+import { getCommandDocMetadata, getSelectedCommandUsage, withCommandDocMetadata, withSelectedCommandUsage } from "./internal/command-doc-metadata.js";
 import { defineKnownCompletionLookup, defineOptionMatch, definePassThroughPriority, getKnownCompletion, getOptionMatch, getPassThroughPriority } from "./internal/passthrough.js";
 import { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode } from "./internal/mode-dispatch.js";
 import { defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingOnlyAnnotationCompletionParser, getOwnParseLanes, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { getDelegatedAnnotationState, hasDelegatedAnnotationCarrier, isAnnotationWrappedInitialState, normalizeDelegatedAnnotationState, normalizeNestedDelegatedAnnotationState } from "./annotation-state.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
 import { completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult } from "./phase2-seed.js";
+import { defineTraits, getTraits } from "./extension.js";
 import { composeDependencyMetadata } from "./dependency-metadata.js";
 
 //#region src/modifiers.ts
@@ -828,6 +829,7 @@ function map(parser, transform) {
 		}
 	};
 	defineParseLanes(mappedParser, getOwnParseLanes(parser));
+	defineTraits(mappedParser, getTraits(parser));
 	delete mappedParser.normalizeValue;
 	delete mappedParser.validateValue;
 	if ("placeholder" in parser) Object.defineProperty(mappedParser, "placeholder", {
@@ -1346,7 +1348,19 @@ function multiple(parser, options = {}) {
 				kind: "available",
 				state: latestInnerState
 			} : { kind: "unavailable" };
-			return syncParser.getDocFragments(innerState, defaultValue != null && defaultValue.length > 0 ? defaultValue[0] : void 0);
+			const docs = syncParser.getDocFragments(innerState, defaultValue != null && defaultValue.length > 0 ? defaultValue[0] : void 0);
+			if (state.kind === "unavailable" || state.state.length < 2) return docs;
+			const metadata = getCommandDocMetadata(docs);
+			const selected = [...getSelectedCommandUsage(metadata)];
+			for (const itemState of state.state.slice(0, -1)) {
+				const itemInnerState = itemState != null && isInjectedAnnotationWrapper(itemState) ? unwrapInjectedWrapper(itemState) : itemState;
+				const itemDocs = syncParser.getDocFragments(itemInnerState === void 0 ? { kind: "unavailable" } : {
+					kind: "available",
+					state: itemInnerState
+				}, defaultValue != null && defaultValue.length > 0 ? defaultValue[0] : void 0);
+				selected.push(...getSelectedCommandUsage(getCommandDocMetadata(itemDocs)));
+			}
+			return withCommandDocMetadata(docs, withSelectedCommandUsage(metadata, selected));
 		}
 	};
 	function validateMultipleResult(result, deferredIndices, hasDeferred = false) {

package/dist/primitives.cjs

@@ -1,6 +1,7 @@
 const require_annotations = require('./internal/annotations.cjs');
 const require_joined_file_suggestion = require('./internal/joined-file-suggestion.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');
@@ -1221,18 +1222,20 @@ function command(name, parser, options = {}) {
 	const isAsync = parser.mode === "async";
 	const syncInnerParser = parser;
 	const asyncInnerParser = parser;
+	const commandUsageId = {};
+	const childUsageScope = /* @__PURE__ */ new WeakMap();
 	const result = {
 		[Symbol.for("@optique/core/commandParser")]: true,
 		mode: parser.mode,
 		$valueType: [],
 		$stateType: [],
 		priority: 15,
-		usage: [{
+		usage: [require_command_usage.identifyCommandUsage({
 			type: "command",
 			name,
 			...options.usageLine != null && { usageLine: options.usageLine },
 			...options.hidden != null && { hidden: options.hidden }
-		}, ...parser.usage],
+		}, commandUsageId), ...require_command_usage.scopeCommandUsage(parser.usage, childUsageScope)],
 		leadingNames: new Set([name]),
 		acceptingAnyToken: false,
 		initialState: void 0,
@@ -1420,12 +1423,12 @@ function command(name, parser, options = {}) {
 				brief: innerFragments.brief ?? options.brief,
 				description: innerFragments.description ?? options.description,
 				footer: innerFragments.footer ?? options.footer
-			}, {
+			}, require_command_doc_metadata.withSelectedCommandUsage({
 				origin: "command",
 				brief: innerMetadata?.brief ?? options.brief,
 				description: innerMetadata?.description ?? options.description,
 				footer: innerMetadata?.footer ?? options.footer
-			});
+			}, [commandUsageId, ...require_command_doc_metadata.getSelectedCommandUsage(require_command_doc_metadata.scopeCommandDocMetadata(require_command_doc_metadata.getCommandDocMetadata(innerFragments), childUsageScope))]));
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			return `command(${JSON.stringify(name)})`;

package/dist/primitives.js

@@ -1,7 +1,8 @@
 import { annotateFreshArray, getAnnotations } from "./internal/annotations.js";
 import { joinedFileSuggestion } from "./internal/joined-file-suggestion.js";
 import { message, metavar, optionName, optionNames, text, valueSet } from "./message.js";
-import { getCommandDocMetadata, withCommandDocMetadata } from "./internal/command-doc-metadata.js";
+import { identifyCommandUsage, scopeCommandUsage } from "./internal/command-usage.js";
+import { getCommandDocMetadata, getSelectedCommandUsage, scopeCommandDocMetadata, withCommandDocMetadata, withSelectedCommandUsage } from "./internal/command-doc-metadata.js";
 import { defineKnownCompletion, defineOptionMatch, definePassThroughPriority, getOptionMatch, getPassThroughFailure, getPassThroughPriority } from "./internal/passthrough.js";
 import { validateCommandNames, validateOptionNames } from "./validate.js";
 import { extractOptionNames, isDocHidden, isSuggestionHidden } from "./usage.js";
@@ -1221,18 +1222,20 @@ function command(name, parser, options = {}) {
 	const isAsync = parser.mode === "async";
 	const syncInnerParser = parser;
 	const asyncInnerParser = parser;
+	const commandUsageId = {};
+	const childUsageScope = /* @__PURE__ */ new WeakMap();
 	const result = {
 		[Symbol.for("@optique/core/commandParser")]: true,
 		mode: parser.mode,
 		$valueType: [],
 		$stateType: [],
 		priority: 15,
-		usage: [{
+		usage: [identifyCommandUsage({
 			type: "command",
 			name,
 			...options.usageLine != null && { usageLine: options.usageLine },
 			...options.hidden != null && { hidden: options.hidden }
-		}, ...parser.usage],
+		}, commandUsageId), ...scopeCommandUsage(parser.usage, childUsageScope)],
 		leadingNames: new Set([name]),
 		acceptingAnyToken: false,
 		initialState: void 0,
@@ -1420,12 +1423,12 @@ function command(name, parser, options = {}) {
 				brief: innerFragments.brief ?? options.brief,
 				description: innerFragments.description ?? options.description,
 				footer: innerFragments.footer ?? options.footer
-			}, {
+			}, withSelectedCommandUsage({
 				origin: "command",
 				brief: innerMetadata?.brief ?? options.brief,
 				description: innerMetadata?.description ?? options.description,
 				footer: innerMetadata?.footer ?? options.footer
-			});
+			}, [commandUsageId, ...getSelectedCommandUsage(scopeCommandDocMetadata(getCommandDocMetadata(innerFragments), childUsageScope))]));
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			return `command(${JSON.stringify(name)})`;