@optique/core 1.4.0-dev.2616 → 1.4.0-dev.2618

package/dist/primitives.d.cts

@@ -104,7 +104,7 @@ interface OptionErrorOptions {
 /**
  * Creates a parser for various styles of command-line options that take an
  * argument value, such as `--option=value`, `-option=value`, `-o value`,
- * `-ovalue`, or `/option:value`.
+ * or `/option:value`.
  * @template M The execution mode of the parser.
  * @template T The type of value this parser produces.
  * @param args The {@link OptionName}s to parse, followed by
@@ -118,7 +118,7 @@ declare function option<M extends Mode, T>(...args: readonly [OptionName, ...rea
 /**
  * Creates a parser for various styles of command-line options that take an
  * argument value, such as `--option=value`, `-option=value`, `-o value`,
- * `-ovalue`, or `/option:value`.
+ * or `/option:value`.
  * @template M The execution mode of the parser.
  * @template T The type of value this parser produces.
  * @param args The {@link OptionName}s to parse, followed by
@@ -140,7 +140,7 @@ declare function option(...optionNames: readonly [OptionName, ...readonly Option
 /**
  * Creates a parser for various styles of command-line options that take an
  * argument value, such as `--option=value`, `-option=value`, `-o value`,
- * `-ovalue`, or `/option:value`.
+ * or `/option:value`.
  * @param args The {@link OptionName}s to parse, followed by
  *             an optional {@link OptionOptions} object that allows you to
  *             specify a description or other metadata.

package/dist/primitives.d.ts

@@ -104,7 +104,7 @@ interface OptionErrorOptions {
 /**
  * Creates a parser for various styles of command-line options that take an
  * argument value, such as `--option=value`, `-option=value`, `-o value`,
- * `-ovalue`, or `/option:value`.
+ * or `/option:value`.
  * @template M The execution mode of the parser.
  * @template T The type of value this parser produces.
  * @param args The {@link OptionName}s to parse, followed by
@@ -118,7 +118,7 @@ declare function option<M extends Mode, T>(...args: readonly [OptionName, ...rea
 /**
  * Creates a parser for various styles of command-line options that take an
  * argument value, such as `--option=value`, `-option=value`, `-o value`,
- * `-ovalue`, or `/option:value`.
+ * or `/option:value`.
  * @template M The execution mode of the parser.
  * @template T The type of value this parser produces.
  * @param args The {@link OptionName}s to parse, followed by
@@ -140,7 +140,7 @@ declare function option(...optionNames: readonly [OptionName, ...readonly Option
 /**
  * Creates a parser for various styles of command-line options that take an
  * argument value, such as `--option=value`, `-option=value`, `-o value`,
- * `-ovalue`, or `/option:value`.
+ * or `/option:value`.
  * @param args The {@link OptionName}s to parse, followed by
  *             an optional {@link OptionOptions} object that allows you to
  *             specify a description or other metadata.

package/dist/primitives.js

@@ -6,14 +6,13 @@ import { dispatchByMode, dispatchIterableByMode, wrapForMode } from "./internal/
 import { getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDerivedValueParser, suggestWithDependency } from "./internal/dependency.js";
 import { effectfulSchedulingNodesKey, exclusiveSourceScopeKey, includeSourceFailureChain, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, sourceCollectionExpansionKey } from "./dependency-runtime.js";
 import { getWrappedChildParseState, getWrappedChildState, isAnnotationWrappedInitialState, normalizeInjectedAnnotationState } from "./annotation-state.js";
-import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
-import { extractLeadingCommandNames } from "./usage-internals.js";
-import { attachedValuePrefix, combinedOptionScope, fullNameOwnsToken, prefixSuggestion, scopeParser, selectableOptionScope } from "./short-option.js";
 import { hiddenCommandAliasesKey } from "./internal/command-alias.js";
+import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
 import { completeOrExtractPhase2Seed, extractPhase2SeedKey } from "./phase2-seed.js";
 import { extractDependencyMetadata } from "./dependency-metadata.js";
 import { fluent } from "./modifiers.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, expandCommandAliasSuggestions, findSimilar } from "./suggestion.js";
+import { extractLeadingCommandNames } from "./usage-internals.js";
 import { isValueParser } from "./valueparser.js";
 
 //#region src/primitives.ts
@@ -257,25 +256,11 @@ function* getSuggestionsWithDependency(valueParser, prefix, dependencyRegistry,
 */
 function* suggestOptionSync(optionNames$1, valueParser, hidden, description, context, prefix) {
 	if (hidden) return;
-	if (context.optionsTerminated) return;
-	const waitingForValue = context.buffer.length > 0 && optionNames$1.includes(context.buffer[context.buffer.length - 1]);
-	if (valueParser != null && !waitingForValue && !isTerminalValueState(context.state)) {
-		const attached = attachedValuePrefix(context, prefix, optionNames$1);
-		if (attached != null) {
-			if (attached.value.length === 0 && optionNames$1.includes(prefix)) yield {
-				kind: "literal",
-				text: prefix,
-				...description != null ? { description } : {}
-			};
-			if (valueParser.suggest != null) for (const suggestion of getSuggestionsWithDependency(valueParser, attached.value, context.dependencyRegistry, context.exec)) yield prefixSuggestion(attached.head, suggestion);
-			return;
-		}
-	}
 	const equalsIndex = prefix.indexOf("=");
-	if (equalsIndex >= 0 && !waitingForValue) {
+	if (equalsIndex >= 0) {
 		const optionPart = prefix.slice(0, equalsIndex);
 		const valuePart = prefix.slice(equalsIndex + 1);
-		if (optionNames$1.includes(optionPart) && !/^-[^-]$/u.test(optionPart)) {
+		if (optionNames$1.includes(optionPart)) {
 			if (valueParser && valueParser.suggest) {
 				const valueSuggestions = getSuggestionsWithDependency(valueParser, valuePart, context.dependencyRegistry, context.exec);
 				for (const suggestion of valueSuggestions) if (suggestion.kind === "literal") yield {
@@ -294,7 +279,7 @@ function* suggestOptionSync(optionNames$1, valueParser, hidden, description, con
 		const expectingValue = context.buffer.length > 0 && optionNames$1.includes(context.buffer[context.buffer.length - 1]);
 		if (!expectingValue && (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/") || prefix.startsWith("+"))) {
 			for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
-				if (prefix === "-" && !/^-[^-]$/u.test(optionName$1)) continue;
+				if (prefix === "-" && optionName$1.length !== 2) continue;
 				yield {
 					kind: "literal",
 					text: optionName$1,
@@ -356,25 +341,11 @@ async function* getSuggestionsWithDependencyAsync(valueParser, prefix, dependenc
 */
 async function* suggestOptionAsync(optionNames$1, valueParser, hidden, description, context, prefix) {
 	if (hidden) return;
-	if (context.optionsTerminated) return;
-	const waitingForValue = context.buffer.length > 0 && optionNames$1.includes(context.buffer[context.buffer.length - 1]);
-	if (valueParser != null && !waitingForValue && !isTerminalValueState(context.state)) {
-		const attached = attachedValuePrefix(context, prefix, optionNames$1);
-		if (attached != null) {
-			if (attached.value.length === 0 && optionNames$1.includes(prefix)) yield {
-				kind: "literal",
-				text: prefix,
-				...description != null ? { description } : {}
-			};
-			if (valueParser.suggest != null) for await (const suggestion of getSuggestionsWithDependencyAsync(valueParser, attached.value, context.dependencyRegistry, context.exec)) yield prefixSuggestion(attached.head, suggestion);
-			return;
-		}
-	}
 	const equalsIndex = prefix.indexOf("=");
-	if (equalsIndex >= 0 && !waitingForValue) {
+	if (equalsIndex >= 0) {
 		const optionPart = prefix.slice(0, equalsIndex);
 		const valuePart = prefix.slice(equalsIndex + 1);
-		if (optionNames$1.includes(optionPart) && !/^-[^-]$/u.test(optionPart)) {
+		if (optionNames$1.includes(optionPart)) {
 			if (valueParser && valueParser.suggest) {
 				const valueSuggestions = getSuggestionsWithDependencyAsync(valueParser, valuePart, context.dependencyRegistry, context.exec);
 				for await (const suggestion of valueSuggestions) if (suggestion.kind === "literal") yield {
@@ -393,7 +364,7 @@ async function* suggestOptionAsync(optionNames$1, valueParser, hidden, descripti
 		const expectingValue = context.buffer.length > 0 && optionNames$1.includes(context.buffer[context.buffer.length - 1]);
 		if (!expectingValue && (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/") || prefix.startsWith("+"))) {
 			for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
-				if (prefix === "-" && !/^-[^-]$/u.test(optionName$1)) continue;
+				if (prefix === "-" && optionName$1.length !== 2) continue;
 				yield {
 					kind: "literal",
 					text: optionName$1,
@@ -553,18 +524,10 @@ function option(...args) {
 					};
 				});
 			}
-			const prefixes = optionNames$1.filter((name) => name.startsWith("--") || name.startsWith("/") || name.startsWith("-") && name.length > 2 && !/^-[^-]$/u.test(name)).map((name) => ({
-				optionName: name,
-				prefix: name.startsWith("/") ? `${name}:` : `${name}=`
-			}));
-			if (valueParser != null && optionNames$1.some((name) => /^-[^-]$/u.test(name) && context.buffer[0].startsWith(name)) && !fullNameOwnsToken(context, context.buffer[0])) {
-				for (const name of optionNames$1) if (/^-[^-]$/u.test(name)) prefixes.push({
-					optionName: name,
-					prefix: name
-				});
-			}
-			for (const { prefix, optionName: optionName$1 } of prefixes) {
+			const prefixes = optionNames$1.filter((name) => name.startsWith("--") || name.startsWith("/") || name.startsWith("-") && name.length > 2).map((name) => name.startsWith("/") ? `${name}:` : `${name}=`);
+			for (const prefix of prefixes) {
 				if (!context.buffer[0].startsWith(prefix)) continue;
+				const optionName$1 = prefix.slice(0, -1);
 				if (hasParsedOptionValue(context.state, valueParser)) return {
 					success: false,
 					consumed: 1,
@@ -603,9 +566,9 @@ function option(...args) {
 				});
 			}
 			if (valueParser == null) {
-				const shortOptions = optionNames$1.filter((name) => name.match(/^-[^-]$/u));
+				const shortOptions = optionNames$1.filter((name) => name.match(/^-[^-]$/));
 				for (const shortOption of shortOptions) {
-					if (!context.buffer[0].startsWith(shortOption) || fullNameOwnsToken(context, context.buffer[0])) continue;
+					if (!context.buffer[0].startsWith(shortOption)) continue;
 					if (hasParsedOptionValue(context.state, valueParser)) return {
 						success: false,
 						consumed: 1,
@@ -619,9 +582,9 @@ function option(...args) {
 								success: true,
 								value: true
 							},
-							buffer: [`-${context.buffer[0].slice(shortOption.length)}`, ...context.buffer.slice(1)]
+							buffer: [`-${context.buffer[0].slice(2)}`, ...context.buffer.slice(1)]
 						},
-						consumed: [context.buffer[0].slice(0, shortOption.length)]
+						consumed: [context.buffer[0].slice(0, 2)]
 					};
 				}
 			}
@@ -883,7 +846,7 @@ function flag(...args) {
 					consumed: context.buffer.slice(0, 1)
 				};
 			}
-			const prefixes = optionNames$1.filter((name) => name.startsWith("--") || name.startsWith("/") || name.startsWith("-") && name.length > 2 && !/^-[^-]$/u.test(name)).map((name) => name.startsWith("/") ? `${name}:` : `${name}=`);
+			const prefixes = optionNames$1.filter((name) => name.startsWith("--") || name.startsWith("/") || name.startsWith("-") && name.length > 2).map((name) => name.startsWith("/") ? `${name}:` : `${name}=`);
 			for (const prefix of prefixes) if (context.buffer[0].startsWith(prefix)) {
 				const value = context.buffer[0].slice(prefix.length);
 				return {
@@ -892,9 +855,9 @@ function flag(...args) {
 					error: message`Flag ${optionName(prefix.slice(0, -1))} does not accept a value, but got: ${value}.`
 				};
 			}
-			const shortOptions = optionNames$1.filter((name) => name.match(/^-[^-]$/u));
+			const shortOptions = optionNames$1.filter((name) => name.match(/^-[^-]$/));
 			for (const shortOption of shortOptions) {
-				if (!context.buffer[0].startsWith(shortOption) || fullNameOwnsToken(context, context.buffer[0])) continue;
+				if (!context.buffer[0].startsWith(shortOption)) continue;
 				if (context.state?.success) return {
 					success: false,
 					consumed: 1,
@@ -908,9 +871,9 @@ function flag(...args) {
 							success: true,
 							value: true
 						},
-						buffer: [`-${context.buffer[0].slice(shortOption.length)}`, ...context.buffer.slice(1)]
+						buffer: [`-${context.buffer[0].slice(2)}`, ...context.buffer.slice(1)]
 					},
-					consumed: [context.buffer[0].slice(0, shortOption.length)]
+					consumed: [context.buffer[0].slice(0, 2)]
 				};
 			}
 			const invalidOption = context.buffer[0];
@@ -951,7 +914,7 @@ function flag(...args) {
 			const suggestions = [];
 			if (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/") || prefix.startsWith("+")) {
 				for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
-					if (prefix === "-" && !/^-[^-]$/u.test(optionName$1)) continue;
+					if (prefix === "-" && optionName$1.length !== 2) continue;
 					suggestions.push({
 						kind: "literal",
 						text: optionName$1,
@@ -1102,7 +1065,7 @@ function negatableFlag(names, options = {}) {
 			const directValue = valueByName.get(context.buffer[0]);
 			if (directValue != null) return parseMatchedNegatableFlag(context, context.buffer[0], directValue, context.buffer.slice(0, 1), 1, context.buffer.slice(1), options);
 			for (const name of optionNames$1) {
-				if (!name.startsWith("--") && !name.startsWith("/") && !name.startsWith("+") && !(name.startsWith("-") && name.length > 2 && !/^-[^-]$/u.test(name))) continue;
+				if (!name.startsWith("--") && !name.startsWith("/") && !name.startsWith("+") && !(name.startsWith("-") && name.length > 2)) continue;
 				const prefix = name.startsWith("/") ? `${name}:` : `${name}=`;
 				if (context.buffer[0].startsWith(prefix)) {
 					const value = context.buffer[0].slice(prefix.length);
@@ -1114,9 +1077,9 @@ function negatableFlag(names, options = {}) {
 				}
 			}
 			for (const shortOption of optionNames$1) {
-				if (!shortOption.match(/^-[^-]$/u)) continue;
-				if (!context.buffer[0].startsWith(shortOption) || fullNameOwnsToken(context, context.buffer[0])) continue;
-				return parseMatchedNegatableFlag(context, shortOption, valueByName.get(shortOption), [context.buffer[0].slice(0, shortOption.length)], 1, [`-${context.buffer[0].slice(shortOption.length)}`, ...context.buffer.slice(1)], options);
+				if (!shortOption.match(/^-[^-]$/)) continue;
+				if (!context.buffer[0].startsWith(shortOption)) continue;
+				return parseMatchedNegatableFlag(context, shortOption, valueByName.get(shortOption), [context.buffer[0].slice(0, 2)], 1, [`-${context.buffer[0].slice(2)}`, ...context.buffer.slice(1)], options);
 			}
 			const invalidOption = context.buffer[0];
 			if (options.errors?.noMatch) {
@@ -1151,7 +1114,7 @@ function negatableFlag(names, options = {}) {
 			const suggestions = [];
 			if (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/") || prefix.startsWith("+")) {
 				for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
-					if (prefix === "-" && !/^-[^-]$/u.test(optionName$1)) continue;
+					if (prefix === "-" && optionName$1.length !== 2) continue;
 					suggestions.push({
 						kind: "literal",
 						text: optionName$1
@@ -1524,8 +1487,6 @@ function command(name, parser, options = {}) {
 	const isAsync = parser.mode === "async";
 	const syncInnerParser = parser;
 	const asyncInnerParser = parser;
-	const commandScope = selectableOptionScope(() => new Set(commandNames));
-	const enteredScope = combinedOptionScope([parser], [name]);
 	const result = {
 		[Symbol.for("@optique/core/commandParser")]: true,
 		mode: parser.mode,
@@ -1593,7 +1554,6 @@ function command(name, parser, options = {}) {
 						] : baseError
 					};
 				}
-				commandScope.select(context, enteredScope);
 				return {
 					success: true,
 					next: {
@@ -1774,9 +1734,7 @@ function command(name, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
-	return fluent(scopeParser(result, commandScope.source, (context) => {
-		if (normalizeCommandState(context.state) != null) commandScope.select(context, enteredScope);
-	}));
+	return fluent(result);
 }
 /**
 * Creates a parser that collects unrecognized options and passes them through.

package/dist/usage-internals.cjs

@@ -76,80 +76,7 @@ function extractLeadingCommandNames(usage) {
 	collectLeadingCandidates(usage, options, commands);
 	return commands;
 }
-/** Collects arities along an entered command path. @internal */
-function collectActiveOptionNames(usage, commandPath, names, fromExclusive, includeDirectAfterCommandOptions) {
-	if (commandPath.length === 0) {
-		collectOptionNamesAtCurrentCommandDepth(usage, names, false);
-		return;
-	}
-	const [commandName, ...rest] = commandPath;
-	for (let i = 0; i < usage.length; i++) {
-		const term = usage[i];
-		if (term.type === "command" && term.name === commandName) {
-			const remainingUsage = usage.slice(i + 1);
-			if (rest.length === 0) collectOptionNamesAtCurrentCommandDepth(remainingUsage, names, !fromExclusive && includeDirectAfterCommandOptions);
-			else collectActiveOptionNames(remainingUsage, rest, names, fromExclusive, includeDirectAfterCommandOptions);
-		} else if (term.type === "exclusive") for (const branch of term.terms) collectActiveOptionNames(branch, commandPath, names, true, includeDirectAfterCommandOptions);
-		else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") collectActiveOptionNames(term.terms, commandPath, names, fromExclusive, includeDirectAfterCommandOptions);
-	}
-}
-/** Collects arities without entering further commands. @internal */
-function collectOptionNamesAtCurrentCommandDepth(usage, names, afterMatchedCommand) {
-	for (const term of usage) if (collectOptionNamesAtCurrentCommandDepthFromTerm(term, names, afterMatchedCommand)) return;
-}
-function collectOptionNamesAtCurrentCommandDepthFromTerm(term, names, afterMatchedCommand) {
-	switch (term.type) {
-		case "command": return !afterMatchedCommand;
-		case "option":
-			if (term.metavar != null) for (const name of term.names) names.value.add(name);
-			else for (const name of term.names) names.flag.add(name);
-			return false;
-		case "optional":
-		case "multiple":
-		case "sequence":
-			collectOptionNamesAtCurrentCommandDepth(term.terms, names, afterMatchedCommand);
-			return false;
-		case "exclusive":
-			for (const branch of term.terms) collectOptionNamesAtCurrentCommandDepth(branch, names, false);
-			return false;
-		case "argument":
-		case "literal":
-		case "passthrough":
-		case "ellipsis": return false;
-	}
-}
-/** Collects scoped root arities across sibling commands. @internal */
-function collectRootOptionNames(usage, names, rootLeadingNames) {
-	for (const term of usage) collectRootOptionNamesFromTerm(term, names, rootLeadingNames);
-}
-function collectRootOptionNamesFromTerm(term, names, rootLeadingNames) {
-	switch (term.type) {
-		case "option":
-			for (const name of term.names) {
-				if (!rootLeadingNames.has(name)) continue;
-				if (term.metavar != null) names.value.add(name);
-				else names.flag.add(name);
-			}
-			return;
-		case "optional":
-		case "multiple":
-		case "sequence":
-			collectRootOptionNames(term.terms, names, rootLeadingNames);
-			return;
-		case "exclusive":
-			for (const branch of term.terms) collectRootOptionNames(branch, names, rootLeadingNames);
-			return;
-		case "argument":
-		case "command":
-		case "literal":
-		case "passthrough":
-		case "ellipsis": return;
-	}
-}
 
 //#endregion
-exports.collectActiveOptionNames = collectActiveOptionNames;
 exports.collectLeadingCandidates = collectLeadingCandidates;
-exports.collectOptionNamesAtCurrentCommandDepth = collectOptionNamesAtCurrentCommandDepth;
-exports.collectRootOptionNames = collectRootOptionNames;
 exports.extractLeadingCommandNames = extractLeadingCommandNames;

package/dist/usage-internals.js

@@ -76,76 +76,6 @@ function extractLeadingCommandNames(usage) {
 	collectLeadingCandidates(usage, options, commands);
 	return commands;
 }
-/** Collects arities along an entered command path. @internal */
-function collectActiveOptionNames(usage, commandPath, names, fromExclusive, includeDirectAfterCommandOptions) {
-	if (commandPath.length === 0) {
-		collectOptionNamesAtCurrentCommandDepth(usage, names, false);
-		return;
-	}
-	const [commandName, ...rest] = commandPath;
-	for (let i = 0; i < usage.length; i++) {
-		const term = usage[i];
-		if (term.type === "command" && term.name === commandName) {
-			const remainingUsage = usage.slice(i + 1);
-			if (rest.length === 0) collectOptionNamesAtCurrentCommandDepth(remainingUsage, names, !fromExclusive && includeDirectAfterCommandOptions);
-			else collectActiveOptionNames(remainingUsage, rest, names, fromExclusive, includeDirectAfterCommandOptions);
-		} else if (term.type === "exclusive") for (const branch of term.terms) collectActiveOptionNames(branch, commandPath, names, true, includeDirectAfterCommandOptions);
-		else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") collectActiveOptionNames(term.terms, commandPath, names, fromExclusive, includeDirectAfterCommandOptions);
-	}
-}
-/** Collects arities without entering further commands. @internal */
-function collectOptionNamesAtCurrentCommandDepth(usage, names, afterMatchedCommand) {
-	for (const term of usage) if (collectOptionNamesAtCurrentCommandDepthFromTerm(term, names, afterMatchedCommand)) return;
-}
-function collectOptionNamesAtCurrentCommandDepthFromTerm(term, names, afterMatchedCommand) {
-	switch (term.type) {
-		case "command": return !afterMatchedCommand;
-		case "option":
-			if (term.metavar != null) for (const name of term.names) names.value.add(name);
-			else for (const name of term.names) names.flag.add(name);
-			return false;
-		case "optional":
-		case "multiple":
-		case "sequence":
-			collectOptionNamesAtCurrentCommandDepth(term.terms, names, afterMatchedCommand);
-			return false;
-		case "exclusive":
-			for (const branch of term.terms) collectOptionNamesAtCurrentCommandDepth(branch, names, false);
-			return false;
-		case "argument":
-		case "literal":
-		case "passthrough":
-		case "ellipsis": return false;
-	}
-}
-/** Collects scoped root arities across sibling commands. @internal */
-function collectRootOptionNames(usage, names, rootLeadingNames) {
-	for (const term of usage) collectRootOptionNamesFromTerm(term, names, rootLeadingNames);
-}
-function collectRootOptionNamesFromTerm(term, names, rootLeadingNames) {
-	switch (term.type) {
-		case "option":
-			for (const name of term.names) {
-				if (!rootLeadingNames.has(name)) continue;
-				if (term.metavar != null) names.value.add(name);
-				else names.flag.add(name);
-			}
-			return;
-		case "optional":
-		case "multiple":
-		case "sequence":
-			collectRootOptionNames(term.terms, names, rootLeadingNames);
-			return;
-		case "exclusive":
-			for (const branch of term.terms) collectRootOptionNames(branch, names, rootLeadingNames);
-			return;
-		case "argument":
-		case "command":
-		case "literal":
-		case "passthrough":
-		case "ellipsis": return;
-	}
-}
 
 //#endregion
-export { collectActiveOptionNames, collectLeadingCandidates, collectOptionNamesAtCurrentCommandDepth, collectRootOptionNames, extractLeadingCommandNames };
+export { collectLeadingCandidates, extractLeadingCommandNames };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.4.0-dev.2616",
+  "version": "1.4.0-dev.2618",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -237,7 +237,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.4.0-dev.2616+37c516eb",
+    "@optique/env": "1.4.0-dev.2618+2cb27efe",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",

package/skills/optique/SKILL.md

@@ -11,8 +11,7 @@ description: >
 license: MIT
 ---
 
-Start at <https://optique.dev/llms.txt> when online. These rules cover the
-combinatorial parser model and common pitfalls offline.
+Start at <https://optique.dev/llms.txt> online; these rules also work offline.
 
 
 Core rules
@@ -30,11 +29,15 @@ Core rules
     Pin `colors`/`maxWidth` in tests; defaults use terminal and environment.
  -  Compose parsers with `object()`, `tuple()`, `seq()`, `or()`, `merge()`, and
     modifiers. Do not hand-write argument scanners around Optique parsers.
- -  Let TypeScript infer parser result types. Only write a separate result
-    interface when another API boundary requires it.
- -  Most parsers are required. `optional(p)` yields `undefined`, and
-    `withDefault(p, value)` supplies a fallback. For absent Boolean flags,
-    use `withDefault(flag("--name"), false)`.
+ -  For command/option help headings, set the runner's
+    `helpSections: { commands: "Commands", options: "Options" }`.
+    It groups untitled entries only on pages with visible commands. See
+    <https://optique.dev/cookbook.md#command-and-option-headings-in-help>.
+ -  Let TypeScript infer results; write a separate result interface only when
+    another API boundary requires it.
+ -  Parsers are usually required. `optional(p)` yields `undefined`, and
+    `withDefault(p, value)` supplies a fallback. Use
+    `withDefault(flag("--name"), false)` for optional Boolean flags.
  -  Use semantic `message` helpers for descriptions and errors. Since 1.3.0,
     customize terminal output with `theme` or `messageFormatter`, preserving
     `initialWidth`, quoting, and width options. Keep canonical errors unthemed.
@@ -47,8 +50,6 @@ Core rules
     `@optique/run/valueparser` for file-system paths. Write a custom
     `{ mode, metavar, parse, format }` value parser only when the catalog does
     not cover the domain.
- -  Since 1.4.0, `-p8080`/`-vp8080` accept attached values. Values consume
-    the literal suffix (`-p=5` gives `"=5"`); full single-dash names win.
  -  Async value parsers like *@optique/git* make containing parsers async.
     Await `run()`/`parse()`/`runParser()` or, for `bindKeyring()`, `runAsync()`.
  -  Use `dependency()` when one value parser controls another's valid values.
@@ -231,9 +232,8 @@ const parser = logLevel();
 Common mistakes checklist
 -------------------------
 
- -  Do not parse `process.argv` manually before calling Optique. Pass the parser
-    to `run()` for applications, or pass explicit argument arrays to `parse()`
-    in tests and embedded use.
+ -  Pass parsers to `run()` for apps; use explicit argument arrays with
+    `parse()` in tests and embedded use. Do not pre-parse `process.argv`.
  -  Do not treat `or(a, b)` as “zero or more alternatives.” It requires one
     matching branch unless the whole `or()` is wrapped in `optional()` or
     `withDefault()`.