@optique/core 1.4.0-dev.2708 → 1.4.0-dev.2711

package/dist/internal/usage.js

@@ -0,0 +1,246 @@
+//#region src/internal/usage.ts
+const EMPTY = {
+	visible: false,
+	omissible: true,
+	hidesRequired: false
+};
+function isHiddenLeaf(term, isHidden) {
+	return (term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") && isHidden(term.hidden);
+}
+function isDegenerateLeaf(term) {
+	return term.type === "option" && term.names.length === 0 || term.type === "command" && term.name === "" || term.type === "argument" && term.metavar.length === 0 || term.type === "literal" && term.value === "";
+}
+function projectTerms(terms, isHidden) {
+	let visible = false;
+	let omissible = true;
+	let hidesRequired = false;
+	for (const term of terms) {
+		const projection = projectTerm(term, isHidden);
+		hidesRequired ||= projection.hidesRequired;
+		if (!projection.visible) continue;
+		visible = true;
+		omissible &&= projection.omissible;
+	}
+	return {
+		visible,
+		omissible,
+		hidesRequired
+	};
+}
+/**
+* Projects an alternative of an exclusive term.  Display filtering drops an
+* alternative whose leading command is hidden as a whole, trailing terms
+* included.
+*/
+function projectBranch(branch, isHidden) {
+	const first = branch[0];
+	if (first?.type === "command" && isHidden(first.hidden)) return {
+		...EMPTY,
+		hidesRequired: true
+	};
+	return projectTerms(branch, isHidden);
+}
+function projectTerm(term, isHidden) {
+	if (isHiddenLeaf(term, isHidden)) return {
+		...EMPTY,
+		hidesRequired: term.type !== "passthrough"
+	};
+	if (isDegenerateLeaf(term)) return EMPTY;
+	switch (term.type) {
+		case "argument":
+		case "option":
+		case "command":
+		case "literal": return {
+			visible: true,
+			omissible: false,
+			hidesRequired: false
+		};
+		case "passthrough":
+		case "ellipsis": return {
+			visible: true,
+			omissible: true,
+			hidesRequired: false
+		};
+		case "optional": {
+			const inner = projectTerms(term.terms, isHidden);
+			return {
+				...inner,
+				omissible: true,
+				hidesRequired: false
+			};
+		}
+		case "sequence": return projectTerms(term.terms, isHidden);
+		case "multiple": {
+			const inner = projectTerms(term.terms, isHidden);
+			return {
+				...inner,
+				omissible: term.min < 1 || inner.omissible,
+				hidesRequired: term.min > 0 && inner.hidesRequired
+			};
+		}
+		case "exclusive": {
+			let visible = false;
+			let omissible = false;
+			let hidesRequired = false;
+			for (const branch of term.terms) {
+				const projection = projectBranch(branch, isHidden);
+				hidesRequired ||= projection.hidesRequired;
+				if (!projection.visible) continue;
+				visible = true;
+				omissible ||= projection.omissible;
+			}
+			return {
+				visible,
+				omissible,
+				hidesRequired
+			};
+		}
+	}
+}
+/**
+* Returns the terms `X` when the visible part of `terms` is exactly
+* `optional(X)`, possibly nested, with a required `X`, and no required term
+* was hidden.
+*/
+function unwrapSingleOptional(terms, isHidden) {
+	if (projectTerms(terms, isHidden).hidesRequired) return void 0;
+	const visible = terms.filter((t) => projectTerm(t, isHidden).visible);
+	if (visible.length !== 1) return void 0;
+	const [only] = visible;
+	if (only.type !== "optional") return void 0;
+	const inner = projectTerms(only.terms, isHidden);
+	if (!inner.visible || inner.hidesRequired) return void 0;
+	if (inner.omissible) return unwrapSingleOptional(only.terms, isHidden);
+	return only.terms;
+}
+function resolveTerms(terms, isHidden) {
+	return terms.map((term) => resolveTerm(term, isHidden));
+}
+function resolveTerm(term, isHidden) {
+	switch (term.type) {
+		case "optional": return {
+			type: "optional",
+			terms: resolveTerms(term.terms, isHidden)
+		};
+		case "sequence": return {
+			type: "sequence",
+			terms: resolveTerms(term.terms, isHidden)
+		};
+		case "multiple": {
+			const terms = resolveTerms(term.terms, isHidden);
+			const resolved = {
+				type: "multiple",
+				terms,
+				min: term.min
+			};
+			if (term.acceptsEmpty == null) return resolved;
+			const projection = projectTerm(resolved, isHidden);
+			if (!projection.visible || projection.omissible === term.acceptsEmpty) return resolved;
+			if (term.acceptsEmpty) return {
+				type: "optional",
+				terms: [resolved]
+			};
+			if (term.min < 1) return resolved;
+			const required = unwrapSingleOptional(terms, isHidden);
+			return required == null ? resolved : {
+				...resolved,
+				terms: required
+			};
+		}
+		case "exclusive": {
+			const branches = term.terms.map((branch) => resolveTerms(branch, isHidden));
+			const resolved = {
+				type: "exclusive",
+				terms: branches
+			};
+			if (term.acceptsEmpty == null) return resolved;
+			const projection = projectTerm(resolved, isHidden);
+			if (!projection.visible || projection.omissible === term.acceptsEmpty) return resolved;
+			if (term.acceptsEmpty) {
+				const visible = branches.filter((branch) => projectBranch(branch, isHidden).visible);
+				return {
+					type: "optional",
+					terms: visible.length === 1 ? visible[0] : [{
+						type: "exclusive",
+						terms: visible
+					}]
+				};
+			}
+			const required = [];
+			for (const branch of branches) {
+				const branchProjection = projectBranch(branch, isHidden);
+				if (!branchProjection.visible || !branchProjection.omissible) {
+					required.push(branch);
+					continue;
+				}
+				const unwrapped = unwrapSingleOptional(branch, isHidden);
+				if (unwrapped == null) return resolved;
+				required.push(unwrapped);
+			}
+			return {
+				type: "exclusive",
+				terms: required
+			};
+		}
+		default: return term;
+	}
+}
+/**
+* Rewrites a usage so that plain synopsis notation reflects the recorded
+* empty-input behavior of its groups.
+*
+* Each `exclusive` or `multiple` term that records `acceptsEmpty` is drawn
+* as omissible exactly when its parser accepts an empty argument list,
+* using only exact local rewrites: a group that should be omissible is
+* wrapped in an optional term, and a group that should be required has
+* `optional(X)` alternatives or repeated items replaced by `X`.  A group
+* whose visible terms cannot be drawn that way keeps its declared notation.
+* Enclosing groups are resolved after their children, so their constraints
+* take precedence.
+*
+* The result records no `acceptsEmpty` fields, so resolving it again
+* returns an equal usage.  Hidden terms are kept; callers filter them for
+* display afterwards.
+* @param usage The usage to resolve.
+* @param isHidden Reports whether a term is hidden in the rendering context.
+* @returns The resolved usage.
+* @internal
+*/
+function resolveUsageForDisplay(usage, isHidden) {
+	return resolveTerms(usage, isHidden);
+}
+/**
+* Removes every `acceptsEmpty` record from a usage without changing how it
+* is drawn otherwise.
+* @param usage The usage to copy.
+* @returns The usage without records.
+* @internal
+*/
+function forgetEmptyInput(usage) {
+	return usage.map(forgetEmptyInputTerm);
+}
+function forgetEmptyInputTerm(term) {
+	switch (term.type) {
+		case "optional": return {
+			type: "optional",
+			terms: forgetEmptyInput(term.terms)
+		};
+		case "sequence": return {
+			type: "sequence",
+			terms: forgetEmptyInput(term.terms)
+		};
+		case "multiple": return {
+			type: "multiple",
+			terms: forgetEmptyInput(term.terms),
+			min: term.min
+		};
+		case "exclusive": return {
+			type: "exclusive",
+			terms: term.terms.map(forgetEmptyInput)
+		};
+		default: return term;
+	}
+}
+
+//#endregion
+export { forgetEmptyInput, resolveUsageForDisplay };

package/dist/modifiers.cjs

@@ -4,6 +4,7 @@ const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 const require_dependency_runtime = require('./dependency-runtime.cjs');
 const require_internal_parser = require('./internal/parser.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
+const require_empty_input = require('./internal/empty-input.cjs');
 const require_execution_context = require('./execution-context.cjs');
 const require_short_option = require('./short-option.cjs');
 const require_passthrough = require('./internal/passthrough.cjs');
@@ -27,6 +28,14 @@ function isUnstartedMultipleItemState(state, originalState) {
 	const unwrappedOriginalState = unwrapMultipleItemState(originalState);
 	return unwrappedState.value === unwrappedOriginalState.value && (unwrappedState.viaBoundCliWrapper || unwrappedOriginalState.viaBoundCliWrapper || unwrappedOriginalState.value != null && typeof unwrappedOriginalState.value === "object");
 }
+/**
+* Returns whether an optional-style wrapper around the given parser is known
+* to complete successfully from its initial state without delegating to a
+* source binding or a deferred completion.
+*/
+function completesOptionalLikeFallback(parser) {
+	return typeof parser.shouldDeferCompletion !== "function" && parser.dependencyMetadata?.source == null && parser[require_internal_parser.unmatchedNonCliDependencySourceStateMarker] !== true ? true : void 0;
+}
 function isBoundCliWrapperState(state) {
 	return state != null && typeof state === "object" && Object.hasOwn(state, "hasCliValue") && typeof state.hasCliValue === "boolean" && (Object.hasOwn(state, "cliState") || state.hasCliValue === false);
 }
@@ -485,7 +494,9 @@ function optional(parser) {
 		state: deriveOptionalInnerParseState(state, parser)
 	}]);
 	require_passthrough.defineKnownCompletionLookup(optionalParser, (state) => require_passthrough.getKnownCompletion(parser, deriveOptionalInnerParseState(state, parser)));
-	return fluent(require_short_option.scopeParser(optionalParser, require_short_option.combinedOptionScope([parser])));
+	const scopedOptionalParser = require_short_option.scopeParser(optionalParser, require_short_option.combinedOptionScope([parser]));
+	require_empty_input.defineEmptyInputFacts(scopedOptionalParser, require_empty_input.optionalLikeFacts(require_empty_input.getEmptyInputFacts(parser), parser.initialState, completesOptionalLikeFallback(parser)));
+	return fluent(scopedOptionalParser);
 }
 /**
 * Error type for structured error messages in {@link withDefault} default value callbacks.
@@ -741,7 +752,9 @@ function withDefault(parser, defaultValue, options) {
 		state: deriveOptionalInnerParseState(state, parser)
 	}]);
 	require_passthrough.defineKnownCompletionLookup(withDefaultParser, (state) => require_passthrough.getKnownCompletion(parser, deriveOptionalInnerParseState(state, parser)));
-	return fluent(require_short_option.scopeParser(withDefaultParser, require_short_option.combinedOptionScope([parser])));
+	const scopedWithDefaultParser = require_short_option.scopeParser(withDefaultParser, require_short_option.combinedOptionScope([parser]));
+	require_empty_input.defineEmptyInputFacts(scopedWithDefaultParser, require_empty_input.optionalLikeFacts(require_empty_input.getEmptyInputFacts(parser), parser.initialState, typeof defaultValue === "function" ? void 0 : completesOptionalLikeFallback(parser)));
+	return fluent(scopedWithDefaultParser);
 }
 /**
 * Creates a parser that transforms the result value of another parser using
@@ -930,6 +943,13 @@ function map(parser, transform) {
 		if (composed != null) mappedParser.dependencyMetadata = composed;
 	}
 	require_dependency_runtime.defineForwardedEffectfulSchedulingNodes(mappedParser, parser);
+	const innerFacts = require_empty_input.getEmptyInputFacts(parser);
+	require_empty_input.defineEmptyInputFacts(mappedParser, {
+		...innerFacts.step == null ? {} : { step: innerFacts.step },
+		...innerFacts.next == null ? {} : { next: innerFacts.next },
+		...innerFacts.afterStep === false ? { afterStep: false } : {},
+		...innerFacts.fromInitial === false ? { fromInitial: false } : {}
+	});
 	return fluent(mappedParser);
 }
 const deferredValueBrand = Symbol.for("@optique/core/deferredValue");
@@ -1104,6 +1124,17 @@ function isDeferredValue(value) {
 	return typeof value === "function" && value[deferredValueBrand] === true;
 }
 /**
+* Computes the empty-input facts of `multiple(parser, options)`.
+*/
+function getMultipleEmptyInputFacts(parser, options) {
+	const min = options.min ?? 0;
+	if (options.max != null || !Number.isInteger(min) || min < 0) return {};
+	const facts = require_empty_input.getEmptyInputFacts(parser);
+	const childInitialState = parser.initialState;
+	const retainsItem = facts.step === "success" || facts.step === "provisional" ? facts.next == null ? void 0 : !isUnstartedMultipleItemState(require_empty_input.resolveEmptyStepState(facts.next, childInitialState), childInitialState) : false;
+	return require_empty_input.multipleFacts(facts, retainsItem, childInitialState, min);
+}
+/**
 * Creates a parser that allows multiple occurrences of a given parser.
 * This parser can be used to parse multiple values of the same type,
 * such as multiple command-line arguments or options.
@@ -1380,6 +1411,9 @@ function multiple(parser, options = {}) {
 			consumed: result.consumed
 		};
 	};
+	const initialState = [];
+	const emptyInputFacts = getMultipleEmptyInputFacts(parser, options);
+	const acceptsEmpty = require_empty_input.acceptsEmptyInput(emptyInputFacts);
 	const resultParser = {
 		mode: parser.mode,
 		$valueType: [],
@@ -1388,11 +1422,12 @@ function multiple(parser, options = {}) {
 		usage: [{
 			type: "multiple",
 			terms: parser.usage,
-			min
+			min,
+			...acceptsEmpty == null ? {} : { acceptsEmpty }
 		}],
 		leadingNames: parser.leadingNames,
 		acceptingAnyToken: min > 0 && (parser.acceptingAnyToken ?? false),
-		initialState: [],
+		initialState,
 		canSkip(state, exec) {
 			if (state.length < min) return false;
 			const currentItemState = state.at(-1);
@@ -1748,7 +1783,9 @@ function multiple(parser, options = {}) {
 		parser,
 		state: unwrapInjectedWrapper(item.state)
 	})));
-	return fluent(require_short_option.scopeParser(resultParser, require_short_option.repeatedOptionScope(parser)));
+	const scopedResultParser = require_short_option.scopeParser(resultParser, require_short_option.repeatedOptionScope(parser));
+	require_empty_input.defineEmptyInputFacts(scopedResultParser, emptyInputFacts);
+	return fluent(scopedResultParser);
 }
 /**
 * Creates a parser that requires the wrapped parser to consume at least one
@@ -1888,7 +1925,13 @@ function nonEmpty(parser) {
 		parser,
 		state
 	}]);
-	return fluent(require_short_option.scopeParser(nonEmptyParser, require_short_option.combinedOptionScope([parser])));
+	const scopedNonEmptyParser = require_short_option.scopeParser(nonEmptyParser, require_short_option.combinedOptionScope([parser]));
+	const innerFacts = require_empty_input.getEmptyInputFacts(parser);
+	require_empty_input.defineEmptyInputFacts(scopedNonEmptyParser, {
+		step: "failure",
+		...innerFacts.fromInitial == null ? {} : { fromInitial: innerFacts.fromInitial }
+	});
+	return fluent(scopedNonEmptyParser);
 }
 const fluentParserMarker = Symbol.for("@optique/core/fluent");
 /**

package/dist/modifiers.js

@@ -4,6 +4,7 @@ import { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode } fro
 import { defineForwardedEffectfulSchedulingNodes } from "./dependency-runtime.js";
 import { defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingOnlyAnnotationCompletionParser, getOwnParseLanes, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { getDelegatedAnnotationState, hasDelegatedAnnotationCarrier, isAnnotationWrappedInitialState, normalizeDelegatedAnnotationState, normalizeNestedDelegatedAnnotationState } from "./annotation-state.js";
+import { acceptsEmptyInput, defineEmptyInputFacts, getEmptyInputFacts, multipleFacts, optionalLikeFacts, resolveEmptyStepState } from "./internal/empty-input.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
 import { combinedOptionScope, repeatedOptionScope, scopeParser } from "./short-option.js";
 import { defineKnownCompletionLookup, defineReachableChildren, getKnownCompletion } from "./internal/passthrough.js";
@@ -27,6 +28,14 @@ function isUnstartedMultipleItemState(state, originalState) {
 	const unwrappedOriginalState = unwrapMultipleItemState(originalState);
 	return unwrappedState.value === unwrappedOriginalState.value && (unwrappedState.viaBoundCliWrapper || unwrappedOriginalState.viaBoundCliWrapper || unwrappedOriginalState.value != null && typeof unwrappedOriginalState.value === "object");
 }
+/**
+* Returns whether an optional-style wrapper around the given parser is known
+* to complete successfully from its initial state without delegating to a
+* source binding or a deferred completion.
+*/
+function completesOptionalLikeFallback(parser) {
+	return typeof parser.shouldDeferCompletion !== "function" && parser.dependencyMetadata?.source == null && parser[unmatchedNonCliDependencySourceStateMarker] !== true ? true : void 0;
+}
 function isBoundCliWrapperState(state) {
 	return state != null && typeof state === "object" && Object.hasOwn(state, "hasCliValue") && typeof state.hasCliValue === "boolean" && (Object.hasOwn(state, "cliState") || state.hasCliValue === false);
 }
@@ -485,7 +494,9 @@ function optional(parser) {
 		state: deriveOptionalInnerParseState(state, parser)
 	}]);
 	defineKnownCompletionLookup(optionalParser, (state) => getKnownCompletion(parser, deriveOptionalInnerParseState(state, parser)));
-	return fluent(scopeParser(optionalParser, combinedOptionScope([parser])));
+	const scopedOptionalParser = scopeParser(optionalParser, combinedOptionScope([parser]));
+	defineEmptyInputFacts(scopedOptionalParser, optionalLikeFacts(getEmptyInputFacts(parser), parser.initialState, completesOptionalLikeFallback(parser)));
+	return fluent(scopedOptionalParser);
 }
 /**
 * Error type for structured error messages in {@link withDefault} default value callbacks.
@@ -741,7 +752,9 @@ function withDefault(parser, defaultValue, options) {
 		state: deriveOptionalInnerParseState(state, parser)
 	}]);
 	defineKnownCompletionLookup(withDefaultParser, (state) => getKnownCompletion(parser, deriveOptionalInnerParseState(state, parser)));
-	return fluent(scopeParser(withDefaultParser, combinedOptionScope([parser])));
+	const scopedWithDefaultParser = scopeParser(withDefaultParser, combinedOptionScope([parser]));
+	defineEmptyInputFacts(scopedWithDefaultParser, optionalLikeFacts(getEmptyInputFacts(parser), parser.initialState, typeof defaultValue === "function" ? void 0 : completesOptionalLikeFallback(parser)));
+	return fluent(scopedWithDefaultParser);
 }
 /**
 * Creates a parser that transforms the result value of another parser using
@@ -930,6 +943,13 @@ function map(parser, transform) {
 		if (composed != null) mappedParser.dependencyMetadata = composed;
 	}
 	defineForwardedEffectfulSchedulingNodes(mappedParser, parser);
+	const innerFacts = getEmptyInputFacts(parser);
+	defineEmptyInputFacts(mappedParser, {
+		...innerFacts.step == null ? {} : { step: innerFacts.step },
+		...innerFacts.next == null ? {} : { next: innerFacts.next },
+		...innerFacts.afterStep === false ? { afterStep: false } : {},
+		...innerFacts.fromInitial === false ? { fromInitial: false } : {}
+	});
 	return fluent(mappedParser);
 }
 const deferredValueBrand = Symbol.for("@optique/core/deferredValue");
@@ -1104,6 +1124,17 @@ function isDeferredValue(value) {
 	return typeof value === "function" && value[deferredValueBrand] === true;
 }
 /**
+* Computes the empty-input facts of `multiple(parser, options)`.
+*/
+function getMultipleEmptyInputFacts(parser, options) {
+	const min = options.min ?? 0;
+	if (options.max != null || !Number.isInteger(min) || min < 0) return {};
+	const facts = getEmptyInputFacts(parser);
+	const childInitialState = parser.initialState;
+	const retainsItem = facts.step === "success" || facts.step === "provisional" ? facts.next == null ? void 0 : !isUnstartedMultipleItemState(resolveEmptyStepState(facts.next, childInitialState), childInitialState) : false;
+	return multipleFacts(facts, retainsItem, childInitialState, min);
+}
+/**
 * Creates a parser that allows multiple occurrences of a given parser.
 * This parser can be used to parse multiple values of the same type,
 * such as multiple command-line arguments or options.
@@ -1380,6 +1411,9 @@ function multiple(parser, options = {}) {
 			consumed: result.consumed
 		};
 	};
+	const initialState = [];
+	const emptyInputFacts = getMultipleEmptyInputFacts(parser, options);
+	const acceptsEmpty = acceptsEmptyInput(emptyInputFacts);
 	const resultParser = {
 		mode: parser.mode,
 		$valueType: [],
@@ -1388,11 +1422,12 @@ function multiple(parser, options = {}) {
 		usage: [{
 			type: "multiple",
 			terms: parser.usage,
-			min
+			min,
+			...acceptsEmpty == null ? {} : { acceptsEmpty }
 		}],
 		leadingNames: parser.leadingNames,
 		acceptingAnyToken: min > 0 && (parser.acceptingAnyToken ?? false),
-		initialState: [],
+		initialState,
 		canSkip(state, exec) {
 			if (state.length < min) return false;
 			const currentItemState = state.at(-1);
@@ -1748,7 +1783,9 @@ function multiple(parser, options = {}) {
 		parser,
 		state: unwrapInjectedWrapper(item.state)
 	})));
-	return fluent(scopeParser(resultParser, repeatedOptionScope(parser)));
+	const scopedResultParser = scopeParser(resultParser, repeatedOptionScope(parser));
+	defineEmptyInputFacts(scopedResultParser, emptyInputFacts);
+	return fluent(scopedResultParser);
 }
 /**
 * Creates a parser that requires the wrapped parser to consume at least one
@@ -1888,7 +1925,13 @@ function nonEmpty(parser) {
 		parser,
 		state
 	}]);
-	return fluent(scopeParser(nonEmptyParser, combinedOptionScope([parser])));
+	const scopedNonEmptyParser = scopeParser(nonEmptyParser, combinedOptionScope([parser]));
+	const innerFacts = getEmptyInputFacts(parser);
+	defineEmptyInputFacts(scopedNonEmptyParser, {
+		step: "failure",
+		...innerFacts.fromInitial == null ? {} : { fromInitial: innerFacts.fromInitial }
+	});
+	return fluent(scopedNonEmptyParser);
 }
 const fluentParserMarker = Symbol.for("@optique/core/fluent");
 /**

package/dist/primitives.cjs

@@ -6,6 +6,7 @@ const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 const require_internal_dependency = require('./internal/dependency.cjs');
 const require_dependency_runtime = require('./dependency-runtime.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
+const require_empty_input = require('./internal/empty-input.cjs');
 const require_execution_context = require('./execution-context.cjs');
 const require_usage_internals = require('./usage-internals.cjs');
 const require_short_option = require('./short-option.cjs');
@@ -174,6 +175,12 @@ function constant(value) {
 		}
 	};
 	require_passthrough.defineKnownCompletion(result, (state) => require_annotation_state.normalizeInjectedAnnotationState(state));
+	require_empty_input.defineEmptyInputFacts(result, {
+		step: "success",
+		next: require_empty_input.UNCHANGED,
+		afterStep: true,
+		fromInitial: true
+	});
 	Object.defineProperty(result, "placeholder", {
 		value,
 		configurable: true,
@@ -202,7 +209,7 @@ function constant(value) {
 * @since 1.0.0
 */
 function fail() {
-	return require_modifiers.fluent({
+	const result = {
 		$valueType: [],
 		$stateType: [],
 		mode: "sync",
@@ -236,7 +243,9 @@ function fail() {
 				sourceOnly: true
 			};
 		}
-	});
+	};
+	require_empty_input.defineEmptyInputFacts(result, require_empty_input.failingStepFacts(false));
+	return require_modifiers.fluent(result);
 }
 /**
 * Internal helper to get suggestions from a value parser, using dependency values
@@ -794,6 +803,7 @@ function option(...args) {
 		configurable: true,
 		enumerable: false
 	});
+	else require_empty_input.defineEmptyInputFacts(result, require_empty_input.failingStepFacts(valueParser == null));
 	return require_modifiers.fluent(result);
 }
 /**
@@ -983,6 +993,7 @@ function flag(...args) {
 		enumerable: false,
 		writable: false
 	});
+	require_empty_input.defineEmptyInputFacts(result, require_empty_input.failingStepFacts(false));
 	return require_modifiers.fluent(result);
 }
 function normalizeNegatableFlagNameList(names) {
@@ -1395,6 +1406,7 @@ function argument(valueParser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	else require_empty_input.defineEmptyInputFacts(result, require_empty_input.failingStepFacts(false));
 	return require_modifiers.fluent(result);
 }
 function normalizeCommandState(state) {
@@ -1770,9 +1782,11 @@ function command(name, parser, options = {}) {
 		const child = selectChild(state);
 		return child == null ? [] : [child];
 	});
-	return require_modifiers.fluent(require_short_option.scopeParser(result, commandScope.source, (context) => {
+	const scoped = require_short_option.scopeParser(result, commandScope.source, (context) => {
 		if (normalizeCommandState(context.state) != null) commandScope.select(context, enteredScope);
-	}));
+	});
+	require_empty_input.defineEmptyInputFacts(scoped, require_empty_input.failingStepFacts(false));
+	return require_modifiers.fluent(scoped);
 }
 /**
 * Creates a parser that collects unrecognized options and passes them through.
@@ -1963,6 +1977,7 @@ function passThrough(options = {}) {
 		const accepts = format === "equalsOnly" ? equalsOptionPattern.test(token) : format === "nextToken" && optionPattern.test(token);
 		return accepts ? result.priority : void 0;
 	});
+	require_empty_input.defineEmptyInputFacts(result, require_empty_input.failingStepFacts(true));
 	return require_modifiers.fluent(result);
 }
 

package/dist/primitives.js

@@ -6,6 +6,7 @@ import { dispatchByMode, dispatchIterableByMode, wrapForMode } from "./internal/
 import { getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDerivedValueParser, suggestWithDependency } from "./internal/dependency.js";
 import { effectfulSchedulingNodesKey, exclusiveSourceScopeKey, includeSourceFailureChain, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, sourceCollectionExpansionKey } from "./dependency-runtime.js";
 import { getWrappedChildParseState, getWrappedChildState, isAnnotationWrappedInitialState, normalizeInjectedAnnotationState } from "./annotation-state.js";
+import { UNCHANGED, defineEmptyInputFacts, failingStepFacts } from "./internal/empty-input.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
 import { extractLeadingCommandNames } from "./usage-internals.js";
 import { attachedValuePrefix, combinedOptionScope, fullNameOwnsToken, prefixSuggestion, scopeParser, selectableOptionScope } from "./short-option.js";
@@ -174,6 +175,12 @@ function constant(value) {
 		}
 	};
 	defineKnownCompletion(result, (state) => normalizeInjectedAnnotationState(state));
+	defineEmptyInputFacts(result, {
+		step: "success",
+		next: UNCHANGED,
+		afterStep: true,
+		fromInitial: true
+	});
 	Object.defineProperty(result, "placeholder", {
 		value,
 		configurable: true,
@@ -202,7 +209,7 @@ function constant(value) {
 * @since 1.0.0
 */
 function fail() {
-	return fluent({
+	const result = {
 		$valueType: [],
 		$stateType: [],
 		mode: "sync",
@@ -236,7 +243,9 @@ function fail() {
 				sourceOnly: true
 			};
 		}
-	});
+	};
+	defineEmptyInputFacts(result, failingStepFacts(false));
+	return fluent(result);
 }
 /**
 * Internal helper to get suggestions from a value parser, using dependency values
@@ -794,6 +803,7 @@ function option(...args) {
 		configurable: true,
 		enumerable: false
 	});
+	else defineEmptyInputFacts(result, failingStepFacts(valueParser == null));
 	return fluent(result);
 }
 /**
@@ -983,6 +993,7 @@ function flag(...args) {
 		enumerable: false,
 		writable: false
 	});
+	defineEmptyInputFacts(result, failingStepFacts(false));
 	return fluent(result);
 }
 function normalizeNegatableFlagNameList(names) {
@@ -1395,6 +1406,7 @@ function argument(valueParser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	else defineEmptyInputFacts(result, failingStepFacts(false));
 	return fluent(result);
 }
 function normalizeCommandState(state) {
@@ -1770,9 +1782,11 @@ function command(name, parser, options = {}) {
 		const child = selectChild(state);
 		return child == null ? [] : [child];
 	});
-	return fluent(scopeParser(result, commandScope.source, (context) => {
+	const scoped = scopeParser(result, commandScope.source, (context) => {
 		if (normalizeCommandState(context.state) != null) commandScope.select(context, enteredScope);
-	}));
+	});
+	defineEmptyInputFacts(scoped, failingStepFacts(false));
+	return fluent(scoped);
 }
 /**
 * Creates a parser that collects unrecognized options and passes them through.
@@ -1963,6 +1977,7 @@ function passThrough(options = {}) {
 		const accepts = format === "equalsOnly" ? equalsOptionPattern.test(token) : format === "nextToken" && optionPattern.test(token);
 		return accepts ? result.priority : void 0;
 	});
+	defineEmptyInputFacts(result, failingStepFacts(true));
 	return fluent(result);
 }