@optique/core 1.4.0-dev.2899 → 1.4.0-dev.2935

package/dist/internal/doc-metadata.cjs

@@ -0,0 +1,121 @@
+const require_message = require('../message.cjs');
+
+//#region src/internal/doc-metadata.ts
+const nodes = /* @__PURE__ */ new WeakMap();
+const values = /* @__PURE__ */ new WeakMap();
+const usageSnapshots = /* @__PURE__ */ new WeakMap();
+const termSnapshots = /* @__PURE__ */ new WeakMap();
+function snapshotUsage(usage) {
+	const existing = usageSnapshots.get(usage);
+	if (existing != null) return existing;
+	const snapshot = Object.freeze(usage.map(snapshotUsageTerm));
+	usageSnapshots.set(usage, snapshot);
+	return snapshot;
+}
+function snapshotUsageTerm(term) {
+	const existing = termSnapshots.get(term);
+	if (existing != null) return existing;
+	let snapshot;
+	switch (term.type) {
+		case "option":
+			snapshot = {
+				...term,
+				names: Object.freeze([...term.names])
+			};
+			break;
+		case "command":
+			snapshot = {
+				...term,
+				...term.aliases != null && { aliases: Object.freeze([...term.aliases]) },
+				...term.hiddenAliases != null && { hiddenAliases: Object.freeze([...term.hiddenAliases]) },
+				...term.usageLine != null && typeof term.usageLine !== "function" && { usageLine: snapshotUsage(term.usageLine) }
+			};
+			break;
+		case "optional":
+		case "sequence":
+			snapshot = {
+				type: term.type,
+				terms: snapshotUsage(term.terms)
+			};
+			break;
+		case "multiple":
+			snapshot = {
+				type: "multiple",
+				terms: snapshotUsage(term.terms),
+				min: term.min,
+				...term.acceptsEmpty != null && { acceptsEmpty: term.acceptsEmpty }
+			};
+			break;
+		case "exclusive":
+			snapshot = {
+				type: "exclusive",
+				terms: Object.freeze(term.terms.map(snapshotUsage)),
+				...term.acceptsEmpty != null && { acceptsEmpty: term.acceptsEmpty }
+			};
+			break;
+		default: snapshot = { ...term };
+	}
+	Object.freeze(snapshot);
+	termSnapshots.set(term, snapshot);
+	return snapshot;
+}
+/**
+* Captures only constructor-owned built-in value documentation.
+* @param parser The built-in value parser's final identity.
+* @param metadata Static formatting facts owned by its constructor.
+* @returns The same parser, with private documentation metadata registered.
+* @internal
+*/
+function captureDocValue(parser, metadata) {
+	values.set(parser, Object.freeze({
+		...metadata,
+		choices: metadata.choices == null ? void 0 : Object.freeze(metadata.choices.slice())
+	}));
+	return parser;
+}
+/**
+* Captures metadata at the return boundary of a listed built-in constructor.
+* @param parser The supported parser's final identity and static usage.
+* @param metadata Constructor-owned documentation inputs to snapshot.
+* @returns The same parser, with private documentation metadata registered.
+* @internal
+*/
+function captureDocParser(parser, metadata) {
+	nodes.set(parser, {
+		...metadata,
+		brief: metadata.brief == null ? void 0 : require_message.cloneMessage(metadata.brief),
+		description: metadata.description == null ? void 0 : require_message.cloneMessage(metadata.description),
+		footer: metadata.footer == null ? void 0 : require_message.cloneMessage(metadata.footer),
+		defaultMessage: metadata.defaultMessage == null ? void 0 : require_message.cloneMessage(metadata.defaultMessage),
+		usageLine: typeof metadata.usageLine === "function" || metadata.usageLine == null ? metadata.usageLine : snapshotUsage(metadata.usageLine),
+		children: metadata.children?.slice(),
+		aliases: metadata.aliases?.slice(),
+		hiddenAliases: metadata.hiddenAliases?.slice(),
+		usage: snapshotUsage(parser.usage)
+	});
+	return parser;
+}
+/**
+* Reads a core-owned node without consulting the parser object.
+* @param parser A parser identity, including an opaque custom parser.
+* @returns Its captured node, or undefined for an unregistered identity.
+* @internal
+*/
+function getDocNode(parser) {
+	return nodes.get(parser);
+}
+/**
+* Reads core-owned static value documentation.
+* @param parser A value parser identity.
+* @returns Its captured facts, or undefined for an unregistered identity.
+* @internal
+*/
+function getDocValue(parser) {
+	return values.get(parser);
+}
+
+//#endregion
+exports.captureDocParser = captureDocParser;
+exports.captureDocValue = captureDocValue;
+exports.getDocNode = getDocNode;
+exports.getDocValue = getDocValue;

package/dist/internal/doc-metadata.d.cts

@@ -0,0 +1,72 @@
+import { Message } from "../message.cjs";
+import { HiddenVisibility, Usage } from "../usage.cjs";
+
+//#region src/internal/doc-metadata.d.ts
+/** Static inputs captured by supported constructors. @internal */
+interface DocNodeInput {
+  readonly kind: "leaf" | "command" | "or" | "object" | "seq" | "optional" | "multiple" | "default";
+  readonly children?: readonly object[];
+  readonly name?: string;
+  readonly aliases?: readonly string[];
+  readonly hiddenAliases?: readonly string[];
+  readonly showAliases?: boolean;
+  readonly showUsage?: boolean;
+  readonly hidden?: HiddenVisibility;
+  readonly brief?: Message;
+  readonly description?: Message;
+  readonly footer?: Message;
+  readonly usageLine?: Usage | ((usage: Usage) => Usage);
+  readonly valueParser?: object;
+  readonly choicesRequested?: boolean;
+  readonly boolean?: boolean;
+  readonly label?: string;
+  readonly min?: number;
+  readonly defaultValue?: unknown;
+  readonly defaultMessage?: Message;
+}
+/** A constructor snapshot. @internal */
+interface DocNode extends DocNodeInput {
+  readonly usage: Usage;
+}
+/** Safe built-in value formatting facts. @internal */
+interface DocValueMetadata {
+  readonly kind: "string" | "number" | "bigint";
+  /** Already deduplicated by the constructor, preserving both zero signs. */
+  readonly choices?: readonly (string | number)[];
+  readonly canFormatDefault?: boolean;
+  readonly preserveNegativeZero?: boolean;
+}
+/**
+ * Captures only constructor-owned built-in value documentation.
+ * @param parser The built-in value parser's final identity.
+ * @param metadata Static formatting facts owned by its constructor.
+ * @returns The same parser, with private documentation metadata registered.
+ * @internal
+ */
+declare function captureDocValue<const T extends object>(parser: T, metadata: DocValueMetadata): T;
+/**
+ * Captures metadata at the return boundary of a listed built-in constructor.
+ * @param parser The supported parser's final identity and static usage.
+ * @param metadata Constructor-owned documentation inputs to snapshot.
+ * @returns The same parser, with private documentation metadata registered.
+ * @internal
+ */
+declare function captureDocParser<T extends {
+  readonly usage: Usage;
+}>(parser: T, metadata: DocNodeInput): T;
+/**
+ * Reads a core-owned node without consulting the parser object.
+ * @param parser A parser identity, including an opaque custom parser.
+ * @returns Its captured node, or undefined for an unregistered identity.
+ * @internal
+ */
+declare function getDocNode(parser: object): DocNode | undefined;
+/**
+ * Reads core-owned static value documentation.
+ * @param parser A value parser identity.
+ * @returns Its captured facts, or undefined for an unregistered identity.
+ * @internal
+ */
+declare function getDocValue(parser: object): DocValueMetadata | undefined;
+//#endregion
+export { DocNode, DocNodeInput, DocValueMetadata, captureDocParser, captureDocValue, getDocNode, getDocValue };

package/dist/internal/doc-metadata.d.ts

@@ -0,0 +1,72 @@
+import { Message } from "../message.js";
+import { HiddenVisibility, Usage } from "../usage.js";
+
+//#region src/internal/doc-metadata.d.ts
+/** Static inputs captured by supported constructors. @internal */
+interface DocNodeInput {
+  readonly kind: "leaf" | "command" | "or" | "object" | "seq" | "optional" | "multiple" | "default";
+  readonly children?: readonly object[];
+  readonly name?: string;
+  readonly aliases?: readonly string[];
+  readonly hiddenAliases?: readonly string[];
+  readonly showAliases?: boolean;
+  readonly showUsage?: boolean;
+  readonly hidden?: HiddenVisibility;
+  readonly brief?: Message;
+  readonly description?: Message;
+  readonly footer?: Message;
+  readonly usageLine?: Usage | ((usage: Usage) => Usage);
+  readonly valueParser?: object;
+  readonly choicesRequested?: boolean;
+  readonly boolean?: boolean;
+  readonly label?: string;
+  readonly min?: number;
+  readonly defaultValue?: unknown;
+  readonly defaultMessage?: Message;
+}
+/** A constructor snapshot. @internal */
+interface DocNode extends DocNodeInput {
+  readonly usage: Usage;
+}
+/** Safe built-in value formatting facts. @internal */
+interface DocValueMetadata {
+  readonly kind: "string" | "number" | "bigint";
+  /** Already deduplicated by the constructor, preserving both zero signs. */
+  readonly choices?: readonly (string | number)[];
+  readonly canFormatDefault?: boolean;
+  readonly preserveNegativeZero?: boolean;
+}
+/**
+ * Captures only constructor-owned built-in value documentation.
+ * @param parser The built-in value parser's final identity.
+ * @param metadata Static formatting facts owned by its constructor.
+ * @returns The same parser, with private documentation metadata registered.
+ * @internal
+ */
+declare function captureDocValue<const T extends object>(parser: T, metadata: DocValueMetadata): T;
+/**
+ * Captures metadata at the return boundary of a listed built-in constructor.
+ * @param parser The supported parser's final identity and static usage.
+ * @param metadata Constructor-owned documentation inputs to snapshot.
+ * @returns The same parser, with private documentation metadata registered.
+ * @internal
+ */
+declare function captureDocParser<T extends {
+  readonly usage: Usage;
+}>(parser: T, metadata: DocNodeInput): T;
+/**
+ * Reads a core-owned node without consulting the parser object.
+ * @param parser A parser identity, including an opaque custom parser.
+ * @returns Its captured node, or undefined for an unregistered identity.
+ * @internal
+ */
+declare function getDocNode(parser: object): DocNode | undefined;
+/**
+ * Reads core-owned static value documentation.
+ * @param parser A value parser identity.
+ * @returns Its captured facts, or undefined for an unregistered identity.
+ * @internal
+ */
+declare function getDocValue(parser: object): DocValueMetadata | undefined;
+//#endregion
+export { DocNode, DocNodeInput, DocValueMetadata, captureDocParser, captureDocValue, getDocNode, getDocValue };

package/dist/internal/doc-metadata.js

@@ -0,0 +1,118 @@
+import { cloneMessage } from "../message.js";
+
+//#region src/internal/doc-metadata.ts
+const nodes = /* @__PURE__ */ new WeakMap();
+const values = /* @__PURE__ */ new WeakMap();
+const usageSnapshots = /* @__PURE__ */ new WeakMap();
+const termSnapshots = /* @__PURE__ */ new WeakMap();
+function snapshotUsage(usage) {
+	const existing = usageSnapshots.get(usage);
+	if (existing != null) return existing;
+	const snapshot = Object.freeze(usage.map(snapshotUsageTerm));
+	usageSnapshots.set(usage, snapshot);
+	return snapshot;
+}
+function snapshotUsageTerm(term) {
+	const existing = termSnapshots.get(term);
+	if (existing != null) return existing;
+	let snapshot;
+	switch (term.type) {
+		case "option":
+			snapshot = {
+				...term,
+				names: Object.freeze([...term.names])
+			};
+			break;
+		case "command":
+			snapshot = {
+				...term,
+				...term.aliases != null && { aliases: Object.freeze([...term.aliases]) },
+				...term.hiddenAliases != null && { hiddenAliases: Object.freeze([...term.hiddenAliases]) },
+				...term.usageLine != null && typeof term.usageLine !== "function" && { usageLine: snapshotUsage(term.usageLine) }
+			};
+			break;
+		case "optional":
+		case "sequence":
+			snapshot = {
+				type: term.type,
+				terms: snapshotUsage(term.terms)
+			};
+			break;
+		case "multiple":
+			snapshot = {
+				type: "multiple",
+				terms: snapshotUsage(term.terms),
+				min: term.min,
+				...term.acceptsEmpty != null && { acceptsEmpty: term.acceptsEmpty }
+			};
+			break;
+		case "exclusive":
+			snapshot = {
+				type: "exclusive",
+				terms: Object.freeze(term.terms.map(snapshotUsage)),
+				...term.acceptsEmpty != null && { acceptsEmpty: term.acceptsEmpty }
+			};
+			break;
+		default: snapshot = { ...term };
+	}
+	Object.freeze(snapshot);
+	termSnapshots.set(term, snapshot);
+	return snapshot;
+}
+/**
+* Captures only constructor-owned built-in value documentation.
+* @param parser The built-in value parser's final identity.
+* @param metadata Static formatting facts owned by its constructor.
+* @returns The same parser, with private documentation metadata registered.
+* @internal
+*/
+function captureDocValue(parser, metadata) {
+	values.set(parser, Object.freeze({
+		...metadata,
+		choices: metadata.choices == null ? void 0 : Object.freeze(metadata.choices.slice())
+	}));
+	return parser;
+}
+/**
+* Captures metadata at the return boundary of a listed built-in constructor.
+* @param parser The supported parser's final identity and static usage.
+* @param metadata Constructor-owned documentation inputs to snapshot.
+* @returns The same parser, with private documentation metadata registered.
+* @internal
+*/
+function captureDocParser(parser, metadata) {
+	nodes.set(parser, {
+		...metadata,
+		brief: metadata.brief == null ? void 0 : cloneMessage(metadata.brief),
+		description: metadata.description == null ? void 0 : cloneMessage(metadata.description),
+		footer: metadata.footer == null ? void 0 : cloneMessage(metadata.footer),
+		defaultMessage: metadata.defaultMessage == null ? void 0 : cloneMessage(metadata.defaultMessage),
+		usageLine: typeof metadata.usageLine === "function" || metadata.usageLine == null ? metadata.usageLine : snapshotUsage(metadata.usageLine),
+		children: metadata.children?.slice(),
+		aliases: metadata.aliases?.slice(),
+		hiddenAliases: metadata.hiddenAliases?.slice(),
+		usage: snapshotUsage(parser.usage)
+	});
+	return parser;
+}
+/**
+* Reads a core-owned node without consulting the parser object.
+* @param parser A parser identity, including an opaque custom parser.
+* @returns Its captured node, or undefined for an unregistered identity.
+* @internal
+*/
+function getDocNode(parser) {
+	return nodes.get(parser);
+}
+/**
+* Reads core-owned static value documentation.
+* @param parser A value parser identity.
+* @returns Its captured facts, or undefined for an unregistered identity.
+* @internal
+*/
+function getDocValue(parser) {
+	return values.get(parser);
+}
+
+//#endregion
+export { captureDocParser, captureDocValue, getDocNode, getDocValue };

package/dist/modifiers.cjs

@@ -5,6 +5,7 @@ const require_dependency_runtime = require('./dependency-runtime.cjs');
 const require_internal_parser = require('./internal/parser.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
 const require_joined_file_suggestion = require('./internal/joined-file-suggestion.cjs');
+const require_internal_doc_metadata = require('./internal/doc-metadata.cjs');
 const require_empty_input = require('./internal/empty-input.cjs');
 const require_execution_context = require('./execution-context.cjs');
 const require_short_option = require('./short-option.cjs');
@@ -498,7 +499,10 @@ function optional(parser) {
 	require_passthrough.defineKnownCompletionLookup(optionalParser, (state) => require_passthrough.getKnownCompletion(parser, deriveOptionalInnerParseState(state, parser)));
 	const scopedOptionalParser = require_short_option.scopeParser(optionalParser, require_short_option.combinedOptionScope([parser]));
 	require_empty_input.defineEmptyInputFacts(scopedOptionalParser, require_empty_input.optionalLikeFacts(require_empty_input.getEmptyInputFacts(parser), parser.initialState, completesOptionalLikeFallback(parser)));
-	return fluent(scopedOptionalParser);
+	return require_internal_doc_metadata.captureDocParser(fluent(scopedOptionalParser), {
+		kind: "optional",
+		children: [parser]
+	});
 }
 /**
 * Error type for structured error messages in {@link withDefault} default value callbacks.
@@ -756,7 +760,12 @@ function withDefault(parser, defaultValue, options) {
 	require_passthrough.defineKnownCompletionLookup(withDefaultParser, (state) => require_passthrough.getKnownCompletion(parser, deriveOptionalInnerParseState(state, parser)));
 	const scopedWithDefaultParser = require_short_option.scopeParser(withDefaultParser, require_short_option.combinedOptionScope([parser]));
 	require_empty_input.defineEmptyInputFacts(scopedWithDefaultParser, require_empty_input.optionalLikeFacts(require_empty_input.getEmptyInputFacts(parser), parser.initialState, typeof defaultValue === "function" ? void 0 : completesOptionalLikeFallback(parser)));
-	return fluent(scopedWithDefaultParser);
+	return require_internal_doc_metadata.captureDocParser(fluent(scopedWithDefaultParser), {
+		kind: "default",
+		children: [parser],
+		defaultValue,
+		defaultMessage: options?.message
+	});
 }
 /**
 * Creates a parser that transforms the result value of another parser using
@@ -1798,7 +1807,11 @@ function multiple(parser, options = {}) {
 	})));
 	const scopedResultParser = require_short_option.scopeParser(resultParser, require_short_option.repeatedOptionScope(parser));
 	require_empty_input.defineEmptyInputFacts(scopedResultParser, emptyInputFacts);
-	return fluent(scopedResultParser);
+	return require_internal_doc_metadata.captureDocParser(fluent(scopedResultParser), {
+		kind: "multiple",
+		children: [parser],
+		min
+	});
 }
 /**
 * Creates a parser that requires the wrapped parser to consume at least one

package/dist/modifiers.js

@@ -5,6 +5,7 @@ import { defineForwardedEffectfulSchedulingNodes } from "./dependency-runtime.js
 import { defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingOnlyAnnotationCompletionParser, getOwnParseLanes, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { getDelegatedAnnotationState, hasDelegatedAnnotationCarrier, isAnnotationWrappedInitialState, normalizeDelegatedAnnotationState, normalizeNestedDelegatedAnnotationState } from "./annotation-state.js";
 import { mergeJoinedFileSuggestions } from "./internal/joined-file-suggestion.js";
+import { captureDocParser } from "./internal/doc-metadata.js";
 import { acceptsEmptyInput, defineEmptyInputFacts, getEmptyInputFacts, multipleFacts, optionalLikeFacts, resolveEmptyStepState } from "./internal/empty-input.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
 import { combinedOptionScope, repeatedOptionScope, scopeParser } from "./short-option.js";
@@ -498,7 +499,10 @@ function optional(parser) {
 	defineKnownCompletionLookup(optionalParser, (state) => getKnownCompletion(parser, deriveOptionalInnerParseState(state, parser)));
 	const scopedOptionalParser = scopeParser(optionalParser, combinedOptionScope([parser]));
 	defineEmptyInputFacts(scopedOptionalParser, optionalLikeFacts(getEmptyInputFacts(parser), parser.initialState, completesOptionalLikeFallback(parser)));
-	return fluent(scopedOptionalParser);
+	return captureDocParser(fluent(scopedOptionalParser), {
+		kind: "optional",
+		children: [parser]
+	});
 }
 /**
 * Error type for structured error messages in {@link withDefault} default value callbacks.
@@ -756,7 +760,12 @@ function withDefault(parser, defaultValue, options) {
 	defineKnownCompletionLookup(withDefaultParser, (state) => getKnownCompletion(parser, deriveOptionalInnerParseState(state, parser)));
 	const scopedWithDefaultParser = scopeParser(withDefaultParser, combinedOptionScope([parser]));
 	defineEmptyInputFacts(scopedWithDefaultParser, optionalLikeFacts(getEmptyInputFacts(parser), parser.initialState, typeof defaultValue === "function" ? void 0 : completesOptionalLikeFallback(parser)));
-	return fluent(scopedWithDefaultParser);
+	return captureDocParser(fluent(scopedWithDefaultParser), {
+		kind: "default",
+		children: [parser],
+		defaultValue,
+		defaultMessage: options?.message
+	});
 }
 /**
 * Creates a parser that transforms the result value of another parser using
@@ -1798,7 +1807,11 @@ function multiple(parser, options = {}) {
 	})));
 	const scopedResultParser = scopeParser(resultParser, repeatedOptionScope(parser));
 	defineEmptyInputFacts(scopedResultParser, emptyInputFacts);
-	return fluent(scopedResultParser);
+	return captureDocParser(fluent(scopedResultParser), {
+		kind: "multiple",
+		children: [parser],
+		min
+	});
 }
 /**
 * Creates a parser that requires the wrapped parser to consume at least one

package/dist/primitives.cjs

@@ -8,6 +8,7 @@ const require_internal_dependency = require('./internal/dependency.cjs');
 const require_dependency_runtime = require('./dependency-runtime.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
 const require_joined_file_suggestion = require('./internal/joined-file-suggestion.cjs');
+const require_internal_doc_metadata = require('./internal/doc-metadata.cjs');
 const require_empty_input = require('./internal/empty-input.cjs');
 const require_execution_context = require('./execution-context.cjs');
 const require_usage_internals = require('./usage-internals.cjs');
@@ -801,7 +802,13 @@ function option(...args) {
 		enumerable: false
 	});
 	else require_empty_input.defineEmptyInputFacts(result, require_empty_input.failingStepFacts(valueParser == null));
-	return require_modifiers.fluent(result);
+	return require_internal_doc_metadata.captureDocParser(require_modifiers.fluent(result), {
+		kind: "leaf",
+		description: options.description,
+		valueParser,
+		choicesRequested: valueParser != null,
+		boolean: valueParser == null
+	});
 }
 /**
 * Creates a parser for command-line flags that must be explicitly provided.
@@ -991,7 +998,11 @@ function flag(...args) {
 		writable: false
 	});
 	require_empty_input.defineEmptyInputFacts(result, require_empty_input.failingStepFacts(false));
-	return require_modifiers.fluent(result);
+	return require_internal_doc_metadata.captureDocParser(require_modifiers.fluent(result), {
+		kind: "leaf",
+		description: options.description,
+		boolean: true
+	});
 }
 function normalizeNegatableFlagNameList(names) {
 	return typeof names === "string" ? [names] : names;
@@ -1404,7 +1415,12 @@ function argument(valueParser, options = {}) {
 		enumerable: false
 	});
 	else require_empty_input.defineEmptyInputFacts(result, require_empty_input.failingStepFacts(false));
-	return require_modifiers.fluent(result);
+	return require_internal_doc_metadata.captureDocParser(require_modifiers.fluent(result), {
+		kind: "leaf",
+		description: options.description,
+		valueParser,
+		choicesRequested: true
+	});
 }
 function normalizeCommandState(state) {
 	return require_annotation_state.normalizeInjectedAnnotationState(state);
@@ -1805,7 +1821,20 @@ function command(name, parser, options = {}) {
 		if (normalizeCommandState(context.state) != null) commandScope.select(context, enteredScope);
 	});
 	require_empty_input.defineEmptyInputFacts(scoped, require_empty_input.failingStepFacts(false));
-	return require_modifiers.fluent(scoped);
+	return require_internal_doc_metadata.captureDocParser(require_modifiers.fluent(scoped), {
+		kind: "command",
+		name,
+		aliases,
+		hiddenAliases,
+		showAliases,
+		showUsage,
+		hidden: options.hidden,
+		brief: options.brief,
+		description: options.description,
+		footer: options.footer,
+		usageLine: options.usageLine,
+		children: [parser]
+	});
 }
 /**
 * Creates a parser that collects unrecognized options and passes them through.

package/dist/primitives.js

@@ -8,6 +8,7 @@ import { getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDepend
 import { effectfulSchedulingNodesKey, exclusiveSourceScopeKey, includeSourceFailureChain, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, sourceCollectionExpansionKey } from "./dependency-runtime.js";
 import { getWrappedChildParseState, getWrappedChildState, isAnnotationWrappedInitialState, normalizeInjectedAnnotationState } from "./annotation-state.js";
 import { joinedFileSuggestion } from "./internal/joined-file-suggestion.js";
+import { captureDocParser } from "./internal/doc-metadata.js";
 import { UNCHANGED, defineEmptyInputFacts, failingStepFacts } from "./internal/empty-input.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
 import { extractLeadingCommandNames } from "./usage-internals.js";
@@ -801,7 +802,13 @@ function option(...args) {
 		enumerable: false
 	});
 	else defineEmptyInputFacts(result, failingStepFacts(valueParser == null));
-	return fluent(result);
+	return captureDocParser(fluent(result), {
+		kind: "leaf",
+		description: options.description,
+		valueParser,
+		choicesRequested: valueParser != null,
+		boolean: valueParser == null
+	});
 }
 /**
 * Creates a parser for command-line flags that must be explicitly provided.
@@ -991,7 +998,11 @@ function flag(...args) {
 		writable: false
 	});
 	defineEmptyInputFacts(result, failingStepFacts(false));
-	return fluent(result);
+	return captureDocParser(fluent(result), {
+		kind: "leaf",
+		description: options.description,
+		boolean: true
+	});
 }
 function normalizeNegatableFlagNameList(names) {
 	return typeof names === "string" ? [names] : names;
@@ -1404,7 +1415,12 @@ function argument(valueParser, options = {}) {
 		enumerable: false
 	});
 	else defineEmptyInputFacts(result, failingStepFacts(false));
-	return fluent(result);
+	return captureDocParser(fluent(result), {
+		kind: "leaf",
+		description: options.description,
+		valueParser,
+		choicesRequested: true
+	});
 }
 function normalizeCommandState(state) {
 	return normalizeInjectedAnnotationState(state);
@@ -1805,7 +1821,20 @@ function command(name, parser, options = {}) {
 		if (normalizeCommandState(context.state) != null) commandScope.select(context, enteredScope);
 	});
 	defineEmptyInputFacts(scoped, failingStepFacts(false));
-	return fluent(scoped);
+	return captureDocParser(fluent(scoped), {
+		kind: "command",
+		name,
+		aliases,
+		hiddenAliases,
+		showAliases,
+		showUsage,
+		hidden: options.hidden,
+		brief: options.brief,
+		description: options.description,
+		footer: options.footer,
+		usageLine: options.usageLine,
+		children: [parser]
+	});
 }
 /**
 * Creates a parser that collects unrecognized options and passes them through.