@optique/core 0.10.7 → 1.0.0-dev.1109

package/dist/modifiers.cjs

@@ -1,6 +1,8 @@
+const require_annotations = require('./annotations.cjs');
 const require_message = require('./message.cjs');
 const require_dependency = require('./dependency.cjs');
 const require_mode_dispatch = require('./mode-dispatch.cjs');
+const require_context = require('./context.cjs');
 
 //#region src/modifiers.ts
 /**
@@ -12,7 +14,7 @@ const require_mode_dispatch = require('./mode-dispatch.cjs');
 * @internal
 */
 function parseOptionalStyleSync(context, parser) {
-	const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
+	const innerState = Array.isArray(context.state) ? context.state[0] : parser.initialState;
 	const result = parser.parse({
 		...context,
 		state: innerState
@@ -24,7 +26,7 @@ function parseOptionalStyleSync(context, parser) {
 * @internal
 */
 async function parseOptionalStyleAsync(context, parser) {
-	const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
+	const innerState = Array.isArray(context.state) ? context.state[0] : parser.initialState;
 	const result = await parser.parse({
 		...context,
 		state: innerState
@@ -62,6 +64,28 @@ function processOptionalStyleResult(result, innerState, context) {
 	return result;
 }
 /**
+* Creates a `shouldDeferCompletion` adapter that unwraps the outer state
+* shape (`[TState] | undefined`) used by {@link optional} and
+* {@link withDefault} before delegating to the inner parser's hook.
+*
+* When state is an array, the adapter unwraps `state[0]` and propagates
+* annotations from the outer array.  Non-array objects (e.g., PromptBindState
+* from `prompt()`) are passed through directly.  `undefined` returns `false`
+* without calling the inner hook.
+*
+* @internal
+*/
+function adaptShouldDeferCompletion(innerCheck) {
+	return (state) => {
+		if (Array.isArray(state)) {
+			const inner = require_annotations.getAnnotations(state) != null && state[0] != null && typeof state[0] === "object" ? require_annotations.inheritAnnotations(state, state[0]) : state[0];
+			return innerCheck(inner);
+		}
+		if (state != null && typeof state === "object") return innerCheck(state);
+		return false;
+	};
+}
+/**
 * Creates a parser that makes another parser optional, allowing it to succeed
 * without consuming input if the wrapped parser fails to match.
 * If the wrapped parser succeeds, this returns its value.
@@ -76,14 +100,14 @@ function processOptionalStyleResult(result, innerState, context) {
 function optional(parser) {
 	const syncParser = parser;
 	function* suggestSync(context, prefix) {
-		const innerState = typeof context.state === "undefined" ? syncParser.initialState : context.state[0];
+		const innerState = Array.isArray(context.state) ? context.state[0] : syncParser.initialState;
 		yield* syncParser.suggest({
 			...context,
 			state: innerState
 		}, prefix);
 	}
 	async function* suggestAsync(context, prefix) {
-		const innerState = typeof context.state === "undefined" ? syncParser.initialState : context.state[0];
+		const innerState = Array.isArray(context.state) ? context.state[0] : syncParser.initialState;
 		const suggestions = parser.suggest({
 			...context,
 			state: innerState
@@ -106,12 +130,23 @@ function optional(parser) {
 		}],
 		initialState: void 0,
 		...wrappedDependencyMarker,
+		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser)) } : {},
 		parse(context) {
 			return require_mode_dispatch.dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
 		complete(state) {
-			if (typeof state === "undefined") {
+			if (!Array.isArray(state)) {
 				if (innerHasWrappedDependency && wrappedPendingState) return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete([wrappedPendingState]), () => parser.complete([wrappedPendingState]));
+				if (typeof parser.shouldDeferCompletion === "function" && state != null && typeof state === "object") {
+					const innerComplete = () => {
+						const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(state), () => parser.complete(state));
+						return require_mode_dispatch.mapModeValue(parser.$mode, innerResult, (result) => result.success ? result : {
+							success: true,
+							value: void 0
+						});
+					};
+					return innerComplete();
+				}
 				return {
 					success: true,
 					value: void 0
@@ -124,7 +159,8 @@ function optional(parser) {
 					value: void 0
 				};
 			}
-			return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(state[0]), () => parser.complete(state[0]));
+			const innerElement = require_annotations.getAnnotations(state) != null && state[0] != null && typeof state[0] === "object" ? require_annotations.inheritAnnotations(state, state[0]) : state[0];
+			return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(innerElement), () => parser.complete(innerElement));
 		},
 		suggest(context, prefix) {
 			return require_mode_dispatch.dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
@@ -174,15 +210,25 @@ var WithDefaultError = class extends Error {
 };
 function withDefault(parser, defaultValue, options) {
 	const syncParser = parser;
+	const getDocDefaultValue = (upperDefaultValue) => {
+		if (upperDefaultValue != null) return upperDefaultValue;
+		if (options?.message) return void 0;
+		if (typeof defaultValue !== "function") return defaultValue;
+		try {
+			return defaultValue();
+		} catch {
+			return void 0;
+		}
+	};
 	function* suggestSync(context, prefix) {
-		const innerState = typeof context.state === "undefined" ? syncParser.initialState : context.state[0];
+		const innerState = Array.isArray(context.state) ? context.state[0] : syncParser.initialState;
 		yield* syncParser.suggest({
 			...context,
 			state: innerState
 		}, prefix);
 	}
 	async function* suggestAsync(context, prefix) {
-		const innerState = typeof context.state === "undefined" ? syncParser.initialState : context.state[0];
+		const innerState = Array.isArray(context.state) ? context.state[0] : syncParser.initialState;
 		const suggestions = parser.suggest({
 			...context,
 			state: innerState
@@ -202,11 +248,12 @@ function withDefault(parser, defaultValue, options) {
 		}],
 		initialState: void 0,
 		...wrappedDependencyMarker,
+		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser)) } : {},
 		parse(context) {
 			return require_mode_dispatch.dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
 		complete(state) {
-			if (typeof state === "undefined") {
+			if (!Array.isArray(state)) {
 				if (require_dependency.transformsDependencyValue(parser)) {
 					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(void 0), () => parser.complete(void 0));
 					const handleInnerResult = (res) => {
@@ -235,8 +282,7 @@ function withDefault(parser, defaultValue, options) {
 							};
 						}
 					};
-					if (innerResult instanceof Promise) return innerResult.then(handleInnerResult);
-					return handleInnerResult(innerResult);
+					return require_mode_dispatch.mapModeValue(parser.$mode, innerResult, handleInnerResult);
 				}
 				if (require_dependency.isWrappedDependencySource(parser)) try {
 					const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
@@ -251,6 +297,10 @@ function withDefault(parser, defaultValue, options) {
 						error: error instanceof WithDefaultError ? error.errorMessage : require_message.message`${require_message.text(String(error))}`
 					};
 				}
+				if (typeof parser.shouldDeferCompletion === "function" && state != null && typeof state === "object") {
+					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(state), () => parser.complete(state));
+					return innerResult;
+				}
 				try {
 					const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
 					return {
@@ -293,8 +343,7 @@ function withDefault(parser, defaultValue, options) {
 							};
 						}
 					};
-					if (innerResult instanceof Promise) return innerResult.then(handleInnerResult);
-					return handleInnerResult(innerResult);
+					return require_mode_dispatch.mapModeValue(parser.$mode, innerResult, handleInnerResult);
 				}
 				try {
 					const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
@@ -309,7 +358,8 @@ function withDefault(parser, defaultValue, options) {
 					};
 				}
 			}
-			return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(state[0]), () => parser.complete(state[0]));
+			const innerElement = require_annotations.getAnnotations(state) != null && state[0] != null && typeof state[0] === "object" ? require_annotations.inheritAnnotations(state, state[0]) : state[0];
+			return require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(innerElement), () => parser.complete(innerElement));
 		},
 		suggest(context, prefix) {
 			return require_mode_dispatch.dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
@@ -319,8 +369,7 @@ function withDefault(parser, defaultValue, options) {
 				kind: "available",
 				state: state.state[0]
 			};
-			const actualDefaultValue = upperDefaultValue != null ? upperDefaultValue : typeof defaultValue === "function" ? defaultValue() : defaultValue;
-			const fragments = syncParser.getDocFragments(innerState, actualDefaultValue);
+			const fragments = syncParser.getDocFragments(innerState, getDocDefaultValue(upperDefaultValue));
 			if (options?.message) {
 				const modifiedFragments = fragments.fragments.map((fragment) => {
 					if (fragment.type === "entry") return {
@@ -374,19 +423,10 @@ function withDefault(parser, defaultValue, options) {
 */
 function map(parser, transform) {
 	const complete = (state) => {
-		const res = parser.complete(state);
-		if (res instanceof Promise) return res.then((r) => {
-			if (r.success) return {
-				success: true,
-				value: transform(r.value)
-			};
-			return r;
-		});
-		if (res.success) return {
+		return require_mode_dispatch.mapModeValue(parser.$mode, parser.complete(state), (result) => result.success ? require_context.isPlaceholderValue(result.value) ? result : {
 			success: true,
-			value: transform(res.value)
-		};
-		return res;
+			value: transform(result.value)
+		} : result);
 	};
 	const dependencyMarkers = require_dependency.isWrappedDependencySource(parser) ? {
 		[require_dependency.wrappedDependencySourceMarker]: parser[require_dependency.wrappedDependencySourceMarker],
@@ -420,50 +460,105 @@ function map(parser, transform) {
 function multiple(parser, options = {}) {
 	const syncParser = parser;
 	const { min = 0, max = Infinity } = options;
+	const unwrapInjectedWrapper = require_annotations.unwrapInjectedAnnotationWrapper;
+	const completeSyncWithUnwrappedFallback = (state) => {
+		try {
+			return syncParser.complete(state);
+		} catch (error) {
+			if (!require_annotations.isInjectedAnnotationWrapper(state)) throw error;
+			return syncParser.complete(unwrapInjectedWrapper(state));
+		}
+	};
+	const parseSyncWithUnwrappedFallback = (context) => {
+		try {
+			const result = syncParser.parse(context);
+			if (result.success || result.consumed !== 0 || !require_annotations.isInjectedAnnotationWrapper(context.state)) return result;
+			return syncParser.parse({
+				...context,
+				state: unwrapInjectedWrapper(context.state)
+			});
+		} catch (error) {
+			if (!require_annotations.isInjectedAnnotationWrapper(context.state)) throw error;
+			return syncParser.parse({
+				...context,
+				state: unwrapInjectedWrapper(context.state)
+			});
+		}
+	};
+	const completeAsyncWithUnwrappedFallback = async (state) => {
+		try {
+			return await parser.complete(state);
+		} catch (error) {
+			if (!require_annotations.isInjectedAnnotationWrapper(state)) throw error;
+			return await parser.complete(unwrapInjectedWrapper(state));
+		}
+	};
+	const parseAsyncWithUnwrappedFallback = async (context) => {
+		try {
+			const result = await parser.parse(context);
+			if (result.success || result.consumed !== 0 || !require_annotations.isInjectedAnnotationWrapper(context.state)) return result;
+			return await parser.parse({
+				...context,
+				state: unwrapInjectedWrapper(context.state)
+			});
+		} catch (error) {
+			if (!require_annotations.isInjectedAnnotationWrapper(context.state)) throw error;
+			return await parser.parse({
+				...context,
+				state: unwrapInjectedWrapper(context.state)
+			});
+		}
+	};
 	const parseSync = (context) => {
 		let added = context.state.length < 1;
-		let result = syncParser.parse({
+		const currentItemStateWithAnnotations = context.state.at(-1) ?? require_annotations.inheritAnnotations(context.state, syncParser.initialState);
+		let result = parseSyncWithUnwrappedFallback({
 			...context,
-			state: context.state.at(-1) ?? syncParser.initialState
+			state: currentItemStateWithAnnotations
 		});
 		if (!result.success) if (!added) {
-			result = syncParser.parse({
+			const nextInitialState = require_annotations.inheritAnnotations(context.state, syncParser.initialState);
+			result = parseSyncWithUnwrappedFallback({
 				...context,
-				state: syncParser.initialState
+				state: nextInitialState
 			});
 			if (!result.success) return result;
 			added = true;
 		} else return result;
+		const itemAnnotationSource = added ? context.state : currentItemStateWithAnnotations;
+		const nextItemState = require_annotations.inheritAnnotations(itemAnnotationSource, result.next.state);
 		return {
 			success: true,
 			next: {
 				...result.next,
-				state: [...added ? context.state : context.state.slice(0, -1), result.next.state]
+				state: require_annotations.annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState])
 			},
 			consumed: result.consumed
 		};
 	};
 	const parseAsync = async (context) => {
 		let added = context.state.length < 1;
-		let resultOrPromise = parser.parse({
+		const currentItemStateWithAnnotations = context.state.at(-1) ?? require_annotations.inheritAnnotations(context.state, parser.initialState);
+		let result = await parseAsyncWithUnwrappedFallback({
 			...context,
-			state: context.state.at(-1) ?? parser.initialState
+			state: currentItemStateWithAnnotations
 		});
-		let result = await resultOrPromise;
 		if (!result.success) if (!added) {
-			resultOrPromise = parser.parse({
+			const nextInitialState = require_annotations.inheritAnnotations(context.state, parser.initialState);
+			result = await parseAsyncWithUnwrappedFallback({
 				...context,
-				state: parser.initialState
+				state: nextInitialState
 			});
-			result = await resultOrPromise;
 			if (!result.success) return result;
 			added = true;
 		} else return result;
+		const itemAnnotationSource = added ? context.state : currentItemStateWithAnnotations;
+		const nextItemState = require_annotations.inheritAnnotations(itemAnnotationSource, result.next.state);
 		return {
 			success: true,
 			next: {
 				...result.next,
-				state: [...added ? context.state : context.state.slice(0, -1), result.next.state]
+				state: require_annotations.annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState])
 			},
 			consumed: result.consumed
 		};
@@ -486,8 +581,8 @@ function multiple(parser, options = {}) {
 			return require_mode_dispatch.dispatchByMode(parser.$mode, () => {
 				const result = [];
 				for (const s of state) {
-					const valueResult = syncParser.complete(s);
-					if (valueResult.success) result.push(valueResult.value);
+					const valueResult = completeSyncWithUnwrappedFallback(s);
+					if (valueResult.success) result.push(unwrapInjectedWrapper(valueResult.value));
 					else return {
 						success: false,
 						error: valueResult.error
@@ -495,9 +590,9 @@ function multiple(parser, options = {}) {
 				}
 				return validateMultipleResult(result);
 			}, async () => {
-				const results = await Promise.all(state.map((s) => parser.complete(s)));
+				const results = await Promise.all(state.map((s) => completeAsyncWithUnwrappedFallback(s)));
 				const values = [];
-				for (const valueResult of results) if (valueResult.success) values.push(valueResult.value);
+				for (const valueResult of results) if (valueResult.success) values.push(unwrapInjectedWrapper(valueResult.value));
 				else return {
 					success: false,
 					error: valueResult.error
@@ -507,10 +602,13 @@ function multiple(parser, options = {}) {
 		},
 		suggest(context, prefix) {
 			const selectedValues = /* @__PURE__ */ new Set();
+			const suggestInitialState = require_annotations.inheritAnnotations(context.state, parser.initialState);
+			const suggestFallbackState = unwrapInjectedWrapper(suggestInitialState);
+			const hasSuggestFallbackState = suggestFallbackState !== suggestInitialState;
 			for (const s of context.state) {
-				const completed = syncParser.complete(s);
+				const completed = completeSyncWithUnwrappedFallback(s);
 				if (completed.success) {
-					const valueStr = String(completed.value);
+					const valueStr = String(unwrapInjectedWrapper(completed.value));
 					selectedValues.add(valueStr);
 				}
 			}
@@ -518,23 +616,80 @@ function multiple(parser, options = {}) {
 				if (suggestion.kind === "literal") return !selectedValues.has(suggestion.text);
 				return true;
 			};
+			const suggestionKey = (suggestion) => {
+				const description = suggestion.description == null ? "" : require_message.formatMessage(suggestion.description);
+				if (suggestion.kind === "literal") return JSON.stringify([
+					"literal",
+					suggestion.text,
+					description
+				]);
+				return JSON.stringify([
+					"file",
+					suggestion.type,
+					suggestion.pattern ?? "",
+					suggestion.includeHidden === true,
+					suggestion.extensions == null ? "" : suggestion.extensions.join("\0"),
+					description
+				]);
+			};
 			return require_mode_dispatch.dispatchIterableByMode(parser.$mode, function* () {
-				for (const s of syncParser.suggest({
+				const emitted = /* @__PURE__ */ new Set();
+				const yieldUnique = function* (suggestions) {
+					for (const s of suggestions) {
+						const key = suggestionKey(s);
+						if (shouldInclude(s) && !emitted.has(key)) {
+							emitted.add(key);
+							yield s;
+						}
+					}
+				};
+				let shouldTryFallback = false;
+				try {
+					yield* yieldUnique(syncParser.suggest({
+						...context,
+						state: suggestInitialState
+					}, prefix));
+				} catch (error) {
+					if (!hasSuggestFallbackState) throw error;
+					shouldTryFallback = true;
+				}
+				if (shouldTryFallback) yield* yieldUnique(syncParser.suggest({
 					...context,
-					state: parser.initialState
-				}, prefix)) if (shouldInclude(s)) yield s;
+					state: suggestFallbackState
+				}, prefix));
 			}, async function* () {
-				const suggestions = parser.suggest({
+				const emitted = /* @__PURE__ */ new Set();
+				const yieldUnique = async function* (suggestions) {
+					for await (const s of suggestions) {
+						const key = suggestionKey(s);
+						if (shouldInclude(s) && !emitted.has(key)) {
+							emitted.add(key);
+							yield s;
+						}
+					}
+				};
+				let shouldTryFallback = false;
+				try {
+					yield* yieldUnique(parser.suggest({
+						...context,
+						state: suggestInitialState
+					}, prefix));
+				} catch (error) {
+					if (!hasSuggestFallbackState) throw error;
+					shouldTryFallback = true;
+				}
+				if (shouldTryFallback) yield* yieldUnique(parser.suggest({
 					...context,
-					state: parser.initialState
-				}, prefix);
-				for await (const s of suggestions) if (shouldInclude(s)) yield s;
+					state: suggestFallbackState
+				}, prefix));
 			});
 		},
 		getDocFragments(state, defaultValue) {
-			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state.length > 0 ? {
+			const latestState = state.kind === "available" && state.state.length > 0 ? state.state.at(-1) : void 0;
+			const latestInnerState = latestState != null && require_annotations.isInjectedAnnotationWrapper(latestState) ? unwrapInjectedWrapper(latestState) : latestState;
+			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : latestInnerState !== void 0 ? {
 				kind: "available",
-				state: state.state.at(-1)
+				state: latestInnerState
 			} : { kind: "unavailable" };
 			return syncParser.getDocFragments(innerState, defaultValue != null && defaultValue.length > 0 ? defaultValue[0] : void 0);
 		}