@loomcli/core 0.5.0 → 0.6.0

package/dist/prototypes.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Every prototype in one value's chain, most derived first, or `undefined` when the chain cannot
+ * be read: a proxy trap throws, a link repeats, or the chain runs past `maxChainLinks` links. A
+ * value with a `null` prototype has an empty chain. Override resolution and translator resolution
+ * both walk the chain this returns.
+ */
+export declare function prototypeChain(value: object): object[] | undefined;

package/dist/prototypes.js

@@ -0,0 +1,29 @@
+/** The most links a prototype chain holds before core reads it as a chain that never ends. */
+const maxChainLinks = 1024;
+/** The walk behind `prototypeChain`, which throws where a proxy trap throws. */
+function walkChain(value) {
+    const chain = [];
+    const seen = new Set([value]);
+    for (let link = Reflect.getPrototypeOf(value); link !== null; link = Reflect.getPrototypeOf(link)) {
+        if (seen.has(link) || chain.length >= maxChainLinks) {
+            return undefined;
+        }
+        seen.add(link);
+        chain.push(link);
+    }
+    return chain;
+}
+/**
+ * Every prototype in one value's chain, most derived first, or `undefined` when the chain cannot
+ * be read: a proxy trap throws, a link repeats, or the chain runs past `maxChainLinks` links. A
+ * value with a `null` prototype has an empty chain. Override resolution and translator resolution
+ * both walk the chain this returns.
+ */
+export function prototypeChain(value) {
+    try {
+        return walkChain(value);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/rendering.d.ts

@@ -1,3 +1,4 @@
+import type { FactSite } from './facts.js';
 import type { Host } from './types.js';
 type SwitchPolicy = 'auto' | 'always' | 'never';
 interface RenderingPolicy {
@@ -14,7 +15,11 @@ interface Capabilities {
     depth: 16 | 256 | 'truecolor';
     mainGlyphs: boolean;
 }
-declare function renderingPolicy(value: unknown): RenderingPolicy;
+/**
+ * One declared rendering policy, checked against its closed sets. `site` is where it was declared,
+ * the Application's `rendering` option or `run()`'s, which a fault marks.
+ */
+declare function renderingPolicy(value: unknown, site: FactSite): RenderingPolicy;
 /** A run owns captured facts; stdout and stderr each resolve this one policy independently. */
 declare function capabilities(host: Host, destination: 'stdout' | 'stderr', policy: RenderingPolicy): Capabilities;
 export type { Capabilities, RenderingPolicy };

package/dist/rendering.js

@@ -1,17 +1,31 @@
 import { DeclarationError } from './errors.js';
-import { isPlainObject } from './facts.js';
-function renderingPolicy(value) {
+import { partFinding } from './facts.js';
+import { isPlainObject } from './plain.js';
+import { renderingPolicyRule } from './plugin-rules.js';
+/**
+ * One declared rendering policy, checked against its closed sets. `site` is where it was declared,
+ * the Application's `rendering` option or `run()`'s, which a fault marks.
+ */
+function renderingPolicy(value, site) {
     if (value === undefined) {
         return {};
     }
     if (!isPlainObject(value)) {
-        throw new DeclarationError('The rendering policy must be an object.');
+        throw new DeclarationError(renderingPolicyRule, {
+            correction: 'Supply an object, or omit rendering.',
+            findings: [partFinding(site, [])],
+            sentence: 'The rendering policy is not an object.',
+        });
     }
     const result = {};
     for (const field of ['color', 'modifiers', 'hyperlinks']) {
         const policy = value[field];
         if (policy !== undefined && policy !== 'auto' && policy !== 'always' && policy !== 'never') {
-            throw new DeclarationError(`Rendering ${field} must be auto, always, or never.`);
+            throw new DeclarationError(renderingPolicyRule, {
+                correction: `Supply one of the three, or omit ${field}.`,
+                findings: [partFinding(site, [field])],
+                sentence: `Rendering ${field} is not auto, always, or never.`,
+            });
         }
         if (policy !== undefined) {
             result[field] = policy;
@@ -19,7 +33,11 @@ function renderingPolicy(value) {
     }
     const controls = value.terminalControls;
     if (controls !== undefined && controls !== 'strip' && controls !== 'preserve') {
-        throw new DeclarationError('Rendering terminalControls must be strip or preserve.');
+        throw new DeclarationError(renderingPolicyRule, {
+            correction: 'Supply strip or preserve, or omit terminalControls.',
+            findings: [partFinding(site, ['terminalControls'])],
+            sentence: 'Rendering terminalControls is not strip or preserve.',
+        });
     }
     if (controls !== undefined) {
         result.terminalControls = controls;

package/dist/rules.d.ts

@@ -0,0 +1,51 @@
+/** A value thrown from an action, a middleware, or a source that no translator answered. */
+declare const foreignThrow: import("./diagnostic-text.js").DiagnosticRule;
+/** The fix every foreign throw shares. */
+declare const foreignThrowCorrection = "Catch the error where it is thrown and throw a failure class, such as FatalError, with a sentence the operator can act on.";
+/** A thrown value that inherits from a failure class without having been constructed by one. */
+declare const unconstructedFailure: import("./diagnostic-text.js").DiagnosticRule;
+/** A translator that threw or answered with something other than a failure. */
+declare const brokenTranslator: import("./diagnostic-text.js").DiagnosticRule;
+/** The fix every broken translator shares. */
+declare const brokenTranslatorCorrection = "Return a failure, or undefined to pass, and throw nothing from the translator.";
+/** A failure view that threw or returned a value that is not a string. */
+declare const brokenFailureView: import("./diagnostic-text.js").DiagnosticRule;
+/** An output or lane view that threw or returned a value that is not a string. */
+declare const brokenOutputView: import("./diagnostic-text.js").DiagnosticRule;
+/** The fix a broken failure view and a broken output view share. */
+declare const viewCorrection = "Return a string from the view's render function, and throw nothing from it.";
+/** An `onFailure` hook that threw or returned a value that is not hints. */
+declare const brokenFailureHook: import("./diagnostic-text.js").DiagnosticRule;
+/** A plugin's middleware or source loader that rejected or exported no default function. */
+declare const pluginLoaderFailed: import("./diagnostic-text.js").DiagnosticRule;
+/** A middleware that called `next()` twice, or after it returned. */
+declare const nextMisuse: import("./diagnostic-text.js").DiagnosticRule;
+/** An action or a plugin that broke the promise a declared result makes. */
+declare const resultContract: import("./diagnostic-text.js").DiagnosticRule;
+/** A validator that threw, rejected, or returned a malformed result. */
+declare const validatorFailed: import("./diagnostic-text.js").DiagnosticRule;
+/** A middleware that assigned `view` a name the routed Command's result cannot render. */
+declare const viewSelection: import("./diagnostic-text.js").DiagnosticRule;
+/** The fix every invalid view selection shares. */
+declare const viewSelectionCorrection = "Assign view one of the view names the routed Command's result declares, and only on a Command that declares a result.";
+/** A `run()` option that holds a value of the wrong kind. */
+declare const runOptions: import("./diagnostic-text.js").DiagnosticRule;
+/** A configuration source whose answers break the answers rule. */
+declare const sourceAnswers: import("./diagnostic-text.js").DiagnosticRule;
+/** The fix every source answers fault shares. */
+declare const sourceAnswersCorrection = "Return a record that maps each requested option's name to { value, label }, with a value of the option's raw type.";
+/** A graph that `inspect()` did not return, or whose nodes disagree with the build it came from. */
+declare const foreignGraph: import("./diagnostic-text.js").DiagnosticRule;
+/** The fix every foreign graph shares. */
+declare const foreignGraphCorrection = "Pass the graph inspect() returned, unchanged.";
+/** A host stream that failed a write the run owed it. */
+declare const brokenDestination: import("./diagnostic-text.js").DiagnosticRule;
+/** A failure class whose exit code is outside 1 through 125. */
+declare const failureExitCode: import("./diagnostic-text.js").DiagnosticRule;
+/** A diagnostic rule identity outside the `<package>[/<subpath>...]/<kebab-case-rule>` grammar. */
+declare const ruleIdentity: import("./diagnostic-text.js").DiagnosticRule;
+/** A diagnostic rule whose headline or explanation holds no prose. */
+declare const ruleProse: import("./diagnostic-text.js").DiagnosticRule;
+/** A diagnostic rule whose docs value is not a web address. */
+declare const ruleDocs: import("./diagnostic-text.js").DiagnosticRule;
+export { brokenDestination, brokenFailureHook, brokenFailureView, brokenOutputView, brokenTranslator, brokenTranslatorCorrection, failureExitCode, foreignGraph, foreignGraphCorrection, foreignThrow, foreignThrowCorrection, nextMisuse, pluginLoaderFailed, resultContract, ruleDocs, ruleIdentity, ruleProse, runOptions, sourceAnswers, sourceAnswersCorrection, unconstructedFailure, validatorFailed, viewCorrection, viewSelection, viewSelectionCorrection, };

package/dist/rules.js

@@ -0,0 +1,115 @@
+import { registerRule } from './diagnostic-text.js';
+/*
+ * Core's own rules for the defects it raises, the run-time declaration faults it finds, and the
+ * faults of the two things an author declares to describe a failure: a failure class's exit code
+ * and a diagnostic rule. Each is declared once here and shared by every site that raises it, as a
+ * plugin's rules are.
+ */
+/** A value thrown from an action, a middleware, or a source that no translator answered. */
+const foreignThrow = registerRule('@loomcli/core/foreign-throw', {
+    explanation: 'Core reports a value that an action, a middleware, or a configuration source threw, and that no translator answered, as a defect, because only the author knows what it means. A distributed build shows the operator one generic message in its place.',
+    headline: 'Unhandled exception',
+});
+/** The fix every foreign throw shares. */
+const foreignThrowCorrection = 'Catch the error where it is thrown and throw a failure class, such as FatalError, with a sentence the operator can act on.';
+/** A thrown value that inherits from a failure class without having been constructed by one. */
+const unconstructedFailure = registerRule('@loomcli/core/unconstructed-failure', {
+    explanation: 'A failure class records its exit code when a failure is constructed, so a value that only inherits from one, such as one made with Object.create(), carries no code core can trust.',
+    headline: 'Failure never constructed',
+});
+/** A translator that threw or answered with something other than a failure. */
+const brokenTranslator = registerRule('@loomcli/core/broken-translator', {
+    explanation: 'A translator turns a foreign throw into a failure synchronously. A throw, or any answer other than a failure or undefined, leaves core no failure to report, so it consults no later translator.',
+    headline: 'Broken translator',
+});
+/** The fix every broken translator shares. */
+const brokenTranslatorCorrection = 'Return a failure, or undefined to pass, and throw nothing from the translator.';
+/** A failure view that threw or returned a value that is not a string. */
+const brokenFailureView = registerRule('@loomcli/core/broken-failure-view', {
+    explanation: "A failure view turns a failure into the text the operator reads, synchronously and without throwing. Core wrote its own text for the failure in the view's place.",
+    headline: 'Broken failure view',
+});
+/** An output or lane view that threw or returned a value that is not a string. */
+const brokenOutputView = registerRule('@loomcli/core/broken-output-view', {
+    explanation: 'A view turns a value into text synchronously and without throwing. Core wrote nothing for the call whose view broke, and a run whose output is incomplete cannot succeed.',
+    headline: 'Broken output view',
+});
+/** The fix a broken failure view and a broken output view share. */
+const viewCorrection = "Return a string from the view's render function, and throw nothing from it.";
+/** An `onFailure` hook that threw or returned a value that is not hints. */
+const brokenFailureHook = registerRule('@loomcli/core/broken-failure-hook', {
+    explanation: "An onFailure hook adds hint lines under a failure, synchronously and without throwing. Core dropped this hook's hints and rendered the failure with every other plugin's.",
+    headline: 'Broken failure hook',
+});
+/** A plugin's middleware or source loader that rejected or exported no default function. */
+const pluginLoaderFailed = registerRule('@loomcli/core/plugin-loader-failed', {
+    explanation: "Core loads a plugin's middleware or source module the first time a run reaches it, and the module owes its function as its default export.",
+    headline: 'Plugin loader failed',
+});
+/** A middleware that called `next()` twice, or after it returned. */
+const nextMisuse = registerRule('@loomcli/core/next-misuse', {
+    explanation: 'next() continues the middleware chain once, while the middleware that received it runs. A second call, or a call after the middleware returned, has no chain left to continue.',
+    headline: 'next() misused',
+});
+/** An action or a plugin that broke the promise a declared result makes. */
+const resultContract = registerRule('@loomcli/core/result-contract', {
+    explanation: 'A Command that declares a result promises its consumer one value, or one sequence of rows, that its action emits once through out.results().',
+    headline: 'Result contract broken',
+});
+/** A validator that threw, rejected, or returned a malformed result. */
+const validatorFailed = registerRule('@loomcli/core/validator-failed', {
+    explanation: 'Only an issue a validator returns states a validation verdict. A validator that throws, rejects, or returns anything but a Standard Schema result leaves core no verdict to report, so validation stops and the action does not run.',
+    headline: 'Validator failed',
+});
+/** A middleware that assigned `view` a name the routed Command's result cannot render. */
+const viewSelection = registerRule('@loomcli/core/view-selection', {
+    explanation: "A middleware selects one of the views the routed Command's result declares, by name, before the action runs. A Command that declares no result has no view to select, and a name its result does not declare has no view to render.",
+    headline: 'Invalid view selection',
+});
+/** The fix every invalid view selection shares. */
+const viewSelectionCorrection = "Assign view one of the view names the routed Command's result declares, and only on a Command that declares a result.";
+/** A `run()` option that holds a value of the wrong kind. */
+const runOptions = registerRule('@loomcli/core/run-options', {
+    explanation: 'run() reads its options before it builds the graph. A caller that embeds the application, such as a test, passes them, and a value of the wrong kind leaves the run nothing to act on.',
+    headline: 'Invalid run options',
+});
+/** A configuration source whose answers break the answers rule. */
+const sourceAnswers = registerRule('@loomcli/core/source-answers', {
+    explanation: 'A configuration source answers with a record that maps each option core requested to { value, label }, where the value has the raw type the option takes and the label is one line of prose. Core fills no option from any other answer.',
+    headline: 'Invalid source answers',
+});
+/** The fix every source answers fault shares. */
+const sourceAnswersCorrection = "Return a record that maps each requested option's name to { value, label }, with a value of the option's raw type.";
+/** A graph that `inspect()` did not return, or whose nodes disagree with the build it came from. */
+const foreignGraph = registerRule('@loomcli/core/foreign-graph', {
+    explanation: 'Core reads a Command graph through the build inspect() rendered it from. A graph inspect() did not return, or one whose nodes do not match that build, leaves core no build to read, so the run stops rather than hand a plugin the wrong Command.',
+    headline: 'Graph not from inspect()',
+});
+/** The fix every foreign graph shares. */
+const foreignGraphCorrection = 'Pass the graph inspect() returned, unchanged.';
+/** A host stream that failed a write the run owed it. */
+const brokenDestination = registerRule('@loomcli/core/broken-destination', {
+    explanation: "Core writes the run's output and its failure reports to the host streams run() captured. A stream that fails a write loses whatever followed it, so the run cannot succeed.",
+    headline: 'Broken destination',
+});
+/** A failure class whose exit code is outside 1 through 125. */
+const failureExitCode = registerRule('@loomcli/core/failure-exit-code', {
+    explanation: "A failure's exit code tells the shell how the run ended: 0 means success, and 126 and above belong to the shell and to signals, so a failure exits with a code from 1 through 125. Core never clamps or replaces the code a failure class declares, so a code no failure may exit with is rejected where the class is first constructed.",
+    headline: 'Undeclarable exit code',
+});
+/** A diagnostic rule identity outside the `<package>[/<subpath>...]/<kebab-case-rule>` grammar. */
+const ruleIdentity = registerRule('@loomcli/core/rule-identity', {
+    explanation: "A rule's identity names the package that declares it and the rule inside it, so tooling keys on it and two packages never share one. It is an identity, a package name and any kebab-case subpath segments that name the part of the package that owns the rule, then a kebab-case rule name, joined by /.",
+    headline: 'Invalid rule identity',
+});
+/** A diagnostic rule whose headline or explanation holds no prose. */
+const ruleProse = registerRule('@loomcli/core/rule-prose', {
+    explanation: "A rule's banner prints its headline, and its explanation teaches why the rule exists, so each holds prose.",
+    headline: 'Empty rule text',
+});
+/** A diagnostic rule whose docs value is not a web address. */
+const ruleDocs = registerRule('@loomcli/core/rule-docs', {
+    explanation: "A diagnostic prints a rule's docs as a link the author follows, so it is an absolute http or https URL.",
+    headline: 'Invalid rule docs',
+});
+export { brokenDestination, brokenFailureHook, brokenFailureView, brokenOutputView, brokenTranslator, brokenTranslatorCorrection, failureExitCode, foreignGraph, foreignGraphCorrection, foreignThrow, foreignThrowCorrection, nextMisuse, pluginLoaderFailed, resultContract, ruleDocs, ruleIdentity, ruleProse, runOptions, sourceAnswers, sourceAnswersCorrection, unconstructedFailure, validatorFailed, viewCorrection, viewSelection, viewSelectionCorrection, };

package/dist/sequence.js

@@ -1,4 +1,5 @@
 import { InternalError, routedSubject } from './errors.js';
+import { resultContract } from './rules.js';
 /**
  * A failure the source raised, so the writer tells it apart from the view and write faults its own
  * pieces raise, which the output path has accounted for already.
@@ -44,7 +45,11 @@ function stepsOf(writer) {
         throw new SourceFault(error);
     }
     if (!steps) {
-        throw new SourceFault(new InternalError(`The result of ${routedSubject(writer.path)} is not iterable.`, undefined));
+        throw new SourceFault(new InternalError(resultContract, {
+            cause: undefined,
+            correction: 'Pass out.results() an iterable or an async iterable of rows.',
+            sentence: `The result of ${routedSubject(writer.path)} is not iterable.`,
+        }));
     }
     return steps;
 }

package/dist/sources.d.ts

@@ -1,4 +1,4 @@
-import { InputError, InternalError } from './errors.js';
+import { LoomError } from './errors.js';
 import type { ExtensionRecords } from './extension.js';
 import type { CommandGraph, OptionNode } from './inspect.js';
 import type { OptionValues } from './options.js';
@@ -25,6 +25,8 @@ interface SourceStage {
     inspected: () => CommandGraph;
     /** The routed Command's own options, or `undefined` while local parsing holds a fault. */
     locals: StageScope | undefined;
+    /** Offers the resolver's foreign throw to the translators, ahead of the plugin-fault wrap. */
+    offer: (thrown: unknown) => LoomError | undefined;
     /** The channel a source writes through, whose results call names the source. */
     out: Out;
     plugins: readonly BuiltPlugin[];
@@ -38,11 +40,11 @@ interface SourceStage {
  * What the stage found beside the values it filled. `labels` names where each filled option's value
  * came from, by option name, and `rejected` names the variable of each Boolean option whose value
  * is outside the grammar. Both are internal to core's failure messages. `fault` is a configuration
- * source's own fault, or the `InputError` its resolver threw, which stops the stage and takes the
- * place of every validation problem.
+ * source's own fault, or the failure its resolver threw, which stops the stage and takes the place
+ * of every validation problem.
  */
 interface SourceOutcome {
-    fault: InternalError | InputError | undefined;
+    fault: LoomError | undefined;
     labels: ReadonlyMap<string, string>;
     rejected: ReadonlyMap<string, string>;
 }

package/dist/sources.js

@@ -1,7 +1,9 @@
-import { asSentence, InputError, InternalError, reasonOf, ResultError } from './errors.js';
-import { isPlainObject, isProseLine } from './facts.js';
+import { asSentence, foreignFailure, InternalError, LoomError, reasonOf } from './errors.js';
+import { isProseLine } from './facts.js';
 import { isSupplied } from './options.js';
+import { isPlainObject } from './plain.js';
 import { loadDefault, pluginSentence, pluginValues } from './plugin.js';
+import { foreignThrow, foreignThrowCorrection, sourceAnswers, sourceAnswersCorrection, } from './rules.js';
 /** The Boolean grammar a bound variable is read through: the whole value, case-insensitive. */
 const truths = new Map([
     ['0', false],
@@ -85,7 +87,11 @@ function rawValue(kind, value) {
 const ruleFaults = new WeakSet();
 /** A fault the answers rule names, recorded so that reading the answers rethrows it unframed. */
 function ruleFault(message) {
-    const fault = new InternalError(message, undefined);
+    const fault = new InternalError(sourceAnswers, {
+        cause: undefined,
+        correction: sourceAnswersCorrection,
+        sentence: message,
+    });
     ruleFaults.add(fault);
     return fault;
 }
@@ -130,7 +136,11 @@ function isResolverExport(value) {
 }
 /** The fault of a source that threw, while it ran or while core read what it returned. */
 function sourceFailure(sentence, error) {
-    return new InternalError(`${sentence} failed in its configuration source: ${asSentence(reasonOf(error))}`, error);
+    return new InternalError(foreignThrow, {
+        cause: error,
+        correction: foreignThrowCorrection,
+        sentence: `${sentence} failed in its configuration source: ${asSentence(reasonOf(error))}`,
+    });
 }
 /**
  * Asks the one configuration source about every requested option, and answers with what it said.
@@ -162,13 +172,14 @@ async function askSource(stage, call) {
         answers = await resolver(context);
     }
     catch (error) {
-        // The resolver's own InputError is a usage failure.
-        // Its out.results() call is the results fault that names it.
-        // Every other throw is the plugin's fault.
-        if (error instanceof InputError || (error instanceof ResultError && error.kind === 'source')) {
+        // The resolver's own failure reports with its class's code, as an action's does.
+        // That covers an InputError, the FatalError out.fatal() throws, and its out.results() fault.
+        // A foreign throw is offered to the translators.
+        // One that no translator answers is the plugin's fault.
+        if (error instanceof LoomError) {
             throw error;
         }
-        throw sourceFailure(sentence, error);
+        throw stage.offer(error) ?? sourceFailure(sentence, error);
     }
     try {
         return readAnswers(sentence, answers, requested);
@@ -238,11 +249,9 @@ async function fillInputs(stage) {
         return { fault: undefined, labels, rejected };
     }
     catch (error) {
-        // The resolver's InputError reports as a usage failure.
+        // The resolver's own failure keeps its class, and so its code.
         // Every other fault above is raised as an internal error, and anything else is wrapped the same way.
-        const fault = error instanceof InternalError || error instanceof InputError
-            ? error
-            : new InternalError(reasonOf(error), error);
+        const fault = error instanceof LoomError ? error : foreignFailure(error);
         return { fault, labels, rejected };
     }
 }

package/dist/style-wire.js

@@ -1,5 +1,5 @@
-import { isPlainObject } from './facts.js';
 import { glyphForms } from './glyphs.generated.js';
+import { isPlainObject } from './plain.js';
 import { applyOperations, emptyAttributes } from './style-state.js';
 import { close, colorFallbacks, escape, headerEnd, isColorName, modifiers, open, tokens, } from './style.js';
 function isByte(value) {

package/dist/style.js

@@ -1,4 +1,4 @@
-import { isPlainObject } from './facts.js';
+import { isPlainObject } from './plain.js';
 /** Concrete terminal foregrounds; backgrounds use the same palette indices. */
 const colors = {
     black: 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 };