@optique/core 1.0.0-dev.1242 → 1.0.0-dev.1251

package/dist/valueparser.cjs

@@ -460,6 +460,19 @@ function float(options = {}) {
 	};
 }
 /**
+* The set of URL schemes that are considered "special" by the WHATWG URL
+* Standard.  These schemes always use the `://` authority syntax.
+* Non-special schemes use only `:` (e.g., `mailto:`, `urn:`).
+*/
+const SPECIAL_URL_SCHEMES = new Set([
+	"ftp",
+	"file",
+	"http",
+	"https",
+	"ws",
+	"wss"
+]);
+/**
 * Creates a {@link ValueParser} for URL values.
 *
 * This parser validates that the input is a well-formed URL and optionally
@@ -515,12 +528,15 @@ function url(options = {}) {
 			return value.href;
 		},
 		*suggest(prefix) {
-			if (allowedProtocols && prefix.length > 0 && !prefix.includes("://")) for (const protocol of allowedProtocols) {
+			if (allowedProtocols && prefix.length > 0 && !prefix.includes(":")) for (const protocol of allowedProtocols) {
 				const cleanProtocol = protocol.replace(/:+$/, "");
-				if (cleanProtocol.startsWith(prefix.toLowerCase())) yield {
-					kind: "literal",
-					text: `${cleanProtocol}://`
-				};
+				if (cleanProtocol.startsWith(prefix.toLowerCase())) {
+					const suffix = SPECIAL_URL_SCHEMES.has(cleanProtocol) ? "://" : ":";
+					yield {
+						kind: "literal",
+						text: `${cleanProtocol}${suffix}`
+					};
+				}
 			}
 		}
 	};
@@ -2631,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,
@@ -2693,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) {
@@ -2731,7 +2771,7 @@ function cidr(options) {
 							error: msg
 						};
 					}
-				}
+				} else ipv4Error = result;
 			}
 			if (ipVersion === null && ipv6Parser !== null) {
 				const result = ipv6Parser.parse(ipPart);
@@ -2771,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

@@ -460,6 +460,19 @@ function float(options = {}) {
 	};
 }
 /**
+* The set of URL schemes that are considered "special" by the WHATWG URL
+* Standard.  These schemes always use the `://` authority syntax.
+* Non-special schemes use only `:` (e.g., `mailto:`, `urn:`).
+*/
+const SPECIAL_URL_SCHEMES = new Set([
+	"ftp",
+	"file",
+	"http",
+	"https",
+	"ws",
+	"wss"
+]);
+/**
 * Creates a {@link ValueParser} for URL values.
 *
 * This parser validates that the input is a well-formed URL and optionally
@@ -515,12 +528,15 @@ function url(options = {}) {
 			return value.href;
 		},
 		*suggest(prefix) {
-			if (allowedProtocols && prefix.length > 0 && !prefix.includes("://")) for (const protocol of allowedProtocols) {
+			if (allowedProtocols && prefix.length > 0 && !prefix.includes(":")) for (const protocol of allowedProtocols) {
 				const cleanProtocol = protocol.replace(/:+$/, "");
-				if (cleanProtocol.startsWith(prefix.toLowerCase())) yield {
-					kind: "literal",
-					text: `${cleanProtocol}://`
-				};
+				if (cleanProtocol.startsWith(prefix.toLowerCase())) {
+					const suffix = SPECIAL_URL_SCHEMES.has(cleanProtocol) ? "://" : ":";
+					yield {
+						kind: "literal",
+						text: `${cleanProtocol}${suffix}`
+					};
+				}
 			}
 		}
 	};
@@ -2631,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,
@@ -2693,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) {
@@ -2731,7 +2771,7 @@ function cidr(options) {
 							error: msg
 						};
 					}
-				}
+				} else ipv4Error = result;
 			}
 			if (ipVersion === null && ipv6Parser !== null) {
 				const result = ipv6Parser.parse(ipPart);
@@ -2771,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.1242+dd1a7a84",
+  "version": "1.0.0-dev.1251+2501c981",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",