@clo4/cli 2.0.0 → 3.0.0

package/dist/testing.js

@@ -8,10 +8,64 @@ function makeArray(thing) {
 	if (isArray(thing)) return thing.slice();
 	return [thing];
 }
+/**
+* Like {@link makeArray}, but without copying when the input is already an
+* array. Only safe when the caller treats the result as read-only — use it on
+* the hot path to avoid slicing read-only spec metadata.
+*/
+function asArray(thing) {
+	if (thing === void 0) return [];
+	if (isArray(thing)) return thing;
+	return [thing];
+}
 function assert(expr, msg = "") {
 	if (!expr) throw new Error(msg);
 }
-globalThis.process;
+const nodeProcess = globalThis.process;
+/**
+* Write text to stdout (1) or stderr (2) with a synchronous `write` on the file
+* descriptor.
+*
+* The first `console.log` in a Node process builds the stdout stream, which
+* costs 1-3 ms. That's more than parsing takes, so all of this library's output
+* goes through here instead. Without `node:fs` it falls back to `console`.
+*/
+function writeFd(fd, text) {
+	const fs = nodeProcess?.getBuiltinModule?.("node:fs");
+	if (!fs) {
+		(fd === 1 ? console.log : console.error)(text.endsWith("\n") ? text.slice(0, -1) : text);
+		return;
+	}
+	const bytes = new TextEncoder().encode(text);
+	let offset = 0;
+	try {
+		while (offset < bytes.length) offset += fs.writeSync(fd, bytes, offset, bytes.length - offset);
+	} catch (error) {
+		if (error.code === "EAGAIN") (fd === 1 ? nodeProcess?.stdout : nodeProcess?.stderr)?.write(bytes.subarray(offset));
+	}
+}
+/**
+* Where this library's output goes. Tests replace `write` to capture output.
+*
+* @internal
+*/
+const output = { write: writeFd };
+/** Print a message to stdout, trimming trailing whitespace. */
+function print(text) {
+	output.write(1, `${text.trimEnd()}\n`);
+}
+/**
+* Add the defaults of the arguments from index `from` on to `values`, stopping
+* at the first argument without one. The parser and help both use this, so
+* help only shows the defaults the parser uses.
+*/
+function addDefaults(values, args, from = 0) {
+	for (let i = from; i < args.length; i++) {
+		const value = args[i].default;
+		if (value === void 0) return;
+		values.push(value);
+	}
+}
 /**
 * Returns the minimum number of arguments that satisfies the args.
 *
@@ -35,6 +89,820 @@ function getMaxArgs(args) {
 	for (let i = 0; i < args.length; i++) if (args[args.length - 1 - i].isVariadic) return Infinity;
 	return args.length;
 }
+// src/directives.ts
+/** The directives in effect when no command sets any. */
+function defaultDirectives() {
+	return {
+		optionArgSeparators: ["="],
+		flagsArePosixNoncompliant: false,
+		optionsMustPrecedeArguments: false,
+		subcommandsMatchUniquePrefix: false
+	};
+}
+/**
+* Update `directives` for entering `command`. A subcommand inherits each
+* directive until it sets its own.
+*/
+function applyDirectives(directives, command) {
+	const configured = command.parserDirectives;
+	if (!configured) return;
+	if (configured.optionArgSeparators) directives.optionArgSeparators = asArray(configured.optionArgSeparators);
+	if (typeof configured.subcommandsMatchUniquePrefix === "boolean") directives.subcommandsMatchUniquePrefix = configured.subcommandsMatchUniquePrefix;
+	if (typeof configured.optionsMustPrecedeArguments === "boolean") directives.optionsMustPrecedeArguments = configured.optionsMustPrecedeArguments;
+	if (typeof configured.flagsArePosixNoncompliant === "boolean") directives.flagsArePosixNoncompliant = configured.flagsArePosixNoncompliant;
+}
+// src/scope.ts
+/**
+* The options and directives in effect at one command on a path.
+*
+* 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.
+*/
+var OptionScope = class OptionScope {
+	/** Non-persistent options of the current command, in definition order. */
+	local = [];
+	/** Persistent options from every command on the path, in definition order. */
+	persistent = [];
+	/**
+	* Persistent subcommands of the commands above the current one, nearest
+	* command first, so a nearer one wins a name.
+	*/
+	inheritedSubcommands = [];
+	/** The directives in effect. A subcommand inherits each until it sets its own. */
+	directives = defaultDirectives();
+	command = null;
+	/** The scope at the last command on `path`. */
+	static at(path) {
+		const scope = new OptionScope();
+		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;
+		if (parentSubcommands) {
+			const persistent = parentSubcommands.filter((subcommand) => subcommand.isPersistent);
+			if (persistent.length > 0) this.inheritedSubcommands.unshift(...persistent);
+		}
+		this.command = command;
+		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 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];
+		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.
+	*/
+	live() {
+		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);
+				if (names.length > 0) picked.push({
+					option,
+					names
+				});
+			}
+			return picked;
+		};
+		return {
+			local: pick(this.local),
+			persistent: pick(this.persistent)
+		};
+	}
+	/** The options a user can see here: the {@link live} ones that aren't hidden. */
+	visible() {
+		const { local, persistent } = this.live();
+		const shown = (visible) => !visible.option.hidden;
+		return {
+			local: local.filter(shown),
+			persistent: persistent.filter(shown)
+		};
+	}
+	/** 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);
+	}
+	/** The options that must be used, local first. */
+	required() {
+		return [...this.local, ...this.persistent].filter((option) => option.isRequired);
+	}
+	/**
+	* How each of `names` is written with `option`'s value here. Help shows
+	* these, completion offers them, and the spec checker reads each one back
+	* through the parser.
+	*/
+	forms(option, names = asArray(option.name)) {
+		const join = (name) => {
+			if (getMaxArgs(option.args) === 0) return null;
+			if (option.requiresSeparator) return this.requiredSeparator(option);
+			return !this.directives.flagsArePosixNoncompliant && (name === "-" || name === "+") ? "" : null;
+		};
+		return names.map((name) => ({
+			name,
+			join: join(name)
+		}));
+	}
+	/**
+	* The separator that must come between `option` and its value, or null if
+	* it can take a value as a separate token.
+	*/
+	requiredSeparator(option) {
+		const required = option.requiresSeparator;
+		if (typeof required === "string") return required;
+		return required ? this.directives.optionArgSeparators[0] ?? "=" : null;
+	}
+};
+const optionKeys = /* @__PURE__ */ new WeakMap();
+/**
+* A key for the set of `option`'s names. Options with the same names, in any
+* order, get the same key and are one option: the parser continues a
+* repeatable option's uses across them, counts one as used when the other was,
+* and stores their values under the same names, which is how they're read.
+* Options that share only some names are different options, and each shared
+* name refers to whichever one `resolve` picks.
+*/
+function optionKey(option) {
+	let key = optionKeys.get(option);
+	if (key === void 0) {
+		key = typeof option.name === "string" ? option.name : [...option.name].sort().join("\0");
+		optionKeys.set(option, key);
+	}
+	return key;
+}
+function hasName$1(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`
+* says. Names written the same way share one copy of the arguments.
+*/
+function optionToString(option, forms) {
+	const optionArgs = makeArray(option.args);
+	const sorted = [...forms].sort((a, b) => a.name.length - b.name.length);
+	return [...new Set(sorted.map((form) => form.join))].map((join) => {
+		return sorted.filter((form) => form.join === join).map((form) => form.name).join(", ") + argumentsAfterName(optionArgs, join);
+	}).join(", ");
+}
+/** The text after an option's name that shows its arguments, joined to the name by `join`. */
+function argumentsAfterName(args, join) {
+	if (args.length === 0) return "";
+	if (join === null) return ` ${summarizeArguments(args)}`;
+	const [first, ...rest] = args;
+	const name = first.name || "argument";
+	const joined = (first.isOptional ? `[${join}${name}]` : `${join}<${name}>`) + (first.isVariadic ? "..." : "");
+	return rest.length > 0 ? `${joined} ${summarizeArguments(rest)}` : joined;
+}
+function summarizeArguments(args) {
+	return args.map((arg) => argToString(arg)).join(" ");
+}
+function argToString(arg) {
+	const name = arg.name || "argument";
+	let lhs = "<";
+	let rhs = ">";
+	let suffix = "";
+	if (arg.isOptional) {
+		lhs = "[";
+		rhs = "]";
+	}
+	if (arg.isVariadic) suffix = "...";
+	return `${lhs}${name}${rhs}${suffix}`;
+}
+// src/errors.ts
+const repr$1 = JSON.stringify;
+/**
+* A command line the parser can't accept. `run` prints the message with the
+* help for the command at `context.path`, and suggests the closest of
+* `didYouMean.choices` if there is one.
+*/
+var ParseError = class extends Error {
+	context;
+	didYouMean;
+	constructor(context, message, didYouMean) {
+		super(message);
+		this.context = context;
+		this.didYouMean = didYouMean;
+		this.name = this.constructor.name;
+	}
+};
+var UnknownOption = class extends ParseError {
+	option;
+	constructor(option, validOptions, context) {
+		const msg = `${repr$1(option)} looks like a flag, but is unknown in this context`;
+		super(context, msg, {
+			input: option,
+			choices: validOptions
+		});
+		this.option = option;
+	}
+};
+var InvalidOptionArg = class extends ParseError {
+	option;
+	constructor(option, context) {
+		super(context, `Option ${option} doesn't take arguments`);
+		this.option = option;
+	}
+};
+var TooManyArguments = class extends ParseError {
+	constructor(value, context) {
+		super(context, `Too many arguments, ${repr$1(value)} was unexpected`);
+	}
+};
+var TooFewOptionArguments = class extends ParseError {
+	constructor(option, min, max, context) {
+		const msg = min === max ? `Option ${option} needs ${min} argument${min === 1 ? "" : "s"}` : !Number.isFinite(max) ? `Option ${option} needs at least ${min} argument${min === 1 ? "" : "s"}` : `Option ${option} needs between ${min} and ${max} arguments`;
+		super(context, msg);
+	}
+};
+var TooFewArguments = class extends ParseError {
+	constructor(min, max, context) {
+		const msg = min === max ? `Expected ${min} argument${min === 1 ? "" : "s"}` : !Number.isFinite(max) ? `Expected at least ${min} argument${min === 1 ? "" : "s"}` : `Expected between ${min} and ${max} arguments`;
+		super(context, msg);
+	}
+};
+var MissingRequiredOption = class extends ParseError {
+	constructor(name, context) {
+		const msg = `Option ${name} is required, but wasn't found`;
+		super(context, msg);
+	}
+};
+// 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;
+}
+/**
+* Throw if the options used break a `dependsOn` or `exclusiveOn` rule, or if
+* any of `required` is missing.
+*/
+function checkOptionRules(options, seenOptions, required, context) {
+	for (const option of seenOptions) {
+		if (!option.dependsOn) continue;
+		for (const name of option.dependsOn) if (!options.has(name)) throw new ParseError(context, `${asArray(option.name).join("/")} requires ${name}, add it to fix this error`);
+	}
+	for (const option of seenOptions) {
+		if (!option.exclusiveOn) continue;
+		for (const name of option.exclusiveOn) if (options.has(name)) throw new ParseError(context, `${asArray(option.name).join("/")} can't be used together with ${name}`);
+	}
+	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.
+*/
+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;
+	directives = this.scope.directives;
+	hasFoundArg = false;
+	openOption = null;
+	openOptionName = "";
+	valueCount = 0;
+	valueMin = 0;
+	separateValueMax = 0;
+	values = null;
+	valuesStart = 0;
+	valuesMin = 0;
+	valuesMax = 0;
+	valueArgs = [];
+	requiredSeparator = false;
+	tooManyArgs = null;
+	repeatedUses = /* @__PURE__ */ new Map();
+	attached = null;
+	constructor(spec, strict) {
+		this.strict = strict;
+		this.path = [spec];
+		this.enterCommand(spec);
+	}
+	ctx() {
+		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);
+	}
+	unknownOption(option) {
+		return new UnknownOption(option, this.scope.suggestionNames(), this.ctx());
+	}
+	endOption() {
+		const values = this.values;
+		if (this.strict && 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);
+		}
+		this.values = null;
+	}
+	/** End the open option, so no later token can be its value. */
+	closeOption() {
+		this.endOption();
+		this.openOption = null;
+		this.valueCount = this.valueMin = this.separateValueMax = 0;
+	}
+	useOption(option, name) {
+		this.endOption();
+		this.openOption = option;
+		this.openOptionName = name;
+		this.valueCount = 0;
+		this.valueMin = getMinArgs(option.args);
+		this.separateValueMax = option.requiresSeparator ? 0 : getMaxArgs(option.args);
+		this.seenOptions.push(option);
+		if (option.action) this.optionAction = option.action;
+		const names = asArray(option.name);
+		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) {
+				uses = {
+					values: [],
+					count: 0
+				};
+				this.repeatedUses.set(key, uses);
+			}
+			if (this.strict && uses.count >= maxRepeat) throw new ParseError(this.ctx(), "Too many repetitions");
+			uses.count += 1;
+			for (const other of names) options.set(other, uses.values);
+			if (!option.args) {
+				uses.values.push("");
+				return;
+			}
+			optionValues = uses.values;
+		} else {
+			optionValues = [];
+			for (const other of names) options.set(other, optionValues);
+		}
+		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.
+	*/
+	addValue(value, separator) {
+		this.valueCount += 1;
+		if (!this.values) {
+			if (this.strict) throw new InvalidOptionArg(this.openOptionName, this.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;
+		}
+		this.values.push(value);
+		return accepted;
+	}
+	/**
+	* 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.
+	*/
+	addAttachedValue(index, start, value, separator) {
+		if (this.addValue(value, separator)) this.attached = {
+			option: this.openOption,
+			index,
+			start
+		};
+		this.valueMin = this.separateValueMax = 0;
+	}
+	/**
+	* 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;
+	}
+	addArg(value) {
+		this.endOption();
+		if (this.strict && this.argsAreFull) this.tooManyArgs ??= new TooManyArguments(value, this.ctx());
+		this.args.push(value);
+	}
+	/** Read `--` and every token after it as arguments. */
+	argSeparator(input, index) {
+		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?");
+		this.argSeparatorIndex = this.args.length;
+		for (index += 1; index < input.length; index++) this.addArg(input[index]);
+	}
+	/**
+	* 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.
+	*/
+	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);
+	}
+	/**
+	* 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);
+	}
+	enterSubcommand(command) {
+		this.closeOption();
+		this.path.push(command);
+		this.enterCommand(command);
+	}
+	/** Read a token like `-abc`, `+x` or `-ovalue`. */
+	shortOptions(token, index) {
+		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;
+		}
+		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);
+				continue;
+			}
+			this.useOption(option, optionName);
+			if (char === token.length - 1) return;
+			const sep = leadingSeparator(token.slice(char + 1), this.directives.optionArgSeparators);
+			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;
+			}
+		}
+	}
+	/**
+	* 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.
+	*/
+	longOption(token, index) {
+		const found = firstSeparator(token, this.directives.optionArgSeparators);
+		const optionName = found ? token.slice(0, found.index) : token;
+		const option = this.findOption(optionName);
+		if (option) {
+			this.useOption(option, optionName);
+			if (found) {
+				const valueStart = found.index + found.sep.length;
+				this.addAttachedValue(index, valueStart, token.slice(valueStart), found.sep);
+			}
+			return true;
+		}
+		if (this.directives.flagsArePosixNoncompliant) return false;
+		if (this.hasRoomForValue) {
+			this.addValue(token, "");
+			return true;
+		}
+		if (this.strict) throw this.unknownOption(optionName);
+		return true;
+	}
+	/**
+	* Read a token that isn't `--`, a subcommand or an option. It's a value of
+	* the open option if that has room, and otherwise an argument, which stops
+	* later tokens from being subcommands. `unmatched` is why the token isn't a
+	* 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) {
+				const { message, didYouMean } = unmatched.reason();
+				this.tooManyArgs ??= new ParseError(this.ctx(), message, didYouMean);
+			}
+		}
+		this.hasFoundArg = true;
+		this.addArg(token);
+	}
+	/**
+	* Throw if the finished command line is missing anything. Returns the action
+	* to run.
+	*/
+	finish() {
+		const command = this.path[this.path.length - 1];
+		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());
+		this.endOption();
+		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;
+	}
+	/** See {@link ParseResult.defaults}. */
+	defaults(name) {
+		if (this.options.has(name)) return;
+		const args = asArray(this.scope.resolve(name)?.args);
+		if (args.length === 0 || args[0].isOptional) return;
+		const values = [];
+		addDefaults(values, args);
+		return values.length > 0 ? values : void 0;
+	}
+	/** Whether using `option` next would go over its repeat limit or break an `exclusiveOn` rule. */
+	conflicts(option) {
+		const names = asArray(option.name);
+		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;
+		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 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),
+				used: used.has(optionKey(option))
+			});
+		}
+		return usable;
+	}
+	/** What the next token can be. See {@link readNext}. */
+	next() {
+		const open = this.openOption && this.hasRoomForValue ? this.openOption : null;
+		const command = this.path[this.path.length - 1];
+		const afterSeparator = this.argSeparatorIndex !== -1;
+		const optionsAllowed = !afterSeparator && this.optionsAllowed;
+		return {
+			path: this.path,
+			directives: this.directives,
+			optionsAllowed,
+			subcommands: !afterSeparator && this.canMatchSubcommand ? withInherited(this.subcommands ?? [], this.scope.inheritedSubcommands) : [],
+			options: optionsAllowed ? this.usableOptions() : [],
+			value: open && {
+				option: open,
+				arg: argAt(asArray(open.args), this.valueCount),
+				required: this.valueCount < this.valueMin
+			},
+			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];
+		const optionsAllowed = this.optionsAllowed;
+		if (token === "--" && optionsAllowed) {
+			this.argSeparator(input, index);
+			return true;
+		}
+		const subcommand = this.subcommandFor(token);
+		if (subcommand?.command) {
+			this.enterSubcommand(subcommand.command);
+			return false;
+		}
+		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 > 2 && isDoubleDash) {
+				if (this.longOption(token, index)) return false;
+			}
+		}
+		this.valueOrArg(token, subcommand);
+		return false;
+	}
+};
+/** The argument at `index`, reusing a final variadic argument. */
+function argAt(args, index) {
+	if (index < args.length) return args[index];
+	const last = args[args.length - 1];
+	return last?.isVariadic ? last : void 0;
+}
+/**
+* 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);
+}
 // src/testing.ts
 const repr = JSON.stringify;
 /**
@@ -48,12 +916,6 @@ function forEachArgArray(spec, fn, path = []) {
 	for (const option of makeArray(spec.options)) fn(makeArray(option.args), path);
 	for (const subcommand of makeArray(spec.subcommands)) forEachArgArray(subcommand, fn, path);
 }
-/** Run a function once for each `options` property in the spec (recursive) */
-function forEachOptionArray(spec, fn, path = []) {
-	path = path.concat(spec);
-	fn(makeArray(spec.options), path);
-	for (const subcommand of makeArray(spec.subcommands)) forEachOptionArray(subcommand, fn, path);
-}
 /**
 * Run a function once for each `subcommands` property in the spec (recursive)
 *
@@ -67,10 +929,6 @@ function forEachSubcommand(spec, fn, path = []) {
 function joinNames(names) {
 	return makeArray(names).sort((a, b) => a.length - b.length).join("|");
 }
-function isSameName(a, b) {
-	if (isArray(a) && isArray(b)) return a.every((item) => b.includes(item)) && b.every((item) => a.includes(item));
-	return a === b;
-}
 /** Compares spec values by shape. Any two functions count as the same shape. */
 function isSameStructure(a, b) {
 	if (a === b) return true;
@@ -84,6 +942,54 @@ function isSameStructure(a, b) {
 function namedArrayToString(...parts) {
 	return `\`${parts.map((named) => joinNames(named.name)).join(" ")}\``;
 }
+/** Name the last command on `path` in a message, with its index among its siblings. */
+function describeCommand(path) {
+	const command = path[path.length - 1];
+	const parent = path[path.length - 2];
+	if (!parent) return `Command ${namedArrayToString(command)}`;
+	const index = makeArray(parent.subcommands).indexOf(command);
+	return `Subcommand ${namedArrayToString(...path)} (index ${index})`;
+}
+/**
+* Name the option at `index` on the last command on `definedIn` in a message,
+* and the command it's used in when that isn't the one that defines it.
+*/
+function describeOption(definedIn, index, usedIn = definedIn) {
+	const option = makeArray(definedIn[definedIn.length - 1].options)[index];
+	const name = `${namedArrayToString(...definedIn, option)} (index ${index})`;
+	return usedIn === definedIn ? `Option ${name}` : `In ${namedArrayToString(...usedIn)}, option ${name}`;
+}
+/**
+* Run a function once for each option at each command it can be used in: the
+* command's own options, in definition order, then the persistent ones it
+* inherits. A check that is about how the option is written skips the uses
+* that aren't `isDefinedHere`. A check that depends on the scope sees the
+* 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
+		}));
+		for (const { option, definedIn, index } of [...own, ...inherited]) {
+			const where = describeOption(definedIn, index, path);
+			fn({
+				option,
+				path,
+				scope,
+				isDefinedHere: definedIn === path,
+				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) {
 	forEachArgArray(spec, (args, path) => {
@@ -96,14 +1002,38 @@ function assertRequiredArgumentsDoNotFollowOptionalArguments(spec) {
 		}
 	});
 }
+/**
+* Asserts that the parser can use every default. A positional argument with a
+* default must be optional. A required option argument's default is only used
+* when the option is left out, so every argument before it needs a default
+* too, and the option can't be required.
+*/
+function assertDefaultsCanBeUsed(spec) {
+	forEachSubcommand(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 }) => {
+		if (!isDefinedHere) return;
+		let firstWithout = null;
+		for (const [index, arg] of makeArray(option.args).entries()) {
+			if (arg.default === void 0) {
+				firstWithout ??= index;
+				continue;
+			}
+			if (arg.isOptional) continue;
+			const name = `${where}, argument ${arg.name || index} has a default, but`;
+			assert(!option.isRequired, `${name} the option is required, so the default is never used`);
+			assert(firstWithout === null, `${name} the argument at index ${firstWithout} has none, so the default is never used`);
+		}
+	});
+}
 /** Asserts that `isRepeatable` is only assigned a positive integer */
 function assertRepeatableOptionsArePositiveIntegers(spec) {
-	forEachOptionArray(spec, (options, path) => {
-		for (const [index, option] of options.entries()) if (typeof option.isRepeatable === "number") {
-			assert(Number.isSafeInteger(option.isRepeatable), `The option ${namedArrayToString(...path, option)} (index ${index}) has its \`isRepeatable\` value set to a number that is not an integer`);
-			assert(!(option.isRepeatable < 1), `The option ${namedArrayToString(...path, option)} (index ${index}) has its \`isRepeatable\` value set to a number below 1, which means it can't be used at all`);
-			assert(option.isRepeatable !== 1, `The option ${namedArrayToString(...path, option)} (index ${index}) has its \`isRepeatable\` value set to 1, which is no different that omitting the property entirely`);
-		}
+	forEachOption(spec, ({ option, isDefinedHere, where }) => {
+		if (!isDefinedHere || typeof option.isRepeatable !== "number") return;
+		assert(Number.isSafeInteger(option.isRepeatable), `${where} has its \`isRepeatable\` value set to a number that is not an integer`);
+		assert(!(option.isRepeatable < 1), `${where} has its \`isRepeatable\` value set to a number below 1, which means it can't be used at all`);
+		assert(option.isRepeatable !== 1, `${where} has its \`isRepeatable\` value set to 1, which is no different that omitting the property entirely`);
 	});
 }
 /** Asserts that options have unique names in their scope */
@@ -111,40 +1041,57 @@ function assertOptionsHaveLocallyUniqueNames(spec) {
 	forEachSubcommand(spec, (spec, path) => {
 		const optionNames = /* @__PURE__ */ new Set();
 		for (const [index, option] of makeArray(spec.options).entries()) for (const name of makeArray(option.name)) {
-			assert(!optionNames.has(name), `Option ${namedArrayToString(...path, option)} (index ${index}) has a non-unique name, '${name}'. Option names must be unique.`);
+			assert(!optionNames.has(name), `${describeOption(path, index)} has a non-unique name, '${name}'. Option names must be unique.`);
 			optionNames.add(name);
 		}
 	});
 }
 /** Asserts that options don't shadow a persistent option */
 function assertOptionsDoNotShadowPersistentOptions(spec) {
-	forEachOptionArray(spec, (options, path) => {
-		const persistentOptionNames = new Set(path.slice(0, -1).flatMap((subcommand) => subcommand.options ? subcommand.options.filter((option) => option.isPersistent).flatMap((option) => option.name) : []));
-		for (const [index, option] of makeArray(options).entries()) for (const name of makeArray(option.name)) assert(!persistentOptionNames.has(name), `The option ${namedArrayToString(...path, option)} (index ${index}) shadows the name of a persistent option, ${repr(name)}. Option names can't shadow persistent options.`);
+	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.`);
 	});
 }
 /**
-* Asserts that a subcommand's option isn't a different option with exactly the
-* same names as one on a parent.
+* Asserts that when a subcommand's option and a different option on a parent
+* share a name, each of them has a name of its own.
 *
-* Parsed values are looked up by name, so that parent's value would be
-* unreadable. A shared name is fine when each option has a name of its own, and
-* when the options are identical, such as an option kept in a constant.
+* Parsed values are looked up by name, and an option sets every one of its
+* names when it's used. If every name of the parent's option is also the
+* subcommand's, using the subcommand's option replaces the parent's value, so
+* it can't be read. If every name of the subcommand's option is also the
+* parent's, its names hold the parent's value when it isn't used, so it can't
+* tell whether it was. Options with the same names are fine when they're
+* identical, such as an option kept in a constant, because the parser treats
+* them as one option.
 *
 * This skips persistent parent options, because
 * {@link assertOptionsDoNotShadowPersistentOptions} covers those and
 * `allowShadowingPersistentOptions` opts out of it.
 */
 function assertOptionsHaveDifferentNamesFromParents(spec) {
-	forEachOptionArray(spec, (options, path) => {
-		const parents = path.slice(0, -1);
-		for (const [index, option] of options.entries()) for (const parent of parents) for (const parentOption of makeArray(parent.options)) assert(!(!parentOption.isPersistent && isSameName(parentOption.name, option.name) && !isSameStructure({
-			...parentOption,
-			name: 0
-		}, {
-			...option,
-			name: 0
-		})), `The option ${namedArrayToString(...path, option)} (index ${index}) has the same names as a different option, ${namedArrayToString(parent, parentOption)}, so the parent's value can't be read. Add a name that only one of them uses.`);
+	forEachOption(spec, ({ option, path, isDefinedHere, where }) => {
+		if (!isDefinedHere) return;
+		const names = makeArray(option.name);
+		for (const parent of path.slice(0, -1)) for (const parentOption of makeArray(parent.options)) {
+			if (parentOption.isPersistent) continue;
+			const parentNames = makeArray(parentOption.name);
+			const other = namedArrayToString(parent, parentOption);
+			if (optionKey(parentOption) === optionKey(option)) {
+				assert(isSameStructure({
+					...parentOption,
+					name: 0
+				}, {
+					...option,
+					name: 0
+				}), `${where} has the same names as a different option, ${other}, so the parent's value can't be read. Add a name that only one of them uses.`);
+				continue;
+			}
+			assert(!parentNames.every((name) => names.includes(name)), `${where} has every name of a different option, ${other}, so the parent's value can't be read. Add a name that only the parent's option uses.`);
+			assert(!names.every((name) => parentNames.includes(name)), `${where} only has names of a different option, ${other}, so it can't tell whether it was used. Add a name that only the subcommand's option uses.`);
+		}
 	});
 }
 /** Asserts that subcommands don't share a name with a sibling subcommand */
@@ -158,68 +1105,33 @@ function assertSubcommandsHaveLocallyUniqueNames(spec) {
 	});
 }
 /**
-* Asserts that option names starting with a single dash aren't longer
-* than two characters, unless parserDirectives.flagsArePosixNoncompliant is
-* set on an ancestor command.
-*/
-function assertLongOptionNamesDoNotStartWithSingleDash(spec) {
-	forEachOptionArray(spec, (options, path) => {
-		if (path.map((command) => command.parserDirectives?.flagsArePosixNoncompliant).filter((value) => value !== void 0).at(-1) || false) return;
-		for (const [index, option] of makeArray(options).entries()) for (const name of makeArray(option.name)) assert(!((name.startsWith("-") || name.startsWith("+")) && !name.startsWith("--") && name.length > 2), `Option ${namedArrayToString(...path, option)} (index ${index}) has a name that the parser is unable to parse, as it starts with a single '${name[0]}'. Tokens starting with that character are interpreted as short options, so passing '${name}' will be interpreted as '${Array.from(name.slice(1), (letter) => name[0] + letter).join(" ")}'. \`parserDirectives.flagsArePosixNoncompliant\` must be \`true\` on an ancestor command.`);
-	});
-}
-/**
-* Asserts that all option names start with dashes
-*/
-function assertOptionNamesStartWithDashes(spec) {
-	forEachOptionArray(spec, (options, path) => {
-		if (path.map((command) => command.parserDirectives?.flagsArePosixNoncompliant).filter((value) => value !== void 0).at(-1) || false) return;
-		for (const [index, option] of makeArray(options).entries()) for (const name of makeArray(option.name)) assert(name.startsWith("-") || name.startsWith("+"), `Option ${namedArrayToString(...path, option)} (index ${index}) doesn't start with a dash or plus, the parser will be unable to find matching options without \`parserDirectives.flagsAreNonPosixCompliant\` being set to 'true' on an ancestor command`);
-	});
-}
-/**
-* Asserts that nothing is named exactly '--'
-*/
-function assertNothingIsNamedDashDash(spec) {
-	forEachOptionArray(spec, (options, path) => {
-		for (const [index, option] of makeArray(options).entries()) for (const name of makeArray(option.name)) assert(name !== "--", `Option ${namedArrayToString(...path, option)} (index ${index}) is named '--', which is a special instruction to the parser to treat all following tokens as arguments. This will never be matched`);
-	});
-	forEachSubcommand(spec, (subcommands, path) => {
-		for (const [index, subcommand] of makeArray(subcommands).entries()) for (const name of makeArray(subcommand.name)) assert(name !== "--", `Subcommand ${namedArrayToString(...path, subcommand)} (index ${index}) is named '--', which is a special instruction to the parser to treat all following tokens as arguments. This will never be matched`);
-	});
-}
-/**
 * Asserts that no option arg separator is an empty string
 */
 function assertOptionArgSeparatorsHaveCharacters(spec) {
-	forEachSubcommand(spec, (subcommands, path) => {
-		for (const [index, subcommand] of makeArray(subcommands).entries()) {
-			const separators = makeArray(subcommand.parserDirectives?.optionArgSeparators);
-			for (const [sepIndex, separator] of separators.entries()) assert(separator !== "", `Subcommand ${namedArrayToString(...path, subcommand)} (index ${index}) has an empty string for an option arg separator at index ${sepIndex}. If you wanted to disable option arg separators, use an empty array.`);
-		}
+	forEachSubcommand(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.`);
 	});
 }
 /**
-* Asserts that options named "+" or "-" takes one arg
+* Asserts that the parser reads options named "+" or "-" the way they're
+* written, which needs them to take one argument.
+*
+* @deprecated {@link assertNamesReadBack} checks this for every option.
 */
 function assertPlusMinusOptionsTakeOneArg(spec) {
-	forEachOptionArray(spec, (options, path) => {
-		if (path.map((command) => command.parserDirectives?.flagsArePosixNoncompliant).filter((value) => value !== void 0).at(-1) || false) return;
-		for (const [index, option] of makeArray(options).entries()) for (const name of makeArray(option.name)) {
-			if (name !== "-" && name !== "+") continue;
-			assert(option.args && !Array.isArray(option.args), `Option ${namedArrayToString(...path, option)} (index ${index}) must take exactly one argument`);
-		}
-	});
+	assertOptionFormsReadBack(spec, (_, name) => name === "-" || name === "+");
 }
 /**
 * Asserts that names do not have leading or trailing whitespace
 */
 function assertNamesHaveNoExtraWhitespace(spec) {
-	forEachOptionArray(spec, (options, path) => {
-		for (const [index, option] of makeArray(options).entries()) for (const name of makeArray(option.name)) assert(name === name.trim(), `Option ${namedArrayToString(...path, option)} (index ${index}) has a name with extra whitespace`);
+	forEachOption(spec, ({ option, isDefinedHere, where }) => {
+		if (!isDefinedHere) return;
+		for (const name of makeArray(option.name)) assert(name === name.trim(), `${where} has a name with extra whitespace`);
 	});
-	forEachSubcommand(spec, (subcommands, path) => {
-		for (const [index, subcommand] of makeArray(subcommands).entries()) for (const name of makeArray(subcommand.name)) assert(name === name.trim(), `Subcommand ${namedArrayToString(...path, subcommand)} (index ${index}) has a name with extra whitespace`);
+	forEachSubcommand(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) => {
 		for (const [index, arg] of makeArray(args).entries()) for (const name of makeArray(arg.name)) assert(name === name.trim(), `Arg in ${namedArrayToString(...path)} (at index ${index}) has a name with extra whitespace`);
@@ -230,11 +1142,11 @@ function assertNamesHaveNoExtraWhitespace(spec) {
 */
 function assertEverythingHasDescription(spec) {
 	assert(spec.description, `Spec has no description`);
-	forEachOptionArray(spec, (options, path) => {
-		for (const [index, option] of makeArray(options).entries()) assert(option.description, `Option ${namedArrayToString(...path, option)} (index ${index}) has no description`);
+	forEachOption(spec, ({ option, isDefinedHere, where }) => {
+		if (isDefinedHere) assert(option.description, `${where} has no description`);
 	});
-	forEachSubcommand(spec, (subcommands, path) => {
-		for (const [index, subcommand] of makeArray(subcommands).entries()) assert(subcommand.description, `Subcommand ${namedArrayToString(...path, subcommand)} (index ${index}) has no description`);
+	forEachSubcommand(spec, (command, path) => {
+		assert(command.description, `${describeCommand(path)} has no description`);
 	});
 }
 /**
@@ -242,22 +1154,128 @@ function assertEverythingHasDescription(spec) {
 */
 function assertDescriptionLineLengthUnder69(spec) {
 	if (spec.description) assert(spec.description.split("\n").every((line) => line.length <= 68), `Spec has a description line over 68 characters`);
-	forEachOptionArray(spec, (options, path) => {
-		for (const [index, option] of makeArray(options).entries()) if (option.description) assert(option.description.split("\n").every((line) => line.length <= 68), `Option ${namedArrayToString(...path, option)} (index ${index}) has a description line over 68 characters`);
+	forEachOption(spec, ({ option, isDefinedHere, where }) => {
+		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, (subcommands, path) => {
-		for (const [index, subcommand] of makeArray(subcommands).entries()) if (subcommand.description) assert(subcommand.description.split("\n").every((line) => line.length <= 68), `Subcommand ${namedArrayToString(...path, subcommand)} (index ${index}) has a description line over 68 characters`);
+	forEachSubcommand(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`);
 	});
 }
+/**
+* Asserts that the parser reads options with `requiresSeparator` the way
+* they're written, which needs them to take at most one argument.
+*
+* @deprecated {@link assertNamesReadBack} checks this for every option.
+*/
 function assertRequiresSeparatorTakesOneArg(spec) {
-	forEachOptionArray(spec, (options, path) => {
-		for (const [index, option] of makeArray(options).entries()) if (option.requiresSeparator) {
-			const args = makeArray(option.args);
-			assert(getMinArgs(args) <= 1, `Option ${namedArrayToString(...path, option)} (index ${index}) takes a minimum of ${getMinArgs(args)} arg(s), but because of requiresSeparator, it must instead be 0 or 1`);
-			assert(getMaxArgs(args) === 1, `Option ${namedArrayToString(...path, option)} (index ${index}) takes a maximum of ${getMaxArgs(args)} arg(s), but because of requiresSeparator, it's only able to take 1`);
+	assertOptionFormsReadBack(spec, (option) => Boolean(option.requiresSeparator));
+}
+/**
+* What the parser read a token as, for a message. `path` is the command the
+* token came after.
+*/
+function describeReading(reading, path) {
+	switch (reading.kind) {
+		case "separator": return "the end of options, '--'";
+		case "subcommand": return `the subcommand ${namedArrayToString(...path, reading.command)}`;
+		case "options": return reading.options.length === 1 ? `the option ${namedArrayToString(reading.options[0])}` : `the options ${reading.options.map((option) => namedArrayToString(option)).join(", ")}`;
+		case "value": return `a value of the option ${namedArrayToString(reading.option)}`;
+		case "argument": return "an argument";
+		case "unknown": return "an option that doesn't exist";
+	}
+}
+/** Whether the parser read a token as `option` alone. */
+function readsAs(reading, option) {
+	return reading.kind === "options" && reading.options.length === 1 && reading.options[0] === option;
+}
+/**
+* The tokens that reach the last command on `path`, using each command's first
+* name. {@link assertNamesReadBack} checks subcommand names from the root down
+* before options, so each of these is a name the parser reads.
+*/
+function tokensTo(path) {
+	return path.slice(1).map((command) => makeArray(command.name)[0]);
+}
+/**
+* A value for writing options with at the last command on `path`. No name
+* there starts with it, or with it after '-' or '+', so the parser can only
+* read it as a value.
+*/
+function placeholderValue(path, scope) {
+	const names = [...[...scope.local, ...scope.persistent].flatMap((option) => makeArray(option.name)), ...makeArray(path[path.length - 1].subcommands).flatMap((command) => makeArray(command.name))];
+	for (const value of "0123456789abcdefghijklmnopqrstuvwxyz") {
+		const starts = [
+			value,
+			`-${value}`,
+			`+${value}`
+		];
+		if (!names.some((name) => starts.some((start) => name.startsWith(start)))) return value;
+	}
+	return "0";
+}
+/**
+* The tokens that write `form` with every value `option` takes, or one more
+* than its minimum if it takes any number. The first value is joined to the
+* name if the form says so, and the rest are separate tokens.
+*/
+function writeForm(option, form, value) {
+	const max = getMaxArgs(option.args);
+	const count = Number.isFinite(max) ? max : getMinArgs(option.args) + 1;
+	const values = Array.from({ length: count }, () => value);
+	if (form.join === null) return [form.name, ...values];
+	return [form.name + form.join + values[0], ...values.slice(1)];
+}
+/**
+* Asserts that the parser reads each name of the options that `include`
+* picks the way the name is written. See {@link assertNamesReadBack}.
+*/
+function assertOptionFormsReadBack(spec, include) {
+	const root = spec;
+	forEachOption(spec, ({ option, where, scope, path }) => {
+		const before = tokensTo(path);
+		const value = placeholderValue(path, scope);
+		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;
+			if (form.join !== "") {
+				const reading = 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 !== 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]);
+				assert(reading.kind === "value" && reading.option === option, `${written}, but in '${tokens.join(" ")}' the parser reads '${tokens[index]}' as ${describeReading(reading, path)}`);
+			}
 		}
 	});
 }
+/**
+* Asserts that the parser reads every name the way it's written: each name of
+* a subcommand enters that subcommand, and each name of an option uses that
+* option, at every command the option can be used in. Each option is also
+* written the way help shows it, with every value it takes, and the parser has
+* to read all of those values as the option's.
+*/
+function assertNamesReadBack(spec) {
+	const root = spec;
+	forEachSubcommand(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);
+			if (reading.kind === "subcommand" && reading.command === subcommand) continue;
+			assert(false, `${describeCommand([...path, subcommand])} has the name '${name}', but the parser reads it as ${describeReading(reading, path)}`);
+		}
+	});
+	assertOptionFormsReadBack(spec, () => true);
+}
 function assertCommonOptionsArePersistent(spec) {
 	const failures = [];
 	forEachSubcommand(spec, (subcommand, path) => {
@@ -265,7 +1283,8 @@ function assertCommonOptionsArePersistent(spec) {
 		for (const option of makeArray(subcommand.options)) {
 			const allChildSubcommands = [];
 			forEachSubcommand(subcommand, (cmd) => allChildSubcommands.push(cmd));
-			if (allChildSubcommands.every((cmd) => makeArray(cmd.options).some((o) => isSameName(option.name, o.name))) && !failures.some(([name]) => isSameName(name, option.name))) failures.push([option.name, namedArrayToString(...path, option)]);
+			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)]);
 		}
 	});
 	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.
@@ -274,15 +1293,12 @@ ${failures.map(([, line]) => " * " + line).join("\n")}
 }
 /**
 * Asserts that references to other options by name actually refer to options
-* that exist in scope
+* that exist in scope, at every command the option can be used in
 */
 function assertOptionNameReferencesExist(spec) {
-	forEachOptionArray(spec, (options, path) => {
-		const optionNames = /* @__PURE__ */ new Set([...path.slice(0, -1).flatMap((subcommand) => subcommand.options ? subcommand.options.filter((option) => option.isPersistent).flatMap((option) => option.name) : []), ...options.flatMap((option) => option.name)]);
-		for (const [index, option] of makeArray(options).entries()) {
-			for (const name of makeArray(option.dependsOn)) assert(optionNames.has(name), `The option ${namedArrayToString(...path, option)} (index ${index}) depends on an option named ${repr(name)}, which doesn't exist in its scope`);
-			for (const name of makeArray(option.exclusiveOn)) assert(optionNames.has(name), `The option ${namedArrayToString(...path, option)} (index ${index}) is exclusive on an option named ${repr(name)}, which doesn't exist in its scope`);
-		}
+	forEachOption(spec, ({ option, where, scope }) => {
+		for (const name of makeArray(option.dependsOn)) assert(scope.resolve(name) !== null, `${where} depends on an option named ${repr(name)}, which doesn't exist in its scope`);
+		for (const name of makeArray(option.exclusiveOn)) assert(scope.resolve(name) !== null, `${where} is exclusive on an option named ${repr(name)}, which doesn't exist in its scope`);
 	});
 }
 /**
@@ -290,13 +1306,10 @@ function assertOptionNameReferencesExist(spec) {
 */
 function assertPrefixMatchCommandsHaveNoArguments(spec) {
 	forEachSubcommand(spec, (subcommand, path) => {
-		if (!path.some((cmd) => cmd.parserDirectives?.subcommandsMatchUniquePrefix === true)) return;
+		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 }\``);
 	});
 }
-function getName(namingStyle, names) {
-	return names[namingStyle];
-}
 async function runStep(context, name, fn) {
 	if (context) {
 		await context.step(name, fn);
@@ -313,118 +1326,106 @@ async function runStep(context, name, fn) {
 */
 function test(spec, options = {}) {
 	const { allowShadowingPersistentOptions = false, allowNoDescription = false, allowLongDescriptionLines = false, allowMatchingSubcommandPrefixAndArgs = false, namingStyle = "sentence" } = options;
+	const checks = [
+		[
+			"Required arguments don't follow optional arguments",
+			"assertRequiredArgumentsDoNotFollowOptionalArguments",
+			assertRequiredArgumentsDoNotFollowOptionalArguments,
+			true
+		],
+		[
+			"The parser can use every default",
+			"assertDefaultsCanBeUsed",
+			assertDefaultsCanBeUsed,
+			true
+		],
+		[
+			"Repeatable options that are numbers are integers greater than 1",
+			"assertRepeatableOptionsArePositiveIntegers",
+			assertRepeatableOptionsArePositiveIntegers,
+			true
+		],
+		[
+			"Options have locally unique names",
+			"assertOptionsHaveLocallyUniqueNames",
+			assertOptionsHaveLocallyUniqueNames,
+			true
+		],
+		[
+			"Options don't shadow persistent options",
+			"assertOptionsDoNotShadowPersistentOptions",
+			assertOptionsDoNotShadowPersistentOptions,
+			!allowShadowingPersistentOptions
+		],
+		[
+			"Different options on a subcommand and its parents have different names",
+			"assertOptionsHaveDifferentNamesFromParents",
+			assertOptionsHaveDifferentNamesFromParents,
+			true
+		],
+		[
+			"Subcommands have locally unique names",
+			"assertSubcommandsHaveLocallyUniqueNames",
+			assertSubcommandsHaveLocallyUniqueNames,
+			true
+		],
+		[
+			"The parser reads every option and subcommand the way it's written",
+			"assertNamesReadBack",
+			assertNamesReadBack,
+			true
+		],
+		[
+			"Option arg separators are not an empty string",
+			"assertOptionArgSeparatorsHaveCharacters",
+			assertOptionArgSeparatorsHaveCharacters,
+			true
+		],
+		[
+			"Names have no extra leading or trailing whitespace",
+			"assertNamesHaveNoExtraWhitespace",
+			assertNamesHaveNoExtraWhitespace,
+			true
+		],
+		[
+			"Everything has a description",
+			"assertEverythingHasDescription",
+			assertEverythingHasDescription,
+			!allowNoDescription
+		],
+		[
+			"Each line in descriptions is less than or equal to 68 characters",
+			"assertDescriptionLineLengthUnder69",
+			assertDescriptionLineLengthUnder69,
+			!allowLongDescriptionLines
+		],
+		[
+			"Common options are not defined on every subcommand",
+			"assertCommonOptionsArePersistent",
+			assertCommonOptionsArePersistent,
+			true
+		],
+		[
+			"References to other options by name are valid",
+			"assertOptionNameReferencesExist",
+			assertOptionNameReferencesExist,
+			true
+		],
+		[
+			"Commands with `subcommandsMatchUniquePrefix` don't have arguments and subcommands",
+			"assertPrefixMatchCommandsHaveNoArguments",
+			assertPrefixMatchCommandsHaveNoArguments,
+			!allowMatchingSubcommandPrefixAndArgs
+		]
+	];
 	return async (t) => {
-		await runStep(t, getName(namingStyle, {
-			sentence: "Required arguments don't follow optional arguments",
-			function: "assertRequiredArgumentsDoNotFollowOptionalArguments"
-		}), () => {
-			assertRequiredArgumentsDoNotFollowOptionalArguments(spec);
-		});
-		await runStep(t, getName(namingStyle, {
-			sentence: "Repeatable options that are numbers are integers greater than 1",
-			function: "assertRepeatableOptionsArePositiveIntegers"
-		}), () => {
-			assertRepeatableOptionsArePositiveIntegers(spec);
-		});
-		await runStep(t, getName(namingStyle, {
-			sentence: "Long option names don't start with a single dash",
-			function: "assertLongOptionNamesDoNotStartWithSingleDash"
-		}), () => {
-			assertLongOptionNamesDoNotStartWithSingleDash(spec);
-		});
-		await runStep(t, getName(namingStyle, {
-			sentence: "Option names all start with dashes",
-			function: "assertOptionNamesStartWithDashes"
-		}), () => {
-			assertOptionNamesStartWithDashes(spec);
-		});
-		await runStep(t, getName(namingStyle, {
-			sentence: "Options have locally unique names",
-			function: "assertOptionsHaveLocallyUniqueNames"
-		}), () => {
-			assertOptionsHaveLocallyUniqueNames(spec);
-		});
-		if (!allowShadowingPersistentOptions) await runStep(t, getName(namingStyle, {
-			sentence: "Options don't shadow persistent options",
-			function: "assertOptionsDoNotShadowPersistentOptions"
-		}), () => {
-			assertOptionsDoNotShadowPersistentOptions(spec);
-		});
-		await runStep(t, getName(namingStyle, {
-			sentence: "Different options on a subcommand and its parents have different names",
-			function: "assertOptionsHaveDifferentNamesFromParents"
-		}), () => {
-			assertOptionsHaveDifferentNamesFromParents(spec);
-		});
-		await runStep(t, getName(namingStyle, {
-			sentence: "Subcommands have locally unique names",
-			function: "assertSubcommandsHaveLocallyUniqueNames"
-		}), () => {
-			assertSubcommandsHaveLocallyUniqueNames(spec);
-		});
-		await runStep(t, getName(namingStyle, {
-			sentence: "Nothing is named '--'",
-			function: "assertNothingIsNamedDashDash"
-		}), () => {
-			assertNothingIsNamedDashDash(spec);
-		});
-		await runStep(t, getName(namingStyle, {
-			sentence: "Option arg separators are not an empty string",
-			function: "assertOptionArgSeparatorsHaveCharacters"
-		}), () => {
-			assertOptionArgSeparatorsHaveCharacters(spec);
-		});
-		await runStep(t, getName(namingStyle, {
-			sentence: "Options named '-' or '+' take exactly one argument",
-			function: "assertPlusMinusOptionsTakeOneArg"
-		}), () => {
-			assertPlusMinusOptionsTakeOneArg(spec);
-		});
-		await runStep(t, getName(namingStyle, {
-			sentence: "Names have no extra leading or trailing whitespace",
-			function: "assertNamesHaveNoExtraWhitespace"
-		}), () => {
-			assertNamesHaveNoExtraWhitespace(spec);
-		});
-		if (!allowNoDescription) await runStep(t, getName(namingStyle, {
-			sentence: "Everything has a description",
-			function: "assertEverythingHasDescription"
-		}), () => {
-			assertEverythingHasDescription(spec);
-		});
-		if (!allowLongDescriptionLines) await runStep(t, getName(namingStyle, {
-			sentence: "Each line in descriptions is less than or equal to 68 characters",
-			function: "assertDescriptionLineLengthUnder69"
-		}), () => {
-			assertDescriptionLineLengthUnder69(spec);
-		});
-		await runStep(t, getName(namingStyle, {
-			sentence: "Options with `requiresSeparator` take exactly one argument",
-			function: "assertRequiresSeparatorTakesOneArg"
-		}), () => {
-			assertRequiresSeparatorTakesOneArg(spec);
-		});
-		await runStep(t, getName(namingStyle, {
-			sentence: "Common options are not defined on every subcommand",
-			function: "assertCommonOptionsArePersistent"
-		}), () => {
-			assertCommonOptionsArePersistent(spec);
-		});
-		await runStep(t, getName(namingStyle, {
-			sentence: "References to other options by name are valid",
-			function: "assertOptionNameReferencesExist"
-		}), () => {
-			assertOptionNameReferencesExist(spec);
-		});
-		if (!allowMatchingSubcommandPrefixAndArgs) await runStep(t, getName(namingStyle, {
-			sentence: "Commands with `subcommandsMatchUniquePrefix` don't have arguments and subcommands",
-			function: "assertPrefixMatchCommandsHaveNoArguments"
-		}), () => {
-			assertPrefixMatchCommandsHaveNoArguments(spec);
-		});
+		for (const [sentence, functionName, check, enabled] of checks) {
+			if (!enabled) continue;
+			await runStep(t, namingStyle === "function" ? functionName : sentence, () => check(spec));
+		}
 	};
 }
 const testSpec = test;
-export { assertCommonOptionsArePersistent, assertDescriptionLineLengthUnder69, assertEverythingHasDescription, assertLongOptionNamesDoNotStartWithSingleDash, assertNamesHaveNoExtraWhitespace, assertNothingIsNamedDashDash, assertOptionArgSeparatorsHaveCharacters, assertOptionNameReferencesExist, assertOptionNamesStartWithDashes, assertOptionsDoNotShadowPersistentOptions, assertOptionsHaveDifferentNamesFromParents, assertOptionsHaveLocallyUniqueNames, assertPlusMinusOptionsTakeOneArg, assertPrefixMatchCommandsHaveNoArguments, assertRepeatableOptionsArePositiveIntegers, assertRequiredArgumentsDoNotFollowOptionalArguments, assertRequiresSeparatorTakesOneArg, assertSubcommandsHaveLocallyUniqueNames, test, testSpec };
+export { assertCommonOptionsArePersistent, assertDefaultsCanBeUsed, assertDescriptionLineLengthUnder69, assertEverythingHasDescription, assertNamesHaveNoExtraWhitespace, assertNamesReadBack, assertOptionArgSeparatorsHaveCharacters, assertOptionNameReferencesExist, assertOptionsDoNotShadowPersistentOptions, assertOptionsHaveDifferentNamesFromParents, assertOptionsHaveLocallyUniqueNames, assertPlusMinusOptionsTakeOneArg, assertPrefixMatchCommandsHaveNoArguments, assertRepeatableOptionsArePositiveIntegers, assertRequiredArgumentsDoNotFollowOptionalArguments, assertRequiresSeparatorTakesOneArg, assertSubcommandsHaveLocallyUniqueNames, test, testSpec };
 
 //# sourceMappingURL=testing.js.map