@optique/core 1.0.0-dev.1533 → 1.0.0-dev.1547

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}").`);
 			}
 		}
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1533+25e020de",
+  "version": "1.0.0-dev.1547+bde3f632",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",