@optique/core 1.3.0-dev.2417 → 1.3.0-dev.2418

package/dist/dependency-metadata.d.cts

@@ -91,6 +91,24 @@ interface DerivedDependencyCapability {
    */
   readonly replaySuggest?: (prefix: string, dependencyValues: readonly unknown[]) => Iterable<Suggestion> | AsyncIterable<Suggestion>;
 }
+/**
+ * Metadata for a parser whose effectful completion consumes dependency
+ * source values without replaying a parse.
+ *
+ * A prompt with a derived configuration is the canonical case: resolving
+ * the configuration reads previously published dependency values, so the
+ * named sources must publish before the parser's effectful completion may
+ * run.  The scheduler adds provider edges for these IDs, propagates
+ * demand through them when the owning source is demanded, and includes
+ * them in failure lineage.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface CompletionDependencyCapability {
+  /** The dependency source IDs the effectful completion reads. */
+  readonly dependencyIds: readonly symbol[];
+}
 /**
  * Metadata indicating that a wrapper transforms the dependency source value.
  *
@@ -116,6 +134,12 @@ interface ParserDependencyMetadata {
   readonly source?: DependencySourceCapability;
   /** Present if the parser depends on one or more sources. */
   readonly derived?: DerivedDependencyCapability;
+  /**
+   * Present if the parser's effectful completion consumes dependency
+   * values (e.g., a prompt with a derived configuration).
+   * @since 1.3.0
+   */
+  readonly completion?: CompletionDependencyCapability;
   /** Present if a transform has been applied. */
   readonly transform?: DependencyTransformCapability;
 }
@@ -163,4 +187,4 @@ interface WithDefaultCompositionOptions {
  */
 declare function composeDependencyMetadata(inner: ParserDependencyMetadata | undefined, wrapperKind: "optional" | "withDefault" | "map", options?: WithDefaultCompositionOptions): ParserDependencyMetadata | undefined;
 //#endregion
-export { DependencySourceCapability, DependencyTransformCapability, DerivedDependencyCapability, ParserDependencyMetadata, WithDefaultCompositionOptions, composeDependencyMetadata, extractDependencyMetadata };
+export { CompletionDependencyCapability, DependencySourceCapability, DependencyTransformCapability, DerivedDependencyCapability, ParserDependencyMetadata, WithDefaultCompositionOptions, composeDependencyMetadata, extractDependencyMetadata };

package/dist/dependency-metadata.d.ts

@@ -91,6 +91,24 @@ interface DerivedDependencyCapability {
    */
   readonly replaySuggest?: (prefix: string, dependencyValues: readonly unknown[]) => Iterable<Suggestion> | AsyncIterable<Suggestion>;
 }
+/**
+ * Metadata for a parser whose effectful completion consumes dependency
+ * source values without replaying a parse.
+ *
+ * A prompt with a derived configuration is the canonical case: resolving
+ * the configuration reads previously published dependency values, so the
+ * named sources must publish before the parser's effectful completion may
+ * run.  The scheduler adds provider edges for these IDs, propagates
+ * demand through them when the owning source is demanded, and includes
+ * them in failure lineage.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface CompletionDependencyCapability {
+  /** The dependency source IDs the effectful completion reads. */
+  readonly dependencyIds: readonly symbol[];
+}
 /**
  * Metadata indicating that a wrapper transforms the dependency source value.
  *
@@ -116,6 +134,12 @@ interface ParserDependencyMetadata {
   readonly source?: DependencySourceCapability;
   /** Present if the parser depends on one or more sources. */
   readonly derived?: DerivedDependencyCapability;
+  /**
+   * Present if the parser's effectful completion consumes dependency
+   * values (e.g., a prompt with a derived configuration).
+   * @since 1.3.0
+   */
+  readonly completion?: CompletionDependencyCapability;
   /** Present if a transform has been applied. */
   readonly transform?: DependencyTransformCapability;
 }
@@ -163,4 +187,4 @@ interface WithDefaultCompositionOptions {
  */
 declare function composeDependencyMetadata(inner: ParserDependencyMetadata | undefined, wrapperKind: "optional" | "withDefault" | "map", options?: WithDefaultCompositionOptions): ParserDependencyMetadata | undefined;
 //#endregion
-export { DependencySourceCapability, DependencyTransformCapability, DerivedDependencyCapability, ParserDependencyMetadata, WithDefaultCompositionOptions, composeDependencyMetadata, extractDependencyMetadata };
+export { CompletionDependencyCapability, DependencySourceCapability, DependencyTransformCapability, DerivedDependencyCapability, ParserDependencyMetadata, WithDefaultCompositionOptions, composeDependencyMetadata, extractDependencyMetadata };

package/dist/dependency-runtime.cjs

@@ -426,6 +426,14 @@ function orderDependencyNodes(nodes) {
 	for (const node of nodes) {
 		const derived = node.parser.dependencyMetadata?.derived;
 		if (derived != null) for (const dependencySourceId of derived.dependencyIds) for (const provider of providers.get(dependencySourceId) ?? []) addEdge(provider, node);
+		const completion = node.parser.dependencyMetadata?.completion;
+		if (completion != null && !hasInactiveCompletion(node)) {
+			const ownSourceId = node.parser.dependencyMetadata?.source?.sourceId;
+			for (const dependencySourceId of completion.dependencyIds) {
+				if (dependencySourceId === ownSourceId) continue;
+				for (const provider of providers.get(dependencySourceId) ?? []) if (provider !== node) addEdge(provider, node);
+			}
+		}
 		if (node.requiresSourceId != null) {
 			for (const provider of providers.get(node.requiresSourceId) ?? []) if (provider !== node) addEdge(provider, node);
 		}
@@ -446,7 +454,7 @@ function orderDependencyNodes(nodes) {
 	if (ordered.length !== nodes.length) {
 		const cycle = nodes.filter((node) => (indegree.get(node) ?? 0) > 0);
 		const labels = cycle.map(formatDependencyNodeLabel).join(" -> ");
-		throw new TypeError(`Circular dependency detected among derived sources: ${labels}.`);
+		throw new TypeError(`Circular dependency detected among dependency sources: ${labels}.`);
 	}
 	return ordered;
 }
@@ -527,18 +535,42 @@ function hasPendingProvider(node, providers, settled, runtime, options) {
 function getNodeRawInput(node) {
 	return node.rawInput ?? extractRawInputFromState(node.state);
 }
+/**
+* Whether a node's completion dependencies are inactive because this
+* occurrence's own state already extracts a value: a field satisfied by
+* the command line or a binding never runs its configuration resolver,
+* so its completion dependencies must not order scheduling, demand
+* upstream sources, or join failure lineage.  A failed extraction keeps
+* the completion active (the effectful completion is its recovery
+* path), and an asynchronous extraction is conservatively treated as
+* active because it cannot be decided synchronously.
+*/
+function hasInactiveCompletion(node) {
+	const metadata = node.parser.dependencyMetadata;
+	if (metadata?.completion == null || metadata.source == null) return false;
+	const extracted = metadata.source.extractSourceValue?.(node.state);
+	if (isPromiseLike(extracted)) {
+		Promise.resolve(extracted).catch(() => {});
+		return false;
+	}
+	return extracted != null && extracted.success === true;
+}
 function registerRuntimeSourceMetadata(nodes, runtime) {
 	for (const node of nodes) {
 		const metadata = node.parser.dependencyMetadata;
 		if (metadata?.source == null) continue;
-		runtime.registerSourceMetadata(metadata.source.sourceId, formatDependencyNodeMetavar(node), metadata.derived?.dependencyIds);
+		const completion = hasInactiveCompletion(node) ? void 0 : metadata.completion;
+		const dependencyIds = completion == null ? metadata.derived?.dependencyIds : [...metadata.derived?.dependencyIds ?? [], ...completion.dependencyIds.filter((id) => !(metadata.derived?.dependencyIds ?? []).includes(id))];
+		runtime.registerSourceMetadata(metadata.source.sourceId, formatDependencyNodeMetavar(node), dependencyIds);
 	}
 }
 function propagateRuntimeSourceFailures(nodes, runtime) {
 	for (const node of orderDependencyNodes(nodes)) {
 		const metadata = node.parser.dependencyMetadata;
-		if (metadata?.derived == null) continue;
-		runtime.propagateSourceFailure(metadata.derived.dependencyIds, formatDependencyNodeMetavar(node), metadata.source?.sourceId);
+		if (metadata == null) continue;
+		const completion = hasInactiveCompletion(node) ? void 0 : metadata.completion;
+		if (metadata.derived == null && completion == null) continue;
+		runtime.propagateSourceFailure([...metadata.derived?.dependencyIds ?? [], ...completion?.dependencyIds ?? []], formatDependencyNodeMetavar(node), metadata.source?.sourceId);
 	}
 }
 /**
@@ -1009,6 +1041,11 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 					session.demanded.add(dependencySourceId);
 					demandAdded = true;
 				}
+				if (metadata?.source != null && metadata.completion != null && session.demanded.has(metadata.source.sourceId) && !hasInactiveCompletion(node)) for (const dependencySourceId of metadata.completion.dependencyIds) {
+					if (session.demanded.has(dependencySourceId)) continue;
+					session.demanded.add(dependencySourceId);
+					demandAdded = true;
+				}
 				if (node.requiresSourceId == null || node.providesSourceIds == null) continue;
 				if (session.demanded.has(node.requiresSourceId)) continue;
 				for (const provided of node.providesSourceIds) if (session.demanded.has(provided)) {

package/dist/dependency-runtime.js

@@ -426,6 +426,14 @@ function orderDependencyNodes(nodes) {
 	for (const node of nodes) {
 		const derived = node.parser.dependencyMetadata?.derived;
 		if (derived != null) for (const dependencySourceId of derived.dependencyIds) for (const provider of providers.get(dependencySourceId) ?? []) addEdge(provider, node);
+		const completion = node.parser.dependencyMetadata?.completion;
+		if (completion != null && !hasInactiveCompletion(node)) {
+			const ownSourceId = node.parser.dependencyMetadata?.source?.sourceId;
+			for (const dependencySourceId of completion.dependencyIds) {
+				if (dependencySourceId === ownSourceId) continue;
+				for (const provider of providers.get(dependencySourceId) ?? []) if (provider !== node) addEdge(provider, node);
+			}
+		}
 		if (node.requiresSourceId != null) {
 			for (const provider of providers.get(node.requiresSourceId) ?? []) if (provider !== node) addEdge(provider, node);
 		}
@@ -446,7 +454,7 @@ function orderDependencyNodes(nodes) {
 	if (ordered.length !== nodes.length) {
 		const cycle = nodes.filter((node) => (indegree.get(node) ?? 0) > 0);
 		const labels = cycle.map(formatDependencyNodeLabel).join(" -> ");
-		throw new TypeError(`Circular dependency detected among derived sources: ${labels}.`);
+		throw new TypeError(`Circular dependency detected among dependency sources: ${labels}.`);
 	}
 	return ordered;
 }
@@ -527,18 +535,42 @@ function hasPendingProvider(node, providers, settled, runtime, options) {
 function getNodeRawInput(node) {
 	return node.rawInput ?? extractRawInputFromState(node.state);
 }
+/**
+* Whether a node's completion dependencies are inactive because this
+* occurrence's own state already extracts a value: a field satisfied by
+* the command line or a binding never runs its configuration resolver,
+* so its completion dependencies must not order scheduling, demand
+* upstream sources, or join failure lineage.  A failed extraction keeps
+* the completion active (the effectful completion is its recovery
+* path), and an asynchronous extraction is conservatively treated as
+* active because it cannot be decided synchronously.
+*/
+function hasInactiveCompletion(node) {
+	const metadata = node.parser.dependencyMetadata;
+	if (metadata?.completion == null || metadata.source == null) return false;
+	const extracted = metadata.source.extractSourceValue?.(node.state);
+	if (isPromiseLike(extracted)) {
+		Promise.resolve(extracted).catch(() => {});
+		return false;
+	}
+	return extracted != null && extracted.success === true;
+}
 function registerRuntimeSourceMetadata(nodes, runtime) {
 	for (const node of nodes) {
 		const metadata = node.parser.dependencyMetadata;
 		if (metadata?.source == null) continue;
-		runtime.registerSourceMetadata(metadata.source.sourceId, formatDependencyNodeMetavar(node), metadata.derived?.dependencyIds);
+		const completion = hasInactiveCompletion(node) ? void 0 : metadata.completion;
+		const dependencyIds = completion == null ? metadata.derived?.dependencyIds : [...metadata.derived?.dependencyIds ?? [], ...completion.dependencyIds.filter((id) => !(metadata.derived?.dependencyIds ?? []).includes(id))];
+		runtime.registerSourceMetadata(metadata.source.sourceId, formatDependencyNodeMetavar(node), dependencyIds);
 	}
 }
 function propagateRuntimeSourceFailures(nodes, runtime) {
 	for (const node of orderDependencyNodes(nodes)) {
 		const metadata = node.parser.dependencyMetadata;
-		if (metadata?.derived == null) continue;
-		runtime.propagateSourceFailure(metadata.derived.dependencyIds, formatDependencyNodeMetavar(node), metadata.source?.sourceId);
+		if (metadata == null) continue;
+		const completion = hasInactiveCompletion(node) ? void 0 : metadata.completion;
+		if (metadata.derived == null && completion == null) continue;
+		runtime.propagateSourceFailure([...metadata.derived?.dependencyIds ?? [], ...completion?.dependencyIds ?? []], formatDependencyNodeMetavar(node), metadata.source?.sourceId);
 	}
 }
 /**
@@ -1009,6 +1041,11 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 					session.demanded.add(dependencySourceId);
 					demandAdded = true;
 				}
+				if (metadata?.source != null && metadata.completion != null && session.demanded.has(metadata.source.sourceId) && !hasInactiveCompletion(node)) for (const dependencySourceId of metadata.completion.dependencyIds) {
+					if (session.demanded.has(dependencySourceId)) continue;
+					session.demanded.add(dependencySourceId);
+					demandAdded = true;
+				}
 				if (node.requiresSourceId == null || node.providesSourceIds == null) continue;
 				if (session.demanded.has(node.requiresSourceId)) continue;
 				for (const provided of node.providesSourceIds) if (session.demanded.has(provided)) {

package/dist/dependency.cjs

@@ -4,5 +4,6 @@ exports.dependency = require_internal_dependency.dependency;
 exports.deriveFrom = require_internal_dependency.deriveFrom;
 exports.deriveFromAsync = require_internal_dependency.deriveFromAsync;
 exports.deriveFromSync = require_internal_dependency.deriveFromSync;
+exports.getDependencySourceInfo = require_internal_dependency.getDependencySourceInfo;
 exports.isDependencySource = require_internal_dependency.isDependencySource;
 exports.isDerivedValueParser = require_internal_dependency.isDerivedValueParser;

package/dist/dependency.d.cts

@@ -1,2 +1,2 @@
-import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser } from "./internal/dependency.cjs";
-export { type AnyDependencySource, type CombineMode, type CombinedDependencyMode, type DependencyMode, type DependencySource, type DependencyValue, type DependencyValues, type DeriveAsyncOptions, type DeriveFromAsyncOptions, type DeriveFromOptions, type DeriveFromSyncOptions, type DeriveOptions, type DeriveSyncOptions, type DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser };
+import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.cjs";
+export { type AnyDependencySource, type CombineMode, type CombinedDependencyMode, type DependencyMode, type DependencySource, type DependencySourceInfo, type DependencyValue, type DependencyValues, type DeriveAsyncOptions, type DeriveFromAsyncOptions, type DeriveFromOptions, type DeriveFromSyncOptions, type DeriveOptions, type DeriveSyncOptions, type DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser };

package/dist/dependency.d.ts

@@ -1,2 +1,2 @@
-import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
-export { type AnyDependencySource, type CombineMode, type CombinedDependencyMode, type DependencyMode, type DependencySource, type DependencyValue, type DependencyValues, type DeriveAsyncOptions, type DeriveFromAsyncOptions, type DeriveFromOptions, type DeriveFromSyncOptions, type DeriveOptions, type DeriveSyncOptions, type DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser };
+import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
+export { type AnyDependencySource, type CombineMode, type CombinedDependencyMode, type DependencyMode, type DependencySource, type DependencySourceInfo, type DependencyValue, type DependencyValues, type DeriveAsyncOptions, type DeriveFromAsyncOptions, type DeriveFromOptions, type DeriveFromSyncOptions, type DeriveOptions, type DeriveSyncOptions, type DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser };

package/dist/dependency.js

@@ -1,3 +1,3 @@
-import { dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
+import { dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
 
-export { dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser };
+export { dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser };

package/dist/index.cjs

@@ -60,6 +60,7 @@ exports.formatMessage = require_message.formatMessage;
 exports.formatUsage = require_usage.formatUsage;
 exports.formatUsageTerm = require_usage.formatUsageTerm;
 exports.getAnnotations = require_internal_annotations.getAnnotations;
+exports.getDependencySourceInfo = require_internal_dependency.getDependencySourceInfo;
 exports.getDocPage = require_internal_parser.getDocPage;
 exports.getDocPageAsync = require_internal_parser.getDocPageAsync;
 exports.getDocPageSync = require_internal_parser.getDocPageSync;

package/dist/index.d.cts

@@ -9,7 +9,7 @@ import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { DeferredValue, DeferredValueOptions, DeferredValueSource, FluentParser, MultipleErrorOptions, MultipleOptions, ParserModifiers, WithDefaultError, WithDefaultOptions, deferredValue, fluent, isDeferredValue, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, SeqOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, seq, tuple } from "./constructs.cjs";
 import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.cjs";
-import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser } from "./internal/dependency.cjs";
+import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.cjs";
 import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.d.ts

@@ -9,7 +9,7 @@ import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { DeferredValue, DeferredValueOptions, DeferredValueSource, FluentParser, MultipleErrorOptions, MultipleOptions, ParserModifiers, WithDefaultError, WithDefaultOptions, deferredValue, fluent, isDeferredValue, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, SeqOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, seq, tuple } from "./constructs.js";
 import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.js";
-import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
+import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
 import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.js

@@ -2,7 +2,7 @@ import { getAnnotations } from "./internal/annotations.js";
 import { commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
 import { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
 import { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.js";
-import { dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
+import { dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
 import { createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { WithDefaultError, deferredValue, fluent, isDeferredValue, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
@@ -12,4 +12,4 @@ import { biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron,
 import { argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.js";
 import { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 
-export { DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/internal/dependency.cjs

@@ -141,6 +141,28 @@ function isDependencySource(parser) {
 	return dependencySourceMarker in parser && parser[dependencySourceMarker] === true;
 }
 /**
+* Reads the identity and diagnostic label of a dependency source without
+* exposing the internal marker symbols.
+*
+* Integration packages (e.g., *@optique/prompt*) use this to declare that
+* an effectful completion consumes the source's value.
+*
+* @param source The dependency source to describe.
+* @returns The source's identity and diagnostic metadata.
+* @throws {TypeError} If `source` is not a dependency source created by
+*         `dependency()`.
+* @internal
+* @since 1.3.0
+*/
+function getDependencySourceInfo(source) {
+	if (source == null || typeof source !== "object" || source[dependencySourceMarker] !== true || typeof source[dependencySourceId] !== "symbol") throw new TypeError("Expected a dependency source created by dependency().");
+	const metavar = source.metavar;
+	return {
+		sourceId: source[dependencySourceId],
+		...typeof metavar === "string" ? { metavar } : {}
+	};
+}
+/**
 * Checks if a value parser is a {@link DerivedValueParser}.
 *
 * @param parser The value parser to check.
@@ -1119,6 +1141,7 @@ exports.derivedValueParserMarker = derivedValueParserMarker;
 exports.formatDependencyError = formatDependencyError;
 exports.getDefaultValuesFunction = getDefaultValuesFunction;
 exports.getDependencyIds = getDependencyIds;
+exports.getDependencySourceInfo = getDependencySourceInfo;
 exports.getSnapshottedDefaultDependencyValues = getSnapshottedDefaultDependencyValues;
 exports.isDeferredParseState = isDeferredParseState;
 exports.isDependencySource = isDependencySource;

package/dist/internal/dependency.d.cts

@@ -474,6 +474,33 @@ declare function dependency<M extends Mode, T>(parser: ValueParser<M, T>): Depen
  * @since 0.10.0
  */
 declare function isDependencySource<M extends Mode, T>(parser: ValueParser<M, T>): parser is DependencySource<M, T>;
+/**
+ * Identity and diagnostic information about a dependency source.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface DependencySourceInfo {
+  /** The source's own identity, unique per `dependency()` call. */
+  readonly sourceId: symbol;
+  /** Metavariable used to identify this source in diagnostics. */
+  readonly metavar?: string;
+}
+/**
+ * Reads the identity and diagnostic label of a dependency source without
+ * exposing the internal marker symbols.
+ *
+ * Integration packages (e.g., *@optique/prompt*) use this to declare that
+ * an effectful completion consumes the source's value.
+ *
+ * @param source The dependency source to describe.
+ * @returns The source's identity and diagnostic metadata.
+ * @throws {TypeError} If `source` is not a dependency source created by
+ *         `dependency()`.
+ * @internal
+ * @since 1.3.0
+ */
+declare function getDependencySourceInfo(source: AnyDependencySource): DependencySourceInfo;
 /**
  * Checks if a value parser is a {@link DerivedValueParser}.
  *
@@ -862,4 +889,4 @@ type DependencyError = {
  */
 declare function formatDependencyError(error: DependencyError): Message;
 //#endregion
-export { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, PendingDependencySourceState, ResolvedDependency, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceId, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, singleDefaultValue, snapshotDefaultDependencyValues, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker };
+export { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceInfo, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, PendingDependencySourceState, ResolvedDependency, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceId, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, getDependencySourceInfo, getSnapshottedDefaultDependencyValues, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, singleDefaultValue, snapshotDefaultDependencyValues, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker };

package/dist/internal/dependency.d.ts

@@ -474,6 +474,33 @@ declare function dependency<M extends Mode, T>(parser: ValueParser<M, T>): Depen
  * @since 0.10.0
  */
 declare function isDependencySource<M extends Mode, T>(parser: ValueParser<M, T>): parser is DependencySource<M, T>;
+/**
+ * Identity and diagnostic information about a dependency source.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface DependencySourceInfo {
+  /** The source's own identity, unique per `dependency()` call. */
+  readonly sourceId: symbol;
+  /** Metavariable used to identify this source in diagnostics. */
+  readonly metavar?: string;
+}
+/**
+ * Reads the identity and diagnostic label of a dependency source without
+ * exposing the internal marker symbols.
+ *
+ * Integration packages (e.g., *@optique/prompt*) use this to declare that
+ * an effectful completion consumes the source's value.
+ *
+ * @param source The dependency source to describe.
+ * @returns The source's identity and diagnostic metadata.
+ * @throws {TypeError} If `source` is not a dependency source created by
+ *         `dependency()`.
+ * @internal
+ * @since 1.3.0
+ */
+declare function getDependencySourceInfo(source: AnyDependencySource): DependencySourceInfo;
 /**
  * Checks if a value parser is a {@link DerivedValueParser}.
  *
@@ -862,4 +889,4 @@ type DependencyError = {
  */
 declare function formatDependencyError(error: DependencyError): Message;
 //#endregion
-export { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, PendingDependencySourceState, ResolvedDependency, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceId, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, singleDefaultValue, snapshotDefaultDependencyValues, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker };
+export { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceInfo, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, PendingDependencySourceState, ResolvedDependency, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceId, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, getDependencySourceInfo, getSnapshottedDefaultDependencyValues, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, singleDefaultValue, snapshotDefaultDependencyValues, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker };

package/dist/internal/dependency.js

@@ -141,6 +141,28 @@ function isDependencySource(parser) {
 	return dependencySourceMarker in parser && parser[dependencySourceMarker] === true;
 }
 /**
+* Reads the identity and diagnostic label of a dependency source without
+* exposing the internal marker symbols.
+*
+* Integration packages (e.g., *@optique/prompt*) use this to declare that
+* an effectful completion consumes the source's value.
+*
+* @param source The dependency source to describe.
+* @returns The source's identity and diagnostic metadata.
+* @throws {TypeError} If `source` is not a dependency source created by
+*         `dependency()`.
+* @internal
+* @since 1.3.0
+*/
+function getDependencySourceInfo(source) {
+	if (source == null || typeof source !== "object" || source[dependencySourceMarker] !== true || typeof source[dependencySourceId] !== "symbol") throw new TypeError("Expected a dependency source created by dependency().");
+	const metavar = source.metavar;
+	return {
+		sourceId: source[dependencySourceId],
+		...typeof metavar === "string" ? { metavar } : {}
+	};
+}
+/**
 * Checks if a value parser is a {@link DerivedValueParser}.
 *
 * @param parser The value parser to check.
@@ -1099,4 +1121,4 @@ function formatDependencyError(error) {
 }
 
 //#endregion
-export { DependencyRegistry, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceId, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, singleDefaultValue, snapshotDefaultDependencyValues, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker };
+export { DependencyRegistry, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceId, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, getDependencySourceInfo, getSnapshottedDefaultDependencyValues, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, singleDefaultValue, snapshotDefaultDependencyValues, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.3.0-dev.2417",
+  "version": "1.3.0-dev.2418",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -221,7 +221,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.3.0-dev.2417+6b19e980",
+    "@optique/env": "1.3.0-dev.2418+afa5cda1",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",

package/skills/optique/SKILL.md

@@ -56,6 +56,11 @@ Core rules
     For a multi-level chain, wrap the middle derivation too:
     `dependency(source.deriveSync(...))`. Optique resolves such chains by
     dependency order, independently of object/tuple field order.
+ -  Use `derivePromptConfig(source, resolver)` (from *@optique/prompt*,
+    re-exported by *@optique/inquirer* and *@optique/clack*) when a prompt's
+    choices or message depend on another parsed value. The resolver may be
+    async and runs only at the real prompt fallback, after the named sources
+    resolve; keep static prompt configs for everything else.
  -  Build subcommands with `command()` combined by `or()`. Put a literal field
     such as `command: constant("serve")` in each branch when you want a
     discriminated union.