@optique/core 1.0.0-dev.1510 → 1.0.0-dev.1519

package/dist/facade.cjs

@@ -587,6 +587,45 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	const versionCommandNames = versionCommandConfig?.names ?? ["version"];
 	const completionCommandNames = completionCommandConfig?.names ?? ["completion"];
 	const completionOptionNames = completionOptionConfig?.names ?? ["--completion"];
+	const activeMetaEntries = [];
+	if (options.help && helpOptionConfig) activeMetaEntries.push([
+		"option",
+		"help option",
+		helpOptionNames
+	]);
+	if (options.help && helpCommandConfig) activeMetaEntries.push([
+		"command",
+		"help command",
+		helpCommandNames
+	]);
+	if (options.version && versionOptionConfig) activeMetaEntries.push([
+		"option",
+		"version option",
+		versionOptionNames
+	]);
+	if (options.version && versionCommandConfig) activeMetaEntries.push([
+		"command",
+		"version command",
+		versionCommandNames
+	]);
+	if (options.completion && completionOptionConfig) activeMetaEntries.push([
+		"option",
+		"completion option",
+		completionOptionNames,
+		true
+	]);
+	if (options.completion && completionCommandConfig) activeMetaEntries.push([
+		"command",
+		"completion command",
+		completionCommandNames
+	]);
+	require_validate.validateMetaNameCollisions({
+		leadingOptions: require_usage.extractLeadingOptionNames(parser.usage, true),
+		leadingCommands: require_usage.extractLeadingCommandNames(parser.usage, true),
+		allOptions: require_usage.extractOptionNames(parser.usage, true),
+		allCommands: require_usage.extractCommandNames(parser.usage, true),
+		allLiterals: require_usage.extractLiteralValues(parser.usage)
+	}, activeMetaEntries);
 	const defaultShells = {
 		bash: require_completion.bash,
 		fish: require_completion.fish,
@@ -1173,15 +1212,15 @@ function disposeContextsSync(contexts) {
 */
 async function runWith(parser, programName, contexts, options) {
 	const args = options?.args ?? [];
-	if (needsEarlyExit(args, options)) {
-		if (parser.$mode === "async") return runParser(parser, programName, args, options);
-		return Promise.resolve(runParser(parser, programName, args, options));
-	}
 	if (contexts.length === 0) {
 		if (parser.$mode === "async") return runParser(parser, programName, args, options);
 		return Promise.resolve(runParser(parser, programName, args, options));
 	}
 	try {
+		if (needsEarlyExit(args, options)) {
+			if (parser.$mode === "async") return runParser(parser, programName, args, options);
+			return Promise.resolve(runParser(parser, programName, args, options));
+		}
 		const ctxOptions = options?.contextOptions;
 		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts, ctxOptions);
 		if (!needsTwoPhase) {
@@ -1245,9 +1284,9 @@ async function runWith(parser, programName, contexts, options) {
 function runWithSync(parser, programName, contexts, options) {
 	if (parser.$mode !== "sync") throw new TypeError("Cannot use an async parser with runWithSync(). Use runWith() or runWithAsync() instead.");
 	const args = options?.args ?? [];
-	if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 	if (contexts.length === 0) return runParser(parser, programName, args, options);
 	try {
+		if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 		const ctxOptions = options?.contextOptions;
 		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts, ctxOptions);
 		if (!needsTwoPhase) {

package/dist/facade.js

@@ -2,8 +2,8 @@ import { injectAnnotations } from "./annotations.js";
 import { commandLine, formatMessage, lineBreak, message, optionName, text, value } from "./message.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { dispatchByMode } from "./mode-dispatch.js";
-import { validateCommandNames, validateOptionNames } from "./validate.js";
-import { formatUsage } from "./usage.js";
+import { validateCommandNames, validateMetaNameCollisions, validateOptionNames } from "./validate.js";
+import { extractCommandNames, extractLeadingCommandNames, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage } from "./usage.js";
 import { formatDocPage } from "./doc.js";
 import { group, longestMatch, object } from "./constructs.js";
 import { multiple, optional, withDefault } from "./modifiers.js";
@@ -587,6 +587,45 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	const versionCommandNames = versionCommandConfig?.names ?? ["version"];
 	const completionCommandNames = completionCommandConfig?.names ?? ["completion"];
 	const completionOptionNames = completionOptionConfig?.names ?? ["--completion"];
+	const activeMetaEntries = [];
+	if (options.help && helpOptionConfig) activeMetaEntries.push([
+		"option",
+		"help option",
+		helpOptionNames
+	]);
+	if (options.help && helpCommandConfig) activeMetaEntries.push([
+		"command",
+		"help command",
+		helpCommandNames
+	]);
+	if (options.version && versionOptionConfig) activeMetaEntries.push([
+		"option",
+		"version option",
+		versionOptionNames
+	]);
+	if (options.version && versionCommandConfig) activeMetaEntries.push([
+		"command",
+		"version command",
+		versionCommandNames
+	]);
+	if (options.completion && completionOptionConfig) activeMetaEntries.push([
+		"option",
+		"completion option",
+		completionOptionNames,
+		true
+	]);
+	if (options.completion && completionCommandConfig) activeMetaEntries.push([
+		"command",
+		"completion command",
+		completionCommandNames
+	]);
+	validateMetaNameCollisions({
+		leadingOptions: extractLeadingOptionNames(parser.usage, true),
+		leadingCommands: extractLeadingCommandNames(parser.usage, true),
+		allOptions: extractOptionNames(parser.usage, true),
+		allCommands: extractCommandNames(parser.usage, true),
+		allLiterals: extractLiteralValues(parser.usage)
+	}, activeMetaEntries);
 	const defaultShells = {
 		bash,
 		fish,
@@ -1173,15 +1212,15 @@ function disposeContextsSync(contexts) {
 */
 async function runWith(parser, programName, contexts, options) {
 	const args = options?.args ?? [];
-	if (needsEarlyExit(args, options)) {
-		if (parser.$mode === "async") return runParser(parser, programName, args, options);
-		return Promise.resolve(runParser(parser, programName, args, options));
-	}
 	if (contexts.length === 0) {
 		if (parser.$mode === "async") return runParser(parser, programName, args, options);
 		return Promise.resolve(runParser(parser, programName, args, options));
 	}
 	try {
+		if (needsEarlyExit(args, options)) {
+			if (parser.$mode === "async") return runParser(parser, programName, args, options);
+			return Promise.resolve(runParser(parser, programName, args, options));
+		}
 		const ctxOptions = options?.contextOptions;
 		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts, ctxOptions);
 		if (!needsTwoPhase) {
@@ -1245,9 +1284,9 @@ async function runWith(parser, programName, contexts, options) {
 function runWithSync(parser, programName, contexts, options) {
 	if (parser.$mode !== "sync") throw new TypeError("Cannot use an async parser with runWithSync(). Use runWith() or runWithAsync() instead.");
 	const args = options?.args ?? [];
-	if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 	if (contexts.length === 0) return runParser(parser, programName, args, options);
 	try {
+		if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 		const ctxOptions = options?.contextOptions;
 		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts, ctxOptions);
 		if (!needsTwoPhase) {

package/dist/index.cjs

@@ -53,6 +53,9 @@ exports.ensureNonEmptyString = require_nonempty.ensureNonEmptyString;
 exports.envVar = require_message.envVar;
 exports.extractArgumentMetavars = require_usage.extractArgumentMetavars;
 exports.extractCommandNames = require_usage.extractCommandNames;
+exports.extractLeadingCommandNames = require_usage.extractLeadingCommandNames;
+exports.extractLeadingOptionNames = require_usage.extractLeadingOptionNames;
+exports.extractLiteralValues = require_usage.extractLiteralValues;
 exports.extractOptionNames = require_usage.extractOptionNames;
 exports.fail = require_primitives.fail;
 exports.fish = require_completion.fish;

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { Annotations, ParseOptions, annotationKey, getAnnotations } from "./annotations.cjs";
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.cjs";
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.cjs";
-import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.cjs";
+import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.cjs";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.cjs";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DeferredMap, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.cjs";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
@@ -12,4 +12,4 @@ import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, Mode
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { ParserValuePlaceholder, SourceContext } from "./context.cjs";
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { Annotations, ParseOptions, annotationKey, getAnnotations } from "./annotations.js";
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
-import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
+import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.js";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DeferredMap, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.js";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
@@ -12,4 +12,4 @@ import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, Mode
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { ParserValuePlaceholder, SourceContext } from "./context.js";
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.js

@@ -2,7 +2,7 @@ import { annotationKey, getAnnotations } from "./annotations.js";
 import { commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { DependencyRegistry, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.js";
-import { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
+import { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
 import { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.js";
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
@@ -12,4 +12,4 @@ import { argument, command, constant, fail, flag, option, passThrough } from "./
 import { getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
 import { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 
-export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/usage.cjs

@@ -41,6 +41,8 @@ function mergeHidden(a, b) {
 * multiple, and exclusive terms.
 *
 * @param usage The usage description to extract option names from.
+* @param includeHidden Whether to include fully hidden options (`hidden: true`)
+*   in the result.  Defaults to `false`.
 * @returns A set containing all option names found in the usage description.
 *
 * @example
@@ -53,12 +55,12 @@ function mergeHidden(a, b) {
 * // names = Set(["--verbose", "-v", "--quiet", "-q"])
 * ```
 */
-function extractOptionNames(usage) {
+function extractOptionNames(usage, includeHidden) {
 	const names = /* @__PURE__ */ new Set();
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
 		for (const term of terms) if (term.type === "option") {
-			if (isSuggestionHidden(term.hidden)) continue;
+			if (!includeHidden && isSuggestionHidden(term.hidden)) continue;
 			for (const name of term.names) names.add(name);
 		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
@@ -72,8 +74,10 @@ function extractOptionNames(usage) {
 * This function recursively traverses the usage structure and collects
 * all command names, similar to {@link extractOptionNames}.
 *
-* @param usage The usage structure to extract command names from
-* @returns A Set of all command names found in the usage structure
+* @param usage The usage structure to extract command names from.
+* @param includeHidden Whether to include fully hidden commands
+*   (`hidden: true`) in the result.  Defaults to `false`.
+* @returns A set of all command names found in the usage structure.
 *
 * @example
 * ```typescript
@@ -86,12 +90,12 @@ function extractOptionNames(usage) {
 * ```
 * @since 0.7.0
 */
-function extractCommandNames(usage) {
+function extractCommandNames(usage, includeHidden) {
 	const names = /* @__PURE__ */ new Set();
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
 		for (const term of terms) if (term.type === "command") {
-			if (isSuggestionHidden(term.hidden)) continue;
+			if (!includeHidden && isSuggestionHidden(term.hidden)) continue;
 			names.add(term.name);
 		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
@@ -100,6 +104,164 @@ function extractCommandNames(usage) {
 	return names;
 }
 /**
+* Extracts option names that are reachable at the leading token position
+* (before any command or argument gate).
+*
+* Unlike {@link extractOptionNames}, which traverses the entire usage tree,
+* this function stops scanning a terms array after encountering a `command`,
+* `argument`, or `literal` term, because subsequent terms are scoped under
+* that positional token.  It still recurses into `optional`, `multiple`,
+* and `exclusive` containers, since they represent alternatives or wrappers
+* at the same position.
+*
+* Known limitation: this function infers token positions from the `usage`
+* tree, which is a display-oriented structure.  Combinators like `tuple()`
+* and `object()` sort or flatten usage by priority rather than token order,
+* so the results can be inaccurate—both false positives (e.g., options
+* appearing before commands due to priority sorting) and false negatives
+* (e.g., options after commands that are actually parallel peers).
+* The proper fix is to use `Parser.leadingNames` instead of usage-tree
+* analysis.  This also cannot detect `conditional(argument(...))`
+* discriminator values, which never appear in the usage tree.
+* See https://github.com/dahlia/optique/issues/734 and
+* https://github.com/dahlia/optique/issues/735
+*
+* @param usage The usage description to extract leading option names from.
+* @param includeHidden Whether to include fully hidden options
+*   (`hidden: true`) in the result.  Defaults to `false`.
+* @returns A set of option names reachable at the leading token position.
+* @since 1.0.0
+*/
+function extractLeadingOptionNames(usage, includeHidden) {
+	const names = /* @__PURE__ */ new Set();
+	function collectLeading(terms) {
+		if (!terms || !Array.isArray(terms)) return;
+		for (const term of terms) switch (term.type) {
+			case "option":
+				if (!includeHidden && isSuggestionHidden(term.hidden)) break;
+				for (const name of term.names) names.add(name);
+				break;
+			case "command": return;
+			case "argument":
+			case "literal": return;
+			case "optional":
+				collectLeading(term.terms);
+				break;
+			case "multiple":
+				collectLeading(term.terms);
+				if (term.min > 0 && branchConsumesToken(term.terms)) return;
+				break;
+			case "exclusive":
+				for (const branch of term.terms) collectLeading(branch);
+				if (exclusiveConsumesToken(term.terms)) return;
+				break;
+			default: break;
+		}
+	}
+	collectLeading(usage);
+	return names;
+}
+/**
+* Extracts command names that could match as the first positional token.
+*
+* Unlike {@link extractCommandNames}, which traverses the entire usage tree,
+* this function stops scanning a terms array after encountering a `command`,
+* `argument`, or `literal` term, because subsequent terms in that array are
+* scoped under that positional token (reachable only after the leading term
+* is consumed).  It still recurses into `optional`, `multiple`, and
+* `exclusive` containers, since they represent alternatives or optional
+* wrappers at the same token position.
+*
+* Known limitation: this function has the same usage-tree ordering and
+* `conditional(argument(...))` caveats as {@link extractLeadingOptionNames}.
+* See https://github.com/dahlia/optique/issues/734 and
+* https://github.com/dahlia/optique/issues/735
+*
+* @param usage The usage description to extract leading command names from.
+* @param includeHidden Whether to include fully hidden commands
+*   (`hidden: true`) in the result.  Defaults to `false`.
+* @returns A set of command names that could match at the first token position.
+* @since 1.0.0
+*/
+function extractLeadingCommandNames(usage, includeHidden) {
+	const names = /* @__PURE__ */ new Set();
+	function collectLeading(terms) {
+		if (!terms || !Array.isArray(terms)) return;
+		for (const term of terms) switch (term.type) {
+			case "command":
+				if (!includeHidden && isSuggestionHidden(term.hidden)) return;
+				names.add(term.name);
+				return;
+			case "argument":
+			case "literal": return;
+			case "optional":
+				collectLeading(term.terms);
+				break;
+			case "multiple":
+				collectLeading(term.terms);
+				if (term.min > 0 && branchConsumesToken(term.terms)) return;
+				break;
+			case "exclusive":
+				for (const branch of term.terms) collectLeading(branch);
+				if (exclusiveConsumesToken(term.terms)) return;
+				break;
+			default: break;
+		}
+	}
+	collectLeading(usage);
+	return names;
+}
+/**
+* Checks whether every branch of an exclusive term must consume a positional
+* token.  When true, terms after the exclusive are at position N+1 and should
+* not be considered "leading".
+*/
+function exclusiveConsumesToken(branches) {
+	if (branches.length === 0) return false;
+	return branches.every((branch) => branchConsumesToken(branch));
+}
+function branchConsumesToken(terms) {
+	if (!terms || !Array.isArray(terms)) return false;
+	for (const term of terms) switch (term.type) {
+		case "command":
+		case "argument":
+		case "literal": return true;
+		case "option": break;
+		case "optional": break;
+		case "multiple":
+			if (term.min > 0 && branchConsumesToken(term.terms)) return true;
+			break;
+		case "exclusive":
+			if (exclusiveConsumesToken(term.terms)) return true;
+			break;
+		default: break;
+	}
+	return false;
+}
+/**
+* Extracts all literal values from a usage description.
+*
+* This function recursively traverses the usage tree and collects all
+* `literal` term values.  Literal values represent fixed strings that
+* the user must type (e.g., conditional discriminator values like
+* `"server"` in `conditional(option("--mode", string()), { server: ... })`).
+*
+* @param usage The usage description to extract literal values from.
+* @returns A set of all literal values found in the usage description.
+* @since 1.0.0
+*/
+function extractLiteralValues(usage) {
+	const values = /* @__PURE__ */ new Set();
+	function traverseUsage(terms) {
+		if (!terms || !Array.isArray(terms)) return;
+		for (const term of terms) if (term.type === "literal") values.add(term.value);
+		else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+		else if (term.type === "exclusive") for (const branch of term.terms) traverseUsage(branch);
+	}
+	traverseUsage(usage);
+	return values;
+}
+/**
 * Extracts all argument metavars from a Usage array.
 *
 * This function recursively traverses the usage structure and collects
@@ -551,6 +713,9 @@ exports.cloneUsage = cloneUsage;
 exports.cloneUsageTerm = cloneUsageTerm;
 exports.extractArgumentMetavars = extractArgumentMetavars;
 exports.extractCommandNames = extractCommandNames;
+exports.extractLeadingCommandNames = extractLeadingCommandNames;
+exports.extractLeadingOptionNames = extractLeadingOptionNames;
+exports.extractLiteralValues = extractLiteralValues;
 exports.extractOptionNames = extractOptionNames;
 exports.formatUsage = formatUsage;
 exports.formatUsageTerm = formatUsageTerm;

package/dist/usage.d.cts

@@ -220,6 +220,8 @@ type Usage = readonly UsageTerm[];
  * multiple, and exclusive terms.
  *
  * @param usage The usage description to extract option names from.
+ * @param includeHidden Whether to include fully hidden options (`hidden: true`)
+ *   in the result.  Defaults to `false`.
  * @returns A set containing all option names found in the usage description.
  *
  * @example
@@ -232,15 +234,17 @@ type Usage = readonly UsageTerm[];
  * // names = Set(["--verbose", "-v", "--quiet", "-q"])
  * ```
  */
-declare function extractOptionNames(usage: Usage): Set<string>;
+declare function extractOptionNames(usage: Usage, includeHidden?: boolean): Set<string>;
 /**
  * Extracts all command names from a Usage array.
  *
  * This function recursively traverses the usage structure and collects
  * all command names, similar to {@link extractOptionNames}.
  *
- * @param usage The usage structure to extract command names from
- * @returns A Set of all command names found in the usage structure
+ * @param usage The usage structure to extract command names from.
+ * @param includeHidden Whether to include fully hidden commands
+ *   (`hidden: true`) in the result.  Defaults to `false`.
+ * @returns A set of all command names found in the usage structure.
  *
  * @example
  * ```typescript
@@ -253,7 +257,73 @@ declare function extractOptionNames(usage: Usage): Set<string>;
  * ```
  * @since 0.7.0
  */
-declare function extractCommandNames(usage: Usage): Set<string>;
+declare function extractCommandNames(usage: Usage, includeHidden?: boolean): Set<string>;
+/**
+ * Extracts option names that are reachable at the leading token position
+ * (before any command or argument gate).
+ *
+ * Unlike {@link extractOptionNames}, which traverses the entire usage tree,
+ * this function stops scanning a terms array after encountering a `command`,
+ * `argument`, or `literal` term, because subsequent terms are scoped under
+ * that positional token.  It still recurses into `optional`, `multiple`,
+ * and `exclusive` containers, since they represent alternatives or wrappers
+ * at the same position.
+ *
+ * Known limitation: this function infers token positions from the `usage`
+ * tree, which is a display-oriented structure.  Combinators like `tuple()`
+ * and `object()` sort or flatten usage by priority rather than token order,
+ * so the results can be inaccurate—both false positives (e.g., options
+ * appearing before commands due to priority sorting) and false negatives
+ * (e.g., options after commands that are actually parallel peers).
+ * The proper fix is to use `Parser.leadingNames` instead of usage-tree
+ * analysis.  This also cannot detect `conditional(argument(...))`
+ * discriminator values, which never appear in the usage tree.
+ * See https://github.com/dahlia/optique/issues/734 and
+ * https://github.com/dahlia/optique/issues/735
+ *
+ * @param usage The usage description to extract leading option names from.
+ * @param includeHidden Whether to include fully hidden options
+ *   (`hidden: true`) in the result.  Defaults to `false`.
+ * @returns A set of option names reachable at the leading token position.
+ * @since 1.0.0
+ */
+declare function extractLeadingOptionNames(usage: Usage, includeHidden?: boolean): Set<string>;
+/**
+ * Extracts command names that could match as the first positional token.
+ *
+ * Unlike {@link extractCommandNames}, which traverses the entire usage tree,
+ * this function stops scanning a terms array after encountering a `command`,
+ * `argument`, or `literal` term, because subsequent terms in that array are
+ * scoped under that positional token (reachable only after the leading term
+ * is consumed).  It still recurses into `optional`, `multiple`, and
+ * `exclusive` containers, since they represent alternatives or optional
+ * wrappers at the same token position.
+ *
+ * Known limitation: this function has the same usage-tree ordering and
+ * `conditional(argument(...))` caveats as {@link extractLeadingOptionNames}.
+ * See https://github.com/dahlia/optique/issues/734 and
+ * https://github.com/dahlia/optique/issues/735
+ *
+ * @param usage The usage description to extract leading command names from.
+ * @param includeHidden Whether to include fully hidden commands
+ *   (`hidden: true`) in the result.  Defaults to `false`.
+ * @returns A set of command names that could match at the first token position.
+ * @since 1.0.0
+ */
+declare function extractLeadingCommandNames(usage: Usage, includeHidden?: boolean): Set<string>;
+/**
+ * Extracts all literal values from a usage description.
+ *
+ * This function recursively traverses the usage tree and collects all
+ * `literal` term values.  Literal values represent fixed strings that
+ * the user must type (e.g., conditional discriminator values like
+ * `"server"` in `conditional(option("--mode", string()), { server: ... })`).
+ *
+ * @param usage The usage description to extract literal values from.
+ * @returns A set of all literal values found in the usage description.
+ * @since 1.0.0
+ */
+declare function extractLiteralValues(usage: Usage): Set<string>;
 /**
  * Extracts all argument metavars from a Usage array.
  *
@@ -417,4 +487,4 @@ interface UsageTermFormatOptions extends UsageFormatOptions {
  */
 declare function formatUsageTerm(term: UsageTerm, options?: UsageTermFormatOptions): string;
 //#endregion
-export { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };
+export { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };

package/dist/usage.d.ts

@@ -220,6 +220,8 @@ type Usage = readonly UsageTerm[];
  * multiple, and exclusive terms.
  *
  * @param usage The usage description to extract option names from.
+ * @param includeHidden Whether to include fully hidden options (`hidden: true`)
+ *   in the result.  Defaults to `false`.
  * @returns A set containing all option names found in the usage description.
  *
  * @example
@@ -232,15 +234,17 @@ type Usage = readonly UsageTerm[];
  * // names = Set(["--verbose", "-v", "--quiet", "-q"])
  * ```
  */
-declare function extractOptionNames(usage: Usage): Set<string>;
+declare function extractOptionNames(usage: Usage, includeHidden?: boolean): Set<string>;
 /**
  * Extracts all command names from a Usage array.
  *
  * This function recursively traverses the usage structure and collects
  * all command names, similar to {@link extractOptionNames}.
  *
- * @param usage The usage structure to extract command names from
- * @returns A Set of all command names found in the usage structure
+ * @param usage The usage structure to extract command names from.
+ * @param includeHidden Whether to include fully hidden commands
+ *   (`hidden: true`) in the result.  Defaults to `false`.
+ * @returns A set of all command names found in the usage structure.
  *
  * @example
  * ```typescript
@@ -253,7 +257,73 @@ declare function extractOptionNames(usage: Usage): Set<string>;
  * ```
  * @since 0.7.0
  */
-declare function extractCommandNames(usage: Usage): Set<string>;
+declare function extractCommandNames(usage: Usage, includeHidden?: boolean): Set<string>;
+/**
+ * Extracts option names that are reachable at the leading token position
+ * (before any command or argument gate).
+ *
+ * Unlike {@link extractOptionNames}, which traverses the entire usage tree,
+ * this function stops scanning a terms array after encountering a `command`,
+ * `argument`, or `literal` term, because subsequent terms are scoped under
+ * that positional token.  It still recurses into `optional`, `multiple`,
+ * and `exclusive` containers, since they represent alternatives or wrappers
+ * at the same position.
+ *
+ * Known limitation: this function infers token positions from the `usage`
+ * tree, which is a display-oriented structure.  Combinators like `tuple()`
+ * and `object()` sort or flatten usage by priority rather than token order,
+ * so the results can be inaccurate—both false positives (e.g., options
+ * appearing before commands due to priority sorting) and false negatives
+ * (e.g., options after commands that are actually parallel peers).
+ * The proper fix is to use `Parser.leadingNames` instead of usage-tree
+ * analysis.  This also cannot detect `conditional(argument(...))`
+ * discriminator values, which never appear in the usage tree.
+ * See https://github.com/dahlia/optique/issues/734 and
+ * https://github.com/dahlia/optique/issues/735
+ *
+ * @param usage The usage description to extract leading option names from.
+ * @param includeHidden Whether to include fully hidden options
+ *   (`hidden: true`) in the result.  Defaults to `false`.
+ * @returns A set of option names reachable at the leading token position.
+ * @since 1.0.0
+ */
+declare function extractLeadingOptionNames(usage: Usage, includeHidden?: boolean): Set<string>;
+/**
+ * Extracts command names that could match as the first positional token.
+ *
+ * Unlike {@link extractCommandNames}, which traverses the entire usage tree,
+ * this function stops scanning a terms array after encountering a `command`,
+ * `argument`, or `literal` term, because subsequent terms in that array are
+ * scoped under that positional token (reachable only after the leading term
+ * is consumed).  It still recurses into `optional`, `multiple`, and
+ * `exclusive` containers, since they represent alternatives or optional
+ * wrappers at the same token position.
+ *
+ * Known limitation: this function has the same usage-tree ordering and
+ * `conditional(argument(...))` caveats as {@link extractLeadingOptionNames}.
+ * See https://github.com/dahlia/optique/issues/734 and
+ * https://github.com/dahlia/optique/issues/735
+ *
+ * @param usage The usage description to extract leading command names from.
+ * @param includeHidden Whether to include fully hidden commands
+ *   (`hidden: true`) in the result.  Defaults to `false`.
+ * @returns A set of command names that could match at the first token position.
+ * @since 1.0.0
+ */
+declare function extractLeadingCommandNames(usage: Usage, includeHidden?: boolean): Set<string>;
+/**
+ * Extracts all literal values from a usage description.
+ *
+ * This function recursively traverses the usage tree and collects all
+ * `literal` term values.  Literal values represent fixed strings that
+ * the user must type (e.g., conditional discriminator values like
+ * `"server"` in `conditional(option("--mode", string()), { server: ... })`).
+ *
+ * @param usage The usage description to extract literal values from.
+ * @returns A set of all literal values found in the usage description.
+ * @since 1.0.0
+ */
+declare function extractLiteralValues(usage: Usage): Set<string>;
 /**
  * Extracts all argument metavars from a Usage array.
  *
@@ -417,4 +487,4 @@ interface UsageTermFormatOptions extends UsageFormatOptions {
  */
 declare function formatUsageTerm(term: UsageTerm, options?: UsageTermFormatOptions): string;
 //#endregion
-export { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };
+export { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };

package/dist/usage.js

@@ -41,6 +41,8 @@ function mergeHidden(a, b) {
 * multiple, and exclusive terms.
 *
 * @param usage The usage description to extract option names from.
+* @param includeHidden Whether to include fully hidden options (`hidden: true`)
+*   in the result.  Defaults to `false`.
 * @returns A set containing all option names found in the usage description.
 *
 * @example
@@ -53,12 +55,12 @@ function mergeHidden(a, b) {
 * // names = Set(["--verbose", "-v", "--quiet", "-q"])
 * ```
 */
-function extractOptionNames(usage) {
+function extractOptionNames(usage, includeHidden) {
 	const names = /* @__PURE__ */ new Set();
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
 		for (const term of terms) if (term.type === "option") {
-			if (isSuggestionHidden(term.hidden)) continue;
+			if (!includeHidden && isSuggestionHidden(term.hidden)) continue;
 			for (const name of term.names) names.add(name);
 		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
@@ -72,8 +74,10 @@ function extractOptionNames(usage) {
 * This function recursively traverses the usage structure and collects
 * all command names, similar to {@link extractOptionNames}.
 *
-* @param usage The usage structure to extract command names from
-* @returns A Set of all command names found in the usage structure
+* @param usage The usage structure to extract command names from.
+* @param includeHidden Whether to include fully hidden commands
+*   (`hidden: true`) in the result.  Defaults to `false`.
+* @returns A set of all command names found in the usage structure.
 *
 * @example
 * ```typescript
@@ -86,12 +90,12 @@ function extractOptionNames(usage) {
 * ```
 * @since 0.7.0
 */
-function extractCommandNames(usage) {
+function extractCommandNames(usage, includeHidden) {
 	const names = /* @__PURE__ */ new Set();
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
 		for (const term of terms) if (term.type === "command") {
-			if (isSuggestionHidden(term.hidden)) continue;
+			if (!includeHidden && isSuggestionHidden(term.hidden)) continue;
 			names.add(term.name);
 		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
@@ -100,6 +104,164 @@ function extractCommandNames(usage) {
 	return names;
 }
 /**
+* Extracts option names that are reachable at the leading token position
+* (before any command or argument gate).
+*
+* Unlike {@link extractOptionNames}, which traverses the entire usage tree,
+* this function stops scanning a terms array after encountering a `command`,
+* `argument`, or `literal` term, because subsequent terms are scoped under
+* that positional token.  It still recurses into `optional`, `multiple`,
+* and `exclusive` containers, since they represent alternatives or wrappers
+* at the same position.
+*
+* Known limitation: this function infers token positions from the `usage`
+* tree, which is a display-oriented structure.  Combinators like `tuple()`
+* and `object()` sort or flatten usage by priority rather than token order,
+* so the results can be inaccurate—both false positives (e.g., options
+* appearing before commands due to priority sorting) and false negatives
+* (e.g., options after commands that are actually parallel peers).
+* The proper fix is to use `Parser.leadingNames` instead of usage-tree
+* analysis.  This also cannot detect `conditional(argument(...))`
+* discriminator values, which never appear in the usage tree.
+* See https://github.com/dahlia/optique/issues/734 and
+* https://github.com/dahlia/optique/issues/735
+*
+* @param usage The usage description to extract leading option names from.
+* @param includeHidden Whether to include fully hidden options
+*   (`hidden: true`) in the result.  Defaults to `false`.
+* @returns A set of option names reachable at the leading token position.
+* @since 1.0.0
+*/
+function extractLeadingOptionNames(usage, includeHidden) {
+	const names = /* @__PURE__ */ new Set();
+	function collectLeading(terms) {
+		if (!terms || !Array.isArray(terms)) return;
+		for (const term of terms) switch (term.type) {
+			case "option":
+				if (!includeHidden && isSuggestionHidden(term.hidden)) break;
+				for (const name of term.names) names.add(name);
+				break;
+			case "command": return;
+			case "argument":
+			case "literal": return;
+			case "optional":
+				collectLeading(term.terms);
+				break;
+			case "multiple":
+				collectLeading(term.terms);
+				if (term.min > 0 && branchConsumesToken(term.terms)) return;
+				break;
+			case "exclusive":
+				for (const branch of term.terms) collectLeading(branch);
+				if (exclusiveConsumesToken(term.terms)) return;
+				break;
+			default: break;
+		}
+	}
+	collectLeading(usage);
+	return names;
+}
+/**
+* Extracts command names that could match as the first positional token.
+*
+* Unlike {@link extractCommandNames}, which traverses the entire usage tree,
+* this function stops scanning a terms array after encountering a `command`,
+* `argument`, or `literal` term, because subsequent terms in that array are
+* scoped under that positional token (reachable only after the leading term
+* is consumed).  It still recurses into `optional`, `multiple`, and
+* `exclusive` containers, since they represent alternatives or optional
+* wrappers at the same token position.
+*
+* Known limitation: this function has the same usage-tree ordering and
+* `conditional(argument(...))` caveats as {@link extractLeadingOptionNames}.
+* See https://github.com/dahlia/optique/issues/734 and
+* https://github.com/dahlia/optique/issues/735
+*
+* @param usage The usage description to extract leading command names from.
+* @param includeHidden Whether to include fully hidden commands
+*   (`hidden: true`) in the result.  Defaults to `false`.
+* @returns A set of command names that could match at the first token position.
+* @since 1.0.0
+*/
+function extractLeadingCommandNames(usage, includeHidden) {
+	const names = /* @__PURE__ */ new Set();
+	function collectLeading(terms) {
+		if (!terms || !Array.isArray(terms)) return;
+		for (const term of terms) switch (term.type) {
+			case "command":
+				if (!includeHidden && isSuggestionHidden(term.hidden)) return;
+				names.add(term.name);
+				return;
+			case "argument":
+			case "literal": return;
+			case "optional":
+				collectLeading(term.terms);
+				break;
+			case "multiple":
+				collectLeading(term.terms);
+				if (term.min > 0 && branchConsumesToken(term.terms)) return;
+				break;
+			case "exclusive":
+				for (const branch of term.terms) collectLeading(branch);
+				if (exclusiveConsumesToken(term.terms)) return;
+				break;
+			default: break;
+		}
+	}
+	collectLeading(usage);
+	return names;
+}
+/**
+* Checks whether every branch of an exclusive term must consume a positional
+* token.  When true, terms after the exclusive are at position N+1 and should
+* not be considered "leading".
+*/
+function exclusiveConsumesToken(branches) {
+	if (branches.length === 0) return false;
+	return branches.every((branch) => branchConsumesToken(branch));
+}
+function branchConsumesToken(terms) {
+	if (!terms || !Array.isArray(terms)) return false;
+	for (const term of terms) switch (term.type) {
+		case "command":
+		case "argument":
+		case "literal": return true;
+		case "option": break;
+		case "optional": break;
+		case "multiple":
+			if (term.min > 0 && branchConsumesToken(term.terms)) return true;
+			break;
+		case "exclusive":
+			if (exclusiveConsumesToken(term.terms)) return true;
+			break;
+		default: break;
+	}
+	return false;
+}
+/**
+* Extracts all literal values from a usage description.
+*
+* This function recursively traverses the usage tree and collects all
+* `literal` term values.  Literal values represent fixed strings that
+* the user must type (e.g., conditional discriminator values like
+* `"server"` in `conditional(option("--mode", string()), { server: ... })`).
+*
+* @param usage The usage description to extract literal values from.
+* @returns A set of all literal values found in the usage description.
+* @since 1.0.0
+*/
+function extractLiteralValues(usage) {
+	const values = /* @__PURE__ */ new Set();
+	function traverseUsage(terms) {
+		if (!terms || !Array.isArray(terms)) return;
+		for (const term of terms) if (term.type === "literal") values.add(term.value);
+		else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+		else if (term.type === "exclusive") for (const branch of term.terms) traverseUsage(branch);
+	}
+	traverseUsage(usage);
+	return values;
+}
+/**
 * Extracts all argument metavars from a Usage array.
 *
 * This function recursively traverses the usage structure and collects
@@ -547,4 +709,4 @@ function* formatUsageTermInternal(term, options) {
 }
 
 //#endregion
-export { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };
+export { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };

package/dist/validate.cjs

@@ -63,6 +63,75 @@ function validateCommandNames(names, label) {
 	}
 }
 /**
+* Validates that there are no name collisions among meta features
+* (help, version, completion) and between meta features and user parsers.
+*
+* The collision check is *position-aware*:
+*
+* - Meta **command** entries match at `args[0]` only, so they are checked
+*   against *leading* user names (those reachable before any positional gate).
+* - Meta **option** entries use lenient scanners that match anywhere in
+*   `argv`, so they are checked against *all* user names at every depth,
+*   including literal values from conditional discriminators.
+*
+* Meta-vs-meta collisions are always checked in a unified namespace,
+* because a meta command named `"--help"` and a meta option named
+* `"--help"` both compete for the same token.
+*
+* @param userNames User parser names extracted at different scopes.
+* @param metaEntries Active meta feature entries annotated with their kind.
+* @throws {TypeError} If any collision or duplicate is detected.
+* @since 1.0.0
+*/
+function validateMetaNameCollisions(userNames, metaEntries) {
+	for (const [, label, names] of metaEntries) {
+		const seen = /* @__PURE__ */ new Set();
+		for (const name of names) {
+			if (seen.has(name)) throw new TypeError(`${capitalize(label)} has a duplicate name: "${name}"`);
+			seen.add(name);
+		}
+	}
+	const nameToLabel = /* @__PURE__ */ new Map();
+	for (const [, label, names] of metaEntries) for (const name of names) {
+		const existingLabel = nameToLabel.get(name);
+		if (existingLabel != null) throw new TypeError(`Name "${name}" is used by both ${existingLabel} and ${label}.`);
+		nameToLabel.set(name, label);
+	}
+	for (let i = 0; i < metaEntries.length; i++) {
+		const [, label, names, prefixMatch] = metaEntries[i];
+		if (!prefixMatch) continue;
+		for (const name of names) {
+			const prefix = name + "=";
+			for (let j = 0; j < metaEntries.length; j++) {
+				const [, otherLabel, otherNames] = metaEntries[j];
+				for (const otherName of otherNames) {
+					if (i === j && otherName === name) continue;
+					if (!otherName.startsWith(prefix)) continue;
+					throw new TypeError("The prefix form of name \"" + name + "\" in " + label + " shadows \"" + otherName + "\" in " + otherLabel + ".");
+				}
+			}
+		}
+	}
+	for (const [kind, label, names, prefixMatch] of metaEntries) {
+		const optionNames = kind === "command" ? userNames.leadingOptions : userNames.allOptions;
+		const commandNames = kind === "command" ? userNames.leadingCommands : userNames.allCommands;
+		for (const name of names) {
+			if (optionNames.has(name)) throw new TypeError(`User-defined option "${name}" conflicts with the built-in ${label}.`);
+			if (commandNames.has(name)) throw new TypeError(`User-defined command "${name}" conflicts with the built-in ${label}.`);
+			if (kind === "option" && userNames.allLiterals.has(name)) throw new TypeError(`Literal value "${name}" conflicts with the built-in ${label}.`);
+			if (prefixMatch) {
+				const prefix = name + "=";
+				for (const userName of optionNames) if (userName.startsWith(prefix)) throw new TypeError(`User-defined option "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
+				for (const userName of commandNames) if (userName.startsWith(prefix)) throw new TypeError(`User-defined command "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
+				for (const literal of userNames.allLiterals) if (literal.startsWith(prefix)) throw new TypeError(`Literal value "${literal}" conflicts with the built-in ${label} (prefix "${prefix}").`);
+			}
+		}
+	}
+}
+function capitalize(s) {
+	return s.charAt(0).toUpperCase() + s.slice(1);
+}
+/**
 * Validates a program name at runtime.
 *
 * Program names may contain spaces (e.g., file paths), but must not be empty,
@@ -81,5 +150,6 @@ function validateProgramName(programName) {
 
 //#endregion
 exports.validateCommandNames = validateCommandNames;
+exports.validateMetaNameCollisions = validateMetaNameCollisions;
 exports.validateOptionNames = validateOptionNames;
 exports.validateProgramName = validateProgramName;

package/dist/validate.js

@@ -62,6 +62,75 @@ function validateCommandNames(names, label) {
 	}
 }
 /**
+* Validates that there are no name collisions among meta features
+* (help, version, completion) and between meta features and user parsers.
+*
+* The collision check is *position-aware*:
+*
+* - Meta **command** entries match at `args[0]` only, so they are checked
+*   against *leading* user names (those reachable before any positional gate).
+* - Meta **option** entries use lenient scanners that match anywhere in
+*   `argv`, so they are checked against *all* user names at every depth,
+*   including literal values from conditional discriminators.
+*
+* Meta-vs-meta collisions are always checked in a unified namespace,
+* because a meta command named `"--help"` and a meta option named
+* `"--help"` both compete for the same token.
+*
+* @param userNames User parser names extracted at different scopes.
+* @param metaEntries Active meta feature entries annotated with their kind.
+* @throws {TypeError} If any collision or duplicate is detected.
+* @since 1.0.0
+*/
+function validateMetaNameCollisions(userNames, metaEntries) {
+	for (const [, label, names] of metaEntries) {
+		const seen = /* @__PURE__ */ new Set();
+		for (const name of names) {
+			if (seen.has(name)) throw new TypeError(`${capitalize(label)} has a duplicate name: "${name}"`);
+			seen.add(name);
+		}
+	}
+	const nameToLabel = /* @__PURE__ */ new Map();
+	for (const [, label, names] of metaEntries) for (const name of names) {
+		const existingLabel = nameToLabel.get(name);
+		if (existingLabel != null) throw new TypeError(`Name "${name}" is used by both ${existingLabel} and ${label}.`);
+		nameToLabel.set(name, label);
+	}
+	for (let i = 0; i < metaEntries.length; i++) {
+		const [, label, names, prefixMatch] = metaEntries[i];
+		if (!prefixMatch) continue;
+		for (const name of names) {
+			const prefix = name + "=";
+			for (let j = 0; j < metaEntries.length; j++) {
+				const [, otherLabel, otherNames] = metaEntries[j];
+				for (const otherName of otherNames) {
+					if (i === j && otherName === name) continue;
+					if (!otherName.startsWith(prefix)) continue;
+					throw new TypeError("The prefix form of name \"" + name + "\" in " + label + " shadows \"" + otherName + "\" in " + otherLabel + ".");
+				}
+			}
+		}
+	}
+	for (const [kind, label, names, prefixMatch] of metaEntries) {
+		const optionNames = kind === "command" ? userNames.leadingOptions : userNames.allOptions;
+		const commandNames = kind === "command" ? userNames.leadingCommands : userNames.allCommands;
+		for (const name of names) {
+			if (optionNames.has(name)) throw new TypeError(`User-defined option "${name}" conflicts with the built-in ${label}.`);
+			if (commandNames.has(name)) throw new TypeError(`User-defined command "${name}" conflicts with the built-in ${label}.`);
+			if (kind === "option" && userNames.allLiterals.has(name)) throw new TypeError(`Literal value "${name}" conflicts with the built-in ${label}.`);
+			if (prefixMatch) {
+				const prefix = name + "=";
+				for (const userName of optionNames) if (userName.startsWith(prefix)) throw new TypeError(`User-defined option "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
+				for (const userName of commandNames) if (userName.startsWith(prefix)) throw new TypeError(`User-defined command "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
+				for (const literal of userNames.allLiterals) if (literal.startsWith(prefix)) throw new TypeError(`Literal value "${literal}" conflicts with the built-in ${label} (prefix "${prefix}").`);
+			}
+		}
+	}
+}
+function capitalize(s) {
+	return s.charAt(0).toUpperCase() + s.slice(1);
+}
+/**
 * Validates a program name at runtime.
 *
 * Program names may contain spaces (e.g., file paths), but must not be empty,
@@ -79,4 +148,4 @@ function validateProgramName(programName) {
 }
 
 //#endregion
-export { validateCommandNames, validateOptionNames, validateProgramName };
+export { validateCommandNames, validateMetaNameCollisions, validateOptionNames, validateProgramName };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1510+f054ad59",
+  "version": "1.0.0-dev.1519+797fd62b",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",