@loomcli/core 0.4.0 → 0.6.0

package/dist/facts.js

@@ -1,4 +1,6 @@
+import { misplacedListingFact, notOneLine } from './command-rules.js';
 import { DeclarationError } from './errors.js';
+import { flagNotBoolean } from './input-rules.js';
 /**
  * One character outside Unicode `White_Space`, so a fact holds prose and not only spacing.
  * The class covers the tab, the space, the line terminators, the no-break space, and every other
@@ -10,17 +12,98 @@ const prose = /\P{White_Space}/u;
  * The seven are LF, VT, FF, CR, NEL, LS, and PS, each of them `White_Space` too.
  */
 const lineTerminator = /[\n\v\f\r\u0085\u2028\u2029]/u;
+/** The finding for the call one site holds, marking one part of it, with a note when given. */
+export function siteFinding(site, mark, note) {
+    const finding = { ...site.declaration, mark };
+    return note === undefined ? finding : { ...finding, note };
+}
+/**
+ * Where one key of a declaration's options object sits, rebuilt with that key alone, as
+ * `plugin(identity, { middleware })` or `new Application(name, { plugins })`, at `1.<key>`. A fault
+ * about one slot shows the slot, not every other one the author declared beside it.
+ */
+export function slotSite(declaration, key, value) {
+    const { call, named, subject } = declaration;
+    // `Object.fromEntries` defines the key as an own property whatever its name.
+    return {
+        at: `1.${key}`,
+        declaration: { arguments: [named, Object.fromEntries([[key, value]])], call },
+        subject,
+    };
+}
+/**
+ * The dotted path to one part inside the value a site holds, such as `1.middleware.activate` for
+ * `activate` under a site at `1.middleware`. A site at the call's own arguments has an empty path.
+ */
+export function partOf(site, ...keys) {
+    return [site.at, ...keys.map(String)].filter((key) => key !== '').join('.');
+}
+/** The finding that marks one part inside the value a site holds, with a note when given. */
+export function partFinding(site, keys, note) {
+    return siteFinding(site, partOf(site, ...keys), note);
+}
+/**
+ * One fact's fault, which marks the fact inside the call that declared it. Every rule about one key
+ * of a declaration's config object reports through it, so each marks the key the same way.
+ */
+export function factFault(rule, site, parts) {
+    const { correction, fact, sentence } = parts;
+    return new DeclarationError(rule, {
+        correction,
+        findings: [siteFinding(site, `${site.at}.${fact}`)],
+        sentence,
+    });
+}
+/**
+ * One yes-or-no declaration key that holds a value other than a Boolean, such as `required` or
+ * `hidden`. Every such key reports under one rule, in one sentence and with one correction.
+ */
+export function flagFault(site, flag) {
+    return factFault(flagNotBoolean, site, {
+        correction: 'Use true or false.',
+        fact: flag,
+        sentence: `${site.subject} declares ${flag} that is not a Boolean.`,
+    });
+}
+/** The site of an input a call declared as `call(name, config)`, such as `option()`. */
+export function callSite(subject, declaration) {
+    return { at: '1', declaration, named: '0', subject };
+}
+/**
+ * The site of one option a plugin declared, rebuilt as `plugin(identity, { options })` from the
+ * options the plugin holds. The option's entry in the record stands for its name.
+ */
+export function pluginOptionSite(plugin, name, subject) {
+    const at = `1.options.${name}`;
+    return {
+        at,
+        declaration: { arguments: [plugin.identity, { options: plugin.options }], call: 'plugin' },
+        named: at,
+        subject,
+    };
+}
+/**
+ * One line of prose: a string that holds a character other than whitespace and no line terminator.
+ * Every one-line fact reads this rule, and so does the label a configuration source answers with.
+ */
+export function isProseLine(value) {
+    return typeof value === 'string' && prose.test(value) && !lineTerminator.test(value);
+}
 /**
  * The `description` core fact: one line of prose every projection reads. A value that is not a
  * string fails the same way a blank one does, because the author reads one rule for one fact.
  * An omitted description is absent, not a fault, so it passes through as `undefined`.
  */
-export function checkDescription(subject, value) {
+export function checkDescription(site, value) {
     if (value === undefined) {
         return undefined;
     }
-    if (typeof value !== 'string' || !prose.test(value) || lineTerminator.test(value)) {
-        throw new DeclarationError(`${subject} description must hold a character other than whitespace and no line terminator. Supply a one-line summary.`);
+    if (!isProseLine(value)) {
+        throw factFault(notOneLine, site, {
+            correction: 'Supply a one-line summary.',
+            fact: 'description',
+            sentence: `${site.subject} description must hold a character other than whitespace and no line terminator.`,
+        });
     }
     return value;
 }
@@ -29,12 +112,12 @@ export function checkDescription(subject, value) {
  * asks one question of it, and an omitted declaration reads `false`. Routing selects and parsing
  * binds without reading it, so a hidden member behaves as any other.
  */
-export function checkHidden(subject, value) {
+export function checkHidden(site, value) {
     if (value === undefined) {
         return false;
     }
     if (typeof value !== 'boolean') {
-        throw new DeclarationError(`${subject} hidden must be a Boolean. Supply true or false, or omit it.`);
+        throw flagFault(site, 'hidden');
     }
     return value;
 }
@@ -44,12 +127,16 @@ export function checkHidden(subject, value) {
  * prints. A bare `true` is rejected with every other value that is not prose: a deprecation with
  * no migration path leaves an operator or an agent with nothing to do.
  */
-export function checkDeprecated(subject, value) {
+export function checkDeprecated(site, value) {
     if (value === undefined) {
         return undefined;
     }
-    if (typeof value !== 'string' || !prose.test(value) || lineTerminator.test(value)) {
-        throw new DeclarationError(`${subject} deprecated message must hold a character other than whitespace and no line terminator. Supply a one-line migration path, such as "Use get instead.".`);
+    if (!isProseLine(value)) {
+        throw factFault(notOneLine, site, {
+            correction: 'Supply a one-line migration path, such as "Use get instead.".',
+            fact: 'deprecated',
+            sentence: `${site.subject} deprecated message must hold a character other than whitespace and no line terminator.`,
+        });
     }
     return value;
 }
@@ -59,10 +146,14 @@ export function checkDeprecated(subject, value) {
  * a JavaScript author, or a TypeScript author whose argument config is inferred from a value,
  * reaches this rule instead.
  */
-export function checkNoListingFacts(subject, declared) {
+export function checkNoListingFacts(site, declared) {
     for (const fact of ['hidden', 'deprecated']) {
         if (fact in declared) {
-            throw new DeclarationError(`${subject} declares ${fact}, which applies to named Commands and options alone. Remove it.`);
+            throw factFault(misplacedListingFact, site, {
+                correction: 'Remove it.',
+                fact,
+                sentence: `${site.subject} declares ${fact}, which applies to named Commands and options alone.`,
+            });
         }
     }
 }
@@ -72,24 +163,16 @@ export function checkNoListingFacts(subject, declared) {
  * omitted version is `0.0.0`, which means unversioned, and core keeps no record of which one the
  * author wrote.
  */
-export function checkVersion(value) {
+export function checkVersion(site, value) {
     if (value === undefined) {
         return '0.0.0';
     }
-    if (typeof value !== 'string' || !prose.test(value) || lineTerminator.test(value)) {
-        throw new DeclarationError('The Application version must be a string that holds a character other than whitespace and no line terminator. Supply a string such as "1.2.0".');
+    if (!isProseLine(value)) {
+        throw factFault(notOneLine, site, {
+            correction: 'Supply a string such as "1.2.0".',
+            fact: 'version',
+            sentence: `${site.subject} version must be a string that holds a character other than whitespace and no line terminator.`,
+        });
     }
     return value;
 }
-/**
- * A structural value core reads as plain data: an object literal, and never a declaration that
- * carries state of its own. The options slots read it to reject a value that is not an options
- * object, and inspection reads it to copy a declared value faithfully.
- */
-export function isPlainObject(value) {
-    if (value === null || typeof value !== 'object') {
-        return false;
-    }
-    const prototype = Object.getPrototypeOf(value);
-    return prototype === Object.prototype || prototype === null;
-}

package/dist/globals.d.ts

@@ -1,6 +1,9 @@
-import { DeclarationError } from './errors.js';
+import type { BoundOption } from './bindings.js';
+import type { DescriptorRegistry } from './extension.js';
+import type { InputSite } from './facts.js';
 import { compileOptions } from './options.js';
-import type { BuiltPlugin, PluginBuild } from './plugin.js';
+import type { CompileScope } from './options.js';
+import type { BuiltPlugin } from './plugin.js';
 import type { OptionConfig, OptionValue } from './types.js';
 import type { InputDeclaration, OptionInput, ValidatedInputs } from './validation.js';
 /**
@@ -18,40 +21,78 @@ type OptionOwner = {
     identity: string;
     order: number;
 };
-/** One side of a collision: the option's declared name under the scope that declared it. */
-interface OptionSite {
-    name: string;
+/** One option the globals table holds: the scope that declared it, and where it was declared. */
+interface TableEntry {
     owner: OptionOwner;
+    site: InputSite;
 }
-/** One key claimed twice, whichever two scopes claimed it. */
-declare function keyCollision(name: string, first: OptionOwner, second: OptionOwner): DeclarationError;
-/** One spelling claimed twice, whichever two scopes claimed it. */
-declare function spellingCollision(spelling: string, first: OptionSite, second: OptionSite): DeclarationError;
 /**
- * The compiled global table: one spelling map shared by every Command in the graph. It holds the
- * application's global options and every installed plugin's options, because the pre-scan reads one
- * table. `inputs` holds the application's declarations alone, because a plugin option is never
- * validated and never reaches an action.
+ * The globals table the pre-scan reads, with every rule that pairs two of its options settled: one
+ * spelling map, the scope that owns each key and where it was declared, and the variable each
+ * option binds. It holds the application's global options and every installed plugin's options,
+ * because the pre-scan reads one table.
  */
-interface BuiltGlobals {
-    bind: (values: ValidatedInputs) => unknown;
-    inputs: readonly InputDeclaration[];
-    names: ReadonlyMap<string, OptionOwner>;
+interface GlobalTable {
+    names: ReadonlyMap<string, TableEntry>;
     options: ReturnType<typeof compileOptions>;
+    /** The variable each option in the table binds, with the option that binds it. */
+    variables: ReadonlyMap<string, BoundOption>;
+}
+/**
+ * The compiled table one graph build shares. `inputs` holds the application's declarations alone,
+ * because a plugin option is never validated and never reaches an action.
+ */
+interface BuiltGlobals extends GlobalTable {
+    bind: (values: ValidatedInputs) => unknown;
+    inputs: readonly OptionInput[];
     plugins: readonly BuiltPlugin[];
 }
-/** The Application's private global declarations and their schema-derived value binder. */
+/** The validated extension record of each declaration, keyed by the declaration itself. */
+type InputRecords = ReadonlyMap<InputDeclaration, Readonly<Record<string, unknown>>>;
+/**
+ * The Application's private global declarations, their schema-derived value binder, and the
+ * extension record each declaration's own call validated.
+ */
 interface GlobalsState<Globals = unknown> {
     bind: (values: ValidatedInputs) => Globals;
     inputs: readonly OptionInput[];
+    records: InputRecords;
 }
 declare function emptyGlobals(): GlobalsState<{}>;
-declare function declareGlobalOption<Globals, Name extends string, Config extends OptionConfig>(state: GlobalsState<Globals>, input: OptionInput<Name, Config>): GlobalsState<Globals & Record<Name, OptionValue<Config>>>;
+/** Where one global option was declared: its `globalOption()` call on the Application. */
+declare function globalSite(input: OptionInput): InputSite;
+/**
+ * Where each of one plugin's options was declared: its entry in the `options` record of the
+ * plugin's `plugin()` call, which is rebuilt from every option the plugin holds.
+ */
+declare function pluginSites(identity: string, inputs: readonly OptionInput[]): (input: OptionInput) => InputSite;
+/**
+ * One global option's own facts, binding, and extension values, checked at its `globalOption()`
+ * call against the Application's descriptors. The rules that pair it with another option belong to
+ * the table, which the caller rebuilds with it.
+ */
+declare function declareGlobalOption<Globals, Name extends string, Config extends OptionConfig>(state: GlobalsState<Globals>, declared: OptionInput<Name, Config>, descriptors: DescriptorRegistry): {
+    readonly input: OptionInput<Name, Config>;
+    readonly state: GlobalsState<Globals & Record<Name, OptionValue<Config>>>;
+};
 /**
  * The one table the pre-scan reads: the application's global options in authoring order, then each
  * installed plugin's options in installation order. Every collision between the two scopes, by key
  * or by spelling, is reported here, so the pre-scan meets a table with one owner per name.
  */
-declare function buildGlobals(node: GlobalsState, plugins: readonly BuiltPlugin[], build: PluginBuild): BuiltGlobals;
-export type { BuiltGlobals, GlobalsState, OptionOwner, OptionSite };
-export { buildGlobals, declareGlobalOption, emptyGlobals, keyCollision, spellingCollision };
+declare function globalTable(inputs: readonly OptionInput[], plugins: readonly BuiltPlugin[]): GlobalTable;
+/** The table one graph build shares, which every earlier call already proved free of collisions. */
+declare function buildGlobals(node: GlobalsState, plugins: readonly BuiltPlugin[]): BuiltGlobals;
+/**
+ * One Command's own options against the globals table, compiled for dispatch. The table holds the
+ * application's globals and every plugin option, so a local collision reads the same sentence
+ * whichever scope on the other side claimed the name, the spelling, or the variable. One
+ * invocation's scope is this Command's own options and the table, so a variable binds one option
+ * there, while a sibling Command may bind it again. `scope` names the Command and places each of
+ * its options.
+ */
+declare function checkLocalOptions(declarations: readonly OptionInput[], table: GlobalTable, scope: CompileScope<OptionInput>): ReturnType<typeof compileOptions>;
+/** The options in one list that bind a variable, each named and placed by its scope. */
+declare function boundOptions(inputs: readonly OptionInput[], describe: (input: OptionInput) => Omit<BoundOption, 'variable'>): BoundOption[];
+export type { BuiltGlobals, GlobalsState, GlobalTable, InputRecords, OptionOwner, TableEntry };
+export { boundOptions, buildGlobals, checkLocalOptions, declareGlobalOption, emptyGlobals, globalSite, globalTable, pluginSites, };

package/dist/globals.js

@@ -1,8 +1,17 @@
-import { DeclarationError } from './errors.js';
+import { checkEnvBinding, claimVariables } from './bindings.js';
+import { DeclarationError, quoted } from './errors.js';
 import { buildExtensions } from './extension.js';
-import { checkDeprecated, checkDescription, checkHidden } from './facts.js';
-import { compileOptions } from './options.js';
+import { callSite, checkDeprecated, checkDescription, checkHidden, factFault, pluginOptionSite, siteFinding, } from './facts.js';
+import { globalPresenceRule, optionDeclaredTwice, spellingTaken } from './input-rules.js';
+import { checkOptionName, compileOptions, spellingMark } from './options.js';
+import { captureConfig, checkInputConfig } from './validation.js';
 const globalSubject = 'the global options';
+/**
+ * The presence keys a global option may not declare, in the order its diagnostic names them. A
+ * global's validation runs on every Command, plugin Commands included, so a rule that a value must
+ * exist belongs to the Commands that read it.
+ */
+const omissionRules = ['required', 'validateOmitted'];
 /** A collision sentence names a plugin first, then the application's globals, then a local. */
 const ranks = {
     application: 1,
@@ -22,7 +31,7 @@ function ordered(first, second) {
 /** How one owner reads in a key collision. A repeated preposition is dropped after the first. */
 function declaredBy(owner, leading) {
     if (owner.kind === 'plugin') {
-        return `${leading ? 'by ' : ''}plugin "${owner.identity}"`;
+        return `${leading ? 'by ' : ''}plugin ${quoted(owner.identity)}`;
     }
     return owner.kind === 'application'
         ? 'as a global option'
@@ -31,11 +40,11 @@ function declaredBy(owner, leading) {
 /** How one owner reads in a spelling collision, where each side names its own option. */
 function usedBy({ name, owner }) {
     if (owner.kind === 'plugin') {
-        return `plugin "${owner.identity}" option "${name}"`;
+        return `plugin ${quoted(owner.identity)} option ${quoted(name)}`;
     }
     return owner.kind === 'application'
-        ? `the global option "${name}"`
-        : `the local option "${name}" on ${owner.subject}`;
+        ? `the global option ${quoted(name)}`
+        : `the local option ${quoted(name)} on ${owner.subject}`;
 }
 /** The correction each pair earns: a local is renamed, and two plugins are chosen between. */
 function correction(first, second) {
@@ -46,23 +55,91 @@ function correction(first, second) {
         ? 'Install one of them or rename the option.'
         : 'Rename one declaration.';
 }
+/** The note beside one side's finding, which says which scope declared it. */
+const sideNotes = {
+    application: 'the global option',
+    local: 'the local option',
+    plugin: 'the plugin option',
+};
 /** One key claimed twice, whichever two scopes claimed it. */
-function keyCollision(name, first, second) {
-    const [leading, trailing] = ordered({ name, owner: first }, { name, owner: second });
-    return new DeclarationError(`Option "${name}" is declared ${declaredBy(leading.owner, true)} and ${declaredBy(trailing.owner, false)}. ${correction(leading.owner, trailing.owner)}`);
+function keyCollision(first, second) {
+    const pair = ordered(first, second);
+    const [leading, trailing] = pair;
+    return new DeclarationError(optionDeclaredTwice, {
+        correction: correction(leading.owner, trailing.owner),
+        findings: pair.map(({ owner, site }) => siteFinding(site, site.named, sideNotes[owner.kind])),
+        sentence: `Option ${quoted(leading.name)} is declared ${declaredBy(leading.owner, true)} and ${declaredBy(trailing.owner, false)}.`,
+    });
 }
 /** One spelling claimed twice, whichever two scopes claimed it. */
 function spellingCollision(spelling, first, second) {
-    const [leading, trailing] = ordered(first, second);
-    return new DeclarationError(`Option spelling "${spelling}" is used by ${usedBy(leading)} and ${usedBy(trailing)}. Change one declaration.`);
+    const pair = ordered(first, second);
+    const [leading, trailing] = pair;
+    return new DeclarationError(spellingTaken, {
+        correction: 'Change one declaration.',
+        findings: pair.map(({ owner, role, site }) => siteFinding(site, spellingMark(site, role), sideNotes[owner.kind])),
+        sentence: `Option spelling ${quoted(spelling)} is used by ${usedBy(leading)} and ${usedBy(trailing)}.`,
+    });
 }
 function emptyGlobals() {
-    return { bind: () => ({}), inputs: [] };
+    return { bind: () => ({}), inputs: [], records: new Map() };
+}
+/** Where one global option was declared: its `globalOption()` call on the Application. */
+function globalSite(input) {
+    // A global option belongs to the application, not to one Command, so its facts read that way.
+    return callSite(`Global option ${quoted(input.name)}`, {
+        arguments: [input.name, input.config],
+        call: 'globalOption',
+        path: [],
+    });
 }
-function declareGlobalOption(state, input) {
+/**
+ * Where each of one plugin's options was declared: its entry in the `options` record of the
+ * plugin's `plugin()` call, which is rebuilt from every option the plugin holds.
+ */
+function pluginSites(identity, inputs) {
+    const options = Object.fromEntries(inputs.map(({ config, name }) => [name, config]));
+    return (input) => pluginOptionSite({ identity, options }, input.name, `Plugin ${quoted(identity)} option "${input.name}"`);
+}
+/**
+ * One global option's own facts, binding, and extension values, checked at its `globalOption()`
+ * call against the Application's descriptors. The rules that pair it with another option belong to
+ * the table, which the caller rebuilds with it.
+ */
+function declareGlobalOption(state, declared, descriptors) {
+    // The name is judged before the config, as every other declaration judges its own name first.
+    checkOptionName(declared.name, globalSite(declared));
+    checkInputConfig(declared, { call: 'globalOption', path: [] });
+    const input = { ...declared, config: captureConfig(declared.config) };
+    const site = globalSite(input);
+    const sentence = site.subject;
+    const rejected = omissionRules.find((key) => key in input.config);
+    if (rejected !== undefined) {
+        throw factFault(globalPresenceRule, site, {
+            correction: `Remove ${rejected}, and check for the value in each Command that needs it.`,
+            fact: rejected,
+            sentence: `${sentence} declares ${rejected}.`,
+        });
+    }
+    checkDescription(site, input.config.description);
+    checkHidden(site, input.config.hidden);
+    checkDeprecated(site, input.config.deprecated);
+    checkEnvBinding(site, input.config);
+    const record = buildExtensions({
+        declared: input.config.extensions,
+        descriptors,
+        site: { ...site, at: '1.extensions' },
+        subject: { phrase: `on the global option ${quoted(input.name)}`, sentence },
+        target: 'option',
+    });
+    // The caller validates the captured input this state stores, so both read one capture.
     return {
-        bind: (values) => ({ ...state.bind(values), ...values.option(input) }),
-        inputs: [...state.inputs, input],
+        input,
+        state: {
+            bind: (values) => ({ ...state.bind(values), ...values.option(input) }),
+            inputs: [...state.inputs, input],
+            records: new Map([...state.records, [input, record]]),
+        },
     };
 }
 /**
@@ -70,48 +147,96 @@ function declareGlobalOption(state, input) {
  * installed plugin's options in installation order. Every collision between the two scopes, by key
  * or by spelling, is reported here, so the pre-scan meets a table with one owner per name.
  */
-function buildGlobals(node, plugins, build) {
+function globalTable(inputs, plugins) {
     const names = new Map();
     const application = { kind: 'application' };
-    // A global option belongs to the application, not to one Command, so its facts read that way.
-    for (const input of node.inputs) {
-        const sentence = `Global option "${input.name}"`;
-        checkDescription(sentence, input.config.description);
-        checkHidden(sentence, input.config.hidden);
-        checkDeprecated(sentence, input.config.deprecated);
-        build.extensions.set(input, buildExtensions({
-            declared: input.config.extensions,
-            descriptors: build.descriptors,
-            subject: { phrase: `on the global option "${input.name}"`, sentence },
-            target: 'option',
-        }));
-        names.set(input.name, application);
+    for (const input of inputs) {
+        names.set(input.name, { owner: application, site: globalSite(input) });
     }
-    const options = compileOptions(node.inputs, globalSubject);
+    const options = compileOptions(inputs, { siteOf: globalSite, subject: globalSubject });
     plugins.forEach((installed, order) => {
         join({ identity: installed.identity, kind: 'plugin', order }, installed.inputs, {
             names,
             options,
         });
     });
-    return { bind: node.bind, inputs: node.inputs, names, options, plugins };
+    const variables = claimVariables([
+        ...boundOptions(inputs, (input) => ({
+            phrase: `global option ${quoted(input.name)}`,
+            site: globalSite(input),
+        })),
+        ...plugins.flatMap((installed) => {
+            const siteOf = pluginSites(installed.identity, installed.inputs);
+            return boundOptions(installed.inputs, (input) => ({
+                phrase: `plugin ${quoted(installed.identity)} option "${input.name}"`,
+                site: siteOf(input),
+            }));
+        }),
+    ]);
+    return { names, options, variables };
+}
+/** The table one graph build shares, which every earlier call already proved free of collisions. */
+function buildGlobals(node, plugins) {
+    return { ...globalTable(node.inputs, plugins), bind: node.bind, inputs: node.inputs, plugins };
+}
+/**
+ * One Command's own options against the globals table, compiled for dispatch. The table holds the
+ * application's globals and every plugin option, so a local collision reads the same sentence
+ * whichever scope on the other side claimed the name, the spelling, or the variable. One
+ * invocation's scope is this Command's own options and the table, so a variable binds one option
+ * there, while a sibling Command may bind it again. `scope` names the Command and places each of
+ * its options.
+ */
+function checkLocalOptions(declarations, table, scope) {
+    const { siteOf, subject } = scope;
+    const local = { kind: 'local', subject };
+    for (const declaration of declarations) {
+        const claimed = table.names.get(declaration.name);
+        if (claimed) {
+            throw keyCollision({ ...claimed, name: declaration.name }, { name: declaration.name, owner: local, site: siteOf(declaration) });
+        }
+    }
+    const options = compileOptions(declarations, scope);
+    for (const [spelling, option] of options) {
+        const global = table.options.get(spelling);
+        const claimed = global && table.names.get(global.name);
+        const declaration = declarations.find((input) => input.name === option.name);
+        if (global && claimed && declaration) {
+            throw spellingCollision(spelling, { ...claimed, name: global.name, role: global.role }, { name: option.name, owner: local, role: option.role, site: siteOf(declaration) });
+        }
+    }
+    claimVariables(boundOptions(declarations, (input) => ({
+        phrase: `${subject} option "${input.name}"`,
+        site: siteOf(input),
+    })), table.variables);
+    return options;
+}
+/** The options in one list that bind a variable, each named and placed by its scope. */
+function boundOptions(inputs, describe) {
+    return inputs.flatMap((input) => input.config.env === undefined ? [] : [{ ...describe(input), variable: input.config.env }]);
 }
 /** One plugin's options joining the table the application's globals already hold. */
 function join(owner, inputs, table) {
     const { names, options } = table;
+    const siteOf = pluginSites(owner.identity, inputs);
     for (const input of inputs) {
         const claimed = names.get(input.name);
         if (claimed) {
-            throw keyCollision(input.name, owner, claimed);
+            throw keyCollision({ name: input.name, owner, site: siteOf(input) }, { ...claimed, name: input.name });
         }
-        names.set(input.name, owner);
+        names.set(input.name, { owner, site: siteOf(input) });
     }
-    for (const [spelling, option] of compileOptions(inputs, `plugin "${owner.identity}"`)) {
-        const claimed = options.get(spelling);
-        if (claimed) {
-            throw spellingCollision(spelling, { name: option.name, owner }, { name: claimed.name, owner: names.get(claimed.name) ?? { kind: 'application' } });
+    for (const [spelling, option] of compileOptions(inputs, {
+        siteOf,
+        subject: `plugin ${quoted(owner.identity)}`,
+    })) {
+        const existing = options.get(spelling);
+        const claimed = existing && names.get(existing.name);
+        const own = names.get(option.name);
+        if (existing && claimed && own) {
+            throw spellingCollision(spelling, { ...own, name: option.name, role: option.role }, { ...claimed, name: existing.name, role: existing.role });
         }
         options.set(spelling, option);
     }
 }
-export { buildGlobals, declareGlobalOption, emptyGlobals, keyCollision, spellingCollision };
+export { boundOptions, buildGlobals, checkLocalOptions, declareGlobalOption, emptyGlobals, globalSite, globalTable, pluginSites, };

package/dist/hints.d.ts

@@ -0,0 +1,79 @@
+import type { Writable } from 'node:stream';
+import type { DeveloperScene } from './developer.js';
+import type { LoomError } from './errors.js';
+import type { CommandGraph, CommandNode } from './inspect.js';
+import type { Output } from './output.js';
+import type { BuiltPlugin } from './plugin.js';
+import type { ContextualStyle } from './style.js';
+import type { ViewRegistry } from './view.js';
+/**
+ * What one `onFailure` hook reads beside the failure. `application` and `path` are the values the
+ * failure view reads, and `style` is the contextual style for stderr, so a hook escapes text the
+ * operator typed. `graph` is the frozen graph `inspect()` returns for the run, and `command` is the
+ * node at `path` inside it; reading either builds the run's graph once.
+ */
+interface FailureHookContext {
+    readonly application: string;
+    readonly path: readonly string[];
+    readonly style: ContextualStyle;
+    readonly graph: CommandGraph;
+    readonly command: CommandNode;
+}
+/**
+ * A plugin's `onFailure` hook: a synchronous function that returns one hint, a list of hints, or
+ * nothing for a failure `run()` renders after graph build. It receives the failure typed read-only,
+ * as a failure view does. Core does not freeze the failure, and it reads the exit code before any
+ * hook runs, so a working hook cannot change the code.
+ */
+type FailureHook = (failure: Readonly<LoomError>, context: FailureHookContext) => string | readonly string[] | undefined;
+/** What the hooks can read once the graph has built: the installed plugins and the run's graph. */
+interface BuiltRun {
+    plugins: readonly BuiltPlugin[];
+    inspected: () => CommandGraph;
+}
+/**
+ * Where one failure happened, filled where `run()` catches it. `built` is absent for a failure
+ * raised at or before graph build, which no hook runs for, because no valid graph exists.
+ */
+interface FailureScene {
+    application: string;
+    path: readonly string[];
+    built: BuiltRun | undefined;
+}
+/**
+ * What one run's build decides about its reports. A development build shows the author a
+ * Developer Diagnostic for every fault only the author can fix, each after the first report of the
+ * run opening with one blank line; a distributed build shows the generic defect message at most
+ * once per run.
+ */
+interface BuildReports {
+    readonly development: boolean;
+    /** Whether this run has written the generic defect message already. */
+    generic: boolean;
+    /** Whether this run has written a failure report already. */
+    reported: boolean;
+}
+/** Where one failure report is written, the registry its view resolves through, and the build. */
+interface FailureSink {
+    output: Output;
+    registry: ViewRegistry;
+    stderr: Writable;
+    build: BuildReports;
+}
+/**
+ * Reports one failure. The hooks run first, so the diagnostic or the view receives their hints. A
+ * view that breaks leaves core's default text without hints on the plain fallback path, and each
+ * broken contract's report follows that whole diagnostic. It answers whether a view or a hook
+ * broke, which forces the run's code to 1 outside a cancelled run.
+ */
+declare function reportFailure(sink: FailureSink, failure: LoomError, scene: FailureScene & {
+    host: DeveloperScene['host'];
+}): Promise<boolean>;
+/**
+ * What a run writes on the plain fallback path when a destination failed a write or reporting
+ * itself failed: the Developer Diagnostic of the broken destination in a development build, and
+ * the generic defect message, at most once per run, in a distributed one.
+ */
+declare function destinationReport(build: BuildReports, cause: unknown, scene: DeveloperScene): string;
+export type { BuildReports, BuiltRun, FailureHook, FailureHookContext, FailureScene };
+export { destinationReport, reportFailure };