@optique/core 1.4.0-dev.2892 → 1.4.0-dev.2895

package/dist/facade.cjs

@@ -818,7 +818,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	require_validate.validateProgramName(programName);
-	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, showAliases, showEnvironment, sectionOrder, helpSections, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
+	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, showAliases, showEnvironment, sectionOrder, helpSections, showUsage, usageLine, commandList = "recursive", aboveError = "usage", errorUsage = "root", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	let maxWidth = requestedMaxWidth;
@@ -1117,8 +1117,15 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						})));
 					}
 					if (effectiveAboveError === "usage") {
-						resolveUsageWidth(augmentedParser.usage);
-						stderr(`${usageLabel()}${indentLines(require_usage.formatUsage(programName, augmentedParser.usage, {
+						const rootUsage = augmentedParser.usage;
+						const optionCount = Number(helpParsers.helpOption != null) + Number(versionParsers.versionOption != null);
+						const alternativeCount = optionCount + Number(helpParsers.helpCommand != null) + Number(versionParsers.versionCommand != null) + Number(completionParsers.completionCommand != null);
+						const errorUsageTerms = aboveError === "usage" && errorUsage === "command" ? require_usage_internals.projectCommandUsage(rootUsage, classified.commandPath, alternativeCount === 0 ? void 0 : {
+							optionCount,
+							alternativeCount
+						}) ?? rootUsage : rootUsage;
+						resolveUsageWidth(errorUsageTerms);
+						stderr(`${usageLabel()}${indentLines(require_usage.formatUsage(programName, errorUsageTerms, {
 							theme,
 							colors,
 							maxWidth: maxWidth == null ? void 0 : maxWidth - usageLabelWidth(),

package/dist/facade.d.cts

@@ -326,6 +326,17 @@ interface RunOptions<THelp, TError> {
    * @default `"usage"`
    */
   readonly aboveError?: "usage" | "help" | "none";
+  /**
+   * Scope of the compact preamble when `aboveError` is `"usage"`.
+   * `"command"` uses the failed parse's canonical command path and usage
+   * metadata, retaining parent options. Hidden or unresolved paths and
+   * unsupported compositions fall back to root usage. Neither mode applies
+   * help-only `usageLine` overrides or evaluates the parser again.
+   *
+   * @default `"root"`
+   * @since 1.4.0
+   */
+  readonly errorUsage?: "root" | "command";
   /**
    * Callback invoked after error output for a parse failure, an invalid
    * command path before help, or a missing or unsupported completion shell.

package/dist/facade.d.ts

@@ -326,6 +326,17 @@ interface RunOptions<THelp, TError> {
    * @default `"usage"`
    */
   readonly aboveError?: "usage" | "help" | "none";
+  /**
+   * Scope of the compact preamble when `aboveError` is `"usage"`.
+   * `"command"` uses the failed parse's canonical command path and usage
+   * metadata, retaining parent options. Hidden or unresolved paths and
+   * unsupported compositions fall back to root usage. Neither mode applies
+   * help-only `usageLine` overrides or evaluates the parser again.
+   *
+   * @default `"root"`
+   * @since 1.4.0
+   */
+  readonly errorUsage?: "root" | "command";
   /**
    * Callback invoked after error output for a parse failure, an invalid
    * command path before help, or a missing or unsupported completion shell.

package/dist/facade.js

@@ -12,7 +12,7 @@ import { collectExplicitSourceValues, collectExplicitSourceValuesAsync, createDe
 import { createInputTrace } from "./input-trace.js";
 import { attemptParseAsync, attemptParseSync, createEffectfulCompletionSession, createParserContext, getDocPage } from "./internal/parser.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
-import { collectActiveOptionNames, collectRootOptionNames } from "./usage-internals.js";
+import { collectActiveOptionNames, collectRootOptionNames, projectCommandUsage } from "./usage-internals.js";
 import { allowDuplicateLeadingCommandNamesKey, hiddenCommandAliasesKey } from "./internal/command-alias.js";
 import { completeOrExtractPhase2Seed } from "./phase2-seed.js";
 import { multiple, optional, withDefault } from "./modifiers.js";
@@ -818,7 +818,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	validateProgramName(programName);
-	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, showAliases, showEnvironment, sectionOrder, helpSections, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
+	const { colors, messageFormatter, theme: requestedTheme, maxWidth: requestedMaxWidth, termWidth, showDefault, showChoices, showAliases, showEnvironment, sectionOrder, helpSections, showUsage, usageLine, commandList = "recursive", aboveError = "usage", errorUsage = "root", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	let maxWidth = requestedMaxWidth;
@@ -1117,8 +1117,15 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						})));
 					}
 					if (effectiveAboveError === "usage") {
-						resolveUsageWidth(augmentedParser.usage);
-						stderr(`${usageLabel()}${indentLines(formatUsage(programName, augmentedParser.usage, {
+						const rootUsage = augmentedParser.usage;
+						const optionCount = Number(helpParsers.helpOption != null) + Number(versionParsers.versionOption != null);
+						const alternativeCount = optionCount + Number(helpParsers.helpCommand != null) + Number(versionParsers.versionCommand != null) + Number(completionParsers.completionCommand != null);
+						const errorUsageTerms = aboveError === "usage" && errorUsage === "command" ? projectCommandUsage(rootUsage, classified.commandPath, alternativeCount === 0 ? void 0 : {
+							optionCount,
+							alternativeCount
+						}) ?? rootUsage : rootUsage;
+						resolveUsageWidth(errorUsageTerms);
+						stderr(`${usageLabel()}${indentLines(formatUsage(programName, errorUsageTerms, {
 							theme,
 							colors,
 							maxWidth: maxWidth == null ? void 0 : maxWidth - usageLabelWidth(),

package/dist/usage-internals.cjs

@@ -2,6 +2,103 @@ 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);
+	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 : [
+			...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 : [
+			...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 : [
+		...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 +249,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,104 @@
-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);
+	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 : [
+			...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 : [
+			...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 : [
+		...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 +245,4 @@ function collectRootOptionNamesFromTerm(term, names, rootLeadingNames) {
 }
 
 //#endregion
-export { collectActiveOptionNames, collectLeadingCandidates, collectOptionNamesAtCurrentCommandDepth, collectRootOptionNames, extractLeadingCommandNames };
+export { collectActiveOptionNames, collectLeadingCandidates, collectOptionNamesAtCurrentCommandDepth, collectRootOptionNames, extractLeadingCommandNames, projectCommandUsage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.4.0-dev.2892",
+  "version": "1.4.0-dev.2895",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -261,7 +261,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.4.0-dev.2892+c7a6d04d",
+    "@optique/env": "1.4.0-dev.2895+fb7758c4",
     "@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.