@optique/core 1.4.0-dev.2606 → 1.4.0-dev.2607

package/dist/short-option.cjs

@@ -0,0 +1,197 @@
+const require_internal_annotations = require('./internal/annotations.cjs');
+const require_usage = require('./usage.cjs');
+const require_usage_internals = require('./usage-internals.cjs');
+
+//#region src/short-option.ts
+const optionScopeKey = Symbol("optionScope");
+const scopeSourceKey = Symbol("optionScopeSource");
+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) require_usage_internals.collectOptionNamesAtCurrentCommandDepth(parser.usage, arities, false);
+			return parser.leadingNames;
+		};
+		primitiveScopes.set(parser, source);
+	}
+	return source;
+}
+/** Combines declarations without flattening conditional ownership. @internal */
+function combinedOptionScope(parsers) {
+	return (selections, arities, context) => new Set(parsers.flatMap((parser) => [...parserScope(parser)(selections, arities, context)]));
+}
+/** Tracks declarations after a command or discriminator routes input. @internal */
+function selectableOptionScope(initial) {
+	const source = (selections, arities, context) => (selections.get(source) ?? initial)(selections, arities, context);
+	return {
+		source,
+		select(context, selected) {
+			context[optionScopeKey]?.selections.set(source, selected);
+		}
+	};
+}
+/** Keeps selected conditional names distinct from sibling declarations. @internal */
+function conditionalOptionScope(discriminator, fallback, candidates = []) {
+	const scope = selectableOptionScope((selections, arities, context) => {
+		const canSkip = discriminator.canSkip?.(context == null ? discriminator.initialState : require_internal_annotations.inheritAnnotations(context.state, discriminator.initialState), context?.exec) === true;
+		return combinedOptionScope([
+			discriminator,
+			...canSkip ? candidates : [],
+			...fallback == null ? [] : [fallback]
+		])(selections, arities, context);
+	});
+	return {
+		source: scope.source,
+		select(context, branch) {
+			scope.select(context, combinedOptionScope([discriminator, branch]));
+		}
+	};
+}
+/** Returns the names reachable in this parse scope. @internal */
+function getOptionScope(context) {
+	const scoped = context[optionScopeKey];
+	const names = scoped == null ? require_usage.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) {
+	const inherited = context[optionScopeKey];
+	return {
+		...context,
+		[optionScopeKey]: {
+			names: inherited?.names ?? /* @__PURE__ */ new Set(),
+			sources: new Set([...inherited?.sources ?? [], parserScope(parser)]),
+			selections: inherited?.selections ?? /* @__PURE__ */ new Map()
+		}
+	};
+}
+/** Isolates route selections while probing a competing branch. @internal */
+function forkOptionScope(context) {
+	const scoped = context[optionScopeKey];
+	return scoped == null ? context : {
+		...context,
+		[optionScopeKey]: {
+			...scoped,
+			selections: new Map(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) {
+	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(context, parser);
+				prepare?.(scoped);
+				return parse.call(parser, scoped);
+			}
+		},
+		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 && (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) require_usage_internals.collectOptionNamesAtCurrentCommandDepth(context.usage, names, false);
+	else for (const source of scoped.sources) source(scoped.selections, names, context);
+	for (let index = 1; index < prefix.length; index++) {
+		const remainder = `-${prefix.slice(index)}`;
+		for (const name of scope) if (name.startsWith("-") && !name.startsWith("--") && name.length > 2 && (name.startsWith(remainder) || remainder.startsWith(`${name}=`))) return void 0;
+		const short = `-${prefix[index]}`;
+		if (optionNames.includes(short)) return {
+			head: prefix.slice(0, index + 1),
+			value: prefix.slice(index + 1)
+		};
+		if (!scope.has(short) || !names.flag.has(short) || names.value.has(short)) return void 0;
+	}
+	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
+exports.adoptOptionScope = adoptOptionScope;
+exports.attachedValuePrefix = attachedValuePrefix;
+exports.combinedOptionScope = combinedOptionScope;
+exports.conditionalOptionScope = conditionalOptionScope;
+exports.forkOptionScope = forkOptionScope;
+exports.fullNameOwnsToken = fullNameOwnsToken;
+exports.prefixSuggestion = prefixSuggestion;
+exports.restoreOptionScope = restoreOptionScope;
+exports.scopeParser = scopeParser;
+exports.selectableOptionScope = selectableOptionScope;
+exports.withOptionScope = withOptionScope;
+exports.withParserOptionScope = withParserOptionScope;

package/dist/short-option.js

@@ -0,0 +1,186 @@
+import { inheritAnnotations } from "./internal/annotations.js";
+import { extractOptionNames } from "./usage.js";
+import { collectOptionNamesAtCurrentCommandDepth } from "./usage-internals.js";
+
+//#region src/short-option.ts
+const optionScopeKey = Symbol("optionScope");
+const scopeSourceKey = Symbol("optionScopeSource");
+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;
+}
+/** Combines declarations without flattening conditional ownership. @internal */
+function combinedOptionScope(parsers) {
+	return (selections, arities, context) => new Set(parsers.flatMap((parser) => [...parserScope(parser)(selections, arities, context)]));
+}
+/** Tracks declarations after a command or discriminator routes input. @internal */
+function selectableOptionScope(initial) {
+	const source = (selections, arities, context) => (selections.get(source) ?? initial)(selections, arities, context);
+	return {
+		source,
+		select(context, selected) {
+			context[optionScopeKey]?.selections.set(source, selected);
+		}
+	};
+}
+/** Keeps selected conditional names distinct from sibling declarations. @internal */
+function conditionalOptionScope(discriminator, fallback, candidates = []) {
+	const scope = selectableOptionScope((selections, arities, context) => {
+		const canSkip = discriminator.canSkip?.(context == null ? discriminator.initialState : inheritAnnotations(context.state, discriminator.initialState), context?.exec) === true;
+		return combinedOptionScope([
+			discriminator,
+			...canSkip ? candidates : [],
+			...fallback == null ? [] : [fallback]
+		])(selections, arities, context);
+	});
+	return {
+		source: scope.source,
+		select(context, branch) {
+			scope.select(context, combinedOptionScope([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) {
+	const inherited = context[optionScopeKey];
+	return {
+		...context,
+		[optionScopeKey]: {
+			names: inherited?.names ?? /* @__PURE__ */ new Set(),
+			sources: new Set([...inherited?.sources ?? [], parserScope(parser)]),
+			selections: inherited?.selections ?? /* @__PURE__ */ new Map()
+		}
+	};
+}
+/** Isolates route selections while probing a competing branch. @internal */
+function forkOptionScope(context) {
+	const scoped = context[optionScopeKey];
+	return scoped == null ? context : {
+		...context,
+		[optionScopeKey]: {
+			...scoped,
+			selections: new Map(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) {
+	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(context, parser);
+				prepare?.(scoped);
+				return parse.call(parser, scoped);
+			}
+		},
+		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 && (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; index++) {
+		const remainder = `-${prefix.slice(index)}`;
+		for (const name of scope) if (name.startsWith("-") && !name.startsWith("--") && name.length > 2 && (name.startsWith(remainder) || remainder.startsWith(`${name}=`))) return void 0;
+		const short = `-${prefix[index]}`;
+		if (optionNames.includes(short)) return {
+			head: prefix.slice(0, index + 1),
+			value: prefix.slice(index + 1)
+		};
+		if (!scope.has(short) || !names.flag.has(short) || names.value.has(short)) return void 0;
+	}
+	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, prefixSuggestion, restoreOptionScope, scopeParser, selectableOptionScope, withOptionScope, 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.2606",
+  "version": "1.4.0-dev.2607",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -237,7 +237,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.4.0-dev.2606+b74e9130",
+    "@optique/env": "1.4.0-dev.2607+84d98355",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",

package/skills/optique/SKILL.md

@@ -30,13 +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.
- -  Let TypeScript infer the parsed value type from the parser. Do not
-    hand-maintain a separate interface for the result unless another API
-    boundary requires it.
- -  Most parsers are required until you wrap them. `optional(p)` yields
-    `undefined`; `withDefault(p, value)` yields a fallback value. For Boolean
-    flags, use `withDefault(flag("--name"), false)` when absence should mean
-    `false`.
+ -  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.
@@ -49,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.