@optique/core 1.0.0-dev.908 → 1.0.0

package/dist/internal/parser.js

@@ -0,0 +1,711 @@
+import { hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
+import { cloneMessage, message } from "../message.js";
+import { cloneUsage, normalizeUsage } from "../usage.js";
+import { cloneDocEntry, isDocEntryHidden } from "../doc.js";
+import { dispatchByMode } from "./mode-dispatch.js";
+import { collectExplicitSourceValues, collectExplicitSourceValuesAsync, createDependencyRuntimeContext } from "../dependency-runtime.js";
+import { createInputTrace } from "../input-trace.js";
+
+//#region src/internal/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");
+/**
+* Internal marker for parsers that want parent-state annotations injected
+* directly into rebuilt child states instead of relying on structural
+* inheritance.
+*
+* Wrappers like `bindConfig()`, `bindEnv()`, and `prompt()` opt in because
+* their fallback contracts depend on carrying annotations through wrapper
+* state objects during parse, complete, and suggest.
+*
+* @internal
+*/
+const inheritParentAnnotationsKey = Symbol.for("@optique/core/inheritParentAnnotations");
+/**
+* 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
+*/
+const annotationWrapperRequiresSourceBindingKey = Symbol.for("@optique/core/annotationWrapperRequiresSourceBinding");
+/**
+* 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,
+		trace: exec.trace,
+		buffer: frame.buffer,
+		state: frame.state,
+		optionsTerminated: frame.optionsTerminated,
+		usage: exec.usage,
+		dependencyRegistry: exec.dependencyRegistry
+	};
+}
+function injectAnnotationsIntoState(state, options) {
+	return injectAnnotations(state, options?.annotations);
+}
+/**
+* Parses an array of command-line arguments using the provided combined parser.
+* This function processes the input arguments, applying the parser to each
+* argument until all arguments are consumed or an error occurs.
+*
+* This function only accepts synchronous parsers. For asynchronous parsers,
+* use {@link parseAsync}.
+*
+* @template T The type of the value produced by the parser.
+* @param parser The combined {@link Parser} to use for parsing the input
+*               arguments.  Must be a synchronous parser.
+* @param args The array of command-line arguments to parse.  Usually this is
+*             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
+* @param options Optional {@link ParseOptions} for customizing parsing behavior.
+* @returns A {@link Result} object indicating whether the parsing was
+*          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.
+*/
+function parseSync(parser, args, options) {
+	const initialState = injectAnnotationsIntoState(parser.initialState, options);
+	const shouldUnwrapAnnotatedValue = hasMeaningfulAnnotations(options?.annotations) || isInjectedAnnotationWrapper(parser.initialState);
+	const exec = {
+		usage: parser.usage,
+		phase: "parse",
+		path: [],
+		trace: createInputTrace()
+	};
+	let context = createParserContext({
+		buffer: args,
+		state: initialState,
+		optionsTerminated: false
+	}, exec);
+	do {
+		const result = parser.parse(context);
+		if (!result.success) return {
+			success: false,
+			error: result.error
+		};
+		const previousBuffer = context.buffer;
+		context = result.next;
+		if (isBufferUnchanged(previousBuffer, context.buffer)) return {
+			success: false,
+			error: message`Unexpected option or argument: ${context.buffer[0]}.`
+		};
+	} while (context.buffer.length > 0);
+	const runtime = createDependencyRuntimeContext();
+	const completeExec = {
+		...exec,
+		phase: "complete",
+		dependencyRuntime: runtime,
+		dependencyRegistry: runtime.registry,
+		trace: context.exec?.trace ?? context.trace ?? exec.trace
+	};
+	const endResult = parser.complete(context.state, completeExec);
+	return endResult.success ? {
+		success: true,
+		value: shouldUnwrapAnnotatedValue ? unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
+		...endResult.deferred ? { deferred: true } : {},
+		...endResult.deferredKeys ? { deferredKeys: endResult.deferredKeys } : {}
+	} : {
+		success: false,
+		error: endResult.error
+	};
+}
+/**
+* Returns `true` when the buffer has not changed between iterations,
+* indicating a parser is stalling without consuming input.
+*/
+function isBufferUnchanged(previous, current) {
+	return current.length > 0 && current.length === previous.length && current.every((item, i) => item === previous[i]);
+}
+/**
+* Parses an array of command-line arguments using the provided combined parser.
+* This function processes the input arguments, applying the parser to each
+* argument until all arguments are consumed or an error occurs.
+*
+* This function accepts any parser (sync or async) and always returns a Promise.
+* For synchronous parsing with sync parsers, use {@link parseSync} instead.
+*
+* @template T The type of the value produced by the parser.
+* @param parser The combined {@link Parser} to use for parsing the input
+*               arguments.
+* @param args The array of command-line arguments to parse.  Usually this is
+*             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
+* @param options Optional {@link ParseOptions} for customizing parsing behavior.
+* @returns A Promise that resolves to a {@link Result} object indicating
+*          whether the parsing was successful or not.
+* @since 0.9.0
+* @since 0.10.0 Added optional `options` parameter for annotations support.
+*/
+async function parseAsync(parser, args, options) {
+	const initialState = injectAnnotationsIntoState(parser.initialState, options);
+	const shouldUnwrapAnnotatedValue = hasMeaningfulAnnotations(options?.annotations) || isInjectedAnnotationWrapper(parser.initialState);
+	const exec = {
+		usage: parser.usage,
+		phase: "parse",
+		path: [],
+		trace: createInputTrace()
+	};
+	let context = createParserContext({
+		buffer: args,
+		state: initialState,
+		optionsTerminated: false
+	}, exec);
+	do {
+		const result = await parser.parse(context);
+		if (!result.success) return {
+			success: false,
+			error: result.error
+		};
+		const previousBuffer = context.buffer;
+		context = result.next;
+		if (isBufferUnchanged(previousBuffer, context.buffer)) return {
+			success: false,
+			error: message`Unexpected option or argument: ${context.buffer[0]}.`
+		};
+	} while (context.buffer.length > 0);
+	const runtime = createDependencyRuntimeContext();
+	const completeExec = {
+		...exec,
+		phase: "complete",
+		dependencyRuntime: runtime,
+		dependencyRegistry: runtime.registry,
+		trace: context.exec?.trace ?? context.trace ?? exec.trace
+	};
+	const endResult = await parser.complete(context.state, completeExec);
+	return endResult.success ? {
+		success: true,
+		value: shouldUnwrapAnnotatedValue ? unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
+		...endResult.deferred ? { deferred: true } : {},
+		...endResult.deferredKeys ? { deferredKeys: endResult.deferredKeys } : {}
+	} : {
+		success: false,
+		error: endResult.error
+	};
+}
+/**
+* Parses an array of command-line arguments using the provided combined parser.
+* This function processes the input arguments, applying the parser to each
+* argument until all arguments are consumed or an error occurs.
+*
+* The return type depends on the parser's mode:
+* - Sync parsers return `Result<T>` directly.
+* - Async parsers return `Promise<Result<T>>`.
+*
+* For explicit control, use {@link parseSync} or {@link parseAsync}.
+*
+* @template M The execution mode of the parser.
+* @template T The type of the value produced by the parser.
+* @param parser The combined {@link Parser} to use for parsing the input
+*               arguments.
+* @param args The array of command-line arguments to parse.  Usually this is
+*             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
+* @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) {
+	return dispatchByMode(parser.mode, () => parseSync(parser, args, options), () => parseAsync(parser, args, options));
+}
+/**
+* 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.
+*
+* This function only accepts synchronous parsers. For asynchronous parsers,
+* use {@link suggestAsync}.
+*
+* @template T The type of the value produced by the parser.
+* @param parser The {@link Parser} to use for generating suggestions.
+*               Must be a synchronous parser.
+* @param args The array of command-line arguments including the partial
+*             argument to complete.  The last element is treated as
+*             the prefix for suggestions.
+* @param options Optional {@link ParseOptions} for customizing parsing behavior.
+* @returns An array of {@link Suggestion} objects containing completion
+*          candidates.
+* @example
+* ```typescript
+* const parser = object({
+*   verbose: option("-v", "--verbose"),
+*   format: option("-f", "--format", choice(["json", "yaml"]))
+* });
+*
+* // Get suggestions for options starting with "--"
+* const suggestions = suggestSync(parser, ["--"]);
+* // Returns: [{ text: "--verbose" }, { text: "--format" }]
+*
+* // Get suggestions after parsing some arguments
+* 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.
+*/
+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 = createParserContext({
+		buffer: allButLast,
+		state: initialState,
+		optionsTerminated: false
+	}, {
+		usage: parser.usage,
+		phase: "suggest",
+		path: [],
+		trace: createInputTrace()
+	});
+	while (context.buffer.length > 0) {
+		const result = parser.parse(context);
+		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(parser, context), prefix));
+}
+/**
+* Creates a dependency runtime from the current parser state and returns
+* a context with the populated registry.  Used by top-level suggest
+* functions to mirror the construct-owned model where suggest() receives
+* a context with a dependency registry.
+* @internal
+*/
+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();
+	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
+	}];
+}
+/**
+* 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
+*/
+function getDelegatingSuggestRuntimeNodes(innerParser, outerParser, state, path, innerState, outerPosition = "append") {
+	const innerNodes = getParserSuggestRuntimeNodes(innerParser, innerState, path);
+	if (outerParser.dependencyMetadata?.source == null) return innerNodes;
+	const outerNode = {
+		path,
+		parser: outerParser,
+		state
+	};
+	return outerPosition === "prepend" ? [outerNode, ...innerNodes] : [...innerNodes, outerNode];
+}
+/**
+* Composes source metadata for a wrapper parser while preserving any derived
+* or transform capabilities from the inner parser unchanged.
+*
+* @internal
+*/
+function composeWrappedSourceMetadata(dependencyMetadata, wrapSource) {
+	if (dependencyMetadata?.source == null) return dependencyMetadata;
+	return {
+		...dependencyMetadata,
+		source: wrapSource(dependencyMetadata.source)
+	};
+}
+/**
+* Marks a parser as inheriting parent-state annotations through wrapper-state
+* reconstruction.
+*
+* @internal
+*/
+function defineInheritedAnnotationParser(parser) {
+	Object.defineProperty(parser, inheritParentAnnotationsKey, {
+		value: true,
+		configurable: true,
+		enumerable: false
+	});
+}
+/**
+* Marks a wrapper parser as requiring a real source-binding state before
+* annotation-only primitive wrappers should trigger completion.
+*
+* @internal
+*/
+function defineSourceBindingOnlyAnnotationCompletionParser(parser) {
+	Object.defineProperty(parser, annotationWrapperRequiresSourceBindingKey, {
+		value: true,
+		configurable: true,
+		enumerable: false
+	});
+}
+/**
+* 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.
+*
+* This function accepts any parser (sync or async) and always returns a Promise.
+* For synchronous suggestion generation with sync parsers, use
+* {@link suggestSync} instead.
+*
+* @template T The type of the value produced by the parser.
+* @param parser The {@link Parser} to use for generating suggestions.
+* @param args The array of command-line arguments including the partial
+*             argument to complete.  The last element is treated as
+*             the prefix for suggestions.
+* @param options Optional {@link ParseOptions} for customizing parsing behavior.
+* @returns A Promise that resolves to an array of {@link Suggestion} objects
+*          containing completion candidates.
+* @since 0.9.0
+* @since 0.10.0 Added optional `options` parameter for annotations support.
+*/
+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 = createParserContext({
+		buffer: allButLast,
+		state: initialState,
+		optionsTerminated: false
+	}, {
+		usage: parser.usage,
+		phase: "suggest",
+		path: [],
+		trace: createInputTrace()
+	});
+	while (context.buffer.length > 0) {
+		const result = await parser.parse(context);
+		if (!result.success) {
+			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;
+		}
+		const previousBuffer = context.buffer;
+		context = result.next;
+		if (isBufferUnchanged(previousBuffer, context.buffer)) return [];
+	}
+	const ctx = await withSuggestRuntimeAsync(parser, context);
+	const suggestions = [];
+	for await (const suggestion of parser.suggest(ctx, prefix)) suggestions.push(suggestion);
+	return suggestions;
+}
+/**
+* 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.
+*
+* The return type depends on the parser's mode:
+* - Sync parsers return `readonly Suggestion[]` directly.
+* - Async parsers return `Promise<readonly Suggestion[]>`.
+*
+* For explicit control, use {@link suggestSync} or {@link suggestAsync}.
+*
+* @template M The execution mode of the parser.
+* @template T The type of the value produced by the parser.
+* @param parser The {@link Parser} to use for generating suggestions.
+* @param args The array of command-line arguments including the partial
+*             argument to complete.  The last element is treated as
+*             the prefix for suggestions.
+* @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.
+*/
+function suggest(parser, args, options) {
+	return dispatchByMode(parser.mode, () => suggestSync(parser, args, options), () => suggestAsync(parser, args, options));
+}
+/**
+* Recursively searches for a command within nested exclusive usage terms.
+* When the command is found, returns the expanded usage terms for that command.
+*
+* @param term The usage term to search in
+* @param commandName The command name to find
+* @returns The expanded usage terms if found, null otherwise
+*/
+function findCommandInExclusive(term, commandName) {
+	if (term.type !== "exclusive") return null;
+	for (const termGroup of term.terms) {
+		const firstTerm = termGroup[0];
+		if (firstTerm?.type === "command" && firstTerm.name === commandName) return termGroup;
+		if (firstTerm?.type === "exclusive") {
+			const found = findCommandInExclusive(firstTerm, commandName);
+			if (found) return [...found, ...termGroup.slice(1)];
+		}
+	}
+	return null;
+}
+/**
+* Generates a documentation page for a synchronous parser.
+*
+* This is the sync-specific version of {@link getDocPage}. It only accepts
+* sync parsers and returns the documentation page directly (not wrapped
+* in a Promise).
+*
+* @param parser The sync parser to generate documentation for.
+* @param argsOrOptions Optional array of command-line arguments for context,
+*        or a {@link ParseOptions} object for annotations.  When a
+*        `ParseOptions` is passed here, the `options` parameter is ignored.
+* @param options Optional {@link ParseOptions} for customizing parsing
+*        behavior.  Only used when `argsOrOptions` is an array or omitted.
+* @returns A {@link DocPage} or `undefined`.
+* @since 0.9.0
+* @since 0.10.0 Added optional `options` parameter for annotations support.
+* @since 1.0.0 The second parameter now also accepts a `ParseOptions` object
+*              directly.
+*/
+function getDocPageSync(parser, argsOrOptions, options) {
+	if (Array.isArray(argsOrOptions)) return getDocPageSyncImpl(parser, argsOrOptions, options);
+	return getDocPageSyncImpl(parser, [], argsOrOptions ?? options);
+}
+/**
+* Generates a documentation page for any parser, returning a Promise.
+*
+* This function accepts parsers of any mode (sync or async) and always
+* returns a Promise. Use this when working with parsers that may contain
+* async value parsers.
+*
+* @param parser The parser to generate documentation for.
+* @param argsOrOptions Optional array of command-line arguments for context,
+*        or a {@link ParseOptions} object for annotations.  When a
+*        `ParseOptions` is passed here, the `options` parameter is ignored.
+* @param options Optional {@link ParseOptions} for customizing parsing
+*        behavior.  Only used when `argsOrOptions` is an array or omitted.
+* @returns A Promise of {@link DocPage} or `undefined`.
+* @since 0.9.0
+* @since 0.10.0 Added optional `options` parameter for annotations support.
+* @since 1.0.0 The second parameter now also accepts a `ParseOptions` object
+*              directly.
+*/
+function getDocPageAsync(parser, argsOrOptions, options) {
+	const args = Array.isArray(argsOrOptions) ? argsOrOptions : [];
+	const opts = Array.isArray(argsOrOptions) ? options : argsOrOptions ?? options;
+	if (parser.mode === "sync") return Promise.resolve(getDocPageSyncImpl(parser, args, opts));
+	return getDocPageAsyncImpl(parser, args, opts);
+}
+function getDocPage(parser, argsOrOptions, options) {
+	const args = Array.isArray(argsOrOptions) ? argsOrOptions : [];
+	const opts = Array.isArray(argsOrOptions) ? options : argsOrOptions ?? options;
+	if (parser.mode === "sync") return getDocPageSyncImpl(parser, args, opts);
+	return getDocPageAsyncImpl(parser, args, opts);
+}
+/**
+* Internal sync implementation of getDocPage.
+*/
+function getDocPageSyncImpl(parser, args, options) {
+	const initialState = injectAnnotationsIntoState(parser.initialState, options);
+	const exec = {
+		usage: parser.usage,
+		phase: "parse",
+		path: [],
+		trace: createInputTrace()
+	};
+	let context = createParserContext({
+		buffer: args,
+		state: initialState,
+		optionsTerminated: false
+	}, exec);
+	while (context.buffer.length > 0) {
+		const result = parser.parse(context);
+		if (!result.success) break;
+		const previousBuffer = context.buffer;
+		context = result.next;
+		if (isBufferUnchanged(previousBuffer, context.buffer)) break;
+	}
+	return buildDocPage(parser, context, args);
+}
+/**
+* Internal async implementation of getDocPage.
+*/
+async function getDocPageAsyncImpl(parser, args, options) {
+	const initialState = injectAnnotationsIntoState(parser.initialState, options);
+	const exec = {
+		usage: parser.usage,
+		phase: "parse",
+		path: [],
+		trace: createInputTrace()
+	};
+	let context = createParserContext({
+		buffer: args,
+		state: initialState,
+		optionsTerminated: false
+	}, exec);
+	while (context.buffer.length > 0) {
+		const result = await parser.parse(context);
+		if (!result.success) break;
+		const previousBuffer = context.buffer;
+		context = result.next;
+		if (isBufferUnchanged(previousBuffer, context.buffer)) break;
+	}
+	return buildDocPage(parser, context, args);
+}
+/**
+* Builds a DocPage from the parser and context.
+* Shared by both sync and async implementations.
+*/
+function buildDocPage(parser, context, args) {
+	let effectiveArgs = args;
+	let { brief, description, fragments, footer } = parser.getDocFragments({
+		kind: "available",
+		state: context.state
+	}, 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 = inheritAnnotations(context.state, ["matched", cmdName]);
+		const matched = parser.getDocFragments({
+			kind: "available",
+			state: matchedState
+		}, void 0);
+		({brief, description, fragments, footer} = matched);
+		effectiveArgs = [cmdName];
+	}
+	const buildingSections = [];
+	let untitledSection = null;
+	const titledSectionMap = /* @__PURE__ */ new Map();
+	for (const fragment of fragments) if (fragment.type === "entry") {
+		if (isDocEntryHidden(fragment)) continue;
+		if (untitledSection == null) {
+			untitledSection = { entries: [] };
+			buildingSections.push(untitledSection);
+		}
+		untitledSection.entries.push(cloneDocEntry(fragment));
+	} else if (fragment.type === "section") {
+		const visible = fragment.entries.filter((e) => !isDocEntryHidden(e));
+		if (visible.length === 0) continue;
+		if (fragment.title == null) {
+			if (untitledSection == null) {
+				untitledSection = { entries: [] };
+				buildingSections.push(untitledSection);
+			}
+			untitledSection.entries.push(...visible.map(cloneDocEntry));
+		} else {
+			let section = titledSectionMap.get(fragment.title);
+			if (section == null) {
+				section = {
+					title: fragment.title,
+					entries: []
+				};
+				titledSectionMap.set(fragment.title, section);
+				buildingSections.push(section);
+			}
+			section.entries.push(...visible.map(cloneDocEntry));
+		}
+	}
+	const sections = buildingSections;
+	const usage = [...normalizeUsage(parser.usage)];
+	const maybeApplyCommandUsageLine = (term, arg, isLastArg, usageIndex) => {
+		if (term?.type !== "command" || term.name !== arg || !isLastArg || term.usageLine == null) return;
+		const defaultUsageLine = cloneUsage(usage.slice(usageIndex + 1));
+		const customUsageLine = typeof term.usageLine === "function" ? term.usageLine(defaultUsageLine) : term.usageLine;
+		const normalizedCustomUsageLine = normalizeUsage(customUsageLine);
+		usage.splice(usageIndex + 1, usage.length - (usageIndex + 1), ...normalizedCustomUsageLine);
+	};
+	let i = 0;
+	for (let argIndex = 0; argIndex < effectiveArgs.length; argIndex++) {
+		const arg = effectiveArgs[argIndex];
+		if (i >= usage.length) break;
+		let term = usage[i];
+		if (term.type === "exclusive") {
+			const found = findCommandInExclusive(term, arg);
+			if (found) {
+				usage.splice(i, 1, ...found);
+				term = usage[i];
+			}
+		}
+		maybeApplyCommandUsageLine(term, arg, argIndex === effectiveArgs.length - 1, i);
+		i++;
+	}
+	if (effectiveArgs.length === 0 && usage.length > 0) {
+		const first = usage[0];
+		if (first.type === "command" && first.usageLine != null) {
+			const defaultUsageLine = cloneUsage(usage.slice(1));
+			const customUsageLine = typeof first.usageLine === "function" ? first.usageLine(defaultUsageLine) : first.usageLine;
+			const normalizedCustomUsageLine = normalizeUsage(customUsageLine);
+			usage.splice(1, usage.length - 1, ...normalizedCustomUsageLine);
+		}
+	}
+	return {
+		usage,
+		sections,
+		...brief != null && { brief: cloneMessage(brief) },
+		...description != null && { description: cloneMessage(description) },
+		...footer != null && { footer: cloneMessage(footer) }
+	};
+}
+
+//#endregion
+export { annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker };