@loomcli/core 0.5.0 → 0.7.0

package/dist/plugin.js

@@ -1,15 +1,25 @@
 import { checkEnvBinding, claimVariables } from './bindings.js';
-import { attach, commandNode } from './command.js';
-import { DeclarationError, InternalError, reasonOf } from './errors.js';
+import { captureDeclaration, elidedRead, unreadableArgument, unreadableFault } from './capture.js';
+import { notACommand } from './command-rules.js';
+import { attach, commandCode, commandNode } from './command.js';
+import { elided, quoteString, spelled } from './diagnostic-text.js';
+import { DeclarationError, InternalError, quoted, reasonOf } from './errors.js';
 import { appliesTo, buildExtensions, isDescriptor, registerDescriptor } from './extension.js';
-import { checkDeprecated, checkDescription, checkHidden, isPlainObject } from './facts.js';
-import { boundOptions } from './globals.js';
+import { checkDeprecated, checkDescription, checkHidden, factFault, partFinding, pluginOptionSite, slotSite, } from './facts.js';
+import { boundOptions, pluginSites } from './globals.js';
+import { checkIdentity } from './identity.js';
 import { coreViews } from './lanes.js';
 import { booleanValue, compileOptions } from './options.js';
+import { copyOwnKeys, decidePlain, declaring, isPlainObject, shallowList, shallowRecord, } from './plain.js';
+import { foreignValue, middlewareActivation, notAFunction, notAList, notAnObject, pluginInstalledTwice, pluginOptionRule, signalClaimedTwice, slotTaken, sourceBinding, sourceBoundOwnOption, unknownSignal, } from './plugin-rules.js';
+import { pluginLoaderFailed } from './rules.js';
 import { isProcessSignal } from './signals.js';
 import { buildTheme } from './theme.js';
-import { captureConfig, checkDeclarations } from './validation.js';
+import { readTranslations } from './translators.js';
+import { captureConfig, checkDeclarations, defaultDepthFault } from './validation.js';
 import { buildViews, viewIdentities } from './view.js';
+/** The slots of a definition that hold a list, each copied with its entries as they were built. */
+const definitionLists = ['extensions', 'signals', 'commands', 'views', 'translators'];
 /** Authored values register here, so the public type publishes no state to reach or replace. */
 const nodes = new WeakMap();
 /**
@@ -25,110 +35,219 @@ class PluginDeclaration {
 }
 /**
  * One plugin: an identity and the contributions it carries. Creating and installing the value runs
- * none of its code: a hook runs at graph build, and the middleware runs inside an invocation, so an
- * installed plugin an invocation never reaches costs that invocation its hooks alone. Every rule
- * that one definition carries on its own throws here, before the value exists.
+ * none of its code: `onCommandAttach` runs at graph build, `onFailure` runs when `run()` renders a
+ * failure, and the middleware runs inside an invocation, so an installed plugin an invocation never
+ * reaches costs that invocation its hooks alone. The definition is read once, after the identity,
+ * and every rule that one definition carries on its own throws here, before the value exists.
  */
 function plugin(identity, definition) {
-    const captured = {
-        ...definition,
-        ...(definition?.theme === undefined
-            ? {}
-            : { theme: isPlainObject(definition.theme) ? { ...definition.theme } : definition.theme }),
-    };
-    return new PluginDeclaration(readPlugin(identity, isPlainObject(definition) ? captured : definition));
+    return new PluginDeclaration(declaring(() => readPlugin(identity, definition)));
+}
+/**
+ * The one copy of a definition that `plugin()` reads: the definition, its theme mapping, options
+ * record, middleware with its activation list, and source, and each list it holds. An entry of a
+ * list is what its factory built and is not copied, and each option's config is captured where its
+ * own rules read it, so a fault about it names the option. A read that throws is the unreadable
+ * fault of the definition, and a definition that is not a plain object is the not-an-object fault.
+ */
+function captureDefinition(identity, definition) {
+    return captureDeclaration(definition, (copy, read) => {
+        read.nested(copy, 'theme', shallowRecord);
+        read.nested(copy, 'options', shallowRecord);
+        read.nested(copy, 'middleware', copyMiddleware);
+        read.nested(copy, 'source', shallowRecord);
+        for (const list of definitionLists) {
+            read.nested(copy, list, shallowList);
+        }
+    }, {
+        notAnObject: () => new DeclarationError(notAnObject, {
+            correction: 'Supply { options, middleware, extensions, views }.',
+            findings: [{ arguments: [identity, definition], call: 'plugin', mark: '1' }],
+            sentence: `${pluginSentence(identity)} declares a definition that is not an object.`,
+        }),
+        unreadable: unreadableArgument({ call: 'plugin', named: identity, subject: pluginSentence(identity) }, 'definition'),
+    });
+}
+/** A middleware object's copy, its activation list copied too, or any other value as declared. */
+function copyMiddleware(middleware) {
+    if (!decidePlain(middleware)) {
+        return middleware;
+    }
+    const copy = copyOwnKeys(middleware);
+    if (Object.hasOwn(copy, 'activate')) {
+        copy.activate = shallowList(copy.activate);
+    }
+    return copy;
 }
 /** How every plugin diagnostic names one plugin at the start of a sentence. */
 function pluginSentence(identity) {
-    return `Plugin "${identity}"`;
+    return `Plugin ${quoted(identity)}`;
+}
+/** Where one slot of a plugin's definition sits, rebuilt as `plugin(identity, { slot })`. */
+function pluginSlot(identity, slot, value) {
+    return slotSite({ call: 'plugin', named: identity, subject: pluginSentence(identity) }, slot, value);
+}
+/** The subject a plugin's `views` list reports under, and the call that declared it. */
+function pluginViews(identity) {
+    return {
+        declares: true,
+        owner: { call: 'plugin', named: identity },
+        sentence: pluginSentence(identity),
+    };
 }
-/** Reads the declarations behind an installed value; anything else is a declaration error. */
+/** The declarations behind one installed value, or `undefined` for a value `plugin()` did not make. */
 function nodeOf(value) {
-    const node = typeof value === 'object' && value !== null ? nodes.get(value) : undefined;
-    if (!node) {
-        throw new DeclarationError('The Application holds a value that is not a plugin. Supply the value returned by plugin(identity, definition).');
-    }
-    return node;
+    return typeof value === 'object' && value !== null ? nodes.get(value) : undefined;
 }
-/** The identity one plugin declares, which is a nonempty string. */
-function readIdentity(identity) {
-    if (typeof identity !== 'string') {
-        throw new DeclarationError('A plugin declares an identity that is not a string. Supply a nonempty string, such as the package name.');
-    }
-    if (identity === '') {
-        throw new DeclarationError('A plugin declares an empty identity. Supply a nonempty string, such as the package name.');
-    }
-    return identity;
+/** One `plugins` entry as a finding prints it: a plugin as its `plugin()` call, elided. */
+function entryCode(value) {
+    const node = nodeOf(value);
+    return node ? spelled(`plugin(${quoteString(node.identity)}, ${elided})`) : value;
 }
-/** The declarations one plugin value carries, which a JavaScript author reaches as any value. */
-function definitionOf(identity, definition) {
-    if (!isPlainObject(definition)) {
-        throw new DeclarationError(`${pluginSentence(identity)} declares a definition that is not an object. Supply { options, middleware, extensions, views }.`);
-    }
-    return definition;
+/** How a second claim on one slot reads: its clause, the note on the owner's entry, and the fix. */
+const slotWords = {
+    signals: {
+        clause: (owner) => `claims the signals slot, which plugin ${quoted(owner)} already holds.`,
+        correction: 'Install one owner.',
+        held: 'holds the signals slot',
+    },
+    source: {
+        clause: (owner) => `declares a configuration source, which plugin ${quoted(owner)} already declares.`,
+        correction: 'Install one source.',
+        held: 'declares the configuration source',
+    },
+    theme: {
+        clause: (owner) => `claims the theme slot, which plugin ${quoted(owner)} already holds.`,
+        correction: 'Install one owner.',
+        held: 'holds the theme slot',
+    },
+};
+/** A second claim on one slot, which marks the owner's entry and the claimant's in `plugins`. */
+function slotFault(site, slot, claim) {
+    const { claimant, installed, owner } = claim;
+    const words = slotWords[slot];
+    return new DeclarationError(slotTaken, {
+        correction: words.correction,
+        findings: [
+            partFinding(site, [owner], words.held),
+            partFinding(site, [claimant], 'claims it again'),
+        ],
+        sentence: `${pluginSentence(installed[claimant]?.identity ?? '')} ${words.clause(installed[owner]?.identity ?? '')}`,
+    });
 }
 /**
  * The installed list in composition order, with every rule that reads two plugins together: an
  * identity installed twice, a second claim on the theme slot, the signals slot, or the
- * configuration source, and two distinct descriptors under one identity. The slot is read
- * defensively, because a JavaScript author reaches it with any value. Each plugin's own rules
- * already ran at its `plugin()` call.
+ * configuration source, and two distinct descriptors under one identity. The slot is the copy the
+ * Application's constructor took, which a JavaScript author fills with any value. Each plugin's own
+ * rules already ran at its `plugin()` call.
  */
-function installPlugins(plugins) {
+function installPlugins(application, plugins) {
+    const printed = Array.isArray(plugins) ? Array.from(plugins, entryCode) : plugins;
+    const site = slotSite({ call: 'new Application', named: application, subject: 'The Application' }, 'plugins', printed);
     if (!Array.isArray(plugins)) {
-        throw new DeclarationError('The Application plugins must be an array. Supply a list of plugin values.');
+        throw new DeclarationError(notAList, {
+            correction: 'Supply a list of plugin values.',
+            findings: [partFinding(site, [])],
+            sentence: 'The Application declares plugins that are not an array.',
+        });
     }
     const list = plugins;
-    const installed = list.map((value) => nodeOf(value));
-    const identities = new Set();
+    const installed = list.map((value, index) => {
+        const node = nodeOf(value);
+        if (!node) {
+            throw new DeclarationError(foreignValue, {
+                correction: 'Supply the value returned by plugin(identity, definition).',
+                findings: [partFinding(site, [index])],
+                sentence: 'The Application holds a value that is not a plugin.',
+            });
+        }
+        return node;
+    });
+    const positions = new Map();
     const descriptors = new Map();
     // Each slot has one owner, so the first plugin to claim it names the second claimant's diagnostic.
-    const owners = {};
-    for (const entry of installed) {
+    const owners = new Map();
+    const claim = (slot, index) => {
+        const owner = owners.get(slot);
+        if (owner !== undefined) {
+            throw slotFault(site, slot, { claimant: index, installed, owner });
+        }
+        owners.set(slot, index);
+    };
+    for (const [index, entry] of installed.entries()) {
         const { identity } = entry;
-        if (identities.has(identity)) {
-            throw new DeclarationError(`The Application installs plugin "${identity}" twice. Install each plugin once.`);
+        const first = positions.get(identity);
+        if (first !== undefined) {
+            throw new DeclarationError(pluginInstalledTwice, {
+                correction: 'Install each plugin once.',
+                findings: [
+                    partFinding(site, [first], 'the first installation'),
+                    partFinding(site, [index], 'the second installation'),
+                ],
+                sentence: `The Application installs plugin ${quoted(identity)} twice.`,
+            });
         }
-        identities.add(identity);
+        positions.set(identity, index);
         if (entry.theme !== undefined) {
-            if (owners.theme !== undefined) {
-                throw new DeclarationError(`${pluginSentence(identity)} claims the theme slot, which plugin "${owners.theme}" already holds. Install one owner.`);
-            }
-            owners.theme = identity;
+            claim('theme', index);
         }
-        for (const descriptor of entry.descriptors.values()) {
-            registerDescriptor(descriptors, descriptor);
+        for (const [key, descriptor] of entry.descriptors) {
+            registerDescriptor(descriptors, descriptor, {
+                identity: key,
+                place: partFinding(site, [index]),
+            });
         }
         // An empty claim leaves the signals slot free.
         if (entry.signals.length > 0) {
-            if (owners.signals !== undefined) {
-                throw new DeclarationError(`${pluginSentence(identity)} claims the signals slot, which plugin "${owners.signals}" already holds. Install one owner.`);
-            }
-            owners.signals = identity;
+            claim('signals', index);
         }
         if (entry.source) {
-            if (owners.source !== undefined) {
-                throw new DeclarationError(`${pluginSentence(identity)} declares a configuration source, which plugin "${owners.source}" already declares. Install one source.`);
-            }
-            owners.source = identity;
+            claim('source', index);
         }
     }
     return { descriptors, plugins: installed };
 }
 /** The keys a plugin option may not declare, in the order its diagnostic names them. */
 const forbidden = ['validate', 'validateOmitted', 'required'];
-/** The rules a plugin option answers before every rule an ordinary declaration carries. */
-function checkPluginOption(sentence, config) {
-    if (!isPlainObject(config)) {
-        throw new DeclarationError(`${sentence} is not an option declaration. Supply { type, ... }.`);
-    }
+/**
+ * The rules a plugin option answers before every rule an ordinary declaration carries, read from
+ * the one copy of its config that `captureConfig` takes, which it answers with for every later read.
+ * `siteOf` places the option with the value its entry prints as: the config as declared for a value
+ * that is not one, elided for a config whose read threw, and the copy for every later rule.
+ */
+function checkPluginOption(siteOf, declared) {
+    const sentence = siteOf(declared).subject;
+    const config = captureConfig(declared, {
+        notAnObject: () => new DeclarationError(notAnObject, {
+            correction: 'Supply { type, ... }.',
+            findings: [partFinding(siteOf(declared), [])],
+            sentence: `${sentence} is not an option declaration.`,
+        }),
+        // The default's walk stopped at the limit, so the finding prints it elided.
+        tooDeep: () => {
+            const { keys, shown } = elidedRead('default');
+            return defaultDepthFault(sentence, [partFinding(siteOf(shown), keys)]);
+        },
+        // A part whose read threw is never read again, so the finding prints it elided.
+        unreadable: (thrown, slot) => {
+            const { keys, shown } = elidedRead(slot);
+            return unreadableFault({ declared: 'config', findings: [partFinding(siteOf(shown), keys)], subject: sentence }, thrown);
+        },
+    });
+    const site = siteOf(config);
     const rejected = forbidden.find((key) => key in config);
     if (rejected !== undefined) {
-        throw new DeclarationError(`${sentence} declares ${rejected}. Remove it; a plugin option carries no validator or presence rule, and the middleware interprets the value.`);
-    }
-    checkDescription(sentence, config.description);
-    checkHidden(sentence, config.hidden);
-    checkDeprecated(sentence, config.deprecated);
+        throw factFault(pluginOptionRule, site, {
+            correction: 'Remove it; a plugin option carries no validator or presence rule, and the middleware interprets the value.',
+            fact: rejected,
+            sentence: `${sentence} declares ${rejected}.`,
+        });
+    }
+    checkDescription(site, config.description);
+    checkHidden(site, config.hidden);
+    checkDeprecated(site, config.deprecated);
+    return config;
 }
 /**
  * One plugin's option declarations, in declaration order. They join the globals table, so the rules
@@ -136,19 +255,36 @@ function checkPluginOption(sentence, config) {
  */
 function readOptions(identity, declared, build) {
     if (declared !== undefined && !isPlainObject(declared)) {
-        throw new DeclarationError(`${pluginSentence(identity)} declares options that are not an object. Supply a record of option declarations.`);
+        throw new DeclarationError(notAnObject, {
+            correction: 'Supply a record of option declarations.',
+            findings: [partFinding(pluginSlot(identity, 'options', declared), [])],
+            sentence: `${pluginSentence(identity)} declares options that are not an object.`,
+        });
     }
     const inputs = [];
-    for (const [name, config] of Object.entries(declared ?? {})) {
-        const sentence = `${pluginSentence(identity)} option "${name}"`;
-        checkPluginOption(sentence, config);
-        checkEnvBinding(sentence, config);
-        const input = { config: captureConfig(config), kind: 'option', name };
+    // A finding prints each option's captured config once it is taken, and each later one elided.
+    const shown = Object.fromEntries(Object.keys(declared ?? {}).map((name) => [name, spelled(elided)]));
+    for (const [name, entry] of Object.entries(declared ?? {})) {
+        const sentence = `${pluginSentence(identity)} option ${quoted(name)}`;
+        // A computed key defines its own property even for `__proto__`, where assignment would not.
+        const siteOf = (value) => pluginOptionSite({ identity, options: { ...shown, [name]: value } }, name, sentence);
+        const config = checkPluginOption(siteOf, entry);
+        // Defining the key keeps its place, and holds even for a key of `__proto__`.
+        Object.defineProperty(shown, name, {
+            configurable: true,
+            enumerable: true,
+            value: config,
+            writable: true,
+        });
+        const site = siteOf(config);
+        checkEnvBinding(site, config);
+        const input = { config, kind: 'option', name };
         // The shared rules name the plugin and the option, so a fault reads with its contributor.
-        checkDeclarations([input], sentence);
+        checkDeclarations([{ input, site }], sentence);
         build.records.set(input, buildExtensions({
             declared: config.extensions,
             descriptors: build.descriptors,
+            site: { ...site, at: `${site.at}.extensions` },
             subject: {
                 phrase: `on ${sentence.slice(0, 1).toLowerCase()}${sentence.slice(1)}`,
                 sentence,
@@ -158,30 +294,49 @@ function readOptions(identity, declared, build) {
         inputs.push(input);
     }
     // Two options of one plugin meet in the one table the pre-scan reads, so they share its rules.
-    compileOptions(inputs, `plugin "${identity}"`);
-    claimVariables(boundOptions(inputs, (name) => `plugin "${identity}" option "${name}"`));
+    const siteOf = pluginSites(identity, inputs);
+    compileOptions(inputs, { siteOf, subject: `plugin ${quoted(identity)}` });
+    claimVariables(boundOptions(inputs, (input) => ({
+        phrase: `plugin ${quoted(identity)} option ${quoted(input.name)}`,
+        site: siteOf(input),
+    })));
     return inputs;
 }
-/** One activation name, which must be one of the plugin's own declared options. */
-function readActivationName(identity, name, names) {
-    if (typeof name !== 'string' || !names.has(name)) {
-        throw new DeclarationError(`${pluginSentence(identity)} activates middleware on option "${String(name)}", which it does not declare. Name one of the plugin's own options.`);
-    }
-    return name;
-}
-/** The activation a middleware declares, checked against the options its own plugin declares. */
-function readActivation(identity, declared, names) {
-    if (declared === 'always') {
+/**
+ * The activation a middleware declares, checked against the options its own plugin declares. `site`
+ * holds the middleware object, and a fault marks its `activate` key, or the object itself when the
+ * key is absent.
+ */
+function readActivation(site, declared, names) {
+    const { activate } = declared;
+    if (activate === 'always') {
         return 'always';
     }
-    if (!Array.isArray(declared)) {
-        throw new DeclarationError(`${pluginSentence(identity)} declares middleware with no activation. Supply activate: 'always' or a list of the plugin's own option names.`);
+    if (!Array.isArray(activate)) {
+        throw new DeclarationError(middlewareActivation, {
+            correction: "Supply activate: 'always' or a list of the plugin's own option names.",
+            findings: [partFinding(site, 'activate' in declared ? ['activate'] : [])],
+            sentence: `${site.subject} declares middleware with no activation.`,
+        });
     }
-    const list = declared;
+    const list = activate;
     if (list.length === 0) {
-        throw new DeclarationError(`${pluginSentence(identity)} declares middleware with an empty activation list. Name at least one of the plugin's options or use 'always'.`);
-    }
-    return list.map((name) => readActivationName(identity, name, names));
+        throw new DeclarationError(middlewareActivation, {
+            correction: "Name at least one of the plugin's options or use 'always'.",
+            findings: [partFinding(site, ['activate'])],
+            sentence: `${site.subject} declares middleware with an empty activation list.`,
+        });
+    }
+    return list.map((name, index) => {
+        if (typeof name !== 'string' || !names.has(name)) {
+            throw new DeclarationError(middlewareActivation, {
+                correction: "Name one of the plugin's own options.",
+                findings: [partFinding(site, ['activate', index])],
+                sentence: `${site.subject} activates middleware on option ${quoted(name)}, which it does not declare.`,
+            });
+        }
+        return name;
+    });
 }
 /**
  * The loader a middleware declares. Core calls it with no arguments and reads whatever it resolves
@@ -201,28 +356,47 @@ async function loadDefault(identity, load, owed) {
         module = await load();
     }
     catch (error) {
-        throw new InternalError(`Loading plugin "${identity}" failed: ${reasonOf(error)}`, error);
+        throw new InternalError(pluginLoaderFailed, {
+            cause: error,
+            correction: loaderCorrection,
+            sentence: `Loading plugin ${quoted(identity)} failed: ${reasonOf(error)}`,
+        });
     }
     const exported = module !== null && typeof module === 'object' && 'default' in module
         ? module.default
         : undefined;
     if (!owed.guard(exported)) {
-        throw new InternalError(`Loading plugin "${identity}" failed: the module exports no default ${owed.noun} function.`, undefined);
+        throw new InternalError(pluginLoaderFailed, {
+            cause: undefined,
+            correction: loaderCorrection,
+            sentence: `Loading plugin ${quoted(identity)} failed: the module exports no default ${owed.noun} function.`,
+        });
     }
     return exported;
 }
+/** The fix every plugin loader fault shares. */
+const loaderCorrection = "Make load() resolve to a module whose default export is the plugin's function, such as () => import('./middleware.js').";
 /** One plugin's middleware, or `undefined` for a plugin that declares none. */
 function readMiddleware(identity, declared, names) {
     if (declared === undefined) {
         return undefined;
     }
+    const site = pluginSlot(identity, 'middleware', declared);
     if (!isPlainObject(declared)) {
-        throw new DeclarationError(`${pluginSentence(identity)} declares middleware that is not an object. Supply { activate, load }.`);
+        throw new DeclarationError(notAnObject, {
+            correction: 'Supply { activate, load }.',
+            findings: [partFinding(site, [])],
+            sentence: `${pluginSentence(identity)} declares middleware that is not an object.`,
+        });
     }
-    const activate = readActivation(identity, declared.activate, names);
+    const activate = readActivation(site, declared, names);
     const { load } = declared;
     if (!isLoader(load)) {
-        throw new DeclarationError(`${pluginSentence(identity)} declares middleware with no load function. Supply load: () => import('./middleware.js').`);
+        throw new DeclarationError(notAFunction, {
+            correction: "Supply load: () => import('./middleware.js').",
+            findings: [partFinding(site, 'load' in declared ? ['load'] : [])],
+            sentence: `${pluginSentence(identity)} declares middleware with no load function.`,
+        });
     }
     return { activate, load };
 }
@@ -236,17 +410,42 @@ function readCommands(identity, declared) {
         return [];
     }
     if (!Array.isArray(declared)) {
-        throw new DeclarationError(`${pluginSentence(identity)} declares commands that are not an array. Supply a list of Command values.`);
+        throw new DeclarationError(notAList, {
+            correction: 'Supply a list of Command values.',
+            findings: [partFinding(pluginSlot(identity, 'commands', declared), [])],
+            sentence: `${pluginSentence(identity)} declares commands that are not an array.`,
+        });
     }
     const list = declared;
     const commands = [];
+    // Each entry prints as the Command it is, so a finding rebuilds the list the plugin declared.
+    const entries = Array.from(list, (value) => {
+        const node = commandNode(value);
+        return node ? commandCode(node.name) : value;
+    });
     // A for...of walk reads a hole as undefined, which the entry rule rejects, where map would skip it.
-    for (const value of list) {
+    for (const [index, value] of list.entries()) {
         const node = commandNode(value);
+        const placement = {
+            arguments: [identity, { commands: entries }],
+            call: 'plugin',
+            mark: `1.commands.${String(index)}`,
+        };
         if (!node) {
-            throw new DeclarationError(`${pluginSentence(identity)} holds a value that is not a Command. Supply the value returned by new Command(name).`);
+            throw new DeclarationError(notACommand, {
+                correction: 'Supply the value returned by new Command(name).',
+                findings: [placement],
+                sentence: `${pluginSentence(identity)} holds a value that is not a Command.`,
+            });
         }
-        commands.push(attach({ argument: undefined, children: commands, hasAction: false, name: null }, node));
+        const parent = {
+            argument: undefined,
+            children: commands,
+            hasAction: false,
+            name: null,
+            path: [],
+        };
+        commands.push(attach(parent, node, placement));
     }
     return commands;
 }
@@ -260,21 +459,39 @@ function readSignals(identity, declared) {
     if (declared === undefined) {
         return [];
     }
+    const site = pluginSlot(identity, 'signals', declared);
     if (!Array.isArray(declared)) {
-        throw new DeclarationError(`${pluginSentence(identity)} declares signals that are not an array. Supply a list of signal names.`);
+        throw new DeclarationError(notAList, {
+            correction: 'Supply a list of signal names.',
+            findings: [partFinding(site, [])],
+            sentence: `${pluginSentence(identity)} declares signals that are not an array.`,
+        });
     }
     const list = declared;
-    const claimed = new Set();
-    for (const value of list) {
+    // Each claimed signal's position, so a repeat marks both claims.
+    const claimed = new Map();
+    for (const [index, value] of list.entries()) {
         if (!isProcessSignal(value)) {
-            throw new DeclarationError(`${pluginSentence(identity)} claims signal "${String(value)}". Claim SIGINT or SIGTERM.`);
+            throw new DeclarationError(unknownSignal, {
+                correction: 'Claim SIGINT or SIGTERM.',
+                findings: [partFinding(site, [index])],
+                sentence: `${pluginSentence(identity)} claims signal ${quoted(value)}.`,
+            });
         }
-        if (claimed.has(value)) {
-            throw new DeclarationError(`${pluginSentence(identity)} claims signal "${value}" twice. Claim each signal once.`);
+        const first = claimed.get(value);
+        if (first !== undefined) {
+            throw new DeclarationError(signalClaimedTwice, {
+                correction: 'Claim each signal once.',
+                findings: [
+                    partFinding(site, [first], 'the first claim'),
+                    partFinding(site, [index], 'the second claim'),
+                ],
+                sentence: `${pluginSentence(identity)} claims signal ${quoted(value)} twice.`,
+            });
         }
-        claimed.add(value);
+        claimed.set(value, index);
     }
-    return [...claimed];
+    return [...claimed.keys()];
 }
 /**
  * A lifecycle hook is a function core calls at one named point, so being callable is the whole
@@ -289,7 +506,29 @@ function readHook(identity, declared) {
         return undefined;
     }
     if (!isHook(declared)) {
-        throw new DeclarationError(`${pluginSentence(identity)} declares onCommandAttach that is not a function. Supply a function of the Command.`);
+        throw new DeclarationError(notAFunction, {
+            correction: 'Supply a function of the Command.',
+            findings: [partFinding(pluginSlot(identity, 'onCommandAttach', declared), [])],
+            sentence: `${pluginSentence(identity)} declares onCommandAttach that is not a function.`,
+        });
+    }
+    return declared;
+}
+/** Being callable is the whole claim, as it is for `onCommandAttach`; `run()` checks what it returns. */
+function isFailureHook(value) {
+    return typeof value === 'function';
+}
+/** One plugin's `onFailure` hook, or `undefined` for a plugin that declares none. */
+function readFailureHook(identity, declared) {
+    if (declared === undefined) {
+        return undefined;
+    }
+    if (!isFailureHook(declared)) {
+        throw new DeclarationError(notAFunction, {
+            correction: 'Supply a function of the failure and its context.',
+            findings: [partFinding(pluginSlot(identity, 'onFailure', declared), [])],
+            sentence: `${pluginSentence(identity)} declares onFailure that is not a function.`,
+        });
     }
     return declared;
 }
@@ -305,48 +544,90 @@ function readSource(identity, declaration, own) {
         return undefined;
     }
     const sentence = pluginSentence(identity);
+    const site = pluginSlot(identity, 'source', declared);
     if (!isPlainObject(declared)) {
-        throw new DeclarationError(`${sentence} declares a source that is not an object. Supply { binding, load }.`);
+        throw new DeclarationError(notAnObject, {
+            correction: 'Supply { binding, load }.',
+            findings: [partFinding(site, [])],
+            sentence: `${sentence} declares a source that is not an object.`,
+        });
     }
     const { binding, load } = declared;
-    const listed = (declaration.extensions ?? []).some((descriptor) => descriptor === binding);
-    if (!listed || !isDescriptor(binding)) {
-        throw new DeclarationError(`${sentence} declares a source binding that is not one of its extensions. Supply a descriptor the plugin lists under extensions.`);
-    }
-    if (binding.target !== 'option') {
-        throw new DeclarationError(`${sentence} declares source binding "${binding.identity}", which applies to ${appliesTo(binding.target)}. Supply an extension that applies to options.`);
+    // A fault about one key marks the key, or the source itself when the key is absent.
+    const keyFinding = (key) => partFinding(site, key in declared ? [key] : []);
+    // The plugin's own extensions were admitted first, so a listed binding is in the registry.
+    // Its identity is read from there, where admission read it once, and never from the binding again.
+    const bound = [...own.build.descriptors].find(([, descriptor]) => descriptor === binding);
+    if (bound === undefined) {
+        throw new DeclarationError(sourceBinding, {
+            correction: 'Supply a descriptor the plugin lists under extensions.',
+            findings: [keyFinding('binding')],
+            sentence: `${sentence} declares a source binding that is not one of its extensions.`,
+        });
+    }
+    const [bindingIdentity, { target }] = bound;
+    if (target !== 'option') {
+        throw new DeclarationError(sourceBinding, {
+            correction: 'Supply an extension that applies to options.',
+            findings: [keyFinding('binding')],
+            sentence: `${sentence} declares source binding ${quoted(bindingIdentity)}, which applies to ${appliesTo(target)}.`,
+        });
     }
     if (!isLoader(load)) {
-        throw new DeclarationError(`${sentence} declares a source with no load function. Supply load: () => import('./source.js').`);
+        throw new DeclarationError(notAFunction, {
+            correction: "Supply load: () => import('./source.js').",
+            findings: [keyFinding('load')],
+            sentence: `${sentence} declares a source with no load function.`,
+        });
     }
-    const carrier = own.inputs.find((input) => Object.hasOwn(own.build.records.get(input) ?? {}, binding.identity));
+    const carrier = own.inputs.find((input) => Object.hasOwn(own.build.records.get(input) ?? {}, bindingIdentity));
     if (carrier) {
-        throw new DeclarationError(`${sentence} option "${carrier.name}" carries its own source binding. Remove the value; the source's own options resolve before it loads.`);
-    }
-    return { binding: binding.identity, load };
+        // The record prints each option's captured config, which is what its rules read.
+        const option = pluginSites(identity, own.inputs)(carrier);
+        throw new DeclarationError(sourceBoundOwnOption, {
+            correction: "Remove the value; the source's own options resolve before it loads.",
+            findings: [partFinding(option, ['extensions'])],
+            sentence: `${option.subject} carries its own source binding.`,
+        });
+    }
+    return { binding: bindingIdentity, load };
 }
 /** A plugin's own list names the extensions it defines, before any declaration carries one. */
 function defineExtensions(identity, declaration, build) {
     const { extensions } = declaration;
+    const site = pluginSlot(identity, 'extensions', extensions);
     if (extensions !== undefined && !Array.isArray(extensions)) {
-        throw new DeclarationError(`${pluginSentence(identity)} declares extensions that are not an array. Supply a list of extension descriptors.`);
-    }
-    for (const descriptor of extensions ?? []) {
+        throw new DeclarationError(notAList, {
+            correction: 'Supply a list of extension descriptors.',
+            findings: [partFinding(site, [])],
+            sentence: `${pluginSentence(identity)} declares extensions that are not an array.`,
+        });
+    }
+    const list = Array.isArray(extensions) ? extensions : [];
+    for (const [index, descriptor] of list.entries()) {
         if (!isDescriptor(descriptor)) {
-            throw new DeclarationError(`${pluginSentence(identity)} holds a value that is not an extension. Supply the value returned by extension(identity, config).`);
+            throw new DeclarationError(foreignValue, {
+                correction: 'Supply the value returned by extension(identity, config).',
+                findings: [partFinding(site, [index])],
+                sentence: `${pluginSentence(identity)} holds a value that is not an extension.`,
+            });
         }
-        registerDescriptor(build.descriptors, descriptor);
+        registerDescriptor(build.descriptors, descriptor, {
+            holder: pluginSentence(identity),
+            place: partFinding(site, [index]),
+        });
     }
 }
 /**
- * Every rule one definition carries on its own, in the order the definition's slots are read. The
- * plugin's own extensions register before any declaration carries a value, so a duplicated package
- * copy is reported from the list that defines it. The views list is read against core's view
- * identities, and the Application reads it again against every other contributor's.
+ * Every rule one definition carries on its own, in the order the definition's slots are read, each
+ * from the one copy `captureDefinition` takes once the identity is judged. The plugin's own
+ * extensions register before any declaration carries a value, so a duplicated package copy is
+ * reported from the list that defines it. The views list is read against core's view identities,
+ * and the Application reads the same copy again against every other contributor's.
  */
-function readPlugin(identity, definition) {
-    const named = readIdentity(identity);
-    const declaration = definitionOf(named, definition);
+function readPlugin(named, definition) {
+    checkIdentity('plugin', named);
+    const declaration = captureDefinition(named, definition);
     const theme = declaration.theme === undefined ? undefined : buildTheme(declaration.theme, named);
     const build = { descriptors: new Map(), records: new Map() };
     defineExtensions(named, declaration, build);
@@ -357,7 +638,9 @@ function readPlugin(identity, definition) {
     const commands = readCommands(named, declaration.commands);
     const middleware = readMiddleware(named, declaration.middleware, names);
     const onCommandAttach = readHook(named, declaration.onCommandAttach);
-    buildViews({ declares: true, sentence: pluginSentence(named) }, declaration.views, viewIdentities(coreViews));
+    const onFailure = readFailureHook(named, declaration.onFailure);
+    buildViews(pluginViews(named), declaration.views, viewIdentities(coreViews));
+    const translators = readTranslations(pluginSlot(named, 'translators', declaration.translators), declaration.translators);
     return {
         commands,
         descriptors: build.descriptors,
@@ -365,10 +648,12 @@ function readPlugin(identity, definition) {
         inputs,
         middleware,
         onCommandAttach,
+        onFailure,
         records: build.records,
         signals,
         source,
         theme,
+        translators,
         views: declaration.views,
     };
 }
@@ -407,10 +692,10 @@ function pluginValues(inputs, values) {
 /** One plugin's own spellings for one run, frozen, so no plugin writes what another reads. */
 function pluginSpellings(inputs, values) {
     // Entries become own keys even for a name such as `__proto__`, which assignment would not.
-    const spelled = inputs.flatMap(({ name }) => {
+    const supplied = inputs.flatMap(({ name }) => {
         const spelling = values.spellings.get(name);
         return spelling === undefined ? [] : [[name, spelling]];
     });
-    return Object.freeze(Object.fromEntries(spelled));
+    return Object.freeze(Object.fromEntries(supplied));
 }
-export { installPlugins, loadDefault, ownedSignals, plugin, pluginSentence, pluginSpellings, pluginValues, };
+export { installPlugins, loadDefault, ownedSignals, plugin, pluginSentence, pluginSpellings, pluginViews, pluginValues, };