@optique/core 1.0.0-dev.1531 → 1.0.0-dev.1536

package/dist/constructs.cjs

@@ -2591,7 +2591,8 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			result.push(optionWithoutMetavar);
 			result.push({
 				type: "literal",
-				value: literalValue
+				value: literalValue,
+				optionValue: true
 			});
 		} else if (term.type === "optional") result.push({
 			...term,

package/dist/constructs.js

@@ -2591,7 +2591,8 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			result.push(optionWithoutMetavar);
 			result.push({
 				type: "literal",
-				value: literalValue
+				value: literalValue,
+				optionValue: true
 			});
 		} else if (term.type === "optional") result.push({
 			...term,

package/dist/facade.cjs

@@ -622,6 +622,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	require_validate.validateMetaNameCollisions({
 		leadingOptions: require_usage.extractLeadingOptionNames(parser.usage, true),
 		leadingCommands: require_usage.extractLeadingCommandNames(parser.usage, true),
+		leadingLiterals: require_usage.extractLeadingLiteralValues(parser.usage),
 		allOptions: require_usage.extractOptionNames(parser.usage, true),
 		allCommands: require_usage.extractCommandNames(parser.usage, true),
 		allLiterals: require_usage.extractLiteralValues(parser.usage)

package/dist/facade.js

@@ -3,7 +3,7 @@ import { commandLine, formatMessage, lineBreak, message, optionName, text, value
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { dispatchByMode } from "./mode-dispatch.js";
 import { validateCommandNames, validateMetaNameCollisions, validateOptionNames } from "./validate.js";
-import { extractCommandNames, extractLeadingCommandNames, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage } from "./usage.js";
+import { extractCommandNames, extractLeadingCommandNames, extractLeadingLiteralValues, 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";
@@ -622,6 +622,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	validateMetaNameCollisions({
 		leadingOptions: extractLeadingOptionNames(parser.usage, true),
 		leadingCommands: extractLeadingCommandNames(parser.usage, true),
+		leadingLiterals: extractLeadingLiteralValues(parser.usage),
 		allOptions: extractOptionNames(parser.usage, true),
 		allCommands: extractCommandNames(parser.usage, true),
 		allLiterals: extractLiteralValues(parser.usage)

package/dist/index.cjs

@@ -54,6 +54,7 @@ exports.envVar = require_message.envVar;
 exports.extractArgumentMetavars = require_usage.extractArgumentMetavars;
 exports.extractCommandNames = require_usage.extractCommandNames;
 exports.extractLeadingCommandNames = require_usage.extractLeadingCommandNames;
+exports.extractLeadingLiteralValues = require_usage.extractLeadingLiteralValues;
 exports.extractLeadingOptionNames = require_usage.extractLeadingOptionNames;
 exports.extractLiteralValues = require_usage.extractLiteralValues;
 exports.extractOptionNames = require_usage.extractOptionNames;

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, extractLeadingCommandNames, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.cjs";
+import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingLiteralValues, 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, 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 };
+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, extractLeadingLiteralValues, 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, extractLeadingCommandNames, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
+import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingLiteralValues, 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, 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 };
+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, extractLeadingLiteralValues, 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, extractLeadingCommandNames, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
+import { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingLiteralValues, 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, 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 };
+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, extractLeadingLiteralValues, 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/parser.cjs

@@ -52,7 +52,7 @@ function parseSync(parser, args, options) {
 		};
 		const previousBuffer = context.buffer;
 		context = result.next;
-		if (context.buffer.length > 0 && context.buffer.length === previousBuffer.length && context.buffer.every((item, i) => item === previousBuffer[i])) return {
+		if (isBufferUnchanged(previousBuffer, context.buffer)) return {
 			success: false,
 			error: require_message.message`Unexpected option or argument: ${context.buffer[0]}.`
 		};
@@ -69,6 +69,13 @@ function parseSync(parser, args, options) {
 	};
 }
 /**
+* Returns `true` when the buffer has not changed between iterations,
+* indicating a parser is stalling without consuming input.
+*/
+function isBufferUnchanged(previous, current) {
+	return current.length > 0 && current.length === previous.length && current.every((item, i) => item === previous[i]);
+}
+/**
 * Parses an array of command-line arguments using the provided combined parser.
 * This function processes the input arguments, applying the parser to each
 * argument until all arguments are consumed or an error occurs.
@@ -104,7 +111,7 @@ async function parseAsync(parser, args, options) {
 		};
 		const previousBuffer = context.buffer;
 		context = result.next;
-		if (context.buffer.length > 0 && context.buffer.length === previousBuffer.length && context.buffer.every((item, i) => item === previousBuffer[i])) return {
+		if (isBufferUnchanged(previousBuffer, context.buffer)) return {
 			success: false,
 			error: require_message.message`Unexpected option or argument: ${context.buffer[0]}.`
 		};
@@ -196,7 +203,7 @@ function suggestSync(parser, args, options) {
 		if (!result.success) return Array.from(parser.suggest(context, prefix));
 		const previousBuffer = context.buffer;
 		context = result.next;
-		if (context.buffer.length > 0 && context.buffer.length === previousBuffer.length && context.buffer.every((item, i) => item === previousBuffer[i])) return [];
+		if (isBufferUnchanged(previousBuffer, context.buffer)) return [];
 	}
 	return Array.from(parser.suggest(context, prefix));
 }
@@ -239,7 +246,7 @@ async function suggestAsync(parser, args, options) {
 		}
 		const previousBuffer = context.buffer;
 		context = result.next;
-		if (context.buffer.length > 0 && context.buffer.length === previousBuffer.length && context.buffer.every((item, i) => item === previousBuffer[i])) return [];
+		if (isBufferUnchanged(previousBuffer, context.buffer)) return [];
 	}
 	const suggestions = [];
 	for await (const suggestion of parser.suggest(context, prefix)) suggestions.push(suggestion);
@@ -359,7 +366,9 @@ function getDocPageSyncImpl(parser, args, options) {
 	while (context.buffer.length > 0) {
 		const result = parser.parse(context);
 		if (!result.success) break;
+		const previousBuffer = context.buffer;
 		context = result.next;
+		if (isBufferUnchanged(previousBuffer, context.buffer)) break;
 	}
 	return buildDocPage(parser, context, args);
 }
@@ -377,7 +386,9 @@ async function getDocPageAsyncImpl(parser, args, options) {
 	while (context.buffer.length > 0) {
 		const result = await parser.parse(context);
 		if (!result.success) break;
+		const previousBuffer = context.buffer;
 		context = result.next;
+		if (isBufferUnchanged(previousBuffer, context.buffer)) break;
 	}
 	return buildDocPage(parser, context, args);
 }

package/dist/parser.js

@@ -52,7 +52,7 @@ function parseSync(parser, args, options) {
 		};
 		const previousBuffer = context.buffer;
 		context = result.next;
-		if (context.buffer.length > 0 && context.buffer.length === previousBuffer.length && context.buffer.every((item, i) => item === previousBuffer[i])) return {
+		if (isBufferUnchanged(previousBuffer, context.buffer)) return {
 			success: false,
 			error: message`Unexpected option or argument: ${context.buffer[0]}.`
 		};
@@ -69,6 +69,13 @@ function parseSync(parser, args, options) {
 	};
 }
 /**
+* Returns `true` when the buffer has not changed between iterations,
+* indicating a parser is stalling without consuming input.
+*/
+function isBufferUnchanged(previous, current) {
+	return current.length > 0 && current.length === previous.length && current.every((item, i) => item === previous[i]);
+}
+/**
 * Parses an array of command-line arguments using the provided combined parser.
 * This function processes the input arguments, applying the parser to each
 * argument until all arguments are consumed or an error occurs.
@@ -104,7 +111,7 @@ async function parseAsync(parser, args, options) {
 		};
 		const previousBuffer = context.buffer;
 		context = result.next;
-		if (context.buffer.length > 0 && context.buffer.length === previousBuffer.length && context.buffer.every((item, i) => item === previousBuffer[i])) return {
+		if (isBufferUnchanged(previousBuffer, context.buffer)) return {
 			success: false,
 			error: message`Unexpected option or argument: ${context.buffer[0]}.`
 		};
@@ -196,7 +203,7 @@ function suggestSync(parser, args, options) {
 		if (!result.success) return Array.from(parser.suggest(context, prefix));
 		const previousBuffer = context.buffer;
 		context = result.next;
-		if (context.buffer.length > 0 && context.buffer.length === previousBuffer.length && context.buffer.every((item, i) => item === previousBuffer[i])) return [];
+		if (isBufferUnchanged(previousBuffer, context.buffer)) return [];
 	}
 	return Array.from(parser.suggest(context, prefix));
 }
@@ -239,7 +246,7 @@ async function suggestAsync(parser, args, options) {
 		}
 		const previousBuffer = context.buffer;
 		context = result.next;
-		if (context.buffer.length > 0 && context.buffer.length === previousBuffer.length && context.buffer.every((item, i) => item === previousBuffer[i])) return [];
+		if (isBufferUnchanged(previousBuffer, context.buffer)) return [];
 	}
 	const suggestions = [];
 	for await (const suggestion of parser.suggest(context, prefix)) suggestions.push(suggestion);
@@ -359,7 +366,9 @@ function getDocPageSyncImpl(parser, args, options) {
 	while (context.buffer.length > 0) {
 		const result = parser.parse(context);
 		if (!result.success) break;
+		const previousBuffer = context.buffer;
 		context = result.next;
+		if (isBufferUnchanged(previousBuffer, context.buffer)) break;
 	}
 	return buildDocPage(parser, context, args);
 }
@@ -377,7 +386,9 @@ async function getDocPageAsyncImpl(parser, args, options) {
 	while (context.buffer.length > 0) {
 		const result = await parser.parse(context);
 		if (!result.success) break;
+		const previousBuffer = context.buffer;
 		context = result.next;
+		if (isBufferUnchanged(previousBuffer, context.buffer)) break;
 	}
 	return buildDocPage(parser, context, args);
 }

package/dist/usage.cjs

@@ -121,10 +121,8 @@ function extractCommandNames(usage, includeHidden) {
 * 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
+* analysis.
+* See 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
@@ -172,10 +170,9 @@ function extractLeadingOptionNames(usage, includeHidden) {
 * `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
+* Known limitation: this function has the same usage-tree ordering caveat
+* as {@link extractLeadingOptionNames}.
+* See 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
@@ -212,27 +209,86 @@ function extractLeadingCommandNames(usage, includeHidden) {
 	return names;
 }
 /**
+* Extracts literal values that could match as the first positional token.
+*
+* Unlike {@link extractLiteralValues}, 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.  It still recurses into `optional`,
+* `multiple`, and `exclusive` containers.
+*
+* Literals tagged with `optionValue: true` (produced by
+* `appendLiteralToUsage()` when rewriting option metavars for
+* `conditional()` discriminators) are skipped, because they represent
+* option values rather than standalone positional tokens.
+*
+* Known limitation: this function has the same usage-tree ordering caveat
+* as {@link extractLeadingOptionNames}.
+* See https://github.com/dahlia/optique/issues/735
+*
+* @param usage The usage description to extract leading literal values from.
+* @returns A set of literal values that could match at the first token
+*   position.
+* @since 1.0.0
+*/
+function extractLeadingLiteralValues(usage) {
+	const values = /* @__PURE__ */ new Set();
+	function collectLeading(terms) {
+		if (!terms || !Array.isArray(terms)) return;
+		for (const term of terms) switch (term.type) {
+			case "literal":
+				if (term.optionValue) break;
+				values.add(term.value);
+				return;
+			case "command":
+			case "argument": return;
+			case "optional":
+				collectLeading(term.terms);
+				break;
+			case "multiple":
+				collectLeading(term.terms);
+				if (term.min > 0 && branchConsumesToken(term.terms, true)) return;
+				break;
+			case "exclusive":
+				for (const branch of term.terms) collectLeading(branch);
+				if (exclusiveConsumesToken(term.terms, true)) return;
+				break;
+			default: break;
+		}
+	}
+	collectLeading(usage);
+	return values;
+}
+/**
 * 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".
+*
+* @param skipOptionValueLiterals When `true`, literals tagged with
+*   `optionValue` are treated as non-positional.  Only
+*   `extractLeadingLiteralValues()` passes `true`; the option/command
+*   extractors use the default (`false`) so that option+value pairs
+*   still act as positional gates.
 */
-function exclusiveConsumesToken(branches) {
+function exclusiveConsumesToken(branches, skipOptionValueLiterals = false) {
 	if (branches.length === 0) return false;
-	return branches.every((branch) => branchConsumesToken(branch));
+	return branches.every((branch) => branchConsumesToken(branch, skipOptionValueLiterals));
 }
-function branchConsumesToken(terms) {
+function branchConsumesToken(terms, skipOptionValueLiterals = false) {
 	if (!terms || !Array.isArray(terms)) return false;
 	for (const term of terms) switch (term.type) {
 		case "command":
-		case "argument":
-		case "literal": return true;
+		case "argument": return true;
+		case "literal":
+			if (skipOptionValueLiterals && term.optionValue) break;
+			return true;
 		case "option": break;
 		case "optional": break;
 		case "multiple":
-			if (term.min > 0 && branchConsumesToken(term.terms)) return true;
+			if (term.min > 0 && branchConsumesToken(term.terms, skipOptionValueLiterals)) return true;
 			break;
 		case "exclusive":
-			if (exclusiveConsumesToken(term.terms)) return true;
+			if (exclusiveConsumesToken(term.terms, skipOptionValueLiterals)) return true;
 			break;
 		default: break;
 	}
@@ -714,6 +770,7 @@ exports.cloneUsageTerm = cloneUsageTerm;
 exports.extractArgumentMetavars = extractArgumentMetavars;
 exports.extractCommandNames = extractCommandNames;
 exports.extractLeadingCommandNames = extractLeadingCommandNames;
+exports.extractLeadingLiteralValues = extractLeadingLiteralValues;
 exports.extractLeadingOptionNames = extractLeadingOptionNames;
 exports.extractLiteralValues = extractLiteralValues;
 exports.extractOptionNames = extractOptionNames;

package/dist/usage.d.cts

@@ -178,6 +178,18 @@ type UsageTerm =
    * The literal value that must be provided exactly as written.
    */
   readonly value: string;
+  /**
+   * When `true`, this literal was derived from an option's metavar by
+   * `appendLiteralToUsage()` in `conditional()` and represents an option
+   * value, not a standalone positional token.
+   * {@link extractLeadingLiteralValues} and the `skipOptionValueLiterals`
+   * mode of `branchConsumesToken()` use this to distinguish option values
+   * from real positional literals.  {@link extractLeadingOptionNames} and
+   * {@link extractLeadingCommandNames} intentionally still treat these
+   * literals as positional gates.
+   * @since 1.0.0
+   */
+  readonly optionValue?: boolean;
 }
 /**
  * A pass-through term, which represents unrecognized options that are
@@ -276,10 +288,8 @@ declare function extractCommandNames(usage: Usage, includeHidden?: boolean): Set
  * 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
+ * analysis.
+ * See 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
@@ -299,10 +309,9 @@ declare function extractLeadingOptionNames(usage: Usage, includeHidden?: boolean
  * `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
+ * Known limitation: this function has the same usage-tree ordering caveat
+ * as {@link extractLeadingOptionNames}.
+ * See 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
@@ -311,6 +320,30 @@ declare function extractLeadingOptionNames(usage: Usage, includeHidden?: boolean
  * @since 1.0.0
  */
 declare function extractLeadingCommandNames(usage: Usage, includeHidden?: boolean): Set<string>;
+/**
+ * Extracts literal values that could match as the first positional token.
+ *
+ * Unlike {@link extractLiteralValues}, 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.  It still recurses into `optional`,
+ * `multiple`, and `exclusive` containers.
+ *
+ * Literals tagged with `optionValue: true` (produced by
+ * `appendLiteralToUsage()` when rewriting option metavars for
+ * `conditional()` discriminators) are skipped, because they represent
+ * option values rather than standalone positional tokens.
+ *
+ * Known limitation: this function has the same usage-tree ordering caveat
+ * as {@link extractLeadingOptionNames}.
+ * See https://github.com/dahlia/optique/issues/735
+ *
+ * @param usage The usage description to extract leading literal values from.
+ * @returns A set of literal values that could match at the first token
+ *   position.
+ * @since 1.0.0
+ */
+declare function extractLeadingLiteralValues(usage: Usage): Set<string>;
 /**
  * Extracts all literal values from a usage description.
  *
@@ -487,4 +520,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, extractLeadingCommandNames, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };
+export { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingLiteralValues, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };

package/dist/usage.d.ts

@@ -178,6 +178,18 @@ type UsageTerm =
    * The literal value that must be provided exactly as written.
    */
   readonly value: string;
+  /**
+   * When `true`, this literal was derived from an option's metavar by
+   * `appendLiteralToUsage()` in `conditional()` and represents an option
+   * value, not a standalone positional token.
+   * {@link extractLeadingLiteralValues} and the `skipOptionValueLiterals`
+   * mode of `branchConsumesToken()` use this to distinguish option values
+   * from real positional literals.  {@link extractLeadingOptionNames} and
+   * {@link extractLeadingCommandNames} intentionally still treat these
+   * literals as positional gates.
+   * @since 1.0.0
+   */
+  readonly optionValue?: boolean;
 }
 /**
  * A pass-through term, which represents unrecognized options that are
@@ -276,10 +288,8 @@ declare function extractCommandNames(usage: Usage, includeHidden?: boolean): Set
  * 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
+ * analysis.
+ * See 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
@@ -299,10 +309,9 @@ declare function extractLeadingOptionNames(usage: Usage, includeHidden?: boolean
  * `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
+ * Known limitation: this function has the same usage-tree ordering caveat
+ * as {@link extractLeadingOptionNames}.
+ * See 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
@@ -311,6 +320,30 @@ declare function extractLeadingOptionNames(usage: Usage, includeHidden?: boolean
  * @since 1.0.0
  */
 declare function extractLeadingCommandNames(usage: Usage, includeHidden?: boolean): Set<string>;
+/**
+ * Extracts literal values that could match as the first positional token.
+ *
+ * Unlike {@link extractLiteralValues}, 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.  It still recurses into `optional`,
+ * `multiple`, and `exclusive` containers.
+ *
+ * Literals tagged with `optionValue: true` (produced by
+ * `appendLiteralToUsage()` when rewriting option metavars for
+ * `conditional()` discriminators) are skipped, because they represent
+ * option values rather than standalone positional tokens.
+ *
+ * Known limitation: this function has the same usage-tree ordering caveat
+ * as {@link extractLeadingOptionNames}.
+ * See https://github.com/dahlia/optique/issues/735
+ *
+ * @param usage The usage description to extract leading literal values from.
+ * @returns A set of literal values that could match at the first token
+ *   position.
+ * @since 1.0.0
+ */
+declare function extractLeadingLiteralValues(usage: Usage): Set<string>;
 /**
  * Extracts all literal values from a usage description.
  *
@@ -487,4 +520,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, extractLeadingCommandNames, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };
+export { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingLiteralValues, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };

package/dist/usage.js

@@ -121,10 +121,8 @@ function extractCommandNames(usage, includeHidden) {
 * 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
+* analysis.
+* See 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
@@ -172,10 +170,9 @@ function extractLeadingOptionNames(usage, includeHidden) {
 * `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
+* Known limitation: this function has the same usage-tree ordering caveat
+* as {@link extractLeadingOptionNames}.
+* See 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
@@ -212,27 +209,86 @@ function extractLeadingCommandNames(usage, includeHidden) {
 	return names;
 }
 /**
+* Extracts literal values that could match as the first positional token.
+*
+* Unlike {@link extractLiteralValues}, 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.  It still recurses into `optional`,
+* `multiple`, and `exclusive` containers.
+*
+* Literals tagged with `optionValue: true` (produced by
+* `appendLiteralToUsage()` when rewriting option metavars for
+* `conditional()` discriminators) are skipped, because they represent
+* option values rather than standalone positional tokens.
+*
+* Known limitation: this function has the same usage-tree ordering caveat
+* as {@link extractLeadingOptionNames}.
+* See https://github.com/dahlia/optique/issues/735
+*
+* @param usage The usage description to extract leading literal values from.
+* @returns A set of literal values that could match at the first token
+*   position.
+* @since 1.0.0
+*/
+function extractLeadingLiteralValues(usage) {
+	const values = /* @__PURE__ */ new Set();
+	function collectLeading(terms) {
+		if (!terms || !Array.isArray(terms)) return;
+		for (const term of terms) switch (term.type) {
+			case "literal":
+				if (term.optionValue) break;
+				values.add(term.value);
+				return;
+			case "command":
+			case "argument": return;
+			case "optional":
+				collectLeading(term.terms);
+				break;
+			case "multiple":
+				collectLeading(term.terms);
+				if (term.min > 0 && branchConsumesToken(term.terms, true)) return;
+				break;
+			case "exclusive":
+				for (const branch of term.terms) collectLeading(branch);
+				if (exclusiveConsumesToken(term.terms, true)) return;
+				break;
+			default: break;
+		}
+	}
+	collectLeading(usage);
+	return values;
+}
+/**
 * 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".
+*
+* @param skipOptionValueLiterals When `true`, literals tagged with
+*   `optionValue` are treated as non-positional.  Only
+*   `extractLeadingLiteralValues()` passes `true`; the option/command
+*   extractors use the default (`false`) so that option+value pairs
+*   still act as positional gates.
 */
-function exclusiveConsumesToken(branches) {
+function exclusiveConsumesToken(branches, skipOptionValueLiterals = false) {
 	if (branches.length === 0) return false;
-	return branches.every((branch) => branchConsumesToken(branch));
+	return branches.every((branch) => branchConsumesToken(branch, skipOptionValueLiterals));
 }
-function branchConsumesToken(terms) {
+function branchConsumesToken(terms, skipOptionValueLiterals = false) {
 	if (!terms || !Array.isArray(terms)) return false;
 	for (const term of terms) switch (term.type) {
 		case "command":
-		case "argument":
-		case "literal": return true;
+		case "argument": return true;
+		case "literal":
+			if (skipOptionValueLiterals && term.optionValue) break;
+			return true;
 		case "option": break;
 		case "optional": break;
 		case "multiple":
-			if (term.min > 0 && branchConsumesToken(term.terms)) return true;
+			if (term.min > 0 && branchConsumesToken(term.terms, skipOptionValueLiterals)) return true;
 			break;
 		case "exclusive":
-			if (exclusiveConsumesToken(term.terms)) return true;
+			if (exclusiveConsumesToken(term.terms, skipOptionValueLiterals)) return true;
 			break;
 		default: break;
 	}
@@ -709,4 +765,4 @@ function* formatUsageTermInternal(term, options) {
 }
 
 //#endregion
-export { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };
+export { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingLiteralValues, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };

package/dist/validate.cjs

@@ -118,12 +118,13 @@ function validateMetaNameCollisions(userNames, metaEntries) {
 		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}.`);
+			const literalNames = kind === "command" ? userNames.leadingLiterals : userNames.allLiterals;
+			if (literalNames.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}").`);
+				for (const literal of literalNames) if (literal.startsWith(prefix)) throw new TypeError(`Literal value "${literal}" conflicts with the built-in ${label} (prefix "${prefix}").`);
 			}
 		}
 	}

package/dist/validate.js

@@ -117,12 +117,13 @@ function validateMetaNameCollisions(userNames, metaEntries) {
 		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}.`);
+			const literalNames = kind === "command" ? userNames.leadingLiterals : userNames.allLiterals;
+			if (literalNames.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}").`);
+				for (const literal of literalNames) if (literal.startsWith(prefix)) throw new TypeError(`Literal value "${literal}" conflicts with the built-in ${label} (prefix "${prefix}").`);
 			}
 		}
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1531+6382e76e",
+  "version": "1.0.0-dev.1536+1f9feab6",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",