@optique/core 1.1.0-dev.1998 → 1.1.0-dev.2053

package/dist/facade.cjs

@@ -384,162 +384,42 @@ function createCompletionParser(programName, availableShells, commandConfig, opt
 		completionOption
 	};
 }
-function combineWithHelpVersion(originalParser, helpParsers, versionParsers, completionParsers, groups, helpOptionNames, versionOptionNames) {
+function createMetaOptionDocParser(source) {
+	return {
+		mode: "sync",
+		$valueType: [],
+		$stateType: [],
+		priority: 200,
+		usage: source.usage,
+		leadingNames: source.leadingNames,
+		acceptingAnyToken: false,
+		initialState: null,
+		parse: () => ({
+			success: false,
+			error: require_message.message`Documentation-only meta option.`,
+			consumed: 0
+		}),
+		complete: (state) => ({
+			success: true,
+			value: state
+		}),
+		suggest: function* () {},
+		getDocFragments: (_state, defaultValue) => source.getDocFragments({
+			kind: "available",
+			state: source.initialState
+		}, defaultValue)
+	};
+}
+function combineWithHelpVersion(originalParser, helpParsers, versionParsers, completionParsers, groups) {
 	const parsers = [];
-	const effectiveHelpOptionNames = helpOptionNames ?? ["--help"];
-	const effectiveVersionOptionNames = versionOptionNames ?? ["--version"];
 	if (helpParsers.helpOption) {
-		const lenientHelpParser = {
-			mode: "sync",
-			$valueType: [],
-			$stateType: [],
-			priority: 200,
-			usage: helpParsers.helpOption.usage,
-			leadingNames: helpParsers.helpOption.leadingNames,
-			acceptingAnyToken: false,
-			initialState: null,
-			parse(context) {
-				const { buffer, optionsTerminated } = context;
-				if (optionsTerminated) return {
-					success: false,
-					error: require_message.message`Options terminated.`,
-					consumed: 0
-				};
-				let helpFound = false;
-				let helpIndex = -1;
-				let versionIndex = -1;
-				for (let i = 0; i < buffer.length; i++) {
-					if (buffer[i] === "--") break;
-					if (effectiveHelpOptionNames.includes(buffer[i])) {
-						helpFound = true;
-						helpIndex = i;
-					}
-					if (effectiveVersionOptionNames.includes(buffer[i])) versionIndex = i;
-				}
-				if (helpFound && versionIndex > helpIndex) return {
-					success: false,
-					error: require_message.message`Version option wins.`,
-					consumed: 0
-				};
-				if (helpFound) {
-					const commands = [];
-					for (let i = 0; i < helpIndex; i++) {
-						const arg = buffer[i];
-						if (!arg.startsWith("-")) commands.push(arg);
-					}
-					return {
-						success: true,
-						next: {
-							...context,
-							buffer: [],
-							state: {
-								[metaResultBrand]: true,
-								help: true,
-								version: false,
-								completion: false,
-								commands,
-								helpFlag: true
-							}
-						},
-						consumed: buffer.slice(0)
-					};
-				}
-				return {
-					success: false,
-					error: require_message.message`Flag ${require_message.optionName(effectiveHelpOptionNames[0])} not found.`,
-					consumed: 0
-				};
-			},
-			complete(state) {
-				return {
-					success: true,
-					value: state
-				};
-			},
-			*suggest(_context, prefix) {
-				for (const name of effectiveHelpOptionNames) if (name.startsWith(prefix)) yield {
-					kind: "literal",
-					text: name
-				};
-			},
-			getDocFragments(state) {
-				return helpParsers.helpOption?.getDocFragments(state) ?? { fragments: [] };
-			}
-		};
-		const wrappedHelp = groups?.helpOptionGroup ? require_constructs.group(groups.helpOptionGroup, lenientHelpParser) : lenientHelpParser;
+		const helpOptionDocParser = createMetaOptionDocParser(helpParsers.helpOption);
+		const wrappedHelp = groups?.helpOptionGroup ? require_constructs.group(groups.helpOptionGroup, helpOptionDocParser) : helpOptionDocParser;
 		parsers.push(wrappedHelp);
 	}
 	if (versionParsers.versionOption) {
-		const lenientVersionParser = {
-			mode: "sync",
-			$valueType: [],
-			$stateType: [],
-			priority: 200,
-			usage: versionParsers.versionOption.usage,
-			leadingNames: versionParsers.versionOption.leadingNames,
-			acceptingAnyToken: false,
-			initialState: null,
-			parse(context) {
-				const { buffer, optionsTerminated } = context;
-				if (optionsTerminated) return {
-					success: false,
-					error: require_message.message`Options terminated.`,
-					consumed: 0
-				};
-				let versionFound = false;
-				let versionIndex = -1;
-				let helpIndex = -1;
-				for (let i = 0; i < buffer.length; i++) {
-					if (buffer[i] === "--") break;
-					if (effectiveVersionOptionNames.includes(buffer[i])) {
-						versionFound = true;
-						versionIndex = i;
-					}
-					if (effectiveHelpOptionNames.includes(buffer[i])) helpIndex = i;
-				}
-				if (versionFound && helpIndex > versionIndex) return {
-					success: false,
-					error: require_message.message`Help option wins.`,
-					consumed: 0
-				};
-				if (versionFound) return {
-					success: true,
-					next: {
-						...context,
-						buffer: [],
-						state: {
-							[metaResultBrand]: true,
-							help: false,
-							version: true,
-							completion: false,
-							versionFlag: true
-						}
-					},
-					consumed: buffer.slice(0)
-				};
-				return {
-					success: false,
-					error: require_message.message`Flag ${require_message.optionName(effectiveVersionOptionNames[0])} not found.`,
-					consumed: 0
-				};
-			},
-			complete(state) {
-				return {
-					success: true,
-					value: state
-				};
-			},
-			*suggest(_context, prefix) {
-				for (const name of effectiveVersionOptionNames) if (name.startsWith(prefix)) yield {
-					kind: "literal",
-					text: name
-				};
-			},
-			getDocFragments(state) {
-				return versionParsers.versionOption?.getDocFragments(state) ?? { fragments: [] };
-			}
-		};
-		const wrappedVersion = groups?.versionOptionGroup ? require_constructs.group(groups.versionOptionGroup, lenientVersionParser) : lenientVersionParser;
+		const versionOptionDocParser = createMetaOptionDocParser(versionParsers.versionOption);
+		const wrappedVersion = groups?.versionOptionGroup ? require_constructs.group(groups.versionOptionGroup, versionOptionDocParser) : versionOptionDocParser;
 		parsers.push(wrappedVersion);
 	}
 	if (versionParsers.versionCommand) {
@@ -717,7 +597,7 @@ function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versio
 * Handles shell completion requests.
 * @since 0.6.0
 */
-function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder) {
+function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder, rootOptionSuggestions = []) {
 	const shellName = completionArgs[0] || "";
 	const args = completionArgs.slice(1);
 	const callOnError = (code) => onError(code);
@@ -768,17 +648,248 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 	}
 	return require_mode_dispatch.dispatchByMode(parser.mode, () => {
 		const syncParser = parser;
-		const suggestions = require_parser.suggest(syncParser, args);
+		const completionSuggestions = getSyncCompletionSuggestions(syncParser, args, rootOptionSuggestions);
+		const suggestions = withRootOptionSuggestions(completionSuggestions.suggestions, args, rootOptionSuggestions, completionSuggestions.argumentContext);
 		for (const chunk of shell.encodeSuggestions(suggestions)) stdout(chunk);
 		const result = callOnCompletion(0);
 		if (result instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
 		return result;
 	}, async () => {
-		const suggestions = await require_parser.suggestAsync(parser, args);
-		for (const chunk of shell.encodeSuggestions(suggestions)) stdout(chunk);
+		const asyncParser = parser;
+		const completionSuggestions = await getAsyncCompletionSuggestions(asyncParser, args, rootOptionSuggestions);
+		for (const chunk of shell.encodeSuggestions(withRootOptionSuggestions(completionSuggestions.suggestions, args, rootOptionSuggestions, completionSuggestions.argumentContext))) stdout(chunk);
 		return callOnCompletion(0);
 	});
 }
+function withRootOptionSuggestions(suggestions, args, extraSuggestions, argumentContext) {
+	if (extraSuggestions.length === 0) return suggestions;
+	const prefix = args.at(-1) ?? "";
+	if (argumentContext.optionsTerminated) return suggestions;
+	if (argumentContext.completingOptionValue) return suggestions;
+	if (argumentContext.completedRootOption) return suggestions;
+	if (!(prefix === "" || prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/") || prefix.startsWith("+"))) return suggestions;
+	const seen = new Set(suggestions.flatMap((suggestion) => suggestion.kind === "literal" ? [suggestion.text] : []));
+	const combined = [...suggestions];
+	for (const suggestion of extraSuggestions) {
+		if (prefix === "-" && suggestion.text.startsWith("--")) continue;
+		if (prefix !== "" && !suggestion.text.startsWith(prefix)) continue;
+		if (seen.has(suggestion.text)) continue;
+		combined.push(suggestion);
+		seen.add(suggestion.text);
+	}
+	return combined;
+}
+function getSyncCompletionSuggestions(parser, args, rootOptionSuggestions) {
+	const prefix = args.at(-1) ?? "";
+	let context = createCompletionArgumentParserContext(parser, args.slice(0, -1));
+	while (context.buffer.length > 0) {
+		const result = parser.parse(context);
+		if (result instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
+		if (!result.success) {
+			const argumentContext = getFailedCompletionArgumentContext(result, context, parser, rootOptionSuggestions);
+			return {
+				suggestions: Array.from(parser.suggest(withCompletionSuggestRuntime(parser, context), prefix)),
+				argumentContext
+			};
+		}
+		const previousBuffer = context.buffer;
+		context = result.next;
+		if (isCompletionBufferUnchanged(previousBuffer, context.buffer)) return {
+			suggestions: [],
+			argumentContext: getCompletedCompletionArgumentContext(context)
+		};
+	}
+	return {
+		suggestions: Array.from(parser.suggest(withCompletionSuggestRuntime(parser, context), prefix)),
+		argumentContext: getCompletedCompletionArgumentContext(context)
+	};
+}
+async function getAsyncCompletionSuggestions(parser, args, rootOptionSuggestions) {
+	const prefix = args.at(-1) ?? "";
+	let context = createCompletionArgumentParserContext(parser, args.slice(0, -1));
+	while (context.buffer.length > 0) {
+		const result = await parser.parse(context);
+		if (!result.success) {
+			const argumentContext = getFailedCompletionArgumentContext(result, context, parser, rootOptionSuggestions);
+			const suggestions$1 = [];
+			const suggestContext$1 = await withCompletionSuggestRuntimeAsync(parser, context);
+			for await (const suggestion of parser.suggest(suggestContext$1, prefix)) suggestions$1.push(suggestion);
+			return {
+				suggestions: suggestions$1,
+				argumentContext
+			};
+		}
+		const previousBuffer = context.buffer;
+		context = result.next;
+		if (isCompletionBufferUnchanged(previousBuffer, context.buffer)) return {
+			suggestions: [],
+			argumentContext: getCompletedCompletionArgumentContext(context)
+		};
+	}
+	const suggestions = [];
+	const suggestContext = await withCompletionSuggestRuntimeAsync(parser, context);
+	for await (const suggestion of parser.suggest(suggestContext, prefix)) suggestions.push(suggestion);
+	return {
+		suggestions,
+		argumentContext: getCompletedCompletionArgumentContext(context)
+	};
+}
+function getCompletedCompletionArgumentContext(context) {
+	return {
+		completingOptionValue: false,
+		completedRootOption: false,
+		optionsTerminated: context.optionsTerminated
+	};
+}
+function withCompletionSuggestRuntime(parser, context) {
+	const runtime = require_dependency_runtime.createDependencyRuntimeContext();
+	const nodes = getCompletionSuggestRuntimeNodes(parser, context.state, context.exec?.path ?? []);
+	if (nodes.length > 0) require_dependency_runtime.collectExplicitSourceValues(nodes, runtime);
+	return addCompletionSuggestRuntime(context, runtime);
+}
+async function withCompletionSuggestRuntimeAsync(parser, context) {
+	const runtime = require_dependency_runtime.createDependencyRuntimeContext();
+	const nodes = getCompletionSuggestRuntimeNodes(parser, context.state, context.exec?.path ?? []);
+	if (nodes.length > 0) await require_dependency_runtime.collectExplicitSourceValuesAsync(nodes, runtime);
+	return addCompletionSuggestRuntime(context, runtime);
+}
+function addCompletionSuggestRuntime(context, runtime) {
+	return {
+		...context,
+		dependencyRegistry: runtime.registry,
+		exec: context.exec ? {
+			...context.exec,
+			dependencyRuntime: runtime,
+			dependencyRegistry: runtime.registry
+		} : void 0
+	};
+}
+function getCompletionSuggestRuntimeNodes(parser, state, path) {
+	if (typeof parser.getSuggestRuntimeNodes === "function") return parser.getSuggestRuntimeNodes(state, path);
+	if (parser.dependencyMetadata?.source == null) return [];
+	return [{
+		path,
+		parser,
+		state
+	}];
+}
+function createCompletionArgumentParserContext(parser, args) {
+	return require_parser.createParserContext({
+		buffer: args,
+		state: parser.initialState,
+		optionsTerminated: false
+	}, {
+		usage: parser.usage,
+		phase: "suggest",
+		path: [],
+		trace: require_input_trace.createInputTrace()
+	});
+}
+function getFailedCompletionArgumentContext(result, context, parser, rootOptionSuggestions) {
+	const activeValueOptionNames = collectActiveValueOptionNames(parser.usage, context.exec?.commandPath ?? [], result.consumed > 0, parser.leadingNames);
+	const token = context.buffer[0];
+	return {
+		completingOptionValue: (result.consumed === 0 || result.consumed === 1) && activeValueOptionNames.has(token),
+		completedRootOption: result.consumed === 0 && isRootOptionToken(token, rootOptionSuggestions),
+		optionsTerminated: context.optionsTerminated
+	};
+}
+function isCompletionBufferUnchanged(before, after) {
+	return before.length === after.length && before.every((arg, index) => arg === after[index]);
+}
+function collectActiveValueOptionNames(usage, commandPath, includeDirectAfterCommandOptions, rootLeadingNames) {
+	const optionNames = {
+		value: /* @__PURE__ */ new Set(),
+		flag: /* @__PURE__ */ new Set()
+	};
+	if (commandPath.length === 0) {
+		collectRootOptionNames(usage, optionNames, rootLeadingNames);
+		return optionNames.value;
+	} else collectActiveOptionNames(usage, commandPath, optionNames, false, includeDirectAfterCommandOptions);
+	const names = new Set(optionNames.value);
+	for (const name of optionNames.flag) names.delete(name);
+	return names;
+}
+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":
+			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;
+	}
+}
+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") collectActiveOptionNames(term.terms, commandPath, names, fromExclusive, includeDirectAfterCommandOptions);
+	}
+}
+function isRootOptionToken(token, rootOptionSuggestions) {
+	return token != null && rootOptionSuggestions.some((suggestion) => token === suggestion.text || token.startsWith(`${suggestion.text}=`));
+}
+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":
+			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;
+	}
+}
+function getRootMetaOptionSuggestions(helpOptionConfig, helpOptionNames, versionOptionConfig, versionOptionNames) {
+	const suggestions = [];
+	if (helpOptionConfig != null && !require_usage.isSuggestionHidden(helpOptionConfig.hidden)) suggestions.push(...helpOptionNames.map((name) => ({
+		kind: "literal",
+		text: name
+	})));
+	if (versionOptionConfig != null && !require_usage.isSuggestionHidden(versionOptionConfig.hidden)) suggestions.push(...versionOptionNames.map((name) => ({
+		kind: "literal",
+		text: name
+	})));
+	return suggestions;
+}
 /**
 * Validates the configured version value.
 *
@@ -852,6 +963,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	const versionCommandNames = versionCommandConfig?.names ?? ["version"];
 	const completionCommandNames = completionCommandConfig?.names ?? ["completion"];
 	const completionOptionNames = completionOptionConfig?.names ?? ["--completion"];
+	const rootOptionSuggestions = getRootMetaOptionSuggestions(helpOptionConfig, helpOptionNames, versionOptionConfig, versionOptionNames);
 	const activeMetaEntries = [];
 	if (options.help && helpOptionConfig) activeMetaEntries.push([
 		"option",
@@ -915,7 +1027,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		versionOptionGroup: versionOptionConfig?.group,
 		completionCommandGroup: completionCommandConfig?.group,
 		completionOptionGroup: completionOptionConfig?.group
-	}, helpOptionConfig ? [...helpOptionNames] : void 0, versionOptionConfig ? [...versionOptionNames] : void 0);
+	});
 	const handleResult = (classified) => {
 		switch (classified.type) {
 			case "success": return classified.value;
@@ -926,7 +1038,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 				classified.shell,
 				...classified.commandPath ?? [],
 				...classified.args
-			], programName, parser, classified.source === "command" ? completionParsers.completionCommand : completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], classified.source === "option", sectionOrder);
+			], programName, parser, classified.source === "command" ? completionParsers.completionCommand : completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], classified.source === "option", sectionOrder, rootOptionSuggestions);
 			case "help": {
 				let helpGeneratorParser;
 				const helpAsCommand = helpCommandConfig != null;