@optique/core 1.1.0-dev.2087 → 1.1.0-dev.2146

package/dist/dependency-runtime.d.ts

@@ -49,7 +49,14 @@ interface DependencyResolution {
  * @internal
  * @since 1.0.0
  */
-
+interface SourceDefaultFailure {
+  /** The source that failed. */
+  readonly sourceId: symbol;
+  /** The path of the node. */
+  readonly path: readonly PropertyKey[];
+  /** The failed result or error message. */
+  readonly error: ValueParserResult<unknown>;
+}
 /**
  * A key for caching replayed parse results.
  *
@@ -145,5 +152,193 @@ interface DependencyRuntimeContext {
  * @internal
  * @since 1.0.0
  */
+declare function createDependencyRuntimeContext(registry?: DependencyRegistryLike): DependencyRuntimeContext;
+/**
+ * Creates a stable fingerprint from dependency values.
+ *
+ * @param values The dependency values to fingerprint.
+ * @returns A string fingerprint.
+ * @internal
+ * @since 1.0.0
+ */
+declare function createDependencyFingerprint(values: readonly unknown[]): string;
+declare function createReplayKey(path: readonly PropertyKey[], rawInput: string, dependencyValues: readonly unknown[], replayParse?: Function): ReplayKey;
+/**
+ * Collects explicit source values from parser states and registers them
+ * in the runtime context.
+ *
+ * @param nodes The runtime nodes to inspect.
+ * @param runtime The dependency runtime context.
+ * @throws Propagates synchronous errors thrown by `extractSourceValue()`.
+ * @throws {TypeError} If `extractSourceValue()` returns a promise-like result.
+ *         Use {@link collectExplicitSourceValuesAsync} when async source
+ *         extraction is expected.
+ * @internal
+ * @since 1.0.0
+ */
+declare function collectExplicitSourceValues(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): void;
+/**
+ * Async version of {@link collectExplicitSourceValues}.
+ * Awaits async `extractSourceValue` results instead of rejecting
+ * promise-like values as the synchronous variant does.
+ *
+ * @param nodes The runtime nodes to inspect.
+ * @param runtime The dependency runtime context.
+ * @throws Propagates errors thrown or rejected by `extractSourceValue()`.
+ * @internal
+ * @since 1.0.0
+ */
+declare function collectExplicitSourceValuesAsync(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): Promise<void>;
+/**
+ * Fills missing source defaults for source parsers whose state is
+ * unpopulated.
+ *
+ * Returns an array of failures for sources whose default evaluation
+ * failed (either threw or returned `{ success: false }`).  The caller
+ * should propagate these so that dependent parsers see the real error
+ * instead of silently treating the source as absent.
+ *
+ * @param nodes The runtime nodes to inspect.
+ * @param runtime The dependency runtime context.
+ * @returns Failures from default evaluation (empty if all succeeded).
+ * @throws {TypeError} If `getMissingSourceValue()` returns a promise-like
+ *         result. Use {@link fillMissingSourceDefaultsAsync} when async
+ *         default extraction is expected.
+ * @internal
+ * @since 1.0.0
+ */
+declare function fillMissingSourceDefaults(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): readonly SourceDefaultFailure[];
+/**
+ * Async version of {@link fillMissingSourceDefaults}.
+ * Awaits async `getMissingSourceValue` results.
+ *
+ * @param nodes The runtime nodes to inspect.
+ * @param runtime The dependency runtime context.
+ * @returns Failures from default evaluation (empty if all succeeded).
+ * @internal
+ * @since 1.0.0
+ */
+declare function fillMissingSourceDefaultsAsync(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): Promise<readonly SourceDefaultFailure[]>;
+/**
+ * Replays a derived parser with resolved dependency values (sync).
+ *
+ * Returns `undefined` if dependencies cannot be resolved.
+ *
+ * @param node The runtime node with derived metadata.
+ * @param rawInput The raw input to replay.
+ * @param runtime The dependency runtime context.
+ * @returns The replay result, or `undefined`.
+ * @throws {TypeError} If `replayParse()` returns a promise-like result.
+ *         Use {@link replayDerivedParserAsync} for async replay.
+ * @internal
+ * @since 1.0.0
+ */
+declare function replayDerivedParser(node: RuntimeNode, rawInput: string, runtime: DependencyRuntimeContext): ValueParserResult<unknown> | undefined;
+/**
+ * Replays a derived parser with resolved dependency values (async).
+ *
+ * Returns `undefined` if dependencies cannot be resolved.
+ *
+ * @param node The runtime node with derived metadata.
+ * @param rawInput The raw input to replay.
+ * @param runtime The dependency runtime context.
+ * @returns The replay result, or `undefined`.
+ * @internal
+ * @since 1.0.0
+ */
+declare function replayDerivedParserAsync(node: RuntimeNode, rawInput: string, runtime: DependencyRuntimeContext): Promise<ValueParserResult<unknown> | undefined>;
+/**
+ * Extracts `rawInput` from a parser state that may contain a
+ * {@link DeferredParseState}.  During the transition period, primitives
+ * still produce `DeferredParseState` with `rawInput`.
+ *
+ * Handles direct `DeferredParseState` and array-wrapped
+ * `[DeferredParseState]` (from optional/withDefault wrappers).
+ *
+ * @param state The parser state to inspect.
+ * @returns The raw input string, or `undefined` if the state does not
+ *   contain a `DeferredParseState`.
+ * @internal
+ * @since 1.0.0
+ */
+declare function extractRawInputFromState(state: unknown): string | undefined;
+/**
+ * Recursively collects dependency source values from {@link DependencySourceState}
+ * objects found in the state tree and registers them in the runtime.
+ *
+ * This must run BEFORE deferred resolution so that all source values
+ * are available when replaying derived parsers.
+ *
+ * @param state The state tree to traverse.
+ * @param runtime The dependency runtime context to populate.
+ * @param visited Cycle guard for recursive traversal.
+ * @param excludedFields Optional property keys to skip at the current level.
+ *                       This exclusion set is not propagated recursively.
+ */
+declare function collectSourcesFromState(state: unknown, runtime: DependencyRuntimeContext, visited?: WeakSet<object>, excludedFields?: ReadonlySet<PropertyKey>): void;
+/**
+ * Recursively resolves all {@link DeferredParseState} objects in a state
+ * tree using the dependency runtime (sync).
+ *
+ * Performs a two-pass traversal:
+ *  1. Collect all {@link DependencySourceState} values into the runtime.
+ *  2. Resolve all {@link DeferredParseState} using the populated runtime.
+ *
+ * This replaces the old `resolveDeferredParseStates` with runtime-based
+ * resolution.  Only traverses plain objects and arrays; class instances
+ * and primitives are returned as-is.
+ *
+ * @param state The state tree to resolve.
+ * @param runtime The dependency runtime context.
+ * @returns The resolved state tree.
+ * @throws {TypeError} If a deferred parser returns a promise-like result from
+ *         `parseWithDependency()`. Use {@link resolveStateWithRuntimeAsync}
+ *         for async resolution.
+ * @internal
+ * @since 1.0.0
+ */
+declare function resolveStateWithRuntime(state: unknown, runtime: DependencyRuntimeContext): unknown;
+/**
+ * Async version of {@link resolveStateWithRuntime}.
+ *
+ * @param state The state tree to resolve.
+ * @param runtime The dependency runtime context.
+ * @returns The resolved state tree.
+ * @internal
+ * @since 1.0.0
+ */
+declare function resolveStateWithRuntimeAsync(state: unknown, runtime: DependencyRuntimeContext): Promise<unknown>;
+/**
+ * Builds {@link RuntimeNode}s from field→parser pairs and a state record.
+ *
+ * Used by `object()` and `merge()` constructs.
+ *
+ * @param pairs Field→parser pairs.
+ * @param state The state record keyed by field name.
+ * @param parentPath Optional parent path prefix.
+ * @returns An array of runtime nodes.
+ * @internal
+ * @since 1.0.0
+ */
+declare function buildRuntimeNodesFromPairs(pairs: ReadonlyArray<readonly [PropertyKey, {
+  readonly dependencyMetadata?: ParserDependencyMetadata;
+  readonly initialState?: unknown;
+}]>, state: Record<PropertyKey, unknown>, parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
+/**
+ * Builds {@link RuntimeNode}s from a parser array and a state array.
+ *
+ * Used by `tuple()` and `concat()` constructs.
+ *
+ * @param parsers The child parsers.
+ * @param stateArray The state array (one element per parser).
+ * @param parentPath Optional parent path prefix.
+ * @returns An array of runtime nodes.
+ * @internal
+ * @since 1.0.0
+ */
+declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
+  readonly dependencyMetadata?: ParserDependencyMetadata;
+  readonly initialState?: unknown;
+}>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
 //#endregion
-export { DependencyRuntimeContext, RuntimeNode };
+export { DependencyRequest, DependencyResolution, DependencyRuntimeContext, DependencyValueOrigin, ReplayKey, RuntimeNode, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync };

package/dist/dependency-runtime.js

@@ -457,6 +457,27 @@ async function replayDerivedParserAsync(node, rawInput, runtime) {
 	return result;
 }
 /**
+* Extracts `rawInput` from a parser state that may contain a
+* {@link DeferredParseState}.  During the transition period, primitives
+* still produce `DeferredParseState` with `rawInput`.
+*
+* Handles direct `DeferredParseState` and array-wrapped
+* `[DeferredParseState]` (from optional/withDefault wrappers).
+*
+* @param state The parser state to inspect.
+* @returns The raw input string, or `undefined` if the state does not
+*   contain a `DeferredParseState`.
+* @internal
+* @since 1.0.0
+*/
+function extractRawInputFromState(state) {
+	if (state == null) return void 0;
+	if (typeof state !== "object") return void 0;
+	if (isDeferredParseState(state)) return state.rawInput;
+	if (Array.isArray(state) && state.length === 1 && isDeferredParseState(state[0])) return state[0].rawInput;
+	return void 0;
+}
+/**
 * Checks if a value is a plain object (not a class instance) for the
 * purpose of recursive state traversal.
 */
@@ -696,4 +717,4 @@ function buildRuntimeNodesFromArray(parsers, stateArray, parentPath) {
 }
 
 //#endregion
-export { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, createDependencyRuntimeContext, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync };
+export { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync };

package/dist/dependency.cjs

@@ -1,8 +1,8 @@
-const require_dependency = require('./internal/dependency.cjs');
+const require_internal_dependency = require('./internal/dependency.cjs');
 
-exports.dependency = require_dependency.dependency;
-exports.deriveFrom = require_dependency.deriveFrom;
-exports.deriveFromAsync = require_dependency.deriveFromAsync;
-exports.deriveFromSync = require_dependency.deriveFromSync;
-exports.isDependencySource = require_dependency.isDependencySource;
-exports.isDerivedValueParser = require_dependency.isDerivedValueParser;
+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.isDependencySource = require_internal_dependency.isDependencySource;
+exports.isDerivedValueParser = require_internal_dependency.isDerivedValueParser;

package/dist/displaywidth.d.cts

@@ -0,0 +1,12 @@
+//#region src/displaywidth.d.ts
+/**
+ * Computes the terminal display width of a string, accounting for
+ * East Asian wide characters, combining marks, emoji, and ANSI escapes.
+ *
+ * @param text The string to measure.
+ * @returns The number of terminal columns the string occupies.
+ * @internal
+ */
+declare function getDisplayWidth(text: string): number;
+//#endregion
+export { getDisplayWidth };

package/dist/displaywidth.d.ts

@@ -0,0 +1,12 @@
+//#region src/displaywidth.d.ts
+/**
+ * Computes the terminal display width of a string, accounting for
+ * East Asian wide characters, combining marks, emoji, and ANSI escapes.
+ *
+ * @param text The string to measure.
+ * @returns The number of terminal columns the string occupies.
+ * @internal
+ */
+declare function getDisplayWidth(text: string): number;
+//#endregion
+export { getDisplayWidth };

package/dist/doc.cjs

@@ -497,6 +497,9 @@ function maxVisibleAtomicWidth(usage) {
 				max = Math.max(max, maxVisibleAtomicWidth(branch));
 			}
 			break;
+		case "sequence":
+			max = Math.max(max, maxVisibleAtomicWidth(term.terms));
+			break;
 		case "literal":
 			if (term.value !== "") max = Math.max(max, require_displaywidth.getDisplayWidth(term.value));
 			break;

package/dist/doc.js

@@ -497,6 +497,9 @@ function maxVisibleAtomicWidth(usage) {
 				max = Math.max(max, maxVisibleAtomicWidth(branch));
 			}
 			break;
+		case "sequence":
+			max = Math.max(max, maxVisibleAtomicWidth(term.terms));
+			break;
 		case "literal":
 			if (term.value !== "") max = Math.max(max, getDisplayWidth(term.value));
 			break;

package/dist/execution-context.d.cts

@@ -0,0 +1,23 @@
+import { Usage } from "./usage.cjs";
+import { ExecutionContext, ParserContext } from "./internal/parser.cjs";
+
+//#region src/execution-context.d.ts
+
+/**
+ * Appends a child parser segment to the current execution path.
+ * @internal
+ */
+declare function withChildExecPath(exec: ExecutionContext | undefined, segment: PropertyKey): ExecutionContext | undefined;
+/**
+ * Merges child-owned execution fields back into the parent execution context.
+ * @internal
+ */
+declare function mergeChildExec(parent: ExecutionContext | undefined, child: ExecutionContext | undefined): ExecutionContext | undefined;
+/**
+ * Creates a child parser context while keeping flat and nested execution data
+ * aligned.
+ * @internal
+ */
+declare function withChildContext<TParentState, TChildState>(context: ParserContext<TParentState>, segment: PropertyKey, state: TChildState, usage?: Usage): ParserContext<TChildState>;
+//#endregion
+export { mergeChildExec, withChildContext, withChildExecPath };

package/dist/execution-context.d.ts

@@ -0,0 +1,23 @@
+import { Usage } from "./usage.js";
+import { ExecutionContext, ParserContext } from "./internal/parser.js";
+
+//#region src/execution-context.d.ts
+
+/**
+ * Appends a child parser segment to the current execution path.
+ * @internal
+ */
+declare function withChildExecPath(exec: ExecutionContext | undefined, segment: PropertyKey): ExecutionContext | undefined;
+/**
+ * Merges child-owned execution fields back into the parent execution context.
+ * @internal
+ */
+declare function mergeChildExec(parent: ExecutionContext | undefined, child: ExecutionContext | undefined): ExecutionContext | undefined;
+/**
+ * Creates a child parser context while keeping flat and nested execution data
+ * aligned.
+ * @internal
+ */
+declare function withChildContext<TParentState, TChildState>(context: ParserContext<TParentState>, segment: PropertyKey, state: TChildState, usage?: Usage): ParserContext<TChildState>;
+//#endregion
+export { mergeChildExec, withChildContext, withChildExecPath };

package/dist/extension.cjs

@@ -1,6 +1,6 @@
-const require_annotations = require('./internal/annotations.cjs');
+const require_internal_annotations = require('./internal/annotations.cjs');
 const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
-const require_parser = require('./internal/parser.cjs');
+const require_internal_parser = require('./internal/parser.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
 
 //#region src/extension.ts
@@ -14,13 +14,13 @@ const emptyTraits = Object.freeze({});
 * @since 1.0.0
 */
 function defineTraits(parser, traits) {
-	if (traits.inheritsAnnotations === true) require_parser.defineInheritedAnnotationParser(parser);
-	if (traits.completesFromSource === true) Object.defineProperty(parser, require_parser.unmatchedNonCliDependencySourceStateMarker, {
+	if (traits.inheritsAnnotations === true) require_internal_parser.defineInheritedAnnotationParser(parser);
+	if (traits.completesFromSource === true) Object.defineProperty(parser, require_internal_parser.unmatchedNonCliDependencySourceStateMarker, {
 		value: true,
 		configurable: true,
 		enumerable: true
 	});
-	if (traits.requiresSourceBinding === true) Object.defineProperty(parser, require_parser.annotationWrapperRequiresSourceBindingKey, {
+	if (traits.requiresSourceBinding === true) Object.defineProperty(parser, require_internal_parser.annotationWrapperRequiresSourceBindingKey, {
 		value: true,
 		configurable: true,
 		enumerable: false
@@ -35,9 +35,9 @@ function defineTraits(parser, traits) {
 */
 function getTraits(parser) {
 	const traits = {
-		...Reflect.get(parser, require_parser.inheritParentAnnotationsKey) === true ? { inheritsAnnotations: true } : {},
-		...Reflect.get(parser, require_parser.unmatchedNonCliDependencySourceStateMarker) === true ? { completesFromSource: true } : {},
-		...Reflect.get(parser, require_parser.annotationWrapperRequiresSourceBindingKey) === true ? { requiresSourceBinding: true } : {}
+		...Reflect.get(parser, require_internal_parser.inheritParentAnnotationsKey) === true ? { inheritsAnnotations: true } : {},
+		...Reflect.get(parser, require_internal_parser.unmatchedNonCliDependencySourceStateMarker) === true ? { completesFromSource: true } : {},
+		...Reflect.get(parser, require_internal_parser.annotationWrapperRequiresSourceBindingKey) === true ? { requiresSourceBinding: true } : {}
 	};
 	return Object.keys(traits).length > 0 ? traits : emptyTraits;
 }
@@ -55,7 +55,7 @@ function getTraits(parser) {
 * @since 1.0.0
 */
 function delegateSuggestNodes(innerParser, outerParser, state, path, innerState, position = "append") {
-	return require_parser.getDelegatingSuggestRuntimeNodes(innerParser, outerParser, state, path, innerState, position);
+	return require_internal_parser.getDelegatingSuggestRuntimeNodes(innerParser, outerParser, state, path, innerState, position);
 }
 /**
 * Maps the source capability of a parser's dependency metadata while
@@ -69,7 +69,7 @@ function delegateSuggestNodes(innerParser, outerParser, state, path, innerState,
 * @since 1.0.0
 */
 function mapSourceMetadata(parser, mapSource) {
-	return require_parser.composeWrappedSourceMetadata(parser.dependencyMetadata, mapSource);
+	return require_internal_parser.composeWrappedSourceMetadata(parser.dependencyMetadata, mapSource);
 }
 
 //#endregion
@@ -77,11 +77,11 @@ exports.defineTraits = defineTraits;
 exports.delegateSuggestNodes = delegateSuggestNodes;
 exports.dispatchByMode = require_mode_dispatch.dispatchByMode;
 exports.getTraits = getTraits;
-exports.inheritAnnotations = require_annotations.inheritAnnotations;
-exports.injectAnnotations = require_annotations.injectAnnotations;
-exports.isInjectedAnnotationState = require_annotations.isInjectedAnnotationState;
+exports.inheritAnnotations = require_internal_annotations.inheritAnnotations;
+exports.injectAnnotations = require_internal_annotations.injectAnnotations;
+exports.isInjectedAnnotationState = require_internal_annotations.isInjectedAnnotationState;
 exports.mapModeValue = require_mode_dispatch.mapModeValue;
 exports.mapSourceMetadata = mapSourceMetadata;
-exports.unwrapInjectedAnnotationState = require_annotations.unwrapInjectedAnnotationState;
+exports.unwrapInjectedAnnotationState = require_internal_annotations.unwrapInjectedAnnotationState;
 exports.withAnnotationView = require_annotation_state.withAnnotationView;
 exports.wrapForMode = require_mode_dispatch.wrapForMode;