@loomcli/core 0.1.1 → 0.2.0

package/dist/plugin.js

@@ -0,0 +1,250 @@
+import { DeclarationError } from './errors.js';
+import { buildExtensions, isDescriptor, registerDescriptor } from './extension.js';
+import { checkDeprecated, checkDescription, checkHidden, isPlainObject } from './facts.js';
+import { isProcessSignal } from './signals.js';
+import { captureConfig, checkDeclarations } from './validation.js';
+/** Authored values register here, so the public type publishes no state to reach or replace. */
+const nodes = new WeakMap();
+/**
+ * The runtime value `plugin()` returns. `Options` appears in a read position alone, which makes it
+ * covariant: a `plugins` list holds plugins with different options the way `failures` holds
+ * renderers for different classes, and `Middleware` and `load` accept a narrower plugin.
+ */
+class PluginDeclaration {
+    constructor(node) {
+        nodes.set(this, node);
+        Object.freeze(this);
+    }
+}
+/**
+ * One plugin: an identity and the declarations it contributes. The value performs no work when it
+ * is created and none when it is installed, so an installed plugin an invocation never reaches
+ * costs that invocation nothing.
+ */
+function plugin(identity, definition) {
+    return new PluginDeclaration({ definition, identity });
+}
+/** How every plugin diagnostic names one plugin at the start of a sentence. */
+function pluginSentence(identity) {
+    return `Plugin "${identity}"`;
+}
+/** Reads the declarations behind an installed value; anything else is a declaration error. */
+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;
+}
+/** 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;
+}
+/** The declarations one plugin value carries, which a JavaScript author reaches as any value. */
+function definitionOf(identity, node) {
+    const { definition } = node;
+    if (!isPlainObject(definition)) {
+        throw new DeclarationError(`${pluginSentence(identity)} declares a definition that is not an object. Supply { options, middleware, extensions, failures }.`);
+    }
+    return definition;
+}
+/**
+ * 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.
+ */
+function installPlugins(plugins) {
+    if (!Array.isArray(plugins)) {
+        throw new DeclarationError('The Application plugins must be an array. Supply a list of plugin values.');
+    }
+    const installed = [];
+    const identities = new Set();
+    for (const value of plugins) {
+        const node = nodeOf(value);
+        const identity = readIdentity(node, identities);
+        identities.add(identity);
+        installed.push({ declaration: definitionOf(identity, node), identity });
+    }
+    return installed;
+}
+/** The keys a plugin option may not declare, in the order its diagnostic names them. */
+const forbidden = ['validate', 'validateOmitted', 'required'];
+/** The rules a plugin option answers before every rule an ordinary declaration carries. */
+function checkPluginOption(sentence, config) {
+    if (!isPlainObject(config)) {
+        throw new DeclarationError(`${sentence} is not an option declaration. Supply { type, ... }.`);
+    }
+    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.`);
+    }
+    checkDescription(sentence, config.description);
+    checkHidden(sentence, config.hidden);
+    checkDeprecated(sentence, config.deprecated);
+}
+/**
+ * One plugin's option declarations, in declaration order. They join the globals table, so the rules
+ * that pair them with another scope's options belong to that table and not to this reading.
+ */
+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.`);
+    }
+    const inputs = [];
+    for (const [name, config] of Object.entries(declared ?? {})) {
+        const sentence = `${pluginSentence(identity)} option "${name}"`;
+        checkPluginOption(sentence, 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({
+            declared: config.extensions,
+            descriptors: build.descriptors,
+            subject: {
+                phrase: `on ${sentence.slice(0, 1).toLowerCase()}${sentence.slice(1)}`,
+                sentence,
+            },
+            target: 'option',
+        }));
+        inputs.push(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') {
+        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.`);
+    }
+    const list = declared;
+    if (list.length === 0) {
+        throw new DeclarationError(`${pluginSentence(identity)} declares middleware with an empty activation list. Name at least one of the plugin's options or use 'always'.`);
+    }
+    return list.map((name) => readActivationName(identity, name, names));
+}
+/**
+ * The loader a middleware declares. Core calls it with no arguments and reads whatever it resolves
+ * to, so being callable is the whole runtime claim this check makes.
+ */
+function isLoader(value) {
+    return typeof value === 'function';
+}
+/** One plugin's middleware, or `undefined` for a plugin that declares none. */
+function readMiddleware(identity, declared, names) {
+    if (declared === undefined) {
+        return undefined;
+    }
+    if (!isPlainObject(declared)) {
+        throw new DeclarationError(`${pluginSentence(identity)} declares middleware that is not an object. Supply { activate, load }.`);
+    }
+    const activate = readActivation(identity, declared.activate, names);
+    const { load } = declared;
+    if (!isLoader(load)) {
+        throw new DeclarationError(`${pluginSentence(identity)} declares middleware with no load function. Supply load: () => import('./middleware.js').`);
+    }
+    return { activate, load };
+}
+/**
+ * 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.
+ * Each signal is claimed once, because core installs one listener per entry and a second listener
+ * on one signal would take the force path on the first signal the run receives.
+ */
+function readSignals(identity, declared) {
+    if (declared === undefined) {
+        return [];
+    }
+    if (!Array.isArray(declared)) {
+        throw new DeclarationError(`${pluginSentence(identity)} declares signals that are not an array. Supply a list of signal names.`);
+    }
+    const list = declared;
+    const claimed = new Set();
+    for (const value of list) {
+        if (!isProcessSignal(value)) {
+            throw new DeclarationError(`${pluginSentence(identity)} claims signal "${String(value)}". Claim SIGINT or SIGTERM.`);
+        }
+        if (claimed.has(value)) {
+            throw new DeclarationError(`${pluginSentence(identity)} claims signal "${value}" twice. Claim each signal once.`);
+        }
+        claimed.add(value);
+    }
+    return [...claimed];
+}
+/** A plugin's own list names the extensions it defines, before any declaration carries one. */
+function defineExtensions(identity, declaration, build) {
+    const { extensions } = declaration;
+    if (extensions !== undefined && !Array.isArray(extensions)) {
+        throw new DeclarationError(`${pluginSentence(identity)} declares extensions that are not an array. Supply a list of extension descriptors.`);
+    }
+    for (const descriptor of extensions ?? []) {
+        if (!isDescriptor(descriptor)) {
+            throw new DeclarationError(`${pluginSentence(identity)} holds a value that is not an extension. Supply the value returned by extension(identity, config).`);
+        }
+        registerDescriptor(build.descriptors, descriptor);
+    }
+}
+/** One plugin's failure registrations, which are a list before any of them is read. */
+function readFailures(identity, declared) {
+    if (declared === undefined) {
+        return [];
+    }
+    if (!Array.isArray(declared)) {
+        throw new DeclarationError(`${pluginSentence(identity)} declares failures that are not an array. Supply a list of renderFailure values.`);
+    }
+    return declared;
+}
+/**
+ * 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.
+ */
+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;
+    return installed.map(({ declaration, 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 {
+            failures: readFailures(identity, declaration.failures),
+            identity,
+            inputs,
+            middleware: readMiddleware(identity, declaration.middleware, names),
+            signals,
+        };
+    });
+}
+/** 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 };

package/dist/signals.d.ts

@@ -0,0 +1,52 @@
+/** The signals a plugin may claim, which is the closed set core installs process listeners for. */
+type ProcessSignal = 'SIGINT' | 'SIGTERM';
+/**
+ * What aborted one run's private controller. Core owns this value, so a middleware reads `source`
+ * and never infers a signal name; `cause` carries the caller's own `signal.reason` when a caller
+ * aborted. The first cause to abort fixes the reason and the code, and a later cause changes
+ * neither.
+ */
+interface CancellationReason {
+    source: ProcessSignal | 'caller';
+    cause?: unknown;
+}
+/** The status each cause resolves. A script that saw 0 after an interrupt would carry on. */
+declare const codes: {
+    readonly SIGINT: 130;
+    readonly SIGTERM: 143;
+    readonly caller: 130;
+};
+/** The status one cancelled run resolves, which is the part of `ExitCode` a signal decides. */
+type CancellationCode = (typeof codes)[CancellationReason['source']];
+/** Whether one declared value names a signal core installs a listener for. */
+declare function isProcessSignal(value: unknown): value is ProcessSignal;
+/** The status one cancelled run resolves, which the first cause to abort fixed. */
+declare function cancellationCode(reason: CancellationReason): CancellationCode;
+/**
+ * Whether one thrown value is the cancellation the run already reports: the reason core aborted
+ * with, which an API that rejects with `signal.reason` throws back, or an error every runtime
+ * names `AbortError`. The chain wraps an unexpected throw, so the wrapped cause reads the same.
+ */
+declare function isCancellationEcho(thrown: unknown, reason: unknown): boolean;
+/**
+ * The process listeners one run holds, and the caller subscription it opened at run entry. Install
+ * and removal sit together so the bracket a run keeps is readable in one place.
+ */
+interface SignalBracket {
+    /** Installs one listener per claimed signal, once the graph has built and validated. */
+    install: (owned: readonly ProcessSignal[]) => void;
+    /** The reason the first cause fixed, or `undefined` while nothing has aborted the run. */
+    reason: () => CancellationReason | undefined;
+    /** Removes every listener this run holds. Called on the run's last exit path. */
+    finish: () => void;
+}
+/**
+ * The bracket for one run. Core subscribes to a caller's signal at run entry, and installs its own
+ * process listeners only for the plugin that owns the signals slot, only after the graph has built,
+ * and only until the run resolves. A process signal that arrives once the run is already cancelled
+ * is the force path: core removes its own listeners and re-raises, so the default disposition ends
+ * the process when no other listener remains. Core does not own the process.
+ */
+declare function bracketRun(controller: AbortController, caller: AbortSignal | undefined): SignalBracket;
+export type { CancellationCode, CancellationReason, ProcessSignal, SignalBracket };
+export { bracketRun, cancellationCode, isCancellationEcho, isProcessSignal };

package/dist/signals.js

@@ -0,0 +1,85 @@
+import { InternalError } from './errors.js';
+/** The status each cause resolves. A script that saw 0 after an interrupt would carry on. */
+const codes = { SIGINT: 130, SIGTERM: 143, caller: 130 };
+/** The closed set a claim is drawn from, as the values a runtime signal name may take. */
+const claimable = new Set(['SIGINT', 'SIGTERM']);
+/** Whether one declared value names a signal core installs a listener for. */
+function isProcessSignal(value) {
+    return typeof value === 'string' && claimable.has(value);
+}
+/** The status one cancelled run resolves, which the first cause to abort fixed. */
+function cancellationCode(reason) {
+    return codes[reason.source];
+}
+/**
+ * Whether one thrown value is the cancellation the run already reports: the reason core aborted
+ * with, which an API that rejects with `signal.reason` throws back, or an error every runtime
+ * names `AbortError`. The chain wraps an unexpected throw, so the wrapped cause reads the same.
+ */
+function isCancellationEcho(thrown, reason) {
+    if (thrown === reason) {
+        return true;
+    }
+    if (thrown instanceof Error && thrown.name === 'AbortError') {
+        return true;
+    }
+    return thrown instanceof InternalError && isCancellationEcho(thrown.cause, reason);
+}
+/**
+ * The bracket for one run. Core subscribes to a caller's signal at run entry, and installs its own
+ * process listeners only for the plugin that owns the signals slot, only after the graph has built,
+ * and only until the run resolves. A process signal that arrives once the run is already cancelled
+ * is the force path: core removes its own listeners and re-raises, so the default disposition ends
+ * the process when no other listener remains. Core does not own the process.
+ */
+function bracketRun(controller, caller) {
+    let reason = undefined;
+    let held = [];
+    const release = () => {
+        for (const entry of held) {
+            process.off(entry.signal, entry.handler);
+        }
+        held = [];
+    };
+    const cancel = (next) => {
+        if (reason) {
+            return;
+        }
+        reason = next;
+        controller.abort(next);
+    };
+    const received = (signal) => {
+        if (reason) {
+            release();
+            process.kill(process.pid, signal);
+            return;
+        }
+        cancel({ source: signal });
+    };
+    const aborted = () => {
+        cancel({ cause: caller?.reason, source: 'caller' });
+    };
+    if (caller?.aborted === true) {
+        aborted();
+    }
+    else {
+        caller?.addEventListener('abort', aborted);
+    }
+    return {
+        finish: () => {
+            release();
+            caller?.removeEventListener('abort', aborted);
+        },
+        install: (owned) => {
+            for (const signal of owned) {
+                const handler = () => {
+                    received(signal);
+                };
+                process.on(signal, handler);
+                held.push({ handler, signal });
+            }
+        },
+        reason: () => reason,
+    };
+}
+export { bracketRun, cancellationCode, isCancellationEcho, isProcessSignal };

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 /// <reference types="node" preserve="true" />
 import type { Readable, Writable } from 'node:stream';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { ExtensionValue } from './extension.js';
 type LowercaseLetter = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z';
 type ShortAlias = LowercaseLetter | Uppercase<LowercaseLetter>;
 type OptionSpelling = {
@@ -32,6 +33,31 @@ type Omission = {
 } | {
     validateOmitted?: false;
 };
+/**
+ * The one-line summary every projection reads. It is a core fact: optional, and a string that holds
+ * a character other than whitespace and no line terminator.
+ */
+interface Described {
+    description?: string;
+}
+/**
+ * The two core facts a listing reads on a named Command and on an option.
+ * `hidden` keeps the member off every listing, and an omitted one reads `false`.
+ * `deprecated` is the one-line migration message a listing shows beside the member.
+ * Neither belongs to an argument, which cannot leave the grammar it sits in, or to the root.
+ */
+interface Listed {
+    hidden?: boolean;
+    deprecated?: string;
+}
+/** The extension values one option declaration carries, whatever scope declares the option. */
+interface OptionExtensions {
+    extensions?: readonly ExtensionValue<'option'>[];
+}
+/** The same slot on an argument declaration, typed by the target its values must name. */
+interface ArgumentExtensions {
+    extensions?: readonly ExtensionValue<'argument'>[];
+}
 /**
  * The tokens one declaration collects before validation: one string, or the whole collection. A
  * multiple option and a variadic argument collect alike, so they share this raw shape.
@@ -54,7 +80,7 @@ export type GlobalNameConstraint<Name extends string, Globals> = Name extends ke
 } : unknown;
 /** A required record key excludes open strings; distribution rejects each union member. */
 export type NameConstraint<Name extends string, Whole extends string = Name> = {} extends Record<Name, unknown> ? LiteralNameFault : Name extends Whole ? [Whole] extends [Name] ? unknown : LiteralNameFault : LiteralNameFault;
-export type ExitCode = 0 | 1 | 2;
+export type ExitCode = 0 | 1 | 2 | 130 | 143;
 export interface InputTerminal {
     isTTY: boolean;
 }
@@ -77,6 +103,11 @@ export interface Host {
 }
 export interface RunOptions {
     host?: Partial<Host>;
+    /**
+     * A caller-owned signal that cancels the run. Core subscribes to it at run entry and honors an
+     * abort at every phase boundary; it composes with an installed signals owner.
+     */
+    signal?: AbortSignal;
 }
 /** The declaration one schema call validates, under the name and the scope it was declared in. */
 export interface InputIdentity {
@@ -130,17 +161,17 @@ export interface Out {
     render<Data>(data: Data, renderer: Renderer<Data>): Promise<void>;
     fatal(message: string): never;
 }
-export type StringOption = OptionSpelling & Presence & Multiplicity & Omission & {
+export type StringOption = OptionSpelling & Presence & Multiplicity & Omission & Described & Listed & OptionExtensions & {
     type: 'string';
     polarity?: never;
     validate?: StandardSchemaV1;
 };
 /** A variadic argument collects the remaining tokens, so it follows the multiple option rules. */
-export type VariadicArgument = Presence & {
+export type VariadicArgument = Presence & Described & ArgumentExtensions & {
     variadic: true;
     validate?: StandardSchemaV1;
 };
-export type ScalarArgument = Presence & Omission & {
+export type ScalarArgument = Presence & Omission & Described & ArgumentExtensions & {
     variadic?: false;
     validate?: StandardSchemaV1;
 };
@@ -198,7 +229,7 @@ export type ArgumentValue<Config extends ArgumentConfig> = Config extends {
 } | {
     validateOmitted: true;
 } ? never : undefined);
-export type BooleanOption = (OptionSpelling & {
+export type BooleanOption = (OptionSpelling & Described & Listed & OptionExtensions & {
     type: 'boolean';
     validate?: never;
     default?: never;
@@ -206,7 +237,7 @@ export type BooleanOption = (OptionSpelling & {
     required?: never;
     validateOmitted?: never;
     polarity?: 'positive' | 'negative';
-}) | {
+}) | (Described & Listed & OptionExtensions & {
     type: 'boolean';
     validate?: never;
     default?: never;
@@ -216,8 +247,23 @@ export type BooleanOption = (OptionSpelling & {
     polarity: 'both';
     short?: ShortAlias;
     shortOnly?: false;
-};
+});
 export type OptionConfig = StringOption | BooleanOption;
+/**
+ * The parsing part of a string option config, which is all a plugin option declares. A plugin
+ * option carries no schema and no presence rule, because it is read before local parsing, where the
+ * validation context every schema is promised cannot exist. Its middleware interprets the value.
+ * A Boolean plugin option is an ordinary `BooleanOption`, which already declares none of them.
+ */
+export type PluginStringOption = OptionSpelling & Multiplicity & Described & Listed & OptionExtensions & {
+    type: 'string';
+    default?: string | string[];
+    polarity?: never;
+    required?: never;
+    validate?: never;
+    validateOmitted?: never;
+};
+export type PluginOptionConfig = PluginStringOption | BooleanOption;
 export type OptionValue<Config extends OptionConfig> = Config extends StringOption ? Config extends {
     multiple: true;
 } ? ValidatedValue<Config, string[]> : ValidatedValue<Config, string> | (Config extends {
@@ -233,6 +279,8 @@ export interface ActionContext<Args, Options = {}> {
     passthrough: string[];
     out: Out;
     host: Host;
+    /** The run's cancellation signal, which a caller or an installed signals owner aborts. */
+    signal: AbortSignal;
 }
 export type Action<Args, Options = {}> = (context: ActionContext<Args, Options>) => unknown;
 /** Phantom key. It keeps the inferred declaration types exact and holds no runtime value. */

package/dist/validation.d.ts

@@ -72,9 +72,11 @@ export declare function issuePath(issue: StandardSchemaV1.Issue): string | undef
 /**
  * Every declaration rule that reads the declaration alone. It is synchronous, so `inspect()` and
  * `run()` apply exactly the same rules, and only validating a default through its schema, which
- * can be asynchronous, is left to `run()`.
+ * can be asynchronous, is left to `run()`. A contributor that declares under its own name, such as
+ * a plugin, supplies the subject its diagnostics read with; every other caller is named by the
+ * declaration itself.
  */
-export declare function checkDeclarations(inputs: readonly InputDeclaration[]): void;
+export declare function checkDeclarations(inputs: readonly InputDeclaration[], named?: string): void;
 /**
  * Every declared default, validated before any token is read. The host is captured by then, so a
  * default's schema reads the same Host its action will, under the `default` phase.

package/dist/validation.js

@@ -1,5 +1,6 @@
 import { schemaOptions } from './context.js';
 import { DeclarationError, InputError } from './errors.js';
+import { booleanValue } from './options.js';
 /** Every declaration in validation order: the globals first, then the reading Command's own. */
 function scoped(inputs) {
     return [
@@ -117,9 +118,8 @@ function holdsRawDefault(input) {
  * `validateOmitted: true` is the one way an omitted scalar reaches its schema, so every other rule
  * that already decides absence rejects it, and the flag needs a schema to receive the omission.
  */
-function checkOmissionValidation(input) {
+function checkOmissionValidation(input, subject) {
     const { config } = input;
-    const subject = declaredName(input);
     if (config.required) {
         throw new DeclarationError(`${subject} is required and declares validateOmitted. Remove validateOmitted or make the input optional.`);
     }
@@ -133,34 +133,34 @@ function checkOmissionValidation(input) {
         throw new DeclarationError(`${subject} declares validateOmitted without a schema. Add validate or remove validateOmitted.`);
     }
 }
-function checkDeclaration(input) {
+function checkDeclaration(input, subject) {
     const { config } = input;
     if (input.kind === 'option' && input.config.type === 'boolean') {
         if ('validate' in config ||
             'default' in config ||
             'required' in config ||
             'validateOmitted' in config) {
-            throw new DeclarationError(`${declaredName(input)} is Boolean. Remove validate, default, required, and validateOmitted; use polarity to control its absent value.`);
+            throw new DeclarationError(`${subject} is Boolean. Remove validate, default, required, and validateOmitted; use polarity to control its absent value.`);
         }
         return;
     }
     if (config.required !== undefined && typeof config.required !== 'boolean') {
-        throw new DeclarationError(`${declaredName(input)} required must be Boolean. Use true or false.`);
+        throw new DeclarationError(`${subject} required must be Boolean. Use true or false.`);
     }
     if (input.kind === 'argument' &&
         input.config.variadic !== undefined &&
         typeof input.config.variadic !== 'boolean') {
-        throw new DeclarationError(`${declaredName(input)} variadic must be Boolean. Use true or false.`);
+        throw new DeclarationError(`${subject} variadic must be Boolean. Use true or false.`);
     }
     // The test reads presence, not truth, so a declared `undefined` is a declaration to reject.
     if ('validateOmitted' in config && typeof config.validateOmitted !== 'boolean') {
-        throw new DeclarationError(`${declaredName(input)} validateOmitted must be Boolean. Use true or false.`);
+        throw new DeclarationError(`${subject} validateOmitted must be Boolean. Use true or false.`);
     }
     if (config.required && Object.hasOwn(config, 'default')) {
-        throw new DeclarationError(`${declaredName(input)} is required and declares a default. Remove the default or make the input optional.`);
+        throw new DeclarationError(`${subject} is required and declares a default. Remove the default or make the input optional.`);
     }
     if (validatesOmission(input)) {
-        checkOmissionValidation(input);
+        checkOmissionValidation(input, subject);
     }
     const schema = config.validate;
     if (schema !== undefined &&
@@ -170,7 +170,7 @@ function checkDeclaration(input) {
             schema['~standard'].version !== 1 ||
             typeof schema['~standard'].vendor !== 'string' ||
             typeof schema['~standard'].validate !== 'function')) {
-        throw new DeclarationError(`${declaredName(input)} validate must be a Standard Schema v1 object. Supply a compatible schema.`);
+        throw new DeclarationError(`${subject} validate must be a Standard Schema v1 object. Supply a compatible schema.`);
     }
 }
 function readIssue(issue) {
@@ -259,15 +259,17 @@ function hasDefault(input) {
 /**
  * Every declaration rule that reads the declaration alone. It is synchronous, so `inspect()` and
  * `run()` apply exactly the same rules, and only validating a default through its schema, which
- * can be asynchronous, is left to `run()`.
+ * can be asynchronous, is left to `run()`. A contributor that declares under its own name, such as
+ * a plugin, supplies the subject its diagnostics read with; every other caller is named by the
+ * declaration itself.
  */
-export function checkDeclarations(inputs) {
+export function checkDeclarations(inputs, named) {
     for (const input of inputs) {
-        checkDeclaration(input);
+        checkDeclaration(input, named ?? declaredName(input));
     }
     for (const input of inputs.filter((entry) => hasDefault(entry))) {
         if (input.config.validate === undefined && !holdsRawDefault(input)) {
-            const subject = declaredName(input);
+            const subject = named ?? declaredName(input);
             throw new DeclarationError(collects(input)
                 ? `${subject} default must be an array of strings without a schema. Supply a string array default.`
                 : `${subject} default must be a string without a schema. Supply a string default.`);
@@ -366,7 +368,7 @@ export async function validateValues(invocation) {
     for (const entry of declarations) {
         const { input } = entry;
         if (input.kind === 'option' && input.config.type === 'boolean') {
-            values.set(input, supplied.options.booleans.get(input.name) ?? input.config.polarity === 'negative');
+            values.set(input, booleanValue(supplied.options, input.name, input.config));
         }
         else {
             const collected = collects(input);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loomcli/core",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "The Loom CLI core package. Provides the scaffolding for creating new Loom CLI applications.",
   "license": "MIT",
   "repository": {