@optique/core 1.4.0-dev.2731 → 1.4.0-dev.2737

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

@@ -0,0 +1,168 @@
+
+//#region src/internal/command-doc-policy.ts
+const policyKey = Symbol("commandDocPolicy");
+const barePolicyKey = Symbol("bareCommandDocPolicy");
+function policy(exec) {
+	return exec?.[policyKey];
+}
+function samePath(a, b) {
+	return a.length === b.length && a.every((part, i) => part === b[i]);
+}
+/**
+* Enables command policy tracking for document generation only.
+* @param exec The initial execution context.
+* @returns A context with an empty immutable policy trace.
+* @internal
+* @since 1.4.0
+*/
+function trackCommandDocPolicy(exec) {
+	return {
+		...exec,
+		[policyKey]: { records: [] }
+	};
+}
+/**
+* Records a successfully matched command occurrence.
+* @param exec The command's execution context.
+* @param id The constructor identity.
+* @param showUsage The declared command policy.
+* @returns A new context when tracking is enabled, otherwise the original.
+* @internal
+* @since 1.4.0
+*/
+function matchCommandDocPolicy(exec, id, showUsage) {
+	const current = policy(exec);
+	if (exec == null || current == null) return exec;
+	const scope = {
+		id,
+		path: [...exec.path],
+		parent: current.active,
+		showUsage
+	};
+	return {
+		...exec,
+		[policyKey]: {
+			...current,
+			records: [...current.records, scope]
+		}
+	};
+}
+/**
+* Enters the actual parent command while delegating to its inner parser.
+* @param exec The context before appending the inner command path.
+* @param id The command constructor identity.
+* @returns A child context with the matching occurrence as active scope.
+* @internal
+* @since 1.4.0
+*/
+function enterCommandDocPolicy(exec, id) {
+	const current = policy(exec);
+	if (exec == null || current == null) return exec;
+	const active = current.records.findLast((scope) => scope.id === id && samePath(scope.path, exec.path));
+	return {
+		...exec,
+		[policyKey]: {
+			...current,
+			active
+		}
+	};
+}
+/**
+* Transfers the selected child's policy and restores the caller's scope.
+* Empty child records deliberately replace previous records.
+* @param parent The caller's context.
+* @param child The selected child's context.
+* @param merged The otherwise merged context.
+* @returns The merged context with document policy forwarding.
+* @internal
+* @since 1.4.0
+*/
+function mergeCommandDocPolicy(parent, child, merged) {
+	const parentPolicy = policy(parent);
+	const childPolicy = policy(child);
+	if (parentPolicy == null && childPolicy == null) return merged;
+	return {
+		...merged,
+		[policyKey]: {
+			active: parentPolicy?.active,
+			records: childPolicy?.records ?? []
+		}
+	};
+}
+/**
+* Removes an abandoned parser branch from a speculative context copy.
+* @param exec The context before trying a replacement branch.
+* @param path The structural path of the abandoned branch.
+* @returns A context containing only retained scope occurrences.
+* @internal
+* @since 1.4.0
+*/
+function withoutCommandDocPolicySubtree(exec, path) {
+	const current = policy(exec);
+	if (exec == null || current == null) return exec;
+	const retained = /* @__PURE__ */ new Set();
+	const records = current.records.filter((scope) => {
+		const inside = scope.path.length >= path.length && path.every((part, i) => part === scope.path[i]);
+		if (inside || scope.parent != null && !retained.has(scope.parent)) return false;
+		retained.add(scope);
+		return true;
+	});
+	let active = current.active;
+	while (active != null && !retained.has(active)) active = active.parent;
+	return {
+		...exec,
+		[policyKey]: {
+			active,
+			records
+		}
+	};
+}
+/**
+* Resolves the selected command's nearest explicit ancestor policy.
+* @param exec The final successful document parsing context.
+* @returns A command default, or undefined when no selected command sets one.
+* @internal
+* @since 1.4.0
+*/
+function getCommandDocPolicy(exec) {
+	let scope = policy(exec)?.records.at(-1);
+	while (scope != null) {
+		if (scope.showUsage != null) return scope.showUsage;
+		scope = scope.parent;
+	}
+	return void 0;
+}
+/**
+* Stores a bare command's static default, preserved by transparent spreads.
+* @param parser The newly constructed command parser.
+* @param showUsage Its declared policy.
+* @internal
+* @since 1.4.0
+*/
+function defineBareCommandDocPolicy(parser, showUsage) {
+	Object.defineProperty(parser, barePolicyKey, {
+		value: showUsage,
+		enumerable: true
+	});
+}
+/**
+* Reads static policy after the existing bare-command brand check.
+* @param parser The branded command parser.
+* @returns Its declared policy, or undefined.
+* @internal
+* @since 1.4.0
+*/
+function getBareCommandDocPolicy(parser) {
+	const value = Reflect.get(parser, barePolicyKey);
+	return typeof value === "boolean" ? value : void 0;
+}
+
+//#endregion
+exports.defineBareCommandDocPolicy = defineBareCommandDocPolicy;
+exports.enterCommandDocPolicy = enterCommandDocPolicy;
+exports.getBareCommandDocPolicy = getBareCommandDocPolicy;
+exports.getCommandDocPolicy = getCommandDocPolicy;
+exports.matchCommandDocPolicy = matchCommandDocPolicy;
+exports.mergeCommandDocPolicy = mergeCommandDocPolicy;
+exports.trackCommandDocPolicy = trackCommandDocPolicy;
+exports.withoutCommandDocPolicySubtree = withoutCommandDocPolicySubtree;

package/dist/internal/command-doc-policy.d.cts

@@ -0,0 +1,77 @@
+import { ExecutionContext } from "./parser.cjs";
+
+//#region src/internal/command-doc-policy.d.ts
+
+/**
+ * Enables command policy tracking for document generation only.
+ * @param exec The initial execution context.
+ * @returns A context with an empty immutable policy trace.
+ * @internal
+ * @since 1.4.0
+ */
+declare function trackCommandDocPolicy(exec: ExecutionContext): ExecutionContext;
+/**
+ * Records a successfully matched command occurrence.
+ * @param exec The command's execution context.
+ * @param id The constructor identity.
+ * @param showUsage The declared command policy.
+ * @returns A new context when tracking is enabled, otherwise the original.
+ * @internal
+ * @since 1.4.0
+ */
+declare function matchCommandDocPolicy(exec: ExecutionContext | undefined, id: symbol, showUsage: boolean | undefined): ExecutionContext | undefined;
+/**
+ * Enters the actual parent command while delegating to its inner parser.
+ * @param exec The context before appending the inner command path.
+ * @param id The command constructor identity.
+ * @returns A child context with the matching occurrence as active scope.
+ * @internal
+ * @since 1.4.0
+ */
+declare function enterCommandDocPolicy(exec: ExecutionContext | undefined, id: symbol): ExecutionContext | undefined;
+/**
+ * Transfers the selected child's policy and restores the caller's scope.
+ * Empty child records deliberately replace previous records.
+ * @param parent The caller's context.
+ * @param child The selected child's context.
+ * @param merged The otherwise merged context.
+ * @returns The merged context with document policy forwarding.
+ * @internal
+ * @since 1.4.0
+ */
+declare function mergeCommandDocPolicy(parent: ExecutionContext | undefined, child: ExecutionContext | undefined, merged: ExecutionContext): ExecutionContext;
+/**
+ * Removes an abandoned parser branch from a speculative context copy.
+ * @param exec The context before trying a replacement branch.
+ * @param path The structural path of the abandoned branch.
+ * @returns A context containing only retained scope occurrences.
+ * @internal
+ * @since 1.4.0
+ */
+declare function withoutCommandDocPolicySubtree(exec: ExecutionContext | undefined, path: readonly PropertyKey[]): ExecutionContext | undefined;
+/**
+ * Resolves the selected command's nearest explicit ancestor policy.
+ * @param exec The final successful document parsing context.
+ * @returns A command default, or undefined when no selected command sets one.
+ * @internal
+ * @since 1.4.0
+ */
+declare function getCommandDocPolicy(exec: ExecutionContext | undefined): boolean | undefined;
+/**
+ * Stores a bare command's static default, preserved by transparent spreads.
+ * @param parser The newly constructed command parser.
+ * @param showUsage Its declared policy.
+ * @internal
+ * @since 1.4.0
+ */
+declare function defineBareCommandDocPolicy(parser: object, showUsage: boolean | undefined): void;
+/**
+ * Reads static policy after the existing bare-command brand check.
+ * @param parser The branded command parser.
+ * @returns Its declared policy, or undefined.
+ * @internal
+ * @since 1.4.0
+ */
+declare function getBareCommandDocPolicy(parser: object): boolean | undefined;
+//#endregion
+export { defineBareCommandDocPolicy, enterCommandDocPolicy, getBareCommandDocPolicy, getCommandDocPolicy, matchCommandDocPolicy, mergeCommandDocPolicy, trackCommandDocPolicy, withoutCommandDocPolicySubtree };

package/dist/internal/command-doc-policy.d.ts

@@ -0,0 +1,77 @@
+import { ExecutionContext } from "./parser.js";
+
+//#region src/internal/command-doc-policy.d.ts
+
+/**
+ * Enables command policy tracking for document generation only.
+ * @param exec The initial execution context.
+ * @returns A context with an empty immutable policy trace.
+ * @internal
+ * @since 1.4.0
+ */
+declare function trackCommandDocPolicy(exec: ExecutionContext): ExecutionContext;
+/**
+ * Records a successfully matched command occurrence.
+ * @param exec The command's execution context.
+ * @param id The constructor identity.
+ * @param showUsage The declared command policy.
+ * @returns A new context when tracking is enabled, otherwise the original.
+ * @internal
+ * @since 1.4.0
+ */
+declare function matchCommandDocPolicy(exec: ExecutionContext | undefined, id: symbol, showUsage: boolean | undefined): ExecutionContext | undefined;
+/**
+ * Enters the actual parent command while delegating to its inner parser.
+ * @param exec The context before appending the inner command path.
+ * @param id The command constructor identity.
+ * @returns A child context with the matching occurrence as active scope.
+ * @internal
+ * @since 1.4.0
+ */
+declare function enterCommandDocPolicy(exec: ExecutionContext | undefined, id: symbol): ExecutionContext | undefined;
+/**
+ * Transfers the selected child's policy and restores the caller's scope.
+ * Empty child records deliberately replace previous records.
+ * @param parent The caller's context.
+ * @param child The selected child's context.
+ * @param merged The otherwise merged context.
+ * @returns The merged context with document policy forwarding.
+ * @internal
+ * @since 1.4.0
+ */
+declare function mergeCommandDocPolicy(parent: ExecutionContext | undefined, child: ExecutionContext | undefined, merged: ExecutionContext): ExecutionContext;
+/**
+ * Removes an abandoned parser branch from a speculative context copy.
+ * @param exec The context before trying a replacement branch.
+ * @param path The structural path of the abandoned branch.
+ * @returns A context containing only retained scope occurrences.
+ * @internal
+ * @since 1.4.0
+ */
+declare function withoutCommandDocPolicySubtree(exec: ExecutionContext | undefined, path: readonly PropertyKey[]): ExecutionContext | undefined;
+/**
+ * Resolves the selected command's nearest explicit ancestor policy.
+ * @param exec The final successful document parsing context.
+ * @returns A command default, or undefined when no selected command sets one.
+ * @internal
+ * @since 1.4.0
+ */
+declare function getCommandDocPolicy(exec: ExecutionContext | undefined): boolean | undefined;
+/**
+ * Stores a bare command's static default, preserved by transparent spreads.
+ * @param parser The newly constructed command parser.
+ * @param showUsage Its declared policy.
+ * @internal
+ * @since 1.4.0
+ */
+declare function defineBareCommandDocPolicy(parser: object, showUsage: boolean | undefined): void;
+/**
+ * Reads static policy after the existing bare-command brand check.
+ * @param parser The branded command parser.
+ * @returns Its declared policy, or undefined.
+ * @internal
+ * @since 1.4.0
+ */
+declare function getBareCommandDocPolicy(parser: object): boolean | undefined;
+//#endregion
+export { defineBareCommandDocPolicy, enterCommandDocPolicy, getBareCommandDocPolicy, getCommandDocPolicy, matchCommandDocPolicy, mergeCommandDocPolicy, trackCommandDocPolicy, withoutCommandDocPolicySubtree };

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

@@ -0,0 +1,160 @@
+//#region src/internal/command-doc-policy.ts
+const policyKey = Symbol("commandDocPolicy");
+const barePolicyKey = Symbol("bareCommandDocPolicy");
+function policy(exec) {
+	return exec?.[policyKey];
+}
+function samePath(a, b) {
+	return a.length === b.length && a.every((part, i) => part === b[i]);
+}
+/**
+* Enables command policy tracking for document generation only.
+* @param exec The initial execution context.
+* @returns A context with an empty immutable policy trace.
+* @internal
+* @since 1.4.0
+*/
+function trackCommandDocPolicy(exec) {
+	return {
+		...exec,
+		[policyKey]: { records: [] }
+	};
+}
+/**
+* Records a successfully matched command occurrence.
+* @param exec The command's execution context.
+* @param id The constructor identity.
+* @param showUsage The declared command policy.
+* @returns A new context when tracking is enabled, otherwise the original.
+* @internal
+* @since 1.4.0
+*/
+function matchCommandDocPolicy(exec, id, showUsage) {
+	const current = policy(exec);
+	if (exec == null || current == null) return exec;
+	const scope = {
+		id,
+		path: [...exec.path],
+		parent: current.active,
+		showUsage
+	};
+	return {
+		...exec,
+		[policyKey]: {
+			...current,
+			records: [...current.records, scope]
+		}
+	};
+}
+/**
+* Enters the actual parent command while delegating to its inner parser.
+* @param exec The context before appending the inner command path.
+* @param id The command constructor identity.
+* @returns A child context with the matching occurrence as active scope.
+* @internal
+* @since 1.4.0
+*/
+function enterCommandDocPolicy(exec, id) {
+	const current = policy(exec);
+	if (exec == null || current == null) return exec;
+	const active = current.records.findLast((scope) => scope.id === id && samePath(scope.path, exec.path));
+	return {
+		...exec,
+		[policyKey]: {
+			...current,
+			active
+		}
+	};
+}
+/**
+* Transfers the selected child's policy and restores the caller's scope.
+* Empty child records deliberately replace previous records.
+* @param parent The caller's context.
+* @param child The selected child's context.
+* @param merged The otherwise merged context.
+* @returns The merged context with document policy forwarding.
+* @internal
+* @since 1.4.0
+*/
+function mergeCommandDocPolicy(parent, child, merged) {
+	const parentPolicy = policy(parent);
+	const childPolicy = policy(child);
+	if (parentPolicy == null && childPolicy == null) return merged;
+	return {
+		...merged,
+		[policyKey]: {
+			active: parentPolicy?.active,
+			records: childPolicy?.records ?? []
+		}
+	};
+}
+/**
+* Removes an abandoned parser branch from a speculative context copy.
+* @param exec The context before trying a replacement branch.
+* @param path The structural path of the abandoned branch.
+* @returns A context containing only retained scope occurrences.
+* @internal
+* @since 1.4.0
+*/
+function withoutCommandDocPolicySubtree(exec, path) {
+	const current = policy(exec);
+	if (exec == null || current == null) return exec;
+	const retained = /* @__PURE__ */ new Set();
+	const records = current.records.filter((scope) => {
+		const inside = scope.path.length >= path.length && path.every((part, i) => part === scope.path[i]);
+		if (inside || scope.parent != null && !retained.has(scope.parent)) return false;
+		retained.add(scope);
+		return true;
+	});
+	let active = current.active;
+	while (active != null && !retained.has(active)) active = active.parent;
+	return {
+		...exec,
+		[policyKey]: {
+			active,
+			records
+		}
+	};
+}
+/**
+* Resolves the selected command's nearest explicit ancestor policy.
+* @param exec The final successful document parsing context.
+* @returns A command default, or undefined when no selected command sets one.
+* @internal
+* @since 1.4.0
+*/
+function getCommandDocPolicy(exec) {
+	let scope = policy(exec)?.records.at(-1);
+	while (scope != null) {
+		if (scope.showUsage != null) return scope.showUsage;
+		scope = scope.parent;
+	}
+	return void 0;
+}
+/**
+* Stores a bare command's static default, preserved by transparent spreads.
+* @param parser The newly constructed command parser.
+* @param showUsage Its declared policy.
+* @internal
+* @since 1.4.0
+*/
+function defineBareCommandDocPolicy(parser, showUsage) {
+	Object.defineProperty(parser, barePolicyKey, {
+		value: showUsage,
+		enumerable: true
+	});
+}
+/**
+* Reads static policy after the existing bare-command brand check.
+* @param parser The branded command parser.
+* @returns Its declared policy, or undefined.
+* @internal
+* @since 1.4.0
+*/
+function getBareCommandDocPolicy(parser) {
+	const value = Reflect.get(parser, barePolicyKey);
+	return typeof value === "boolean" ? value : void 0;
+}
+
+//#endregion
+export { defineBareCommandDocPolicy, enterCommandDocPolicy, getBareCommandDocPolicy, getCommandDocPolicy, matchCommandDocPolicy, mergeCommandDocPolicy, trackCommandDocPolicy, withoutCommandDocPolicySubtree };

package/dist/internal/parser.cjs

@@ -1,4 +1,5 @@
 const require_internal_annotations = require('./annotations.cjs');
+const require_internal_command_doc_policy = require('./command-doc-policy.cjs');
 const require_usage = require('../usage.cjs');
 const require_message = require('../message.cjs');
 const require_doc = require('../doc.cjs');
@@ -800,12 +801,12 @@ function getDocPage(parser, argsOrOptions, options) {
 */
 function getDocPageSyncImpl(parser, args, options) {
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	const exec = {
+	const exec = require_internal_command_doc_policy.trackCommandDocPolicy({
 		usage: parser.usage,
 		phase: "parse",
 		path: [],
 		trace: require_input_trace.createInputTrace()
-	};
+	});
 	let context = createParserContext({
 		buffer: args,
 		state: initialState,
@@ -829,12 +830,12 @@ function getDocPageSyncImpl(parser, args, options) {
 */
 async function getDocPageAsyncImpl(parser, args, options) {
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	const exec = {
+	const exec = require_internal_command_doc_policy.trackCommandDocPolicy({
 		usage: parser.usage,
 		phase: "parse",
 		path: [],
 		trace: require_input_trace.createInputTrace()
-	};
+	});
 	let context = createParserContext({
 		buffer: args,
 		state: initialState,
@@ -859,6 +860,7 @@ async function getDocPageAsyncImpl(parser, args, options) {
 */
 function buildDocPage(parser, context, args, matchedCommandArgIndices) {
 	let effectiveArgs = args;
+	let showUsage = require_internal_command_doc_policy.getCommandDocPolicy(context.exec);
 	let { brief, description, fragments, footer, environmentBindings } = parser.getDocFragments({
 		kind: "available",
 		state: context.state
@@ -872,6 +874,7 @@ function buildDocPage(parser, context, args, matchedCommandArgIndices) {
 		}, void 0);
 		({brief, description, fragments, footer, environmentBindings} = matched);
 		effectiveArgs = [cmdName];
+		showUsage = require_internal_command_doc_policy.getBareCommandDocPolicy(parser);
 	}
 	const buildingSections = [];
 	let untitledSection = null;
@@ -949,6 +952,7 @@ function buildDocPage(parser, context, args, matchedCommandArgIndices) {
 		...binding.description != null && { description: require_message.cloneMessage(binding.description) }
 	}));
 	return {
+		...showUsage != null && { showUsage },
 		...visibleBindings != null && visibleBindings.length > 0 && { environmentBindings: visibleBindings },
 		usage: revealMatchedCommandUsage(usage, effectiveArgs, commandArgIndices ?? null),
 		sections,

package/dist/internal/parser.js

@@ -1,4 +1,5 @@
 import { hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
+import { getBareCommandDocPolicy, getCommandDocPolicy, trackCommandDocPolicy } from "./command-doc-policy.js";
 import { cloneUsage, isDocHidden, normalizeUsage } from "../usage.js";
 import { cloneMessage, message } from "../message.js";
 import { cloneDocEntry, isDocEntryHidden } from "../doc.js";
@@ -800,12 +801,12 @@ function getDocPage(parser, argsOrOptions, options) {
 */
 function getDocPageSyncImpl(parser, args, options) {
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	const exec = {
+	const exec = trackCommandDocPolicy({
 		usage: parser.usage,
 		phase: "parse",
 		path: [],
 		trace: createInputTrace()
-	};
+	});
 	let context = createParserContext({
 		buffer: args,
 		state: initialState,
@@ -829,12 +830,12 @@ function getDocPageSyncImpl(parser, args, options) {
 */
 async function getDocPageAsyncImpl(parser, args, options) {
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	const exec = {
+	const exec = trackCommandDocPolicy({
 		usage: parser.usage,
 		phase: "parse",
 		path: [],
 		trace: createInputTrace()
-	};
+	});
 	let context = createParserContext({
 		buffer: args,
 		state: initialState,
@@ -859,6 +860,7 @@ async function getDocPageAsyncImpl(parser, args, options) {
 */
 function buildDocPage(parser, context, args, matchedCommandArgIndices) {
 	let effectiveArgs = args;
+	let showUsage = getCommandDocPolicy(context.exec);
 	let { brief, description, fragments, footer, environmentBindings } = parser.getDocFragments({
 		kind: "available",
 		state: context.state
@@ -872,6 +874,7 @@ function buildDocPage(parser, context, args, matchedCommandArgIndices) {
 		}, void 0);
 		({brief, description, fragments, footer, environmentBindings} = matched);
 		effectiveArgs = [cmdName];
+		showUsage = getBareCommandDocPolicy(parser);
 	}
 	const buildingSections = [];
 	let untitledSection = null;
@@ -949,6 +952,7 @@ function buildDocPage(parser, context, args, matchedCommandArgIndices) {
 		...binding.description != null && { description: cloneMessage(binding.description) }
 	}));
 	return {
+		...showUsage != null && { showUsage },
 		...visibleBindings != null && visibleBindings.length > 0 && { environmentBindings: visibleBindings },
 		usage: revealMatchedCommandUsage(usage, effectiveArgs, commandArgIndices ?? null),
 		sections,

package/dist/primitives.cjs

@@ -1,4 +1,5 @@
 const require_internal_annotations = require('./internal/annotations.cjs');
+const require_internal_command_doc_policy = require('./internal/command-doc-policy.cjs');
 const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
 const require_message = require('./message.cjs');
@@ -1447,6 +1448,12 @@ function getShowCommandAliases(options) {
 	if (typeof showAliases !== "boolean") throw new TypeError("Command showAliases must be a boolean.");
 	return showAliases;
 }
+function getShowCommandUsage(options) {
+	const showUsage = options.showUsage;
+	if (showUsage == null) return void 0;
+	if (typeof showUsage !== "boolean") throw new TypeError("Command showUsage must be a boolean.");
+	return showUsage;
+}
 function getHiddenCommandAliases(options) {
 	const hiddenAliases = options[require_command_alias.hiddenCommandAliasesKey];
 	if (hiddenAliases == null) return [];
@@ -1511,12 +1518,15 @@ async function* suggestCommandAsync(context, prefix, name, aliases, parser, opti
 *          to the inner parser for the remaining arguments.
 * @throws {TypeError} If `name` is empty, whitespace-only, contains
 *         embedded whitespace, or contains control characters.
-* @throws {TypeError} If `options.showAliases` is present but not a boolean.
+* @throws {TypeError} If `options.showAliases` or `options.showUsage` is
+*         non-nullish and not a boolean.
 */
 function command(name, parser, options = {}) {
 	const commandNames = getCommandNames(name, options);
 	const aliases = getVisibleCommandAliases(options);
 	const showAliases = getShowCommandAliases(options);
+	const showUsage = getShowCommandUsage(options);
+	const commandId = Symbol("commandDocScope");
 	const hiddenAliases = getHiddenCommandAliases(options);
 	require_validate.validateCommandNames(commandNames, "Command");
 	validateUniqueCommandNames(commandNames);
@@ -1602,7 +1612,7 @@ function command(name, parser, options = {}) {
 						...context,
 						buffer: context.buffer.slice(1),
 						state: createCommandState(context.state, ["matched", name]),
-						...context.exec != null ? { exec: appendCommandPath(context.exec, name) } : {}
+						...context.exec != null ? { exec: require_internal_command_doc_policy.matchCommandDocPolicy(appendCommandPath(context.exec, name), commandId, showUsage) } : {}
 					},
 					consumed: context.buffer.slice(0, 1)
 				};
@@ -1626,7 +1636,13 @@ function command(name, parser, options = {}) {
 					}
 					return parseResult;
 				};
-				return require_mode_dispatch.dispatchByMode(parser.mode, () => wrapState(syncInnerParser.parse(require_execution_context.withChildContext(context, name, innerState, parser.usage))), async () => wrapState(await parser.parse(require_execution_context.withChildContext(context, name, innerState, parser.usage))));
+				return require_mode_dispatch.dispatchByMode(parser.mode, () => wrapState(syncInnerParser.parse(require_execution_context.withChildContext({
+					...context,
+					exec: require_internal_command_doc_policy.enterCommandDocPolicy(context.exec, commandId)
+				}, name, innerState, parser.usage))), async () => wrapState(await parser.parse(require_execution_context.withChildContext({
+					...context,
+					exec: require_internal_command_doc_policy.enterCommandDocPolicy(context.exec, commandId)
+				}, name, innerState, parser.usage))));
 			}
 			return {
 				success: false,
@@ -1744,6 +1760,7 @@ function command(name, parser, options = {}) {
 			return `command(${JSON.stringify(name)})`;
 		}
 	};
+	require_internal_command_doc_policy.defineBareCommandDocPolicy(result, showUsage);
 	if (typeof parser.normalizeValue === "function") Object.defineProperty(result, "normalizeValue", {
 		value: parser.normalizeValue.bind(parser),
 		configurable: true,

package/dist/primitives.d.cts

@@ -451,6 +451,14 @@ interface CommandOptions {
    * @since 1.0.0
    */
   readonly usageLine?: Usage | ((defaultUsageLine: Usage) => Usage);
+  /**
+   * Whether to show the usage synopsis in this command's full help.
+   * Descendants inherit this setting unless they explicitly override it.
+   * Omission inherits the nearest ancestor setting, then the runner setting,
+   * with a final default of `true`. Usage-only error preambles are unaffected.
+   * @since 1.4.0
+   */
+  readonly showUsage?: boolean;
   /**
    * Controls command visibility:
    *
@@ -537,7 +545,8 @@ type CommandState<TState> = undefined | ["matched", string] | ["parsing", TState
  *          to the inner parser for the remaining arguments.
  * @throws {TypeError} If `name` is empty, whitespace-only, contains
  *         embedded whitespace, or contains control characters.
- * @throws {TypeError} If `options.showAliases` is present but not a boolean.
+ * @throws {TypeError} If `options.showAliases` or `options.showUsage` is
+ *         non-nullish and not a boolean.
  */
 declare function command<M extends Mode, T, TState>(name: string, parser: Parser<M, T, TState>, options?: CommandOptions): FluentParser<M, T, CommandState<TState>>;
 /**