@optique/core 1.4.0-dev.2618 → 1.4.0-dev.2619

package/dist/short-option.js

@@ -0,0 +1,297 @@
+import { inheritAnnotations } from "./internal/annotations.js";
+import { extractOptionNames } from "./usage.js";
+import { mapModeValue } from "./internal/mode-dispatch.js";
+import { withChildExecPath } from "./execution-context.js";
+import { collectOptionNamesAtCurrentCommandDepth } from "./usage-internals.js";
+
+//#region src/short-option.ts
+const optionScopeKey = Symbol("optionScope");
+const optionPathKey = Symbol("optionScopePath");
+const scopeSourceKey = Symbol("optionScopeSource");
+const scopeLocations = /* @__PURE__ */ new WeakMap();
+const scopeBindings = /* @__PURE__ */ new WeakMap();
+function getScopeBindings(selections) {
+	let bindings = scopeBindings.get(selections);
+	if (bindings == null) {
+		bindings = /* @__PURE__ */ new WeakMap();
+		scopeBindings.set(selections, bindings);
+	}
+	return bindings;
+}
+function bindScope(source, path, selections) {
+	const boundScopes = getScopeBindings(selections);
+	let node = boundScopes.get(source);
+	if (node == null) {
+		node = {
+			children: /* @__PURE__ */ new Map(),
+			bound: (selections$1, arities, context) => source(selections$1, arities, context, [])
+		};
+		boundScopes.set(source, node);
+		scopeLocations.set(node.bound, []);
+	}
+	for (let i = 0; i < path.length; i++) {
+		let child = node.children.get(path[i]);
+		if (child == null) {
+			const occurrence = path.slice(0, i + 1);
+			child = {
+				children: /* @__PURE__ */ new Map(),
+				bound: (selections$1, arities, context) => source(selections$1, arities, context, occurrence)
+			};
+			node.children.set(path[i], child);
+			scopeLocations.set(child.bound, occurrence);
+		}
+		node = child;
+	}
+	return node.bound;
+}
+function scopePath(context) {
+	return context.exec?.path ?? context[optionPathKey] ?? [];
+}
+/** Tracks child occurrences even for contexts without execution metadata. @internal */
+function withOptionScopeChild(context, segment) {
+	return {
+		...context,
+		[optionPathKey]: [...scopePath(context), segment]
+	};
+}
+const primitiveScopes = /* @__PURE__ */ new WeakMap();
+function parserScope(parser) {
+	const declared = parser[scopeSourceKey];
+	if (declared != null) return declared;
+	let source = primitiveScopes.get(parser);
+	if (source == null) {
+		source = (_selections, arities) => {
+			if (arities != null) collectOptionNamesAtCurrentCommandDepth(parser.usage, arities, false);
+			return parser.leadingNames;
+		};
+		primitiveScopes.set(parser, source);
+	}
+	return source;
+}
+/** Preserves dynamic option ownership through a transparent wrapper. @internal */
+function inheritOptionScope(target, inner) {
+	Object.defineProperty(target, scopeSourceKey, {
+		value: parserScope(inner),
+		enumerable: true,
+		configurable: true
+	});
+}
+/** Combines declarations without flattening conditional ownership. @internal */
+function combinedOptionScope(parsers, segments) {
+	return (selections, arities, context, path = []) => new Set(parsers.flatMap((parser, index) => [...parserScope(parser)(selections, arities, context, segments == null ? path : [...path, segments[index]])]));
+}
+/** Evaluates repeated declarations at their actual item occurrences. @internal */
+function repeatedOptionScope(parser) {
+	return (selections, arities, context, path = []) => {
+		const indices = /* @__PURE__ */ new Set();
+		const collect = (location) => {
+			if (location != null && path.every((segment, index) => location[index] === segment)) {
+				const index = location[path.length];
+				if (typeof index === "number") indices.add(index);
+			}
+		};
+		for (const selected of selections.keys()) collect(scopeLocations.get(selected));
+		if (context != null) collect(scopePath(context));
+		if (indices.size === 0) indices.add(0);
+		return new Set([...indices].flatMap((index) => [...parserScope(parser)(selections, arities, context, [...path, index])]));
+	};
+}
+/** Tracks declarations after a command or discriminator routes input. @internal */
+function selectableOptionScope(initial) {
+	const source = (selections, arities, context, path = []) => (selections.get(bindScope(source, path, selections)) ?? initial)(selections, arities, context, path);
+	return {
+		source,
+		select(context, selected) {
+			const selections = context[optionScopeKey]?.selections;
+			if (selections == null) return;
+			selections.set(bindScope(source, scopePath(context), selections), selected);
+		}
+	};
+}
+/** Keeps selected conditional names distinct from sibling declarations. @internal */
+function conditionalOptionScope(discriminator, fallback, candidates = []) {
+	const scope = selectableOptionScope((selections, arities, context, path) => {
+		const canSkip = discriminator.canSkip?.(context == null ? discriminator.initialState : inheritAnnotations(context.state, discriminator.initialState), context?.exec == null ? void 0 : withChildExecPath({
+			...context.exec,
+			path: path ?? scopePath(context)
+		}, "_discriminator")) === true;
+		return combinedOptionScope([
+			discriminator,
+			...canSkip ? candidates : [],
+			...fallback == null ? [] : [fallback]
+		], [
+			"_discriminator",
+			...canSkip ? candidates.map(() => "_branch") : [],
+			...fallback == null ? [] : ["_branch"]
+		])(selections, arities, context, path);
+	});
+	return {
+		source: scope.source,
+		select(context, branch) {
+			scope.select(context, combinedOptionScope([discriminator, branch], ["_discriminator", "_branch"]));
+		}
+	};
+}
+/** Returns the names reachable in this parse scope. @internal */
+function getOptionScope(context) {
+	const scoped = context[optionScopeKey];
+	const names = scoped == null ? extractOptionNames(context.usage, true) : new Set([...scoped.names, ...[...scoped.sources].flatMap((source) => [...source(scoped.selections, void 0, context)])]);
+	return names;
+}
+/** Adds reachable names without consulting the flattened help tree. @internal */
+function withOptionScope(context, names) {
+	const inherited = context[optionScopeKey];
+	return {
+		...context,
+		[optionScopeKey]: {
+			names: new Set([...inherited?.names ?? [], ...names]),
+			sources: inherited?.sources ?? /* @__PURE__ */ new Set(),
+			selections: inherited?.selections ?? /* @__PURE__ */ new Map()
+		}
+	};
+}
+/** Adds a parser's owned declarations, retaining modifier metadata. @internal */
+function withParserOptionScope(context, parser, segment) {
+	const inherited = context[optionScopeKey];
+	const selections = inherited?.selections ?? /* @__PURE__ */ new Map();
+	return {
+		...context,
+		[optionScopeKey]: {
+			names: inherited?.names ?? /* @__PURE__ */ new Set(),
+			sources: new Set([...inherited?.sources ?? [], bindScope(parserScope(parser), segment == null ? scopePath(context) : [...scopePath(context), segment], selections)]),
+			selections
+		}
+	};
+}
+/** Isolates route selections while probing a competing branch. @internal */
+function forkOptionScope(context) {
+	const scoped = context[optionScopeKey];
+	if (scoped == null) return context;
+	const selections = new Map(scoped.selections);
+	scopeBindings.set(selections, getScopeBindings(scoped.selections));
+	return {
+		...context,
+		[optionScopeKey]: {
+			...scoped,
+			selections
+		}
+	};
+}
+/** Publishes winning routes without persisting temporary candidate names. @internal */
+function adoptOptionScope(context, next) {
+	const own = context[optionScopeKey];
+	const child = next[optionScopeKey];
+	if (own != null && child != null) for (const [source, selected] of child.selections) own.selections.set(source, selected);
+	return context;
+}
+/** Removes names reserved only for a speculative probe. @internal */
+function restoreOptionScope(next, parent) {
+	adoptOptionScope(parent, next);
+	const own = parent[optionScopeKey];
+	const child = next[optionScopeKey];
+	return own == null || child == null ? next : {
+		...next,
+		[optionScopeKey]: {
+			...child,
+			names: own.names,
+			selections: own.selections
+		}
+	};
+}
+/** Decorates construct entry points while retaining internal metadata. @internal */
+function scopeParser(parser, source = () => parser.leadingNames, prepare, isolate = false) {
+	const parse = parser.parse;
+	const suggest = parser.suggest;
+	Object.defineProperties(parser, {
+		[scopeSourceKey]: {
+			value: source,
+			enumerable: true
+		},
+		parse: {
+			enumerable: true,
+			configurable: true,
+			writable: true,
+			value: (context) => {
+				const scoped = withParserOptionScope(isolate ? forkOptionScope(context) : context, parser);
+				prepare?.(scoped);
+				return mapModeValue(parser.mode, parse.call(parser, scoped), (result) => {
+					if (!result.success) return result;
+					let next = result.next;
+					if (isolate) {
+						adoptOptionScope(context, next);
+						const parent = context[optionScopeKey];
+						const child = next[optionScopeKey];
+						if (parent != null && child != null) next = {
+							...next,
+							[optionScopeKey]: {
+								...child,
+								selections: parent.selections
+							}
+						};
+					}
+					return {
+						...result,
+						next: {
+							...next,
+							[optionPathKey]: scopePath(context)
+						}
+					};
+				});
+			}
+		},
+		suggest: {
+			enumerable: true,
+			configurable: true,
+			writable: true,
+			value: (context, prefix) => {
+				const scoped = withParserOptionScope(context, parser);
+				prepare?.(scoped);
+				return suggest.call(parser, scoped, prefix);
+			}
+		}
+	});
+	return parser;
+}
+/** Tests full-name ownership before splitting a short prefix. @internal */
+function fullNameOwnsToken(context, token) {
+	if (!/^-[^-]/.test(token)) return false;
+	for (const name of getOptionScope(context)) if (name.startsWith("-") && !name.startsWith("--") && name.length > 2 && !/^-[^-]$/u.test(name) && (token === name || token.startsWith(`${name}=`))) return true;
+	return false;
+}
+/** Finds the value part of an attached short-option completion. @internal */
+function attachedValuePrefix(context, prefix, optionNames) {
+	if (!/^-[^-]/.test(prefix)) return void 0;
+	const scope = getOptionScope(context);
+	const names = {
+		value: /* @__PURE__ */ new Set(),
+		flag: /* @__PURE__ */ new Set()
+	};
+	const scoped = context[optionScopeKey];
+	if (scoped == null) collectOptionNamesAtCurrentCommandDepth(context.usage, names, false);
+	else for (const source of scoped.sources) source(scoped.selections, names, context);
+	for (let index = 1; index < prefix.length;) {
+		const character = String.fromCodePoint(prefix.codePointAt(index));
+		const nextIndex = index + character.length;
+		const remainder = `-${prefix.slice(index)}`;
+		for (const name of scope) if (name.startsWith("-") && !name.startsWith("--") && name.length > 2 && !/^-[^-]$/u.test(name) && (name.startsWith(remainder) || remainder.startsWith(`${name}=`))) return void 0;
+		const short = `-${character}`;
+		if (optionNames.includes(short)) return {
+			head: prefix.slice(0, nextIndex),
+			value: prefix.slice(nextIndex)
+		};
+		if (!scope.has(short) || !names.flag.has(short) || names.value.has(short)) return void 0;
+		index = nextIndex;
+	}
+	return void 0;
+}
+/** Preserves the prefix when embedding value suggestions in one token. @internal */
+function prefixSuggestion(head, suggestion) {
+	return {
+		kind: "literal",
+		text: head + (suggestion.kind === "literal" ? suggestion.text : suggestion.pattern ?? ""),
+		...suggestion.description != null ? { description: suggestion.description } : {}
+	};
+}
+
+//#endregion
+export { adoptOptionScope, attachedValuePrefix, combinedOptionScope, conditionalOptionScope, forkOptionScope, fullNameOwnsToken, inheritOptionScope, prefixSuggestion, repeatedOptionScope, restoreOptionScope, scopeParser, selectableOptionScope, withOptionScope, withOptionScopeChild, withParserOptionScope };

package/dist/usage-internals.cjs

@@ -76,7 +76,80 @@ function extractLeadingCommandNames(usage) {
 	collectLeadingCandidates(usage, options, commands);
 	return commands;
 }
+/** Collects arities along an entered command path. @internal */
+function collectActiveOptionNames(usage, commandPath, names, fromExclusive, includeDirectAfterCommandOptions) {
+	if (commandPath.length === 0) {
+		collectOptionNamesAtCurrentCommandDepth(usage, names, false);
+		return;
+	}
+	const [commandName, ...rest] = commandPath;
+	for (let i = 0; i < usage.length; i++) {
+		const term = usage[i];
+		if (term.type === "command" && term.name === commandName) {
+			const remainingUsage = usage.slice(i + 1);
+			if (rest.length === 0) collectOptionNamesAtCurrentCommandDepth(remainingUsage, names, !fromExclusive && includeDirectAfterCommandOptions);
+			else collectActiveOptionNames(remainingUsage, rest, names, fromExclusive, includeDirectAfterCommandOptions);
+		} else if (term.type === "exclusive") for (const branch of term.terms) collectActiveOptionNames(branch, commandPath, names, true, includeDirectAfterCommandOptions);
+		else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") collectActiveOptionNames(term.terms, commandPath, names, fromExclusive, includeDirectAfterCommandOptions);
+	}
+}
+/** Collects arities without entering further commands. @internal */
+function collectOptionNamesAtCurrentCommandDepth(usage, names, afterMatchedCommand) {
+	for (const term of usage) if (collectOptionNamesAtCurrentCommandDepthFromTerm(term, names, afterMatchedCommand)) return;
+}
+function collectOptionNamesAtCurrentCommandDepthFromTerm(term, names, afterMatchedCommand) {
+	switch (term.type) {
+		case "command": return !afterMatchedCommand;
+		case "option":
+			if (term.metavar != null) for (const name of term.names) names.value.add(name);
+			else for (const name of term.names) names.flag.add(name);
+			return false;
+		case "optional":
+		case "multiple":
+		case "sequence":
+			collectOptionNamesAtCurrentCommandDepth(term.terms, names, afterMatchedCommand);
+			return false;
+		case "exclusive":
+			for (const branch of term.terms) collectOptionNamesAtCurrentCommandDepth(branch, names, false);
+			return false;
+		case "argument":
+		case "literal":
+		case "passthrough":
+		case "ellipsis": return false;
+	}
+}
+/** Collects scoped root arities across sibling commands. @internal */
+function collectRootOptionNames(usage, names, rootLeadingNames) {
+	for (const term of usage) collectRootOptionNamesFromTerm(term, names, rootLeadingNames);
+}
+function collectRootOptionNamesFromTerm(term, names, rootLeadingNames) {
+	switch (term.type) {
+		case "option":
+			for (const name of term.names) {
+				if (!rootLeadingNames.has(name)) continue;
+				if (term.metavar != null) names.value.add(name);
+				else names.flag.add(name);
+			}
+			return;
+		case "optional":
+		case "multiple":
+		case "sequence":
+			collectRootOptionNames(term.terms, names, rootLeadingNames);
+			return;
+		case "exclusive":
+			for (const branch of term.terms) collectRootOptionNames(branch, names, rootLeadingNames);
+			return;
+		case "argument":
+		case "command":
+		case "literal":
+		case "passthrough":
+		case "ellipsis": return;
+	}
+}
 
 //#endregion
+exports.collectActiveOptionNames = collectActiveOptionNames;
 exports.collectLeadingCandidates = collectLeadingCandidates;
+exports.collectOptionNamesAtCurrentCommandDepth = collectOptionNamesAtCurrentCommandDepth;
+exports.collectRootOptionNames = collectRootOptionNames;
 exports.extractLeadingCommandNames = extractLeadingCommandNames;

package/dist/usage-internals.js

@@ -76,6 +76,76 @@ function extractLeadingCommandNames(usage) {
 	collectLeadingCandidates(usage, options, commands);
 	return commands;
 }
+/** Collects arities along an entered command path. @internal */
+function collectActiveOptionNames(usage, commandPath, names, fromExclusive, includeDirectAfterCommandOptions) {
+	if (commandPath.length === 0) {
+		collectOptionNamesAtCurrentCommandDepth(usage, names, false);
+		return;
+	}
+	const [commandName, ...rest] = commandPath;
+	for (let i = 0; i < usage.length; i++) {
+		const term = usage[i];
+		if (term.type === "command" && term.name === commandName) {
+			const remainingUsage = usage.slice(i + 1);
+			if (rest.length === 0) collectOptionNamesAtCurrentCommandDepth(remainingUsage, names, !fromExclusive && includeDirectAfterCommandOptions);
+			else collectActiveOptionNames(remainingUsage, rest, names, fromExclusive, includeDirectAfterCommandOptions);
+		} else if (term.type === "exclusive") for (const branch of term.terms) collectActiveOptionNames(branch, commandPath, names, true, includeDirectAfterCommandOptions);
+		else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") collectActiveOptionNames(term.terms, commandPath, names, fromExclusive, includeDirectAfterCommandOptions);
+	}
+}
+/** Collects arities without entering further commands. @internal */
+function collectOptionNamesAtCurrentCommandDepth(usage, names, afterMatchedCommand) {
+	for (const term of usage) if (collectOptionNamesAtCurrentCommandDepthFromTerm(term, names, afterMatchedCommand)) return;
+}
+function collectOptionNamesAtCurrentCommandDepthFromTerm(term, names, afterMatchedCommand) {
+	switch (term.type) {
+		case "command": return !afterMatchedCommand;
+		case "option":
+			if (term.metavar != null) for (const name of term.names) names.value.add(name);
+			else for (const name of term.names) names.flag.add(name);
+			return false;
+		case "optional":
+		case "multiple":
+		case "sequence":
+			collectOptionNamesAtCurrentCommandDepth(term.terms, names, afterMatchedCommand);
+			return false;
+		case "exclusive":
+			for (const branch of term.terms) collectOptionNamesAtCurrentCommandDepth(branch, names, false);
+			return false;
+		case "argument":
+		case "literal":
+		case "passthrough":
+		case "ellipsis": return false;
+	}
+}
+/** Collects scoped root arities across sibling commands. @internal */
+function collectRootOptionNames(usage, names, rootLeadingNames) {
+	for (const term of usage) collectRootOptionNamesFromTerm(term, names, rootLeadingNames);
+}
+function collectRootOptionNamesFromTerm(term, names, rootLeadingNames) {
+	switch (term.type) {
+		case "option":
+			for (const name of term.names) {
+				if (!rootLeadingNames.has(name)) continue;
+				if (term.metavar != null) names.value.add(name);
+				else names.flag.add(name);
+			}
+			return;
+		case "optional":
+		case "multiple":
+		case "sequence":
+			collectRootOptionNames(term.terms, names, rootLeadingNames);
+			return;
+		case "exclusive":
+			for (const branch of term.terms) collectRootOptionNames(branch, names, rootLeadingNames);
+			return;
+		case "argument":
+		case "command":
+		case "literal":
+		case "passthrough":
+		case "ellipsis": return;
+	}
+}
 
 //#endregion
-export { collectLeadingCandidates, extractLeadingCommandNames };
+export { collectActiveOptionNames, collectLeadingCandidates, collectOptionNamesAtCurrentCommandDepth, collectRootOptionNames, extractLeadingCommandNames };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.4.0-dev.2618",
+  "version": "1.4.0-dev.2619",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -237,7 +237,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.4.0-dev.2618+2cb27efe",
+    "@optique/env": "1.4.0-dev.2619+6fa1e1d4",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",

package/skills/optique/SKILL.md

@@ -11,7 +11,8 @@ description: >
 license: MIT
 ---
 
-Start at <https://optique.dev/llms.txt> online; these rules also work offline.
+Start at <https://optique.dev/llms.txt> when online. These rules cover the
+combinatorial parser model and common pitfalls offline.
 
 
 Core rules
@@ -29,15 +30,11 @@ Core rules
     Pin `colors`/`maxWidth` in tests; defaults use terminal and environment.
  -  Compose parsers with `object()`, `tuple()`, `seq()`, `or()`, `merge()`, and
     modifiers. Do not hand-write argument scanners around Optique parsers.
- -  For command/option help headings, set the runner's
-    `helpSections: { commands: "Commands", options: "Options" }`.
-    It groups untitled entries only on pages with visible commands. See
-    <https://optique.dev/cookbook.md#command-and-option-headings-in-help>.
- -  Let TypeScript infer results; write a separate result interface only when
-    another API boundary requires it.
- -  Parsers are usually required. `optional(p)` yields `undefined`, and
-    `withDefault(p, value)` supplies a fallback. Use
-    `withDefault(flag("--name"), false)` for optional Boolean flags.
+ -  Let TypeScript infer parser result types. Only write a separate result
+    interface when another API boundary requires it.
+ -  Most parsers are required. `optional(p)` yields `undefined`, and
+    `withDefault(p, value)` supplies a fallback. For absent Boolean flags,
+    use `withDefault(flag("--name"), false)`.
  -  Use semantic `message` helpers for descriptions and errors. Since 1.3.0,
     customize terminal output with `theme` or `messageFormatter`, preserving
     `initialWidth`, quoting, and width options. Keep canonical errors unthemed.
@@ -50,6 +47,8 @@ Core rules
     `@optique/run/valueparser` for file-system paths. Write a custom
     `{ mode, metavar, parse, format }` value parser only when the catalog does
     not cover the domain.
+ -  Since 1.4.0, `-p8080`/`-vp8080` accept attached values. Values consume
+    the literal suffix (`-p=5` gives `"=5"`); full single-dash names win.
  -  Async value parsers like *@optique/git* make containing parsers async.
     Await `run()`/`parse()`/`runParser()` or, for `bindKeyring()`, `runAsync()`.
  -  Use `dependency()` when one value parser controls another's valid values.
@@ -232,8 +231,9 @@ const parser = logLevel();
 Common mistakes checklist
 -------------------------
 
- -  Pass parsers to `run()` for apps; use explicit argument arrays with
-    `parse()` in tests and embedded use. Do not pre-parse `process.argv`.
+ -  Do not parse `process.argv` manually before calling Optique. Pass the parser
+    to `run()` for applications, or pass explicit argument arrays to `parse()`
+    in tests and embedded use.
  -  Do not treat `or(a, b)` as “zero or more alternatives.” It requires one
     matching branch unless the whole `or()` is wrapped in `optional()` or
     `withDefault()`.