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

package/dist/dependency-runtime.cjs

@@ -541,6 +541,16 @@ function propagateRuntimeSourceFailures(nodes, runtime) {
 		runtime.propagateSourceFailure(metadata.derived.dependencyIds, formatDependencyNodeMetavar(node), metadata.source?.sourceId);
 	}
 }
+/**
+* Appends the recorded dependency chain to a source failure.
+*
+* @param error The source failure to annotate.
+* @param sourceId The identifier of the failed source.
+* @param runtime The dependency runtime that recorded the failure chain.
+* @returns The annotated failure, or the original failure when no chain exists.
+* @internal
+* @since 1.3.0
+*/
 function includeSourceFailureChain(error, sourceId, runtime) {
 	const chain = runtime.getSourceFailureChain(sourceId);
 	return chain == null || chain.length < 2 ? error : require_message.message`${error} Dependency chain: ${chain.join(" -> ")}.`;
@@ -1315,8 +1325,9 @@ function buildRuntimeNodesFromPairs(pairs, state, parentPath) {
 	const nodes = [];
 	for (const [field, parser] of pairs) {
 		const fieldState = Object.hasOwn(state, field) ? state[field] : void 0;
-		const rawInput = extractRawInputFromState(fieldState);
-		const defaultDependencyValues = getDefaultDependencySnapshot(fieldState);
+		const isDerived = parser.dependencyMetadata?.derived != null;
+		const rawInput = isDerived ? extractRawInputFromState(fieldState) : void 0;
+		const defaultDependencyValues = isDerived ? getDefaultDependencySnapshot(fieldState) : void 0;
 		nodes.push({
 			path: [...prefix, field],
 			parser,
@@ -1346,8 +1357,9 @@ function buildRuntimeNodesFromArray(parsers, stateArray, parentPath) {
 	for (let i = 0; i < parsers.length; i++) {
 		const parser = parsers[i];
 		const elemState = i < stateArray.length ? stateArray[i] : void 0;
-		const rawInput = extractRawInputFromState(elemState);
-		const defaultDependencyValues = getDefaultDependencySnapshot(elemState);
+		const isDerived = parser.dependencyMetadata?.derived != null;
+		const rawInput = isDerived ? extractRawInputFromState(elemState) : void 0;
+		const defaultDependencyValues = isDerived ? getDefaultDependencySnapshot(elemState) : void 0;
 		nodes.push({
 			path: [...prefix, i],
 			parser,
@@ -1400,6 +1412,7 @@ exports.effectfulSchedulingNodesKey = effectfulSchedulingNodesKey;
 exports.extractRawInputFromState = extractRawInputFromState;
 exports.fillMissingSourceDefaults = fillMissingSourceDefaults;
 exports.fillMissingSourceDefaultsAsync = fillMissingSourceDefaultsAsync;
+exports.includeSourceFailureChain = includeSourceFailureChain;
 exports.orderDependencyNodes = orderDependencyNodes;
 exports.recordDerivedRawInput = recordDerivedRawInput;
 exports.replayDerivedParser = replayDerivedParser;

package/dist/dependency-runtime.d.cts

@@ -309,6 +309,17 @@ declare function orderDependencyNodes(nodes: readonly RuntimeNode[]): readonly R
 declare function resolveDerivedSourceValues(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext, options?: ResolveDerivedSourceValuesOptions): void;
 /** Async version of {@link resolveDerivedSourceValues}. */
 declare function resolveDerivedSourceValuesAsync(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext, options?: ResolveDerivedSourceValuesOptions): Promise<void>;
+/**
+ * Appends the recorded dependency chain to a source failure.
+ *
+ * @param error The source failure to annotate.
+ * @param sourceId The identifier of the failed source.
+ * @param runtime The dependency runtime that recorded the failure chain.
+ * @returns The annotated failure, or the original failure when no chain exists.
+ * @internal
+ * @since 1.3.0
+ */
+declare function includeSourceFailureChain(error: Message, sourceId: symbol, runtime: DependencyRuntimeContext): Message;
 /**
  * Fills missing source defaults for source parsers whose state is
  * unpopulated.
@@ -683,4 +694,4 @@ declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
   readonly initialState?: unknown;
 }>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
 //#endregion
-export { CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ReplayKey, ResolveDerivedSourceValuesOptions, RuntimeNode, SchedulingBarrierContext, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, orderDependencyNodes, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };
+export { CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ReplayKey, ResolveDerivedSourceValuesOptions, RuntimeNode, SchedulingBarrierContext, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };

package/dist/dependency-runtime.d.ts

@@ -309,6 +309,17 @@ declare function orderDependencyNodes(nodes: readonly RuntimeNode[]): readonly R
 declare function resolveDerivedSourceValues(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext, options?: ResolveDerivedSourceValuesOptions): void;
 /** Async version of {@link resolveDerivedSourceValues}. */
 declare function resolveDerivedSourceValuesAsync(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext, options?: ResolveDerivedSourceValuesOptions): Promise<void>;
+/**
+ * Appends the recorded dependency chain to a source failure.
+ *
+ * @param error The source failure to annotate.
+ * @param sourceId The identifier of the failed source.
+ * @param runtime The dependency runtime that recorded the failure chain.
+ * @returns The annotated failure, or the original failure when no chain exists.
+ * @internal
+ * @since 1.3.0
+ */
+declare function includeSourceFailureChain(error: Message, sourceId: symbol, runtime: DependencyRuntimeContext): Message;
 /**
  * Fills missing source defaults for source parsers whose state is
  * unpopulated.
@@ -683,4 +694,4 @@ declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
   readonly initialState?: unknown;
 }>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
 //#endregion
-export { CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ReplayKey, ResolveDerivedSourceValuesOptions, RuntimeNode, SchedulingBarrierContext, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, orderDependencyNodes, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };
+export { CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ReplayKey, ResolveDerivedSourceValuesOptions, RuntimeNode, SchedulingBarrierContext, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };

package/dist/dependency-runtime.js

@@ -541,6 +541,16 @@ function propagateRuntimeSourceFailures(nodes, runtime) {
 		runtime.propagateSourceFailure(metadata.derived.dependencyIds, formatDependencyNodeMetavar(node), metadata.source?.sourceId);
 	}
 }
+/**
+* Appends the recorded dependency chain to a source failure.
+*
+* @param error The source failure to annotate.
+* @param sourceId The identifier of the failed source.
+* @param runtime The dependency runtime that recorded the failure chain.
+* @returns The annotated failure, or the original failure when no chain exists.
+* @internal
+* @since 1.3.0
+*/
 function includeSourceFailureChain(error, sourceId, runtime) {
 	const chain = runtime.getSourceFailureChain(sourceId);
 	return chain == null || chain.length < 2 ? error : message`${error} Dependency chain: ${chain.join(" -> ")}.`;
@@ -1315,8 +1325,9 @@ function buildRuntimeNodesFromPairs(pairs, state, parentPath) {
 	const nodes = [];
 	for (const [field, parser] of pairs) {
 		const fieldState = Object.hasOwn(state, field) ? state[field] : void 0;
-		const rawInput = extractRawInputFromState(fieldState);
-		const defaultDependencyValues = getDefaultDependencySnapshot(fieldState);
+		const isDerived = parser.dependencyMetadata?.derived != null;
+		const rawInput = isDerived ? extractRawInputFromState(fieldState) : void 0;
+		const defaultDependencyValues = isDerived ? getDefaultDependencySnapshot(fieldState) : void 0;
 		nodes.push({
 			path: [...prefix, field],
 			parser,
@@ -1346,8 +1357,9 @@ function buildRuntimeNodesFromArray(parsers, stateArray, parentPath) {
 	for (let i = 0; i < parsers.length; i++) {
 		const parser = parsers[i];
 		const elemState = i < stateArray.length ? stateArray[i] : void 0;
-		const rawInput = extractRawInputFromState(elemState);
-		const defaultDependencyValues = getDefaultDependencySnapshot(elemState);
+		const isDerived = parser.dependencyMetadata?.derived != null;
+		const rawInput = isDerived ? extractRawInputFromState(elemState) : void 0;
+		const defaultDependencyValues = isDerived ? getDefaultDependencySnapshot(elemState) : void 0;
 		nodes.push({
 			path: [...prefix, i],
 			parser,
@@ -1384,4 +1396,4 @@ function getDefaultDependencySnapshotInner(state, visited) {
 }
 
 //#endregion
-export { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, orderDependencyNodes, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };
+export { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };

package/dist/primitives.cjs

@@ -36,8 +36,8 @@ function isTerminalValueState(state) {
 * execution trace.
 * @internal
 */
-function createOptionParseState(parseResult, rawInput) {
-	require_dependency_runtime.recordDerivedRawInput(parseResult, rawInput);
+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) {
@@ -92,9 +92,7 @@ function resolveDerivedCompletionSync(derivedMetadata, state, exec) {
 function includeDependencyFailureChain(error, dependencyMetadata, exec) {
 	const sourceId = dependencyMetadata?.source?.sourceId;
 	if (sourceId == null || exec?.dependencyRuntime == null) return error;
-	const chain = exec.dependencyRuntime.getSourceFailureChain(sourceId);
-	if (chain == null || chain.length < 2) return error;
-	return require_message.message`${error} Dependency chain: ${chain.join(" -> ")}.`;
+	return require_dependency_runtime.includeSourceFailureChain(error, sourceId, exec.dependencyRuntime);
 }
 async function resolveDerivedCompletionAsync(derivedMetadata, state, exec) {
 	if (derivedMetadata?.derived == null || exec?.dependencyRuntime == null) return state;
@@ -507,7 +505,7 @@ function option(...args) {
 						success: true,
 						next: {
 							...next,
-							state: createOptionParseState(parseResult, rawInput),
+							state: createOptionParseState(parseResult, rawInput, syncValueParser),
 							buffer: context.buffer.slice(2)
 						},
 						consumed: context.buffer.slice(0, 2)
@@ -519,7 +517,7 @@ function option(...args) {
 						success: true,
 						next: {
 							...next,
-							state: createOptionParseState(parseResult, rawInput),
+							state: createOptionParseState(parseResult, rawInput, valueParser),
 							buffer: context.buffer.slice(2)
 						},
 						consumed: context.buffer.slice(0, 2)
@@ -550,7 +548,7 @@ function option(...args) {
 						success: true,
 						next: {
 							...next,
-							state: createOptionParseState(parseResult, rawInput),
+							state: createOptionParseState(parseResult, rawInput, syncValueParser),
 							buffer: context.buffer.slice(1)
 						},
 						consumed: context.buffer.slice(0, 1)
@@ -562,7 +560,7 @@ function option(...args) {
 						success: true,
 						next: {
 							...next,
-							state: createOptionParseState(parseResult, rawInput),
+							state: createOptionParseState(parseResult, rawInput, valueParser),
 							buffer: context.buffer.slice(1)
 						},
 						consumed: context.buffer.slice(0, 1)
@@ -1250,7 +1248,7 @@ function argument(valueParser, options = {}) {
 					next: {
 						...next,
 						buffer: context.buffer.slice(i + 1),
-						state: createOptionParseState(parseResult, rawInput),
+						state: createOptionParseState(parseResult, rawInput, syncValueParser),
 						optionsTerminated
 					},
 					consumed: context.buffer.slice(0, i + 1)
@@ -1263,7 +1261,7 @@ function argument(valueParser, options = {}) {
 					next: {
 						...next,
 						buffer: context.buffer.slice(i + 1),
-						state: createOptionParseState(parseResult, rawInput),
+						state: createOptionParseState(parseResult, rawInput, valueParser),
 						optionsTerminated
 					},
 					consumed: context.buffer.slice(0, i + 1)

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, recordDerivedRawInput, 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,8 +36,8 @@ function isTerminalValueState(state) {
 * execution trace.
 * @internal
 */
-function createOptionParseState(parseResult, rawInput) {
-	recordDerivedRawInput(parseResult, rawInput);
+function createOptionParseState(parseResult, rawInput, valueParser) {
+	if (isDerivedValueParser(valueParser)) recordDerivedRawInput(parseResult, rawInput);
 	return parseResult;
 }
 function buildTraceEntry(kind, rawInput, consumed, valueParser, parseResult, optionNames$1) {
@@ -92,9 +92,7 @@ function resolveDerivedCompletionSync(derivedMetadata, state, exec) {
 function includeDependencyFailureChain(error, dependencyMetadata, exec) {
 	const sourceId = dependencyMetadata?.source?.sourceId;
 	if (sourceId == null || exec?.dependencyRuntime == null) return error;
-	const chain = exec.dependencyRuntime.getSourceFailureChain(sourceId);
-	if (chain == null || chain.length < 2) return error;
-	return message`${error} Dependency chain: ${chain.join(" -> ")}.`;
+	return includeSourceFailureChain(error, sourceId, exec.dependencyRuntime);
 }
 async function resolveDerivedCompletionAsync(derivedMetadata, state, exec) {
 	if (derivedMetadata?.derived == null || exec?.dependencyRuntime == null) return state;
@@ -507,7 +505,7 @@ function option(...args) {
 						success: true,
 						next: {
 							...next,
-							state: createOptionParseState(parseResult, rawInput),
+							state: createOptionParseState(parseResult, rawInput, syncValueParser),
 							buffer: context.buffer.slice(2)
 						},
 						consumed: context.buffer.slice(0, 2)
@@ -519,7 +517,7 @@ function option(...args) {
 						success: true,
 						next: {
 							...next,
-							state: createOptionParseState(parseResult, rawInput),
+							state: createOptionParseState(parseResult, rawInput, valueParser),
 							buffer: context.buffer.slice(2)
 						},
 						consumed: context.buffer.slice(0, 2)
@@ -550,7 +548,7 @@ function option(...args) {
 						success: true,
 						next: {
 							...next,
-							state: createOptionParseState(parseResult, rawInput),
+							state: createOptionParseState(parseResult, rawInput, syncValueParser),
 							buffer: context.buffer.slice(1)
 						},
 						consumed: context.buffer.slice(0, 1)
@@ -562,7 +560,7 @@ function option(...args) {
 						success: true,
 						next: {
 							...next,
-							state: createOptionParseState(parseResult, rawInput),
+							state: createOptionParseState(parseResult, rawInput, valueParser),
 							buffer: context.buffer.slice(1)
 						},
 						consumed: context.buffer.slice(0, 1)
@@ -1250,7 +1248,7 @@ function argument(valueParser, options = {}) {
 					next: {
 						...next,
 						buffer: context.buffer.slice(i + 1),
-						state: createOptionParseState(parseResult, rawInput),
+						state: createOptionParseState(parseResult, rawInput, syncValueParser),
 						optionsTerminated
 					},
 					consumed: context.buffer.slice(0, i + 1)
@@ -1263,7 +1261,7 @@ function argument(valueParser, options = {}) {
 					next: {
 						...next,
 						buffer: context.buffer.slice(i + 1),
-						state: createOptionParseState(parseResult, rawInput),
+						state: createOptionParseState(parseResult, rawInput, valueParser),
 						optionsTerminated
 					},
 					consumed: context.buffer.slice(0, i + 1)

package/package.json

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