@clo4/cli 1.0.0 → 2.0.0

package/dist/index.js

@@ -1,5 +1,3 @@
-// \0rolldown/runtime.js
-var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod, mod.exports), cb = null), mod.exports);
 // src/util.ts
 function isArray(o) {
 	return Array.isArray(o);
@@ -25,247 +23,65 @@ function makeArray1(thing) {
 	if (isArray(thing)) return thing.slice();
 	return [thing];
 }
-/** Set many keys in a Map to the same value */
-function setEach(map, keys, value) {
-	if (isArray(keys)) for (const key of keys) map.set(key, value);
-	else map.set(keys, value);
-}
-function assert(expr, msg = "") {
-	if (!expr) throw new Error(msg);
+const nodeProcess = globalThis.process;
+/**
+* Write text to stdout (1) or stderr (2) with a synchronous `write` on the file
+* descriptor.
+*
+* The first `console.log` in a Node process builds the stdout stream, which
+* costs 1-3 ms. That's more than parsing takes, so all of this library's output
+* goes through here instead. Without `node:fs` it falls back to `console`.
+*/
+function writeFd(fd, text) {
+	const fs = nodeProcess?.getBuiltinModule?.("node:fs");
+	if (!fs) {
+		(fd === 1 ? console.log : console.error)(text.endsWith("\n") ? text.slice(0, -1) : text);
+		return;
+	}
+	const bytes = new TextEncoder().encode(text);
+	let offset = 0;
+	try {
+		while (offset < bytes.length) offset += fs.writeSync(fd, bytes, offset, bytes.length - offset);
+	} catch (error) {
+		if (error.code === "EAGAIN") (fd === 1 ? nodeProcess?.stdout : nodeProcess?.stderr)?.write(bytes.subarray(offset));
+	}
 }
+/**
+* Where this library's output goes. Tests replace `write` to capture output.
+*
+* @internal
+*/
+const output = { write: writeFd };
 /** Print a message to stdout, trimming trailing whitespace. */
 function print(text) {
-	console.log(text.trimEnd());
+	output.write(1, `${text.trimEnd()}\n`);
 }
 /** Print an error message to stderr with the shared `Error:` prefix. */
 function printActionError(message) {
-	console.error("Error:", message);
+	output.write(2, `Error: ${message}\n`);
 }
-// src/analyze.ts
-const $optionArg = (index, start, end, literal, option, separator) => ({
-	kind: "option-arg",
-	index,
-	literal,
-	start,
-	end,
-	option,
-	separator
-});
-const $unknownOption = (index, start, end, literal, validOptions) => ({
-	kind: "unknown-option",
-	index,
-	start,
-	end,
-	literal,
-	validOptions
-});
-const $arg = (index, start, end, literal) => ({
-	kind: "arg",
-	index,
-	start,
-	end,
-	literal
-});
-const $argSeparator = (index, start, end, literal) => ({
-	kind: "arg-separator",
-	index,
-	start,
-	end,
-	literal
-});
-const $subcommand = (index, start, end, literal, subcommand) => {
-	return {
-		kind: "subcommand",
-		index,
-		start,
-		end,
-		literal,
-		subcommand
-	};
-};
-const $option = (index, start, end, literal, option) => {
-	return {
-		kind: "option",
-		index,
-		start,
-		end,
-		literal,
-		option
-	};
-};
 /**
-* Lex the input, output some tokens
+* Returns the minimum number of arguments that satisfies the args.
 *
-* This generator uses the options and subcommands to categorize the
-* input tokens. It will not track or reject arguments - tokens that
-* don't match an option or subcommand are yielded as arguments.
+* Accepts the raw spec value (a single arg, an array, or `undefined`) so the
+* hot path doesn't have to copy it into an array first.
 */
-function analyze(input, spec) {
-	const tokens = [];
-	if (input.length === 0) {
-		const localOptions = /* @__PURE__ */ new Map();
-		const localRequiredOptions = /* @__PURE__ */ new Map();
-		const persistentOptions = /* @__PURE__ */ new Map();
-		const persistentRequiredOptions = /* @__PURE__ */ new Map();
-		if (spec.options) for (const option of spec.options) if (option.isPersistent) {
-			setEach(persistentOptions, option.name, option);
-			if (option.isRequired) setEach(persistentRequiredOptions, option.name, option);
-		} else {
-			setEach(localOptions, option.name, option);
-			if (option.isRequired) setEach(localRequiredOptions, option.name, option);
-		}
-		return {
-			finalState: {
-				localOptions,
-				persistentOptions,
-				localRequiredOptions,
-				persistentRequiredOptions
-			},
-			tokens
-		};
-	}
-	let localSubcommands;
-	const localOptions = /* @__PURE__ */ new Map();
-	const persistentOptions = /* @__PURE__ */ new Map();
-	const localRequiredOptions = /* @__PURE__ */ new Map();
-	const persistentRequiredOptions = /* @__PURE__ */ new Map();
-	let separators = ["="];
-	let hasFoundArg = false;
-	let posixCompliantOptions = true;
-	let subcommandsMatchUniquePrefix = false;
-	let optionsMustPrecedeArguments = false;
-	let hasUsedNonPersistentOption = false;
-	const getOption = (name) => localOptions.get(name) ?? persistentOptions.get(name) ?? null;
-	const hasOption = (name) => localOptions.has(name) || persistentOptions.has(name);
-	const getSubcommand = (name) => {
-		if (!localSubcommands) return null;
-		let prefixMatch = null;
-		let prefixCount = 0;
-		for (const command of localSubcommands) {
-			const names = typeof command.name === "string" ? [command.name] : command.name;
-			for (const cmdName of names) {
-				if (cmdName === name) return command;
-				if (subcommandsMatchUniquePrefix && cmdName.startsWith(name)) {
-					prefixMatch = command;
-					prefixCount += 1;
-					break;
-				}
-			}
-		}
-		return prefixCount === 1 ? prefixMatch : null;
-	};
-	const updateCurrentCommand = (command) => {
-		if (command.options) for (const option of command.options) if (option.isPersistent) {
-			setEach(persistentOptions, option.name, option);
-			if (option.isRequired) setEach(persistentRequiredOptions, option.name, option);
-		} else {
-			setEach(localOptions, option.name, option);
-			if (option.isRequired) setEach(localRequiredOptions, option.name, option);
-		}
-		localSubcommands = command.subcommands;
-		const directives = command.parserDirectives;
-		if (directives?.optionArgSeparators) separators = asArray(directives.optionArgSeparators);
-		if (directives?.subcommandsMatchUniquePrefix) subcommandsMatchUniquePrefix = directives.subcommandsMatchUniquePrefix;
-		if (directives?.optionsMustPrecedeArguments) optionsMustPrecedeArguments = directives.optionsMustPrecedeArguments;
-		if (typeof directives?.flagsArePosixNoncompliant === "boolean") posixCompliantOptions = !directives.flagsArePosixNoncompliant;
-	};
-	updateCurrentCommand(spec);
-	tokens: for (let index = 0; index < input.length; index++) {
-		const token = input[index];
-		if (token === "--") {
-			tokens.push($argSeparator(index, 0, token.length, token));
-			index += 1;
-			for (; index < input.length; index++) {
-				const tok = input[index];
-				tokens.push($arg(index, 0, tok.length, tok));
-			}
-			break tokens;
-		}
-		if (!hasFoundArg && !hasUsedNonPersistentOption && localSubcommands) {
-			const command = getSubcommand(token);
-			if (command) {
-				localOptions.clear();
-				updateCurrentCommand(command);
-				tokens.push($subcommand(index, 0, token.length, token, command));
-				continue tokens;
-			}
-		}
-		if (!(optionsMustPrecedeArguments && hasFoundArg)) {
-			if (posixCompliantOptions && token.length > 1 && (token.startsWith("-") || token.startsWith("+")) && !token.startsWith("--")) {
-				const leadingChar = token[0];
-				const dashOption = getOption(leadingChar);
-				if (dashOption?.args && !hasOption(token.slice(0, 2))) {
-					tokens.push($option(index, 0, 1, leadingChar, dashOption));
-					tokens.push($optionArg(index, 1, token.length, token.slice(1), leadingChar, ""));
-					continue tokens;
-				}
-				chars: for (let char = 1; char < token.length; char++) {
-					const optionName = `${leadingChar}${token[char]}`;
-					const option = getOption(optionName);
-					if (!option) {
-						tokens.push($unknownOption(index, char, char + 1, optionName, [...localOptions.keys(), ...persistentOptions.keys()]));
-						continue chars;
-					}
-					if (!hasUsedNonPersistentOption && !option.isPersistent) hasUsedNonPersistentOption = true;
-					tokens.push($option(index, char, char + 1, optionName, option));
-					if (option.args && char < token.length - 1) {
-						const remainingChars = token.slice(char + 1);
-						const sep = separators.find((sep) => remainingChars.startsWith(sep)) || "";
-						const argStartOffset = char + sep.length;
-						tokens.push($optionArg(index, argStartOffset + 1, token.length, token.slice(argStartOffset + 1), optionName, sep));
-						break;
-					}
-				}
-				continue tokens;
-			}
-			if (!posixCompliantOptions || token.length > 2 && token.startsWith("--")) {
-				let foundSep = null;
-				let foundSepIndex = -1;
-				separators: for (const sep of separators) {
-					const index = token.indexOf(sep);
-					if (index === -1) continue separators;
-					foundSep = sep;
-					foundSepIndex = index;
-				}
-				if (foundSep) {
-					const optionName = token.slice(0, foundSepIndex);
-					const option = getOption(optionName);
-					if (option) {
-						if (!hasUsedNonPersistentOption && !option.isPersistent) hasUsedNonPersistentOption = true;
-						tokens.push($option(index, 0, foundSepIndex, token.slice(0, foundSepIndex), option));
-						tokens.push($optionArg(index, foundSepIndex + foundSep.length, token.length, token.slice(foundSepIndex + foundSep.length), optionName, foundSep));
-						continue tokens;
-					} else if (posixCompliantOptions) {
-						const optionName = token.slice(0, foundSepIndex);
-						tokens.push($unknownOption(index, 0, foundSepIndex, optionName, [...localOptions.keys(), ...persistentOptions.keys()]));
-						tokens.push($optionArg(index, foundSepIndex + foundSep.length, token.length, token.slice(foundSepIndex + foundSep.length), optionName, foundSep));
-						continue tokens;
-					}
-				} else {
-					const option = getOption(token);
-					if (option) {
-						if (!hasUsedNonPersistentOption && !option.isPersistent) hasUsedNonPersistentOption = true;
-						tokens.push($option(index, 0, token.length, token, option));
-						continue tokens;
-					} else if (posixCompliantOptions) {
-						tokens.push($unknownOption(index, 0, token.length, token, [...localOptions.keys(), ...persistentOptions.keys()]));
-						continue tokens;
-					}
-				}
-			}
-		}
-		if (!hasFoundArg) hasFoundArg = true;
-		tokens.push($arg(index, 0, token.length, token));
+function getMinArgs(args) {
+	if (args === void 0) return 0;
+	if (!isArray(args)) return args.isOptional ? 0 : 1;
+	let count = 0;
+	for (let i = 0; i < args.length; i++) {
+		if (args[i].isOptional) break;
+		count++;
 	}
-	return {
-		finalState: {
-			localOptions,
-			persistentOptions,
-			localRequiredOptions,
-			persistentRequiredOptions
-		},
-		tokens
-	};
+	return count;
+}
+/** Returns the maximum number of arguments that satisfies the args. */
+function getMaxArgs(args) {
+	if (args === void 0) return 0;
+	if (!isArray(args)) return args.isVariadic ? Infinity : 1;
+	for (let i = 0; i < args.length; i++) if (args[args.length - 1 - i].isVariadic) return Infinity;
+	return args.length;
 }
 // src/errors.ts
 const repr = JSON.stringify;
@@ -283,14 +99,14 @@ var UnknownOption = class extends ParseError {
 	end;
 	option;
 	validOptions;
-	constructor(token, context) {
-		const msg = `${repr(token.literal)} looks like a flag, but is unknown in this context`;
+	constructor(found, context) {
+		const msg = `${repr(found.option)} looks like a flag, but is unknown in this context`;
 		super(context, msg);
-		this.option = token.literal;
-		this.validOptions = token.validOptions;
-		this.index = token.index;
-		this.start = token.start;
-		this.end = token.end;
+		this.option = found.option;
+		this.validOptions = found.validOptions;
+		this.index = found.index;
+		this.start = found.start;
+		this.end = found.end;
 	}
 };
 var InvalidOptionArg = class extends ParseError {
@@ -299,24 +115,24 @@ var InvalidOptionArg = class extends ParseError {
 	end;
 	arg;
 	option;
-	constructor(token, context) {
-		const msg = `Option ${token.option} doesn't take arguments`;
+	constructor(found, context) {
+		const msg = `Option ${found.option} doesn't take arguments`;
 		super(context, msg);
-		this.index = token.index;
-		this.start = token.start;
-		this.end = token.end;
-		this.option = token.option;
-		this.arg = token.literal;
+		this.index = found.index;
+		this.start = found.start;
+		this.end = found.end;
+		this.option = found.option;
+		this.arg = found.arg;
 	}
 };
 var TooManyArguments = class extends ParseError {
 	index;
 	value;
-	constructor(token, context) {
-		const msg = `Too many arguments, ${repr(token.literal)} was unexpected`;
+	constructor(found, context) {
+		const msg = `Too many arguments, ${repr(found.value)} was unexpected`;
 		super(context, msg);
-		this.index = token.index;
-		this.value = token.literal;
+		this.index = found.index;
+		this.value = found.value;
 	}
 };
 var TooFewOptionArguments = class extends ParseError {
@@ -337,122 +153,101 @@ var MissingRequiredOption = class extends ParseError {
 		super(context, msg);
 	}
 };
-// src/help.ts
-var import_fastest_levenshtein = (/* @__PURE__ */ __commonJSMin(((exports) => {
-	exports.__esModule = true;
-	exports.distance = exports.closest = void 0;
-	var peq = /* @__PURE__ */ new Uint32Array(65536);
-	var myers_32 = function(a, b) {
-		var n = a.length;
-		var m = b.length;
-		var lst = 1 << n - 1;
-		var pv = -1;
-		var mv = 0;
-		var sc = n;
-		var i = n;
-		while (i--) peq[a.charCodeAt(i)] |= 1 << i;
-		for (i = 0; i < m; i++) {
-			var eq = peq[b.charCodeAt(i)];
-			var xv = eq | mv;
-			eq |= (eq & pv) + pv ^ pv;
-			mv |= ~(eq | pv);
-			pv &= eq;
-			if (mv & lst) sc++;
-			if (pv & lst) sc--;
-			mv = mv << 1 | 1;
-			pv = pv << 1 | ~(xv | mv);
-			mv &= xv;
-		}
-		i = n;
-		while (i--) peq[a.charCodeAt(i)] = 0;
-		return sc;
-	};
-	var myers_x = function(b, a) {
-		var n = a.length;
-		var m = b.length;
-		var mhc = [];
-		var phc = [];
-		var hsize = Math.ceil(n / 32);
-		var vsize = Math.ceil(m / 32);
-		for (var i = 0; i < hsize; i++) {
-			phc[i] = -1;
-			mhc[i] = 0;
-		}
-		var j = 0;
-		for (; j < vsize - 1; j++) {
-			var mv_1 = 0;
-			var pv_1 = -1;
-			var start_1 = j * 32;
-			var vlen_1 = Math.min(32, m) + start_1;
-			for (var k = start_1; k < vlen_1; k++) peq[b.charCodeAt(k)] |= 1 << k;
-			for (var i = 0; i < n; i++) {
-				var eq = peq[a.charCodeAt(i)];
-				var pb = phc[i / 32 | 0] >>> i & 1;
-				var mb = mhc[i / 32 | 0] >>> i & 1;
-				var xv = eq | mv_1;
-				var xh = ((eq | mb) & pv_1) + pv_1 ^ pv_1 | eq | mb;
-				var ph = mv_1 | ~(xh | pv_1);
-				var mh = pv_1 & xh;
-				if (ph >>> 31 ^ pb) phc[i / 32 | 0] ^= 1 << i;
-				if (mh >>> 31 ^ mb) mhc[i / 32 | 0] ^= 1 << i;
-				ph = ph << 1 | pb;
-				mh = mh << 1 | mb;
-				pv_1 = mh | ~(xv | ph);
-				mv_1 = ph & xv;
-			}
-			for (var k = start_1; k < vlen_1; k++) peq[b.charCodeAt(k)] = 0;
+// src/suggest.ts
+/**
+* "Did you mean" suggestions for unknown commands and options.
+*
+* This only runs after a mistake, but it's loaded on every run, so it's kept
+* small and does nothing until it's called.
+*
+* @module
+*/
+/** How many `-` or `+` characters `name` starts with. */
+function dashCount(name) {
+	let i = 0;
+	while (i < name.length && (name[i] === "-" || name[i] === "+")) i++;
+	return i;
+}
+/** Whether every character of `short` appears in `long`, in order. */
+function isAbbreviation(short, long) {
+	let i = 0;
+	for (let j = 0; j < long.length && i < short.length; j++) if (long[j] === short[i]) i++;
+	return i === short.length;
+}
+/**
+* Levenshtein distance where swapping two adjacent characters also counts as
+* one edit (optimal string alignment). Returns `limit + 1` as soon as the
+* distance must be larger than `limit`.
+*/
+function editDistance(a, b, limit) {
+	let before = new Uint32Array(b.length + 1);
+	let previous = new Uint32Array(b.length + 1);
+	let current = new Uint32Array(b.length + 1);
+	for (let j = 0; j <= b.length; j++) previous[j] = j;
+	for (let i = 1; i <= a.length; i++) {
+		current[0] = i;
+		let rowMin = i;
+		for (let j = 1; j <= b.length; j++) {
+			const substitution = previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1);
+			let d = Math.min(previous[j] + 1, current[j - 1] + 1, substitution);
+			if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) d = Math.min(d, before[j - 2] + 1);
+			current[j] = d;
+			if (d < rowMin) rowMin = d;
 		}
-		var mv = 0;
-		var pv = -1;
-		var start = j * 32;
-		var vlen = Math.min(32, m - start) + start;
-		for (var k = start; k < vlen; k++) peq[b.charCodeAt(k)] |= 1 << k;
-		var score = m;
-		for (var i = 0; i < n; i++) {
-			var eq = peq[a.charCodeAt(i)];
-			var pb = phc[i / 32 | 0] >>> i & 1;
-			var mb = mhc[i / 32 | 0] >>> i & 1;
-			var xv = eq | mv;
-			var xh = ((eq | mb) & pv) + pv ^ pv | eq | mb;
-			var ph = mv | ~(xh | pv);
-			var mh = pv & xh;
-			score += ph >>> m - 1 & 1;
-			score -= mh >>> m - 1 & 1;
-			if (ph >>> 31 ^ pb) phc[i / 32 | 0] ^= 1 << i;
-			if (mh >>> 31 ^ mb) mhc[i / 32 | 0] ^= 1 << i;
-			ph = ph << 1 | pb;
-			mh = mh << 1 | mb;
-			pv = mh | ~(xv | ph);
-			mv = ph & xv;
+		if (rowMin > limit) return limit + 1;
+		const recycled = before;
+		before = previous;
+		previous = current;
+		current = recycled;
+	}
+	return previous[b.length];
+}
+/**
+* The choice the user most likely meant by `input`, or `undefined` if none is
+* close enough to be worth suggesting. In order:
+*
+* 1. The only choice that starts with the input (`--verb` for `--verbose`).
+* 2. The only choice that contains every character of the input in order, for
+*    inputs of 3 or more characters (`bld` for `build`).
+* 3. The choice with the fewest edits, allowing one edit per three characters
+*    of the input. Leading dashes don't count toward the length or the edits.
+*/
+function closestChoice(input, choices) {
+	const inputDashes = dashCount(input);
+	const bare = input.slice(inputDashes);
+	if (bare.length >= 2) {
+		let match;
+		let count = 0;
+		for (const choice of choices) if (choice.startsWith(input)) {
+			match = choice;
+			count++;
 		}
-		for (var k = start; k < vlen; k++) peq[b.charCodeAt(k)] = 0;
-		return score;
-	};
-	var distance = function(a, b) {
-		if (a.length < b.length) {
-			var tmp = b;
-			b = a;
-			a = tmp;
+		if (count === 1) return match;
+	}
+	if (bare.length >= 3) {
+		let match;
+		let count = 0;
+		for (const choice of choices) if (isAbbreviation(bare, choice.slice(dashCount(choice)))) {
+			match = choice;
+			count++;
 		}
-		if (b.length === 0) return a.length;
-		if (a.length <= 32) return myers_32(a, b);
-		return myers_x(a, b);
-	};
-	exports.distance = distance;
-	var closest = function(str, arr) {
-		var min_distance = Infinity;
-		var min_index = 0;
-		for (var i = 0; i < arr.length; i++) {
-			var dist = distance(str, arr[i]);
-			if (dist < min_distance) {
-				min_distance = dist;
-				min_index = i;
-			}
+		if (count === 1) return match;
+	}
+	let best;
+	let limit = Math.floor(bare.length / 3);
+	for (const choice of choices) {
+		const other = choice.slice(dashCount(choice));
+		if (Math.abs(other.length - bare.length) > limit) continue;
+		const distance = editDistance(bare, other, limit);
+		if (distance <= limit && (best === void 0 || distance < limit)) {
+			best = choice;
+			limit = distance;
+			if (distance === 0) break;
 		}
-		return arr[min_index];
-	};
-	exports.closest = closest;
-})))();
+	}
+	return best;
+}
+// src/help.ts
 function getNamed(named, name) {
 	return named.find((obj) => makeArray(obj.name).includes(name)) ?? null;
 }
@@ -472,7 +267,7 @@ function dedent(str) {
 function getHelp(path, config = {}) {
 	const { description = true, usage = true, didYouMean } = config;
 	const sections = getSections(path);
-	if (didYouMean) sections.didYouMean = (0, import_fastest_levenshtein.closest)(didYouMean.input, didYouMean.choices);
+	if (didYouMean) sections.didYouMean = closestChoice(didYouMean.input, didYouMean.choices);
 	if (!description) sections.description = void 0;
 	if (!usage) sections.usage = void 0;
 	return formatHelpSections(sections);
@@ -683,211 +478,352 @@ function argToString(arg) {
 	return `${lhs}${name}${rhs}${suffix}`;
 }
 // src/parse.ts
+function hasName(names, name) {
+	return typeof names === "string" ? names === name : names.includes(name);
+}
 /**
-* Returns the minimum number of arguments that satisfies the args.
-*
-* Accepts the raw spec value (a single arg, an array, or `undefined`) so the
-* hot path doesn't have to copy it into an array first.
+* Find the option `name` refers to. Local options win over persistent ones, and
+* within each list a later definition wins over an earlier one.
 */
-function getMinArgs(args) {
-	if (args === void 0) return 0;
-	if (!isArray(args)) return args.isOptional ? 0 : 1;
-	let count = 0;
-	for (let i = 0; i < args.length; i++) {
-		if (args[i].isOptional) break;
-		count++;
-	}
-	return count;
-}
-/** Returns the maximum number of arguments that satisfies the args. */
-function getMaxArgs(args) {
-	if (args === void 0) return 0;
-	if (!isArray(args)) return args.isVariadic ? Infinity : 1;
-	for (let i = 0; i < args.length; i++) if (args[args.length - 1 - i].isVariadic) return Infinity;
-	return args.length;
-}
-/** Check if a map has a key or any key from an array */
-function has(map, key) {
-	if (isArray(key)) return map.has(key[0]);
-	return map.has(key);
+function findOption(local, persistent, name) {
+	for (let i = local.length - 1; i >= 0; i--) if (hasName(local[i].name, name)) return local[i];
+	for (let i = persistent.length - 1; i >= 0; i--) if (hasName(persistent[i].name, name)) return persistent[i];
+	return null;
 }
-/** Get a value from a map by a key or any key from an array */
-function get(map, key) {
-	if (isArray(key)) return map.get(key[0]);
-	return map.get(key);
+/** Every name that's valid as an option here, for "did you mean" suggestions. */
+function optionNames(local, persistent) {
+	const names = [];
+	for (const options of [local, persistent]) {
+		const seen = /* @__PURE__ */ new Set();
+		for (const option of options) for (const name of asArray(option.name)) if (!seen.has(name)) {
+			seen.add(name);
+			names.push(name);
+		}
+	}
+	return names;
 }
 /**
-* Parse the input tokens using the given CLI spec.
-*
-* This returns a `ParseResult`, which contains the array of
-* subcommands used, the provided options, and the arguments.
+* Read a command line against a spec in one pass.
 *
-* If parsing fails, this function throws.
+* This is the only code that decides what each input token is. With `strict`,
+* it throws on the first problem, which is what {@link parse} needs. Without
+* it, it never throws: it skips whatever is invalid and keeps going, so
+* completion can still read a line that's wrong at the moment.
 *
-* This function is exposed to make it easier to build a custom runner.
+* This runs once per process, so it's written for a cold start: one loop, few
+* helper functions and plain arrays, because every extra function is compiled
+* the first time it runs.
 */
-function parse(input, spec) {
+function scan(input, spec, strict) {
 	const path = [spec];
 	const actions = [];
 	const optionActions = [];
-	if (spec.action) actions.push(spec.action);
-	else if (spec.requiresSubcommand) actions.push(usage);
-	let commandArgsMin = getMinArgs(spec.args);
-	let commandArgsMax = getMaxArgs(spec.args);
-	const foundArgs = [];
-	const foundOptions = /* @__PURE__ */ new Map();
-	let state = 0;
-	let optionArgs = null;
-	let optionArgsMin = 0;
-	let optionArgsMax = 0;
-	let requiredSeparator = false;
+	const args = [];
+	const options = /* @__PURE__ */ new Map();
+	const seenOptions = [];
 	let argSeparatorIndex = -1;
-	const dependsOnOptions = [];
-	const exclusiveOnOptions = [];
-	const parseOption = (token) => {
-		const option = token.option;
-		if (!option.isRepeatable && has(foundOptions, option.name)) throw new ParseError(ctx(), "Repeated option");
-		if (option.exclusiveOn) exclusiveOnOptions.push(option);
-		if (option.dependsOn) dependsOnOptions.push(option);
+	let local = [];
+	const persistent = [];
+	const localRequired = [];
+	const persistentRequired = [];
+	let subcommands;
+	let commandArgsMin = 0;
+	let commandArgsMax = 0;
+	let separators = ["="];
+	let posixCompliantOptions = true;
+	let subcommandsMatchUniquePrefix = false;
+	let optionsMustPrecedeArguments = false;
+	let hasFoundArg = false;
+	let openOption = null;
+	let openOptionName = "";
+	let valueCount = 0;
+	let valueMin = 0;
+	let separateValueMax = 0;
+	let values = null;
+	let valuesStart = 0;
+	let valuesMin = 0;
+	let valuesMax = 0;
+	let requiredSeparator = false;
+	const repeatCounts = /* @__PURE__ */ new Map();
+	const ctx = () => ({ path });
+	const enterCommand = (command) => {
+		local = [];
+		localRequired.length = 0;
+		if (command.options) for (const option of command.options) if (option.isPersistent) {
+			persistent.push(option);
+			if (option.isRequired) persistentRequired.push(option);
+		} else {
+			local.push(option);
+			if (option.isRequired) localRequired.push(option);
+		}
+		subcommands = command.subcommands;
+		commandArgsMin = getMinArgs(command.args);
+		commandArgsMax = getMaxArgs(command.args);
+		if (command.action) actions.push(command.action);
+		else if (command.requiresSubcommand) actions.push(usage);
+		const directives = command.parserDirectives;
+		if (directives) {
+			if (directives.optionArgSeparators) separators = asArray(directives.optionArgSeparators);
+			if (typeof directives.subcommandsMatchUniquePrefix === "boolean") subcommandsMatchUniquePrefix = directives.subcommandsMatchUniquePrefix;
+			if (typeof directives.optionsMustPrecedeArguments === "boolean") optionsMustPrecedeArguments = directives.optionsMustPrecedeArguments;
+			if (typeof directives.flagsArePosixNoncompliant === "boolean") posixCompliantOptions = !directives.flagsArePosixNoncompliant;
+		}
+	};
+	const endOption = () => {
+		if (strict && values && values.length - valuesStart < valuesMin) throw new TooFewOptionArguments(valuesMin, valuesMax, ctx());
+		values = null;
+	};
+	const useOption = (option, name) => {
+		endOption();
+		openOption = option;
+		openOptionName = name;
+		valueCount = 0;
+		valueMin = getMinArgs(option.args);
+		separateValueMax = option.requiresSeparator ? 0 : getMaxArgs(option.args);
+		seenOptions.push(option);
 		if (option.action) optionActions.push(option.action);
+		const names = asArray(option.name);
+		let optionValues;
 		if (option.isRepeatable) {
 			const maxRepeat = option.isRepeatable === true ? Infinity : option.isRepeatable;
-			let arr = get(foundOptions, option.name);
-			if (!arr) {
-				arr = [];
-				setEach(foundOptions, option.name, arr);
+			const existing = options.get(names[0]);
+			let isSharedCount = true;
+			for (const other of names) if (options.get(other) !== existing) isSharedCount = false;
+			let uses = isSharedCount ? existing : void 0;
+			if (!uses) {
+				uses = [];
+				for (const other of names) options.set(other, uses);
 			}
-			if (arr.length >= maxRepeat) throw new ParseError(ctx(), "Too many repetitions");
-			arr.push("");
-			return;
+			const count = repeatCounts.get(uses) ?? uses.length;
+			if (strict && count >= maxRepeat) throw new ParseError(ctx(), "Too many repetitions");
+			repeatCounts.set(uses, count + 1);
+			if (!option.args) {
+				uses.push("");
+				return;
+			}
+			optionValues = uses;
+		} else {
+			optionValues = [];
+			for (const other of names) options.set(other, optionValues);
 		}
-		optionArgsMin = getMinArgs(option.args);
-		optionArgsMax = getMaxArgs(option.args);
-		optionArgs = [];
-		setEach(foundOptions, option.name, optionArgs);
-		if (optionArgsMax === 0) {
-			optionArgs = null;
-			state = 0;
-			return;
+		valuesMin = valueMin;
+		valuesMax = getMaxArgs(option.args);
+		requiredSeparator = option.requiresSeparator ?? false;
+		if (valuesMax > 0) {
+			values = optionValues;
+			valuesStart = optionValues.length;
 		}
-		if (option.requiresSeparator) {
-			state = 2;
-			requiredSeparator = option.requiresSeparator;
-		} else state = 1;
 	};
-	const parseArg = (token) => {
-		if (!path[path.length - 1].requiresSubcommand && foundArgs.length >= commandArgsMax) throw new TooManyArguments(token, ctx());
-		foundArgs.push(token.literal);
-	};
-	const parseArgSeparator = () => {
-		if (foundArgs.length >= commandArgsMax) throw new ParseError(ctx(), "Unexpected argument '--', did you mean to use an option instead?");
-		argSeparatorIndex = foundArgs.length;
-		state = 0;
+	const addValue = (index, start, end, value, separator) => {
+		valueCount += 1;
+		if (!values) {
+			if (strict) throw new InvalidOptionArg({
+				option: openOptionName,
+				arg: value,
+				index,
+				start,
+				end
+			}, ctx());
+			return;
+		}
+		if (strict && typeof requiredSeparator === "string" && separator !== requiredSeparator) throw new ParseError(ctx(), `Incorrect separator, use '${requiredSeparator}' instead of '${separator}'`);
+		values.push(value);
 	};
-	const parseSubcommand = (token) => {
-		path.push(token.subcommand);
-		commandArgsMin = getMinArgs(token.subcommand.args);
-		commandArgsMax = getMaxArgs(token.subcommand.args);
-		if (token.subcommand.action) actions.push(token.subcommand.action);
-		else if (token.subcommand.requiresSubcommand) actions.push(usage);
+	const addArg = (index, value) => {
+		endOption();
+		if (strict && !path[path.length - 1].requiresSubcommand && args.length >= commandArgsMax) throw new TooManyArguments({
+			value,
+			index
+		}, ctx());
+		args.push(value);
 	};
-	const ctx = () => ({ path });
-	const { finalState, tokens } = analyze(input, spec);
-	for (const token of tokens) switch (state) {
-		case 0:
-			switch (token.kind) {
-				case "subcommand":
-					parseSubcommand(token);
-					break;
-				case "arg":
-					parseArg(token);
-					break;
-				case "option":
-					parseOption(token);
-					break;
-				case "unknown-option": throw new UnknownOption(token, ctx());
-				case "option-arg": throw new InvalidOptionArg(token, ctx());
-				case "arg-separator":
-					parseArgSeparator();
-					break;
-				default: throw new ParseError(ctx(), "Unreachable");
+	enterCommand(spec);
+	tokens: for (let index = 0; index < input.length; index++) {
+		const token = input[index];
+		if (token === "--") {
+			endOption();
+			if (strict && args.length >= commandArgsMax) throw new ParseError(ctx(), "Unexpected argument '--', did you mean to use an option instead?");
+			argSeparatorIndex = args.length;
+			openOption = null;
+			valueCount = valueMin = separateValueMax = 0;
+			for (index += 1; index < input.length; index++) addArg(index, input[index]);
+			break tokens;
+		}
+		const hasRoomForValue = valueCount < separateValueMax;
+		if (!hasFoundArg && !(valueCount < valueMin || hasRoomForValue && separateValueMax === Infinity) && subcommands) {
+			const allowPrefix = subcommandsMatchUniquePrefix && !hasRoomForValue && token !== "";
+			let command = null;
+			let prefixCount = 0;
+			commands: for (const candidate of subcommands) {
+				const names = candidate.name;
+				if (typeof names === "string") {
+					if (names === token) {
+						command = candidate;
+						prefixCount = -1;
+						break commands;
+					}
+					if (allowPrefix && names.startsWith(token)) {
+						command = candidate;
+						prefixCount += 1;
+					}
+					continue commands;
+				}
+				let prefixMatched = false;
+				for (const name of names) {
+					if (name === token) {
+						command = candidate;
+						prefixCount = -1;
+						break commands;
+					}
+					if (allowPrefix && !prefixMatched && name.startsWith(token)) {
+						prefixMatched = true;
+						command = candidate;
+						prefixCount += 1;
+					}
+				}
 			}
-			break;
-		case 1:
-			assert(Array.isArray(optionArgs), "Invalid state, must have an array to store option arguments");
-			switch (token.kind) {
-				case "option-arg":
-				case "arg":
-					if (optionArgs.length < optionArgsMax) optionArgs.push(token.literal);
-					else {
-						optionArgs = null;
-						state = 0;
-						parseArg(token);
+			if (command && (prefixCount === -1 || prefixCount === 1)) {
+				endOption();
+				openOption = null;
+				valueCount = valueMin = separateValueMax = 0;
+				path.push(command);
+				enterCommand(command);
+				continue tokens;
+			}
+		}
+		if (!(optionsMustPrecedeArguments && hasFoundArg)) {
+			const first = token.charCodeAt(0);
+			const isDoubleDash = first === 45 && token.charCodeAt(1) === 45;
+			if (posixCompliantOptions && token.length > 1 && (first === 45 || first === 43) && !isDoubleDash) {
+				const leadingChar = token[0];
+				const dashOption = findOption(local, persistent, leadingChar);
+				if (dashOption?.args && !findOption(local, persistent, token.slice(0, 2))) {
+					useOption(dashOption, leadingChar);
+					addValue(index, 1, token.length, token.slice(1), "");
+					continue tokens;
+				}
+				for (let char = 1; char < token.length; char++) {
+					const optionName = leadingChar + token[char];
+					const option = findOption(local, persistent, optionName);
+					if (!option) {
+						if (char === 1 && valueCount < separateValueMax) {
+							addValue(index, 0, token.length, token, "");
+							continue tokens;
+						}
+						if (strict) throw new UnknownOption({
+							option: optionName,
+							validOptions: optionNames(local, persistent),
+							index,
+							start: char,
+							end: char + 1
+						}, ctx());
+						continue;
 					}
-					break;
-				case "option":
-					if (optionArgs.length < optionArgsMin) throw new TooFewOptionArguments(optionArgsMin, optionArgsMax, ctx());
-					parseOption(token);
-					break;
-				case "unknown-option":
-					if (optionArgs.length < optionArgsMax) optionArgs.push(token.literal);
-					else throw new UnknownOption(token, ctx());
-					break;
-				case "arg-separator":
-					if (optionArgs.length < optionArgsMin) throw new TooFewOptionArguments(optionArgsMin, optionArgsMax, ctx());
-					parseArgSeparator();
-					break;
-				case "subcommand": throw new ParseError(ctx(), "Unexpected token");
-				default: throw new ParseError(ctx(), "Unreachable");
+					useOption(option, optionName);
+					if (option.args && char < token.length - 1) {
+						const remainingChars = token.slice(char + 1);
+						let sep = "";
+						for (const candidate of separators) if (remainingChars.startsWith(candidate)) {
+							sep = candidate;
+							break;
+						}
+						const argStart = char + sep.length + 1;
+						addValue(index, argStart, token.length, token.slice(argStart), sep);
+						break;
+					}
+				}
+				continue tokens;
 			}
-			break;
-		case 2:
-			assert(Array.isArray(optionArgs), "Invalid state, must have an array to store option arguments");
-			assert(requiredSeparator, "Invalid state, a separator must be set");
-			switch (token.kind) {
-				case "option-arg":
-					if (typeof requiredSeparator === "string" && token.separator !== requiredSeparator) throw new ParseError(ctx(), `Incorrect separator, use '${requiredSeparator}' instead of '${token.separator}'`);
-					optionArgs.push(token.literal);
-					state = 0;
-					break;
-				case "arg":
-					if (optionArgsMin > 0) throw new TooFewOptionArguments(optionArgsMin, optionArgsMax, ctx());
-					optionArgs = null;
-					state = 0;
-					parseArg(token);
-					break;
-				case "option":
-					if (optionArgsMin > 0) throw new TooFewOptionArguments(optionArgsMin, optionArgsMax, ctx());
-					parseOption(token);
-					break;
-				case "unknown-option": throw new UnknownOption(token, ctx());
-				case "arg-separator": throw new ParseError(ctx(), "Unexpected token");
-				case "subcommand":
-					if (optionArgsMin > 0) throw new TooFewOptionArguments(optionArgsMin, optionArgsMax, ctx());
-					parseSubcommand(token);
-					state = 0;
-					break;
-				default: throw new ParseError(ctx(), "Unreachable");
+			if (!posixCompliantOptions || token.length > 2 && isDoubleDash) {
+				let foundSep = "";
+				let foundSepIndex = -1;
+				for (const sep of separators) {
+					const at = token.indexOf(sep);
+					if (at === -1) continue;
+					if (foundSepIndex === -1 || at < foundSepIndex || at === foundSepIndex && sep.length > foundSep.length) {
+						foundSep = sep;
+						foundSepIndex = at;
+					}
+				}
+				const optionName = foundSep ? token.slice(0, foundSepIndex) : token;
+				const option = findOption(local, persistent, optionName);
+				if (option) {
+					useOption(option, optionName);
+					if (foundSep) {
+						const valueStart = foundSepIndex + foundSep.length;
+						addValue(index, valueStart, token.length, token.slice(valueStart), foundSep);
+					}
+					continue tokens;
+				}
+				if (posixCompliantOptions) {
+					if (valueCount < separateValueMax) {
+						addValue(index, 0, token.length, token, "");
+						continue tokens;
+					}
+					if (strict) throw new UnknownOption({
+						option: optionName,
+						validOptions: optionNames(local, persistent),
+						index,
+						start: 0,
+						end: optionName.length
+					}, ctx());
+					continue tokens;
+				}
 			}
+		}
+		if (valueCount < separateValueMax) {
+			addValue(index, 0, token.length, token, "");
+			continue tokens;
+		}
+		hasFoundArg = true;
+		addArg(index, token);
 	}
-	const hasOptionAction = optionActions.length > 0;
-	if (!hasOptionAction && foundArgs.length < commandArgsMin) throw new TooFewArguments(commandArgsMin, commandArgsMax, ctx());
-	if (optionArgs && optionArgs.length < optionArgsMin) throw new TooFewOptionArguments(optionArgsMin, optionArgsMax, ctx());
-	for (const option of dependsOnOptions) for (const name of option.dependsOn) if (!foundOptions.has(name)) throw new ParseError(ctx(), `${option.name} requires ${name}, add it to fix this error`);
-	for (const option of exclusiveOnOptions) for (const name of option.exclusiveOn) if (foundOptions.has(name)) throw new ParseError(ctx(), `${option.name} can't be used together with ${name}`);
-	if (!hasOptionAction) {
-		for (const name of finalState.localRequiredOptions.keys()) if (!foundOptions.has(name)) throw new MissingRequiredOption(name, ctx());
-		for (const name of finalState.persistentRequiredOptions.keys()) if (!foundOptions.has(name)) throw new MissingRequiredOption(name, ctx());
+	if (strict) {
+		const hasOptionAction = optionActions.length > 0;
+		if (!hasOptionAction && args.length < commandArgsMin) throw new TooFewArguments(commandArgsMin, commandArgsMax, ctx());
+		endOption();
+		for (const option of seenOptions) {
+			if (!option.dependsOn) continue;
+			for (const name of option.dependsOn) if (!options.has(name)) throw new ParseError(ctx(), `${asArray(option.name).join("/")} requires ${name}, add it to fix this error`);
+		}
+		for (const option of seenOptions) {
+			if (!option.exclusiveOn) continue;
+			for (const name of option.exclusiveOn) if (options.has(name)) throw new ParseError(ctx(), `${asArray(option.name).join("/")} can't be used together with ${name}`);
+		}
+		if (!hasOptionAction) {
+			for (const required of [localRequired, persistentRequired]) for (const option of required) for (const name of asArray(option.name)) if (!options.has(name)) throw new MissingRequiredOption(name, ctx());
+		}
 	}
+	const open = openOption;
 	return {
 		path,
 		actions,
 		optionActions,
+		args,
 		argSeparatorIndex,
-		args: foundArgs,
-		options: foundOptions
+		options,
+		seenOptions,
+		localOptions: local,
+		persistentOptions: persistent,
+		openOption: open && valueCount < separateValueMax ? {
+			option: open,
+			valueCount
+		} : null
 	};
 }
+/**
+* Parse the input tokens using the given CLI spec.
+*
+* This returns a `ParseResult`, which contains the array of
+* subcommands used, the provided options, and the arguments.
+*
+* If parsing fails, this function throws.
+*
+* This function is exposed to make it easier to build a custom runner.
+*/
+function parse(input, spec) {
+	return scan(input, spec, true);
+}
 // src/completion.ts
 const SHELLS = [
 	"bash",
@@ -900,97 +836,6 @@ function isShell(value) {
 const firstLine = (description) => description ? description.split("\n", 1)[0].trim() : "";
 /** Turn an arbitrary name into a safe shell identifier fragment. */
 const sanitize = (value) => value.replace(/[^A-Za-z0-9]+/g, "_");
-function encodeLocation(location) {
-	const bytes = new TextEncoder().encode(JSON.stringify(location));
-	let binary = "";
-	for (const byte of bytes) binary += String.fromCharCode(byte);
-	return btoa(binary);
-}
-function decodeLocation(encoded) {
-	const binary = atob(encoded);
-	const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
-	return JSON.parse(new TextDecoder().decode(bytes));
-}
-/** Build {@link ArgComplete} for one argument at a known spec location. */
-function argCompleteFor(arg, location) {
-	const staticValues = (arg.suggestions ?? []).map((suggestion) => typeof suggestion === "string" ? suggestion : makeArray(suggestion.name)[0]);
-	const genIndex = makeArray(arg.generators).findIndex((generator) => generator.custom);
-	const customLocation = genIndex >= 0 ? encodeLocation({
-		...location,
-		genIndex
-	}) : void 0;
-	if (!arg.template && staticValues.length === 0 && !customLocation) return;
-	return {
-		template: arg.template,
-		staticValues,
-		customLocation
-	};
-}
-/** Completion for a option's first argument, if it has any metadata. */
-function optionArgComplete(option, path) {
-	const arg = asArray(option.args)[0];
-	if (!arg) return void 0;
-	return argCompleteFor(arg, {
-		path,
-		option: makeArray(option.name)[0],
-		argIndex: 0
-	});
-}
-/** Completion for a command's first positional arg that has metadata. */
-function positionalComplete(command, path) {
-	const args = asArray(command.args);
-	for (let index = 0; index < args.length; index += 1) {
-		const ac = argCompleteFor(args[index], {
-			path,
-			argIndex: index
-		});
-		if (ac) return ac;
-	}
-}
-function toOptionInfo(option, path) {
-	return {
-		tokens: makeArray(option.name),
-		description: firstLine(option.description),
-		takesArg: asArray(option.args).length > 0,
-		argComplete: optionArgComplete(option, path)
-	};
-}
-/**
-* Flatten the spec into a list of command nodes. Hidden options and subcommands
-* are excluded; persistent options are propagated to descendants.
-*/
-function walk(spec) {
-	const nodes = [];
-	const recurse = (command, key, path, inheritedPersistent) => {
-		const ownOptions = (command.options ?? []).filter((option) => !option.hidden);
-		const children = (command.subcommands ?? []).filter((sub) => !sub.hidden);
-		const node = {
-			key,
-			path,
-			subcommands: [],
-			options: [...inheritedPersistent, ...ownOptions].map((option) => toOptionInfo(option, path)),
-			positional: positionalComplete(command, path),
-			transitions: []
-		};
-		const childPersistent = [...inheritedPersistent, ...ownOptions.filter((option) => option.isPersistent)];
-		for (const child of children) {
-			const tokens = makeArray(child.name);
-			const childKey = `${key}_${sanitize(tokens[0])}`;
-			node.subcommands.push({
-				tokens,
-				description: firstLine(child.description)
-			});
-			for (const token of tokens) node.transitions.push({
-				token,
-				childKey
-			});
-			recurse(child, childKey, [...path, tokens[0]], childPersistent);
-		}
-		nodes.push(node);
-	};
-	recurse(spec, "cmd", [], []);
-	return nodes;
-}
 /** Single-quote a string for bash/zsh. */
 function shQuote(value) {
 	return `'${value.replaceAll("'", "'\\''")}'`;
@@ -999,318 +844,53 @@ function shQuote(value) {
 function fishQuote(value) {
 	return `'${value.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`;
 }
-/** Every candidate token offered at a node (subcommand aliases + option aliases). */
-function candidateTokens(node) {
-	const tokens = [];
-	for (const sub of node.subcommands) tokens.push(...sub.tokens);
-	for (const option of node.options) tokens.push(...option.tokens);
-	return tokens;
-}
-function renderTransitionCases(nodes, indent) {
-	const lines = [];
-	for (const node of nodes) for (const { token, childKey } of node.transitions) lines.push(`${indent}${shQuote(`${node.key}::${token}`)}) cmd=${shQuote(childKey)} ;;`);
-	return lines;
-}
 /**
-* bash candidate lines for an arg. `append` keeps existing COMPREPLY (for a
-* positional, which coexists with subcommands/options); otherwise it replaces.
-* The generator callback uses the typed command and is guarded for resilience.
+* Read the line typed so far with the parser in lenient mode, which skips
+* anything invalid instead of throwing.
 */
-function bashArgLines(ac, indent, append) {
-	const lines = [];
-	const op = append ? "COMPREPLY+=" : "COMPREPLY=";
-	const hasWords = ac.staticValues.length > 0 || ac.customLocation !== void 0;
-	if (hasWords) {
-		lines.push(`${indent}local words=${ac.staticValues.length > 0 ? shQuote(ac.staticValues.join(" ")) : "\"\""}`);
-		if (ac.customLocation) {
-			lines.push(`${indent}if command -v "\${COMP_WORDS[0]}" >/dev/null 2>&1; then`);
-			lines.push(`${indent}  words="$words $("\${COMP_WORDS[0]}" completion generate-suggestions ${shQuote(ac.customLocation)} -- "\${COMP_WORDS[@]:1}" 2>/dev/null)"`);
-			lines.push(`${indent}fi`);
-		}
-		lines.push(`${indent}${op}( $(compgen -W "$words" -- "$cur") )`);
-	}
-	if (ac.template) {
-		const option = ac.template === "folders" ? "-d" : "-f";
-		const fileOp = hasWords || append ? "COMPREPLY+=" : "COMPREPLY=";
-		lines.push(`${indent}${fileOp}( $(compgen ${option} -- "$cur") )`);
-	}
-	return lines;
-}
-function renderBash(spec, nodes) {
-	const id = sanitize(spec.name);
-	const lines = [];
-	lines.push(`_${id}() {`);
-	lines.push(`  local cur="\${COMP_WORDS[COMP_CWORD]}"`);
-	lines.push(`  local prev="\${COMP_WORDS[COMP_CWORD-1]}"`);
-	lines.push(`  local cmd="cmd" i w`);
-	lines.push(`  for (( i=1; i < COMP_CWORD; i++ )); do`);
-	lines.push(`    w="\${COMP_WORDS[i]}"`);
-	lines.push(`    case "$w" in -* ) continue ;; esac`);
-	lines.push(`    case "\${cmd}::\${w}" in`);
-	lines.push(...renderTransitionCases(nodes, "      "));
-	lines.push(`    esac`);
-	lines.push(`  done`);
-	const argCases = [];
-	for (const node of nodes) for (const option of node.options) {
-		if (!option.argComplete) continue;
-		for (const token of option.tokens) {
-			argCases.push(`    ${shQuote(`${node.key}::${token}`)})`);
-			argCases.push(...bashArgLines(option.argComplete, "      ", false));
-			argCases.push(`      return ;;`);
-		}
-	}
-	if (argCases.length > 0) {
-		lines.push(`  case "\${cmd}::\${prev}" in`);
-		lines.push(...argCases);
-		lines.push(`  esac`);
-	}
-	lines.push(`  local opts=""`);
-	lines.push(`  case "$cmd" in`);
-	for (const node of nodes) lines.push(`    ${shQuote(node.key)}) opts=${shQuote(candidateTokens(node).join(" "))} ;;`);
-	lines.push(`  esac`);
-	lines.push(`  COMPREPLY=( $(compgen -W "$opts" -- "$cur") )`);
-	const posCases = [];
-	for (const node of nodes) {
-		if (!node.positional) continue;
-		posCases.push(`    ${shQuote(node.key)})`);
-		posCases.push(...bashArgLines(node.positional, "      ", true));
-		posCases.push(`      ;;`);
-	}
-	if (posCases.length > 0) {
-		lines.push(`  case "$cmd" in`);
-		lines.push(...posCases);
-		lines.push(`  esac`);
-	}
-	lines.push(`}`);
-	lines.push(`complete -F _${id} ${shQuote(spec.name)}`);
-	return lines.join("\n");
-}
-/** zsh candidate lines for an arg (used for both option values and positionals). */
-function zshArgLines(ac, indent) {
-	const lines = [];
-	if (ac.staticValues.length > 0 || ac.customLocation !== void 0) {
-		lines.push(`${indent}local -a vals`);
-		lines.push(`${indent}vals=( ${ac.staticValues.map(shQuote).join(" ")} )`);
-		if (ac.customLocation) {
-			lines.push(`${indent}if command -v "$words[1]" >/dev/null 2>&1; then`);
-			lines.push(`${indent}  vals+=( \${(f)"$("$words[1]" completion generate-suggestions ${shQuote(ac.customLocation)} -- \${words[2,-1]} 2>/dev/null)"} )`);
-			lines.push(`${indent}fi`);
-		}
-		lines.push(`${indent}compadd -a vals`);
-	}
-	if (ac.template) lines.push(`${indent}${ac.template === "folders" ? "_files -/" : "_files"}`);
-	return lines;
-}
-function renderZsh(spec, nodes) {
-	const id = sanitize(spec.name);
-	const lines = [];
-	lines.push(`#compdef ${spec.name}`);
-	lines.push(`_${id}() {`);
-	lines.push(`  local cmd=cmd i w prev`);
-	lines.push(`  for (( i=2; i < CURRENT; i++ )); do`);
-	lines.push(`    w="\${words[i]}"`);
-	lines.push(`    case "$w" in -* ) continue ;; esac`);
-	lines.push(`    case "\${cmd}::\${w}" in`);
-	lines.push(...renderTransitionCases(nodes, "      "));
-	lines.push(`    esac`);
-	lines.push(`  done`);
-	lines.push(`  prev="\${words[CURRENT-1]}"`);
-	const argCases = [];
-	for (const node of nodes) for (const option of node.options) {
-		if (!option.argComplete) continue;
-		for (const token of option.tokens) {
-			argCases.push(`    ${shQuote(`${node.key}::${token}`)})`);
-			argCases.push(...zshArgLines(option.argComplete, "      "));
-			argCases.push(`      return ;;`);
-		}
-	}
-	if (argCases.length > 0) {
-		lines.push(`  case "\${cmd}::\${prev}" in`);
-		lines.push(...argCases);
-		lines.push(`  esac`);
-	}
-	lines.push(`  local -a opts`);
-	lines.push(`  case "$cmd" in`);
-	for (const node of nodes) {
-		const entries = [];
-		for (const sub of node.subcommands) for (const token of sub.tokens) entries.push(shQuote(`${token}:${sub.description}`));
-		for (const option of node.options) for (const token of option.tokens) entries.push(shQuote(`${token}:${option.description}`));
-		lines.push(`    ${shQuote(node.key)}) opts=( ${entries.join(" ")} ) ;;`);
-	}
-	lines.push(`  esac`);
-	lines.push(`  _describe -t values ${shQuote(spec.name)} opts`);
-	const posCases = [];
-	for (const node of nodes) {
-		if (!node.positional) continue;
-		posCases.push(`    ${shQuote(node.key)})`);
-		posCases.push(...zshArgLines(node.positional, "      "));
-		posCases.push(`      ;;`);
-	}
-	if (posCases.length > 0) {
-		lines.push(`  case "$cmd" in`);
-		lines.push(...posCases);
-		lines.push(`  esac`);
-	}
-	lines.push(`}`);
-	lines.push(`_${id} "$@"`);
-	return lines.join("\n");
-}
-/** Build the fish `complete` option selectors (`-s x`, `-l long`, `-o old`). */
-function fishOptionSelectors(tokens) {
-	const parts = [];
-	for (const token of tokens) if (token.startsWith("--")) parts.push(`-l ${fishQuote(token.slice(2))}`);
-	else if (token.startsWith("-") && token.length === 2) parts.push(`-s ${fishQuote(token.slice(1))}`);
-	else if (token.startsWith("-") && token.length > 2) parts.push(`-o ${fishQuote(token.slice(1))}`);
-	else parts.push(`-a ${fishQuote(token)}`);
-	return parts.join(" ");
-}
-/** A guarded fish command substitution that runs a generator by location. */
-function fishGuardedCallback(location) {
-	return `(set -l c (commandline -opc)[1]; if command -q -- $c; or test -x "$c"; $c completion generate-suggestions ${location} -- (commandline -opc) 2>/dev/null; end)`;
-}
-/** The `-a` candidate bits and whether the shell's file completion is wanted. */
-function fishValueBits(ac) {
-	const parts = [...ac.staticValues];
-	if (ac.template === "folders" || Array.isArray(ac.template)) parts.push("(__fish_complete_directories)");
-	if (ac.customLocation) parts.push(fishGuardedCallback(ac.customLocation));
-	return {
-		aBits: parts.length > 0 ? ` -a ${fishQuote(parts.join(" "))}` : "",
-		wantsFiles: ac.template === "filepaths" || Array.isArray(ac.template)
-	};
-}
-/**
-* The suffix after a option's selectors. Uses `-x` (exclusive: requires a value
-* and suppresses fish's file fallback) when the arg has its own candidates and
-* isn't a filepaths template; `-r` lets files through when they're wanted.
-*/
-function fishOptionArgSuffix(option) {
-	if (!option.takesArg) return "";
-	if (!option.argComplete) return " -r";
-	const { aBits, wantsFiles } = fishValueBits(option.argComplete);
-	return `${wantsFiles ? " -r" : " -x"}${aBits}`;
-}
-function renderFish(spec, nodes) {
-	const id = sanitize(spec.name);
-	const name = spec.name;
-	const lines = [];
-	lines.push(`function __fish_${id}_at`);
-	lines.push(`  set -l cmd cmd`);
-	lines.push(`  set -l toks (commandline -opc)`);
-	lines.push(`  for w in $toks[2..-1]`);
-	lines.push(`    if string match -qr '^-' -- $w`);
-	lines.push(`      continue`);
-	lines.push(`    end`);
-	lines.push(`    switch "$cmd $w"`);
-	for (const node of nodes) for (const { token, childKey } of node.transitions) {
-		lines.push(`      case ${fishQuote(`${node.key} ${token}`)}`);
-		lines.push(`        set cmd ${fishQuote(childKey)}`);
-	}
-	lines.push(`    end`);
-	lines.push(`  end`);
-	lines.push(`  test "$cmd" = "$argv[1]"`);
-	lines.push(`end`);
-	lines.push("");
-	lines.push(`complete -c ${fishQuote(name)} -f`);
-	for (const node of nodes) {
-		const guard = `-n ${fishQuote(`__fish_${id}_at ${node.key}`)}`;
-		for (const sub of node.subcommands) for (const token of sub.tokens) {
-			const desc = sub.description ? ` -d ${fishQuote(sub.description)}` : "";
-			lines.push(`complete -c ${fishQuote(name)} ${guard} -a ${fishQuote(token)}${desc}`);
-		}
-		for (const option of node.options) {
-			const desc = option.description ? ` -d ${fishQuote(option.description)}` : "";
-			const suffix = fishOptionArgSuffix(option);
-			lines.push(`complete -c ${fishQuote(name)} ${guard} ${fishOptionSelectors(option.tokens)}${suffix}${desc}`);
-		}
-		if (node.positional) {
-			const { aBits, wantsFiles } = fishValueBits(node.positional);
-			lines.push(`complete -c ${fishQuote(name)} ${guard}${aBits}${wantsFiles ? " -F" : ""}`);
-		}
-	}
-	return lines.join("\n");
-}
-function analyzeState(spec, before) {
-	const { tokens, finalState } = analyze(before, spec);
-	const path = [spec];
-	let current = spec;
-	let pending = null;
-	let pendingFilled = 0;
-	let pendingMax = 0;
-	let positionalIndex = 0;
-	let forceArgs = false;
-	let sawPositional = false;
-	let usedNonPersistentOption = false;
+function readLine(spec, before) {
+	const scanned = scan(before, spec, false);
+	const path = scanned.path;
 	const presentNames = /* @__PURE__ */ new Set();
 	const countByOption = /* @__PURE__ */ new Map();
-	for (const token of tokens) switch (token.kind) {
-		case "subcommand":
-			current = token.subcommand;
-			path.push(current);
-			positionalIndex = 0;
-			sawPositional = false;
-			pending = null;
-			break;
-		case "option": {
-			const option = token.option;
-			for (const name of makeArray(option.name)) presentNames.add(name);
-			countByOption.set(option, (countByOption.get(option) ?? 0) + 1);
-			if (!option.isPersistent) usedNonPersistentOption = true;
-			const max = getMaxArgs(option.args);
-			if (max > 0 && !option.requiresSeparator) {
-				pending = {
-					option,
-					argIndex: 0
-				};
-				pendingFilled = 0;
-				pendingMax = max;
-			} else pending = null;
-			break;
-		}
-		case "option-arg":
-			pending = null;
-			break;
-		case "arg":
-			if (pending && pendingFilled < pendingMax) {
-				pendingFilled += 1;
-				pending = {
-					option: pending.option,
-					argIndex: pendingFilled
-				};
-				if (pendingFilled >= pendingMax) pending = null;
-			} else {
-				positionalIndex += 1;
-				sawPositional = true;
-				pending = null;
-			}
-			break;
-		case "arg-separator":
-			forceArgs = true;
-			pending = null;
-			break;
-		case "unknown-option": pending = null;
+	for (const option of scanned.seenOptions) {
+		for (const name of makeArray(option.name)) presentNames.add(name);
+		countByOption.set(option, (countByOption.get(option) ?? 0) + 1);
 	}
+	const open = scanned.openOption;
+	const pending = open ? {
+		option: open.option,
+		argIndex: open.valueCount
+	} : null;
 	const availableOptions = [];
 	const seen = /* @__PURE__ */ new Set();
-	for (const map of [finalState.localOptions, finalState.persistentOptions]) for (const option of map.values()) if (!seen.has(option)) {
-		seen.add(option);
-		availableOptions.push(option);
+	for (const list of [scanned.localOptions, scanned.persistentOptions]) {
+		const byName = /* @__PURE__ */ new Map();
+		for (const option of list) for (const name of makeArray(option.name)) byName.set(name, option);
+		for (const option of byName.values()) if (!seen.has(option)) {
+			seen.add(option);
+			availableOptions.push(option);
+		}
 	}
 	return {
 		path,
-		current,
+		current: path[path.length - 1],
 		availableOptions,
 		pending,
-		positionalIndex,
+		positionalIndex: scanned.args.length,
 		presentNames,
 		countByOption,
-		forceArgs,
-		sawPositional,
-		usedNonPersistentOption
+		forceArgs: scanned.argSeparatorIndex !== -1,
+		sawPositional: scanned.args.length > 0
 	};
 }
-/** Does any command on the path enable a sticky parser directive? */
+/** A directive's value in effect (the deepest command that sets it). */
 function directiveOnPath(path, key) {
-	return path.some((command) => command.parserDirectives?.[key]);
+	for (let i = path.length - 1; i >= 0; i--) {
+		const value = path[i].parserDirectives?.[key];
+		if (typeof value === "boolean") return value;
+	}
+	return false;
 }
 /** The option-arg separators in effect (the deepest command that sets them). */
 function separatorsOnPath(path) {
@@ -1361,21 +941,33 @@ async function argValues(arg, tokens, partial) {
 	if (arg.template) candidates.push(...await enumeratePaths(partial, arg.template));
 	return candidates;
 }
-/** Pick the argument being completed at a positional index (honors variadic). */
-function positionalArg(command, index) {
-	const args = asArray(command.args);
+/** Pick the argument at an index, reusing a final variadic argument. */
+function argAt(args, index) {
 	if (args.length === 0) return void 0;
 	if (index < args.length) return args[index];
 	const last = args[args.length - 1];
 	return last?.isVariadic ? last : void 0;
 }
+/** Pick the argument being completed at a positional index (honors variadic). */
+function positionalArg(command, index) {
+	return argAt(asArray(command.args), index);
+}
+/** Decide which kinds of candidate the word being completed can use. */
+function wantedCandidates(state, req) {
+	const posixNoncompliant = directiveOnPath(state.path, "flagsArePosixNoncompliant");
+	const partialIsOption = !posixNoncompliant && (req.partial.startsWith("-") || req.partial.startsWith("+"));
+	return {
+		wantValues: !(req.gateOptions && partialIsOption),
+		wantOptions: !req.gateOptions || partialIsOption || posixNoncompliant
+	};
+}
 /**
-* Resolve completion candidates for a partial command line, reusing the parser
-* (`analyze`) for context. Dispatches between completing a option's value and
+* Resolve completion candidates for a partial command line, reading it with the
+* parser's `scan` for context. Dispatches between completing a option's value and
 * completing a fresh token (subcommand / positional / option).
 */
 async function completeRuntime(req) {
-	const state = analyzeState(req.spec, req.before);
+	const state = readLine(req.spec, req.before);
 	const separators = separatorsOnPath(state.path);
 	const optionValue = await resolveOptionValue(state, req, separators);
 	if (optionValue) return optionValue;
@@ -1400,8 +992,12 @@ async function resolveOptionValue(state, req, separators) {
 		}));
 	}
 	if (state.pending) {
-		const arg = asArray(state.pending.option.args)[state.pending.argIndex];
-		return arg ? argValues(arg, tokens, req.partial) : [];
+		const { option, argIndex } = state.pending;
+		const args = asArray(option.args);
+		const arg = argAt(args, argIndex);
+		if (argIndex < args.length) return arg ? argValues(arg, tokens, req.partial) : [];
+		const { wantValues, wantOptions } = wantedCandidates(state, req);
+		return [...arg && wantValues ? await argValues(arg, tokens, req.partial) : [], ...wantOptions ? allowedOptionCandidates(state, separators) : []];
 	}
 	return null;
 }
@@ -1409,15 +1005,12 @@ async function resolveOptionValue(state, req, separators) {
 async function freshTokenCandidates(state, req, separators) {
 	const candidates = [];
 	const tokens = [...req.before];
-	const posixNoncompliant = directiveOnPath(state.path, "flagsArePosixNoncompliant");
-	const partialIsOption = !posixNoncompliant && (req.partial.startsWith("-") || req.partial.startsWith("+"));
-	const wantValues = !(req.gateOptions && partialIsOption);
-	const wantOptions = !req.gateOptions || partialIsOption || posixNoncompliant;
+	const { wantValues, wantOptions } = wantedCandidates(state, req);
 	if (wantValues) {
 		const positional = positionalArg(state.current, state.positionalIndex);
 		if (positional) candidates.push(...await argValues(positional, tokens, req.partial));
 		if (state.forceArgs) return candidates;
-		if (!state.sawPositional && !state.usedNonPersistentOption) for (const sub of state.current.subcommands ?? []) {
+		if (!state.sawPositional) for (const sub of state.current.subcommands ?? []) {
 			if (sub.hidden) continue;
 			const description = firstLine(sub.description);
 			for (const token of makeArray(sub.name)) candidates.push({
@@ -1426,10 +1019,13 @@ async function freshTokenCandidates(state, req, separators) {
 			});
 		}
 	} else if (state.forceArgs) return candidates;
-	const optionsBlocked = state.sawPositional && directiveOnPath(state.path, "optionsMustPrecedeArguments");
-	if (wantOptions && !optionsBlocked) candidates.push(...optionCandidates(state, separators));
+	if (wantOptions) candidates.push(...allowedOptionCandidates(state, separators));
 	return candidates;
 }
+/** Option candidates, unless options must precede arguments and one was seen. */
+function allowedOptionCandidates(state, separators) {
+	return state.sawPositional && directiveOnPath(state.path, "optionsMustPrecedeArguments") ? [] : optionCandidates(state, separators);
+}
 /** Eligible option candidates after relationship filtering. */
 function optionCandidates(state, separators) {
 	const required = [];
@@ -1504,49 +1100,8 @@ function renderRuntimeShim(spec, shell) {
 	].join("\n");
 }
 /** Generate a completion script for `shell` from a CLI spec. */
-function getCompletion(spec, shell, mode = "runtime") {
-	if (mode === "runtime") return renderRuntimeShim(spec, shell);
-	const nodes = walk(spec);
-	switch (shell) {
-		case "bash": return renderBash(spec, nodes);
-		case "zsh": return renderZsh(spec, nodes);
-		case "fish": return renderFish(spec, nodes);
-	}
-}
-/** Resolve the argument a {@link Location} points at, or null if it's stale. */
-function resolveArg(spec, location) {
-	let command = spec;
-	let ancestorPersistent = [];
-	for (const segment of location.path) {
-		ancestorPersistent = [...ancestorPersistent, ...(command.options ?? []).filter((option) => option.isPersistent)];
-		const child = (command.subcommands ?? []).find((sub) => makeArray(sub.name).includes(segment));
-		if (!child) return null;
-		command = child;
-	}
-	let args;
-	if (location.option !== void 0) {
-		const option = [...ancestorPersistent, ...command.options ?? []].find((candidate) => makeArray(candidate.name).includes(location.option));
-		if (!option) return null;
-		args = asArray(option.args);
-	} else args = asArray(command.args);
-	return args[location.argIndex] ?? null;
-}
-/**
-* Run the generator a base64 location points at and return its suggestions as
-* insertable strings, or null if the location is invalid.
-*/
-async function generateSuggestions(spec, encoded, tokens) {
-	let location;
-	try {
-		location = decodeLocation(encoded);
-	} catch {
-		return null;
-	}
-	const arg = resolveArg(spec, location);
-	if (!arg) return null;
-	const generator = makeArray(arg.generators)[location.genIndex];
-	if (!generator?.custom) return null;
-	return (await generator.custom(tokens)).map((suggestion) => typeof suggestion === "string" ? suggestion : makeArray(suggestion.name)[0]);
+function getCompletion(spec, shell) {
+	return renderRuntimeShim(spec, shell);
 }
 /** A subcommand that prints a shell completion script for the whole CLI. */
 const completion = {
@@ -1557,15 +1112,6 @@ const completion = {
 		isOptional: true,
 		suggestions: SHELLS
 	},
-	options: [{
-		name: "--runtime",
-		description: "Resolve candidates by invoking the CLI (default)",
-		exclusiveOn: ["--shell"]
-	}, {
-		name: "--shell",
-		description: "Emit a self-contained script with no per-Tab CLI call",
-		exclusiveOn: ["--runtime"]
-	}],
 	subcommands: [{
 		name: "complete",
 		description: "Resolve completion candidates for a partial command line",
@@ -1591,31 +1137,8 @@ const completion = {
 			if (lines.length > 0) print(lines.join("\n"));
 			return 0;
 		}
-	}, {
-		name: "generate-suggestions",
-		description: "Print dynamic suggestions for a completion generator",
-		hidden: true,
-		args: [{ name: "location" }, {
-			name: "tokens",
-			isVariadic: true,
-			isOptional: true
-		}],
-		async action({ path, args: [encoded, ...tokens] }) {
-			const spec = path[0];
-			if (encoded === void 0) {
-				printActionError("Missing generator location");
-				return 1;
-			}
-			const suggestions = await generateSuggestions(spec, encoded, tokens);
-			if (suggestions === null) {
-				printActionError(`Unknown generator location '${encoded}'`);
-				return 1;
-			}
-			if (suggestions.length > 0) print(suggestions.join("\n"));
-			return 0;
-		}
 	}],
-	action({ path: [spec], args: [shell], options, help }) {
+	action({ path: [spec], args: [shell], help }) {
 		if (shell === void 0) {
 			print(`Supported shells: ${SHELLS.join(", ")}`);
 			return 0;
@@ -1630,7 +1153,7 @@ const completion = {
 			})}`);
 			return 1;
 		}
-		print(getCompletion(spec, shell, options.has("--shell") ? "shell" : "runtime"));
+		print(getCompletion(spec, shell));
 		return 0;
 	}
 };
@@ -1686,8 +1209,9 @@ async function run(spec, args = defaultArgs()) {
 	}
 	return Math.min(Math.max(exitCode ?? 0, 0), 255);
 }
+/** Print `Error:` and the given values to stderr, separated by spaces. */
 function printError(...strings) {
-	console.error("Error:", ...strings);
+	output.write(2, `${["Error:", ...strings].map(String).join(" ")}\n`);
 }
 function defaultArgs() {
 	return globalThis.process?.argv?.slice(2) ?? [];