@loomcli/core 0.4.0 → 0.5.0

package/dist/sources.js

@@ -0,0 +1,249 @@
+import { asSentence, InputError, InternalError, reasonOf, ResultError } from './errors.js';
+import { isPlainObject, isProseLine } from './facts.js';
+import { isSupplied } from './options.js';
+import { loadDefault, pluginSentence, pluginValues } from './plugin.js';
+/** The Boolean grammar a bound variable is read through: the whole value, case-insensitive. */
+const truths = new Map([
+    ['0', false],
+    ['1', true],
+    ['false', false],
+    ['true', true],
+]);
+/**
+ * Reads one option's bound variable. An empty variable is unset and falls through, a string option
+ * receives the raw string, and a Boolean option reads the whole value through the grammar, so the
+ * value states the option's value and not a spelling.
+ */
+function readVariable(input, env) {
+    const variable = input.config.env;
+    const raw = variable !== undefined && Object.hasOwn(env, variable) ? env[variable] : undefined;
+    if (raw === undefined || raw === '') {
+        return undefined;
+    }
+    if (input.config.type === 'string') {
+        return { kind: 'fill', value: raw };
+    }
+    const value = truths.get(raw.toLowerCase());
+    return value === undefined ? { kind: 'rejected' } : { kind: 'fill', value };
+}
+/** Writes one filled value where the option's own shape keeps it, a list as the run's own copy. */
+function fill(values, name, value) {
+    if (typeof value === 'boolean') {
+        values.booleans.set(name, value);
+    }
+    else if (typeof value === 'string') {
+        values.strings.set(name, value);
+    }
+    else {
+        values.lists.set(name, [...value]);
+    }
+}
+/** How a fault names the value an answer owed, by the shape the option takes. */
+const owed = {
+    boolean: 'a Boolean',
+    list: 'an array of strings',
+    string: 'a string',
+};
+function rawKind(input) {
+    if (input.config.type === 'boolean') {
+        return 'boolean';
+    }
+    return input.config.multiple === true ? 'list' : 'string';
+}
+/**
+ * The run's own copy of an answered list, or `undefined` when it is not a list of strings. Every
+ * index is read, so a hole fails the check as any entry that is not a string does.
+ */
+function stringList(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const list = [];
+    // Iteration visits a hole as undefined, where every() skips it.
+    for (const entry of value) {
+        if (typeof entry !== 'string') {
+            return undefined;
+        }
+        list.push(entry);
+    }
+    return list;
+}
+/** One answered value as the raw type its option takes, or `undefined` when it holds another. */
+function rawValue(kind, value) {
+    if (kind === 'list') {
+        return stringList(value);
+    }
+    if (kind === 'boolean') {
+        return typeof value === 'boolean' ? value : undefined;
+    }
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * The faults the answers rule names. Reading the answers runs the plugin's own code, such as a
+ * getter, so a throw of any other kind while reading them is the plugin's failure.
+ */
+const ruleFaults = new WeakSet();
+/** A fault the answers rule names, recorded so that reading the answers rethrows it unframed. */
+function ruleFault(message) {
+    const fault = new InternalError(message, undefined);
+    ruleFaults.add(fault);
+    return fault;
+}
+/** One answer read under the answers rule: an object that holds a one-line label and a value. */
+function readAnswer(sentence, input, answer) {
+    const shape = isPlainObject(answer) ? answer : undefined;
+    const label = shape?.label;
+    if (!shape || !isProseLine(label)) {
+        throw ruleFault(`${sentence} answered option "${input.name}" with an answer that is not { value, label }.`);
+    }
+    const kind = rawKind(input);
+    const value = rawValue(kind, shape.value);
+    if (value === undefined) {
+        throw ruleFault(`${sentence} answered option "${input.name}" with a value that is not ${owed[kind]}.`);
+    }
+    return { label, value };
+}
+/**
+ * Every answer the resolver returned, read before any is filled, so an answer the rule rejects
+ * leaves every requested option unfilled. A key core did not request is the source's fault.
+ */
+function readAnswers(sentence, answers, requested) {
+    if (!isPlainObject(answers)) {
+        throw ruleFault(`${sentence} returned configuration answers that are not a record.`);
+    }
+    const byName = new Map(requested.map((target) => [target.input.name, target]));
+    return Object.entries(answers).map(([name, answer]) => {
+        const target = byName.get(name);
+        if (!target) {
+            throw ruleFault(`${sentence} answered option "${name}", which core did not request.`);
+        }
+        const { label, value } = readAnswer(sentence, target.input, answer);
+        return { label, target, value };
+    });
+}
+/**
+ * The default export a source loader must resolve to. A loaded module is data core never declared,
+ * so the check is the one runtime fact that decides it: the export is callable.
+ */
+function isResolverExport(value) {
+    return typeof value === 'function';
+}
+/** The fault of a source that threw, while it ran or while core read what it returned. */
+function sourceFailure(sentence, error) {
+    return new InternalError(`${sentence} failed in its configuration source: ${asSentence(reasonOf(error))}`, error);
+}
+/**
+ * Asks the one configuration source about every requested option, and answers with what it said.
+ * Core loads the source here and calls it once, awaiting it; one cancelled during the call awaits
+ * it. The run checks its signal and then reaches the load with no await between, so a run
+ * cancelled before the load starts neither step, and one cancelled during the load calls nothing.
+ * Core builds the context before the call, so a fault of its own is never the plugin's.
+ */
+async function askSource(stage, call) {
+    const { owner, requested } = call;
+    const resolver = await loadDefault(owner.identity, owner.source.load, {
+        guard: isResolverExport,
+        noun: 'source',
+    });
+    if (stage.signal.aborted) {
+        return [];
+    }
+    const sentence = pluginSentence(owner.identity);
+    const context = {
+        graph: stage.inspected(),
+        host: stage.host,
+        options: pluginValues(owner.inputs, stage.globals.values),
+        out: stage.out,
+        requests: requested.map(({ input, scope }) => stage.request(input, scope.global)),
+        style: stage.style,
+    };
+    let answers = undefined;
+    try {
+        answers = await resolver(context);
+    }
+    catch (error) {
+        // The resolver's own InputError is a usage failure.
+        // Its out.results() call is the results fault that names it.
+        // Every other throw is the plugin's fault.
+        if (error instanceof InputError || (error instanceof ResultError && error.kind === 'source')) {
+            throw error;
+        }
+        throw sourceFailure(sentence, error);
+    }
+    try {
+        return readAnswers(sentence, answers, requested);
+    }
+    catch (error) {
+        if (error instanceof InternalError && ruleFaults.has(error)) {
+            throw error;
+        }
+        throw sourceFailure(sentence, error);
+    }
+}
+/**
+ * The environment tier: each option in scope that argv left unfilled reads its bound variable. A
+ * filled option is labeled with its variable, and a Boolean one outside the grammar is recorded
+ * as rejected, which fills nothing.
+ */
+function fillFromEnvironment(scopes, env) {
+    const labels = new Map();
+    const rejected = new Map();
+    for (const scope of scopes) {
+        for (const input of scope.inputs) {
+            const reading = isSupplied(scope.values, input.name) ? undefined : readVariable(input, env);
+            const variable = input.config.env ?? '';
+            if (reading?.kind === 'fill') {
+                fill(scope.values, input.name, reading.value);
+                labels.set(input.name, variable);
+            }
+            else if (reading?.kind === 'rejected') {
+                rejected.set(input.name, variable);
+            }
+        }
+    }
+    return { labels, rejected };
+}
+/**
+ * The options the configuration source is asked about: those still unfilled that carry its
+ * binding and hold no environment fault, the globals table first and then the routed Command's own,
+ * each in declaration order.
+ */
+function requestedOf(scopes, excluded, bound) {
+    return scopes.flatMap((scope) => scope.inputs
+        .filter((input) => !isSupplied(scope.values, input.name) &&
+        !excluded.has(input.name) &&
+        Object.hasOwn(bound.extensions.get(input) ?? {}, bound.binding))
+        .map((input) => ({ input, scope })));
+}
+/**
+ * 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.
+ */
+async function fillInputs(stage) {
+    const scopes = stage.locals ? [stage.globals, stage.locals] : [stage.globals];
+    const { labels, rejected } = fillFromEnvironment(scopes, stage.host.env);
+    const owner = stage.plugins.find((installed) => installed.source !== undefined);
+    const requested = owner
+        ? requestedOf(scopes, rejected, { binding: owner.source.binding, extensions: stage.extensions })
+        : [];
+    if (!owner || requested.length === 0) {
+        return { fault: undefined, labels, rejected };
+    }
+    try {
+        for (const { label, target, value } of await askSource(stage, { owner, requested })) {
+            fill(target.scope.values, target.input.name, value);
+            labels.set(target.input.name, label);
+        }
+        return { fault: undefined, labels, rejected };
+    }
+    catch (error) {
+        // The resolver's InputError reports as a usage failure.
+        // Every other fault above is raised as an internal error, and anything else is wrapped the same way.
+        const fault = error instanceof InternalError || error instanceof InputError
+            ? error
+            : new InternalError(reasonOf(error), error);
+        return { fault, labels, rejected };
+    }
+}
+export { fillInputs };

package/dist/types.d.ts

@@ -2,7 +2,7 @@
 import type { Readable, Writable } from 'node:stream';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { ExtensionValue } from './extension.js';
-import type { ResultNode } from './inspect.js';
+import type { CommandGraph, CommandNode, ResultNode } from './inspect.js';
 import type { RenderingPolicy } from './rendering.js';
 import type { ContextualStyle } from './style.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';
@@ -21,12 +21,23 @@ type Presence = {
     required?: false;
     default?: unknown;
 };
-/** The literal member keeps `multiple: true` exact under contextual typing, as `Presence` does. */
+/**
+ * The literal member keeps `multiple: true` exact under contextual typing, as `Presence` does.
+ * A multiple option takes its list from the configuration source, so it binds no variable.
+ */
 type Multiplicity = {
     multiple: true;
-} | {
+    env?: never;
+} | ({
     multiple?: false;
-};
+} & EnvBinding);
+/**
+ * The environment binding: the variable the input-source stage fills the option from when argv
+ * supplies none. The declaration names it explicitly, and core derives no name.
+ */
+interface EnvBinding {
+    env?: string;
+}
 /**
  * `validateOmitted: true` sends an omitted optional scalar to its own schema. The literal member
  * keeps the flag exact under contextual typing, as `Multiplicity` does.
@@ -62,15 +73,22 @@ 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.
+ * The tokens one declaration collects before validation: one string, or several. A multiple option
+ * and a variadic argument collect alike, so they share this raw shape.
  */
 type RawValue<Config> = Config extends {
     multiple: true;
 } | {
     variadic: true;
 } ? string[] : string;
-type SchemaOutput<Schema, Raw> = Schema extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<Schema> : Raw;
+/** A multiple option and a variadic argument pass each value through the same validator. */
+type PerValue<Config, Value> = Config extends {
+    multiple: true;
+} | {
+    variadic: true;
+} ? Value[] : Value;
+/** The validated value: the validator's output for each value, or the raw shape without one. */
+type SchemaOutput<Config, Schema, Raw> = Schema extends StandardSchemaV1 ? PerValue<Config, StandardSchemaV1.InferOutput<Schema>> : Raw;
 type SchemaInput<Schema> = Schema extends StandardSchemaV1 ? StandardSchemaV1.InferInput<Schema> : string;
 /** The named key states the rule, so a rejected declaration name reads as its own diagnostic. */
 interface LiteralNameFault {
@@ -324,19 +342,24 @@ export type ScalarArgument = Presence & Omission & Described & ArgumentExtension
     validate?: StandardSchemaV1;
 };
 export type ArgumentConfig = VariadicArgument | ScalarArgument;
-export type ValidatedValue<Config, Raw> = Config extends unknown ? 'validate' extends keyof Config ? SchemaOutput<Config['validate'], Raw> : Raw : never;
-/** Keep each conditional declaration paired with its own schema input type. */
+export type ValidatedValue<Config, Raw> = Config extends unknown ? 'validate' extends keyof Config ? SchemaOutput<Config, Config['validate'], Raw> : Raw : never;
+/** Keep each conditional declaration paired with its own validator input type. */
 export type DefaultConstraint<Config> = Config extends unknown ? Config & {
-    default?: 'validate' extends keyof Config ? SchemaInput<Config['validate']> : RawValue<Config>;
+    default?: 'validate' extends keyof Config ? PerValue<Config, SchemaInput<Config['validate']>> : RawValue<Config>;
 } : never;
 /**
- * A multiple option hands its whole collection to one schema, so the declared schema must accept a
- * `string[]` input. The key names the fault, the way the other declaration constraints do.
+ * A multiple option or a variadic argument passes each value to its validator alone, so the
+ * declared validator must accept one `string`. The key names the fault, the way the other
+ * declaration constraints do.
  */
-export type MultipleConstraint<Config> = Config extends {
+export type PerValueConstraint<Config> = Config extends {
     multiple: true;
-} ? 'validate' extends keyof Config ? string[] extends SchemaInput<Config['validate']> ? unknown : {
-    'A multiple option schema must accept a string[] input': Config['validate'];
+} | {
+    variadic: true;
+} ? 'validate' extends keyof Config ? [
+    SchemaInput<Config['validate']>
+] extends [never] ? unknown : string extends SchemaInput<Config['validate']> ? unknown : {
+    'A validator of several values must accept one string input': Config['validate'];
 } : unknown : unknown;
 /**
  * The declaration rules `validateOmitted: true` needs: a schema that accepts `undefined`, an
@@ -362,12 +385,28 @@ export type ValidateOmittedConstraint<Config> = Config extends {
 } | {
     variadic: true;
 } ? {
-    'A collected input validates its omission as an empty array': never;
+    'An input of several values receives no values as an empty array': never;
 } : 'validate' extends keyof Config ? undefined extends SchemaInput<Config['validate']> ? unknown : {
-    'A validateOmitted schema must accept an undefined input': Config['validate'];
+    'A validateOmitted validator must accept an undefined input': Config['validate'];
 } : {
-    'validateOmitted needs a validate schema to receive the omission': never;
+    'validateOmitted needs a validator to receive the omission': never;
 } : unknown;
+/**
+ * A global option declares no presence rule, so its omission is always plain absence. A union
+ * config fails when any member declares the key, and a wide `OptionConfig` passes, because its
+ * members only allow the key.
+ */
+export type GlobalOmissionConstraint<Config> = [Extract<Config, {
+    required: unknown;
+}>] extends [
+    never
+] ? [Extract<Config, {
+    validateOmitted: unknown;
+}>] extends [never] ? unknown : {
+    'A global option declares no validateOmitted; its omission is plain absence': never;
+} : {
+    'A global option declares no required; the Commands that read it check for it': never;
+};
 export type ArgumentValue<Config extends ArgumentConfig> = Config extends {
     variadic: true;
 } ? ValidatedValue<Config, string[]> : ValidatedValue<Config, string> | (Config extends {
@@ -377,7 +416,7 @@ export type ArgumentValue<Config extends ArgumentConfig> = Config extends {
 } | {
     validateOmitted: true;
 } ? never : undefined);
-export type BooleanOption = (OptionSpelling & Described & Listed & OptionExtensions & {
+export type BooleanOption = (OptionSpelling & Described & Listed & EnvBinding & OptionExtensions & {
     type: 'boolean';
     validate?: never;
     default?: never;
@@ -385,7 +424,7 @@ export type BooleanOption = (OptionSpelling & Described & Listed & OptionExtensi
     required?: never;
     validateOmitted?: never;
     polarity?: 'positive' | 'negative';
-}) | (Described & Listed & OptionExtensions & {
+}) | (Described & Listed & EnvBinding & OptionExtensions & {
     type: 'boolean';
     validate?: never;
     default?: never;
@@ -422,10 +461,16 @@ export type OptionValue<Config extends OptionConfig> = Config extends StringOpti
 } | {
     validateOmitted: true;
 } ? never : undefined) : boolean;
+/**
+ * What an action receives. `graph` is the frozen graph `inspect()` returns for this run, and
+ * `command` is the routed node inside it: the same two values the run's middleware receive.
+ */
 export interface ActionContext<Args, Options = {}, Result = unknown> {
     readonly style: ContextualStyle;
     args: Args;
     options: Options;
+    readonly graph: CommandGraph;
+    readonly command: CommandNode;
     passthrough: string[];
     out: Out<Result>;
     host: Host;

package/dist/validation.d.ts

@@ -24,6 +24,14 @@ export interface ScopedInputs {
     globals: readonly InputDeclaration[];
     locals: readonly InputDeclaration[];
 }
+/**
+ * What the input-source stage leaves for validation's messages, by option name: the label of each
+ * value it filled, and the variable of each Boolean option whose value is outside the grammar.
+ */
+interface Provenance {
+    labels: ReadonlyMap<string, string>;
+    rejected: ReadonlyMap<string, string>;
+}
 /** The raw tokens one invocation collected, keyed by declaration and by option name. */
 interface SuppliedValues {
     args: ReadonlyMap<InputDeclaration, string | string[]>;
@@ -36,8 +44,14 @@ export interface Invocation {
     host: Host;
     inputs: ScopedInputs;
     passthrough: readonly string[];
-    /** The run's cancellation signal, which stops this phase between two schema calls. */
+    /**
+     * The plugin options, which are never validated. A Boolean one whose variable is outside the
+     * grammar is still a problem of this phase, reported after the globals and before the locals.
+     */
+    plugins: readonly OptionInput[];
+    /** The run's cancellation signal, which stops this phase between two validator calls. */
     signal: AbortSignal;
+    sources: Provenance;
     supplied: SuppliedValues;
 }
 /**
@@ -66,7 +80,7 @@ export type { ValidatedInputs };
  */
 export declare function captureConfig<Config extends ArgumentConfig | OptionConfig>(config: Config): Config;
 /**
- * The declaration flag that sends an omitted value to its own schema. Every declaration reads it
+ * The declaration flag that sends an omitted value to its own validator. Every declaration reads it
  * here, and the declaration rules below reject it wherever another rule already decides absence.
  */
 export declare function validatesOmission(input: InputDeclaration): boolean;
@@ -77,16 +91,16 @@ export declare function validatesOmission(input: InputDeclaration): boolean;
  */
 export declare function issuePath(issue: StandardSchemaV1.Issue): string | undefined;
 /**
- * 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()`. 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.
+ * Every declaration rule that reads the declaration alone. It is synchronous, so the call that
+ * declares an input applies it, and build applies it to an input a lifecycle hook declared; only
+ * validating a default through its validator, which 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[], 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.
+ * default's validator reads the same Host its action will, under the `default` phase.
  */
 export declare function prepareInputs(inputs: ScopedInputs, host: Host): Promise<DefaultValues>;
 export declare function validateValues(invocation: Invocation): Promise<ValidatedInputs>;