@optique/core 0.10.0-dev.363 → 0.10.0-dev.368

package/dist/constructs.cjs

@@ -6,6 +6,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.
@@ -200,16 +251,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) {
@@ -227,7 +268,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);
@@ -423,7 +469,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,11 +1,62 @@
-import { message, optionName, values } from "./message.js";
+import { message, optionName, text, values } from "./message.js";
 import { DependencyRegistry, dependencyId, isDeferredParseState, isDependencySourceState, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, wrappedDependencySourceMarker } from "./dependency.js";
 import { dispatchByMode, dispatchIterableByMode } from "./mode-dispatch.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.
@@ -200,16 +251,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) {
@@ -227,7 +268,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);
@@ -423,7 +469,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

@@ -492,9 +492,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 			} 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

@@ -492,9 +492,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 			} 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/index.cjs

@@ -75,6 +75,7 @@ exports.isNonEmptyString = require_nonempty.isNonEmptyString;
 exports.isPendingDependencySourceState = require_dependency.isPendingDependencySourceState;
 exports.isValueParser = require_valueparser.isValueParser;
 exports.isWrappedDependencySource = require_dependency.isWrappedDependencySource;
+exports.lineBreak = require_message.lineBreak;
 exports.link = require_message.link;
 exports.locale = require_valueparser.locale;
 exports.longestMatch = require_constructs.longestMatch;

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { Annotations, ParseOptions, annotationKey, getAnnotations } from "./annotations.cjs";
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.cjs";
-import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.cjs";
+import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.cjs";
 import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.cjs";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowDefaultOptions, formatDocPage } from "./doc.cjs";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.cjs";
@@ -12,4 +12,4 @@ import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, Mode
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { ParserValuePlaceholder, SourceContext } from "./context.cjs";
 import { CompletionHelpVisibility, CompletionName, ExtractRequiredOptions, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CompletionHelpVisibility, CompletionName, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, link, locale, longestMatch, macAddress, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CompletionHelpVisibility, CompletionName, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Annotations, ParseOptions, annotationKey, getAnnotations } from "./annotations.js";
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
-import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
+import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
 import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowDefaultOptions, formatDocPage } from "./doc.js";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.js";
@@ -12,4 +12,4 @@ import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, Mode
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { ParserValuePlaceholder, SourceContext } from "./context.js";
 import { CompletionHelpVisibility, CompletionName, ExtractRequiredOptions, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CompletionHelpVisibility, CompletionName, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, link, locale, longestMatch, macAddress, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CompletionHelpVisibility, CompletionName, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { annotationKey, getAnnotations } from "./annotations.js";
-import { commandLine, envVar, formatMessage, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
+import { commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { DependencyRegistry, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.js";
 import { extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
@@ -12,4 +12,4 @@ import { argument, command, constant, flag, option, passThrough } from "./primit
 import { getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
 import { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 
-export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, link, locale, longestMatch, macAddress, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/message.cjs

@@ -140,6 +140,18 @@ function commandLine(commandLine$1) {
 	};
 }
 /**
+* Creates a {@link MessageTerm} for an explicit single-line break.
+*
+* Unlike single `\n` in `text()` terms (which are treated as soft breaks and
+* normalized to spaces), this term always renders as a hard line break.
+*
+* @returns A {@link MessageTerm} representing an explicit line break.
+* @since 0.10.0
+*/
+function lineBreak() {
+	return { type: "lineBreak" };
+}
+/**
 * Creates a {@link MessageTerm} for a URL.
 * @param url The URL, which can be a URL object or a string that can be parsed
 *            as a URL. For example, `"https://example.com"` or
@@ -332,7 +344,11 @@ function formatMessage(msg, options = {}) {
 				text: useColors ? `\x1b[36m${cmd}${resetSequence}` : cmd,
 				width: cmd.length
 			};
-		} else if (term.type === "url") {
+		} else if (term.type === "lineBreak") yield {
+			text: "\n",
+			width: -1
+		};
+		else if (term.type === "url") {
 			const urlString = term.url.href;
 			const displayText = useQuotes ? `<${urlString}>` : urlString;
 			if (useColors) {
@@ -369,6 +385,7 @@ function formatMessage(msg, options = {}) {
 exports.commandLine = commandLine;
 exports.envVar = envVar;
 exports.formatMessage = formatMessage;
+exports.lineBreak = lineBreak;
 exports.link = link;
 exports.message = message;
 exports.metavar = metavar;

package/dist/message.d.cts

@@ -123,6 +123,15 @@ type MessageTerm =
    */
   readonly commandLine: string;
 }
+/**
+ * An explicit single-line break term in the message.
+ * @since 0.10.0
+ */ | {
+  /**
+   * The type of the term, which is `"lineBreak"` for an explicit line break.
+   */
+  readonly type: "lineBreak";
+}
 /**
  * A URL term in the message, which represents a clickable hyperlink.
  * @since 0.10.0
@@ -223,6 +232,16 @@ declare function envVar(envVar: string): MessageTerm;
  * @since 0.6.0
  */
 declare function commandLine(commandLine: string): MessageTerm;
+/**
+ * Creates a {@link MessageTerm} for an explicit single-line break.
+ *
+ * Unlike single `\n` in `text()` terms (which are treated as soft breaks and
+ * normalized to spaces), this term always renders as a hard line break.
+ *
+ * @returns A {@link MessageTerm} representing an explicit line break.
+ * @since 0.10.0
+ */
+declare function lineBreak(): MessageTerm;
 /**
  * Creates a {@link MessageTerm} for a URL.
  * @param url The URL, which can be a URL object or a string that can be parsed
@@ -361,4 +380,4 @@ interface MessageFormatOptions {
  */
 declare function formatMessage(msg: Message, options?: MessageFormatOptions): string;
 //#endregion
-export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };
+export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };

package/dist/message.d.ts

@@ -123,6 +123,15 @@ type MessageTerm =
    */
   readonly commandLine: string;
 }
+/**
+ * An explicit single-line break term in the message.
+ * @since 0.10.0
+ */ | {
+  /**
+   * The type of the term, which is `"lineBreak"` for an explicit line break.
+   */
+  readonly type: "lineBreak";
+}
 /**
  * A URL term in the message, which represents a clickable hyperlink.
  * @since 0.10.0
@@ -223,6 +232,16 @@ declare function envVar(envVar: string): MessageTerm;
  * @since 0.6.0
  */
 declare function commandLine(commandLine: string): MessageTerm;
+/**
+ * Creates a {@link MessageTerm} for an explicit single-line break.
+ *
+ * Unlike single `\n` in `text()` terms (which are treated as soft breaks and
+ * normalized to spaces), this term always renders as a hard line break.
+ *
+ * @returns A {@link MessageTerm} representing an explicit line break.
+ * @since 0.10.0
+ */
+declare function lineBreak(): MessageTerm;
 /**
  * Creates a {@link MessageTerm} for a URL.
  * @param url The URL, which can be a URL object or a string that can be parsed
@@ -361,4 +380,4 @@ interface MessageFormatOptions {
  */
 declare function formatMessage(msg: Message, options?: MessageFormatOptions): string;
 //#endregion
-export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };
+export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };

package/dist/message.js

@@ -139,6 +139,18 @@ function commandLine(commandLine$1) {
 	};
 }
 /**
+* Creates a {@link MessageTerm} for an explicit single-line break.
+*
+* Unlike single `\n` in `text()` terms (which are treated as soft breaks and
+* normalized to spaces), this term always renders as a hard line break.
+*
+* @returns A {@link MessageTerm} representing an explicit line break.
+* @since 0.10.0
+*/
+function lineBreak() {
+	return { type: "lineBreak" };
+}
+/**
 * Creates a {@link MessageTerm} for a URL.
 * @param url The URL, which can be a URL object or a string that can be parsed
 *            as a URL. For example, `"https://example.com"` or
@@ -331,7 +343,11 @@ function formatMessage(msg, options = {}) {
 				text: useColors ? `\x1b[36m${cmd}${resetSequence}` : cmd,
 				width: cmd.length
 			};
-		} else if (term.type === "url") {
+		} else if (term.type === "lineBreak") yield {
+			text: "\n",
+			width: -1
+		};
+		else if (term.type === "url") {
 			const urlString = term.url.href;
 			const displayText = useQuotes ? `<${urlString}>` : urlString;
 			if (useColors) {
@@ -365,4 +381,4 @@ function formatMessage(msg, options = {}) {
 }
 
 //#endregion
-export { commandLine, envVar, formatMessage, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };
+export { commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };

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.10.0-dev.363+787c7d2e",
+  "version": "0.10.0-dev.368+9dbf7490",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",