@optique/core 0.10.7 → 1.0.0-dev.1116

package/dist/primitives.cjs

@@ -1,3 +1,4 @@
+const require_annotations = require('./annotations.cjs');
 const require_message = require('./message.cjs');
 const require_dependency = require('./dependency.cjs');
 const require_mode_dispatch = require('./mode-dispatch.cjs');
@@ -7,6 +8,10 @@ const require_usage_internals = require('./usage-internals.cjs');
 const require_valueparser = require('./valueparser.cjs');
 
 //#region src/primitives.ts
+function hasParsedOptionValue(state, valueParser) {
+	if (valueParser != null) return require_dependency.isDeferredParseState(state) || require_dependency.isDependencySourceState(state) || state != null && "success" in state && state.success;
+	return state != null && "success" in state && state.success && state.value === true;
+}
 /**
 * Helper function to create the appropriate state for an option value.
 * - If the value parser is a DerivedValueParser, wraps the result in a DeferredParseState
@@ -55,6 +60,54 @@ function constant(value) {
 	};
 }
 /**
+* Creates a parser that always fails without consuming any input.
+*
+* This is the counterpart to {@link constant}: while `constant(value)` always
+* succeeds, `fail<T>()` always fails.  At the type level it is declared to
+* produce a value of type `T`, so it composes seamlessly with other parsers
+* that expect `Parser<"sync", T, …>`.
+*
+* The primary use case is as the inner parser for
+* `bindConfig(fail<T>(), { … })` when a value should *only* come from a
+* config file and has no corresponding CLI flag or argument.  Because `fail()`
+* always fails, `bindConfig` will always fall back to the config file (or the
+* supplied default).
+*
+* @template T The type of value this parser is declared to produce.
+* @returns A {@link Parser} that always fails at parse time and always fails at
+*          complete time.
+* @since 1.0.0
+*/
+function fail() {
+	return {
+		$valueType: [],
+		$stateType: [],
+		$mode: "sync",
+		priority: 0,
+		usage: [],
+		initialState: void 0,
+		parse(_context) {
+			return {
+				success: false,
+				consumed: 0,
+				error: require_message.message`No value provided.`
+			};
+		},
+		complete(_state) {
+			return {
+				success: false,
+				error: require_message.message`No value provided.`
+			};
+		},
+		suggest(_context, _prefix) {
+			return [];
+		},
+		getDocFragments(_state, _defaultValue) {
+			return { fragments: [] };
+		}
+	};
+}
+/**
 * Internal helper to get suggestions from a value parser, using dependency values
 * if the parser is a derived parser and dependency values are available.
 * @internal
@@ -116,7 +169,8 @@ function* suggestOptionSync(optionNames$1, valueParser, hidden, context, prefix)
 			}
 		}
 	} else {
-		if (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/")) {
+		const expectingValue = context.buffer.length > 0 && optionNames$1.includes(context.buffer[context.buffer.length - 1]);
+		if (!expectingValue && (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/"))) {
 			for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
 				if (prefix === "-" && optionName$1.length !== 2) continue;
 				yield {
@@ -197,7 +251,8 @@ async function* suggestOptionAsync(optionNames$1, valueParser, hidden, context,
 			}
 		}
 	} else {
-		if (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/")) {
+		const expectingValue = context.buffer.length > 0 && optionNames$1.includes(context.buffer[context.buffer.length - 1]);
+		if (!expectingValue && (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/"))) {
 			for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
 				if (prefix === "-" && optionName$1.length !== 2) continue;
 				yield {
@@ -266,13 +321,13 @@ function option(...args) {
 			terms: [{
 				type: "option",
 				names: optionNames$1,
-				...options.hidden && { hidden: true }
+				...options.hidden != null && { hidden: options.hidden }
 			}]
 		} : {
 			type: "option",
 			names: optionNames$1,
 			metavar: valueParser.metavar,
-			...options.hidden && { hidden: true }
+			...options.hidden != null && { hidden: options.hidden }
 		}],
 		initialState: valueParser == null ? {
 			success: true,
@@ -303,8 +358,7 @@ function option(...args) {
 				consumed: context.buffer.slice(0, 1)
 			};
 			if (optionNames$1.includes(context.buffer[0])) {
-				const hasValue = valueParser != null ? context.state?.success || require_dependency.isDeferredParseState(context.state) || require_dependency.isDependencySourceState(context.state) : context.state?.success && context.state?.value;
-				if (hasValue) return {
+				if (hasParsedOptionValue(context.state, valueParser)) return {
 					success: false,
 					consumed: 1,
 					error: options.errors?.duplicate ? typeof options.errors.duplicate === "function" ? options.errors.duplicate(context.buffer[0]) : options.errors.duplicate : require_message.message`${require_message.optionName(context.buffer[0])} cannot be used multiple times.`
@@ -347,14 +401,17 @@ function option(...args) {
 					consumed: context.buffer.slice(0, 2)
 				};
 			}
-			const prefixes = optionNames$1.filter((name) => name.startsWith("--") || name.startsWith("/")).map((name) => name.startsWith("/") ? `${name}:` : `${name}=`);
+			const prefixes = optionNames$1.filter((name) => name.startsWith("--") || name.startsWith("/") || name.startsWith("-") && name.length > 2).map((name) => name.startsWith("/") ? `${name}:` : `${name}=`);
 			for (const prefix of prefixes) {
 				if (!context.buffer[0].startsWith(prefix)) continue;
-				if (context.state?.success && (valueParser != null || context.state.value)) return {
-					success: false,
-					consumed: 1,
-					error: options.errors?.duplicate ? typeof options.errors.duplicate === "function" ? options.errors.duplicate(prefix) : options.errors.duplicate : require_message.message`${require_message.optionName(prefix)} cannot be used multiple times.`
-				};
+				if (hasParsedOptionValue(context.state, valueParser)) {
+					const optionName$1 = prefix.slice(0, -1);
+					return {
+						success: false,
+						consumed: 1,
+						error: options.errors?.duplicate ? typeof options.errors.duplicate === "function" ? options.errors.duplicate(prefix) : options.errors.duplicate : require_message.message`${require_message.optionName(optionName$1)} cannot be used multiple times.`
+					};
+				}
 				const rawInput = context.buffer[0].slice(prefix.length);
 				if (valueParser == null) return {
 					success: false,
@@ -385,7 +442,7 @@ function option(...args) {
 				const shortOptions = optionNames$1.filter((name) => name.match(/^-[^-]$/));
 				for (const shortOption of shortOptions) {
 					if (!context.buffer[0].startsWith(shortOption)) continue;
-					if (context.state?.success && (valueParser != null || context.state.value)) return {
+					if (hasParsedOptionValue(context.state, valueParser)) return {
 						success: false,
 						consumed: 1,
 						error: options.errors?.duplicate ? typeof options.errors.duplicate === "function" ? options.errors.duplicate(shortOption) : options.errors.duplicate : require_message.message`${require_message.optionName(shortOption)} cannot be used multiple times.`
@@ -458,11 +515,11 @@ function option(...args) {
 			};
 		},
 		suggest(context, prefix) {
-			if (isAsync) return suggestOptionAsync(optionNames$1, valueParser, options.hidden ?? false, context, prefix);
-			return suggestOptionSync(optionNames$1, valueParser, options.hidden ?? false, context, prefix);
+			if (isAsync) return suggestOptionAsync(optionNames$1, valueParser, require_usage.isSuggestionHidden(options.hidden), context, prefix);
+			return suggestOptionSync(optionNames$1, valueParser, require_usage.isSuggestionHidden(options.hidden), context, prefix);
 		},
 		getDocFragments(_state, defaultValue) {
-			if (options.hidden) return {
+			if (require_usage.isDocHidden(options.hidden)) return {
 				fragments: [],
 				description: options.description
 			};
@@ -536,7 +593,7 @@ function flag(...args) {
 		usage: [{
 			type: "option",
 			names: optionNames$1,
-			...options.hidden && { hidden: true }
+			...options.hidden != null && { hidden: options.hidden }
 		}],
 		initialState: void 0,
 		parse(context) {
@@ -579,7 +636,7 @@ function flag(...args) {
 					consumed: context.buffer.slice(0, 1)
 				};
 			}
-			const prefixes = optionNames$1.filter((name) => name.startsWith("--") || name.startsWith("/")).map((name) => name.startsWith("/") ? `${name}:` : `${name}=`);
+			const prefixes = optionNames$1.filter((name) => name.startsWith("--") || name.startsWith("/") || name.startsWith("-") && name.length > 2).map((name) => name.startsWith("/") ? `${name}:` : `${name}=`);
 			for (const prefix of prefixes) if (context.buffer[0].startsWith(prefix)) {
 				const value = context.buffer[0].slice(prefix.length);
 				return {
@@ -643,7 +700,7 @@ function flag(...args) {
 			};
 		},
 		suggest(_context, prefix) {
-			if (options.hidden) return [];
+			if (require_usage.isSuggestionHidden(options.hidden)) return [];
 			const suggestions = [];
 			if (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/")) {
 				for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
@@ -657,7 +714,7 @@ function flag(...args) {
 			return suggestions;
 		},
 		getDocFragments(_state, _defaultValue) {
-			if (options.hidden) return {
+			if (require_usage.isDocHidden(options.hidden)) return {
 				fragments: [],
 				description: options.description
 			};
@@ -698,7 +755,7 @@ function argument(valueParser, options = {}) {
 	const term = {
 		type: "argument",
 		metavar: valueParser.metavar,
-		...options.hidden && { hidden: true }
+		...options.hidden != null && { hidden: options.hidden }
 	};
 	const result = {
 		$mode: valueParser.$mode,
@@ -787,11 +844,11 @@ function argument(valueParser, options = {}) {
 		},
 		suggest(context, prefix) {
 			if (context.state != null) return require_mode_dispatch.dispatchIterableByMode(valueParser.$mode, function* () {}, async function* () {});
-			if (isAsync) return suggestArgumentAsync(valueParser, options.hidden ?? false, prefix, context.dependencyRegistry);
-			return suggestArgumentSync(valueParser, options.hidden ?? false, prefix, context.dependencyRegistry);
+			if (isAsync) return suggestArgumentAsync(valueParser, require_usage.isSuggestionHidden(options.hidden), prefix, context.dependencyRegistry);
+			return suggestArgumentSync(valueParser, require_usage.isSuggestionHidden(options.hidden), prefix, context.dependencyRegistry);
 		},
 		getDocFragments(_state, defaultValue) {
-			if (options.hidden) return {
+			if (require_usage.isDocHidden(options.hidden)) return {
 				fragments: [],
 				description: options.description
 			};
@@ -815,7 +872,7 @@ function argument(valueParser, options = {}) {
 	return result;
 }
 function* suggestCommandSync(context, prefix, name, parser, options) {
-	if (options.hidden) return;
+	if (require_usage.isSuggestionHidden(options.hidden)) return;
 	if (context.state === void 0) {
 		if (name.startsWith(prefix)) yield {
 			kind: "literal",
@@ -832,7 +889,7 @@ function* suggestCommandSync(context, prefix, name, parser, options) {
 	}, prefix);
 }
 async function* suggestCommandAsync(context, prefix, name, parser, options) {
-	if (options.hidden) return;
+	if (require_usage.isSuggestionHidden(options.hidden)) return;
 	if (context.state === void 0) {
 		if (name.startsWith(prefix)) yield {
 			kind: "literal",
@@ -870,6 +927,7 @@ async function* suggestCommandAsync(context, prefix, name, parser, options) {
 function command(name, parser, options = {}) {
 	const isAsync = parser.$mode === "async";
 	const result = {
+		[Symbol.for("@optique/core/commandParser")]: true,
 		$mode: parser.$mode,
 		$valueType: [],
 		$stateType: [],
@@ -877,7 +935,8 @@ function command(name, parser, options = {}) {
 		usage: [{
 			type: "command",
 			name,
-			...options.hidden && { hidden: true }
+			...options.usageLine != null && { usageLine: options.usageLine },
+			...options.hidden != null && { hidden: options.hidden }
 		}, ...parser.usage],
 		initialState: void 0,
 		parse(context) {
@@ -977,7 +1036,7 @@ function command(name, parser, options = {}) {
 		},
 		getDocFragments(state, defaultValue) {
 			if (state.kind === "unavailable" || typeof state.state === "undefined") {
-				if (options.hidden) return {
+				if (require_usage.isDocHidden(options.hidden)) return {
 					fragments: [],
 					description: options.description
 				};
@@ -1071,7 +1130,7 @@ function passThrough(options = {}) {
 		priority: -10,
 		usage: [{
 			type: "passthrough",
-			...options.hidden && { hidden: true }
+			...options.hidden != null && { hidden: options.hidden }
 		}],
 		initialState: [],
 		parse(context) {
@@ -1088,7 +1147,7 @@ function passThrough(options = {}) {
 					next: {
 						...context,
 						buffer: [],
-						state: [...context.state, ...captured]
+						state: require_annotations.annotateFreshArray(context.state, [...context.state, ...captured])
 					},
 					consumed: captured
 				};
@@ -1109,7 +1168,7 @@ function passThrough(options = {}) {
 					next: {
 						...context,
 						buffer: context.buffer.slice(1),
-						state: [...context.state, token]
+						state: require_annotations.annotateFreshArray(context.state, [...context.state, token])
 					},
 					consumed: [token]
 				};
@@ -1125,7 +1184,7 @@ function passThrough(options = {}) {
 					next: {
 						...context,
 						buffer: context.buffer.slice(1),
-						state: [...context.state, token]
+						state: require_annotations.annotateFreshArray(context.state, [...context.state, token])
 					},
 					consumed: [token]
 				};
@@ -1135,11 +1194,11 @@ function passThrough(options = {}) {
 					next: {
 						...context,
 						buffer: context.buffer.slice(2),
-						state: [
+						state: require_annotations.annotateFreshArray(context.state, [
 							...context.state,
 							token,
 							nextToken
-						]
+						])
 					},
 					consumed: [token, nextToken]
 				};
@@ -1148,7 +1207,7 @@ function passThrough(options = {}) {
 					next: {
 						...context,
 						buffer: context.buffer.slice(1),
-						state: [...context.state, token]
+						state: require_annotations.annotateFreshArray(context.state, [...context.state, token])
 					},
 					consumed: [token]
 				};
@@ -1160,16 +1219,21 @@ function passThrough(options = {}) {
 			};
 		},
 		complete(state) {
-			return {
+			if (require_annotations.getAnnotations(state) == null) return {
 				success: true,
 				value: state
 			};
+			const copied = [...state];
+			return {
+				success: true,
+				value: copied
+			};
 		},
 		suggest(_context, _prefix) {
 			return [];
 		},
 		getDocFragments(_state, _defaultValue) {
-			if (options.hidden) return {
+			if (require_usage.isDocHidden(options.hidden)) return {
 				fragments: [],
 				description: options.description
 			};
@@ -1192,6 +1256,7 @@ function passThrough(options = {}) {
 exports.argument = argument;
 exports.command = command;
 exports.constant = constant;
+exports.fail = fail;
 exports.flag = flag;
 exports.option = option;
 exports.passThrough = passThrough;

package/dist/primitives.d.cts

@@ -1,5 +1,5 @@
 import { Message } from "./message.cjs";
-import { OptionName } from "./usage.cjs";
+import { HiddenVisibility, OptionName, Usage } from "./usage.cjs";
 import { ValueParser, ValueParserResult } from "./valueparser.cjs";
 import { DeferredParseState, PendingDependencySourceState } from "./dependency.cjs";
 import { Mode, Parser } from "./parser.cjs";
@@ -18,6 +18,26 @@ type OptionState<T> = ValueParserResult<T> | DeferredParseState<T> | PendingDepe
  * @template T The type of the constant value produced by the parser.
  */
 declare function constant<const T>(value: T): Parser<"sync", T, T>;
+/**
+ * Creates a parser that always fails without consuming any input.
+ *
+ * This is the counterpart to {@link constant}: while `constant(value)` always
+ * succeeds, `fail<T>()` always fails.  At the type level it is declared to
+ * produce a value of type `T`, so it composes seamlessly with other parsers
+ * that expect `Parser<"sync", T, …>`.
+ *
+ * The primary use case is as the inner parser for
+ * `bindConfig(fail<T>(), { … })` when a value should *only* come from a
+ * config file and has no corresponding CLI flag or argument.  Because `fail()`
+ * always fails, `bindConfig` will always fall back to the config file (or the
+ * supplied default).
+ *
+ * @template T The type of value this parser is declared to produce.
+ * @returns A {@link Parser} that always fails at parse time and always fails at
+ *          complete time.
+ * @since 1.0.0
+ */
+declare function fail<T>(): Parser<"sync", T, undefined>;
 /**
  * Options for the {@link option} parser.
  */
@@ -27,12 +47,16 @@ interface OptionOptions {
    */
   readonly description?: Message;
   /**
-   * When `true`, hides the option from help text, shell completion
-   * suggestions, and "Did you mean?" error suggestions. The option
-   * remains fully functional for parsing.
+   * Controls option visibility:
+   *
+   * - `true`: hide from usage, docs, and suggestions
+   * - `"usage"`: hide from usage only
+   * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
+   *
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
   /**
    * Error message customization options.
    * @since 0.5.0
@@ -84,7 +108,8 @@ interface OptionErrorOptions {
 }
 /**
  * Creates a parser for various styles of command-line options that take an
- * argument value, such as `--option=value`, `-o value`, or `/option:value`.
+ * argument value, such as `--option=value`, `-option=value`, `-o value`,
+ * or `/option:value`.
  * @template M The execution mode of the parser.
  * @template T The type of value this parser produces.
  * @param args The {@link OptionName}s to parse, followed by
@@ -97,7 +122,8 @@ interface OptionErrorOptions {
 declare function option<M extends Mode, T>(...args: readonly [...readonly OptionName[], ValueParser<M, T>]): Parser<M, T, ValueParserResult<T> | undefined>;
 /**
  * Creates a parser for various styles of command-line options that take an
- * argument value, such as `--option=value`, `-o value`, or `/option:value`.
+ * argument value, such as `--option=value`, `-option=value`, `-o value`,
+ * or `/option:value`.
  * @template M The execution mode of the parser.
  * @template T The type of value this parser produces.
  * @param args The {@link OptionName}s to parse, followed by
@@ -118,7 +144,8 @@ declare function option<M extends Mode, T>(...args: readonly [...readonly Option
 declare function option(...optionNames: readonly OptionName[]): Parser<"sync", boolean, ValueParserResult<boolean> | undefined>;
 /**
  * Creates a parser for various styles of command-line options that take an
- * argument value, such as `--option=value`, `-o value`, or `/option:value`.
+ * argument value, such as `--option=value`, `-option=value`, `-o value`,
+ * or `/option:value`.
  * @param args The {@link OptionName}s to parse, followed by
  *             an optional {@link OptionOptions} object that allows you to
  *             specify a description or other metadata.
@@ -135,12 +162,16 @@ interface FlagOptions {
    */
   readonly description?: Message;
   /**
-   * When `true`, hides the flag from help text, shell completion
-   * suggestions, and "Did you mean?" error suggestions. The flag
-   * remains fully functional for parsing.
+   * Controls flag visibility:
+   *
+   * - `true`: hide from usage, docs, and suggestions
+   * - `"usage"`: hide from usage only
+   * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
+   *
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
   /**
    * Error message customization options.
    * @since 0.5.0
@@ -221,12 +252,16 @@ interface ArgumentOptions {
    */
   readonly description?: Message;
   /**
-   * When `true`, hides the argument from help text, shell completion
-   * suggestions, and error suggestions. The argument remains fully
-   * functional for parsing.
+   * Controls argument visibility:
+   *
+   * - `true`: hide from usage, docs, and suggestions
+   * - `"usage"`: hide from usage only
+   * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
+   *
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
   /**
    * Error message customization options.
    * @since 0.5.0
@@ -292,12 +327,29 @@ interface CommandOptions {
    */
   readonly footer?: Message;
   /**
-   * When `true`, hides the command from help text, shell completion
-   * suggestions, and "Did you mean?" error suggestions. The command
-   * remains fully functional for parsing.
+   * Usage line override for this command's own help page.
+   *
+   * This option customizes the usage tail shown when rendering help for this
+   * command itself (e.g., `myapp config --help`). It does not change parsing
+   * behavior or shell completion.
+   *
+   * - `Usage`: Replaces the default usage tail.
+   * - `(defaultUsageLine) => Usage`: Computes the usage tail from the default.
+   *
+   * @since 1.0.0
+   */
+  readonly usageLine?: Usage | ((defaultUsageLine: Usage) => Usage);
+  /**
+   * Controls command visibility:
+   *
+   * - `true`: hide from usage, docs, and suggestions
+   * - `"usage"`: hide from usage only
+   * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
+   *
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
   /**
    * Error messages customization.
    * @since 0.5.0
@@ -376,11 +428,16 @@ interface PassThroughOptions {
    */
   readonly description?: Message;
   /**
-   * When `true`, hides the pass-through from help text and shell
-   * completion suggestions. The parser remains fully functional.
+   * Controls pass-through visibility:
+   *
+   * - `true`: hide from usage, docs, and suggestions
+   * - `"usage"`: hide from usage only
+   * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
+   *
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
 }
 /**
  * Creates a parser that collects unrecognized options and passes them through.
@@ -430,4 +487,4 @@ interface PassThroughOptions {
  */
 declare function passThrough(options?: PassThroughOptions): Parser<"sync", readonly string[], readonly string[]>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough };
+export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, option, passThrough };