@optique/core 1.1.9 → 1.1.11

package/dist/primitives.js

@@ -6,6 +6,7 @@ import { dispatchByMode, dispatchIterableByMode, wrapForMode } from "./internal/
 import { getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDerivedValueParser, suggestWithDependency } from "./internal/dependency.js";
 import { replayDerivedParser, replayDerivedParserAsync } from "./dependency-runtime.js";
 import { getWrappedChildParseState, getWrappedChildState, isAnnotationWrappedInitialState, normalizeInjectedAnnotationState } from "./annotation-state.js";
+import { getCommandDocMetadata, withCommandDocMetadata } from "./internal/command-doc-metadata.js";
 import { defineKnownCompletion, defineOptionMatch, definePassThroughPriority, getOptionMatch, getPassThroughFailure, getPassThroughPriority } from "./internal/passthrough.js";
 import { hiddenCommandAliasesKey } from "./internal/command-alias.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
@@ -639,10 +640,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"
@@ -658,10 +659,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(", ")})`;
@@ -930,10 +931,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: {
@@ -942,10 +943,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(", ")})`;
@@ -1302,10 +1303,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"
@@ -1317,10 +1318,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()`;
@@ -1671,11 +1672,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",
@@ -1685,7 +1686,7 @@ function command(name, parser, options = {}) {
 						},
 						description: options.brief ?? options.description
 					}]
-				};
+				}, {});
 			}
 			const innerState = commandState[0] === "parsing" ? {
 				kind: "available",
@@ -1695,12 +1696,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)})`;
@@ -1901,18 +1908,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.1.9",
+  "version": "1.1.11",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -196,7 +196,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.1.9",
+    "@optique/env": "1.1.11",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",