@optique/core 1.3.0-dev.2398 → 1.3.0-dev.2401

package/dist/internal/dependency.d.cts

@@ -13,6 +13,16 @@ import { Mode, Suggestion } from "./parser.cjs";
  * @since 0.10.0
  */
 declare const dependencySourceMarker: unique symbol;
+/**
+ * A unique symbol used to store a dependency source's own identity.
+ *
+ * This is distinct from {@link dependencyId}, which stores an upstream
+ * reference on a derived parser.  A parser wrapped with `dependency()` after
+ * derivation carries both values.
+ * @internal
+ * @since 1.3.0
+ */
+declare const dependencySourceId: unique symbol;
 /**
  * A unique symbol used to identify derived value parsers at compile time.
  * This marker is used to distinguish {@link DerivedValueParser} from regular
@@ -176,7 +186,7 @@ interface DependencySource<M extends Mode = "sync", T = unknown> extends ValuePa
    * Unique identifier for this dependency source.
    * @internal
    */
-  readonly [dependencyId]: symbol;
+  readonly [dependencySourceId]: symbol;
   /**
    * Creates a derived value parser whose behavior depends on this
    * dependency source's value.
@@ -255,7 +265,7 @@ type CombinedDependencyMode<T extends readonly unknown[]> = "async" extends { [K
  */
 interface AnyDependencySource<M extends Mode = Mode> {
   readonly [dependencySourceMarker]: true;
-  readonly [dependencyId]: symbol;
+  readonly [dependencySourceId]: symbol;
   readonly mode: M;
 }
 /**
@@ -355,9 +365,6 @@ interface DeriveFromAsyncOptions<Deps extends readonly AnyDependencySource[], T>
 /**
  * A value parser that depends on another parser's value.
  *
- * A derived value parser cannot be nested (i.e., you cannot call
- * {@link DependencySource.derive} on a {@link DerivedValueParser}).
- *
  * @template M The execution mode of the parser (`"sync"` or `"async"`).
  * @template T The type of value this parser produces.
  * @template S The type of the source dependency value.
@@ -424,6 +431,8 @@ interface DerivedValueParser<M extends Mode = "sync", T = unknown, S = unknown>
  * A dependency source wraps an existing value parser and enables creating
  * derived parsers that depend on the parsed value. This is useful for
  * scenarios where one option's valid values depend on another option's value.
+ * A derived parser can itself become a source by wrapping it with
+ * `dependency()`, allowing dependency chains of any depth.
  *
  * @template M The execution mode of the value parser.
  * @template T The type of value the parser produces.
@@ -445,6 +454,14 @@ interface DerivedValueParser<M extends Mode = "sync", T = unknown, S = unknown>
  *   factory: (dir) => gitBranch({ dir }),
  *   defaultValue: () => process.cwd(),
  * });
+ *
+ * // A derived parser can provide the next dependency level.
+ * const branchSource = dependency(branchParser);
+ * const commitParser = branchSource.deriveSync({
+ *   metavar: "COMMIT",
+ *   factory: (branch) => gitCommit({ branch }),
+ *   defaultValue: () => "main",
+ * });
  * ```
  * @since 0.10.0
  */
@@ -845,4 +862,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, 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, 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 };

package/dist/internal/dependency.d.ts

@@ -13,6 +13,16 @@ import { Mode, Suggestion } from "./parser.js";
  * @since 0.10.0
  */
 declare const dependencySourceMarker: unique symbol;
+/**
+ * A unique symbol used to store a dependency source's own identity.
+ *
+ * This is distinct from {@link dependencyId}, which stores an upstream
+ * reference on a derived parser.  A parser wrapped with `dependency()` after
+ * derivation carries both values.
+ * @internal
+ * @since 1.3.0
+ */
+declare const dependencySourceId: unique symbol;
 /**
  * A unique symbol used to identify derived value parsers at compile time.
  * This marker is used to distinguish {@link DerivedValueParser} from regular
@@ -176,7 +186,7 @@ interface DependencySource<M extends Mode = "sync", T = unknown> extends ValuePa
    * Unique identifier for this dependency source.
    * @internal
    */
-  readonly [dependencyId]: symbol;
+  readonly [dependencySourceId]: symbol;
   /**
    * Creates a derived value parser whose behavior depends on this
    * dependency source's value.
@@ -255,7 +265,7 @@ type CombinedDependencyMode<T extends readonly unknown[]> = "async" extends { [K
  */
 interface AnyDependencySource<M extends Mode = Mode> {
   readonly [dependencySourceMarker]: true;
-  readonly [dependencyId]: symbol;
+  readonly [dependencySourceId]: symbol;
   readonly mode: M;
 }
 /**
@@ -355,9 +365,6 @@ interface DeriveFromAsyncOptions<Deps extends readonly AnyDependencySource[], T>
 /**
  * A value parser that depends on another parser's value.
  *
- * A derived value parser cannot be nested (i.e., you cannot call
- * {@link DependencySource.derive} on a {@link DerivedValueParser}).
- *
  * @template M The execution mode of the parser (`"sync"` or `"async"`).
  * @template T The type of value this parser produces.
  * @template S The type of the source dependency value.
@@ -424,6 +431,8 @@ interface DerivedValueParser<M extends Mode = "sync", T = unknown, S = unknown>
  * A dependency source wraps an existing value parser and enables creating
  * derived parsers that depend on the parsed value. This is useful for
  * scenarios where one option's valid values depend on another option's value.
+ * A derived parser can itself become a source by wrapping it with
+ * `dependency()`, allowing dependency chains of any depth.
  *
  * @template M The execution mode of the value parser.
  * @template T The type of value the parser produces.
@@ -445,6 +454,14 @@ interface DerivedValueParser<M extends Mode = "sync", T = unknown, S = unknown>
  *   factory: (dir) => gitBranch({ dir }),
  *   defaultValue: () => process.cwd(),
  * });
+ *
+ * // A derived parser can provide the next dependency level.
+ * const branchSource = dependency(branchParser);
+ * const commitParser = branchSource.deriveSync({
+ *   metavar: "COMMIT",
+ *   factory: (branch) => gitCommit({ branch }),
+ *   defaultValue: () => "main",
+ * });
  * ```
  * @since 0.10.0
  */
@@ -845,4 +862,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, 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, 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 };

package/dist/internal/dependency.js

@@ -9,6 +9,16 @@ import { message } from "../message.js";
 */
 const dependencySourceMarker = Symbol.for("@optique/core/dependency/dependencySourceMarker");
 /**
+* A unique symbol used to store a dependency source's own identity.
+*
+* This is distinct from {@link dependencyId}, which stores an upstream
+* reference on a derived parser.  A parser wrapped with `dependency()` after
+* derivation carries both values.
+* @internal
+* @since 1.3.0
+*/
+const dependencySourceId = Symbol.for("@optique/core/dependency/dependencySourceId");
+/**
 * A unique symbol used to identify derived value parsers at compile time.
 * This marker is used to distinguish {@link DerivedValueParser} from regular
 * {@link ValueParser} instances.
@@ -66,6 +76,8 @@ const suggestWithDependency = Symbol.for("@optique/core/dependency/suggestWithDe
 * A dependency source wraps an existing value parser and enables creating
 * derived parsers that depend on the parsed value. This is useful for
 * scenarios where one option's valid values depend on another option's value.
+* A derived parser can itself become a source by wrapping it with
+* `dependency()`, allowing dependency chains of any depth.
 *
 * @template M The execution mode of the value parser.
 * @template T The type of value the parser produces.
@@ -87,15 +99,23 @@ const suggestWithDependency = Symbol.for("@optique/core/dependency/suggestWithDe
 *   factory: (dir) => gitBranch({ dir }),
 *   defaultValue: () => process.cwd(),
 * });
+*
+* // A derived parser can provide the next dependency level.
+* const branchSource = dependency(branchParser);
+* const commitParser = branchSource.deriveSync({
+*   metavar: "COMMIT",
+*   factory: (branch) => gitCommit({ branch }),
+*   defaultValue: () => "main",
+* });
 * ```
 * @since 0.10.0
 */
 function dependency(parser) {
 	const id = Symbol();
-	const result = {
-		...parser,
+	const result = Object.create(Object.getPrototypeOf(parser), Object.getOwnPropertyDescriptors(parser));
+	Object.defineProperties(result, Object.getOwnPropertyDescriptors({
 		[dependencySourceMarker]: true,
-		[dependencyId]: id,
+		[dependencySourceId]: id,
 		derive(options) {
 			if (options.mode !== "sync" && options.mode !== "async") throw new TypeError("derive() requires an explicit mode field (\"sync\" or \"async\").");
 			return createDerivedValueParser(id, parser, options, options.mode);
@@ -107,7 +127,7 @@ function dependency(parser) {
 		deriveAsync(options) {
 			return createAsyncDerivedParserFromAsyncFactory(id, options);
 		}
-	};
+	}));
 	return result;
 }
 /**
@@ -166,7 +186,7 @@ function isDerivedValueParser(parser) {
 function deriveFrom(options) {
 	if (options.mode !== "sync" && options.mode !== "async") throw new TypeError("deriveFrom() requires an explicit mode field (\"sync\" or \"async\").");
 	const depsAsync = options.dependencies.some((dep) => dep.mode === "async");
-	const sourceId = options.dependencies.length > 0 ? options.dependencies[0][dependencyId] : Symbol();
+	const sourceId = options.dependencies.length > 0 ? options.dependencies[0][dependencySourceId] : Symbol();
 	const factoryReturnsAsync = options.mode === "async";
 	const isAsync = depsAsync || factoryReturnsAsync;
 	if (isAsync) {
@@ -191,7 +211,7 @@ function deriveFrom(options) {
 */
 function deriveFromSync(options) {
 	const depsAsync = options.dependencies.some((dep) => dep.mode === "async");
-	const sourceId = options.dependencies.length > 0 ? options.dependencies[0][dependencyId] : Symbol();
+	const sourceId = options.dependencies.length > 0 ? options.dependencies[0][dependencySourceId] : Symbol();
 	if (depsAsync) return createAsyncDerivedFromParserFromSyncFactory(sourceId, options);
 	return createSyncDerivedFromParser(sourceId, options);
 }
@@ -210,7 +230,7 @@ function deriveFromSync(options) {
 * @since 0.10.0
 */
 function deriveFromAsync(options) {
-	const sourceId = options.dependencies.length > 0 ? options.dependencies[0][dependencyId] : Symbol();
+	const sourceId = options.dependencies.length > 0 ? options.dependencies[0][dependencySourceId] : Symbol();
 	return createAsyncDerivedFromParserFromAsyncFactory(sourceId, options);
 }
 function isAsyncModeParser(parser) {
@@ -282,7 +302,7 @@ async function parseDerivedResultWithSnapshotAsync(parser, input, sourceValues)
 	return attachDefaultDependencySnapshot(await parseDerivedResultAsync(parser, input), snapshot);
 }
 function createSyncDerivedFromParser(sourceId, options) {
-	const alldependencyIds = options.dependencies.map((dep) => dep[dependencyId]);
+	const alldependencyIds = options.dependencies.map((dep) => dep[dependencySourceId]);
 	return {
 		mode: "sync",
 		metavar: options.metavar,
@@ -387,7 +407,7 @@ function createSyncDerivedFromParser(sourceId, options) {
 * factory returns an async parser.
 */
 function createAsyncDerivedFromParserFromAsyncFactory(sourceId, options) {
-	const alldependencyIds = options.dependencies.map((dep) => dep[dependencyId]);
+	const alldependencyIds = options.dependencies.map((dep) => dep[dependencySourceId]);
 	return {
 		mode: "async",
 		metavar: options.metavar,
@@ -475,7 +495,7 @@ function createAsyncDerivedFromParserFromAsyncFactory(sourceId, options) {
 * sources are async but the factory returns a sync parser.
 */
 function createAsyncDerivedFromParserFromSyncFactory(sourceId, options) {
-	const alldependencyIds = options.dependencies.map((dep) => dep[dependencyId]);
+	const alldependencyIds = options.dependencies.map((dep) => dep[dependencySourceId]);
 	return {
 		mode: "async",
 		metavar: options.metavar,
@@ -1079,4 +1099,4 @@ function formatDependencyError(error) {
 }
 
 //#endregion
-export { DependencyRegistry, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, 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, getSnapshottedDefaultDependencyValues, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, singleDefaultValue, snapshotDefaultDependencyValues, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker };

package/dist/primitives.cjs

@@ -36,7 +36,8 @@ function isTerminalValueState(state) {
 * execution trace.
 * @internal
 */
-function createOptionParseState(parseResult) {
+function createOptionParseState(parseResult, rawInput, valueParser) {
+	if (require_internal_dependency.isDerivedValueParser(valueParser)) require_dependency_runtime.recordDerivedRawInput(parseResult, rawInput);
 	return parseResult;
 }
 function buildTraceEntry(kind, rawInput, consumed, valueParser, parseResult, optionNames$1) {
@@ -88,6 +89,11 @@ function resolveDerivedCompletionSync(derivedMetadata, state, exec) {
 	}, traceEntry.rawInput, exec.dependencyRuntime);
 	return replayed ?? traceEntry.preliminaryResult ?? state;
 }
+function includeDependencyFailureChain(error, dependencyMetadata, exec) {
+	const sourceId = dependencyMetadata?.source?.sourceId;
+	if (sourceId == null || exec?.dependencyRuntime == null) return error;
+	return require_dependency_runtime.includeSourceFailureChain(error, sourceId, exec.dependencyRuntime);
+}
 async function resolveDerivedCompletionAsync(derivedMetadata, state, exec) {
 	if (derivedMetadata?.derived == null || exec?.dependencyRuntime == null) return state;
 	const traceEntry = exec.trace?.get(exec.path);
@@ -499,7 +505,7 @@ function option(...args) {
 						success: true,
 						next: {
 							...next,
-							state: createOptionParseState(parseResult),
+							state: createOptionParseState(parseResult, rawInput, syncValueParser),
 							buffer: context.buffer.slice(2)
 						},
 						consumed: context.buffer.slice(0, 2)
@@ -511,7 +517,7 @@ function option(...args) {
 						success: true,
 						next: {
 							...next,
-							state: createOptionParseState(parseResult),
+							state: createOptionParseState(parseResult, rawInput, valueParser),
 							buffer: context.buffer.slice(2)
 						},
 						consumed: context.buffer.slice(0, 2)
@@ -542,7 +548,7 @@ function option(...args) {
 						success: true,
 						next: {
 							...next,
-							state: createOptionParseState(parseResult),
+							state: createOptionParseState(parseResult, rawInput, syncValueParser),
 							buffer: context.buffer.slice(1)
 						},
 						consumed: context.buffer.slice(0, 1)
@@ -554,7 +560,7 @@ function option(...args) {
 						success: true,
 						next: {
 							...next,
-							state: createOptionParseState(parseResult),
+							state: createOptionParseState(parseResult, rawInput, valueParser),
 							buffer: context.buffer.slice(1)
 						},
 						consumed: context.buffer.slice(0, 1)
@@ -616,7 +622,7 @@ function option(...args) {
 				const resolvedState = valueParser != null && dependencyMetadata?.derived != null ? resolveDerivedCompletionSync(dependencyMetadata, state, exec) : state;
 				return resolvedState.success ? resolvedState : {
 					success: false,
-					error: formatInvalidValueError(resolvedState.error)
+					error: formatInvalidValueError(includeDependencyFailureChain(resolvedState.error, dependencyMetadata, exec))
 				};
 			};
 			const completeAsync = async () => {
@@ -625,7 +631,7 @@ function option(...args) {
 				const resolved = await resolveDerivedCompletionAsync(dependencyMetadata, state, exec);
 				return resolved.success ? resolved : {
 					success: false,
-					error: formatInvalidValueError(resolved.error)
+					error: formatInvalidValueError(includeDependencyFailureChain(resolved.error, dependencyMetadata, exec))
 				};
 			};
 			return require_mode_dispatch.dispatchByMode(mode, completeSync, completeAsync);
@@ -1242,7 +1248,7 @@ function argument(valueParser, options = {}) {
 					next: {
 						...next,
 						buffer: context.buffer.slice(i + 1),
-						state: createOptionParseState(parseResult),
+						state: createOptionParseState(parseResult, rawInput, syncValueParser),
 						optionsTerminated
 					},
 					consumed: context.buffer.slice(0, i + 1)
@@ -1255,7 +1261,7 @@ function argument(valueParser, options = {}) {
 					next: {
 						...next,
 						buffer: context.buffer.slice(i + 1),
-						state: createOptionParseState(parseResult),
+						state: createOptionParseState(parseResult, rawInput, valueParser),
 						optionsTerminated
 					},
 					consumed: context.buffer.slice(0, i + 1)
@@ -1272,7 +1278,7 @@ function argument(valueParser, options = {}) {
 				const resolvedState = dependencyMetadata?.derived != null ? resolveDerivedCompletionSync(dependencyMetadata, state, exec) : state;
 				return resolvedState.success ? resolvedState : {
 					success: false,
-					error: formatInvalidValueError(resolvedState.error)
+					error: formatInvalidValueError(includeDependencyFailureChain(resolvedState.error, dependencyMetadata, exec))
 				};
 			};
 			const completeAsync = async () => {
@@ -1281,7 +1287,7 @@ function argument(valueParser, options = {}) {
 				const resolved = await resolveDerivedCompletionAsync(dependencyMetadata, state, exec);
 				return resolved.success ? resolved : {
 					success: false,
-					error: formatInvalidValueError(resolved.error)
+					error: formatInvalidValueError(includeDependencyFailureChain(resolved.error, dependencyMetadata, exec))
 				};
 			};
 			return require_mode_dispatch.dispatchByMode(valueParser.mode, completeSync, completeAsync);

package/dist/primitives.js

@@ -4,7 +4,7 @@ import { validateCommandNames, validateOptionNames } from "./validate.js";
 import { extractOptionNames, isDocHidden, isSuggestionHidden } from "./usage.js";
 import { dispatchByMode, dispatchIterableByMode, wrapForMode } from "./internal/mode-dispatch.js";
 import { getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDerivedValueParser, suggestWithDependency } from "./internal/dependency.js";
-import { effectfulSchedulingNodesKey, replayDerivedParser, replayDerivedParserAsync, sourceCollectionExpansionKey, staticSourceScopeKey } from "./dependency-runtime.js";
+import { effectfulSchedulingNodesKey, includeSourceFailureChain, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, sourceCollectionExpansionKey, staticSourceScopeKey } from "./dependency-runtime.js";
 import { getWrappedChildParseState, getWrappedChildState, isAnnotationWrappedInitialState, normalizeInjectedAnnotationState } from "./annotation-state.js";
 import { hiddenCommandAliasesKey } from "./internal/command-alias.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
@@ -36,7 +36,8 @@ function isTerminalValueState(state) {
 * execution trace.
 * @internal
 */
-function createOptionParseState(parseResult) {
+function createOptionParseState(parseResult, rawInput, valueParser) {
+	if (isDerivedValueParser(valueParser)) recordDerivedRawInput(parseResult, rawInput);
 	return parseResult;
 }
 function buildTraceEntry(kind, rawInput, consumed, valueParser, parseResult, optionNames$1) {
@@ -88,6 +89,11 @@ function resolveDerivedCompletionSync(derivedMetadata, state, exec) {
 	}, traceEntry.rawInput, exec.dependencyRuntime);
 	return replayed ?? traceEntry.preliminaryResult ?? state;
 }
+function includeDependencyFailureChain(error, dependencyMetadata, exec) {
+	const sourceId = dependencyMetadata?.source?.sourceId;
+	if (sourceId == null || exec?.dependencyRuntime == null) return error;
+	return includeSourceFailureChain(error, sourceId, exec.dependencyRuntime);
+}
 async function resolveDerivedCompletionAsync(derivedMetadata, state, exec) {
 	if (derivedMetadata?.derived == null || exec?.dependencyRuntime == null) return state;
 	const traceEntry = exec.trace?.get(exec.path);
@@ -499,7 +505,7 @@ function option(...args) {
 						success: true,
 						next: {
 							...next,
-							state: createOptionParseState(parseResult),
+							state: createOptionParseState(parseResult, rawInput, syncValueParser),
 							buffer: context.buffer.slice(2)
 						},
 						consumed: context.buffer.slice(0, 2)
@@ -511,7 +517,7 @@ function option(...args) {
 						success: true,
 						next: {
 							...next,
-							state: createOptionParseState(parseResult),
+							state: createOptionParseState(parseResult, rawInput, valueParser),
 							buffer: context.buffer.slice(2)
 						},
 						consumed: context.buffer.slice(0, 2)
@@ -542,7 +548,7 @@ function option(...args) {
 						success: true,
 						next: {
 							...next,
-							state: createOptionParseState(parseResult),
+							state: createOptionParseState(parseResult, rawInput, syncValueParser),
 							buffer: context.buffer.slice(1)
 						},
 						consumed: context.buffer.slice(0, 1)
@@ -554,7 +560,7 @@ function option(...args) {
 						success: true,
 						next: {
 							...next,
-							state: createOptionParseState(parseResult),
+							state: createOptionParseState(parseResult, rawInput, valueParser),
 							buffer: context.buffer.slice(1)
 						},
 						consumed: context.buffer.slice(0, 1)
@@ -616,7 +622,7 @@ function option(...args) {
 				const resolvedState = valueParser != null && dependencyMetadata?.derived != null ? resolveDerivedCompletionSync(dependencyMetadata, state, exec) : state;
 				return resolvedState.success ? resolvedState : {
 					success: false,
-					error: formatInvalidValueError(resolvedState.error)
+					error: formatInvalidValueError(includeDependencyFailureChain(resolvedState.error, dependencyMetadata, exec))
 				};
 			};
 			const completeAsync = async () => {
@@ -625,7 +631,7 @@ function option(...args) {
 				const resolved = await resolveDerivedCompletionAsync(dependencyMetadata, state, exec);
 				return resolved.success ? resolved : {
 					success: false,
-					error: formatInvalidValueError(resolved.error)
+					error: formatInvalidValueError(includeDependencyFailureChain(resolved.error, dependencyMetadata, exec))
 				};
 			};
 			return dispatchByMode(mode, completeSync, completeAsync);
@@ -1242,7 +1248,7 @@ function argument(valueParser, options = {}) {
 					next: {
 						...next,
 						buffer: context.buffer.slice(i + 1),
-						state: createOptionParseState(parseResult),
+						state: createOptionParseState(parseResult, rawInput, syncValueParser),
 						optionsTerminated
 					},
 					consumed: context.buffer.slice(0, i + 1)
@@ -1255,7 +1261,7 @@ function argument(valueParser, options = {}) {
 					next: {
 						...next,
 						buffer: context.buffer.slice(i + 1),
-						state: createOptionParseState(parseResult),
+						state: createOptionParseState(parseResult, rawInput, valueParser),
 						optionsTerminated
 					},
 					consumed: context.buffer.slice(0, i + 1)
@@ -1272,7 +1278,7 @@ function argument(valueParser, options = {}) {
 				const resolvedState = dependencyMetadata?.derived != null ? resolveDerivedCompletionSync(dependencyMetadata, state, exec) : state;
 				return resolvedState.success ? resolvedState : {
 					success: false,
-					error: formatInvalidValueError(resolvedState.error)
+					error: formatInvalidValueError(includeDependencyFailureChain(resolvedState.error, dependencyMetadata, exec))
 				};
 			};
 			const completeAsync = async () => {
@@ -1281,7 +1287,7 @@ function argument(valueParser, options = {}) {
 				const resolved = await resolveDerivedCompletionAsync(dependencyMetadata, state, exec);
 				return resolved.success ? resolved : {
 					success: false,
-					error: formatInvalidValueError(resolved.error)
+					error: formatInvalidValueError(includeDependencyFailureChain(resolved.error, dependencyMetadata, exec))
 				};
 			};
 			return dispatchByMode(valueParser.mode, completeSync, completeAsync);

package/package.json

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

package/skills/optique/SKILL.md

@@ -52,6 +52,10 @@ Core rules
  -  Async value parsers make the containing parser async. If you use packages
     such as *@optique/git*, remember to `await run(...)`, `await parse(...)`, or
     `await runParser(...)` as appropriate.
+ -  Use `dependency()` when one value parser controls another's valid values.
+    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.
  -  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.
@@ -228,6 +232,9 @@ Common mistakes checklist
     `message` values.
  -  Do not forget to register source contexts when using `bindEnv()`,
     `bindConfig()`, or `bindDerivedDefault()`.
+ -  Do not flatten a multi-level dependency graph into duplicated one-level
+    factories. Wrap each derived value that becomes a later source with
+    `dependency()` and derive the next parser from it.
  -  Do not probe runtime capabilities eagerly before constructing a prompt
     parser. Put synchronous or asynchronous checks in the prompt config's
     `when` field and provide a typed `otherwise` value. The check then runs