@loomcli/core 0.4.0 → 0.6.0

package/dist/plugin.js

@@ -1,9 +1,22 @@
-import { DeclarationError } from './errors.js';
-import { buildExtensions, isDescriptor, registerDescriptor } from './extension.js';
-import { checkDeprecated, checkDescription, checkHidden, isPlainObject } from './facts.js';
+import { checkEnvBinding, claimVariables } from './bindings.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, 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 { isPlainObject } 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 { readTranslations } from './translators.js';
 import { captureConfig, checkDeclarations } from './validation.js';
+import { buildViews, viewIdentities } from './view.js';
 /** Authored values register here, so the public type publishes no state to reach or replace. */
 const nodes = new WeakMap();
 /**
@@ -19,8 +32,10 @@ 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.
+ * 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. Every rule
+ * that one definition carries on its own throws here, before the value exists.
  */
 function plugin(identity, definition) {
     const captured = {
@@ -29,78 +44,171 @@ function plugin(identity, definition) {
             ? {}
             : { theme: isPlainObject(definition.theme) ? { ...definition.theme } : definition.theme }),
     };
-    return new PluginDeclaration({
-        definition: isPlainObject(definition) ? captured : definition,
-        identity,
-    });
+    return new PluginDeclaration(readPlugin(identity, isPlainObject(definition) ? captured : definition));
 }
 /** 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 installed value declares, which is a nonempty string installed once. */
-function readIdentity(node, installed) {
-    const { identity } = node;
-    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.');
-    }
-    if (installed.has(identity)) {
-        throw new DeclarationError(`The Application installs plugin "${identity}" twice. Install each plugin once.`);
-    }
-    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, node) {
-    const { definition } = node;
+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 }.`);
+        throw 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.`,
+        });
     }
     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 the rules that read the list itself. The slot is
- * read defensively, because a JavaScript author reaches it with any value. Each plugin's own
- * declarations are read by the build steps that consume them, in the order those steps run.
+ * 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.
  */
-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 installed = [];
-    const identities = new Set();
-    for (const value of plugins) {
+    const list = plugins;
+    const installed = list.map((value, index) => {
         const node = nodeOf(value);
-        const identity = readIdentity(node, identities);
-        identities.add(identity);
-        installed.push({ declaration: definitionOf(identity, node), identity });
+        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 = 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;
+        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.`,
+            });
+        }
+        positions.set(identity, index);
+        if (entry.theme !== undefined) {
+            claim('theme', index);
+        }
+        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) {
+            claim('signals', index);
+        }
+        if (entry.source) {
+            claim('source', index);
+        }
     }
-    return installed;
+    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) {
+function checkPluginOption(site, config) {
+    const sentence = site.subject;
     if (!isPlainObject(config)) {
-        throw new DeclarationError(`${sentence} is not an option declaration. Supply { type, ... }.`);
+        throw new DeclarationError(notAnObject, {
+            correction: 'Supply { type, ... }.',
+            findings: [partFinding(site, [])],
+            sentence: `${sentence} is not an option declaration.`,
+        });
     }
     const rejected = forbidden.find((key) => key in config);
     if (rejected !== undefined) {
-        throw new DeclarationError(`${sentence} declares ${rejected}. Remove it; a plugin option carries no schema or presence rule, and the middleware interprets the value.`);
+        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(sentence, config.description);
-    checkHidden(sentence, config.hidden);
-    checkDeprecated(sentence, config.deprecated);
+    checkDescription(site, config.description);
+    checkHidden(site, config.hidden);
+    checkDeprecated(site, config.deprecated);
 }
 /**
  * One plugin's option declarations, in declaration order. They join the globals table, so the rules
@@ -108,18 +216,25 @@ 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);
+        const sentence = `${pluginSentence(identity)} option ${quoted(name)}`;
+        const site = pluginOptionSite({ identity, options: declared }, name, sentence);
+        checkPluginOption(site, config);
+        checkEnvBinding(site, config);
         const input = { config: captureConfig(config), kind: 'option', name };
         // The shared rules name the plugin and the option, so a fault reads with its contributor.
-        checkDeclarations([input], sentence);
-        build.extensions.set(input, buildExtensions({
+        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,
@@ -128,28 +243,50 @@ 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.
+    const siteOf = pluginSites(identity, inputs);
+    compileOptions(inputs, { siteOf, subject: `plugin ${quoted(identity)}` });
+    claimVariables(boundOptions(inputs, (input) => ({
+        phrase: `plugin ${quoted(identity)} option "${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'.`);
+        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) => readActivationName(identity, name, names));
+    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
@@ -158,21 +295,110 @@ function readActivation(identity, declared, names) {
 function isLoader(value) {
     return typeof value === 'function';
 }
+/**
+ * The default export one plugin loader resolves to, checked by the guard its caller supplies. A
+ * loader that throws where it is called and one that rejects later are one failure, and a module
+ * without the export names the kind of function it owed, such as `middleware` or `source`.
+ */
+async function loadDefault(identity, load, owed) {
+    let module = undefined;
+    try {
+        module = await load();
+    }
+    catch (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(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 };
 }
+/**
+ * The Commands one plugin attaches to the root, each checked by the attach the root applies, as a
+ * finished Command, against the plugin's own earlier Commands, and against the nesting cap. The
+ * Application attaches them again when it is constructed, against every other root child.
+ */
+function readCommands(identity, declared) {
+    if (declared === undefined) {
+        return [];
+    }
+    if (!Array.isArray(declared)) {
+        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 [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(notACommand, {
+                correction: 'Supply the value returned by new Command(name).',
+                findings: [placement],
+                sentence: `${pluginSentence(identity)} holds a value that is not a Command.`,
+            });
+        }
+        const parent = {
+            argument: undefined,
+            children: commands,
+            hasAction: false,
+            name: null,
+            path: [],
+        };
+        commands.push(attach(parent, node, placement));
+    }
+    return commands;
+}
 /**
  * One plugin's claim on the signals slot, drawn from the closed set core installs listeners for.
  * An empty list claims nothing, so it leaves the slot free for another plugin.
@@ -183,21 +409,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
@@ -212,67 +456,193 @@ 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;
+}
+/**
+ * The configuration source one plugin declares, or `undefined` for a plugin that declares none.
+ * The binding is one of the plugin's own option-target extensions, so core knows which options to
+ * ask about without knowing what the binding means. The plugin's own options resolve before the
+ * source loads, so none of them may carry its binding.
+ */
+function readSource(identity, declaration, own) {
+    const declared = declaration.source;
+    if (declared === undefined) {
+        return undefined;
+    }
+    const sentence = pluginSentence(identity);
+    const site = pluginSlot(identity, 'source', declared);
+    if (!isPlainObject(declared)) {
+        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;
+    // 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(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) ?? {}, bindingIdentity));
+    if (carrier) {
+        const option = pluginOptionSite({ identity, options: declaration.options }, carrier.name, `${sentence} option ${quoted(carrier.name)}`);
+        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.`);
+        throw new DeclarationError(notAList, {
+            correction: 'Supply a list of extension descriptors.',
+            findings: [partFinding(site, [])],
+            sentence: `${pluginSentence(identity)} declares extensions that are not an array.`,
+        });
     }
-    for (const descriptor of extensions ?? []) {
+    for (const [index, descriptor] of (extensions ?? []).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 installed plugin's declarations, in installation order. A plugin's own extensions register
- * before any declaration carries a value, so a duplicated package copy is reported from the list
- * that installed it.
+ * 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.
  */
-function buildPlugins(installed, build) {
-    /**
-     * The signals slot has one owner, so the first plugin to claim it names the second claimant's
-     * diagnostic. An empty claim leaves the slot free.
-     */
-    let owner = undefined;
-    let themeOwner = undefined;
-    return installed.map(({ declaration, identity }) => {
-        let theme = undefined;
-        if (declaration.theme !== undefined) {
-            if (themeOwner !== undefined) {
-                throw new DeclarationError(`${pluginSentence(identity)} claims the theme slot, which plugin "${themeOwner}" already holds. Install one owner.`);
-            }
-            theme = buildTheme(declaration.theme, identity);
-            themeOwner = identity;
-        }
-        defineExtensions(identity, declaration, build);
-        const inputs = readOptions(identity, declaration.options, build);
-        const names = new Set(inputs.map((input) => input.name));
-        const signals = readSignals(identity, declaration.signals);
-        if (signals.length > 0) {
-            if (owner !== undefined) {
-                throw new DeclarationError(`${pluginSentence(identity)} claims the signals slot, which plugin "${owner}" already holds. Install one owner.`);
-            }
-            owner = identity;
-        }
-        return {
-            identity,
-            inputs,
-            middleware: readMiddleware(identity, declaration.middleware, names),
-            onCommandAttach: readHook(identity, declaration.onCommandAttach),
-            signals,
-            theme,
-            views: declaration.views,
-        };
-    });
+function readPlugin(named, definition) {
+    checkIdentity('plugin', named);
+    const declaration = definitionOf(named, definition);
+    const theme = declaration.theme === undefined ? undefined : buildTheme(declaration.theme, named);
+    const build = { descriptors: new Map(), records: new Map() };
+    defineExtensions(named, declaration, build);
+    const inputs = readOptions(named, declaration.options, build);
+    const names = new Set(inputs.map((input) => input.name));
+    const signals = readSignals(named, declaration.signals);
+    const source = readSource(named, declaration, { build, inputs });
+    const commands = readCommands(named, declaration.commands);
+    const middleware = readMiddleware(named, declaration.middleware, names);
+    const onCommandAttach = readHook(named, declaration.onCommandAttach);
+    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,
+        identity: named,
+        inputs,
+        middleware,
+        onCommandAttach,
+        onFailure,
+        records: build.records,
+        signals,
+        source,
+        theme,
+        translators,
+        views: declaration.views,
+    };
 }
 /** The signals the one slot owner claimed, or none when no installed plugin claims the slot. */
 function ownedSignals(plugins) {
     return plugins.find((entry) => entry.signals.length > 0)?.signals ?? [];
 }
-export { buildPlugins, installPlugins, ownedSignals, plugin, pluginSentence };
+/** A collected value, or the declared array default, as this run's own copy. */
+function collectedValue(collected, declared) {
+    if (collected) {
+        return [...collected];
+    }
+    return Array.isArray(declared) ? [...declared] : [];
+}
+/** One plugin option's value for one run: what a tier supplied, or the declared default. */
+function pluginValue({ config, name }, values) {
+    const declared = config.default;
+    if (config.type === 'boolean') {
+        return booleanValue(values, name, config);
+    }
+    if (config.multiple === true) {
+        return collectedValue(values.lists.get(name), declared);
+    }
+    // Build already proved that a string option without a validator declares a string default.
+    return values.strings.get(name) ?? (typeof declared === 'string' ? declared : undefined);
+}
+/**
+ * One plugin's own option values for one run: what argv or an input source supplied, or the
+ * declared default, filled without validation. A collected value and an array default are copied,
+ * so a plugin that writes to what it received changes neither the declaration nor the next run.
+ * Entries become own keys even for a name such as `__proto__`, which assignment would not.
+ */
+function pluginValues(inputs, values) {
+    return Object.fromEntries(inputs.map((input) => [input.name, pluginValue(input, 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 supplied = inputs.flatMap(({ name }) => {
+        const spelling = values.spellings.get(name);
+        return spelling === undefined ? [] : [[name, spelling]];
+    });
+    return Object.freeze(Object.fromEntries(supplied));
+}
+export { installPlugins, loadDefault, ownedSignals, plugin, pluginSentence, pluginSpellings, pluginViews, pluginValues, };