@optique/core 0.10.0-dev.342 → 0.10.0-dev.343

package/dist/facade.cjs

@@ -660,6 +660,43 @@ function indentLines(text$1, indent) {
 	return text$1.split("\n").join("\n" + " ".repeat(indent));
 }
 /**
+* Checks if the arguments contain help, version, or completion requests
+* that should be handled immediately without context processing.
+*
+* This enables early exit optimization: when users request help, version,
+* or completion, we skip annotation collection and context processing
+* entirely, delegating directly to runParser().
+*
+* @param args Command-line arguments to check.
+* @param options Run options containing help/version/completion configuration.
+* @returns `true` if early exit should be performed, `false` otherwise.
+*/
+function needsEarlyExit(args, options) {
+	if (options.help) {
+		const helpMode = options.help.mode ?? "option";
+		if ((helpMode === "option" || helpMode === "both") && args.includes("--help")) return true;
+		if ((helpMode === "command" || helpMode === "both") && args[0] === "help") return true;
+	}
+	if (options.version) {
+		const versionMode = options.version.mode ?? "option";
+		if ((versionMode === "option" || versionMode === "both") && args.includes("--version")) return true;
+		if ((versionMode === "command" || versionMode === "both") && args[0] === "version") return true;
+	}
+	if (options.completion) {
+		const completionMode = options.completion.mode ?? "both";
+		const completionName = options.completion.name ?? "both";
+		if (completionMode === "command" || completionMode === "both") {
+			if ((completionName === "singular" || completionName === "both") && args[0] === "completion") return true;
+			if ((completionName === "plural" || completionName === "both") && args[0] === "completions") return true;
+		}
+		if (completionMode === "option" || completionMode === "both") for (const arg of args) {
+			if ((completionName === "singular" || completionName === "both") && (arg === "--completion" || arg.startsWith("--completion="))) return true;
+			if ((completionName === "plural" || completionName === "both") && (arg === "--completions" || arg.startsWith("--completions="))) return true;
+		}
+	}
+	return false;
+}
+/**
 * Merges multiple annotation objects, with earlier contexts having priority.
 *
 * When the same symbol key exists in multiple annotations, the value from
@@ -779,6 +816,10 @@ function hasDynamicContexts(contexts) {
 */
 async function runWith(parser, programName, contexts, options) {
 	const args = options?.args ?? [];
+	if (needsEarlyExit(args, options)) {
+		if (parser.$mode === "async") return runParser(parser, programName, args, options);
+		return Promise.resolve(runParser(parser, programName, args, options));
+	}
 	if (contexts.length === 0) {
 		if (parser.$mode === "async") return runParser(parser, programName, args, options);
 		return Promise.resolve(runParser(parser, programName, args, options));
@@ -834,6 +875,7 @@ async function runWith(parser, programName, contexts, options) {
 */
 function runWithSync(parser, programName, contexts, options) {
 	const args = options?.args ?? [];
+	if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 	if (contexts.length === 0) return runParser(parser, programName, args, options);
 	const phase1Annotations = collectAnnotationsSync(contexts);
 	const needsTwoPhase = hasDynamicContexts(contexts);

package/dist/facade.js

@@ -660,6 +660,43 @@ function indentLines(text$1, indent) {
 	return text$1.split("\n").join("\n" + " ".repeat(indent));
 }
 /**
+* Checks if the arguments contain help, version, or completion requests
+* that should be handled immediately without context processing.
+*
+* This enables early exit optimization: when users request help, version,
+* or completion, we skip annotation collection and context processing
+* entirely, delegating directly to runParser().
+*
+* @param args Command-line arguments to check.
+* @param options Run options containing help/version/completion configuration.
+* @returns `true` if early exit should be performed, `false` otherwise.
+*/
+function needsEarlyExit(args, options) {
+	if (options.help) {
+		const helpMode = options.help.mode ?? "option";
+		if ((helpMode === "option" || helpMode === "both") && args.includes("--help")) return true;
+		if ((helpMode === "command" || helpMode === "both") && args[0] === "help") return true;
+	}
+	if (options.version) {
+		const versionMode = options.version.mode ?? "option";
+		if ((versionMode === "option" || versionMode === "both") && args.includes("--version")) return true;
+		if ((versionMode === "command" || versionMode === "both") && args[0] === "version") return true;
+	}
+	if (options.completion) {
+		const completionMode = options.completion.mode ?? "both";
+		const completionName = options.completion.name ?? "both";
+		if (completionMode === "command" || completionMode === "both") {
+			if ((completionName === "singular" || completionName === "both") && args[0] === "completion") return true;
+			if ((completionName === "plural" || completionName === "both") && args[0] === "completions") return true;
+		}
+		if (completionMode === "option" || completionMode === "both") for (const arg of args) {
+			if ((completionName === "singular" || completionName === "both") && (arg === "--completion" || arg.startsWith("--completion="))) return true;
+			if ((completionName === "plural" || completionName === "both") && (arg === "--completions" || arg.startsWith("--completions="))) return true;
+		}
+	}
+	return false;
+}
+/**
 * Merges multiple annotation objects, with earlier contexts having priority.
 *
 * When the same symbol key exists in multiple annotations, the value from
@@ -779,6 +816,10 @@ function hasDynamicContexts(contexts) {
 */
 async function runWith(parser, programName, contexts, options) {
 	const args = options?.args ?? [];
+	if (needsEarlyExit(args, options)) {
+		if (parser.$mode === "async") return runParser(parser, programName, args, options);
+		return Promise.resolve(runParser(parser, programName, args, options));
+	}
 	if (contexts.length === 0) {
 		if (parser.$mode === "async") return runParser(parser, programName, args, options);
 		return Promise.resolve(runParser(parser, programName, args, options));
@@ -834,6 +875,7 @@ async function runWith(parser, programName, contexts, options) {
 */
 function runWithSync(parser, programName, contexts, options) {
 	const args = options?.args ?? [];
+	if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 	if (contexts.length === 0) return runParser(parser, programName, args, options);
 	const phase1Annotations = collectAnnotationsSync(contexts);
 	const needsTwoPhase = hasDynamicContexts(contexts);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.10.0-dev.342+b6648cfd",
+  "version": "0.10.0-dev.343+2ef903e6",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",