@optique/core 1.3.0-dev.2396 → 1.3.0-dev.2399

package/dist/constructs.cjs

@@ -1807,7 +1807,7 @@ function* suggestObjectSync(context, prefix, parserPairs) {
 	const nodes = require_dependency_runtime.buildRuntimeNodesFromPairs(sourceParserPairs, context.state && typeof context.state === "object" ? context.state : {}, context.exec?.path);
 	require_dependency_runtime.collectExplicitSourceValues(expandSourceCollectionNodes(nodes), runtime);
 	if (context.state && typeof context.state === "object") require_dependency_runtime.collectSourcesFromState(context.state, runtime, /* @__PURE__ */ new WeakSet(), context.exec?.excludedSourceFields);
-	completeDependencySourceDefaults(context, sourceParserPairs, runtime.registry, context.exec);
+	completeDependencySourceDefaults(context, sourceParserPairs, runtime, context.exec);
 	const contextWithRegistry = {
 		...context,
 		dependencyRegistry: runtime.registry,
@@ -1843,7 +1843,7 @@ async function* suggestObjectAsync(context, prefix, parserPairs) {
 	const nodes = require_dependency_runtime.buildRuntimeNodesFromPairs(sourceParserPairs, context.state && typeof context.state === "object" ? context.state : {}, context.exec?.path);
 	await require_dependency_runtime.collectExplicitSourceValuesAsync(expandSourceCollectionNodes(nodes), runtime);
 	if (context.state && typeof context.state === "object") require_dependency_runtime.collectSourcesFromState(context.state, runtime, /* @__PURE__ */ new WeakSet(), context.exec?.excludedSourceFields);
-	await completeDependencySourceDefaultsAsync(context, sourceParserPairs, runtime.registry, context.exec);
+	await completeDependencySourceDefaultsAsync(context, sourceParserPairs, runtime, context.exec);
 	const contextWithRegistry = {
 		...context,
 		dependencyRegistry: runtime.registry,
@@ -1935,12 +1935,14 @@ function* pendingDependencyDefaults(context, parserPairs, registry) {
 * @see https://github.com/dahlia/optique/issues/186
 * @internal
 */
-function completeDependencySourceDefaults(context, parserPairs, registry, exec) {
-	for (const { parser, state } of pendingDependencyDefaults(context, parserPairs, registry)) {
+function completeDependencySourceDefaults(context, parserPairs, runtime, exec) {
+	for (const { parser, state } of pendingDependencyDefaults(context, parserPairs, runtime.registry)) {
 		const completed = parser.complete(state, exec);
 		const depState = wrapAsDependencySourceState(completed, parser);
-		if (depState) registerCompletedDependency(depState, registry);
+		if (depState) registerCompletedDependency(depState, runtime.registry);
 	}
+	const stateRecord = context.state != null && typeof context.state === "object" ? context.state : {};
+	require_dependency_runtime.resolveDerivedSourceValues(expandSourceCollectionNodes(require_dependency_runtime.buildRuntimeNodesFromPairs(parserPairs, stateRecord, exec?.path)), runtime, { effectfulProviders: "inactive" });
 }
 /**
 * Wraps a completed result as a {@link DependencySourceState} if the parser
@@ -1973,12 +1975,14 @@ function wrapAsDependencySourceState(completed, parser) {
 * @see https://github.com/dahlia/optique/issues/186
 * @internal
 */
-async function completeDependencySourceDefaultsAsync(context, parserPairs, registry, exec) {
-	for (const { parser, state } of pendingDependencyDefaults(context, parserPairs, registry)) {
+async function completeDependencySourceDefaultsAsync(context, parserPairs, runtime, exec) {
+	for (const { parser, state } of pendingDependencyDefaults(context, parserPairs, runtime.registry)) {
 		const completed = await parser.complete(state, exec);
 		const depState = wrapAsDependencySourceState(completed, parser);
-		if (depState) registerCompletedDependency(depState, registry);
+		if (depState) registerCompletedDependency(depState, runtime.registry);
 	}
+	const stateRecord = context.state != null && typeof context.state === "object" ? context.state : {};
+	await require_dependency_runtime.resolveDerivedSourceValuesAsync(expandSourceCollectionNodes(require_dependency_runtime.buildRuntimeNodesFromPairs(parserPairs, stateRecord, exec?.path)), runtime, { effectfulProviders: "inactive" });
 }
 /**
 * Collects field-level parser pairs from child parsers that expose them
@@ -3154,7 +3158,7 @@ function suggestTupleSync(context, prefix, parsers) {
 		completeDependencySourceDefaults({
 			...advancedContext,
 			state: createAnnotatedArrayStateRecord(stateArray)
-		}, buildIndexedParserPairs(parsers), runtime.registry, advancedContext.exec);
+		}, buildIndexedParserPairs(parsers), runtime, advancedContext.exec);
 	}
 	markFailedTupleSuggestSources(parsers, stateArray, advanced.failedParserIndexes, runtime, advancedContext.exec?.path);
 	const contextWithRegistry = {
@@ -3188,7 +3192,7 @@ async function* suggestTupleAsync(context, prefix, parsers) {
 		await completeDependencySourceDefaultsAsync({
 			...advancedContext,
 			state: createAnnotatedArrayStateRecord(stateArray)
-		}, buildIndexedParserPairs(parsers), runtime.registry, advancedContext.exec);
+		}, buildIndexedParserPairs(parsers), runtime, advancedContext.exec);
 	}
 	await markFailedTupleSuggestSourcesAsync(parsers, stateArray, advanced.failedParserIndexes, runtime, advancedContext.exec?.path);
 	const contextWithRegistry = {
@@ -4003,7 +4007,7 @@ function seq(...rawArgs) {
 				completeDependencySourceDefaults({
 					...advancedContext,
 					state: createAnnotatedArrayStateRecord(stateArray)
-				}, buildIndexedParserPairs(syncParsers), runtime.registry, advancedContext.exec);
+				}, buildIndexedParserPairs(syncParsers), runtime, advancedContext.exec);
 				const contextWithRegistry = {
 					...advancedContext,
 					dependencyRegistry: runtime.registry,
@@ -4033,7 +4037,7 @@ function seq(...rawArgs) {
 				await completeDependencySourceDefaultsAsync({
 					...advancedContext,
 					state: createAnnotatedArrayStateRecord(stateArray)
-				}, buildIndexedParserPairs(parsers), runtime.registry, advancedContext.exec);
+				}, buildIndexedParserPairs(parsers), runtime, advancedContext.exec);
 				const contextWithRegistry = {
 					...advancedContext,
 					dependencyRegistry: runtime.registry,
@@ -4975,7 +4979,7 @@ function merge(...args) {
 				});
 				if (context.state && typeof context.state === "object") await require_dependency_runtime.collectExplicitSourceValuesAsync(expandSourceCollectionNodes(require_dependency_runtime.buildRuntimeNodesFromPairs(childFieldPairs$1, context.state, context.exec?.path)), runtime$1);
 				if (context.state && typeof context.state === "object") require_dependency_runtime.collectSourcesFromState(context.state, runtime$1, /* @__PURE__ */ new WeakSet(), duplicateFieldNames$1);
-				await completeDependencySourceDefaultsAsync(context, childFieldPairs$1, runtime$1.registry, context.exec);
+				await completeDependencySourceDefaultsAsync(context, childFieldPairs$1, runtime$1, context.exec);
 				const contextWithRegistry$1 = {
 					...context,
 					dependencyRegistry: runtime$1.registry
@@ -5015,7 +5019,7 @@ function merge(...args) {
 			});
 			if (context.state && typeof context.state === "object") require_dependency_runtime.collectExplicitSourceValues(expandSourceCollectionNodes(require_dependency_runtime.buildRuntimeNodesFromPairs(childFieldPairs, context.state, context.exec?.path)), runtime);
 			if (context.state && typeof context.state === "object") require_dependency_runtime.collectSourcesFromState(context.state, runtime, /* @__PURE__ */ new WeakSet(), duplicateFieldNames);
-			completeDependencySourceDefaults(context, childFieldPairs, runtime.registry, context.exec);
+			completeDependencySourceDefaults(context, childFieldPairs, runtime, context.exec);
 			const contextWithRegistry = {
 				...context,
 				dependencyRegistry: runtime.registry
@@ -5126,7 +5130,7 @@ function buildSuggestRegistry(preParsedContext, parsers) {
 		completeDependencySourceDefaults({
 			...preParsedContext,
 			state: createAnnotatedArrayStateRecord(stateArray)
-		}, buildIndexedParserPairs(parsers), runtime.registry, preParsedContext.exec);
+		}, buildIndexedParserPairs(parsers), runtime, preParsedContext.exec);
 		const prefix = preParsedContext.exec?.path ?? [];
 		for (let i = 0; i < parsers.length; i++) seedSuggestRuntimeFromFieldParsers(parsers[i], require_annotation_state.getWrappedChildState(stateArray, stateArray[i], parsers[i]), runtime, [...prefix, i]);
 	}
@@ -5154,7 +5158,7 @@ async function buildSuggestRegistryAsync(preParsedContext, parsers) {
 		await completeDependencySourceDefaultsAsync({
 			...preParsedContext,
 			state: createAnnotatedArrayStateRecord(stateArray)
-		}, buildIndexedParserPairs(parsers), runtime.registry, preParsedContext.exec);
+		}, buildIndexedParserPairs(parsers), runtime, preParsedContext.exec);
 		const prefix = preParsedContext.exec?.path ?? [];
 		for (let i = 0; i < parsers.length; i++) await seedSuggestRuntimeFromFieldParsersAsync(parsers[i], require_annotation_state.getWrappedChildState(stateArray, stateArray[i], parsers[i]), runtime, [...prefix, i]);
 	}
@@ -5194,7 +5198,7 @@ function seedSuggestRuntimeFromFieldParsers(parser, state, runtime, parentPath)
 			dependencyRuntime: runtime,
 			dependencyRegistry: runtime.registry
 		}
-	}, pairs, runtime.registry, {
+	}, pairs, runtime, {
 		usage: parser.usage,
 		phase: "suggest",
 		path: parentPath,
@@ -5226,7 +5230,7 @@ async function seedSuggestRuntimeFromFieldParsersAsync(parser, state, runtime, p
 			dependencyRuntime: runtime,
 			dependencyRegistry: runtime.registry
 		}
-	}, pairs, runtime.registry, {
+	}, pairs, runtime, {
 		usage: parser.usage,
 		phase: "suggest",
 		path: parentPath,

package/dist/constructs.js

@@ -5,7 +5,7 @@ import { extractArgumentMetavars, extractCommandNames, extractOptionNames, isDoc
 import { deduplicateDocFragments } from "./doc.js";
 import { dispatchByMode, dispatchIterableByMode } from "./internal/mode-dispatch.js";
 import { createDependencySourceState, dependencyId, isDependencySourceState, isPendingDependencySourceState, isWrappedDependencySource, wrappedDependencySourceMarker } from "./internal/dependency.js";
-import { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyRuntimeContext, effectfulSchedulingNodesKey, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey } from "./dependency-runtime.js";
+import { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyRuntimeContext, effectfulSchedulingNodesKey, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey } from "./dependency-runtime.js";
 import { defineInheritedAnnotationParser, defineParseLanes, getOwnParseLanes, getParserSuggestRuntimeNodes, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { annotationViewTargets, getWrappedChildParseState, getWrappedChildState, reconcileObjectChildState, unwrapAnnotationView } from "./annotation-state.js";
 import { allowDuplicateLeadingCommandNamesKey } from "./internal/command-alias.js";
@@ -1807,7 +1807,7 @@ function* suggestObjectSync(context, prefix, parserPairs) {
 	const nodes = buildRuntimeNodesFromPairs(sourceParserPairs, context.state && typeof context.state === "object" ? context.state : {}, context.exec?.path);
 	collectExplicitSourceValues(expandSourceCollectionNodes(nodes), runtime);
 	if (context.state && typeof context.state === "object") collectSourcesFromState(context.state, runtime, /* @__PURE__ */ new WeakSet(), context.exec?.excludedSourceFields);
-	completeDependencySourceDefaults(context, sourceParserPairs, runtime.registry, context.exec);
+	completeDependencySourceDefaults(context, sourceParserPairs, runtime, context.exec);
 	const contextWithRegistry = {
 		...context,
 		dependencyRegistry: runtime.registry,
@@ -1843,7 +1843,7 @@ async function* suggestObjectAsync(context, prefix, parserPairs) {
 	const nodes = buildRuntimeNodesFromPairs(sourceParserPairs, context.state && typeof context.state === "object" ? context.state : {}, context.exec?.path);
 	await collectExplicitSourceValuesAsync(expandSourceCollectionNodes(nodes), runtime);
 	if (context.state && typeof context.state === "object") collectSourcesFromState(context.state, runtime, /* @__PURE__ */ new WeakSet(), context.exec?.excludedSourceFields);
-	await completeDependencySourceDefaultsAsync(context, sourceParserPairs, runtime.registry, context.exec);
+	await completeDependencySourceDefaultsAsync(context, sourceParserPairs, runtime, context.exec);
 	const contextWithRegistry = {
 		...context,
 		dependencyRegistry: runtime.registry,
@@ -1935,12 +1935,14 @@ function* pendingDependencyDefaults(context, parserPairs, registry) {
 * @see https://github.com/dahlia/optique/issues/186
 * @internal
 */
-function completeDependencySourceDefaults(context, parserPairs, registry, exec) {
-	for (const { parser, state } of pendingDependencyDefaults(context, parserPairs, registry)) {
+function completeDependencySourceDefaults(context, parserPairs, runtime, exec) {
+	for (const { parser, state } of pendingDependencyDefaults(context, parserPairs, runtime.registry)) {
 		const completed = parser.complete(state, exec);
 		const depState = wrapAsDependencySourceState(completed, parser);
-		if (depState) registerCompletedDependency(depState, registry);
+		if (depState) registerCompletedDependency(depState, runtime.registry);
 	}
+	const stateRecord = context.state != null && typeof context.state === "object" ? context.state : {};
+	resolveDerivedSourceValues(expandSourceCollectionNodes(buildRuntimeNodesFromPairs(parserPairs, stateRecord, exec?.path)), runtime, { effectfulProviders: "inactive" });
 }
 /**
 * Wraps a completed result as a {@link DependencySourceState} if the parser
@@ -1973,12 +1975,14 @@ function wrapAsDependencySourceState(completed, parser) {
 * @see https://github.com/dahlia/optique/issues/186
 * @internal
 */
-async function completeDependencySourceDefaultsAsync(context, parserPairs, registry, exec) {
-	for (const { parser, state } of pendingDependencyDefaults(context, parserPairs, registry)) {
+async function completeDependencySourceDefaultsAsync(context, parserPairs, runtime, exec) {
+	for (const { parser, state } of pendingDependencyDefaults(context, parserPairs, runtime.registry)) {
 		const completed = await parser.complete(state, exec);
 		const depState = wrapAsDependencySourceState(completed, parser);
-		if (depState) registerCompletedDependency(depState, registry);
+		if (depState) registerCompletedDependency(depState, runtime.registry);
 	}
+	const stateRecord = context.state != null && typeof context.state === "object" ? context.state : {};
+	await resolveDerivedSourceValuesAsync(expandSourceCollectionNodes(buildRuntimeNodesFromPairs(parserPairs, stateRecord, exec?.path)), runtime, { effectfulProviders: "inactive" });
 }
 /**
 * Collects field-level parser pairs from child parsers that expose them
@@ -3154,7 +3158,7 @@ function suggestTupleSync(context, prefix, parsers) {
 		completeDependencySourceDefaults({
 			...advancedContext,
 			state: createAnnotatedArrayStateRecord(stateArray)
-		}, buildIndexedParserPairs(parsers), runtime.registry, advancedContext.exec);
+		}, buildIndexedParserPairs(parsers), runtime, advancedContext.exec);
 	}
 	markFailedTupleSuggestSources(parsers, stateArray, advanced.failedParserIndexes, runtime, advancedContext.exec?.path);
 	const contextWithRegistry = {
@@ -3188,7 +3192,7 @@ async function* suggestTupleAsync(context, prefix, parsers) {
 		await completeDependencySourceDefaultsAsync({
 			...advancedContext,
 			state: createAnnotatedArrayStateRecord(stateArray)
-		}, buildIndexedParserPairs(parsers), runtime.registry, advancedContext.exec);
+		}, buildIndexedParserPairs(parsers), runtime, advancedContext.exec);
 	}
 	await markFailedTupleSuggestSourcesAsync(parsers, stateArray, advanced.failedParserIndexes, runtime, advancedContext.exec?.path);
 	const contextWithRegistry = {
@@ -4003,7 +4007,7 @@ function seq(...rawArgs) {
 				completeDependencySourceDefaults({
 					...advancedContext,
 					state: createAnnotatedArrayStateRecord(stateArray)
-				}, buildIndexedParserPairs(syncParsers), runtime.registry, advancedContext.exec);
+				}, buildIndexedParserPairs(syncParsers), runtime, advancedContext.exec);
 				const contextWithRegistry = {
 					...advancedContext,
 					dependencyRegistry: runtime.registry,
@@ -4033,7 +4037,7 @@ function seq(...rawArgs) {
 				await completeDependencySourceDefaultsAsync({
 					...advancedContext,
 					state: createAnnotatedArrayStateRecord(stateArray)
-				}, buildIndexedParserPairs(parsers), runtime.registry, advancedContext.exec);
+				}, buildIndexedParserPairs(parsers), runtime, advancedContext.exec);
 				const contextWithRegistry = {
 					...advancedContext,
 					dependencyRegistry: runtime.registry,
@@ -4975,7 +4979,7 @@ function merge(...args) {
 				});
 				if (context.state && typeof context.state === "object") await collectExplicitSourceValuesAsync(expandSourceCollectionNodes(buildRuntimeNodesFromPairs(childFieldPairs$1, context.state, context.exec?.path)), runtime$1);
 				if (context.state && typeof context.state === "object") collectSourcesFromState(context.state, runtime$1, /* @__PURE__ */ new WeakSet(), duplicateFieldNames$1);
-				await completeDependencySourceDefaultsAsync(context, childFieldPairs$1, runtime$1.registry, context.exec);
+				await completeDependencySourceDefaultsAsync(context, childFieldPairs$1, runtime$1, context.exec);
 				const contextWithRegistry$1 = {
 					...context,
 					dependencyRegistry: runtime$1.registry
@@ -5015,7 +5019,7 @@ function merge(...args) {
 			});
 			if (context.state && typeof context.state === "object") collectExplicitSourceValues(expandSourceCollectionNodes(buildRuntimeNodesFromPairs(childFieldPairs, context.state, context.exec?.path)), runtime);
 			if (context.state && typeof context.state === "object") collectSourcesFromState(context.state, runtime, /* @__PURE__ */ new WeakSet(), duplicateFieldNames);
-			completeDependencySourceDefaults(context, childFieldPairs, runtime.registry, context.exec);
+			completeDependencySourceDefaults(context, childFieldPairs, runtime, context.exec);
 			const contextWithRegistry = {
 				...context,
 				dependencyRegistry: runtime.registry
@@ -5126,7 +5130,7 @@ function buildSuggestRegistry(preParsedContext, parsers) {
 		completeDependencySourceDefaults({
 			...preParsedContext,
 			state: createAnnotatedArrayStateRecord(stateArray)
-		}, buildIndexedParserPairs(parsers), runtime.registry, preParsedContext.exec);
+		}, buildIndexedParserPairs(parsers), runtime, preParsedContext.exec);
 		const prefix = preParsedContext.exec?.path ?? [];
 		for (let i = 0; i < parsers.length; i++) seedSuggestRuntimeFromFieldParsers(parsers[i], getWrappedChildState(stateArray, stateArray[i], parsers[i]), runtime, [...prefix, i]);
 	}
@@ -5154,7 +5158,7 @@ async function buildSuggestRegistryAsync(preParsedContext, parsers) {
 		await completeDependencySourceDefaultsAsync({
 			...preParsedContext,
 			state: createAnnotatedArrayStateRecord(stateArray)
-		}, buildIndexedParserPairs(parsers), runtime.registry, preParsedContext.exec);
+		}, buildIndexedParserPairs(parsers), runtime, preParsedContext.exec);
 		const prefix = preParsedContext.exec?.path ?? [];
 		for (let i = 0; i < parsers.length; i++) await seedSuggestRuntimeFromFieldParsersAsync(parsers[i], getWrappedChildState(stateArray, stateArray[i], parsers[i]), runtime, [...prefix, i]);
 	}
@@ -5194,7 +5198,7 @@ function seedSuggestRuntimeFromFieldParsers(parser, state, runtime, parentPath)
 			dependencyRuntime: runtime,
 			dependencyRegistry: runtime.registry
 		}
-	}, pairs, runtime.registry, {
+	}, pairs, runtime, {
 		usage: parser.usage,
 		phase: "suggest",
 		path: parentPath,
@@ -5226,7 +5230,7 @@ async function seedSuggestRuntimeFromFieldParsersAsync(parser, state, runtime, p
 			dependencyRuntime: runtime,
 			dependencyRegistry: runtime.registry
 		}
-	}, pairs, runtime.registry, {
+	}, pairs, runtime, {
 		usage: parser.usage,
 		phase: "suggest",
 		path: parentPath,

package/dist/dependency-metadata.cjs

@@ -14,12 +14,15 @@ const require_internal_dependency = require('./internal/dependency.cjs');
 * @since 1.0.0
 */
 function extractDependencyMetadata(valueParser) {
-	if (require_internal_dependency.isDependencySource(valueParser)) return { source: {
+	let source;
+	if (require_internal_dependency.isDependencySource(valueParser)) source = {
 		kind: "source",
-		sourceId: valueParser[require_internal_dependency.dependencyId],
+		sourceId: valueParser[require_internal_dependency.dependencySourceId],
+		metavar: valueParser.metavar,
 		extractSourceValue: extractFromBareState,
 		preservesSourceValue: true
-	} };
+	};
+	let derived;
 	if (require_internal_dependency.isDerivedValueParser(valueParser)) {
 		const isMultiSource = require_internal_dependency.dependencyIds in valueParser && valueParser[require_internal_dependency.dependencyIds] != null;
 		const allIds = isMultiSource ? valueParser[require_internal_dependency.dependencyIds] : [valueParser[require_internal_dependency.dependencyId]];
@@ -39,15 +42,19 @@ function extractDependencyMetadata(valueParser) {
 			const depArg = isMultiSource ? depValues : depValues[0];
 			return suggestFn(prefix, depArg);
 		} : void 0;
-		return { derived: {
+		derived = {
 			kind: "derived",
 			dependencyIds: allIds,
+			metavar: valueParser.metavar,
 			getDefaultDependencyValues: defaultValuesFn,
 			replayParse,
 			replaySuggest
-		} };
+		};
 	}
-	return void 0;
+	return source == null && derived == null ? void 0 : {
+		source,
+		derived
+	};
 }
 /**
 * Extracts the source parse result from a plain source state.

package/dist/dependency-metadata.d.cts

@@ -14,6 +14,8 @@ interface DependencySourceCapability {
   readonly kind: "source";
   /** The unique dependency source identifier. */
   readonly sourceId: symbol;
+  /** Metavariable used to identify this source in diagnostics. */
+  readonly metavar?: string;
   /**
    * Extracts the dependency source parse result from the parser's state.
    *
@@ -73,6 +75,8 @@ interface DerivedDependencyCapability {
   readonly kind: "derived";
   /** The dependency source IDs this parser depends on. */
   readonly dependencyIds: readonly symbol[];
+  /** Metavariable used to identify this parser in diagnostics. */
+  readonly metavar?: string;
   /**
    * Returns default values for each dependency, used when the
    * corresponding sources are not provided.

package/dist/dependency-metadata.d.ts

@@ -14,6 +14,8 @@ interface DependencySourceCapability {
   readonly kind: "source";
   /** The unique dependency source identifier. */
   readonly sourceId: symbol;
+  /** Metavariable used to identify this source in diagnostics. */
+  readonly metavar?: string;
   /**
    * Extracts the dependency source parse result from the parser's state.
    *
@@ -73,6 +75,8 @@ interface DerivedDependencyCapability {
   readonly kind: "derived";
   /** The dependency source IDs this parser depends on. */
   readonly dependencyIds: readonly symbol[];
+  /** Metavariable used to identify this parser in diagnostics. */
+  readonly metavar?: string;
   /**
    * Returns default values for each dependency, used when the
    * corresponding sources are not provided.

package/dist/dependency-metadata.js

@@ -1,4 +1,4 @@
-import { defaultValues, dependencyId, dependencyIds, isDependencySource, isDependencySourceState, isDerivedValueParser, parseWithDependency, singleDefaultValue, suggestWithDependency } from "./internal/dependency.js";
+import { defaultValues, dependencyId, dependencyIds, dependencySourceId, isDependencySource, isDependencySourceState, isDerivedValueParser, parseWithDependency, singleDefaultValue, suggestWithDependency } from "./internal/dependency.js";
 
 //#region src/dependency-metadata.ts
 /**
@@ -14,12 +14,15 @@ import { defaultValues, dependencyId, dependencyIds, isDependencySource, isDepen
 * @since 1.0.0
 */
 function extractDependencyMetadata(valueParser) {
-	if (isDependencySource(valueParser)) return { source: {
+	let source;
+	if (isDependencySource(valueParser)) source = {
 		kind: "source",
-		sourceId: valueParser[dependencyId],
+		sourceId: valueParser[dependencySourceId],
+		metavar: valueParser.metavar,
 		extractSourceValue: extractFromBareState,
 		preservesSourceValue: true
-	} };
+	};
+	let derived;
 	if (isDerivedValueParser(valueParser)) {
 		const isMultiSource = dependencyIds in valueParser && valueParser[dependencyIds] != null;
 		const allIds = isMultiSource ? valueParser[dependencyIds] : [valueParser[dependencyId]];
@@ -39,15 +42,19 @@ function extractDependencyMetadata(valueParser) {
 			const depArg = isMultiSource ? depValues : depValues[0];
 			return suggestFn(prefix, depArg);
 		} : void 0;
-		return { derived: {
+		derived = {
 			kind: "derived",
 			dependencyIds: allIds,
+			metavar: valueParser.metavar,
 			getDefaultDependencyValues: defaultValuesFn,
 			replayParse,
 			replaySuggest
-		} };
+		};
 	}
-	return void 0;
+	return source == null && derived == null ? void 0 : {
+		source,
+		derived
+	};
 }
 /**
 * Extracts the source parse result from a plain source state.