@loomcli/core 0.2.0 → 0.4.0

package/dist/types.d.ts

@@ -2,6 +2,9 @@
 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 { 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';
 type ShortAlias = LowercaseLetter | Uppercase<LowercaseLetter>;
 type OptionSpelling = {
@@ -89,6 +92,7 @@ export interface OutputTerminal extends InputTerminal {
     rows: number | undefined;
 }
 export interface Host {
+    platform: string;
     argv: string[];
     cwd: string;
     env: Record<string, string | undefined>;
@@ -102,6 +106,7 @@ export interface Host {
     stderr: Writable;
 }
 export interface RunOptions {
+    rendering?: RenderingPolicy;
     host?: Partial<Host>;
     /**
      * A caller-owned signal that cancels the run. Core subscribes to it at run entry and honors an
@@ -143,24 +148,167 @@ export type ValidationContext = {
     passthrough: readonly string[];
     supplied: SuppliedInputs;
 };
+/** Immutable authoring and measurement context for one view destination. */
+export interface ViewContext {
+    readonly style: ContextualStyle;
+    readonly width: (text: string) => number;
+}
+/** A pure synchronous view turns one typed value into the marked text core resolves. */
+export interface View<Data> {
+    render: (data: Readonly<Data>, context: ViewContext) => string;
+    /** A view has one shape; the row view of Results is the other. */
+    row?: never;
+}
+/**
+ * A row view renders a sequence one row at a time.
+ * `head` and `tail` open and close the sequence, and each defaults to the empty string.
+ * Every function is pure and synchronous and owns the newlines in the text it returns.
+ */
+export interface RowView<Row> {
+    row: (row: Readonly<Row>, index: number, context: ViewContext) => string;
+    head?: (context: ViewContext) => string;
+    tail?: (count: number, context: ViewContext) => string;
+    /** A row view has one shape; the whole view of Rendered output is the other. */
+    render?: never;
+}
+/** The views record of a value result: every entry renders the whole value. */
+export type ResultViews<Value> = Readonly<Record<string, View<Value>>>;
+/**
+ * The views record of a rows result: a whole view over the collected rows, which core buffers the
+ * sequence for, or a row view, which core feeds as the rows arrive.
+ */
+export type RowViews<Row> = Readonly<Record<string, View<readonly Row[]> | RowView<Row>>>;
+/**
+ * One view a result names, with its data type erased, as the view registry erases a declared
+ * view's. The write site reads each function back through the key that resolved it.
+ */
+export type ResultView = View<never> | RowView<never>;
+/**
+ * One declared result as the write site reads it: the unit the action emits, the view names it
+ * declares in record order, and the key core renders when nothing selects another.
+ */
+export interface DeclaredResult {
+    default: string;
+    kind: 'value' | 'rows';
+    views: ReadonlyMap<string, ResultView>;
+}
+/** Phantom key. It brands the surface a lifecycle hook receives, so a forged value is not one. */
+export declare const attachedCommand: unique symbol;
+/**
+ * One Command as `onCommandAttach` receives it: the facts `inspect()` publishes, with their types
+ * erased, and the authoring calls a hook may make. Each call returns a new value whose facts hold
+ * what the call added, so a hook reads its own earlier calls back. The calls a hook cannot make are
+ * absent, because each of them changes what the action was compiled against or the graph's shape.
+ */
+export interface AttachedCommand {
+    readonly [attachedCommand]: true;
+    /** The Command's own name, and `null` for the root. */
+    readonly name: string | null;
+    readonly path: readonly string[];
+    readonly hasAction: boolean;
+    /** The declared argument names, in declaration order. */
+    readonly arguments: readonly string[];
+    /** The declared local option names, in declaration order. */
+    readonly options: readonly string[];
+    readonly result: ResultNode | null;
+    /**
+     * The extension record `inspect()` would publish for this Command at this hook: the author's
+     * layers, then every value an earlier hook or this hook's earlier `extend()` calls added.
+     */
+    readonly extensions: Readonly<Record<string, unknown>>;
+    argument(name: string, config: ArgumentConfig): AttachedCommand;
+    option(name: string, config: OptionConfig): AttachedCommand;
+    views(replacements: Readonly<Record<string, ResultView>>, options?: {
+        default?: string;
+    }): AttachedCommand;
+    extend(...values: readonly ExtensionValue<'command'>[]): AttachedCommand;
+}
 /**
- * One value turned into the exact text core writes. A renderer owns every byte, the trailing
- * newline included. It is synchronous and pure: it receives the value alone, returns a string, and
- * holds no output handle. A throw or a non-string return is a renderer failure.
+ * The lifecycle hook core calls once per Command at graph build, in installation order, each
+ * receiving what the previous plugin's hook returned.
  */
-export interface Renderer<Data> {
-    render: (data: Readonly<Data>) => string;
+export type CommandAttachHook = (command: AttachedCommand) => AttachedCommand;
+/**
+ * What `out.results` accepts for one declared result. The declaration rides in the declared types
+ * as a closed discriminant, so a Command that declares none carries the neutral `unknown` and its
+ * `out.results` takes `never`. The parameter is never a union, so distribution reaches one member.
+ */
+export type ResultInput<Result> = Result extends {
+    kind: 'value';
+    value: infer Value;
+} ? Value : Result extends {
+    kind: 'rows';
+    row: infer Row;
+} ? Iterable<Row> | AsyncIterable<Row> : never;
+/**
+ * The result an `out` carries where the declaration is not in hand. Its `results` accepts any
+ * value, because the authoring call already checked what the Command declares, and the channel
+ * core builds for an action carries that declaration at run time.
+ */
+export interface OpenResult {
+    kind: 'value';
+    value: unknown;
 }
-export interface Out {
+/** The record a `views()` call takes, which is the shape the carried result names. */
+export type ResultViewsOf<Result> = Result extends {
+    kind: 'value';
+    value: infer Value;
+} ? ResultViews<Value> : Result extends {
+    kind: 'rows';
+    row: infer Row;
+} ? RowViews<Row> : never;
+export interface Out<Result = unknown> {
     print(message: string): Promise<void>;
     info(message: string): Promise<void>;
     success(message: string): Promise<void>;
     warn(message: string): Promise<void>;
     error(message: string): Promise<void>;
-    /** The neutral presentation call: a rendered value has no purpose and no destination. */
-    render<Data>(data: Data, renderer: Renderer<Data>): Promise<void>;
+    /** The neutral view call: a rendered value has no purpose and no destination. */
+    render<Data>(data: Data, view: View<Data>): Promise<void>;
+    /** The same call over a sequence: core writes each row's text as the source yields it. */
+    render<Row>(rows: Iterable<Row> | AsyncIterable<Row>, view: RowView<Row>): Promise<void>;
+    /**
+     * The Command's own result, emitted once. Property syntax keeps the parameter contravariant, so
+     * a neutral `Out` never stands in for one that carries a declaration.
+     */
+    results: (value: ResultInput<Result>) => Promise<void>;
     fatal(message: string): never;
 }
+/**
+ * What the action's channel answers to: the routed path its diagnostics name, the result the
+ * routed Command declared, and the view this run selected. The declaration decides the
+ * destinations the channel carries, so the redirect is read from the graph once and never from the
+ * view a run selected; `view` decides the rendering alone, and is `null` when nothing selected one
+ * and the declaration's default stands.
+ */
+export interface ResultBinding {
+    path: readonly string[];
+    result: DeclaredResult | undefined;
+    view: string | null;
+}
+/**
+ * The routed Command's invocation after parsing and validation, which every middleware reads. The
+ * values are what the action receives, the output of each declaration's schema, for that Command's
+ * own arguments and local options; global and plugin option values are not here. The records are
+ * untyped and frozen, because a middleware runs ahead of every action and the graph carries no
+ * type for a value.
+ */
+export interface Request {
+    readonly args: Readonly<Record<string, unknown>>;
+    readonly options: Readonly<Record<string, unknown>>;
+    readonly passthrough: readonly string[];
+}
+/** The channel one action receives, with the emission the results lane holds it to. */
+export interface ActionChannel {
+    out: Out<OpenResult>;
+    /** Whether the action emitted its result, which the missing rule reads after it returned. */
+    emitted: () => boolean;
+    /**
+     * Stops every sequence this channel still has pending. The action's own failure stays primary,
+     * so a sequence it never awaited is stopped rather than drained.
+     */
+    stop: () => void;
+}
 export type StringOption = OptionSpelling & Presence & Multiplicity & Omission & Described & Listed & OptionExtensions & {
     type: 'string';
     polarity?: never;
@@ -251,8 +399,9 @@ export type BooleanOption = (OptionSpelling & Described & Listed & OptionExtensi
 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.
+ * option carries no schema and no presence rule, because the pre-scan consumes it ahead of routing,
+ * 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 & {
@@ -273,36 +422,40 @@ export type OptionValue<Config extends OptionConfig> = Config extends StringOpti
 } | {
     validateOmitted: true;
 } ? never : undefined) : boolean;
-export interface ActionContext<Args, Options = {}> {
+export interface ActionContext<Args, Options = {}, Result = unknown> {
+    readonly style: ContextualStyle;
     args: Args;
     options: Options;
     passthrough: string[];
-    out: Out;
+    out: Out<Result>;
     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;
+export type Action<Args, Options = {}, Result = unknown> = (context: ActionContext<Args, Options, Result>) => unknown;
 /** Phantom key. It keeps the inferred declaration types exact and holds no runtime value. */
 export declare const declaredTypes: unique symbol;
 /**
- * The three inferred types one declaration carries. The phantom member keeps them exact. Args and
- * options widen, so a child can satisfy a looser reader. The globals appear in both a parameter and
- * a return position, which makes them invariant: a child's globals must be the parent's own type,
- * not a subset and not a superset, because one table serves every Command in the graph.
+ * Arguments and local options describe the action's own inputs. Globals are a requirement on the
+ * Receiving Application: a library that needs none can attach wherever its local keys are disjoint.
  */
-export interface DeclaredTypes<Args, Options, Globals> {
+export interface DeclaredTypes<Args, Options, Globals, Result = unknown> {
     args: Args;
-    globals: (value: Globals) => Globals;
+    globals: (value: Globals) => void;
     options: Options;
+    /**
+     * The result the Command declares, or `unknown` where it declares none. A plain field keeps it
+     * covariant, so a child that carries one still satisfies a neutral `Command` annotation.
+     */
+    result: Result;
 }
 /**
  * The handler one declaration accepts. It reads the phantom types, not the `action()` call, so it
  * holds on a fresh declaration, on a partly declared one, and on one that registered its action.
  */
 export type ActionHandler<Declaration> = Declaration extends {
-    [declaredTypes]: DeclaredTypes<infer Args, infer Options, infer Globals>;
-} ? Action<Args, Globals & Options> : never;
+    [declaredTypes]: DeclaredTypes<infer Args, infer Options, infer Globals, infer Result>;
+} ? Action<Args, Globals & Options, Result> : never;
 /** The args object an extracted handler receives for this declaration. */
 export type ActionArgs<Declaration> = ActionArgument<Declaration> extends {
     args: infer Args;

package/dist/validation.d.ts

@@ -36,6 +36,8 @@ export interface Invocation {
     host: Host;
     inputs: ScopedInputs;
     passthrough: readonly string[];
+    /** The run's cancellation signal, which stops this phase between two schema calls. */
+    signal: AbortSignal;
     supplied: SuppliedValues;
 }
 /**
@@ -50,6 +52,11 @@ declare class ValidatedInputs {
     argument<Name extends string, Config extends ArgumentConfig>(input: ArgumentInput<Name, Config>): Record<Name, ArgumentValue<Config>>;
     /** The one-key record this option contributes to `options`, typed by its own config. */
     option<Name extends string, Config extends OptionConfig>(input: OptionInput<Name, Config>): Record<Name, OptionValue<Config>>;
+    /**
+     * One validated value read without its declared type, which is what an untyped reader such as a
+     * middleware's request receives. The declared types stay with the two readers above.
+     */
+    read(input: InputDeclaration): unknown;
 }
 export type { ValidatedInputs };
 /**
@@ -65,7 +72,7 @@ export declare function captureConfig<Config extends ArgumentConfig | OptionConf
 export declare function validatesOmission(input: InputDeclaration): boolean;
 /**
  * The dotted path an issue names inside a value, or `undefined` when the issue names the value
- * itself. Core's default text and an application's own renderer read a position through this one
+ * itself. Core's default text and an application's own view read a position through this one
  * helper, so a rejected item reads alike wherever its diagnostic is written.
  */
 export declare function issuePath(issue: StandardSchemaV1.Issue): string | undefined;

package/dist/validation.js

@@ -29,6 +29,13 @@ class ValidatedInputs {
     option(input) {
         return this.#field(input);
     }
+    /**
+     * One validated value read without its declared type, which is what an untyped reader such as a
+     * middleware's request receives. The declared types stay with the two readers above.
+     */
+    read(input) {
+        return this.#values.get(input);
+    }
     #field(input) {
         // Last resort: no typed path exists. The map stores every validated value as `unknown`.
         // An object literal with a generic computed key does not type as `Record<Name, _>` either.
@@ -227,7 +234,7 @@ async function validate(input, raw, context) {
 }
 /**
  * The dotted path an issue names inside a value, or `undefined` when the issue names the value
- * itself. Core's default text and an application's own renderer read a position through this one
+ * itself. Core's default text and an application's own view read a position through this one
  * helper, so a rejected item reads alike wherever its diagnostic is written.
  */
 export function issuePath(issue) {
@@ -239,7 +246,7 @@ export function issuePath(issue) {
 /**
  * The issues one rejection reports. A schema that returned none still rejected the value, so the
  * placeholder stands in for its silence. Reporting takes this list once: the reported problem
- * carries it and the default text is derived from it, so a renderer and core read the same issues.
+ * carries it and the default text is derived from it, so a view and core read the same issues.
  */
 function reported(issues) {
     return issues.length === 0
@@ -366,6 +373,14 @@ export async function validateValues(invocation) {
         lines.push(...messages(suppliedName(entry.input, spelling), issues));
     };
     for (const entry of declarations) {
+        if (invocation.signal.aborted) {
+            /**
+             * A cancelled run starts no further schema call. The one already in flight was awaited
+             * above, and whatever this phase collected is never raised, because the run resolves its
+             * cancellation code instead.
+             */
+            break;
+        }
         const { input } = entry;
         if (input.kind === 'option' && input.config.type === 'boolean') {
             values.set(input, booleanValue(supplied.options, input.name, input.config));

package/dist/view.d.ts

@@ -0,0 +1,180 @@
+import type { LoomError } from './errors.js';
+import type { RowView, View, ViewContext } from './types.js';
+/** Phantom key. It brands a declared view and holds no runtime value. */
+declare const declaredView: unique symbol;
+/** Phantom key. It makes a declared view invariant in its data type and holds no runtime value. */
+declare const invariant: unique symbol;
+/** Phantom key. It brands a view override and holds no runtime value. */
+declare const viewOverride: unique symbol;
+/** The brand one declared view carries, as an extension value carries its own. */
+interface DeclaredViewBrand {
+    readonly [declaredView]: true;
+}
+/**
+ * One declared view: the identity a diagnostic names it by, and the default view function an
+ * override replaces. The witness makes `Data` invariant, so a declared view is never reassigned as
+ * a declared view of another data type and a replacement that requires data the key does not carry
+ * is a compile error.
+ */
+interface DeclaredView<Data> extends View<Data>, DeclaredViewBrand {
+    readonly identity: string;
+    readonly [invariant]: (data: Data) => Data;
+}
+/**
+ * One declared row view: the same brand and witness a declared view carries, over the row type.
+ * `override` keyed by it takes a row view, under the rules a declared view follows unchanged.
+ */
+interface DeclaredRowView<Row> extends RowView<Row>, DeclaredViewBrand {
+    readonly identity: string;
+    readonly [invariant]: (row: Row) => Row;
+}
+/**
+ * The supertype a contribution list uses. It keeps the identity, the brand, and a view function of
+ * either shape over `never`, and drops the invariance witness, because a list cannot carry one type
+ * parameter per element and an invariant type has no common supertype across data types.
+ */
+type AnyDeclaredView = (View<never> | RowView<never>) & DeclaredViewBrand & {
+    readonly identity: string;
+};
+/** A failure class as an override key, so `UsageError` and an application's subclass both fit. */
+type FailureClass<Failure extends LoomError> = abstract new (...args: never[]) => Failure;
+/**
+ * One stored view function, with the data type erased. A registry holds one entry per key and
+ * cannot carry a type parameter per entry, so `override(key, replacement)` is where the
+ * replacement is typed against the key it answers.
+ */
+type ViewFunction = (data: never, context: ViewContext) => unknown;
+/** One stored row function, with the row type erased for the same reason. */
+type RowFunction = (row: never, index: number, context: ViewContext) => unknown;
+/** One stored function that opens a sequence and reads the context alone. */
+type HeadFunction = (context: ViewContext) => unknown;
+/** One stored function that closes a sequence and reads its completed row count. */
+type TailFunction = (count: number, context: ViewContext) => unknown;
+/** One stored view value: the functions of whichever shape its author supplied. */
+interface StoredView {
+    render?: ViewFunction | undefined;
+    row?: RowFunction | undefined;
+    head?: HeadFunction | undefined;
+    tail?: TailFunction | undefined;
+}
+/** Which of the two exclusive view functions one value carries, or that it carries the wrong set. */
+type ViewShape = 'both' | 'neither' | 'render' | 'row';
+/**
+ * The shape one value names. The argument is read defensively, because every call that takes a view
+ * is reachable from JavaScript and `null` is one such value.
+ */
+declare function shapeOf(value: {
+    render?: unknown;
+    row?: unknown;
+} | null | undefined): ViewShape;
+/**
+ * One declared view of either shape: an identity and its default functions. The data type is
+ * inferred from the function's first parameter when that parameter is an object type or a
+ * `readonly` array, and is stated for a primitive or a union, because inference runs through
+ * `Readonly<Data>`. The two shapes are told apart by the function present, and a definition that
+ * carries both or neither is rejected here rather than guessed at.
+ */
+declare function view<Data>(identity: string, definition: View<Data>): DeclaredView<Data>;
+declare function view<Row>(identity: string, definition: RowView<Row>): DeclaredRowView<Row>;
+/**
+ * What one override replaces: a declared view, a failure class read as its prototype, or a value
+ * that is neither, which build reports as the entry fault of the list that holds it.
+ */
+type OverrideKey = {
+    kind: 'view';
+    view: AnyDeclaredView;
+} | {
+    kind: 'failure';
+    name: string;
+    prototype: object;
+} | {
+    kind: 'invalid';
+};
+/** One override: the key it answers and the view value that supersedes the default. */
+interface OverrideRecord {
+    key: OverrideKey;
+    replacement: StoredView;
+}
+/** The runtime value `override()` returns. Its pair lives in the registry above. */
+declare class OverrideDeclaration {
+    readonly [viewOverride]: true;
+    constructor(record: OverrideRecord);
+}
+/** An opaque override pairing one key with the view function that replaces its default. */
+type ViewOverride = Pick<OverrideDeclaration, typeof viewOverride>;
+/** What a plugin's own list holds: the views it declares and the overrides it makes. */
+type ViewContribution = AnyDeclaredView | ViewOverride;
+/**
+ * One override pairing a key with a replacement view. Under a declared view the replacement is
+ * typed from the view's data; under a failure class it is typed from the class's instances, which
+ * is the typed path for a class-keyed list, because an array literal cannot carry a different type
+ * parameter per element.
+ */
+declare function override<Data>(key: DeclaredView<Data>, replacement: NoInfer<View<Data>>): ViewOverride;
+declare function override<Row>(key: DeclaredRowView<Row>, replacement: NoInfer<RowView<Row>>): ViewOverride;
+declare function override<Failure extends LoomError>(key: FailureClass<Failure> & {
+    readonly [declaredView]?: never;
+}, replacement: NoInfer<View<Failure>>): ViewOverride;
+/** One contributor's overrides, read once per build and consulted in contributor order. */
+interface ViewContributions {
+    failures: Map<unknown, StoredView>;
+    views: Map<AnyDeclaredView, StoredView>;
+}
+/**
+ * Every contributor in resolution order: the application's overrides, then each installed plugin's
+ * in installation order. The declaring view's own default answers when no contributor does.
+ */
+type ViewRegistry = readonly ViewContributions[];
+/** The identities one build has met, so a second object under one identity is visible. */
+type ViewIdentities = Map<string, AnyDeclaredView>;
+/** How one contributor's diagnostics name it, and whether its list may declare a view. */
+interface ViewSubject {
+    /** A plugin declares views beside its overrides; an application overrides alone. */
+    declares: boolean;
+    sentence: string;
+}
+/** The identity register one build starts from, holding the views core itself declares. */
+declare function viewIdentities(declared: readonly AnyDeclaredView[]): ViewIdentities;
+/**
+ * One contributor's own overrides, with the identity of every declared view it lists or names as a
+ * key registered. Listing a declared view is what puts its identity on the graph; an application
+ * lists overrides alone, so a declaration in its list is the same fault as any other value.
+ */
+declare function buildViews(subject: ViewSubject, declared: unknown, identities: ViewIdentities): ViewContributions;
+/**
+ * The view function one declared view resolves to: the first contributor that overrides it, then
+ * its own default. A bare view is never overridden, so it resolves to its own function.
+ */
+declare function resolveView<Data>(registry: ViewRegistry, value: View<Data>): (data: Data, context: ViewContext) => unknown;
+/** The three functions one sequence writes through: `head`, `row` per item, and `tail`. */
+interface ResolvedRowView<Row> {
+    row: (row: Row, index: number, context: ViewContext) => unknown;
+    head: HeadFunction | undefined;
+    tail: TailFunction | undefined;
+}
+/**
+ * The row functions one row view resolves to, by the walk `resolveView` defines. A replacement
+ * supplies the whole shape, so an override that omits `head` drops the default's `head` with it.
+ */
+declare function resolveRowView<Row>(registry: ViewRegistry, value: RowView<Row>): ResolvedRowView<Row>;
+/**
+ * The report of one failure: the text core writes, and whether a view produced it. An unrendered
+ * report carries core's own text, which the plain fallback path writes beside the diagnostic
+ * naming the view that could not answer.
+ */
+type FailureReport = {
+    kind: 'rendered';
+    text: string;
+} | {
+    kind: 'unrendered';
+    text: string;
+    reason: string;
+};
+/**
+ * The text core writes for one failure. Resolution walks the registry as `resolveFailure` defines
+ * it and falls to core's own default text, which escapes the raw facts it interpolates. A
+ * `FatalError` keeps the authored marked message it was given.
+ */
+declare function describeFailure(registry: ViewRegistry, failure: LoomError, context?: ViewContext): FailureReport;
+export type { AnyDeclaredView, DeclaredRowView, DeclaredView, DeclaredViewBrand, FailureClass, FailureReport, ResolvedRowView, ViewContribution, ViewContributions, ViewIdentities, ViewOverride, ViewRegistry, ViewShape, };
+export { buildViews, describeFailure, override, resolveRowView, resolveView, shapeOf, view, viewIdentities, };