@loomcli/core 0.5.0 → 0.7.0

package/dist/command.js

@@ -1,13 +1,19 @@
 var _a, _b;
 import { checkEnvBinding, checkNoArgumentBinding } from './bindings.js';
-import { commandSentence, commandSubject, DeclarationError, InternalError, NonCallableCommandError, ResultError, UnexpectedArgumentError, UnknownCommandError, } from './errors.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 { buildExtensions, extendStore, publishStore, registerDescriptor, storeCommandLayers, validateLayer, } from './extension.js';
-import { checkDeprecated, checkDescription, checkHidden, checkNoListingFacts, isPlainObject, } from './facts.js';
+import { checkDeprecated, checkDescription, checkHidden, checkNoListingFacts, declarerNote, siteFinding, } from './facts.js';
 import { buildGlobals, checkLocalOptions } from './globals.js';
-import { nodeAt, resultNode, snapshot } from './inspect.js';
-import { compileOptions, copyValues, emptyValues, extractGlobals, isOptionToken, mergeValues, parseInputs, } from './options.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 { declaring, isPlainObject, shallowList, snapshot } from './plain.js';
+import { brokenAttachHook, notAnObject } from './plugin-rules.js';
 import { fillInputs } from './sources.js';
-import { captureConfig, checkDeclarations, validateValues } from './validation.js';
+import { captureInputConfig, configUnread, checkDeclarations, declaringSite, inputPlace, 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.
@@ -41,13 +47,62 @@ function nodeHandle(name, state) {
 export function commandNode(value) {
     return typeof value === 'object' && value !== null ? nodes.get(value) : undefined;
 }
-/** 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(`${commandSentence(name)} options must be an object. Supply a Command options object.`);
+/**
+ * The path a finding opens with for a declaration call on one Command. The root's is empty. A named
+ * Command's call cannot know the parent it will join, so its path is its own name.
+ */
+function pathOf(name) {
+    return name === null ? [] : [name];
+}
+/** A call's arguments as its author wrote them: the trailing ones left undefined are dropped. */
+export function callArguments(...values) {
+    let length = values.length;
+    while (length > 0 && values[length - 1] === undefined) {
+        length -= 1;
+    }
+    return values.slice(0, length);
+}
+/** A Command value as a finding prints it, which it would otherwise print as an ellipsis. */
+export function commandCode(name) {
+    return spelled(`new Command(${quoteString(name)})`);
+}
+/** The finding for one `command()` call that attached a child under the Command at `path`. */
+export function commandPlacement(path, child) {
+    return { arguments: [commandCode(child)], call: 'command', mark: '0', path };
+}
+/** The finding for one `new Command()` call, which carries the name and the options slot. */
+function constructorFinding(name, options, mark) {
+    return { arguments: callArguments(name, options), call: 'new Command', mark };
+}
+/**
+ * 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;
     }
-    if (isPlainObject(options) && 'globals' in options) {
-        throw new DeclarationError(`${commandSentence(name)} declares globals. Declare globals on the Application and register its environment.`);
+    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.`,
+        }),
+        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')],
+            sentence: `${commandSentence(name)} declares globals.`,
+        });
     }
 }
 /** One name rule for an argument, option, or view name: a bare token the parser can read. */
@@ -66,11 +121,25 @@ export function isPortableName(name) {
 /** The one correction every portable name diagnostic ends with. */
 export const portableNameCorrection = 'Use a nonempty name of A-Z, a-z, 0-9, ".", "_", and "-" that does not start with "-" or ".".';
 /** An alias is typed at the prompt the way a Command name is, so it answers to the portable rule. */
-function checkAliasName(command, alias) {
-    if (!isPortableName(alias)) {
-        throw new DeclarationError(`${commandSentence(command)} declares an alias named "${String(alias)}". ${portableNameCorrection}`);
+function checkAliasNames(command, names) {
+    for (const [index, alias] of names.entries()) {
+        if (!isPortableName(alias)) {
+            throw new DeclarationError(portableName, {
+                correction: portableNameCorrection,
+                findings: [{ arguments: names, call: 'alias', mark: String(index), path: pathOf(command) }],
+                sentence: `${commandSentence(command)} declares an alias named ${quoted(alias)}.`,
+            });
+        }
     }
 }
+/**
+ * The finding for the `alias()` call that declared one alias on the Command at `path`, rebuilt from
+ * every alias the Command holds.
+ */
+function aliasFinding(command, alias, note) {
+    const { aliases, path } = command;
+    return { arguments: aliases, call: 'alias', mark: String(aliases.indexOf(alias)), note, path };
+}
 /** How the extension diagnostics of one Command's own layers name it. */
 export function layerOf(name) {
     return { phrase: `on ${commandSubject(name)}`, sentence: commandSentence(name) };
@@ -95,25 +164,39 @@ 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)) {
-        throw new DeclarationError(`Command name "${String(name)}" is invalid. ${portableNameCorrection}`);
+        // 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 === undefined ? undefined : spelled(elided), '0'),
+            ],
+            sentence: `Command name ${quoted(name)} is invalid.`,
+        });
     }
-    checkCommandOptions(name, options);
-    const slot = isPlainObject(options) ? options : undefined;
-    const sentence = commandSentence(name);
+    const slot = captureCommandOptions(name, options);
+    if (slot !== undefined) {
+        checkCommandOptions(name, slot);
+    }
+    const site = {
+        at: '1',
+        declaration: { arguments: [name, slot], call: 'new Command' },
+        subject: commandSentence(name),
+    };
     // The facts are read in the order their diagnostics have always ranked.
-    const description = checkDescription(sentence, slot?.description);
-    const hidden = checkHidden(sentence, slot?.hidden);
-    const deprecated = checkDeprecated(sentence, slot?.deprecated);
+    const description = checkDescription(site, slot?.description);
+    const hidden = checkHidden(site, slot?.hidden);
+    const deprecated = checkDeprecated(site, slot?.deprecated);
     const descriptors = new Map();
     const extensions = storeCommandLayers({
         descriptors,
         layers: [slot?.extensions],
+        site: { ...site, at: '1.extensions' },
         subject: layerOf(name),
     });
     return {
@@ -130,16 +213,56 @@ function namedState(name, options) {
  * A declaration call after `action()` is an order fault the receiver's own earlier call makes
  * certain. The types remove the call for a TypeScript author; a JavaScript author meets it here.
  */
-function checkOpen(state, clause, remedy) {
+function checkOpen(state, late) {
     if (state.action !== undefined) {
-        throw new DeclarationError(`${commandSentence(state.name)} ${clause} after its action. ${remedy}`);
+        throw new DeclarationError(declaredAfterAction, {
+            correction: late.remedy,
+            findings: [
+                {
+                    arguments: late.arguments,
+                    call: late.call,
+                    mark: '0',
+                    note: 'after action()',
+                    path: pathOf(state.name),
+                },
+            ],
+            sentence: `${commandSentence(state.name)} ${late.clause} after its action.`,
+        });
     }
 }
 /** The remedy a late argument or option earns. */
 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)}`);
+}
+/** 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 }));
+    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, { global: false, 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) };
+}
 /** One Command declares arguments or attaches children, whichever call came second. */
-function placementFault(name, argument, child) {
-    return new DeclarationError(`${commandSentence(name)} declares argument "${argument}" and attaches child "${child}". Move the argument into a child Command or remove the children.`);
+function placementFault(parent, argument, child) {
+    return new DeclarationError(argumentsBesideChildren, {
+        correction: 'Move the argument into a child Command or remove the children.',
+        findings: [
+            inputFinding(parent.path, argument, 'the argument'),
+            { ...child.placement, note: 'the child' },
+        ],
+        sentence: `${commandSentence(parent.name)} declares argument "${argument.name}" and attaches child "${child.name}".`,
+    });
 }
 /** The options one declaration list holds, in declaration order. */
 function optionsOf(inputs) {
@@ -163,6 +286,7 @@ function recordInput(state, input) {
     const record = buildExtensions({
         declared: input.config.extensions,
         descriptors,
+        site: { ...inputSite(name, pathOf(name), input), at: '1.extensions' },
         subject: {
             phrase: `on ${commandSubject(name)} ${input.kind} "${input.name}"`,
             sentence: `${commandSentence(name)} ${input.kind} "${input.name}"`,
@@ -177,31 +301,63 @@ function recordInput(state, input) {
  */
 function checkArgument(state, input) {
     const { name } = state;
-    const subject = commandSubject(name);
-    if (!isDeclaredName(input.name)) {
-        throw new DeclarationError(`${commandSentence(name)} declares an argument named "${String(input.name)}". Use a nonempty name without a leading hyphen, whitespace, or "=".`);
-    }
+    const path = pathOf(name);
+    const command = { name, path, subject: commandSubject(name) };
     const declared = state.inputs.filter((entry) => entry.kind === 'argument');
-    if (declared.some((entry) => entry.name === input.name)) {
-        throw new DeclarationError(`Argument "${input.name}" is declared more than once on ${subject}. Remove or rename the duplicate.`);
-    }
+    checkArgumentName(command, declared, input);
     const child = state.children[0];
     if (child) {
-        throw placementFault(name, input.name, child.name);
+        throw placementFault(command, input, child);
     }
     const previous = declared.at(-1);
     if (previous) {
-        checkSlotOrder(slotOf(previous), slotOf(input), subject);
+        checkSlotOrder(slotOf(previous), slotOf(input), command);
+    }
+    const site = inputSite(name, path, input);
+    checkDescription(site, input.config.description);
+    checkNoListingFacts(site, input.config);
+    checkNoArgumentBinding(site, input.config);
+    checkDeclarations([{ input, site }]);
+}
+/** One argument's name answers the declared-name rule and names no argument declared before it. */
+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: [nameFinding(path, input)],
+            sentence: `${commandSentence(command.name)} declares an argument named ${quoted(input.name)}.`,
+        });
+    }
+    const first = declared.find((entry) => entry.name === input.name);
+    if (first) {
+        throw new DeclarationError(argumentDeclaredTwice, {
+            correction: 'Remove or rename the duplicate.',
+            findings: [
+                inputFinding(path, first, 'the first declaration'),
+                inputFinding(path, input, 'the second declaration'),
+            ],
+            sentence: `Argument "${input.name}" is declared more than once on ${command.subject}.`,
+        });
     }
-    const sentence = `${commandSentence(name)} argument "${input.name}"`;
-    checkDescription(sentence, input.config.description);
-    checkNoListingFacts(sentence, input.config);
-    checkNoArgumentBinding(sentence, input.config);
-    checkDeclarations([input]);
 }
 /** The declared value joins `args` under its literal name, typed by its own config. */
-export function declareArgument(state, input) {
-    checkOpen(state, `declares argument "${input.name}"`, inputRemedy);
+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 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);
+    const input = {
+        ...declared,
+        config: captureInputConfig(declared, { call: 'argument', path: pathOf(name) }),
+    };
+    checkOpen(state, {
+        arguments: [input.name, input.config],
+        call: 'argument',
+        clause: `declares argument ${quoted(input.name)}`,
+        remedy: inputRemedy,
+    });
     checkArgument(state, input);
     const recorded = recordInput(state, input);
     const previous = state.bind;
@@ -222,16 +378,29 @@ const noGlobals = { names: new Map(), options: new Map(), variables: new Map() }
  * options also meet the Application's globals table, which a named Command meets when its subtree
  * joins an Application.
  */
-export function declareOption(state, input, table = noGlobals) {
-    checkOpen(state, `declares option "${input.name}"`, inputRemedy);
-    const sentence = `${commandSentence(state.name)} option "${input.name}"`;
-    checkDescription(sentence, input.config.description);
-    checkHidden(sentence, input.config.hidden);
-    checkDeprecated(sentence, input.config.deprecated);
-    checkEnvBinding(sentence, input.config);
+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 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',
+        clause: `declares option ${quoted(input.name)}`,
+        remedy: inputRemedy,
+    });
+    checkDescription(site, input.config.description);
+    checkHidden(site, input.config.hidden);
+    checkDeprecated(site, input.config.deprecated);
+    checkEnvBinding(site, input.config);
     const recorded = recordInput(state, input);
-    checkLocalOptions([...optionsOf(state.inputs), input], table, commandSubject(state.name));
-    checkDeclarations([input]);
+    checkLocalOptions([...optionsOf(state.inputs), input], table, localScope(state.name, pathOf(state.name)));
+    checkDeclarations([{ input, site }]);
     const previous = state.bind;
     return {
         ...state,
@@ -249,23 +418,40 @@ export function declareOption(state, input, table = noGlobals) {
  */
 export function declareAlias(state, names) {
     const { name } = state;
+    const path = pathOf(name);
     const first = names[0];
     if (first === undefined) {
-        throw new DeclarationError(`${commandSentence(name)} declares an alias with no names. Supply at least one name.`);
+        throw new DeclarationError(aliasWithoutNames, {
+            correction: 'Supply at least one name.',
+            findings: [{ arguments: [], call: 'alias', path }],
+            sentence: `${commandSentence(name)} declares an alias with no names.`,
+        });
     }
     // The call's own input is judged before the receiver's state.
     // A non-string name then reports as an alias name instead of failing to print in the order diagnostic.
-    for (const alias of names) {
-        checkAliasName(name, alias);
-    }
-    checkOpen(state, `declares alias "${first}"`, 'Declare aliases before action().');
+    checkAliasNames(name, names);
+    checkOpen(state, {
+        arguments: names,
+        call: 'alias',
+        clause: `declares alias "${first}"`,
+        remedy: 'Declare aliases before action().',
+    });
     const aliases = [...state.aliases];
-    for (const alias of names) {
+    for (const [index, alias] of names.entries()) {
+        const repeated = { arguments: names, call: 'alias', mark: String(index), path };
         if (alias === name) {
-            throw new DeclarationError(`${commandSentence(name)} declares alias "${alias}", which is its own name. Remove the alias.`);
+            throw new DeclarationError(repeatedAlias, {
+                correction: 'Remove the alias.',
+                findings: [{ ...repeated, note: 'its own name' }],
+                sentence: `${commandSentence(name)} declares alias "${alias}", which is its own name.`,
+            });
         }
         if (aliases.includes(alias)) {
-            throw new DeclarationError(`${commandSentence(name)} declares alias "${alias}" twice. Remove the repeated alias.`);
+            throw new DeclarationError(repeatedAlias, {
+                correction: 'Remove the repeated alias.',
+                findings: [{ ...repeated, note: 'already an alias' }],
+                sentence: `${commandSentence(name)} declares alias "${alias}" twice.`,
+            });
         }
         aliases.push(alias);
     }
@@ -280,6 +466,7 @@ export function declareExtensions(state, values) {
     const layer = validateLayer({
         declared: values,
         descriptors,
+        site: { at: '', declaration: { arguments: values, call: 'extend', path: pathOf(state.name) } },
         subject: layerOf(state.name),
         target: 'command',
     });
@@ -299,7 +486,19 @@ function declaredChannel(out) {
  */
 export function declareAction(state, handler) {
     if (state.action !== undefined) {
-        throw new DeclarationError(`${commandSentence(state.name)} has multiple actions. Register one action.`);
+        throw new DeclarationError(multipleActions, {
+            correction: 'Register one action.',
+            findings: [
+                {
+                    arguments: [handler],
+                    call: 'action',
+                    mark: '0',
+                    note: 'the second action',
+                    path: pathOf(state.name),
+                },
+            ],
+            sentence: `${commandSentence(state.name)} has multiple actions.`,
+        });
     }
     // The graph and the routed node stay getters, because a spread would build the graph on every run.
     const stored = (context) => handler({
@@ -324,33 +523,71 @@ export function declareAction(state, handler) {
  * here; the empty record and the default wait for attach, because `views()` can still add keys.
  */
 export function declareResult(state, kind, declaration) {
-    checkOpen(state, 'declares its result', 'Declare result() or rows() before action().');
-    const results = [...state.results, { kind, views: recordOf(declaration, 'views') }];
-    mergeResult(state.name, results);
+    const call = {
+        arguments: callArguments(declaration),
+        kind,
+        views: recordOf(declaration, 'views'),
+    };
+    checkOpen(state, {
+        arguments: call.arguments,
+        call: resultCallName(call),
+        clause: 'declares its result',
+        remedy: 'Declare result() or rows() before action().',
+    });
+    const results = [...state.results, call];
+    mergeResult({ name: state.name, path: pathOf(state.name) }, results);
     return { ...state, results };
 }
 /** A `views()` call reshapes views and closes nothing, so it is never a late declaration. */
 export function declareResultViews(state, replacements, options) {
-    const results = [
-        ...state.results,
-        { default: recordOf(options, 'default'), kind: 'views', views: replacements },
-    ];
-    mergeResult(state.name, results);
+    const results = [...state.results, viewsCall(replacements, options)];
+    mergeResult({ name: state.name, path: pathOf(state.name) }, results);
     return { ...state, results };
 }
+/** One `views()` call as the results lane records it. */
+function viewsCall(replacements, options) {
+    return {
+        arguments: callArguments(replacements, options),
+        default: recordOf(options, 'default'),
+        kind: 'views',
+        views: replacements,
+    };
+}
 /** One property of an authoring argument, read defensively: the rules report whatever it holds. */
 function recordOf(declaration, key) {
     return isPlainObject(declaration) ? declaration[key] : undefined;
 }
+/** The authoring call one results-lane call was made through. */
+function resultCallName(call) {
+    return call.kind === 'value' ? 'result' : call.kind;
+}
+/** The finding for one results-lane call on the Command at `path`, marking one of its arguments. */
+function resultFinding(path, call, mark) {
+    const finding = { arguments: call.arguments, call: resultCallName(call), mark: mark.at, path };
+    return mark.note === undefined ? finding : { ...finding, note: mark.note };
+}
+/** Where one views entry sits among its call's arguments: in `views` for a declaration, or first. */
+function entryMark(call, key) {
+    return call.kind === 'views' ? `0.${key}` : `0.views.${key}`;
+}
 /** The parent a declaration is, as attach reads it. */
 function parentOf(state) {
     return {
-        argument: state.inputs.find((input) => input.kind === 'argument')?.name,
+        argument: state.inputs.find((input) => input.kind === 'argument'),
         children: state.children,
         hasAction: state.action !== undefined,
         name: state.name,
+        path: pathOf(state.name),
     };
 }
+/** The path one child sits at under its parent. */
+function childPath(parent, child) {
+    return [...parent.path, child];
+}
+/** The call that attached one child, noted with the child's name. */
+function childFinding(entry) {
+    return { ...entry.placement, note: `child "${entry.name}"` };
+}
 /**
  * One parent's namespace, which every canonical name and alias under it shares. The rule reads the
  * same whichever sibling the author attached first.
@@ -358,21 +595,41 @@ function parentOf(state) {
 function checkSiblings(parent, child) {
     const sentence = commandSentence(parent.name);
     const { children } = parent;
-    if (children.some((entry) => entry.name === child.name)) {
-        throw new DeclarationError(`${sentence} attaches two children named "${child.name}". Rename or remove one.`);
+    const aliased = (entry, alias) => aliasFinding({ aliases: entry.node.declared.aliases, path: childPath(parent, entry.name) }, alias, `alias of child "${entry.name}"`);
+    const correction = 'Rename or remove one.';
+    const twin = children.find((entry) => entry.name === child.name);
+    if (twin) {
+        throw new DeclarationError(siblingNameTaken, {
+            correction,
+            findings: [childFinding(twin), childFinding(child)],
+            sentence: `${sentence} attaches two children named "${child.name}".`,
+        });
     }
     for (const alias of child.node.declared.aliases) {
-        if (children.some((entry) => entry.name === alias)) {
-            throw new DeclarationError(`${sentence} attaches child "${child.name}" with alias "${alias}", which is also the name of child "${alias}". Rename or remove one.`);
+        const holder = children.find((entry) => entry.name === alias);
+        if (holder) {
+            throw new DeclarationError(siblingNameTaken, {
+                correction,
+                findings: [childFinding(holder), aliased(child, alias)],
+                sentence: `${sentence} attaches child "${child.name}" with alias "${alias}", which is also the name of child "${alias}".`,
+            });
         }
         const owner = children.find((entry) => entry.node.declared.aliases.includes(alias));
         if (owner) {
-            throw new DeclarationError(`${sentence} attaches child "${child.name}" with alias "${alias}", which is also an alias of child "${owner.name}". Rename or remove one.`);
+            throw new DeclarationError(siblingNameTaken, {
+                correction,
+                findings: [aliased(owner, alias), aliased(child, alias)],
+                sentence: `${sentence} attaches child "${child.name}" with alias "${alias}", which is also an alias of child "${owner.name}".`,
+            });
         }
     }
-    const aliased = children.find((entry) => entry.node.declared.aliases.includes(child.name));
-    if (aliased) {
-        throw new DeclarationError(`${sentence} attaches child "${aliased.name}" with alias "${child.name}", which is also the name of child "${child.name}". Rename or remove one.`);
+    const owner = children.find((entry) => entry.node.declared.aliases.includes(child.name));
+    if (owner) {
+        throw new DeclarationError(siblingNameTaken, {
+            correction,
+            findings: [aliased(owner, child.name), childFinding(child)],
+            sentence: `${sentence} attaches child "${owner.name}" with alias "${child.name}", which is also the name of child "${child.name}".`,
+        });
     }
 }
 /**
@@ -381,7 +638,11 @@ function checkSiblings(parent, child) {
  */
 function checkNesting(parent, child, level) {
     if (level >= nestingCap.depth && child.node.declared.children.length > 0) {
-        throw new DeclarationError(`${commandSentence(parent)} attaches child "${child.name}", which has children of its own. Nest Commands at most ${nestingCap.words} levels below the root.`);
+        throw new DeclarationError(nestingDepth, {
+            correction: `Nest Commands at most ${nestingCap.words} levels below the root.`,
+            findings: [{ ...child.placement, note: 'has children of its own' }],
+            sentence: `${commandSentence(parent)} attaches child "${child.name}", which has children of its own.`,
+        });
     }
 }
 /**
@@ -389,14 +650,23 @@ function checkNesting(parent, child, level) {
  * children. A group with no children receives an invocation no handler can answer, and a local
  * option on a group reaches no handler either, because locals never inherit.
  */
-function checkGroup(state) {
+function checkGroup(state, place) {
     const { name } = state;
     if (state.children.length === 0) {
-        throw new DeclarationError(`${commandSentence(name)} has no action. Register an action.`);
+        const { placement } = place;
+        throw new DeclarationError(commandWithoutAction, {
+            correction: 'Register an action.',
+            findings: placement === undefined ? [] : [{ ...placement, note: 'no action and no children' }],
+            sentence: `${commandSentence(name)} has no action.`,
+        });
     }
     const option = state.inputs.find((input) => input.kind === 'option');
     if (option) {
-        throw new DeclarationError(`${commandSentence(name)} declares option "${option.name}" but registers no action to receive it. Register an action or remove the option.`);
+        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 ${quoted(option.name)} but registers no action to receive it.`,
+        });
     }
 }
 /**
@@ -404,10 +674,10 @@ function checkGroup(state) {
  * result needs an action, its merged views record names at least one view and its default, and a
  * Command without an action is a group. It answers with the resolved result.
  */
-function checkFinished(declared, hasAction) {
-    const result = buildResult(declared, hasAction);
+function checkFinished(declared, hasAction, place) {
+    const result = buildResult(declared, hasAction, place.path);
     if (!hasAction) {
-        checkGroup(declared);
+        checkGroup(declared, place);
     }
     return result;
 }
@@ -415,18 +685,23 @@ function checkFinished(declared, hasAction) {
  * The one attach operation `Command.command()`, `Application.command()`, and a plugin's
  * `commands` list share. A Command is an immutable value, so the child is final here: it is checked
  * as a finished Command, against the parent's current children, and against the nesting cap from
- * the shallowest level the parent can sit at.
+ * the shallowest level the parent can sit at. The placement is the call that attached it, which a
+ * finding about the child as a whole marks.
  */
-export function attach(parent, node) {
+export function attach(parent, node, placement) {
     const { name } = node;
+    const child = { name, node, placement };
     if (parent.hasAction) {
-        throw new DeclarationError(`${commandSentence(parent.name)} attaches child "${name}" after its action. Attach children before action().`);
+        throw new DeclarationError(declaredAfterAction, {
+            correction: 'Attach children before action().',
+            findings: [{ ...placement, note: 'after action()' }],
+            sentence: `${commandSentence(parent.name)} attaches child "${name}" after its action.`,
+        });
     }
     if (parent.argument !== undefined) {
-        throw placementFault(parent.name, parent.argument, name);
+        throw placementFault(parent, parent.argument, child);
     }
-    checkFinished(node.declared, node.hasAction);
-    const child = { name, node };
+    checkFinished(node.declared, node.hasAction, { path: childPath(parent, name), placement });
     checkSiblings(parent, child);
     checkNesting(parent.name, child, parentLevel(parent.name) + 1);
     return child;
@@ -435,13 +710,18 @@ export function attach(parent, node) {
 export function childNode(parent, child) {
     const node = commandNode(child);
     if (!node) {
-        throw new DeclarationError(`${commandSentence(parent)} attaches a value that is not a Command. Attach the value returned by new Command(name).`);
+        throw new DeclarationError(notACommand, {
+            correction: 'Attach the value returned by new Command(name).',
+            findings: [{ arguments: [child], call: 'command', mark: '0', path: pathOf(parent) }],
+            sentence: `${commandSentence(parent)} attaches a value that is not a Command.`,
+        });
     }
     return node;
 }
 /** Attaching is a declaration call too, so the receiver keeps the children it already had. */
 function attachChild(state, child) {
-    const attached = attach(parentOf(state), childNode(state.name, child));
+    const node = childNode(state.name, child);
+    const attached = attach(parentOf(state), node, commandPlacement(pathOf(state.name), node.name));
     return { ...state, children: [...state.children, attached] };
 }
 /**
@@ -453,34 +733,47 @@ function attachChild(state, child) {
  * here fires only once the cap rises: attach reads one level, and only this walk knows each level.
  */
 function joinSubtree(scope, child, { level, parent }) {
-    const { name, node } = child;
-    checkNesting(parent, child, level);
-    if (scope.owners.has(node)) {
-        throw new DeclarationError(`${commandSentence(parent)} attaches child "${name}", which ${commandSubject(scope.owners.get(node) ?? null)} also attaches. Attach a Command value at one point; create a new Command for each placement.`);
+    const { name, node, placement } = child;
+    checkNesting(parent.name, child, level);
+    const owner = scope.owners.get(node);
+    if (owner) {
+        throw new DeclarationError(commandAttachedTwice, {
+            correction: 'Attach a Command value at one point; create a new Command for each placement.',
+            findings: [
+                { ...owner.placement, note: 'the first placement' },
+                { ...placement, note: 'the second placement' },
+            ],
+            sentence: `${commandSentence(parent.name)} attaches child "${name}", which ${commandSubject(owner.name)} also attaches.`,
+        });
     }
-    scope.owners.set(node, parent);
-    for (const descriptor of node.declared.descriptors.values()) {
-        registerDescriptor(scope.descriptors, descriptor);
+    scope.owners.set(node, { name: parent.name, placement });
+    for (const [key, descriptor] of node.declared.descriptors) {
+        registerDescriptor(scope.descriptors, descriptor, { identity: key });
     }
-    checkLocalOptions(optionsOf(node.declared.inputs), scope.table, commandSubject(name));
+    const path = childPath(parent, name);
+    checkLocalOptions(optionsOf(node.declared.inputs), scope.table, localScope(name, path));
     for (const entry of node.declared.children) {
-        joinSubtree(scope, entry, { level: level + 1, parent: name });
+        // A nested child's own placement knew its parent alone, so the walk places it under the root.
+        const rooted = { ...entry, placement: commandPlacement(path, entry.name) };
+        joinSubtree(scope, rooted, { level: level + 1, parent: { name, path } });
     }
 }
 /**
  * Attaches one child to an Application's root and walks the subtree it brings, once. The scope's
  * registers are copies: the caller commits the owners, and the returned root holds the descriptors.
  */
-export function attachToRoot(state, node, scope) {
-    const attached = attach(parentOf(state), node);
-    joinSubtree(scope, attached, { level: parentLevel(state.name) + 1, parent: state.name });
+export function attachToRoot(state, child, scope) {
+    const parent = parentOf(state);
+    const attached = attach(parent, child.node, child.placement);
+    joinSubtree(scope, attached, { level: parentLevel(state.name) + 1, parent });
     return { ...state, children: [...state.children, attached], descriptors: scope.descriptors };
 }
 /** Every attached Command's local options against a globals table that has just grown. */
-function checkAttachedOptions(table, children) {
+function checkAttachedOptions(table, parent, children) {
     for (const { name, node } of children) {
-        checkLocalOptions(optionsOf(node.declared.inputs), table, commandSubject(name));
-        checkAttachedOptions(table, node.declared.children);
+        const path = childPath(parent, name);
+        checkLocalOptions(optionsOf(node.declared.inputs), table, localScope(name, path));
+        checkAttachedOptions(table, { name, path }, node.declared.children);
     }
 }
 /**
@@ -488,42 +781,54 @@ function checkAttachedOptions(table, children) {
  * grown. The table's new option reads as the other side of any collision.
  */
 export function checkDeclaredOptions(state, table) {
-    checkLocalOptions(optionsOf(state.inputs), table, commandSubject(state.name));
-    checkAttachedOptions(table, state.children);
+    const place = { name: state.name, path: pathOf(state.name) };
+    checkLocalOptions(optionsOf(state.inputs), table, localScope(place.name, place.path));
+    checkAttachedOptions(table, place, state.children);
 }
 /** A variadic or optional slot ends the positional list, so nothing may follow either one. */
-function checkSlotOrder(slot, next, subject) {
+function checkSlotOrder(slot, next, command) {
+    const { path, subject } = command;
+    const after = inputFinding(path, next.input, 'the argument after it');
     if (slot.variadic) {
-        throw new DeclarationError(`Argument "${slot.input.name}" is variadic and precedes argument "${next.input.name}" on ${subject}. Declare the variadic argument last.`);
+        throw new DeclarationError(variadicArgumentLast, {
+            correction: 'Declare the variadic argument last.',
+            findings: [inputFinding(path, slot.input, 'the variadic argument'), after],
+            sentence: `Argument "${slot.input.name}" is variadic and precedes argument "${next.input.name}" on ${subject}.`,
+        });
     }
     if (!slot.required) {
-        throw new DeclarationError(next.required
-            ? `Argument "${slot.input.name}" is optional and precedes required argument "${next.input.name}" on ${subject}. Declare optional arguments after required ones.`
-            : `Argument "${next.input.name}" follows optional argument "${slot.input.name}" on ${subject}. Declare an optional argument last.`);
+        const findings = [inputFinding(path, slot.input, 'the optional argument'), after];
+        throw new DeclarationError(optionalArgumentLast, next.required
+            ? {
+                correction: 'Declare optional arguments after required ones.',
+                findings,
+                sentence: `Argument "${slot.input.name}" is optional and precedes required argument "${next.input.name}" on ${subject}.`,
+            }
+            : {
+                correction: 'Declare an optional argument last.',
+                findings,
+                sentence: `Argument "${next.input.name}" follows optional argument "${slot.input.name}" on ${subject}.`,
+            });
     }
 }
 /**
  * The positional slots one declaration holds. Every authored argument answered these rules at its
  * own call, so they throw here only for an argument a lifecycle hook declared.
  */
-function collectArguments(state, subject) {
+function collectArguments(state, command) {
     const slots = [];
-    const seen = new Set();
+    const declared = [];
+    const judged = { ...command, subject: commandSubject(command.name) };
     for (const input of state.inputs.filter((entry) => entry.kind === 'argument')) {
-        if (!isDeclaredName(input.name)) {
-            throw new DeclarationError(`${commandSentence(state.name)} declares an argument named "${String(input.name)}". Use a nonempty name without a leading hyphen, whitespace, or "=".`);
-        }
-        if (seen.has(input.name)) {
-            throw new DeclarationError(`Argument "${input.name}" is declared more than once on ${subject}. Remove or rename the duplicate.`);
-        }
-        seen.add(input.name);
+        checkArgumentName(judged, declared, input);
+        declared.push(input);
         slots.push(slotOf(input));
     }
     for (let index = 0; index + 1 < slots.length; index += 1) {
         const slot = slots[index];
         const next = slots[index + 1];
         if (slot && next) {
-            checkSlotOrder(slot, next, subject);
+            checkSlotOrder(slot, next, judged);
         }
     }
     return slots;
@@ -564,23 +869,36 @@ function recordEntries(record) {
  * One `views` entry under the unit its declaration named, read back as the shape its own functions
  * name. The two shapes are exclusive, and a row view answers a rows declaration alone.
  */
-function resultView(declaration, name, entry) {
-    const { kind, sentence } = declaration;
+function resultView(kind, site, entry) {
+    const { call, key, path, sentence } = site;
+    const findings = [resultFinding(path, call, { at: entryMark(call, key) })];
     const whole = isWholeView(entry);
     const row = isRowView(entry);
     if (whole && row) {
-        throw new DeclarationError(`${sentence} names view "${name}" with render and row. Supply one of the two.`);
+        throw new DeclarationError(viewShape, {
+            correction: 'Supply one of the two.',
+            findings,
+            sentence: `${sentence} names view ${quoted(key)} with render and row.`,
+        });
     }
     if (row) {
         if (kind === 'value') {
-            throw new DeclarationError(`${sentence} names row view "${name}" on a value result. Supply a view with render, or declare the result with rows().`);
+            throw new DeclarationError(rowViewOnValue, {
+                correction: 'Supply a view with render, or declare the result with rows().',
+                findings,
+                sentence: `${sentence} names row view ${quoted(key)} on a value result.`,
+            });
         }
         return entry;
     }
     if (whole) {
         return entry;
     }
-    throw new DeclarationError(`${sentence} names view "${name}" with a value that is not a view. Supply a view with render or a row view with row.`);
+    throw new DeclarationError(viewShape, {
+        correction: 'Supply a view with render or a row view with row.',
+        findings,
+        sentence: `${sentence} names view ${quoted(key)} with a value that is not a view.`,
+    });
 }
 /**
  * Every rule a results-lane call can judge on its own, applied to one Command's calls in the order
@@ -588,18 +906,31 @@ function resultView(declaration, name, entry) {
  * place and appends a new one, so each name keeps the position the call that first named it gave
  * it. A `default` once named persists through later calls that name none.
  */
-function mergeResult(name, results) {
-    const sentence = commandSentence(name);
+function mergeResult(command, results) {
+    const { path } = command;
+    const sentence = commandSentence(command.name);
     const declarations = results.filter((call) => call.kind !== 'views');
-    if (declarations.length > 1) {
-        throw new DeclarationError(`${sentence} declares two results. Declare one result() or rows() call.`);
+    const [declaration, second] = declarations;
+    if (declaration && second) {
+        throw new DeclarationError(multipleResults, {
+            correction: 'Declare one result() or rows() call.',
+            findings: [
+                resultFinding(path, declaration, { at: '0', note: 'the first result' }),
+                resultFinding(path, second, { at: '0', note: 'the second result' }),
+            ],
+            sentence: `${sentence} declares two results.`,
+        });
     }
-    const declaration = declarations[0];
     // A `views()` call reshapes a result's views, so one with no result reshapes nothing.
     // The types publish the call where a result is carried, so this reaches a JavaScript author.
     if (!declaration) {
-        if (results.length > 0) {
-            throw new DeclarationError(`${sentence} reshapes its views and declares no result. Declare result() or rows() before action().`);
+        const [reshape] = results;
+        if (reshape) {
+            throw new DeclarationError(viewsWithoutResult, {
+                correction: 'Declare result() or rows() before action().',
+                findings: [resultFinding(path, reshape, { at: '0' })],
+                sentence: `${sentence} reshapes its views and declares no result.`,
+            });
         }
         return undefined;
     }
@@ -607,40 +938,57 @@ function mergeResult(name, results) {
     let selected = undefined;
     for (const call of results) {
         for (const [key, entry] of recordEntries(call.views)) {
-            const view = resultView({ kind: declaration.kind, sentence }, key, entry);
+            const view = resultView(declaration.kind, { call, key, path, sentence }, entry);
             if (!isViewName(key)) {
-                throw new DeclarationError(`${sentence} names view "${key}". Use a nonempty name without whitespace, a leading hyphen, or "=", and not a number.`);
+                throw new DeclarationError(viewName, {
+                    correction: 'Use a nonempty name without whitespace, a leading hyphen, or "=", and not a number.',
+                    findings: [resultFinding(path, call, { at: entryMark(call, key) })],
+                    sentence: `${sentence} names view ${quoted(key)}.`,
+                });
             }
             views.set(key, view);
         }
-        if (call.kind === 'views') {
-            selected = selectedKey(call.default) ?? selected;
+        const key = call.kind === 'views' ? selectedKey(call.default) : undefined;
+        if (key !== undefined) {
+            selected = { call, key };
         }
     }
-    return { kind: declaration.kind, selected, views };
+    return { declaration, kind: declaration.kind, selected, views };
 }
 /**
  * The finished result: the merged record, which needs an action, at least one view, and a default
  * that names one of them. The first key answers until one is named.
  */
-function buildResult(declared, hasAction) {
-    const merged = mergeResult(declared.name, declared.results);
+function buildResult(declared, hasAction, path) {
+    const merged = mergeResult({ name: declared.name, path }, declared.results);
     if (!merged) {
         return undefined;
     }
     const sentence = commandSentence(declared.name);
+    const { declaration, selected, views } = merged;
     if (!hasAction) {
-        throw new DeclarationError(`${sentence} declares a result and no action. Register an action or remove the result.`);
+        throw new DeclarationError(resultWithoutAction, {
+            correction: 'Register an action or remove the result.',
+            findings: [resultFinding(path, declaration, { at: '0' })],
+            sentence: `${sentence} declares a result and no action.`,
+        });
     }
-    const { selected, views } = merged;
     const first = views.keys().next();
     if (first.done === true) {
-        throw new DeclarationError(`${sentence} declares a result with no views. Name at least one view.`);
+        throw new DeclarationError(resultWithoutViews, {
+            correction: 'Name at least one view.',
+            findings: [resultFinding(path, declaration, { at: '0.views' })],
+            sentence: `${sentence} declares a result with no views.`,
+        });
     }
-    if (selected !== undefined && !views.has(selected)) {
-        throw new DeclarationError(`${sentence} selects default view "${selected}", which it does not name. Name the view or select a named one.`);
+    if (selected !== undefined && !views.has(selected.key)) {
+        throw new DeclarationError(unknownDefaultView, {
+            correction: 'Name the view or select a named one.',
+            findings: [resultFinding(path, selected.call, { at: '1.default' })],
+            sentence: `${sentence} selects default view ${quoted(selected.key)}, which it does not name.`,
+        });
     }
-    return { default: selected ?? first.value, kind: merged.kind, views };
+    return { default: selected?.key ?? first.value, kind: merged.kind, views };
 }
 /** The values one build made, so a value a hook returns is one of them and never a forged shape. */
 const attachments = new WeakMap();
@@ -663,7 +1011,7 @@ class AttachedCommandValue {
     #result;
     constructor(state) {
         this.#state = state;
-        this.#result = resultNode(buildResult(state.declared, state.hasAction));
+        this.#result = resultNode(buildResult(state.declared, state.hasAction, state.path));
         attachments.set(this, state);
         Object.freeze(this);
     }
@@ -690,17 +1038,13 @@ class AttachedCommandValue {
         return publishStore(this.#state.extensions);
     }
     argument(name, config) {
-        return this.#declare({ config: captureConfig(config), kind: 'argument', name });
+        return this.#declare({ config, kind: 'argument', name });
     }
     option(name, config) {
-        return this.#declare({ config: captureConfig(config), kind: 'option', name });
+        return this.#declare({ config, kind: 'option', name });
     }
     views(replacements, options) {
-        const call = {
-            default: recordOf(options, 'default'),
-            kind: 'views',
-            views: replacements,
-        };
+        const call = viewsCall(replacements, options);
         const { declared } = this.#state;
         return this.#derive({ call, kind: 'views' }, { ...declared, results: [...declared.results, call] });
     }
@@ -714,6 +1058,7 @@ class AttachedCommandValue {
         const layer = validateLayer({
             declared: values,
             descriptors: registry,
+            site: { at: '', declaration: { arguments: values, call: 'extend', path: state.path } },
             subject: state.subject,
             target: 'command',
         });
@@ -724,8 +1069,22 @@ class AttachedCommandValue {
         });
     }
     /** One input the running hook declared, which the Command's own names now hold. */
-    #declare(input) {
+    #declare(raw) {
         const { declared, identity } = this.#state;
+        const { path } = this.#state;
+        // The name is judged before the config, as Command and Application judge it.
+        if (raw.kind === 'argument') {
+            const { name } = declared;
+            checkArgumentName({ name, path, subject: commandSubject(name) }, [], raw);
+        }
+        else {
+            checkOptionName(raw.name, configUnread(inputSite(declared.name, path, raw)));
+        }
+        // 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: captureInputConfig(raw, place) }
+            : { ...raw, config: captureInputConfig(raw, place) };
         return this.#derive({ identity, input, kind: 'input' }, { ...declared, inputs: [...declared.inputs, input] });
     }
     #derive(call, declared) {
@@ -734,9 +1093,13 @@ class AttachedCommandValue {
     }
 }
 _a = AttachedCommandValue;
-/** The reason one failed hook reports, which is the thrown value's own message. */
-function attachReason(error) {
-    return error instanceof Error ? error.message : String(error);
+/** The finding for the hook one plugin declared, as `plugin(identity, { onCommandAttach })`. */
+function hookFinding(identity, hook) {
+    return {
+        arguments: [identity, { onCommandAttach: hook }],
+        call: 'plugin',
+        mark: '1.onCommandAttach',
+    };
 }
 /** One hook's own call, whose failure is the plugin's, and whose own report is its own. */
 function callHook(value, hook, named) {
@@ -748,7 +1111,11 @@ function callHook(value, hook, named) {
         if (error instanceof DeclarationError) {
             throw error;
         }
-        throw new DeclarationError(`Plugin "${named.identity}" failed in onCommandAttach for ${named.subject}: ${attachReason(error)}.`);
+        throw new DeclarationError(brokenAttachHook, {
+            correction: 'Return the value the hook received or a value derived from it, and throw only a DeclarationError from the hook.',
+            findings: [hookFinding(named.identity, hook)],
+            sentence: `Plugin ${quoted(named.identity)} failed in onCommandAttach for ${named.subject}: ${asSentence(reasonOf(error))}`,
+        }, { cause: error });
     }
 }
 /**
@@ -759,7 +1126,11 @@ function callHook(value, hook, named) {
 function attachOnce(value, hook, named) {
     const state = attachments.get(callHook(value, hook, named));
     if (!state || state.lineage !== named.lineage) {
-        throw new DeclarationError(`Plugin "${named.identity}" returned a value that is not the attached Command from onCommandAttach for ${named.subject}. Return the value it received or a value derived from it.`);
+        throw new DeclarationError(brokenAttachHook, {
+            correction: 'Return the value it received or a value derived from it.',
+            findings: [hookFinding(named.identity, hook)],
+            sentence: `Plugin ${quoted(named.identity)} returned a value that is not the attached Command from onCommandAttach for ${named.subject}.`,
+        });
     }
     return state;
 }
@@ -817,10 +1188,24 @@ function applyAttachCalls(state, calls) {
     }
     return next;
 }
+/**
+ * The reason rule one name collision breaks.
+ * Two options or two arguments break the rule the application's own collision of the pair breaks.
+ * An argument and an option under one name break name-shared-across-kinds, which only a hook reaches.
+ */
+function nameCollisionRule(declared, held) {
+    if (declared !== held) {
+        return nameSharedAcrossKinds;
+    }
+    return declared === 'option' ? optionDeclaredTwice : argumentDeclaredTwice;
+}
 /** The clause and the remedy an input another plugin's hook already declared earns. */
-function hookClause(kind, identity) {
+function hookClause(earlier, path) {
+    const { identity, input } = earlier;
     return {
-        clause: `an ${kind} plugin "${identity}" declared through onCommandAttach`,
+        clause: `an ${input.kind} plugin ${quoted(identity)} declared through onCommandAttach`,
+        held: inputFinding(path, input, declarerNote(identity)),
+        kind: input.kind,
         remedy: 'Install one of them.',
     };
 }
@@ -842,6 +1227,25 @@ function attachedRemedy(target) {
     }
     return 'Install one of them.';
 }
+/** The collision with one option the globals table holds, a global or a plugin's own option. */
+function tableCollision(entry) {
+    const { owner, site } = entry;
+    if (owner.kind === 'plugin') {
+        const clause = `an option of plugin ${quoted(owner.identity)}`;
+        return {
+            clause,
+            held: siteFinding(site, site.named, clause),
+            kind: 'option',
+            remedy: attachedRemedy('plugin'),
+        };
+    }
+    return {
+        clause: 'a global option',
+        held: siteFinding(site, site.named, 'the global option'),
+        kind: 'option',
+        remedy: attachedRemedy('global'),
+    };
+}
 /**
  * What one name a hook-declared input of either kind collides with, in the order the scopes are
  * reported: an earlier hook's option, an earlier hook's argument, a local option, a global or
@@ -850,32 +1254,36 @@ function attachedRemedy(target) {
  */
 function attachedCollision(input, held) {
     const { name } = input;
-    const hook = held.hooks.get(name);
+    const { path } = held;
+    const hook = held.hooks.get(name) ?? held.hookArguments.get(name);
     if (hook !== undefined) {
-        return hookClause('option', hook);
-    }
-    const hooked = held.hookArguments.get(name);
-    if (hooked !== undefined) {
-        return hookClause('argument', hooked);
+        return hookClause(hook, path);
     }
-    if (held.locals.has(name)) {
-        return { clause: 'a local option', remedy: attachedRemedy('local') };
+    const local = held.locals.get(name);
+    if (local !== undefined) {
+        return {
+            clause: 'a local option',
+            held: inputFinding(path, local, 'the local option'),
+            kind: 'option',
+            remedy: attachedRemedy('local'),
+        };
     }
-    const claimed = held.globals.names.get(name);
-    if (claimed) {
-        const target = claimed.kind === 'plugin' ? 'plugin' : 'global';
-        const clause = claimed.kind === 'plugin' ? `an option of plugin "${claimed.identity}"` : 'a global option';
-        return { clause, remedy: attachedRemedy(target) };
+    const entry = held.globals.names.get(name);
+    if (entry) {
+        return tableCollision(entry);
     }
-    return held.arguments.has(name)
-        ? { clause: 'an argument', remedy: attachedRemedy('argument') }
-        : undefined;
+    const argument = held.arguments.get(name);
+    return argument === undefined
+        ? undefined
+        : {
+            clause: 'an argument',
+            held: inputFinding(path, argument, 'the argument'),
+            kind: 'argument',
+            remedy: attachedRemedy('argument'),
+        };
 }
-/**
- * The spellings one compiled table holds, each under the form its own option is named by, which is
- * its long form where it declares one and the colliding spelling itself where it declares none.
- */
-function readSpellings(table, claimed) {
+/** The spellings one compiled table holds, each with its form and the place that declared it. */
+function readSpellings(table, claimed, placeOf) {
     const longs = new Map();
     for (const [spelling, option] of table) {
         if (option.role === 'long') {
@@ -884,53 +1292,107 @@ function readSpellings(table, claimed) {
     }
     for (const [spelling, option] of table) {
         if (!claimed.has(spelling)) {
-            claimed.set(spelling, longs.get(option.name) ?? spelling);
+            const form = longs.get(option.name) ?? spelling;
+            claimed.set(spelling, { finding: placeOf(option.name, option.role), 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);
+}
 /** One hook-declared option's spellings, against every spelling the table already claims. */
 function checkAttachedSpelling(declared, named) {
-    const { claimed, subject } = named;
-    const table = compileOptions([declared.input], subject);
-    for (const [spelling] of table) {
+    const { claimed, scope } = named;
+    const { identity, input } = declared;
+    const { subject } = scope;
+    const site = scope.siteOf(input);
+    const table = compileOptions([input], scope);
+    for (const [spelling, option] of table) {
         const used = claimed.get(spelling);
         if (used !== undefined) {
-            throw new DeclarationError(`Plugin "${declared.identity}" declares option "${declared.input.name}" with spelling "${spelling}" on ${subject}, which "${used}" already uses.`);
+            throw new DeclarationError(spellingTaken, {
+                correction: 'Change one of the two spellings or omit the plugin.',
+                findings: [
+                    spellingPlace(site, option.role, 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)));
+}
+/** The declarations of one kind, keyed by name, the first of each name winning. */
+function byName(inputs) {
+    const named = new Map();
+    for (const input of inputs) {
+        if (!named.has(input.name)) {
+            named.set(input.name, input);
         }
     }
-    readSpellings(table, claimed);
+    return named;
+}
+/** Where the globals table's options declared their spellings, a global or a plugin's option. */
+function tableSpellings(globals) {
+    return (name, role) => {
+        const entry = globals.names.get(name);
+        if (!entry) {
+            return undefined;
+        }
+        const { owner, site } = entry;
+        const note = owner.kind === 'plugin'
+            ? `an option of plugin ${quoted(owner.identity)}`
+            : `the global option ${quoted(name)}`;
+        return spellingPlace(site, role, note);
+    };
 }
 /**
  * Every input a hook declared, against the names and spellings the Command, the globals table, and
  * an earlier hook already hold. It runs before the Command's own inputs compile, so a hook-declared
- * input reports as the plugin's fault and never as the author's.
+ * input reports as the plugin's fault and never as the author's. A collision carries a finding for
+ * the hook's input and one for the declaration that already holds the name or spelling.
  */
-function checkAttachedInputs(declared, attached, globals) {
-    const subject = commandSubject(declared.name);
+function checkAttachedInputs(declared, attached, place) {
+    const { globals, path } = place;
+    const scope = localScope(declared.name, path);
+    const { subject } = scope;
     const hooked = new Set(attached.map((entry) => entry.input));
     const authored = declared.inputs.filter((input) => !hooked.has(input));
     const options = authored.filter((input) => input.kind === 'option');
+    const locals = byName(options);
     const held = {
-        arguments: new Set(authored.filter((input) => input.kind === 'argument').map((input) => input.name)),
+        arguments: byName(authored.filter((input) => input.kind === 'argument')),
         globals,
         hookArguments: new Map(),
         hooks: new Map(),
-        locals: new Set(options.map((input) => input.name)),
+        locals,
+        path,
     };
     const claimed = new Map();
-    readSpellings(globals.options, claimed);
-    readSpellings(compileOptions(options, subject), claimed);
-    for (const { identity, input } of attached) {
+    readSpellings(globals.options, claimed, tableSpellings(globals));
+    readSpellings(compileOptions(options, scope), claimed, (name, role) => {
+        const local = locals.get(name);
+        return local === undefined || local.kind !== 'option'
+            ? undefined
+            : spellingPlace(scope.siteOf(local), role, `the local option ${quoted(name)}`);
+    });
+    for (const entry of attached) {
+        const { identity, input } = entry;
         const collision = attachedCollision(input, held);
         if (collision) {
-            throw new DeclarationError(`Plugin "${identity}" declares ${input.kind} "${input.name}" on ${subject}, which is already declared as ${collision.clause}. ${collision.remedy}`);
+            throw new DeclarationError(nameCollisionRule(input.kind, collision.kind), {
+                correction: collision.remedy,
+                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}.`,
+            });
         }
         if (input.kind === 'option') {
-            checkAttachedSpelling({ identity, input }, { claimed, subject });
-            held.hooks.set(input.name, identity);
+            checkAttachedSpelling({ identity, input }, { claimed, scope });
+            held.hooks.set(input.name, entry);
         }
         else {
-            held.hookArguments.set(input.name, identity);
+            held.hookArguments.set(input.name, entry);
         }
     }
 }
@@ -969,29 +1431,31 @@ function bindDispatch(state, action, globals) {
 function checkInputFacts(inputs, command, context) {
     const { name, subject } = command;
     for (const input of inputs) {
-        const sentence = `${commandSentence(name)} ${input.kind} "${input.name}"`;
-        checkDescription(sentence, input.config.description);
+        const site = inputSite(name, context.path, input);
+        const sentence = site.subject;
+        checkDescription(site, input.config.description);
         if (input.kind === 'argument') {
-            checkNoListingFacts(sentence, input.config);
-            checkNoArgumentBinding(sentence, input.config);
+            checkNoListingFacts(site, input.config);
+            checkNoArgumentBinding(site, input.config);
         }
         else {
-            checkHidden(sentence, input.config.hidden);
-            checkDeprecated(sentence, input.config.deprecated);
-            checkEnvBinding(sentence, input.config);
+            checkHidden(site, input.config.hidden);
+            checkDeprecated(site, input.config.deprecated);
+            checkEnvBinding(site, input.config);
         }
         context.extensions.set(input, buildExtensions({
             declared: input.config.extensions,
             descriptors: context.descriptors,
+            site: { ...site, at: '1.extensions' },
             subject: { phrase: `on ${subject} ${input.kind} "${input.name}"`, sentence },
             target: input.kind,
         }));
     }
 }
 /** One Command declares arguments or attaches children, whichever declaration made each of them. */
-function checkArgumentPlacement(name, slot, child) {
+function checkArgumentPlacement(command, slot, child) {
     if (slot && child) {
-        throw placementFault(name, slot.input.name, child.name);
+        throw placementFault(command, slot.input, child);
     }
 }
 /**
@@ -1008,7 +1472,8 @@ export function buildCommand(state, context) {
     for (const [input, record] of state.records) {
         context.extensions.set(input, record);
     }
-    const declaredSlots = collectArguments(state, subject);
+    const place = { name, path: context.path };
+    const declaredSlots = collectArguments(state, place);
     const hasAction = action !== undefined;
     /**
      * The hooks run once the author's declaration is complete, and each value a hook receives resolves
@@ -1027,15 +1492,15 @@ export function buildCommand(state, context) {
     checkInputFacts(hookInputs.map((call) => call.input), { name, subject }, context);
     // The hook-declared names are checked first, so a collision reports in the plugin's voice.
     // A rule the author's own declaration voices never speaks for a name a hook declared.
-    checkAttachedInputs(hooked, hookInputs, globals);
+    checkAttachedInputs(hooked, hookInputs, { globals, path: context.path });
     // Every value was validated once, the author's at each call and each hook's at its `extend()`.
     const extensions = publishStore(progress.extensions);
-    const slots = hookInputs.length > 0 ? collectArguments(hooked, subject) : declaredSlots;
-    checkArgumentPlacement(name, slots[0], state.children[0]);
-    const result = checkFinished(hooked, hasAction);
-    const options = checkLocalOptions(optionsOf(hooked.inputs), globals, subject);
+    const slots = hookInputs.length > 0 ? collectArguments(hooked, place) : declaredSlots;
+    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));
     // A hook's erased calls answer the declaration rules an authored call answers at the call.
-    checkDeclarations(hookInputs.map((call) => call.input));
+    checkDeclarations(hookInputs.map(({ input }) => ({ input, site: inputSite(name, context.path, input) })));
     const children = new Map();
     const routes = new Map();
     for (const child of state.children) {
@@ -1093,7 +1558,7 @@ export class CommandBuilder {
     }
     argument(name, config) {
         const input = {
-            config: captureConfig(config),
+            config,
             kind: 'argument',
             name,
         };
@@ -1101,7 +1566,7 @@ export class CommandBuilder {
     }
     option(name, config) {
         const input = {
-            config: captureConfig(config),
+            config,
             kind: 'option',
             name,
         };
@@ -1158,7 +1623,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);
     }
 }
@@ -1172,12 +1637,35 @@ export function collectInputs(command) {
     ];
 }
 /**
- * The names a routing failure offers: the canonical names of the visible children, in authoring
- * order. A candidate list is a listing, so a hidden child is absent from it, and a parent whose
- * children are all hidden offers none.
+ * 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.
+ */
+export function inputPlaces(graph) {
+    const places = new Map();
+    for (const input of graph.globals.inputs) {
+        places.set(input, inputPlace(input, { global: true, path: [] }));
+    }
+    const walk = (command, path) => {
+        for (const input of command.inputs) {
+            places.set(input, inputPlace(input, { global: false, path }));
+        }
+        for (const [name, child] of command.children) {
+            walk(child, [...path, name]);
+        }
+    };
+    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).map(([name]) => name);
+    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
@@ -1186,8 +1674,12 @@ function candidatesOf(command) {
 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. */
-export function route(root, tokens) {
+/**
+ * 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;
@@ -1202,6 +1694,7 @@ export function route(root, tokens) {
         // 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;
     }
     return { command, path, tokens: tokens.slice(index) };
@@ -1240,10 +1733,13 @@ 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. */
-export function routeInvocation(graph, argv) {
+/**
+ * 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);
+    const routed = route(graph.root, scan.rest, walked);
     return {
         command: routed.command,
         path: routed.path,
@@ -1306,7 +1802,7 @@ function requestNode(graph, path, place) {
     const options = place.global ? graph.globals : nodeAt(graph, path).options;
     const node = options.find((option) => option.name === place.name);
     if (!node) {
-        throw new InternalError(`Option "${place.name}" is not in the inspected graph.`, undefined);
+        throw graphMismatch(`Option "${place.name}" is not in the inspected graph.`);
     }
     return node;
 }
@@ -1330,6 +1826,7 @@ async function fillScope({ graph, invocation, routed }, local) {
         locals: local.kind === 'parsed'
             ? { global: false, inputs: optionsOf(routed.command.inputs), values: locals }
             : undefined,
+        offer: invocation.offer,
         out: invocation.sourceOut,
         plugins: graph.globals.plugins,
         request: (input, global) => requestNode(invocation.inspected(), routed.path, { global, name: input.name }),
@@ -1426,6 +1923,7 @@ export async function prepareDispatch(graph, routed, invocation) {
         return { ...ready, globals, kind: 'ready', result };
     }
     catch (error) {
-        return held(error);
+        // The fault is held as a failure, so a throw from reading a validator's output is never offered.
+        return held(toFailure(error));
     }
 }