@optique/core 1.0.0-dev.1533 → 1.0.0-dev.1547

package/dist/constructs.cjs

@@ -9,6 +9,43 @@ const require_suggestion = require('./suggestion.cjs');
 const require_usage_internals = require('./usage-internals.cjs');
 
 //#region src/constructs.ts
+/**
+* A shared empty set used as the `leadingNames` value for parsers that
+* do not match any specific name at the first buffer position.
+*/
+const EMPTY_LEADING_NAMES = /* @__PURE__ */ new Set();
+/**
+* Computes the union of `leadingNames` from all given parsers.
+* Used for alternative combinators (`or()`, `longestMatch()`) where all
+* branches compete independently.
+*/
+function unionLeadingNames(parsers) {
+	const names = /* @__PURE__ */ new Set();
+	for (const p of parsers) for (const name of p.leadingNames) names.add(name);
+	return names.size === 0 ? EMPTY_LEADING_NAMES : names;
+}
+/**
+* Computes `leadingNames` for shared-buffer compositions (`tuple()`,
+* `object()`, `merge()`, `concat()`).
+*
+* Children are processed in descending priority order (matching the
+* round-robin parse loop).  Once a child with `acceptingAnyToken` is
+* encountered, no lower-priority children can match at position 0, so
+* their names are excluded.
+*/
+function sharedBufferLeadingNames(parsers) {
+	const sorted = parsers.toSorted((a, b) => b.priority - a.priority);
+	const names = /* @__PURE__ */ new Set();
+	let positionalBlocked = false;
+	for (const p of sorted) {
+		if (p.leadingNames) for (const name of p.leadingNames) {
+			if (positionalBlocked && !name.startsWith("-")) continue;
+			names.add(name);
+		}
+		if (p.acceptingAnyToken) positionalBlocked = true;
+	}
+	return names.size === 0 ? EMPTY_LEADING_NAMES : names;
+}
 const inheritParentAnnotationsKey = Symbol.for("@optique/core/inheritParentAnnotations");
 /**
 * Internal symbol for exposing field-level parser pairs from `object()`
@@ -463,6 +500,8 @@ function or(...args) {
 			type: "exclusive",
 			terms: parsers.map((p) => p.usage)
 		}],
+		leadingNames: unionLeadingNames(parsers),
+		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState: void 0,
 		complete: createExclusiveComplete(parsers, options, noMatchContext, combinedMode),
 		parse(context) {
@@ -600,6 +639,8 @@ function longestMatch(...args) {
 			type: "exclusive",
 			terms: parsers.map((p) => p.usage)
 		}],
+		leadingNames: unionLeadingNames(parsers),
+		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState: void 0,
 		complete: createExclusiveComplete(parsers, options, noMatchContext, combinedMode),
 		parse(context) {
@@ -1185,6 +1226,8 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		[fieldParsersKey]: parserPairs,
 		priority: Math.max(...parserKeys.map((k) => parsers[k].priority)),
 		usage: applyHiddenToUsage(parserPairs.flatMap(([_, p]) => p.usage), options.hidden),
+		leadingNames: sharedBufferLeadingNames(parserPairs.map(([_, p]) => p)),
+		acceptingAnyToken: parserPairs.some(([_, p]) => p.acceptingAnyToken),
 		get initialState() {
 			return createInitialState();
 		},
@@ -1556,6 +1599,8 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		$valueType: [],
 		$stateType: [],
 		usage: parsers.toSorted((a, b) => b.priority - a.priority).flatMap((p) => p.usage),
+		leadingNames: sharedBufferLeadingNames(parsers),
+		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		priority: parsers.length > 0 ? Math.max(...parsers.map((p) => p.priority)) : 0,
 		initialState: parsers.map((parser) => parser.initialState),
 		parse(context) {
@@ -1877,6 +1922,8 @@ function merge(...args) {
 		[fieldParsersKey]: mergedFieldParsers,
 		priority: Math.max(...parsers.map((p) => p.priority)),
 		usage: applyHiddenToUsage(parsers.flatMap((p) => p.usage), options.hidden),
+		leadingNames: sharedBufferLeadingNames(parsers),
+		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState,
 		parse(context) {
 			if (isAsync) return parseAsync(context);
@@ -2415,6 +2462,8 @@ function concat(...parsers) {
 		$stateType: [],
 		priority: parsers.length > 0 ? Math.max(...parsers.map((p) => p.priority)) : 0,
 		usage: parsers.flatMap((p) => p.usage),
+		leadingNames: sharedBufferLeadingNames(parsers),
+		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState,
 		parse(context) {
 			if (isAsync) return parseAsync(context);
@@ -2492,6 +2541,8 @@ function group(label, parser, options = {}) {
 		$stateType: parser.$stateType,
 		priority: parser.priority,
 		usage: applyHiddenToUsage(parser.usage, options.hidden),
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: parser.acceptingAnyToken,
 		initialState: parser.initialState,
 		...fieldParsersKey in parser ? { [fieldParsersKey]: parser[fieldParsersKey] } : {},
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: parser.shouldDeferCompletion.bind(parser) } : {},
@@ -2976,6 +3027,8 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		$stateType: [],
 		priority: maxPriority,
 		usage,
+		leadingNames: defaultBranch ? unionLeadingNames([discriminator, defaultBranch]) : discriminator.leadingNames,
+		acceptingAnyToken: defaultBranch?.acceptingAnyToken ?? false,
 		initialState,
 		parse(context) {
 			if (isAsync) return parseAsync(context);

package/dist/constructs.js

@@ -9,6 +9,43 @@ import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggest
 import { collectLeadingCandidates } from "./usage-internals.js";
 
 //#region src/constructs.ts
+/**
+* A shared empty set used as the `leadingNames` value for parsers that
+* do not match any specific name at the first buffer position.
+*/
+const EMPTY_LEADING_NAMES = /* @__PURE__ */ new Set();
+/**
+* Computes the union of `leadingNames` from all given parsers.
+* Used for alternative combinators (`or()`, `longestMatch()`) where all
+* branches compete independently.
+*/
+function unionLeadingNames(parsers) {
+	const names = /* @__PURE__ */ new Set();
+	for (const p of parsers) for (const name of p.leadingNames) names.add(name);
+	return names.size === 0 ? EMPTY_LEADING_NAMES : names;
+}
+/**
+* Computes `leadingNames` for shared-buffer compositions (`tuple()`,
+* `object()`, `merge()`, `concat()`).
+*
+* Children are processed in descending priority order (matching the
+* round-robin parse loop).  Once a child with `acceptingAnyToken` is
+* encountered, no lower-priority children can match at position 0, so
+* their names are excluded.
+*/
+function sharedBufferLeadingNames(parsers) {
+	const sorted = parsers.toSorted((a, b) => b.priority - a.priority);
+	const names = /* @__PURE__ */ new Set();
+	let positionalBlocked = false;
+	for (const p of sorted) {
+		if (p.leadingNames) for (const name of p.leadingNames) {
+			if (positionalBlocked && !name.startsWith("-")) continue;
+			names.add(name);
+		}
+		if (p.acceptingAnyToken) positionalBlocked = true;
+	}
+	return names.size === 0 ? EMPTY_LEADING_NAMES : names;
+}
 const inheritParentAnnotationsKey = Symbol.for("@optique/core/inheritParentAnnotations");
 /**
 * Internal symbol for exposing field-level parser pairs from `object()`
@@ -463,6 +500,8 @@ function or(...args) {
 			type: "exclusive",
 			terms: parsers.map((p) => p.usage)
 		}],
+		leadingNames: unionLeadingNames(parsers),
+		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState: void 0,
 		complete: createExclusiveComplete(parsers, options, noMatchContext, combinedMode),
 		parse(context) {
@@ -600,6 +639,8 @@ function longestMatch(...args) {
 			type: "exclusive",
 			terms: parsers.map((p) => p.usage)
 		}],
+		leadingNames: unionLeadingNames(parsers),
+		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState: void 0,
 		complete: createExclusiveComplete(parsers, options, noMatchContext, combinedMode),
 		parse(context) {
@@ -1185,6 +1226,8 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		[fieldParsersKey]: parserPairs,
 		priority: Math.max(...parserKeys.map((k) => parsers[k].priority)),
 		usage: applyHiddenToUsage(parserPairs.flatMap(([_, p]) => p.usage), options.hidden),
+		leadingNames: sharedBufferLeadingNames(parserPairs.map(([_, p]) => p)),
+		acceptingAnyToken: parserPairs.some(([_, p]) => p.acceptingAnyToken),
 		get initialState() {
 			return createInitialState();
 		},
@@ -1556,6 +1599,8 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		$valueType: [],
 		$stateType: [],
 		usage: parsers.toSorted((a, b) => b.priority - a.priority).flatMap((p) => p.usage),
+		leadingNames: sharedBufferLeadingNames(parsers),
+		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		priority: parsers.length > 0 ? Math.max(...parsers.map((p) => p.priority)) : 0,
 		initialState: parsers.map((parser) => parser.initialState),
 		parse(context) {
@@ -1877,6 +1922,8 @@ function merge(...args) {
 		[fieldParsersKey]: mergedFieldParsers,
 		priority: Math.max(...parsers.map((p) => p.priority)),
 		usage: applyHiddenToUsage(parsers.flatMap((p) => p.usage), options.hidden),
+		leadingNames: sharedBufferLeadingNames(parsers),
+		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState,
 		parse(context) {
 			if (isAsync) return parseAsync(context);
@@ -2415,6 +2462,8 @@ function concat(...parsers) {
 		$stateType: [],
 		priority: parsers.length > 0 ? Math.max(...parsers.map((p) => p.priority)) : 0,
 		usage: parsers.flatMap((p) => p.usage),
+		leadingNames: sharedBufferLeadingNames(parsers),
+		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState,
 		parse(context) {
 			if (isAsync) return parseAsync(context);
@@ -2492,6 +2541,8 @@ function group(label, parser, options = {}) {
 		$stateType: parser.$stateType,
 		priority: parser.priority,
 		usage: applyHiddenToUsage(parser.usage, options.hidden),
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: parser.acceptingAnyToken,
 		initialState: parser.initialState,
 		...fieldParsersKey in parser ? { [fieldParsersKey]: parser[fieldParsersKey] } : {},
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: parser.shouldDeferCompletion.bind(parser) } : {},
@@ -2976,6 +3027,8 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		$stateType: [],
 		priority: maxPriority,
 		usage,
+		leadingNames: defaultBranch ? unionLeadingNames([discriminator, defaultBranch]) : discriminator.leadingNames,
+		acceptingAnyToken: defaultBranch?.acceptingAnyToken ?? false,
 		initialState,
 		parse(context) {
 			if (isAsync) return parseAsync(context);

package/dist/facade.cjs

@@ -196,6 +196,8 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 			$stateType: [],
 			priority: 200,
 			usage: helpParsers.helpOption.usage,
+			leadingNames: helpParsers.helpOption.leadingNames,
+			acceptingAnyToken: false,
 			initialState: null,
 			parse(context) {
 				const { buffer, optionsTerminated } = context;
@@ -275,6 +277,8 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 			$stateType: [],
 			priority: 200,
 			usage: versionParsers.versionOption.usage,
+			leadingNames: versionParsers.versionOption.leadingNames,
+			acceptingAnyToken: false,
 			initialState: null,
 			parse(context) {
 				const { buffer, optionsTerminated } = context;
@@ -620,9 +624,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		completionCommandNames
 	]);
 	require_validate.validateMetaNameCollisions({
-		leadingOptions: require_usage.extractLeadingOptionNames(parser.usage, true),
-		leadingCommands: require_usage.extractLeadingCommandNames(parser.usage, true),
-		leadingLiterals: require_usage.extractLeadingLiteralValues(parser.usage),
+		leadingNames: parser.leadingNames,
 		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, extractLeadingLiteralValues, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage } from "./usage.js";
+import { extractCommandNames, 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";
@@ -196,6 +196,8 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 			$stateType: [],
 			priority: 200,
 			usage: helpParsers.helpOption.usage,
+			leadingNames: helpParsers.helpOption.leadingNames,
+			acceptingAnyToken: false,
 			initialState: null,
 			parse(context) {
 				const { buffer, optionsTerminated } = context;
@@ -275,6 +277,8 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 			$stateType: [],
 			priority: 200,
 			usage: versionParsers.versionOption.usage,
+			leadingNames: versionParsers.versionOption.leadingNames,
+			acceptingAnyToken: false,
 			initialState: null,
 			parse(context) {
 				const { buffer, optionsTerminated } = context;
@@ -620,9 +624,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		completionCommandNames
 	]);
 	validateMetaNameCollisions({
-		leadingOptions: extractLeadingOptionNames(parser.usage, true),
-		leadingCommands: extractLeadingCommandNames(parser.usage, true),
-		leadingLiterals: extractLeadingLiteralValues(parser.usage),
+		leadingNames: parser.leadingNames,
 		allOptions: extractOptionNames(parser.usage, true),
 		allCommands: extractCommandNames(parser.usage, true),
 		allLiterals: extractLiteralValues(parser.usage)

package/dist/index.cjs

@@ -53,9 +53,6 @@ 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.extractLeadingLiteralValues = require_usage.extractLeadingLiteralValues;
-exports.extractLeadingOptionNames = require_usage.extractLeadingOptionNames;
 exports.extractLiteralValues = require_usage.extractLiteralValues;
 exports.extractOptionNames = require_usage.extractOptionNames;
 exports.fail = require_primitives.fail;

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

@@ -128,6 +128,8 @@ function optional(parser) {
 			type: "optional",
 			terms: parser.usage
 		}],
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: false,
 		initialState: void 0,
 		...wrappedDependencyMarker,
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser)) } : {},
@@ -246,6 +248,8 @@ function withDefault(parser, defaultValue, options) {
 			type: "optional",
 			terms: parser.usage
 		}],
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: false,
 		initialState: void 0,
 		...wrappedDependencyMarker,
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser)) } : {},
@@ -650,6 +654,8 @@ function multiple(parser, options = {}) {
 			terms: parser.usage,
 			min
 		}],
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: min > 0 && (parser.acceptingAnyToken ?? false),
 		initialState: [],
 		parse(context) {
 			return require_mode_dispatch.dispatchByMode(parser.$mode, () => parseSync(context), () => parseAsync(context));
@@ -886,6 +892,8 @@ function nonEmpty(parser) {
 		$stateType: parser.$stateType,
 		priority: parser.priority,
 		usage: parser.usage,
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: parser.acceptingAnyToken,
 		initialState: parser.initialState,
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: parser.shouldDeferCompletion.bind(parser) } : {},
 		parse(context) {

package/dist/modifiers.js

@@ -128,6 +128,8 @@ function optional(parser) {
 			type: "optional",
 			terms: parser.usage
 		}],
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: false,
 		initialState: void 0,
 		...wrappedDependencyMarker,
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser)) } : {},
@@ -246,6 +248,8 @@ function withDefault(parser, defaultValue, options) {
 			type: "optional",
 			terms: parser.usage
 		}],
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: false,
 		initialState: void 0,
 		...wrappedDependencyMarker,
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser)) } : {},
@@ -650,6 +654,8 @@ function multiple(parser, options = {}) {
 			terms: parser.usage,
 			min
 		}],
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: min > 0 && (parser.acceptingAnyToken ?? false),
 		initialState: [],
 		parse(context) {
 			return dispatchByMode(parser.$mode, () => parseSync(context), () => parseAsync(context));
@@ -886,6 +892,8 @@ function nonEmpty(parser) {
 		$stateType: parser.$stateType,
 		priority: parser.priority,
 		usage: parser.usage,
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: parser.acceptingAnyToken,
 		initialState: parser.initialState,
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: parser.shouldDeferCompletion.bind(parser) } : {},
 		parse(context) {

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.d.cts

@@ -105,6 +105,44 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * to use it in command-line interfaces.
    */
   readonly usage: Usage;
+  /**
+   * Names that this parser could match at the first buffer position.
+   * Used by `runParser()` to detect collisions with built-in meta
+   * features (help, version, completion).
+   *
+   * Each built-in combinator computes this from its structural semantics.
+   * Custom parser implementations must include every fixed token that
+   * the parser accepts at `argv[0]` — command names, option names, and
+   * literal values alike.  For example, a parser whose usage declares
+   * `{ type: "literal", value: "serve" }` should include `"serve"` in
+   * this set.  Parsers that accept *any* token (like `argument()`) should
+   * return an empty set and set {@link acceptingAnyToken} to `true`
+   * instead.
+   *
+   * @since 1.0.0
+   */
+  readonly leadingNames: ReadonlySet<string>;
+  /**
+   * Whether this parser unconditionally consumes any positional token at
+   * the first buffer position.  A parser with this flag accepts any
+   * non-option token but may still reject option-like tokens (those
+   * starting with `"-"`).
+   *
+   * In shared-buffer compositions (`tuple()`, `object()`, `merge()`,
+   * `concat()`), a catch-all parser blocks positional names (command
+   * names) from lower-priority siblings but does not block option-like
+   * names.  In `conditional()`, option-like names from the default
+   * branch remain reachable even when the discriminator is a catch-all.
+   *
+   * Only `argument()` is inherently accepting-any-token; combinators
+   * like `or()` and `map()` propagate this from their children.
+   * Wrappers that can succeed without consuming (`optional()`,
+   * `withDefault()`, `multiple()` with `min = 0`) always set this
+   * to `false`.
+   *
+   * @since 1.0.0
+   */
+  readonly acceptingAnyToken: boolean;
   /**
    * The initial state for this parser.  This is used to initialize the
    * state when parsing starts.

package/dist/parser.d.ts

@@ -105,6 +105,44 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * to use it in command-line interfaces.
    */
   readonly usage: Usage;
+  /**
+   * Names that this parser could match at the first buffer position.
+   * Used by `runParser()` to detect collisions with built-in meta
+   * features (help, version, completion).
+   *
+   * Each built-in combinator computes this from its structural semantics.
+   * Custom parser implementations must include every fixed token that
+   * the parser accepts at `argv[0]` — command names, option names, and
+   * literal values alike.  For example, a parser whose usage declares
+   * `{ type: "literal", value: "serve" }` should include `"serve"` in
+   * this set.  Parsers that accept *any* token (like `argument()`) should
+   * return an empty set and set {@link acceptingAnyToken} to `true`
+   * instead.
+   *
+   * @since 1.0.0
+   */
+  readonly leadingNames: ReadonlySet<string>;
+  /**
+   * Whether this parser unconditionally consumes any positional token at
+   * the first buffer position.  A parser with this flag accepts any
+   * non-option token but may still reject option-like tokens (those
+   * starting with `"-"`).
+   *
+   * In shared-buffer compositions (`tuple()`, `object()`, `merge()`,
+   * `concat()`), a catch-all parser blocks positional names (command
+   * names) from lower-priority siblings but does not block option-like
+   * names.  In `conditional()`, option-like names from the default
+   * branch remain reachable even when the discriminator is a catch-all.
+   *
+   * Only `argument()` is inherently accepting-any-token; combinators
+   * like `or()` and `map()` propagate this from their children.
+   * Wrappers that can succeed without consuming (`optional()`,
+   * `withDefault()`, `multiple()` with `min = 0`) always set this
+   * to `false`.
+   *
+   * @since 1.0.0
+   */
+  readonly acceptingAnyToken: boolean;
   /**
    * The initial state for this parser.  This is used to initialize the
    * state when parsing starts.