@loomcli/core 0.2.0 → 0.3.0

package/dist/inspect.js

@@ -17,11 +17,13 @@ function spellingsOf(table, name) {
     return spellings;
 }
 /**
- * A snapshot of one declared value. Arrays and plain objects are copied and frozen to any depth, so
- * a consumer cannot reach the declaration through the graph, and a later call reports the declared
- * value again. Primitives and library objects are reported as they are.
+ * A snapshot of one value. Arrays and plain objects are copied and frozen to any depth, so a
+ * consumer cannot reach the source through the copy, and a later call reports the value again.
+ * Primitives and library objects, such as a class instance or a `Date` a schema produced, are
+ * reported as they are, because core cannot copy them meaningfully. The graph reads it for a
+ * declared value and the chain reads it for the request one middleware holds.
  */
-function snapshot(value) {
+export function snapshot(value) {
     if (Array.isArray(value)) {
         return Object.freeze(value.map((entry) => snapshot(entry)));
     }
@@ -111,9 +113,21 @@ function commandNode(command, place) {
         name: command.name,
         options: Object.freeze(optionNodes(command.inputs, { records, scope: 'application', table: command.options })),
         path,
+        result: resultNode(command.result),
     };
     return Object.freeze(node);
 }
+/** The declared result as plain data, or `null` on a Command that declares none. */
+function resultNode(result) {
+    if (!result) {
+        return null;
+    }
+    return Object.freeze({
+        default: result.default,
+        kind: result.kind,
+        views: Object.freeze([...result.views.keys()]),
+    });
+}
 /**
  * Renders one built graph as frozen plain data. Nothing here reads a host fact or a schema. The
  * globals list holds the application's own options, then each installed plugin's in installation
@@ -138,4 +152,4 @@ function inspectGraph(name, graph, facts) {
     };
     return Object.freeze(inspected);
 }
-export { inspectGraph };
+export { inspectGraph, resultNode };

package/dist/lanes.d.ts

@@ -0,0 +1,26 @@
+import type { AnyDeclaredView, DeclaredView } from './view.js';
+/** The five semantic methods, each with the glyph and the style token its lane carries. */
+type Lane = 'error' | 'info' | 'print' | 'success' | 'warn';
+/**
+ * The five lane views core declares, one per semantic method. An application replaces the function
+ * of any of them through `views`, and the replacement owns the gutter the default supplies.
+ */
+declare const lanes: Readonly<Record<Lane, DeclaredView<string>>>;
+/**
+ * What one sequence that stopped early reports: the Command it belongs to, the rows its source
+ * produced before the stop, and the rows core wrote. `head` is no row, so it is not counted.
+ */
+interface IncompleteResult {
+    path: readonly string[];
+    yielded: number;
+    written: number;
+}
+/**
+ * The line a sequence writes on stderr when it stopped before its end, so an empty result and a
+ * truncated one never read alike. An override that returns the empty string silences it.
+ */
+declare const incompleteResult: DeclaredView<IncompleteResult>;
+/** Every view core declares, so one build register holds their identities from the start. */
+declare const coreViews: readonly AnyDeclaredView[];
+export type { IncompleteResult, Lane };
+export { coreViews, incompleteResult, lanes };

package/dist/lanes.js

@@ -0,0 +1,45 @@
+import { routedSubject } from './errors.js';
+import { glyph } from './glyphs.generated.js';
+import { view } from './view.js';
+/**
+ * The identity prefix core's own views take, the package name by the plugin-identity convention.
+ * Core compiles from `src` alone, so the name is spelled here rather than read from the manifest.
+ */
+const core = '@loomcli/core';
+/**
+ * The default function of a marked lane: the matching glyph and one space before the first line,
+ * and continuation lines indented by the measured gutter without repeating the glyph. The
+ * semantic method appends the newline, so the view returns none.
+ */
+function marked(mark) {
+    return (message, context) => {
+        const glyphText = glyph[mark];
+        const gutter = ' '.repeat(context.width(glyphText) + 1);
+        return `${context.style[mark](glyphText)} ${message.replace(/(?<newline>\r?\n)(?!$)/gu, `$<newline>${gutter}`)}`;
+    };
+}
+/** One lane view over the original message string, line breaks and authored styles included. */
+function lane(name, render) {
+    return view(`${core}/lanes/${name}`, { render });
+}
+/**
+ * The five lane views core declares, one per semantic method. An application replaces the function
+ * of any of them through `views`, and the replacement owns the gutter the default supplies.
+ */
+const lanes = {
+    error: lane('error', marked('error')),
+    info: lane('info', marked('info')),
+    print: lane('print', (message) => message),
+    success: lane('success', marked('success')),
+    warn: lane('warn', marked('warning')),
+};
+/**
+ * The line a sequence writes on stderr when it stopped before its end, so an empty result and a
+ * truncated one never read alike. An override that returns the empty string silences it.
+ */
+const incompleteResult = view(`${core}/results/incomplete`, {
+    render: ({ path, written, yielded }) => `Output is incomplete: ${routedSubject(path)} stopped after ${yielded} rows, ${written} written.\n`,
+});
+/** Every view core declares, so one build register holds their identities from the start. */
+const coreViews = [...Object.values(lanes), incompleteResult];
+export { coreViews, incompleteResult, lanes };

package/dist/output.d.ts

@@ -1,5 +1,9 @@
 import type { Writable } from 'node:stream';
-import type { Host, Out } from './types.js';
+import type { Lane } from './lanes.js';
+import type { RenderingPolicy } from './rendering.js';
+import type { Palette } from './style-state.js';
+import type { ActionChannel, Host, OpenResult, Out, ResultBinding, ViewContext } from './types.js';
+import type { ViewRegistry } from './view.js';
 type WriteState = {
     kind: 'ok';
 } | {
@@ -7,44 +11,118 @@ type WriteState = {
     error: unknown;
 };
 /** The semantic calls, which choose a destination. A rendered value has no purpose of its own. */
-type Purpose = 'print' | 'info' | 'success' | 'warn' | 'error';
+type Purpose = Lane;
+/** The two streams every write site names. */
+type Stream = 'stdout' | 'stderr';
 export declare class Output {
-    readonly host: Pick<Host, 'stdout' | 'stderr'>;
+    readonly host: Host;
+    private readonly signal;
     private readonly destinations;
     private renderFault;
-    readonly out: Out;
-    constructor(host: Pick<Host, 'stdout' | 'stderr'>);
-    /** A semantic message is one line on its destination; only `print` writes to stdout. */
-    emit(kind: Purpose, message: string): Promise<void>;
+    private readonly stops;
+    private route;
+    /**
+     * The channel every caller writes through. It is typed with the result left open, because the
+     * declaration a call answers to is checked where the action was authored.
+     */
+    readonly out: Out<OpenResult>;
+    private palette;
+    private policy;
+    private registry;
+    style: import("./style.js").ContextualStyle;
+    constructor(host: Host, signal: AbortSignal);
+    /**
+     * The channel one action receives. On a Command that declares a result nothing the action writes
+     * but the result reaches stdout: `print` and `render` move to stderr, and they move the view
+     * context with the destination, so capability detection follows the stream the bytes reach. The
+     * destination is decided here, from the declaration, and never from the view a run selected.
+     */
+    channel(binding: ResultBinding): ActionChannel;
+    /**
+     * One `out.results` call on the action's channel. The declaration decides the unit, the selected
+     * view decides how it renders, and stdout carries the result under either one. The selected
+     * view is the one a middleware named before the action dispatched, or the declaration's default
+     * when none did. A call the declaration does not answer for is a fault of the lane and writes
+     * nothing.
+     */
+    private results;
+    /**
+     * One fault of the results lane: the call rejects, and the same failure is reported after this
+     * invocation's primary outcome, so a call the action never awaited still turns a would-be 0 into
+     * 1 and one the action let propagate is reported once.
+     */
+    private resultFault;
+    /** The registry one invocation resolves through, republished as each contributor is read. */
+    useViews(registry: ViewRegistry): void;
+    /** The routed path, published once routing resolved it, which an incomplete sequence names. */
+    useRoute(path: readonly string[]): void;
+    /** What this invocation's output raised beside its calls, in the order it was raised. */
+    get stopped(): readonly unknown[];
+    configure(policy: RenderingPolicy, palette: Palette): void;
+    context(destination: Stream): ViewContext;
+    /**
+     * A semantic message is one line on its destination; only `print` writes to stdout. The message
+     * is checked before the lane view runs, and this call appends the one newline after it, so a
+     * lane view returns none and an override that returns the empty string still writes one.
+     */
+    emit(kind: Purpose, message: string, destination: Stream): Promise<void>;
     /**
      * The failure report of one invocation. Like `render`, the text is queued on its destination
-     * exactly as given: the caller already carries its own trailing newline, whether that text came
-     * from a registered renderer or from core's own default text.
+     * after style resolution: the caller already carries its own trailing newline, whether that text
+     * came from a resolved view or from core's own default text.
      */
     report(text: string): Promise<void>;
     /**
-     * The renderer owns every byte, so its text is queued on stdout exactly as returned. A throw or
-     * a non-string return rejects this call alone: nothing is written for it, later output still
-     * writes, and the recorded cause ends the invocation once the action has completed.
+     * One `out.render` call, dispatched on the shape of the view it was handed. The two shapes are
+     * exclusive, so a JavaScript author's value that carries both, or neither, is the output-view
+     * fault of this call and nothing is written for it.
+     */
+    private renderValue;
+    /**
+     * The view one sequence writes through, in the shape its own view carries. The caller supplies
+     * the contributors the view resolves through: `out.render`'s call-site view resolves through
+     * this invocation's registry, as ADR-0021 requires, and a result's view resolves through none,
+     * because a result's selected view is replaced by view name alone.
+     */
+    private sequenceView;
+    /**
+     * One sequence, which holds its place on the destination from here until its last piece is
+     * written. The returned rejection is observed here as well, because an action that never awaits
+     * the call must not end the process with an unhandled rejection.
+     */
+    private sequence;
+    /**
+     * The line one incomplete sequence writes on stderr, ahead of the fault's own report. It resolves
+     * through the registry like any other rendered output, so an override that returns the empty
+     * string silences it and one that throws is a view fault. A stderr that has failed already takes
+     * the plain fallback path and no further.
+     */
+    private incomplete;
+    /**
+     * The write site owns its newline; core resolves the view's marked text before queuing it. A
+     * throw or a non-string return rejects this call alone: nothing is written for it, later output
+     * still writes, and the recorded cause ends the invocation once the action has completed.
      */
     private rendered;
     /**
-     * The rejected call. The first renderer failure is the reported one, so a later one adds no
+     * The rejected call. The first view failure is the reported one, so a later one adds no
      * second diagnostic, and the rejection is observed here as well, because an action that never
      * awaits the call must not end the process with an unhandled rejection.
      */
     private renderFailed;
-    /** What a renderer failed with during this invocation, if one did. */
+    /** What a view failed with during this invocation, if one did. */
     get fault(): {
         cause: unknown;
     } | undefined;
+    /** The queue one stream writes through, opened the first time this invocation reaches it. */
+    private destination;
     private write;
     settle(): Promise<WriteState>;
     dispose(): void;
 }
 /**
  * The plain fallback path: a fresh destination on stderr, outside the invocation's queues and
- * outside every registration, so no application code runs on it. The caller composes the newlines
+ * outside every override, so no application code runs on it. The caller composes the newlines
  * between whatever it is reporting, then passes the one string this writes verbatim. A failed
  * write ends reporting.
  */