@optique/core 1.3.0 → 1.3.2

package/dist/primitives.cjs

@@ -6,6 +6,7 @@ const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 const require_internal_dependency = require('./internal/dependency.cjs');
 const require_dependency_runtime = require('./dependency-runtime.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
+const require_passthrough = require('./internal/passthrough.cjs');
 const require_command_alias = require('./internal/command-alias.cjs');
 const require_execution_context = require('./execution-context.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
@@ -151,6 +152,7 @@ function constant(value) {
 			return { fragments: [] };
 		}
 	};
+	require_passthrough.defineKnownCompletion(result, (state) => require_annotation_state.normalizeInjectedAnnotationState(state));
 	Object.defineProperty(result, "placeholder", {
 		value,
 		configurable: true,
@@ -527,19 +529,17 @@ function option(...args) {
 			const prefixes = optionNames$1.filter((name) => name.startsWith("--") || name.startsWith("/") || name.startsWith("-") && name.length > 2).map((name) => name.startsWith("/") ? `${name}:` : `${name}=`);
 			for (const prefix of prefixes) {
 				if (!context.buffer[0].startsWith(prefix)) continue;
-				if (hasParsedOptionValue(context.state, valueParser)) {
-					const optionName$1 = prefix.slice(0, -1);
-					return {
-						success: false,
-						consumed: 1,
-						error: options.errors?.duplicate ? typeof options.errors.duplicate === "function" ? options.errors.duplicate(prefix) : options.errors.duplicate : require_message.message`${require_message.optionName(optionName$1)} cannot be used multiple times.`
-					};
-				}
+				const optionName$1 = prefix.slice(0, -1);
+				if (hasParsedOptionValue(context.state, valueParser)) return {
+					success: false,
+					consumed: 1,
+					error: options.errors?.duplicate ? typeof options.errors.duplicate === "function" ? options.errors.duplicate(prefix) : options.errors.duplicate : require_message.message`${require_message.optionName(optionName$1)} cannot be used multiple times.`
+				};
 				const rawInput = context.buffer[0].slice(prefix.length);
 				if (valueParser == null) return {
 					success: false,
 					consumed: 1,
-					error: options.errors?.unexpectedValue ? typeof options.errors.unexpectedValue === "function" ? options.errors.unexpectedValue(rawInput) : options.errors.unexpectedValue : require_message.message`Option ${require_message.optionName(prefix)} is a Boolean flag, but got a value: ${rawInput}.`
+					error: options.errors?.unexpectedValue ? typeof options.errors.unexpectedValue === "function" ? options.errors.unexpectedValue(rawInput) : options.errors.unexpectedValue : require_message.message`Option ${require_message.optionName(optionName$1)} is a Boolean flag, but got a value: ${rawInput}.`
 				};
 				return require_mode_dispatch.dispatchByMode(mode, () => {
 					const parseResult = syncValueParser.parse(rawInput);
@@ -592,10 +592,15 @@ function option(...args) {
 			}
 			const invalidOption = context.buffer[0];
 			if (options.errors?.noMatch) {
+				if (typeof options.errors.noMatch !== "function") return {
+					success: false,
+					consumed: 0,
+					error: options.errors.noMatch
+				};
 				const candidates = /* @__PURE__ */ new Set();
 				for (const name of require_usage.extractOptionNames(context.usage)) candidates.add(name);
 				const suggestions = require_suggestion.findSimilar(invalidOption, candidates, require_suggestion.DEFAULT_FIND_SIMILAR_OPTIONS);
-				const errorMessage = typeof options.errors.noMatch === "function" ? options.errors.noMatch(invalidOption, suggestions) : options.errors.noMatch;
+				const errorMessage = options.errors.noMatch(invalidOption, suggestions);
 				return {
 					success: false,
 					consumed: 0,
@@ -880,10 +885,15 @@ function flag(...args) {
 			}
 			const invalidOption = context.buffer[0];
 			if (options.errors?.noMatch) {
+				if (typeof options.errors.noMatch !== "function") return {
+					success: false,
+					consumed: 0,
+					error: options.errors.noMatch
+				};
 				const candidates = /* @__PURE__ */ new Set();
 				for (const name of require_usage.extractOptionNames(context.usage)) candidates.add(name);
 				const suggestions = require_suggestion.findSimilar(invalidOption, candidates, require_suggestion.DEFAULT_FIND_SIMILAR_OPTIONS);
-				const errorMessage = typeof options.errors.noMatch === "function" ? options.errors.noMatch(invalidOption, suggestions) : options.errors.noMatch;
+				const errorMessage = options.errors.noMatch(invalidOption, suggestions);
 				return {
 					success: false,
 					consumed: 0,
@@ -1192,7 +1202,7 @@ function argument(valueParser, options = {}) {
 	const syncValueParser = valueParser;
 	const dependencyMetadata = require_dependency_metadata.extractDependencyMetadata(valueParser);
 	const formatInvalidValueError = (error) => options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(error) : options.errors.invalidValue : require_message.message`${require_message.metavar(valueParser.metavar)}: ${error}`;
-	const optionPattern = /^--?[a-z0-9-]+$/i;
+	const optionPattern = /^(?!--=)(--?[a-z0-9-]+)(?:=|$)/i;
 	const term = {
 		type: "argument",
 		metavar: valueParser.metavar,
@@ -1219,14 +1229,15 @@ function argument(valueParser, options = {}) {
 			};
 			let i = 0;
 			let optionsTerminated = context.optionsTerminated;
-			if (!optionsTerminated) {
-				if (context.buffer[i] === "--") {
-					optionsTerminated = true;
-					i++;
-				} else if (context.buffer[i].match(optionPattern)) return {
+			if (!optionsTerminated) if (context.buffer[i] === "--") {
+				optionsTerminated = true;
+				i++;
+			} else {
+				const optionMatch = context.buffer[i].match(optionPattern);
+				if (optionMatch != null) return {
 					success: false,
 					consumed: i,
-					error: require_message.message`Expected an argument, but got an option: ${require_message.optionName(context.buffer[i])}.`
+					error: require_message.message`Expected an argument, but got an option: ${require_message.optionName(optionMatch[1])}.`
 				};
 			}
 			if (context.buffer.length < i + 1) return {
@@ -1736,6 +1747,22 @@ function command(name, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	require_passthrough.definePassThroughPriority(result, [parser], (state, token) => {
+		const active = normalizeCommandState(state);
+		if (active == null) return void 0;
+		const childState = active[0] === "matched" ? parser.initialState : active[1];
+		return require_passthrough.getPassThroughPriority(parser, getCommandParseChildState(state, childState, parser), token);
+	});
+	require_passthrough.defineOptionMatch(result, (state, token) => {
+		const active = normalizeCommandState(state);
+		if (active == null) return void 0;
+		const childState = active[0] === "matched" ? parser.initialState : active[1];
+		const match = require_passthrough.getOptionMatch(parser, getCommandParseChildState(state, childState, parser), token);
+		return match == null ? void 0 : {
+			...match,
+			continuesCommand: true
+		};
+	});
 	return require_modifiers.fluent(result);
 }
 /**
@@ -1809,6 +1836,8 @@ function passThrough(options = {}) {
 				consumed: 0,
 				error: require_message.message`No input to pass through.`
 			};
+			const failure = require_passthrough.getPassThroughFailure(context, this?.priority ?? -10);
+			if (failure != null) return failure.failure;
 			const token = context.buffer[0];
 			if (format === "greedy") {
 				const captured = [...context.buffer];
@@ -1920,6 +1949,11 @@ function passThrough(options = {}) {
 			return `passThrough(${format})`;
 		}
 	};
+	require_passthrough.definePassThroughPriority(result, [result], (_state, token) => {
+		if (token == null || format === "greedy") return result.priority;
+		const accepts = format === "equalsOnly" ? equalsOptionPattern.test(token) : format === "nextToken" && optionPattern.test(token);
+		return accepts ? result.priority : void 0;
+	});
 	return require_modifiers.fluent(result);
 }
 

package/dist/primitives.js

@@ -6,6 +6,7 @@ import { dispatchByMode, dispatchIterableByMode, wrapForMode } from "./internal/
 import { getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDerivedValueParser, suggestWithDependency } from "./internal/dependency.js";
 import { effectfulSchedulingNodesKey, exclusiveSourceScopeKey, includeSourceFailureChain, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, sourceCollectionExpansionKey } from "./dependency-runtime.js";
 import { getWrappedChildParseState, getWrappedChildState, isAnnotationWrappedInitialState, normalizeInjectedAnnotationState } from "./annotation-state.js";
+import { defineKnownCompletion, defineOptionMatch, definePassThroughPriority, getOptionMatch, getPassThroughFailure, getPassThroughPriority } from "./internal/passthrough.js";
 import { hiddenCommandAliasesKey } from "./internal/command-alias.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
 import { completeOrExtractPhase2Seed, extractPhase2SeedKey } from "./phase2-seed.js";
@@ -151,6 +152,7 @@ function constant(value) {
 			return { fragments: [] };
 		}
 	};
+	defineKnownCompletion(result, (state) => normalizeInjectedAnnotationState(state));
 	Object.defineProperty(result, "placeholder", {
 		value,
 		configurable: true,
@@ -527,19 +529,17 @@ function option(...args) {
 			const prefixes = optionNames$1.filter((name) => name.startsWith("--") || name.startsWith("/") || name.startsWith("-") && name.length > 2).map((name) => name.startsWith("/") ? `${name}:` : `${name}=`);
 			for (const prefix of prefixes) {
 				if (!context.buffer[0].startsWith(prefix)) continue;
-				if (hasParsedOptionValue(context.state, valueParser)) {
-					const optionName$1 = prefix.slice(0, -1);
-					return {
-						success: false,
-						consumed: 1,
-						error: options.errors?.duplicate ? typeof options.errors.duplicate === "function" ? options.errors.duplicate(prefix) : options.errors.duplicate : message`${optionName(optionName$1)} cannot be used multiple times.`
-					};
-				}
+				const optionName$1 = prefix.slice(0, -1);
+				if (hasParsedOptionValue(context.state, valueParser)) return {
+					success: false,
+					consumed: 1,
+					error: options.errors?.duplicate ? typeof options.errors.duplicate === "function" ? options.errors.duplicate(prefix) : options.errors.duplicate : message`${optionName(optionName$1)} cannot be used multiple times.`
+				};
 				const rawInput = context.buffer[0].slice(prefix.length);
 				if (valueParser == null) return {
 					success: false,
 					consumed: 1,
-					error: options.errors?.unexpectedValue ? typeof options.errors.unexpectedValue === "function" ? options.errors.unexpectedValue(rawInput) : options.errors.unexpectedValue : message`Option ${optionName(prefix)} is a Boolean flag, but got a value: ${rawInput}.`
+					error: options.errors?.unexpectedValue ? typeof options.errors.unexpectedValue === "function" ? options.errors.unexpectedValue(rawInput) : options.errors.unexpectedValue : message`Option ${optionName(optionName$1)} is a Boolean flag, but got a value: ${rawInput}.`
 				};
 				return dispatchByMode(mode, () => {
 					const parseResult = syncValueParser.parse(rawInput);
@@ -592,10 +592,15 @@ function option(...args) {
 			}
 			const invalidOption = context.buffer[0];
 			if (options.errors?.noMatch) {
+				if (typeof options.errors.noMatch !== "function") return {
+					success: false,
+					consumed: 0,
+					error: options.errors.noMatch
+				};
 				const candidates = /* @__PURE__ */ new Set();
 				for (const name of extractOptionNames(context.usage)) candidates.add(name);
 				const suggestions = findSimilar(invalidOption, candidates, DEFAULT_FIND_SIMILAR_OPTIONS);
-				const errorMessage = typeof options.errors.noMatch === "function" ? options.errors.noMatch(invalidOption, suggestions) : options.errors.noMatch;
+				const errorMessage = options.errors.noMatch(invalidOption, suggestions);
 				return {
 					success: false,
 					consumed: 0,
@@ -880,10 +885,15 @@ function flag(...args) {
 			}
 			const invalidOption = context.buffer[0];
 			if (options.errors?.noMatch) {
+				if (typeof options.errors.noMatch !== "function") return {
+					success: false,
+					consumed: 0,
+					error: options.errors.noMatch
+				};
 				const candidates = /* @__PURE__ */ new Set();
 				for (const name of extractOptionNames(context.usage)) candidates.add(name);
 				const suggestions = findSimilar(invalidOption, candidates, DEFAULT_FIND_SIMILAR_OPTIONS);
-				const errorMessage = typeof options.errors.noMatch === "function" ? options.errors.noMatch(invalidOption, suggestions) : options.errors.noMatch;
+				const errorMessage = options.errors.noMatch(invalidOption, suggestions);
 				return {
 					success: false,
 					consumed: 0,
@@ -1192,7 +1202,7 @@ function argument(valueParser, options = {}) {
 	const syncValueParser = valueParser;
 	const dependencyMetadata = extractDependencyMetadata(valueParser);
 	const formatInvalidValueError = (error) => options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(error) : options.errors.invalidValue : message`${metavar(valueParser.metavar)}: ${error}`;
-	const optionPattern = /^--?[a-z0-9-]+$/i;
+	const optionPattern = /^(?!--=)(--?[a-z0-9-]+)(?:=|$)/i;
 	const term = {
 		type: "argument",
 		metavar: valueParser.metavar,
@@ -1219,14 +1229,15 @@ function argument(valueParser, options = {}) {
 			};
 			let i = 0;
 			let optionsTerminated = context.optionsTerminated;
-			if (!optionsTerminated) {
-				if (context.buffer[i] === "--") {
-					optionsTerminated = true;
-					i++;
-				} else if (context.buffer[i].match(optionPattern)) return {
+			if (!optionsTerminated) if (context.buffer[i] === "--") {
+				optionsTerminated = true;
+				i++;
+			} else {
+				const optionMatch = context.buffer[i].match(optionPattern);
+				if (optionMatch != null) return {
 					success: false,
 					consumed: i,
-					error: message`Expected an argument, but got an option: ${optionName(context.buffer[i])}.`
+					error: message`Expected an argument, but got an option: ${optionName(optionMatch[1])}.`
 				};
 			}
 			if (context.buffer.length < i + 1) return {
@@ -1736,6 +1747,22 @@ function command(name, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	definePassThroughPriority(result, [parser], (state, token) => {
+		const active = normalizeCommandState(state);
+		if (active == null) return void 0;
+		const childState = active[0] === "matched" ? parser.initialState : active[1];
+		return getPassThroughPriority(parser, getCommandParseChildState(state, childState, parser), token);
+	});
+	defineOptionMatch(result, (state, token) => {
+		const active = normalizeCommandState(state);
+		if (active == null) return void 0;
+		const childState = active[0] === "matched" ? parser.initialState : active[1];
+		const match = getOptionMatch(parser, getCommandParseChildState(state, childState, parser), token);
+		return match == null ? void 0 : {
+			...match,
+			continuesCommand: true
+		};
+	});
 	return fluent(result);
 }
 /**
@@ -1809,6 +1836,8 @@ function passThrough(options = {}) {
 				consumed: 0,
 				error: message`No input to pass through.`
 			};
+			const failure = getPassThroughFailure(context, this?.priority ?? -10);
+			if (failure != null) return failure.failure;
 			const token = context.buffer[0];
 			if (format === "greedy") {
 				const captured = [...context.buffer];
@@ -1920,6 +1949,11 @@ function passThrough(options = {}) {
 			return `passThrough(${format})`;
 		}
 	};
+	definePassThroughPriority(result, [result], (_state, token) => {
+		if (token == null || format === "greedy") return result.priority;
+		const accepts = format === "equalsOnly" ? equalsOptionPattern.test(token) : format === "nextToken" && optionPattern.test(token);
+		return accepts ? result.priority : void 0;
+	});
 	return fluent(result);
 }
 

package/dist/suggestion.cjs

@@ -86,8 +86,10 @@ function findSimilar(input, candidates, options = {}) {
 		const normalizedCandidate = caseSensitive ? candidate : candidate.toLowerCase();
 		if (seen.has(candidate)) continue;
 		seen.add(candidate);
+		if (normalizedInput === normalizedCandidate) return [candidate];
+		const minimumDistance = Math.abs(normalizedInput.length - normalizedCandidate.length);
+		if (minimumDistance > maxDistance || minimumDistance / input.length > maxDistanceRatio) continue;
 		const distance = levenshteinDistance(normalizedInput, normalizedCandidate);
-		if (distance === 0) return [candidate];
 		const distanceRatio = distance / input.length;
 		if (distance <= maxDistance && distanceRatio <= maxDistanceRatio) matches.push({
 			candidate,

package/dist/suggestion.js

@@ -86,8 +86,10 @@ function findSimilar(input, candidates, options = {}) {
 		const normalizedCandidate = caseSensitive ? candidate : candidate.toLowerCase();
 		if (seen.has(candidate)) continue;
 		seen.add(candidate);
+		if (normalizedInput === normalizedCandidate) return [candidate];
+		const minimumDistance = Math.abs(normalizedInput.length - normalizedCandidate.length);
+		if (minimumDistance > maxDistance || minimumDistance / input.length > maxDistanceRatio) continue;
 		const distance = levenshteinDistance(normalizedInput, normalizedCandidate);
-		if (distance === 0) return [candidate];
 		const distanceRatio = distance / input.length;
 		if (distance <= maxDistance && distanceRatio <= maxDistanceRatio) matches.push({
 			candidate,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -237,7 +237,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.3.0",
+    "@optique/env": "1.3.2",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",