@optique/core 1.0.0-dev.1288 → 1.0.0-dev.1291

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/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.1288+e8d1d8b0",
+  "version": "1.0.0-dev.1291+36a7f4c9",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",