@clo4/cli 3.0.0 → 3.0.1

package/dist/index.js

@@ -192,42 +192,6 @@ function closestChoice(input, choices) {
 }
 // src/subcommands.ts
 /**
-* Find the subcommand `token` names among `subcommands`, in a command where
-* `directives` are in effect, or else among the persistent subcommands the
-* command `inherited`. An exact name always wins. With
-* `subcommandsMatchUniquePrefix`, a token that's a prefix of exactly one
-* of the command's own names matches that command, unless `exactOnly`. A
-* hidden or inherited command only matches its exact name, so it can't make a
-* visible command's prefix ambiguous or take a prefix meant as an argument,
-* and an empty token is no command's prefix.
-*/
-function matchSubcommand(subcommands, token, directives, exactOnly = false, inherited = []) {
-	for (const candidate of subcommands) if (hasName$1(candidate, token)) return { command: candidate };
-	for (const candidate of inherited) if (hasName$1(candidate, token)) return { command: candidate };
-	const matches = directives.subcommandsMatchUniquePrefix && !exactOnly ? prefixMatches(subcommands, token) : [];
-	if (matches.length === 1) return { command: matches[0] };
-	return new NoSubcommand(withInherited(subcommands, inherited), token, matches);
-}
-/**
-* A command's own `subcommands` followed by the `inherited` ones it can use,
-* leaving out each inherited one that an earlier command shadows a name of.
-*/
-function withInherited(subcommands, inherited) {
-	if (inherited.length === 0) return subcommands;
-	const all = [...subcommands];
-	for (const candidate of inherited) if (!asArray(candidate.name).some((name) => all.some((earlier) => hasName$1(earlier, name)))) all.push(candidate);
-	return all;
-}
-function hasName$1(command, token) {
-	const names = command.name;
-	return typeof names === "string" ? names === token : names.includes(token);
-}
-/** The visible commands that `token` is a prefix of a name of, each listed once. */
-function prefixMatches(subcommands, token) {
-	if (token === "") return [];
-	return subcommands.filter((candidate) => !candidate.hidden && asArray(candidate.name).some((name) => name.startsWith(token)));
-}
-/**
 * A token that names no subcommand. The reason is only worked out when asked
 * for, since most tokens the parser tries aren't subcommands.
 */
@@ -293,16 +257,17 @@ function applyDirectives(directives, command) {
 }
 // src/scope.ts
 /**
-* The options and directives in effect at one command on a path.
+* What a name means at one command on a path: the options, subcommands,
+* directives and argument limits in effect there.
 *
 * Moving to a subcommand replaces the local options and adds its persistent
 * options to the inherited ones. A name refers to one option: a local option
 * wins over a persistent one, and a later option wins over an earlier one in
-* the same list. The parser, help, completion and the spec checker all ask
-* this module which option a name refers to, so they can't disagree. It also
-* holds the persistent subcommands the current command inherits.
+* the same list. A subcommand wins over an option where the next token can
+* name a subcommand. The parser, help, completion and the spec checker all
+* ask this module what a name refers to, so they can't disagree.
 */
-var OptionScope = class OptionScope {
+var CommandScope = class CommandScope {
 	/** Non-persistent options of the current command, in definition order. */
 	local = [];
 	/** Persistent options from every command on the path, in definition order. */
@@ -314,25 +279,69 @@ var OptionScope = class OptionScope {
 	inheritedSubcommands = [];
 	/** The directives in effect. A subcommand inherits each until it sets its own. */
 	directives = defaultDirectives();
-	command = null;
+	current = null;
+	/** The fewest positional arguments the current command takes. */
+	argsMin = 0;
+	/** The most positional arguments the current command takes. */
+	argsMax = 0;
 	/** The scope at the last command on `path`. */
 	static at(path) {
-		const scope = new OptionScope();
+		const scope = new CommandScope();
 		for (const command of path) scope.enter(command);
 		return scope;
 	}
 	/** Move to `command`, a subcommand of the current one. */
 	enter(command) {
-		const parentSubcommands = this.command?.subcommands;
+		const parentSubcommands = this.current?.subcommands;
 		if (parentSubcommands) {
 			const persistent = parentSubcommands.filter((subcommand) => subcommand.isPersistent);
 			if (persistent.length > 0) this.inheritedSubcommands.unshift(...persistent);
 		}
-		this.command = command;
+		this.current = command;
+		this.argsMin = getMinArgs(command.args);
+		this.argsMax = getMaxArgs(command.args);
 		this.local.length = 0;
 		if (command.options) for (const option of command.options) (option.isPersistent ? this.persistent : this.local).push(option);
 		applyDirectives(this.directives, command);
 	}
+	/** The current command. */
+	get command() {
+		if (!this.current) throw new Error("The scope hasn't entered a command");
+		return this.current;
+	}
+	/** Whether the current command has subcommands of its own or inherits any. */
+	get hasSubcommands() {
+		return this.current?.subcommands !== void 0 || this.inheritedSubcommands.length > 0;
+	}
+	/**
+	* The subcommands the next token can name: the current command's own,
+	* followed by each inherited one that an earlier one doesn't shadow a name
+	* of. Hidden ones are included.
+	*/
+	subcommands() {
+		const own = this.current?.subcommands ?? [];
+		if (this.inheritedSubcommands.length === 0) return own;
+		const all = [...own];
+		for (const candidate of this.inheritedSubcommands) if (!asArray(candidate.name).some((name) => all.some((earlier) => hasName(earlier.name, name)))) all.push(candidate);
+		return all;
+	}
+	/**
+	* Find the subcommand `token` names: one of the current command's own, or
+	* else an inherited persistent one. An exact name always wins. With
+	* `subcommandsMatchUniquePrefix`, a token that's a prefix of exactly one of
+	* the command's own names matches that command, unless `exactOnly`. A hidden
+	* or inherited command only matches its exact name, so it can't make a
+	* visible command's prefix ambiguous or take a prefix meant as an argument,
+	* and an empty token is no command's prefix.
+	*/
+	matchSubcommand(token, exactOnly = false) {
+		const own = this.current?.subcommands ?? [];
+		for (const candidate of own) if (hasName(candidate.name, token)) return { command: candidate };
+		for (const candidate of this.inheritedSubcommands) if (hasName(candidate.name, token)) return { command: candidate };
+		const matches = this.directives.subcommandsMatchUniquePrefix && !exactOnly ? prefixMatches(own, token) : [];
+		if (matches.length === 1) return { command: matches[0] };
+		return new NoSubcommand(this.subcommands(), token, matches);
+	}
 	/** The option `name` refers to, if any. */
 	resolve(name) {
 		const { local, persistent } = this;
@@ -343,15 +352,16 @@ var OptionScope = class OptionScope {
 	/**
 	* The options that can be used here, in definition order, each with only
 	* its live names: the names that still refer to it. Options with every name
-	* shadowed are left out.
+	* shadowed are left out. Where the next token can name a subcommand, as
+	* `subcommands` says, a name that one matches is that subcommand's.
 	*/
-	live() {
+	live(subcommands = null) {
 		const owner = /* @__PURE__ */ new Map();
 		for (const options of [this.persistent, this.local]) for (const option of options) for (const name of asArray(option.name)) owner.set(name, option);
 		const pick = (options) => {
 			const picked = [];
 			for (const option of options) {
-				const names = asArray(option.name).filter((name) => owner.get(name) === option);
+				const names = asArray(option.name).filter((name) => owner.get(name) === option && !(subcommands && this.matchSubcommand(name, subcommands.exactOnly).command));
 				if (names.length > 0) picked.push({
 					option,
 					names
@@ -364,9 +374,12 @@ var OptionScope = class OptionScope {
 			persistent: pick(this.persistent)
 		};
 	}
-	/** The options a user can see here: the {@link live} ones that aren't hidden. */
+	/**
+	* The options a user can see at the start of the current command: the
+	* {@link live} ones that aren't hidden, without the names a subcommand takes.
+	*/
 	visible() {
-		const { local, persistent } = this.live();
+		const { local, persistent } = this.live(this.hasSubcommands ? { exactOnly: false } : null);
 		const shown = (visible) => !visible.option.hidden;
 		return {
 			local: local.filter(shown),
@@ -375,8 +388,9 @@ var OptionScope = class OptionScope {
 	}
 	/** The live names of each option a user could have meant, for "did you mean" suggestions. */
 	suggestionNames() {
-		const { local, persistent } = this.visible();
-		return [...local, ...persistent].map((visible) => visible.names);
+		const { local, persistent } = this.live();
+		const shown = (visible) => !visible.option.hidden;
+		return [...local, ...persistent].filter(shown).map((visible) => visible.names);
 	}
 	/** The options that must be used, local first. */
 	required() {
@@ -407,6 +421,46 @@ var OptionScope = class OptionScope {
 		if (typeof required === "string") return required;
 		return required ? this.directives.optionArgSeparators[0] ?? "=" : null;
 	}
+	/** Whether the parser splits an option from its value at `separator` here. */
+	readsSeparator(separator) {
+		return this.directives.optionArgSeparators.includes(separator);
+	}
+	/** The separator that `text` starts with, or "" if none. Used after a short option. */
+	leadingSeparator(text) {
+		for (const separator of this.directives.optionArgSeparators) if (text.startsWith(separator)) return separator;
+		return "";
+	}
+	/**
+	* The separator that appears first in `token`, so the value after it can
+	* contain the other separators. When two separators start at the same place,
+	* the longer one wins. Null if there's none, or if the one found is empty.
+	*/
+	firstSeparator(token) {
+		let found = "";
+		let index = -1;
+		for (const candidate of this.directives.optionArgSeparators) {
+			const at = token.indexOf(candidate);
+			if (at === -1) continue;
+			if (index === -1 || at < index || at === index && candidate.length > found.length) {
+				found = candidate;
+				index = at;
+			}
+		}
+		return found ? {
+			index,
+			separator: found
+		} : null;
+	}
+	/**
+	* Why `option`, used as `name`, can't take a value given after `separator`,
+	* or null if it can. A separate token has the separator "".
+	*/
+	separatorProblem(option, name, separator) {
+		const required = option.requiresSeparator;
+		if (typeof required === "string" && separator !== required) return `Incorrect separator, use '${required}' instead of '${separator}'`;
+		if (required === true && separator === "") return `Missing separator, use '${this.requiredSeparator(option)}' between ${name} and its value`;
+		return null;
+	}
 };
 const optionKeys = /* @__PURE__ */ new WeakMap();
 /**
@@ -428,6 +482,11 @@ function optionKey(option) {
 function hasName(names, name) {
 	return typeof names === "string" ? names === name : names.includes(name);
 }
+/** The visible commands that `token` is a prefix of a name of, each listed once. */
+function prefixMatches(subcommands, token) {
+	if (token === "") return [];
+	return subcommands.filter((candidate) => !candidate.hidden && asArray(candidate.name).some((name) => name.startsWith(token)));
+}
 // src/help.ts
 function dedent(str) {
 	if (str[0] !== "\n") return str;
@@ -474,14 +533,15 @@ const helpCommand = {
 	action({ path, args, help }) {
 		const self = path[path.length - 1];
 		const helpPath = path.slice(0, -1);
+		const scope = CommandScope.at(helpPath);
 		for (const name of args) {
 			const command = helpPath[helpPath.length - 1];
 			if (!command.subcommands) break;
-			const scope = OptionScope.at(helpPath);
-			const match = matchSubcommand(command.subcommands, name, scope.directives, false, scope.inheritedSubcommands);
+			const match = scope.matchSubcommand(name);
 			if (match.command === self && !command.subcommands.includes(self)) break;
 			if (match.command) {
 				helpPath.push(match.command);
+				scope.enter(match.command);
 				continue;
 			}
 			if (!command.requiresSubcommand && getMaxArgs(command.args) > 0) break;
@@ -508,7 +568,7 @@ function getSubcommandPathString(commands) {
 }
 function getSections(commands) {
 	const command = commands[commands.length - 1];
-	const scope = OptionScope.at(commands);
+	const scope = CommandScope.at(commands);
 	const show = ({ option, names }) => optionToString(option, scope.forms(option, names));
 	const description = command.description;
 	const defaultDesc = "No description";
@@ -712,32 +772,9 @@ var MissingRequiredOption = class extends ParseError {
 	}
 };
 // src/parse.ts
-/** The first of `separators` that `text` starts with, or "" if none. */
-function leadingSeparator(text, separators) {
-	for (const sep of separators) if (text.startsWith(sep)) return sep;
-	return "";
-}
-/**
-* Find the separator that appears first in `token`, so the value after it can
-* contain the other separators. When two separators start at the same place,
-* the longer one wins. Returns null if there's no separator, or if the one
-* found is empty.
-*/
-function firstSeparator(token, separators) {
-	let sep = "";
-	let index = -1;
-	for (const candidate of separators) {
-		const at = token.indexOf(candidate);
-		if (at === -1) continue;
-		if (index === -1 || at < index || at === index && candidate.length > sep.length) {
-			sep = candidate;
-			index = at;
-		}
-	}
-	return sep ? {
-		index,
-		sep
-	} : null;
+/** How many times `option` can be used. */
+function repeatLimit(option) {
+	return typeof option.isRepeatable === "number" ? option.isRepeatable : Infinity;
 }
 /**
 * Throw if the options used break a `dependsOn` or `exclusiveOn` rule, or if
@@ -755,25 +792,21 @@ function checkOptionRules(options, seenOptions, required, context) {
 	for (const option of required) for (const name of asArray(option.name)) if (!options.has(name)) throw new MissingRequiredOption(name, context);
 }
 /**
-* The state of reading one command line in a single pass. This is the only
-* code that decides what each input token is. When `strict`, it throws on the
-* first problem, which is what {@link parse} needs. Otherwise it never throws:
-* it skips whatever is invalid and keeps going, so {@link readNext} can still
-* read a line that's wrong at the moment. Each method handles one kind of
-* token.
+* The state of reading one command line, one token at a time. This is the
+* only code that decides what each input token is. It never throws: it skips
+* whatever is invalid and keeps going, so {@link readNext} can still read a
+* line that's wrong at the moment, and it keeps the first problem it finds for
+* {@link parse} to throw. Each method handles one kind of token, and says what
+* the token was read as.
 */
 var Scanner = class {
-	strict;
 	path;
 	optionAction = void 0;
 	args = [];
 	options = /* @__PURE__ */ new Map();
 	seenOptions = [];
 	argSeparatorIndex = -1;
-	scope = new OptionScope();
-	subcommands = void 0;
-	commandArgsMin = 0;
-	commandArgsMax = 0;
+	scope = new CommandScope();
 	directives = this.scope.directives;
 	hasFoundArg = false;
 	openOption = null;
@@ -786,40 +819,60 @@ var Scanner = class {
 	valuesMin = 0;
 	valuesMax = 0;
 	valueArgs = [];
-	requiredSeparator = false;
+	/**
+	* Makes the error for the first token that can't be read the way it's
+	* written, like an unknown option or a value an option doesn't take.
+	* {@link parse} stops there.
+	*/
+	problem = null;
 	tooManyArgs = null;
 	repeatedUses = /* @__PURE__ */ new Map();
-	attached = null;
-	constructor(spec, strict) {
-		this.strict = strict;
+	constructor(spec) {
 		this.path = [spec];
-		this.enterCommand(spec);
+		this.scope.enter(spec);
 	}
 	ctx() {
-		return { path: this.path };
+		return { path: [...this.path] };
 	}
 	/** Whether the open option can take the next token as a value. */
 	get hasRoomForValue() {
 		return this.valueCount < this.separateValueMax;
 	}
-	enterCommand(command) {
-		this.scope.enter(command);
-		this.subcommands = command.subcommands;
-		this.commandArgsMin = getMinArgs(command.args);
-		this.commandArgsMax = getMaxArgs(command.args);
-	}
 	findOption(name) {
 		return this.scope.resolve(name);
 	}
+	/**
+	* Keep the problem `make` describes if it's the first. The error is only
+	* made if {@link parse} throws it, since a lenient read never needs it and
+	* an error is slow to make. So `make` can't read anything later tokens change.
+	*/
+	fail(make) {
+		if (!this.problem) {
+			const ctx = this.ctx();
+			this.problem = () => make(ctx);
+		}
+	}
+	/** Keep the first argument the command has no room for, like {@link fail}. */
+	failArgs(make) {
+		if (!this.tooManyArgs) {
+			const ctx = this.ctx();
+			this.tooManyArgs = () => make(ctx);
+		}
+	}
 	unknownOption(option) {
-		return new UnknownOption(option, this.scope.suggestionNames(), this.ctx());
+		if (!this.problem) {
+			const names = this.scope.suggestionNames();
+			this.fail((ctx) => new UnknownOption(option, names, ctx));
+		}
 	}
 	endOption() {
 		const values = this.values;
-		if (this.strict && values) {
+		if (values) {
 			const given = values.length - this.valuesStart;
-			if (given < this.valuesMin) throw new TooFewOptionArguments(this.openOptionName, this.valuesMin, this.valuesMax, this.ctx());
-			addDefaults(values, this.valueArgs, given);
+			if (given < this.valuesMin) {
+				const { openOptionName, valuesMin, valuesMax } = this;
+				this.fail((ctx) => new TooFewOptionArguments(openOptionName, valuesMin, valuesMax, ctx));
+			} else addDefaults(values, this.valueArgs, given);
 		}
 		this.values = null;
 	}
@@ -842,7 +895,6 @@ var Scanner = class {
 		const options = this.options;
 		let optionValues;
 		if (option.isRepeatable) {
-			const maxRepeat = option.isRepeatable === true ? Infinity : option.isRepeatable;
 			const key = optionKey(option);
 			let uses = this.repeatedUses.get(key);
 			if (!uses) {
@@ -852,7 +904,7 @@ var Scanner = class {
 				};
 				this.repeatedUses.set(key, uses);
 			}
-			if (this.strict && uses.count >= maxRepeat) throw new ParseError(this.ctx(), "Too many repetitions");
+			if (uses.count >= repeatLimit(option)) this.fail((ctx) => new ParseError(ctx, "Too many repetitions"));
 			uses.count += 1;
 			for (const other of names) options.set(other, uses.values);
 			if (!option.args) {
@@ -866,150 +918,162 @@ var Scanner = class {
 		}
 		this.valuesMin = this.valueMin;
 		this.valuesMax = getMaxArgs(option.args);
-		this.requiredSeparator = option.requiresSeparator ?? false;
 		if (this.valuesMax > 0) {
 			this.values = optionValues;
 			this.valuesStart = optionValues.length;
 			this.valueArgs = asArray(option.args);
 		}
 	}
-	/**
-	* Add a value to the open option. Returns whether it's a value the option
-	* accepts. A lenient read keeps going either way.
-	*/
+	/** Add a value to the open option. Returns whether it's a value the option accepts. */
 	addValue(value, separator) {
 		this.valueCount += 1;
 		if (!this.values) {
-			if (this.strict) throw new InvalidOptionArg(this.openOptionName, this.ctx());
+			const name = this.openOptionName;
+			this.fail((ctx) => new InvalidOptionArg(name, ctx));
 			return false;
 		}
-		const requiredSeparator = this.requiredSeparator;
-		let accepted = true;
-		if (typeof requiredSeparator === "string" && separator !== requiredSeparator) {
-			if (this.strict) throw new ParseError(this.ctx(), `Incorrect separator, use '${requiredSeparator}' instead of '${separator}'`);
-			accepted = false;
-		}
-		if (requiredSeparator === true && separator === "") {
-			if (this.strict) {
-				const suggested = this.scope.requiredSeparator(this.openOption);
-				throw new ParseError(this.ctx(), `Missing separator, use '${suggested}' between ${this.openOptionName} and its value`);
-			}
-			accepted = false;
-		}
+		const problem = this.scope.separatorProblem(this.openOption, this.openOptionName, separator);
+		if (problem) this.fail((ctx) => new ParseError(ctx, problem));
 		this.values.push(value);
-		return accepted;
+		return problem === null;
+	}
+	/** Add a separate token as a value of the open option. */
+	value(token) {
+		this.addValue(token, "");
+		return {
+			kind: "value",
+			option: this.openOption
+		};
 	}
 	/**
-	* Add a value attached to the option's own token, the token at `index`,
-	* starting at `start`. It's the option's only value, so no later token can be
-	* one.
+	* Add a value attached to the option's own token, starting at `start`. It's
+	* the option's only value, so no later token can be one. Returns where the
+	* value starts, or null if the option doesn't accept it.
 	*/
-	addAttachedValue(index, start, value, separator) {
-		if (this.addValue(value, separator)) this.attached = {
-			option: this.openOption,
-			index,
-			start
-		};
+	addAttachedValue(start, value, separator) {
+		const option = this.openOption;
+		const accepted = this.addValue(value, separator);
 		this.valueMin = this.separateValueMax = 0;
+		return accepted ? {
+			option,
+			start
+		} : null;
 	}
 	/**
 	* Whether the command already has all the arguments it takes. A command that
 	* requires a subcommand takes none.
 	*/
 	get argsAreFull() {
-		const path = this.path;
-		return path[path.length - 1].requiresSubcommand === true || this.args.length >= this.commandArgsMax;
+		return this.scope.command.requiresSubcommand === true || this.args.length >= this.scope.argsMax;
 	}
 	addArg(value) {
 		this.endOption();
-		if (this.strict && this.argsAreFull) this.tooManyArgs ??= new TooManyArguments(value, this.ctx());
+		if (this.argsAreFull) this.failArgs((ctx) => new TooManyArguments(value, ctx));
 		this.args.push(value);
+		return { kind: "argument" };
 	}
-	/** Read `--` and every token after it as arguments. */
-	argSeparator(input, index) {
+	/** Read `--`. Every token after it is an argument. */
+	argSeparator() {
 		this.closeOption();
-		const command = this.path[this.path.length - 1];
-		if (this.strict && this.argsAreFull && !command.requiresSubcommand) this.tooManyArgs ??= new ParseError(this.ctx(), "Unexpected argument '--', did you mean to use an option instead?");
+		const command = this.scope.command;
+		if (this.argsAreFull && !command.requiresSubcommand) this.failArgs((ctx) => new ParseError(ctx, "Unexpected argument '--', did you mean to use an option instead?"));
 		this.argSeparatorIndex = this.args.length;
-		for (index += 1; index < input.length; index++) this.addArg(input[index]);
+		return { kind: "separator" };
 	}
 	/**
-	* Whether the next token can name a subcommand, its own or an inherited
-	* one. It can't once an argument is found, or while the open option needs
-	* the next token as its value. A required or variadic option value takes
-	* priority over a subcommand.
+	* How the next token can name a subcommand, its own or an inherited one, or
+	* null if it can't. It can't once an argument is found, or while the open
+	* option needs the next token as its value. A required or variadic option
+	* value takes priority over a subcommand. A short optional value could be a
+	* prefix of a subcommand's name, so only an exact name can end an option
+	* that still has room.
 	*/
-	get canMatchSubcommand() {
-		if (this.hasFoundArg) return false;
-		if (!this.subcommands && this.scope.inheritedSubcommands.length === 0) return false;
-		return !(this.valueCount < this.valueMin || this.hasRoomForValue && this.separateValueMax === Infinity);
+	get subcommandMatching() {
+		if (this.hasFoundArg || !this.scope.hasSubcommands) return null;
+		if (this.valueCount < this.valueMin || this.hasRoomForValue && this.separateValueMax === Infinity) return null;
+		return { exactOnly: this.hasRoomForValue };
 	}
 	/**
 	* The subcommand the next token enters if it's `token`, or why it enters
 	* none. Null if the next token can't be a subcommand at all.
 	*/
 	subcommandFor(token) {
-		if (!this.canMatchSubcommand) return null;
-		return matchSubcommand(this.subcommands ?? [], token, this.directives, this.hasRoomForValue, this.scope.inheritedSubcommands);
+		const matching = this.subcommandMatching;
+		return matching && this.scope.matchSubcommand(token, matching.exactOnly);
 	}
 	enterSubcommand(command) {
 		this.closeOption();
 		this.path.push(command);
-		this.enterCommand(command);
+		this.scope.enter(command);
+		return {
+			kind: "subcommand",
+			command
+		};
 	}
 	/** Read a token like `-abc`, `+x` or `-ovalue`. */
-	shortOptions(token, index) {
+	shortOptions(token) {
 		const leadingChar = token[0];
 		const dashOption = this.findOption(leadingChar);
 		if (dashOption?.args && !this.findOption(token.slice(0, 2))) {
 			this.useOption(dashOption, leadingChar);
-			this.addAttachedValue(index, 1, token.slice(1), "");
-			return;
+			const attached = this.addAttachedValue(1, token.slice(1), "");
+			return {
+				kind: "options",
+				options: [dashOption],
+				attached
+			};
 		}
+		const used = [];
+		let attached = null;
 		for (let char = 1; char < token.length; char++) {
 			const optionName = leadingChar + token[char];
 			const option = this.findOption(optionName);
 			if (!option) {
-				if (char === 1 && this.hasRoomForValue) {
-					this.addValue(token, "");
-					return;
-				}
-				if (this.strict) throw this.unknownOption(optionName);
+				if (char === 1 && this.hasRoomForValue) return this.value(token);
+				this.unknownOption(optionName);
 				continue;
 			}
 			this.useOption(option, optionName);
-			if (char === token.length - 1) return;
-			const sep = leadingSeparator(token.slice(char + 1), this.directives.optionArgSeparators);
+			used.push(option);
+			if (char === token.length - 1) break;
+			const sep = this.scope.leadingSeparator(token.slice(char + 1));
 			if (option.args || sep && !this.findOption(leadingChar + token[char + 1])) {
 				const argStart = char + sep.length + 1;
-				this.addAttachedValue(index, argStart, token.slice(argStart), sep);
-				return;
+				attached = this.addAttachedValue(argStart, token.slice(argStart), sep);
+				break;
 			}
 		}
+		return used.length > 0 ? {
+			kind: "options",
+			options: used,
+			attached
+		} : { kind: "unknown" };
 	}
 	/**
 	* Read a token like `--name` or `--name=value`, or any token when options
-	* aren't POSIX compliant. Returns false if the token should be an argument.
+	* aren't POSIX compliant. Returns null if the token should be an argument.
 	*/
-	longOption(token, index) {
-		const found = firstSeparator(token, this.directives.optionArgSeparators);
+	longOption(token) {
+		const found = this.scope.firstSeparator(token);
 		const optionName = found ? token.slice(0, found.index) : token;
 		const option = this.findOption(optionName);
 		if (option) {
 			this.useOption(option, optionName);
+			let attached = null;
 			if (found) {
-				const valueStart = found.index + found.sep.length;
-				this.addAttachedValue(index, valueStart, token.slice(valueStart), found.sep);
+				const valueStart = found.index + found.separator.length;
+				attached = this.addAttachedValue(valueStart, token.slice(valueStart), found.separator);
 			}
-			return true;
-		}
-		if (this.directives.flagsArePosixNoncompliant) return false;
-		if (this.hasRoomForValue) {
-			this.addValue(token, "");
-			return true;
+			return {
+				kind: "options",
+				options: [option],
+				attached
+			};
 		}
-		if (this.strict) throw this.unknownOption(optionName);
-		return true;
+		if (this.directives.flagsArePosixNoncompliant) return null;
+		if (this.hasRoomForValue) return this.value(token);
+		this.unknownOption(optionName);
+		return { kind: "unknown" };
 	}
 	/**
 	* Read a token that isn't `--`, a subcommand or an option. It's a value of
@@ -1018,34 +1082,39 @@ var Scanner = class {
 	* subcommand, if it could have been one.
 	*/
 	valueOrArg(token, unmatched) {
-		if (this.hasRoomForValue) {
-			this.addValue(token, "");
-			return;
-		}
-		if (this.strict && unmatched && this.argsAreFull) {
-			const command = this.path[this.path.length - 1];
-			if (command.subcommands?.length || command.requiresSubcommand) {
+		if (this.hasRoomForValue) return this.value(token);
+		if (unmatched && this.argsAreFull) {
+			const command = this.scope.command;
+			if (command.subcommands?.length || command.requiresSubcommand) this.failArgs((ctx) => {
 				const { message, didYouMean } = unmatched.reason();
-				this.tooManyArgs ??= new ParseError(this.ctx(), message, didYouMean);
-			}
+				return new ParseError(ctx, message, didYouMean);
+			});
 		}
 		this.hasFoundArg = true;
-		this.addArg(token);
+		return this.addArg(token);
 	}
 	/**
-	* Throw if the finished command line is missing anything. Returns the action
-	* to run.
+	* Throw if the finished command line is missing anything. Returns what it
+	* was parsed as. Only call this when there's no {@link problem}.
 	*/
 	finish() {
-		const command = this.path[this.path.length - 1];
+		const command = this.scope.command;
 		const showsUsage = command.requiresSubcommand && !command.action && this.args.length === 0;
 		const skipsChecks = this.optionAction !== void 0 || showsUsage;
-		if (!skipsChecks && this.tooManyArgs) throw this.tooManyArgs;
-		if (!skipsChecks && this.args.length < this.commandArgsMin) throw new TooFewArguments(this.commandArgsMin, this.commandArgsMax, this.ctx());
+		if (!skipsChecks && this.tooManyArgs) throw this.tooManyArgs();
+		if (!skipsChecks && this.args.length < this.scope.argsMin) throw new TooFewArguments(this.scope.argsMin, this.scope.argsMax, this.ctx());
 		this.endOption();
+		if (this.problem) throw this.problem();
 		if (!skipsChecks) checkOptionRules(this.options, this.seenOptions, this.scope.required(), this.ctx());
-		if (!command.requiresSubcommand && this.args.length >= this.commandArgsMin) addDefaults(this.args, asArray(command.args), this.args.length);
-		return this.optionAction ?? command.action ?? usage;
+		if (!command.requiresSubcommand && this.args.length >= this.scope.argsMin) addDefaults(this.args, asArray(command.args), this.args.length);
+		return {
+			path: this.path,
+			action: this.optionAction ?? command.action ?? usage,
+			args: this.args,
+			argSeparatorIndex: this.argSeparatorIndex,
+			options: this.options,
+			defaults: (name) => this.defaults(name)
+		};
 	}
 	/** See {@link ParseResult.defaults}. */
 	defaults(name) {
@@ -1058,42 +1127,41 @@ var Scanner = class {
 	}
 	/** Whether using `option` next would go over its repeat limit or break an `exclusiveOn` rule. */
 	conflicts(option) {
-		const names = asArray(option.name);
+		if ((this.repeatedUses.get(optionKey(option))?.count ?? 0) >= repeatLimit(option)) return true;
 		const options = this.options;
-		if (typeof option.isRepeatable === "number") {
-			if ((this.repeatedUses.get(optionKey(option))?.count ?? 0) >= option.isRepeatable) return true;
-		}
 		if (option.exclusiveOn?.some((name) => options.has(name))) return true;
+		const names = asArray(option.name);
 		return this.seenOptions.some((seen) => seen.exclusiveOn?.some((name) => names.includes(name)));
 	}
 	/** The options the next token can use. See {@link NextToken.options}. */
 	usableOptions() {
 		const used = new Set(this.seenOptions.map(optionKey));
-		const { local, persistent } = this.scope.live();
+		const { local, persistent } = this.scope.live(this.subcommandMatching);
 		const usable = [];
 		for (const { option, names } of [...local, ...persistent]) {
 			if (this.conflicts(option)) continue;
-			const typeable = names.filter((name) => !this.subcommandFor(name)?.command);
-			if (typeable.length === 0) continue;
 			usable.push({
 				option,
-				forms: this.scope.forms(option, typeable),
+				forms: this.scope.forms(option, names),
 				used: used.has(optionKey(option))
 			});
 		}
 		return usable;
 	}
-	/** What the next token can be. See {@link readNext}. */
+	/**
+	* What the next token can be. See {@link readNext}. Reading more tokens
+	* doesn't change what this returns.
+	*/
 	next() {
 		const open = this.openOption && this.hasRoomForValue ? this.openOption : null;
-		const command = this.path[this.path.length - 1];
+		const command = this.scope.command;
 		const afterSeparator = this.argSeparatorIndex !== -1;
 		const optionsAllowed = !afterSeparator && this.optionsAllowed;
 		return {
-			path: this.path,
-			directives: this.directives,
+			path: [...this.path],
+			directives: { ...this.directives },
 			optionsAllowed,
-			subcommands: !afterSeparator && this.canMatchSubcommand ? withInherited(this.subcommands ?? [], this.scope.inheritedSubcommands) : [],
+			subcommands: !afterSeparator && this.subcommandMatching ? this.scope.subcommands() : [],
 			options: optionsAllowed ? this.usableOptions() : [],
 			value: open && {
 				option: open,
@@ -1103,79 +1171,27 @@ var Scanner = class {
 			arg: open ? void 0 : argAt(asArray(command.args), this.args.length)
 		};
 	}
-	/** Read the token at `index`, the next one, and say what it was read as. */
-	readAndClassify(input, index) {
-		if (this.argSeparatorIndex !== -1) return { kind: "argument" };
-		const depth = this.path.length;
-		const seen = this.seenOptions.length;
-		const args = this.args.length;
-		const values = this.valueCount;
-		if (this.readAt(input, index)) return { kind: "separator" };
-		if (this.path.length > depth) return {
-			kind: "subcommand",
-			command: this.path[depth]
-		};
-		if (this.seenOptions.length > seen) {
-			const found = this.attachedAt(index);
-			const attached = found && {
-				option: found.option,
-				start: found.start
-			};
-			return {
-				kind: "options",
-				options: this.seenOptions.slice(seen),
-				attached
-			};
-		}
-		if (this.args.length > args) return { kind: "argument" };
-		if (this.valueCount > values) return {
-			kind: "value",
-			option: this.openOption
-		};
-		return { kind: "unknown" };
-	}
-	/** The value attached to the token at `index`, if it has one the option accepts. */
-	attachedAt(index) {
-		return this.attached?.index === index ? this.attached : null;
-	}
 	/** Whether the next token can be an option. Once options must stop, every token is an argument. */
 	get optionsAllowed() {
 		return !(this.directives.optionsMustPrecedeArguments && this.hasFoundArg);
 	}
-	/** Read every token of `input`. */
-	read(input) {
-		for (let index = 0; index < input.length; index++) if (this.readAt(input, index)) return;
-	}
-	/**
-	* Read the token at `index`. Returns true if it was `--`, which reads every
-	* token after it too.
-	*/
-	readAt(input, index) {
-		const token = input[index];
+	read(token) {
+		if (this.argSeparatorIndex !== -1) return this.addArg(token);
 		const optionsAllowed = this.optionsAllowed;
-		if (token === "--" && optionsAllowed) {
-			this.argSeparator(input, index);
-			return true;
-		}
+		if (token === "--" && optionsAllowed) return this.argSeparator();
 		const subcommand = this.subcommandFor(token);
-		if (subcommand?.command) {
-			this.enterSubcommand(subcommand.command);
-			return false;
-		}
+		if (subcommand?.command) return this.enterSubcommand(subcommand.command);
 		if (optionsAllowed) {
 			const flagsArePosixNoncompliant = this.directives.flagsArePosixNoncompliant;
 			const first = token.charCodeAt(0);
 			const isDoubleDash = first === 45 && token.charCodeAt(1) === 45;
-			if (!flagsArePosixNoncompliant && token.length > 1 && (first === 45 || first === 43) && !isDoubleDash) {
-				this.shortOptions(token, index);
-				return false;
-			}
+			if (!flagsArePosixNoncompliant && token.length > 1 && (first === 45 || first === 43) && !isDoubleDash) return this.shortOptions(token);
 			if (flagsArePosixNoncompliant || token.length > 2 && isDoubleDash) {
-				if (this.longOption(token, index)) return false;
+				const reading = this.longOption(token);
+				if (reading) return reading;
 			}
 		}
-		this.valueOrArg(token, subcommand);
-		return false;
+		return this.valueOrArg(token, subcommand);
 	}
 };
 /** The argument at `index`, reusing a final variadic argument. */
@@ -1186,17 +1202,19 @@ function argAt(args, index) {
 }
 /**
 * Work out what the token after `before` can be, and how the parser reads
-* `partial` if it's an option with a value attached. Reads leniently, so a
-* line that's wrong at the moment still has an answer. Completion is built on
-* this.
+* `partial`: whether it's an option, and if so, whether it has a value
+* attached. Reads leniently, so a line that's wrong at the moment still has
+* an answer. Completion is built on this.
 */
 function readNext(spec, before, partial) {
-	const s = new Scanner(spec, false);
-	s.read(before);
+	const s = new Scanner(spec);
+	for (const token of before) s.read(token);
 	const next = s.next();
 	let attached = null;
+	let partialIsOption = false;
 	if (partial !== "" && next.optionsAllowed) {
-		const reading = readToken(spec, before, partial);
+		const reading = s.read(partial);
+		partialIsOption = reading.kind === "options" || reading.kind === "unknown" || reading.kind === "separator";
 		const found = reading.kind === "options" ? reading.attached : null;
 		const arg = found && asArray(found.option.args)[0];
 		if (found && arg) attached = {
@@ -1208,19 +1226,11 @@ function readNext(spec, before, partial) {
 	}
 	return {
 		...next,
-		attached
+		attached,
+		partialIsOption
 	};
 }
 /**
-* Say what the parser reads `token` as when it comes after `before`. Reads
-* leniently, like {@link readNext}.
-*/
-function readToken(spec, before, token) {
-	const s = new Scanner(spec, false);
-	s.read(before);
-	return s.readAndClassify([...before, token], before.length);
-}
-/**
 * Parse the input tokens using the given CLI spec.
 *
 * This returns a `ParseResult`, which contains the array of
@@ -1230,17 +1240,12 @@ function readToken(spec, before, token) {
 * If parsing fails, this function throws.
 */
 function parse(input, spec) {
-	const s = new Scanner(spec, true);
-	s.read(input);
-	const action = s.finish();
-	return {
-		path: s.path,
-		action,
-		args: s.args,
-		argSeparatorIndex: s.argSeparatorIndex,
-		options: s.options,
-		defaults: (name) => s.defaults(name)
-	};
+	const s = new Scanner(spec);
+	for (const token of input) {
+		s.read(token);
+		if (s.problem) throw s.problem();
+	}
+	return s.finish();
 }
 // src/completion.ts
 const SHELLS = [
@@ -1320,11 +1325,18 @@ async function argValues(arg, tokens, partial) {
 }
 /** Decide which kinds of candidate the word being completed can use. */
 function wantedCandidates(next, req) {
-	const posixNoncompliant = next.directives.flagsArePosixNoncompliant;
-	const partialIsOption = next.optionsAllowed && !posixNoncompliant && (req.partial.startsWith("-") || req.partial.startsWith("+"));
+	if (!req.gateOptions || next.directives.flagsArePosixNoncompliant) return {
+		wantValues: true,
+		wantOptions: true,
+		wantSubcommand: () => true
+	};
+	const partial = req.partial;
+	const wantValues = !next.partialIsOption;
+	const starts = (name) => partial !== "" && name.startsWith(partial);
 	return {
-		wantValues: !(req.gateOptions && partialIsOption),
-		wantOptions: !req.gateOptions || partialIsOption || posixNoncompliant
+		wantValues,
+		wantOptions: next.options.some(({ forms }) => forms.some(({ name }) => starts(name))),
+		wantSubcommand: (name) => wantValues || starts(name)
 	};
 }
 /**
@@ -1344,17 +1356,17 @@ async function completeRuntime(req) {
 	}
 	if (next.value?.required) return next.value.arg ? argValues(next.value.arg, tokens, req.partial) : [];
 	const candidates = [];
-	const { wantValues, wantOptions } = wantedCandidates(next, req);
+	const { wantValues, wantOptions, wantSubcommand } = wantedCandidates(next, req);
 	if (wantValues) {
 		const arg = next.value ? next.value.arg : next.arg;
 		if (arg) candidates.push(...await argValues(arg, tokens, req.partial));
-		for (const sub of visibleSubcommands(next.subcommands)) {
-			const description = firstLine(sub.description);
-			for (const token of makeArray(sub.name)) candidates.push({
-				value: token,
-				description
-			});
-		}
+	}
+	for (const sub of visibleSubcommands(next.subcommands)) {
+		const description = firstLine(sub.description);
+		for (const token of makeArray(sub.name)) if (wantSubcommand(token)) candidates.push({
+			value: token,
+			description
+		});
 	}
 	if (wantOptions) candidates.push(...optionCandidates(next));
 	return candidates;