@optique/core 0.9.4 → 0.9.6

package/dist/constructs.cjs

@@ -4,6 +4,57 @@ const require_suggestion = require('./suggestion.cjs');
 
 //#region src/constructs.ts
 /**
+* Collects option names and command names that are valid at the current
+* parse position by walking the usage tree.  Only "leading" candidates
+* (those reachable before a required positional argument) are collected.
+*/
+function collectLeadingCandidates(terms, optionNames, commandNames) {
+	if (!terms || !Array.isArray(terms)) return true;
+	for (const term of terms) {
+		if (term.type === "option") {
+			for (const name of term.names) optionNames.add(name);
+			return false;
+		}
+		if (term.type === "command") {
+			commandNames.add(term.name);
+			return false;
+		}
+		if (term.type === "argument") return false;
+		if (term.type === "optional") {
+			collectLeadingCandidates(term.terms, optionNames, commandNames);
+			continue;
+		}
+		if (term.type === "multiple") {
+			collectLeadingCandidates(term.terms, optionNames, commandNames);
+			if (term.min === 0) continue;
+			return false;
+		}
+		if (term.type === "exclusive") {
+			let allAlternativesSkippable = true;
+			for (const exclusiveUsage of term.terms) {
+				const alternativeSkippable = collectLeadingCandidates(exclusiveUsage, optionNames, commandNames);
+				allAlternativesSkippable = allAlternativesSkippable && alternativeSkippable;
+			}
+			if (allAlternativesSkippable) continue;
+			return false;
+		}
+	}
+	return true;
+}
+function createUnexpectedInputErrorWithScopedSuggestions(baseError, invalidInput, parsers, customFormatter) {
+	const options = /* @__PURE__ */ new Set();
+	const commands = /* @__PURE__ */ new Set();
+	for (const parser of parsers) collectLeadingCandidates(parser.usage, options, commands);
+	const candidates = new Set([...options, ...commands]);
+	const suggestions = require_suggestion.findSimilar(invalidInput, candidates, require_suggestion.DEFAULT_FIND_SIMILAR_OPTIONS);
+	const suggestionMsg = customFormatter ? customFormatter(suggestions) : require_suggestion.createSuggestionMessage(suggestions);
+	return suggestionMsg.length > 0 ? [
+		...baseError,
+		require_message.text("\n\n"),
+		...suggestionMsg
+	] : baseError;
+}
+/**
 * Checks if the given token is an option name that requires a value
 * (i.e., has a metavar) within the given usage terms.
 * @param usage The usage terms to search through.
@@ -202,16 +253,6 @@ function getNoMatchError(options, noMatchContext) {
 	return customNoMatch ? typeof customNoMatch === "function" ? customNoMatch(noMatchContext) : customNoMatch : generateNoMatchError(noMatchContext);
 }
 /**
-* Creates default error for parse() method when buffer is not empty.
-* Shared by or() and longestMatch().
-* @internal
-*/
-function createUnexpectedInputError(token, usage, options) {
-	const defaultMsg = require_message.message`Unexpected option or subcommand: ${require_message.optionName(token)}.`;
-	if (options?.errors?.unexpectedInput != null) return typeof options.errors.unexpectedInput === "function" ? options.errors.unexpectedInput(token) : options.errors.unexpectedInput;
-	return require_suggestion.createErrorWithSuggestions(defaultMsg, token, usage, "both", options?.errors?.suggestions);
-}
-/**
 * @since 0.5.0
 */
 function or(...args) {
@@ -230,7 +271,12 @@ function or(...args) {
 	const syncParsers = parsers;
 	const getInitialError = (context) => ({
 		consumed: 0,
-		error: context.buffer.length < 1 ? getNoMatchError(options, noMatchContext) : createUnexpectedInputError(context.buffer[0], context.usage, options)
+		error: context.buffer.length < 1 ? getNoMatchError(options, noMatchContext) : (() => {
+			const token = context.buffer[0];
+			const defaultMsg = require_message.message`Unexpected option or subcommand: ${require_message.optionName(token)}.`;
+			if (options?.errors?.unexpectedInput != null) return typeof options.errors.unexpectedInput === "function" ? options.errors.unexpectedInput(token) : options.errors.unexpectedInput;
+			return createUnexpectedInputErrorWithScopedSuggestions(defaultMsg, token, parsers, options?.errors?.suggestions);
+		})()
 	});
 	const parseSync = (context) => {
 		let error = getInitialError(context);
@@ -372,7 +418,12 @@ function longestMatch(...args) {
 	const syncParsers = parsers;
 	const getInitialError = (context) => ({
 		consumed: 0,
-		error: context.buffer.length < 1 ? getNoMatchError(options, noMatchContext) : createUnexpectedInputError(context.buffer[0], context.usage, options)
+		error: context.buffer.length < 1 ? getNoMatchError(options, noMatchContext) : (() => {
+			const token = context.buffer[0];
+			const defaultMsg = require_message.message`Unexpected option or subcommand: ${require_message.optionName(token)}.`;
+			if (options?.errors?.unexpectedInput != null) return typeof options.errors.unexpectedInput === "function" ? options.errors.unexpectedInput(token) : options.errors.unexpectedInput;
+			return createUnexpectedInputErrorWithScopedSuggestions(defaultMsg, token, parsers, options?.errors?.suggestions);
+		})()
 	});
 	const parseSync = (context) => {
 		let bestMatch = null;

package/dist/constructs.js

@@ -1,9 +1,60 @@
-import { message, optionName, values } from "./message.js";
+import { message, optionName, text, values } from "./message.js";
 import { extractArgumentMetavars, extractCommandNames, extractOptionNames } from "./usage.js";
-import { createErrorWithSuggestions, deduplicateSuggestions } from "./suggestion.js";
+import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, findSimilar } from "./suggestion.js";
 
 //#region src/constructs.ts
 /**
+* Collects option names and command names that are valid at the current
+* parse position by walking the usage tree.  Only "leading" candidates
+* (those reachable before a required positional argument) are collected.
+*/
+function collectLeadingCandidates(terms, optionNames, commandNames) {
+	if (!terms || !Array.isArray(terms)) return true;
+	for (const term of terms) {
+		if (term.type === "option") {
+			for (const name of term.names) optionNames.add(name);
+			return false;
+		}
+		if (term.type === "command") {
+			commandNames.add(term.name);
+			return false;
+		}
+		if (term.type === "argument") return false;
+		if (term.type === "optional") {
+			collectLeadingCandidates(term.terms, optionNames, commandNames);
+			continue;
+		}
+		if (term.type === "multiple") {
+			collectLeadingCandidates(term.terms, optionNames, commandNames);
+			if (term.min === 0) continue;
+			return false;
+		}
+		if (term.type === "exclusive") {
+			let allAlternativesSkippable = true;
+			for (const exclusiveUsage of term.terms) {
+				const alternativeSkippable = collectLeadingCandidates(exclusiveUsage, optionNames, commandNames);
+				allAlternativesSkippable = allAlternativesSkippable && alternativeSkippable;
+			}
+			if (allAlternativesSkippable) continue;
+			return false;
+		}
+	}
+	return true;
+}
+function createUnexpectedInputErrorWithScopedSuggestions(baseError, invalidInput, parsers, customFormatter) {
+	const options = /* @__PURE__ */ new Set();
+	const commands = /* @__PURE__ */ new Set();
+	for (const parser of parsers) collectLeadingCandidates(parser.usage, options, commands);
+	const candidates = new Set([...options, ...commands]);
+	const suggestions = findSimilar(invalidInput, candidates, DEFAULT_FIND_SIMILAR_OPTIONS);
+	const suggestionMsg = customFormatter ? customFormatter(suggestions) : createSuggestionMessage(suggestions);
+	return suggestionMsg.length > 0 ? [
+		...baseError,
+		text("\n\n"),
+		...suggestionMsg
+	] : baseError;
+}
+/**
 * Checks if the given token is an option name that requires a value
 * (i.e., has a metavar) within the given usage terms.
 * @param usage The usage terms to search through.
@@ -202,16 +253,6 @@ function getNoMatchError(options, noMatchContext) {
 	return customNoMatch ? typeof customNoMatch === "function" ? customNoMatch(noMatchContext) : customNoMatch : generateNoMatchError(noMatchContext);
 }
 /**
-* Creates default error for parse() method when buffer is not empty.
-* Shared by or() and longestMatch().
-* @internal
-*/
-function createUnexpectedInputError(token, usage, options) {
-	const defaultMsg = message`Unexpected option or subcommand: ${optionName(token)}.`;
-	if (options?.errors?.unexpectedInput != null) return typeof options.errors.unexpectedInput === "function" ? options.errors.unexpectedInput(token) : options.errors.unexpectedInput;
-	return createErrorWithSuggestions(defaultMsg, token, usage, "both", options?.errors?.suggestions);
-}
-/**
 * @since 0.5.0
 */
 function or(...args) {
@@ -230,7 +271,12 @@ function or(...args) {
 	const syncParsers = parsers;
 	const getInitialError = (context) => ({
 		consumed: 0,
-		error: context.buffer.length < 1 ? getNoMatchError(options, noMatchContext) : createUnexpectedInputError(context.buffer[0], context.usage, options)
+		error: context.buffer.length < 1 ? getNoMatchError(options, noMatchContext) : (() => {
+			const token = context.buffer[0];
+			const defaultMsg = message`Unexpected option or subcommand: ${optionName(token)}.`;
+			if (options?.errors?.unexpectedInput != null) return typeof options.errors.unexpectedInput === "function" ? options.errors.unexpectedInput(token) : options.errors.unexpectedInput;
+			return createUnexpectedInputErrorWithScopedSuggestions(defaultMsg, token, parsers, options?.errors?.suggestions);
+		})()
 	});
 	const parseSync = (context) => {
 		let error = getInitialError(context);
@@ -372,7 +418,12 @@ function longestMatch(...args) {
 	const syncParsers = parsers;
 	const getInitialError = (context) => ({
 		consumed: 0,
-		error: context.buffer.length < 1 ? getNoMatchError(options, noMatchContext) : createUnexpectedInputError(context.buffer[0], context.usage, options)
+		error: context.buffer.length < 1 ? getNoMatchError(options, noMatchContext) : (() => {
+			const token = context.buffer[0];
+			const defaultMsg = message`Unexpected option or subcommand: ${optionName(token)}.`;
+			if (options?.errors?.unexpectedInput != null) return typeof options.errors.unexpectedInput === "function" ? options.errors.unexpectedInput(token) : options.errors.unexpectedInput;
+			return createUnexpectedInputErrorWithScopedSuggestions(defaultMsg, token, parsers, options?.errors?.suggestions);
+		})()
 	});
 	const parseSync = (context) => {
 		let bestMatch = null;

package/dist/facade.cjs

@@ -284,9 +284,26 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 		completion: require_primitives.constant(false),
 		result: originalParser
 	}));
+	const mainParserIndex = parsers.length - 1;
 	if (parsers.length === 1) return parsers[0];
-	else if (parsers.length === 2) return require_constructs.longestMatch(parsers[0], parsers[1]);
-	else return require_constructs.longestMatch(...parsers);
+	let combined;
+	if (parsers.length === 2) combined = require_constructs.longestMatch(parsers[0], parsers[1]);
+	else combined = require_constructs.longestMatch(...parsers);
+	const topUsage = combined.usage[0];
+	if (topUsage?.type === "exclusive" && mainParserIndex > 0) {
+		const terms = [...topUsage.terms];
+		const [mainTerm] = terms.splice(mainParserIndex, 1);
+		const lenientCount = (helpParsers.helpOption ? 1 : 0) + (versionParsers.versionOption ? 1 : 0);
+		terms.splice(lenientCount, 0, mainTerm);
+		combined = {
+			...combined,
+			usage: [{
+				...topUsage,
+				terms
+			}]
+		};
+	}
+	return combined;
 }
 /**
 * Classifies the parsing result into a discriminated union for cleaner handling.
@@ -455,9 +472,9 @@ function runParser(parser, programName, args, options = {}) {
 			} else {
 				const singularMatchExact = completionName === "singular" || completionName === "both" ? arg === "--completion" : false;
 				const pluralMatchExact = completionName === "plural" || completionName === "both" ? arg === "--completions" : false;
-				if ((singularMatchExact || pluralMatchExact) && i + 1 < args.length) {
-					const shell = args[i + 1];
-					const completionArgs = args.slice(i + 2);
+				if (singularMatchExact || pluralMatchExact) {
+					const shell = i + 1 < args.length ? args[i + 1] : "";
+					const completionArgs = i + 1 < args.length ? args.slice(i + 2) : [];
 					return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName);
 				}
 			}

package/dist/facade.js

@@ -284,9 +284,26 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 		completion: constant(false),
 		result: originalParser
 	}));
+	const mainParserIndex = parsers.length - 1;
 	if (parsers.length === 1) return parsers[0];
-	else if (parsers.length === 2) return longestMatch(parsers[0], parsers[1]);
-	else return longestMatch(...parsers);
+	let combined;
+	if (parsers.length === 2) combined = longestMatch(parsers[0], parsers[1]);
+	else combined = longestMatch(...parsers);
+	const topUsage = combined.usage[0];
+	if (topUsage?.type === "exclusive" && mainParserIndex > 0) {
+		const terms = [...topUsage.terms];
+		const [mainTerm] = terms.splice(mainParserIndex, 1);
+		const lenientCount = (helpParsers.helpOption ? 1 : 0) + (versionParsers.versionOption ? 1 : 0);
+		terms.splice(lenientCount, 0, mainTerm);
+		combined = {
+			...combined,
+			usage: [{
+				...topUsage,
+				terms
+			}]
+		};
+	}
+	return combined;
 }
 /**
 * Classifies the parsing result into a discriminated union for cleaner handling.
@@ -455,9 +472,9 @@ function runParser(parser, programName, args, options = {}) {
 			} else {
 				const singularMatchExact = completionName === "singular" || completionName === "both" ? arg === "--completion" : false;
 				const pluralMatchExact = completionName === "plural" || completionName === "both" ? arg === "--completions" : false;
-				if ((singularMatchExact || pluralMatchExact) && i + 1 < args.length) {
-					const shell = args[i + 1];
-					const completionArgs = args.slice(i + 2);
+				if (singularMatchExact || pluralMatchExact) {
+					const shell = i + 1 < args.length ? args[i + 1] : "";
+					const completionArgs = i + 1 < args.length ? args.slice(i + 2) : [];
 					return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName);
 				}
 			}

package/dist/suggestion.cjs

@@ -232,5 +232,6 @@ function deduplicateSuggestions(suggestions) {
 //#endregion
 exports.DEFAULT_FIND_SIMILAR_OPTIONS = DEFAULT_FIND_SIMILAR_OPTIONS;
 exports.createErrorWithSuggestions = createErrorWithSuggestions;
+exports.createSuggestionMessage = createSuggestionMessage;
 exports.deduplicateSuggestions = deduplicateSuggestions;
 exports.findSimilar = findSimilar;

package/dist/suggestion.js

@@ -230,4 +230,4 @@ function deduplicateSuggestions(suggestions) {
 }
 
 //#endregion
-export { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, deduplicateSuggestions, findSimilar };
+export { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, findSimilar };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",