@optique/core 1.0.0-dev.427 → 1.0.0-dev.429

package/dist/usage.d.cts

@@ -12,6 +12,30 @@ import { NonEmptyString } from "./nonempty.cjs";
  * - Plus-prefixed options (`+o`)
  */
 type OptionName = `--${string}` | `-${string}` | `/${string}` | `+${string}`;
+/**
+ * Visibility control for parser terms.
+ *
+ * - `true`: hidden from usage, documentation, and suggestions
+ * - `"usage"`: hidden from usage only
+ * - `"doc"`: hidden from documentation only
+ */
+type HiddenVisibility = boolean | "usage" | "doc";
+/**
+ * Returns whether the term should be hidden from usage output.
+ */
+declare function isUsageHidden(hidden?: HiddenVisibility): boolean;
+/**
+ * Returns whether the term should be hidden from documentation output.
+ */
+declare function isDocHidden(hidden?: HiddenVisibility): boolean;
+/**
+ * Returns whether the term should be hidden from suggestion/error candidates.
+ */
+declare function isSuggestionHidden(hidden?: HiddenVisibility): boolean;
+/**
+ * Merges two hidden visibility settings by taking the union of restrictions.
+ */
+declare function mergeHidden(a?: HiddenVisibility, b?: HiddenVisibility): HiddenVisibility | undefined;
 /**
  * Represents a single term in a command-line usage description.
  */
@@ -31,11 +55,10 @@ type UsageTerm =
    */
   readonly metavar: NonEmptyString;
   /**
-   * When `true`, hides the argument from help text, shell completion
-   * suggestions, and error suggestions.
+   * Visibility controls for this term.
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
 }
 /**
  * An option term, which represents a command-line option that can
@@ -56,11 +79,10 @@ type UsageTerm =
    */
   readonly metavar?: NonEmptyString;
   /**
-   * When `true`, hides the option from help text, shell completion
-   * suggestions, and "Did you mean?" error suggestions.
+   * Visibility controls for this term.
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
 }
 /**
  * A command term, which represents a subcommand in the command-line
@@ -76,11 +98,10 @@ type UsageTerm =
    */
   readonly name: string;
   /**
-   * When `true`, hides the command from help text, shell completion
-   * suggestions, and "Did you mean?" error suggestions.
+   * Visibility controls for this term.
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
 }
 /**
  * An optional term, which represents an optional component
@@ -155,11 +176,10 @@ type UsageTerm =
    */
   readonly type: "passthrough";
   /**
-   * When `true`, hides the pass-through from help text and shell
-   * completion suggestions.
+   * Visibility controls for this term.
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
 };
 /**
  * Represents a command-line usage description, which is a sequence of
@@ -330,4 +350,4 @@ interface UsageTermFormatOptions extends UsageFormatOptions {
  */
 declare function formatUsageTerm(term: UsageTerm, options?: UsageTermFormatOptions): string;
 //#endregion
-export { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage };
+export { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };

package/dist/usage.d.ts

@@ -12,6 +12,30 @@ import { NonEmptyString } from "./nonempty.js";
  * - Plus-prefixed options (`+o`)
  */
 type OptionName = `--${string}` | `-${string}` | `/${string}` | `+${string}`;
+/**
+ * Visibility control for parser terms.
+ *
+ * - `true`: hidden from usage, documentation, and suggestions
+ * - `"usage"`: hidden from usage only
+ * - `"doc"`: hidden from documentation only
+ */
+type HiddenVisibility = boolean | "usage" | "doc";
+/**
+ * Returns whether the term should be hidden from usage output.
+ */
+declare function isUsageHidden(hidden?: HiddenVisibility): boolean;
+/**
+ * Returns whether the term should be hidden from documentation output.
+ */
+declare function isDocHidden(hidden?: HiddenVisibility): boolean;
+/**
+ * Returns whether the term should be hidden from suggestion/error candidates.
+ */
+declare function isSuggestionHidden(hidden?: HiddenVisibility): boolean;
+/**
+ * Merges two hidden visibility settings by taking the union of restrictions.
+ */
+declare function mergeHidden(a?: HiddenVisibility, b?: HiddenVisibility): HiddenVisibility | undefined;
 /**
  * Represents a single term in a command-line usage description.
  */
@@ -31,11 +55,10 @@ type UsageTerm =
    */
   readonly metavar: NonEmptyString;
   /**
-   * When `true`, hides the argument from help text, shell completion
-   * suggestions, and error suggestions.
+   * Visibility controls for this term.
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
 }
 /**
  * An option term, which represents a command-line option that can
@@ -56,11 +79,10 @@ type UsageTerm =
    */
   readonly metavar?: NonEmptyString;
   /**
-   * When `true`, hides the option from help text, shell completion
-   * suggestions, and "Did you mean?" error suggestions.
+   * Visibility controls for this term.
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
 }
 /**
  * A command term, which represents a subcommand in the command-line
@@ -76,11 +98,10 @@ type UsageTerm =
    */
   readonly name: string;
   /**
-   * When `true`, hides the command from help text, shell completion
-   * suggestions, and "Did you mean?" error suggestions.
+   * Visibility controls for this term.
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
 }
 /**
  * An optional term, which represents an optional component
@@ -155,11 +176,10 @@ type UsageTerm =
    */
   readonly type: "passthrough";
   /**
-   * When `true`, hides the pass-through from help text and shell
-   * completion suggestions.
+   * Visibility controls for this term.
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
 };
 /**
  * Represents a command-line usage description, which is a sequence of
@@ -330,4 +350,4 @@ interface UsageTermFormatOptions extends UsageFormatOptions {
  */
 declare function formatUsageTerm(term: UsageTerm, options?: UsageTermFormatOptions): string;
 //#endregion
-export { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage };
+export { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };

package/dist/usage.js

@@ -1,5 +1,33 @@
 //#region src/usage.ts
 /**
+* Returns whether the term should be hidden from usage output.
+*/
+function isUsageHidden(hidden) {
+	return hidden === true || hidden === "usage";
+}
+/**
+* Returns whether the term should be hidden from documentation output.
+*/
+function isDocHidden(hidden) {
+	return hidden === true || hidden === "doc";
+}
+/**
+* Returns whether the term should be hidden from suggestion/error candidates.
+*/
+function isSuggestionHidden(hidden) {
+	return hidden === true;
+}
+/**
+* Merges two hidden visibility settings by taking the union of restrictions.
+*/
+function mergeHidden(a, b) {
+	if (a == null) return b;
+	if (b == null) return a;
+	if (a === true || b === true) return true;
+	if (a !== b) return true;
+	return a;
+}
+/**
 * Extracts all option names from a usage description.
 *
 * This function recursively traverses a {@link Usage} tree and collects all
@@ -24,7 +52,7 @@ function extractOptionNames(usage) {
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
 		for (const term of terms) if (term.type === "option") {
-			if (term.hidden) continue;
+			if (isSuggestionHidden(term.hidden)) continue;
 			for (const name of term.names) names.add(name);
 		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
@@ -57,7 +85,7 @@ function extractCommandNames(usage) {
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
 		for (const term of terms) if (term.type === "command") {
-			if (term.hidden) continue;
+			if (isSuggestionHidden(term.hidden)) continue;
 			names.add(term.name);
 		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
@@ -91,7 +119,7 @@ function extractArgumentMetavars(usage) {
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
 		for (const term of terms) if (term.type === "argument") {
-			if (term.hidden) continue;
+			if (isSuggestionHidden(term.hidden)) continue;
 			metavars.add(term.metavar);
 		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
@@ -116,14 +144,14 @@ function extractArgumentMetavars(usage) {
 * @returns A formatted string representation of the usage description.
 */
 function formatUsage(programName, usage, options = {}) {
-	usage = normalizeUsage(usage);
+	usage = normalizeUsage(filterUsageForDisplay(usage));
 	if (options.expandCommands) {
 		const lastTerm = usage.at(-1);
 		if (usage.length > 0 && usage.slice(0, -1).every((t) => t.type === "command") && lastTerm.type === "exclusive" && lastTerm.terms.every((t) => t.length > 0 && (t[0].type === "command" || t[0].type === "option" || t[0].type === "argument" || t[0].type === "optional" && t[0].terms.length === 1 && (t[0].terms[0].type === "command" || t[0].terms[0].type === "option" || t[0].terms[0].type === "argument")))) {
 			const lines = [];
 			for (let command of lastTerm.terms) {
 				const firstTerm = command[0];
-				if (firstTerm?.type === "command" && firstTerm.hidden) continue;
+				if (firstTerm?.type === "command" && isUsageHidden(firstTerm.hidden)) continue;
 				if (usage.length > 1) command = [...usage.slice(0, -1), ...command];
 				lines.push(formatUsage(programName, command, options));
 			}
@@ -204,9 +232,47 @@ function normalizeUsageTerm(term) {
 		};
 	} else return term;
 }
+function filterUsageForDisplay(usage) {
+	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 === "optional") {
+			const filtered = filterUsageForDisplay(term.terms);
+			if (filtered.length > 0) terms.push({
+				type: "optional",
+				terms: filtered
+			});
+			continue;
+		}
+		if (term.type === "multiple") {
+			const filtered = filterUsageForDisplay(term.terms);
+			if (filtered.length > 0) terms.push({
+				type: "multiple",
+				terms: filtered,
+				min: term.min
+			});
+			continue;
+		}
+		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);
+			}).filter((branch) => branch.length > 0);
+			if (filteredBranches.length > 0) terms.push({
+				type: "exclusive",
+				terms: filteredBranches
+			});
+			continue;
+		}
+		terms.push(term);
+	}
+	return terms;
+}
 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
@@ -225,9 +291,11 @@ function* formatUsageTerms(terms, options) {
 * @returns A formatted string representation of the usage term.
 */
 function formatUsageTerm(term, options = {}) {
+	const visibleTerms = filterUsageForDisplay([term]);
+	if (visibleTerms.length < 1) return "";
 	let lineWidth = 0;
 	let output = "";
-	for (const { text, width } of formatUsageTermInternal(term, options)) {
+	for (const { text, width } of formatUsageTermInternal(visibleTerms[0], options)) {
 		if (options.maxWidth != null && lineWidth + width > options.maxWidth) {
 			output += "\n";
 			lineWidth = 0;
@@ -350,4 +418,4 @@ function* formatUsageTermInternal(term, options) {
 }
 
 //#endregion
-export { extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage };
+export { extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.427+497e26fe",
+  "version": "1.0.0-dev.429+66edc8ed",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",