@loomcli/core 0.5.0 → 0.7.0

package/dist/application.js

@@ -1,18 +1,28 @@
+import { captureDeclaration, unreadableArgument } from './capture.js';
 import { runInvocation } from './chain.js';
-import { attachToRoot, childNode, buildGraph, checkDeclaredOptions, collectInputs, declareAction, declareExtensions, declareArgument, declareOption, declareResult, declareResultViews, freshState, isPortableName, layerOf, portableNameCorrection, } from './command.js';
-import { DeclarationError, InternalError, reasonOf, toFailure } from './errors.js';
+import { portableName } from './command-rules.js';
+import { attachToRoot, callArguments, childNode, buildGraph, checkDeclaredOptions, collectInputs, commandPlacement, inputPlaces, declareAction, declareExtensions, declareArgument, declareOption, declareResult, declareResultViews, freshState, isPortableName, layerOf, portableNameCorrection, } from './command.js';
+import { escapeControlCharacters } from './controls.js';
+import { elided, spelled } from './diagnostic-text.js';
+import { DeclarationError, exitCodeOf, InternalError, quoted, reasonOf, toFailure, } from './errors.js';
 import { storeCommandLayers } from './extension.js';
-import { checkDescription, checkNoListingFacts, checkVersion, isPlainObject } from './facts.js';
-import { declareGlobalOption, emptyGlobals, globalTable } from './globals.js';
+import { checkDescription, checkNoListingFacts, checkVersion, partFinding, slotSite, } from './facts.js';
+import { declareGlobalOption, emptyGlobals, globalSite, globalTable } from './globals.js';
+import { destinationReport, reportFailure } from './hints.js';
 import { captureHost } from './host.js';
+import { globalOptionAfterCommand } from './input-rules.js';
 import { inspectGraph } from './inspect.js';
 import { coreViews } from './lanes.js';
 import { Output, reportPlainly } from './output.js';
-import { installPlugins, ownedSignals, pluginSentence } from './plugin.js';
+import { declaring, isPlainObject, shallowList, shallowRecord } from './plain.js';
+import { invalidPacket, notAnObject, retiredApplicationOption } from './plugin-rules.js';
+import { installPlugins, ownedSignals, pluginViews } from './plugin.js';
 import { renderingPolicy } from './rendering.js';
+import { brokenOutputView, runOptions, viewCorrection } from './rules.js';
 import { bracketRun, cancellationCode, isCancellationEcho } from './signals.js';
-import { captureConfig, checkDeclarations, prepareInputs } from './validation.js';
-import { buildViews, describeFailure, viewIdentities } from './view.js';
+import { readTranslations, translateThrow } from './translators.js';
+import { checkDeclarations, prepareInputs } from './validation.js';
+import { buildViews, viewIdentities } from './view.js';
 /** The registry a failure is reported through when the application's own could not be built. */
 const noViews = [];
 /**
@@ -27,6 +37,16 @@ function silenced(thrown, signal, cancelled) {
  * `undefined` is itself throwable, so the absence is spelled here rather than borrowed from it.
  */
 const noPrimary = Symbol('no primary');
+/**
+ * The write state a run reports by. A destination whose write failure the action let propagate,
+ * and a translator answered, is reported as that translated failure, so its failure is no longer
+ * the destination fault that forces 1.
+ */
+function answeredWrite(writes, answered) {
+    return writes.kind === 'failed' && answered !== undefined && writes.error === answered
+        ? { kind: 'ok' }
+        : writes;
+}
 /**
  * Whether the primary outcome carries one recorded cause already: the value itself, or a failure
  * that wraps it at any depth, which an action that caught a source failure and rethrew its own
@@ -54,10 +74,31 @@ function checkSignal(signal) {
         return undefined;
     }
     if (!(signal instanceof AbortSignal)) {
-        throw new InternalError('run() received a signal that is not an AbortSignal. Supply the signal of an AbortController.', undefined);
+        throw new InternalError(runOptions, {
+            cause: undefined,
+            correction: 'Supply the signal of an AbortController.',
+            sentence: 'run() received a signal that is not an AbortSignal.',
+        });
     }
     return signal;
 }
+/**
+ * Whether a throw in a cancelled run echoes its cancellation, so no translator is offered it. A
+ * value that cannot be read, such as an Error whose `name` getter throws, counts as an echo, so
+ * it keeps its cancellation code and no translator replaces it.
+ */
+function echoesCancellation(thrown, controller) {
+    const { signal } = controller;
+    if (!signal.aborted) {
+        return false;
+    }
+    try {
+        return isCancellationEcho(thrown, signal.reason);
+    }
+    catch {
+        return true;
+    }
+}
 /**
  * The Application holds the unnamed root's declaration state and applies the same transitions a
  * Command does, so each declaration call has one typed implementation and no builder to recover.
@@ -78,7 +119,7 @@ class ApplicationBuilder {
     }
     argument(name, config) {
         const input = {
-            config: captureConfig(config),
+            config,
             kind: 'argument',
             name,
         };
@@ -86,7 +127,7 @@ class ApplicationBuilder {
     }
     option(name, config) {
         const input = {
-            config: captureConfig(config),
+            config,
             kind: 'option',
             name,
         };
@@ -94,19 +135,31 @@ class ApplicationBuilder {
     }
     globalOption(name, config) {
         // The plugins' Commands attach at construction, so only the application's own calls close it.
+        // The config is judged after the order, so the finding prints it elided and reads none of it.
         if (this.#config.composed) {
-            throw new DeclarationError(`The Application declares global option "${name}" after command() or action(). Declare global options before attaching Commands or registering an action.`);
+            throw new DeclarationError(globalOptionAfterCommand, {
+                correction: 'Declare global options before attaching Commands or registering an action.',
+                findings: [
+                    {
+                        arguments: callArguments(name, config === undefined ? undefined : spelled(elided)),
+                        call: 'globalOption',
+                        mark: '0',
+                        path: [],
+                    },
+                ],
+                sentence: `The Application declares global option ${quoted(name)} after command() or action().`,
+            });
         }
         const input = {
-            config: captureConfig(config),
+            config,
             kind: 'option',
             name,
         };
         const descriptors = new Map(this.#root.descriptors);
-        const globals = declareGlobalOption(this.#globals, input, descriptors);
+        const { input: captured, state: globals } = declareGlobalOption(this.#globals, input, descriptors);
         const root = { ...this.#root, descriptors };
         checkDeclaredOptions(root, globalTable(globals.inputs, this.#config.plugins));
-        checkDeclarations([input]);
+        checkDeclarations([{ input: captured, site: globalSite(captured) }]);
         return new ApplicationBuilder(this.#name, { config: this.#config, globals, root });
     }
     /** Registering the action closes input authoring; extension configuration remains available. */
@@ -120,7 +173,8 @@ class ApplicationBuilder {
             owners: new Map(this.#config.owners),
             table: this.table(),
         };
-        const root = attachToRoot(this.#root, childNode(null, child), scope);
+        const node = childNode(null, child);
+        const root = attachToRoot(this.#root, { node, placement: commandPlacement([], node.name) }, scope);
         return this.derive(root, { composed: true, owners: scope.owners });
     }
     /**
@@ -180,7 +234,10 @@ class ApplicationBuilder {
             rendering: () => undefined,
             views: () => undefined,
         });
-        return inspectGraph(this.#name, built.graph, built.facts);
+        return inspectGraph(this.#name, built.graph, {
+            ...built.facts,
+            development: this.#config.development,
+        });
     }
     async run(options) {
         let stderr = process.stderr;
@@ -193,6 +250,27 @@ class ApplicationBuilder {
         const faults = [];
         // The failure this run reports as its primary outcome, so nothing reports it a second time.
         let primary = noPrimary;
+        // Each failure a translator answered, keyed to the foreign throw it replaced.
+        const translatedFrom = new Map();
+        // Where a failure happened: the path routing walked, and what the hooks read once the graph built.
+        let walked = Object.freeze([]);
+        let reached = undefined;
+        // The host a failure's report reads, once it is captured; before that, the process's own.
+        let reportHost = undefined;
+        const scene = () => ({
+            application: this.#name,
+            built: reached,
+            host: (reportHost ??= captureHost(undefined, stderr)),
+            path: walked,
+        });
+        // What this run's build decides about its reports, shared by every report the run writes.
+        const build = {
+            development: this.#config.development,
+            generic: false,
+            reported: false,
+        };
+        // What broke the run's reporting: a destination's write error, or a throw while reporting.
+        let reportingCause = undefined;
         // One private controller per run, subscribed to the caller's signal at run entry.
         const controller = new AbortController();
         /**
@@ -207,6 +285,20 @@ class ApplicationBuilder {
             const reason = graphBuilt ? signals?.reason() : undefined;
             return reason ? cancellationCode(reason) : undefined;
         };
+        /**
+         * Offers one throw from the application's work to the translators. A view's failure and a
+         * cancellation echo are never offered, because each already names what it is.
+         */
+        const offer = (thrown) => {
+            if (output?.raisedByView(thrown) === true || echoesCancellation(thrown, controller)) {
+                return undefined;
+            }
+            const failure = translateThrow(this.#config.translators, thrown);
+            if (failure !== undefined) {
+                translatedFrom.set(failure, thrown);
+            }
+            return failure;
+        };
         /**
          * Every exit path of the run leaves through the removal below, the one place it is written,
          * so no listener this run installed outlives it however the run ends.
@@ -216,6 +308,7 @@ class ApplicationBuilder {
                 const overrides = options?.host;
                 stderr = overrides?.stderr ?? stderr;
                 const host = captureHost(overrides, stderr);
+                reportHost = host;
                 const invocationOutput = new Output(host, controller.signal);
                 output = invocationOutput;
                 // The constructor validated the declared policy, which the build hands over after the overrides.
@@ -226,7 +319,8 @@ class ApplicationBuilder {
                         invocationOutput.configure(policy, plugins.find((entry) => entry.theme !== undefined)?.theme ?? new Map());
                     },
                     rendering: (declared) => {
-                        policy = { ...declared, ...renderingPolicy(options?.rendering) };
+                        const rendering = options?.rendering;
+                        policy = { ...declared, ...renderingPolicy(rendering, runRendering(rendering)) };
                         invocationOutput.configure(policy, new Map());
                     },
                     views: (value) => {
@@ -235,8 +329,17 @@ class ApplicationBuilder {
                     },
                 });
                 const { graph } = built;
+                // The graph `inspect()` returns, built at most once for the run, whoever reads it first.
+                let inspectedGraph = undefined;
+                const { development } = this.#config;
+                const inspected = () => (inspectedGraph ??= inspectGraph(this.#name, graph, { ...built.facts, development }));
+                reached = { inspected, plugins: built.plugins };
+                if (development) {
+                    // A development build asks every converter at build, so its check runs on every run.
+                    inspected();
+                }
                 const inputs = { globals: graph.globals.inputs, locals: collectInputs(graph.root) };
-                const defaults = await prepareInputs(inputs, host);
+                const defaults = await prepareInputs(inputs, host, inputPlaces(graph));
                 graphBuilt = true;
                 if (!controller.signal.aborted) {
                     /**
@@ -247,14 +350,15 @@ class ApplicationBuilder {
                     await runInvocation({
                         channel: (binding) => invocationOutput.channel(binding),
                         defaults,
-                        facts: built.facts,
                         graph,
                         host,
-                        name: this.#name,
+                        inspected,
+                        offer,
                         out: output.out,
                         plugins: built.plugins,
                         report: (fault) => faults.push(fault),
                         route: (path) => {
+                            walked = path;
                             invocationOutput.useRoute(path);
                         },
                         signal: controller.signal,
@@ -268,80 +372,96 @@ class ApplicationBuilder {
                 const fault = output.fault;
                 if (fault) {
                     // The action returned, so the view failure is this invocation's own failure.
-                    throw new InternalError(`Rendering output failed: ${reasonOf(fault.cause)}`, fault.cause);
+                    throw new InternalError(brokenOutputView, {
+                        cause: fault.cause,
+                        correction: viewCorrection,
+                        sentence: `Rendering output failed: ${reasonOf(fault.cause)}`,
+                    });
                 }
             }
             catch (error) {
                 primary = error;
                 try {
                     const failure = toFailure(error);
-                    code = failure.exitCode;
+                    code = exitCodeOf(failure);
                     output ??= new Output(captureHost(undefined, stderr), controller.signal);
-                    const writes = await output.settle();
+                    const writes = answeredWrite(await output.settle(), translatedFrom.get(failure));
                     if (writes.kind === 'ok' && !silenced(error, controller.signal, cancellation())) {
-                        const report = describeFailure(registry ?? noViews, failure, output.context('stderr'));
-                        if (report.kind === 'rendered') {
-                            // The view owns the trailing newline; output resolves its marked text.
-                            await output.report(report.text);
-                        }
-                        else {
+                        // A broken failure view or onFailure hook forces 1 over the failure's own code.
+                        const sink = { build, output, registry: registry ?? noViews, stderr };
+                        if (await reportFailure(sink, failure, scene())) {
                             code = 1;
-                            // `report.text` is core's default text, which already ends in `\n`.
-                            await reportPlainly(stderr, `${report.text}Internal error: Rendering the failure failed: ${report.reason}\n`);
                         }
                     }
                 }
-                catch {
+                catch (reportError) {
                     code = 1;
                     reportingFailed = true;
+                    reportingCause = reportError;
                 }
             }
             /**
              * A sequence that stopped on its own source reports the same way: the call the action never
              * awaited observed nothing, and a failure the action let propagate is the primary outcome
-             * already, so the one it raised is not reported twice.
+             * already, so the one it raised is not reported twice. A throw a translator replaced is
+             * carried by the failure it became, whether or not that failure keeps it as its cause. A
+             * foreign throw that is not carried is a deferred fault, offered to the translators here,
+             * where core would otherwise wrap it as an internal error.
              */
+            // A primary no translator answered replaced nothing, so even a thrown `undefined` is reported.
+            const replaced = translatedFrom.get(primary) ?? noPrimary;
+            const deferred = new Set();
             for (const cause of output?.stopped ?? []) {
-                if (!carried(primary, cause)) {
-                    faults.push(toFailure(cause));
+                if (!carried(primary, cause) && cause !== replaced) {
+                    // A failure is never offered, so only a foreign throw can be translated here.
+                    const translated = offer(cause);
+                    if (translated !== undefined) {
+                        deferred.add(translated);
+                    }
+                    faults.push(translated ?? toFailure(cause));
                 }
             }
             // A plugin's own fault is reported after the primary outcome and turns a would-be 0 into 1.
+            // A deferred fault a translator answered turns it into that failure's own code instead.
             // The primary outcome keeps its code, the way a view failure leaves it alone.
             // It is reported the way the primary failure is, so an override answers its class.
             for (const fault of faults) {
                 if (!silenced(fault, controller.signal, cancellation())) {
-                    code = code === 0 ? 1 : code;
+                    const own = deferred.has(fault) ? exitCodeOf(fault) : 1;
+                    code = code === 0 ? own : code;
                     try {
-                        const report = describeFailure(registry ?? noViews, fault, output?.context('stderr'));
-                        if (report.kind === 'rendered') {
-                            await output?.report(report.text);
-                        }
-                        else {
+                        const sink = output && { build, output, registry: registry ?? noViews, stderr };
+                        if (sink && (await reportFailure(sink, fault, scene()))) {
                             code = 1;
-                            await reportPlainly(stderr, `${report.text}Internal error: Rendering the failure failed: ${report.reason}\n`);
                         }
                     }
-                    catch {
+                    catch (reportError) {
                         reportingFailed = true;
+                        reportingCause ??= reportError;
                     }
                 }
             }
             if (output) {
-                const writes = await output.settle();
+                const writes = answeredWrite(await output.settle(), translatedFrom.get(primary));
                 if (writes.kind === 'failed') {
                     code = 1;
                     reportingFailed = true;
+                    reportingCause ??= writes.error;
                 }
                 output.dispose();
             }
             if (reportingFailed) {
-                await reportPlainly(stderr, 'Internal error: Could not write invocation output.\n');
+                const { application, host } = scene();
+                const text = destinationReport(build, reportingCause, { application, host });
+                if (text !== '') {
+                    await reportPlainly(stderr, text);
+                }
             }
             /**
              * One rule orders every code: a cancelled run resolves its signal's code, and a broken
-             * failure view or destination in that run is reported as text without changing it. The
-             * signal decides the code whatever the action did afterward, so this reading comes last.
+             * failure view, onFailure hook, or destination in that run is reported as text without
+             * changing it. The signal decides the code whatever the action did afterward, so this
+             * reading comes last.
              */
             code = cancellation() ?? code;
             process.exitCode = code;
@@ -352,48 +472,140 @@ class ApplicationBuilder {
         }
     }
 }
-/** Reject obsolete wiring before silently losing options that invocations depend on. */
-function checkOptions(options) {
+/** The retired Application options, in the order they are rejected, each with its fix. */
+const retired = [
+    ['globals', 'Declare them with globalOption(name, config).'],
+    ['failures', 'Declare view overrides under views with override(key, view).'],
+];
+/** Where one Application option sits, rebuilt as `new Application(name, { key })`. */
+function optionSite(name, key, value) {
+    return slotSite({ call: 'new Application', named: name, subject: 'The Application' }, key, value);
+}
+/** Where `run()`'s own rendering policy sits: the options object of the call on the Application. */
+function runRendering(rendering) {
+    return {
+        at: '0.rendering',
+        declaration: { arguments: [{ rendering }], call: 'run', path: [] },
+        subject: 'The run',
+    };
+}
+/**
+ * Reject obsolete wiring before silently losing options that invocations depend on. `options` is the
+ * copy `captureOptions` took, or `undefined` for an Application declared without options.
+ */
+function checkOptions(name, options) {
+    const site = {
+        at: '1',
+        declaration: { arguments: callArguments(name, options), call: 'new Application' },
+        subject: 'The Application',
+    };
     if (options === undefined) {
-        return { description: undefined, version: checkVersion(undefined) };
-    }
-    if (!isPlainObject(options)) {
-        throw new DeclarationError('The Application options must be an object. Supply an Application options object.');
-    }
-    if ('globals' in options) {
-        throw new DeclarationError('The Application options contain globals. Declare them with globalOption(name, config).');
+        return { description: undefined, version: checkVersion(site, undefined) };
     }
-    if ('failures' in options) {
-        throw new DeclarationError('The Application options contain failures. Declare view overrides under views with override(key, view).');
+    for (const [key, correction] of retired) {
+        if (key in options) {
+            const retiredSite = optionSite(name, key, Reflect.get(options, key));
+            throw new DeclarationError(retiredApplicationOption, {
+                correction,
+                findings: [partFinding(retiredSite, [])],
+                sentence: `The Application options contain ${key}.`,
+            });
+        }
     }
     // The root is every page's entry point, so it carries neither listing fact.
     // A key that may not be there is a fault of the slot, so it answers with the slot's shape.
-    checkNoListingFacts('The Application', options);
+    checkNoListingFacts(site, options);
     return {
-        description: checkDescription('The Application', options.description),
-        version: checkVersion(options.version),
+        description: checkDescription(site, options.description),
+        version: checkVersion(site, options.version),
     };
 }
+/**
+ * Whether the packet an Application received reads `development`. No packet is distributed, so an
+ * application that never opted in cannot show an operator the author's detail. The build is read
+ * once, here, so a later change to the imported object changes no run.
+ */
+function readPacket(name, packet) {
+    if (packet === undefined) {
+        return false;
+    }
+    const site = optionSite(name, 'packet', packet);
+    if (!isPlainObject(packet)) {
+        throw new DeclarationError(invalidPacket, {
+            correction: 'Import loom.packet.json and pass it as packet.',
+            findings: [partFinding(site, [])],
+            sentence: 'The Application packet must be an object.',
+        });
+    }
+    const { build } = packet;
+    if (build === 'development' || build === 'distributed') {
+        return build === 'development';
+    }
+    const found = build === undefined
+        ? 'The packet has no build.'
+        : `The packet's build is ${typeof build === 'string' ? `"${escapeControlCharacters(build)}"` : 'not a string'}.`;
+    throw new DeclarationError(invalidPacket, {
+        correction: 'Set build to "development" or "distributed".',
+        findings: [partFinding(site, 'build' in packet ? ['build'] : [])],
+        sentence: found,
+    });
+}
+/** The parts of the Application options that are lists, each copied with its entries as built. */
+const optionLists = ['plugins', 'views', 'translators', 'extensions'];
+/**
+ * The one copy of the options that `new Application(name, options)` reads: the options object, its
+ * packet and rendering policy, and each list it holds. An entry of a list is what its factory built
+ * and is not copied. A read that throws is the unreadable fault of the options, and a value that is
+ * not a plain object is the not-an-object fault. An Application declared without options has none
+ * to copy.
+ */
+function captureOptions(name, options) {
+    if (options === undefined) {
+        return undefined;
+    }
+    return captureDeclaration(options, (copy, read) => {
+        read.nested(copy, 'packet', shallowRecord);
+        read.nested(copy, 'rendering', shallowRecord);
+        for (const list of optionLists) {
+            read.nested(copy, list, shallowList);
+        }
+    }, {
+        notAnObject: () => new DeclarationError(notAnObject, {
+            correction: 'Supply an Application options object.',
+            findings: [{ arguments: [name, options], call: 'new Application', mark: '1' }],
+            sentence: 'The Application declares options that are not an object.',
+        }),
+        unreadable: unreadableArgument({ call: 'new Application', named: name, subject: 'The Application' }, 'options'),
+    });
+}
 /**
  * Every rule `new Application(name, options)` applies, in the order it reads the slot: the
- * application's own view overrides, the rendering policy, the options slot and its facts, the
- * installed list and every rule between two plugins, the root's extension values, and then each
- * plugin's Commands, which attach to the root first, in installation order and list order.
+ * application's own view overrides, its translations, the rendering policy, the options slot and
+ * its facts, the installed list and every rule between two plugins, the root's extension values,
+ * and then each plugin's Commands, which attach to the root first, in installation order and list
+ * order. Each reads the one copy of the options `captureOptions` takes.
  */
-function declareApplication(options) {
-    const slot = isPlainObject(options) ? options : undefined;
+function declareApplication(name, declared) {
+    const slot = captureOptions(name, declared);
     const identities = viewIdentities(coreViews);
-    const views = buildViews({ declares: false, sentence: 'The Application' }, slot?.views, identities);
-    const rendering = renderingPolicy(slot?.rendering);
-    const facts = checkOptions(options);
-    const installed = installPlugins(slot?.plugins ?? []);
+    const views = buildViews({
+        declares: false,
+        owner: { call: 'new Application', named: name },
+        sentence: 'The Application',
+    }, slot?.views, identities);
+    const translations = readTranslations(optionSite(name, 'translators', slot?.translators), slot?.translators);
+    const rendering = renderingPolicy(slot?.rendering, optionSite(name, 'rendering', slot?.rendering));
+    const facts = checkOptions(name, slot);
+    const development = readPacket(name, slot?.packet);
+    const installed = installPlugins(name, slot?.plugins ?? []);
     const { plugins } = installed;
-    const contributors = plugins.map((entry) => buildViews({ declares: true, sentence: pluginSentence(entry.identity) }, entry.views, identities));
+    const contributors = plugins.map((entry) => buildViews(pluginViews(entry.identity), entry.views, identities));
     const table = globalTable([], plugins);
     const descriptors = installed.descriptors;
     const extensions = storeCommandLayers({
         descriptors,
         layers: [slot?.extensions],
+        site: optionSite(name, 'extensions', slot?.extensions),
         subject: layerOf(null),
     });
     // The Application checks its own facts, so the root carries none.
@@ -406,14 +618,24 @@ function declareApplication(options) {
     });
     const owners = new Map();
     for (const command of plugins.flatMap((entry) => entry.commands)) {
-        root = attachToRoot(root, command.node, {
+        root = attachToRoot(root, command, {
             descriptors: new Map(root.descriptors),
             owners,
             table,
         });
     }
     return {
-        config: { composed: false, contributors, facts, owners, plugins, rendering, views },
+        config: {
+            composed: false,
+            contributors,
+            development,
+            facts,
+            owners,
+            plugins,
+            rendering,
+            translators: [translations, ...plugins.map((entry) => entry.translators)],
+            views,
+        },
         globals: emptyGlobals(),
         root,
     };
@@ -421,7 +643,11 @@ function declareApplication(options) {
 /** The application name is typed as a command at the prompt, so it answers to the portable rule. */
 function checkApplicationName(name) {
     if (!isPortableName(name)) {
-        throw new DeclarationError(`Application name "${String(name)}" is invalid. ${portableNameCorrection}`);
+        throw new DeclarationError(portableName, {
+            correction: portableNameCorrection,
+            findings: [{ arguments: [name], call: 'new Application', mark: '0' }],
+            sentence: `Application name ${quoted(name)} is invalid.`,
+        });
     }
     return name;
 }
@@ -429,7 +655,8 @@ function checkApplicationName(name) {
 class ApplicationDeclaration extends ApplicationBuilder {
     constructor(name, options) {
         // The arguments evaluate in order, so the name is checked before any option is read.
-        super(checkApplicationName(name), declareApplication(options));
+        const checked = checkApplicationName(name);
+        super(checked, declaring(() => declareApplication(checked, options)));
     }
 }
 export const Application = ApplicationDeclaration;

package/dist/bindings.d.ts

@@ -1,3 +1,4 @@
+import type { FactSite } from './facts.js';
 /** The two keys the binding rules read, whichever scope declared the option. */
 interface BindingConfig {
     readonly env?: unknown;
@@ -6,21 +7,25 @@ interface BindingConfig {
 /**
  * The environment binding one option declares, or `undefined` when it declares none. A multiple
  * option takes its list from the configuration source, so it cannot bind, and a bound name must be
- * a variable name. `sentence` names the declaration at the start of the diagnostic.
+ * a variable name. The site names the declaration and marks its `env`.
  */
-export declare function checkEnvBinding(sentence: string, config: BindingConfig): string | undefined;
+export declare function checkEnvBinding(site: FactSite, config: BindingConfig): string | undefined;
 /** An argument is identified by its place among bare tokens, so no variable can stand in for it. */
-export declare function checkNoArgumentBinding(sentence: string, config: object): void;
-/** One option bound to a variable, with the phrase a duplicate-variable diagnostic names it by. */
+export declare function checkNoArgumentBinding(site: FactSite, config: object): void;
+/**
+ * One option bound to a variable: the phrase a duplicate-variable diagnostic names it by, and the
+ * site whose `env` its finding marks.
+ */
 export interface BoundOption {
-    readonly site: string;
+    readonly phrase: string;
+    readonly site: FactSite;
     readonly variable: string;
 }
 /**
- * The variables one scope binds, each to the phrase of the option that binds it. Within one
- * invocation's scope a variable binds one option, so a second binder is a declaration error that
- * names the first binder, in scope order, and then the second. `held` is what an enclosing scope
- * already binds, such as the globals table under a Command's own options.
+ * The variables one scope binds, each to the option that binds it. Within one invocation's scope a
+ * variable binds one option, so a second binder is a declaration error that names the first
+ * binder, in scope order, and then the second. `held` is what an enclosing scope already binds,
+ * such as the globals table under a Command's own options.
  */
-export declare function claimVariables(bound: readonly BoundOption[], held?: ReadonlyMap<string, string>): ReadonlyMap<string, string>;
+export declare function claimVariables(bound: readonly BoundOption[], held?: ReadonlyMap<string, BoundOption>): ReadonlyMap<string, BoundOption>;
 export {};