@optique/core 1.0.0-dev.1536 → 1.0.0-dev.1553

package/dist/usage.d.ts

@@ -270,80 +270,6 @@ declare function extractOptionNames(usage: Usage, includeHidden?: boolean): Set<
  * @since 0.7.0
  */
 declare function extractCommandNames(usage: Usage, includeHidden?: boolean): Set<string>;
-/**
- * Extracts option names that are reachable at the leading token position
- * (before any command or argument gate).
- *
- * Unlike {@link extractOptionNames}, which traverses the entire usage tree,
- * this function stops scanning a terms array after encountering a `command`,
- * `argument`, or `literal` term, because subsequent terms are scoped under
- * that positional token.  It still recurses into `optional`, `multiple`,
- * and `exclusive` containers, since they represent alternatives or wrappers
- * at the same position.
- *
- * Known limitation: this function infers token positions from the `usage`
- * tree, which is a display-oriented structure.  Combinators like `tuple()`
- * and `object()` sort or flatten usage by priority rather than token order,
- * so the results can be inaccurate—both false positives (e.g., options
- * appearing before commands due to priority sorting) and false negatives
- * (e.g., options after commands that are actually parallel peers).
- * The proper fix is to use `Parser.leadingNames` instead of usage-tree
- * analysis.
- * See https://github.com/dahlia/optique/issues/735
- *
- * @param usage The usage description to extract leading option names from.
- * @param includeHidden Whether to include fully hidden options
- *   (`hidden: true`) in the result.  Defaults to `false`.
- * @returns A set of option names reachable at the leading token position.
- * @since 1.0.0
- */
-declare function extractLeadingOptionNames(usage: Usage, includeHidden?: boolean): Set<string>;
-/**
- * Extracts command names that could match as the first positional token.
- *
- * Unlike {@link extractCommandNames}, which traverses the entire usage tree,
- * this function stops scanning a terms array after encountering a `command`,
- * `argument`, or `literal` term, because subsequent terms in that array are
- * scoped under that positional token (reachable only after the leading term
- * is consumed).  It still recurses into `optional`, `multiple`, and
- * `exclusive` containers, since they represent alternatives or optional
- * wrappers at the same token position.
- *
- * Known limitation: this function has the same usage-tree ordering caveat
- * as {@link extractLeadingOptionNames}.
- * See https://github.com/dahlia/optique/issues/735
- *
- * @param usage The usage description to extract leading command names from.
- * @param includeHidden Whether to include fully hidden commands
- *   (`hidden: true`) in the result.  Defaults to `false`.
- * @returns A set of command names that could match at the first token position.
- * @since 1.0.0
- */
-declare function extractLeadingCommandNames(usage: Usage, includeHidden?: boolean): Set<string>;
-/**
- * Extracts literal values that could match as the first positional token.
- *
- * Unlike {@link extractLiteralValues}, which traverses the entire usage tree,
- * this function stops scanning a terms array after encountering a `command`,
- * `argument`, or `literal` term, because subsequent terms in that array are
- * scoped under that positional token.  It still recurses into `optional`,
- * `multiple`, and `exclusive` containers.
- *
- * Literals tagged with `optionValue: true` (produced by
- * `appendLiteralToUsage()` when rewriting option metavars for
- * `conditional()` discriminators) are skipped, because they represent
- * option values rather than standalone positional tokens.
- *
- * Known limitation: this function has the same usage-tree ordering caveat
- * as {@link extractLeadingOptionNames}.
- * See https://github.com/dahlia/optique/issues/735
- *
- * @param usage The usage description to extract leading literal values from.
- * @returns A set of literal values that could match at the first token
- *   position.
- * @since 1.0.0
- */
-declare function extractLeadingLiteralValues(usage: Usage): Set<string>;
 /**
  * Extracts all literal values from a usage description.
  *
@@ -520,4 +446,4 @@ interface UsageTermFormatOptions extends UsageFormatOptions {
  */
 declare function formatUsageTerm(term: UsageTerm, options?: UsageTermFormatOptions): string;
 //#endregion
-export { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingLiteralValues, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };
+export { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };

package/dist/usage.js

@@ -104,197 +104,6 @@ function extractCommandNames(usage, includeHidden) {
 	return names;
 }
 /**
-* Extracts option names that are reachable at the leading token position
-* (before any command or argument gate).
-*
-* Unlike {@link extractOptionNames}, which traverses the entire usage tree,
-* this function stops scanning a terms array after encountering a `command`,
-* `argument`, or `literal` term, because subsequent terms are scoped under
-* that positional token.  It still recurses into `optional`, `multiple`,
-* and `exclusive` containers, since they represent alternatives or wrappers
-* at the same position.
-*
-* Known limitation: this function infers token positions from the `usage`
-* tree, which is a display-oriented structure.  Combinators like `tuple()`
-* and `object()` sort or flatten usage by priority rather than token order,
-* so the results can be inaccurate—both false positives (e.g., options
-* appearing before commands due to priority sorting) and false negatives
-* (e.g., options after commands that are actually parallel peers).
-* The proper fix is to use `Parser.leadingNames` instead of usage-tree
-* analysis.
-* See https://github.com/dahlia/optique/issues/735
-*
-* @param usage The usage description to extract leading option names from.
-* @param includeHidden Whether to include fully hidden options
-*   (`hidden: true`) in the result.  Defaults to `false`.
-* @returns A set of option names reachable at the leading token position.
-* @since 1.0.0
-*/
-function extractLeadingOptionNames(usage, includeHidden) {
-	const names = /* @__PURE__ */ new Set();
-	function collectLeading(terms) {
-		if (!terms || !Array.isArray(terms)) return;
-		for (const term of terms) switch (term.type) {
-			case "option":
-				if (!includeHidden && isSuggestionHidden(term.hidden)) break;
-				for (const name of term.names) names.add(name);
-				break;
-			case "command": return;
-			case "argument":
-			case "literal": return;
-			case "optional":
-				collectLeading(term.terms);
-				break;
-			case "multiple":
-				collectLeading(term.terms);
-				if (term.min > 0 && branchConsumesToken(term.terms)) return;
-				break;
-			case "exclusive":
-				for (const branch of term.terms) collectLeading(branch);
-				if (exclusiveConsumesToken(term.terms)) return;
-				break;
-			default: break;
-		}
-	}
-	collectLeading(usage);
-	return names;
-}
-/**
-* Extracts command names that could match as the first positional token.
-*
-* Unlike {@link extractCommandNames}, which traverses the entire usage tree,
-* this function stops scanning a terms array after encountering a `command`,
-* `argument`, or `literal` term, because subsequent terms in that array are
-* scoped under that positional token (reachable only after the leading term
-* is consumed).  It still recurses into `optional`, `multiple`, and
-* `exclusive` containers, since they represent alternatives or optional
-* wrappers at the same token position.
-*
-* Known limitation: this function has the same usage-tree ordering caveat
-* as {@link extractLeadingOptionNames}.
-* See https://github.com/dahlia/optique/issues/735
-*
-* @param usage The usage description to extract leading command names from.
-* @param includeHidden Whether to include fully hidden commands
-*   (`hidden: true`) in the result.  Defaults to `false`.
-* @returns A set of command names that could match at the first token position.
-* @since 1.0.0
-*/
-function extractLeadingCommandNames(usage, includeHidden) {
-	const names = /* @__PURE__ */ new Set();
-	function collectLeading(terms) {
-		if (!terms || !Array.isArray(terms)) return;
-		for (const term of terms) switch (term.type) {
-			case "command":
-				if (!includeHidden && isSuggestionHidden(term.hidden)) return;
-				names.add(term.name);
-				return;
-			case "argument":
-			case "literal": return;
-			case "optional":
-				collectLeading(term.terms);
-				break;
-			case "multiple":
-				collectLeading(term.terms);
-				if (term.min > 0 && branchConsumesToken(term.terms)) return;
-				break;
-			case "exclusive":
-				for (const branch of term.terms) collectLeading(branch);
-				if (exclusiveConsumesToken(term.terms)) return;
-				break;
-			default: break;
-		}
-	}
-	collectLeading(usage);
-	return names;
-}
-/**
-* Extracts literal values that could match as the first positional token.
-*
-* Unlike {@link extractLiteralValues}, which traverses the entire usage tree,
-* this function stops scanning a terms array after encountering a `command`,
-* `argument`, or `literal` term, because subsequent terms in that array are
-* scoped under that positional token.  It still recurses into `optional`,
-* `multiple`, and `exclusive` containers.
-*
-* Literals tagged with `optionValue: true` (produced by
-* `appendLiteralToUsage()` when rewriting option metavars for
-* `conditional()` discriminators) are skipped, because they represent
-* option values rather than standalone positional tokens.
-*
-* Known limitation: this function has the same usage-tree ordering caveat
-* as {@link extractLeadingOptionNames}.
-* See https://github.com/dahlia/optique/issues/735
-*
-* @param usage The usage description to extract leading literal values from.
-* @returns A set of literal values that could match at the first token
-*   position.
-* @since 1.0.0
-*/
-function extractLeadingLiteralValues(usage) {
-	const values = /* @__PURE__ */ new Set();
-	function collectLeading(terms) {
-		if (!terms || !Array.isArray(terms)) return;
-		for (const term of terms) switch (term.type) {
-			case "literal":
-				if (term.optionValue) break;
-				values.add(term.value);
-				return;
-			case "command":
-			case "argument": return;
-			case "optional":
-				collectLeading(term.terms);
-				break;
-			case "multiple":
-				collectLeading(term.terms);
-				if (term.min > 0 && branchConsumesToken(term.terms, true)) return;
-				break;
-			case "exclusive":
-				for (const branch of term.terms) collectLeading(branch);
-				if (exclusiveConsumesToken(term.terms, true)) return;
-				break;
-			default: break;
-		}
-	}
-	collectLeading(usage);
-	return values;
-}
-/**
-* Checks whether every branch of an exclusive term must consume a positional
-* token.  When true, terms after the exclusive are at position N+1 and should
-* not be considered "leading".
-*
-* @param skipOptionValueLiterals When `true`, literals tagged with
-*   `optionValue` are treated as non-positional.  Only
-*   `extractLeadingLiteralValues()` passes `true`; the option/command
-*   extractors use the default (`false`) so that option+value pairs
-*   still act as positional gates.
-*/
-function exclusiveConsumesToken(branches, skipOptionValueLiterals = false) {
-	if (branches.length === 0) return false;
-	return branches.every((branch) => branchConsumesToken(branch, skipOptionValueLiterals));
-}
-function branchConsumesToken(terms, skipOptionValueLiterals = false) {
-	if (!terms || !Array.isArray(terms)) return false;
-	for (const term of terms) switch (term.type) {
-		case "command":
-		case "argument": return true;
-		case "literal":
-			if (skipOptionValueLiterals && term.optionValue) break;
-			return true;
-		case "option": break;
-		case "optional": break;
-		case "multiple":
-			if (term.min > 0 && branchConsumesToken(term.terms, skipOptionValueLiterals)) return true;
-			break;
-		case "exclusive":
-			if (exclusiveConsumesToken(term.terms, skipOptionValueLiterals)) return true;
-			break;
-		default: break;
-	}
-	return false;
-}
-/**
 * Extracts all literal values from a usage description.
 *
 * This function recursively traverses the usage tree and collects all
@@ -765,4 +574,4 @@ function* formatUsageTermInternal(term, options) {
 }
 
 //#endregion
-export { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingLiteralValues, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };
+export { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };

package/dist/validate.cjs

@@ -112,19 +112,30 @@ function validateMetaNameCollisions(userNames, metaEntries) {
 			}
 		}
 	}
-	for (const [kind, label, names, prefixMatch] of metaEntries) {
-		const optionNames = kind === "command" ? userNames.leadingOptions : userNames.allOptions;
-		const commandNames = kind === "command" ? userNames.leadingCommands : userNames.allCommands;
-		for (const name of names) {
-			if (optionNames.has(name)) throw new TypeError(`User-defined option "${name}" conflicts with the built-in ${label}.`);
-			if (commandNames.has(name)) throw new TypeError(`User-defined command "${name}" conflicts with the built-in ${label}.`);
-			const literalNames = kind === "command" ? userNames.leadingLiterals : userNames.allLiterals;
-			if (literalNames.has(name)) throw new TypeError(`Literal value "${name}" conflicts with the built-in ${label}.`);
-			if (prefixMatch) {
-				const prefix = name + "=";
-				for (const userName of optionNames) if (userName.startsWith(prefix)) throw new TypeError(`User-defined option "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
-				for (const userName of commandNames) if (userName.startsWith(prefix)) throw new TypeError(`User-defined command "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
-				for (const literal of literalNames) if (literal.startsWith(prefix)) throw new TypeError(`Literal value "${literal}" conflicts with the built-in ${label} (prefix "${prefix}").`);
+	for (const [kind, label, names, prefixMatch] of metaEntries) for (const name of names) {
+		if (kind === "command") {
+			if (userNames.leadingNames.has(name)) if (userNames.allOptions.has(name)) throw new TypeError(`User-defined option "${name}" conflicts with the built-in ${label}.`);
+			else if (userNames.allCommands.has(name)) throw new TypeError(`User-defined command "${name}" conflicts with the built-in ${label}.`);
+			else if (userNames.allLiterals.has(name)) throw new TypeError(`Literal value "${name}" conflicts with the built-in ${label}.`);
+			else throw new TypeError(`User-defined name "${name}" conflicts with the built-in ${label}.`);
+		} else {
+			if (userNames.allOptions.has(name)) throw new TypeError(`User-defined option "${name}" conflicts with the built-in ${label}.`);
+			if (userNames.allCommands.has(name)) throw new TypeError(`User-defined command "${name}" conflicts with the built-in ${label}.`);
+			if (userNames.allLiterals.has(name)) throw new TypeError(`Literal value "${name}" conflicts with the built-in ${label}.`);
+		}
+		if (prefixMatch) {
+			const prefix = name + "=";
+			const checkSets = kind === "command" ? [userNames.leadingNames] : [
+				userNames.allOptions,
+				userNames.allCommands,
+				userNames.allLiterals
+			];
+			for (const nameSet of checkSets) for (const userName of nameSet) {
+				if (!userName.startsWith(prefix)) continue;
+				if (userNames.allOptions.has(userName)) throw new TypeError(`User-defined option "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
+				else if (userNames.allCommands.has(userName)) throw new TypeError(`User-defined command "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
+				else if (userNames.allLiterals.has(userName)) throw new TypeError(`Literal value "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
+				else throw new TypeError(`User-defined name "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
 			}
 		}
 	}

package/dist/validate.js

@@ -111,19 +111,30 @@ function validateMetaNameCollisions(userNames, metaEntries) {
 			}
 		}
 	}
-	for (const [kind, label, names, prefixMatch] of metaEntries) {
-		const optionNames = kind === "command" ? userNames.leadingOptions : userNames.allOptions;
-		const commandNames = kind === "command" ? userNames.leadingCommands : userNames.allCommands;
-		for (const name of names) {
-			if (optionNames.has(name)) throw new TypeError(`User-defined option "${name}" conflicts with the built-in ${label}.`);
-			if (commandNames.has(name)) throw new TypeError(`User-defined command "${name}" conflicts with the built-in ${label}.`);
-			const literalNames = kind === "command" ? userNames.leadingLiterals : userNames.allLiterals;
-			if (literalNames.has(name)) throw new TypeError(`Literal value "${name}" conflicts with the built-in ${label}.`);
-			if (prefixMatch) {
-				const prefix = name + "=";
-				for (const userName of optionNames) if (userName.startsWith(prefix)) throw new TypeError(`User-defined option "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
-				for (const userName of commandNames) if (userName.startsWith(prefix)) throw new TypeError(`User-defined command "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
-				for (const literal of literalNames) if (literal.startsWith(prefix)) throw new TypeError(`Literal value "${literal}" conflicts with the built-in ${label} (prefix "${prefix}").`);
+	for (const [kind, label, names, prefixMatch] of metaEntries) for (const name of names) {
+		if (kind === "command") {
+			if (userNames.leadingNames.has(name)) if (userNames.allOptions.has(name)) throw new TypeError(`User-defined option "${name}" conflicts with the built-in ${label}.`);
+			else if (userNames.allCommands.has(name)) throw new TypeError(`User-defined command "${name}" conflicts with the built-in ${label}.`);
+			else if (userNames.allLiterals.has(name)) throw new TypeError(`Literal value "${name}" conflicts with the built-in ${label}.`);
+			else throw new TypeError(`User-defined name "${name}" conflicts with the built-in ${label}.`);
+		} else {
+			if (userNames.allOptions.has(name)) throw new TypeError(`User-defined option "${name}" conflicts with the built-in ${label}.`);
+			if (userNames.allCommands.has(name)) throw new TypeError(`User-defined command "${name}" conflicts with the built-in ${label}.`);
+			if (userNames.allLiterals.has(name)) throw new TypeError(`Literal value "${name}" conflicts with the built-in ${label}.`);
+		}
+		if (prefixMatch) {
+			const prefix = name + "=";
+			const checkSets = kind === "command" ? [userNames.leadingNames] : [
+				userNames.allOptions,
+				userNames.allCommands,
+				userNames.allLiterals
+			];
+			for (const nameSet of checkSets) for (const userName of nameSet) {
+				if (!userName.startsWith(prefix)) continue;
+				if (userNames.allOptions.has(userName)) throw new TypeError(`User-defined option "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
+				else if (userNames.allCommands.has(userName)) throw new TypeError(`User-defined command "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
+				else if (userNames.allLiterals.has(userName)) throw new TypeError(`Literal value "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
+				else throw new TypeError(`User-defined name "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
 			}
 		}
 	}