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

package/dist/parser.js

@@ -1,16 +1,29 @@
 import { injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
 import { cloneMessage, message } from "./message.js";
-import { isDeferredParseState } from "./dependency.js";
-import { collectSourcesFromState, createDependencyRuntimeContext, resolveStateWithRuntime, resolveStateWithRuntimeAsync } from "./dependency-runtime.js";
-import { dispatchByMode } from "./mode-dispatch.js";
 import { cloneUsage, normalizeUsage } from "./usage.js";
 import { cloneDocEntry, isDocEntryHidden } from "./doc.js";
-import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
+import { dispatchByMode } from "./mode-dispatch.js";
+import { createInputTrace } from "./input-trace.js";
 import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
+import { collectExplicitSourceValues, collectExplicitSourceValuesAsync, createDependencyRuntimeContext } from "./dependency-runtime.js";
+import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 
 //#region src/parser.ts
 /**
+* Internal marker for wrappers whose `{ hasCliValue: false }` states should
+* be treated as unmatched dependency-source states during completion-time
+* Phase 1.
+*
+* Wrappers like `bindEnv()` and `bindConfig()` opt in because their missing
+* CLI states still carry enough fallback context to pre-complete exactly
+* once. Wrappers like `prompt()` intentionally do not opt in because
+* prompted values are not yet registered as dependency sources.
+*
+* @internal
+*/
+const unmatchedNonCliDependencySourceStateMarker = Symbol.for("@optique/core/parser/unmatchedNonCliDependencySourceStateMarker");
+/**
 * Creates a {@link ParserContext} from a {@link ParseFrame} and an
 * {@link ExecutionContext}.  The returned object provides both structured
 * access (`frame`, `exec`) and flat access (`buffer`, `state`, etc.)
@@ -25,6 +38,7 @@ import { argument, command, constant, fail, flag, option, passThrough } from "./
 function createParserContext(frame, exec) {
 	return {
 		exec,
+		trace: exec.trace,
 		buffer: frame.buffer,
 		state: frame.state,
 		optionsTerminated: frame.optionsTerminated,
@@ -55,6 +69,8 @@ function injectAnnotationsIntoState(state, options) {
 *          successful or not.  If successful, it contains the parsed value of
 *          type `T`.  If not, it contains an error message describing the
 *          failure.
+* @throws {TypeError} When a synchronous dependency source extractor returns a
+*         thenable during completion-time dependency seeding.
 * @since 0.9.0 Renamed from the original `parse` function which now delegates
 *              to this for sync parsers.
 * @since 0.10.0 Added optional `options` parameter for annotations support.
@@ -65,7 +81,8 @@ function parseSync(parser, args, options) {
 	const exec = {
 		usage: parser.usage,
 		phase: "parse",
-		path: []
+		path: [],
+		trace: createInputTrace()
 	};
 	let context = createParserContext({
 		buffer: args,
@@ -86,14 +103,14 @@ function parseSync(parser, args, options) {
 		};
 	} while (context.buffer.length > 0);
 	const runtime = createDependencyRuntimeContext();
-	const resolvedState = isDeferredParseState(context.state) ? resolveStateWithRuntime(context.state, runtime) : context.state;
 	const completeExec = {
 		...exec,
 		phase: "complete",
 		dependencyRuntime: runtime,
-		dependencyRegistry: runtime.registry
+		dependencyRegistry: runtime.registry,
+		trace: context.exec?.trace ?? context.trace ?? exec.trace
 	};
-	const endResult = parser.complete(resolvedState, completeExec);
+	const endResult = parser.complete(context.state, completeExec);
 	return endResult.success ? {
 		success: true,
 		value: shouldUnwrapAnnotatedValue ? unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
@@ -136,7 +153,8 @@ async function parseAsync(parser, args, options) {
 	const exec = {
 		usage: parser.usage,
 		phase: "parse",
-		path: []
+		path: [],
+		trace: createInputTrace()
 	};
 	let context = createParserContext({
 		buffer: args,
@@ -157,14 +175,14 @@ async function parseAsync(parser, args, options) {
 		};
 	} while (context.buffer.length > 0);
 	const runtime = createDependencyRuntimeContext();
-	const resolvedState = isDeferredParseState(context.state) ? await resolveStateWithRuntimeAsync(context.state, runtime) : context.state;
 	const completeExec = {
 		...exec,
 		phase: "complete",
 		dependencyRuntime: runtime,
-		dependencyRegistry: runtime.registry
+		dependencyRegistry: runtime.registry,
+		trace: context.exec?.trace ?? context.trace ?? exec.trace
 	};
-	const endResult = await parser.complete(resolvedState, completeExec);
+	const endResult = await parser.complete(context.state, completeExec);
 	return endResult.success ? {
 		success: true,
 		value: shouldUnwrapAnnotatedValue ? unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
@@ -195,6 +213,8 @@ async function parseAsync(parser, args, options) {
 * @param options Optional {@link ParseOptions} for customizing parsing behavior.
 * @returns A {@link Result} object (for sync) or Promise thereof (for async)
 *          indicating whether the parsing was successful or not.
+* @throws {TypeError} When a synchronous dependency source extractor returns a
+*         thenable during completion-time dependency seeding.
 * @since 0.10.0 Added optional `options` parameter for annotations support.
 */
 function parse(parser, args, options) {
@@ -232,6 +252,8 @@ function parse(parser, args, options) {
 * const suggestions2 = suggestSync(parser, ["-v", "--format="]);
 * // Returns: [{ text: "--format=json" }, { text: "--format=yaml" }]
 * ```
+* @throws {TypeError} When a synchronous dependency source extractor returns a
+*         thenable during suggestion seeding.
 * @since 0.6.0
 * @since 0.9.0 Renamed from the original `suggest` function.
 * @since 0.10.0 Added optional `options` parameter for annotations support.
@@ -247,16 +269,17 @@ function suggestSync(parser, args, options) {
 	}, {
 		usage: parser.usage,
 		phase: "suggest",
-		path: []
+		path: [],
+		trace: createInputTrace()
 	});
 	while (context.buffer.length > 0) {
 		const result = parser.parse(context);
-		if (!result.success) return Array.from(parser.suggest(withSuggestRuntime(context), prefix));
+		if (!result.success) return Array.from(parser.suggest(withSuggestRuntime(parser, context), prefix));
 		const previousBuffer = context.buffer;
 		context = result.next;
 		if (isBufferUnchanged(previousBuffer, context.buffer)) return [];
 	}
-	return Array.from(parser.suggest(withSuggestRuntime(context), prefix));
+	return Array.from(parser.suggest(withSuggestRuntime(parser, context), prefix));
 }
 /**
 * Creates a dependency runtime from the current parser state and returns
@@ -265,19 +288,54 @@ function suggestSync(parser, args, options) {
 * a context with a dependency registry.
 * @internal
 */
-function withSuggestRuntime(context) {
+function withSuggestRuntime(parser, context) {
+	const runtime = createDependencyRuntimeContext();
+	const nodes = getParserSuggestRuntimeNodes(parser, context.state, context.exec?.path ?? []);
+	if (nodes.length > 0) collectExplicitSourceValues(nodes, runtime);
+	return {
+		...context,
+		dependencyRegistry: runtime.registry,
+		exec: context.exec ? {
+			...context.exec,
+			dependencyRuntime: runtime,
+			dependencyRegistry: runtime.registry
+		} : void 0
+	};
+}
+async function withSuggestRuntimeAsync(parser, context) {
 	const runtime = createDependencyRuntimeContext();
-	collectSourcesFromState(context.state, runtime);
+	const nodes = getParserSuggestRuntimeNodes(parser, context.state, context.exec?.path ?? []);
+	if (nodes.length > 0) await collectExplicitSourceValuesAsync(nodes, runtime);
 	return {
 		...context,
 		dependencyRegistry: runtime.registry,
 		exec: context.exec ? {
 			...context.exec,
+			dependencyRuntime: runtime,
 			dependencyRegistry: runtime.registry
 		} : void 0
 	};
 }
 /**
+* Returns suggest-time runtime nodes for a parser, falling back to the
+* parser's own source metadata when it does not expose a custom hook.
+*
+* @param parser The parser whose suggest-time runtime nodes should be resolved.
+* @param state The current parser state.
+* @param path The path to this parser within the parse tree.
+* @returns The runtime nodes used to seed suggest-time dependency resolution.
+* @internal
+*/
+function getParserSuggestRuntimeNodes(parser, state, path) {
+	if (typeof parser.getSuggestRuntimeNodes === "function") return parser.getSuggestRuntimeNodes(state, path);
+	if (parser.dependencyMetadata?.source == null) return [];
+	return [{
+		path,
+		parser,
+		state
+	}];
+}
+/**
 * Generates command-line suggestions based on current parsing state.
 * This function processes the input arguments up to the last argument,
 * then calls the parser's suggest method with the remaining prefix.
@@ -308,12 +366,13 @@ async function suggestAsync(parser, args, options) {
 	}, {
 		usage: parser.usage,
 		phase: "suggest",
-		path: []
+		path: [],
+		trace: createInputTrace()
 	});
 	while (context.buffer.length > 0) {
 		const result = await parser.parse(context);
 		if (!result.success) {
-			const ctx$1 = withSuggestRuntime(context);
+			const ctx$1 = await withSuggestRuntimeAsync(parser, context);
 			const suggestions$1 = [];
 			for await (const suggestion of parser.suggest(ctx$1, prefix)) suggestions$1.push(suggestion);
 			return suggestions$1;
@@ -322,7 +381,7 @@ async function suggestAsync(parser, args, options) {
 		context = result.next;
 		if (isBufferUnchanged(previousBuffer, context.buffer)) return [];
 	}
-	const ctx = withSuggestRuntime(context);
+	const ctx = await withSuggestRuntimeAsync(parser, context);
 	const suggestions = [];
 	for await (const suggestion of parser.suggest(ctx, prefix)) suggestions.push(suggestion);
 	return suggestions;
@@ -347,6 +406,8 @@ async function suggestAsync(parser, args, options) {
 * @param options Optional {@link ParseOptions} for customizing parsing behavior.
 * @returns An array of {@link Suggestion} objects (for sync) or Promise thereof
 *          (for async) containing completion candidates.
+* @throws {TypeError} When a synchronous dependency source extractor returns a
+*         thenable during suggestion seeding.
 * @since 0.6.0
 * @since 0.10.0 Added optional `options` parameter for annotations support.
 */
@@ -561,4 +622,4 @@ function buildDocPage(parser, context, args) {
 }
 
 //#endregion
-export { DuplicateOptionError, WithDefaultError, argument, command, concat, conditional, constant, createParserContext, fail, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };
+export { DuplicateOptionError, WithDefaultError, argument, command, concat, conditional, constant, createParserContext, fail, flag, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, unmatchedNonCliDependencySourceStateMarker, withDefault };