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

package/dist/parser.d.ts

@@ -105,6 +105,44 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * to use it in command-line interfaces.
    */
   readonly usage: Usage;
+  /**
+   * Names that this parser could match at the first buffer position.
+   * Used by `runParser()` to detect collisions with built-in meta
+   * features (help, version, completion).
+   *
+   * Each built-in combinator computes this from its structural semantics.
+   * Custom parser implementations must include every fixed token that
+   * the parser accepts at `argv[0]` — command names, option names, and
+   * literal values alike.  For example, a parser whose usage declares
+   * `{ type: "literal", value: "serve" }` should include `"serve"` in
+   * this set.  Parsers that accept *any* token (like `argument()`) should
+   * return an empty set and set {@link acceptingAnyToken} to `true`
+   * instead.
+   *
+   * @since 1.0.0
+   */
+  readonly leadingNames: ReadonlySet<string>;
+  /**
+   * Whether this parser unconditionally consumes any positional token at
+   * the first buffer position.  A parser with this flag accepts any
+   * non-option token but may still reject option-like tokens (those
+   * starting with `"-"`).
+   *
+   * In shared-buffer compositions (`tuple()`, `object()`, `merge()`,
+   * `concat()`), a catch-all parser blocks positional names (command
+   * names) from lower-priority siblings but does not block option-like
+   * names.  In `conditional()`, option-like names from the default
+   * branch remain reachable even when the discriminator is a catch-all.
+   *
+   * Only `argument()` is inherently accepting-any-token; combinators
+   * like `or()` and `map()` propagate this from their children.
+   * Wrappers that can succeed without consuming (`optional()`,
+   * `withDefault()`, `multiple()` with `min = 0`) always set this
+   * to `false`.
+   *
+   * @since 1.0.0
+   */
+  readonly acceptingAnyToken: boolean;
   /**
    * The initial state for this parser.  This is used to initialize the
    * state when parsing starts.
@@ -187,6 +225,26 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * @since 1.0.0
    */
   shouldDeferCompletion?(state: TState): boolean;
+  /**
+   * Normalizes a parsed value according to the underlying value parser's
+   * configuration.  When present, {@link withDefault} calls this method
+   * on default values so that runtime defaults match the representation
+   * that the value parser's `parse()` would produce.
+   *
+   * Primitive parsers ({@link option}, {@link argument}) implement this
+   * by delegating to {@link ValueParser.normalize}.  Combinator wrappers
+   * ({@link optional}, {@link withDefault}) forward it from inner parsers.
+   *
+   * Exclusive combinators ({@link or}, `longestMatch()`) and
+   * multi-source combinators (`merge()`) intentionally do *not*
+   * implement this method because the active branch or key ownership
+   * is unknown at default time.
+   *
+   * @param value The value to normalize.
+   * @returns The normalized value.
+   * @since 1.0.0
+   */
+  normalizeValue?(value: TValue): TValue;
 }
 /**
  * The context of the parser, which includes the input buffer and the state.

package/dist/primitives.cjs

@@ -9,6 +9,11 @@ const require_usage_internals = require('./usage-internals.cjs');
 const require_valueparser = require('./valueparser.cjs');
 
 //#region src/primitives.ts
+/**
+* A shared empty set used as the `leadingNames` value for parsers that
+* do not match any specific name at the first buffer position.
+*/
+const EMPTY_LEADING_NAMES = /* @__PURE__ */ new Set();
 function hasParsedOptionValue(state, valueParser) {
 	if (valueParser != null) return require_dependency.isDeferredParseState(state) || require_dependency.isDependencySourceState(state) || state != null && "success" in state && state.success;
 	return state != null && "success" in state && state.success && state.value === true;
@@ -38,6 +43,8 @@ function constant(value) {
 		$mode: "sync",
 		priority: 0,
 		usage: [],
+		leadingNames: EMPTY_LEADING_NAMES,
+		acceptingAnyToken: false,
 		initialState: value,
 		parse(context) {
 			return {
@@ -93,6 +100,8 @@ function fail() {
 		$mode: "sync",
 		priority: 0,
 		usage: [],
+		leadingNames: EMPTY_LEADING_NAMES,
+		acceptingAnyToken: false,
 		initialState: void 0,
 		parse(_context) {
 			return {
@@ -338,6 +347,8 @@ function option(...args) {
 			metavar: valueParser.metavar,
 			...options.hidden != null && { hidden: options.hidden }
 		}],
+		leadingNames: new Set(optionNames$1),
+		acceptingAnyToken: false,
 		initialState: valueParser == null ? {
 			success: true,
 			value: false
@@ -553,6 +564,20 @@ function option(...args) {
 			return `option(${optionNames$1.map((o) => JSON.stringify(o)).join(", ")})`;
 		}
 	};
+	if (valueParser != null && typeof valueParser.normalize === "function") {
+		const normalize = valueParser.normalize.bind(valueParser);
+		Object.defineProperty(result, "normalizeValue", {
+			value(v) {
+				try {
+					return normalize(v);
+				} catch {
+					return v;
+				}
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	if (valueParser != null) Object.defineProperty(result, "placeholder", {
 		get() {
 			try {
@@ -622,6 +647,8 @@ function flag(...args) {
 			names: optionNames$1,
 			...options.hidden != null && { hidden: options.hidden }
 		}],
+		leadingNames: new Set(optionNames$1),
+		acceptingAnyToken: false,
 		initialState: void 0,
 		parse(context) {
 			if (context.optionsTerminated) return {
@@ -797,6 +824,8 @@ function argument(valueParser, options = {}) {
 		$stateType: [],
 		priority: 5,
 		usage: [term],
+		leadingNames: EMPTY_LEADING_NAMES,
+		acceptingAnyToken: true,
 		initialState: void 0,
 		parse(context) {
 			if (context.buffer.length < 1) return {
@@ -903,6 +932,20 @@ function argument(valueParser, options = {}) {
 			return `argument()`;
 		}
 	};
+	if (typeof valueParser.normalize === "function") {
+		const normalize = valueParser.normalize.bind(valueParser);
+		Object.defineProperty(result, "normalizeValue", {
+			value(v) {
+				try {
+					return normalize(v);
+				} catch {
+					return v;
+				}
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	Object.defineProperty(result, "placeholder", {
 		get() {
 			try {
@@ -986,6 +1029,8 @@ function command(name, parser, options = {}) {
 			...options.usageLine != null && { usageLine: options.usageLine },
 			...options.hidden != null && { hidden: options.hidden }
 		}, ...parser.usage],
+		leadingNames: new Set([name]),
+		acceptingAnyToken: false,
 		initialState: void 0,
 		parse(context) {
 			if (context.state === void 0) {
@@ -1119,6 +1164,11 @@ function command(name, parser, options = {}) {
 			return `command(${JSON.stringify(name)})`;
 		}
 	};
+	if (typeof parser.normalizeValue === "function") Object.defineProperty(result, "normalizeValue", {
+		value: parser.normalizeValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return result;
 }
 /**
@@ -1180,6 +1230,8 @@ function passThrough(options = {}) {
 			type: "passthrough",
 			...options.hidden != null && { hidden: options.hidden }
 		}],
+		leadingNames: EMPTY_LEADING_NAMES,
+		acceptingAnyToken: false,
 		initialState: [],
 		parse(context) {
 			if (context.buffer.length < 1) return {

package/dist/primitives.js

@@ -9,6 +9,11 @@ import { extractLeadingCommandNames } from "./usage-internals.js";
 import { isValueParser } from "./valueparser.js";
 
 //#region src/primitives.ts
+/**
+* A shared empty set used as the `leadingNames` value for parsers that
+* do not match any specific name at the first buffer position.
+*/
+const EMPTY_LEADING_NAMES = /* @__PURE__ */ new Set();
 function hasParsedOptionValue(state, valueParser) {
 	if (valueParser != null) return isDeferredParseState(state) || isDependencySourceState(state) || state != null && "success" in state && state.success;
 	return state != null && "success" in state && state.success && state.value === true;
@@ -38,6 +43,8 @@ function constant(value) {
 		$mode: "sync",
 		priority: 0,
 		usage: [],
+		leadingNames: EMPTY_LEADING_NAMES,
+		acceptingAnyToken: false,
 		initialState: value,
 		parse(context) {
 			return {
@@ -93,6 +100,8 @@ function fail() {
 		$mode: "sync",
 		priority: 0,
 		usage: [],
+		leadingNames: EMPTY_LEADING_NAMES,
+		acceptingAnyToken: false,
 		initialState: void 0,
 		parse(_context) {
 			return {
@@ -338,6 +347,8 @@ function option(...args) {
 			metavar: valueParser.metavar,
 			...options.hidden != null && { hidden: options.hidden }
 		}],
+		leadingNames: new Set(optionNames$1),
+		acceptingAnyToken: false,
 		initialState: valueParser == null ? {
 			success: true,
 			value: false
@@ -553,6 +564,20 @@ function option(...args) {
 			return `option(${optionNames$1.map((o) => JSON.stringify(o)).join(", ")})`;
 		}
 	};
+	if (valueParser != null && typeof valueParser.normalize === "function") {
+		const normalize = valueParser.normalize.bind(valueParser);
+		Object.defineProperty(result, "normalizeValue", {
+			value(v) {
+				try {
+					return normalize(v);
+				} catch {
+					return v;
+				}
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	if (valueParser != null) Object.defineProperty(result, "placeholder", {
 		get() {
 			try {
@@ -622,6 +647,8 @@ function flag(...args) {
 			names: optionNames$1,
 			...options.hidden != null && { hidden: options.hidden }
 		}],
+		leadingNames: new Set(optionNames$1),
+		acceptingAnyToken: false,
 		initialState: void 0,
 		parse(context) {
 			if (context.optionsTerminated) return {
@@ -797,6 +824,8 @@ function argument(valueParser, options = {}) {
 		$stateType: [],
 		priority: 5,
 		usage: [term],
+		leadingNames: EMPTY_LEADING_NAMES,
+		acceptingAnyToken: true,
 		initialState: void 0,
 		parse(context) {
 			if (context.buffer.length < 1) return {
@@ -903,6 +932,20 @@ function argument(valueParser, options = {}) {
 			return `argument()`;
 		}
 	};
+	if (typeof valueParser.normalize === "function") {
+		const normalize = valueParser.normalize.bind(valueParser);
+		Object.defineProperty(result, "normalizeValue", {
+			value(v) {
+				try {
+					return normalize(v);
+				} catch {
+					return v;
+				}
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	Object.defineProperty(result, "placeholder", {
 		get() {
 			try {
@@ -986,6 +1029,8 @@ function command(name, parser, options = {}) {
 			...options.usageLine != null && { usageLine: options.usageLine },
 			...options.hidden != null && { hidden: options.hidden }
 		}, ...parser.usage],
+		leadingNames: new Set([name]),
+		acceptingAnyToken: false,
 		initialState: void 0,
 		parse(context) {
 			if (context.state === void 0) {
@@ -1119,6 +1164,11 @@ function command(name, parser, options = {}) {
 			return `command(${JSON.stringify(name)})`;
 		}
 	};
+	if (typeof parser.normalizeValue === "function") Object.defineProperty(result, "normalizeValue", {
+		value: parser.normalizeValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return result;
 }
 /**
@@ -1180,6 +1230,8 @@ function passThrough(options = {}) {
 			type: "passthrough",
 			...options.hidden != null && { hidden: options.hidden }
 		}],
+		leadingNames: EMPTY_LEADING_NAMES,
+		acceptingAnyToken: false,
 		initialState: [],
 		parse(context) {
 			if (context.buffer.length < 1) return {

package/dist/usage.cjs

@@ -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
@@ -769,9 +578,6 @@ exports.cloneUsage = cloneUsage;
 exports.cloneUsageTerm = cloneUsageTerm;
 exports.extractArgumentMetavars = extractArgumentMetavars;
 exports.extractCommandNames = extractCommandNames;
-exports.extractLeadingCommandNames = extractLeadingCommandNames;
-exports.extractLeadingLiteralValues = extractLeadingLiteralValues;
-exports.extractLeadingOptionNames = extractLeadingOptionNames;
 exports.extractLiteralValues = extractLiteralValues;
 exports.extractOptionNames = extractOptionNames;
 exports.formatUsage = formatUsage;

package/dist/usage.d.cts

@@ -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 };