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

package/dist/primitives.d.ts

@@ -1,17 +1,11 @@
 import { Message } from "./message.js";
 import { HiddenVisibility, OptionName, Usage } from "./usage.js";
 import { ValueParser, ValueParserResult } from "./valueparser.js";
-import { DeferredParseState, PendingDependencySourceState } from "./dependency.js";
 import { Mode, Parser } from "./parser.js";
 
 //#region src/primitives.d.ts
-/**
- * State type for options that may use deferred parsing (DerivedValueParser).
- * This extends the normal ValueParserResult to also support DeferredParseState
- * and PendingDependencySourceState.
- * @internal
- */
-type OptionState<T> = ValueParserResult<T> | DeferredParseState<T> | PendingDependencySourceState | undefined;
+/** @internal */
+type OptionState<T> = ValueParserResult<T> | undefined;
 /**
  * Creates a parser that always succeeds without consuming any input and
  * produces a constant value of the type {@link T}.

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}.
@@ -202,7 +304,7 @@ 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;
+			} 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);
 		}
 	}
@@ -284,7 +386,7 @@ 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;
+			} 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)) yield suggestion;
 		}
 	}
@@ -330,6 +432,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 +457,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 +503,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 +546,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 +614,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 +706,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 +928,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,54 +974,58 @@ 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* () {});
@@ -968,8 +1082,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 +1097,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 +1109,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 +1135,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 +1152,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 +1204,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 +1236,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.`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1616+17abc525",
+  "version": "1.0.0-dev.1658+b57e115b",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",