@loomcli/core 0.6.0 → 0.8.0

package/dist/command.js

@@ -1,18 +1,20 @@
 var _a, _b;
 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 { quoteString, spelled } from './diagnostic-text.js';
-import { asSentence, commandSentence, commandSubject, DeclarationError, NonCallableCommandError, quoted, ResultError, toFailure, UnexpectedArgumentError, UnknownCommandError, reasonOf, } from './errors.js';
+import { elided, quoteString, spelled } from './diagnostic-text.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, siteFinding, } from './facts.js';
-import { buildGlobals, checkLocalOptions } from './globals.js';
+import { checkDeprecated, checkDescription, checkHidden, checkNoListingFacts, declarerNote, siteFinding, } from './facts.js';
+import { buildGlobals, checkLocalOptions, frozenValues } from './globals.js';
 import { nameSharedAcrossKinds, optionDeclaredTwice, spellingTaken } from './input-rules.js';
-import { graphMismatch, nodeAt, resultNode, snapshot } from './inspect.js';
-import { checkOptionName, compileOptions, copyValues, emptyValues, extractGlobals, isOptionToken, mergeValues, parseInputs, spellingMark, } from './options.js';
-import { isPlainObject } from './plain.js';
+import { graphMismatch, nodeAt, resultNode } from './inspect.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 { captureConfig, checkInputConfig, 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.
@@ -73,16 +75,30 @@ export function commandPlacement(path, child) {
 function constructorFinding(name, options, mark) {
     return { arguments: callArguments(name, options), call: 'new Command', mark };
 }
-/** A named Command's options slot holds a plain options object, and never retired globals wiring. */
-function checkCommandOptions(name, options) {
-    if (options !== undefined && !isPlainObject(options)) {
-        throw new DeclarationError(notAnObject, {
+/**
+ * The one copy of the options that `new Command(name, options)` reads, taken once the name is
+ * judged: the options object and its `extensions` list, whose entries are what their factory built
+ * and are not copied. A read that throws is the unreadable fault of the options, a value that is not
+ * a plain object is the not-an-object fault, and a Command declared without options has none.
+ */
+function captureCommandOptions(name, options) {
+    if (options === undefined) {
+        return undefined;
+    }
+    return captureDeclaration(options, (copy, read) => {
+        read.nested(copy, 'extensions', shallowList);
+    }, {
+        notAnObject: () => new DeclarationError(notAnObject, {
             correction: 'Supply a Command options object.',
             findings: [constructorFinding(name, options, '1')],
             sentence: `${commandSentence(name)} declares options that are not an object.`,
-        });
-    }
-    if (isPlainObject(options) && 'globals' in options) {
+        }),
+        unreadable: unreadableArgument({ call: 'new Command', named: name, subject: commandSentence(name) }, 'options'),
+    });
+}
+/** A named Command's options never carry the retired globals wiring. */
+function checkCommandOptions(name, options) {
+    if ('globals' in options) {
         throw new DeclarationError(commandGlobals, {
             correction: 'Declare globals on the Application and register its environment.',
             findings: [constructorFinding(name, options, '1.globals')],
@@ -90,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
@@ -149,23 +161,28 @@ export function freshState(declaration) {
     };
 }
 /**
- * A named Command's own declaration, checked before the value exists: the name, the options slot,
- * the core facts, and the extension values the slot carries. A later change to the options object
- * the author passed changes nothing the declaration holds.
+ * A named Command's own declaration, checked before the value exists: the name, then the one copy
+ * of the options slot, its core facts, and the extension values it carries. A later change to the
+ * options object the author passed changes nothing the declaration holds.
  */
 function namedState(name, options) {
     if (!isPortableName(name)) {
+        // The options are read after the name is judged, so the name's finding prints them elided.
         throw new DeclarationError(portableName, {
             correction: portableNameCorrection,
-            findings: [constructorFinding(name, options, '0')],
+            findings: [
+                constructorFinding(name, options === undefined ? undefined : spelled(elided), '0'),
+            ],
             sentence: `Command name ${quoted(name)} is invalid.`,
         });
     }
-    checkCommandOptions(name, options);
-    const slot = isPlainObject(options) ? options : undefined;
+    const slot = captureCommandOptions(name, options);
+    if (slot !== undefined) {
+        checkCommandOptions(name, slot);
+    }
     const site = {
         at: '1',
-        declaration: { arguments: [name, options], call: 'new Command' },
+        declaration: { arguments: [name, slot], call: 'new Command' },
         subject: commandSentence(name),
     };
     // The facts are read in the order their diagnostics have always ranked.
@@ -214,13 +231,21 @@ 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);
 }
+/**
+ * The finding for an input whose name is invalid, marking the name. The config is read after the
+ * name is judged, so it prints elided.
+ */
+function nameFinding(path, input) {
+    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. */
 function localScope(name, path) {
     return { siteOf: (input) => inputSite(name, path, input), subject: commandSubject(name) };
@@ -296,8 +321,8 @@ 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 "=".',
-            findings: [inputFinding(path, input)],
+            correction: declaredNameCorrection,
+            findings: [nameFinding(path, input)],
             sentence: `${commandSentence(command.name)} declares an argument named ${quoted(input.name)}.`,
         });
     }
@@ -317,11 +342,13 @@ function checkArgumentName(command, declared, input) {
 export function declareArgument(state, declared) {
     // The call's own input is judged before the receiver's state, as alias() judges its names.
     // A name of another kind then reports as a declared name instead of failing to print in the order diagnostic.
-    // The config is judged right after its name, and only then captured.
+    // The config is read once right after its name is judged, and every later check reads that copy.
     const { name } = state;
     checkArgumentName({ name, path: pathOf(name), subject: commandSubject(name) }, [], declared);
-    checkInputConfig(declared, { call: 'argument', path: pathOf(name) });
-    const input = { ...declared, config: captureConfig(declared.config) };
+    const input = {
+        ...declared,
+        config: captureInputConfig(declared, { call: 'argument', path: pathOf(name) }),
+    };
     checkOpen(state, {
         arguments: [input.name, input.config],
         call: 'argument',
@@ -350,11 +377,14 @@ const noGlobals = { names: new Map(), options: new Map(), variables: new Map() }
  */
 export function declareOption(state, declared, table = noGlobals) {
     // The call's own input is judged before the receiver's state, as alias() judges its names.
-    // The config is judged right after its name, and only then captured.
-    checkOptionName(declared.name, inputSite(state.name, pathOf(state.name), declared));
-    checkInputConfig(declared, { call: 'option', path: pathOf(state.name) });
-    const input = { ...declared, config: captureConfig(declared.config) };
-    const site = inputSite(state.name, pathOf(state.name), input);
+    // The config is read once right after its name is judged, and every later check reads that copy.
+    const path = pathOf(state.name);
+    checkOptionName(declared.name, configUnread(inputSite(state.name, path, declared)));
+    const input = {
+        ...declared,
+        config: captureInputConfig(declared, { call: 'option', path }),
+    };
+    const site = inputSite(state.name, path, input);
     checkOpen(state, {
         arguments: [input.name, input.config],
         call: 'option',
@@ -406,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);
@@ -632,7 +661,7 @@ function checkGroup(state, place) {
         throw new DeclarationError(groupOption, {
             correction: 'Register an action or remove the option.',
             findings: [inputFinding(place.path, option, 'no action reads it')],
-            sentence: `${commandSentence(name)} declares option "${option.name}" but registers no action to receive it.`,
+            sentence: `${commandSentence(name)} declares option ${quoted(option.name)} but registers no action to receive it.`,
         });
     }
 }
@@ -694,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.
@@ -1045,13 +1074,13 @@ class AttachedCommandValue {
             checkArgumentName({ name, path, subject: commandSubject(name) }, [], raw);
         }
         else {
-            checkOptionName(raw.name, inputSite(declared.name, path, raw));
+            checkOptionName(raw.name, configUnread(inputSite(declared.name, path, raw)));
         }
-        checkInputConfig(raw, { call: raw.kind, path });
         // Each kind captures its own config, so the input keeps the pairing its kind declares.
+        const place = { call: raw.kind, path };
         const input = raw.kind === 'argument'
-            ? { ...raw, config: captureConfig(raw.config) }
-            : { ...raw, config: captureConfig(raw.config) };
+            ? { ...raw, config: captureInputConfig(raw, place) }
+            : { ...raw, config: captureInputConfig(raw, place) };
         return this.#derive({ identity, input, kind: 'input' }, { ...declared, inputs: [...declared.inputs, input] });
     }
     #derive(call, declared) {
@@ -1166,16 +1195,12 @@ function nameCollisionRule(declared, held) {
     }
     return declared === 'option' ? optionDeclaredTwice : argumentDeclaredTwice;
 }
-/** The note a finding for one hook-declared input carries. */
-function hookNote(identity) {
-    return `declared by plugin ${quoted(identity)}`;
-}
 /** The clause and the remedy an input another plugin's hook already declared earns. */
 function hookClause(earlier, path) {
     const { identity, input } = earlier;
     return {
         clause: `an ${input.kind} plugin ${quoted(identity)} declared through onCommandAttach`,
-        held: inputFinding(path, input, hookNote(identity)),
+        held: inputFinding(path, input, declarerNote(identity)),
         kind: input.kind,
         remedy: 'Install one of them.',
     };
@@ -1264,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) {
@@ -1285,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, hookNote(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, hookNote(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) {
@@ -1306,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;
@@ -1314,8 +1339,8 @@ function tableSpellings(globals) {
         const { owner, site } = entry;
         const note = owner.kind === 'plugin'
             ? `an option of plugin ${quoted(owner.identity)}`
-            : `the global option "${name}"`;
-        return spellingPlace(site, role, note);
+            : `the global option ${quoted(name)}`;
+        return spellingPlace(site, origin, note);
     };
 }
 /**
@@ -1342,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 "${name}"`);
+            : spellingPlace(scope.siteOf(local), origin, `the local option ${quoted(name)}`);
     });
     for (const entry of attached) {
         const { identity, input } = entry;
@@ -1354,7 +1379,7 @@ function checkAttachedInputs(declared, attached, place) {
         if (collision) {
             throw new DeclarationError(nameCollisionRule(input.kind, collision.kind), {
                 correction: collision.remedy,
-                findings: [inputFinding(path, input, hookNote(identity)), collision.held],
+                findings: [inputFinding(path, input, declarerNote(identity)), collision.held],
                 sentence: `Plugin ${quoted(identity)} declares ${input.kind} ${quoted(input.name)} on ${subject}, which is already declared as ${collision.clause}.`,
             });
         }
@@ -1375,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({
@@ -1470,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();
@@ -1496,9 +1522,9 @@ export function buildCommand(state, context) {
         hidden: facts.hidden,
         inputs: hooked.inputs,
         name,
-        options,
         result,
         routes,
+        table,
     };
 }
 /**
@@ -1594,7 +1620,7 @@ _b = CommandBuilder;
  */
 class CommandDeclaration extends CommandBuilder {
     constructor(name, options) {
-        const declared = namedState(name, options);
+        const declared = declaring(() => namedState(name, options));
         super(declared.name, declared.state);
     }
 }
@@ -1608,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]);
@@ -1627,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
@@ -1739,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
@@ -1777,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'
@@ -1803,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.
@@ -1864,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);
     }
 }