@loomcli/core 0.3.0 → 0.5.0

package/dist/plugin.js

@@ -1,9 +1,15 @@
-import { DeclarationError } from './errors.js';
-import { buildExtensions, isDescriptor, registerDescriptor } from './extension.js';
+import { checkEnvBinding, claimVariables } from './bindings.js';
+import { attach, commandNode } from './command.js';
+import { DeclarationError, InternalError, reasonOf } from './errors.js';
+import { appliesTo, buildExtensions, isDescriptor, registerDescriptor } from './extension.js';
 import { checkDeprecated, checkDescription, checkHidden, isPlainObject } from './facts.js';
+import { boundOptions } from './globals.js';
+import { coreViews } from './lanes.js';
+import { booleanValue, compileOptions } from './options.js';
 import { isProcessSignal } from './signals.js';
 import { buildTheme } from './theme.js';
 import { captureConfig, checkDeclarations } from './validation.js';
+import { buildViews, viewIdentities } from './view.js';
 /** Authored values register here, so the public type publishes no state to reach or replace. */
 const nodes = new WeakMap();
 /**
@@ -20,7 +26,8 @@ class PluginDeclaration {
 /**
  * One plugin: an identity and the contributions it carries. Creating and installing the value runs
  * none of its code: a hook runs at graph build, and the middleware runs inside an invocation, so an
- * installed plugin an invocation never reaches costs that invocation its hooks alone.
+ * installed plugin an invocation never reaches costs that invocation its hooks alone. Every rule
+ * that one definition carries on its own throws here, before the value exists.
  */
 function plugin(identity, definition) {
     const captured = {
@@ -29,10 +36,7 @@ function plugin(identity, definition) {
             ? {}
             : { theme: isPlainObject(definition.theme) ? { ...definition.theme } : definition.theme }),
     };
-    return new PluginDeclaration({
-        definition: isPlainObject(definition) ? captured : definition,
-        identity,
-    });
+    return new PluginDeclaration(readPlugin(identity, isPlainObject(definition) ? captured : definition));
 }
 /** How every plugin diagnostic names one plugin at the start of a sentence. */
 function pluginSentence(identity) {
@@ -46,46 +50,70 @@ function nodeOf(value) {
     }
     return node;
 }
-/** The identity one installed value declares, which is a nonempty string installed once. */
-function readIdentity(node, installed) {
-    const { identity } = node;
+/** The identity one plugin declares, which is a nonempty string. */
+function readIdentity(identity) {
     if (typeof identity !== 'string') {
         throw new DeclarationError('A plugin declares an identity that is not a string. Supply a nonempty string, such as the package name.');
     }
     if (identity === '') {
         throw new DeclarationError('A plugin declares an empty identity. Supply a nonempty string, such as the package name.');
     }
-    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;
+function definitionOf(identity, definition) {
     if (!isPlainObject(definition)) {
         throw new DeclarationError(`${pluginSentence(identity)} declares a definition that is not an object. Supply { options, middleware, extensions, views }.`);
     }
     return definition;
 }
 /**
- * The installed list in composition order, with the rules that read the list itself. The slot is
- * read defensively, because a JavaScript author reaches it with any value. Each plugin's own
- * declarations are read by the build steps that consume them, in the order those steps run.
+ * The installed list in composition order, with every rule that reads two plugins together: an
+ * identity installed twice, a second claim on the theme slot, the signals slot, or the
+ * configuration source, and two distinct descriptors under one identity. The slot is read
+ * defensively, because a JavaScript author reaches it with any value. Each plugin's own rules
+ * already ran at its `plugin()` call.
  */
 function installPlugins(plugins) {
     if (!Array.isArray(plugins)) {
         throw new DeclarationError('The Application plugins must be an array. Supply a list of plugin values.');
     }
-    const installed = [];
+    const list = plugins;
+    const installed = list.map((value) => nodeOf(value));
     const identities = new Set();
-    for (const value of plugins) {
-        const node = nodeOf(value);
-        const identity = readIdentity(node, identities);
+    const descriptors = new Map();
+    // Each slot has one owner, so the first plugin to claim it names the second claimant's diagnostic.
+    const owners = {};
+    for (const entry of installed) {
+        const { identity } = entry;
+        if (identities.has(identity)) {
+            throw new DeclarationError(`The Application installs plugin "${identity}" twice. Install each plugin once.`);
+        }
         identities.add(identity);
-        installed.push({ declaration: definitionOf(identity, node), identity });
+        if (entry.theme !== undefined) {
+            if (owners.theme !== undefined) {
+                throw new DeclarationError(`${pluginSentence(identity)} claims the theme slot, which plugin "${owners.theme}" already holds. Install one owner.`);
+            }
+            owners.theme = identity;
+        }
+        for (const descriptor of entry.descriptors.values()) {
+            registerDescriptor(descriptors, descriptor);
+        }
+        // An empty claim leaves the signals slot free.
+        if (entry.signals.length > 0) {
+            if (owners.signals !== undefined) {
+                throw new DeclarationError(`${pluginSentence(identity)} claims the signals slot, which plugin "${owners.signals}" already holds. Install one owner.`);
+            }
+            owners.signals = identity;
+        }
+        if (entry.source) {
+            if (owners.source !== undefined) {
+                throw new DeclarationError(`${pluginSentence(identity)} declares a configuration source, which plugin "${owners.source}" already declares. Install one source.`);
+            }
+            owners.source = identity;
+        }
     }
-    return installed;
+    return { descriptors, plugins: installed };
 }
 /** The keys a plugin option may not declare, in the order its diagnostic names them. */
 const forbidden = ['validate', 'validateOmitted', 'required'];
@@ -96,7 +124,7 @@ function checkPluginOption(sentence, config) {
     }
     const rejected = forbidden.find((key) => key in config);
     if (rejected !== undefined) {
-        throw new DeclarationError(`${sentence} declares ${rejected}. Remove it; a plugin option carries no schema or presence rule, and the middleware interprets the value.`);
+        throw new DeclarationError(`${sentence} declares ${rejected}. Remove it; a plugin option carries no validator or presence rule, and the middleware interprets the value.`);
     }
     checkDescription(sentence, config.description);
     checkHidden(sentence, config.hidden);
@@ -114,10 +142,11 @@ function readOptions(identity, declared, build) {
     for (const [name, config] of Object.entries(declared ?? {})) {
         const sentence = `${pluginSentence(identity)} option "${name}"`;
         checkPluginOption(sentence, config);
+        checkEnvBinding(sentence, config);
         const input = { config: captureConfig(config), kind: 'option', name };
         // The shared rules name the plugin and the option, so a fault reads with its contributor.
         checkDeclarations([input], sentence);
-        build.extensions.set(input, buildExtensions({
+        build.records.set(input, buildExtensions({
             declared: config.extensions,
             descriptors: build.descriptors,
             subject: {
@@ -128,6 +157,9 @@ function readOptions(identity, declared, build) {
         }));
         inputs.push(input);
     }
+    // Two options of one plugin meet in the one table the pre-scan reads, so they share its rules.
+    compileOptions(inputs, `plugin "${identity}"`);
+    claimVariables(boundOptions(inputs, (name) => `plugin "${identity}" option "${name}"`));
     return inputs;
 }
 /** One activation name, which must be one of the plugin's own declared options. */
@@ -158,6 +190,27 @@ function readActivation(identity, declared, names) {
 function isLoader(value) {
     return typeof value === 'function';
 }
+/**
+ * The default export one plugin loader resolves to, checked by the guard its caller supplies. A
+ * loader that throws where it is called and one that rejects later are one failure, and a module
+ * without the export names the kind of function it owed, such as `middleware` or `source`.
+ */
+async function loadDefault(identity, load, owed) {
+    let module = undefined;
+    try {
+        module = await load();
+    }
+    catch (error) {
+        throw new InternalError(`Loading plugin "${identity}" failed: ${reasonOf(error)}`, error);
+    }
+    const exported = module !== null && typeof module === 'object' && 'default' in module
+        ? module.default
+        : undefined;
+    if (!owed.guard(exported)) {
+        throw new InternalError(`Loading plugin "${identity}" failed: the module exports no default ${owed.noun} function.`, undefined);
+    }
+    return exported;
+}
 /** One plugin's middleware, or `undefined` for a plugin that declares none. */
 function readMiddleware(identity, declared, names) {
     if (declared === undefined) {
@@ -173,6 +226,30 @@ function readMiddleware(identity, declared, names) {
     }
     return { activate, load };
 }
+/**
+ * The Commands one plugin attaches to the root, each checked by the attach the root applies, as a
+ * finished Command, against the plugin's own earlier Commands, and against the nesting cap. The
+ * Application attaches them again when it is constructed, against every other root child.
+ */
+function readCommands(identity, declared) {
+    if (declared === undefined) {
+        return [];
+    }
+    if (!Array.isArray(declared)) {
+        throw new DeclarationError(`${pluginSentence(identity)} declares commands that are not an array. Supply a list of Command values.`);
+    }
+    const list = declared;
+    const commands = [];
+    // A for...of walk reads a hole as undefined, which the entry rule rejects, where map would skip it.
+    for (const value of list) {
+        const node = commandNode(value);
+        if (!node) {
+            throw new DeclarationError(`${pluginSentence(identity)} holds a value that is not a Command. Supply the value returned by new Command(name).`);
+        }
+        commands.push(attach({ argument: undefined, children: commands, hasAction: false, name: null }, node));
+    }
+    return commands;
+}
 /**
  * One plugin's claim on the signals slot, drawn from the closed set core installs listeners for.
  * An empty list claims nothing, so it leaves the slot free for another plugin.
@@ -216,6 +293,38 @@ function readHook(identity, declared) {
     }
     return declared;
 }
+/**
+ * The configuration source one plugin declares, or `undefined` for a plugin that declares none.
+ * The binding is one of the plugin's own option-target extensions, so core knows which options to
+ * ask about without knowing what the binding means. The plugin's own options resolve before the
+ * source loads, so none of them may carry its binding.
+ */
+function readSource(identity, declaration, own) {
+    const declared = declaration.source;
+    if (declared === undefined) {
+        return undefined;
+    }
+    const sentence = pluginSentence(identity);
+    if (!isPlainObject(declared)) {
+        throw new DeclarationError(`${sentence} declares a source that is not an object. Supply { binding, load }.`);
+    }
+    const { binding, load } = declared;
+    const listed = (declaration.extensions ?? []).some((descriptor) => descriptor === binding);
+    if (!listed || !isDescriptor(binding)) {
+        throw new DeclarationError(`${sentence} declares a source binding that is not one of its extensions. Supply a descriptor the plugin lists under extensions.`);
+    }
+    if (binding.target !== 'option') {
+        throw new DeclarationError(`${sentence} declares source binding "${binding.identity}", which applies to ${appliesTo(binding.target)}. Supply an extension that applies to options.`);
+    }
+    if (!isLoader(load)) {
+        throw new DeclarationError(`${sentence} declares a source with no load function. Supply load: () => import('./source.js').`);
+    }
+    const carrier = own.inputs.find((input) => Object.hasOwn(own.build.records.get(input) ?? {}, binding.identity));
+    if (carrier) {
+        throw new DeclarationError(`${sentence} option "${carrier.name}" carries its own source binding. Remove the value; the source's own options resolve before it loads.`);
+    }
+    return { binding: binding.identity, load };
+}
 /** A plugin's own list names the extensions it defines, before any declaration carries one. */
 function defineExtensions(identity, declaration, build) {
     const { extensions } = declaration;
@@ -230,49 +339,78 @@ function defineExtensions(identity, declaration, build) {
     }
 }
 /**
- * Every installed plugin's declarations, in installation order. A plugin's own extensions register
- * before any declaration carries a value, so a duplicated package copy is reported from the list
- * that installed it.
+ * Every rule one definition carries on its own, in the order the definition's slots are read. The
+ * plugin's own extensions register before any declaration carries a value, so a duplicated package
+ * copy is reported from the list that defines it. The views list is read against core's view
+ * identities, and the Application reads it again against every other contributor's.
  */
-function buildPlugins(installed, build) {
-    /**
-     * The signals slot has one owner, so the first plugin to claim it names the second claimant's
-     * diagnostic. An empty claim leaves the slot free.
-     */
-    let owner = undefined;
-    let themeOwner = undefined;
-    return installed.map(({ declaration, identity }) => {
-        let theme = undefined;
-        if (declaration.theme !== undefined) {
-            if (themeOwner !== undefined) {
-                throw new DeclarationError(`${pluginSentence(identity)} claims the theme slot, which plugin "${themeOwner}" already holds. Install one owner.`);
-            }
-            theme = buildTheme(declaration.theme, identity);
-            themeOwner = identity;
-        }
-        defineExtensions(identity, declaration, build);
-        const inputs = readOptions(identity, declaration.options, build);
-        const names = new Set(inputs.map((input) => input.name));
-        const signals = readSignals(identity, declaration.signals);
-        if (signals.length > 0) {
-            if (owner !== undefined) {
-                throw new DeclarationError(`${pluginSentence(identity)} claims the signals slot, which plugin "${owner}" already holds. Install one owner.`);
-            }
-            owner = identity;
-        }
-        return {
-            identity,
-            inputs,
-            middleware: readMiddleware(identity, declaration.middleware, names),
-            onCommandAttach: readHook(identity, declaration.onCommandAttach),
-            signals,
-            theme,
-            views: declaration.views,
-        };
-    });
+function readPlugin(identity, definition) {
+    const named = readIdentity(identity);
+    const declaration = definitionOf(named, definition);
+    const theme = declaration.theme === undefined ? undefined : buildTheme(declaration.theme, named);
+    const build = { descriptors: new Map(), records: new Map() };
+    defineExtensions(named, declaration, build);
+    const inputs = readOptions(named, declaration.options, build);
+    const names = new Set(inputs.map((input) => input.name));
+    const signals = readSignals(named, declaration.signals);
+    const source = readSource(named, declaration, { build, inputs });
+    const commands = readCommands(named, declaration.commands);
+    const middleware = readMiddleware(named, declaration.middleware, names);
+    const onCommandAttach = readHook(named, declaration.onCommandAttach);
+    buildViews({ declares: true, sentence: pluginSentence(named) }, declaration.views, viewIdentities(coreViews));
+    return {
+        commands,
+        descriptors: build.descriptors,
+        identity: named,
+        inputs,
+        middleware,
+        onCommandAttach,
+        records: build.records,
+        signals,
+        source,
+        theme,
+        views: declaration.views,
+    };
 }
 /** The signals the one slot owner claimed, or none when no installed plugin claims the slot. */
 function ownedSignals(plugins) {
     return plugins.find((entry) => entry.signals.length > 0)?.signals ?? [];
 }
-export { buildPlugins, installPlugins, ownedSignals, plugin, pluginSentence };
+/** A collected value, or the declared array default, as this run's own copy. */
+function collectedValue(collected, declared) {
+    if (collected) {
+        return [...collected];
+    }
+    return Array.isArray(declared) ? [...declared] : [];
+}
+/** One plugin option's value for one run: what a tier supplied, or the declared default. */
+function pluginValue({ config, name }, values) {
+    const declared = config.default;
+    if (config.type === 'boolean') {
+        return booleanValue(values, name, config);
+    }
+    if (config.multiple === true) {
+        return collectedValue(values.lists.get(name), declared);
+    }
+    // Build already proved that a string option without a validator declares a string default.
+    return values.strings.get(name) ?? (typeof declared === 'string' ? declared : undefined);
+}
+/**
+ * One plugin's own option values for one run: what argv or an input source supplied, or the
+ * declared default, filled without validation. A collected value and an array default are copied,
+ * so a plugin that writes to what it received changes neither the declaration nor the next run.
+ * Entries become own keys even for a name such as `__proto__`, which assignment would not.
+ */
+function pluginValues(inputs, values) {
+    return Object.fromEntries(inputs.map((input) => [input.name, pluginValue(input, values)]));
+}
+/** One plugin's own spellings for one run, frozen, so no plugin writes what another reads. */
+function pluginSpellings(inputs, values) {
+    // Entries become own keys even for a name such as `__proto__`, which assignment would not.
+    const spelled = inputs.flatMap(({ name }) => {
+        const spelling = values.spellings.get(name);
+        return spelling === undefined ? [] : [[name, spelling]];
+    });
+    return Object.freeze(Object.fromEntries(spelled));
+}
+export { installPlugins, loadDefault, ownedSignals, plugin, pluginSentence, pluginSpellings, pluginValues, };

package/dist/sources.d.ts

@@ -0,0 +1,56 @@
+import { InputError, InternalError } from './errors.js';
+import type { ExtensionRecords } from './extension.js';
+import type { CommandGraph, OptionNode } from './inspect.js';
+import type { OptionValues } from './options.js';
+import type { BuiltPlugin } from './plugin.js';
+import type { ContextualStyle } from './style.js';
+import type { Host, Out } from './types.js';
+import type { OptionInput } from './validation.js';
+/**
+ * One scope the stage fills: its options in declaration order, and the values argv supplied them.
+ * The stage writes each fill into `values`, so the caller hands it the run's own copy.
+ */
+interface StageScope {
+    global: boolean;
+    inputs: readonly OptionInput[];
+    values: OptionValues;
+}
+/** Everything one input-source stage reads. */
+interface SourceStage {
+    extensions: ExtensionRecords;
+    /** The globals table: the application's global options, then each plugin's in install order. */
+    globals: StageScope;
+    host: Host;
+    /** The graph `inspect()` would return for the run, built on its first read. */
+    inspected: () => CommandGraph;
+    /** The routed Command's own options, or `undefined` while local parsing holds a fault. */
+    locals: StageScope | undefined;
+    /** The channel a source writes through, whose results call names the source. */
+    out: Out;
+    plugins: readonly BuiltPlugin[];
+    /** The `OptionNode` of one option, read from the graph `inspect()` would return for the run. */
+    request: (input: OptionInput, global: boolean) => OptionNode;
+    signal: AbortSignal;
+    /** The contextual style an action receives, so a source escapes raw data before it warns. */
+    style: ContextualStyle;
+}
+/**
+ * What the stage found beside the values it filled. `labels` names where each filled option's value
+ * came from, by option name, and `rejected` names the variable of each Boolean option whose value
+ * is outside the grammar. Both are internal to core's failure messages. `fault` is a configuration
+ * source's own fault, or the `InputError` its resolver threw, which stops the stage and takes the
+ * place of every validation problem.
+ */
+interface SourceOutcome {
+    fault: InternalError | InputError | undefined;
+    labels: ReadonlyMap<string, string>;
+    rejected: ReadonlyMap<string, string>;
+}
+/**
+ * The input-source stage: the environment, then the configuration source, for every option in
+ * scope that argv left unfilled. When no option is left to ask, the source never loads. A source
+ * fault stops the stage and fills nothing more.
+ */
+declare function fillInputs(stage: SourceStage): Promise<SourceOutcome>;
+export type { SourceOutcome, SourceStage, StageScope };
+export { fillInputs };