@optique/core 1.4.0-dev.2899 → 1.4.0-dev.2935

package/dist/usage-internals.cjs

@@ -2,6 +2,108 @@ const require_usage = require('./usage.cjs');
 
 //#region src/usage-internals.ts
 /**
+* Projects augmented runner usage onto a recorded canonical command path.
+* Unsupported or ambiguous metadata returns undefined, preserving root usage.
+* No parser, documentation, or usage-override callbacks are evaluated.
+* @param usage The runner's original augmented usage.
+* @param path The canonical path recorded by the failed parse.
+* @param meta The known augmentation boundary, absent without alternatives.
+* @returns The selected grammar, or undefined when projection is uncertain.
+* @internal
+*/
+function projectCommandUsage(usage, path, meta) {
+	if (path.length === 0) return void 0;
+	if (meta == null) return projectCommandTerms(usage, path, 0);
+	const top = usage[0];
+	if (usage.length !== 1 || top.type !== "exclusive" || top.terms.length !== meta.alternativeCount + 1) return void 0;
+	const selected = projectCommandTerms(top.terms[meta.optionCount], path, 0);
+	if (selected == null) return void 0;
+	const options = top.terms.slice(0, meta.optionCount).filter((branch) => branch.some((term) => term.type === "option" && !require_usage.isUsageHidden(term.hidden)));
+	return options.length === 0 ? selected : [{
+		type: "exclusive",
+		terms: [...options, selected]
+	}];
+}
+function containsCommand(usage) {
+	return usage.some((term) => {
+		switch (term.type) {
+			case "command": return true;
+			case "exclusive": return term.terms.some(containsCommand);
+			case "optional":
+			case "multiple":
+			case "sequence": return containsCommand(term.terms);
+			default: return false;
+		}
+	});
+}
+/** Undefined distinguishes unsupported metadata from a command-free branch. */
+function firstCommandNames(usage) {
+	const hosts = usage.filter((term) => containsCommand([term]));
+	const first = hosts[0];
+	if (first == null) return [];
+	if (first.type === "command") return [first.name];
+	if (hosts.length !== 1) return void 0;
+	if (first.type === "sequence") return firstCommandNames(first.terms);
+	if (first.type !== "exclusive") return void 0;
+	const names = [];
+	for (const branch of first.terms) {
+		const found = firstCommandNames(branch);
+		if (found == null) return void 0;
+		names.push(...found);
+	}
+	return names;
+}
+function projectCommandTerms(usage, path, offset) {
+	if (offset === path.length) return usage;
+	const index = usage.findIndex((term) => containsCommand([term]));
+	if (index < 0) return void 0;
+	const host = usage[index];
+	const prefix = usage.slice(0, index);
+	const suffix = usage.slice(index + 1);
+	const orderedPrefix = prefix.some((term) => term.type === "option" || term.type === "argument" || term.type === "literal");
+	const preserveOrder = (terms$1) => orderedPrefix ? [{
+		type: "sequence",
+		terms: terms$1
+	}] : terms$1;
+	if (host.type === "command") {
+		if (host.name !== path[offset] || require_usage.isUsageHidden(host.hidden)) return void 0;
+		const rest = projectCommandTerms(suffix, path, offset + 1);
+		return rest == null ? void 0 : preserveOrder([
+			...prefix,
+			host,
+			...rest
+		]);
+	}
+	if (containsCommand(suffix)) return void 0;
+	if (host.type === "sequence") {
+		const terms$1 = projectCommandTerms(host.terms, path, offset);
+		return terms$1 == null ? void 0 : preserveOrder([
+			...prefix,
+			{
+				...host,
+				terms: terms$1
+			},
+			...suffix
+		]);
+	}
+	if (host.type !== "exclusive") return void 0;
+	let selected;
+	for (const branch of host.terms) {
+		const names = firstCommandNames(branch);
+		if (names == null) return void 0;
+		if (!names.includes(path[offset])) continue;
+		if (selected != null) return void 0;
+		selected = branch;
+	}
+	if (selected == null) return void 0;
+	const terms = projectCommandTerms(selected, path, offset);
+	return terms == null ? void 0 : preserveOrder([
+		...prefix,
+		...terms,
+		...suffix
+	]);
+}
+/**
 * Collects option names and command names that are valid as the *immediate*
 * next token at the current parse position ("leading candidates").
 *
@@ -152,4 +254,5 @@ exports.collectActiveOptionNames = collectActiveOptionNames;
 exports.collectLeadingCandidates = collectLeadingCandidates;
 exports.collectOptionNamesAtCurrentCommandDepth = collectOptionNamesAtCurrentCommandDepth;
 exports.collectRootOptionNames = collectRootOptionNames;
-exports.extractLeadingCommandNames = extractLeadingCommandNames;
+exports.extractLeadingCommandNames = extractLeadingCommandNames;
+exports.projectCommandUsage = projectCommandUsage;

package/dist/usage-internals.js

@@ -1,7 +1,109 @@
-import { isSuggestionHidden } from "./usage.js";
+import { isSuggestionHidden, isUsageHidden } from "./usage.js";
 
 //#region src/usage-internals.ts
 /**
+* Projects augmented runner usage onto a recorded canonical command path.
+* Unsupported or ambiguous metadata returns undefined, preserving root usage.
+* No parser, documentation, or usage-override callbacks are evaluated.
+* @param usage The runner's original augmented usage.
+* @param path The canonical path recorded by the failed parse.
+* @param meta The known augmentation boundary, absent without alternatives.
+* @returns The selected grammar, or undefined when projection is uncertain.
+* @internal
+*/
+function projectCommandUsage(usage, path, meta) {
+	if (path.length === 0) return void 0;
+	if (meta == null) return projectCommandTerms(usage, path, 0);
+	const top = usage[0];
+	if (usage.length !== 1 || top.type !== "exclusive" || top.terms.length !== meta.alternativeCount + 1) return void 0;
+	const selected = projectCommandTerms(top.terms[meta.optionCount], path, 0);
+	if (selected == null) return void 0;
+	const options = top.terms.slice(0, meta.optionCount).filter((branch) => branch.some((term) => term.type === "option" && !isUsageHidden(term.hidden)));
+	return options.length === 0 ? selected : [{
+		type: "exclusive",
+		terms: [...options, selected]
+	}];
+}
+function containsCommand(usage) {
+	return usage.some((term) => {
+		switch (term.type) {
+			case "command": return true;
+			case "exclusive": return term.terms.some(containsCommand);
+			case "optional":
+			case "multiple":
+			case "sequence": return containsCommand(term.terms);
+			default: return false;
+		}
+	});
+}
+/** Undefined distinguishes unsupported metadata from a command-free branch. */
+function firstCommandNames(usage) {
+	const hosts = usage.filter((term) => containsCommand([term]));
+	const first = hosts[0];
+	if (first == null) return [];
+	if (first.type === "command") return [first.name];
+	if (hosts.length !== 1) return void 0;
+	if (first.type === "sequence") return firstCommandNames(first.terms);
+	if (first.type !== "exclusive") return void 0;
+	const names = [];
+	for (const branch of first.terms) {
+		const found = firstCommandNames(branch);
+		if (found == null) return void 0;
+		names.push(...found);
+	}
+	return names;
+}
+function projectCommandTerms(usage, path, offset) {
+	if (offset === path.length) return usage;
+	const index = usage.findIndex((term) => containsCommand([term]));
+	if (index < 0) return void 0;
+	const host = usage[index];
+	const prefix = usage.slice(0, index);
+	const suffix = usage.slice(index + 1);
+	const orderedPrefix = prefix.some((term) => term.type === "option" || term.type === "argument" || term.type === "literal");
+	const preserveOrder = (terms$1) => orderedPrefix ? [{
+		type: "sequence",
+		terms: terms$1
+	}] : terms$1;
+	if (host.type === "command") {
+		if (host.name !== path[offset] || isUsageHidden(host.hidden)) return void 0;
+		const rest = projectCommandTerms(suffix, path, offset + 1);
+		return rest == null ? void 0 : preserveOrder([
+			...prefix,
+			host,
+			...rest
+		]);
+	}
+	if (containsCommand(suffix)) return void 0;
+	if (host.type === "sequence") {
+		const terms$1 = projectCommandTerms(host.terms, path, offset);
+		return terms$1 == null ? void 0 : preserveOrder([
+			...prefix,
+			{
+				...host,
+				terms: terms$1
+			},
+			...suffix
+		]);
+	}
+	if (host.type !== "exclusive") return void 0;
+	let selected;
+	for (const branch of host.terms) {
+		const names = firstCommandNames(branch);
+		if (names == null) return void 0;
+		if (!names.includes(path[offset])) continue;
+		if (selected != null) return void 0;
+		selected = branch;
+	}
+	if (selected == null) return void 0;
+	const terms = projectCommandTerms(selected, path, offset);
+	return terms == null ? void 0 : preserveOrder([
+		...prefix,
+		...terms,
+		...suffix
+	]);
+}
+/**
 * Collects option names and command names that are valid as the *immediate*
 * next token at the current parse position ("leading candidates").
 *
@@ -148,4 +250,4 @@ function collectRootOptionNamesFromTerm(term, names, rootLeadingNames) {
 }
 
 //#endregion
-export { collectActiveOptionNames, collectLeadingCandidates, collectOptionNamesAtCurrentCommandDepth, collectRootOptionNames, extractLeadingCommandNames };
+export { collectActiveOptionNames, collectLeadingCandidates, collectOptionNamesAtCurrentCommandDepth, collectRootOptionNames, extractLeadingCommandNames, projectCommandUsage };

package/dist/valueparser.cjs

@@ -1,6 +1,7 @@
 const require_message = require('./message.cjs');
 const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 const require_internal_dependency = require('./internal/dependency.cjs');
+const require_internal_doc_metadata = require('./internal/doc-metadata.cjs');
 const require_suggestion = require('./suggestion.cjs');
 const require_nonempty = require('./nonempty.cjs');
 
@@ -92,7 +93,7 @@ function choice(choices, options = {}) {
 		const numberInvalidChoice = options.errors?.invalidChoice;
 		const numberStrings = numberChoices.map((v) => Object.is(v, -0) ? "-0" : String(v));
 		const frozenNumberChoices = Object.freeze(numberChoices);
-		return {
+		return require_internal_doc_metadata.captureDocValue({
 			mode: "sync",
 			metavar: metavar$1,
 			placeholder: choices[0],
@@ -156,7 +157,12 @@ function choice(choices, options = {}) {
 					text: valueStr
 				}));
 			}
-		};
+		}, {
+			kind: "number",
+			choices: numberChoices,
+			preserveNegativeZero: true,
+			canFormatDefault: true
+		});
 	}
 	const stringChoices = Object.freeze([...new Set(choices)]);
 	const stringOptions = options;
@@ -203,7 +209,7 @@ function choice(choices, options = {}) {
 		maxDistance: stringSuggest.maxDistance,
 		maxSuggestions: stringSuggest.maxSuggestions
 	} : stringSuggest;
-	return {
+	return require_internal_doc_metadata.captureDocValue({
 		mode: "sync",
 		metavar: metavar$1,
 		placeholder: choices[0],
@@ -240,7 +246,11 @@ function choice(choices, options = {}) {
 				text: value
 			}));
 		}
-	};
+	}, {
+		kind: "string",
+		choices: stringChoices,
+		canFormatDefault: customKey === void 0 && !caseInsensitive
+	});
 }
 function biject(mapping) {
 	if (mapping === null || typeof mapping !== "object") throw new TypeError("Expected object.");
@@ -723,7 +733,7 @@ function string(options = {}) {
 	const patternSource = options.pattern?.source ?? null;
 	const patternFlags = options.pattern?.flags ?? null;
 	const patternMismatch = options.errors?.patternMismatch;
-	return {
+	return require_internal_doc_metadata.captureDocValue({
 		mode: "sync",
 		metavar: metavar$1,
 		placeholder: options.placeholder ?? "",
@@ -747,7 +757,7 @@ function string(options = {}) {
 		format(value) {
 			return value;
 		}
-	};
+	}, { kind: "string" });
 }
 /**
 * Creates a {@link ValueParser} that compiles regular expression sources.
@@ -1179,7 +1189,7 @@ function integer(options) {
 	if (options?.type === "bigint") {
 		const metavar$2 = options.metavar ?? "INTEGER";
 		require_nonempty.ensureNonEmptyString(metavar$2);
-		return {
+		return require_internal_doc_metadata.captureDocValue({
 			mode: "sync",
 			metavar: metavar$2,
 			placeholder: options?.placeholder ?? (options?.min != null && options.min > 0n ? options.min : options?.max != null && options.max < 0n ? options.max : 0n),
@@ -1205,7 +1215,7 @@ function integer(options) {
 			format(value) {
 				return value.toString();
 			}
-		};
+		}, { kind: "bigint" });
 	}
 	const metavar$1 = options?.metavar ?? "INTEGER";
 	require_nonempty.ensureNonEmptyString(metavar$1);
@@ -1223,7 +1233,7 @@ function integer(options) {
 			error: unsafeIntegerError ? typeof unsafeIntegerError === "function" ? unsafeIntegerError(input) : unsafeIntegerError : require_message.message`Expected a safe integer between ${require_message.text(Number.MIN_SAFE_INTEGER.toLocaleString("en"))} and ${require_message.text(Number.MAX_SAFE_INTEGER.toLocaleString("en"))}, but got ${input}. Use type: "bigint" for large values.`
 		};
 	}
-	return {
+	return require_internal_doc_metadata.captureDocValue({
 		mode: "sync",
 		metavar: metavar$1,
 		placeholder: options?.placeholder ?? (firstAllowed > 0 ? firstAllowed : lastAllowed < 0 ? lastAllowed : 0),
@@ -1256,7 +1266,7 @@ function integer(options) {
 		format(value) {
 			return value.toString();
 		}
-	};
+	}, { kind: "number" });
 }
 /**
 * Creates a {@link ValueParser} for floating-point numbers.

package/dist/valueparser.js

@@ -1,6 +1,7 @@
 import { cloneMessage, lineBreak, message, metavar, text, valueSet } from "./message.js";
 import { mapMaybePromiseByMode, wrapForMode, wrapIterableForMode } from "./internal/mode-dispatch.js";
 import { defaultValues, dependencyId, dependencyIds, derivedValueParserMarker, getSnapshottedDefaultDependencyValues, isDependencySource, isDerivedValueParser, parseWithDependency, singleDefaultValue, snapshotDefaultDependencyValues, suggestWithDependency } from "./internal/dependency.js";
+import { captureDocValue } from "./internal/doc-metadata.js";
 import { appendValueHint, appendValueSuggestions, deduplicateSuggestions } from "./suggestion.js";
 import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 
@@ -92,7 +93,7 @@ function choice(choices, options = {}) {
 		const numberInvalidChoice = options.errors?.invalidChoice;
 		const numberStrings = numberChoices.map((v) => Object.is(v, -0) ? "-0" : String(v));
 		const frozenNumberChoices = Object.freeze(numberChoices);
-		return {
+		return captureDocValue({
 			mode: "sync",
 			metavar: metavar$1,
 			placeholder: choices[0],
@@ -156,7 +157,12 @@ function choice(choices, options = {}) {
 					text: valueStr
 				}));
 			}
-		};
+		}, {
+			kind: "number",
+			choices: numberChoices,
+			preserveNegativeZero: true,
+			canFormatDefault: true
+		});
 	}
 	const stringChoices = Object.freeze([...new Set(choices)]);
 	const stringOptions = options;
@@ -203,7 +209,7 @@ function choice(choices, options = {}) {
 		maxDistance: stringSuggest.maxDistance,
 		maxSuggestions: stringSuggest.maxSuggestions
 	} : stringSuggest;
-	return {
+	return captureDocValue({
 		mode: "sync",
 		metavar: metavar$1,
 		placeholder: choices[0],
@@ -240,7 +246,11 @@ function choice(choices, options = {}) {
 				text: value
 			}));
 		}
-	};
+	}, {
+		kind: "string",
+		choices: stringChoices,
+		canFormatDefault: customKey === void 0 && !caseInsensitive
+	});
 }
 function biject(mapping) {
 	if (mapping === null || typeof mapping !== "object") throw new TypeError("Expected object.");
@@ -723,7 +733,7 @@ function string(options = {}) {
 	const patternSource = options.pattern?.source ?? null;
 	const patternFlags = options.pattern?.flags ?? null;
 	const patternMismatch = options.errors?.patternMismatch;
-	return {
+	return captureDocValue({
 		mode: "sync",
 		metavar: metavar$1,
 		placeholder: options.placeholder ?? "",
@@ -747,7 +757,7 @@ function string(options = {}) {
 		format(value) {
 			return value;
 		}
-	};
+	}, { kind: "string" });
 }
 /**
 * Creates a {@link ValueParser} that compiles regular expression sources.
@@ -1179,7 +1189,7 @@ function integer(options) {
 	if (options?.type === "bigint") {
 		const metavar$2 = options.metavar ?? "INTEGER";
 		ensureNonEmptyString(metavar$2);
-		return {
+		return captureDocValue({
 			mode: "sync",
 			metavar: metavar$2,
 			placeholder: options?.placeholder ?? (options?.min != null && options.min > 0n ? options.min : options?.max != null && options.max < 0n ? options.max : 0n),
@@ -1205,7 +1215,7 @@ function integer(options) {
 			format(value) {
 				return value.toString();
 			}
-		};
+		}, { kind: "bigint" });
 	}
 	const metavar$1 = options?.metavar ?? "INTEGER";
 	ensureNonEmptyString(metavar$1);
@@ -1223,7 +1233,7 @@ function integer(options) {
 			error: unsafeIntegerError ? typeof unsafeIntegerError === "function" ? unsafeIntegerError(input) : unsafeIntegerError : message`Expected a safe integer between ${text(Number.MIN_SAFE_INTEGER.toLocaleString("en"))} and ${text(Number.MAX_SAFE_INTEGER.toLocaleString("en"))}, but got ${input}. Use type: "bigint" for large values.`
 		};
 	}
-	return {
+	return captureDocValue({
 		mode: "sync",
 		metavar: metavar$1,
 		placeholder: options?.placeholder ?? (firstAllowed > 0 ? firstAllowed : lastAllowed < 0 ? lastAllowed : 0),
@@ -1256,7 +1266,7 @@ function integer(options) {
 		format(value) {
 			return value.toString();
 		}
-	};
+	}, { kind: "number" });
 }
 /**
 * Creates a {@link ValueParser} for floating-point numbers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.4.0-dev.2899",
+  "version": "1.4.0-dev.2935",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -251,6 +251,14 @@
       },
       "import": "./dist/internal/help-request.js",
       "require": "./dist/internal/help-request.cjs"
+    },
+    "./doc-pages": {
+      "types": {
+        "import": "./dist/doc-pages.d.ts",
+        "require": "./dist/doc-pages.d.cts"
+      },
+      "import": "./dist/doc-pages.js",
+      "require": "./dist/doc-pages.cjs"
     }
   },
   "imports": {
@@ -261,7 +269,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.4.0-dev.2899+9c2973b0",
+    "@optique/env": "1.4.0-dev.2935+fc126fd1",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",

package/skills/optique/SKILL.md

@@ -80,9 +80,9 @@ Core rules
     Show hidden `aliases` in help with `showAliases` on `command()` or runner.
  -  Use `run(parser, { completion: "both" })` for completion, or the object form
     with `completion.errors` for custom shell errors. Do not hand-write scripts.
- -  Use `usageLine: [{ type: "ellipsis" }]` in runner options when a large root
-    synopsis should become a compact `Usage: myapp ...` line. This applies only
-    to root full help; use `command()`'s `usageLine` for subcommand help.
+ -  Use `usageLine: [{ type: "ellipsis" }]` for compact root full help and the
+    override on `command()` for subcommand help. `errorUsage: "command"` scopes
+    usage above errors with root fallback, ignoring help-only overrides.
  -  Use `showUsage: false` in runner options when full help should show the
     brief and sections without `Usage:`. Set `command()`'s `showUsage: true`
     to restore it; children inherit the nearest explicit ancestor setting.
@@ -243,15 +243,13 @@ Common mistakes checklist
  -  Wrap required `flag("--x")` in `optional()` or `withDefault(..., false)`.
  -  Do not expect `multiple(p)` to fail when absent; it returns `[]`. Wrap with
     `nonEmpty()` when at least one value is required.
- -  Do not confuse free-order parsing with `seq()`. Most constructs let child
-    parsers compete by priority; use `seq()` only for truly ordered grammars.
+ -  Use `seq()` only for ordered grammars; most constructs use parser priority.
  -  Use structured `message` values for errors and descriptions.
  -  Register contexts for `bindEnv()`, `bindConfig()`, `bindDerivedDefault()`,
     and `bindKeyring()` in the runner's `contexts` option.
  -  Use `bindEnv().readFallback()` for env/default in error handlers.
  -  Enable `showEnvironment` for env-only help; set `documentation.description`.
- -  Keep multi-level dependency graphs with `dependency()` rather than
-    duplicating one-level factories.
+ -  Keep multi-level `dependency()` graphs; avoid duplicate one-level factories.
  -  Put runtime prompt checks in `when`, with typed `otherwise`; evaluate them
     only at fallback, never eagerly during construction.
 
@@ -272,8 +270,10 @@ Reference links
  -  Structured messages: <https://optique.dev/concepts/messages.md>
  -  Shell completion: <https://optique.dev/concepts/completion.md>
  -  Command discovery: <https://optique.dev/concepts/discover.md>
- -  CLI: <https://github.com/dahlia/optique/tree/main/examples/file-inspect>
- -  Man pages: <https://optique.dev/concepts/man.md>
+ -  [CLI recipe][file-inspect]
+ -  Markdown references: <https://optique.dev/concepts/markdown-reference.md>
+
+[file-inspect]: https://github.com/dahlia/optique/tree/main/examples/file-inspect
 
 
 Integration packages
@@ -294,6 +294,6 @@ Integration packages
 | `@optique/temporal`         | Temporal date and time parsers              | <https://optique.dev/integrations/temporal.md>        |
 | `@optique/git`              | Async Git reference validation              | <https://optique.dev/integrations/git.md>             |
 | `@optique/logtape`          | LogTape levels and formatter/output options | <https://optique.dev/integrations/logtape.md>         |
-| `@optique/man`              | Man page generation                         | <https://optique.dev/concepts/man.md>                 |
+| `@optique/man`              | Man pages and Markdown references           | <https://optique.dev/concepts/man.md>                 |
 | `@optique/discover`         | Command discovery; opt-in `help.bareGroup`  | <https://optique.dev/concepts/discover.md>            |
 | `@optique/testing`          | Layered CLI testing at a chosen boundary    | <https://optique.dev/concepts/testing.md>             |