@loomcli/core 0.1.0

package/dist/options.js

@@ -0,0 +1,219 @@
+import { DeclarationError, MissingValueError, RepeatedOptionError, ShortGroupError, UnexpectedValueError, UnknownOptionError, } from './errors.js';
+/** Every parsed value lands in one of these maps; `lists` holds the repeated string options. */
+function emptyValues() {
+    return { booleans: new Map(), lists: new Map(), strings: new Map() };
+}
+function validateDeclaration({ name, config }) {
+    if (typeof name !== 'string') {
+        throw new DeclarationError('Option names must be strings. Supply a string name.');
+    }
+    if (!name || name.startsWith('-') || /[\s=]/u.test(name)) {
+        throw new DeclarationError(`Option name "${name}" is invalid. Use a nonempty name without a leading hyphen, whitespace, or "=".`);
+    }
+    if (!['string', 'boolean'].includes(config.type)) {
+        throw new DeclarationError(`Option "${name}" has an invalid type. Use "string" or "boolean".`);
+    }
+    if (config.short !== undefined &&
+        (typeof config.short !== 'string' || !/^[A-Za-z]$/u.test(config.short))) {
+        throw new DeclarationError(`Option "${name}" requires a short alias of one ASCII letter.`);
+    }
+    if (config.shortOnly !== undefined && typeof config.shortOnly !== 'boolean') {
+        throw new DeclarationError(`Option "${name}" shortOnly must be Boolean. Use true or false.`);
+    }
+    if (config.shortOnly && config.short === undefined) {
+        throw new DeclarationError(`Option "${name}" with shortOnly requires a short alias.`);
+    }
+    if (config.type === 'boolean' && config.multiple !== undefined) {
+        throw new DeclarationError(`Option "${name}" is a boolean option and declares multiple. Remove multiple or declare a string option.`);
+    }
+    if (config.multiple !== undefined && typeof config.multiple !== 'boolean') {
+        throw new DeclarationError(`Option "${name}" multiple must be Boolean. Use true or false.`);
+    }
+    if (config.polarity !== undefined) {
+        if (config.type !== 'boolean') {
+            throw new DeclarationError(`Option "${name}" declares polarity but is not Boolean. Remove polarity or use type "boolean".`);
+        }
+        if (!['positive', 'both', 'negative'].includes(config.polarity)) {
+            throw new DeclarationError(`Option "${name}" has an invalid polarity. Use "positive", "both", or "negative".`);
+        }
+        if (config.polarity === 'both' && config.shortOnly) {
+            throw new DeclarationError(`Option "${name}" cannot express both polarities with shortOnly. Enable long forms or select one polarity.`);
+        }
+    }
+}
+function addSpelling(spellings, spelling, option) {
+    const existing = spellings.get(spelling);
+    if (existing) {
+        throw new DeclarationError(`Option spelling "${spelling}" is used by both "${existing.name}" and "${option.name}". Change one declaration.`);
+    }
+    spellings.set(spelling, option);
+}
+export function compileOptions(declarations, subject) {
+    const spellings = new Map();
+    const names = new Set();
+    for (const { name, config } of declarations) {
+        validateDeclaration({ config, name });
+        if (names.has(name)) {
+            throw new DeclarationError(`Option "${name}" is declared more than once on ${subject}. Remove or rename the duplicate.`);
+        }
+        names.add(name);
+        const positive = config.type === 'string'
+            ? { multiple: config.multiple === true, name, type: 'string' }
+            : { name, type: 'boolean', value: config.polarity !== 'negative' };
+        if (!config.shortOnly) {
+            if (config.type === 'string' || config.polarity !== 'negative') {
+                addSpelling(spellings, `--${name}`, { ...positive, role: 'long' });
+            }
+            if (config.type === 'boolean' &&
+                (config.polarity === 'both' || config.polarity === 'negative')) {
+                addSpelling(spellings, `--no-${name}`, {
+                    name,
+                    role: 'negative',
+                    type: 'boolean',
+                    value: false,
+                });
+            }
+        }
+        if (config.short !== undefined) {
+            addSpelling(spellings, `-${config.short}`, { ...positive, role: 'short' });
+        }
+    }
+    return spellings;
+}
+function lookup(spellings, spelling) {
+    const option = spellings.get(spelling);
+    if (!option) {
+        throw new UnknownOptionError(spelling);
+    }
+    return option;
+}
+function acceptValue({ option, spelling, values, next, inline, }) {
+    const repeatable = option.type === 'string' && option.multiple;
+    if (!repeatable && (values.strings.has(option.name) || values.booleans.has(option.name))) {
+        throw new RepeatedOptionError(spelling);
+    }
+    if (option.type === 'boolean') {
+        if (inline !== undefined) {
+            throw new UnexpectedValueError(spelling, inline);
+        }
+        values.booleans.set(option.name, option.value);
+        return false;
+    }
+    const value = inline ?? next;
+    if (value === undefined || (inline === undefined && value.startsWith('-'))) {
+        throw new MissingValueError(spelling);
+    }
+    if (repeatable) {
+        const collected = values.lists.get(option.name) ?? [];
+        collected.push(value);
+        values.lists.set(option.name, collected);
+    }
+    else {
+        values.strings.set(option.name, value);
+    }
+    return inline === undefined;
+}
+function parseOption(spellings, input, values) {
+    const { token, next } = input;
+    if (token.startsWith('--')) {
+        const equals = token.indexOf('=');
+        const spelling = equals === -1 ? token : token.slice(0, equals);
+        const inline = equals === -1 ? undefined : token.slice(equals + 1);
+        return acceptValue({ inline, next, option: lookup(spellings, spelling), spelling, values });
+    }
+    if (token === '-') {
+        lookup(spellings, token);
+    }
+    for (let index = 1; index < token.length; index += 1) {
+        const spelling = `-${token[index]}`;
+        const option = lookup(spellings, spelling);
+        const suffix = token.slice(index + 1);
+        if (option.type === 'string' && suffix !== '') {
+            throw new ShortGroupError({ reason: 'value-position', token: spelling });
+        }
+        const inline = suffix.startsWith('=') ? suffix.slice(1) : undefined;
+        if (acceptValue({ inline, next, option, spelling, values })) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * A hyphen token belongs to the globals when its long spelling or every short letter does. The
+ * pre-scan reads the globals alone, so a letter it does not own is only "not a global option".
+ */
+function isGlobalToken(spellings, token) {
+    if (token.startsWith('--')) {
+        const equals = token.indexOf('=');
+        return spellings.has(equals === -1 ? token : token.slice(0, equals));
+    }
+    const group = token.slice(1).split('=')[0] ?? '';
+    let global = '';
+    let other = '';
+    for (let index = 0; index < group.length; index += 1) {
+        const letter = group.charAt(index);
+        if (spellings.has(`-${letter}`)) {
+            global = global === '' ? letter : global;
+        }
+        else {
+            other = other === '' ? letter : other;
+        }
+    }
+    if (global === '') {
+        return false;
+    }
+    if (other !== '') {
+        throw new ShortGroupError({ global, other, reason: 'mixed-scope', token });
+    }
+    return true;
+}
+/** Consumes global options anywhere before the passthrough delimiter and leaves the rest routable. */
+export function extractGlobals(spellings, tokens) {
+    const values = emptyValues();
+    const rest = [];
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (token === undefined) {
+            break;
+        }
+        if (token === '--') {
+            rest.push(...tokens.slice(index));
+            return { rest, values };
+        }
+        if (!token.startsWith('-') || !isGlobalToken(spellings, token)) {
+            rest.push(token);
+        }
+        else if (parseOption(spellings, { next: tokens[index + 1], token }, values)) {
+            index += 1;
+        }
+    }
+    return { rest, values };
+}
+/** Global and local keys never overlap, so one merged view feeds a single validation pass. */
+export function mergeValues(globals, locals) {
+    return {
+        booleans: new Map([...globals.booleans, ...locals.booleans]),
+        lists: new Map([...globals.lists, ...locals.lists]),
+        strings: new Map([...globals.strings, ...locals.strings]),
+    };
+}
+export function parseInputs(spellings, tokens) {
+    const options = emptyValues();
+    const positionals = [];
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (token === undefined) {
+            break;
+        }
+        if (token === '--') {
+            return { options, passthrough: tokens.slice(index + 1), positionals };
+        }
+        if (!token.startsWith('-')) {
+            positionals.push(token);
+        }
+        else if (parseOption(spellings, { next: tokens[index + 1], token }, options)) {
+            index += 1;
+        }
+    }
+    return { options, passthrough: [], positionals };
+}

package/dist/output.d.ts

@@ -0,0 +1,52 @@
+import type { Writable } from 'node:stream';
+import type { Host, Out } from './types.js';
+type WriteState = {
+    kind: 'ok';
+} | {
+    kind: 'failed';
+    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';
+export declare class Output {
+    readonly host: Pick<Host, 'stdout' | 'stderr'>;
+    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>;
+    /**
+     * 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.
+     */
+    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.
+     */
+    private rendered;
+    /**
+     * The rejected call. The first renderer 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. */
+    get fault(): {
+        cause: unknown;
+    } | undefined;
+    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
+ * between whatever it is reporting, then passes the one string this writes verbatim. A failed
+ * write ends reporting.
+ */
+export declare function reportPlainly(stderr: Writable, text: string): Promise<void>;
+export {};

package/dist/output.js

@@ -0,0 +1,188 @@
+import { setImmediate } from 'node:timers/promises';
+import { FatalError, notTextReason } from './errors.js';
+class Destination {
+    stream;
+    tail = Promise.resolve();
+    state = { kind: 'ok' };
+    constructor(stream) {
+        this.stream = stream;
+        stream.on('error', this.onError);
+    }
+    onError = (error) => {
+        if (this.state.kind === 'ok') {
+            this.state = { error, kind: 'failed' };
+        }
+    };
+    write(text) {
+        const pending = this.tail.then(() => {
+            if (this.state.kind === 'failed') {
+                throw this.state.error;
+            }
+            return this.writeText(text);
+        });
+        // Keep the returned rejection observable, while accounting for calls without await.
+        this.tail = pending.catch(this.onError);
+        return pending;
+    }
+    writeText(text) {
+        return new Promise((resolve, reject) => {
+            if (this.stream.destroyed || this.stream.writableEnded) {
+                reject(new Error('The output destination is closed.'));
+                return;
+            }
+            const onError = (error) => {
+                cleanup();
+                reject(error);
+            };
+            const onClose = () => {
+                onError(new Error('The output destination closed before writing completed.'));
+            };
+            const cleanup = () => {
+                this.stream.off('error', onError);
+                this.stream.off('close', onClose);
+            };
+            this.stream.on('error', onError);
+            this.stream.on('close', onClose);
+            try {
+                this.stream.write(text, (error) => {
+                    cleanup();
+                    if (error) {
+                        reject(error);
+                    }
+                    else {
+                        resolve();
+                    }
+                });
+            }
+            catch (error) {
+                onError(error);
+            }
+        });
+    }
+    dispose() {
+        this.stream.off('error', this.onError);
+    }
+}
+/** The text a renderer produced, or the value that stands for its failure to produce text. */
+function renderText(produce) {
+    try {
+        const text = produce();
+        return typeof text === 'string' ? { text } : { failed: new Error(notTextReason(text)) };
+    }
+    catch (error) {
+        return { failed: error };
+    }
+}
+export class Output {
+    host;
+    destinations = new Map();
+    renderFault = undefined;
+    out;
+    constructor(host) {
+        this.host = host;
+        this.out = {
+            error: (message) => this.emit('error', message),
+            fatal: (message) => {
+                throw new FatalError(message);
+            },
+            info: (message) => this.emit('info', message),
+            print: (message) => this.emit('print', message),
+            render: (data, renderer) => this.rendered(() => renderer.render(data)),
+            success: (message) => this.emit('success', message),
+            warn: (message) => this.emit('warn', message),
+        };
+    }
+    /** A semantic message is one line on its destination; only `print` writes to stdout. */
+    emit(kind, message) {
+        return this.write(kind === 'print' ? this.host.stdout : this.host.stderr, `${message}\n`);
+    }
+    /**
+     * 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.
+     */
+    report(text) {
+        return this.write(this.host.stderr, text);
+    }
+    /**
+     * 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.
+     */
+    rendered(produce) {
+        const rendered = renderText(produce);
+        return 'text' in rendered
+            ? this.write(this.host.stdout, rendered.text)
+            : this.renderFailed(rendered.failed);
+    }
+    /**
+     * The rejected call. The first renderer 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.
+     */
+    renderFailed(cause) {
+        this.renderFault ??= { cause };
+        const rejection = Promise.reject(cause);
+        void rejection.catch(() => undefined);
+        return rejection;
+    }
+    /** What a renderer failed with during this invocation, if one did. */
+    get fault() {
+        return this.renderFault;
+    }
+    write(stream, text) {
+        let destination = this.destinations.get(stream);
+        if (!destination) {
+            destination = new Destination(stream);
+            this.destinations.set(stream, destination);
+        }
+        return destination.write(text);
+    }
+    async settle() {
+        let drained = false;
+        while (!drained) {
+            const pending = [...this.destinations.values()].map((destination) => ({
+                destination,
+                tail: destination.tail,
+            }));
+            await Promise.all(pending.map(({ tail }) => tail));
+            // Node reports write errors after callbacks. Those callbacks can also enqueue output.
+            await setImmediate();
+            drained =
+                pending.length === this.destinations.size &&
+                    pending.every(({ destination, tail }) => destination.tail === tail);
+        }
+        for (const destination of this.destinations.values()) {
+            if (destination.state.kind === 'failed') {
+                return destination.state;
+            }
+        }
+        return { kind: 'ok' };
+    }
+    dispose() {
+        for (const destination of this.destinations.values()) {
+            destination.dispose();
+        }
+    }
+}
+/**
+ * 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
+ * between whatever it is reporting, then passes the one string this writes verbatim. A failed
+ * write ends reporting.
+ */
+export async function reportPlainly(stderr, text) {
+    try {
+        const destination = new Destination(stderr);
+        try {
+            await destination.write(text);
+        }
+        finally {
+            await setImmediate();
+            destination.dispose();
+        }
+    }
+    catch {
+        // A failed fallback ends reporting; it never re-enters rendering.
+    }
+}