@optique/core 1.0.0-dev.1903 → 1.0.0-dev.1972

package/dist/modifiers.js

@@ -1,47 +1,13 @@
-import { annotateFreshArray, annotationKey, getAnnotations, inheritAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
+import { annotateFreshArray, annotationKey, getAnnotations, inheritAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./internal/annotations.js";
 import { formatMessage, message, text } from "./message.js";
-import { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode } from "./mode-dispatch.js";
-import { composeDependencyMetadata } from "./dependency-metadata.js";
-import { completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult } from "./phase2-seed.js";
-import { defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, unmatchedNonCliDependencySourceStateMarker } from "./parser.js";
+import { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode } from "./internal/mode-dispatch.js";
+import { defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { getDelegatedAnnotationState, hasDelegatedAnnotationCarrier, isAnnotationWrappedInitialState, normalizeDelegatedAnnotationState, normalizeNestedDelegatedAnnotationState } from "./annotation-state.js";
+import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
+import { completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult } from "./phase2-seed.js";
+import { composeDependencyMetadata } from "./dependency-metadata.js";
 
 //#region src/modifiers.ts
-function withChildExecPath(exec, segment) {
-	if (exec == null) return void 0;
-	return {
-		...exec,
-		path: [...exec.path ?? [], segment]
-	};
-}
-function mergeChildExec(parent, child) {
-	if (parent == null) return child;
-	if (child == null) return parent;
-	return {
-		...parent,
-		trace: child.trace ?? parent.trace,
-		dependencyRuntime: child.dependencyRuntime ?? parent.dependencyRuntime,
-		dependencyRegistry: child.dependencyRegistry ?? parent.dependencyRegistry,
-		commandPath: child.commandPath ?? parent.commandPath,
-		preCompletedByParser: child.preCompletedByParser ?? parent.preCompletedByParser,
-		excludedSourceFields: child.excludedSourceFields ?? parent.excludedSourceFields
-	};
-}
-function withChildContext(context, segment, state) {
-	const exec = withChildExecPath(context.exec, segment);
-	const dependencyRegistry = context.dependencyRegistry ?? exec?.dependencyRegistry;
-	return {
-		...context,
-		state,
-		...exec != null ? {
-			exec: dependencyRegistry === exec.dependencyRegistry ? exec : {
-				...exec,
-				dependencyRegistry
-			},
-			dependencyRegistry
-		} : {}
-	};
-}
 function isTerminalMultipleItemState(state) {
 	const unwrapped = unwrapMultipleItemState(state).value;
 	return unwrapped != null && typeof unwrapped === "object" && Object.hasOwn(unwrapped, "success") && typeof unwrapped.success === "boolean";
@@ -88,6 +54,9 @@ function normalizeOptionalLikeCompleteResult(result, shouldNormalize) {
 		value: normalizeNestedDelegatedAnnotationState(result.value)
 	} : result;
 }
+function shouldRetryOptionalLikeCompatibilityError(error, state) {
+	return error instanceof TypeError && state != null && typeof state === "object" && isInjectedAnnotationWrapper(state);
+}
 function completeOptionalLikeSync(parser, state, exec) {
 	const hasCarrier = hasDelegatedAnnotationCarrier(state);
 	const shouldRetryFalseResult = hasCarrier && isAnnotationWrappedInitialState(state);
@@ -97,7 +66,7 @@ function completeOptionalLikeSync(parser, state, exec) {
 		if (!result.success && shouldRetryFalseResult) return run(normalizeDelegatedAnnotationState(state), false);
 		return result;
 	} catch (error) {
-		if (!hasCarrier) throw error;
+		if (!shouldRetryOptionalLikeCompatibilityError(error, state)) throw error;
 		return run(normalizeDelegatedAnnotationState(state), false);
 	}
 }
@@ -110,7 +79,7 @@ async function completeOptionalLikeAsync(parser, state, exec) {
 		if (!result.success && shouldRetryFalseResult) return await run(normalizeDelegatedAnnotationState(state), false);
 		return result;
 	} catch (error) {
-		if (!hasCarrier) throw error;
+		if (!shouldRetryOptionalLikeCompatibilityError(error, state)) throw error;
 		return await run(normalizeDelegatedAnnotationState(state), false);
 	}
 }
@@ -121,11 +90,11 @@ function normalizeOptionalLikePhase2Seed(seed, shouldNormalize) {
 	} : seed;
 }
 function extractOptionalLikePhase2Seed(parser, state, exec) {
-	if (!Array.isArray(state) && !(state != null && typeof state === "object")) return wrapForMode(parser.$mode, null);
+	if (!Array.isArray(state) && !(state != null && typeof state === "object")) return wrapForMode(parser.mode, null);
 	const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
 	const hasCarrier = hasDelegatedAnnotationCarrier(innerState);
 	const shouldRetryFalseResult = hasCarrier && isAnnotationWrappedInitialState(innerState);
-	return dispatchByMode(parser.$mode, () => {
+	return dispatchByMode(parser.mode, () => {
 		try {
 			const result = parser.complete(innerState, exec);
 			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result), hasCarrier);
@@ -141,7 +110,7 @@ function extractOptionalLikePhase2Seed(parser, state, exec) {
 			}
 			return normalizeOptionalLikePhase2Seed(seed, hasCarrier);
 		} catch (error) {
-			if (!hasCarrier) throw error;
+			if (!shouldRetryOptionalLikeCompatibilityError(error, innerState)) throw error;
 			const fallbackState = normalizeDelegatedAnnotationState(innerState);
 			const result = parser.complete(fallbackState, exec);
 			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result), false);
@@ -163,7 +132,7 @@ function extractOptionalLikePhase2Seed(parser, state, exec) {
 			}
 			return normalizeOptionalLikePhase2Seed(seed, hasCarrier);
 		} catch (error) {
-			if (!hasCarrier) throw error;
+			if (!shouldRetryOptionalLikeCompatibilityError(error, innerState)) throw error;
 			const fallbackState = normalizeDelegatedAnnotationState(innerState);
 			const result = await parser.complete(fallbackState, exec);
 			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result), false);
@@ -187,12 +156,12 @@ function extractOptionalLikePhase2Seed(parser, state, exec) {
 function deriveOptionalInnerParseState(outerState, parser) {
 	if (Array.isArray(outerState)) {
 		const innerState = outerState[0];
-		if (getAnnotations(outerState) != null && innerState != null && typeof innerState === "object") return inheritAnnotations(outerState, innerState);
+		if (getAnnotations(outerState) != null && innerState != null && typeof innerState === "object") return getDelegatedAnnotationState(outerState, innerState);
 		return innerState;
 	}
 	const initial = parser.initialState;
 	if (initial != null && typeof initial !== "object") return initial;
-	return inheritAnnotations(outerState, initial);
+	return initial != null && typeof initial === "object" ? getDelegatedAnnotationState(outerState, initial) : inheritAnnotations(outerState, initial);
 }
 /**
 * Internal helper for optional-style parsing logic shared by optional()
@@ -226,9 +195,12 @@ async function parseOptionalStyleAsync(context, parser) {
 * Internal helper to process optional-style parse results.
 * @internal
 */
+function hasOptionalLikeParseStateChanged(previousState, nextState) {
+	return previousState !== nextState && normalizeDelegatedAnnotationState(previousState) !== normalizeDelegatedAnnotationState(nextState);
+}
 function processOptionalStyleResult(result, innerState, context) {
 	if (result.success) {
-		if (result.next.state !== innerState || result.consumed.length === 0) return {
+		if (hasOptionalLikeParseStateChanged(innerState, result.next.state) || result.consumed.length === 0) return {
 			success: true,
 			...result.provisional ? { provisional: true } : {},
 			next: {
@@ -277,7 +249,7 @@ function adaptShouldDeferCompletion(innerCheck, parser) {
 				if (!result && shouldRetryFalseResult) return innerCheck(normalizeDelegatedAnnotationState(innerState), exec);
 				return result;
 			} catch (error) {
-				if (!hasCarrier) throw error;
+				if (!shouldRetryOptionalLikeCompatibilityError(error, innerState)) throw error;
 				return innerCheck(normalizeDelegatedAnnotationState(innerState), exec);
 			}
 		}
@@ -335,7 +307,7 @@ function optional(parser) {
 		for await (const s of suggestions) yield s;
 	}
 	const optionalParser = {
-		$mode: parser.$mode,
+		mode: parser.mode,
 		$valueType: [],
 		$stateType: [],
 		...parser[unmatchedNonCliDependencySourceStateMarker] === true ? { [unmatchedNonCliDependencySourceStateMarker]: true } : {},
@@ -366,13 +338,13 @@ function optional(parser) {
 			return extractOptionalLikePhase2Seed(parser, state, exec);
 		},
 		parse(context) {
-			return dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
+			return dispatchByMode(parser.mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
 		complete(state, exec) {
 			if (!Array.isArray(state)) {
 				const delegateToInner = (resolvedInnerState) => {
-					const innerResult = dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, resolvedInnerState, exec), async () => await completeOptionalLikeAsync(parser, resolvedInnerState, exec));
-					return mapModeValue(parser.$mode, innerResult, (result) => result.success ? result : {
+					const innerResult = dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, resolvedInnerState, exec), async () => await completeOptionalLikeAsync(parser, resolvedInnerState, exec));
+					return mapModeValue(parser.mode, innerResult, (result) => result.success ? result : {
 						success: true,
 						value: void 0
 					});
@@ -384,7 +356,7 @@ function optional(parser) {
 				const sourceMetadata = parser.dependencyMetadata?.source;
 				if (sourceMetadata?.preservesSourceValue !== false && sourceMetadata?.getMissingSourceValue != null) {
 					const delegatedState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
-					return dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, delegatedState, exec), async () => await completeOptionalLikeAsync(parser, delegatedState, exec));
+					return dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, delegatedState, exec), async () => await completeOptionalLikeAsync(parser, delegatedState, exec));
 				}
 				if (parser[unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object") {
 					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
@@ -396,10 +368,10 @@ function optional(parser) {
 				};
 			}
 			const innerElement = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
-			return dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, innerElement, exec), async () => await completeOptionalLikeAsync(parser, innerElement, exec));
+			return dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, innerElement, exec), async () => await completeOptionalLikeAsync(parser, innerElement, exec));
 		},
 		suggest(context, prefix) {
-			return dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
+			return dispatchIterableByMode(parser.mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
 		},
 		getDocFragments(state, defaultValue) {
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
@@ -424,7 +396,7 @@ function optional(parser) {
 		const innerValidate = parser.validateValue.bind(parser);
 		Object.defineProperty(optionalParser, "validateValue", {
 			value(v) {
-				if (v === void 0) return wrapForMode(parser.$mode, {
+				if (v === void 0) return wrapForMode(parser.mode, {
 					success: true,
 					value: v
 				});
@@ -504,7 +476,7 @@ function withDefault(parser, defaultValue, options) {
 		for await (const s of suggestions) yield s;
 	}
 	const withDefaultParser = {
-		$mode: parser.$mode,
+		mode: parser.mode,
 		$valueType: [],
 		$stateType: [],
 		...parser[unmatchedNonCliDependencySourceStateMarker] === true ? { [unmatchedNonCliDependencySourceStateMarker]: true } : {},
@@ -534,7 +506,7 @@ function withDefault(parser, defaultValue, options) {
 			return extractOptionalLikePhase2Seed(parser, state, exec);
 		},
 		parse(context) {
-			return dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
+			return dispatchByMode(parser.mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
 		complete(state, exec) {
 			function evaluateDefault() {
@@ -547,12 +519,12 @@ function withDefault(parser, defaultValue, options) {
 			if (!Array.isArray(state)) {
 				if (typeof parser.shouldDeferCompletion === "function" && state != null && typeof state === "object") {
 					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
-					const innerResult = dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, innerState, exec), async () => await completeOptionalLikeAsync(parser, innerState, exec));
+					const innerResult = dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, innerState, exec), async () => await completeOptionalLikeAsync(parser, innerState, exec));
 					return innerResult;
 				}
 				if (parser[unmatchedNonCliDependencySourceStateMarker] === true && state != null && typeof state === "object") {
 					const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
-					const innerResult = dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, innerState, exec), async () => await completeOptionalLikeAsync(parser, innerState, exec));
+					const innerResult = dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, innerState, exec), async () => await completeOptionalLikeAsync(parser, innerState, exec));
 					const handleInnerResult = (result) => {
 						if (result.success && result.value !== void 0) return result;
 						try {
@@ -567,7 +539,7 @@ function withDefault(parser, defaultValue, options) {
 							};
 						}
 					};
-					return mapModeValue(parser.$mode, innerResult, handleInnerResult);
+					return mapModeValue(parser.mode, innerResult, handleInnerResult);
 				}
 				try {
 					const value = evaluateDefault();
@@ -583,10 +555,10 @@ function withDefault(parser, defaultValue, options) {
 				}
 			}
 			const innerElement = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
-			return dispatchByMode(parser.$mode, () => completeOptionalLikeSync(syncParser, innerElement, exec), async () => await completeOptionalLikeAsync(parser, innerElement, exec));
+			return dispatchByMode(parser.mode, () => completeOptionalLikeSync(syncParser, innerElement, exec), async () => await completeOptionalLikeAsync(parser, innerElement, exec));
 		},
 		suggest(context, prefix) {
-			return dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
+			return dispatchIterableByMode(parser.mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
 		},
 		getDocFragments(state, upperDefaultValue) {
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
@@ -748,7 +720,7 @@ function withDefault(parser, defaultValue, options) {
 */
 function map(parser, transform) {
 	const complete = (state, exec) => {
-		return mapModeValue(parser.$mode, parser.complete(state, exec), (result) => {
+		return mapModeValue(parser.mode, parser.complete(state, exec), (result) => {
 			if (!result.success) return result;
 			if (result.deferred) try {
 				return {
@@ -774,7 +746,7 @@ function map(parser, transform) {
 		$valueType: [],
 		complete,
 		[extractPhase2SeedKey](state, exec) {
-			return mapModeValue(parser.$mode, completeOrExtractPhase2Seed(parser, state, exec), (seed) => {
+			return mapModeValue(parser.mode, completeOrExtractPhase2Seed(parser, state, exec), (seed) => {
 				if (seed == null) return null;
 				if (seed.deferred) try {
 					return {
@@ -1115,7 +1087,7 @@ function multiple(parser, options = {}) {
 		};
 	};
 	const resultParser = {
-		$mode: parser.$mode,
+		mode: parser.mode,
 		$valueType: [],
 		$stateType: [],
 		priority: parser.priority,
@@ -1136,10 +1108,10 @@ function multiple(parser, options = {}) {
 			}, ...innerNodes] : innerNodes;
 		},
 		parse(context) {
-			return dispatchByMode(parser.$mode, () => parseSync(context), () => parseAsync(context));
+			return dispatchByMode(parser.mode, () => parseSync(context), () => parseAsync(context));
 		},
 		complete(state, exec) {
-			return dispatchByMode(parser.$mode, () => {
+			return dispatchByMode(parser.mode, () => {
 				const result = [];
 				const deferredIndices = /* @__PURE__ */ new Map();
 				let hasDeferred = false;
@@ -1178,7 +1150,7 @@ function multiple(parser, options = {}) {
 			});
 		},
 		[extractPhase2SeedKey](state, exec) {
-			return dispatchByMode(parser.$mode, () => {
+			return dispatchByMode(parser.mode, () => {
 				const values = [];
 				const deferredIndices = /* @__PURE__ */ new Map();
 				let hasDeferred = false;
@@ -1228,7 +1200,7 @@ function multiple(parser, options = {}) {
 			const currentItemState = context.state.at(-1);
 			const canExtendCurrent = currentItemState != null && !isTerminalMultipleItemState(currentItemState);
 			const canOpenNew = context.state.length < max;
-			if (!canExtendCurrent && !canOpenNew) return dispatchIterableByMode(parser.$mode, function* () {}, async function* () {});
+			if (!canExtendCurrent && !canOpenNew) return dispatchIterableByMode(parser.mode, function* () {}, async function* () {});
 			const itemIndex = canExtendCurrent ? context.state.length - 1 : context.state.length;
 			const suggestInitialState = canExtendCurrent ? currentItemState : inheritAnnotations(context.state, parser.initialState);
 			const suggestFallbackState = unwrapInjectedWrapper(suggestInitialState);
@@ -1271,7 +1243,7 @@ function multiple(parser, options = {}) {
 					description
 				]);
 			};
-			return dispatchIterableByMode(parser.$mode, function* () {
+			return dispatchIterableByMode(parser.mode, function* () {
 				const selectedValues = collectSelectedValuesSync();
 				const emitted = /* @__PURE__ */ new Set();
 				const yieldUnique = function* (suggestions) {
@@ -1404,15 +1376,15 @@ function multiple(parser, options = {}) {
 			value(values) {
 				if (!Array.isArray(values)) {
 					const actualType = values === null ? "null" : typeof values;
-					return wrapForMode(parser.$mode, {
+					return wrapForMode(parser.mode, {
 						success: false,
 						error: message`Expected an array of values, but received ${actualType}.`
 					});
 				}
 				const arity = validateArity(values);
-				if (!arity.success) return wrapForMode(parser.$mode, arity);
-				if (innerValidate == null) return wrapForMode(parser.$mode, arity);
-				return dispatchByMode(parser.$mode, () => {
+				if (!arity.success) return wrapForMode(parser.mode, arity);
+				if (innerValidate == null) return wrapForMode(parser.mode, arity);
+				return dispatchByMode(parser.mode, () => {
 					let changed = false;
 					const normalized = [];
 					for (const v of values) {
@@ -1530,7 +1502,7 @@ function nonEmpty(parser) {
 		return processNonEmptyResult(result);
 	};
 	const nonEmptyParser = {
-		$mode: parser.$mode,
+		mode: parser.mode,
 		$valueType: parser.$valueType,
 		$stateType: parser.$stateType,
 		priority: parser.priority,
@@ -1547,7 +1519,7 @@ function nonEmpty(parser) {
 			}] : []);
 		},
 		parse(context) {
-			return dispatchByMode(parser.$mode, () => parseSync(context), () => parseAsync(context));
+			return dispatchByMode(parser.mode, () => parseSync(context), () => parseAsync(context));
 		},
 		complete(state, exec) {
 			return parser.complete(state, exec);