@loomcli/core 0.1.1 → 0.2.0

package/dist/command.js

@@ -1,5 +1,7 @@
 import { commandSentence, commandSubject, DeclarationError, NonCallableCommandError, UnexpectedArgumentError, UnknownCommandError, } from './errors.js';
-import { bindGlobals, buildGlobals } from './globals.js';
+import { buildExtensions } from './extension.js';
+import { checkDeprecated, checkDescription, checkHidden, checkNoListingFacts, isPlainObject, } from './facts.js';
+import { bindGlobals, buildGlobals, isGlobalOptions, keyCollision, spellingCollision, } from './globals.js';
 import { compileOptions, extractGlobals, mergeValues, parseInputs } from './options.js';
 import { captureConfig, validateValues } from './validation.js';
 /** Authored values register here, so the public type publishes no state to reach or replace. */
@@ -12,6 +14,22 @@ function nodeOf(parent, child) {
     }
     return node;
 }
+/**
+ * The shape of a Command's second argument, read where it is supplied. The retired positional form
+ * declares its globals on a value that holds no `globals` key, so without this rule the globals
+ * vanish silently and the operator, not the author, meets the consequence as an unknown-option
+ * error. It answers before every other rule, because a Command that lost its globals this way would
+ * otherwise report the mismatch with its Application instead of the slot that caused it.
+ * The facts the slot carried were captured at construction, so this reads the slot's shape alone.
+ */
+function checkCommandOptions(name, options) {
+    if (isGlobalOptions(options)) {
+        throw new DeclarationError(`${commandSentence(name)} takes an options object. Supply { globals } instead of a positional GlobalOptions value.`);
+    }
+    if (options !== undefined && !isPlainObject(options)) {
+        throw new DeclarationError(`${commandSentence(name)} options must be an object. Supply { globals }.`);
+    }
+}
 /** One name rule for every declared name in the graph, so a child and an argument read alike. */
 function isDeclaredName(name) {
     return typeof name === 'string' && Boolean(name) && !name.startsWith('-') && !/[\s=]/u.test(name);
@@ -27,17 +45,26 @@ function checkAliasName(command, alias) {
         throw new DeclarationError(`${commandSentence(command)} declares an alias named "${String(alias)}". Use a nonempty name without a leading hyphen, whitespace, or "=".`);
     }
 }
-/** The state every declaration starts from. The unnamed root and each named Command share it. */
-export function freshState(name, globals) {
+/**
+ * The state every declaration starts from. The unnamed root and each named Command share it.
+ * The declaration values arrive captured, because a later change to the options object the author
+ * passed changes nothing the declaration holds.
+ */
+export function freshState(declaration) {
     return {
         actions: [],
         aliases: [],
         bind: () => ({ args: {}, options: {} }),
         children: [],
-        globals,
+        deprecated: declaration.deprecated,
+        description: declaration.description,
+        extensions: declaration.extensions,
+        globals: declaration.globals,
+        hidden: declaration.hidden,
         inputs: [],
         late: [],
-        name,
+        name: declaration.name,
+        options: declaration.options,
     };
 }
 /** A declaration after the action is an order fault; build reports the first one recorded. */
@@ -216,18 +243,26 @@ function collectArguments(state, subject) {
     }
     return slots;
 }
+/**
+ * One Command's own options against the shared globals table. The table holds the application's
+ * globals and every plugin option, so a local collision reads the same sentence whichever scope on
+ * the other side claimed the name or the spelling.
+ */
 function compileLocalOptions(state, globals, subject) {
     const declarations = state.inputs.filter((input) => input.kind === 'option');
+    const local = { kind: 'local', subject };
+    const application = { kind: 'application' };
     for (const declaration of declarations) {
-        if (globals.names.has(declaration.name)) {
-            throw new DeclarationError(`Option "${declaration.name}" is declared as a global option and as a local option on ${subject}. Rename the local option.`);
+        const claimed = globals.names.get(declaration.name);
+        if (claimed) {
+            throw keyCollision(declaration.name, claimed, local);
         }
     }
     const options = compileOptions(declarations, subject);
     for (const [spelling, option] of options) {
         const global = globals.options.get(spelling);
         if (global) {
-            throw new DeclarationError(`Option spelling "${spelling}" is used by the global option "${global.name}" and the local option "${option.name}" on ${subject}. Change one declaration.`);
+            throw spellingCollision(spelling, { name: global.name, owner: globals.names.get(global.name) ?? application }, { name: option.name, owner: local });
         }
     }
     return options;
@@ -249,7 +284,7 @@ function checkGroup(state, children) {
 }
 /** Binds one Command's declarations to its action, so an action reads only validated values. */
 function bindDispatch(state, action) {
-    return ({ host, out, passthrough, values }) => {
+    return ({ host, out, passthrough, signal, values }) => {
         const bound = state.bind(values);
         return action({
             args: bound.args,
@@ -257,6 +292,7 @@ function bindDispatch(state, action) {
             options: { ...bindGlobals(state.globals, values), ...bound.options },
             out,
             passthrough,
+            signal,
         });
     };
 }
@@ -265,6 +301,34 @@ export function buildCommand(state, context) {
     const { actions, name } = state;
     const { globals } = context;
     const subject = commandSubject(name);
+    checkCommandOptions(name, state.options);
+    const description = checkDescription(commandSentence(name), state.description);
+    const hidden = checkHidden(commandSentence(name), state.hidden);
+    const deprecated = checkDeprecated(commandSentence(name), state.deprecated);
+    const extensions = buildExtensions({
+        declared: state.extensions,
+        descriptors: context.descriptors,
+        subject: { phrase: `on ${subject}`, sentence: commandSentence(name) },
+        target: 'command',
+    });
+    // Each declaration's own facts, in authoring order, before the rules that pair declarations.
+    for (const input of state.inputs) {
+        const sentence = `${commandSentence(name)} ${input.kind} "${input.name}"`;
+        checkDescription(sentence, input.config.description);
+        if (input.kind === 'argument') {
+            checkNoListingFacts(sentence, input.config);
+        }
+        else {
+            checkHidden(sentence, input.config.hidden);
+            checkDeprecated(sentence, input.config.deprecated);
+        }
+        context.extensions.set(input, buildExtensions({
+            declared: input.config.extensions,
+            descriptors: context.descriptors,
+            subject: { phrase: `on ${subject} ${input.kind} "${input.name}"`, sentence },
+            target: input.kind,
+        }));
+    }
     if (state.globals !== globals.source) {
         throw new DeclarationError(`${commandSentence(name)} holds a different GlobalOptions value than its Application. Share one GlobalOptions value across the declarations.`);
     }
@@ -302,7 +366,11 @@ export function buildCommand(state, context) {
         aliases,
         arguments: slots,
         children,
+        deprecated,
+        description,
         dispatch: action ? bindDispatch(state, action) : undefined,
+        extensions,
+        hidden,
         inputs: state.inputs,
         name,
         options,
@@ -310,9 +378,18 @@ export function buildCommand(state, context) {
     };
 }
 /** The globals table and the owners record each compile once per invocation and the whole graph shares them. */
-export function buildGraph(root) {
-    const context = { globals: buildGlobals(root.globals), owners: new Map() };
-    return { globals: context.globals, root: buildCommand(root, context) };
+export function buildGraph(root, install) {
+    const context = {
+        descriptors: install.descriptors,
+        extensions: install.extensions,
+        globals: buildGlobals(root.globals, install.plugins, install),
+        owners: new Map(),
+    };
+    return {
+        extensions: context.extensions,
+        globals: context.globals,
+        root: buildCommand(root, context),
+    };
 }
 export class CommandBuilder {
     #state;
@@ -340,8 +417,8 @@ export class CommandBuilder {
         return new CommandBuilder(declareOption(this.#state, input));
     }
     /**
-     * Hidden aliases are other bare tokens that route to this Command. They invalidate no call, and
-     * the tuple rest parameter rejects a call that names none.
+     * Aliases are other bare tokens that route to this Command. They invalidate no call, and the
+     * tuple rest parameter rejects a call that names none.
      */
     alias(...names) {
         return new CommandBuilder(declareAlias(this.#state, names));
@@ -364,11 +441,21 @@ export class CommandBuilder {
  * signature of the constructor interface publishes.
  */
 class CommandDeclaration extends CommandBuilder {
-    constructor(name, globals) {
-        super(freshState(name, globals));
+    constructor(name, options) {
+        // The options slot is read defensively, never inspected: an invalid value still yields
+        // `globals`, the core facts, and `extensions` of some kind, and `buildCommand` reports it.
+        super(freshState({
+            deprecated: options?.deprecated,
+            description: options?.description,
+            extensions: options?.extensions,
+            globals: options?.globals,
+            hidden: options?.hidden,
+            name,
+            options,
+        }));
     }
 }
-/** The public constructor requires a name and narrows the globals type to the supplied value. */
+/** The public constructor takes a name and one options object, as the Application does. */
 export const Command = CommandDeclaration;
 /** Every declaration in the graph, so defaults are validated before any token is read. */
 export function collectInputs(command) {
@@ -377,6 +464,14 @@ export function collectInputs(command) {
         ...[...command.children.values()].flatMap((child) => collectInputs(child)),
     ];
 }
+/**
+ * The names a routing failure offers: the canonical names of the visible children, in authoring
+ * order. A candidate list is a listing, so a hidden child is absent from it, and a parent whose
+ * children are all hidden offers none.
+ */
+function candidatesOf(command) {
+    return [...command.children].filter(([, child]) => !child.hidden).map(([name]) => name);
+}
 /** Bare tokens, names or aliases, select children until a Command has none; a hyphen commits. */
 export function route(root, tokens) {
     let command = root;
@@ -389,7 +484,7 @@ export function route(root, tokens) {
         }
         const child = command.routes.get(token);
         if (!child) {
-            throw new UnknownCommandError(token, [...command.children.keys()]);
+            throw new UnknownCommandError(token, candidatesOf(command));
         }
         // An alias routes like the canonical name, and the path it walks reports that name alone.
         command = child.command;
@@ -428,25 +523,44 @@ function bindArguments(command, path, positionals) {
     }
     return values;
 }
-/** Consumes globals, routes to a Command, then validates globals and locals in one pass. */
-export async function selectCommand(graph, invocation) {
-    const { host } = invocation;
-    const scan = extractGlobals(graph.globals.options, [...host.argv]);
-    const { command, path, tokens: rest } = route(graph.root, scan.rest);
+/** Consumes the globals table, then routes the remaining bare tokens to a Command. */
+export function routeInvocation(graph, argv) {
+    const scan = extractGlobals(graph.globals.options, [...argv]);
+    const routed = route(graph.root, scan.rest);
+    return {
+        command: routed.command,
+        path: routed.path,
+        scan: scan.values,
+        tokens: routed.tokens,
+    };
+}
+/**
+ * The phases the middleware chain terminates in: the callable check, local parsing, validation, and
+ * the action. It answers with the call that dispatches, so the caller records that the action was
+ * invoked at the moment it invokes it and no earlier failure reads as a dispatch.
+ */
+export async function prepareDispatch(graph, routed, invocation) {
+    const { command, path, scan } = routed;
     const { dispatch } = command;
     // A group answers no invocation of its own, so it fails with the routing errors above it.
     if (!dispatch) {
-        throw new NonCallableCommandError(path, [...command.children.keys()]);
+        throw new NonCallableCommandError(path, candidatesOf(command));
     }
-    const parsed = parseInputs(command.options, rest);
+    const parsed = parseInputs(command.options, routed.tokens);
     const args = bindArguments(command, path, parsed.positionals);
     const values = await validateValues({
         command: path,
         defaults: invocation.defaults,
-        host,
+        host: invocation.host,
         inputs: { globals: graph.globals.inputs, locals: command.inputs },
         passthrough: parsed.passthrough,
-        supplied: { args, options: mergeValues(scan.values, parsed.options) },
+        supplied: { args, options: mergeValues(scan, parsed.options) },
+    });
+    return () => dispatch({
+        host: invocation.host,
+        out: invocation.out,
+        passthrough: parsed.passthrough,
+        signal: invocation.signal,
+        values,
     });
-    return { dispatch, passthrough: parsed.passthrough, values };
 }

package/dist/errors.d.ts

@@ -134,8 +134,16 @@ export type FailureRenderer = Pick<RegisteredFailure, typeof failureRegistration
 export declare function renderFailure<Failure extends LoomError>(type: abstract new (...args: never[]) => Failure, renderer: Renderer<Failure>): FailureRenderer;
 /** The renderers one application registered, keyed by the class each one names. */
 export type FailureRegistry = ReadonlyMap<unknown, Registration>;
-/** One class answers to one renderer, so a second registration for it is a declaration fault. */
-export declare function buildFailures(failures: readonly FailureRenderer[]): FailureRegistry;
+/**
+ * One class answers to one renderer inside one contributor, so a second registration for it is a
+ * declaration fault. The subject names the contributor: the Application, or an installed plugin.
+ */
+export declare function buildFailures(failures: readonly FailureRenderer[], subject?: string): FailureRegistry;
+/**
+ * One registry from every contributor's own, resolving first-in-wins: the application's
+ * registrations, then each installed plugin's in installation order, then core's text.
+ */
+export declare function mergeFailures(registries: readonly FailureRegistry[]): FailureRegistry;
 /**
  * The report of one failure: the text core writes, and whether a registered renderer produced it.
  * An unrendered report carries core's own text, which the plain fallback path writes beside the

package/dist/errors.js

@@ -3,6 +3,13 @@ function routedSentence(command) {
     const name = command.at(-1);
     return name === undefined ? 'The root Command' : commandSentence(name);
 }
+/**
+ * The clause that offers the candidates, which is absent when there are none: every child of the
+ * Command is hidden, so the diagnostic ends after the sentence that names the fault.
+ */
+function offering(candidates) {
+    return candidates.length === 0 ? '' : ` Use one of: ${candidates.join(', ')}.`;
+}
 function shortGroupMessage(fault) {
     return fault.reason === 'value-position'
         ? `Value option "${fault.token}" must be last in its short group. Supply its value in the next token.`
@@ -46,10 +53,10 @@ class RegisteredFailure {
     }
 }
 /** Reads the pair behind a registered value; anything else is a declaration error. */
-function nodeOf(value) {
+function nodeOf(value, subject) {
     const registration = nodes.get(value);
     if (!registration) {
-        throw new DeclarationError('The Application holds a value that is not a failure renderer. Supply the value returned by renderFailure(type, renderer).');
+        throw new DeclarationError(`${subject} holds a value that is not a failure renderer. Supply the value returned by renderFailure(type, renderer).`);
     }
     return registration;
 }
@@ -96,7 +103,7 @@ export class UnknownCommandError extends UsageError {
     token;
     candidates;
     constructor(token, candidates) {
-        super(`Unknown command "${token}". Use one of: ${candidates.join(', ')}.`);
+        super(`Unknown command "${token}".${offering(candidates)}`);
         this.candidates = candidates;
         this.name = 'UnknownCommandError';
         this.token = token;
@@ -107,7 +114,7 @@ export class NonCallableCommandError extends UsageError {
     command;
     candidates;
     constructor(command, candidates) {
-        super(`${routedSentence(command)} requires a subcommand. Use one of: ${candidates.join(', ')}.`);
+        super(`${routedSentence(command)} requires a subcommand.${offering(candidates)}`);
         this.candidates = candidates;
         this.command = command;
         this.name = 'NonCallableCommandError';
@@ -225,18 +232,36 @@ export function renderFailure(type, renderer) {
         render: (failure) => (failure instanceof type ? renderer.render(failure) : undefined),
     });
 }
-/** One class answers to one renderer, so a second registration for it is a declaration fault. */
-export function buildFailures(failures) {
+/**
+ * One class answers to one renderer inside one contributor, so a second registration for it is a
+ * declaration fault. The subject names the contributor: the Application, or an installed plugin.
+ */
+export function buildFailures(failures, subject = 'The Application') {
     const registry = new Map();
     for (const failure of failures) {
-        const registration = nodeOf(failure);
+        const registration = nodeOf(failure, subject);
         if (registry.has(registration.prototype)) {
-            throw new DeclarationError(`The Application registers two failure renderers for "${registration.name}". Remove one registration.`);
+            throw new DeclarationError(`${subject} registers two failure renderers for "${registration.name}". Remove one registration.`);
         }
         registry.set(registration.prototype, registration);
     }
     return registry;
 }
+/**
+ * One registry from every contributor's own, resolving first-in-wins: the application's
+ * registrations, then each installed plugin's in installation order, then core's text.
+ */
+export function mergeFailures(registries) {
+    const merged = new Map();
+    for (const registry of registries) {
+        for (const [type, registration] of registry) {
+            if (!merged.has(type)) {
+                merged.set(type, registration);
+            }
+        }
+    }
+    return merged;
+}
 /**
  * The text core writes for one failure. Resolution walks the failure's prototype chain most
  * derived first through the application's registrations, then falls to core's own text, so a

package/dist/extension.d.ts

@@ -0,0 +1,95 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { ArgumentNode, CommandNode, OptionNode } from './inspect.js';
+/** The three declaration kinds an extension can name, each with its own node in the graph. */
+type ExtensionTarget = 'argument' | 'command' | 'option';
+/**
+ * The descriptor supertype a plugin's `extensions` list uses. It publishes the identity and the
+ * target and erases both the schema and the factory call signature, because a schema-typed call
+ * signature relates only by schema identity and a list cannot name one schema per element. A
+ * descriptor is assignable to it; an extension value, which publishes its brand alone, is not.
+ */
+interface AnyExtension {
+    readonly identity: string;
+    readonly target: ExtensionTarget;
+}
+/** One carried value: the input its author supplied and the descriptor that produced it. */
+interface CarriedValue {
+    descriptor: AnyExtension;
+    input: unknown;
+}
+/** Phantom key. It brands an extension value with its target and holds no runtime value. */
+declare const extensionTarget: unique symbol;
+/**
+ * The value one extension produces, branded with its target so a value on the wrong declaration is
+ * a compile error. It publishes the brand alone, so a value is never mistaken for the descriptor
+ * that produced it, and the input it carries stays private to this package.
+ */
+declare class ExtensionCarrier<Target extends ExtensionTarget> {
+    readonly [extensionTarget]: (target: Target) => Target;
+    constructor(record: CarriedValue);
+}
+/** A branded extension value, keyed by its extension's identity and typed by its target. */
+type ExtensionValue<Target extends ExtensionTarget> = Pick<ExtensionCarrier<Target>, typeof extensionTarget>;
+/**
+ * A descriptor that is also a factory: calling it with the schema's input returns the branded value
+ * a declaration carries. The schema is public so a typed read recovers the output type.
+ */
+interface Extension<Target extends ExtensionTarget = ExtensionTarget, Schema extends StandardSchemaV1 = StandardSchemaV1> extends AnyExtension {
+    (input: StandardSchemaV1.InferInput<Schema>): ExtensionValue<Target>;
+    readonly schema: Schema;
+    readonly target: Target;
+}
+/**
+ * One typed fact a plugin defines for one target. The descriptor is compared by reference wherever
+ * it appears, so one identity means one descriptor and a duplicated package copy is visible.
+ */
+declare function extension<Target extends ExtensionTarget, Schema extends StandardSchemaV1>(identity: string, config: {
+    schema: Schema;
+    target: Target;
+}): Extension<Target, Schema>;
+/** The node kind one descriptor's target names, so a read against another kind cannot compile. */
+type NodeFor<Target extends ExtensionTarget> = Target extends 'command' ? CommandNode : Target extends 'option' ? OptionNode : ArgumentNode;
+/** Stored output is plain data the graph froze, so every read of it is read-only to any depth. */
+type DeepReadonly<Value> = Value extends readonly (infer Item)[] ? readonly DeepReadonly<Item>[] : Value extends object ? {
+    readonly [Key in keyof Value]: DeepReadonly<Value[Key]>;
+} : Value;
+/**
+ * The typed read of one extension value. It takes the node kind the descriptor targets, returns the
+ * stored output or `undefined`, compares the descriptor by reference with the one that produced the
+ * value, and runs no schema.
+ */
+declare function readExtension<Target extends ExtensionTarget, Schema extends StandardSchemaV1>(node: NodeFor<Target>, descriptor: Extension<Target, Schema>): DeepReadonly<StandardSchemaV1.InferOutput<Schema>> | undefined;
+/** The declaration one `extensions` slot belongs to, as its own diagnostics name it. */
+interface ExtensionSubject {
+    /** The subject after a preposition, such as `on Command "get"`. */
+    phrase: string;
+    /** The subject at the start of a sentence, such as `Command "get"`. */
+    sentence: string;
+}
+/** Every descriptor one build has met, so a second descriptor under one identity is visible. */
+type DescriptorRegistry = Map<string, AnyExtension>;
+/**
+ * The record each declaration published during one build, keyed by the declaration itself. The
+ * records live here rather than on the declaration, because one build's outputs belong to that
+ * build alone and inspection reads them back with the nodes it renders.
+ */
+type ExtensionRecords = Map<object, Readonly<Record<string, unknown>>>;
+/** Whether a value is a descriptor: a callable object carrying an identity and a declared target. */
+declare function isDescriptor(value: unknown): value is AnyExtension;
+/** One identity means one descriptor, wherever on the graph that descriptor appears. */
+declare function registerDescriptor(descriptors: DescriptorRegistry, descriptor: AnyExtension): void;
+/** Everything one `extensions` slot needs to answer: whose it is, and what it may carry. */
+interface ExtensionSlot {
+    declared: unknown;
+    descriptors: DescriptorRegistry;
+    subject: ExtensionSubject;
+    target: ExtensionTarget;
+}
+/**
+ * The frozen record one declaration publishes: each carried value validated once, synchronously,
+ * and stored under its extension's identity. The descriptors that produced them are recorded beside
+ * the record, so a typed read compares by reference without the graph carrying a reference.
+ */
+declare function buildExtensions(slot: ExtensionSlot): Readonly<Record<string, unknown>>;
+export type { AnyExtension, DeepReadonly, DescriptorRegistry, Extension, ExtensionRecords, ExtensionSubject, ExtensionTarget, ExtensionValue, };
+export { buildExtensions, extension, isDescriptor, readExtension, registerDescriptor };