@loomcli/core 0.1.1 → 0.3.0

package/dist/chain.d.ts

@@ -0,0 +1,68 @@
+import type { BuiltGraph } from './command.js';
+import type { LoomError } from './errors.js';
+import type { CommandGraph, CommandNode } from './inspect.js';
+import type { BuiltPlugin, PluginOptions, PluginOptionValues } from './plugin.js';
+import type { ContextualStyle } from './style.js';
+import type { ActionChannel, Host, OpenResult, Out, Request, ResultBinding } from './types.js';
+import type { DefaultValues } from './validation.js';
+/**
+ * What the rest of one chain did: the action ran, a later middleware took over by returning without
+ * calling its own `next()`, or the run was cancelled before the action ran.
+ */
+type ChainOutcome = 'cancelled' | 'dispatched' | 'taken-over';
+/**
+ * What one middleware receives. `graph` is the frozen graph `inspect()` returns, built once for the
+ * run, and `command` is the routed node inside it. `options` holds this plugin's own option values
+ * and never another plugin's or the application's globals. `request` is the routed Command's
+ * invocation, parsed and validated ahead of the chain, and `null` while core holds a fault and on a
+ * group. `view` names the view the result renders through: it reads as the declaration's default
+ * until a middleware assigns one, and as `null` on a Command that declares none. The last
+ * assignment before the dispatch boundary wins, and one made after it changes nothing.
+ */
+interface MiddlewareContext<Options extends PluginOptions = PluginOptions> {
+    readonly options: PluginOptionValues<Options>;
+    readonly graph: CommandGraph;
+    readonly command: CommandNode;
+    readonly request: Request | null;
+    get view(): string | null;
+    set view(name: string);
+    readonly host: Host;
+    readonly out: Out;
+    readonly signal: AbortSignal;
+    readonly next: () => Promise<ChainOutcome>;
+}
+/** Everything one invocation needs after its graph is built and its defaults are validated. */
+interface Invocation {
+    style: ContextualStyle;
+    /** The action's own channel, built from the routed Command's declaration when it dispatches. */
+    channel: (binding: ResultBinding) => ActionChannel;
+    defaults: DefaultValues;
+    facts: {
+        description: string | undefined;
+        version: string;
+    };
+    graph: BuiltGraph;
+    host: Host;
+    name: string;
+    /**
+     * The invocation's own channel. A middleware reads it as the neutral `Out`, and the action
+     * receives the channel the results lane builds for the Command that was routed.
+     */
+    out: Out<OpenResult>;
+    plugins: readonly BuiltPlugin[];
+    /** A fault reported after the primary outcome, which turns a would-be 0 into 1. */
+    report: (fault: LoomError) => void;
+    /** The routed path, published where routing resolved it, which output names in its own line. */
+    route: (path: readonly string[]) => void;
+    signal: AbortSignal;
+}
+/**
+ * Runs one invocation: the global pre-scan, routing, the dispatch this invocation prepares, and the
+ * middleware chain it then runs. Local parsing and validation run ahead of the chain so that a
+ * middleware reads the request, and the fault they find is held until the dispatch boundary. A
+ * middleware that returns without calling `next()` has taken over, so the held fault is never
+ * raised and nothing later in the chain runs.
+ */
+declare function runInvocation(invocation: Invocation): Promise<void>;
+export type { ChainOutcome, Invocation, MiddlewareContext };
+export { runInvocation };

package/dist/chain.js

@@ -0,0 +1,372 @@
+import { prepareDispatch, routeInvocation } from './command.js';
+import { InternalError, reasonOf, routedSubject, toFailure } from './errors.js';
+import { inspectGraph } from './inspect.js';
+import { booleanValue } from './options.js';
+import { pluginSentence } from './plugin.js';
+/**
+ * The view one run selects, which is one value whichever middleware wrote it. The assignment is
+ * kept as it arrived, because a JavaScript caller reaches the setter with any value and the check
+ * belongs at the dispatch boundary, where the fault it raises ranks behind a held fault.
+ */
+class ViewSelection {
+    #assigned = undefined;
+    #reached = false;
+    #result;
+    constructor(result) {
+        this.#result = result;
+    }
+    /**
+     * What `view` reads: the assigned name, or the declaration's default until one is assigned, and
+     * `null` on a Command that declares no result, whatever was assigned there. An assignment that is
+     * not a name reads as the default, because the getter answers a view name and the assignment is
+     * the boundary's fault. The assignment itself is kept either way, so the boundary still raises it.
+     */
+    read() {
+        if (!this.#result) {
+            return null;
+        }
+        const assigned = this.#assigned;
+        if (assigned !== undefined && typeof assigned.name === 'string') {
+            return assigned.name;
+        }
+        return this.#result.default;
+    }
+    /** The last assignment before the boundary wins; one made after it changes nothing. */
+    assign(identity, name) {
+        if (!this.#reached) {
+            this.#assigned = { identity, name };
+        }
+    }
+    /** The chain reached the dispatch boundary, so this run's view is fixed whatever follows. */
+    reach() {
+        this.#reached = true;
+    }
+    /**
+     * The name the boundary dispatches through: `null` when no middleware assigned one and the
+     * declaration's default stands. A plugin that selected a view has the name checked here.
+     */
+    resolve(path) {
+        const assigned = this.#assigned;
+        if (assigned === undefined) {
+            return null;
+        }
+        const plugin = pluginSentence(assigned.identity);
+        const { name } = assigned;
+        if (!this.#result) {
+            throw new InternalError(`${plugin} selected view "${String(name)}" on ${routedSubject(path)}, which declares no result.`, undefined);
+        }
+        if (typeof name !== 'string') {
+            throw new InternalError(`${plugin} selected a view that is not a string on ${routedSubject(path)}.`, undefined);
+        }
+        if (!this.#result.views.has(name)) {
+            throw new InternalError(`${plugin} selected view "${name}", which ${routedSubject(path)} does not name.`, undefined);
+        }
+        return name;
+    }
+}
+/**
+ * The default export a 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. Core calls it with the
+ * context it owns and ignores whatever it returns.
+ */
+function isMiddlewareExport(value) {
+    return typeof value === 'function';
+}
+/** Whether one option name was supplied as a token, in any spelling a declaration accepts. */
+function supplied(scan, name) {
+    return scan.strings.has(name) || scan.lists.has(name) || scan.booleans.has(name);
+}
+/** 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's own option values for one run: what the pre-scan produced, or the declared default,
+ * filled without validation. A collected value and an array default are copied, so a middleware
+ * that writes to what it received changes neither the declaration nor the next run.
+ */
+function pluginValues(inputs, scan) {
+    const values = {};
+    for (const { config, name } of inputs) {
+        const declared = config.default;
+        if (config.type === 'boolean') {
+            values[name] = booleanValue(scan, name, config);
+        }
+        else if (config.multiple === true) {
+            values[name] = collectedValue(scan.lists.get(name), declared);
+        }
+        else {
+            // Build already proved that a string option without a schema declares a string default.
+            values[name] =
+                scan.strings.get(name) ?? (typeof declared === 'string' ? declared : undefined);
+        }
+    }
+    return values;
+}
+/** Whether one plugin's declared activation matched the tokens the pre-scan consumed. */
+function activates(installed, scan) {
+    const { middleware } = installed;
+    if (!middleware) {
+        return false;
+    }
+    return (middleware.activate === 'always' || middleware.activate.some((name) => supplied(scan, name)));
+}
+/**
+ * The chain for one invocation: each installed plugin whose activation matched, in installation
+ * order. Activation is read from the pre-scan, before any plugin code loads, so a plugin whose
+ * option was never supplied is not in the chain and its loader is never called.
+ */
+function activatedEntries(plugins, scan) {
+    return plugins
+        .filter((installed) => activates(installed, scan))
+        .map((installed) => ({
+        identity: installed.identity,
+        // Activation proved the middleware exists, so the empty loader is never the one core calls.
+        load: installed.middleware?.load ?? (() => undefined),
+        options: pluginValues(installed.inputs, scan),
+    }));
+}
+/**
+ * The routed node inside the inspected graph, which routing already proved reachable. A missing
+ * segment means the two readings of one graph disagree, so the chain stops rather than hand a
+ * middleware the wrong Command.
+ */
+function nodeAt(graph, path) {
+    let node = graph.root;
+    for (const name of path) {
+        const child = node.children.find((entry) => entry.name === name);
+        if (!child) {
+            throw new InternalError(`The routed command "${path.join(' ')}" is not in the inspected graph.`, undefined);
+        }
+        node = child;
+    }
+    return node;
+}
+/** A downstream promise core awaits for its completion alone; its outcome was recorded already. */
+async function quiet(pending) {
+    if (pending) {
+        try {
+            await pending;
+        }
+        catch {
+            // The rejection was recorded where it crossed the `next()` boundary.
+        }
+    }
+}
+/**
+ * The outcome one entry reports to its caller. `'cancelled'` wins over `'taken-over'`, so a later
+ * middleware that returned because it saw the abort reports as cancelled, the order the exit codes
+ * follow. An action that already ran still reports as dispatched.
+ */
+function reported(chain, outcome) {
+    return outcome === 'taken-over' && chain.cancelled() ? 'cancelled' : outcome;
+}
+/** A `next()` call that is no longer live: it dispatches nothing and rejects. */
+function misuse(turn) {
+    const fault = new InternalError(`${pluginSentence(turn.entry.identity)} called next() ${turn.state.returned ? 'after its middleware returned' : 'twice'}.`, undefined);
+    turn.chain.report(fault);
+    const rejected = Promise.reject(fault);
+    void rejected.catch(() => undefined);
+    return rejected;
+}
+/**
+ * The `next` one middleware receives. It is live until that middleware's own result settles, so a
+ * second call, or a call after the middleware returned, rejects and continues nothing.
+ */
+function nextOf(turn) {
+    const { chain, state } = turn;
+    return () => {
+        if (state.returned || state.calls > 0) {
+            return misuse(turn);
+        }
+        state.calls += 1;
+        const pending = chain.step(turn.index + 1).then((outcome) => {
+            state.outcome = outcome;
+            state.settled = true;
+            return outcome;
+        }, (error) => {
+            state.rejection = { value: error };
+            state.settled = true;
+            chain.record(error);
+            throw error;
+        });
+        state.downstream = pending;
+        // Core awaits the downstream promise itself.
+        // A middleware that never awaits `next()` still holds the chain open.
+        // The run therefore never ends with an unobserved rejection.
+        void pending.catch(() => undefined);
+        return pending;
+    };
+}
+/** The middleware's own result as a value, so the decision below reads one shape. */
+async function call(middleware, context) {
+    try {
+        await middleware(context);
+        return undefined;
+    }
+    catch (error) {
+        return { value: error };
+    }
+}
+/**
+ * What one entry reports to its caller once its own result has settled. A throw before `next()`
+ * settled, or without calling it, is this invocation's failure; a throw during unwinding is an
+ * internal error reported after the primary outcome, which keeps its own code.
+ */
+async function settle(turn, thrown) {
+    const { chain, state } = turn;
+    if (thrown) {
+        const propagated = state.rejection !== undefined && thrown.value === state.rejection.value;
+        if (propagated || !state.settled) {
+            await quiet(state.downstream);
+            throw thrown.value;
+        }
+        /**
+         * A fault core recorded where it was raised, such as a misused `next()`, reaches this point
+         * again when the middleware let it escape. It keeps the one report it already has.
+         */
+        if (!chain.announced(thrown.value)) {
+            chain.report(new InternalError(reasonOf(thrown.value), thrown.value));
+        }
+    }
+    if (state.calls === 0) {
+        return reported(chain, 'taken-over');
+    }
+    await quiet(state.downstream);
+    // A middleware that caught the rejection reports what the chain reached.
+    // The recorded failure still decides the exit code.
+    return reported(chain, state.outcome ?? (chain.invoked() ? 'dispatched' : 'taken-over'));
+}
+/** The module one loader answers with, whether it throws where it is called or rejects later. */
+async function loadModule(entry) {
+    try {
+        return await entry.load();
+    }
+    catch (error) {
+        throw new InternalError(`Loading plugin "${entry.identity}" failed: ${reasonOf(error)}`, error);
+    }
+}
+/** A plugin's module is loaded when the chain reaches it, never before. */
+async function loadMiddleware(entry) {
+    const module = await loadModule(entry);
+    const handler = module !== null && typeof module === 'object' && 'default' in module
+        ? module.default
+        : undefined;
+    if (!isMiddlewareExport(handler)) {
+        throw new InternalError(`Loading plugin "${entry.identity}" failed: the module exports no default middleware function.`, undefined);
+    }
+    return handler;
+}
+/** One entry's turn: its module loads here, when the chain reaches it and never before. */
+async function runEntry(entry, index, chain) {
+    const middleware = await loadMiddleware(entry);
+    if (chain.cancelled()) {
+        /**
+         * A module import cannot be aborted, so a loader already in flight settles and core starts
+         * nothing with it: the middleware it resolved to is skipped.
+         */
+        return 'cancelled';
+    }
+    const state = { calls: 0, returned: false, settled: false };
+    const turn = { chain, entry, index, state };
+    const thrown = await call(middleware, chain.context(entry, nextOf(turn)));
+    state.returned = true;
+    return settle(turn, thrown);
+}
+/** The whole chain, answering with the failure it raised when a middleware caught that failure. */
+async function runChain(invocation, routed, prepared) {
+    const entries = activatedEntries(invocation.plugins, routed.scan);
+    const run = { invoked: false, raised: undefined };
+    const selection = new ViewSelection(prepared.result);
+    /**
+     * The dispatch boundary: the point the chain reaches when its last middleware continues. Core
+     * raises the held fault here, so it ranks ahead of a bad view assignment, or else reads the
+     * selected view and dispatches the action.
+     */
+    const terminal = async () => {
+        selection.reach();
+        if (prepared.kind === 'held') {
+            throw prepared.fault;
+        }
+        const view = selection.resolve(routed.path);
+        run.invoked = true;
+        await prepared.dispatch(view);
+        return 'dispatched';
+    };
+    const cancelled = () => invocation.signal.aborted;
+    if (entries.length === 0) {
+        if (!cancelled()) {
+            await terminal();
+        }
+        return undefined;
+    }
+    // The graph a middleware reads is the one `inspect()` returns, built once for the run.
+    const graph = inspectGraph(invocation.name, invocation.graph, invocation.facts);
+    const command = nodeAt(graph, routed.path);
+    // Every fault this chain has reported, so the same one raised again carries no second report.
+    const announced = new WeakSet();
+    const chain = {
+        announced: (value) => typeof value === 'object' && value !== null && announced.has(value),
+        cancelled,
+        context: (entry, next) => ({
+            command,
+            graph,
+            host: invocation.host,
+            next,
+            options: entry.options,
+            out: invocation.out,
+            request: prepared.request,
+            signal: invocation.signal,
+            get view() {
+                return selection.read();
+            },
+            set view(name) {
+                selection.assign(entry.identity, name);
+            },
+        }),
+        invoked: () => run.invoked,
+        record: (error) => {
+            run.raised ??= toFailure(error);
+        },
+        report: (fault) => {
+            announced.add(fault);
+            invocation.report(fault);
+        },
+        step: (index) => {
+            if (cancelled()) {
+                /**
+                 * Core starts nothing new after cancellation: a middleware the chain has not reached and
+                 * an action not yet dispatched are skipped, and the entries already running unwind.
+                 */
+                return Promise.resolve('cancelled');
+            }
+            const entry = entries[index];
+            return entry ? runEntry(entry, index, chain) : terminal();
+        },
+    };
+    await chain.step(0);
+    return run.raised;
+}
+/**
+ * Runs one invocation: the global pre-scan, routing, the dispatch this invocation prepares, and the
+ * middleware chain it then runs. Local parsing and validation run ahead of the chain so that a
+ * middleware reads the request, and the fault they find is held until the dispatch boundary. A
+ * middleware that returns without calling `next()` has taken over, so the held fault is never
+ * raised and nothing later in the chain runs.
+ */
+async function runInvocation(invocation) {
+    const routed = routeInvocation(invocation.graph, invocation.host.argv);
+    invocation.route(routed.path);
+    const prepared = await prepareDispatch(invocation.graph, routed, invocation);
+    const raised = await runChain(invocation, routed, prepared);
+    if (raised) {
+        // The chain resolved because a middleware caught the rejection.
+        // The failure it caught still decides the exit code.
+        // That is the rule an action's caught output rejection already follows.
+        throw raised;
+    }
+}
+export { runInvocation };