@optique/core 1.4.0-dev.2683 → 1.4.0-dev.2709

package/dist/constructs.cjs

@@ -8,6 +8,7 @@ const require_internal_dependency = require('./internal/dependency.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_usage_internals = require('./usage-internals.cjs');
 const require_short_option = require('./short-option.cjs');
@@ -890,7 +891,8 @@ function applyHiddenToUsageTerm(term, hidden) {
 	if (term.type === "multiple") return {
 		type: "multiple",
 		terms: applyHiddenToUsage(term.terms, hidden),
-		min: term.min
+		min: term.min,
+		...term.acceptsEmpty == null ? {} : { acceptsEmpty: term.acceptsEmpty }
 	};
 	if (term.type === "sequence") return {
 		type: "sequence",
@@ -898,7 +900,8 @@ function applyHiddenToUsageTerm(term, hidden) {
 	};
 	if (term.type === "exclusive") return {
 		type: "exclusive",
-		terms: term.terms.map((u) => applyHiddenToUsage(u, hidden))
+		terms: term.terms.map((u) => applyHiddenToUsage(u, hidden)),
+		...term.acceptsEmpty == null ? {} : { acceptsEmpty: term.acceptsEmpty }
 	};
 	if (term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") return {
 		...term,
@@ -962,7 +965,7 @@ function isOptionRequiringValue(usage, token) {
 		} else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") {
 			if (traverse(term.terms)) return true;
 		} else if (term.type === "exclusive") {
-			for (const exclusiveUsage of term.terms) if (traverse(exclusiveUsage)) return true;
+			for (const exclusiveUsage$1 of term.terms) if (traverse(exclusiveUsage$1)) return true;
 		}
 		return false;
 	}
@@ -1202,6 +1205,28 @@ function preserveExclusiveStateAfterOptionsTerminator(context, result) {
 	};
 }
 /**
+* Describes the branches of an exclusive combinator for the empty-input
+* rules.
+*/
+function getExclusiveBranches(parsers) {
+	return parsers.map((parser) => ({
+		facts: require_empty_input.getEmptyInputFacts(parser),
+		matchesTokens: parser.leadingNames.size > 0 || parser.acceptingAnyToken
+	}));
+}
+/**
+* Builds the exclusive usage term of `or()` and `longestMatch()`, recording
+* whether the combinator accepts an empty argument list when known.
+*/
+function exclusiveUsage(parsers, facts) {
+	const acceptsEmpty = require_empty_input.acceptsEmptyInput(facts);
+	return [{
+		type: "exclusive",
+		terms: parsers.map((p) => p.usage),
+		...acceptsEmpty == null ? {} : { acceptsEmpty }
+	}];
+}
+/**
 * Creates a complete() method shared by or() and longestMatch().
 * @internal
 */
@@ -1914,15 +1939,13 @@ function or(...args) {
 		if (optionsTerminatorResult != null) return preserveExclusiveStateAfterOptionsTerminator(context, optionsTerminatorResult);
 		return error;
 	};
+	const emptyInputFacts = require_empty_input.orFacts(getExclusiveBranches(parsers));
 	const singleResult = {
 		mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		priority: Math.max(...parsers.map((p) => p.priority)),
-		usage: [{
-			type: "exclusive",
-			terms: parsers.map((p) => p.usage)
-		}],
+		usage: exclusiveUsage(parsers, emptyInputFacts),
 		leadingNames: unionLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState: void 0,
@@ -1984,7 +2007,7 @@ function or(...args) {
 	defineExclusiveSchedulingNodes(singleResult, parsers);
 	require_internal_parser.defineInheritedAnnotationParser(singleResult);
 	require_passthrough.defineReachableChildren(singleResult, parsers, (state) => selectExclusiveChildren(parsers, state, true));
-	return require_modifiers.fluent(require_short_option.scopeParser(singleResult, require_short_option.combinedOptionScope(parsers, parsers.map((_, index) => index))));
+	return require_modifiers.fluent(require_empty_input.withEmptyInputFacts(require_short_option.scopeParser(singleResult, require_short_option.combinedOptionScope(parsers, parsers.map((_, index) => index))), emptyInputFacts));
 }
 /**
 * @since 0.5.0
@@ -2162,15 +2185,13 @@ function createLongestMatch(...args) {
 		if (bestMatch != null) return commitLongestMatch(context, bestMatch, void 0, consumingFailure);
 		return error;
 	};
+	const emptyInputFacts = require_empty_input.longestMatchFacts(getExclusiveBranches(parsers));
 	const multiResult = {
 		mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		priority: Math.max(...parsers.map((p) => p.priority)),
-		usage: [{
-			type: "exclusive",
-			terms: parsers.map((p) => p.usage)
-		}],
+		usage: exclusiveUsage(parsers, emptyInputFacts),
 		leadingNames: unionLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState: void 0,
@@ -2230,7 +2251,7 @@ function createLongestMatch(...args) {
 	defineExclusiveSchedulingNodes(multiResult, parsers);
 	require_internal_parser.defineInheritedAnnotationParser(multiResult);
 	require_passthrough.defineReachableChildren(multiResult, parsers, (state) => selectExclusiveChildren(parsers, state, false));
-	return require_modifiers.fluent(require_short_option.scopeParser(multiResult, require_short_option.combinedOptionScope(parsers, parsers.map((_, index) => index))));
+	return require_modifiers.fluent(require_empty_input.withEmptyInputFacts(require_short_option.scopeParser(multiResult, require_short_option.combinedOptionScope(parsers, parsers.map((_, index) => index))), emptyInputFacts));
 }
 /**
 * Creates the initial parse error shared by object-like combinators.
@@ -3288,7 +3309,10 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			state: require_annotation_state.getWrappedChildParseState(state, getFieldState(field, parser), parser)
 		}));
 	});
-	return require_modifiers.fluent(require_short_option.scopeParser(objectParser, require_short_option.combinedOptionScope(parserPairs.map(([, p]) => p), parserPairs.map(([field]) => field)), void 0, true));
+	return require_modifiers.fluent(require_empty_input.withEmptyInputFacts(require_short_option.scopeParser(objectParser, require_short_option.combinedOptionScope(parserPairs.map(([, p]) => p), parserPairs.map(([field]) => field)), void 0, true), combinedMode === "sync" ? require_empty_input.objectFacts(parserPairs.map(([, p]) => ({
+		facts: require_empty_input.getEmptyInputFacts(p),
+		matchesTokens: p.leadingNames.size > 0 || p.acceptingAnyToken
+	})), parserPairs.map(([field]) => field)) : {}));
 }
 function isParserLike(value) {
 	return value != null && (typeof value === "object" || typeof value === "function") && "parse" in value && "$valueType" in value && "$stateType" in value;
@@ -4339,7 +4363,10 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		parser,
 		state: require_annotation_state.getWrappedChildParseState(state, state[index], parser)
 	})));
-	return require_modifiers.fluent(require_short_option.scopeParser(tupleParser, require_short_option.combinedOptionScope(parsers, parsers.map((_, index) => index))));
+	return require_modifiers.fluent(require_empty_input.withEmptyInputFacts(require_short_option.scopeParser(tupleParser, require_short_option.combinedOptionScope(parsers, parsers.map((_, index) => index))), require_empty_input.tupleFacts(parsers.map((p) => ({
+		facts: require_empty_input.getEmptyInputFacts(p),
+		matchesTokens: p.leadingNames.size > 0 || p.acceptingAnyToken
+	})))));
 }
 function seq(...rawArgs) {
 	const label = typeof rawArgs[0] === "string" ? rawArgs[0] : void 0;
@@ -6510,7 +6537,7 @@ function group(label, parser, options = {}) {
 		parser,
 		state
 	}]);
-	return require_modifiers.fluent(require_short_option.scopeParser(groupParser, require_short_option.combinedOptionScope([parser])));
+	return require_modifiers.fluent(require_empty_input.withEmptyInputFacts(require_short_option.scopeParser(groupParser, require_short_option.combinedOptionScope([parser])), require_empty_input.getEmptyInputFacts(parser)));
 }
 /**
 * Creates a conditional parser that selects different branch parsers based on

package/dist/constructs.js

@@ -8,6 +8,7 @@ import { createDependencySourceState, dependencyId, isDependencySourceState, isP
 import { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyRuntimeContext, effectfulSchedulingNodesKey, exclusiveSourceScopeKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, forkRuntimeForCommittedSubtree, getDefaultDependencySnapshot, guaranteedStaticSourceIdsKey, hasInactiveCompletion, isMatchedState, recordSourceScope, releaseUncollectedSourceValues, replaceCachedBarrierFailure, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey } from "./dependency-runtime.js";
 import { defineInheritedAnnotationParser, defineParseLanes, getOwnParseLanes, getParserSuggestRuntimeNodes, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { annotationViewTargets, getWrappedChildParseState, getWrappedChildState, reconcileObjectChildState, unwrapAnnotationView } from "./annotation-state.js";
+import { acceptsEmptyInput, getEmptyInputFacts, longestMatchFacts, objectFacts, orFacts, tupleFacts, withEmptyInputFacts } from "./internal/empty-input.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
 import { collectLeadingCandidates } from "./usage-internals.js";
 import { adoptOptionScope, combinedOptionScope, conditionalOptionScope, forkOptionScope, restoreOptionScope, scopeParser, selectableOptionScope, withOptionScope, withParserOptionScope } from "./short-option.js";
@@ -890,7 +891,8 @@ function applyHiddenToUsageTerm(term, hidden) {
 	if (term.type === "multiple") return {
 		type: "multiple",
 		terms: applyHiddenToUsage(term.terms, hidden),
-		min: term.min
+		min: term.min,
+		...term.acceptsEmpty == null ? {} : { acceptsEmpty: term.acceptsEmpty }
 	};
 	if (term.type === "sequence") return {
 		type: "sequence",
@@ -898,7 +900,8 @@ function applyHiddenToUsageTerm(term, hidden) {
 	};
 	if (term.type === "exclusive") return {
 		type: "exclusive",
-		terms: term.terms.map((u) => applyHiddenToUsage(u, hidden))
+		terms: term.terms.map((u) => applyHiddenToUsage(u, hidden)),
+		...term.acceptsEmpty == null ? {} : { acceptsEmpty: term.acceptsEmpty }
 	};
 	if (term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") return {
 		...term,
@@ -962,7 +965,7 @@ function isOptionRequiringValue(usage, token) {
 		} else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") {
 			if (traverse(term.terms)) return true;
 		} else if (term.type === "exclusive") {
-			for (const exclusiveUsage of term.terms) if (traverse(exclusiveUsage)) return true;
+			for (const exclusiveUsage$1 of term.terms) if (traverse(exclusiveUsage$1)) return true;
 		}
 		return false;
 	}
@@ -1202,6 +1205,28 @@ function preserveExclusiveStateAfterOptionsTerminator(context, result) {
 	};
 }
 /**
+* Describes the branches of an exclusive combinator for the empty-input
+* rules.
+*/
+function getExclusiveBranches(parsers) {
+	return parsers.map((parser) => ({
+		facts: getEmptyInputFacts(parser),
+		matchesTokens: parser.leadingNames.size > 0 || parser.acceptingAnyToken
+	}));
+}
+/**
+* Builds the exclusive usage term of `or()` and `longestMatch()`, recording
+* whether the combinator accepts an empty argument list when known.
+*/
+function exclusiveUsage(parsers, facts) {
+	const acceptsEmpty = acceptsEmptyInput(facts);
+	return [{
+		type: "exclusive",
+		terms: parsers.map((p) => p.usage),
+		...acceptsEmpty == null ? {} : { acceptsEmpty }
+	}];
+}
+/**
 * Creates a complete() method shared by or() and longestMatch().
 * @internal
 */
@@ -1914,15 +1939,13 @@ function or(...args) {
 		if (optionsTerminatorResult != null) return preserveExclusiveStateAfterOptionsTerminator(context, optionsTerminatorResult);
 		return error;
 	};
+	const emptyInputFacts = orFacts(getExclusiveBranches(parsers));
 	const singleResult = {
 		mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		priority: Math.max(...parsers.map((p) => p.priority)),
-		usage: [{
-			type: "exclusive",
-			terms: parsers.map((p) => p.usage)
-		}],
+		usage: exclusiveUsage(parsers, emptyInputFacts),
 		leadingNames: unionLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState: void 0,
@@ -1984,7 +2007,7 @@ function or(...args) {
 	defineExclusiveSchedulingNodes(singleResult, parsers);
 	defineInheritedAnnotationParser(singleResult);
 	defineReachableChildren(singleResult, parsers, (state) => selectExclusiveChildren(parsers, state, true));
-	return fluent(scopeParser(singleResult, combinedOptionScope(parsers, parsers.map((_, index) => index))));
+	return fluent(withEmptyInputFacts(scopeParser(singleResult, combinedOptionScope(parsers, parsers.map((_, index) => index))), emptyInputFacts));
 }
 /**
 * @since 0.5.0
@@ -2162,15 +2185,13 @@ function createLongestMatch(...args) {
 		if (bestMatch != null) return commitLongestMatch(context, bestMatch, void 0, consumingFailure);
 		return error;
 	};
+	const emptyInputFacts = longestMatchFacts(getExclusiveBranches(parsers));
 	const multiResult = {
 		mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		priority: Math.max(...parsers.map((p) => p.priority)),
-		usage: [{
-			type: "exclusive",
-			terms: parsers.map((p) => p.usage)
-		}],
+		usage: exclusiveUsage(parsers, emptyInputFacts),
 		leadingNames: unionLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState: void 0,
@@ -2230,7 +2251,7 @@ function createLongestMatch(...args) {
 	defineExclusiveSchedulingNodes(multiResult, parsers);
 	defineInheritedAnnotationParser(multiResult);
 	defineReachableChildren(multiResult, parsers, (state) => selectExclusiveChildren(parsers, state, false));
-	return fluent(scopeParser(multiResult, combinedOptionScope(parsers, parsers.map((_, index) => index))));
+	return fluent(withEmptyInputFacts(scopeParser(multiResult, combinedOptionScope(parsers, parsers.map((_, index) => index))), emptyInputFacts));
 }
 /**
 * Creates the initial parse error shared by object-like combinators.
@@ -3288,7 +3309,10 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			state: getWrappedChildParseState(state, getFieldState(field, parser), parser)
 		}));
 	});
-	return fluent(scopeParser(objectParser, combinedOptionScope(parserPairs.map(([, p]) => p), parserPairs.map(([field]) => field)), void 0, true));
+	return fluent(withEmptyInputFacts(scopeParser(objectParser, combinedOptionScope(parserPairs.map(([, p]) => p), parserPairs.map(([field]) => field)), void 0, true), combinedMode === "sync" ? objectFacts(parserPairs.map(([, p]) => ({
+		facts: getEmptyInputFacts(p),
+		matchesTokens: p.leadingNames.size > 0 || p.acceptingAnyToken
+	})), parserPairs.map(([field]) => field)) : {}));
 }
 function isParserLike(value) {
 	return value != null && (typeof value === "object" || typeof value === "function") && "parse" in value && "$valueType" in value && "$stateType" in value;
@@ -4339,7 +4363,10 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		parser,
 		state: getWrappedChildParseState(state, state[index], parser)
 	})));
-	return fluent(scopeParser(tupleParser, combinedOptionScope(parsers, parsers.map((_, index) => index))));
+	return fluent(withEmptyInputFacts(scopeParser(tupleParser, combinedOptionScope(parsers, parsers.map((_, index) => index))), tupleFacts(parsers.map((p) => ({
+		facts: getEmptyInputFacts(p),
+		matchesTokens: p.leadingNames.size > 0 || p.acceptingAnyToken
+	})))));
 }
 function seq(...rawArgs) {
 	const label = typeof rawArgs[0] === "string" ? rawArgs[0] : void 0;
@@ -6510,7 +6537,7 @@ function group(label, parser, options = {}) {
 		parser,
 		state
 	}]);
-	return fluent(scopeParser(groupParser, combinedOptionScope([parser])));
+	return fluent(withEmptyInputFacts(scopeParser(groupParser, combinedOptionScope([parser])), getEmptyInputFacts(parser)));
 }
 /**
 * Creates a conditional parser that selects different branch parsers based on

package/dist/doc.cjs

@@ -553,8 +553,16 @@ function formatDocPage(programName, page, options = {}) {
 				column: extraTermOffset
 			}).cursor;
 			const appendAnnotation = (content, layout, style, ambient, quotes) => {
-				const prefix = require_text_layout.placeText(layout.prefix, cursor, descColumnWidth, 1);
-				if (prefix.text !== layout.prefix) description += "\n";
+				let prefixText = layout.prefix;
+				let prefix = require_text_layout.placeText(prefixText, cursor, descColumnWidth, 1);
+				if (prefix.text !== layout.prefix) {
+					description += "\n";
+					prefixText = require_text_layout.trimLeadingSpace(layout.prefix);
+					prefix = require_text_layout.placeText(prefixText, {
+						line: "",
+						column: 0
+					});
+				}
 				const rendered = formatMessage(content, {
 					colors: options.colors ? { resetSuffix: style } : false,
 					quotes,
@@ -562,7 +570,7 @@ function formatDocPage(programName, page, options = {}) {
 					initialWidth: descColumnWidth != null || layout.prefixMetrics.lineCount > 1 ? prefix.cursor.column : void 0
 				}, ambient);
 				const suffix = require_text_layout.placeText(layout.suffix, require_text_layout.placeText(rendered, prefix.cursor).cursor, descColumnWidth);
-				const annotationText = `${layout.prefix}${rendered}${opaqueFormatter && options.colors ? style : ""}${suffix.text}`;
+				const annotationText = `${prefixText}${rendered}${opaqueFormatter && options.colors ? style : ""}${suffix.text}`;
 				description += options.colors ? `${style}${annotationText}${style ? "\x1B[0m" : ""}` : annotationText;
 				cursor = suffix.cursor;
 			};

package/dist/doc.js

@@ -1,5 +1,5 @@
 import { cacheTerminalTheme, renderTerminalTerm, styleCode } from "./terminal-internal.js";
-import { measureAnnotation, measureText, placeText, spaceAfterLabel } from "./text-layout.js";
+import { measureAnnotation, measureText, placeText, spaceAfterLabel, trimLeadingSpace } from "./text-layout.js";
 import { validateLabel, validateProgramName } from "./validate.js";
 import { cloneUsageTerm, formatUsage, formatUsageTerm, isDocHidden } from "./usage.js";
 import { hasAutomaticWidth, minimumUsageWidth, reportAutomaticWidth } from "./terminal-width.js";
@@ -553,8 +553,16 @@ function formatDocPage(programName, page, options = {}) {
 				column: extraTermOffset
 			}).cursor;
 			const appendAnnotation = (content, layout, style, ambient, quotes) => {
-				const prefix = placeText(layout.prefix, cursor, descColumnWidth, 1);
-				if (prefix.text !== layout.prefix) description += "\n";
+				let prefixText = layout.prefix;
+				let prefix = placeText(prefixText, cursor, descColumnWidth, 1);
+				if (prefix.text !== layout.prefix) {
+					description += "\n";
+					prefixText = trimLeadingSpace(layout.prefix);
+					prefix = placeText(prefixText, {
+						line: "",
+						column: 0
+					});
+				}
 				const rendered = formatMessage(content, {
 					colors: options.colors ? { resetSuffix: style } : false,
 					quotes,
@@ -562,7 +570,7 @@ function formatDocPage(programName, page, options = {}) {
 					initialWidth: descColumnWidth != null || layout.prefixMetrics.lineCount > 1 ? prefix.cursor.column : void 0
 				}, ambient);
 				const suffix = placeText(layout.suffix, placeText(rendered, prefix.cursor).cursor, descColumnWidth);
-				const annotationText = `${layout.prefix}${rendered}${opaqueFormatter && options.colors ? style : ""}${suffix.text}`;
+				const annotationText = `${prefixText}${rendered}${opaqueFormatter && options.colors ? style : ""}${suffix.text}`;
 				description += options.colors ? `${style}${annotationText}${style ? "\x1B[0m" : ""}` : annotationText;
 				cursor = suffix.cursor;
 			};