@optique/core 1.0.0-dev.1536 → 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.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.

package/dist/primitives.cjs

@@ -9,6 +9,11 @@ const require_usage_internals = require('./usage-internals.cjs');
 const require_valueparser = require('./valueparser.cjs');
 
 //#region src/primitives.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();
 function hasParsedOptionValue(state, valueParser) {
 	if (valueParser != null) return require_dependency.isDeferredParseState(state) || require_dependency.isDependencySourceState(state) || state != null && "success" in state && state.success;
 	return state != null && "success" in state && state.success && state.value === true;
@@ -38,6 +43,8 @@ function constant(value) {
 		$mode: "sync",
 		priority: 0,
 		usage: [],
+		leadingNames: EMPTY_LEADING_NAMES,
+		acceptingAnyToken: false,
 		initialState: value,
 		parse(context) {
 			return {
@@ -93,6 +100,8 @@ function fail() {
 		$mode: "sync",
 		priority: 0,
 		usage: [],
+		leadingNames: EMPTY_LEADING_NAMES,
+		acceptingAnyToken: false,
 		initialState: void 0,
 		parse(_context) {
 			return {
@@ -338,6 +347,8 @@ function option(...args) {
 			metavar: valueParser.metavar,
 			...options.hidden != null && { hidden: options.hidden }
 		}],
+		leadingNames: new Set(optionNames$1),
+		acceptingAnyToken: false,
 		initialState: valueParser == null ? {
 			success: true,
 			value: false
@@ -622,6 +633,8 @@ function flag(...args) {
 			names: optionNames$1,
 			...options.hidden != null && { hidden: options.hidden }
 		}],
+		leadingNames: new Set(optionNames$1),
+		acceptingAnyToken: false,
 		initialState: void 0,
 		parse(context) {
 			if (context.optionsTerminated) return {
@@ -797,6 +810,8 @@ function argument(valueParser, options = {}) {
 		$stateType: [],
 		priority: 5,
 		usage: [term],
+		leadingNames: EMPTY_LEADING_NAMES,
+		acceptingAnyToken: true,
 		initialState: void 0,
 		parse(context) {
 			if (context.buffer.length < 1) return {
@@ -986,6 +1001,8 @@ function command(name, parser, options = {}) {
 			...options.usageLine != null && { usageLine: options.usageLine },
 			...options.hidden != null && { hidden: options.hidden }
 		}, ...parser.usage],
+		leadingNames: new Set([name]),
+		acceptingAnyToken: false,
 		initialState: void 0,
 		parse(context) {
 			if (context.state === void 0) {
@@ -1180,6 +1197,8 @@ function passThrough(options = {}) {
 			type: "passthrough",
 			...options.hidden != null && { hidden: options.hidden }
 		}],
+		leadingNames: EMPTY_LEADING_NAMES,
+		acceptingAnyToken: false,
 		initialState: [],
 		parse(context) {
 			if (context.buffer.length < 1) return {