@optique/core 1.1.0-dev.2096 → 1.1.0-dev.2148

package/dist/internal/dependency.d.ts

@@ -1,4 +1,6 @@
 import { NonEmptyString } from "../nonempty.js";
+import { Message } from "../message.js";
+import { DependencyRegistryLike } from "../registry-types.js";
 import { ValueParser, ValueParserResult } from "../valueparser.js";
 import { Mode, Suggestion } from "./parser.js";
 
@@ -51,7 +53,7 @@ declare const singleDefaultValue: unique symbol;
  *
  * @internal
  */
-
+declare const defaultDependencyValueSnapshot: unique symbol;
 /**
  * A unique symbol used to access the parseWithDependency method on derived parsers.
  * @since 0.10.0
@@ -535,5 +537,312 @@ declare function deriveFromAsync<Deps extends readonly AnyDependencySource[], T>
  * @returns A cloned parse result with an internal snapshot attached.
  * @internal
  */
+declare function snapshotDefaultDependencyValues<T>(result: ValueParserResult<T>, values: readonly unknown[]): ValueParserResult<T>;
+/**
+ * Reads the snapshotted default dependency values from a parse result.
+ *
+ * @param result The parse result to inspect.
+ * @returns The snapshotted dependency values, if present.
+ * @internal
+ */
+declare function getSnapshottedDefaultDependencyValues<T>(result: ValueParserResult<T>): readonly unknown[] | undefined;
+/**
+ * A unique symbol used to identify deferred parse states.
+ * @since 0.10.0
+ */
+declare const deferredParseMarker: unique symbol;
+/**
+ * Represents a deferred parse state for a DerivedValueParser.
+ *
+ * When a DerivedValueParser is used in an option or argument, the raw
+ * input string is stored along with the parser reference. The actual
+ * parsing is deferred until `complete()` time when all dependencies
+ * have been resolved.
+ *
+ * @template T The type of value this parser will produce after resolution.
+ * @since 0.10.0
+ */
+interface DeferredParseState<T = unknown> {
+  /**
+   * Marker to identify this as a deferred parse state.
+   */
+  readonly [deferredParseMarker]: true;
+  /**
+   * The raw input string to be parsed.
+   */
+  readonly rawInput: string;
+  /**
+   * The DerivedValueParser that will parse the input.
+   */
+  readonly parser: DerivedValueParser<Mode, T, unknown>;
+  /**
+   * The dependency ID that this parser depends on (for single-dependency parsers).
+   */
+  readonly dependencyId: symbol;
+  /**
+   * The dependency IDs that this parser depends on (for multi-dependency parsers).
+   * If present, this is used instead of `dependencyId`.
+   */
+  readonly dependencyIds?: readonly symbol[];
+  /**
+   * The default values to use for dependencies that are not provided.
+   * For multi-dependency parsers, this is a tuple of default values in order.
+   * For single-dependency parsers, this is the single default value.
+   */
+  readonly defaultValues?: readonly unknown[];
+  /**
+   * The preliminary parse result using the default dependency value.
+   * This is used as a fallback if dependency resolution is not needed
+   * or if the dependency was not provided.
+   */
+  readonly preliminaryResult: ValueParserResult<T>;
+}
+/**
+ * Checks if a value is a {@link DeferredParseState}.
+ *
+ * @param value The value to check.
+ * @returns `true` if the value is a deferred parse state, `false` otherwise.
+ * @since 0.10.0
+ */
+declare function isDeferredParseState<T>(value: unknown): value is DeferredParseState<T>;
+/**
+ * Gets all dependency IDs from a derived parser.
+ * If the parser was created with `deriveFrom` (multiple dependencies),
+ * returns the array of dependency IDs. Otherwise, returns an array
+ * containing the single dependency ID.
+ *
+ * @param parser The derived value parser to get dependency IDs from.
+ * @returns An array of dependency ID symbols.
+ * @internal
+ * @since 0.10.0
+ */
+declare function getDependencyIds<M extends Mode, T, S>(parser: DerivedValueParser<M, T, S>): readonly symbol[];
+/**
+ * Gets the default values function from a multi-source derived parser, if
+ * present.
+ *
+ * Single-source `derive()` defaults must stay lazy during suggestion-time
+ * replay so missing dependencies do not eagerly evaluate side-effectful
+ * `defaultValue()` thunks.
+ *
+ * @param parser The derived value parser to get the default values function from.
+ * @returns The default values function, or undefined if not available.
+ * @internal
+ * @since 0.10.0
+ */
+declare function getDefaultValuesFunction<M extends Mode, T, S>(parser: DerivedValueParser<M, T, S>): (() => readonly unknown[]) | undefined;
+/**
+ * Creates a deferred parse state for a DerivedValueParser.
+ *
+ * @template T The type of value the parser will produce.
+ * @template S The type of the source dependency value.
+ * @param rawInput The raw input string to be parsed.
+ * @param parser The DerivedValueParser that will parse the input.
+ * @param preliminaryResult The parse result using default dependency value.
+ * @returns A DeferredParseState object.
+ * @since 0.10.0
+ */
+declare function createDeferredParseState<T, S>(rawInput: string, parser: DerivedValueParser<Mode, T, S>, preliminaryResult: ValueParserResult<T>): DeferredParseState<T>;
+/**
+ * A unique symbol used to identify dependency source parse states.
+ * @since 0.10.0
+ */
+declare const dependencySourceStateMarker: unique symbol;
+/**
+ * Represents a parse state from a DependencySource.
+ * This wraps the normal ValueParserResult with the dependency ID so that
+ * it can be matched with DeferredParseState during resolution.
+ *
+ * @template T The type of value this state contains.
+ * @since 0.10.0
+ */
+interface DependencySourceState<T = unknown> {
+  /**
+   * Marker to identify this as a dependency source state.
+   */
+  readonly [dependencySourceStateMarker]: true;
+  /**
+   * The dependency ID of the source.
+   */
+  readonly [dependencyId]: symbol;
+  /**
+   * The underlying parse result.
+   */
+  readonly result: ValueParserResult<T>;
+}
+/**
+ * Checks if a value is a {@link DependencySourceState}.
+ *
+ * @param value The value to check.
+ * @returns `true` if the value is a dependency source state, `false` otherwise.
+ * @since 0.10.0
+ */
+declare function isDependencySourceState<T>(value: unknown): value is DependencySourceState<T>;
+/**
+ * Creates a dependency source state from a parse result.
+ *
+ * @template T The type of value the state contains.
+ * @param result The parse result.
+ * @param depId The dependency ID.
+ * @returns A DependencySourceState object.
+ * @since 0.10.0
+ */
+declare function createDependencySourceState<T>(result: ValueParserResult<T>, depId: symbol): DependencySourceState<T>;
+/**
+ * A unique symbol used to identify pending dependency source states.
+ * @since 0.10.0
+ */
+declare const pendingDependencySourceStateMarker: unique symbol;
+/**
+ * Represents a pending dependency source state.
+ * This is used when a dependency source option was not provided, but its
+ * dependency ID still needs to be tracked for later resolution with a
+ * default value.
+ *
+ * @since 0.10.0
+ */
+interface PendingDependencySourceState {
+  /**
+   * Marker to identify this as a pending dependency source state.
+   */
+  readonly [pendingDependencySourceStateMarker]: true;
+  /**
+   * The dependency ID of the source.
+   */
+  readonly [dependencyId]: symbol;
+}
+/**
+ * Checks if a value is a {@link PendingDependencySourceState}.
+ *
+ * @param value The value to check.
+ * @returns `true` if the value is a pending dependency source state.
+ * @since 0.10.0
+ */
+declare function isPendingDependencySourceState(value: unknown): value is PendingDependencySourceState;
+/**
+ * Creates a pending dependency source state.
+ *
+ * @param depId The dependency ID.
+ * @returns A PendingDependencySourceState object.
+ * @since 0.10.0
+ */
+declare function createPendingDependencySourceState(depId: symbol): PendingDependencySourceState;
+/**
+ * A unique symbol used to identify parsers that wrap a dependency source.
+ * This is used by withDefault to indicate it contains an inner parser
+ * with a PendingDependencySourceState initialState.
+ * @since 0.10.0
+ */
+declare const wrappedDependencySourceMarker: unique symbol;
+/**
+ * A unique symbol used to indicate that a wrapper transforms the dependency
+ * source value. This is used by withDefault to determine whether its default
+ * value should be registered as the dependency value.
+ *
+ * When a wrapper has this marker set to `true`, it means the wrapper transforms
+ * the dependency source value (e.g., via map()), so the wrapper's output is NOT
+ * a valid dependency source value.
+ *
+ * @since 0.10.0
+ */
+declare const transformsDependencyValueMarker: unique symbol;
+/**
+ * Checks if a parser transforms the dependency value (has transformsDependencyValueMarker).
+ *
+ * @param parser The parser to check.
+ * @returns `true` if the parser transforms the dependency value.
+ * @since 0.10.0
+ */
+declare function transformsDependencyValue(parser: unknown): parser is {
+  [transformsDependencyValueMarker]: true;
+};
+/**
+ * Checks if a parser wraps a dependency source (has wrappedDependencySourceMarker).
+ *
+ * @param parser The parser to check.
+ * @returns `true` if the parser wraps a dependency source.
+ * @since 0.10.0
+ */
+declare function isWrappedDependencySource(parser: unknown): parser is {
+  [wrappedDependencySourceMarker]: PendingDependencySourceState;
+};
+/**
+ * Represents a resolved dependency value stored during parsing.
+ * @since 0.10.0
+ */
+interface ResolvedDependency<T = unknown> {
+  /**
+   * The dependency ID.
+   */
+  readonly id: symbol;
+  /**
+   * The resolved value.
+   */
+  readonly value: T;
+}
+/**
+ * A registry for storing resolved dependency values during parsing.
+ * This is used to pass dependency values from DependencySource options
+ * to DerivedValueParser options.
+ * @since 0.10.0
+ */
+declare class DependencyRegistry implements DependencyRegistryLike {
+  private readonly values;
+  /**
+   * Registers a resolved dependency value.
+   * @param id The dependency ID.
+   * @param value The resolved value.
+   */
+  set<T>(id: symbol, value: T): void;
+  /**
+   * Gets a resolved dependency value.
+   * @param id The dependency ID.
+   * @returns The resolved value, or undefined if not found.
+   */
+  get<T>(id: symbol): T | undefined;
+  /**
+   * Checks if a dependency has been resolved.
+   * @param id The dependency ID.
+   * @returns `true` if the dependency has been resolved.
+   */
+  has(id: symbol): boolean;
+  /**
+   * Creates a copy of the registry.
+   */
+  clone(): DependencyRegistry;
+}
+/**
+ * Error types for dependency resolution failures.
+ * @since 0.10.0
+ */
+type DependencyError = {
+  /**
+   * The dependency was used in multiple locations.
+   */
+  readonly kind: "duplicate";
+  readonly dependencyId: symbol;
+  readonly locations: readonly string[];
+} | {
+  /**
+   * A derived parser references a dependency that was not provided.
+   */
+  readonly kind: "unresolved";
+  readonly dependencyId: symbol;
+  readonly derivedParserMetavar: string;
+} | {
+  /**
+   * Circular dependency detected.
+   */
+  readonly kind: "circular";
+  readonly cycle: readonly symbol[];
+};
+/**
+ * Formats a {@link DependencyError} into a human-readable {@link Message}.
+ *
+ * @param error The dependency error to format.
+ * @returns A Message describing the error.
+ * @since 0.10.0
+ */
+declare function formatDependencyError(error: DependencyError): Message;
 //#endregion
-export { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser };
+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 };

package/dist/internal/dependency.js

@@ -885,6 +885,37 @@ function getDefaultValuesFunction(parser) {
 	return void 0;
 }
 /**
+* Creates a deferred parse state for a DerivedValueParser.
+*
+* @template T The type of value the parser will produce.
+* @template S The type of the source dependency value.
+* @param rawInput The raw input string to be parsed.
+* @param parser The DerivedValueParser that will parse the input.
+* @param preliminaryResult The parse result using default dependency value.
+* @returns A DeferredParseState object.
+* @since 0.10.0
+*/
+function createDeferredParseState(rawInput, parser, preliminaryResult) {
+	const multipleIds = dependencyIds in parser ? parser[dependencyIds] : void 0;
+	const defaultValuesFn = getDefaultValuesFunction(parser);
+	let defaultVals = getSnapshottedDefaultDependencyValues(preliminaryResult);
+	if (defaultVals != null) defaultVals = [...defaultVals];
+	if (defaultVals == null && defaultValuesFn != null) try {
+		defaultVals = [...defaultValuesFn()];
+	} catch {
+		defaultVals = void 0;
+	}
+	return {
+		[deferredParseMarker]: true,
+		rawInput,
+		parser,
+		dependencyId: parser[dependencyId],
+		dependencyIds: multipleIds,
+		defaultValues: defaultVals,
+		preliminaryResult
+	};
+}
+/**
 * A unique symbol used to identify dependency source parse states.
 * @since 0.10.0
 */
@@ -931,6 +962,19 @@ function isPendingDependencySourceState(value) {
 	return typeof value === "object" && value !== null && pendingDependencySourceStateMarker in value && value[pendingDependencySourceStateMarker] === true;
 }
 /**
+* Creates a pending dependency source state.
+*
+* @param depId The dependency ID.
+* @returns A PendingDependencySourceState object.
+* @since 0.10.0
+*/
+function createPendingDependencySourceState(depId) {
+	return {
+		[pendingDependencySourceStateMarker]: true,
+		[dependencyId]: depId
+	};
+}
+/**
 * A unique symbol used to identify parsers that wrap a dependency source.
 * This is used by withDefault to indicate it contains an inner parser
 * with a PendingDependencySourceState initialState.
@@ -950,6 +994,16 @@ const wrappedDependencySourceMarker = Symbol.for("@optique/core/dependency/wrapp
 */
 const transformsDependencyValueMarker = Symbol.for("@optique/core/dependency/transformsDependencyValueMarker");
 /**
+* Checks if a parser transforms the dependency value (has transformsDependencyValueMarker).
+*
+* @param parser The parser to check.
+* @returns `true` if the parser transforms the dependency value.
+* @since 0.10.0
+*/
+function transformsDependencyValue(parser) {
+	return typeof parser === "object" && parser !== null && transformsDependencyValueMarker in parser && parser[transformsDependencyValueMarker] === true;
+}
+/**
 * Checks if a parser wraps a dependency source (has wrappedDependencySourceMarker).
 *
 * @param parser The parser to check.
@@ -959,6 +1013,70 @@ const transformsDependencyValueMarker = Symbol.for("@optique/core/dependency/tra
 function isWrappedDependencySource(parser) {
 	return typeof parser === "object" && parser !== null && wrappedDependencySourceMarker in parser;
 }
+/**
+* A registry for storing resolved dependency values during parsing.
+* This is used to pass dependency values from DependencySource options
+* to DerivedValueParser options.
+* @since 0.10.0
+*/
+var DependencyRegistry = class DependencyRegistry {
+	values = /* @__PURE__ */ new Map();
+	/**
+	* Registers a resolved dependency value.
+	* @param id The dependency ID.
+	* @param value The resolved value.
+	*/
+	set(id, value) {
+		this.values.set(id, value);
+	}
+	/**
+	* Gets a resolved dependency value.
+	* @param id The dependency ID.
+	* @returns The resolved value, or undefined if not found.
+	*/
+	get(id) {
+		return this.values.get(id);
+	}
+	/**
+	* Checks if a dependency has been resolved.
+	* @param id The dependency ID.
+	* @returns `true` if the dependency has been resolved.
+	*/
+	has(id) {
+		return this.values.has(id);
+	}
+	/**
+	* Creates a copy of the registry.
+	*/
+	clone() {
+		const copy = new DependencyRegistry();
+		for (const [id, value] of this.values) copy.values.set(id, value);
+		return copy;
+	}
+};
+/**
+* Formats a {@link DependencyError} into a human-readable {@link Message}.
+*
+* @param error The dependency error to format.
+* @returns A Message describing the error.
+* @since 0.10.0
+*/
+function formatDependencyError(error) {
+	switch (error.kind) {
+		case "duplicate": return [{
+			type: "text",
+			text: `Dependency used in multiple locations: ${error.locations.join(", ")}.`
+		}];
+		case "unresolved": return [{
+			type: "text",
+			text: `Unresolved dependency for ${error.derivedParserMetavar}: the dependency was not provided.`
+		}];
+		case "circular": return [{
+			type: "text",
+			text: `Circular dependency detected.`
+		}];
+	}
+}
 
 //#endregion
-export { createDependencySourceState, defaultValues, dependency, dependencyId, dependencyIds, deriveFrom, deriveFromAsync, deriveFromSync, getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, singleDefaultValue, suggestWithDependency, wrappedDependencySourceMarker };
+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 };

package/dist/internal/parser.cjs

@@ -1,4 +1,4 @@
-const require_annotations = require('./annotations.cjs');
+const require_internal_annotations = require('./annotations.cjs');
 const require_message = require('../message.cjs');
 const require_usage = require('../usage.cjs');
 const require_doc = require('../doc.cjs');
@@ -64,7 +64,7 @@ function createParserContext(frame, exec) {
 	};
 }
 function injectAnnotationsIntoState(state, options) {
-	return require_annotations.injectAnnotations(state, options?.annotations);
+	return require_internal_annotations.injectAnnotations(state, options?.annotations);
 }
 /**
 * Parses an array of command-line arguments using the provided combined parser.
@@ -92,7 +92,7 @@ function injectAnnotationsIntoState(state, options) {
 */
 function parseSync(parser, args, options) {
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	const shouldUnwrapAnnotatedValue = require_annotations.hasMeaningfulAnnotations(options?.annotations) || require_annotations.isInjectedAnnotationWrapper(parser.initialState);
+	const shouldUnwrapAnnotatedValue = require_internal_annotations.hasMeaningfulAnnotations(options?.annotations) || require_internal_annotations.isInjectedAnnotationWrapper(parser.initialState);
 	const exec = {
 		usage: parser.usage,
 		phase: "parse",
@@ -123,12 +123,13 @@ function parseSync(parser, args, options) {
 		phase: "complete",
 		dependencyRuntime: runtime,
 		dependencyRegistry: runtime.registry,
+		commandPath: context.exec?.commandPath ?? exec.commandPath,
 		trace: context.exec?.trace ?? context.trace ?? exec.trace
 	};
 	const endResult = parser.complete(context.state, completeExec);
 	return endResult.success ? {
 		success: true,
-		value: shouldUnwrapAnnotatedValue ? require_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
+		value: shouldUnwrapAnnotatedValue ? require_internal_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
 		...endResult.deferred ? { deferred: true } : {},
 		...endResult.deferredKeys ? { deferredKeys: endResult.deferredKeys } : {}
 	} : {
@@ -164,7 +165,7 @@ function isBufferUnchanged(previous, current) {
 */
 async function parseAsync(parser, args, options) {
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	const shouldUnwrapAnnotatedValue = require_annotations.hasMeaningfulAnnotations(options?.annotations) || require_annotations.isInjectedAnnotationWrapper(parser.initialState);
+	const shouldUnwrapAnnotatedValue = require_internal_annotations.hasMeaningfulAnnotations(options?.annotations) || require_internal_annotations.isInjectedAnnotationWrapper(parser.initialState);
 	const exec = {
 		usage: parser.usage,
 		phase: "parse",
@@ -195,12 +196,13 @@ async function parseAsync(parser, args, options) {
 		phase: "complete",
 		dependencyRuntime: runtime,
 		dependencyRegistry: runtime.registry,
+		commandPath: context.exec?.commandPath ?? exec.commandPath,
 		trace: context.exec?.trace ?? context.trace ?? exec.trace
 	};
 	const endResult = await parser.complete(context.state, completeExec);
 	return endResult.success ? {
 		success: true,
-		value: shouldUnwrapAnnotatedValue ? require_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
+		value: shouldUnwrapAnnotatedValue ? require_internal_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
 		...endResult.deferred ? { deferred: true } : {},
 		...endResult.deferredKeys ? { deferredKeys: endResult.deferredKeys } : {}
 	} : {
@@ -534,7 +536,7 @@ function findCommandInUsageSequence(usage, commandName) {
 * @returns The contextual usage terms if found, null otherwise.
 */
 function findCommandInCurrentUsageTerm(term, commandName, trailingUsage) {
-	if (term.type === "command" && term.name === commandName) return [term, ...trailingUsage];
+	if (term.type === "command" && commandTermMatches(term, commandName)) return [term, ...trailingUsage];
 	if (term.type === "exclusive") {
 		const found = findCommandInExclusive(term, commandName);
 		if (found) return [...found, ...trailingUsage];
@@ -544,7 +546,27 @@ function findCommandInCurrentUsageTerm(term, commandName, trailingUsage) {
 	}
 	return null;
 }
-function recordMatchedCommandArgIndices(consumed, previousCommandPath, nextCommandPath, consumedOffset, indices) {
+function commandTermMatches(term, commandName) {
+	return term?.type === "command" && (term.name === commandName || term.aliases?.includes(commandName) === true || term.hiddenAliases?.includes(commandName) === true);
+}
+function collectCommandInputNames(usage, commandName, names) {
+	for (const term of usage) if (term.type === "command") {
+		if (commandTermMatches(term, commandName)) {
+			names.add(term.name);
+			for (const alias of term.aliases ?? []) names.add(alias);
+			for (const alias of term.hiddenAliases ?? []) names.add(alias);
+		}
+	} else if (term.type === "exclusive") for (const branch of term.terms) collectCommandInputNames(branch, commandName, names);
+	else if (term.type === "sequence") collectCommandInputNames(term.terms, commandName, names);
+	else if (term.type === "optional" || term.type === "multiple") collectCommandInputNames(term.terms, commandName, names);
+}
+function findLastCommandInputIndex(consumed, commandName, usage, searchEnd) {
+	const names = new Set([commandName]);
+	collectCommandInputNames(usage, commandName, names);
+	for (let index = searchEnd - 1; index >= 0; index--) if (names.has(consumed[index])) return index;
+	return -1;
+}
+function recordMatchedCommandArgIndices(usage, consumed, previousCommandPath, nextCommandPath, consumedOffset, indices) {
 	const previousLength = previousCommandPath?.length ?? 0;
 	const next = nextCommandPath ?? [];
 	if (next.length <= previousLength || consumed.length < 1) return;
@@ -552,7 +574,7 @@ function recordMatchedCommandArgIndices(consumed, previousCommandPath, nextComma
 	for (let index = next.length - 1; index >= previousLength; index--) {
 		if (searchEnd <= 0) break;
 		const commandName = next[index];
-		const localIndex = consumed.lastIndexOf(commandName, searchEnd - 1);
+		const localIndex = findLastCommandInputIndex(consumed, commandName, usage, searchEnd);
 		if (localIndex < 0) continue;
 		indices.add(consumedOffset + localIndex);
 		searchEnd = localIndex;
@@ -636,7 +658,7 @@ function getDocPageSyncImpl(parser, args, options) {
 		const previousBuffer = context.buffer;
 		context = result.next;
 		const consumedCount = previousBuffer.length - context.buffer.length;
-		recordMatchedCommandArgIndices(previousBuffer.slice(0, consumedCount), previousCommandPath, context.exec?.commandPath, args.length - previousBuffer.length, matchedCommandArgIndices);
+		recordMatchedCommandArgIndices(parser.usage, previousBuffer.slice(0, consumedCount), previousCommandPath, context.exec?.commandPath, args.length - previousBuffer.length, matchedCommandArgIndices);
 		if (isBufferUnchanged(previousBuffer, context.buffer)) break;
 	}
 	return buildDocPage(parser, context, args, matchedCommandArgIndices);
@@ -665,7 +687,7 @@ async function getDocPageAsyncImpl(parser, args, options) {
 		const previousBuffer = context.buffer;
 		context = result.next;
 		const consumedCount = previousBuffer.length - context.buffer.length;
-		recordMatchedCommandArgIndices(previousBuffer.slice(0, consumedCount), previousCommandPath, context.exec?.commandPath, args.length - previousBuffer.length, matchedCommandArgIndices);
+		recordMatchedCommandArgIndices(parser.usage, previousBuffer.slice(0, consumedCount), previousCommandPath, context.exec?.commandPath, args.length - previousBuffer.length, matchedCommandArgIndices);
 		if (isBufferUnchanged(previousBuffer, context.buffer)) break;
 	}
 	return buildDocPage(parser, context, args, matchedCommandArgIndices);
@@ -682,7 +704,7 @@ function buildDocPage(parser, context, args, matchedCommandArgIndices) {
 	}, void 0);
 	if (args.length === 0 && Reflect.get(parser, Symbol.for("@optique/core/commandParser")) === true && fragments.length === 1 && fragments[0].type === "entry" && fragments[0].term.type === "command") {
 		const cmdName = fragments[0].term.name;
-		const matchedState = require_annotations.inheritAnnotations(context.state, ["matched", cmdName]);
+		const matchedState = require_internal_annotations.inheritAnnotations(context.state, ["matched", cmdName]);
 		const matched = parser.getDocFragments({
 			kind: "available",
 			state: matchedState
@@ -725,7 +747,7 @@ function buildDocPage(parser, context, args, matchedCommandArgIndices) {
 	const sections = buildingSections;
 	const usage = [...require_usage.normalizeUsage(parser.usage)];
 	const maybeApplyCommandUsageLine = (term, arg, isLastArg, usageIndex) => {
-		if (term?.type !== "command" || term.name !== arg || !isLastArg || term.usageLine == null) return;
+		if (term?.type !== "command" || !commandTermMatches(term, arg) || !isLastArg || term.usageLine == null) return;
 		const defaultUsageLine = require_usage.cloneUsage(usage.slice(usageIndex + 1));
 		const customUsageLine = typeof term.usageLine === "function" ? term.usageLine(defaultUsageLine) : term.usageLine;
 		const normalizedCustomUsageLine = require_usage.normalizeUsage(customUsageLine);

package/dist/internal/parser.d.cts

@@ -475,7 +475,15 @@ declare const unmatchedNonCliDependencySourceStateMarker: unique symbol;
  *
  * @internal
  */
-
+declare const inheritParentAnnotationsKey: unique symbol;
+/**
+ * Internal marker for wrapper parsers that should only treat annotation-only
+ * primitive wrapper states as completable when a nested source-binding wrapper
+ * produced them.
+ *
+ * @internal
+ */
+declare const annotationWrapperRequiresSourceBindingKey: unique symbol;
 /**
  * The context of the parser, which includes the input buffer and the state.
  *
@@ -823,7 +831,40 @@ declare function suggestSync<T>(parser: Parser<"sync", T, unknown>, args: readon
  * @returns The runtime nodes used to seed suggest-time dependency resolution.
  * @internal
  */
-
+declare function getParserSuggestRuntimeNodes<TState>(parser: Parser<Mode, unknown, TState>, state: TState, path: readonly PropertyKey[]): readonly RuntimeNode[];
+/**
+ * Returns wrapper-aware suggest-time runtime nodes for parsers that delegate
+ * to an inner parser while also exposing their own source metadata.
+ *
+ * The inner parser's nodes are always preserved so nested wrappers and
+ * constructs can continue to seed the dependency runtime recursively. When
+ * the outer parser itself owns source metadata, its `(path, parser, state)`
+ * node is appended so outer precedence rules still apply.
+ *
+ * @internal
+ */
+declare function getDelegatingSuggestRuntimeNodes<TInnerState>(innerParser: Parser<Mode, unknown, TInnerState>, outerParser: Parser<Mode, unknown, unknown>, state: unknown, path: readonly PropertyKey[], innerState: TInnerState, outerPosition?: "append" | "prepend"): readonly RuntimeNode[];
+/**
+ * Composes source metadata for a wrapper parser while preserving any derived
+ * or transform capabilities from the inner parser unchanged.
+ *
+ * @internal
+ */
+declare function composeWrappedSourceMetadata(dependencyMetadata: ParserDependencyMetadata | undefined, wrapSource: (source: NonNullable<ParserDependencyMetadata["source"]>) => NonNullable<ParserDependencyMetadata["source"]>): ParserDependencyMetadata | undefined;
+/**
+ * Marks a parser as inheriting parent-state annotations through wrapper-state
+ * reconstruction.
+ *
+ * @internal
+ */
+declare function defineInheritedAnnotationParser(parser: object): void;
+/**
+ * Marks a wrapper parser as requiring a real source-binding state before
+ * annotation-only primitive wrappers should trigger completion.
+ *
+ * @internal
+ */
+declare function defineSourceBindingOnlyAnnotationCompletionParser(parser: object): void;
 /**
  * Generates command-line suggestions based on current parsing state.
  * This function processes the input arguments up to the last argument,
@@ -958,4 +999,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 { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync };
+export { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, Result, Suggestion, annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker };