@optique/core 1.1.0-dev.2096 → 1.1.0-dev.2148

package/dist/constructs.cjs

@@ -1,13 +1,14 @@
-const require_annotations = require('./internal/annotations.cjs');
+const require_internal_annotations = require('./internal/annotations.cjs');
 const require_message = require('./message.cjs');
 const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
 const require_doc = require('./doc.cjs');
 const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
-const require_dependency = require('./internal/dependency.cjs');
+const require_internal_dependency = require('./internal/dependency.cjs');
 const require_dependency_runtime = require('./dependency-runtime.cjs');
-const require_parser = require('./internal/parser.cjs');
+const require_internal_parser = require('./internal/parser.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
+const require_command_alias = require('./internal/command-alias.cjs');
 const require_execution_context = require('./execution-context.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
 const require_suggestion = require('./suggestion.cjs');
@@ -20,7 +21,7 @@ const require_usage_internals = require('./usage-internals.cjs');
 */
 const EMPTY_LEADING_NAMES = /* @__PURE__ */ new Set();
 function isNonCliBoundSourceState(state, parser) {
-	return parser[require_parser.unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object" && Object.hasOwn(state, "hasCliValue") && state.hasCliValue === false;
+	return parser[require_internal_parser.unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object" && Object.hasOwn(state, "hasCliValue") && state.hasCliValue === false;
 }
 function withDependencyRuntimeExec(usage, exec, runtime) {
 	if (exec == null) return {
@@ -43,8 +44,8 @@ function withChildContext$1(context, segment, state, parser, usage) {
 }
 function isUnmatchedDependencyState(state, parser) {
 	if (state === void 0) return true;
-	if (Array.isArray(state) && state.length === 1 && require_dependency.isPendingDependencySourceState(state[0])) return true;
-	if (require_dependency.isPendingDependencySourceState(state)) return true;
+	if (Array.isArray(state) && state.length === 1 && require_internal_dependency.isPendingDependencySourceState(state[0])) return true;
+	if (require_internal_dependency.isPendingDependencySourceState(state)) return true;
 	if (isNonCliBoundSourceState(state, parser)) return true;
 	return state === parser.initialState;
 }
@@ -61,7 +62,7 @@ function buildIndexedParserPairs(parsers) {
 }
 function createAnnotatedArrayStateRecord(stateArray) {
 	const stateRecord = Object.fromEntries(stateArray.map((state, index) => [String(index), state]));
-	return require_annotations.inheritAnnotations(stateArray, stateRecord);
+	return require_internal_annotations.inheritAnnotations(stateArray, stateRecord);
 }
 /**
 * Computes the union of `leadingNames` from all given parsers.
@@ -173,7 +174,7 @@ function unwrapNestedAnnotationViews(value, seen = /* @__PURE__ */ new WeakMap()
 	return clone;
 }
 function unwrapCompleteResult(result) {
-	const unwrappedResult = require_dependency.isDependencySourceState(result) ? result.result : result;
+	const unwrappedResult = require_internal_dependency.isDependencySourceState(result) ? result.result : result;
 	if (!unwrappedResult.success || !containsAnnotationView(unwrappedResult.value)) return unwrappedResult;
 	const value = unwrapNestedAnnotationViews(unwrappedResult.value);
 	return value === unwrappedResult.value ? unwrappedResult : {
@@ -257,8 +258,8 @@ function combineTuplePhase2Seeds(first, second) {
 */
 function prepareStateForCompletion(fieldState, parser) {
 	if (fieldState !== void 0) return fieldState;
-	if (require_dependency.isPendingDependencySourceState(parser.initialState)) return [parser.initialState];
-	if (require_dependency.isWrappedDependencySource(parser)) return [parser[require_dependency.wrappedDependencySourceMarker]];
+	if (require_internal_dependency.isPendingDependencySourceState(parser.initialState)) return [parser.initialState];
+	if (require_internal_dependency.isWrappedDependencySource(parser)) return [parser[require_internal_dependency.wrappedDependencySourceMarker]];
 	return fieldState;
 }
 /**
@@ -281,7 +282,7 @@ function buildSuggestRuntimeNodesFromPairs(pairs, state, parentPath) {
 	const nodes = [];
 	for (const [field, parser] of pairs) {
 		const fieldState = Object.hasOwn(state, field) ? state[field] : parser.initialState;
-		nodes.push(...require_parser.getParserSuggestRuntimeNodes(parser, require_annotation_state.getWrappedChildState(state, fieldState, parser), [...prefix, field]));
+		nodes.push(...require_internal_parser.getParserSuggestRuntimeNodes(parser, require_annotation_state.getWrappedChildState(state, fieldState, parser), [...prefix, field]));
 	}
 	return nodes;
 }
@@ -291,7 +292,7 @@ function buildSuggestRuntimeNodesFromArray(parsers, stateArray, parentPath) {
 	for (let i = 0; i < parsers.length; i++) {
 		const parser = parsers[i];
 		const elementState = i < stateArray.length ? stateArray[i] : void 0;
-		nodes.push(...require_parser.getParserSuggestRuntimeNodes(parser, require_annotation_state.getWrappedChildState(stateArray, elementState, parser), [...prefix, i]));
+		nodes.push(...require_internal_parser.getParserSuggestRuntimeNodes(parser, require_annotation_state.getWrappedChildState(stateArray, elementState, parser), [...prefix, i]));
 	}
 	return nodes;
 }
@@ -301,7 +302,12 @@ function createUnexpectedInputErrorWithScopedSuggestions(baseError, invalidInput
 	for (const parser of parsers) require_usage_internals.collectLeadingCandidates(parser.usage, options, commands);
 	const candidates = new Set([...options, ...commands]);
 	const suggestions = require_suggestion.findSimilar(invalidInput, candidates, require_suggestion.DEFAULT_FIND_SIMILAR_OPTIONS);
-	const suggestionMsg = customFormatter ? customFormatter(suggestions) : require_suggestion.createSuggestionMessage(suggestions);
+	const aliasUsage = [{
+		type: "exclusive",
+		terms: parsers.map((parser) => parser.usage)
+	}];
+	const displaySuggestions = require_suggestion.expandCommandAliasSuggestions(aliasUsage, suggestions);
+	const suggestionMsg = customFormatter ? customFormatter(displaySuggestions) : require_suggestion.createSuggestionMessage(displaySuggestions);
 	return suggestionMsg.length > 0 ? [
 		...baseError,
 		require_message.text("\n\n"),
@@ -457,6 +463,18 @@ var DuplicateOptionError = class extends Error {
 	}
 };
 /**
+* Error class thrown when duplicate command names or aliases are detected
+* during parser construction. This is a programmer error, not a user error.
+*/
+var DuplicateCommandNameError = class extends TypeError {
+	constructor(commandName, sources) {
+		const sourceNames = sources.map((s) => typeof s === "symbol" ? s.description ?? s.toString() : s);
+		super(`Duplicate command name "${commandName}" found in parsers: ${sourceNames.join(", ")}. Each command name or alias must be unique within active parser alternatives.`);
+		this.commandName = commandName;
+		this.sources = sources;
+	}
+};
+/**
 * Checks for duplicate option names across parser sources and throws an error
 * if duplicates are found. This should be called at construction time.
 * @param parserSources Array of [source, usage] tuples
@@ -473,6 +491,48 @@ function checkDuplicateOptionNames(parserSources) {
 	}
 	for (const [name, sources] of optionNameSources) if (sources.length > 1) throw new DuplicateOptionError(name, sources);
 }
+function checkDuplicateLeadingCommandNames(parserSources) {
+	const commandNameSources = /* @__PURE__ */ new Map();
+	for (const [source, parser] of parserSources) {
+		const commandNames = require_usage.extractCommandNames(parser.usage, true);
+		for (const name of parser.leadingNames) {
+			if (!commandNames.has(name)) continue;
+			const sources = commandNameSources.get(name);
+			commandNameSources.set(name, sources == null ? [source] : [...sources, source]);
+		}
+	}
+	for (const [name, sources] of commandNameSources) if (sources.length > 1) throw new DuplicateCommandNameError(name, sources);
+}
+function checkDuplicateReachableLeadingCommandNames(parserSources) {
+	const commandNameSources = /* @__PURE__ */ new Map();
+	const sortedSources = [...parserSources].sort(([, parserA], [, parserB]) => parserB.priority - parserA.priority);
+	const blockedNames = /* @__PURE__ */ new Set();
+	let positionalBlocked = false;
+	for (let i = 0; i < sortedSources.length;) {
+		const priority = sortedSources[i][1].priority;
+		const priorityGroup = [];
+		while (i < sortedSources.length && sortedSources[i][1].priority === priority) {
+			priorityGroup.push(sortedSources[i]);
+			i++;
+		}
+		const groupNames = /* @__PURE__ */ new Set();
+		let groupAcceptsAnyToken = false;
+		for (const [source, parser] of priorityGroup) {
+			if (parser.acceptingAnyToken) groupAcceptsAnyToken = true;
+			const commandNames = require_usage.extractCommandNames(parser.usage, true);
+			for (const name of parser.leadingNames) {
+				if (!commandNames.has(name)) continue;
+				if (positionalBlocked || blockedNames.has(name)) continue;
+				groupNames.add(name);
+				const sources = commandNameSources.get(name);
+				commandNameSources.set(name, sources == null ? [source] : [...sources, source]);
+			}
+		}
+		for (const name of groupNames) blockedNames.add(name);
+		if (groupAcceptsAnyToken) positionalBlocked = true;
+	}
+	for (const [name, sources] of commandNameSources) if (sources.length > 1) throw new DuplicateCommandNameError(name, sources);
+}
 /**
 * Extracts option names that participate in CLI syntax.
 *
@@ -518,7 +578,7 @@ function annotateExclusiveParserResult(parentState, parser, result) {
 }
 function createExclusiveState(parentState, index, parser, result) {
 	const annotatedResult = annotateExclusiveParserResult(parentState, parser, result);
-	return require_annotations.annotateFreshArray(parentState, [index, annotatedResult]);
+	return require_internal_annotations.annotateFreshArray(parentState, [index, annotatedResult]);
 }
 /**
 * Creates a complete() method shared by or() and longestMatch().
@@ -614,7 +674,7 @@ function getExclusiveSuggestRuntimeNodes(parsers, state, path) {
 	const [index, parserResult] = activeState;
 	if (!parserResult?.success || index < 0 || index >= parsers.length) return [];
 	const parser = parsers[index];
-	return require_parser.getParserSuggestRuntimeNodes(parser, parserResult.next.state, [...path, index]);
+	return require_internal_parser.getParserSuggestRuntimeNodes(parser, parserResult.next.state, [...path, index]);
 }
 function findExclusiveZeroInputCandidateSync(parsers, state, exec) {
 	const emptyCtx = {
@@ -737,6 +797,7 @@ function or(...args) {
 	}
 	if (parsers.length < 1) throw new TypeError("or() requires at least one parser argument.");
 	assertParsers(parsers, "or()");
+	checkDuplicateLeadingCommandNames(parsers.map((parser, index) => [String(index), parser]));
 	const noMatchContext = analyzeNoMatchContext(parsers);
 	const combinedMode = parsers.some((p) => p.mode === "async") ? "async" : "sync";
 	const syncParsers = parsers;
@@ -1205,13 +1266,16 @@ function or(...args) {
 	};
 	const singleDependencyMetadata = composeExclusiveDependencyMetadata(parsers);
 	if (singleDependencyMetadata != null) singleResult.dependencyMetadata = singleDependencyMetadata;
-	require_parser.defineInheritedAnnotationParser(singleResult);
+	require_internal_parser.defineInheritedAnnotationParser(singleResult);
 	return singleResult;
 }
 /**
 * @since 0.5.0
 */
 function longestMatch(...args) {
+	return createLongestMatch(...args);
+}
+function createLongestMatch(...args) {
 	let parsers;
 	let options;
 	if (args.length > 0 && args[args.length - 1] && typeof args[args.length - 1] === "object" && !("$valueType" in args[args.length - 1])) {
@@ -1223,6 +1287,8 @@ function longestMatch(...args) {
 	}
 	if (parsers.length < 1) throw new TypeError("longestMatch() requires at least one parser argument.");
 	assertParsers(parsers, "longestMatch()");
+	const allowDuplicateLeadingCommandNames = options?.[require_command_alias.allowDuplicateLeadingCommandNamesKey] === true;
+	if (!allowDuplicateLeadingCommandNames) checkDuplicateLeadingCommandNames(parsers.map((parser, index) => [String(index), parser]));
 	const noMatchContext = analyzeNoMatchContext(parsers);
 	const combinedMode = parsers.some((p) => p.mode === "async") ? "async" : "sync";
 	const syncParsers = parsers;
@@ -1375,7 +1441,7 @@ function longestMatch(...args) {
 	};
 	const multiDependencyMetadata = composeExclusiveDependencyMetadata(parsers);
 	if (multiDependencyMetadata != null) multiResult.dependencyMetadata = multiDependencyMetadata;
-	require_parser.defineInheritedAnnotationParser(multiResult);
+	require_internal_parser.defineInheritedAnnotationParser(multiResult);
 	return multiResult;
 }
 /**
@@ -1458,7 +1524,7 @@ async function* suggestObjectAsync(context, prefix, parserPairs) {
 * @internal
 */
 function registerCompletedDependency(completed, registry) {
-	if (require_dependency.isDependencySourceState(completed) && completed.result.success && !registry.has(completed[require_dependency.dependencyId])) registry.set(completed[require_dependency.dependencyId], completed.result.value);
+	if (require_internal_dependency.isDependencySourceState(completed) && completed.result.success && !registry.has(completed[require_internal_dependency.dependencyId])) registry.set(completed[require_internal_dependency.dependencyId], completed.result.value);
 }
 /**
 * Yields `(parser, state)` pairs for dependency source parsers whose field
@@ -1469,7 +1535,7 @@ function registerCompletedDependency(completed, registry) {
 */
 function* pendingDependencyDefaults(context, parserPairs, registry) {
 	for (const [field, fieldParser] of parserPairs) {
-		const sourceId = fieldParser.dependencyMetadata?.source?.sourceId ?? (require_dependency.isWrappedDependencySource(fieldParser) ? fieldParser[require_dependency.wrappedDependencySourceMarker][require_dependency.dependencyId] : require_dependency.isPendingDependencySourceState(fieldParser.initialState) ? fieldParser.initialState[require_dependency.dependencyId] : void 0);
+		const sourceId = fieldParser.dependencyMetadata?.source?.sourceId ?? (require_internal_dependency.isWrappedDependencySource(fieldParser) ? fieldParser[require_internal_dependency.wrappedDependencySourceMarker][require_internal_dependency.dependencyId] : require_internal_dependency.isPendingDependencySourceState(fieldParser.initialState) ? fieldParser.initialState[require_internal_dependency.dependencyId] : void 0);
 		if (sourceId != null && registry?.has(sourceId)) continue;
 		const fieldState = context.state != null && typeof context.state === "object" && field in context.state ? context.state[field] : void 0;
 		const annotatedFieldState = getAnnotatedFieldState(context.state, field, fieldParser);
@@ -1488,19 +1554,19 @@ function* pendingDependencyDefaults(context, parserPairs, registry) {
 			continue;
 		}
 		if (fieldState != null) {
-			if (!Array.isArray(fieldState) && !require_dependency.isDependencySourceState(fieldState) && (require_dependency.isWrappedDependencySource(fieldParser) || require_dependency.isPendingDependencySourceState(fieldParser.initialState))) yield {
+			if (!Array.isArray(fieldState) && !require_internal_dependency.isDependencySourceState(fieldState) && (require_internal_dependency.isWrappedDependencySource(fieldParser) || require_internal_dependency.isPendingDependencySourceState(fieldParser.initialState))) yield {
 				parser: fieldParser,
 				state: getAnnotatedFieldState(context.state, field, fieldParser)
 			};
 			continue;
 		}
-		if (require_dependency.isPendingDependencySourceState(fieldParser.initialState)) yield {
+		if (require_internal_dependency.isPendingDependencySourceState(fieldParser.initialState)) yield {
 			parser: fieldParser,
 			state: fieldParser.initialState
 		};
-		else if (require_dependency.isWrappedDependencySource(fieldParser)) yield {
+		else if (require_internal_dependency.isWrappedDependencySource(fieldParser)) yield {
 			parser: fieldParser,
-			state: [fieldParser[require_dependency.wrappedDependencySourceMarker]]
+			state: [fieldParser[require_internal_dependency.wrappedDependencySourceMarker]]
 		};
 	}
 }
@@ -1532,13 +1598,13 @@ function completeDependencySourceDefaults(context, parserPairs, registry, exec)
 * @internal
 */
 function wrapAsDependencySourceState(completed, parser) {
-	if (require_dependency.isDependencySourceState(completed)) return completed;
+	if (require_internal_dependency.isDependencySourceState(completed)) return completed;
 	const metadataSource = parser.dependencyMetadata?.source;
 	if (metadataSource?.preservesSourceValue === false) return void 0;
-	const hasDep = metadataSource != null || require_dependency.isWrappedDependencySource(parser) || require_dependency.isPendingDependencySourceState(parser.initialState);
+	const hasDep = metadataSource != null || require_internal_dependency.isWrappedDependencySource(parser) || require_internal_dependency.isPendingDependencySourceState(parser.initialState);
 	if (hasDep && typeof completed === "object" && completed !== null && "success" in completed && completed.success && "value" in completed && completed.value !== void 0) {
-		const depId = metadataSource?.sourceId ?? (require_dependency.isWrappedDependencySource(parser) ? parser[require_dependency.wrappedDependencySourceMarker][require_dependency.dependencyId] : parser.initialState[require_dependency.dependencyId]);
-		return require_dependency.createDependencySourceState(completed, depId);
+		const depId = metadataSource?.sourceId ?? (require_internal_dependency.isWrappedDependencySource(parser) ? parser[require_internal_dependency.wrappedDependencySourceMarker][require_internal_dependency.dependencyId] : parser.initialState[require_internal_dependency.dependencyId]);
+		return require_internal_dependency.createDependencySourceState(completed, depId);
 	}
 	return void 0;
 }
@@ -1648,20 +1714,20 @@ function preCompleteAndRegisterDependencies(state, fieldParserPairs, registry, e
 			if (depState) registerCompletedDependency(depState, registry);
 			continue;
 		}
-		if (Array.isArray(fieldState) && fieldState.length === 1 && require_dependency.isPendingDependencySourceState(fieldState[0])) {
+		if (Array.isArray(fieldState) && fieldState.length === 1 && require_internal_dependency.isPendingDependencySourceState(fieldState[0])) {
 			const completed = fieldParser.complete(fieldState, require_execution_context.withChildExecPath(exec, field));
 			preCompleted.set(field, completed);
-			if (require_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
-		} else if (fieldState === void 0 && require_dependency.isPendingDependencySourceState(fieldParser.initialState)) {
+			if (require_internal_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
+		} else if (fieldState === void 0 && require_internal_dependency.isPendingDependencySourceState(fieldParser.initialState)) {
 			const completed = fieldParser.complete([fieldParser.initialState], require_execution_context.withChildExecPath(exec, field));
 			preCompleted.set(field, completed);
-			if (require_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
-		} else if (fieldState === void 0 && require_dependency.isWrappedDependencySource(fieldParser)) {
-			const pendingState = fieldParser[require_dependency.wrappedDependencySourceMarker];
+			if (require_internal_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
+		} else if (fieldState === void 0 && require_internal_dependency.isWrappedDependencySource(fieldParser)) {
+			const pendingState = fieldParser[require_internal_dependency.wrappedDependencySourceMarker];
 			const completed = fieldParser.complete([pendingState], require_execution_context.withChildExecPath(exec, field));
 			preCompleted.set(field, completed);
-			if (require_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
-		} else if (fieldState != null && !Array.isArray(fieldState) && !require_dependency.isDependencySourceState(fieldState) && (require_dependency.isWrappedDependencySource(fieldParser) || require_dependency.isPendingDependencySourceState(fieldParser.initialState))) {
+			if (require_internal_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
+		} else if (fieldState != null && !Array.isArray(fieldState) && !require_internal_dependency.isDependencySourceState(fieldState) && (require_internal_dependency.isWrappedDependencySource(fieldParser) || require_internal_dependency.isPendingDependencySourceState(fieldParser.initialState))) {
 			const annotatedFieldState$1 = getAnnotatedFieldState(state, field, fieldParser);
 			const completed = fieldParser.complete(annotatedFieldState$1, require_execution_context.withChildExecPath(exec, field));
 			preCompleted.set(field, completed);
@@ -1701,20 +1767,20 @@ async function preCompleteAndRegisterDependenciesAsync(state, fieldParserPairs,
 			if (depState) registerCompletedDependency(depState, registry);
 			continue;
 		}
-		if (Array.isArray(fieldState) && fieldState.length === 1 && require_dependency.isPendingDependencySourceState(fieldState[0])) {
+		if (Array.isArray(fieldState) && fieldState.length === 1 && require_internal_dependency.isPendingDependencySourceState(fieldState[0])) {
 			const completed = await fieldParser.complete(fieldState, require_execution_context.withChildExecPath(exec, field));
 			preCompleted.set(field, completed);
-			if (require_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
-		} else if (fieldState === void 0 && require_dependency.isPendingDependencySourceState(fieldParser.initialState)) {
+			if (require_internal_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
+		} else if (fieldState === void 0 && require_internal_dependency.isPendingDependencySourceState(fieldParser.initialState)) {
 			const completed = await fieldParser.complete([fieldParser.initialState], require_execution_context.withChildExecPath(exec, field));
 			preCompleted.set(field, completed);
-			if (require_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
-		} else if (fieldState === void 0 && require_dependency.isWrappedDependencySource(fieldParser)) {
-			const pendingState = fieldParser[require_dependency.wrappedDependencySourceMarker];
+			if (require_internal_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
+		} else if (fieldState === void 0 && require_internal_dependency.isWrappedDependencySource(fieldParser)) {
+			const pendingState = fieldParser[require_internal_dependency.wrappedDependencySourceMarker];
 			const completed = await fieldParser.complete([pendingState], require_execution_context.withChildExecPath(exec, field));
 			preCompleted.set(field, completed);
-			if (require_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
-		} else if (fieldState != null && !Array.isArray(fieldState) && !require_dependency.isDependencySourceState(fieldState) && (require_dependency.isWrappedDependencySource(fieldParser) || require_dependency.isPendingDependencySourceState(fieldParser.initialState))) {
+			if (require_internal_dependency.isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
+		} else if (fieldState != null && !Array.isArray(fieldState) && !require_internal_dependency.isDependencySourceState(fieldState) && (require_internal_dependency.isWrappedDependencySource(fieldParser) || require_internal_dependency.isPendingDependencySourceState(fieldParser.initialState))) {
 			const annotatedFieldState$1 = getAnnotatedFieldState(state, field, fieldParser);
 			const completed = await fieldParser.complete(annotatedFieldState$1, require_execution_context.withChildExecPath(exec, field));
 			preCompleted.set(field, completed);
@@ -1768,6 +1834,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		};
 	};
 	if (!options.allowDuplicates) checkDuplicateOptionNames(parserPairs.map(([field, parser]) => [field, parser.usage]));
+	checkDuplicateReachableLeadingCommandNames(parserPairs.map(([field, parser]) => [field, parser]));
 	const noMatchContext = analyzeNoMatchContext(parserKeys.map((k) => parsers[k]));
 	const combinedMode = parserKeys.some((k) => parsers[k].mode === "async") ? "async" : "sync";
 	const getInitialError = (context) => ({
@@ -2301,7 +2368,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		configurable: true,
 		enumerable: false
 	});
-	require_parser.defineInheritedAnnotationParser(objectParser);
+	require_internal_parser.defineInheritedAnnotationParser(objectParser);
 	return objectParser;
 }
 function isParserLike(value) {
@@ -2485,15 +2552,15 @@ function collectRetainedLeadingCandidatesAtState(terms, state) {
 function createSeqState(sourceState, index, states) {
 	const seqState = {
 		index,
-		states: require_annotations.annotateFreshArray(sourceState, states)
+		states: require_internal_annotations.annotateFreshArray(sourceState, states)
 	};
-	return require_annotations.inheritAnnotations(sourceState, seqState);
+	return require_internal_annotations.inheritAnnotations(sourceState, seqState);
 }
 function getSeqChildState(seqState, index, parser) {
 	return require_annotation_state.getWrappedChildState(seqState, seqState.states[index], parser);
 }
 function updateSeqChildState(sourceState, index, childState, parser) {
-	return require_annotations.annotateFreshArray(sourceState.states, sourceState.states.map((state, stateIndex) => stateIndex === index ? require_annotation_state.getWrappedChildState(sourceState.states, childState, parser) : state));
+	return require_internal_annotations.annotateFreshArray(sourceState.states, sourceState.states.map((state, stateIndex) => stateIndex === index ? require_annotation_state.getWrappedChildState(sourceState.states, childState, parser) : state));
 }
 function shouldAdvanceSeqBeforeParse(parser, parserState, initialParserState, currentContext, index, parsers) {
 	const token = currentContext.buffer[0];
@@ -2586,7 +2653,7 @@ async function advanceSeqSuggestContextAsync(context, parsers, initialStates) {
 function createSeqComplete(parsers, combinedMode) {
 	const syncParsers = parsers;
 	return (state, exec) => require_mode_dispatch.dispatchByMode(combinedMode, () => {
-		const stateArray = require_annotations.annotateFreshArray(state, state.states);
+		const stateArray = require_internal_annotations.annotateFreshArray(state, state.states);
 		const runtime = exec?.dependencyRuntime ?? require_dependency_runtime.createDependencyRuntimeContext(exec?.dependencyRegistry);
 		const childExec = {
 			...exec,
@@ -2626,7 +2693,7 @@ function createSeqComplete(parsers, combinedMode) {
 			} : {}
 		};
 	}, async () => {
-		const stateArray = require_annotations.annotateFreshArray(state, state.states);
+		const stateArray = require_internal_annotations.annotateFreshArray(state, state.states);
 		const runtime = exec?.dependencyRuntime ?? require_dependency_runtime.createDependencyRuntimeContext(exec?.dependencyRegistry);
 		const childExec = {
 			...exec,
@@ -2748,7 +2815,7 @@ function advanceTupleSuggestContextSync(context, parsers) {
 		for (const [parser, index] of remainingParsers) {
 			const result = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 			if (result.success && result.consumed.length > 0) {
-				const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((state, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : state));
+				const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((state, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : state));
 				const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 				currentContext = {
 					...currentContext,
@@ -2773,7 +2840,7 @@ function advanceTupleSuggestContextSync(context, parsers) {
 		if (!foundMatch) for (const [parser, index] of remainingParsers) {
 			const result = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 			if (result.success && result.consumed.length < 1) {
-				const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((state, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : state));
+				const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((state, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : state));
 				const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 				currentContext = {
 					...currentContext,
@@ -2814,7 +2881,7 @@ async function advanceTupleSuggestContextAsync(context, parsers) {
 		for (const [parser, index] of remainingParsers) {
 			const result = await parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 			if (result.success && result.consumed.length > 0) {
-				const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((state, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : state));
+				const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((state, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : state));
 				const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 				currentContext = {
 					...currentContext,
@@ -2839,7 +2906,7 @@ async function advanceTupleSuggestContextAsync(context, parsers) {
 		if (!foundMatch) for (const [parser, index] of remainingParsers) {
 			const result = await parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 			if (result.success && result.consumed.length < 1) {
-				const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((state, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : state));
+				const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((state, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : state));
 				const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 				currentContext = {
 					...currentContext,
@@ -2875,7 +2942,7 @@ function markFailedTupleSuggestSources(parsers, stateArray, failedParserIndexes,
 		const parser = parsers[index];
 		if (parser == null) continue;
 		const parserState = stateArray && Array.isArray(stateArray) ? stateArray[index] : parser.initialState;
-		const nodes = require_parser.getParserSuggestRuntimeNodes(parser, require_annotation_state.getWrappedChildState(stateArray, parserState, parser), [...prefix, index]);
+		const nodes = require_internal_parser.getParserSuggestRuntimeNodes(parser, require_annotation_state.getWrappedChildState(stateArray, parserState, parser), [...prefix, index]);
 		if (nodes.length < 1) continue;
 		const failedRuntime = require_dependency_runtime.createDependencyRuntimeContext();
 		require_dependency_runtime.collectExplicitSourceValues(nodes, failedRuntime);
@@ -2892,7 +2959,7 @@ async function markFailedTupleSuggestSourcesAsync(parsers, stateArray, failedPar
 		const parser = parsers[index];
 		if (parser == null) continue;
 		const parserState = stateArray && Array.isArray(stateArray) ? stateArray[index] : parser.initialState;
-		const nodes = require_parser.getParserSuggestRuntimeNodes(parser, require_annotation_state.getWrappedChildState(stateArray, parserState, parser), [...prefix, index]);
+		const nodes = require_internal_parser.getParserSuggestRuntimeNodes(parser, require_annotation_state.getWrappedChildState(stateArray, parserState, parser), [...prefix, index]);
 		if (nodes.length < 1) continue;
 		const failedRuntime = require_dependency_runtime.createDependencyRuntimeContext();
 		await require_dependency_runtime.collectExplicitSourceValuesAsync(nodes, failedRuntime);
@@ -2932,7 +2999,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			for (const [parser, index] of remainingParsers) {
 				const result = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 				if (result.success && result.consumed.length > 0) {
-					const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
+					const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -2953,7 +3020,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			if (!foundMatch) for (const [parser, index] of remainingParsers) {
 				const result = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 				if (result.success && result.consumed.length < 1) {
-					const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
+					const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -2999,7 +3066,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				const resultOrPromise = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 				const result = await resultOrPromise;
 				if (result.success && result.consumed.length > 0) {
-					const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
+					const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -3021,7 +3088,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				const resultOrPromise = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 				const result = await resultOrPromise;
 				if (result.success && result.consumed.length < 1) {
-					const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
+					const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -3299,7 +3366,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		configurable: true,
 		enumerable: false
 	});
-	require_parser.defineInheritedAnnotationParser(tupleParser);
+	require_internal_parser.defineInheritedAnnotationParser(tupleParser);
 	return tupleParser;
 }
 function seq(...rawArgs) {
@@ -3627,7 +3694,7 @@ function seq(...rawArgs) {
 		configurable: true,
 		enumerable: false
 	});
-	require_parser.defineInheritedAnnotationParser(seqParser);
+	require_internal_parser.defineInheritedAnnotationParser(seqParser);
 	return seqParser;
 }
 function merge(...args) {
@@ -3651,6 +3718,7 @@ function merge(...args) {
 	const syncSorted = syncWithIndex.toSorted(([a], [b]) => b.priority - a.priority);
 	const syncParsers = syncSorted.map(([p]) => p);
 	if (!options.allowDuplicates) checkDuplicateOptionNames(sorted.map(([parser, originalIndex]) => [String(originalIndex), parser.usage]));
+	checkDuplicateReachableLeadingCommandNames(sorted.map(([parser, originalIndex]) => [String(originalIndex), parser]));
 	const mergedFieldParsers = collectChildFieldParsers(parsers);
 	const duplicateOutputFieldNames = collectDuplicateFieldNames(mergedFieldParsers);
 	const parserStateKey = (index) => `__parser_${index}`;
@@ -3826,8 +3894,8 @@ function merge(...args) {
 					if (resolvedState && typeof resolvedState === "object") {
 						const extractedState = {};
 						for (const field in parser.initialState) extractedState[field] = field in resolvedState ? resolvedState[field] : parser.initialState[field];
-						const annotations = require_annotations.getAnnotations(resolvedState);
-						if (annotations !== void 0) return require_annotations.inheritAnnotations(resolvedState, extractedState);
+						const annotations = require_internal_annotations.getAnnotations(resolvedState);
+						if (annotations !== void 0) return require_internal_annotations.inheritAnnotations(resolvedState, extractedState);
 						return extractedState;
 					}
 					return parser.initialState;
@@ -3980,7 +4048,7 @@ function merge(...args) {
 					if (resolvedState && typeof resolvedState === "object") {
 						const extractedState = {};
 						for (const field in parser.initialState) extractedState[field] = field in resolvedState ? resolvedState[field] : parser.initialState[field];
-						return require_annotations.inheritAnnotations(resolvedState, extractedState);
+						return require_internal_annotations.inheritAnnotations(resolvedState, extractedState);
 					}
 					return parser.initialState;
 				}
@@ -4277,7 +4345,7 @@ function merge(...args) {
 			};
 		}
 	};
-	require_parser.defineInheritedAnnotationParser(mergeParser);
+	require_internal_parser.defineInheritedAnnotationParser(mergeParser);
 	return mergeParser;
 }
 /**
@@ -4413,7 +4481,7 @@ async function seedSuggestRuntimeFromFieldParsersAsync(parser, state, runtime, p
 */
 function preParseSuggestContext(context, parsers) {
 	if (context.buffer.length < 1 || !Array.isArray(context.state)) return context;
-	return preParseSuggestLoop(context, require_annotations.annotateFreshArray(context.state, context.state.slice()), parsers);
+	return preParseSuggestLoop(context, require_internal_annotations.annotateFreshArray(context.state, context.state.slice()), parsers);
 }
 /**
 * Async variant of {@link preParseSuggestContext} that awaits async child
@@ -4422,7 +4490,7 @@ function preParseSuggestContext(context, parsers) {
 */
 async function preParseSuggestContextAsync(context, parsers) {
 	if (context.buffer.length < 1 || !Array.isArray(context.state)) return context;
-	return await preParseSuggestLoop(context, require_annotations.annotateFreshArray(context.state, context.state.slice()), parsers);
+	return await preParseSuggestLoop(context, require_internal_annotations.annotateFreshArray(context.state, context.state.slice()), parsers);
 }
 /**
 * Shared loop for sync and async concat suggest pre-parse.  When a child
@@ -4529,7 +4597,7 @@ function concat(...parsers) {
 			for (const [parser, index] of remainingParsers) {
 				const result = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 				if (result.success && result.consumed.length > 0) {
-					const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
+					const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -4550,7 +4618,7 @@ function concat(...parsers) {
 			if (!foundMatch) for (const [parser, index] of remainingParsers) {
 				const result = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 				if (result.success && result.consumed.length < 1) {
-					const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
+					const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -4595,7 +4663,7 @@ function concat(...parsers) {
 			for (const [parser, index] of remainingParsers) {
 				const result = await parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 				if (result.success && result.consumed.length > 0) {
-					const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
+					const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -4616,7 +4684,7 @@ function concat(...parsers) {
 			if (!foundMatch) for (const [parser, index] of remainingParsers) {
 				const result = await parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
 				if (result.success && result.consumed.length < 1) {
-					const newStateArray = require_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
+					const newStateArray = require_internal_annotations.annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? require_annotation_state.getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = require_execution_context.mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -4891,7 +4959,7 @@ function concat(...parsers) {
 			return { fragments: result };
 		}
 	};
-	require_parser.defineInheritedAnnotationParser(concatParser);
+	require_internal_parser.defineInheritedAnnotationParser(concatParser);
 	return concatParser;
 }
 function group(label, parser, options = {}) {
@@ -5951,7 +6019,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			return { fragments };
 		}
 	};
-	require_parser.defineInheritedAnnotationParser(conditionalParser);
+	require_internal_parser.defineInheritedAnnotationParser(conditionalParser);
 	return conditionalParser;
 }