@optique/core 1.0.0-dev.1616 → 1.0.0-dev.1659

package/dist/primitives.js

@@ -1,13 +1,14 @@
 import { annotateFreshArray, getAnnotations } from "./annotations.js";
 import { message, metavar, optionName, optionNames, text, valueSet } from "./message.js";
-import { createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, dependencyId, getDefaultValuesFunction, getDependencyIds, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, suggestWithDependency } from "./dependency.js";
-import { dispatchIterableByMode } from "./mode-dispatch.js";
+import { getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDerivedValueParser, suggestWithDependency } from "./dependency.js";
 import { validateCommandNames, validateOptionNames } from "./validate.js";
 import { extractOptionNames, isDocHidden, isSuggestionHidden } from "./usage.js";
+import { dispatchByMode, dispatchIterableByMode } from "./mode-dispatch.js";
+import { extractDependencyMetadata } from "./dependency-metadata.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, findSimilar } from "./suggestion.js";
 import { extractLeadingCommandNames } from "./usage-internals.js";
-import { extractDependencyMetadata } from "./dependency-metadata.js";
 import { isValueParser } from "./valueparser.js";
+import { replayDerivedParser, replayDerivedParserAsync } from "./dependency-runtime.js";
 
 //#region src/primitives.ts
 /**
@@ -15,23 +16,124 @@ import { isValueParser } from "./valueparser.js";
 * do not match any specific name at the first buffer position.
 */
 const EMPTY_LEADING_NAMES = /* @__PURE__ */ new Set();
+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,
+		preCompletedByParser: child.preCompletedByParser ?? parent.preCompletedByParser,
+		excludedSourceFields: child.excludedSourceFields ?? parent.excludedSourceFields
+	};
+}
+function withChildContext(context, segment, state, usage) {
+	const exec = withChildExecPath(context.exec, segment);
+	const dependencyRegistry = context.dependencyRegistry ?? exec?.dependencyRegistry;
+	return {
+		...context,
+		state,
+		...usage != null ? { usage } : {},
+		...exec != null ? {
+			exec: dependencyRegistry === exec.dependencyRegistry ? exec : {
+				...exec,
+				dependencyRegistry
+			},
+			dependencyRegistry
+		} : {}
+	};
+}
 function hasParsedOptionValue(state, valueParser) {
-	if (valueParser != null) return isDeferredParseState(state) || isDependencySourceState(state) || state != null && "success" in state && state.success;
+	if (valueParser != null) return state != null && typeof state === "object" && "success" in state && typeof state.success === "boolean";
 	return state != null && "success" in state && state.success && state.value === true;
 }
 /**
-* Helper function to create the appropriate state for an option value.
-* - If the value parser is a DerivedValueParser, wraps the result in a DeferredParseState
-*   to allow later resolution with actual dependency values.
-* - If the value parser is a DependencySource, wraps the result in a DependencySourceState
-*   so that it can be matched with DeferredParseState during resolution.
+* Helper function to create the stored state for an option or argument value.
+*
+* Primitive parsers now keep only the plain parse result as their local state.
+* Any dependency-aware replay information is recorded separately in the
+* execution trace.
 * @internal
 */
-function createOptionParseState(rawInput, valueParser, parseResult) {
-	if (isDerivedValueParser(valueParser)) return createDeferredParseState(rawInput, valueParser, parseResult);
-	if (isDependencySource(valueParser)) return createDependencySourceState(parseResult, valueParser[dependencyId]);
+function createOptionParseState(parseResult) {
 	return parseResult;
 }
+function buildTraceEntry(kind, rawInput, consumed, valueParser, parseResult, optionNames$1) {
+	const entry = {
+		kind,
+		rawInput,
+		consumed,
+		preliminaryResult: parseResult,
+		...optionNames$1 != null ? { optionNames: optionNames$1 } : {},
+		metavar: valueParser.metavar
+	};
+	if (isDerivedValueParser(valueParser)) {
+		const defaults = getSnapshottedDefaultDependencyValues(parseResult);
+		if (defaults != null) return {
+			...entry,
+			defaultDependencyValues: defaults
+		};
+	}
+	return entry;
+}
+function recordTrace(context, entry) {
+	if (context.exec?.trace == null) return context;
+	const trace = context.exec.trace.set(context.exec.path, entry);
+	return {
+		...context,
+		trace,
+		exec: {
+			...context.exec,
+			trace
+		}
+	};
+}
+function resolveDerivedCompletionSync(derivedMetadata, state, exec) {
+	if (derivedMetadata?.derived == null || exec?.dependencyRuntime == null) return state;
+	const traceEntry = exec.trace?.get(exec.path);
+	if (traceEntry?.rawInput == null) return traceEntry?.preliminaryResult ?? state;
+	if (traceEntry.preliminaryResult != null) {
+		const resolution = exec.dependencyRuntime.resolveDependencies({
+			dependencyIds: derivedMetadata.derived.dependencyIds,
+			defaultValues: traceEntry.defaultDependencyValues
+		});
+		if (resolution.kind === "resolved" && resolution.usedDefaults.length > 0 && resolution.usedDefaults.every((used) => used)) return traceEntry.preliminaryResult;
+	}
+	const replayed = replayDerivedParser({
+		path: exec.path,
+		parser: { dependencyMetadata: { derived: derivedMetadata.derived } },
+		state,
+		defaultDependencyValues: traceEntry.defaultDependencyValues
+	}, traceEntry.rawInput, exec.dependencyRuntime);
+	return replayed ?? traceEntry.preliminaryResult ?? state;
+}
+async function resolveDerivedCompletionAsync(derivedMetadata, state, exec) {
+	if (derivedMetadata?.derived == null || exec?.dependencyRuntime == null) return state;
+	const traceEntry = exec.trace?.get(exec.path);
+	if (traceEntry?.rawInput == null) return traceEntry?.preliminaryResult ?? state;
+	if (traceEntry.preliminaryResult != null) {
+		const resolution = exec.dependencyRuntime.resolveDependencies({
+			dependencyIds: derivedMetadata.derived.dependencyIds,
+			defaultValues: traceEntry.defaultDependencyValues
+		});
+		if (resolution.kind === "resolved" && resolution.usedDefaults.length > 0 && resolution.usedDefaults.every((used) => used)) return traceEntry.preliminaryResult;
+	}
+	const replayed = await replayDerivedParserAsync({
+		path: exec.path,
+		parser: { dependencyMetadata: { derived: derivedMetadata.derived } },
+		state,
+		defaultDependencyValues: traceEntry.defaultDependencyValues
+	}, traceEntry.rawInput, exec.dependencyRuntime);
+	return replayed ?? traceEntry.preliminaryResult ?? state;
+}
 /**
 * Creates a parser that always succeeds without consuming any input and
 * produces a constant value of the type {@link T}.
@@ -130,12 +232,13 @@ function fail() {
 * if the parser is a derived parser and dependency values are available.
 * @internal
 */
-function* getSuggestionsWithDependency(valueParser, prefix, dependencyRegistry) {
+function* getSuggestionsWithDependency(valueParser, prefix, dependencyRegistry, exec) {
 	if (!valueParser.suggest) return;
 	if (isDerivedValueParser(valueParser) && suggestWithDependency in valueParser) {
 		const derived = valueParser;
 		const suggestWithDep = derived[suggestWithDependency];
 		if (suggestWithDep && dependencyRegistry) {
+			const dependencyRuntime = exec?.dependencyRuntime;
 			const depIds = getDependencyIds(derived);
 			const defaultsFn = getDefaultValuesFunction(derived);
 			const defaults = defaultsFn?.();
@@ -146,7 +249,8 @@ function* getSuggestionsWithDependency(valueParser, prefix, dependencyRegistry)
 				if (dependencyRegistry.has(depId)) {
 					dependencyValues.push(dependencyRegistry.get(depId));
 					hasAnyValue = true;
-				} else if (defaults && i < defaults.length) dependencyValues.push(defaults[i]);
+				} else if (dependencyRuntime?.isSourceFailed(depId)) return;
+				else if (defaults && i < defaults.length) dependencyValues.push(defaults[i]);
 				else {
 					yield* valueParser.suggest(prefix);
 					return;
@@ -173,7 +277,7 @@ function* suggestOptionSync(optionNames$1, valueParser, hidden, context, prefix)
 		const valuePart = prefix.slice(equalsIndex + 1);
 		if (optionNames$1.includes(optionPart)) {
 			if (valueParser && valueParser.suggest) {
-				const valueSuggestions = getSuggestionsWithDependency(valueParser, valuePart, context.dependencyRegistry);
+				const valueSuggestions = getSuggestionsWithDependency(valueParser, valuePart, context.dependencyRegistry, context.exec);
 				for (const suggestion of valueSuggestions) if (suggestion.kind === "literal") yield {
 					kind: "literal",
 					text: `${optionPart}=${suggestion.text}`,
@@ -202,8 +306,8 @@ function* suggestOptionSync(optionNames$1, valueParser, hidden, context, prefix)
 			if (context.buffer.length > 0) {
 				const lastToken = context.buffer[context.buffer.length - 1];
 				if (optionNames$1.includes(lastToken)) shouldSuggestValues = true;
-			} else if (context.state === void 0 && context.buffer.length === 0) shouldSuggestValues = true;
-			if (shouldSuggestValues) yield* getSuggestionsWithDependency(valueParser, prefix, context.dependencyRegistry);
+			} else if (context.state === void 0 && context.buffer.length === 0 && (context.exec?.path?.length ?? 0) === 0 && !(prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/"))) shouldSuggestValues = true;
+			if (shouldSuggestValues) yield* getSuggestionsWithDependency(valueParser, prefix, context.dependencyRegistry, context.exec);
 		}
 	}
 }
@@ -212,12 +316,13 @@ function* suggestOptionSync(optionNames$1, valueParser, hidden, context, prefix)
 * if the parser is a derived parser and dependency values are available.
 * @internal
 */
-async function* getSuggestionsWithDependencyAsync(valueParser, prefix, dependencyRegistry) {
+async function* getSuggestionsWithDependencyAsync(valueParser, prefix, dependencyRegistry, exec) {
 	if (!valueParser.suggest) return;
 	if (isDerivedValueParser(valueParser) && suggestWithDependency in valueParser) {
 		const derived = valueParser;
 		const suggestWithDep = derived[suggestWithDependency];
 		if (suggestWithDep && dependencyRegistry) {
+			const dependencyRuntime = exec?.dependencyRuntime;
 			const depIds = getDependencyIds(derived);
 			const defaultsFn = getDefaultValuesFunction(derived);
 			const defaults = defaultsFn?.();
@@ -228,7 +333,8 @@ async function* getSuggestionsWithDependencyAsync(valueParser, prefix, dependenc
 				if (dependencyRegistry.has(depId)) {
 					dependencyValues.push(dependencyRegistry.get(depId));
 					hasAnyValue = true;
-				} else if (defaults && i < defaults.length) dependencyValues.push(defaults[i]);
+				} else if (dependencyRuntime?.isSourceFailed(depId)) return;
+				else if (defaults && i < defaults.length) dependencyValues.push(defaults[i]);
 				else {
 					for await (const suggestion of valueParser.suggest(prefix)) yield suggestion;
 					return;
@@ -255,7 +361,7 @@ async function* suggestOptionAsync(optionNames$1, valueParser, hidden, context,
 		const valuePart = prefix.slice(equalsIndex + 1);
 		if (optionNames$1.includes(optionPart)) {
 			if (valueParser && valueParser.suggest) {
-				const valueSuggestions = getSuggestionsWithDependencyAsync(valueParser, valuePart, context.dependencyRegistry);
+				const valueSuggestions = getSuggestionsWithDependencyAsync(valueParser, valuePart, context.dependencyRegistry, context.exec);
 				for await (const suggestion of valueSuggestions) if (suggestion.kind === "literal") yield {
 					kind: "literal",
 					text: `${optionPart}=${suggestion.text}`,
@@ -284,8 +390,8 @@ async function* suggestOptionAsync(optionNames$1, valueParser, hidden, context,
 			if (context.buffer.length > 0) {
 				const lastToken = context.buffer[context.buffer.length - 1];
 				if (optionNames$1.includes(lastToken)) shouldSuggestValues = true;
-			} else if (context.state === void 0 && context.buffer.length === 0) shouldSuggestValues = true;
-			if (shouldSuggestValues) for await (const suggestion of getSuggestionsWithDependencyAsync(valueParser, prefix, context.dependencyRegistry)) yield suggestion;
+			} else if (context.state === void 0 && context.buffer.length === 0 && (context.exec?.path?.length ?? 0) === 0 && !(prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/"))) shouldSuggestValues = true;
+			if (shouldSuggestValues) for await (const suggestion of getSuggestionsWithDependencyAsync(valueParser, prefix, context.dependencyRegistry, context.exec)) yield suggestion;
 		}
 	}
 }
@@ -293,17 +399,17 @@ async function* suggestOptionAsync(optionNames$1, valueParser, hidden, context,
 * Internal sync helper for argument suggest functionality.
 * @internal
 */
-function* suggestArgumentSync(valueParser, hidden, prefix, dependencyRegistry) {
+function* suggestArgumentSync(valueParser, hidden, prefix, dependencyRegistry, exec) {
 	if (hidden) return;
-	if (valueParser.suggest) yield* getSuggestionsWithDependency(valueParser, prefix, dependencyRegistry);
+	if (valueParser.suggest) yield* getSuggestionsWithDependency(valueParser, prefix, dependencyRegistry, exec);
 }
 /**
 * Internal async helper for argument suggest functionality.
 * @internal
 */
-async function* suggestArgumentAsync(valueParser, hidden, prefix, dependencyRegistry) {
+async function* suggestArgumentAsync(valueParser, hidden, prefix, dependencyRegistry, exec) {
 	if (hidden) return;
-	if (valueParser.suggest) yield* getSuggestionsWithDependencyAsync(valueParser, prefix, dependencyRegistry);
+	if (valueParser.suggest) yield* getSuggestionsWithDependencyAsync(valueParser, prefix, dependencyRegistry, exec);
 }
 function option(...args) {
 	const lastArg = args.at(-1);
@@ -330,6 +436,8 @@ function option(...args) {
 	validateOptionNames(optionNames$1, "Option");
 	const mode = valueParser?.$mode ?? "sync";
 	const isAsync = mode === "async";
+	const syncValueParser = valueParser;
+	const dependencyMetadata = valueParser != null ? extractDependencyMetadata(valueParser) : void 0;
 	const result = {
 		$mode: mode,
 		$valueType: [],
@@ -353,10 +461,7 @@ function option(...args) {
 		initialState: valueParser == null ? {
 			success: true,
 			value: false
-		} : isDependencySource(valueParser) ? createPendingDependencySourceState(valueParser[dependencyId]) : {
-			success: false,
-			error: options.errors?.missing ? typeof options.errors.missing === "function" ? options.errors.missing(optionNames$1) : options.errors.missing : message`Missing option ${optionNames(optionNames$1)}.`
-		},
+		} : void 0,
 		parse(context) {
 			if (context.optionsTerminated) return {
 				success: false,
@@ -402,25 +507,31 @@ function option(...args) {
 					error: message`Option ${optionName(context.buffer[0])} requires a value, but got no value.`
 				};
 				const rawInput = context.buffer[1];
-				const parseResultOrPromise = valueParser.parse(rawInput);
-				if (isAsync) return parseResultOrPromise.then((parseResult) => ({
-					success: true,
-					next: {
-						...context,
-						state: createOptionParseState(rawInput, valueParser, parseResult),
-						buffer: context.buffer.slice(2)
-					},
-					consumed: context.buffer.slice(0, 2)
-				}));
-				return {
-					success: true,
-					next: {
-						...context,
-						state: createOptionParseState(rawInput, valueParser, parseResultOrPromise),
-						buffer: context.buffer.slice(2)
-					},
-					consumed: context.buffer.slice(0, 2)
-				};
+				return dispatchByMode(mode, () => {
+					const parseResult = syncValueParser.parse(rawInput);
+					const next = recordTrace(context, buildTraceEntry("option-value", rawInput, context.buffer.slice(0, 2), syncValueParser, parseResult, optionNames$1));
+					return {
+						success: true,
+						next: {
+							...next,
+							state: createOptionParseState(parseResult),
+							buffer: context.buffer.slice(2)
+						},
+						consumed: context.buffer.slice(0, 2)
+					};
+				}, async () => {
+					const parseResult = await valueParser.parse(rawInput);
+					const next = recordTrace(context, buildTraceEntry("option-value", rawInput, context.buffer.slice(0, 2), valueParser, parseResult, optionNames$1));
+					return {
+						success: true,
+						next: {
+							...next,
+							state: createOptionParseState(parseResult),
+							buffer: context.buffer.slice(2)
+						},
+						consumed: context.buffer.slice(0, 2)
+					};
+				});
 			}
 			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) {
@@ -439,25 +550,31 @@ function option(...args) {
 					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}.`
 				};
-				const parseResultOrPromise = valueParser.parse(rawInput);
-				if (isAsync) return parseResultOrPromise.then((parseResult) => ({
-					success: true,
-					next: {
-						...context,
-						state: createOptionParseState(rawInput, valueParser, parseResult),
-						buffer: context.buffer.slice(1)
-					},
-					consumed: context.buffer.slice(0, 1)
-				}));
-				return {
-					success: true,
-					next: {
-						...context,
-						state: createOptionParseState(rawInput, valueParser, parseResultOrPromise),
-						buffer: context.buffer.slice(1)
-					},
-					consumed: context.buffer.slice(0, 1)
-				};
+				return dispatchByMode(mode, () => {
+					const parseResult = syncValueParser.parse(rawInput);
+					const next = recordTrace(context, buildTraceEntry("option-value", rawInput, context.buffer.slice(0, 1), syncValueParser, parseResult, optionNames$1));
+					return {
+						success: true,
+						next: {
+							...next,
+							state: createOptionParseState(parseResult),
+							buffer: context.buffer.slice(1)
+						},
+						consumed: context.buffer.slice(0, 1)
+					};
+				}, async () => {
+					const parseResult = await valueParser.parse(rawInput);
+					const next = recordTrace(context, buildTraceEntry("option-value", rawInput, context.buffer.slice(0, 1), valueParser, parseResult, optionNames$1));
+					return {
+						success: true,
+						next: {
+							...next,
+							state: createOptionParseState(parseResult),
+							buffer: context.buffer.slice(1)
+						},
+						consumed: context.buffer.slice(0, 1)
+					};
+				});
 			}
 			if (valueParser == null) {
 				const shortOptions = optionNames$1.filter((name) => name.match(/^-[^-]$/));
@@ -501,39 +618,33 @@ function option(...args) {
 				error: createErrorWithSuggestions(baseError, invalidOption, context.usage, "option")
 			};
 		},
-		complete(state, _exec) {
-			if (state == null) return valueParser == null ? {
+		complete(state, exec) {
+			const formatInvalidValueError = (error) => options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(error) : options.errors.invalidValue : message`${optionNames(optionNames$1)}: ${error}`;
+			const missing = valueParser == null ? {
 				success: true,
 				value: false
 			} : {
 				success: false,
 				error: options.errors?.missing ? typeof options.errors.missing === "function" ? options.errors.missing(optionNames$1) : options.errors.missing : message`Missing option ${optionNames(optionNames$1)}.`
 			};
-			if (isPendingDependencySourceState(state)) return {
-				success: false,
-				error: options.errors?.missing ? typeof options.errors.missing === "function" ? options.errors.missing(optionNames$1) : options.errors.missing : message`Missing option ${optionNames(optionNames$1)}.`
-			};
-			if (isDeferredParseState(state)) {
-				const preliminaryResult = state.preliminaryResult;
-				if (preliminaryResult.success) return preliminaryResult;
-				return {
+			const completeSync = () => {
+				if (state == null) return missing;
+				const resolvedState = valueParser != null && dependencyMetadata?.derived != null ? resolveDerivedCompletionSync(dependencyMetadata, state, exec) : state;
+				return resolvedState.success ? resolvedState : {
 					success: false,
-					error: options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(preliminaryResult.error) : options.errors.invalidValue : message`${optionNames(optionNames$1)}: ${preliminaryResult.error}`
+					error: formatInvalidValueError(resolvedState.error)
 				};
-			}
-			if (isDependencySourceState(state)) {
-				const result$1 = state.result;
-				if (result$1.success) return result$1;
-				return {
+			};
+			const completeAsync = async () => {
+				if (state == null) return missing;
+				if (valueParser == null || dependencyMetadata?.derived == null) return completeSync();
+				const resolved = await resolveDerivedCompletionAsync(dependencyMetadata, state, exec);
+				return resolved.success ? resolved : {
 					success: false,
-					error: options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(result$1.error) : options.errors.invalidValue : message`${optionNames(optionNames$1)}: ${result$1.error}`
+					error: formatInvalidValueError(resolved.error)
 				};
-			}
-			if (state.success) return state;
-			return {
-				success: false,
-				error: options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(state.error) : options.errors.invalidValue : message`${optionNames(optionNames$1)}: ${state.error}`
 			};
+			return dispatchByMode(mode, completeSync, completeAsync);
 		},
 		suggest(context, prefix) {
 			if (isAsync) return suggestOptionAsync(optionNames$1, valueParser, isSuggestionHidden(options.hidden), context, prefix);
@@ -599,10 +710,11 @@ function option(...args) {
 		enumerable: false,
 		writable: false
 	});
-	if (valueParser != null) {
-		const depMeta = extractDependencyMetadata(valueParser);
-		if (depMeta != null) result.dependencyMetadata = depMeta;
-	}
+	if (dependencyMetadata != null) Object.defineProperty(result, "dependencyMetadata", {
+		value: dependencyMetadata,
+		configurable: true,
+		enumerable: false
+	});
 	return result;
 }
 /**
@@ -820,6 +932,8 @@ function flag(...args) {
 */
 function argument(valueParser, options = {}) {
 	const isAsync = valueParser.$mode === "async";
+	const syncValueParser = valueParser;
+	const dependencyMetadata = extractDependencyMetadata(valueParser);
 	const optionPattern = /^--?[a-z0-9-]+$/i;
 	const term = {
 		type: "argument",
@@ -864,59 +978,63 @@ function argument(valueParser, options = {}) {
 				error: options.errors?.multiple ? typeof options.errors.multiple === "function" ? options.errors.multiple(valueParser.metavar) : options.errors.multiple : message`The argument ${metavar(valueParser.metavar)} cannot be used multiple times.`
 			};
 			const rawInput = context.buffer[i];
-			const parseResultOrPromise = valueParser.parse(rawInput);
-			if (isAsync) return parseResultOrPromise.then((parseResult) => ({
-				success: true,
-				next: {
-					...context,
-					buffer: context.buffer.slice(i + 1),
-					state: createOptionParseState(rawInput, valueParser, parseResult),
-					optionsTerminated
-				},
-				consumed: context.buffer.slice(0, i + 1)
-			}));
-			return {
-				success: true,
-				next: {
-					...context,
-					buffer: context.buffer.slice(i + 1),
-					state: createOptionParseState(rawInput, valueParser, parseResultOrPromise),
-					optionsTerminated
-				},
-				consumed: context.buffer.slice(0, i + 1)
-			};
+			return dispatchByMode(valueParser.$mode, () => {
+				const parseResult = syncValueParser.parse(rawInput);
+				const next = recordTrace(context, buildTraceEntry("argument-value", rawInput, context.buffer.slice(0, i + 1), syncValueParser, parseResult));
+				return {
+					success: true,
+					next: {
+						...next,
+						buffer: context.buffer.slice(i + 1),
+						state: createOptionParseState(parseResult),
+						optionsTerminated
+					},
+					consumed: context.buffer.slice(0, i + 1)
+				};
+			}, async () => {
+				const parseResult = await valueParser.parse(rawInput);
+				const next = recordTrace(context, buildTraceEntry("argument-value", rawInput, context.buffer.slice(0, i + 1), valueParser, parseResult));
+				return {
+					success: true,
+					next: {
+						...next,
+						buffer: context.buffer.slice(i + 1),
+						state: createOptionParseState(parseResult),
+						optionsTerminated
+					},
+					consumed: context.buffer.slice(0, i + 1)
+				};
+			});
 		},
-		complete(state, _exec) {
-			if (state == null) return {
+		complete(state, exec) {
+			const formatInvalidValueError = (error) => options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(error) : options.errors.invalidValue : message`${metavar(valueParser.metavar)}: ${error}`;
+			const missing = {
 				success: false,
 				error: options.errors?.endOfInput ?? message`Expected a ${metavar(valueParser.metavar)}, but too few arguments.`
 			};
-			if (isDeferredParseState(state)) {
-				const preliminaryResult = state.preliminaryResult;
-				if (preliminaryResult.success) return preliminaryResult;
-				return {
+			const completeSync = () => {
+				if (state == null) return missing;
+				const resolvedState = dependencyMetadata?.derived != null ? resolveDerivedCompletionSync(dependencyMetadata, state, exec) : state;
+				return resolvedState.success ? resolvedState : {
 					success: false,
-					error: options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(preliminaryResult.error) : options.errors.invalidValue : message`${metavar(valueParser.metavar)}: ${preliminaryResult.error}`
+					error: formatInvalidValueError(resolvedState.error)
 				};
-			}
-			if (isDependencySourceState(state)) {
-				const result$1 = state.result;
-				if (result$1.success) return result$1;
-				return {
+			};
+			const completeAsync = async () => {
+				if (state == null) return missing;
+				if (dependencyMetadata?.derived == null) return completeSync();
+				const resolved = await resolveDerivedCompletionAsync(dependencyMetadata, state, exec);
+				return resolved.success ? resolved : {
 					success: false,
-					error: options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(result$1.error) : options.errors.invalidValue : message`${metavar(valueParser.metavar)}: ${result$1.error}`
+					error: formatInvalidValueError(resolved.error)
 				};
-			}
-			if (state.success) return state;
-			return {
-				success: false,
-				error: options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(state.error) : options.errors.invalidValue : message`${metavar(valueParser.metavar)}: ${state.error}`
 			};
+			return dispatchByMode(valueParser.$mode, completeSync, completeAsync);
 		},
 		suggest(context, prefix) {
 			if (context.state != null) return dispatchIterableByMode(valueParser.$mode, function* () {}, async function* () {});
-			if (isAsync) return suggestArgumentAsync(valueParser, isSuggestionHidden(options.hidden), prefix, context.dependencyRegistry);
-			return suggestArgumentSync(valueParser, isSuggestionHidden(options.hidden), prefix, context.dependencyRegistry);
+			if (isAsync) return suggestArgumentAsync(valueParser, isSuggestionHidden(options.hidden), prefix, context.dependencyRegistry, context.exec);
+			return suggestArgumentSync(valueParser, isSuggestionHidden(options.hidden), prefix, context.dependencyRegistry, context.exec);
 		},
 		getDocFragments(_state, defaultValue) {
 			if (isDocHidden(options.hidden)) return {
@@ -968,8 +1086,11 @@ function argument(valueParser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
-	const depMeta = extractDependencyMetadata(valueParser);
-	if (depMeta != null) result.dependencyMetadata = depMeta;
+	if (dependencyMetadata != null) Object.defineProperty(result, "dependencyMetadata", {
+		value: dependencyMetadata,
+		configurable: true,
+		enumerable: false
+	});
 	return result;
 }
 function* suggestCommandSync(context, prefix, name, parser, options) {
@@ -980,14 +1101,8 @@ function* suggestCommandSync(context, prefix, name, parser, options) {
 			text: name,
 			...options.description && { description: options.description }
 		};
-	} else if (context.state[0] === "matched") yield* parser.suggest({
-		...context,
-		state: parser.initialState
-	}, prefix);
-	else if (context.state[0] === "parsing") yield* parser.suggest({
-		...context,
-		state: context.state[1]
-	}, prefix);
+	} else if (context.state[0] === "matched") yield* parser.suggest(withChildContext(context, name, parser.initialState, parser.usage), prefix);
+	else if (context.state[0] === "parsing") yield* parser.suggest(withChildContext(context, name, context.state[1], parser.usage), prefix);
 }
 async function* suggestCommandAsync(context, prefix, name, parser, options) {
 	if (isSuggestionHidden(options.hidden)) return;
@@ -998,16 +1113,10 @@ async function* suggestCommandAsync(context, prefix, name, parser, options) {
 			...options.description && { description: options.description }
 		};
 	} else if (context.state[0] === "matched") {
-		const suggestions = parser.suggest({
-			...context,
-			state: parser.initialState
-		}, prefix);
+		const suggestions = parser.suggest(withChildContext(context, name, parser.initialState, parser.usage), prefix);
 		for await (const s of suggestions) yield s;
 	} else if (context.state[0] === "parsing") {
-		const suggestions = parser.suggest({
-			...context,
-			state: context.state[1]
-		}, prefix);
+		const suggestions = parser.suggest(withChildContext(context, name, context.state[1], parser.usage), prefix);
 		for await (const s of suggestions) yield s;
 	}
 }
@@ -1030,6 +1139,8 @@ async function* suggestCommandAsync(context, prefix, name, parser, options) {
 function command(name, parser, options = {}) {
 	validateCommandNames([name], "Command");
 	const isAsync = parser.$mode === "async";
+	const syncInnerParser = parser;
+	const asyncInnerParser = parser;
 	const result = {
 		[Symbol.for("@optique/core/commandParser")]: true,
 		$mode: parser.$mode,
@@ -1045,6 +1156,16 @@ function command(name, parser, options = {}) {
 		leadingNames: new Set([name]),
 		acceptingAnyToken: false,
 		initialState: void 0,
+		getSuggestRuntimeNodes(state, path) {
+			if (state === void 0) return [];
+			const childState = state[0] === "matched" ? parser.initialState : state[1];
+			const childPath = [...path, name];
+			return parser.getSuggestRuntimeNodes?.(childState, childPath) ?? (parser.dependencyMetadata?.source != null ? [{
+				path: childPath,
+				parser,
+				state: childState
+			}] : []);
+		},
 		parse(context) {
 			if (context.state === void 0) {
 				if (context.buffer.length < 1 || context.buffer[0] !== name) {
@@ -1087,23 +1208,25 @@ function command(name, parser, options = {}) {
 				};
 			} else if (context.state[0] === "matched" || context.state[0] === "parsing") {
 				const innerState = context.state[0] === "matched" ? parser.initialState : context.state[1];
-				const parseResultOrPromise = parser.parse({
-					...context,
-					state: innerState
-				});
 				const wrapState = (parseResult) => {
-					if (parseResult.success) return {
-						success: true,
-						next: {
-							...parseResult.next,
-							state: ["parsing", parseResult.next.state]
-						},
-						consumed: parseResult.consumed
-					};
+					if (parseResult.success) {
+						const mergedExec = mergeChildExec(context.exec, parseResult.next.exec);
+						return {
+							success: true,
+							next: {
+								...parseResult.next,
+								state: ["parsing", parseResult.next.state],
+								...mergedExec != null ? {
+									exec: mergedExec,
+									dependencyRegistry: mergedExec.dependencyRegistry
+								} : {}
+							},
+							consumed: parseResult.consumed
+						};
+					}
 					return parseResult;
 				};
-				if (isAsync) return parseResultOrPromise.then(wrapState);
-				return wrapState(parseResultOrPromise);
+				return dispatchByMode(parser.$mode, () => wrapState(syncInnerParser.parse(withChildContext(context, name, innerState, parser.usage))), async () => wrapState(await parser.parse(withChildContext(context, name, innerState, parser.usage))));
 			}
 			return {
 				success: false,
@@ -1117,20 +1240,31 @@ function command(name, parser, options = {}) {
 				error: options.errors?.notFound ?? message`Command ${optionName(name)} was not matched.`
 			};
 			else if (state[0] === "matched") {
-				const parseResultOrPromise = parser.parse({
+				const childExec = withChildExecPath(exec, name);
+				const childContext = {
 					buffer: [],
 					optionsTerminated: false,
-					usage: [],
-					state: parser.initialState
-				});
-				if (isAsync) return parseResultOrPromise.then((parseResult$1) => {
-					if (parseResult$1.success) return parser.complete(parseResult$1.next.state, exec);
-					return parser.complete(parser.initialState, exec);
+					usage: parser.usage,
+					state: parser.initialState,
+					...childExec != null ? {
+						exec: childExec,
+						trace: childExec.trace,
+						dependencyRegistry: childExec.dependencyRegistry
+					} : {}
+				};
+				return dispatchByMode(parser.$mode, () => {
+					const parseResult = syncInnerParser.parse(childContext);
+					const nextExec = parseResult.success ? mergeChildExec(childExec, parseResult.next.exec) : childExec;
+					return syncInnerParser.complete(parseResult.success ? parseResult.next.state : syncInnerParser.initialState, nextExec);
+				}, async () => {
+					const parseResult = await asyncInnerParser.parse(childContext);
+					const nextExec = parseResult.success ? mergeChildExec(childExec, parseResult.next.exec) : childExec;
+					return asyncInnerParser.complete(parseResult.success ? parseResult.next.state : parser.initialState, nextExec);
 				});
-				const parseResult = parseResultOrPromise;
-				if (parseResult.success) return parser.complete(parseResult.next.state, exec);
-				return parser.complete(parser.initialState, exec);
-			} else if (state[0] === "parsing") return parser.complete(state[1], exec);
+			} else if (state[0] === "parsing") {
+				const childExec = withChildExecPath(exec, name);
+				return dispatchByMode(parser.$mode, () => syncInnerParser.complete(state[1], childExec), async () => await asyncInnerParser.complete(state[1], childExec));
+			}
 			return {
 				success: false,
 				error: options.errors?.invalidState ?? message`Invalid command state during completion.`