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

package/dist/input-trace.js

@@ -21,23 +21,102 @@ function serializePath(path) {
 	if (path.length === 0) return "";
 	return path.map(serializeKey).join("");
 }
+function height(node$1) {
+	return node$1?.height ?? 0;
+}
+function node(key, entry, left, right) {
+	return {
+		key,
+		entry,
+		left,
+		right,
+		height: 1 + Math.max(height(left), height(right))
+	};
+}
+function balance(key, entry, left, right) {
+	if (height(left) - height(right) > 1 && left != null) {
+		const pivot = left.right;
+		if (height(pivot) > height(left.left) && pivot != null) return node(pivot.key, pivot.entry, node(left.key, left.entry, left.left, pivot.left), node(key, entry, pivot.right, right));
+		return node(left.key, left.entry, left.left, node(key, entry, left.right, right));
+	}
+	if (height(right) - height(left) > 1 && right != null) {
+		const pivot = right.left;
+		if (height(pivot) > height(right.right) && pivot != null) return node(pivot.key, pivot.entry, node(key, entry, left, pivot.left), node(right.key, right.entry, pivot.right, right.right));
+		return node(right.key, right.entry, node(key, entry, left, right.left), right.right);
+	}
+	return node(key, entry, left, right);
+}
+function setEntry(root, key, entry) {
+	if (root == null) return node(key, entry, void 0, void 0);
+	if (key === root.key) return entry === root.entry ? root : {
+		...root,
+		entry
+	};
+	if (key < root.key) {
+		const left = setEntry(root.left, key, entry);
+		return left === root.left ? root : balance(root.key, root.entry, left, root.right);
+	}
+	const right = setEntry(root.right, key, entry);
+	return right === root.right ? root : balance(root.key, root.entry, root.left, right);
+}
+function popMin(root) {
+	if (root.left == null) return [root, root.right];
+	const [minimum, left] = popMin(root.left);
+	return [minimum, balance(root.key, root.entry, left, root.right)];
+}
+function deleteEntry(root, key) {
+	if (root == null) return void 0;
+	if (key === root.key) {
+		if (root.left == null) return root.right;
+		if (root.right == null) return root.left;
+		const [successor, right$1] = popMin(root.right);
+		return balance(successor.key, successor.entry, root.left, right$1);
+	}
+	if (key < root.key) {
+		const left = deleteEntry(root.left, key);
+		return left === root.left ? root : balance(root.key, root.entry, left, root.right);
+	}
+	const right = deleteEntry(root.right, key);
+	return right === root.right ? root : balance(root.key, root.entry, root.left, right);
+}
+function inspectNode(root, lower, upper) {
+	if (root == null) return {
+		size: 0,
+		height: 0
+	};
+	if (lower !== void 0 && root.key <= lower || upper !== void 0 && root.key >= upper) throw new TypeError("Input trace keys are not strictly ordered.");
+	const left = inspectNode(root.left, lower, root.key);
+	const right = inspectNode(root.right, root.key, upper);
+	const actualHeight = 1 + Math.max(left.height, right.height);
+	if (root.height !== actualHeight || Math.abs(left.height - right.height) > 1) throw new TypeError("Input trace heights or balance are invalid.");
+	return {
+		size: 1 + left.size + right.size,
+		height: actualHeight
+	};
+}
 var InputTraceImpl = class InputTraceImpl {
-	#entries;
-	constructor(entries) {
-		this.#entries = entries ?? /* @__PURE__ */ new Map();
+	#root;
+	constructor(root) {
+		this.#root = root;
 	}
 	get(path) {
-		return this.#entries.get(serializePath(path));
+		const key = serializePath(path);
+		let current = this.#root;
+		while (current != null) {
+			if (key === current.key) return current.entry;
+			current = key < current.key ? current.left : current.right;
+		}
+		return void 0;
 	}
 	set(path, entry) {
-		const copy = new Map(this.#entries);
-		copy.set(serializePath(path), entry);
-		return new InputTraceImpl(copy);
+		return new InputTraceImpl(setEntry(this.#root, serializePath(path), entry));
 	}
 	delete(path) {
-		const copy = new Map(this.#entries);
-		copy.delete(serializePath(path));
-		return new InputTraceImpl(copy);
+		return new InputTraceImpl(deleteEntry(this.#root, serializePath(path)));
+	}
+	static inspect(trace) {
+		if (!(trace instanceof InputTraceImpl)) throw new TypeError("Expected an Optique input trace.");
+		return inspectNode(trace.#root);
 	}
 };
 /**

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;

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;