@optique/core 1.0.0-dev.1891 → 1.0.0-dev.1895

package/dist/annotation-state.cjs

@@ -87,6 +87,83 @@ function normalizeDelegatedAnnotationState(state) {
 function hasDelegatedAnnotationCarrier(state) {
 	return state != null && typeof state === "object" && (require_annotations.isInjectedAnnotationWrapper(state) || annotationViewTargets.has(state));
 }
+function isPendingNestedNormalizationAlias(originalValue, normalizedValue, seen) {
+	if (originalValue == null || typeof originalValue !== "object") return false;
+	const entry = seen.get(originalValue);
+	return entry != null && !entry.finalized && entry.clone === normalizedValue;
+}
+/**
+* Recursively removes delegated annotation carriers from plain-object and array
+* 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.
+*
+* @param value The candidate value to normalize.
+* @param seen Tracks already-normalized objects so cyclic values keep their
+*             shape.
+* @returns The original value when no delegated carriers are present, or a
+*          normalized clone with delegated carriers removed.
+* @internal
+*/
+function normalizeNestedDelegatedAnnotationState(value, seen = /* @__PURE__ */ new WeakMap()) {
+	const normalized = normalizeDelegatedAnnotationState(value);
+	if (normalized == null || typeof normalized !== "object") return normalized;
+	const source = normalized;
+	const existing = seen.get(source);
+	if (existing != null) return existing.finalized ? existing.result : existing.clone;
+	if (Array.isArray(source)) {
+		let changed$1 = false;
+		const clone$1 = require_annotations.annotateFreshArray(source, source.slice());
+		const entry$1 = {
+			clone: clone$1,
+			finalized: false,
+			result: clone$1
+		};
+		seen.set(source, entry$1);
+		for (let i = 0; i < source.length; i++) {
+			const nextValue = normalizeNestedDelegatedAnnotationState(source[i], seen);
+			if (nextValue !== source[i]) {
+				clone$1[i] = nextValue;
+				if (!isPendingNestedNormalizationAlias(source[i], nextValue, seen)) changed$1 = true;
+			}
+		}
+		entry$1.finalized = true;
+		entry$1.result = changed$1 ? clone$1 : source;
+		return changed$1 ? clone$1 : source;
+	}
+	const proto = Object.getPrototypeOf(source);
+	if (proto !== Object.prototype && proto !== null) return normalized;
+	const descriptors = Object.getOwnPropertyDescriptors(source);
+	let changed = false;
+	const clone = Object.create(proto);
+	const entry = {
+		clone,
+		finalized: false,
+		result: clone
+	};
+	seen.set(source, entry);
+	for (const key of Reflect.ownKeys(descriptors)) {
+		const descriptor = descriptors[key];
+		if (descriptor != null && "value" in descriptor) {
+			const nextValue = normalizeNestedDelegatedAnnotationState(descriptor.value, seen);
+			if (nextValue !== descriptor.value) {
+				descriptors[key] = {
+					...descriptor,
+					value: nextValue
+				};
+				if (!isPendingNestedNormalizationAlias(descriptor.value, nextValue, seen)) changed = true;
+			}
+		}
+	}
+	entry.finalized = true;
+	entry.result = changed ? clone : source;
+	if (!changed) return source;
+	Object.defineProperties(clone, descriptors);
+	return clone;
+}
 /**
 * Creates a short-lived delegated state that exposes the parent's annotations
 * regardless of the child state's runtime shape.
@@ -103,9 +180,10 @@ function hasDelegatedAnnotationCarrier(state) {
 */
 function getDelegatedAnnotationState(parentState, childState) {
 	const annotations = require_annotations.getAnnotations(parentState);
-	if (annotations === void 0 || require_annotations.getAnnotations(childState) === annotations) return childState;
+	if (annotations === void 0) return childState;
+	if (require_annotations.isInjectedAnnotationWrapper(childState)) return require_annotations.injectAnnotations(normalizeInjectedAnnotationState(childState), annotations);
+	if (require_annotations.getAnnotations(childState) === annotations) return childState;
 	if (childState == null || typeof childState !== "object") return require_annotations.injectAnnotations(childState, annotations);
-	if (require_annotations.isInjectedAnnotationWrapper(childState)) return require_annotations.injectAnnotations(childState, annotations);
 	if (isNonPlainDelegatedObject(childState)) return withAnnotationView(childState, annotations);
 	return require_annotations.inheritAnnotations(parentState, childState);
 }
@@ -201,5 +279,6 @@ exports.hasDelegatedAnnotationCarrier = hasDelegatedAnnotationCarrier;
 exports.isAnnotationWrappedInitialState = isAnnotationWrappedInitialState;
 exports.normalizeDelegatedAnnotationState = normalizeDelegatedAnnotationState;
 exports.normalizeInjectedAnnotationState = normalizeInjectedAnnotationState;
+exports.normalizeNestedDelegatedAnnotationState = normalizeNestedDelegatedAnnotationState;
 exports.reconcileObjectChildState = reconcileObjectChildState;
 exports.unwrapAnnotationView = unwrapAnnotationView;

package/dist/annotation-state.js

@@ -1,4 +1,4 @@
-import { annotationKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
+import { annotateFreshArray, annotationKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
 import { inheritParentAnnotationsKey } from "./parser.js";
 
 //#region src/annotation-state.ts
@@ -87,6 +87,83 @@ function normalizeDelegatedAnnotationState(state) {
 function hasDelegatedAnnotationCarrier(state) {
 	return state != null && typeof state === "object" && (isInjectedAnnotationWrapper(state) || annotationViewTargets.has(state));
 }
+function isPendingNestedNormalizationAlias(originalValue, normalizedValue, seen) {
+	if (originalValue == null || typeof originalValue !== "object") return false;
+	const entry = seen.get(originalValue);
+	return entry != null && !entry.finalized && entry.clone === normalizedValue;
+}
+/**
+* Recursively removes delegated annotation carriers from plain-object and array
+* 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.
+*
+* @param value The candidate value to normalize.
+* @param seen Tracks already-normalized objects so cyclic values keep their
+*             shape.
+* @returns The original value when no delegated carriers are present, or a
+*          normalized clone with delegated carriers removed.
+* @internal
+*/
+function normalizeNestedDelegatedAnnotationState(value, seen = /* @__PURE__ */ new WeakMap()) {
+	const normalized = normalizeDelegatedAnnotationState(value);
+	if (normalized == null || typeof normalized !== "object") return normalized;
+	const source = normalized;
+	const existing = seen.get(source);
+	if (existing != null) return existing.finalized ? existing.result : existing.clone;
+	if (Array.isArray(source)) {
+		let changed$1 = false;
+		const clone$1 = annotateFreshArray(source, source.slice());
+		const entry$1 = {
+			clone: clone$1,
+			finalized: false,
+			result: clone$1
+		};
+		seen.set(source, entry$1);
+		for (let i = 0; i < source.length; i++) {
+			const nextValue = normalizeNestedDelegatedAnnotationState(source[i], seen);
+			if (nextValue !== source[i]) {
+				clone$1[i] = nextValue;
+				if (!isPendingNestedNormalizationAlias(source[i], nextValue, seen)) changed$1 = true;
+			}
+		}
+		entry$1.finalized = true;
+		entry$1.result = changed$1 ? clone$1 : source;
+		return changed$1 ? clone$1 : source;
+	}
+	const proto = Object.getPrototypeOf(source);
+	if (proto !== Object.prototype && proto !== null) return normalized;
+	const descriptors = Object.getOwnPropertyDescriptors(source);
+	let changed = false;
+	const clone = Object.create(proto);
+	const entry = {
+		clone,
+		finalized: false,
+		result: clone
+	};
+	seen.set(source, entry);
+	for (const key of Reflect.ownKeys(descriptors)) {
+		const descriptor = descriptors[key];
+		if (descriptor != null && "value" in descriptor) {
+			const nextValue = normalizeNestedDelegatedAnnotationState(descriptor.value, seen);
+			if (nextValue !== descriptor.value) {
+				descriptors[key] = {
+					...descriptor,
+					value: nextValue
+				};
+				if (!isPendingNestedNormalizationAlias(descriptor.value, nextValue, seen)) changed = true;
+			}
+		}
+	}
+	entry.finalized = true;
+	entry.result = changed ? clone : source;
+	if (!changed) return source;
+	Object.defineProperties(clone, descriptors);
+	return clone;
+}
 /**
 * Creates a short-lived delegated state that exposes the parent's annotations
 * regardless of the child state's runtime shape.
@@ -103,9 +180,10 @@ function hasDelegatedAnnotationCarrier(state) {
 */
 function getDelegatedAnnotationState(parentState, childState) {
 	const annotations = getAnnotations(parentState);
-	if (annotations === void 0 || getAnnotations(childState) === annotations) return childState;
+	if (annotations === void 0) return childState;
+	if (isInjectedAnnotationWrapper(childState)) return injectAnnotations(normalizeInjectedAnnotationState(childState), annotations);
+	if (getAnnotations(childState) === annotations) return childState;
 	if (childState == null || typeof childState !== "object") return injectAnnotations(childState, annotations);
-	if (isInjectedAnnotationWrapper(childState)) return injectAnnotations(childState, annotations);
 	if (isNonPlainDelegatedObject(childState)) return withAnnotationView(childState, annotations);
 	return inheritAnnotations(parentState, childState);
 }
@@ -193,4 +271,4 @@ function reconcileObjectChildState(parentState, childState) {
 }
 
 //#endregion
-export { annotationViewTargets, getDelegatedAnnotationState, getWrappedChildParseState, getWrappedChildState, hasDelegatedAnnotationCarrier, isAnnotationWrappedInitialState, normalizeDelegatedAnnotationState, normalizeInjectedAnnotationState, reconcileObjectChildState, unwrapAnnotationView };
+export { annotationViewTargets, getDelegatedAnnotationState, getWrappedChildParseState, getWrappedChildState, hasDelegatedAnnotationCarrier, isAnnotationWrappedInitialState, normalizeDelegatedAnnotationState, normalizeInjectedAnnotationState, normalizeNestedDelegatedAnnotationState, reconcileObjectChildState, unwrapAnnotationView };

package/dist/modifiers.cjs

@@ -85,58 +85,72 @@ function isPromiseLike(value) {
 function normalizeOptionalLikeCompleteResult(result) {
 	return result.success ? {
 		...result,
-		value: require_annotation_state.normalizeDelegatedAnnotationState(result.value)
+		value: require_annotation_state.normalizeNestedDelegatedAnnotationState(result.value)
 	} : result;
 }
 function completeOptionalLikeSync(parser, state, exec) {
-	const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(state);
+	const hasCarrier = require_annotation_state.hasDelegatedAnnotationCarrier(state);
 	try {
-		const result = parser.complete(state, exec);
-		if (!result.success && require_annotation_state.hasDelegatedAnnotationCarrier(state)) return normalizeOptionalLikeCompleteResult(parser.complete(fallbackState, exec));
-		return normalizeOptionalLikeCompleteResult(result);
+		return normalizeOptionalLikeCompleteResult(parser.complete(state, exec));
 	} catch (error) {
-		if (!require_annotation_state.hasDelegatedAnnotationCarrier(state)) throw error;
+		if (!hasCarrier) throw error;
+		const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(state);
 		return normalizeOptionalLikeCompleteResult(parser.complete(fallbackState, exec));
 	}
 }
 async function completeOptionalLikeAsync(parser, state, exec) {
-	const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(state);
+	const hasCarrier = require_annotation_state.hasDelegatedAnnotationCarrier(state);
 	try {
-		const result = await parser.complete(state, exec);
-		if (!result.success && require_annotation_state.hasDelegatedAnnotationCarrier(state)) return normalizeOptionalLikeCompleteResult(await parser.complete(fallbackState, exec));
-		return normalizeOptionalLikeCompleteResult(result);
+		return normalizeOptionalLikeCompleteResult(await parser.complete(state, exec));
 	} catch (error) {
-		if (!require_annotation_state.hasDelegatedAnnotationCarrier(state)) throw error;
+		if (!hasCarrier) throw error;
+		const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(state);
 		return normalizeOptionalLikeCompleteResult(await parser.complete(fallbackState, exec));
 	}
 }
 function normalizeOptionalLikePhase2Seed(seed) {
 	return seed == null ? null : {
 		...seed,
-		value: require_annotation_state.normalizeDelegatedAnnotationState(seed.value)
+		value: require_annotation_state.normalizeNestedDelegatedAnnotationState(seed.value)
 	};
 }
 function extractOptionalLikePhase2Seed(parser, state, exec) {
 	if (!Array.isArray(state) && !(state != null && typeof state === "object")) return require_mode_dispatch.wrapForMode(parser.$mode, null);
 	const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
-	const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(innerState);
+	const hasCarrier = require_annotation_state.hasDelegatedAnnotationCarrier(innerState);
 	return require_mode_dispatch.dispatchByMode(parser.$mode, () => {
 		try {
-			const seed = require_phase2_seed.completeOrExtractPhase2Seed(parser, innerState, exec);
-			if (seed == null && require_annotation_state.hasDelegatedAnnotationCarrier(innerState)) return normalizeOptionalLikePhase2Seed(require_phase2_seed.completeOrExtractPhase2Seed(parser, fallbackState, exec));
+			const result = parser.complete(innerState, exec);
+			if (result.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(result));
+			const seed = require_phase2_seed.extractPhase2Seed(parser, innerState, exec);
+			if (seed == null && hasCarrier) {
+				const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(innerState);
+				return normalizeOptionalLikePhase2Seed(require_phase2_seed.extractPhase2Seed(parser, fallbackState, exec));
+			}
 			return normalizeOptionalLikePhase2Seed(seed);
 		} catch (error) {
-			if (!require_annotation_state.hasDelegatedAnnotationCarrier(innerState)) throw error;
-			return normalizeOptionalLikePhase2Seed(require_phase2_seed.completeOrExtractPhase2Seed(parser, fallbackState, exec));
+			if (!hasCarrier) throw error;
+			const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(innerState);
+			const result = parser.complete(fallbackState, exec);
+			if (result.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(result));
+			return normalizeOptionalLikePhase2Seed(require_phase2_seed.extractPhase2Seed(parser, fallbackState, exec));
 		}
 	}, async () => {
 		try {
-			const seed = await require_phase2_seed.completeOrExtractPhase2Seed(parser, innerState, exec);
-			if (seed == null && require_annotation_state.hasDelegatedAnnotationCarrier(innerState)) return normalizeOptionalLikePhase2Seed(await require_phase2_seed.completeOrExtractPhase2Seed(parser, fallbackState, exec));
+			const result = await parser.complete(innerState, exec);
+			if (result.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(result));
+			const seed = await require_phase2_seed.extractPhase2Seed(parser, innerState, exec);
+			if (seed == null && hasCarrier) {
+				const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(innerState);
+				return normalizeOptionalLikePhase2Seed(await require_phase2_seed.extractPhase2Seed(parser, fallbackState, exec));
+			}
 			return normalizeOptionalLikePhase2Seed(seed);
 		} catch (error) {
-			if (!require_annotation_state.hasDelegatedAnnotationCarrier(innerState)) throw error;
-			return normalizeOptionalLikePhase2Seed(await require_phase2_seed.completeOrExtractPhase2Seed(parser, fallbackState, exec));
+			if (!hasCarrier) throw error;
+			const fallbackState = require_annotation_state.normalizeDelegatedAnnotationState(innerState);
+			const result = await parser.complete(fallbackState, exec);
+			if (result.success) return normalizeOptionalLikePhase2Seed(require_phase2_seed.phase2SeedFromValueResult(result));
+			return normalizeOptionalLikePhase2Seed(await require_phase2_seed.extractPhase2Seed(parser, fallbackState, exec));
 		}
 	});
 }

package/dist/modifiers.js

@@ -2,9 +2,9 @@ import { annotateFreshArray, annotationKey, getAnnotations, inheritAnnotations,
 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 } from "./phase2-seed.js";
+import { completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult } from "./phase2-seed.js";
 import { defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, unmatchedNonCliDependencySourceStateMarker } from "./parser.js";
-import { getDelegatedAnnotationState, hasDelegatedAnnotationCarrier, normalizeDelegatedAnnotationState } from "./annotation-state.js";
+import { getDelegatedAnnotationState, hasDelegatedAnnotationCarrier, normalizeDelegatedAnnotationState, normalizeNestedDelegatedAnnotationState } from "./annotation-state.js";
 
 //#region src/modifiers.ts
 function withChildExecPath(exec, segment) {
@@ -85,58 +85,72 @@ function isPromiseLike(value) {
 function normalizeOptionalLikeCompleteResult(result) {
 	return result.success ? {
 		...result,
-		value: normalizeDelegatedAnnotationState(result.value)
+		value: normalizeNestedDelegatedAnnotationState(result.value)
 	} : result;
 }
 function completeOptionalLikeSync(parser, state, exec) {
-	const fallbackState = normalizeDelegatedAnnotationState(state);
+	const hasCarrier = hasDelegatedAnnotationCarrier(state);
 	try {
-		const result = parser.complete(state, exec);
-		if (!result.success && hasDelegatedAnnotationCarrier(state)) return normalizeOptionalLikeCompleteResult(parser.complete(fallbackState, exec));
-		return normalizeOptionalLikeCompleteResult(result);
+		return normalizeOptionalLikeCompleteResult(parser.complete(state, exec));
 	} catch (error) {
-		if (!hasDelegatedAnnotationCarrier(state)) throw error;
+		if (!hasCarrier) throw error;
+		const fallbackState = normalizeDelegatedAnnotationState(state);
 		return normalizeOptionalLikeCompleteResult(parser.complete(fallbackState, exec));
 	}
 }
 async function completeOptionalLikeAsync(parser, state, exec) {
-	const fallbackState = normalizeDelegatedAnnotationState(state);
+	const hasCarrier = hasDelegatedAnnotationCarrier(state);
 	try {
-		const result = await parser.complete(state, exec);
-		if (!result.success && hasDelegatedAnnotationCarrier(state)) return normalizeOptionalLikeCompleteResult(await parser.complete(fallbackState, exec));
-		return normalizeOptionalLikeCompleteResult(result);
+		return normalizeOptionalLikeCompleteResult(await parser.complete(state, exec));
 	} catch (error) {
-		if (!hasDelegatedAnnotationCarrier(state)) throw error;
+		if (!hasCarrier) throw error;
+		const fallbackState = normalizeDelegatedAnnotationState(state);
 		return normalizeOptionalLikeCompleteResult(await parser.complete(fallbackState, exec));
 	}
 }
 function normalizeOptionalLikePhase2Seed(seed) {
 	return seed == null ? null : {
 		...seed,
-		value: normalizeDelegatedAnnotationState(seed.value)
+		value: normalizeNestedDelegatedAnnotationState(seed.value)
 	};
 }
 function extractOptionalLikePhase2Seed(parser, state, exec) {
 	if (!Array.isArray(state) && !(state != null && typeof state === "object")) return wrapForMode(parser.$mode, null);
 	const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
-	const fallbackState = normalizeDelegatedAnnotationState(innerState);
+	const hasCarrier = hasDelegatedAnnotationCarrier(innerState);
 	return dispatchByMode(parser.$mode, () => {
 		try {
-			const seed = completeOrExtractPhase2Seed(parser, innerState, exec);
-			if (seed == null && hasDelegatedAnnotationCarrier(innerState)) return normalizeOptionalLikePhase2Seed(completeOrExtractPhase2Seed(parser, fallbackState, exec));
+			const result = parser.complete(innerState, exec);
+			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result));
+			const seed = extractPhase2Seed(parser, innerState, exec);
+			if (seed == null && hasCarrier) {
+				const fallbackState = normalizeDelegatedAnnotationState(innerState);
+				return normalizeOptionalLikePhase2Seed(extractPhase2Seed(parser, fallbackState, exec));
+			}
 			return normalizeOptionalLikePhase2Seed(seed);
 		} catch (error) {
-			if (!hasDelegatedAnnotationCarrier(innerState)) throw error;
-			return normalizeOptionalLikePhase2Seed(completeOrExtractPhase2Seed(parser, fallbackState, exec));
+			if (!hasCarrier) throw error;
+			const fallbackState = normalizeDelegatedAnnotationState(innerState);
+			const result = parser.complete(fallbackState, exec);
+			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result));
+			return normalizeOptionalLikePhase2Seed(extractPhase2Seed(parser, fallbackState, exec));
 		}
 	}, async () => {
 		try {
-			const seed = await completeOrExtractPhase2Seed(parser, innerState, exec);
-			if (seed == null && hasDelegatedAnnotationCarrier(innerState)) return normalizeOptionalLikePhase2Seed(await completeOrExtractPhase2Seed(parser, fallbackState, exec));
+			const result = await parser.complete(innerState, exec);
+			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result));
+			const seed = await extractPhase2Seed(parser, innerState, exec);
+			if (seed == null && hasCarrier) {
+				const fallbackState = normalizeDelegatedAnnotationState(innerState);
+				return normalizeOptionalLikePhase2Seed(await extractPhase2Seed(parser, fallbackState, exec));
+			}
 			return normalizeOptionalLikePhase2Seed(seed);
 		} catch (error) {
-			if (!hasDelegatedAnnotationCarrier(innerState)) throw error;
-			return normalizeOptionalLikePhase2Seed(await completeOrExtractPhase2Seed(parser, fallbackState, exec));
+			if (!hasCarrier) throw error;
+			const fallbackState = normalizeDelegatedAnnotationState(innerState);
+			const result = await parser.complete(fallbackState, exec);
+			if (result.success) return normalizeOptionalLikePhase2Seed(phase2SeedFromValueResult(result));
+			return normalizeOptionalLikePhase2Seed(await extractPhase2Seed(parser, fallbackState, exec));
 		}
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1891+f32e7ae2",
+  "version": "1.0.0-dev.1895+42aa2942",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",