@optique/core 1.0.0-dev.1897 → 1.0.0-dev.1901

package/dist/annotation-state.cjs

@@ -132,14 +132,103 @@ function normalizeNestedDelegatedStructuredState(source, seen) {
 	entry.result = clone;
 	return clone;
 }
+function normalizeNestedDelegatedMapState(source, seen) {
+	const clone = /* @__PURE__ */ new Map();
+	const entry = {
+		clone,
+		finalized: false,
+		result: clone
+	};
+	seen.set(source, entry);
+	const normalizedEntries = [];
+	const overrides = /* @__PURE__ */ new Map();
+	let changed = false;
+	for (const [key, value] of source) {
+		const nextKey = normalizeNestedDelegatedAnnotationState(key, seen);
+		const nextValue = normalizeNestedDelegatedAnnotationState(value, seen);
+		normalizedEntries.push([nextKey, nextValue]);
+		if (!isPendingNestedNormalizationAlias(key, nextKey, seen) && nextKey !== key || !isPendingNestedNormalizationAlias(value, nextValue, seen) && nextValue !== value) changed = true;
+	}
+	for (const key of Reflect.ownKeys(source)) {
+		const descriptor = Object.getOwnPropertyDescriptor(source, key);
+		if (descriptor == null || !("value" in descriptor)) continue;
+		const nextValue = normalizeNestedDelegatedAnnotationState(descriptor.value, seen);
+		if (nextValue === descriptor.value) continue;
+		overrides.set(key, nextValue);
+		if (!isPendingNestedNormalizationAlias(descriptor.value, nextValue, seen)) changed = true;
+	}
+	if (!changed) {
+		entry.finalized = true;
+		entry.result = source;
+		return source;
+	}
+	for (const [key, value] of normalizedEntries) clone.set(key, value);
+	const descriptors = Object.getOwnPropertyDescriptors(source);
+	for (const [key, nextValue] of overrides) {
+		const descriptor = descriptors[key];
+		if (descriptor == null || !("value" in descriptor)) continue;
+		descriptors[key] = {
+			...descriptor,
+			value: nextValue
+		};
+	}
+	Object.defineProperties(clone, descriptors);
+	entry.finalized = true;
+	entry.result = clone;
+	return clone;
+}
+function normalizeNestedDelegatedSetState(source, seen) {
+	const clone = /* @__PURE__ */ new Set();
+	const entry = {
+		clone,
+		finalized: false,
+		result: clone
+	};
+	seen.set(source, entry);
+	const normalizedValues = [];
+	const overrides = /* @__PURE__ */ new Map();
+	let changed = false;
+	for (const value of source) {
+		const nextValue = normalizeNestedDelegatedAnnotationState(value, seen);
+		normalizedValues.push(nextValue);
+		if (nextValue !== value && !isPendingNestedNormalizationAlias(value, nextValue, seen)) changed = true;
+	}
+	for (const key of Reflect.ownKeys(source)) {
+		const descriptor = Object.getOwnPropertyDescriptor(source, key);
+		if (descriptor == null || !("value" in descriptor)) continue;
+		const nextValue = normalizeNestedDelegatedAnnotationState(descriptor.value, seen);
+		if (nextValue === descriptor.value) continue;
+		overrides.set(key, nextValue);
+		if (!isPendingNestedNormalizationAlias(descriptor.value, nextValue, seen)) changed = true;
+	}
+	if (!changed) {
+		entry.finalized = true;
+		entry.result = source;
+		return source;
+	}
+	for (const value of normalizedValues) clone.add(value);
+	const descriptors = Object.getOwnPropertyDescriptors(source);
+	for (const [key, nextValue] of overrides) {
+		const descriptor = descriptors[key];
+		if (descriptor == null || !("value" in descriptor)) continue;
+		descriptors[key] = {
+			...descriptor,
+			value: nextValue
+		};
+	}
+	Object.defineProperties(clone, descriptors);
+	entry.finalized = true;
+	entry.result = clone;
+	return clone;
+}
 /**
-* Recursively removes delegated annotation carriers from plain-object and array
-* structures.
+* Recursively removes delegated annotation carriers from plain-object, array,
+* and built-in collection structures.
 *
-* Nested plain objects and arrays are shallow-cloned only when a delegated
-* carrier is found below them. Non-plain objects are unwrapped at the top
-* level and then preserved as-is to avoid mutating or reconstructing class
-* instances.
+* Nested plain objects, arrays, Maps, and Sets are shallow-cloned only when a
+* delegated carrier is found below them. Other non-plain objects are unwrapped
+* at the top level and then preserved as-is to avoid mutating or reconstructing
+* class instances.
 *
 * @param value The candidate value to normalize.
 * @param seen Tracks already-normalized objects so cyclic values keep their
@@ -155,6 +244,8 @@ function normalizeNestedDelegatedAnnotationState(value, seen = /* @__PURE__ */ n
 	const existing = seen.get(source);
 	if (existing != null) return existing.finalized ? existing.result : existing.clone;
 	if (Array.isArray(source)) return normalizeNestedDelegatedStructuredState(source, seen);
+	if (source instanceof Map) return normalizeNestedDelegatedMapState(source, seen);
+	if (source instanceof Set) return normalizeNestedDelegatedSetState(source, seen);
 	const proto = Object.getPrototypeOf(source);
 	if (proto !== Object.prototype && proto !== null) return normalized;
 	return normalizeNestedDelegatedStructuredState(source, seen);

package/dist/annotation-state.js

@@ -132,14 +132,103 @@ function normalizeNestedDelegatedStructuredState(source, seen) {
 	entry.result = clone;
 	return clone;
 }
+function normalizeNestedDelegatedMapState(source, seen) {
+	const clone = /* @__PURE__ */ new Map();
+	const entry = {
+		clone,
+		finalized: false,
+		result: clone
+	};
+	seen.set(source, entry);
+	const normalizedEntries = [];
+	const overrides = /* @__PURE__ */ new Map();
+	let changed = false;
+	for (const [key, value] of source) {
+		const nextKey = normalizeNestedDelegatedAnnotationState(key, seen);
+		const nextValue = normalizeNestedDelegatedAnnotationState(value, seen);
+		normalizedEntries.push([nextKey, nextValue]);
+		if (!isPendingNestedNormalizationAlias(key, nextKey, seen) && nextKey !== key || !isPendingNestedNormalizationAlias(value, nextValue, seen) && nextValue !== value) changed = true;
+	}
+	for (const key of Reflect.ownKeys(source)) {
+		const descriptor = Object.getOwnPropertyDescriptor(source, key);
+		if (descriptor == null || !("value" in descriptor)) continue;
+		const nextValue = normalizeNestedDelegatedAnnotationState(descriptor.value, seen);
+		if (nextValue === descriptor.value) continue;
+		overrides.set(key, nextValue);
+		if (!isPendingNestedNormalizationAlias(descriptor.value, nextValue, seen)) changed = true;
+	}
+	if (!changed) {
+		entry.finalized = true;
+		entry.result = source;
+		return source;
+	}
+	for (const [key, value] of normalizedEntries) clone.set(key, value);
+	const descriptors = Object.getOwnPropertyDescriptors(source);
+	for (const [key, nextValue] of overrides) {
+		const descriptor = descriptors[key];
+		if (descriptor == null || !("value" in descriptor)) continue;
+		descriptors[key] = {
+			...descriptor,
+			value: nextValue
+		};
+	}
+	Object.defineProperties(clone, descriptors);
+	entry.finalized = true;
+	entry.result = clone;
+	return clone;
+}
+function normalizeNestedDelegatedSetState(source, seen) {
+	const clone = /* @__PURE__ */ new Set();
+	const entry = {
+		clone,
+		finalized: false,
+		result: clone
+	};
+	seen.set(source, entry);
+	const normalizedValues = [];
+	const overrides = /* @__PURE__ */ new Map();
+	let changed = false;
+	for (const value of source) {
+		const nextValue = normalizeNestedDelegatedAnnotationState(value, seen);
+		normalizedValues.push(nextValue);
+		if (nextValue !== value && !isPendingNestedNormalizationAlias(value, nextValue, seen)) changed = true;
+	}
+	for (const key of Reflect.ownKeys(source)) {
+		const descriptor = Object.getOwnPropertyDescriptor(source, key);
+		if (descriptor == null || !("value" in descriptor)) continue;
+		const nextValue = normalizeNestedDelegatedAnnotationState(descriptor.value, seen);
+		if (nextValue === descriptor.value) continue;
+		overrides.set(key, nextValue);
+		if (!isPendingNestedNormalizationAlias(descriptor.value, nextValue, seen)) changed = true;
+	}
+	if (!changed) {
+		entry.finalized = true;
+		entry.result = source;
+		return source;
+	}
+	for (const value of normalizedValues) clone.add(value);
+	const descriptors = Object.getOwnPropertyDescriptors(source);
+	for (const [key, nextValue] of overrides) {
+		const descriptor = descriptors[key];
+		if (descriptor == null || !("value" in descriptor)) continue;
+		descriptors[key] = {
+			...descriptor,
+			value: nextValue
+		};
+	}
+	Object.defineProperties(clone, descriptors);
+	entry.finalized = true;
+	entry.result = clone;
+	return clone;
+}
 /**
-* Recursively removes delegated annotation carriers from plain-object and array
-* structures.
+* Recursively removes delegated annotation carriers from plain-object, array,
+* and built-in collection structures.
 *
-* Nested plain objects and arrays are shallow-cloned only when a delegated
-* carrier is found below them. Non-plain objects are unwrapped at the top
-* level and then preserved as-is to avoid mutating or reconstructing class
-* instances.
+* Nested plain objects, arrays, Maps, and Sets are shallow-cloned only when a
+* delegated carrier is found below them. Other non-plain objects are unwrapped
+* at the top level and then preserved as-is to avoid mutating or reconstructing
+* class instances.
 *
 * @param value The candidate value to normalize.
 * @param seen Tracks already-normalized objects so cyclic values keep their
@@ -155,6 +244,8 @@ function normalizeNestedDelegatedAnnotationState(value, seen = /* @__PURE__ */ n
 	const existing = seen.get(source);
 	if (existing != null) return existing.finalized ? existing.result : existing.clone;
 	if (Array.isArray(source)) return normalizeNestedDelegatedStructuredState(source, seen);
+	if (source instanceof Map) return normalizeNestedDelegatedMapState(source, seen);
+	if (source instanceof Set) return normalizeNestedDelegatedSetState(source, seen);
 	const proto = Object.getPrototypeOf(source);
 	if (proto !== Object.prototype && proto !== null) return normalized;
 	return normalizeNestedDelegatedStructuredState(source, seen);

package/dist/modifiers.cjs

@@ -90,22 +90,28 @@ function normalizeOptionalLikeCompleteResult(result) {
 }
 function completeOptionalLikeSync(parser, state, exec) {
 	const hasCarrier = require_annotation_state.hasDelegatedAnnotationCarrier(state);
+	const shouldRetryFalseResult = require_annotation_state.isAnnotationWrappedInitialState(state);
+	const run = (candidate) => normalizeOptionalLikeCompleteResult(parser.complete(candidate, exec));
 	try {
-		return normalizeOptionalLikeCompleteResult(parser.complete(state, exec));
+		const result = run(state);
+		if (!result.success && shouldRetryFalseResult) return run(require_annotation_state.normalizeDelegatedAnnotationState(state));
+		return result;
 	} catch (error) {
 		if (!hasCarrier) throw error;
-		const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(state);
-		return normalizeOptionalLikeCompleteResult(parser.complete(fallbackState, exec));
+		return run(require_annotation_state.normalizeDelegatedAnnotationState(state));
 	}
 }
 async function completeOptionalLikeAsync(parser, state, exec) {
 	const hasCarrier = require_annotation_state.hasDelegatedAnnotationCarrier(state);
+	const shouldRetryFalseResult = require_annotation_state.isAnnotationWrappedInitialState(state);
+	const run = async (candidate) => normalizeOptionalLikeCompleteResult(await parser.complete(candidate, exec));
 	try {
-		return normalizeOptionalLikeCompleteResult(await parser.complete(state, exec));
+		const result = await run(state);
+		if (!result.success && shouldRetryFalseResult) return await run(require_annotation_state.normalizeDelegatedAnnotationState(state));
+		return result;
 	} catch (error) {
 		if (!hasCarrier) throw error;
-		const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(state);
-		return normalizeOptionalLikeCompleteResult(await parser.complete(fallbackState, exec));
+		return await run(require_annotation_state.normalizeDelegatedAnnotationState(state));
 	}
 }
 function normalizeOptionalLikePhase2Seed(seed) {
@@ -253,10 +259,14 @@ function adaptShouldDeferCompletion(innerCheck, parser) {
 	return (state, exec) => {
 		if (Array.isArray(state) || state != null && typeof state === "object") {
 			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+			const hasCarrier = require_annotation_state.hasDelegatedAnnotationCarrier(innerState);
+			const shouldRetryFalseResult = hasCarrier && require_annotation_state.isAnnotationWrappedInitialState(innerState);
 			try {
-				return innerCheck(innerState, exec);
+				const result = innerCheck(innerState, exec);
+				if (!result && shouldRetryFalseResult) return innerCheck(require_annotation_state.normalizeDelegatedAnnotationState(innerState), exec);
+				return result;
 			} catch (error) {
-				if (!require_annotation_state.hasDelegatedAnnotationCarrier(innerState)) throw error;
+				if (!hasCarrier) throw error;
 				return innerCheck(require_annotation_state.normalizeDelegatedAnnotationState(innerState), exec);
 			}
 		}
@@ -277,6 +287,13 @@ function normalizeOptionalLikeInnerState(state, initialState, parser) {
 	if (state != null && typeof state === "object") return state;
 	return initialState;
 }
+function normalizeOptionalLikeSuggestState(state, initialState, parser) {
+	if (Array.isArray(state)) {
+		const innerState = state[0];
+		return innerState != null && typeof innerState === "object" ? require_annotation_state.getDelegatedAnnotationState(state, innerState) : innerState;
+	}
+	return normalizeOptionalLikeInnerState(state, initialState, parser);
+}
 /**
 * Creates a parser that makes another parser optional, allowing it to succeed
 * without consuming input if the wrapped parser fails to match.
@@ -292,14 +309,14 @@ function normalizeOptionalLikeInnerState(state, initialState, parser) {
 function optional(parser) {
 	const syncParser = parser;
 	function* suggestSync(context, prefix) {
-		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState, parser);
+		const innerState = normalizeOptionalLikeSuggestState(context.state, syncParser.initialState, parser);
 		yield* syncParser.suggest({
 			...context,
 			state: innerState
 		}, prefix);
 	}
 	async function* suggestAsync(context, prefix) {
-		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState, parser);
+		const innerState = normalizeOptionalLikeSuggestState(context.state, syncParser.initialState, parser);
 		const suggestions = parser.suggest({
 			...context,
 			state: innerState
@@ -327,7 +344,7 @@ function optional(parser) {
 				parser: optionalParser,
 				state
 			}];
-			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+			const innerState = normalizeOptionalLikeSuggestState(state, parser.initialState, parser);
 			return parser.getSuggestRuntimeNodes?.(innerState, path) ?? (parser.dependencyMetadata?.source != null ? [{
 				path,
 				parser,
@@ -461,14 +478,14 @@ function withDefault(parser, defaultValue, options) {
 		}
 	};
 	function* suggestSync(context, prefix) {
-		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState, parser);
+		const innerState = normalizeOptionalLikeSuggestState(context.state, syncParser.initialState, parser);
 		yield* syncParser.suggest({
 			...context,
 			state: innerState
 		}, prefix);
 	}
 	async function* suggestAsync(context, prefix) {
-		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState, parser);
+		const innerState = normalizeOptionalLikeSuggestState(context.state, syncParser.initialState, parser);
 		const suggestions = parser.suggest({
 			...context,
 			state: innerState
@@ -495,7 +512,7 @@ function withDefault(parser, defaultValue, options) {
 				parser: withDefaultParser,
 				state
 			}];
-			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+			const innerState = normalizeOptionalLikeSuggestState(state, parser.initialState, parser);
 			return parser.getSuggestRuntimeNodes?.(innerState, path) ?? (parser.dependencyMetadata?.source != null ? [{
 				path,
 				parser,

package/dist/modifiers.js

@@ -4,7 +4,7 @@ import { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode } fro
 import { composeDependencyMetadata } from "./dependency-metadata.js";
 import { completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult } from "./phase2-seed.js";
 import { defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, unmatchedNonCliDependencySourceStateMarker } from "./parser.js";
-import { getDelegatedAnnotationState, hasDelegatedAnnotationCarrier, normalizeDelegatedAnnotationState, normalizeNestedDelegatedAnnotationState } from "./annotation-state.js";
+import { getDelegatedAnnotationState, hasDelegatedAnnotationCarrier, isAnnotationWrappedInitialState, normalizeDelegatedAnnotationState, normalizeNestedDelegatedAnnotationState } from "./annotation-state.js";
 
 //#region src/modifiers.ts
 function withChildExecPath(exec, segment) {
@@ -90,22 +90,28 @@ function normalizeOptionalLikeCompleteResult(result) {
 }
 function completeOptionalLikeSync(parser, state, exec) {
 	const hasCarrier = hasDelegatedAnnotationCarrier(state);
+	const shouldRetryFalseResult = isAnnotationWrappedInitialState(state);
+	const run = (candidate) => normalizeOptionalLikeCompleteResult(parser.complete(candidate, exec));
 	try {
-		return normalizeOptionalLikeCompleteResult(parser.complete(state, exec));
+		const result = run(state);
+		if (!result.success && shouldRetryFalseResult) return run(normalizeDelegatedAnnotationState(state));
+		return result;
 	} catch (error) {
 		if (!hasCarrier) throw error;
-		const fallbackState = normalizeDelegatedAnnotationState(state);
-		return normalizeOptionalLikeCompleteResult(parser.complete(fallbackState, exec));
+		return run(normalizeDelegatedAnnotationState(state));
 	}
 }
 async function completeOptionalLikeAsync(parser, state, exec) {
 	const hasCarrier = hasDelegatedAnnotationCarrier(state);
+	const shouldRetryFalseResult = isAnnotationWrappedInitialState(state);
+	const run = async (candidate) => normalizeOptionalLikeCompleteResult(await parser.complete(candidate, exec));
 	try {
-		return normalizeOptionalLikeCompleteResult(await parser.complete(state, exec));
+		const result = await run(state);
+		if (!result.success && shouldRetryFalseResult) return await run(normalizeDelegatedAnnotationState(state));
+		return result;
 	} catch (error) {
 		if (!hasCarrier) throw error;
-		const fallbackState = normalizeDelegatedAnnotationState(state);
-		return normalizeOptionalLikeCompleteResult(await parser.complete(fallbackState, exec));
+		return await run(normalizeDelegatedAnnotationState(state));
 	}
 }
 function normalizeOptionalLikePhase2Seed(seed) {
@@ -253,10 +259,14 @@ function adaptShouldDeferCompletion(innerCheck, parser) {
 	return (state, exec) => {
 		if (Array.isArray(state) || state != null && typeof state === "object") {
 			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+			const hasCarrier = hasDelegatedAnnotationCarrier(innerState);
+			const shouldRetryFalseResult = hasCarrier && isAnnotationWrappedInitialState(innerState);
 			try {
-				return innerCheck(innerState, exec);
+				const result = innerCheck(innerState, exec);
+				if (!result && shouldRetryFalseResult) return innerCheck(normalizeDelegatedAnnotationState(innerState), exec);
+				return result;
 			} catch (error) {
-				if (!hasDelegatedAnnotationCarrier(innerState)) throw error;
+				if (!hasCarrier) throw error;
 				return innerCheck(normalizeDelegatedAnnotationState(innerState), exec);
 			}
 		}
@@ -277,6 +287,13 @@ function normalizeOptionalLikeInnerState(state, initialState, parser) {
 	if (state != null && typeof state === "object") return state;
 	return initialState;
 }
+function normalizeOptionalLikeSuggestState(state, initialState, parser) {
+	if (Array.isArray(state)) {
+		const innerState = state[0];
+		return innerState != null && typeof innerState === "object" ? getDelegatedAnnotationState(state, innerState) : innerState;
+	}
+	return normalizeOptionalLikeInnerState(state, initialState, parser);
+}
 /**
 * Creates a parser that makes another parser optional, allowing it to succeed
 * without consuming input if the wrapped parser fails to match.
@@ -292,14 +309,14 @@ function normalizeOptionalLikeInnerState(state, initialState, parser) {
 function optional(parser) {
 	const syncParser = parser;
 	function* suggestSync(context, prefix) {
-		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState, parser);
+		const innerState = normalizeOptionalLikeSuggestState(context.state, syncParser.initialState, parser);
 		yield* syncParser.suggest({
 			...context,
 			state: innerState
 		}, prefix);
 	}
 	async function* suggestAsync(context, prefix) {
-		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState, parser);
+		const innerState = normalizeOptionalLikeSuggestState(context.state, syncParser.initialState, parser);
 		const suggestions = parser.suggest({
 			...context,
 			state: innerState
@@ -327,7 +344,7 @@ function optional(parser) {
 				parser: optionalParser,
 				state
 			}];
-			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+			const innerState = normalizeOptionalLikeSuggestState(state, parser.initialState, parser);
 			return parser.getSuggestRuntimeNodes?.(innerState, path) ?? (parser.dependencyMetadata?.source != null ? [{
 				path,
 				parser,
@@ -461,14 +478,14 @@ function withDefault(parser, defaultValue, options) {
 		}
 	};
 	function* suggestSync(context, prefix) {
-		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState, parser);
+		const innerState = normalizeOptionalLikeSuggestState(context.state, syncParser.initialState, parser);
 		yield* syncParser.suggest({
 			...context,
 			state: innerState
 		}, prefix);
 	}
 	async function* suggestAsync(context, prefix) {
-		const innerState = normalizeOptionalLikeInnerState(context.state, syncParser.initialState, parser);
+		const innerState = normalizeOptionalLikeSuggestState(context.state, syncParser.initialState, parser);
 		const suggestions = parser.suggest({
 			...context,
 			state: innerState
@@ -495,7 +512,7 @@ function withDefault(parser, defaultValue, options) {
 				parser: withDefaultParser,
 				state
 			}];
-			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+			const innerState = normalizeOptionalLikeSuggestState(state, parser.initialState, parser);
 			return parser.getSuggestRuntimeNodes?.(innerState, path) ?? (parser.dependencyMetadata?.source != null ? [{
 				path,
 				parser,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1897+409a60db",
+  "version": "1.0.0-dev.1901+a2ce4da0",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",