@loomcli/core 0.4.0 → 0.6.0

package/dist/errors.js

@@ -1,3 +1,8 @@
+import { escapeControlCharacters } from './controls.js';
+import { diagnosticText, isDiagnosticRule, valueCode } from './diagnostic-text.js';
+import { isFailureExitCode } from './exit-codes.js';
+import { failureExitCode, foreignThrow, foreignThrowCorrection, resultContract, unconstructedFailure, } from './rules.js';
+import { ignoreRejection, isThenable } from './thenable.js';
 /** The same subject at the start of a sentence, where a token fault names its Command. */
 function routedSentence(command) {
     const subject = routedSubject(command);
@@ -14,36 +19,85 @@ function resultMessage(kind, command) {
     if (kind === 'undeclared') {
         return `${routedSentence(command)} declares no result. Declare one with result() or rows() before action().`;
     }
-    return `A middleware called out.results() on ${routedSubject(command)}. Only the action emits a result.`;
+    const caller = kind === 'source' ? 'A configuration source' : 'A middleware';
+    return `${caller} called out.results() on ${routedSubject(command)}. Only the action emits a result.`;
 }
 /**
- * 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.
+ * A value a sentence quotes: raw text an operator typed, or a name or identity an author declared.
+ * Text is escaped, so a control character or a bidirectional control in it cannot reorder or break
+ * the line. A value of any other kind prints as the code a finding prints for it, because a rule
+ * that rejects a value that is not a string quotes that value too. The failure's public field
+ * keeps the raw value.
  */
-function offering(candidates) {
-    return candidates.length === 0 ? '' : ` Use one of: ${candidates.join(', ')}.`;
+export function quoted(value) {
+    return typeof value === 'string' ? `"${escapeControlCharacters(value)}"` : valueCode(value);
+}
+/**
+ * The clause that states a routing fault's fix: the candidates, or, when the Command offers none
+ * because every child is hidden or deprecated, the kind of name to supply.
+ */
+function offering(candidates, kind) {
+    return candidates.length === 0
+        ? ` Supply the name of a declared ${kind}.`
+        : ` Use one of: ${candidates.join(', ')}.`;
+}
+/**
+ * The sentence for a group routed without a subcommand. The root has no name to repeat, and the
+ * default text already opens with the application name, so the root's sentence names no Command.
+ */
+function nonCallableMessage(command, candidates) {
+    return command.length === 0
+        ? `A command is required.${offering(candidates, 'command')}`
+        : `${routedSentence(command)} requires a subcommand.${offering(candidates, 'subcommand')}`;
 }
 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.`
-        : `Short group "${fault.token}" mixes the global option "-${fault.global}" with "-${fault.other}", which is not a global option. Supply global options as separate tokens, and local options after their command name.`;
+        ? `Value option ${quoted(fault.token)} must be last in its short group. Supply its value in the next token.`
+        : `A short group mixes the global option ${quoted(`-${fault.global}`)} with ${quoted(`-${fault.other}`)}, which is not a global option. Supply global options as separate tokens, and local options after their command name.`;
+}
+/**
+ * The sentence for a class whose declared code no failure may exit with. The class is named by its
+ * constructor, because the subclass has not yet set the instance's `name`.
+ */
+function undeclarableSentence(className, declared) {
+    const clause = typeof declared === 'number' && Number.isFinite(declared)
+        ? `declares exit code ${String(declared)}.`
+        : 'declares an exit code that is not a finite number.';
+    return `Failure class ${quoted(className)} ${clause}`;
+}
+/**
+ * The one message a distributed build shows an operator for a defect or a declaration fault: the
+ * application name and a fixed phrase, with no reason, class name, code, or path.
+ */
+export function genericDefectText(application) {
+    return `${application}: Something went wrong.\n`;
 }
 /**
- * Core's own text for one failure: its message under the category prefix its class carries, with
- * the trailing newline every view's text carries. The four categories are disjoint branches of the
- * hierarchy, so one ordered test reads every class, and a class without a prefix of its own writes
- * the sentence alone. It is the default view of every failure class and the text the plain
- * fallback path writes, so it runs no application code and nothing downstream composes its newline.
+ * Whether one failure is only the author's to fix: a declaration fault or a defect. A development
+ * build shows the author its Developer Diagnostic; a distributed one shows the generic message.
  */
-export function defaultText(failure) {
+export function isAuthorFault(failure) {
+    return failure instanceof DeclarationError || failure instanceof InternalError;
+}
+/**
+ * Core's own text for one failure, with the trailing newline every view's text carries. The
+ * application name opens every line of a usage failure's message, one line for each problem it
+ * reports, so the operator reads who is speaking on each. A declaration fault and a defect read
+ * the generic defect message, because only the author can act on their detail, and a development
+ * build shows that detail ahead of every view. Every other class writes its message alone, even
+ * one that declares a usage error's exit code. It is the default view of every failure class and
+ * the text the plain fallback path writes, so it runs no application code and nothing downstream
+ * composes its newline.
+ */
+export function defaultText(failure, application) {
     if (failure instanceof UsageError) {
-        return `Invalid input: ${failure.message}\n`;
-    }
-    if (failure instanceof DeclarationError) {
-        return `Invalid declaration: ${failure.message}\n`;
+        return failure.message
+            .split('\n')
+            .map((line) => `${application}: ${line}\n`)
+            .join('');
     }
-    if (failure instanceof InternalError) {
-        return `Internal error: ${failure.message}\n`;
+    if (isAuthorFault(failure)) {
+        return genericDefectText(application);
     }
     return `${failure.message}\n`;
 }
@@ -61,32 +115,90 @@ export function commandSentence(name) {
     const subject = commandSubject(name);
     return `${subject.slice(0, 1).toUpperCase()}${subject.slice(1)}`;
 }
+/**
+ * Each failure class's code, captured at the first construction of the class or of a subclass that
+ * declares none, so a static changed afterward cannot give one class a second code. Core's own
+ * classes are captured when this module loads, so no write to their statics reaches a failure.
+ */
+const classCodes = new WeakMap();
+/** Each constructed failure's code, which its `exitCode` reports and `run()` resolves. */
+const failureCodes = new WeakMap();
+/**
+ * The code one class exits with: the code captured for it, or else its own static when it declares
+ * one, or else its parent's. `constructed` names the class the diagnostic reports, the one the
+ * failing construction named.
+ */
+function classCode(target, constructed) {
+    const captured = classCodes.get(target);
+    if (captured !== undefined) {
+        return captured;
+    }
+    const parent = Reflect.getPrototypeOf(target);
+    const declared = Object.hasOwn(target, 'exitCode') || parent === null
+        ? Reflect.get(target, 'exitCode')
+        : classCode(parent, constructed);
+    if (!isFailureExitCode(declared)) {
+        // A class declaration is no call, so no finding stands for it.
+        throw new DeclarationError(failureExitCode, {
+            correction: 'Declare a whole number from 1 through 125.',
+            sentence: undeclarableSentence(constructed.name, declared),
+        });
+    }
+    classCodes.set(target, declared);
+    return declared;
+}
+/**
+ * The code a failure exits with. A value that inherits from a failure class without having been
+ * constructed holds none, and `toFailure` reports it as an internal error, so it reads 1.
+ */
+export function exitCodeOf(failure) {
+    return failureCodes.get(failure) ?? 1;
+}
 /**
  * Every failure `run()` reports is an instance of a public class. Each class carries the facts its
- * sentence interpolates, so a view reads them instead of parsing prose, and the exit status is
- * a field of the base, so a subclass inherits it. `message` never carries a category prefix; the
- * default views add it.
+ * sentence interpolates, so a view reads them instead of parsing prose. The exit code is a static
+ * field the class declares, read from the nearest ancestor that declares one and captured at the
+ * class's first construction, so one class exits with one code and a projection reads it without
+ * an instance. The instance reports the same value through a read-only accessor, and no subclass
+ * property or assignment changes the code `run()` resolves. `message` never carries a category
+ * prefix; the default views add it.
  */
 export class LoomError extends Error {
-    exitCode;
-    constructor(message, exitCode) {
-        super(message);
-        this.exitCode = exitCode;
+    static exitCode = 1;
+    /**
+     * Reads the constructed class's code, captured at its first construction. A code outside 1
+     * through 125 throws a `DeclarationError` in place of the failure and captures nothing, because
+     * core never clamps or replaces a code. `options` is the platform's own, so a failure that
+     * replaces another error keeps it as `cause` only when its author passes one.
+     */
+    constructor(message, options) {
+        const code = classCode(new.target, new.target);
+        super(message, options);
+        failureCodes.set(this, code);
         this.name = 'LoomError';
     }
+    /**
+     * The code this failure exits with. An accessor without a setter, so a TypeScript subclass cannot
+     * declare it as a property, and an assignment throws in strict mode code and is ignored in sloppy
+     * mode code.
+     */
+    get exitCode() {
+        return exitCodeOf(this);
+    }
 }
 /** Exit 2: the invocation, not the application, is wrong. */
 export class UsageError extends LoomError {
-    constructor(message) {
-        super(message, 2);
+    static exitCode = 2;
+    constructor(message, options) {
+        super(message, options);
         this.name = 'UsageError';
     }
 }
 /** The whole validation phase in authoring order, so one failure reports every rejected input. */
 export class InputError extends UsageError {
     problems;
-    constructor(message, problems) {
-        super(message);
+    constructor(message, problems, options) {
+        super(message, options);
         this.name = 'InputError';
         this.problems = problems;
     }
@@ -95,7 +207,7 @@ export class UnknownCommandError extends UsageError {
     token;
     candidates;
     constructor(token, candidates) {
-        super(`Unknown command "${token}".${offering(candidates)}`);
+        super(`Unknown command ${quoted(token)}.${offering(candidates, 'command')}`);
         this.candidates = candidates;
         this.name = 'UnknownCommandError';
         this.token = token;
@@ -106,7 +218,7 @@ export class NonCallableCommandError extends UsageError {
     command;
     candidates;
     constructor(command, candidates) {
-        super(`${routedSentence(command)} requires a subcommand.${offering(candidates)}`);
+        super(nonCallableMessage(command, candidates));
         this.candidates = candidates;
         this.command = command;
         this.name = 'NonCallableCommandError';
@@ -129,7 +241,7 @@ export class UnexpectedArgumentError extends UsageError {
 export class UnknownOptionError extends UsageError {
     spelling;
     constructor(spelling) {
-        super(`Unknown option "${spelling}". Supply a declared option; prefix a hyphenated path with "./".`);
+        super(`Unknown option ${quoted(spelling)}. Supply a declared option; prefix a hyphenated path with "./".`);
         this.name = 'UnknownOptionError';
         this.spelling = spelling;
     }
@@ -137,7 +249,7 @@ export class UnknownOptionError extends UsageError {
 export class MissingValueError extends UsageError {
     spelling;
     constructor(spelling) {
-        super(`Option "${spelling}" requires a value. Supply a value after "${spelling}".`);
+        super(`Option ${quoted(spelling)} requires a value. Supply a value after ${quoted(spelling)}.`);
         this.name = 'MissingValueError';
         this.spelling = spelling;
     }
@@ -147,7 +259,7 @@ export class UnexpectedValueError extends UsageError {
     spelling;
     value;
     constructor(spelling, value) {
-        super(`Boolean option "${spelling}" does not accept a value. Supply the flag alone.`);
+        super(`Boolean option ${quoted(spelling)} does not accept a value. Supply the flag alone.`);
         this.name = 'UnexpectedValueError';
         this.spelling = spelling;
         this.value = value;
@@ -156,7 +268,7 @@ export class UnexpectedValueError extends UsageError {
 export class RepeatedOptionError extends UsageError {
     spelling;
     constructor(spelling) {
-        super(`Option "${spelling}" can be supplied only once. Remove the repeated option.`);
+        super(`Option ${quoted(spelling)} can be supplied only once. Remove the repeated option.`);
         this.name = 'RepeatedOptionError';
         this.spelling = spelling;
     }
@@ -171,27 +283,105 @@ export class ShortGroupError extends UsageError {
         this.token = fault.token;
     }
 }
-/** Exit 1: the declaration is wrong, so the author reads the diagnostic. */
+/** The platform's error options one value carries, read without trusting its shape. */
+function errorOptions(value) {
+    return typeof value === 'object' && value !== null && 'cause' in value
+        ? { cause: value.cause }
+        : undefined;
+}
+/** A correction as a caller supplied it: one sentence, a copied list of them, or none. */
+function readCorrection(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    return Array.isArray(value)
+        ? Object.freeze(value.filter((fix) => typeof fix === 'string'))
+        : undefined;
+}
+/** The findings a caller supplied, copied into a frozen list, or none for a value that holds none. */
+function readFindings(value) {
+    return Object.freeze(Array.isArray(value) ? value.filter(isFinding) : []);
+}
+/** Whether one value is a finding a diagnostic can print: an object naming its call and arguments. */
+function isFinding(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'call' in value &&
+        typeof value.call === 'string' &&
+        'arguments' in value &&
+        Array.isArray(value.arguments));
+}
+function faultParts(first, second, third) {
+    if (!isDiagnosticRule(first)) {
+        return {
+            correction: undefined,
+            findings: Object.freeze([]),
+            options: errorOptions(second),
+            rule: undefined,
+            sentence: String(first),
+        };
+    }
+    const parts = typeof second === 'object' && second !== null ? { ...second } : {};
+    return {
+        correction: readCorrection(parts.correction),
+        findings: readFindings(parts.findings),
+        options: errorOptions(third),
+        rule: first,
+        sentence: String(parts.sentence),
+    };
+}
+/**
+ * Exit 1: the declaration is wrong, so the author reads its Developer Diagnostic. A rule and the
+ * fault's own parts build it, or a sentence alone does for a fault with no rule. `message` holds
+ * the whole diagnostic as plain text at 80 columns, so a fault thrown at an authoring call prints
+ * it through the runtime's own uncaught-error output, and `sentence` holds the sentence alone.
+ */
 export class DeclarationError extends LoomError {
-    constructor(message) {
-        super(message, 1);
+    rule;
+    sentence;
+    findings;
+    correction;
+    constructor(first, second, third) {
+        const parts = faultParts(first, second, third);
+        super(diagnosticText({ ...parts, evidence: [], fallback: 'INVALID DECLARATION' }), parts.options);
         this.name = 'DeclarationError';
+        this.rule = parts.rule;
+        this.sentence = parts.sentence;
+        this.findings = parts.findings;
+        this.correction = parts.correction;
     }
 }
-/** Exit 1: the application ended the invocation itself. An application may subclass it. */
+/**
+ * Exit 1: the application ended the invocation itself. An application may subclass it, and the
+ * subclass may declare its own exit code.
+ */
 export class FatalError extends LoomError {
-    constructor(message) {
-        super(message, 1);
+    constructor(message, options) {
+        super(message, options);
         this.name = 'FatalError';
     }
 }
-/** Exit 1: an unexpected exception, a non-error throw, or a view that could not answer. */
+/**
+ * Exit 1: a defect, such as an unexpected exception, a non-error throw, or a view that could not
+ * answer. A rule and the defect's own parts build it, or a sentence and the thrown value do for a
+ * defect with no rule. `message` stays the sentence, because only `run()` reports a defect, and a
+ * development build renders its Developer Diagnostic from the parts.
+ */
 export class InternalError extends LoomError {
     cause;
-    constructor(message, cause) {
-        super(message, 1);
-        this.cause = cause;
+    rule;
+    sentence;
+    correction;
+    constructor(first, 
+    // The rule form's parts or the sentence form's thrown value, read by shape below.
+    second) {
+        const parts = faultParts(first, second, undefined);
+        super(parts.sentence);
+        this.cause = parts.rule === undefined ? second : errorOptions(second)?.cause;
         this.name = 'InternalError';
+        this.rule = parts.rule;
+        this.sentence = parts.sentence;
+        this.correction = parts.correction;
     }
 }
 /**
@@ -204,26 +394,115 @@ export class ResultError extends InternalError {
     path;
     kind;
     constructor(kind, path) {
-        super(resultMessage(kind, path), undefined);
+        super(resultContract, { cause: undefined, sentence: resultMessage(kind, path) });
         this.kind = kind;
         this.name = 'ResultError';
         this.path = path;
     }
 }
-/** What a diagnostic says about an unexpected value, whether or not it was an Error. */
+/**
+ * One message someone else wrote, as a sentence of its own. A schema or a plugin writes its message
+ * with or without a full stop, so a diagnostic supplies one only where the message carries none.
+ */
+export function asSentence(text) {
+    return text.endsWith('.') ? text : `${text}.`;
+}
+/**
+ * What a diagnostic says about an unexpected value, whether or not it was an Error, with every
+ * control character escaped. A `DeclarationError` answers its sentence, because its message holds
+ * its whole diagnostic. Every sentence that quotes a thrown value reads it here, so a reason stays
+ * on one line and no bidirectional control reaches a terminal, whichever rule's sentence carries
+ * it, while the author's words around it keep their line breaks. Reading it never throws: an Error
+ * whose message is not a string or cannot be read, and a value whose prototype cannot be read, such
+ * as a proxy whose trap throws, answer one fixed sentence.
+ */
 export function reasonOf(thrown) {
-    return thrown instanceof Error ? thrown.message : 'An unknown error occurred.';
+    return escapeControlCharacters(rawReasonOf(thrown));
+}
+/** The thrown value's reason as it was written, read without throwing. */
+function rawReasonOf(thrown) {
+    const unreadableReason = 'The thrown value has no readable message.';
+    try {
+        if (!(thrown instanceof Error)) {
+            return 'An unknown error occurred.';
+        }
+        if (thrown instanceof DeclarationError) {
+            return thrown.sentence;
+        }
+        const { message } = thrown;
+        return typeof message === 'string' ? message : unreadableReason;
+    }
+    catch {
+        return unreadableReason;
+    }
 }
 /**
  * Why a returned value is not the text a view owes. A view is synchronous, so a returned promise is
- * a non-string return like any other, and its rejection is adopted and swallowed here: an
- * unobserved rejection would end the process before the invocation could report anything.
+ * a non-string return like any other: it receives a rejection handler and is otherwise ignored.
  */
 export function notTextReason(value) {
-    void Promise.resolve(value).catch(() => undefined);
+    if (isThenable(value)) {
+        ignoreRejection(value);
+    }
     return `The view returned ${typeof value} instead of a string.`;
 }
-/** Every thrown value reaches reporting as a failure class; anything else is internal. */
+/**
+ * Whether a thrown value is a failure class by its prototype chain, read defensively, because a
+ * revoked proxy or a proxy whose prototype trap throws answers no chain. Such a value is foreign.
+ */
+function isLoomError(thrown) {
+    try {
+        return thrown instanceof LoomError;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Every thrown value reaches reporting as a failure class; anything else is internal. A value that
+ * inherits from a failure class without having been constructed holds no code, so it is internal
+ * too.
+ */
 export function toFailure(thrown) {
-    return thrown instanceof LoomError ? thrown : new InternalError(reasonOf(thrown), thrown);
+    if (!isLoomError(thrown)) {
+        return foreignFailure(thrown);
+    }
+    return failureCodes.has(thrown)
+        ? thrown
+        : new InternalError(unconstructedFailure, {
+            cause: thrown,
+            correction: 'Construct the failure with new before throwing it.',
+            sentence: 'A thrown value inherits from a failure class but was never constructed as one.',
+        });
+}
+/**
+ * The defect a foreign throw reports: its reason as the sentence, and the thrown value as the
+ * cause a development build's diagnostic shows.
+ */
+export function foreignFailure(thrown) {
+    return new InternalError(foreignThrow, {
+        cause: thrown,
+        correction: foreignThrowCorrection,
+        sentence: reasonOf(thrown),
+    });
+}
+// Core's own classes are captured now, before any application code can write their statics.
+for (const Class of [
+    LoomError,
+    UsageError,
+    InputError,
+    UnknownCommandError,
+    NonCallableCommandError,
+    UnexpectedArgumentError,
+    UnknownOptionError,
+    MissingValueError,
+    UnexpectedValueError,
+    RepeatedOptionError,
+    ShortGroupError,
+    DeclarationError,
+    FatalError,
+    InternalError,
+    ResultError,
+]) {
+    classCodes.set(Class, Class.exitCode);
 }

package/dist/exit-codes.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The first code no failure class may declare. 126 and 127 belong to the shell, and 128 plus a
+ * signal number reports a signal, which covers 130 and 143.
+ */
+declare const firstReserved = 126;
+/** Every whole number below `Bound`, counted up from 0, as one union of literal types. */
+type WholeNumbersBelow<Bound extends number, Counted extends number[] = []> = Counted['length'] extends Bound ? Counted[number] : WholeNumbersBelow<Bound, [...Counted, Counted['length']]>;
+/** The codes a failure class may declare, 1 through 125. 0 is success, and the rest are reserved. */
+export type FailureExitCode = Exclude<WholeNumbersBelow<typeof firstReserved>, 0>;
+/**
+ * Whether one declared value is a code a failure class may exit with. A JavaScript class, or one
+ * that escaped the type check, may declare any value at all, so the check reads it as unknown.
+ */
+export declare function isFailureExitCode(value: unknown): value is FailureExitCode;
+/** The command was used incorrectly. */
+export declare const EX_USAGE = 64;
+/** The input data was incorrect. */
+export declare const EX_DATAERR = 65;
+/** An input file did not exist or could not be read. */
+export declare const EX_NOINPUT = 66;
+/** An addressee is unknown. */
+export declare const EX_NOUSER = 67;
+/** A host name is unknown. */
+export declare const EX_NOHOST = 68;
+/** A service is unavailable. */
+export declare const EX_UNAVAILABLE = 69;
+/** An internal software error. */
+export declare const EX_SOFTWARE = 70;
+/** An operating system error. */
+export declare const EX_OSERR = 71;
+/** A system file is missing or malformed. */
+export declare const EX_OSFILE = 72;
+/** An output file cannot be created. */
+export declare const EX_CANTCREAT = 73;
+/** An input or output error. */
+export declare const EX_IOERR = 74;
+/** A temporary failure; a retry may succeed. */
+export declare const EX_TEMPFAIL = 75;
+/** A remote system broke the protocol. */
+export declare const EX_PROTOCOL = 76;
+/** Permission is insufficient. */
+export declare const EX_NOPERM = 77;
+/** The configuration is wrong. */
+export declare const EX_CONFIG = 78;
+export {};

package/dist/exit-codes.js

@@ -0,0 +1,46 @@
+/**
+ * The first code no failure class may declare. 126 and 127 belong to the shell, and 128 plus a
+ * signal number reports a signal, which covers 130 and 143.
+ */
+const firstReserved = 126;
+/**
+ * Whether one declared value is a code a failure class may exit with. A JavaScript class, or one
+ * that escaped the type check, may declare any value at all, so the check reads it as unknown.
+ */
+export function isFailureExitCode(value) {
+    return (typeof value === 'number' && Number.isInteger(value) && value >= 1 && value < firstReserved);
+}
+// The failure codes BSD's `sysexits.h` names, as flat constants with literal types.
+// A failure class declares one by name: `static override readonly exitCode = EX_UNAVAILABLE;`.
+// `EX_OK` is not here, because no failure declares 0.
+// Core raises invalid input as 2 and never raises `EX_USAGE`.
+/** The command was used incorrectly. */
+export const EX_USAGE = 64;
+/** The input data was incorrect. */
+export const EX_DATAERR = 65;
+/** An input file did not exist or could not be read. */
+export const EX_NOINPUT = 66;
+/** An addressee is unknown. */
+export const EX_NOUSER = 67;
+/** A host name is unknown. */
+export const EX_NOHOST = 68;
+/** A service is unavailable. */
+export const EX_UNAVAILABLE = 69;
+/** An internal software error. */
+export const EX_SOFTWARE = 70;
+/** An operating system error. */
+export const EX_OSERR = 71;
+/** A system file is missing or malformed. */
+export const EX_OSFILE = 72;
+/** An output file cannot be created. */
+export const EX_CANTCREAT = 73;
+/** An input or output error. */
+export const EX_IOERR = 74;
+/** A temporary failure; a retry may succeed. */
+export const EX_TEMPFAIL = 75;
+/** A remote system broke the protocol. */
+export const EX_PROTOCOL = 76;
+/** Permission is insufficient. */
+export const EX_NOPERM = 77;
+/** The configuration is wrong. */
+export const EX_CONFIG = 78;