@loomcli/core 0.5.0 → 0.7.0

package/dist/theme.d.ts

@@ -1,3 +1,7 @@
 import type { Palette } from './style-state.js';
+/**
+ * One plugin's theme, read as the palette core resolves semantic styles through. Each fault marks
+ * the theme, or the one entry at fault, in `plugin(identity, { theme })`.
+ */
 declare function buildTheme(value: unknown, identity: string): Palette;
 export { buildTheme };

package/dist/theme.js

@@ -1,19 +1,39 @@
-import { DeclarationError } from './errors.js';
-import { isPlainObject } from './facts.js';
+import { DeclarationError, quoted } from './errors.js';
+import { partFinding, slotSite } from './facts.js';
+import { isPlainObject } from './plain.js';
+import { themeMapping, themeNameTaken } from './plugin-rules.js';
 import { chains, reservedStyleNames } from './style.js';
+/**
+ * One plugin's theme, read as the palette core resolves semantic styles through. Each fault marks
+ * the theme, or the one entry at fault, in `plugin(identity, { theme })`.
+ */
 function buildTheme(value, identity) {
+    const subject = `Plugin ${quoted(identity)}`;
+    const site = slotSite({ call: 'plugin', named: identity, subject }, 'theme', value);
     if (!isPlainObject(value)) {
-        throw new DeclarationError(`Plugin "${identity}" must declare theme as a mapping of names to concrete style chains.`);
+        throw new DeclarationError(themeMapping, {
+            correction: 'Supply a mapping of names to concrete style chains.',
+            findings: [partFinding(site, [])],
+            sentence: `${subject} declares a theme that is not a mapping.`,
+        });
     }
     const palette = new Map();
     for (const [name, chain] of Object.entries(value)) {
         if (reservedStyleNames.has(name)) {
-            throw new DeclarationError(`Plugin "${identity}" theme name "${name}" shadows a built-in style member.`);
+            throw new DeclarationError(themeNameTaken, {
+                correction: 'Rename the theme entry.',
+                findings: [partFinding(site, [name])],
+                sentence: `${subject} theme name ${quoted(name)} shadows a built-in style member.`,
+            });
         }
         const operations = typeof chain === 'function' ? chains.get(chain) : undefined;
         if (chain !== undefined &&
             (operations === undefined || operations.some((entry) => entry[0] === 'token'))) {
-            throw new DeclarationError(`Plugin "${identity}" theme mapping "${name}" must be an unapplied concrete style chain without semantic tokens.`);
+            throw new DeclarationError(themeMapping, {
+                correction: 'Map the name to a concrete chain such as style.cyan.bold, without calling it or naming a semantic style.',
+                findings: [partFinding(site, [name])],
+                sentence: `${subject} theme mapping ${quoted(name)} is not an unapplied concrete style chain without semantic tokens.`,
+            });
         }
         palette.set(name, operations ?? []);
     }

package/dist/thenable.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Whether one value is a promise or another thenable. A thenable object and a promise from another
+ * realm are as unwaitable to a synchronous caller as a native one, so the test is the contract and
+ * not the class, and a function with a callable `then` counts, as Promises/A+ says. A value whose
+ * `then` cannot be read, such as a proxy whose trap throws, is not a thenable, so the test itself
+ * never throws.
+ */
+export declare function isThenable(value: unknown): value is PromiseLike<unknown>;
+/**
+ * Attaches a rejection handler to a thenable a synchronous function returned, and otherwise
+ * ignores it. An unobserved rejection would end the process before the run could report anything.
+ * The thenable is adopted inside a fresh promise, so a `then` that throws rejects that promise
+ * instead of throwing here.
+ */
+export declare function ignoreRejection(value: PromiseLike<unknown>): void;

package/dist/thenable.js

@@ -0,0 +1,29 @@
+/**
+ * Whether one value is a promise or another thenable. A thenable object and a promise from another
+ * realm are as unwaitable to a synchronous caller as a native one, so the test is the contract and
+ * not the class, and a function with a callable `then` counts, as Promises/A+ says. A value whose
+ * `then` cannot be read, such as a proxy whose trap throws, is not a thenable, so the test itself
+ * never throws.
+ */
+export function isThenable(value) {
+    try {
+        return ((typeof value === 'object' || typeof value === 'function') &&
+            value !== null &&
+            'then' in value &&
+            typeof value.then === 'function');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Attaches a rejection handler to a thenable a synchronous function returned, and otherwise
+ * ignores it. An unobserved rejection would end the process before the run could report anything.
+ * The thenable is adopted inside a fresh promise, so a `then` that throws rejects that promise
+ * instead of throwing here.
+ */
+export function ignoreRejection(value) {
+    void new Promise((resolve) => {
+        resolve(value);
+    }).catch(() => undefined);
+}

package/dist/translators.d.ts

@@ -0,0 +1,69 @@
+import { LoomError } from './errors.js';
+import type { FactSite } from './facts.js';
+/** Phantom key. It brands a translation and holds no runtime value. */
+declare const translation: unique symbol;
+/**
+ * A class a translation is keyed on, such as `SyntaxError`. Its instance type is the type the
+ * translator receives, so the function needs no narrowing of its own.
+ */
+type ErrorClass<Thrown extends object> = abstract new (...args: never[]) => Thrown;
+/**
+ * A function that turns one foreign throw into one of the author's failures, or answers
+ * `undefined` to pass the throw on to the next translator.
+ */
+type Translator<Thrown extends object> = (error: Thrown) => LoomError | undefined;
+/** One translation as core reads it back: the key's prototype, its name, and the typed call. */
+interface TranslationRecord {
+    /** The object a thrown value's prototype chain holds when the key's class constructed it. */
+    prototype: object;
+    /** The key's name, which a broken translator's diagnostic reports. */
+    name: string;
+    /**
+     * The translator, typed at `translate()` against its key. It answers `undefined` without calling
+     * the translator for a value its key does not claim as an instance.
+     */
+    offer: (thrown: object) => unknown;
+}
+/** The runtime value `translate()` returns. Its record lives in the registry above. */
+declare class TranslationDeclaration {
+    readonly [translation]: true;
+    constructor(record: TranslationRecord);
+}
+/** An opaque translation pairing one error class with the translator that answers it. */
+type Translation = Pick<TranslationDeclaration, typeof translation>;
+/**
+ * Pairs an error class with the translator that turns its instances into a failure. The
+ * translator receives the thrown instance typed from the class, and a `translators` list on the
+ * Application or a plugin registers the pair.
+ */
+declare function translate<Thrown extends object>(key: ErrorClass<Thrown>, translator: Translator<Thrown>): Translation;
+/**
+ * One contributor's translations: how a diagnostic names it, and its records by key prototype,
+ * each list in the order the contributor listed it.
+ */
+interface TranslationContributor {
+    /** The contributor as a diagnostic's subject, such as `the Application` or `plugin "@acme/http"`. */
+    subject: string;
+    byPrototype: ReadonlyMap<object, readonly TranslationRecord[]>;
+}
+/**
+ * Every contributor in resolution order: the application's translations, then each installed
+ * plugin's in installation order.
+ */
+type TranslatorRegistry = readonly TranslationContributor[];
+/**
+ * One contributor's `translators` list. `site` names the contributor at the start of a sentence,
+ * `The Application` or `Plugin "@acme/http"`, and holds the call that declared the list, which a
+ * fault marks. The slot is read defensively, because a JavaScript author reaches it with any value.
+ */
+declare function readTranslations(site: FactSite, declared: unknown): TranslationContributor;
+/**
+ * The failure the translators answer for one foreign throw, or `undefined` when the throw is never
+ * offered or every translator passed. Resolution follows the override walk: each contributor in
+ * order, the thrown value's chain walked in full at each, most derived first, and within one
+ * class the list order. A broken translator ends the walk with its defect, so no later translator
+ * hides it.
+ */
+declare function translateThrow(registry: TranslatorRegistry, thrown: unknown): LoomError | undefined;
+export type { ErrorClass, TranslationContributor, Translation, Translator, TranslatorRegistry };
+export { readTranslations, translate, translateThrow };

package/dist/translators.js

@@ -0,0 +1,253 @@
+import { spelled } from './diagnostic-text.js';
+import { asSentence, DeclarationError, InternalError, LoomError, quoted, reasonOf, } from './errors.js';
+import { partFinding } from './facts.js';
+import { foreignValue, notAFunction, notAList, translationKey } from './plugin-rules.js';
+import { prototypeChain } from './prototypes.js';
+import { brokenTranslator, brokenTranslatorCorrection } from './rules.js';
+import { ignoreRejection, isThenable } from './thenable.js';
+/** Authored translations register here, so the public type publishes nothing to reach. */
+const records = new WeakMap();
+/** The runtime value `translate()` returns. Its record lives in the registry above. */
+class TranslationDeclaration {
+    constructor(record) {
+        records.set(this, record);
+        Object.freeze(this);
+    }
+}
+/**
+ * The prototype a class key carries, or `undefined` for a value that is not a class. A class is a
+ * function whose `prototype` is the object its instances' chains hold, so an arrow function, a
+ * bound function, and every non-function are no key at all. A key whose `prototype` cannot be
+ * read, such as a proxy whose trap throws, is no key either.
+ */
+function keyPrototype(key) {
+    let prototype = undefined;
+    try {
+        if (typeof key !== 'function' || !('prototype' in key)) {
+            return undefined;
+        }
+        prototype = key.prototype;
+    }
+    catch {
+        return undefined;
+    }
+    return typeof prototype === 'object' && prototype !== null ? prototype : undefined;
+}
+/** A key's own name, or `undefined` when it has none that can be read. */
+function nameOf(key) {
+    let name = undefined;
+    try {
+        name = 'name' in key ? key.name : undefined;
+    }
+    catch {
+        name = undefined;
+    }
+    return typeof name === 'string' && name !== '' ? name : undefined;
+}
+/**
+ * How a diagnostic names one key class: its name, quoted and escaped, or what it is when it has no
+ * name that can be read.
+ */
+function keyName(key) {
+    const name = nameOf(key);
+    return name === undefined ? 'an anonymous class' : quoted(name);
+}
+/** A name JavaScript source can spell as an identifier, which a finding prints a class key as. */
+const identifier = /^[A-Za-z_$][\w$]*$/u;
+/**
+ * The finding for one `translate()` call, marking the argument at `mark`. A class key prints as
+ * its name, as its author wrote it, where any other function prints as an ellipsis.
+ */
+function translateFinding(key, translator, mark) {
+    const name = typeof key === 'function' ? nameOf(key) : undefined;
+    const code = name !== undefined && identifier.test(name) ? spelled(name) : key;
+    return { arguments: [code, translator], call: 'translate', mark };
+}
+/**
+ * Whether a key claims a thrown value as its instance. A value whose chain cannot be read is not
+ * claimed, so its translator is never called and is not blamed for the failed read.
+ */
+function claims(thrown, key) {
+    try {
+        return thrown instanceof key;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Pairs an error class with the translator that turns its instances into a failure. The
+ * translator receives the thrown instance typed from the class, and a `translators` list on the
+ * Application or a plugin registers the pair.
+ */
+function translate(key, translator) {
+    const prototype = keyPrototype(key);
+    // A key whose prototype's chain cannot be read, such as through a proxy whose trap throws, is no
+    // Key either, so it is reported as a non-class before any failure-class check.
+    const chain = prototype === undefined ? undefined : prototypeChain(prototype);
+    if (prototype === undefined || chain === undefined) {
+        throw new DeclarationError(translationKey, {
+            correction: 'Supply an error class, such as SyntaxError.',
+            findings: [translateFinding(key, translator, '0')],
+            sentence: 'translate() received a key that is not a class.',
+        });
+    }
+    // Core never offers a failure to translators, so a translation keyed on a failure class never runs.
+    if (prototype === LoomError.prototype || chain.includes(LoomError.prototype)) {
+        throw new DeclarationError(translationKey, {
+            correction: 'Key the translation on the foreign class it replaces.',
+            findings: [translateFinding(key, translator, '0')],
+            sentence: 'translate() received a failure class as its key.',
+        });
+    }
+    if (typeof translator !== 'function') {
+        throw new DeclarationError(notAFunction, {
+            correction: 'Supply a function that returns a failure or undefined.',
+            findings: [translateFinding(key, translator, '1')],
+            sentence: 'translate() received a translator that is not a function.',
+        });
+    }
+    return new TranslationDeclaration({
+        name: keyName(key),
+        offer: (thrown) => (claims(thrown, key) ? translator(thrown) : undefined),
+        prototype,
+    });
+}
+/**
+ * One contributor's `translators` list. `site` names the contributor at the start of a sentence,
+ * `The Application` or `Plugin "@acme/http"`, and holds the call that declared the list, which a
+ * fault marks. The slot is read defensively, because a JavaScript author reaches it with any value.
+ */
+function readTranslations(site, declared) {
+    const sentence = site.subject;
+    const byPrototype = new Map();
+    for (const record of translationRecords(site, declared)) {
+        const listed = byPrototype.get(record.prototype) ?? [];
+        listed.push(record);
+        byPrototype.set(record.prototype, listed);
+    }
+    return {
+        byPrototype,
+        subject: `${sentence.slice(0, 1).toLowerCase()}${sentence.slice(1)}`,
+    };
+}
+/** The fix a `translators` slot's list fault and entry fault share. */
+const translationSupply = 'translate(ErrorClass, translator)';
+/** The record behind each entry of one `translators` slot, whose every other value is its fault. */
+function translationRecords(site, declared) {
+    if (declared !== undefined && !Array.isArray(declared)) {
+        throw new DeclarationError(notAList, {
+            correction: `Supply a list of values returned by ${translationSupply}.`,
+            findings: [partFinding(site, [])],
+            sentence: `${site.subject} declares translators that are not an array.`,
+        });
+    }
+    const list = declared ?? [];
+    // Array.from visits a hole as undefined, where map would skip it and leave the hole in place.
+    return Array.from(list, (entry, index) => {
+        const record = typeof entry === 'object' && entry !== null ? records.get(entry) : undefined;
+        if (!record) {
+            throw new DeclarationError(foreignValue, {
+                correction: `Supply the value returned by ${translationSupply}.`,
+                findings: [partFinding(site, [index])],
+                sentence: `${site.subject} holds a translator entry that is not a translation.`,
+            });
+        }
+        return record;
+    });
+}
+/**
+ * Every prototype in one thrown value's chain, most derived first, or `undefined` when the value is
+ * never offered: a value whose chain holds a failure class, and a value whose chain cannot be read,
+ * such as a proxy whose trap throws, or whose chain repeats a link or never ends. A value with a
+ * `null` prototype has an empty chain, which no key matches.
+ */
+function offeredChain(thrown) {
+    const chain = prototypeChain(thrown);
+    return chain?.includes(LoomError.prototype) ? undefined : chain;
+}
+/** How a broken translator's diagnostic names a value that is not a failure. */
+function returnedKind(value) {
+    if (value === null) {
+        return 'null';
+    }
+    if (isThenable(value)) {
+        return 'a promise';
+    }
+    const kind = typeof value;
+    return /^[aeiou]/u.test(kind) ? `an ${kind}` : `a ${kind}`;
+}
+/** Whether a translator's answer is a failure, read without letting a hostile value throw. */
+function isFailure(value) {
+    try {
+        return value instanceof LoomError;
+    }
+    catch {
+        return false;
+    }
+}
+/** The defect of a broken translator under its rule, with the sentence and cause each shape gives. */
+function brokenDefect(sentence, cause) {
+    return new InternalError(brokenTranslator, {
+        cause,
+        correction: brokenTranslatorCorrection,
+        sentence,
+    });
+}
+/**
+ * The defect of a translator that threw. Its cause is a new `AggregateError` that holds the
+ * translator's throw and then the original throw, so neither is lost and neither is mutated. The
+ * reason is read through `reasonOf`, which escapes it onto one line.
+ */
+function threwDefect(who, error, thrown) {
+    const reason = reasonOf(error);
+    const cause = new AggregateError([error, thrown], 'The translator threw while translating the original throw.');
+    return brokenDefect(`${who} threw: ${asSentence(reason)}`, cause);
+}
+/** The one translator call, whose throw or non-failure answer is the defect of that translator. */
+function consult(contributor, record, thrown) {
+    const who = `The translator ${contributor.subject} registered for ${record.name}`;
+    let answer = undefined;
+    try {
+        answer = record.offer(thrown);
+    }
+    catch (error) {
+        return threwDefect(who, error, thrown);
+    }
+    if (answer === undefined || isFailure(answer)) {
+        return answer;
+    }
+    // A translator is synchronous, so a returned promise is ignored once its rejection is observed.
+    if (isThenable(answer)) {
+        ignoreRejection(answer);
+    }
+    return brokenDefect(`${who} returned ${returnedKind(answer)} instead of a failure.`, thrown);
+}
+/**
+ * The failure the translators answer for one foreign throw, or `undefined` when the throw is never
+ * offered or every translator passed. Resolution follows the override walk: each contributor in
+ * order, the thrown value's chain walked in full at each, most derived first, and within one
+ * class the list order. A broken translator ends the walk with its defect, so no later translator
+ * hides it.
+ */
+function translateThrow(registry, thrown) {
+    if ((typeof thrown !== 'object' && typeof thrown !== 'function') || thrown === null) {
+        return undefined;
+    }
+    // With no translation registered, the chain is never read.
+    const chain = registry.some((contributor) => contributor.byPrototype.size > 0)
+        ? (offeredChain(thrown) ?? [])
+        : [];
+    for (const contributor of registry) {
+        for (const prototype of chain) {
+            for (const record of contributor.byPrototype.get(prototype) ?? []) {
+                const answer = consult(contributor, record, thrown);
+                if (answer !== undefined) {
+                    return answer;
+                }
+            }
+        }
+    }
+    return undefined;
+}
+export { readTranslations, translate, translateThrow };

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 /// <reference types="node" preserve="true" />
 import type { Readable, Writable } from 'node:stream';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { FailureExitCode } from './exit-codes.js';
 import type { ExtensionValue } from './extension.js';
 import type { CommandGraph, CommandNode, ResultNode } from './inspect.js';
 import type { RenderingPolicy } from './rendering.js';
@@ -101,7 +102,8 @@ export type GlobalNameConstraint<Name extends string, Globals> = Name extends ke
 } : unknown;
 /** A required record key excludes open strings; distribution rejects each union member. */
 export type NameConstraint<Name extends string, Whole extends string = Name> = {} extends Record<Name, unknown> ? LiteralNameFault : Name extends Whole ? [Whole] extends [Name] ? unknown : LiteralNameFault : LiteralNameFault;
-export type ExitCode = 0 | 1 | 2 | 130 | 143;
+/** The status `run()` resolves: success, a failure class's code, or a cancellation code. */
+export type ExitCode = 0 | FailureExitCode | 130 | 143;
 export interface InputTerminal {
     isTTY: boolean;
 }
@@ -122,6 +124,14 @@ export interface Host {
     stdin: Readable;
     stdout: Writable;
     stderr: Writable;
+    /**
+     * Reads one source file for a defect's Developer Diagnostic, or answers `undefined`. Core calls
+     * it only in a development build, only while it reports a defect, and only for a path under the
+     * working directory. Process capture supplies a reader that refuses a file outside `cwd` after
+     * resolving symbolic links, and answers `undefined` for a path that is not a regular file or
+     * that exceeds 1 MiB.
+     */
+    readSource?: (path: string, cwd: string) => string | undefined;
 }
 export interface RunOptions {
     rendering?: RenderingPolicy;
@@ -175,7 +185,7 @@ export interface ViewContext {
 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;
+    row?: undefined;
 }
 /**
  * A row view renders a sequence one row at a time.
@@ -187,7 +197,7 @@ export interface RowView<Row> {
     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;
+    render?: undefined;
 }
 /** The views record of a value result: every entry renders the whole value. */
 export type ResultViews<Value> = Readonly<Record<string, View<Value>>>;

package/dist/unicode.generated.d.ts

@@ -0,0 +1,27 @@
+/*!
+The tables derive from the Unicode Character Database.
+Copyright © 1991-2025 Unicode, Inc. Licensed under the Unicode License v3,
+in licenses/unicode-LICENSE.txt of @loomcli/core.
+
+They are generated from the tables of @rockorager/uucode.
+Copyright (c) 2026 Tim Culverhouse. Licensed under the MIT License,
+in licenses/uucode-LICENSE.md of @loomcli/core.
+*/
+/** The grapheme break state machine, indexed by state and two break properties. */
+export declare const graphemeTable: {
+    breakStateCount: number;
+    breakTable: Uint8Array<ArrayBuffer>;
+    graphemeBreakPropertyCount: number;
+};
+/** Each code point's width and grapheme break property, in a three-stage lookup. */
+export declare const widthTable: {
+    emojiVSFlag: number;
+    maxCodePoint: number;
+    stage1: Uint16Array<ArrayBuffer>;
+    stage1Shift: number;
+    stage2: Uint8Array<ArrayBuffer>;
+    stage2Mask: number;
+    stage3: Uint16Array<ArrayBuffer>;
+    widthMask: number;
+    zeroWidthFlag: number;
+};