@optique/core 1.0.0-dev.1555 → 1.0.0-dev.1565

package/dist/context.d.cts

@@ -96,7 +96,9 @@ interface SourceContext<TRequiredOptions = void> {
    * Unique identifier for this context.
    *
    * This symbol is typically the same as the annotation key used by parsers
-   * that consume this context's data.
+   * that consume this context's data.  Passing multiple contexts with the
+   * same id to {@link runWith}, {@link runWithSync}, or {@link runWithAsync}
+   * throws a `TypeError`.
    */
   readonly id: symbol;
   /**

package/dist/context.d.ts

@@ -96,7 +96,9 @@ interface SourceContext<TRequiredOptions = void> {
    * Unique identifier for this context.
    *
    * This symbol is typically the same as the annotation key used by parsers
-   * that consume this context's data.
+   * that consume this context's data.  Passing multiple contexts with the
+   * same id to {@link runWith}, {@link runWithSync}, or {@link runWithAsync}
+   * throws a `TypeError`.
    */
   readonly id: symbol;
   /**

package/dist/facade.cjs

@@ -1192,6 +1192,8 @@ function disposeContextsSync(contexts) {
 * @param contexts Source contexts to use (priority: earlier overrides later).
 * @param options Run options including args, help, version, etc.
 * @returns Promise that resolves to the parsed result.
+* @throws {TypeError} If two or more contexts share the same
+* {@link SourceContext.id}.
 * @since 0.10.0
 *
 * @example
@@ -1221,6 +1223,7 @@ async function runWith(parser, programName, contexts, options) {
 		return Promise.resolve(runParser(parser, programName, args, options));
 	}
 	try {
+		require_validate.validateContextIds(contexts);
 		if (needsEarlyExit(args, options)) {
 			if (parser.$mode === "async") return runParser(parser, programName, args, options);
 			return Promise.resolve(runParser(parser, programName, args, options));
@@ -1281,6 +1284,8 @@ async function runWith(parser, programName, contexts, options) {
 * @returns The parsed result.
 * @throws {TypeError} If an async parser is passed at runtime.  Use
 * {@link runWith} or {@link runWithAsync} for async parsers.
+* @throws {TypeError} If two or more contexts share the same
+* {@link SourceContext.id}.
 * @throws {Error} If any context returns a Promise or if a context's
 * `[Symbol.asyncDispose]` returns a Promise.
 * @since 0.10.0
@@ -1290,6 +1295,7 @@ function runWithSync(parser, programName, contexts, options) {
 	const args = options?.args ?? [];
 	if (contexts.length === 0) return runParser(parser, programName, args, options);
 	try {
+		require_validate.validateContextIds(contexts);
 		if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 		const ctxOptions = options?.contextOptions;
 		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts, ctxOptions);
@@ -1333,6 +1339,8 @@ function runWithSync(parser, programName, contexts, options) {
 * @param contexts Source contexts to use (priority: earlier overrides later).
 * @param options Run options including args, help, version, etc.
 * @returns Promise that resolves to the parsed result.
+* @throws {TypeError} If two or more contexts share the same
+* {@link SourceContext.id}.
 * @since 0.10.0
 */
 function runWithAsync(parser, programName, contexts, options) {

package/dist/facade.d.cts

@@ -428,6 +428,8 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
  * @returns Promise that resolves to the parsed result.
+ * @throws {TypeError} If two or more contexts share the same
+ * {@link SourceContext.id}.
  * @since 0.10.0
  *
  * @example
@@ -467,6 +469,8 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * @returns The parsed result.
  * @throws {TypeError} If an async parser is passed at runtime.  Use
  * {@link runWith} or {@link runWithAsync} for async parsers.
+ * @throws {TypeError} If two or more contexts share the same
+ * {@link SourceContext.id}.
  * @throws {Error} If any context returns a Promise or if a context's
  * `[Symbol.asyncDispose]` returns a Promise.
  * @since 0.10.0
@@ -486,6 +490,8 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
  * @returns Promise that resolves to the parsed result.
+ * @throws {TypeError} If two or more contexts share the same
+ * {@link SourceContext.id}.
  * @since 0.10.0
  */
 declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;

package/dist/facade.d.ts

@@ -428,6 +428,8 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
  * @returns Promise that resolves to the parsed result.
+ * @throws {TypeError} If two or more contexts share the same
+ * {@link SourceContext.id}.
  * @since 0.10.0
  *
  * @example
@@ -467,6 +469,8 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * @returns The parsed result.
  * @throws {TypeError} If an async parser is passed at runtime.  Use
  * {@link runWith} or {@link runWithAsync} for async parsers.
+ * @throws {TypeError} If two or more contexts share the same
+ * {@link SourceContext.id}.
  * @throws {Error} If any context returns a Promise or if a context's
  * `[Symbol.asyncDispose]` returns a Promise.
  * @since 0.10.0
@@ -486,6 +490,8 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
  * @returns Promise that resolves to the parsed result.
+ * @throws {TypeError} If two or more contexts share the same
+ * {@link SourceContext.id}.
  * @since 0.10.0
  */
 declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;

package/dist/facade.js

@@ -2,7 +2,7 @@ import { injectAnnotations } from "./annotations.js";
 import { commandLine, formatMessage, lineBreak, message, optionName, text, value } from "./message.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { dispatchByMode } from "./mode-dispatch.js";
-import { validateCommandNames, validateMetaNameCollisions, validateOptionNames, validateProgramName } from "./validate.js";
+import { validateCommandNames, validateContextIds, validateMetaNameCollisions, validateOptionNames, validateProgramName } from "./validate.js";
 import { extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage } from "./usage.js";
 import { formatDocPage } from "./doc.js";
 import { group, longestMatch, object } from "./constructs.js";
@@ -1192,6 +1192,8 @@ function disposeContextsSync(contexts) {
 * @param contexts Source contexts to use (priority: earlier overrides later).
 * @param options Run options including args, help, version, etc.
 * @returns Promise that resolves to the parsed result.
+* @throws {TypeError} If two or more contexts share the same
+* {@link SourceContext.id}.
 * @since 0.10.0
 *
 * @example
@@ -1221,6 +1223,7 @@ async function runWith(parser, programName, contexts, options) {
 		return Promise.resolve(runParser(parser, programName, args, options));
 	}
 	try {
+		validateContextIds(contexts);
 		if (needsEarlyExit(args, options)) {
 			if (parser.$mode === "async") return runParser(parser, programName, args, options);
 			return Promise.resolve(runParser(parser, programName, args, options));
@@ -1281,6 +1284,8 @@ async function runWith(parser, programName, contexts, options) {
 * @returns The parsed result.
 * @throws {TypeError} If an async parser is passed at runtime.  Use
 * {@link runWith} or {@link runWithAsync} for async parsers.
+* @throws {TypeError} If two or more contexts share the same
+* {@link SourceContext.id}.
 * @throws {Error} If any context returns a Promise or if a context's
 * `[Symbol.asyncDispose]` returns a Promise.
 * @since 0.10.0
@@ -1290,6 +1295,7 @@ function runWithSync(parser, programName, contexts, options) {
 	const args = options?.args ?? [];
 	if (contexts.length === 0) return runParser(parser, programName, args, options);
 	try {
+		validateContextIds(contexts);
 		if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 		const ctxOptions = options?.contextOptions;
 		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts, ctxOptions);
@@ -1333,6 +1339,8 @@ function runWithSync(parser, programName, contexts, options) {
 * @param contexts Source contexts to use (priority: earlier overrides later).
 * @param options Run options including args, help, version, etc.
 * @returns Promise that resolves to the parsed result.
+* @throws {TypeError} If two or more contexts share the same
+* {@link SourceContext.id}.
 * @since 0.10.0
 */
 function runWithAsync(parser, programName, contexts, options) {

package/dist/usage.cjs

@@ -239,6 +239,9 @@ function formatUsage(programName, usage, options = {}) {
 *    nested exclusive terms into their parent exclusive term to avoid
 *    redundant nesting. For example, an exclusive term containing another
 *    exclusive term will have its nested terms flattened into the parent.
+*    Similarly, nested optional terms are collapsed:
+*    `optional(optional(X))` becomes `optional(X)` when the outer optional
+*    contains only a single inner optional term.
 *
 * 3. *Sorting*: Reorders terms to improve readability by placing:
 *    - Commands (subcommands) first
@@ -251,8 +254,8 @@ function formatUsage(programName, usage, options = {}) {
 *
 * @param usage The usage description to normalize.
 * @returns A normalized usage description with degenerate terms removed,
-*          nested exclusive terms flattened, and remaining terms sorted for
-*          optimal readability.
+*          nested exclusive and optional terms flattened, and remaining
+*          terms sorted for optimal readability.
 */
 function normalizeUsage(usage) {
 	const terms = usage.map(normalizeUsageTerm).filter(isNonDegenerateTerm);
@@ -266,11 +269,14 @@ function normalizeUsage(usage) {
 	return terms;
 }
 function normalizeUsageTerm(term) {
-	if (term.type === "optional") return {
-		type: "optional",
-		terms: normalizeUsage(term.terms)
-	};
-	else if (term.type === "multiple") return {
+	if (term.type === "optional") {
+		const normalized = normalizeUsage(term.terms);
+		if (normalized.length === 1 && normalized[0].type === "optional") return normalized[0];
+		return {
+			type: "optional",
+			terms: normalized
+		};
+	} else if (term.type === "multiple") return {
 		type: "multiple",
 		terms: normalizeUsage(term.terms),
 		min: term.min

package/dist/usage.d.cts

@@ -379,6 +379,9 @@ declare function formatUsage(programName: string, usage: Usage, options?: UsageF
  *    nested exclusive terms into their parent exclusive term to avoid
  *    redundant nesting. For example, an exclusive term containing another
  *    exclusive term will have its nested terms flattened into the parent.
+ *    Similarly, nested optional terms are collapsed:
+ *    `optional(optional(X))` becomes `optional(X)` when the outer optional
+ *    contains only a single inner optional term.
  *
  * 3. *Sorting*: Reorders terms to improve readability by placing:
  *    - Commands (subcommands) first
@@ -391,8 +394,8 @@ declare function formatUsage(programName: string, usage: Usage, options?: UsageF
  *
  * @param usage The usage description to normalize.
  * @returns A normalized usage description with degenerate terms removed,
- *          nested exclusive terms flattened, and remaining terms sorted for
- *          optimal readability.
+ *          nested exclusive and optional terms flattened, and remaining
+ *          terms sorted for optimal readability.
  */
 declare function normalizeUsage(usage: Usage): Usage;
 /**

package/dist/usage.d.ts

@@ -379,6 +379,9 @@ declare function formatUsage(programName: string, usage: Usage, options?: UsageF
  *    nested exclusive terms into their parent exclusive term to avoid
  *    redundant nesting. For example, an exclusive term containing another
  *    exclusive term will have its nested terms flattened into the parent.
+ *    Similarly, nested optional terms are collapsed:
+ *    `optional(optional(X))` becomes `optional(X)` when the outer optional
+ *    contains only a single inner optional term.
  *
  * 3. *Sorting*: Reorders terms to improve readability by placing:
  *    - Commands (subcommands) first
@@ -391,8 +394,8 @@ declare function formatUsage(programName: string, usage: Usage, options?: UsageF
  *
  * @param usage The usage description to normalize.
  * @returns A normalized usage description with degenerate terms removed,
- *          nested exclusive terms flattened, and remaining terms sorted for
- *          optimal readability.
+ *          nested exclusive and optional terms flattened, and remaining
+ *          terms sorted for optimal readability.
  */
 declare function normalizeUsage(usage: Usage): Usage;
 /**

package/dist/usage.js

@@ -239,6 +239,9 @@ function formatUsage(programName, usage, options = {}) {
 *    nested exclusive terms into their parent exclusive term to avoid
 *    redundant nesting. For example, an exclusive term containing another
 *    exclusive term will have its nested terms flattened into the parent.
+*    Similarly, nested optional terms are collapsed:
+*    `optional(optional(X))` becomes `optional(X)` when the outer optional
+*    contains only a single inner optional term.
 *
 * 3. *Sorting*: Reorders terms to improve readability by placing:
 *    - Commands (subcommands) first
@@ -251,8 +254,8 @@ function formatUsage(programName, usage, options = {}) {
 *
 * @param usage The usage description to normalize.
 * @returns A normalized usage description with degenerate terms removed,
-*          nested exclusive terms flattened, and remaining terms sorted for
-*          optimal readability.
+*          nested exclusive and optional terms flattened, and remaining
+*          terms sorted for optimal readability.
 */
 function normalizeUsage(usage) {
 	const terms = usage.map(normalizeUsageTerm).filter(isNonDegenerateTerm);
@@ -266,11 +269,14 @@ function normalizeUsage(usage) {
 	return terms;
 }
 function normalizeUsageTerm(term) {
-	if (term.type === "optional") return {
-		type: "optional",
-		terms: normalizeUsage(term.terms)
-	};
-	else if (term.type === "multiple") return {
+	if (term.type === "optional") {
+		const normalized = normalizeUsage(term.terms);
+		if (normalized.length === 1 && normalized[0].type === "optional") return normalized[0];
+		return {
+			type: "optional",
+			terms: normalized
+		};
+	} else if (term.type === "multiple") return {
 		type: "multiple",
 		terms: normalizeUsage(term.terms),
 		min: term.min

package/dist/validate.cjs

@@ -177,9 +177,25 @@ function validateLabel(label) {
 	if (/^\s+$/.test(label)) throw new TypeError(`Label must not be whitespace-only: "${escapeControlChars(label)}".`);
 	if (CONTROL_CHAR_RE.test(label)) throw new TypeError(`Label must not contain control characters: "${escapeControlChars(label)}".`);
 }
+/**
+* Validates that all source contexts have unique
+* {@link import("./context.ts").SourceContext.id | id} values.
+*
+* @param contexts The source contexts to validate.
+* @throws {TypeError} If two or more contexts share the same id.
+* @since 1.0.0
+*/
+function validateContextIds(contexts) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const context of contexts) {
+		if (seen.has(context.id)) throw new TypeError(`Duplicate SourceContext id: ${String(context.id)}`);
+		seen.add(context.id);
+	}
+}
 
 //#endregion
 exports.validateCommandNames = validateCommandNames;
+exports.validateContextIds = validateContextIds;
 exports.validateLabel = validateLabel;
 exports.validateMetaNameCollisions = validateMetaNameCollisions;
 exports.validateOptionNames = validateOptionNames;

package/dist/validate.js

@@ -176,6 +176,21 @@ function validateLabel(label) {
 	if (/^\s+$/.test(label)) throw new TypeError(`Label must not be whitespace-only: "${escapeControlChars(label)}".`);
 	if (CONTROL_CHAR_RE.test(label)) throw new TypeError(`Label must not contain control characters: "${escapeControlChars(label)}".`);
 }
+/**
+* Validates that all source contexts have unique
+* {@link import("./context.ts").SourceContext.id | id} values.
+*
+* @param contexts The source contexts to validate.
+* @throws {TypeError} If two or more contexts share the same id.
+* @since 1.0.0
+*/
+function validateContextIds(contexts) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const context of contexts) {
+		if (seen.has(context.id)) throw new TypeError(`Duplicate SourceContext id: ${String(context.id)}`);
+		seen.add(context.id);
+	}
+}
 
 //#endregion
-export { validateCommandNames, validateLabel, validateMetaNameCollisions, validateOptionNames, validateProgramName };
+export { validateCommandNames, validateContextIds, validateLabel, validateMetaNameCollisions, validateOptionNames, validateProgramName };

package/dist/valueparser.cjs

@@ -1161,8 +1161,8 @@ function ipv4(options) {
 		metavar,
 		placeholder: allowZero ? "0.0.0.0" : allowLoopback ? "127.0.0.1" : "192.0.2.1",
 		parse(input) {
-			const parts = input.split(".");
-			if (parts.length !== 4) {
+			const octets = parseIpv4Octets(input);
+			if (octets === null) {
 				const errorMsg = options?.errors?.invalidIpv4;
 				const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Expected a valid IPv4 address, but got ${input}.`;
 				return {
@@ -1170,51 +1170,6 @@ function ipv4(options) {
 					error: msg
 				};
 			}
-			const octets = [];
-			for (const part of parts) {
-				if (part.length === 0) {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				if (part.trim() !== part) {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				if (part.length > 1 && part[0] === "0") {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				if (!/^[0-9]+$/.test(part)) {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				const octet = Number(part);
-				if (!Number.isInteger(octet) || octet < 0 || octet > 255) {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				octets.push(octet);
-			}
 			const ipAddress = octets.join(".");
 			if (!allowPrivate && isPrivateIp(octets)) {
 				const errorMsg = options?.errors?.privateNotAllowed;
@@ -2855,6 +2810,33 @@ function ipv6(options) {
 	return ipv6ParserObj;
 }
 /**
+* Parses a dotted-decimal IPv4 string into four validated octets.
+* Returns null if the input is not a valid strict IPv4 address
+* (exactly four decimal octets 0–255, no leading zeros, no whitespace,
+* no non-decimal characters).
+*/
+function parseIpv4Octets(input) {
+	const parts = input.split(".");
+	if (parts.length !== 4) return null;
+	const octets = [
+		0,
+		0,
+		0,
+		0
+	];
+	for (let i = 0; i < 4; i++) {
+		const part = parts[i];
+		if (part.length === 0) return null;
+		if (part.trim() !== part) return null;
+		if (part.length > 1 && part[0] === "0") return null;
+		if (!/^[0-9]+$/.test(part)) return null;
+		const octet = Number(part);
+		if (!Number.isInteger(octet) || octet < 0 || octet > 255) return null;
+		octets[i] = octet;
+	}
+	return octets;
+}
+/**
 * Parses and normalizes an IPv6 address to canonical form.
 * Returns null if the input is not a valid IPv6 address.
 */
@@ -2864,10 +2846,8 @@ function parseAndNormalizeIpv6(input) {
 	if (ipv4MappedMatch) {
 		const ipv6Part = ipv4MappedMatch[1];
 		const ipv4Part = ipv4MappedMatch[2];
-		const ipv4Octets = ipv4Part.split(".");
-		if (ipv4Octets.length !== 4) return null;
-		const octets = ipv4Octets.map((o) => parseInt(o, 10));
-		if (octets.some((o) => isNaN(o) || o < 0 || o > 255)) return null;
+		const octets = parseIpv4Octets(ipv4Part);
+		if (octets === null) return null;
 		const group1 = octets[0] << 8 | octets[1];
 		const group2 = octets[2] << 8 | octets[3];
 		const fullAddress = `${ipv6Part}:${group1.toString(16)}:${group2.toString(16)}`;

package/dist/valueparser.js

@@ -1161,8 +1161,8 @@ function ipv4(options) {
 		metavar,
 		placeholder: allowZero ? "0.0.0.0" : allowLoopback ? "127.0.0.1" : "192.0.2.1",
 		parse(input) {
-			const parts = input.split(".");
-			if (parts.length !== 4) {
+			const octets = parseIpv4Octets(input);
+			if (octets === null) {
 				const errorMsg = options?.errors?.invalidIpv4;
 				const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Expected a valid IPv4 address, but got ${input}.`;
 				return {
@@ -1170,51 +1170,6 @@ function ipv4(options) {
 					error: msg
 				};
 			}
-			const octets = [];
-			for (const part of parts) {
-				if (part.length === 0) {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				if (part.trim() !== part) {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				if (part.length > 1 && part[0] === "0") {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				if (!/^[0-9]+$/.test(part)) {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				const octet = Number(part);
-				if (!Number.isInteger(octet) || octet < 0 || octet > 255) {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				octets.push(octet);
-			}
 			const ipAddress = octets.join(".");
 			if (!allowPrivate && isPrivateIp(octets)) {
 				const errorMsg = options?.errors?.privateNotAllowed;
@@ -2855,6 +2810,33 @@ function ipv6(options) {
 	return ipv6ParserObj;
 }
 /**
+* Parses a dotted-decimal IPv4 string into four validated octets.
+* Returns null if the input is not a valid strict IPv4 address
+* (exactly four decimal octets 0–255, no leading zeros, no whitespace,
+* no non-decimal characters).
+*/
+function parseIpv4Octets(input) {
+	const parts = input.split(".");
+	if (parts.length !== 4) return null;
+	const octets = [
+		0,
+		0,
+		0,
+		0
+	];
+	for (let i = 0; i < 4; i++) {
+		const part = parts[i];
+		if (part.length === 0) return null;
+		if (part.trim() !== part) return null;
+		if (part.length > 1 && part[0] === "0") return null;
+		if (!/^[0-9]+$/.test(part)) return null;
+		const octet = Number(part);
+		if (!Number.isInteger(octet) || octet < 0 || octet > 255) return null;
+		octets[i] = octet;
+	}
+	return octets;
+}
+/**
 * Parses and normalizes an IPv6 address to canonical form.
 * Returns null if the input is not a valid IPv6 address.
 */
@@ -2864,10 +2846,8 @@ function parseAndNormalizeIpv6(input) {
 	if (ipv4MappedMatch) {
 		const ipv6Part = ipv4MappedMatch[1];
 		const ipv4Part = ipv4MappedMatch[2];
-		const ipv4Octets = ipv4Part.split(".");
-		if (ipv4Octets.length !== 4) return null;
-		const octets = ipv4Octets.map((o) => parseInt(o, 10));
-		if (octets.some((o) => isNaN(o) || o < 0 || o > 255)) return null;
+		const octets = parseIpv4Octets(ipv4Part);
+		if (octets === null) return null;
 		const group1 = octets[0] << 8 | octets[1];
 		const group2 = octets[2] << 8 | octets[3];
 		const fullAddress = `${ipv6Part}:${group1.toString(16)}:${group2.toString(16)}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1555+118c402b",
+  "version": "1.0.0-dev.1565+dd141298",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",