@clo4/cli 3.0.0 → 3.0.1

package/dist/testing.js

@@ -111,18 +111,62 @@ function applyDirectives(directives, command) {
 	if (typeof configured.optionsMustPrecedeArguments === "boolean") directives.optionsMustPrecedeArguments = configured.optionsMustPrecedeArguments;
 	if (typeof configured.flagsArePosixNoncompliant === "boolean") directives.flagsArePosixNoncompliant = configured.flagsArePosixNoncompliant;
 }
+// src/subcommands.ts
+/**
+* A token that names no subcommand. The reason is only worked out when asked
+* for, since most tokens the parser tries aren't subcommands.
+*/
+var NoSubcommand = class {
+	subcommands;
+	token;
+	prefixOf;
+	command = null;
+	/**
+	* `prefixOf` are the commands `token` is a prefix of a name of, where
+	* prefixes match. There is never exactly one of them.
+	*/
+	constructor(subcommands, token, prefixOf) {
+		this.subcommands = subcommands;
+		this.token = token;
+		this.prefixOf = prefixOf;
+	}
+	/** Why the token names none of the subcommands, as an error message and suggestions. */
+	reason() {
+		const token = this.token;
+		if (token === "") return { message: "Expected a command, but the value was empty" };
+		if (this.prefixOf.length > 0) return { message: `Ambiguous command '${token}', could be: ${this.prefixOf.flatMap((command) => asArray(command.name).filter((name) => name.startsWith(token))).join(", ")}` };
+		const choices = visibleSubcommands(this.subcommands).map((command) => asArray(command.name));
+		return {
+			message: `Unknown command '${token}'`,
+			didYouMean: {
+				input: token,
+				choices
+			}
+		};
+	}
+};
+/** The subcommands that help, completion and suggestions show. */
+function visibleSubcommands(subcommands) {
+	return subcommands?.filter((subcommand) => !subcommand.hidden) ?? [];
+}
+/** The action of a command that has none of its own: print the command's help. */
+const usage = ({ help }) => {
+	print(help());
+	return 0;
+};
 // 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. */
@@ -134,44 +178,89 @@ 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;
-		for (let i = local.length - 1; i >= 0; i--) if (hasName$1(local[i].name, name)) return local[i];
-		for (let i = persistent.length - 1; i >= 0; i--) if (hasName$1(persistent[i].name, name)) return persistent[i];
+		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;
 	}
 	/**
 	* 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
@@ -184,9 +273,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),
@@ -195,8 +287,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() {
@@ -227,6 +320,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();
 /**
@@ -245,88 +378,14 @@ function optionKey(option) {
 	}
 	return key;
 }
-function hasName$1(names, name) {
+function hasName(names, name) {
 	return typeof names === "string" ? names === name : names.includes(name);
 }
-// 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(candidate, token)) return { command: candidate };
-	for (const candidate of inherited) if (hasName(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(earlier, name)))) all.push(candidate);
-	return all;
-}
-function hasName(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.
-*/
-var NoSubcommand = class {
-	subcommands;
-	token;
-	prefixOf;
-	command = null;
-	/**
-	* `prefixOf` are the commands `token` is a prefix of a name of, where
-	* prefixes match. There is never exactly one of them.
-	*/
-	constructor(subcommands, token, prefixOf) {
-		this.subcommands = subcommands;
-		this.token = token;
-		this.prefixOf = prefixOf;
-	}
-	/** Why the token names none of the subcommands, as an error message and suggestions. */
-	reason() {
-		const token = this.token;
-		if (token === "") return { message: "Expected a command, but the value was empty" };
-		if (this.prefixOf.length > 0) return { message: `Ambiguous command '${token}', could be: ${this.prefixOf.flatMap((command) => asArray(command.name).filter((name) => name.startsWith(token))).join(", ")}` };
-		const choices = visibleSubcommands(this.subcommands).map((command) => asArray(command.name));
-		return {
-			message: `Unknown command '${token}'`,
-			didYouMean: {
-				input: token,
-				choices
-			}
-		};
-	}
-};
-/** The subcommands that help, completion and suggestions show. */
-function visibleSubcommands(subcommands) {
-	return subcommands?.filter((subcommand) => !subcommand.hidden) ?? [];
-}
-/** The action of a command that has none of its own: print the command's help. */
-const usage = ({ help }) => {
-	print(help());
-	return 0;
-};
 // src/help.ts
 /**
 * Show an option's names, each written with its arguments the way `forms`
@@ -422,32 +481,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
@@ -465,25 +501,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;
@@ -496,40 +528,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;
 	}
@@ -552,7 +604,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) {
@@ -562,7 +613,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) {
@@ -576,150 +627,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
@@ -728,34 +791,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) {
@@ -768,42 +836,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,
@@ -813,79 +880,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. */
@@ -895,36 +910,72 @@ function argAt(args, index) {
 	return last?.isVariadic ? last : void 0;
 }
 /**
+* Start reading a command line for `spec`, to say what each token is read as
+* in turn. Reads leniently, like {@link readNext}.
+*/
+function tokenReader(spec) {
+	return new Scanner(spec);
+}
+/**
 * Say what the parser reads `token` as when it comes after `before`. Reads
-* leniently, like {@link readNext}.
+* leniently, like {@link readNext}. To read every token of a line, use
+* {@link tokenReader}.
 */
 function readToken(spec, before, token) {
-	const s = new Scanner(spec, false);
-	s.read(before);
-	return s.readAndClassify([...before, token], before.length);
+	const s = new Scanner(spec);
+	for (const earlier of before) s.read(earlier);
+	return s.read(token);
 }
 // src/testing.ts
 const repr = JSON.stringify;
+/** One command in the spec, with what's in effect there. */
+var CommandVisit = class {
+	path;
+	own;
+	inherited;
+	built = null;
+	constructor(path, own, inherited) {
+		this.path = path;
+		this.own = own;
+		this.inherited = inherited;
+	}
+	/** The last command on the path. */
+	get command() {
+		return this.path[this.path.length - 1];
+	}
+	/** The options, subcommands and directives in effect here, built on first use. */
+	get scope() {
+		return this.built ??= CommandScope.at(this.path);
+	}
+};
 /**
-* Run a function once for each `args` property in the spec (recursive)
-*
-* This will convert single args to an array with one item.
+* Run a function once for each command in the spec, parents before their
+* subcommands, starting with `spec`. Each visit's path and scope start at
+* `spec`.
 */
-function forEachArgArray(spec, fn, path = []) {
-	path = path.concat(spec);
-	fn(makeArray(spec.args), path);
-	for (const option of makeArray(spec.options)) fn(makeArray(option.args), path);
-	for (const subcommand of makeArray(spec.subcommands)) forEachArgArray(subcommand, fn, path);
+function forEachCommand(spec, fn) {
+	const visit = (path, inherited) => {
+		const command = path[path.length - 1];
+		const own = makeArray(command.options).map((option, index) => ({
+			option,
+			definedIn: path,
+			index
+		}));
+		fn(new CommandVisit(path, own, inherited));
+		const next = [...inherited, ...own.filter(({ option }) => option.isPersistent)];
+		for (const subcommand of makeArray(command.subcommands)) visit([...path, subcommand], next);
+	};
+	visit([spec], []);
 }
 /**
-* Run a function once for each `subcommands` property in the spec (recursive)
-*
-* This will also run the function for the root spec itself.
+* Run a function once for each `args` property in the spec: each command's,
+* then its options'. This will convert single args to an array with one item.
 */
-function forEachSubcommand(spec, fn, path = []) {
-	path = path.concat(spec);
-	fn(spec, path);
-	for (const subcommand of makeArray(spec.subcommands)) forEachSubcommand(subcommand, fn, path);
+function forEachArgArray(spec, fn) {
+	forEachCommand(spec, ({ command, path }) => {
+		fn(makeArray(command.args), path);
+		for (const option of makeArray(command.options)) fn(makeArray(option.args), path);
+	});
 }
 function joinNames(names) {
 	return makeArray(names).sort((a, b) => a.length - b.length).join("|");
@@ -967,14 +1018,7 @@ function describeOption(definedIn, index, usedIn = definedIn) {
 * option the way the parser does at each command.
 */
 function forEachOption(spec, fn) {
-	const visit = (path, inherited) => {
-		const command = path[path.length - 1];
-		const scope = OptionScope.at(path);
-		const own = makeArray(command.options).map((option, index) => ({
-			option,
-			definedIn: path,
-			index
-		}));
+	forEachCommand(spec, ({ path, own, inherited, scope }) => {
 		for (const { option, definedIn, index } of [...own, ...inherited]) {
 			const where = describeOption(definedIn, index, path);
 			fn({
@@ -985,10 +1029,7 @@ function forEachOption(spec, fn) {
 				where
 			});
 		}
-		const next = [...inherited, ...own.filter(({ option }) => option.isPersistent)];
-		for (const subcommand of makeArray(command.subcommands)) visit([...path, subcommand], next);
-	};
-	visit([spec], []);
+	});
 }
 /** Asserts that required arguments do not come after an optional argument */
 function assertRequiredArgumentsDoNotFollowOptionalArguments(spec) {
@@ -1009,7 +1050,7 @@ function assertRequiredArgumentsDoNotFollowOptionalArguments(spec) {
 * too, and the option can't be required.
 */
 function assertDefaultsCanBeUsed(spec) {
-	forEachSubcommand(spec, (command, path) => {
+	forEachCommand(spec, ({ command, path }) => {
 		for (const [index, arg] of makeArray(command.args).entries()) assert(arg.default === void 0 || arg.isOptional, `In ${namedArrayToString(...path)}, argument ${arg.name || index} has a default, but it's required, so the default is never used`);
 	});
 	forEachOption(spec, ({ option, isDefinedHere, where }) => {
@@ -1038,9 +1079,9 @@ function assertRepeatableOptionsArePositiveIntegers(spec) {
 }
 /** Asserts that options have unique names in their scope */
 function assertOptionsHaveLocallyUniqueNames(spec) {
-	forEachSubcommand(spec, (spec, path) => {
+	forEachCommand(spec, ({ path, own }) => {
 		const optionNames = /* @__PURE__ */ new Set();
-		for (const [index, option] of makeArray(spec.options).entries()) for (const name of makeArray(option.name)) {
+		for (const { option, index } of own) for (const name of makeArray(option.name)) {
 			assert(!optionNames.has(name), `${describeOption(path, index)} has a non-unique name, '${name}'. Option names must be unique.`);
 			optionNames.add(name);
 		}
@@ -1048,10 +1089,8 @@ function assertOptionsHaveLocallyUniqueNames(spec) {
 }
 /** Asserts that options don't shadow a persistent option */
 function assertOptionsDoNotShadowPersistentOptions(spec) {
-	forEachOption(spec, ({ option, path, isDefinedHere, where }) => {
-		if (!isDefinedHere) return;
-		const inherited = OptionScope.at(path.slice(0, -1)).persistent;
-		for (const name of makeArray(option.name)) assert(!inherited.some((persistent) => makeArray(persistent.name).includes(name)), `${where} shadows the name of a persistent option, ${repr(name)}. Option names can't shadow persistent options.`);
+	forEachCommand(spec, ({ path, own, inherited }) => {
+		for (const { option, index } of own) for (const name of makeArray(option.name)) assert(!inherited.some((persistent) => makeArray(persistent.option.name).includes(name)), `${describeOption(path, index)} shadows the name of a persistent option, ${repr(name)}. Option names can't shadow persistent options.`);
 	});
 }
 /**
@@ -1096,9 +1135,9 @@ function assertOptionsHaveDifferentNamesFromParents(spec) {
 }
 /** Asserts that subcommands don't share a name with a sibling subcommand */
 function assertSubcommandsHaveLocallyUniqueNames(spec) {
-	forEachSubcommand(spec, (spec, path) => {
+	forEachCommand(spec, ({ command, path }) => {
 		const names = /* @__PURE__ */ new Set();
-		for (const [index, subcommand] of makeArray(spec.subcommands).entries()) for (const name of makeArray(subcommand.name)) {
+		for (const [index, subcommand] of makeArray(command.subcommands).entries()) for (const name of makeArray(subcommand.name)) {
 			assert(!names.has(name), `The subcommand ${namedArrayToString(...path, subcommand)} (index ${index}) has a non-unique name, ${repr(name)}. Subcommand names must be unique among the subcommands in the same array.`);
 			names.add(name);
 		}
@@ -1108,7 +1147,7 @@ function assertSubcommandsHaveLocallyUniqueNames(spec) {
 * Asserts that no option arg separator is an empty string
 */
 function assertOptionArgSeparatorsHaveCharacters(spec) {
-	forEachSubcommand(spec, (command, path) => {
+	forEachCommand(spec, ({ command, path }) => {
 		const separators = makeArray(command.parserDirectives?.optionArgSeparators);
 		for (const [sepIndex, separator] of separators.entries()) assert(separator !== "", `${describeCommand(path)} has an empty string for an option arg separator at index ${sepIndex}. If you wanted to disable option arg separators, use an empty array.`);
 	});
@@ -1130,7 +1169,7 @@ function assertNamesHaveNoExtraWhitespace(spec) {
 		if (!isDefinedHere) return;
 		for (const name of makeArray(option.name)) assert(name === name.trim(), `${where} has a name with extra whitespace`);
 	});
-	forEachSubcommand(spec, (command, path) => {
+	forEachCommand(spec, ({ command, path }) => {
 		for (const name of makeArray(command.name)) assert(name === name.trim(), `${describeCommand(path)} has a name with extra whitespace`);
 	});
 	forEachArgArray(spec, (args, path) => {
@@ -1145,7 +1184,7 @@ function assertEverythingHasDescription(spec) {
 	forEachOption(spec, ({ option, isDefinedHere, where }) => {
 		if (isDefinedHere) assert(option.description, `${where} has no description`);
 	});
-	forEachSubcommand(spec, (command, path) => {
+	forEachCommand(spec, ({ command, path }) => {
 		assert(command.description, `${describeCommand(path)} has no description`);
 	});
 }
@@ -1158,7 +1197,7 @@ function assertDescriptionLineLengthUnder69(spec) {
 		if (!isDefinedHere || !option.description) return;
 		assert(option.description.split("\n").every((line) => line.length <= 68), `${where} has a description line over 68 characters`);
 	});
-	forEachSubcommand(spec, (command, path) => {
+	forEachCommand(spec, ({ command, path }) => {
 		if (command.description) assert(command.description.split("\n").every((line) => line.length <= 68), `${describeCommand(path)} has a description line over 68 characters`);
 		for (const [index, arg] of makeArray(command.args).entries()) assert(!arg.description || arg.description.split("\n").every((line) => line.length <= 68), `In ${namedArrayToString(...path)}, argument ${arg.name || index} has a description line over 68 characters`);
 	});
@@ -1239,19 +1278,22 @@ function assertOptionFormsReadBack(spec, include) {
 		const names = makeArray(option.name).filter((name) => scope.resolve(name) === option);
 		for (const form of scope.forms(option, names)) {
 			if (!include(option, form.name)) continue;
+			const tokens = writeForm(option, form, value);
+			const reader = tokenReader(root);
+			for (const token of before) reader.read(token);
+			const first = reader.read(tokens[0]);
 			if (form.join !== "") {
-				const reading = readToken(root, before, form.name);
+				const reading = form.join === null ? first : readToken(root, before, form.name);
 				assert(readsAs(reading, option), `${where} has the name '${form.name}', but the parser reads it as ${describeReading(reading, path)}`);
 			}
-			const tokens = writeForm(option, form, value);
 			const written = `${where} is written '${optionToString(option, [form])}'`;
+			if (form.join) assert(scope.readsSeparator(form.join), `${written}, but '${form.join}' isn't one of the option arg separators there (${scope.directives.optionArgSeparators.map((separator) => `'${separator}'`).join(", ") || "none"}). Add it to \`parserDirectives.optionArgSeparators\`.`);
 			if (form.join !== null) {
-				const first = readToken(root, before, tokens[0]);
 				const joined = first.kind === "options" && first.attached?.option === option;
 				assert(readsAs(first, option) && joined, `${written}, but the parser reads '${tokens[0]}' as ${describeReading(first, path)}${joined ? "" : " without a value"}`);
 			}
 			for (let index = 1; index < tokens.length; index++) {
-				const reading = readToken(root, [...before, ...tokens.slice(0, index)], tokens[index]);
+				const reading = reader.read(tokens[index]);
 				assert(reading.kind === "value" && reading.option === option, `${written}, but in '${tokens.join(" ")}' the parser reads '${tokens[index]}' as ${describeReading(reading, path)}`);
 			}
 		}
@@ -1266,7 +1308,7 @@ function assertOptionFormsReadBack(spec, include) {
 */
 function assertNamesReadBack(spec) {
 	const root = spec;
-	forEachSubcommand(spec, (command, path) => {
+	forEachCommand(spec, ({ command, path }) => {
 		const before = tokensTo(path);
 		for (const subcommand of makeArray(command.subcommands)) for (const name of makeArray(subcommand.name)) {
 			const reading = readToken(root, before, name);
@@ -1278,13 +1320,16 @@ function assertNamesReadBack(spec) {
 }
 function assertCommonOptionsArePersistent(spec) {
 	const failures = [];
-	forEachSubcommand(spec, (subcommand, path) => {
-		if (!subcommand.subcommands) return;
-		for (const option of makeArray(subcommand.options)) {
-			const allChildSubcommands = [];
-			forEachSubcommand(subcommand, (cmd) => allChildSubcommands.push(cmd));
+	forEachCommand(spec, ({ command, path }) => {
+		if (!command.subcommands) return;
+		let common = makeArray(command.options);
+		forEachCommand(command, ({ command: below }) => {
+			const keys = makeArray(below.options).map(optionKey);
+			common = common.filter((option) => keys.includes(optionKey(option)));
+		});
+		for (const option of common) {
 			const key = optionKey(option);
-			if (allChildSubcommands.every((cmd) => makeArray(cmd.options).some((o) => optionKey(o) === key)) && !failures.some(([failed]) => failed === key)) failures.push([key, namedArrayToString(...path, option)]);
+			if (!failures.some(([failed]) => failed === key)) failures.push([key, namedArrayToString(...path, option)]);
 		}
 	});
 	assert(failures.length === 0, `The following options were also defined by all subcommands. Instead, define the option once, and use \`isPersistent: true\` to persist it across all subcommands.
@@ -1305,9 +1350,9 @@ function assertOptionNameReferencesExist(spec) {
 * Asserts that commands that will match subcommands by prefix do not take arguments
 */
 function assertPrefixMatchCommandsHaveNoArguments(spec) {
-	forEachSubcommand(spec, (subcommand, path) => {
-		if (!OptionScope.at(path).directives.subcommandsMatchUniquePrefix) return;
-		assert(!(subcommand.subcommands && subcommand.args), `The command ${namedArrayToString(...path)} has at least one argument and subcommand, but matches subcommands based on unique prefixes. To fix this, use \`parserDirectives: { subcommandsMatchUniquePrefix: false }\``);
+	forEachCommand(spec, ({ command, path, scope }) => {
+		if (!scope.directives.subcommandsMatchUniquePrefix) return;
+		assert(!(command.subcommands && command.args), `The command ${namedArrayToString(...path)} has at least one argument and subcommand, but matches subcommands based on unique prefixes. To fix this, use \`parserDirectives: { subcommandsMatchUniquePrefix: false }\``);
 	});
 }
 async function runStep(context, name, fn) {