@optique/core 0.5.1 → 0.6.0-dev.103

package/dist/constructs.js

@@ -74,6 +74,33 @@ function or(...args) {
 				success: false
 			};
 		},
+		suggest(context, prefix) {
+			const suggestions = [];
+			if (context.state == null) for (const parser of parsers) {
+				const parserSuggestions = parser.suggest({
+					...context,
+					state: parser.initialState
+				}, prefix);
+				suggestions.push(...parserSuggestions);
+			}
+			else {
+				const [index, parserResult] = context.state;
+				if (parserResult.success) {
+					const parserSuggestions = parsers[index].suggest({
+						...context,
+						state: parserResult.next.state
+					}, prefix);
+					suggestions.push(...parserSuggestions);
+				}
+			}
+			const seen = /* @__PURE__ */ new Set();
+			return suggestions.filter((suggestion) => {
+				const key = suggestion.kind === "literal" ? suggestion.text : `__FILE__:${suggestion.type}:${suggestion.extensions?.join(",")}:${suggestion.pattern}`;
+				if (seen.has(key)) return false;
+				seen.add(key);
+				return true;
+			});
+		},
 		getDocFragments(state, _defaultValue) {
 			let description;
 			let fragments;
@@ -182,6 +209,33 @@ function longestMatch(...args) {
 				success: false
 			};
 		},
+		suggest(context, prefix) {
+			const suggestions = [];
+			if (context.state == null) for (const parser of parsers) {
+				const parserSuggestions = parser.suggest({
+					...context,
+					state: parser.initialState
+				}, prefix);
+				suggestions.push(...parserSuggestions);
+			}
+			else {
+				const [index, parserResult] = context.state;
+				if (parserResult.success) {
+					const parserSuggestions = parsers[index].suggest({
+						...context,
+						state: parserResult.next.state
+					}, prefix);
+					suggestions.push(...parserSuggestions);
+				}
+			}
+			const seen = /* @__PURE__ */ new Set();
+			return suggestions.filter((suggestion) => {
+				const key = suggestion.kind === "literal" ? suggestion.text : `__FILE__:${suggestion.type}:${suggestion.extensions?.join(",")}:${suggestion.pattern}`;
+				if (seen.has(key)) return false;
+				seen.add(key);
+				return true;
+			});
+		},
 		getDocFragments(state, _defaultValue) {
 			let description;
 			let fragments;
@@ -302,6 +356,24 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				value: result
 			};
 		},
+		suggest(context, prefix) {
+			const suggestions = [];
+			for (const [field, parser] of parserPairs) {
+				const fieldState = context.state && typeof context.state === "object" && field in context.state ? context.state[field] : parser.initialState;
+				const fieldSuggestions = parser.suggest({
+					...context,
+					state: fieldState
+				}, prefix);
+				suggestions.push(...fieldSuggestions);
+			}
+			const seen = /* @__PURE__ */ new Set();
+			return suggestions.filter((suggestion) => {
+				const key = suggestion.kind === "literal" ? suggestion.text : `__FILE__:${suggestion.type}:${suggestion.extensions?.join(",")}:${suggestion.pattern}`;
+				if (seen.has(key)) return false;
+				seen.add(key);
+				return true;
+			});
+		},
 		getDocFragments(state, defaultValue) {
 			const fragments = parserPairs.flatMap(([field, p]) => {
 				const fieldState = state.kind === "unavailable" ? { kind: "unavailable" } : {
@@ -412,6 +484,25 @@ function tuple(labelOrParsers, maybeParsers) {
 				value: result
 			};
 		},
+		suggest(context, prefix) {
+			const suggestions = [];
+			for (let i = 0; i < parsers.length; i++) {
+				const parser = parsers[i];
+				const parserState = context.state && Array.isArray(context.state) ? context.state[i] : parser.initialState;
+				const parserSuggestions = parser.suggest({
+					...context,
+					state: parserState
+				}, prefix);
+				suggestions.push(...parserSuggestions);
+			}
+			const seen = /* @__PURE__ */ new Set();
+			return suggestions.filter((suggestion) => {
+				const key = suggestion.kind === "literal" ? suggestion.text : `__FILE__:${suggestion.type}:${suggestion.extensions?.join(",")}:${suggestion.pattern}`;
+				if (seen.has(key)) return false;
+				seen.add(key);
+				return true;
+			});
+		},
 		getDocFragments(state, defaultValue) {
 			const fragments = parsers.flatMap((p, i) => {
 				const indexState = state.kind === "unavailable" ? { kind: "unavailable" } : {
@@ -523,6 +614,35 @@ function merge(...args) {
 				value: object$1
 			};
 		},
+		suggest(context, prefix) {
+			const suggestions = [];
+			for (let i = 0; i < parsers.length; i++) {
+				const parser = parsers[i];
+				let parserState;
+				if (parser.initialState === void 0) {
+					const key = `__parser_${i}`;
+					if (context.state && typeof context.state === "object" && key in context.state) parserState = context.state[key];
+					else parserState = void 0;
+				} else if (parser.initialState && typeof parser.initialState === "object") if (context.state && typeof context.state === "object") {
+					const extractedState = {};
+					for (const field in parser.initialState) extractedState[field] = field in context.state ? context.state[field] : parser.initialState[field];
+					parserState = extractedState;
+				} else parserState = parser.initialState;
+				else parserState = parser.initialState;
+				const parserSuggestions = parser.suggest({
+					...context,
+					state: parserState
+				}, prefix);
+				suggestions.push(...parserSuggestions);
+			}
+			const seen = /* @__PURE__ */ new Set();
+			return suggestions.filter((suggestion) => {
+				const key = suggestion.kind === "literal" ? suggestion.text : `__FILE__:${suggestion.type}:${suggestion.extensions?.join(",")}:${suggestion.pattern}`;
+				if (seen.has(key)) return false;
+				seen.add(key);
+				return true;
+			});
+		},
 		getDocFragments(state, _defaultValue) {
 			const fragments = parsers.flatMap((p) => {
 				const parserState = p.initialState === void 0 ? { kind: "unavailable" } : state.kind === "unavailable" ? { kind: "unavailable" } : {
@@ -641,6 +761,25 @@ function concat(...parsers) {
 				value: results
 			};
 		},
+		suggest(context, prefix) {
+			const suggestions = [];
+			for (let i = 0; i < parsers.length; i++) {
+				const parser = parsers[i];
+				const parserState = context.state && Array.isArray(context.state) ? context.state[i] : parser.initialState;
+				const parserSuggestions = parser.suggest({
+					...context,
+					state: parserState
+				}, prefix);
+				suggestions.push(...parserSuggestions);
+			}
+			const seen = /* @__PURE__ */ new Set();
+			return suggestions.filter((suggestion) => {
+				const key = suggestion.kind === "literal" ? suggestion.text : `__FILE__:${suggestion.type}:${suggestion.extensions?.join(",")}:${suggestion.pattern}`;
+				if (seen.has(key)) return false;
+				seen.add(key);
+				return true;
+			});
+		},
 		getDocFragments(state, _defaultValue) {
 			const fragments = parsers.flatMap((p, index) => {
 				const indexState = state.kind === "unavailable" ? { kind: "unavailable" } : {
@@ -719,6 +858,7 @@ function group(label, parser) {
 		initialState: parser.initialState,
 		parse: (context) => parser.parse(context),
 		complete: (state) => parser.complete(state),
+		suggest: (context, prefix) => parser.suggest(context, prefix),
 		getDocFragments: (state, defaultValue) => {
 			const { description, fragments } = parser.getDocFragments(state, defaultValue);
 			const allEntries = [];

package/dist/facade.cjs

@@ -2,6 +2,7 @@ const require_message = require('./message.cjs');
 const require_constructs = require('./constructs.cjs');
 const require_usage = require('./usage.cjs');
 const require_doc = require('./doc.cjs');
+const require_completion = require('./completion.cjs');
 const require_modifiers = require('./modifiers.cjs');
 const require_valueparser = require('./valueparser.cjs');
 const require_primitives = require('./primitives.cjs');
@@ -118,6 +119,13 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers) {
 					value: state
 				};
 			},
+			suggest(_context, prefix) {
+				if ("--help".startsWith(prefix)) return [{
+					kind: "literal",
+					text: "--help"
+				}];
+				return [];
+			},
 			getDocFragments(state) {
 				return helpParsers.helpOption?.getDocFragments(state) ?? { fragments: [] };
 			}
@@ -179,6 +187,13 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers) {
 					value: state
 				};
 			},
+			suggest(_context, prefix) {
+				if ("--version".startsWith(prefix)) return [{
+					kind: "literal",
+					text: "--version"
+				}];
+				return [];
+			},
 			getDocFragments(state) {
 				return versionParsers.versionOption?.getDocFragments(state) ?? { fragments: [] };
 			}
@@ -213,9 +228,9 @@ function classifyResult(result, args) {
 		type: "error",
 		error: result.error
 	};
-	const value = result.value;
-	if (typeof value === "object" && value != null && "help" in value && "version" in value) {
-		const parsedValue = value;
+	const value$1 = result.value;
+	if (typeof value$1 === "object" && value$1 != null && "help" in value$1 && "version" in value$1) {
+		const parsedValue = value$1;
 		const hasVersionOption = args.includes("--version");
 		const hasVersionCommand = args.length > 0 && args[0] === "version";
 		const hasHelpOption = args.includes("--help");
@@ -237,15 +252,53 @@ function classifyResult(result, args) {
 		if ((hasVersionOption || hasVersionCommand) && (parsedValue.version || parsedValue.versionFlag)) return { type: "version" };
 		return {
 			type: "success",
-			value: parsedValue.result ?? value
+			value: parsedValue.result ?? value$1
 		};
 	}
 	return {
 		type: "success",
-		value
+		value: value$1
 	};
 }
 /**
+* Handles shell completion requests.
+* @since 0.6.0
+*/
+function handleCompletion(completionArgs, programName, parser, stdout, stderr, onCompletion, onError, availableShells, colors) {
+	if (completionArgs.length === 0) {
+		stderr("Error: Missing shell name for completion.\n");
+		stderr("Usage: " + programName + " completion <shell> [args...]\n");
+		return onError(1);
+	}
+	const shellName = completionArgs[0];
+	const args = completionArgs.slice(1);
+	const shell = availableShells[shellName];
+	if (!shell) {
+		const available = [];
+		for (const shell$1 in availableShells) {
+			if (available.length > 0) available.push(require_message.text(", "));
+			available.push(require_message.value(shell$1));
+		}
+		stderr(require_message.formatMessage(require_message.message`Error: Unsupported shell ${shellName}. Available shells: ${available}.`, {
+			colors,
+			quotes: !colors
+		}));
+		return onError(1);
+	}
+	if (args.length === 0) {
+		const script = shell.generateScript(programName, ["completion", shellName]);
+		stdout(script);
+	} else {
+		const suggestions = require_parser.suggest(parser, args);
+		for (const chunk of shell.encodeSuggestions(suggestions)) stdout(chunk);
+	}
+	try {
+		return onCompletion(0);
+	} catch {
+		return onCompletion();
+	}
+}
+/**
 * Runs a parser against command-line arguments with built-in help and error
 * handling.
 *
@@ -275,14 +328,41 @@ function classifyResult(result, args) {
 * @throws {RunError} When parsing fails and no `onError` callback is provided.
 */
 function run(parser, programName, args, options = {}) {
+	let { colors, maxWidth, showDefault, aboveError = "usage", onError = () => {
+		throw new RunError("Failed to parse command line arguments.");
+	}, stderr = console.error, stdout = console.log, brief, description, footer } = options;
+	const completionMode = options.completion?.mode ?? "both";
+	const onCompletion = options.completion?.onShow ?? (() => ({}));
+	if (options.completion) {
+		const defaultShells = {
+			bash: require_completion.bash,
+			fish: require_completion.fish,
+			pwsh: require_completion.pwsh,
+			zsh: require_completion.zsh
+		};
+		const availableShells = options.completion.shells ? {
+			...defaultShells,
+			...options.completion.shells
+		} : defaultShells;
+		if ((completionMode === "command" || completionMode === "both") && args.length >= 1 && args[0] === "completion") return handleCompletion(args.slice(1), programName, parser, stdout, stderr, onCompletion, onError, availableShells, colors);
+		if (completionMode === "option" || completionMode === "both") for (let i = 0; i < args.length; i++) {
+			const arg = args[i];
+			if (arg.startsWith("--completion=")) {
+				const shell = arg.slice(13);
+				const completionArgs = args.slice(i + 1);
+				return handleCompletion([shell, ...completionArgs], programName, parser, stdout, stderr, onCompletion, onError, availableShells, colors);
+			} else if (arg === "--completion" && i + 1 < args.length) {
+				const shell = args[i + 1];
+				const completionArgs = args.slice(i + 2);
+				return handleCompletion([shell, ...completionArgs], programName, parser, stdout, stderr, onCompletion, onError, availableShells, colors);
+			}
+		}
+	}
 	const helpMode = options.help?.mode ?? "option";
 	const onHelp = options.help?.onShow ?? (() => ({}));
 	const versionMode = options.version?.mode ?? "option";
 	const versionValue = options.version?.value ?? "";
 	const onVersion = options.version?.onShow ?? (() => ({}));
-	let { colors, maxWidth, showDefault, aboveError = "usage", onError = () => {
-		throw new RunError("Failed to parse command line arguments.");
-	}, stderr = console.error, stdout = console.log, brief, description, footer } = options;
 	const help = options.help ? helpMode : "none";
 	const version = options.version ? versionMode : "none";
 	const helpParsers = help === "none" ? {
@@ -345,36 +425,38 @@ function run(parser, programName, args, options = {}) {
 				return onHelp();
 			}
 		}
-		case "error": break;
-	}
-	if (aboveError === "help") {
-		const doc = require_parser.getDocPage(args.length < 1 ? augmentedParser : parser, args);
-		if (doc == null) aboveError = "usage";
-		else {
-			const augmentedDoc = {
-				...doc,
-				brief: brief ?? doc.brief,
-				description: description ?? doc.description,
-				footer: footer ?? doc.footer
-			};
-			stderr(require_doc.formatDocPage(programName, augmentedDoc, {
+		case "error": {
+			if (aboveError === "help") {
+				const doc = require_parser.getDocPage(args.length < 1 ? augmentedParser : parser, args);
+				if (doc == null) aboveError = "usage";
+				else {
+					const augmentedDoc = {
+						...doc,
+						brief: brief ?? doc.brief,
+						description: description ?? doc.description,
+						footer: footer ?? doc.footer
+					};
+					stderr(require_doc.formatDocPage(programName, augmentedDoc, {
+						colors,
+						maxWidth,
+						showDefault
+					}));
+				}
+			}
+			if (aboveError === "usage") stderr(`Usage: ${indentLines(require_usage.formatUsage(programName, augmentedParser.usage, {
+				colors,
+				maxWidth: maxWidth == null ? void 0 : maxWidth - 7,
+				expandCommands: true
+			}), 7)}`);
+			const errorMessage = require_message.formatMessage(classified.error, {
 				colors,
-				maxWidth,
-				showDefault
-			}));
+				quotes: !colors
+			});
+			stderr(`Error: ${errorMessage}`);
+			return onError(1);
 		}
+		default: throw new RunError("Unexpected parse result type");
 	}
-	if (aboveError === "usage") stderr(`Usage: ${indentLines(require_usage.formatUsage(programName, augmentedParser.usage, {
-		colors,
-		maxWidth: maxWidth == null ? void 0 : maxWidth - 7,
-		expandCommands: true
-	}), 7)}`);
-	const errorMessage = require_message.formatMessage(classified.error, {
-		colors,
-		quotes: !colors
-	});
-	stderr(`Error: ${errorMessage}`);
-	return onError(1);
 }
 /**
 * An error class used to indicate that the command line arguments
@@ -386,8 +468,8 @@ var RunError = class extends Error {
 		this.name = "RunError";
 	}
 };
-function indentLines(text, indent) {
-	return text.split("\n").join("\n" + " ".repeat(indent));
+function indentLines(text$1, indent) {
+	return text$1.split("\n").join("\n" + " ".repeat(indent));
 }
 
 //#endregion

package/dist/facade.d.cts

@@ -1,6 +1,7 @@
 import { Message } from "./message.cjs";
 import { ShowDefaultOptions } from "./doc.cjs";
 import { InferValue, Parser } from "./parser.cjs";
+import { ShellCompletion } from "./completion.cjs";
 
 //#region src/facade.d.ts
 
@@ -88,6 +89,40 @@ interface RunOptions<THelp, TError> {
      */
     readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
   };
+  /**
+   * Completion configuration. When provided, enables shell completion functionality.
+   * @since 0.6.0
+   */
+  readonly completion?: {
+    /**
+     * Determines how completion is made available:
+     *
+     * - `"command"`: Only the `completion` subcommand is available
+     * - `"option"`: Only the `--completion` option is available
+     * - `"both"`: Both `completion` subcommand and `--completion` option are available
+     *
+     * @default `"both"`
+     */
+    readonly mode?: "command" | "option" | "both";
+    /**
+     * Available shell completions. By default, includes `bash`, `fish`, `pwsh`,
+     * and `zsh`. You can provide additional custom shell completions or override
+     * the defaults.
+     *
+     * @default `{ bash, fish, pwsh, zsh }`
+     */
+    readonly shells?: Record<string, ShellCompletion>;
+    /**
+     * Callback function invoked when completion is requested. The function can
+     * optionally receive an exit code parameter.
+     *
+     * You usually want to pass `process.exit` on Node.js or Bun and `Deno.exit`
+     * on Deno to this option.
+     *
+     * @default Returns `void` when completion is shown.
+     */
+    readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
+  };
   /**
    * What to display above error messages:
    * - `"usage"`: Show usage information

package/dist/facade.d.ts

@@ -1,6 +1,7 @@
 import { Message } from "./message.js";
 import { ShowDefaultOptions } from "./doc.js";
 import { InferValue, Parser } from "./parser.js";
+import { ShellCompletion } from "./completion.js";
 
 //#region src/facade.d.ts
 
@@ -88,6 +89,40 @@ interface RunOptions<THelp, TError> {
      */
     readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
   };
+  /**
+   * Completion configuration. When provided, enables shell completion functionality.
+   * @since 0.6.0
+   */
+  readonly completion?: {
+    /**
+     * Determines how completion is made available:
+     *
+     * - `"command"`: Only the `completion` subcommand is available
+     * - `"option"`: Only the `--completion` option is available
+     * - `"both"`: Both `completion` subcommand and `--completion` option are available
+     *
+     * @default `"both"`
+     */
+    readonly mode?: "command" | "option" | "both";
+    /**
+     * Available shell completions. By default, includes `bash`, `fish`, `pwsh`,
+     * and `zsh`. You can provide additional custom shell completions or override
+     * the defaults.
+     *
+     * @default `{ bash, fish, pwsh, zsh }`
+     */
+    readonly shells?: Record<string, ShellCompletion>;
+    /**
+     * Callback function invoked when completion is requested. The function can
+     * optionally receive an exit code parameter.
+     *
+     * You usually want to pass `process.exit` on Node.js or Bun and `Deno.exit`
+     * on Deno to this option.
+     *
+     * @default Returns `void` when completion is shown.
+     */
+    readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
+  };
   /**
    * What to display above error messages:
    * - `"usage"`: Show usage information