@optique/core 0.7.11 → 0.7.13-dev.361

package/dist/constructs.cjs

@@ -24,6 +24,52 @@ function isOptionRequiringValue(usage, token) {
 	}
 	return traverse(usage);
 }
+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;
+}
 /**
 * Extracts required (non-optional) usage terms from a usage array.
 * @param usage The usage to extract required terms from
@@ -132,7 +178,7 @@ function or(...args) {
 					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 require_suggestion.createErrorWithSuggestions(defaultMsg, token, context.usage, "both", options?.errors?.suggestions);
+					return createUnexpectedInputErrorWithScopedSuggestions(defaultMsg, token, parsers, options?.errors?.suggestions);
 				})()
 			};
 			const orderedParsers = parsers.map((p, i) => [p, i]);
@@ -193,7 +239,9 @@ function or(...args) {
 			});
 		},
 		getDocFragments(state, _defaultValue) {
+			let brief;
 			let description;
+			let footer;
 			let fragments;
 			if (state.kind === "unavailable" || state.state == null) fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }, void 0).fragments);
 			else {
@@ -203,7 +251,9 @@ function or(...args) {
 					state: parserResult.next.state
 				} : { kind: "unavailable" };
 				const docFragments = parsers[index].getDocFragments(innerState, void 0);
+				brief = docFragments.brief;
 				description = docFragments.description;
+				footer = docFragments.footer;
 				fragments = docFragments.fragments;
 			}
 			const entries = fragments.filter((f) => f.type === "entry");
@@ -214,7 +264,9 @@ function or(...args) {
 				else sections.push(fragment);
 			}
 			return {
+				brief,
 				description,
+				footer,
 				fragments: [...sections.map((s) => ({
 					...s,
 					type: "section"
@@ -276,7 +328,7 @@ function longestMatch(...args) {
 					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 require_suggestion.createErrorWithSuggestions(defaultMsg, token, context.usage, "both", options?.errors?.suggestions);
+					return createUnexpectedInputErrorWithScopedSuggestions(defaultMsg, token, parsers, options?.errors?.suggestions);
 				})()
 			};
 			for (let i = 0; i < parsers.length; i++) {
@@ -337,6 +389,7 @@ function longestMatch(...args) {
 			});
 		},
 		getDocFragments(state, _defaultValue) {
+			let brief;
 			let description;
 			let footer;
 			let fragments;
@@ -348,12 +401,14 @@ function longestMatch(...args) {
 						kind: "available",
 						state: result.next.state
 					});
+					brief = docResult.brief;
 					description = docResult.description;
 					footer = docResult.footer;
 					fragments = docResult.fragments;
 				} else fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }).fragments);
 			}
 			return {
+				brief,
 				description,
 				fragments,
 				footer

package/dist/constructs.js

@@ -1,6 +1,6 @@
-import { message, optionName, values } from "./message.js";
+import { message, optionName, text, values } from "./message.js";
 import { extractArgumentMetavars, extractCommandNames, extractOptionNames } from "./usage.js";
-import { createErrorWithSuggestions } from "./suggestion.js";
+import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, findSimilar } from "./suggestion.js";
 
 //#region src/constructs.ts
 /**
@@ -24,6 +24,52 @@ function isOptionRequiringValue(usage, token) {
 	}
 	return traverse(usage);
 }
+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;
+}
 /**
 * Extracts required (non-optional) usage terms from a usage array.
 * @param usage The usage to extract required terms from
@@ -132,7 +178,7 @@ function or(...args) {
 					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 createErrorWithSuggestions(defaultMsg, token, context.usage, "both", options?.errors?.suggestions);
+					return createUnexpectedInputErrorWithScopedSuggestions(defaultMsg, token, parsers, options?.errors?.suggestions);
 				})()
 			};
 			const orderedParsers = parsers.map((p, i) => [p, i]);
@@ -193,7 +239,9 @@ function or(...args) {
 			});
 		},
 		getDocFragments(state, _defaultValue) {
+			let brief;
 			let description;
+			let footer;
 			let fragments;
 			if (state.kind === "unavailable" || state.state == null) fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }, void 0).fragments);
 			else {
@@ -203,7 +251,9 @@ function or(...args) {
 					state: parserResult.next.state
 				} : { kind: "unavailable" };
 				const docFragments = parsers[index].getDocFragments(innerState, void 0);
+				brief = docFragments.brief;
 				description = docFragments.description;
+				footer = docFragments.footer;
 				fragments = docFragments.fragments;
 			}
 			const entries = fragments.filter((f) => f.type === "entry");
@@ -214,7 +264,9 @@ function or(...args) {
 				else sections.push(fragment);
 			}
 			return {
+				brief,
 				description,
+				footer,
 				fragments: [...sections.map((s) => ({
 					...s,
 					type: "section"
@@ -276,7 +328,7 @@ function longestMatch(...args) {
 					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 createErrorWithSuggestions(defaultMsg, token, context.usage, "both", options?.errors?.suggestions);
+					return createUnexpectedInputErrorWithScopedSuggestions(defaultMsg, token, parsers, options?.errors?.suggestions);
 				})()
 			};
 			for (let i = 0; i < parsers.length; i++) {
@@ -337,6 +389,7 @@ function longestMatch(...args) {
 			});
 		},
 		getDocFragments(state, _defaultValue) {
+			let brief;
 			let description;
 			let footer;
 			let fragments;
@@ -348,12 +401,14 @@ function longestMatch(...args) {
 						kind: "available",
 						state: result.next.state
 					});
+					brief = docResult.brief;
 					description = docResult.description;
 					footer = docResult.footer;
 					fragments = docResult.fragments;
 				} else fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }).fragments);
 			}
 			return {
+				brief,
 				description,
 				fragments,
 				footer

package/dist/doc.d.cts

@@ -60,6 +60,12 @@ type DocFragment = {
  * a final document page.
  */
 interface DocFragments {
+  /**
+   * An optional brief that provides a short summary for the collection
+   * of fragments.
+   * @since 0.7.12
+   */
+  readonly brief?: Message;
   /**
    * An optional description that applies to the entire collection of fragments.
    */

package/dist/doc.d.ts

@@ -60,6 +60,12 @@ type DocFragment = {
  * a final document page.
  */
 interface DocFragments {
+  /**
+   * An optional brief that provides a short summary for the collection
+   * of fragments.
+   * @since 0.7.12
+   */
+  readonly brief?: Message;
   /**
    * An optional description that applies to the entire collection of fragments.
    */

package/dist/facade.cjs

@@ -561,11 +561,13 @@ function run(parser, programName, args, options = {}) {
 			const doc = require_parser.getDocPage(helpGeneratorParser, classified.commands);
 			if (doc != null) {
 				const isMetaCommandHelp = (completionName === "singular" || completionName === "both" ? requestedCommand === "completion" : false) || (completionName === "plural" || completionName === "both" ? requestedCommand === "completions" : false) || requestedCommand === "help" || requestedCommand === "version";
+				const isSubcommandHelp = classified.commands.length > 0;
+				const shouldOverride = !isMetaCommandHelp && !isSubcommandHelp;
 				const augmentedDoc = {
 					...doc,
-					brief: !isMetaCommandHelp ? brief ?? doc.brief : doc.brief,
-					description: !isMetaCommandHelp ? description ?? doc.description : doc.description,
-					footer: !isMetaCommandHelp ? footer ?? doc.footer : doc.footer
+					brief: shouldOverride ? brief ?? doc.brief : doc.brief ?? brief,
+					description: shouldOverride ? description ?? doc.description : doc.description ?? description,
+					footer: shouldOverride ? footer ?? doc.footer : doc.footer ?? footer
 				};
 				stdout(require_doc.formatDocPage(programName, augmentedDoc, {
 					colors,

package/dist/facade.js

@@ -561,11 +561,13 @@ function run(parser, programName, args, options = {}) {
 			const doc = getDocPage(helpGeneratorParser, classified.commands);
 			if (doc != null) {
 				const isMetaCommandHelp = (completionName === "singular" || completionName === "both" ? requestedCommand === "completion" : false) || (completionName === "plural" || completionName === "both" ? requestedCommand === "completions" : false) || requestedCommand === "help" || requestedCommand === "version";
+				const isSubcommandHelp = classified.commands.length > 0;
+				const shouldOverride = !isMetaCommandHelp && !isSubcommandHelp;
 				const augmentedDoc = {
 					...doc,
-					brief: !isMetaCommandHelp ? brief ?? doc.brief : doc.brief,
-					description: !isMetaCommandHelp ? description ?? doc.description : doc.description,
-					footer: !isMetaCommandHelp ? footer ?? doc.footer : doc.footer
+					brief: shouldOverride ? brief ?? doc.brief : doc.brief ?? brief,
+					description: shouldOverride ? description ?? doc.description : doc.description ?? description,
+					footer: shouldOverride ? footer ?? doc.footer : doc.footer ?? footer
 				};
 				stdout(formatDocPage(programName, augmentedDoc, {
 					colors,

package/dist/parser.cjs

@@ -159,7 +159,7 @@ function getDocPage(parser, args = []) {
 		if (!result.success) break;
 		context = result.next;
 	} while (context.buffer.length > 0);
-	const { description, fragments, footer } = parser.getDocFragments({
+	const { brief, description, fragments, footer } = parser.getDocFragments({
 		kind: "available",
 		state: context.state
 	}, void 0);
@@ -184,6 +184,7 @@ function getDocPage(parser, args = []) {
 	return {
 		usage,
 		sections,
+		...brief != null && { brief },
 		...description != null && { description },
 		...footer != null && { footer }
 	};

package/dist/parser.js

@@ -159,7 +159,7 @@ function getDocPage(parser, args = []) {
 		if (!result.success) break;
 		context = result.next;
 	} while (context.buffer.length > 0);
-	const { description, fragments, footer } = parser.getDocFragments({
+	const { brief, description, fragments, footer } = parser.getDocFragments({
 		kind: "available",
 		state: context.state
 	}, void 0);
@@ -184,6 +184,7 @@ function getDocPage(parser, args = []) {
 	return {
 		usage,
 		sections,
+		...brief != null && { brief },
 		...description != null && { description },
 		...footer != null && { footer }
 	};

package/dist/primitives.cjs

@@ -725,6 +725,7 @@ function command(name, parser, options = {}) {
 			const innerFragments = parser.getDocFragments(innerState, defaultValue);
 			return {
 				...innerFragments,
+				brief: innerFragments.brief ?? options.brief,
 				description: innerFragments.description ?? options.description,
 				footer: innerFragments.footer ?? options.footer
 			};

package/dist/primitives.js

@@ -725,6 +725,7 @@ function command(name, parser, options = {}) {
 			const innerFragments = parser.getDocFragments(innerState, defaultValue);
 			return {
 				...innerFragments,
+				brief: innerFragments.brief ?? options.brief,
 				description: innerFragments.description ?? options.description,
 				footer: innerFragments.footer ?? options.footer
 			};

package/dist/suggestion.cjs

@@ -183,4 +183,5 @@ function createErrorWithSuggestions(baseError, invalidInput, usage, type = "both
 //#endregion
 exports.DEFAULT_FIND_SIMILAR_OPTIONS = DEFAULT_FIND_SIMILAR_OPTIONS;
 exports.createErrorWithSuggestions = createErrorWithSuggestions;
+exports.createSuggestionMessage = createSuggestionMessage;
 exports.findSimilar = findSimilar;

package/dist/suggestion.js

@@ -181,4 +181,4 @@ function createErrorWithSuggestions(baseError, invalidInput, usage, type = "both
 }
 
 //#endregion
-export { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, findSimilar };
+export { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, findSimilar };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.7.11",
+  "version": "0.7.13-dev.361+10f5601c",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",