@optique/core 1.0.12-dev.2703 → 1.0.13-dev.2743

package/dist/constructs.cjs

@@ -1,5 +1,6 @@
 const require_annotations = require('./internal/annotations.cjs');
 const require_message = require('./message.cjs');
+const require_command_doc_metadata = require('./internal/command-doc-metadata.cjs');
 const require_passthrough = require('./internal/passthrough.cjs');
 const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
@@ -1275,6 +1276,7 @@ function or(...args) {
 		},
 		suggest: createExclusiveSuggest(parsers, combinedMode),
 		getDocFragments(state, _defaultValue) {
+			let commandMetadata;
 			let brief;
 			let description;
 			let footer;
@@ -1287,18 +1289,19 @@ function or(...args) {
 					state: parserResult.next.state
 				} : { kind: "unavailable" };
 				const docFragments = parsers[index].getDocFragments(innerState, void 0);
+				commandMetadata = require_command_doc_metadata.getCommandDocMetadata(docFragments);
 				brief = docFragments.brief;
 				description = docFragments.description;
 				footer = docFragments.footer;
 				fragments = docFragments.fragments;
 			}
 			if (state.kind === "unavailable" || state.state == null) fragments = require_doc.deduplicateDocFragments(fragments);
-			return {
+			return require_command_doc_metadata.withCommandDocMetadata({
 				brief,
 				description,
 				footer,
 				fragments
-			};
+			}, commandMetadata);
 		}
 	};
 	const singleDependencyMetadata = composeExclusiveDependencyMetadata(parsers);
@@ -1501,6 +1504,7 @@ function longestMatch(...args) {
 		},
 		suggest: createExclusiveSuggest(parsers, combinedMode),
 		getDocFragments(state, _defaultValue) {
+			let commandMetadata;
 			let brief;
 			let description;
 			let footer;
@@ -1516,6 +1520,7 @@ function longestMatch(...args) {
 						kind: "available",
 						state: result.next.state
 					});
+					commandMetadata = require_command_doc_metadata.getCommandDocMetadata(docResult);
 					brief = docResult.brief;
 					description = docResult.description;
 					footer = docResult.footer;
@@ -1526,12 +1531,12 @@ function longestMatch(...args) {
 					shouldDeduplicate = true;
 				}
 			}
-			return {
+			return require_command_doc_metadata.withCommandDocMetadata({
 				brief,
 				description,
 				fragments: shouldDeduplicate ? require_doc.deduplicateDocFragments(fragments) : fragments,
 				footer
-			};
+			}, commandMetadata);
 		}
 	};
 	const multiDependencyMetadata = composeExclusiveDependencyMetadata(parsers);
@@ -2477,12 +2482,15 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			}, () => suggestObjectAsync(context, prefix, parserPairs));
 		},
 		getDocFragments(state, defaultValue) {
+			let commandMetadata;
 			const fragments = parserPairs.flatMap(([field, p]) => {
 				const fieldState = state.kind === "unavailable" ? { kind: "unavailable" } : {
 					kind: "available",
 					state: state.state[field]
 				};
-				return p.getDocFragments(fieldState, defaultValue?.[field]).fragments;
+				const docs = p.getDocFragments(fieldState, defaultValue?.[field]);
+				commandMetadata = require_command_doc_metadata.collectCommandDocMetadata(commandMetadata, docs);
+				return docs.fragments;
 			});
 			const hiddenAwareFragments = applyHiddenToDocFragments(fragments, options.hidden);
 			const entries = hiddenAwareFragments.filter((d) => d.type === "entry");
@@ -2497,10 +2505,13 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				entries
 			};
 			sections.push(section);
-			return { fragments: sections.map((s) => ({
-				...s,
-				type: "section"
-			})) };
+			return require_command_doc_metadata.withCommandDocMetadata({
+				...commandMetadata,
+				fragments: sections.map((s) => ({
+					...s,
+					type: "section"
+				}))
+			}, commandMetadata);
 		}
 	};
 	const fieldNormalizers = [];
@@ -3126,12 +3137,15 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			return require_mode_dispatch.dispatchIterableByMode(combinedMode, () => suggestTupleSync(context, prefix, syncParsers), () => suggestTupleAsync(context, prefix, parsers));
 		},
 		getDocFragments(state, defaultValue) {
+			let commandMetadata;
 			const fragments = syncParsers.flatMap((p, i) => {
 				const indexState = state.kind === "unavailable" ? { kind: "unavailable" } : {
 					kind: "available",
 					state: state.state[i]
 				};
-				return p.getDocFragments(indexState, defaultValue?.[i]).fragments;
+				const docs = p.getDocFragments(indexState, defaultValue?.[i]);
+				commandMetadata = require_command_doc_metadata.collectCommandDocMetadata(commandMetadata, docs);
+				return docs.fragments;
 			});
 			const entries = fragments.filter((d) => d.type === "entry");
 			const sections = [];
@@ -3145,10 +3159,13 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				entries
 			};
 			sections.push(section);
-			return { fragments: sections.map((s) => ({
-				...s,
-				type: "section"
-			})) };
+			return require_command_doc_metadata.withCommandDocMetadata({
+				...commandMetadata,
+				fragments: sections.map((s) => ({
+					...s,
+					type: "section"
+				}))
+			}, commandMetadata);
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			const parsersStr = parsers.length === 1 ? `[1 parser]` : `[${parsers.length} parsers]`;
@@ -4038,6 +4055,7 @@ function merge(...args) {
 			}();
 		},
 		getDocFragments(state, _defaultValue) {
+			let commandMetadata;
 			let brief;
 			let description;
 			let footer;
@@ -4055,6 +4073,7 @@ function merge(...args) {
 					state: state.state
 				};
 				const docFragments = p.getDocFragments(parserState, void 0);
+				commandMetadata = require_command_doc_metadata.collectCommandDocMetadata(commandMetadata, docFragments, true);
 				brief ??= docFragments.brief;
 				description ??= docFragments.description;
 				footer ??= docFragments.footer;
@@ -4074,7 +4093,7 @@ function merge(...args) {
 					entries
 				};
 				sections.push(labeledSection);
-				return {
+				return require_command_doc_metadata.withCommandDocMetadata({
 					brief,
 					description,
 					footer,
@@ -4082,9 +4101,9 @@ function merge(...args) {
 						...s,
 						type: "section"
 					}))
-				};
+				}, commandMetadata);
 			}
-			return {
+			return require_command_doc_metadata.withCommandDocMetadata({
 				brief,
 				description,
 				footer,
@@ -4095,7 +4114,7 @@ function merge(...args) {
 					type: "section",
 					entries
 				}]
-			};
+			}, commandMetadata);
 		}
 	};
 	require_parser.defineParseLanes(mergeParser, mergeParseLanes);
@@ -4707,12 +4726,15 @@ function concat(...parsers) {
 			}();
 		},
 		getDocFragments(state, _defaultValue) {
+			let commandMetadata;
 			const fragments = syncParsers.flatMap((p, index) => {
 				const indexState = state.kind === "unavailable" ? { kind: "unavailable" } : {
 					kind: "available",
 					state: state.state[index]
 				};
-				return p.getDocFragments(indexState, void 0).fragments;
+				const docs = p.getDocFragments(indexState, void 0);
+				commandMetadata = require_command_doc_metadata.collectCommandDocMetadata(commandMetadata, docs);
+				return docs.fragments;
 			});
 			const entries = fragments.filter((f) => f.type === "entry");
 			const sections = [];
@@ -4729,7 +4751,10 @@ function concat(...parsers) {
 				type: "section",
 				entries
 			});
-			return { fragments: result };
+			return require_command_doc_metadata.withCommandDocMetadata({
+				...commandMetadata,
+				fragments: result
+			}, commandMetadata);
 		}
 	};
 	require_parser.defineInheritedAnnotationParser(concatParser);
@@ -4764,7 +4789,8 @@ function group(label, parser, options = {}) {
 			return parser.suggest(context, prefix);
 		},
 		getDocFragments: (state, defaultValue) => {
-			const { brief, description, footer, fragments } = parser.getDocFragments(state, defaultValue);
+			const docs = parser.getDocFragments(state, defaultValue);
+			const { brief, description, footer, fragments } = docs;
 			const hiddenAwareFragments = applyHiddenToDocFragments(fragments, options.hidden);
 			const allEntries = [];
 			const titledSections = [];
@@ -4787,7 +4813,7 @@ function group(label, parser, options = {}) {
 				title: label,
 				entries: allEntries
 			} : { entries: allEntries };
-			return {
+			return require_command_doc_metadata.withCommandDocMetadata({
 				brief,
 				description,
 				footer,
@@ -4798,7 +4824,7 @@ function group(label, parser, options = {}) {
 					type: "section",
 					...labeledSection
 				}]
-			};
+			}, require_command_doc_metadata.getCommandDocMetadata(docs));
 		}
 	};
 	require_parser.defineParseLanes(groupParser, require_parser.getOwnParseLanes(parser));

package/dist/constructs.js

@@ -1,5 +1,6 @@
 import { annotateFreshArray, getAnnotations, inheritAnnotations } from "./internal/annotations.js";
 import { message, optionName, text, values } from "./message.js";
+import { collectCommandDocMetadata, getCommandDocMetadata, withCommandDocMetadata } from "./internal/command-doc-metadata.js";
 import { combineOptionMatches, combinePassThroughPriorities, defineOptionMatch, definePassThroughPriority, delegateKnownCompletion, getKnownCompletion, getOptionMatch, getPassThroughFailureHint, getPassThroughPriority, hasPassThroughUsage, matchesOptionToken, retainConsumingFailure, retainConsumingFailureHint, withPassThroughFailure } from "./internal/passthrough.js";
 import { validateLabel } from "./validate.js";
 import { extractArgumentMetavars, extractCommandNames, extractOptionNames, isDocHidden, mergeHidden } from "./usage.js";
@@ -1275,6 +1276,7 @@ function or(...args) {
 		},
 		suggest: createExclusiveSuggest(parsers, combinedMode),
 		getDocFragments(state, _defaultValue) {
+			let commandMetadata;
 			let brief;
 			let description;
 			let footer;
@@ -1287,18 +1289,19 @@ function or(...args) {
 					state: parserResult.next.state
 				} : { kind: "unavailable" };
 				const docFragments = parsers[index].getDocFragments(innerState, void 0);
+				commandMetadata = getCommandDocMetadata(docFragments);
 				brief = docFragments.brief;
 				description = docFragments.description;
 				footer = docFragments.footer;
 				fragments = docFragments.fragments;
 			}
 			if (state.kind === "unavailable" || state.state == null) fragments = deduplicateDocFragments(fragments);
-			return {
+			return withCommandDocMetadata({
 				brief,
 				description,
 				footer,
 				fragments
-			};
+			}, commandMetadata);
 		}
 	};
 	const singleDependencyMetadata = composeExclusiveDependencyMetadata(parsers);
@@ -1501,6 +1504,7 @@ function longestMatch(...args) {
 		},
 		suggest: createExclusiveSuggest(parsers, combinedMode),
 		getDocFragments(state, _defaultValue) {
+			let commandMetadata;
 			let brief;
 			let description;
 			let footer;
@@ -1516,6 +1520,7 @@ function longestMatch(...args) {
 						kind: "available",
 						state: result.next.state
 					});
+					commandMetadata = getCommandDocMetadata(docResult);
 					brief = docResult.brief;
 					description = docResult.description;
 					footer = docResult.footer;
@@ -1526,12 +1531,12 @@ function longestMatch(...args) {
 					shouldDeduplicate = true;
 				}
 			}
-			return {
+			return withCommandDocMetadata({
 				brief,
 				description,
 				fragments: shouldDeduplicate ? deduplicateDocFragments(fragments) : fragments,
 				footer
-			};
+			}, commandMetadata);
 		}
 	};
 	const multiDependencyMetadata = composeExclusiveDependencyMetadata(parsers);
@@ -2477,12 +2482,15 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			}, () => suggestObjectAsync(context, prefix, parserPairs));
 		},
 		getDocFragments(state, defaultValue) {
+			let commandMetadata;
 			const fragments = parserPairs.flatMap(([field, p]) => {
 				const fieldState = state.kind === "unavailable" ? { kind: "unavailable" } : {
 					kind: "available",
 					state: state.state[field]
 				};
-				return p.getDocFragments(fieldState, defaultValue?.[field]).fragments;
+				const docs = p.getDocFragments(fieldState, defaultValue?.[field]);
+				commandMetadata = collectCommandDocMetadata(commandMetadata, docs);
+				return docs.fragments;
 			});
 			const hiddenAwareFragments = applyHiddenToDocFragments(fragments, options.hidden);
 			const entries = hiddenAwareFragments.filter((d) => d.type === "entry");
@@ -2497,10 +2505,13 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				entries
 			};
 			sections.push(section);
-			return { fragments: sections.map((s) => ({
-				...s,
-				type: "section"
-			})) };
+			return withCommandDocMetadata({
+				...commandMetadata,
+				fragments: sections.map((s) => ({
+					...s,
+					type: "section"
+				}))
+			}, commandMetadata);
 		}
 	};
 	const fieldNormalizers = [];
@@ -3126,12 +3137,15 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			return dispatchIterableByMode(combinedMode, () => suggestTupleSync(context, prefix, syncParsers), () => suggestTupleAsync(context, prefix, parsers));
 		},
 		getDocFragments(state, defaultValue) {
+			let commandMetadata;
 			const fragments = syncParsers.flatMap((p, i) => {
 				const indexState = state.kind === "unavailable" ? { kind: "unavailable" } : {
 					kind: "available",
 					state: state.state[i]
 				};
-				return p.getDocFragments(indexState, defaultValue?.[i]).fragments;
+				const docs = p.getDocFragments(indexState, defaultValue?.[i]);
+				commandMetadata = collectCommandDocMetadata(commandMetadata, docs);
+				return docs.fragments;
 			});
 			const entries = fragments.filter((d) => d.type === "entry");
 			const sections = [];
@@ -3145,10 +3159,13 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				entries
 			};
 			sections.push(section);
-			return { fragments: sections.map((s) => ({
-				...s,
-				type: "section"
-			})) };
+			return withCommandDocMetadata({
+				...commandMetadata,
+				fragments: sections.map((s) => ({
+					...s,
+					type: "section"
+				}))
+			}, commandMetadata);
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			const parsersStr = parsers.length === 1 ? `[1 parser]` : `[${parsers.length} parsers]`;
@@ -4038,6 +4055,7 @@ function merge(...args) {
 			}();
 		},
 		getDocFragments(state, _defaultValue) {
+			let commandMetadata;
 			let brief;
 			let description;
 			let footer;
@@ -4055,6 +4073,7 @@ function merge(...args) {
 					state: state.state
 				};
 				const docFragments = p.getDocFragments(parserState, void 0);
+				commandMetadata = collectCommandDocMetadata(commandMetadata, docFragments, true);
 				brief ??= docFragments.brief;
 				description ??= docFragments.description;
 				footer ??= docFragments.footer;
@@ -4074,7 +4093,7 @@ function merge(...args) {
 					entries
 				};
 				sections.push(labeledSection);
-				return {
+				return withCommandDocMetadata({
 					brief,
 					description,
 					footer,
@@ -4082,9 +4101,9 @@ function merge(...args) {
 						...s,
 						type: "section"
 					}))
-				};
+				}, commandMetadata);
 			}
-			return {
+			return withCommandDocMetadata({
 				brief,
 				description,
 				footer,
@@ -4095,7 +4114,7 @@ function merge(...args) {
 					type: "section",
 					entries
 				}]
-			};
+			}, commandMetadata);
 		}
 	};
 	defineParseLanes(mergeParser, mergeParseLanes);
@@ -4707,12 +4726,15 @@ function concat(...parsers) {
 			}();
 		},
 		getDocFragments(state, _defaultValue) {
+			let commandMetadata;
 			const fragments = syncParsers.flatMap((p, index) => {
 				const indexState = state.kind === "unavailable" ? { kind: "unavailable" } : {
 					kind: "available",
 					state: state.state[index]
 				};
-				return p.getDocFragments(indexState, void 0).fragments;
+				const docs = p.getDocFragments(indexState, void 0);
+				commandMetadata = collectCommandDocMetadata(commandMetadata, docs);
+				return docs.fragments;
 			});
 			const entries = fragments.filter((f) => f.type === "entry");
 			const sections = [];
@@ -4729,7 +4751,10 @@ function concat(...parsers) {
 				type: "section",
 				entries
 			});
-			return { fragments: result };
+			return withCommandDocMetadata({
+				...commandMetadata,
+				fragments: result
+			}, commandMetadata);
 		}
 	};
 	defineInheritedAnnotationParser(concatParser);
@@ -4764,7 +4789,8 @@ function group(label, parser, options = {}) {
 			return parser.suggest(context, prefix);
 		},
 		getDocFragments: (state, defaultValue) => {
-			const { brief, description, footer, fragments } = parser.getDocFragments(state, defaultValue);
+			const docs = parser.getDocFragments(state, defaultValue);
+			const { brief, description, footer, fragments } = docs;
 			const hiddenAwareFragments = applyHiddenToDocFragments(fragments, options.hidden);
 			const allEntries = [];
 			const titledSections = [];
@@ -4787,7 +4813,7 @@ function group(label, parser, options = {}) {
 				title: label,
 				entries: allEntries
 			} : { entries: allEntries };
-			return {
+			return withCommandDocMetadata({
 				brief,
 				description,
 				footer,
@@ -4798,7 +4824,7 @@ function group(label, parser, options = {}) {
 					type: "section",
 					...labeledSection
 				}]
-			};
+			}, getCommandDocMetadata(docs));
 		}
 	};
 	defineParseLanes(groupParser, getOwnParseLanes(parser));

package/dist/internal/command-doc-metadata.cjs

@@ -0,0 +1,90 @@
+
+//#region src/internal/command-doc-metadata.ts
+function withOrigin(metadata, origin) {
+	const result = { ...metadata };
+	Object.defineProperty(result, "origin", {
+		value: origin,
+		enumerable: false
+	});
+	return result;
+}
+const commandDocMetadata = Symbol.for("@optique/core/commandDocMetadata");
+const commandDocCarrier = Symbol.for("@optique/core/commandDocMetadataCarrier");
+/**
+* Reads effective page metadata, including custom collection-level fields.
+* @param docs The child's documentation.
+* @returns Its selected-command metadata, if any.
+*/
+function getCommandDocMetadata(docs) {
+	const carrier = docs.fragments[commandDocCarrier];
+	if (carrier != null) {
+		const brief = docs.brief === carrier.brief ? carrier.metadata.brief : docs.brief;
+		const origin = carrier.metadata.origin ?? "entry";
+		const customPage = origin === "entry" && (docs.brief !== carrier.brief || docs.footer !== carrier.footer);
+		const description = origin === "entry" && !customPage || docs.description === carrier.description ? carrier.metadata.description : docs.description;
+		const footer = docs.footer === carrier.footer ? carrier.metadata.footer : docs.footer;
+		return withOrigin({
+			...brief == null ? {} : { brief },
+			...description == null ? {} : { description },
+			...footer == null ? {} : { footer }
+		}, customPage ? "custom" : origin);
+	}
+	const metadata = docs[commandDocMetadata];
+	if (metadata != null) return metadata;
+	return docs.brief != null || docs.description != null || docs.footer != null ? withOrigin({
+		brief: docs.brief,
+		description: docs.description,
+		footer: docs.footer
+	}, "custom") : void 0;
+}
+/**
+* Preserves selected-command metadata when rebuilding documentation fragments.
+* @param docs The rebuilt documentation.
+* @param metadata The selected-command metadata to preserve.
+* @returns Documentation with the internal metadata attached.
+*/
+function withCommandDocMetadata(docs, metadata) {
+	if (metadata == null) return docs;
+	metadata = withOrigin(metadata, metadata.origin ?? "entry");
+	const fragments = [...docs.fragments];
+	Object.defineProperty(fragments, commandDocCarrier, { value: {
+		metadata,
+		brief: docs.brief,
+		description: docs.description,
+		footer: docs.footer
+	} });
+	const result = {
+		...docs,
+		fragments
+	};
+	Object.defineProperty(result, commandDocMetadata, { value: metadata });
+	return result;
+}
+/**
+* Collects selected-command metadata in documentation traversal order.
+* @param current Metadata from earlier children.
+* @param docs The next child's documentation.
+* @param includeCustom Whether to retain custom page fields inside merge().
+* @returns The first defined value from children with the same origin.
+*/
+function collectCommandDocMetadata(current, docs, includeCustom = false) {
+	const next = getCommandDocMetadata(docs);
+	if (next == null) return current;
+	const origin = next.origin ?? "entry";
+	if (origin === "entry" || origin === "custom" && !includeCustom) return current ?? withOrigin({}, "entry");
+	if (current?.origin === "command" && origin !== "command") return current;
+	if (current?.origin !== origin) current = void 0;
+	const brief = current?.brief ?? next.brief;
+	const description = current?.description ?? next.description;
+	const footer = current?.footer ?? next.footer;
+	return withOrigin({
+		...brief == null ? {} : { brief },
+		...description == null ? {} : { description },
+		...footer == null ? {} : { footer }
+	}, origin);
+}
+
+//#endregion
+exports.collectCommandDocMetadata = collectCommandDocMetadata;
+exports.getCommandDocMetadata = getCommandDocMetadata;
+exports.withCommandDocMetadata = withCommandDocMetadata;

package/dist/internal/command-doc-metadata.js

@@ -0,0 +1,87 @@
+//#region src/internal/command-doc-metadata.ts
+function withOrigin(metadata, origin) {
+	const result = { ...metadata };
+	Object.defineProperty(result, "origin", {
+		value: origin,
+		enumerable: false
+	});
+	return result;
+}
+const commandDocMetadata = Symbol.for("@optique/core/commandDocMetadata");
+const commandDocCarrier = Symbol.for("@optique/core/commandDocMetadataCarrier");
+/**
+* Reads effective page metadata, including custom collection-level fields.
+* @param docs The child's documentation.
+* @returns Its selected-command metadata, if any.
+*/
+function getCommandDocMetadata(docs) {
+	const carrier = docs.fragments[commandDocCarrier];
+	if (carrier != null) {
+		const brief = docs.brief === carrier.brief ? carrier.metadata.brief : docs.brief;
+		const origin = carrier.metadata.origin ?? "entry";
+		const customPage = origin === "entry" && (docs.brief !== carrier.brief || docs.footer !== carrier.footer);
+		const description = origin === "entry" && !customPage || docs.description === carrier.description ? carrier.metadata.description : docs.description;
+		const footer = docs.footer === carrier.footer ? carrier.metadata.footer : docs.footer;
+		return withOrigin({
+			...brief == null ? {} : { brief },
+			...description == null ? {} : { description },
+			...footer == null ? {} : { footer }
+		}, customPage ? "custom" : origin);
+	}
+	const metadata = docs[commandDocMetadata];
+	if (metadata != null) return metadata;
+	return docs.brief != null || docs.description != null || docs.footer != null ? withOrigin({
+		brief: docs.brief,
+		description: docs.description,
+		footer: docs.footer
+	}, "custom") : void 0;
+}
+/**
+* Preserves selected-command metadata when rebuilding documentation fragments.
+* @param docs The rebuilt documentation.
+* @param metadata The selected-command metadata to preserve.
+* @returns Documentation with the internal metadata attached.
+*/
+function withCommandDocMetadata(docs, metadata) {
+	if (metadata == null) return docs;
+	metadata = withOrigin(metadata, metadata.origin ?? "entry");
+	const fragments = [...docs.fragments];
+	Object.defineProperty(fragments, commandDocCarrier, { value: {
+		metadata,
+		brief: docs.brief,
+		description: docs.description,
+		footer: docs.footer
+	} });
+	const result = {
+		...docs,
+		fragments
+	};
+	Object.defineProperty(result, commandDocMetadata, { value: metadata });
+	return result;
+}
+/**
+* Collects selected-command metadata in documentation traversal order.
+* @param current Metadata from earlier children.
+* @param docs The next child's documentation.
+* @param includeCustom Whether to retain custom page fields inside merge().
+* @returns The first defined value from children with the same origin.
+*/
+function collectCommandDocMetadata(current, docs, includeCustom = false) {
+	const next = getCommandDocMetadata(docs);
+	if (next == null) return current;
+	const origin = next.origin ?? "entry";
+	if (origin === "entry" || origin === "custom" && !includeCustom) return current ?? withOrigin({}, "entry");
+	if (current?.origin === "command" && origin !== "command") return current;
+	if (current?.origin !== origin) current = void 0;
+	const brief = current?.brief ?? next.brief;
+	const description = current?.description ?? next.description;
+	const footer = current?.footer ?? next.footer;
+	return withOrigin({
+		...brief == null ? {} : { brief },
+		...description == null ? {} : { description },
+		...footer == null ? {} : { footer }
+	}, origin);
+}
+
+//#endregion
+export { collectCommandDocMetadata, getCommandDocMetadata, withCommandDocMetadata };

package/dist/modifiers.cjs

@@ -1,5 +1,6 @@
 const require_annotations = require('./internal/annotations.cjs');
 const require_message = require('./message.cjs');
+const require_command_doc_metadata = require('./internal/command-doc-metadata.cjs');
 const require_passthrough = require('./internal/passthrough.cjs');
 const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 const require_parser = require('./internal/parser.cjs');
@@ -621,10 +622,10 @@ function withDefault(parser, defaultValue, options) {
 					};
 					return fragment;
 				});
-				return {
+				return require_command_doc_metadata.withCommandDocMetadata({
 					...fragments,
 					fragments: modifiedFragments
-				};
+				}, require_command_doc_metadata.getCommandDocMetadata(fragments));
 			}
 			return fragments;
 		}

package/dist/modifiers.js

@@ -1,5 +1,6 @@
 import { annotateFreshArray, annotationKey, getAnnotations, inheritAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./internal/annotations.js";
 import { formatMessage, message, text } from "./message.js";
+import { getCommandDocMetadata, withCommandDocMetadata } from "./internal/command-doc-metadata.js";
 import { defineKnownCompletionLookup, defineOptionMatch, definePassThroughPriority, getKnownCompletion, getOptionMatch, getPassThroughPriority } from "./internal/passthrough.js";
 import { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode } from "./internal/mode-dispatch.js";
 import { defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingOnlyAnnotationCompletionParser, getOwnParseLanes, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
@@ -621,10 +622,10 @@ function withDefault(parser, defaultValue, options) {
 					};
 					return fragment;
 				});
-				return {
+				return withCommandDocMetadata({
 					...fragments,
 					fragments: modifiedFragments
-				};
+				}, getCommandDocMetadata(fragments));
 			}
 			return fragments;
 		}

package/dist/primitives.cjs

@@ -1,5 +1,6 @@
 const require_annotations = require('./internal/annotations.cjs');
 const require_message = require('./message.cjs');
+const require_command_doc_metadata = require('./internal/command-doc-metadata.cjs');
 const require_passthrough = require('./internal/passthrough.cjs');
 const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
@@ -626,10 +627,10 @@ function option(...args) {
 			return suggestOptionSync(optionNames$1, valueParser, require_usage.isSuggestionHidden(options.hidden), options.description, context, prefix);
 		},
 		getDocFragments(_state, defaultValue) {
-			if (require_usage.isDocHidden(options.hidden)) return {
+			if (require_usage.isDocHidden(options.hidden)) return require_command_doc_metadata.withCommandDocMetadata({
 				fragments: [],
 				description: options.description
-			};
+			}, {});
 			const choicesMessage = valueParser?.choices != null && valueParser.choices.length > 0 ? require_message.valueSet(valueParser.choices.map((c) => valueParser.format(c)), {
 				fallback: "",
 				type: "unit"
@@ -645,10 +646,10 @@ function option(...args) {
 				default: defaultValue != null && valueParser != null ? require_message.message`${valueParser.format(defaultValue)}` : void 0,
 				choices: choicesMessage
 			}];
-			return {
+			return require_command_doc_metadata.withCommandDocMetadata({
 				fragments,
 				description: options.description
-			};
+			}, {});
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			return `option(${optionNames$1.map((o) => JSON.stringify(o)).join(", ")})`;
@@ -913,10 +914,10 @@ function flag(...args) {
 			return suggestions;
 		},
 		getDocFragments(_state, _defaultValue) {
-			if (require_usage.isDocHidden(options.hidden)) return {
+			if (require_usage.isDocHidden(options.hidden)) return require_command_doc_metadata.withCommandDocMetadata({
 				fragments: [],
 				description: options.description
-			};
+			}, {});
 			const fragments = [{
 				type: "entry",
 				term: {
@@ -925,10 +926,10 @@ function flag(...args) {
 				},
 				description: options.description
 			}];
-			return {
+			return require_command_doc_metadata.withCommandDocMetadata({
 				fragments,
 				description: options.description
-			};
+			}, {});
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			return `flag(${optionNames$1.map((o) => JSON.stringify(o)).join(", ")})`;
@@ -1064,10 +1065,10 @@ function argument(valueParser, options = {}) {
 			return suggestArgumentSync(valueParser, require_usage.isSuggestionHidden(options.hidden), prefix, context.dependencyRegistry, context.exec);
 		},
 		getDocFragments(_state, defaultValue) {
-			if (require_usage.isDocHidden(options.hidden)) return {
+			if (require_usage.isDocHidden(options.hidden)) return require_command_doc_metadata.withCommandDocMetadata({
 				fragments: [],
 				description: options.description
-			};
+			}, {});
 			const choicesMessage = valueParser.choices != null && valueParser.choices.length > 0 ? require_message.valueSet(valueParser.choices.map((c) => valueParser.format(c)), {
 				fallback: "",
 				type: "unit"
@@ -1079,10 +1080,10 @@ function argument(valueParser, options = {}) {
 				default: defaultValue == null ? void 0 : require_message.message`${valueParser.format(defaultValue)}`,
 				choices: choicesMessage
 			}];
-			return {
+			return require_command_doc_metadata.withCommandDocMetadata({
 				fragments,
 				description: options.description
-			};
+			}, {});
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			return `argument()`;
@@ -1392,11 +1393,11 @@ function command(name, parser, options = {}) {
 		getDocFragments(state, defaultValue) {
 			const commandState = state.kind === "available" ? normalizeCommandState(state.state) : void 0;
 			if (state.kind === "unavailable" || typeof commandState === "undefined") {
-				if (require_usage.isDocHidden(options.hidden)) return {
+				if (require_usage.isDocHidden(options.hidden)) return require_command_doc_metadata.withCommandDocMetadata({
 					fragments: [],
 					description: options.description
-				};
-				return {
+				}, {});
+				return require_command_doc_metadata.withCommandDocMetadata({
 					description: options.description,
 					fragments: [{
 						type: "entry",
@@ -1406,7 +1407,7 @@ function command(name, parser, options = {}) {
 						},
 						description: options.brief ?? options.description
 					}]
-				};
+				}, {});
 			}
 			const innerState = commandState[0] === "parsing" ? {
 				kind: "available",
@@ -1416,12 +1417,18 @@ function command(name, parser, options = {}) {
 				state: getCommandChildState(state.state, parser.initialState, parser)
 			};
 			const innerFragments = parser.getDocFragments(innerState, defaultValue);
-			return {
+			const innerMetadata = require_command_doc_metadata.getCommandDocMetadata(innerFragments) ?? innerFragments;
+			return require_command_doc_metadata.withCommandDocMetadata({
 				...innerFragments,
 				brief: innerFragments.brief ?? options.brief,
 				description: innerFragments.description ?? options.description,
 				footer: innerFragments.footer ?? options.footer
-			};
+			}, {
+				origin: "command",
+				brief: innerMetadata?.brief ?? options.brief,
+				description: innerMetadata?.description ?? options.description,
+				footer: innerMetadata?.footer ?? options.footer
+			});
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			return `command(${JSON.stringify(name)})`;
@@ -1619,18 +1626,18 @@ function passThrough(options = {}) {
 			return [];
 		},
 		getDocFragments(_state, _defaultValue) {
-			if (require_usage.isDocHidden(options.hidden)) return {
+			if (require_usage.isDocHidden(options.hidden)) return require_command_doc_metadata.withCommandDocMetadata({
 				fragments: [],
 				description: options.description
-			};
-			return {
+			}, {});
+			return require_command_doc_metadata.withCommandDocMetadata({
 				fragments: [{
 					type: "entry",
 					term: { type: "passthrough" },
 					description: options.description
 				}],
 				description: options.description
-			};
+			}, {});
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			return `passThrough(${format})`;

package/dist/primitives.js

@@ -1,5 +1,6 @@
 import { annotateFreshArray, getAnnotations } from "./internal/annotations.js";
 import { message, metavar, optionName, optionNames, text, valueSet } from "./message.js";
+import { getCommandDocMetadata, withCommandDocMetadata } from "./internal/command-doc-metadata.js";
 import { defineKnownCompletion, defineOptionMatch, definePassThroughPriority, getOptionMatch, getPassThroughFailure, getPassThroughPriority } from "./internal/passthrough.js";
 import { validateCommandNames, validateOptionNames } from "./validate.js";
 import { extractOptionNames, isDocHidden, isSuggestionHidden } from "./usage.js";
@@ -626,10 +627,10 @@ function option(...args) {
 			return suggestOptionSync(optionNames$1, valueParser, isSuggestionHidden(options.hidden), options.description, context, prefix);
 		},
 		getDocFragments(_state, defaultValue) {
-			if (isDocHidden(options.hidden)) return {
+			if (isDocHidden(options.hidden)) return withCommandDocMetadata({
 				fragments: [],
 				description: options.description
-			};
+			}, {});
 			const choicesMessage = valueParser?.choices != null && valueParser.choices.length > 0 ? valueSet(valueParser.choices.map((c) => valueParser.format(c)), {
 				fallback: "",
 				type: "unit"
@@ -645,10 +646,10 @@ function option(...args) {
 				default: defaultValue != null && valueParser != null ? message`${valueParser.format(defaultValue)}` : void 0,
 				choices: choicesMessage
 			}];
-			return {
+			return withCommandDocMetadata({
 				fragments,
 				description: options.description
-			};
+			}, {});
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			return `option(${optionNames$1.map((o) => JSON.stringify(o)).join(", ")})`;
@@ -913,10 +914,10 @@ function flag(...args) {
 			return suggestions;
 		},
 		getDocFragments(_state, _defaultValue) {
-			if (isDocHidden(options.hidden)) return {
+			if (isDocHidden(options.hidden)) return withCommandDocMetadata({
 				fragments: [],
 				description: options.description
-			};
+			}, {});
 			const fragments = [{
 				type: "entry",
 				term: {
@@ -925,10 +926,10 @@ function flag(...args) {
 				},
 				description: options.description
 			}];
-			return {
+			return withCommandDocMetadata({
 				fragments,
 				description: options.description
-			};
+			}, {});
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			return `flag(${optionNames$1.map((o) => JSON.stringify(o)).join(", ")})`;
@@ -1064,10 +1065,10 @@ function argument(valueParser, options = {}) {
 			return suggestArgumentSync(valueParser, isSuggestionHidden(options.hidden), prefix, context.dependencyRegistry, context.exec);
 		},
 		getDocFragments(_state, defaultValue) {
-			if (isDocHidden(options.hidden)) return {
+			if (isDocHidden(options.hidden)) return withCommandDocMetadata({
 				fragments: [],
 				description: options.description
-			};
+			}, {});
 			const choicesMessage = valueParser.choices != null && valueParser.choices.length > 0 ? valueSet(valueParser.choices.map((c) => valueParser.format(c)), {
 				fallback: "",
 				type: "unit"
@@ -1079,10 +1080,10 @@ function argument(valueParser, options = {}) {
 				default: defaultValue == null ? void 0 : message`${valueParser.format(defaultValue)}`,
 				choices: choicesMessage
 			}];
-			return {
+			return withCommandDocMetadata({
 				fragments,
 				description: options.description
-			};
+			}, {});
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			return `argument()`;
@@ -1392,11 +1393,11 @@ function command(name, parser, options = {}) {
 		getDocFragments(state, defaultValue) {
 			const commandState = state.kind === "available" ? normalizeCommandState(state.state) : void 0;
 			if (state.kind === "unavailable" || typeof commandState === "undefined") {
-				if (isDocHidden(options.hidden)) return {
+				if (isDocHidden(options.hidden)) return withCommandDocMetadata({
 					fragments: [],
 					description: options.description
-				};
-				return {
+				}, {});
+				return withCommandDocMetadata({
 					description: options.description,
 					fragments: [{
 						type: "entry",
@@ -1406,7 +1407,7 @@ function command(name, parser, options = {}) {
 						},
 						description: options.brief ?? options.description
 					}]
-				};
+				}, {});
 			}
 			const innerState = commandState[0] === "parsing" ? {
 				kind: "available",
@@ -1416,12 +1417,18 @@ function command(name, parser, options = {}) {
 				state: getCommandChildState(state.state, parser.initialState, parser)
 			};
 			const innerFragments = parser.getDocFragments(innerState, defaultValue);
-			return {
+			const innerMetadata = getCommandDocMetadata(innerFragments) ?? innerFragments;
+			return withCommandDocMetadata({
 				...innerFragments,
 				brief: innerFragments.brief ?? options.brief,
 				description: innerFragments.description ?? options.description,
 				footer: innerFragments.footer ?? options.footer
-			};
+			}, {
+				origin: "command",
+				brief: innerMetadata?.brief ?? options.brief,
+				description: innerMetadata?.description ?? options.description,
+				footer: innerMetadata?.footer ?? options.footer
+			});
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			return `command(${JSON.stringify(name)})`;
@@ -1619,18 +1626,18 @@ function passThrough(options = {}) {
 			return [];
 		},
 		getDocFragments(_state, _defaultValue) {
-			if (isDocHidden(options.hidden)) return {
+			if (isDocHidden(options.hidden)) return withCommandDocMetadata({
 				fragments: [],
 				description: options.description
-			};
-			return {
+			}, {});
+			return withCommandDocMetadata({
 				fragments: [{
 					type: "entry",
 					term: { type: "passthrough" },
 					description: options.description
 				}],
 				description: options.description
-			};
+			}, {});
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			return `passThrough(${format})`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.12-dev.2703",
+  "version": "1.0.13-dev.2743",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",