@optique/core 1.0.0-dev.1197 → 1.0.0-dev.1202

package/dist/facade.cjs

@@ -670,7 +670,7 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 	if (!shellName) {
 		stderr("Error: Missing shell name for completion.\n");
 		if (completionParser) {
-			const displayName = completionCommandDisplayName ?? "completion";
+			const displayName = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
 			const doc = require_parser.getDocPage(completionParser, [displayName]);
 			if (doc) stderr(require_doc.formatDocPage(programName, doc, {
 				colors,
@@ -869,13 +869,13 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 			if (equalsMatch) {
 				const shell = arg.slice(equalsMatch.length + 1);
 				const completionArgs = args.slice(i + 1);
-				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], true, sectionOrder);
+				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], true, sectionOrder);
 			}
 			const exactMatch = completionOptionNames.includes(arg);
 			if (exactMatch) {
 				const shell = i + 1 < args.length ? args[i + 1] : "";
 				const completionArgs = i + 1 < args.length ? args.slice(i + 2) : [];
-				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], true, sectionOrder);
+				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], true, sectionOrder);
 			}
 		}
 	}

package/dist/facade.js

@@ -670,7 +670,7 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 	if (!shellName) {
 		stderr("Error: Missing shell name for completion.\n");
 		if (completionParser) {
-			const displayName = completionCommandDisplayName ?? "completion";
+			const displayName = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
 			const doc = getDocPage(completionParser, [displayName]);
 			if (doc) stderr(formatDocPage(programName, doc, {
 				colors,
@@ -869,13 +869,13 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 			if (equalsMatch) {
 				const shell = arg.slice(equalsMatch.length + 1);
 				const completionArgs = args.slice(i + 1);
-				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], true, sectionOrder);
+				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], true, sectionOrder);
 			}
 			const exactMatch = completionOptionNames.includes(arg);
 			if (exactMatch) {
 				const shell = i + 1 < args.length ? args[i + 1] : "";
 				const completionArgs = i + 1 < args.length ? args.slice(i + 2) : [];
-				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], true, sectionOrder);
+				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], true, sectionOrder);
 			}
 		}
 	}

package/dist/program.cjs

@@ -34,7 +34,7 @@
 * // Program<"sync", { readonly name: string }>
 * ```
 *
-* @since 0.11.0
+* @since 1.0.0
 */
 function defineProgram(program) {
 	return program;

package/dist/program.d.cts

@@ -71,7 +71,7 @@ interface ProgramMetadata {
  * };
  * ```
  *
- * @since 0.11.0
+ * @since 1.0.0
  */
 interface Program<M extends Mode, T> {
   /**
@@ -117,7 +117,7 @@ interface Program<M extends Mode, T> {
  * // Program<"sync", { readonly name: string }>
  * ```
  *
- * @since 0.11.0
+ * @since 1.0.0
  */
 declare function defineProgram<M extends Mode, T>(program: Program<M, T>): Program<M, T>;
 //#endregion

package/dist/program.d.ts

@@ -71,7 +71,7 @@ interface ProgramMetadata {
  * };
  * ```
  *
- * @since 0.11.0
+ * @since 1.0.0
  */
 interface Program<M extends Mode, T> {
   /**
@@ -117,7 +117,7 @@ interface Program<M extends Mode, T> {
  * // Program<"sync", { readonly name: string }>
  * ```
  *
- * @since 0.11.0
+ * @since 1.0.0
  */
 declare function defineProgram<M extends Mode, T>(program: Program<M, T>): Program<M, T>;
 //#endregion

package/dist/program.js

@@ -33,7 +33,7 @@
 * // Program<"sync", { readonly name: string }>
 * ```
 *
-* @since 0.11.0
+* @since 1.0.0
 */
 function defineProgram(program) {
 	return program;

package/dist/valueparser.cjs

@@ -797,9 +797,14 @@ function locale(options = {}) {
 *
 * This parser validates that the input is a well-formed UUID string in the
 * standard format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` where each `x`
-* is a hexadecimal digit.  The parser can optionally restrict to specific
-* UUID versions.
+* is a hexadecimal digit.
 *
+* By default, the parser enforces strict [RFC 9562] validation: it requires
+* a standardized version digit (1 through 8) and the RFC 9562 variant bits
+* (`10xx`).  The nil and max UUIDs are accepted as special standard values.
+* Set `strict: false` to disable version and variant validation.
+*
+* [RFC 9562]: https://www.rfc-editor.org/rfc/rfc9562
 * @param options Configuration options for the UUID parser.
 * @returns A {@link ValueParser} that converts string input to {@link Uuid}
 *          strings.
@@ -808,9 +813,11 @@ function uuid(options = {}) {
 	const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 	const metavar = options.metavar ?? "UUID";
 	require_nonempty.ensureNonEmptyString(metavar);
+	const strict = options.strict !== false;
 	const allowedVersions = options.allowedVersions != null ? Object.freeze([...options.allowedVersions]) : null;
 	const invalidUuid = options.errors?.invalidUuid;
 	const disallowedVersion = options.errors?.disallowedVersion;
+	const invalidVariant = options.errors?.invalidVariant;
 	return {
 		$mode: "sync",
 		metavar,
@@ -819,9 +826,14 @@ function uuid(options = {}) {
 				success: false,
 				error: invalidUuid ? typeof invalidUuid === "function" ? invalidUuid(input) : invalidUuid : require_message.message`Expected a valid UUID in format ${"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}, but got ${input}.`
 			};
+			const lower = input.toLowerCase();
+			if (lower === "00000000-0000-0000-0000-000000000000" || lower === "ffffffff-ffff-ffff-ffff-ffffffffffff") return {
+				success: true,
+				value: input
+			};
+			const versionChar = input.charAt(14);
+			const version = parseInt(versionChar, 16);
 			if (allowedVersions != null && allowedVersions.length > 0) {
-				const versionChar = input.charAt(14);
-				const version = parseInt(versionChar, 16);
 				if (!allowedVersions.includes(version)) return {
 					success: false,
 					error: disallowedVersion ? typeof disallowedVersion === "function" ? disallowedVersion(version, allowedVersions) : disallowedVersion : (() => {
@@ -834,6 +846,25 @@ function uuid(options = {}) {
 						return require_message.message`Expected UUID version ${expectedVersions}, but got version ${version.toLocaleString("en")}.`;
 					})()
 				};
+			} else if (strict && (version < 1 || version > 8)) return {
+				success: false,
+				error: disallowedVersion ? typeof disallowedVersion === "function" ? disallowedVersion(version, [
+					1,
+					2,
+					3,
+					4,
+					5,
+					6,
+					7,
+					8
+				]) : disallowedVersion : require_message.message`Expected UUID version 1 through 8, but got version ${version.toLocaleString("en")}.`
+			};
+			if (strict) {
+				const variantChar = input.charAt(19).toLowerCase();
+				if (variantChar !== "8" && variantChar !== "9" && variantChar !== "a" && variantChar !== "b") return {
+					success: false,
+					error: invalidVariant ? typeof invalidVariant === "function" ? invalidVariant(input) : invalidVariant : require_message.message`Expected RFC 9562 variant (8, 9, a, or b at position 20), but got ${variantChar} in ${input}.`
+				};
 			}
 			return {
 				success: true,

package/dist/valueparser.d.cts

@@ -563,9 +563,33 @@ interface UuidOptions {
   /**
    * List of allowed UUID versions (e.g., `[4, 5]` for UUIDs version 4 and 5).
    * If specified, the parser will validate that the UUID matches one of the
-   * allowed versions. If not specified, any valid UUID format is accepted.
+   * allowed versions.  If not specified, the accepted versions depend on
+   * the {@link strict} option.
    */
   readonly allowedVersions?: readonly number[];
+  /**
+   * Whether to enforce strict [RFC 9562] validation.  When `true` (the
+   * default), the parser validates that the version digit is one of the
+   * currently standardized versions (1 through 8) and that the variant bits
+   * follow the RFC 9562 layout (`10xx`, i.e., hex digits `8`, `9`, `a`,
+   * or `b` at position 20 of the UUID string).
+   *
+   * The nil UUID (`00000000-0000-0000-0000-000000000000`) and max UUID
+   * (`ffffffff-ffff-ffff-ffff-ffffffffffff`) are accepted as special
+   * standard values regardless of this setting.
+   *
+   * When `false`, the parser only validates the UUID format without
+   * checking version or variant fields.
+   *
+   * When {@link allowedVersions} is provided, it takes precedence over the
+   * strict version check, but variant bit validation still applies if
+   * `strict` is `true`.
+   *
+   * [RFC 9562]: https://www.rfc-editor.org/rfc/rfc9562
+   * @default true
+   * @since 1.0.0
+   */
+  readonly strict?: boolean;
   /**
    * Custom error messages for UUID parsing failures.
    * @since 0.5.0
@@ -583,6 +607,12 @@ interface UuidOptions {
      * @since 0.5.0
      */
     disallowedVersion?: Message | ((version: number, allowedVersions: readonly number[]) => Message);
+    /**
+     * Custom error message when UUID variant bits are not RFC 9562 compliant.
+     * Can be a static message or a function that receives the input.
+     * @since 1.0.0
+     */
+    invalidVariant?: Message | ((input: string) => Message);
   };
 }
 /**
@@ -590,9 +620,14 @@ interface UuidOptions {
  *
  * This parser validates that the input is a well-formed UUID string in the
  * standard format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` where each `x`
- * is a hexadecimal digit.  The parser can optionally restrict to specific
- * UUID versions.
+ * is a hexadecimal digit.
+ *
+ * By default, the parser enforces strict [RFC 9562] validation: it requires
+ * a standardized version digit (1 through 8) and the RFC 9562 variant bits
+ * (`10xx`).  The nil and max UUIDs are accepted as special standard values.
+ * Set `strict: false` to disable version and variant validation.
  *
+ * [RFC 9562]: https://www.rfc-editor.org/rfc/rfc9562
  * @param options Configuration options for the UUID parser.
  * @returns A {@link ValueParser} that converts string input to {@link Uuid}
  *          strings.

package/dist/valueparser.d.ts

@@ -563,9 +563,33 @@ interface UuidOptions {
   /**
    * List of allowed UUID versions (e.g., `[4, 5]` for UUIDs version 4 and 5).
    * If specified, the parser will validate that the UUID matches one of the
-   * allowed versions. If not specified, any valid UUID format is accepted.
+   * allowed versions.  If not specified, the accepted versions depend on
+   * the {@link strict} option.
    */
   readonly allowedVersions?: readonly number[];
+  /**
+   * Whether to enforce strict [RFC 9562] validation.  When `true` (the
+   * default), the parser validates that the version digit is one of the
+   * currently standardized versions (1 through 8) and that the variant bits
+   * follow the RFC 9562 layout (`10xx`, i.e., hex digits `8`, `9`, `a`,
+   * or `b` at position 20 of the UUID string).
+   *
+   * The nil UUID (`00000000-0000-0000-0000-000000000000`) and max UUID
+   * (`ffffffff-ffff-ffff-ffff-ffffffffffff`) are accepted as special
+   * standard values regardless of this setting.
+   *
+   * When `false`, the parser only validates the UUID format without
+   * checking version or variant fields.
+   *
+   * When {@link allowedVersions} is provided, it takes precedence over the
+   * strict version check, but variant bit validation still applies if
+   * `strict` is `true`.
+   *
+   * [RFC 9562]: https://www.rfc-editor.org/rfc/rfc9562
+   * @default true
+   * @since 1.0.0
+   */
+  readonly strict?: boolean;
   /**
    * Custom error messages for UUID parsing failures.
    * @since 0.5.0
@@ -583,6 +607,12 @@ interface UuidOptions {
      * @since 0.5.0
      */
     disallowedVersion?: Message | ((version: number, allowedVersions: readonly number[]) => Message);
+    /**
+     * Custom error message when UUID variant bits are not RFC 9562 compliant.
+     * Can be a static message or a function that receives the input.
+     * @since 1.0.0
+     */
+    invalidVariant?: Message | ((input: string) => Message);
   };
 }
 /**
@@ -590,9 +620,14 @@ interface UuidOptions {
  *
  * This parser validates that the input is a well-formed UUID string in the
  * standard format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` where each `x`
- * is a hexadecimal digit.  The parser can optionally restrict to specific
- * UUID versions.
+ * is a hexadecimal digit.
+ *
+ * By default, the parser enforces strict [RFC 9562] validation: it requires
+ * a standardized version digit (1 through 8) and the RFC 9562 variant bits
+ * (`10xx`).  The nil and max UUIDs are accepted as special standard values.
+ * Set `strict: false` to disable version and variant validation.
  *
+ * [RFC 9562]: https://www.rfc-editor.org/rfc/rfc9562
  * @param options Configuration options for the UUID parser.
  * @returns A {@link ValueParser} that converts string input to {@link Uuid}
  *          strings.

package/dist/valueparser.js

@@ -797,9 +797,14 @@ function locale(options = {}) {
 *
 * This parser validates that the input is a well-formed UUID string in the
 * standard format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` where each `x`
-* is a hexadecimal digit.  The parser can optionally restrict to specific
-* UUID versions.
+* is a hexadecimal digit.
 *
+* By default, the parser enforces strict [RFC 9562] validation: it requires
+* a standardized version digit (1 through 8) and the RFC 9562 variant bits
+* (`10xx`).  The nil and max UUIDs are accepted as special standard values.
+* Set `strict: false` to disable version and variant validation.
+*
+* [RFC 9562]: https://www.rfc-editor.org/rfc/rfc9562
 * @param options Configuration options for the UUID parser.
 * @returns A {@link ValueParser} that converts string input to {@link Uuid}
 *          strings.
@@ -808,9 +813,11 @@ function uuid(options = {}) {
 	const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 	const metavar = options.metavar ?? "UUID";
 	ensureNonEmptyString(metavar);
+	const strict = options.strict !== false;
 	const allowedVersions = options.allowedVersions != null ? Object.freeze([...options.allowedVersions]) : null;
 	const invalidUuid = options.errors?.invalidUuid;
 	const disallowedVersion = options.errors?.disallowedVersion;
+	const invalidVariant = options.errors?.invalidVariant;
 	return {
 		$mode: "sync",
 		metavar,
@@ -819,9 +826,14 @@ function uuid(options = {}) {
 				success: false,
 				error: invalidUuid ? typeof invalidUuid === "function" ? invalidUuid(input) : invalidUuid : message`Expected a valid UUID in format ${"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}, but got ${input}.`
 			};
+			const lower = input.toLowerCase();
+			if (lower === "00000000-0000-0000-0000-000000000000" || lower === "ffffffff-ffff-ffff-ffff-ffffffffffff") return {
+				success: true,
+				value: input
+			};
+			const versionChar = input.charAt(14);
+			const version = parseInt(versionChar, 16);
 			if (allowedVersions != null && allowedVersions.length > 0) {
-				const versionChar = input.charAt(14);
-				const version = parseInt(versionChar, 16);
 				if (!allowedVersions.includes(version)) return {
 					success: false,
 					error: disallowedVersion ? typeof disallowedVersion === "function" ? disallowedVersion(version, allowedVersions) : disallowedVersion : (() => {
@@ -834,6 +846,25 @@ function uuid(options = {}) {
 						return message`Expected UUID version ${expectedVersions}, but got version ${version.toLocaleString("en")}.`;
 					})()
 				};
+			} else if (strict && (version < 1 || version > 8)) return {
+				success: false,
+				error: disallowedVersion ? typeof disallowedVersion === "function" ? disallowedVersion(version, [
+					1,
+					2,
+					3,
+					4,
+					5,
+					6,
+					7,
+					8
+				]) : disallowedVersion : message`Expected UUID version 1 through 8, but got version ${version.toLocaleString("en")}.`
+			};
+			if (strict) {
+				const variantChar = input.charAt(19).toLowerCase();
+				if (variantChar !== "8" && variantChar !== "9" && variantChar !== "a" && variantChar !== "b") return {
+					success: false,
+					error: invalidVariant ? typeof invalidVariant === "function" ? invalidVariant(input) : invalidVariant : message`Expected RFC 9562 variant (8, 9, a, or b at position 20), but got ${variantChar} in ${input}.`
+				};
 			}
 			return {
 				success: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1197+8fa87a88",
+  "version": "1.0.0-dev.1202+34b3b6f1",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",