@optique/core 0.9.2 → 0.9.4

package/dist/constructs.cjs

@@ -314,7 +314,9 @@ function or(...args) {
 		},
 		suggest: createExclusiveSuggest(parsers, isAsync),
 		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 {
@@ -324,7 +326,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");
@@ -335,7 +339,9 @@ function or(...args) {
 				else sections.push(fragment);
 			}
 			return {
+				brief,
 				description,
+				footer,
 				fragments: [...sections.map((s) => ({
 					...s,
 					type: "section"
@@ -452,6 +458,7 @@ function longestMatch(...args) {
 		},
 		suggest: createExclusiveSuggest(parsers, isAsync),
 		getDocFragments(state, _defaultValue) {
+			let brief;
 			let description;
 			let footer;
 			let fragments;
@@ -463,12 +470,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

@@ -314,7 +314,9 @@ function or(...args) {
 		},
 		suggest: createExclusiveSuggest(parsers, isAsync),
 		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 {
@@ -324,7 +326,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");
@@ -335,7 +339,9 @@ function or(...args) {
 				else sections.push(fragment);
 			}
 			return {
+				brief,
 				description,
+				footer,
 				fragments: [...sections.map((s) => ({
 					...s,
 					type: "section"
@@ -452,6 +458,7 @@ function longestMatch(...args) {
 		},
 		suggest: createExclusiveSuggest(parsers, isAsync),
 		getDocFragments(state, _defaultValue) {
+			let brief;
 			let description;
 			let footer;
 			let fragments;
@@ -463,12 +470,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

@@ -500,14 +500,69 @@ function runParser(parser, programName, args, options = {}) {
 					else if (commandParsers.length === 2) helpGeneratorParser = require_constructs.longestMatch(commandParsers[0], commandParsers[1]);
 					else helpGeneratorParser = require_constructs.longestMatch(...commandParsers);
 				}
+				const reportInvalidHelpCommand = (validationError) => {
+					stderr(`Usage: ${indentLines(require_usage.formatUsage(programName, augmentedParser.usage, {
+						colors,
+						maxWidth: maxWidth == null ? void 0 : maxWidth - 7,
+						expandCommands: true
+					}), 7)}`);
+					const errorMessage = require_message.formatMessage(validationError, {
+						colors,
+						quotes: !colors
+					});
+					stderr(`Error: ${errorMessage}`);
+					return onError(1);
+				};
+				if (classified.commands.length > 0) {
+					let validationContext = {
+						buffer: [...classified.commands],
+						optionsTerminated: false,
+						state: helpGeneratorParser.initialState,
+						usage: helpGeneratorParser.usage
+					};
+					const processStep = (stepResult) => {
+						if (!stepResult.success) return stepResult.error;
+						if (stepResult.consumed.length < 1) return require_message.message`Unexpected option or subcommand: ${require_message.optionName(validationContext.buffer[0])}.`;
+						validationContext = {
+							...validationContext,
+							buffer: stepResult.next.buffer,
+							optionsTerminated: stepResult.next.optionsTerminated,
+							state: stepResult.next.state,
+							usage: stepResult.next.usage ?? validationContext.usage
+						};
+						return validationContext.buffer.length > 0 ? "continue" : null;
+					};
+					let validationResult = "continue";
+					while (validationResult === "continue") {
+						const stepResult = helpGeneratorParser.parse(validationContext);
+						if (stepResult instanceof Promise) {
+							const asyncValidate = async (result$1) => {
+								let res = processStep(result$1);
+								while (res === "continue") {
+									const next = helpGeneratorParser.parse(validationContext);
+									const resolved = next instanceof Promise ? await next : next;
+									res = processStep(resolved);
+								}
+								if (res != null) return reportInvalidHelpCommand(res);
+								const docOrPromise$1 = require_parser.getDocPage(helpGeneratorParser, classified.commands);
+								return docOrPromise$1 instanceof Promise ? docOrPromise$1.then(displayHelp) : displayHelp(docOrPromise$1);
+							};
+							return stepResult.then(asyncValidate);
+						}
+						validationResult = processStep(stepResult);
+					}
+					if (validationResult != null) return reportInvalidHelpCommand(validationResult);
+				}
 				const displayHelp = (doc) => {
 					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

@@ -500,14 +500,69 @@ function runParser(parser, programName, args, options = {}) {
 					else if (commandParsers.length === 2) helpGeneratorParser = longestMatch(commandParsers[0], commandParsers[1]);
 					else helpGeneratorParser = longestMatch(...commandParsers);
 				}
+				const reportInvalidHelpCommand = (validationError) => {
+					stderr(`Usage: ${indentLines(formatUsage(programName, augmentedParser.usage, {
+						colors,
+						maxWidth: maxWidth == null ? void 0 : maxWidth - 7,
+						expandCommands: true
+					}), 7)}`);
+					const errorMessage = formatMessage(validationError, {
+						colors,
+						quotes: !colors
+					});
+					stderr(`Error: ${errorMessage}`);
+					return onError(1);
+				};
+				if (classified.commands.length > 0) {
+					let validationContext = {
+						buffer: [...classified.commands],
+						optionsTerminated: false,
+						state: helpGeneratorParser.initialState,
+						usage: helpGeneratorParser.usage
+					};
+					const processStep = (stepResult) => {
+						if (!stepResult.success) return stepResult.error;
+						if (stepResult.consumed.length < 1) return message`Unexpected option or subcommand: ${optionName(validationContext.buffer[0])}.`;
+						validationContext = {
+							...validationContext,
+							buffer: stepResult.next.buffer,
+							optionsTerminated: stepResult.next.optionsTerminated,
+							state: stepResult.next.state,
+							usage: stepResult.next.usage ?? validationContext.usage
+						};
+						return validationContext.buffer.length > 0 ? "continue" : null;
+					};
+					let validationResult = "continue";
+					while (validationResult === "continue") {
+						const stepResult = helpGeneratorParser.parse(validationContext);
+						if (stepResult instanceof Promise) {
+							const asyncValidate = async (result$1) => {
+								let res = processStep(result$1);
+								while (res === "continue") {
+									const next = helpGeneratorParser.parse(validationContext);
+									const resolved = next instanceof Promise ? await next : next;
+									res = processStep(resolved);
+								}
+								if (res != null) return reportInvalidHelpCommand(res);
+								const docOrPromise$1 = getDocPage(helpGeneratorParser, classified.commands);
+								return docOrPromise$1 instanceof Promise ? docOrPromise$1.then(displayHelp) : displayHelp(docOrPromise$1);
+							};
+							return stepResult.then(asyncValidate);
+						}
+						validationResult = processStep(stepResult);
+					}
+					if (validationResult != null) return reportInvalidHelpCommand(validationResult);
+				}
 				const displayHelp = (doc) => {
 					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

@@ -337,7 +337,7 @@ async function getDocPageAsyncImpl(parser, args) {
 * Shared by both sync and async implementations.
 */
 function buildDocPage(parser, context, args) {
-	const { description, fragments, footer } = parser.getDocFragments({
+	const { brief, description, fragments, footer } = parser.getDocFragments({
 		kind: "available",
 		state: context.state
 	}, void 0);
@@ -356,15 +356,14 @@ function buildDocPage(parser, context, args) {
 		const term = usage[i];
 		if (term.type === "exclusive") {
 			const found = findCommandInExclusive(term, arg);
-			if (found) {
-				usage.splice(i, 1, ...found);
-				i += found.length;
-			} else i++;
-		} else i++;
+			if (found) usage.splice(i, 1, ...found);
+		}
+		i++;
 	}
 	return {
 		usage,
 		sections,
+		...brief != null && { brief },
 		...description != null && { description },
 		...footer != null && { footer }
 	};

package/dist/parser.js

@@ -337,7 +337,7 @@ async function getDocPageAsyncImpl(parser, args) {
 * Shared by both sync and async implementations.
 */
 function buildDocPage(parser, context, args) {
-	const { description, fragments, footer } = parser.getDocFragments({
+	const { brief, description, fragments, footer } = parser.getDocFragments({
 		kind: "available",
 		state: context.state
 	}, void 0);
@@ -356,15 +356,14 @@ function buildDocPage(parser, context, args) {
 		const term = usage[i];
 		if (term.type === "exclusive") {
 			const found = findCommandInExclusive(term, arg);
-			if (found) {
-				usage.splice(i, 1, ...found);
-				i += found.length;
-			} else i++;
-		} else i++;
+			if (found) usage.splice(i, 1, ...found);
+		}
+		i++;
 	}
 	return {
 		usage,
 		sections,
+		...brief != null && { brief },
 		...description != null && { description },
 		...footer != null && { footer }
 	};

package/dist/primitives.cjs

@@ -867,6 +867,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

@@ -867,6 +867,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/package.json

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