@loomcli/core 0.5.0 → 0.6.0

package/dist/diagnostic-text.js

@@ -0,0 +1,283 @@
+import { escapeControlCharacters } from './controls.js';
+import { isPlainObject } from './plain.js';
+/** The width a diagnostic takes in a thrown error's message, or when the stderr width is unknown. */
+const messageWidth = 80;
+/** How far a finding's code sits from the left edge. */
+const findingIndent = '    ';
+/** How deep a finding's argument is printed before the rest reads as an ellipsis. */
+const depthLimit = 4;
+/** The stand-in for a value a finding does not spell out: a function, a validator, or a cycle. */
+const elided = '…';
+/** A key an object literal can spell without quotes. */
+const identifierKey = /^[A-Za-z_$][\w$]*$/u;
+/** A string as a single-quoted JavaScript literal, with every control escaped. */
+function quoteString(text) {
+    return `'${escapeControlCharacters(text.replaceAll('\\', String.raw `\\`).replaceAll("'", String.raw `\'`))}'`;
+}
+/**
+ * Stand-ins a finding prints as the code they name, such as `new Command('get')` for the Command
+ * value an attach received, which a finding would otherwise print as an ellipsis.
+ */
+const spellings = new WeakMap();
+/** A finding argument that prints as the code given, which the caller has already escaped. */
+function spelled(code) {
+    const value = Object.freeze({});
+    spellings.set(value, code);
+    return value;
+}
+/** The code a stand-in prints as, or `undefined` for any other value. */
+function spellingOf(value) {
+    return typeof value === 'object' && value !== null ? spellings.get(value) : undefined;
+}
+/** Whether a value is a Standard Schema, which a finding prints as an ellipsis like a function. */
+function isValidator(value) {
+    return '~standard' in value;
+}
+/** A primitive as JavaScript source, or `undefined` for an object or a function. */
+function primitiveCode(value) {
+    switch (typeof value) {
+        case 'string': {
+            return quoteString(value);
+        }
+        case 'number': {
+            return Object.is(value, -0) ? '-0' : String(value);
+        }
+        case 'bigint': {
+            return `${String(value)}n`;
+        }
+        case 'symbol': {
+            return escapeControlCharacters(String(value));
+        }
+        case 'boolean':
+        case 'undefined': {
+            return String(value);
+        }
+        default: {
+            return value === null ? 'null' : undefined;
+        }
+    }
+}
+/** One object key as an object literal spells it. */
+function keyCode(key) {
+    return identifierKey.test(key) ? key : quoteString(key);
+}
+/**
+ * Printed code in progress, and the span each argument path and key covers, which a mark
+ * underlines. Reading a value runs no author code beyond property reads, and a read that throws
+ * prints an ellipsis.
+ */
+class CodePrinter {
+    text;
+    spans = new Map();
+    constructor(text) {
+        this.text = text;
+    }
+    /** Appends one value and records the span it covers under its path. */
+    value(value, place) {
+        const start = this.text.length;
+        try {
+            // Nested members append while the composite is read, so its tail appends after them.
+            const tail = this.composite(value, place);
+            this.text += tail;
+        }
+        catch {
+            this.text = `${this.text.slice(0, start)}${elided}`;
+        }
+        this.spans.set(place.path, { end: this.text.length, start });
+    }
+    /** Appends each item with a comma between, as a list of arguments or members is written. */
+    separated(items, write) {
+        for (const [index, item] of items.entries()) {
+            if (index > 0) {
+                this.text += ', ';
+            }
+            write(item, index);
+        }
+    }
+    /**
+     * The code for one value, appending nested members as it goes and returning what is left to
+     * append. A function, a validator, a class instance, a cycle, and a value deeper than the limit
+     * print an ellipsis.
+     */
+    composite(value, { path, seen }) {
+        const known = primitiveCode(value) ?? spellingOf(value);
+        if (known !== undefined) {
+            return known;
+        }
+        if (typeof value !== 'object' || value === null || seen.has(value) || seen.size >= depthLimit) {
+            return elided;
+        }
+        const inner = { path, seen: new Set([...seen, value]) };
+        if (Array.isArray(value)) {
+            return this.list(value, inner);
+        }
+        return isValidator(value) || !isPlainObject(value) ? elided : this.record(value, inner);
+    }
+    /** One array literal. Its members append in place, so each records its own span. */
+    list(list, { path, seen }) {
+        this.text += '[';
+        // A hole reads as undefined, so the list is copied before it is walked.
+        this.separated([...list], (member, index) => {
+            this.value(member, { path: `${path}.${String(index)}`, seen });
+        });
+        return ']';
+    }
+    /** One object literal. A key's span covers the whole `key: value` pair, which a mark underlines. */
+    record(record, place) {
+        const keys = Object.keys(record);
+        if (keys.length === 0) {
+            return '{}';
+        }
+        this.text += '{ ';
+        this.separated(keys, (key) => {
+            this.member(key, Reflect.get(record, key), place);
+        });
+        return ' }';
+    }
+    /** One `key: value` pair of an object literal. */
+    member(key, value, { path, seen }) {
+        const start = this.text.length;
+        const member = `${path}.${key}`;
+        this.text += `${keyCode(key)}: `;
+        this.value(value, { path: member, seen });
+        this.spans.set(member, { end: this.text.length, start });
+    }
+}
+/** One call with its arguments, and the span each argument and key covers inside the line. */
+function printCall(prefix, finding) {
+    const printer = new CodePrinter(`${prefix}${escapeControlCharacters(finding.call)}(`);
+    const seen = new Set();
+    printer.separated(finding.arguments, (argument, index) => {
+        printer.value(argument, { path: String(index), seen });
+    });
+    printer.text += ')';
+    return printer;
+}
+/** One value as the JavaScript a finding prints for it. */
+function valueCode(value) {
+    const printer = new CodePrinter('');
+    printer.value(value, { path: '', seen: new Set() });
+    return printer.text;
+}
+/** The line of carets under a finding's mark, with its note beside it, or none. */
+function markLine(printed, finding) {
+    const span = finding.mark === undefined ? undefined : printed.spans.get(finding.mark);
+    if (span === undefined) {
+        return [];
+    }
+    const carets = '^'.repeat(Math.max(1, span.end - span.start));
+    const note = finding.note === undefined ? '' : ` ${escapeControlCharacters(finding.note)}`;
+    return [`${' '.repeat(span.start)}${carets}${note}`];
+}
+/**
+ * The receiver a finding's call sits on: the Command its path names, or the Application for the
+ * root, and the comment above it that opens with the path, after the application name when known.
+ */
+function receiverLines(path, application) {
+    const words = application === undefined ? path : [application, ...path];
+    const comment = words.length === 0 ? [] : [`// ${escapeControlCharacters(words.join(' '))}`];
+    const last = path.at(-1);
+    if (last !== undefined) {
+        return [...comment, `new Command(${quoteString(last)})`];
+    }
+    return [
+        ...comment,
+        `new Application(${application === undefined ? elided : quoteString(application)})`,
+    ];
+}
+/** One finding as indented code: the rebuilt call, and the marks under the part at fault. */
+function findingSection(finding, application) {
+    const receiver = finding.path === undefined ? [] : receiverLines(finding.path, application);
+    const printed = printCall(finding.path === undefined ? '' : '  .', finding);
+    return [...receiver, printed.text, ...markLine(printed, finding)]
+        .map((line) => `${findingIndent}${line}`.trimEnd())
+        .join('\n');
+}
+/** Prose wrapped to the width at spaces. A word wider than the width keeps a line of its own. */
+function wrap(text, width) {
+    const lines = [];
+    let line = '';
+    for (const word of text.split(' ')) {
+        if (line !== '' && line.length + 1 + word.length > width) {
+            lines.push(line);
+            line = word;
+        }
+        else {
+            line = line === '' ? word : `${line} ${word}`;
+        }
+    }
+    lines.push(line);
+    return lines.join('\n');
+}
+/**
+ * The sentence with every control escaped. A declaration fault's sentence is written by the author
+ * of a rule, so its line breaks, such as the issue lines under a rejected default, stay breaks; a
+ * defect's sentence can carry a thrown value's reason, so it stays on one line.
+ */
+function sentenceText(anatomy) {
+    return anatomy.fallback === 'DEFECT'
+        ? escapeControlCharacters(anatomy.sentence)
+        : anatomy.sentence.split('\n').map(escapeControlCharacters).join('\n');
+}
+/** The banner: two hyphens, the headline in capitals, a run of hyphens, and the rule's identity. */
+function bannerLine(anatomy, width) {
+    const { rule } = anatomy;
+    const title = rule === undefined ? anatomy.fallback : rule.headline.toUpperCase();
+    const left = `-- ${escapeControlCharacters(title)} `;
+    const right = rule === undefined ? '' : ` ${escapeControlCharacters(rule.identity)}`;
+    const fill = Math.max(2, width - left.length - right.length);
+    return `${left}${'-'.repeat(fill)}${right}`;
+}
+/** The correction: one imperative sentence, or one fix per line when several fit. */
+function correctionSection(correction) {
+    if (correction === undefined) {
+        return [];
+    }
+    if (typeof correction === 'string') {
+        return [escapeControlCharacters(correction)];
+    }
+    return correction.length === 0
+        ? []
+        : [correction.map((fix) => `- ${escapeControlCharacters(fix)}`).join('\n')];
+}
+/**
+ * One Developer Diagnostic as plain text with no trailing newline: the banner, the sentence, the
+ * findings, the explanation, the correction, and the docs link, separated by one blank line, each
+ * left out when the fault does not carry it. The banner is returned apart, so a caller that styles
+ * it can.
+ */
+function diagnosticSections(anatomy, layout) {
+    const { rule } = anatomy;
+    const sections = [
+        sentenceText(anatomy),
+        ...anatomy.findings.map((finding) => findingSection(finding, layout.application)),
+        ...anatomy.evidence,
+        ...(rule === undefined ? [] : [wrap(escapeControlCharacters(rule.explanation), layout.width)]),
+        ...correctionSection(anatomy.correction),
+        ...(rule?.docs === undefined ? [] : [`See ${escapeControlCharacters(rule.docs)}`]),
+    ];
+    return { banner: bannerLine(anatomy, layout.width), body: sections.join('\n\n') };
+}
+/** The whole diagnostic as the plain text a thrown fault's message holds. */
+function diagnosticText(anatomy, layout = { width: messageWidth }) {
+    const { banner, body } = diagnosticSections(anatomy, layout);
+    return `${banner}\n\n${body}`;
+}
+/** Every descriptor built through `registerRule`, so a hand-built object is not a rule. */
+const rules = new WeakSet();
+/** One frozen descriptor from parts already checked, which every site raising it shares. */
+function registerRule(identity, definition) {
+    const rule = Object.freeze({
+        docs: definition.docs,
+        explanation: definition.explanation,
+        headline: definition.headline,
+        identity,
+    });
+    rules.add(rule);
+    return rule;
+}
+/** Whether a value is a descriptor `diagnosticRule()` built. */
+function isDiagnosticRule(value) {
+    return typeof value === 'object' && value !== null && rules.has(value);
+}
+export { diagnosticSections, diagnosticText, elided, isDiagnosticRule, messageWidth, quoteString, registerRule, spelled, valueCode, wrap, };

package/dist/diagnostic.d.ts

@@ -0,0 +1,11 @@
+import type { DiagnosticRule } from './diagnostic-text.js';
+/**
+ * Declares one Developer Diagnostic rule: its identity, the headline its banner prints, the
+ * explanation that says why the rule exists, and an optional docs link. It returns a frozen
+ * descriptor that every site raising the rule shares, as `extension()` and `issueCode()` do.
+ */
+export declare function diagnosticRule(identity: string, definition: {
+    readonly headline: string;
+    readonly explanation: string;
+    readonly docs?: string;
+}): DiagnosticRule;

package/dist/diagnostic.js

@@ -0,0 +1,70 @@
+import { registerRule } from './diagnostic-text.js';
+import { DeclarationError, quoted } from './errors.js';
+import { isRuleIdentity } from './identity.js';
+import { ruleDocs, ruleIdentity, ruleProse } from './rules.js';
+/** Whether a text holds a character other than whitespace. */
+function isFilled(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+/** Whether a docs value is an absolute web address. */
+function isWebAddress(value) {
+    if (!URL.canParse(value)) {
+        return false;
+    }
+    const { protocol } = new URL(value);
+    return protocol === 'https:' || protocol === 'http:';
+}
+/** The definition's own fields, read by shape, because a JavaScript caller reaches the call. */
+function definitionOf(definition) {
+    return typeof definition === 'object' && definition !== null ? { ...definition } : {};
+}
+/** The finding for one `diagnosticRule()` call, marking the argument or key at fault. */
+function callFinding(identity, definition, mark) {
+    return { arguments: [identity, definition], call: 'diagnosticRule', mark };
+}
+/**
+ * The definition's headline, explanation, and docs, checked. A fault marks the key at fault, or the
+ * definition itself when the author left the key out.
+ */
+function checkDefinition(identity, definition) {
+    const fields = definitionOf(definition);
+    const { docs, explanation, headline } = fields;
+    const part = (key) => callFinding(identity, definition, key in fields ? `1.${key}` : '1');
+    if (!isFilled(headline)) {
+        throw new DeclarationError(ruleProse, {
+            correction: 'Supply a short noun phrase.',
+            findings: [part('headline')],
+            sentence: `Diagnostic rule ${quoted(identity)} declares an empty headline.`,
+        });
+    }
+    if (!isFilled(explanation)) {
+        throw new DeclarationError(ruleProse, {
+            correction: 'Supply prose that says why the rule exists.',
+            findings: [part('explanation')],
+            sentence: `Diagnostic rule ${quoted(identity)} declares an empty explanation.`,
+        });
+    }
+    if (docs !== undefined && (typeof docs !== 'string' || !isWebAddress(docs))) {
+        throw new DeclarationError(ruleDocs, {
+            correction: 'Supply an absolute https URL, or omit docs.',
+            findings: [part('docs')],
+            sentence: `Diagnostic rule ${quoted(identity)} declares docs that are not a URL.`,
+        });
+    }
+    return docs === undefined ? { explanation, headline } : { docs, explanation, headline };
+}
+/**
+ * Declares one Developer Diagnostic rule: its identity, the headline its banner prints, the
+ * explanation that says why the rule exists, and an optional docs link. It returns a frozen
+ * descriptor that every site raising the rule shares, as `extension()` and `issueCode()` do.
+ */
+export function diagnosticRule(identity, definition) {
+    if (!isRuleIdentity(identity)) {
+        throw new DeclarationError(ruleIdentity, {
+            correction: 'Name it <package>[/<subpath>...]/<kebab-case-rule>, such as "@acme/retry/retry-limit".',
+            findings: [callFinding(identity, definition, '0')],
+            sentence: `Diagnostic rule ${quoted(identity)} has no package part, or a subpath or rule name that is not kebab-case.`,
+        });
+    }
+    return registerRule(identity, checkDefinition(identity, definition));
+}

package/dist/errors.d.ts

@@ -1,9 +1,19 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { DiagnosticParts, DiagnosticRule, Finding } from './diagnostic-text.js';
+import type { FailureExitCode } from './exit-codes.js';
 import type { InputIdentity } from './types.js';
+/**
+ * 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.
+ */
+export declare function quoted(value: unknown): string;
 /**
  * The two short-group faults. A value option that is not last in its group names that option's
- * spelling; a group that mixes scopes names the whole group and the two letters that disagree.
- * The extra letters shape the sentence alone, so `token` and `reason` are the reported facts.
+ * spelling; a group that mixes scopes names only the two letters that disagree, because the rest
+ * of the group may hold an inline value. `token` keeps the whole group as the reported fact.
  */
 type ShortGroupFault = {
     reason: 'value-position';
@@ -15,32 +25,66 @@ type ShortGroupFault = {
     other: string;
 };
 /**
- * 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.
+ * 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 declare function genericDefectText(application: string): string;
+/**
+ * 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 declare function isAuthorFault(failure: LoomError): failure is DeclarationError | 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 declare function defaultText(failure: LoomError): string;
+export declare function defaultText(failure: LoomError, application: string): string;
 /** How a diagnostic names one Command inside a sentence: by name, or as the unnamed root. */
 export declare function commandSubject(name: string | null): string;
 /** The routed path names the Command a sentence speaks of; an empty path is the root. */
 export declare function routedSubject(command: readonly string[]): string;
 /** The same subject at the start of a sentence. */
 export declare function commandSentence(name: string | null): string;
+/**
+ * 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 declare function exitCodeOf(failure: LoomError): FailureExitCode;
 /**
  * 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 declare abstract class LoomError extends Error {
-    readonly exitCode: 1 | 2;
-    constructor(message: string, exitCode: 1 | 2);
+    static readonly exitCode: FailureExitCode;
+    /**
+     * 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: string, options?: ErrorOptions);
+    /**
+     * 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(): FailureExitCode;
 }
 /** Exit 2: the invocation, not the application, is wrong. */
 export declare abstract class UsageError extends LoomError {
-    constructor(message: string);
+    static readonly exitCode: FailureExitCode;
+    constructor(message: string, options?: ErrorOptions);
 }
 /** One input the validation phase rejected: an omission, or a value its schema refused. */
 export type InputProblem = {
@@ -56,7 +100,7 @@ export type InputProblem = {
 /** The whole validation phase in authoring order, so one failure reports every rejected input. */
 export declare class InputError extends UsageError {
     readonly problems: readonly InputProblem[];
-    constructor(message: string, problems: readonly InputProblem[]);
+    constructor(message: string, problems: readonly InputProblem[], options?: ErrorOptions);
 }
 export declare class UnknownCommandError extends UsageError {
     readonly token: string;
@@ -98,17 +142,41 @@ export declare class ShortGroupError extends UsageError {
     readonly reason: 'value-position' | 'mixed-scope';
     constructor(fault: ShortGroupFault);
 }
-/** Exit 1: the declaration is wrong, so the author reads the diagnostic. */
+/**
+ * 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 declare class DeclarationError extends LoomError {
-    constructor(message: string);
+    readonly rule: DiagnosticRule | undefined;
+    readonly sentence: string;
+    readonly findings: readonly Finding[];
+    readonly correction: string | readonly string[] | undefined;
+    constructor(rule: DiagnosticRule, parts: DiagnosticParts, options?: ErrorOptions);
+    constructor(sentence: string, options?: ErrorOptions);
 }
-/** 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 declare class FatalError extends LoomError {
-    constructor(message: string);
+    constructor(message: string, options?: ErrorOptions);
 }
-/** 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 declare class InternalError extends LoomError {
     readonly cause: unknown;
+    readonly rule: DiagnosticRule | undefined;
+    readonly sentence: string;
+    readonly correction: string | readonly string[] | undefined;
+    constructor(rule: DiagnosticRule, parts: Omit<DiagnosticParts, 'findings'> & {
+        readonly cause: unknown;
+    });
     constructor(message: string, cause: unknown);
 }
 /** The five ways the results lane is broken, each named where core meets it. */
@@ -130,14 +198,30 @@ export declare class ResultError extends InternalError {
  * with or without a full stop, so a diagnostic supplies one only where the message carries none.
  */
 export declare function asSentence(text: string): string;
-/** What a diagnostic says about an unexpected value, whether or not it was an Error. */
+/**
+ * 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 declare function reasonOf(thrown: unknown): string;
 /**
  * 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 declare function notTextReason(value: unknown): string;
-/** Every thrown value reaches reporting as a failure class; anything else is internal. */
+/**
+ * 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 declare function toFailure(thrown: unknown): LoomError;
+/**
+ * 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 declare function foreignFailure(thrown: unknown): InternalError;
 export {};