@loomcli/core 0.7.0 → 0.8.0

package/dist/command.js

@@ -3,17 +3,18 @@ import { checkEnvBinding, checkNoArgumentBinding } from './bindings.js';
 import { captureDeclaration, unreadableArgument } from './capture.js';
 import { aliasWithoutNames, argumentDeclaredTwice, argumentsBesideChildren, commandAttachedTwice, commandGlobals, commandWithoutAction, declaredAfterAction, declaredName, groupOption, multipleActions, multipleResults, nestingDepth, notACommand, optionalArgumentLast, portableName, repeatedAlias, resultWithoutAction, resultWithoutViews, rowViewOnValue, siblingNameTaken, unknownDefaultView, variadicArgumentLast, viewName, viewShape, viewsWithoutResult, } from './command-rules.js';
 import { elided, quoteString, spelled } from './diagnostic-text.js';
-import { asSentence, commandSentence, commandSubject, DeclarationError, NonCallableCommandError, quoted, ResultError, toFailure, UnexpectedArgumentError, UnknownCommandError, reasonOf, } from './errors.js';
+import { asSentence, commandSentence, commandSubject, DeclarationError, NonCallableCommandError, quoted, ResultError, toFailure, reasonOf, } from './errors.js';
 import { buildExtensions, extendStore, publishStore, registerDescriptor, storeCommandLayers, validateLayer, } from './extension.js';
 import { checkDeprecated, checkDescription, checkHidden, checkNoListingFacts, declarerNote, siteFinding, } from './facts.js';
-import { buildGlobals, checkLocalOptions } from './globals.js';
+import { buildGlobals, checkLocalOptions, frozenValues } from './globals.js';
 import { nameSharedAcrossKinds, optionDeclaredTwice, spellingTaken } from './input-rules.js';
 import { graphMismatch, nodeAt, resultNode } from './inspect.js';
-import { checkOptionName, compileOptions, copyValues, emptyValues, extractGlobals, isOptionToken, mergeValues, parseInputs, spellingMark, } from './options.js';
+import { checkOptionName, compileOptions, copyValues, declaredNameCorrection, emptyValues, isDeclaredName, mergeValues, repeatedAliasText, spellingMark, tableEntries, } from './options.js';
+import { argumentSlot, candidatesOf } from './parse.js';
 import { declaring, isPlainObject, shallowList, snapshot } from './plain.js';
 import { brokenAttachHook, notAnObject } from './plugin-rules.js';
 import { fillInputs } from './sources.js';
-import { captureInputConfig, configUnread, checkDeclarations, declaringSite, inputPlace, validateValues, } from './validation.js';
+import { captureInputConfig, configUnread, checkDeclarations, declaringSite, inputPlace, rejectsGlobal, validateValues, } from './validation.js';
 /**
  * The deepest level below the root a Command may sit at, and the word its diagnostic spells it with.
  * A child of the root sits at level 1. Raising the cap relaxes a rule and breaks no application.
@@ -105,10 +106,6 @@ function checkCommandOptions(name, options) {
         });
     }
 }
-/** One name rule for an argument, option, or view name: a bare token the parser can read. */
-function isDeclaredName(name) {
-    return typeof name === 'string' && Boolean(name) && !name.startsWith('-') && !/[\s=]/u.test(name);
-}
 /**
  * The portable name rule, for every name an operator types as a command at a shell prompt: the
  * application name, every Command name, and every alias. The characters are the POSIX portable
@@ -234,11 +231,11 @@ function checkOpen(state, late) {
 const inputRemedy = 'Declare arguments and options before action().';
 /** Where one input was declared: the call on the Command at `path` that declared it. */
 function inputSite(name, path, input) {
-    return declaringSite(input, inputPlace(input, { global: false, path }), `${commandSentence(name)} ${input.kind} ${quoted(input.name)}`);
+    return declaringSite(input, inputPlace(input, path), `${commandSentence(name)} ${input.kind} ${quoted(input.name)}`);
 }
 /** The finding for the `argument()` or `option()` call that declared one input, marking its name. */
 function inputFinding(path, input, note) {
-    const site = declaringSite(input, inputPlace(input, { global: false, path }));
+    const site = declaringSite(input, inputPlace(input, path));
     return siteFinding(site, site.named, note);
 }
 /**
@@ -246,7 +243,7 @@ function inputFinding(path, input, note) {
  * name is judged, so it prints elided.
  */
 function nameFinding(path, input) {
-    const site = configUnread(declaringSite(input, inputPlace(input, { global: false, path })));
+    const site = configUnread(declaringSite(input, inputPlace(input, path)));
     return siteFinding(site, site.named);
 }
 /** The scope one Command's own options compile under: its subject, and each option's call. */
@@ -324,7 +321,7 @@ function checkArgumentName(command, declared, input) {
     const { path } = command;
     if (!isDeclaredName(input.name)) {
         throw new DeclarationError(declaredName, {
-            correction: 'Use a nonempty name without a leading hyphen, whitespace, or "=".',
+            correction: declaredNameCorrection,
             findings: [nameFinding(path, input)],
             sentence: `${commandSentence(command.name)} declares an argument named ${quoted(input.name)}.`,
         });
@@ -439,18 +436,17 @@ export function declareAlias(state, names) {
     const aliases = [...state.aliases];
     for (const [index, alias] of names.entries()) {
         const repeated = { arguments: names, call: 'alias', mark: String(index), path };
+        const text = repeatedAliasText(commandSentence(name), alias);
         if (alias === name) {
             throw new DeclarationError(repeatedAlias, {
-                correction: 'Remove the alias.',
+                ...text.own,
                 findings: [{ ...repeated, note: 'its own name' }],
-                sentence: `${commandSentence(name)} declares alias "${alias}", which is its own name.`,
             });
         }
         if (aliases.includes(alias)) {
             throw new DeclarationError(repeatedAlias, {
-                correction: 'Remove the repeated alias.',
+                ...text.twice,
                 findings: [{ ...repeated, note: 'already an alias' }],
-                sentence: `${commandSentence(name)} declares alias "${alias}" twice.`,
             });
         }
         aliases.push(alias);
@@ -727,7 +723,7 @@ function attachChild(state, child) {
 /**
  * Walks one subtree joining an Application, once, for the rules only the Application can judge: one
  * Command value reached through two paths, two distinct descriptors under one identity, a local
- * option that meets a global or plugin option's key, spelling, or variable, and the nesting cap
+ * option that meets a global option's key, spelling, or variable, and the nesting cap
  * measured from the root. A claim is by node identity, and the name serves the diagnostic alone.
  * At a cap of two a named parent's `command()` already rejects every deeper tree, so the depth check
  * here fires only once the cap rises: attach reads one level, and only this walk knows each level.
@@ -1293,13 +1289,13 @@ function readSpellings(table, claimed, placeOf) {
     for (const [spelling, option] of table) {
         if (!claimed.has(spelling)) {
             const form = longs.get(option.name) ?? spelling;
-            claimed.set(spelling, { finding: placeOf(option.name, option.role), form });
+            claimed.set(spelling, { finding: placeOf(option.name, option), form });
         }
     }
 }
 /** The place one input's spelling sits: the key of its call that yields the spelling. */
-function spellingPlace(site, role, note) {
-    return siteFinding(site, spellingMark(site, role), note);
+function spellingPlace(site, origin, note) {
+    return siteFinding(site, spellingMark(site, origin), note);
 }
 /** One hook-declared option's spellings, against every spelling the table already claims. */
 function checkAttachedSpelling(declared, named) {
@@ -1314,14 +1310,14 @@ function checkAttachedSpelling(declared, named) {
             throw new DeclarationError(spellingTaken, {
                 correction: 'Change one of the two spellings or omit the plugin.',
                 findings: [
-                    spellingPlace(site, option.role, declarerNote(identity)),
+                    spellingPlace(site, option, declarerNote(identity)),
                     ...(used.finding === undefined ? [] : [used.finding]),
                 ],
                 sentence: `Plugin ${quoted(identity)} declares option ${quoted(input.name)} with spelling ${quoted(spelling)} on ${subject}, which ${quoted(used.form)} already uses.`,
             });
         }
     }
-    readSpellings(table, claimed, (_name, role) => spellingPlace(site, role, declarerNote(identity)));
+    readSpellings(table, claimed, (_name, origin) => spellingPlace(site, origin, declarerNote(identity)));
 }
 /** The declarations of one kind, keyed by name, the first of each name winning. */
 function byName(inputs) {
@@ -1335,7 +1331,7 @@ function byName(inputs) {
 }
 /** Where the globals table's options declared their spellings, a global or a plugin's option. */
 function tableSpellings(globals) {
-    return (name, role) => {
+    return (name, origin) => {
         const entry = globals.names.get(name);
         if (!entry) {
             return undefined;
@@ -1344,7 +1340,7 @@ function tableSpellings(globals) {
         const note = owner.kind === 'plugin'
             ? `an option of plugin ${quoted(owner.identity)}`
             : `the global option ${quoted(name)}`;
-        return spellingPlace(site, role, note);
+        return spellingPlace(site, origin, note);
     };
 }
 /**
@@ -1371,11 +1367,11 @@ function checkAttachedInputs(declared, attached, place) {
     };
     const claimed = new Map();
     readSpellings(globals.options, claimed, tableSpellings(globals));
-    readSpellings(compileOptions(options, scope), claimed, (name, role) => {
+    readSpellings(compileOptions(options, scope), claimed, (name, origin) => {
         const local = locals.get(name);
         return local === undefined || local.kind !== 'option'
             ? undefined
-            : spellingPlace(scope.siteOf(local), role, `the local option ${quoted(name)}`);
+            : spellingPlace(scope.siteOf(local), origin, `the local option ${quoted(name)}`);
     });
     for (const entry of attached) {
         const { identity, input } = entry;
@@ -1404,7 +1400,7 @@ function bindDispatch(state, action, globals) {
         // The graph erases the binder's generic relationship.
         // It holds because attachment checks the global output requirement.
         // The call or the attach that met both options rejected a collision between a global and a local.
-        // This binder returns the Application's validated globals alone.
+        // This binder returns the validated value of every global option, the plugins' included.
         // oxlint-disable-next-line typescript/no-unsafe-type-assertion
         const globalOptions = globals.bind(values);
         return action({
@@ -1499,6 +1495,7 @@ export function buildCommand(state, context) {
     checkArgumentPlacement(place, slots[0], state.children[0]);
     const result = checkFinished(hooked, hasAction, { path: context.path });
     const options = checkLocalOptions(optionsOf(hooked.inputs), globals, localScope(name, context.path));
+    const table = new Map([...tableEntries(options, false), ...globals.table]);
     // A hook's erased calls answer the declaration rules an authored call answers at the call.
     checkDeclarations(hookInputs.map(({ input }) => ({ input, site: inputSite(name, context.path, input) })));
     const children = new Map();
@@ -1525,9 +1522,9 @@ export function buildCommand(state, context) {
         hidden: facts.hidden,
         inputs: hooked.inputs,
         name,
-        options,
         result,
         routes,
+        table,
     };
 }
 /**
@@ -1637,17 +1634,15 @@ export function collectInputs(command) {
     ];
 }
 /**
- * Where every input of one graph was declared: each global option at its `globalOption()` call,
- * and each Command's own inputs at their calls on the Command, under its path from the root.
+ * Where every input of one graph was declared: each global option at its `globalOption()` call or
+ * in its plugin's `options` record, and each Command's own inputs at their calls on the Command,
+ * under its path from the root.
  */
 export function inputPlaces(graph) {
-    const places = new Map();
-    for (const input of graph.globals.inputs) {
-        places.set(input, inputPlace(input, { global: true, path: [] }));
-    }
+    const places = new Map(graph.globals.sites);
     const walk = (command, path) => {
         for (const input of command.inputs) {
-            places.set(input, inputPlace(input, { global: false, path }));
+            places.set(input, declaringSite(input, inputPlace(input, path)));
         }
         for (const [name, child] of command.children) {
             walk(child, [...path, name]);
@@ -1656,97 +1651,36 @@ export function inputPlaces(graph) {
     walk(graph.root, []);
     return places;
 }
-/**
- * The names a routing failure offers: the canonical names of the visible, current children, in
- * authoring order. A candidate list is a listing, so a hidden or a deprecated child is absent from
- * it, as completion leaves them out, and a parent whose children are all hidden or deprecated
- * offers none. A deprecated child typed in full still routes.
- */
-function candidatesOf(command) {
-    return [...command.children]
-        .filter(([, child]) => !child.hidden && child.deprecated === undefined)
-        .map(([name]) => name);
-}
-/**
- * Whether a token names one of the Command's children: the Command has children and the token is
- * no option token. Routing and `locate` read a bare word through this rule.
- */
-export function readsAsChild(command, token) {
-    return command.children.size > 0 && !isOptionToken(token);
-}
-/**
- * Bare tokens, names or aliases, select children until a Command has none; a hyphen commits.
- * `walked` receives the path after each name routes, so an unknown Command leaves its caller
- * holding the partial path walked before it.
- */
-export function route(root, tokens, walked) {
-    let command = root;
-    const path = [];
-    let index = 0;
-    for (let token = tokens[index]; token !== undefined; token = tokens[index]) {
-        if (!readsAsChild(command, token)) {
-            break;
-        }
-        const child = command.routes.get(token);
-        if (!child) {
-            throw new UnknownCommandError(token, candidatesOf(command));
-        }
-        // An alias routes like the canonical name, and the path it walks reports that name alone.
-        command = child.command;
-        path.push(child.name);
-        walked?.(Object.freeze([...path]));
-        index += 1;
+/** One positional word bound to its slot: a variadic slot collects it, any other holds it. */
+function bindWord(values, slot, word) {
+    const bound = values.get(slot.input);
+    if (!slot.variadic) {
+        values.set(slot.input, word);
+    }
+    else if (Array.isArray(bound)) {
+        bound.push(word);
+    }
+    else {
+        values.set(slot.input, [word]);
     }
-    return { command, path, tokens: tokens.slice(index) };
 }
 /**
- * The tokens each positional slot received. An omitted required argument binds nothing here and
+ * The words each positional slot received. Parsing already held the first positional no slot
+ * accepts, so every positional here has a slot. An omitted required argument binds nothing and
  * reports as a missing input in the validation phase, so omission has one class whether the input
- * is an argument or an option. Extra tokens are a token fault, so this phase still reports them.
+ * is an argument or an option. An empty variadic tail binds nothing, so validation reads it as
+ * `[]` or reports the omission.
  */
-function bindArguments(command, path, positionals) {
+function bindArguments(command, positionals) {
     const values = new Map();
-    for (const [position, token] of positionals.entries()) {
+    for (const [position, word] of positionals.entries()) {
         const slot = argumentSlot(command.arguments, position);
-        if (!slot) {
-            throw new UnexpectedArgumentError(path, command.arguments.length, positionals.slice(position));
-        }
-        // An empty variadic tail binds nothing, so validation reads it as `[]` or reports the omission.
-        const bound = values.get(slot.input);
-        if (!slot.variadic) {
-            values.set(slot.input, token);
-        }
-        else if (Array.isArray(bound)) {
-            bound.push(token);
-        }
-        else {
-            values.set(slot.input, [token]);
+        if (slot) {
+            bindWord(values, slot, word);
         }
     }
     return values;
 }
-/**
- * The slot the positional at one index fills: the slot at that index, else a variadic last slot,
- * which accepts every later positional, else none. Binding and `locate` read positions through it.
- */
-export function argumentSlot(slots, position) {
-    const last = slots.at(-1);
-    return slots[position] ?? (last?.variadic ? last : undefined);
-}
-/**
- * Consumes the globals table, then routes the remaining bare tokens to a Command. `walked`
- * receives the path as routing extends it, the partial path of an unknown Command included.
- */
-export function routeInvocation(graph, argv, walked) {
-    const scan = extractGlobals(graph.globals.options, [...argv]);
-    const routed = route(graph.root, scan.rest, walked);
-    return {
-        command: routed.command,
-        path: routed.path,
-        scan: scan.values,
-        tokens: routed.tokens,
-    };
-}
 /**
  * The frozen records one middleware reads: the routed Command's own inputs, and the tail. Every
  * value is a plain-data copy frozen to every depth, so a middleware that reaches into a list or a
@@ -1768,30 +1702,25 @@ function requestOf(command, values, passthrough) {
     });
 }
 /**
- * The callable check and local parsing. A group answers no invocation of its own, so it holds the
- * missing-subcommand error with the rank the routing errors have and parses no token; a token
- * fault holds the same way.
+ * The held structural fault, then the callable check. A group answers no invocation of its own, so
+ * it holds the missing-subcommand error, which ranks after every structural fault.
  */
 function parseLocal(routed) {
-    const { command, path } = routed;
+    const { command, fault, path } = routed;
     const { dispatch } = command;
-    try {
-        if (!dispatch) {
-            throw new NonCallableCommandError(path, candidatesOf(command));
-        }
-        const parsed = parseInputs(command.options, routed.tokens);
-        const args = bindArguments(command, path, parsed.positionals);
-        return {
-            args,
-            dispatch,
-            kind: 'parsed',
-            options: parsed.options,
-            passthrough: parsed.passthrough,
-        };
+    if (fault) {
+        return { fault, kind: 'held' };
     }
-    catch (error) {
-        return { fault: error, kind: 'held' };
+    if (!dispatch) {
+        return { fault: new NonCallableCommandError(path, candidatesOf(command)), kind: 'held' };
     }
+    return {
+        args: bindArguments(command, routed.positionals),
+        dispatch,
+        kind: 'parsed',
+        options: routed.values.locals,
+        passthrough: routed.passthrough,
+    };
 }
 /**
  * The node of one option a configuration source is asked about: in the graph's globals, or among
@@ -1806,21 +1735,24 @@ function requestNode(graph, path, place) {
     }
     return node;
 }
+/** The passthrough tail a validator reads: the routed Command's, or none while a fault is held. */
+function tailOf(local) {
+    return local.kind === 'parsed' ? local.passthrough : [];
+}
 /**
- * The input-source stage over this run's own copies of the parsed values. The global and plugin
- * options fill whatever local parsing held; the routed Command's own options fill only when local
- * parsing held no fault, because the request is `null` otherwise.
+ * The input-source stage over this run's own copies of the parsed values. The global options fill
+ * whatever was held, and a faulted occurrence supplied nothing, so a source may fill its option;
+ * the routed Command's own options fill only when nothing is held, because the request is `null`
+ * otherwise. A configuration source's own options pass their validators before the source is
+ * called, as a pass over those options alone.
  */
-async function fillScope({ graph, invocation, routed }, local) {
-    const globals = copyValues(routed.scan);
+async function fillScope(preparation, local) {
+    const { graph, invocation, routed } = preparation;
+    const globals = copyValues(routed.values.globals);
     const locals = copyValues(local.kind === 'parsed' ? local.options : emptyValues());
     const sources = await fillInputs({
         extensions: graph.extensions,
-        globals: {
-            global: true,
-            inputs: [...graph.globals.inputs, ...graph.globals.plugins.flatMap((entry) => entry.inputs)],
-            values: globals,
-        },
+        globals: { global: true, inputs: graph.globals.inputs, values: globals },
         host: invocation.host,
         inspected: invocation.inspected,
         locals: local.kind === 'parsed'
@@ -1832,28 +1764,52 @@ async function fillScope({ graph, invocation, routed }, local) {
         request: (input, global) => requestNode(invocation.inspected(), routed.path, { global, name: input.name }),
         signal: invocation.signal,
         style: invocation.style,
+        validate: (inputs, provenance) => validateInvocation(preparation, {
+            local,
+            locals,
+            only: new Set(inputs),
+            sources: provenance,
+            values: globals,
+        }),
     });
     return { globals, locals, sources };
 }
 /**
- * Validation and the dispatch it prepares, over the values the input-source stage left. It answers
- * with the call that dispatches, so the caller records that the action was invoked at the moment
- * it invokes it and no earlier failure reads as a dispatch.
+ * A validation pass over the values the input-source stage has filled: every global option
+ * whatever was held, and the routed Command's own declarations only when nothing is held and the
+ * Command is not a group. `only` narrows the declarations a pass validates, as the pass over a
+ * configuration source's own options does ahead of its call, while every validator reads the same
+ * context. The run's one pass reads that earlier pass's values and problems rather than validating
+ * them again.
  */
-async function readyDispatch({ graph, invocation, routed }, filled) {
-    const { command, path } = routed;
-    const { local } = filled;
-    const values = await validateValues({
-        command: path,
-        defaults: invocation.defaults,
+function validateInvocation({ graph, invocation, routed }, filled) {
+    const { local, only, sources } = filled;
+    const parsed = local.kind === 'parsed';
+    return validateValues({
+        command: routed.path,
+        declaredValues: invocation.declaredValues,
         host: invocation.host,
-        inputs: { globals: graph.globals.inputs, locals: command.inputs },
-        passthrough: local.passthrough,
-        plugins: graph.globals.plugins.flatMap((entry) => entry.inputs),
+        inputs: { globals: graph.globals.inputs, locals: parsed ? routed.command.inputs : [] },
+        passthrough: tailOf(local),
+        places: invocation.places,
         signal: invocation.signal,
-        sources: filled.sources,
-        supplied: { args: local.args, options: filled.values },
+        sources,
+        supplied: {
+            args: parsed ? local.args : new Map(),
+            options: parsed ? mergeValues(filled.values, filled.locals) : filled.values,
+        },
+        table: routed.command.table,
+        ...(only ? { only } : {}),
+        ...(sources.validated ? { prior: sources.validated } : {}),
     });
+}
+/**
+ * The dispatch a clean validation prepares. It answers with the call that dispatches, so the caller
+ * records that the action was invoked at the moment it invokes it and no earlier failure reads as a
+ * dispatch.
+ */
+function readyDispatch({ invocation, routed }, local, values) {
+    const { command, path } = routed;
     return {
         dispatch: async (view) => {
             // The channel is built at the boundary, because the view a middleware selected is read there.
@@ -1893,37 +1849,47 @@ async function readyDispatch({ graph, invocation, routed }, filled) {
 /**
  * Prepares one dispatch ahead of the middleware chain and holds whatever fault it found, so a
  * middleware reads the request before the action runs and a takeover never observes the fault.
- * The phases run in order: local parsing, the input-source stage, and validation. A local fault
- * outranks a configuration source's fault, and after either one core runs no validation.
+ * The phases run in order: the structural fault parsing held, a group's missing subcommand, the
+ * input-source stage, and validation. Either of the first two outranks a configuration source's
+ * fault, and a source's fault takes the place of every validation problem. Validation checks the
+ * global options whatever was held, so a middleware reads them after a local fault; a structural
+ * fault on a global option, a rejected global option, a source's fault, or a validator's own fault
+ * leaves `options` `null`.
  */
 export async function prepareDispatch(graph, routed, invocation) {
     const result = routed.command.result;
     const local = parseLocal(routed);
     const preparation = { graph, invocation, routed };
     const { globals, locals, sources } = await fillScope(preparation, local);
-    const held = (fault) => ({
-        fault,
+    const held = (fault, options) => ({
+        fault: local.kind === 'held' ? local.fault : fault,
         globals,
         kind: 'held',
+        options,
         request: null,
         result,
     });
-    if (local.kind === 'held') {
-        return held(local.fault);
-    }
     if (sources.fault) {
-        return held(sources.fault);
+        return held(sources.fault, null);
     }
     try {
-        const ready = await readyDispatch(preparation, {
+        const validation = await validateInvocation(preparation, {
             local,
+            locals,
             sources,
-            values: mergeValues(globals, locals),
+            values: globals,
         });
-        return { ...ready, globals, kind: 'ready', result };
+        const options = routed.globalFault || rejectsGlobal(validation)
+            ? null
+            : frozenValues(graph.globals.inputs, validation.values);
+        if (local.kind === 'held' || validation.failure) {
+            return held(validation.failure, options);
+        }
+        const ready = readyDispatch(preparation, local, validation.values);
+        return { ...ready, globals, kind: 'ready', options, result };
     }
     catch (error) {
         // The fault is held as a failure, so a throw from reading a validator's output is never offered.
-        return held(toFailure(error));
+        return held(toFailure(error), null);
     }
 }

package/dist/errors.d.ts

@@ -10,20 +10,6 @@ import type { InputIdentity } from './types.js';
  * keeps the raw value.
  */
 export declare function quoted(value: unknown): string;
-/**
- * The two short-group faults. A value option that is not last in its group names that option's
- * spelling; a group that mixes scopes names only the two letters that disagree, because the rest
- * of the group may hold an inline value. `token` keeps the whole group as the reported fact.
- */
-type ShortGroupFault = {
-    reason: 'value-position';
-    token: string;
-} | {
-    reason: 'mixed-scope';
-    token: string;
-    global: string;
-    other: string;
-};
 /**
  * The one message a distributed build shows an operator for a defect or a declaration fault: the
  * application name and a fixed phrase, with no reason, class name, code, or path.
@@ -123,24 +109,39 @@ export declare class UnknownOptionError extends UsageError {
     readonly spelling: string;
     constructor(spelling: string);
 }
+/**
+ * Where a missing value should have been: the words ran out, or the next word was an option word or
+ * the bare `--`, which is never a separate value, so the sentence names the attached form too.
+ */
+type MissingValueForm = 'attached' | 'separate';
 export declare class MissingValueError extends UsageError {
     readonly spelling: string;
-    constructor(spelling: string);
+    constructor(spelling: string, form?: MissingValueForm);
 }
-/** A Boolean spelling takes no value, so the token carried one the declaration cannot accept. */
+/**
+ * A Boolean or counted spelling takes no value, so the token carried one the declaration cannot
+ * accept. A counted option's sentence tells the operator to repeat the spelling instead, and `kind`
+ * chooses the sentence alone.
+ */
 export declare class UnexpectedValueError extends UsageError {
     readonly spelling: string;
     readonly value: string;
-    constructor(spelling: string, value: string);
+    constructor(spelling: string, value: string, kind?: 'boolean' | 'count');
 }
 export declare class RepeatedOptionError extends UsageError {
     readonly spelling: string;
     constructor(spelling: string);
 }
-export declare class ShortGroupError extends UsageError {
-    readonly token: string;
-    readonly reason: 'value-position' | 'mixed-scope';
-    constructor(fault: ShortGroupFault);
+/**
+ * An option word the Command routing reached does not declare, while a visible Command below it
+ * does, such as a Command's own option typed before its name, or a parent's own option the routed
+ * Command declares with another value class. `commands` holds each such Command's path from the
+ * root, in authoring order.
+ */
+export declare class MisplacedOptionError extends UsageError {
+    readonly spelling: string;
+    readonly commands: readonly (readonly string[])[];
+    constructor(spelling: string, commands: readonly (readonly string[])[]);
 }
 /**
  * Exit 1: the declaration is wrong, so the author reads its Developer Diagnostic. A rule and the