@optique/core 1.0.0-dev.1279 → 1.0.0-dev.1290

package/dist/doc.cjs

@@ -76,6 +76,17 @@ function formatDocPage(programName, page, options = {}) {
 	const termIndent = options.termIndent ?? 2;
 	const termWidth = options.termWidth ?? 26;
 	if (options.maxWidth != null && (!Number.isFinite(options.maxWidth) || !Number.isInteger(options.maxWidth))) throw new TypeError(`maxWidth must be a finite integer, got ${options.maxWidth}.`);
+	const filteredSections = page.sections.map((s) => ({
+		...s,
+		entries: s.entries.filter((e) => {
+			const rendered = require_usage.formatUsageTerm(e.term, { context: "doc" });
+			return rendered.trim() !== "";
+		})
+	}));
+	page = {
+		...page,
+		sections: filteredSections
+	};
 	if (options.maxWidth != null) {
 		const hasEntries = page.sections.some((s) => s.entries.length > 0);
 		const hasContent = (msg) => Array.isArray(msg) && msg.length > 0;
@@ -171,6 +182,7 @@ function formatDocPage(programName, page, options = {}) {
 			const term = require_usage.formatUsageTerm(entry.term, {
 				colors: options.colors,
 				optionsSeparator: ", ",
+				context: "doc",
 				maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - termIndent
 			});
 			const descColumnWidth = options.maxWidth == null ? void 0 : options.maxWidth - termIndent - effectiveTermWidth - 2;

package/dist/doc.js

@@ -76,6 +76,17 @@ function formatDocPage(programName, page, options = {}) {
 	const termIndent = options.termIndent ?? 2;
 	const termWidth = options.termWidth ?? 26;
 	if (options.maxWidth != null && (!Number.isFinite(options.maxWidth) || !Number.isInteger(options.maxWidth))) throw new TypeError(`maxWidth must be a finite integer, got ${options.maxWidth}.`);
+	const filteredSections = page.sections.map((s) => ({
+		...s,
+		entries: s.entries.filter((e) => {
+			const rendered = formatUsageTerm(e.term, { context: "doc" });
+			return rendered.trim() !== "";
+		})
+	}));
+	page = {
+		...page,
+		sections: filteredSections
+	};
 	if (options.maxWidth != null) {
 		const hasEntries = page.sections.some((s) => s.entries.length > 0);
 		const hasContent = (msg) => Array.isArray(msg) && msg.length > 0;
@@ -171,6 +182,7 @@ function formatDocPage(programName, page, options = {}) {
 			const term = formatUsageTerm(entry.term, {
 				colors: options.colors,
 				optionsSeparator: ", ",
+				context: "doc",
 				maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - termIndent
 			});
 			const descColumnWidth = options.maxWidth == null ? void 0 : options.maxWidth - termIndent - effectiveTermWidth - 2;

package/dist/facade.cjs

@@ -879,24 +879,44 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		const helpOptionArgs = helpTerminatorIndex >= 0 ? args.slice(0, helpTerminatorIndex) : args;
 		const hasHelpOption = helpOptionConfig ? completionCommandConfig && completionCommandNames.includes(args[0]) ? args.length >= 2 && helpOptionNames.includes(args[1]) : helpOptionNames.some((n) => helpOptionArgs.includes(n)) : false;
 		if (completionCommandConfig && args.length >= 1 && completionCommandNames.includes(args[0]) && !hasHelpOption) return handleCompletion(args.slice(1), programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], false, sectionOrder);
+		const hasMetaEntryBefore = (endIndex) => {
+			const argsBefore = args.slice(0, endIndex);
+			if (helpOptionConfig && helpOptionNames.some((n) => argsBefore.includes(n))) return true;
+			if (versionOptionConfig && versionOptionNames.some((n) => argsBefore.includes(n))) return true;
+			if (endIndex > 0) {
+				if (helpCommandConfig && helpCommandNames.includes(args[0])) return true;
+				if (versionCommandConfig && versionCommandNames.includes(args[0])) return true;
+			}
+			return false;
+		};
+		let completionOptionIndex = -1;
 		if (completionOptionConfig) {
 			const loopBound = helpTerminatorIndex >= 0 ? helpTerminatorIndex : args.length;
 			for (let i = 0; i < loopBound; i++) {
 				const arg = args[i];
 				const equalsMatch = completionOptionNames.find((n) => arg.startsWith(n + "="));
 				if (equalsMatch) {
+					if (hasMetaEntryBefore(i)) {
+						completionOptionIndex = i;
+						break;
+					}
 					const shell = arg.slice(equalsMatch.length + 1);
 					const completionArgs = args.slice(i + 1);
 					return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], true, sectionOrder);
 				}
 				const exactMatch = completionOptionNames.includes(arg);
 				if (exactMatch) {
+					if (hasMetaEntryBefore(i)) {
+						completionOptionIndex = i;
+						break;
+					}
 					const shell = i + 1 < args.length ? args[i + 1] : "";
 					const completionArgs = i + 1 < args.length ? args.slice(i + 2) : [];
 					return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], true, sectionOrder);
 				}
 			}
 		}
+		if (completionOptionIndex >= 0) args = args.slice(0, completionOptionIndex);
 	}
 	const augmentedParser = !options.help && !options.version && !options.completion ? parser : combineWithHelpVersion(parser, helpParsers, versionParsers, completionParsers, {
 		helpCommandGroup: helpCommandConfig?.group,

package/dist/facade.js

@@ -879,24 +879,44 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		const helpOptionArgs = helpTerminatorIndex >= 0 ? args.slice(0, helpTerminatorIndex) : args;
 		const hasHelpOption = helpOptionConfig ? completionCommandConfig && completionCommandNames.includes(args[0]) ? args.length >= 2 && helpOptionNames.includes(args[1]) : helpOptionNames.some((n) => helpOptionArgs.includes(n)) : false;
 		if (completionCommandConfig && args.length >= 1 && completionCommandNames.includes(args[0]) && !hasHelpOption) return handleCompletion(args.slice(1), programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], false, sectionOrder);
+		const hasMetaEntryBefore = (endIndex) => {
+			const argsBefore = args.slice(0, endIndex);
+			if (helpOptionConfig && helpOptionNames.some((n) => argsBefore.includes(n))) return true;
+			if (versionOptionConfig && versionOptionNames.some((n) => argsBefore.includes(n))) return true;
+			if (endIndex > 0) {
+				if (helpCommandConfig && helpCommandNames.includes(args[0])) return true;
+				if (versionCommandConfig && versionCommandNames.includes(args[0])) return true;
+			}
+			return false;
+		};
+		let completionOptionIndex = -1;
 		if (completionOptionConfig) {
 			const loopBound = helpTerminatorIndex >= 0 ? helpTerminatorIndex : args.length;
 			for (let i = 0; i < loopBound; i++) {
 				const arg = args[i];
 				const equalsMatch = completionOptionNames.find((n) => arg.startsWith(n + "="));
 				if (equalsMatch) {
+					if (hasMetaEntryBefore(i)) {
+						completionOptionIndex = i;
+						break;
+					}
 					const shell = arg.slice(equalsMatch.length + 1);
 					const completionArgs = args.slice(i + 1);
 					return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], true, sectionOrder);
 				}
 				const exactMatch = completionOptionNames.includes(arg);
 				if (exactMatch) {
+					if (hasMetaEntryBefore(i)) {
+						completionOptionIndex = i;
+						break;
+					}
 					const shell = i + 1 < args.length ? args[i + 1] : "";
 					const completionArgs = i + 1 < args.length ? args.slice(i + 2) : [];
 					return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], true, sectionOrder);
 				}
 			}
 		}
+		if (completionOptionIndex >= 0) args = args.slice(0, completionOptionIndex);
 	}
 	const augmentedParser = !options.help && !options.version && !options.completion ? parser : combineWithHelpVersion(parser, helpParsers, versionParsers, completionParsers, {
 		helpCommandGroup: helpCommandConfig?.group,

package/dist/usage.cjs

@@ -237,12 +237,16 @@ function normalizeUsageTerm(term) {
 		};
 	} else return term;
 }
-function filterUsageForDisplay(usage) {
+function filterUsageForDisplay(usage, isHidden = isUsageHidden) {
 	const terms = [];
 	for (const term of usage) {
-		if ((term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") && isUsageHidden(term.hidden)) continue;
+		if ((term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") && isHidden(term.hidden)) continue;
+		if (term.type === "option" && term.names.length === 0) continue;
+		if (term.type === "command" && term.name === "") continue;
+		if (term.type === "argument" && term.metavar.length === 0) continue;
+		if (term.type === "literal" && term.value === "") continue;
 		if (term.type === "optional") {
-			const filtered = filterUsageForDisplay(term.terms);
+			const filtered = filterUsageForDisplay(term.terms, isHidden);
 			if (filtered.length > 0) terms.push({
 				type: "optional",
 				terms: filtered
@@ -250,7 +254,7 @@ function filterUsageForDisplay(usage) {
 			continue;
 		}
 		if (term.type === "multiple") {
-			const filtered = filterUsageForDisplay(term.terms);
+			const filtered = filterUsageForDisplay(term.terms, isHidden);
 			if (filtered.length > 0) terms.push({
 				type: "multiple",
 				terms: filtered,
@@ -261,8 +265,8 @@ function filterUsageForDisplay(usage) {
 		if (term.type === "exclusive") {
 			const filteredBranches = term.terms.map((branch) => {
 				const first = branch[0];
-				if (first?.type === "command" && isUsageHidden(first.hidden)) return [];
-				return filterUsageForDisplay(branch);
+				if (first?.type === "command" && isHidden(first.hidden)) return [];
+				return filterUsageForDisplay(branch, isHidden);
 			}).filter((branch) => branch.length > 0);
 			if (filteredBranches.length > 0) terms.push({
 				type: "exclusive",
@@ -277,7 +281,6 @@ function filterUsageForDisplay(usage) {
 function* formatUsageTerms(terms, options) {
 	let i = 0;
 	for (const t of terms) {
-		if ("hidden" in t && (t.type === "argument" || t.type === "option" || t.type === "command" || t.type === "passthrough") && isUsageHidden(t.hidden)) continue;
 		if (i > 0) yield {
 			text: " ",
 			width: 1
@@ -296,7 +299,8 @@ function* formatUsageTerms(terms, options) {
 * @returns A formatted string representation of the usage term.
 */
 function formatUsageTerm(term, options = {}) {
-	const visibleTerms = filterUsageForDisplay([term]);
+	const hiddenCheck = options.context === "doc" ? isDocHidden : isUsageHidden;
+	const visibleTerms = filterUsageForDisplay([term], hiddenCheck);
 	if (visibleTerms.length < 1) return "";
 	let lineWidth = 0;
 	let output = "";

package/dist/usage.d.cts

@@ -356,6 +356,16 @@ interface UsageTermFormatOptions extends UsageFormatOptions {
    * @default `"/"`
    */
   readonly optionsSeparator?: string;
+  /**
+   * The rendering context, which determines which hidden visibility values
+   * cause terms to be filtered out.
+   *
+   * - `"usage"` (default): filters terms hidden from usage output
+   * - `"doc"`: filters terms hidden from documentation output
+   * @default `"usage"`
+   * @since 1.0.0
+   */
+  readonly context?: "usage" | "doc";
 }
 /**
  * Formats a single {@link UsageTerm} into a string representation

package/dist/usage.d.ts

@@ -356,6 +356,16 @@ interface UsageTermFormatOptions extends UsageFormatOptions {
    * @default `"/"`
    */
   readonly optionsSeparator?: string;
+  /**
+   * The rendering context, which determines which hidden visibility values
+   * cause terms to be filtered out.
+   *
+   * - `"usage"` (default): filters terms hidden from usage output
+   * - `"doc"`: filters terms hidden from documentation output
+   * @default `"usage"`
+   * @since 1.0.0
+   */
+  readonly context?: "usage" | "doc";
 }
 /**
  * Formats a single {@link UsageTerm} into a string representation

package/dist/usage.js

@@ -236,12 +236,16 @@ function normalizeUsageTerm(term) {
 		};
 	} else return term;
 }
-function filterUsageForDisplay(usage) {
+function filterUsageForDisplay(usage, isHidden = isUsageHidden) {
 	const terms = [];
 	for (const term of usage) {
-		if ((term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") && isUsageHidden(term.hidden)) continue;
+		if ((term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") && isHidden(term.hidden)) continue;
+		if (term.type === "option" && term.names.length === 0) continue;
+		if (term.type === "command" && term.name === "") continue;
+		if (term.type === "argument" && term.metavar.length === 0) continue;
+		if (term.type === "literal" && term.value === "") continue;
 		if (term.type === "optional") {
-			const filtered = filterUsageForDisplay(term.terms);
+			const filtered = filterUsageForDisplay(term.terms, isHidden);
 			if (filtered.length > 0) terms.push({
 				type: "optional",
 				terms: filtered
@@ -249,7 +253,7 @@ function filterUsageForDisplay(usage) {
 			continue;
 		}
 		if (term.type === "multiple") {
-			const filtered = filterUsageForDisplay(term.terms);
+			const filtered = filterUsageForDisplay(term.terms, isHidden);
 			if (filtered.length > 0) terms.push({
 				type: "multiple",
 				terms: filtered,
@@ -260,8 +264,8 @@ function filterUsageForDisplay(usage) {
 		if (term.type === "exclusive") {
 			const filteredBranches = term.terms.map((branch) => {
 				const first = branch[0];
-				if (first?.type === "command" && isUsageHidden(first.hidden)) return [];
-				return filterUsageForDisplay(branch);
+				if (first?.type === "command" && isHidden(first.hidden)) return [];
+				return filterUsageForDisplay(branch, isHidden);
 			}).filter((branch) => branch.length > 0);
 			if (filteredBranches.length > 0) terms.push({
 				type: "exclusive",
@@ -276,7 +280,6 @@ function filterUsageForDisplay(usage) {
 function* formatUsageTerms(terms, options) {
 	let i = 0;
 	for (const t of terms) {
-		if ("hidden" in t && (t.type === "argument" || t.type === "option" || t.type === "command" || t.type === "passthrough") && isUsageHidden(t.hidden)) continue;
 		if (i > 0) yield {
 			text: " ",
 			width: 1
@@ -295,7 +298,8 @@ function* formatUsageTerms(terms, options) {
 * @returns A formatted string representation of the usage term.
 */
 function formatUsageTerm(term, options = {}) {
-	const visibleTerms = filterUsageForDisplay([term]);
+	const hiddenCheck = options.context === "doc" ? isDocHidden : isUsageHidden;
+	const visibleTerms = filterUsageForDisplay([term], hiddenCheck);
 	if (visibleTerms.length < 1) return "";
 	let lineWidth = 0;
 	let output = "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1279+377e2475",
+  "version": "1.0.0-dev.1290+a999711d",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",