@optique/core 1.0.0-dev.1580 → 1.0.0-dev.1590

package/dist/parser.d.ts

@@ -164,13 +164,17 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * message.
    * @param state The current state of the parser, which may contain accumulated
    *              data or context needed to produce the final value.
+   * @param exec Optional shared execution context.  When provided, gives the
+   *             parser access to cross-cutting runtime data such as the current
+   *             execution phase and dependency registry.
    * @returns A result object indicating success or failure of
    *          the transformation.  If successful, it should contain
    *          the parsed value of type {@link TValue}.  If not applicable,
    *          it should return an error message.
    *          In async mode, returns a Promise that resolves to the result.
+   * @since 1.0.0 Added optional `exec` parameter.
    */
-  complete(state: TState): ModeValue<M, ValueParserResult<TValue>>;
+  complete(state: TState, exec?: ExecutionContext): ModeValue<M, ValueParserResult<TValue>>;
   /**
    * Generates next-step suggestions based on the current context
    * and an optional prefix.  This can be used to provide shell completion
@@ -221,10 +225,12 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * source) has resolved.
    *
    * @param state The current parser state.
+   * @param exec Optional shared execution context.
    * @returns `true` if completion should be deferred.
    * @since 1.0.0
+   * @since 1.0.0 Added optional `exec` parameter.
    */
-  shouldDeferCompletion?(state: TState): boolean;
+  shouldDeferCompletion?(state: TState, exec?: ExecutionContext): boolean;
   /**
    * Normalizes a parsed value according to the underlying value parser's
    * configuration.  When present, {@link withDefault} calls this method
@@ -246,11 +252,82 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    */
   normalizeValue?(value: TValue): TValue;
 }
+/**
+ * Parser-local frame data containing the input buffer and parser state.
+ * This represents the per-parser progress during parsing, separated from
+ * cross-cutting execution context.
+ * @template TState The type of the state used during parsing.
+ * @since 1.0.0
+ */
+interface ParseFrame<TState> {
+  /**
+   * The array of input strings that the parser is currently processing.
+   */
+  readonly buffer: readonly string[];
+  /**
+   * The current state of the parser, which is used to track
+   * the progress of parsing and any accumulated data.
+   */
+  readonly state: TState;
+  /**
+   * A flag indicating whether no more options should be parsed and instead
+   * the remaining input should be treated as positional arguments.
+   */
+  readonly optionsTerminated: boolean;
+}
+/**
+ * The phase of the execution pipeline.
+ * @since 1.0.0
+ */
+type ExecutionPhase = "parse" | "precomplete" | "resolve" | "complete" | "suggest";
+/**
+ * Shared execution context carrying cross-cutting runtime data.
+ * This includes information that is shared across all parsers in a parse
+ * tree, such as usage information, dependency registries, and the current
+ * execution phase.
+ * @since 1.0.0
+ */
+interface ExecutionContext {
+  /**
+   * Usage information for the entire parser tree.
+   */
+  readonly usage: Usage;
+  /**
+   * The current phase of the execution pipeline.
+   */
+  readonly phase: ExecutionPhase;
+  /**
+   * The path from the root to the current parser in the parse tree.
+   * Used by constructs to track the current position during dependency
+   * resolution and completion.
+   */
+  readonly path: readonly PropertyKey[];
+  /**
+   * A registry containing resolved dependency values from DependencySource
+   * parsers.
+   * @since 0.10.0
+   */
+  readonly dependencyRegistry?: DependencyRegistryLike;
+}
 /**
  * The context of the parser, which includes the input buffer and the state.
+ *
+ * `ParserContext` provides structured access to shared execution context
+ * via {@link exec}, and flat access to all fields for backward
+ * compatibility.
+ *
  * @template TState The type of the state used during parsing.
  */
 interface ParserContext<TState> {
+  /**
+   * Shared execution context (usage, phase, path, dependencyRegistry).
+   *
+   * Present when the context was created via {@link createParserContext}.
+   * Later runtime work will make this field required.
+   *
+   * @since 1.0.0
+   */
+  readonly exec?: ExecutionContext;
   /**
    * The array of input strings that the parser is currently processing.
    */
@@ -284,6 +361,19 @@ interface ParserContext<TState> {
    */
   readonly dependencyRegistry?: DependencyRegistryLike;
 }
+/**
+ * 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.)
+ * for backward compatibility.
+ *
+ * @template TState The type of the state used during parsing.
+ * @param frame Parser-local frame data.
+ * @param exec Shared execution context.
+ * @returns A {@link ParserContext} instance.
+ * @since 1.0.0
+ */
+declare function createParserContext<TState>(frame: ParseFrame<TState>, exec: ExecutionContext): ParserContext<TState>;
 /**
  * Represents a suggestion for command-line completion or guidance.
  * @since 0.6.0
@@ -648,4 +738,4 @@ declare function getDocPage(parser: Parser<"sync", unknown, unknown>, argsOrOpti
 declare function getDocPage(parser: Parser<"async", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): Promise<DocPage | undefined>;
 declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, 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 { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, ExecutionContext, ExecutionPhase, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, 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 };

package/dist/parser.js

@@ -8,6 +8,28 @@ import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from
 import { argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
 
 //#region src/parser.ts
+/**
+* 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.)
+* for backward compatibility.
+*
+* @template TState The type of the state used during parsing.
+* @param frame Parser-local frame data.
+* @param exec Shared execution context.
+* @returns A {@link ParserContext} instance.
+* @since 1.0.0
+*/
+function createParserContext(frame, exec) {
+	return {
+		exec,
+		buffer: frame.buffer,
+		state: frame.state,
+		optionsTerminated: frame.optionsTerminated,
+		usage: exec.usage,
+		dependencyRegistry: exec.dependencyRegistry
+	};
+}
 function injectAnnotationsIntoState(state, options) {
 	const annotations = options?.annotations;
 	if (annotations == null) return state;
@@ -38,12 +60,16 @@ function injectAnnotationsIntoState(state, options) {
 function parseSync(parser, args, options) {
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
 	const shouldUnwrapAnnotatedValue = options?.annotations != null || isInjectedAnnotationWrapper(parser.initialState);
-	let context = {
+	const exec = {
+		usage: parser.usage,
+		phase: "parse",
+		path: []
+	};
+	let context = createParserContext({
 		buffer: args,
-		optionsTerminated: false,
 		state: initialState,
-		usage: parser.usage
-	};
+		optionsTerminated: false
+	}, exec);
 	do {
 		const result = parser.parse(context);
 		if (!result.success) return {
@@ -57,7 +83,11 @@ function parseSync(parser, args, options) {
 			error: message`Unexpected option or argument: ${context.buffer[0]}.`
 		};
 	} while (context.buffer.length > 0);
-	const endResult = parser.complete(context.state);
+	const completeExec = {
+		...exec,
+		phase: "complete"
+	};
+	const endResult = parser.complete(context.state, completeExec);
 	return endResult.success ? {
 		success: true,
 		value: shouldUnwrapAnnotatedValue ? unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
@@ -97,12 +127,16 @@ function isBufferUnchanged(previous, current) {
 async function parseAsync(parser, args, options) {
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
 	const shouldUnwrapAnnotatedValue = options?.annotations != null || isInjectedAnnotationWrapper(parser.initialState);
-	let context = {
+	const exec = {
+		usage: parser.usage,
+		phase: "parse",
+		path: []
+	};
+	let context = createParserContext({
 		buffer: args,
-		optionsTerminated: false,
 		state: initialState,
-		usage: parser.usage
-	};
+		optionsTerminated: false
+	}, exec);
 	do {
 		const result = await parser.parse(context);
 		if (!result.success) return {
@@ -116,7 +150,11 @@ async function parseAsync(parser, args, options) {
 			error: message`Unexpected option or argument: ${context.buffer[0]}.`
 		};
 	} while (context.buffer.length > 0);
-	const endResult = await parser.complete(context.state);
+	const completeExec = {
+		...exec,
+		phase: "complete"
+	};
+	const endResult = await parser.complete(context.state, completeExec);
 	return endResult.success ? {
 		success: true,
 		value: shouldUnwrapAnnotatedValue ? unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
@@ -192,12 +230,15 @@ function suggestSync(parser, args, options) {
 	const allButLast = args.slice(0, -1);
 	const prefix = args[args.length - 1];
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	let context = {
+	let context = createParserContext({
 		buffer: allButLast,
-		optionsTerminated: false,
 		state: initialState,
-		usage: parser.usage
-	};
+		optionsTerminated: false
+	}, {
+		usage: parser.usage,
+		phase: "suggest",
+		path: []
+	});
 	while (context.buffer.length > 0) {
 		const result = parser.parse(context);
 		if (!result.success) return Array.from(parser.suggest(context, prefix));
@@ -231,12 +272,15 @@ async function suggestAsync(parser, args, options) {
 	const allButLast = args.slice(0, -1);
 	const prefix = args[args.length - 1];
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	let context = {
+	let context = createParserContext({
 		buffer: allButLast,
-		optionsTerminated: false,
 		state: initialState,
-		usage: parser.usage
-	};
+		optionsTerminated: false
+	}, {
+		usage: parser.usage,
+		phase: "suggest",
+		path: []
+	});
 	while (context.buffer.length > 0) {
 		const result = await parser.parse(context);
 		if (!result.success) {
@@ -486,4 +530,4 @@ function buildDocPage(parser, context, args) {
 }
 
 //#endregion
-export { DuplicateOptionError, WithDefaultError, argument, command, concat, conditional, constant, 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, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };

package/dist/primitives.cjs

@@ -53,7 +53,7 @@ function constant(value) {
 				consumed: []
 			};
 		},
-		complete(state) {
+		complete(state, _exec) {
 			return {
 				success: true,
 				value: state
@@ -110,7 +110,7 @@ function fail() {
 				error: require_message.message`No value provided.`
 			};
 		},
-		complete(_state) {
+		complete(_state, _exec) {
 			return {
 				success: false,
 				error: require_message.message`No value provided.`
@@ -500,7 +500,7 @@ function option(...args) {
 				error: require_suggestion.createErrorWithSuggestions(baseError, invalidOption, context.usage, "option")
 			};
 		},
-		complete(state) {
+		complete(state, _exec) {
 			if (state == null) return valueParser == null ? {
 				success: true,
 				value: false
@@ -742,7 +742,7 @@ function flag(...args) {
 				error: require_suggestion.createErrorWithSuggestions(baseError, invalidOption, context.usage, "option")
 			};
 		},
-		complete(state) {
+		complete(state, _exec) {
 			if (state == null) return {
 				success: false,
 				error: options.errors?.missing ? typeof options.errors.missing === "function" ? options.errors.missing(optionNames$1) : options.errors.missing : require_message.message`Required flag ${require_message.optionNames(optionNames$1)} is missing.`
@@ -881,7 +881,7 @@ function argument(valueParser, options = {}) {
 				consumed: context.buffer.slice(0, i + 1)
 			};
 		},
-		complete(state) {
+		complete(state, _exec) {
 			if (state == null) return {
 				success: false,
 				error: options.errors?.endOfInput ?? require_message.message`Expected a ${require_message.metavar(valueParser.metavar)}, but too few arguments.`
@@ -1104,7 +1104,7 @@ function command(name, parser, options = {}) {
 				error: options.errors?.invalidState ?? require_message.message`Invalid command state.`
 			};
 		},
-		complete(state) {
+		complete(state, exec) {
 			if (typeof state === "undefined") return {
 				success: false,
 				error: options.errors?.notFound ?? require_message.message`Command ${require_message.optionName(name)} was not matched.`
@@ -1117,13 +1117,13 @@ function command(name, parser, options = {}) {
 					state: parser.initialState
 				});
 				if (isAsync) return parseResultOrPromise.then((parseResult$1) => {
-					if (parseResult$1.success) return parser.complete(parseResult$1.next.state);
-					return parser.complete(parser.initialState);
+					if (parseResult$1.success) return parser.complete(parseResult$1.next.state, exec);
+					return parser.complete(parser.initialState, exec);
 				});
 				const parseResult = parseResultOrPromise;
-				if (parseResult.success) return parser.complete(parseResult.next.state);
-				return parser.complete(parser.initialState);
-			} else if (state[0] === "parsing") return parser.complete(state[1]);
+				if (parseResult.success) return parser.complete(parseResult.next.state, exec);
+				return parser.complete(parser.initialState, exec);
+			} else if (state[0] === "parsing") return parser.complete(state[1], exec);
 			return {
 				success: false,
 				error: options.errors?.invalidState ?? require_message.message`Invalid command state during completion.`
@@ -1324,7 +1324,7 @@ function passThrough(options = {}) {
 				error: require_message.message`Unknown passThrough format: ${format}.`
 			};
 		},
-		complete(state) {
+		complete(state, _exec) {
 			if (require_annotations.getAnnotations(state) == null) return {
 				success: true,
 				value: state

package/dist/primitives.js

@@ -53,7 +53,7 @@ function constant(value) {
 				consumed: []
 			};
 		},
-		complete(state) {
+		complete(state, _exec) {
 			return {
 				success: true,
 				value: state
@@ -110,7 +110,7 @@ function fail() {
 				error: message`No value provided.`
 			};
 		},
-		complete(_state) {
+		complete(_state, _exec) {
 			return {
 				success: false,
 				error: message`No value provided.`
@@ -500,7 +500,7 @@ function option(...args) {
 				error: createErrorWithSuggestions(baseError, invalidOption, context.usage, "option")
 			};
 		},
-		complete(state) {
+		complete(state, _exec) {
 			if (state == null) return valueParser == null ? {
 				success: true,
 				value: false
@@ -742,7 +742,7 @@ function flag(...args) {
 				error: createErrorWithSuggestions(baseError, invalidOption, context.usage, "option")
 			};
 		},
-		complete(state) {
+		complete(state, _exec) {
 			if (state == null) return {
 				success: false,
 				error: options.errors?.missing ? typeof options.errors.missing === "function" ? options.errors.missing(optionNames$1) : options.errors.missing : message`Required flag ${optionNames(optionNames$1)} is missing.`
@@ -881,7 +881,7 @@ function argument(valueParser, options = {}) {
 				consumed: context.buffer.slice(0, i + 1)
 			};
 		},
-		complete(state) {
+		complete(state, _exec) {
 			if (state == null) return {
 				success: false,
 				error: options.errors?.endOfInput ?? message`Expected a ${metavar(valueParser.metavar)}, but too few arguments.`
@@ -1104,7 +1104,7 @@ function command(name, parser, options = {}) {
 				error: options.errors?.invalidState ?? message`Invalid command state.`
 			};
 		},
-		complete(state) {
+		complete(state, exec) {
 			if (typeof state === "undefined") return {
 				success: false,
 				error: options.errors?.notFound ?? message`Command ${optionName(name)} was not matched.`
@@ -1117,13 +1117,13 @@ function command(name, parser, options = {}) {
 					state: parser.initialState
 				});
 				if (isAsync) return parseResultOrPromise.then((parseResult$1) => {
-					if (parseResult$1.success) return parser.complete(parseResult$1.next.state);
-					return parser.complete(parser.initialState);
+					if (parseResult$1.success) return parser.complete(parseResult$1.next.state, exec);
+					return parser.complete(parser.initialState, exec);
 				});
 				const parseResult = parseResultOrPromise;
-				if (parseResult.success) return parser.complete(parseResult.next.state);
-				return parser.complete(parser.initialState);
-			} else if (state[0] === "parsing") return parser.complete(state[1]);
+				if (parseResult.success) return parser.complete(parseResult.next.state, exec);
+				return parser.complete(parser.initialState, exec);
+			} else if (state[0] === "parsing") return parser.complete(state[1], exec);
 			return {
 				success: false,
 				error: options.errors?.invalidState ?? message`Invalid command state during completion.`
@@ -1324,7 +1324,7 @@ function passThrough(options = {}) {
 				error: message`Unknown passThrough format: ${format}.`
 			};
 		},
-		complete(state) {
+		complete(state, _exec) {
 			if (getAnnotations(state) == null) return {
 				success: true,
 				value: state

package/dist/valueparser.cjs

@@ -1659,6 +1659,7 @@ function socketAddress(options) {
 	const separator = options?.separator ?? ":";
 	if (separator === "") throw new TypeError("Expected separator to not be empty.");
 	if (/\p{Nd}/u.test(separator)) throw new TypeError(`Expected separator to not contain digits, but got: ${JSON.stringify(separator)}.`);
+	const formatExample = `host${JSON.stringify(separator).slice(1, -1)}port`;
 	const metavar = options?.metavar ?? `HOST${separator}PORT`;
 	require_nonempty.ensureNonEmptyString(metavar);
 	const defaultPort = options?.defaultPort;
@@ -1820,7 +1821,7 @@ function socketAddress(options) {
 					const portSplitHostIsDegenerate = separatorIsHostChar ? firstHostError.hostPart.replaceAll(separator, "") === "" : firstHostError.hostPart.includes(separator);
 					if (portSplitHostIsDegenerate) return {
 						success: false,
-						error: require_message.message`Expected a socket address in format host${separator}port, but got ${input}.`
+						error: require_message.message`Expected a socket address in format ${require_message.text(formatExample)}, but got ${input}.`
 					};
 					if (!disambiguationParser.parse(trimmed).success) return {
 						success: false,
@@ -1829,7 +1830,7 @@ function socketAddress(options) {
 				}
 				if (disambiguationParser.parse(trimmed).success) return {
 					success: false,
-					error: require_message.message`Expected a socket address in format host${separator}port, but got ${input}.`
+					error: require_message.message`Expected a socket address in format ${require_message.text(formatExample)}, but got ${input}.`
 				};
 				return {
 					success: false,
@@ -1943,7 +1944,7 @@ function socketAddress(options) {
 			}
 			return {
 				success: false,
-				error: require_message.message`Expected a socket address in format host${separator}port, but got ${input}.`
+				error: require_message.message`Expected a socket address in format ${require_message.text(formatExample)}, but got ${input}.`
 			};
 		},
 		format(value) {

package/dist/valueparser.js

@@ -1659,6 +1659,7 @@ function socketAddress(options) {
 	const separator = options?.separator ?? ":";
 	if (separator === "") throw new TypeError("Expected separator to not be empty.");
 	if (/\p{Nd}/u.test(separator)) throw new TypeError(`Expected separator to not contain digits, but got: ${JSON.stringify(separator)}.`);
+	const formatExample = `host${JSON.stringify(separator).slice(1, -1)}port`;
 	const metavar = options?.metavar ?? `HOST${separator}PORT`;
 	ensureNonEmptyString(metavar);
 	const defaultPort = options?.defaultPort;
@@ -1820,7 +1821,7 @@ function socketAddress(options) {
 					const portSplitHostIsDegenerate = separatorIsHostChar ? firstHostError.hostPart.replaceAll(separator, "") === "" : firstHostError.hostPart.includes(separator);
 					if (portSplitHostIsDegenerate) return {
 						success: false,
-						error: message`Expected a socket address in format host${separator}port, but got ${input}.`
+						error: message`Expected a socket address in format ${text(formatExample)}, but got ${input}.`
 					};
 					if (!disambiguationParser.parse(trimmed).success) return {
 						success: false,
@@ -1829,7 +1830,7 @@ function socketAddress(options) {
 				}
 				if (disambiguationParser.parse(trimmed).success) return {
 					success: false,
-					error: message`Expected a socket address in format host${separator}port, but got ${input}.`
+					error: message`Expected a socket address in format ${text(formatExample)}, but got ${input}.`
 				};
 				return {
 					success: false,
@@ -1943,7 +1944,7 @@ function socketAddress(options) {
 			}
 			return {
 				success: false,
-				error: message`Expected a socket address in format host${separator}port, but got ${input}.`
+				error: message`Expected a socket address in format ${text(formatExample)}, but got ${input}.`
 			};
 		},
 		format(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1580+2d932679",
+  "version": "1.0.0-dev.1590+eb65aeba",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",