@optique/core 1.0.0-dev.1901 → 1.0.0-dev.1970

package/dist/parser.js

@@ -1,705 +1,3 @@
-import { hasMeaningfulAnnotations, 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";
-import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
-import { argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
-import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
+import { createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
 
-//#region src/parser.ts
-/**
-* Internal marker for wrappers whose `{ hasCliValue: false }` states should
-* be treated as unmatched dependency-source states during completion-time
-* Phase 1.
-*
-* Wrappers like `bindEnv()` and `bindConfig()` opt in because their missing
-* CLI states still carry enough fallback context to pre-complete exactly
-* once. Wrappers like `prompt()` intentionally do not opt in because
-* prompted values are not yet registered as dependency sources.
-*
-* @internal
-*/
-const unmatchedNonCliDependencySourceStateMarker = Symbol.for("@optique/core/parser/unmatchedNonCliDependencySourceStateMarker");
-/**
-* 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) {
-	const annotations = options?.annotations;
-	if (!hasMeaningfulAnnotations(annotations)) return state;
-	return injectAnnotations(state, 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);
-	let context = {
-		buffer: args,
-		optionsTerminated: false,
-		state: initialState,
-		usage: parser.usage
-	};
-	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);
-	let context = {
-		buffer: args,
-		optionsTerminated: false,
-		state: initialState,
-		usage: parser.usage
-	};
-	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 matched = parser.getDocFragments({
-			kind: "available",
-			state: ["matched", cmdName]
-		}, 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 { DuplicateOptionError, WithDefaultError, annotationWrapperRequiresSourceBindingKey, argument, command, composeWrappedSourceMetadata, concat, conditional, constant, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, fail, flag, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, group, inheritParentAnnotationsKey, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, unmatchedNonCliDependencySourceStateMarker, withDefault };
+export { createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync };