@optique/core 1.4.0-dev.2662 → 1.4.0-dev.2665

package/dist/primitives.cjs

@@ -11,6 +11,7 @@ const require_usage_internals = require('./usage-internals.cjs');
 const require_short_option = require('./short-option.cjs');
 const require_passthrough = require('./internal/passthrough.cjs');
 const require_command_alias = require('./internal/command-alias.cjs');
+const require_failure = require('./internal/failure.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
 const require_dependency_metadata = require('./dependency-metadata.cjs');
 const require_modifiers = require('./modifiers.cjs');
@@ -115,6 +116,22 @@ async function resolveDerivedCompletionAsync(derivedMetadata, state, exec) {
 	}, traceEntry.rawInput, exec.dependencyRuntime);
 	return replayed ?? traceEntry.preliminaryResult ?? state;
 }
+/** Defers option/flag typo work until a failure's message is requested. */
+function unmatchedOptionFailure(invalidOption, usage, errors) {
+	const noMatch = errors?.noMatch;
+	if (noMatch != null && typeof noMatch !== "function") return {
+		success: false,
+		consumed: 0,
+		error: noMatch
+	};
+	return require_failure.createDeferredFailure(0, () => {
+		if (noMatch != null) {
+			const candidates = new Set(require_usage.extractOptionNames(usage));
+			return noMatch.call(errors, invalidOption, require_suggestion.findSimilar(invalidOption, candidates, require_suggestion.DEFAULT_FIND_SIMILAR_OPTIONS));
+		}
+		return require_suggestion.createErrorWithSuggestions(require_message.message`No matched option for ${require_message.optionName(invalidOption)}.`, invalidOption, usage, "option");
+	});
+}
 /**
 * Creates a parser that always succeeds without consuming any input and
 * produces a constant value of the type {@link T}.
@@ -634,28 +651,7 @@ function option(...args) {
 				}
 			}
 			const invalidOption = context.buffer[0];
-			if (options.errors?.noMatch) {
-				if (typeof options.errors.noMatch !== "function") return {
-					success: false,
-					consumed: 0,
-					error: options.errors.noMatch
-				};
-				const candidates = /* @__PURE__ */ new Set();
-				for (const name of require_usage.extractOptionNames(context.usage)) candidates.add(name);
-				const suggestions = require_suggestion.findSimilar(invalidOption, candidates, require_suggestion.DEFAULT_FIND_SIMILAR_OPTIONS);
-				const errorMessage = options.errors.noMatch(invalidOption, suggestions);
-				return {
-					success: false,
-					consumed: 0,
-					error: errorMessage
-				};
-			}
-			const baseError = require_message.message`No matched option for ${require_message.optionName(invalidOption)}.`;
-			return {
-				success: false,
-				consumed: 0,
-				error: require_suggestion.createErrorWithSuggestions(baseError, invalidOption, context.usage, "option")
-			};
+			return unmatchedOptionFailure(invalidOption, context.usage, options.errors);
 		},
 		complete(state, exec) {
 			const missing = valueParser == null ? {
@@ -928,28 +924,7 @@ function flag(...args) {
 				};
 			}
 			const invalidOption = context.buffer[0];
-			if (options.errors?.noMatch) {
-				if (typeof options.errors.noMatch !== "function") return {
-					success: false,
-					consumed: 0,
-					error: options.errors.noMatch
-				};
-				const candidates = /* @__PURE__ */ new Set();
-				for (const name of require_usage.extractOptionNames(context.usage)) candidates.add(name);
-				const suggestions = require_suggestion.findSimilar(invalidOption, candidates, require_suggestion.DEFAULT_FIND_SIMILAR_OPTIONS);
-				const errorMessage = options.errors.noMatch(invalidOption, suggestions);
-				return {
-					success: false,
-					consumed: 0,
-					error: errorMessage
-				};
-			}
-			const baseError = require_message.message`No matched option for ${require_message.optionName(invalidOption)}.`;
-			return {
-				success: false,
-				consumed: 0,
-				error: require_suggestion.createErrorWithSuggestions(baseError, invalidOption, context.usage, "option")
-			};
+			return unmatchedOptionFailure(invalidOption, context.usage, options.errors);
 		},
 		complete(state, _exec) {
 			if (state == null) return {
@@ -1137,23 +1112,7 @@ function negatableFlag(names, options = {}) {
 				if (!context.buffer[0].startsWith(shortOption) || require_short_option.fullNameOwnsToken(context, context.buffer[0])) continue;
 				return parseMatchedNegatableFlag(context, shortOption, valueByName.get(shortOption), [context.buffer[0].slice(0, shortOption.length)], 1, [`-${context.buffer[0].slice(shortOption.length)}`, ...context.buffer.slice(1)], options);
 			}
-			const invalidOption = context.buffer[0];
-			if (options.errors?.noMatch) {
-				const candidates = /* @__PURE__ */ new Set();
-				for (const name of require_usage.extractOptionNames(context.usage)) candidates.add(name);
-				const suggestions = require_suggestion.findSimilar(invalidOption, candidates, require_suggestion.DEFAULT_FIND_SIMILAR_OPTIONS);
-				return {
-					success: false,
-					consumed: 0,
-					error: typeof options.errors.noMatch === "function" ? options.errors.noMatch(invalidOption, suggestions) : options.errors.noMatch
-				};
-			}
-			const baseError = require_message.message`No matched option for ${require_message.optionName(invalidOption)}.`;
-			return {
-				success: false,
-				consumed: 0,
-				error: require_suggestion.createErrorWithSuggestions(baseError, invalidOption, context.usage, "option")
-			};
+			return unmatchedOptionFailure(context.buffer[0], context.usage, options.errors);
 		},
 		complete(state, _exec) {
 			if (state == null) return {
@@ -1594,33 +1553,27 @@ function command(name, parser, options = {}) {
 			if (state === void 0) {
 				if (context.buffer.length < 1 || !commandNames.includes(context.buffer[0])) {
 					const actual = context.buffer.length > 0 ? context.buffer[0] : null;
-					const leadingCmds = require_usage_internals.extractLeadingCommandNames(context.usage);
-					const rawSuggestions = actual ? require_suggestion.findSimilar(actual, leadingCmds, require_suggestion.DEFAULT_FIND_SIMILAR_OPTIONS) : [];
-					const suggestions = require_suggestion.expandCommandAliasSuggestions(context.usage, rawSuggestions);
-					if (options.errors?.notMatched) {
-						const errorMessage = options.errors.notMatched;
-						return {
-							success: false,
-							consumed: 0,
-							error: typeof errorMessage === "function" ? errorMessage(name, actual, suggestions) : errorMessage
-						};
-					}
-					if (actual == null) return {
+					const notMatched = options.errors?.notMatched;
+					if (notMatched != null && typeof notMatched !== "function") return {
 						success: false,
 						consumed: 0,
-						error: require_message.message`Expected command ${require_message.optionName(name)}, but got end of input.`
+						error: notMatched
 					};
-					const baseError = require_message.message`Expected command ${require_message.optionName(name)}, but got ${actual}.`;
-					const suggestionMsg = require_suggestion.createSuggestionMessage(suggestions);
-					return {
-						success: false,
-						consumed: 0,
-						error: suggestionMsg.length > 0 ? [
+					const usage = context.usage;
+					return require_failure.createDeferredFailure(0, () => {
+						const leadingCmds = require_usage_internals.extractLeadingCommandNames(usage);
+						const rawSuggestions = actual ? require_suggestion.findSimilar(actual, leadingCmds, require_suggestion.DEFAULT_FIND_SIMILAR_OPTIONS) : [];
+						const suggestions = require_suggestion.expandCommandAliasSuggestions(usage, rawSuggestions);
+						if (notMatched != null) return notMatched(name, actual, suggestions);
+						if (actual == null) return require_message.message`Expected command ${require_message.optionName(name)}, but got end of input.`;
+						const baseError = require_message.message`Expected command ${require_message.optionName(name)}, but got ${actual}.`;
+						const suggestionMsg = require_suggestion.createSuggestionMessage(suggestions);
+						return suggestionMsg.length > 0 ? [
 							...baseError,
 							require_message.text("\n\n"),
 							...suggestionMsg
-						] : baseError
-					};
+						] : baseError;
+					});
 				}
 				commandScope.select(context, enteredScope);
 				return {

package/dist/primitives.d.cts

@@ -96,6 +96,8 @@ interface OptionErrorOptions {
    * Can be a static message or a function that receives:
    * - invalidOption: The invalid option name that was provided
    * - suggestions: Array of similar valid option names (can be empty)
+   * The callback runs when a retained failure's error is read, and may be
+   * skipped for discarded failures. It should not have side effects.
    *
    * @since 0.7.0
    */
@@ -209,6 +211,8 @@ interface FlagErrorOptions {
    * Can be a static message or a function that receives:
    * - invalidOption: The invalid option name that was provided
    * - suggestions: Array of similar valid option names (can be empty)
+   * The callback runs when a retained failure's error is read, and may be
+   * skipped for discarded failures. It should not have side effects.
    *
    * @since 0.7.0
    */
@@ -321,6 +325,7 @@ interface NegatableFlagErrorOptions {
   readonly unexpectedValue?: Message | ((optionName: string, value: string) => Message);
   /**
    * Custom error message when no matching flag is found.
+   * Callbacks may be skipped when a mismatch is discarded.
    */
   readonly noMatch?: Message | ((invalidOption: string, suggestions: readonly string[]) => Message);
 }
@@ -484,6 +489,8 @@ interface CommandErrorOptions {
    * - expected: The expected command name
    * - actual: The actual input (or null if no input)
    * - suggestions: Array of similar valid command names (can be empty)
+   * The callback runs when a retained failure's error is read, and may be
+   * skipped for discarded failures. It should not have side effects.
    */
   readonly notMatched?: Message | ((expected: string, actual: string | null, suggestions?: readonly string[]) => Message);
   /**

package/dist/primitives.d.ts

@@ -96,6 +96,8 @@ interface OptionErrorOptions {
    * Can be a static message or a function that receives:
    * - invalidOption: The invalid option name that was provided
    * - suggestions: Array of similar valid option names (can be empty)
+   * The callback runs when a retained failure's error is read, and may be
+   * skipped for discarded failures. It should not have side effects.
    *
    * @since 0.7.0
    */
@@ -209,6 +211,8 @@ interface FlagErrorOptions {
    * Can be a static message or a function that receives:
    * - invalidOption: The invalid option name that was provided
    * - suggestions: Array of similar valid option names (can be empty)
+   * The callback runs when a retained failure's error is read, and may be
+   * skipped for discarded failures. It should not have side effects.
    *
    * @since 0.7.0
    */
@@ -321,6 +325,7 @@ interface NegatableFlagErrorOptions {
   readonly unexpectedValue?: Message | ((optionName: string, value: string) => Message);
   /**
    * Custom error message when no matching flag is found.
+   * Callbacks may be skipped when a mismatch is discarded.
    */
   readonly noMatch?: Message | ((invalidOption: string, suggestions: readonly string[]) => Message);
 }
@@ -484,6 +489,8 @@ interface CommandErrorOptions {
    * - expected: The expected command name
    * - actual: The actual input (or null if no input)
    * - suggestions: Array of similar valid command names (can be empty)
+   * The callback runs when a retained failure's error is read, and may be
+   * skipped for discarded failures. It should not have side effects.
    */
   readonly notMatched?: Message | ((expected: string, actual: string | null, suggestions?: readonly string[]) => Message);
   /**

package/dist/primitives.js

@@ -11,6 +11,7 @@ import { extractLeadingCommandNames } from "./usage-internals.js";
 import { attachedValuePrefix, combinedOptionScope, fullNameOwnsToken, prefixSuggestion, scopeParser, selectableOptionScope } from "./short-option.js";
 import { defineKnownCompletion, definePassThroughPriority, defineReachableChildren, getPassThroughFailure } from "./internal/passthrough.js";
 import { hiddenCommandAliasesKey } from "./internal/command-alias.js";
+import { createDeferredFailure } from "./internal/failure.js";
 import { completeOrExtractPhase2Seed, extractPhase2SeedKey } from "./phase2-seed.js";
 import { extractDependencyMetadata } from "./dependency-metadata.js";
 import { fluent } from "./modifiers.js";
@@ -115,6 +116,22 @@ async function resolveDerivedCompletionAsync(derivedMetadata, state, exec) {
 	}, traceEntry.rawInput, exec.dependencyRuntime);
 	return replayed ?? traceEntry.preliminaryResult ?? state;
 }
+/** Defers option/flag typo work until a failure's message is requested. */
+function unmatchedOptionFailure(invalidOption, usage, errors) {
+	const noMatch = errors?.noMatch;
+	if (noMatch != null && typeof noMatch !== "function") return {
+		success: false,
+		consumed: 0,
+		error: noMatch
+	};
+	return createDeferredFailure(0, () => {
+		if (noMatch != null) {
+			const candidates = new Set(extractOptionNames(usage));
+			return noMatch.call(errors, invalidOption, findSimilar(invalidOption, candidates, DEFAULT_FIND_SIMILAR_OPTIONS));
+		}
+		return createErrorWithSuggestions(message`No matched option for ${optionName(invalidOption)}.`, invalidOption, usage, "option");
+	});
+}
 /**
 * Creates a parser that always succeeds without consuming any input and
 * produces a constant value of the type {@link T}.
@@ -634,28 +651,7 @@ function option(...args) {
 				}
 			}
 			const invalidOption = context.buffer[0];
-			if (options.errors?.noMatch) {
-				if (typeof options.errors.noMatch !== "function") return {
-					success: false,
-					consumed: 0,
-					error: options.errors.noMatch
-				};
-				const candidates = /* @__PURE__ */ new Set();
-				for (const name of extractOptionNames(context.usage)) candidates.add(name);
-				const suggestions = findSimilar(invalidOption, candidates, DEFAULT_FIND_SIMILAR_OPTIONS);
-				const errorMessage = options.errors.noMatch(invalidOption, suggestions);
-				return {
-					success: false,
-					consumed: 0,
-					error: errorMessage
-				};
-			}
-			const baseError = message`No matched option for ${optionName(invalidOption)}.`;
-			return {
-				success: false,
-				consumed: 0,
-				error: createErrorWithSuggestions(baseError, invalidOption, context.usage, "option")
-			};
+			return unmatchedOptionFailure(invalidOption, context.usage, options.errors);
 		},
 		complete(state, exec) {
 			const missing = valueParser == null ? {
@@ -928,28 +924,7 @@ function flag(...args) {
 				};
 			}
 			const invalidOption = context.buffer[0];
-			if (options.errors?.noMatch) {
-				if (typeof options.errors.noMatch !== "function") return {
-					success: false,
-					consumed: 0,
-					error: options.errors.noMatch
-				};
-				const candidates = /* @__PURE__ */ new Set();
-				for (const name of extractOptionNames(context.usage)) candidates.add(name);
-				const suggestions = findSimilar(invalidOption, candidates, DEFAULT_FIND_SIMILAR_OPTIONS);
-				const errorMessage = options.errors.noMatch(invalidOption, suggestions);
-				return {
-					success: false,
-					consumed: 0,
-					error: errorMessage
-				};
-			}
-			const baseError = message`No matched option for ${optionName(invalidOption)}.`;
-			return {
-				success: false,
-				consumed: 0,
-				error: createErrorWithSuggestions(baseError, invalidOption, context.usage, "option")
-			};
+			return unmatchedOptionFailure(invalidOption, context.usage, options.errors);
 		},
 		complete(state, _exec) {
 			if (state == null) return {
@@ -1137,23 +1112,7 @@ function negatableFlag(names, options = {}) {
 				if (!context.buffer[0].startsWith(shortOption) || fullNameOwnsToken(context, context.buffer[0])) continue;
 				return parseMatchedNegatableFlag(context, shortOption, valueByName.get(shortOption), [context.buffer[0].slice(0, shortOption.length)], 1, [`-${context.buffer[0].slice(shortOption.length)}`, ...context.buffer.slice(1)], options);
 			}
-			const invalidOption = context.buffer[0];
-			if (options.errors?.noMatch) {
-				const candidates = /* @__PURE__ */ new Set();
-				for (const name of extractOptionNames(context.usage)) candidates.add(name);
-				const suggestions = findSimilar(invalidOption, candidates, DEFAULT_FIND_SIMILAR_OPTIONS);
-				return {
-					success: false,
-					consumed: 0,
-					error: typeof options.errors.noMatch === "function" ? options.errors.noMatch(invalidOption, suggestions) : options.errors.noMatch
-				};
-			}
-			const baseError = message`No matched option for ${optionName(invalidOption)}.`;
-			return {
-				success: false,
-				consumed: 0,
-				error: createErrorWithSuggestions(baseError, invalidOption, context.usage, "option")
-			};
+			return unmatchedOptionFailure(context.buffer[0], context.usage, options.errors);
 		},
 		complete(state, _exec) {
 			if (state == null) return {
@@ -1594,33 +1553,27 @@ function command(name, parser, options = {}) {
 			if (state === void 0) {
 				if (context.buffer.length < 1 || !commandNames.includes(context.buffer[0])) {
 					const actual = context.buffer.length > 0 ? context.buffer[0] : null;
-					const leadingCmds = extractLeadingCommandNames(context.usage);
-					const rawSuggestions = actual ? findSimilar(actual, leadingCmds, DEFAULT_FIND_SIMILAR_OPTIONS) : [];
-					const suggestions = expandCommandAliasSuggestions(context.usage, rawSuggestions);
-					if (options.errors?.notMatched) {
-						const errorMessage = options.errors.notMatched;
-						return {
-							success: false,
-							consumed: 0,
-							error: typeof errorMessage === "function" ? errorMessage(name, actual, suggestions) : errorMessage
-						};
-					}
-					if (actual == null) return {
+					const notMatched = options.errors?.notMatched;
+					if (notMatched != null && typeof notMatched !== "function") return {
 						success: false,
 						consumed: 0,
-						error: message`Expected command ${optionName(name)}, but got end of input.`
+						error: notMatched
 					};
-					const baseError = message`Expected command ${optionName(name)}, but got ${actual}.`;
-					const suggestionMsg = createSuggestionMessage(suggestions);
-					return {
-						success: false,
-						consumed: 0,
-						error: suggestionMsg.length > 0 ? [
+					const usage = context.usage;
+					return createDeferredFailure(0, () => {
+						const leadingCmds = extractLeadingCommandNames(usage);
+						const rawSuggestions = actual ? findSimilar(actual, leadingCmds, DEFAULT_FIND_SIMILAR_OPTIONS) : [];
+						const suggestions = expandCommandAliasSuggestions(usage, rawSuggestions);
+						if (notMatched != null) return notMatched(name, actual, suggestions);
+						if (actual == null) return message`Expected command ${optionName(name)}, but got end of input.`;
+						const baseError = message`Expected command ${optionName(name)}, but got ${actual}.`;
+						const suggestionMsg = createSuggestionMessage(suggestions);
+						return suggestionMsg.length > 0 ? [
 							...baseError,
 							text("\n\n"),
 							...suggestionMsg
-						] : baseError
-					};
+						] : baseError;
+					});
 				}
 				commandScope.select(context, enteredScope);
 				return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.4.0-dev.2662",
+  "version": "1.4.0-dev.2665",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -237,7 +237,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.4.0-dev.2662+8add1ff9",
+    "@optique/env": "1.4.0-dev.2665+868a9d77",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",

package/skills/optique/SKILL.md

@@ -36,10 +36,10 @@ Core rules
  -  Let TypeScript infer results unless another API needs a separate interface.
  -  Parsers usually require input. `optional(p)` yields `undefined`; use
     `withDefault(p, value)` or `withDefault(flag("-v"), false)` for fallbacks.
- -  Use semantic `message` helpers for descriptions and errors. Since 1.3.0,
-    customize terminal output with `theme` or `messageFormatter`, preserving
-    `initialWidth`, quoting, and width options. Keep canonical errors unthemed.
-    `flag()` supports static/callback `errors.unexpectedValue` since 1.4.0.
+ -  Use semantic `message` helpers; keep canonical errors unthemed. Since
+    1.3.0, `theme`/`messageFormatter` should preserve `initialWidth`, quoting,
+    and width options. `flag()` has static/callback `errors.unexpectedValue`
+    since 1.4.0. Mismatch callbacks may be skipped; avoid side effects.
  -  Use value parsers such as `integer()`, `choice()`, `biject()`, `regExp()`,
     `url()`, `origin()`, and `uuid()` instead of validating raw strings after
     parsing. Use `regExp({ flags })` for user-supplied sources, `biject()` for