@optique/core 1.0.0-dev.1244 → 1.0.0-dev.1252

package/dist/constructs.cjs

@@ -8,6 +8,21 @@ const require_usage_internals = require('./usage-internals.cjs');
 
 //#region src/constructs.ts
 const inheritParentAnnotationsKey = Symbol.for("@optique/core/inheritParentAnnotations");
+/**
+* Returns the field state with parent annotations inherited, respecting
+* the parser's {@link inheritParentAnnotationsKey} flag.  This is the
+* same logic as {@link createFieldStateGetter} inside `object()` but
+* without the per-state cache, for use in module-level helpers like
+* {@link pendingDependencyDefaults}.
+* @internal
+*/
+function getAnnotatedFieldState(parentState, field, parser) {
+	const sourceState = parentState != null && typeof parentState === "object" && field in parentState ? parentState[field] : parser.initialState;
+	if (sourceState == null || typeof sourceState !== "object") return sourceState;
+	const annotations = require_annotations.getAnnotations(parentState);
+	if (annotations === void 0 || require_annotations.getAnnotations(sourceState) === annotations) return sourceState;
+	return Reflect.get(parser, inheritParentAnnotationsKey) === true ? require_annotations.injectAnnotations(sourceState, annotations) : require_annotations.inheritAnnotations(parentState, sourceState);
+}
 function createUnexpectedInputErrorWithScopedSuggestions(baseError, invalidInput, parsers, customFormatter) {
 	const options = /* @__PURE__ */ new Set();
 	const commands = /* @__PURE__ */ new Set();
@@ -693,7 +708,13 @@ function registerCompletedDependency(completed, registry) {
 function* pendingDependencyDefaults(context, parserPairs) {
 	for (const [field, fieldParser] of parserPairs) {
 		const fieldState = context.state != null && typeof context.state === "object" && field in context.state ? context.state[field] : void 0;
-		if (fieldState != null) continue;
+		if (fieldState != null) {
+			if (!Array.isArray(fieldState) && !require_dependency.isDependencySourceState(fieldState) && (require_dependency.isWrappedDependencySource(fieldParser) || require_dependency.isPendingDependencySourceState(fieldParser.initialState))) yield {
+				parser: fieldParser,
+				state: getAnnotatedFieldState(context.state, field, fieldParser)
+			};
+			continue;
+		}
 		if (require_dependency.isPendingDependencySourceState(fieldParser.initialState)) yield {
 			parser: fieldParser,
 			state: fieldParser.initialState
@@ -714,7 +735,31 @@ function* pendingDependencyDefaults(context, parserPairs) {
 * @internal
 */
 function completeDependencySourceDefaults(context, parserPairs, registry) {
-	for (const { parser, state } of pendingDependencyDefaults(context, parserPairs)) registerCompletedDependency(parser.complete(state), registry);
+	for (const { parser, state } of pendingDependencyDefaults(context, parserPairs)) {
+		const completed = parser.complete(state);
+		const depState = wrapAsDependencySourceState(completed, parser);
+		if (depState) registerCompletedDependency(depState, registry);
+	}
+}
+/**
+* Wraps a completed result as a {@link DependencySourceState} if the parser
+* contains a dependency source and the result is a successful plain Result
+* with a defined value.  Returns the existing state if the result is already
+* a DependencySourceState, or `undefined` if no wrapping applies.
+*
+* This helper is shared by both `object()` Phase 1 and the suggest-time
+* pre-completion paths to keep the dep-ID selection and `value !== undefined`
+* rule in one place.
+* @internal
+*/
+function wrapAsDependencySourceState(completed, parser) {
+	if (require_dependency.isDependencySourceState(completed)) return completed;
+	const hasDep = require_dependency.isWrappedDependencySource(parser) || require_dependency.isPendingDependencySourceState(parser.initialState);
+	if (hasDep && typeof completed === "object" && completed !== null && "success" in completed && completed.success && "value" in completed && completed.value !== void 0) {
+		const depId = require_dependency.isWrappedDependencySource(parser) ? parser[require_dependency.wrappedDependencySourceMarker][require_dependency.dependencyId] : parser.initialState[require_dependency.dependencyId];
+		return require_dependency.createDependencySourceState(completed, depId);
+	}
+	return void 0;
 }
 /**
 * Async version of {@link completeDependencySourceDefaults} that awaits
@@ -725,7 +770,11 @@ function completeDependencySourceDefaults(context, parserPairs, registry) {
 * @internal
 */
 async function completeDependencySourceDefaultsAsync(context, parserPairs, registry) {
-	for (const { parser, state } of pendingDependencyDefaults(context, parserPairs)) registerCompletedDependency(await parser.complete(state), registry);
+	for (const { parser, state } of pendingDependencyDefaults(context, parserPairs)) {
+		const completed = await parser.complete(state);
+		const depState = wrapAsDependencySourceState(completed, parser);
+		if (depState) registerCompletedDependency(depState, registry);
+	}
 }
 /**
 * Recursively collects dependency values from DependencySourceState objects
@@ -1085,6 +1134,14 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 							preCompletedState[fieldKey] = completed;
 							preCompletedKeys.add(fieldKey);
 						} else preCompletedState[fieldKey] = fieldState;
+					} else if (fieldState != null && !Array.isArray(fieldState) && !require_dependency.isDependencySourceState(fieldState) && (require_dependency.isWrappedDependencySource(fieldParser) || require_dependency.isPendingDependencySourceState(fieldParser.initialState))) {
+						const annotatedFieldState = getFieldState(field, fieldParser);
+						const completed = fieldParser.complete(annotatedFieldState);
+						const depState = wrapAsDependencySourceState(completed, fieldParser);
+						if (depState) {
+							preCompletedState[fieldKey] = depState;
+							preCompletedKeys.add(fieldKey);
+						} else preCompletedState[fieldKey] = annotatedFieldState;
 					} else preCompletedState[fieldKey] = getFieldState(field, fieldParser);
 				}
 				const resolvedState = resolveDeferredParseStates(preCompletedState);
@@ -1138,6 +1195,14 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 							preCompletedState[fieldKey] = completed;
 							preCompletedKeys.add(fieldKey);
 						} else preCompletedState[fieldKey] = fieldState;
+					} else if (fieldState != null && !Array.isArray(fieldState) && !require_dependency.isDependencySourceState(fieldState) && (require_dependency.isWrappedDependencySource(fieldParser) || require_dependency.isPendingDependencySourceState(fieldParser.initialState))) {
+						const annotatedFieldState = getFieldState(field, fieldParser);
+						const completed = await fieldParser.complete(annotatedFieldState);
+						const depState = wrapAsDependencySourceState(completed, fieldParser);
+						if (depState) {
+							preCompletedState[fieldKey] = depState;
+							preCompletedKeys.add(fieldKey);
+						} else preCompletedState[fieldKey] = annotatedFieldState;
 					} else preCompletedState[fieldKey] = getFieldState(field, fieldParser);
 				}
 				const resolvedState = await resolveDeferredParseStatesAsync(preCompletedState);

package/dist/constructs.js

@@ -1,6 +1,6 @@
 import { getAnnotations, inheritAnnotations, injectAnnotations } from "./annotations.js";
 import { message, optionName, text, values } from "./message.js";
-import { DependencyRegistry, dependencyId, isDeferredParseState, isDependencySourceState, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, wrappedDependencySourceMarker } from "./dependency.js";
+import { DependencyRegistry, createDependencySourceState, dependencyId, isDeferredParseState, isDependencySourceState, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, wrappedDependencySourceMarker } from "./dependency.js";
 import { dispatchByMode, dispatchIterableByMode } from "./mode-dispatch.js";
 import { extractArgumentMetavars, extractCommandNames, extractOptionNames, isDocHidden, mergeHidden } from "./usage.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, findSimilar } from "./suggestion.js";
@@ -8,6 +8,21 @@ import { collectLeadingCandidates } from "./usage-internals.js";
 
 //#region src/constructs.ts
 const inheritParentAnnotationsKey = Symbol.for("@optique/core/inheritParentAnnotations");
+/**
+* Returns the field state with parent annotations inherited, respecting
+* the parser's {@link inheritParentAnnotationsKey} flag.  This is the
+* same logic as {@link createFieldStateGetter} inside `object()` but
+* without the per-state cache, for use in module-level helpers like
+* {@link pendingDependencyDefaults}.
+* @internal
+*/
+function getAnnotatedFieldState(parentState, field, parser) {
+	const sourceState = parentState != null && typeof parentState === "object" && field in parentState ? parentState[field] : parser.initialState;
+	if (sourceState == null || typeof sourceState !== "object") return sourceState;
+	const annotations = getAnnotations(parentState);
+	if (annotations === void 0 || getAnnotations(sourceState) === annotations) return sourceState;
+	return Reflect.get(parser, inheritParentAnnotationsKey) === true ? injectAnnotations(sourceState, annotations) : inheritAnnotations(parentState, sourceState);
+}
 function createUnexpectedInputErrorWithScopedSuggestions(baseError, invalidInput, parsers, customFormatter) {
 	const options = /* @__PURE__ */ new Set();
 	const commands = /* @__PURE__ */ new Set();
@@ -693,7 +708,13 @@ function registerCompletedDependency(completed, registry) {
 function* pendingDependencyDefaults(context, parserPairs) {
 	for (const [field, fieldParser] of parserPairs) {
 		const fieldState = context.state != null && typeof context.state === "object" && field in context.state ? context.state[field] : void 0;
-		if (fieldState != null) continue;
+		if (fieldState != null) {
+			if (!Array.isArray(fieldState) && !isDependencySourceState(fieldState) && (isWrappedDependencySource(fieldParser) || isPendingDependencySourceState(fieldParser.initialState))) yield {
+				parser: fieldParser,
+				state: getAnnotatedFieldState(context.state, field, fieldParser)
+			};
+			continue;
+		}
 		if (isPendingDependencySourceState(fieldParser.initialState)) yield {
 			parser: fieldParser,
 			state: fieldParser.initialState
@@ -714,7 +735,31 @@ function* pendingDependencyDefaults(context, parserPairs) {
 * @internal
 */
 function completeDependencySourceDefaults(context, parserPairs, registry) {
-	for (const { parser, state } of pendingDependencyDefaults(context, parserPairs)) registerCompletedDependency(parser.complete(state), registry);
+	for (const { parser, state } of pendingDependencyDefaults(context, parserPairs)) {
+		const completed = parser.complete(state);
+		const depState = wrapAsDependencySourceState(completed, parser);
+		if (depState) registerCompletedDependency(depState, registry);
+	}
+}
+/**
+* Wraps a completed result as a {@link DependencySourceState} if the parser
+* contains a dependency source and the result is a successful plain Result
+* with a defined value.  Returns the existing state if the result is already
+* a DependencySourceState, or `undefined` if no wrapping applies.
+*
+* This helper is shared by both `object()` Phase 1 and the suggest-time
+* pre-completion paths to keep the dep-ID selection and `value !== undefined`
+* rule in one place.
+* @internal
+*/
+function wrapAsDependencySourceState(completed, parser) {
+	if (isDependencySourceState(completed)) return completed;
+	const hasDep = isWrappedDependencySource(parser) || isPendingDependencySourceState(parser.initialState);
+	if (hasDep && typeof completed === "object" && completed !== null && "success" in completed && completed.success && "value" in completed && completed.value !== void 0) {
+		const depId = isWrappedDependencySource(parser) ? parser[wrappedDependencySourceMarker][dependencyId] : parser.initialState[dependencyId];
+		return createDependencySourceState(completed, depId);
+	}
+	return void 0;
 }
 /**
 * Async version of {@link completeDependencySourceDefaults} that awaits
@@ -725,7 +770,11 @@ function completeDependencySourceDefaults(context, parserPairs, registry) {
 * @internal
 */
 async function completeDependencySourceDefaultsAsync(context, parserPairs, registry) {
-	for (const { parser, state } of pendingDependencyDefaults(context, parserPairs)) registerCompletedDependency(await parser.complete(state), registry);
+	for (const { parser, state } of pendingDependencyDefaults(context, parserPairs)) {
+		const completed = await parser.complete(state);
+		const depState = wrapAsDependencySourceState(completed, parser);
+		if (depState) registerCompletedDependency(depState, registry);
+	}
 }
 /**
 * Recursively collects dependency values from DependencySourceState objects
@@ -1085,6 +1134,14 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 							preCompletedState[fieldKey] = completed;
 							preCompletedKeys.add(fieldKey);
 						} else preCompletedState[fieldKey] = fieldState;
+					} else if (fieldState != null && !Array.isArray(fieldState) && !isDependencySourceState(fieldState) && (isWrappedDependencySource(fieldParser) || isPendingDependencySourceState(fieldParser.initialState))) {
+						const annotatedFieldState = getFieldState(field, fieldParser);
+						const completed = fieldParser.complete(annotatedFieldState);
+						const depState = wrapAsDependencySourceState(completed, fieldParser);
+						if (depState) {
+							preCompletedState[fieldKey] = depState;
+							preCompletedKeys.add(fieldKey);
+						} else preCompletedState[fieldKey] = annotatedFieldState;
 					} else preCompletedState[fieldKey] = getFieldState(field, fieldParser);
 				}
 				const resolvedState = resolveDeferredParseStates(preCompletedState);
@@ -1138,6 +1195,14 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 							preCompletedState[fieldKey] = completed;
 							preCompletedKeys.add(fieldKey);
 						} else preCompletedState[fieldKey] = fieldState;
+					} else if (fieldState != null && !Array.isArray(fieldState) && !isDependencySourceState(fieldState) && (isWrappedDependencySource(fieldParser) || isPendingDependencySourceState(fieldParser.initialState))) {
+						const annotatedFieldState = getFieldState(field, fieldParser);
+						const completed = await fieldParser.complete(annotatedFieldState);
+						const depState = wrapAsDependencySourceState(completed, fieldParser);
+						if (depState) {
+							preCompletedState[fieldKey] = depState;
+							preCompletedKeys.add(fieldKey);
+						} else preCompletedState[fieldKey] = annotatedFieldState;
 					} else preCompletedState[fieldKey] = getFieldState(field, fieldParser);
 				}
 				const resolvedState = await resolveDeferredParseStatesAsync(preCompletedState);

package/dist/valueparser.cjs

@@ -2647,8 +2647,30 @@ function cidr(options) {
 	const maxPrefix = options?.maxPrefix;
 	const errors = options?.errors;
 	const metavar = options?.metavar ?? "CIDR";
-	const ipv4Parser = version === 4 || version === "both" ? ipv4(options?.ipv4) : null;
-	const ipv6Parser = version === 6 || version === "both" ? ipv6(options?.ipv6) : null;
+	const genericIpSentinel = [];
+	const ipv4Parser = version === 4 || version === "both" ? ipv4({
+		...options?.ipv4,
+		errors: {
+			invalidIpv4: genericIpSentinel,
+			privateNotAllowed: errors?.privateNotAllowed,
+			loopbackNotAllowed: errors?.loopbackNotAllowed,
+			linkLocalNotAllowed: errors?.linkLocalNotAllowed,
+			multicastNotAllowed: errors?.multicastNotAllowed,
+			broadcastNotAllowed: errors?.broadcastNotAllowed,
+			zeroNotAllowed: errors?.zeroNotAllowed
+		}
+	}) : null;
+	const ipv6Parser = version === 6 || version === "both" ? ipv6({
+		...options?.ipv6,
+		errors: {
+			invalidIpv6: genericIpSentinel,
+			loopbackNotAllowed: errors?.loopbackNotAllowed,
+			linkLocalNotAllowed: errors?.linkLocalNotAllowed,
+			multicastNotAllowed: errors?.multicastNotAllowed,
+			zeroNotAllowed: errors?.zeroNotAllowed,
+			uniqueLocalNotAllowed: errors?.uniqueLocalNotAllowed
+		}
+	}) : null;
 	return {
 		$mode: "sync",
 		metavar,
@@ -2709,6 +2731,8 @@ function cidr(options) {
 			}
 			let ipVersion = null;
 			let normalizedIp = null;
+			let ipv4Error = null;
+			let ipv6Error = null;
 			if (ipv4Parser !== null) {
 				const result = ipv4Parser.parse(ipPart);
 				if (result.success) {
@@ -2747,7 +2771,7 @@ function cidr(options) {
 							error: msg
 						};
 					}
-				}
+				} else ipv4Error = result;
 			}
 			if (ipVersion === null && ipv6Parser !== null) {
 				const result = ipv6Parser.parse(ipPart);
@@ -2787,9 +2811,120 @@ function cidr(options) {
 							error: msg
 						};
 					}
-				}
+				} else ipv6Error = result;
 			}
 			if (ipVersion === null || normalizedIp === null) {
+				const candidates = [[
+					ipv4Error,
+					4,
+					32
+				], [
+					ipv6Error,
+					6,
+					128
+				]];
+				for (const [err, ver, maxPfx] of candidates) if (err !== null && !err.success && err.error !== genericIpSentinel) {
+					if (prefix > maxPfx) {
+						const errorMsg$1 = errors?.invalidPrefix;
+						if (typeof errorMsg$1 === "function") return {
+							success: false,
+							error: errorMsg$1(prefix, ver)
+						};
+						const msg$1 = errorMsg$1 ?? [
+							{
+								type: "text",
+								text: "Expected a prefix length between 0 and "
+							},
+							{
+								type: "text",
+								text: maxPfx.toString()
+							},
+							{
+								type: "text",
+								text: ` for IPv${ver}, but got `
+							},
+							{
+								type: "text",
+								text: prefix.toString()
+							},
+							{
+								type: "text",
+								text: "."
+							}
+						];
+						return {
+							success: false,
+							error: msg$1
+						};
+					}
+					if (minPrefix !== void 0 && prefix < minPrefix) {
+						const errorMsg$1 = errors?.prefixBelowMinimum;
+						if (typeof errorMsg$1 === "function") return {
+							success: false,
+							error: errorMsg$1(prefix, minPrefix)
+						};
+						const msg$1 = errorMsg$1 ?? [
+							{
+								type: "text",
+								text: "Expected a prefix length greater than or equal to "
+							},
+							{
+								type: "text",
+								text: minPrefix.toString()
+							},
+							{
+								type: "text",
+								text: ", but got "
+							},
+							{
+								type: "text",
+								text: prefix.toString()
+							},
+							{
+								type: "text",
+								text: "."
+							}
+						];
+						return {
+							success: false,
+							error: msg$1
+						};
+					}
+					if (maxPrefix !== void 0 && prefix > maxPrefix) {
+						const errorMsg$1 = errors?.prefixAboveMaximum;
+						if (typeof errorMsg$1 === "function") return {
+							success: false,
+							error: errorMsg$1(prefix, maxPrefix)
+						};
+						const msg$1 = errorMsg$1 ?? [
+							{
+								type: "text",
+								text: "Expected a prefix length less than or equal to "
+							},
+							{
+								type: "text",
+								text: maxPrefix.toString()
+							},
+							{
+								type: "text",
+								text: ", but got "
+							},
+							{
+								type: "text",
+								text: prefix.toString()
+							},
+							{
+								type: "text",
+								text: "."
+							}
+						];
+						return {
+							success: false,
+							error: msg$1
+						};
+					}
+					return err;
+				}
 				const errorMsg = errors?.invalidCidr;
 				if (typeof errorMsg === "function") return {
 					success: false,

package/dist/valueparser.d.cts

@@ -1922,6 +1922,50 @@ interface CidrOptions {
      * Can be a static message or a function that receives the prefix and maximum.
      */
     prefixAboveMaximum?: Message | ((prefix: number, max: number) => Message);
+    /**
+     * Custom error message when a private IPv4 address is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     * @since 1.0.0
+     */
+    privateNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when a loopback address is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     * @since 1.0.0
+     */
+    loopbackNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when a link-local address is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     * @since 1.0.0
+     */
+    linkLocalNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when a multicast address is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     * @since 1.0.0
+     */
+    multicastNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when the broadcast address is used but disallowed
+     * (IPv4 only).
+     * Can be a static message or a function that receives the IP.
+     * @since 1.0.0
+     */
+    broadcastNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when the zero address is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     * @since 1.0.0
+     */
+    zeroNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when a unique local address is used but disallowed
+     * (IPv6 only).
+     * Can be a static message or a function that receives the IP.
+     * @since 1.0.0
+     */
+    uniqueLocalNotAllowed?: Message | ((ip: string) => Message);
   };
 }
 /**

package/dist/valueparser.d.ts

@@ -1922,6 +1922,50 @@ interface CidrOptions {
      * Can be a static message or a function that receives the prefix and maximum.
      */
     prefixAboveMaximum?: Message | ((prefix: number, max: number) => Message);
+    /**
+     * Custom error message when a private IPv4 address is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     * @since 1.0.0
+     */
+    privateNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when a loopback address is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     * @since 1.0.0
+     */
+    loopbackNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when a link-local address is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     * @since 1.0.0
+     */
+    linkLocalNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when a multicast address is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     * @since 1.0.0
+     */
+    multicastNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when the broadcast address is used but disallowed
+     * (IPv4 only).
+     * Can be a static message or a function that receives the IP.
+     * @since 1.0.0
+     */
+    broadcastNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when the zero address is used but disallowed.
+     * Can be a static message or a function that receives the IP.
+     * @since 1.0.0
+     */
+    zeroNotAllowed?: Message | ((ip: string) => Message);
+    /**
+     * Custom error message when a unique local address is used but disallowed
+     * (IPv6 only).
+     * Can be a static message or a function that receives the IP.
+     * @since 1.0.0
+     */
+    uniqueLocalNotAllowed?: Message | ((ip: string) => Message);
   };
 }
 /**

package/dist/valueparser.js

@@ -2647,8 +2647,30 @@ function cidr(options) {
 	const maxPrefix = options?.maxPrefix;
 	const errors = options?.errors;
 	const metavar = options?.metavar ?? "CIDR";
-	const ipv4Parser = version === 4 || version === "both" ? ipv4(options?.ipv4) : null;
-	const ipv6Parser = version === 6 || version === "both" ? ipv6(options?.ipv6) : null;
+	const genericIpSentinel = [];
+	const ipv4Parser = version === 4 || version === "both" ? ipv4({
+		...options?.ipv4,
+		errors: {
+			invalidIpv4: genericIpSentinel,
+			privateNotAllowed: errors?.privateNotAllowed,
+			loopbackNotAllowed: errors?.loopbackNotAllowed,
+			linkLocalNotAllowed: errors?.linkLocalNotAllowed,
+			multicastNotAllowed: errors?.multicastNotAllowed,
+			broadcastNotAllowed: errors?.broadcastNotAllowed,
+			zeroNotAllowed: errors?.zeroNotAllowed
+		}
+	}) : null;
+	const ipv6Parser = version === 6 || version === "both" ? ipv6({
+		...options?.ipv6,
+		errors: {
+			invalidIpv6: genericIpSentinel,
+			loopbackNotAllowed: errors?.loopbackNotAllowed,
+			linkLocalNotAllowed: errors?.linkLocalNotAllowed,
+			multicastNotAllowed: errors?.multicastNotAllowed,
+			zeroNotAllowed: errors?.zeroNotAllowed,
+			uniqueLocalNotAllowed: errors?.uniqueLocalNotAllowed
+		}
+	}) : null;
 	return {
 		$mode: "sync",
 		metavar,
@@ -2709,6 +2731,8 @@ function cidr(options) {
 			}
 			let ipVersion = null;
 			let normalizedIp = null;
+			let ipv4Error = null;
+			let ipv6Error = null;
 			if (ipv4Parser !== null) {
 				const result = ipv4Parser.parse(ipPart);
 				if (result.success) {
@@ -2747,7 +2771,7 @@ function cidr(options) {
 							error: msg
 						};
 					}
-				}
+				} else ipv4Error = result;
 			}
 			if (ipVersion === null && ipv6Parser !== null) {
 				const result = ipv6Parser.parse(ipPart);
@@ -2787,9 +2811,120 @@ function cidr(options) {
 							error: msg
 						};
 					}
-				}
+				} else ipv6Error = result;
 			}
 			if (ipVersion === null || normalizedIp === null) {
+				const candidates = [[
+					ipv4Error,
+					4,
+					32
+				], [
+					ipv6Error,
+					6,
+					128
+				]];
+				for (const [err, ver, maxPfx] of candidates) if (err !== null && !err.success && err.error !== genericIpSentinel) {
+					if (prefix > maxPfx) {
+						const errorMsg$1 = errors?.invalidPrefix;
+						if (typeof errorMsg$1 === "function") return {
+							success: false,
+							error: errorMsg$1(prefix, ver)
+						};
+						const msg$1 = errorMsg$1 ?? [
+							{
+								type: "text",
+								text: "Expected a prefix length between 0 and "
+							},
+							{
+								type: "text",
+								text: maxPfx.toString()
+							},
+							{
+								type: "text",
+								text: ` for IPv${ver}, but got `
+							},
+							{
+								type: "text",
+								text: prefix.toString()
+							},
+							{
+								type: "text",
+								text: "."
+							}
+						];
+						return {
+							success: false,
+							error: msg$1
+						};
+					}
+					if (minPrefix !== void 0 && prefix < minPrefix) {
+						const errorMsg$1 = errors?.prefixBelowMinimum;
+						if (typeof errorMsg$1 === "function") return {
+							success: false,
+							error: errorMsg$1(prefix, minPrefix)
+						};
+						const msg$1 = errorMsg$1 ?? [
+							{
+								type: "text",
+								text: "Expected a prefix length greater than or equal to "
+							},
+							{
+								type: "text",
+								text: minPrefix.toString()
+							},
+							{
+								type: "text",
+								text: ", but got "
+							},
+							{
+								type: "text",
+								text: prefix.toString()
+							},
+							{
+								type: "text",
+								text: "."
+							}
+						];
+						return {
+							success: false,
+							error: msg$1
+						};
+					}
+					if (maxPrefix !== void 0 && prefix > maxPrefix) {
+						const errorMsg$1 = errors?.prefixAboveMaximum;
+						if (typeof errorMsg$1 === "function") return {
+							success: false,
+							error: errorMsg$1(prefix, maxPrefix)
+						};
+						const msg$1 = errorMsg$1 ?? [
+							{
+								type: "text",
+								text: "Expected a prefix length less than or equal to "
+							},
+							{
+								type: "text",
+								text: maxPrefix.toString()
+							},
+							{
+								type: "text",
+								text: ", but got "
+							},
+							{
+								type: "text",
+								text: prefix.toString()
+							},
+							{
+								type: "text",
+								text: "."
+							}
+						];
+						return {
+							success: false,
+							error: msg$1
+						};
+					}
+					return err;
+				}
 				const errorMsg = errors?.invalidCidr;
 				if (typeof errorMsg === "function") return {
 					success: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1244+338f4cf1",
+  "version": "1.0.0-dev.1252+eebac476",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",