@loomcli/core 0.1.0

package/dist/command.js

@@ -0,0 +1,452 @@
+import { commandSentence, commandSubject, DeclarationError, NonCallableCommandError, UnexpectedArgumentError, UnknownCommandError, } from './errors.js';
+import { bindGlobals, buildGlobals } from './globals.js';
+import { compileOptions, extractGlobals, mergeValues, parseInputs } from './options.js';
+import { captureConfig, validateValues } from './validation.js';
+/** Authored values register here, so the public type publishes no state to reach or replace. */
+const nodes = new WeakMap();
+/** Reads the declarations behind an attached value; anything else is a declaration error. */
+function nodeOf(parent, child) {
+    const node = nodes.get(child);
+    if (!node) {
+        throw new DeclarationError(`${commandSentence(parent)} attaches a value that is not a Command. Attach the value returned by new Command(name).`);
+    }
+    return node;
+}
+/** One name rule for every declared name in the graph, so a child and an argument read alike. */
+function isDeclaredName(name) {
+    return typeof name === 'string' && Boolean(name) && !name.startsWith('-') && !/[\s=]/u.test(name);
+}
+function checkChildName(parent, name) {
+    if (!isDeclaredName(name)) {
+        throw new DeclarationError(`${commandSentence(parent)} attaches a child named "${String(name)}". Use a nonempty name without a leading hyphen, whitespace, or "=".`);
+    }
+}
+/** An alias is a bare token the way a child name is, so it answers to the same name rule. */
+function checkAliasName(command, alias) {
+    if (!isDeclaredName(alias)) {
+        throw new DeclarationError(`${commandSentence(command)} declares an alias named "${String(alias)}". Use a nonempty name without a leading hyphen, whitespace, or "=".`);
+    }
+}
+/** The state every declaration starts from. The unnamed root and each named Command share it. */
+export function freshState(name, globals) {
+    return {
+        actions: [],
+        aliases: [],
+        bind: () => ({ args: {}, options: {} }),
+        children: [],
+        globals,
+        inputs: [],
+        late: [],
+        name,
+    };
+}
+/** A declaration after the action is an order fault; build reports the first one recorded. */
+function recordLate(state, declarations) {
+    return state.actions.length > 0 ? [...state.late, ...declarations] : state.late;
+}
+/** The declared value joins `args` under its literal name, typed by its own config. */
+export function declareArgument(state, input) {
+    const previous = state.bind;
+    return {
+        ...state,
+        bind: (values) => {
+            const bound = previous(values);
+            return { ...bound, args: { ...bound.args, ...values.argument(input) } };
+        },
+        inputs: [...state.inputs, input],
+        late: recordLate(state, [{ input, kind: 'input' }]),
+    };
+}
+/** The declared value joins `options` under its literal name, typed by its own config. */
+export function declareOption(state, input) {
+    const previous = state.bind;
+    return {
+        ...state,
+        bind: (values) => {
+            const bound = previous(values);
+            return { ...bound, options: { ...bound.options, ...values.option(input) } };
+        },
+        inputs: [...state.inputs, input],
+        late: recordLate(state, [{ input, kind: 'input' }]),
+    };
+}
+/** One call's names stay one group, so the empty call the types reject still reports as one. */
+export function declareAlias(state, names) {
+    return {
+        ...state,
+        aliases: [...state.aliases, names],
+        late: recordLate(state, names.map((alias) => ({ alias, kind: 'alias' }))),
+    };
+}
+export function declareAction(state, handler) {
+    return { ...state, actions: [...state.actions, handler] };
+}
+/** Attaching is a declaration call too, so the receiver keeps the children it already had. */
+export function attachChild(state, child) {
+    return {
+        ...state,
+        children: [...state.children, child],
+        late: recordLate(state, [{ child, kind: 'child' }]),
+    };
+}
+/** The types remove a late call for TypeScript authors; JavaScript authors read it here. */
+function checkDeclarationOrder(state) {
+    const { name } = state;
+    const late = state.late[0];
+    if (!late) {
+        return;
+    }
+    if (late.kind === 'input') {
+        throw new DeclarationError(`${commandSentence(name)} declares ${late.input.kind} "${late.input.name}" after its action. Declare arguments and options before action().`);
+    }
+    if (late.kind === 'alias') {
+        throw new DeclarationError(`${commandSentence(name)} declares alias "${late.alias}" after its action. Declare aliases before action().`);
+    }
+    // Child identity and names are settled before this call, so the node and its name are valid.
+    throw new DeclarationError(`${commandSentence(name)} attaches child "${String(nodeOf(name, late.child).name)}" after its action. Attach children before action().`);
+}
+/** Child names are checked before any child builds, so parent diagnostics come first. */
+function collectChildren(state) {
+    const attached = [];
+    const seen = new Set();
+    for (const child of state.children) {
+        const node = nodeOf(state.name, child);
+        const name = node.name;
+        checkChildName(state.name, name);
+        if (seen.has(name)) {
+            throw new DeclarationError(`${commandSentence(state.name)} attaches two children named "${name}". Rename or remove one.`);
+        }
+        seen.add(name);
+        attached.push([name, node]);
+    }
+    return attached;
+}
+/**
+ * A Command's own alias rules, and the flat list in declaration order that routing and inspection
+ * read. Each call keeps its own group, so a call that names none reports as the call it is.
+ */
+function collectAliases(state) {
+    const { name } = state;
+    const aliases = [];
+    const seen = new Set();
+    for (const declaration of state.aliases) {
+        if (declaration.length === 0) {
+            throw new DeclarationError(`${commandSentence(name)} declares an alias with no names. Supply at least one name.`);
+        }
+        for (const alias of declaration) {
+            checkAliasName(name, alias);
+            if (alias === name) {
+                throw new DeclarationError(`${commandSentence(name)} declares alias "${alias}", which is its own name. Remove the alias.`);
+            }
+            if (seen.has(alias)) {
+                throw new DeclarationError(`${commandSentence(name)} declares alias "${alias}" twice. Remove the repeated alias.`);
+            }
+            seen.add(alias);
+            aliases.push(alias);
+        }
+    }
+    return aliases;
+}
+/**
+ * One parent's namespace, which every canonical name and alias under it shares. Each child settled
+ * its own alias rules while it built, so what is left is the collision with a sibling. The names are
+ * read before the walk, so the rule reads the same whichever sibling the author declared first.
+ */
+function aliasNamespace(parent, names) {
+    const owners = new Map();
+    return function claim(child, alias) {
+        if (names.has(alias)) {
+            throw new DeclarationError(`${commandSentence(parent)} attaches child "${child}" with alias "${alias}", which is also the name of child "${alias}". Rename or remove one.`);
+        }
+        const owner = owners.get(alias);
+        if (owner !== undefined) {
+            throw new DeclarationError(`${commandSentence(parent)} attaches child "${child}" with alias "${alias}", which is also an alias of child "${owner}". Rename or remove one.`);
+        }
+        owners.set(alias, child);
+    };
+}
+/**
+ * Claims a child for its parent when the depth-first walk reaches it, then builds its subtree. A
+ * claimed node always means a second parent, because the duplicate-name rule rejects one parent
+ * attaching a value twice. Parents may share a name, so the claim is by node identity and the name
+ * serves the diagnostic alone.
+ */
+function buildChild(parent, [name, node], context) {
+    const owner = context.owners.get(node);
+    if (owner !== undefined) {
+        throw new DeclarationError(`${commandSentence(parent)} attaches child "${name}", which ${commandSubject(owner)} also attaches. Attach a Command value at one point; create a new Command for each placement.`);
+    }
+    context.owners.set(node, parent);
+    return node.build(context);
+}
+/** A variadic or optional slot ends the positional list, so nothing may follow either one. */
+function checkSlotOrder(slot, next, subject) {
+    if (slot.variadic) {
+        throw new DeclarationError(`Argument "${slot.input.name}" is variadic and precedes argument "${next.input.name}" on ${subject}. Declare the variadic argument last.`);
+    }
+    if (!slot.required) {
+        throw new DeclarationError(next.required
+            ? `Argument "${slot.input.name}" is optional and precedes required argument "${next.input.name}" on ${subject}. Declare optional arguments after required ones.`
+            : `Argument "${next.input.name}" follows optional argument "${slot.input.name}" on ${subject}. Declare an optional argument last.`);
+    }
+}
+function collectArguments(state, subject) {
+    const slots = [];
+    const seen = new Set();
+    for (const input of state.inputs.filter((entry) => entry.kind === 'argument')) {
+        if (!isDeclaredName(input.name)) {
+            throw new DeclarationError(`${commandSentence(state.name)} declares an argument named "${String(input.name)}". Use a nonempty name without a leading hyphen, whitespace, or "=".`);
+        }
+        if (seen.has(input.name)) {
+            throw new DeclarationError(`Argument "${input.name}" is declared more than once on ${subject}. Remove or rename the duplicate.`);
+        }
+        seen.add(input.name);
+        slots.push({
+            input,
+            required: input.config.required === true,
+            variadic: input.config.variadic === true,
+        });
+    }
+    for (let index = 0; index + 1 < slots.length; index += 1) {
+        const slot = slots[index];
+        const next = slots[index + 1];
+        if (slot && next) {
+            checkSlotOrder(slot, next, subject);
+        }
+    }
+    return slots;
+}
+function compileLocalOptions(state, globals, subject) {
+    const declarations = state.inputs.filter((input) => input.kind === 'option');
+    for (const declaration of declarations) {
+        if (globals.names.has(declaration.name)) {
+            throw new DeclarationError(`Option "${declaration.name}" is declared as a global option and as a local option on ${subject}. Rename the local option.`);
+        }
+    }
+    const options = compileOptions(declarations, subject);
+    for (const [spelling, option] of options) {
+        const global = globals.options.get(spelling);
+        if (global) {
+            throw new DeclarationError(`Option spelling "${spelling}" is used by the global option "${global.name}" and the local option "${option.name}" on ${subject}. Change one declaration.`);
+        }
+    }
+    return options;
+}
+/**
+ * A Command without an action is a group, and routing sends an invocation on to one of its
+ * children. A group with no children receives an invocation no handler can answer, and a local
+ * option on a group reaches no handler either, because locals never inherit.
+ */
+function checkGroup(state, children) {
+    const { name } = state;
+    if (children.length === 0) {
+        throw new DeclarationError(`${commandSentence(name)} has no action. Register an action.`);
+    }
+    const option = state.inputs.find((input) => input.kind === 'option');
+    if (option) {
+        throw new DeclarationError(`${commandSentence(name)} declares option "${option.name}" but registers no action to receive it. Register an action or remove the option.`);
+    }
+}
+/** Binds one Command's declarations to its action, so an action reads only validated values. */
+function bindDispatch(state, action) {
+    return ({ host, out, passthrough, values }) => {
+        const bound = state.bind(values);
+        return action({
+            args: bound.args,
+            host,
+            options: { ...bindGlobals(state.globals, values), ...bound.options },
+            out,
+            passthrough,
+        });
+    };
+}
+/** Validates one declaration against the shared globals table and compiles it for dispatch. */
+export function buildCommand(state, context) {
+    const { actions, name } = state;
+    const { globals } = context;
+    const subject = commandSubject(name);
+    if (state.globals !== globals.source) {
+        throw new DeclarationError(`${commandSentence(name)} holds a different GlobalOptions value than its Application. Share one GlobalOptions value across the declarations.`);
+    }
+    const attached = collectChildren(state);
+    checkDeclarationOrder(state);
+    const aliases = collectAliases(state);
+    const slots = collectArguments(state, subject);
+    const first = slots[0];
+    const child = attached[0];
+    if (first && child) {
+        throw new DeclarationError(`${commandSentence(name)} declares argument "${first.input.name}" and attaches child "${child[0]}". Move the argument into a child Command or remove the children.`);
+    }
+    if (actions.length > 1) {
+        throw new DeclarationError(`${commandSentence(name)} has multiple actions. Register one action.`);
+    }
+    const action = actions[0];
+    if (!action) {
+        checkGroup(state, attached);
+    }
+    const options = compileLocalOptions(state, globals, subject);
+    const children = new Map();
+    const routes = new Map();
+    const claim = aliasNamespace(name, new Set(attached.map((entry) => entry[0])));
+    for (const entry of attached) {
+        // The subtree builds before its aliases are claimed, so the tree rule keeps its precedence.
+        const routed = { command: buildChild(name, entry, context), name: entry[0] };
+        children.set(routed.name, routed.command);
+        routes.set(routed.name, routed);
+        for (const alias of routed.command.aliases) {
+            claim(routed.name, alias);
+            routes.set(alias, routed);
+        }
+    }
+    return {
+        aliases,
+        arguments: slots,
+        children,
+        dispatch: action ? bindDispatch(state, action) : undefined,
+        inputs: state.inputs,
+        name,
+        options,
+        routes,
+    };
+}
+/** The globals table and the owners record each compile once per invocation and the whole graph shares them. */
+export function buildGraph(root) {
+    const context = { globals: buildGlobals(root.globals), owners: new Map() };
+    return { globals: context.globals, root: buildCommand(root, context) };
+}
+export class CommandBuilder {
+    #state;
+    constructor(state) {
+        this.#state = state;
+        nodes.set(this, this);
+    }
+    get name() {
+        return this.#state.name;
+    }
+    argument(name, config) {
+        const input = {
+            config: captureConfig(config),
+            kind: 'argument',
+            name,
+        };
+        return new CommandBuilder(declareArgument(this.#state, input));
+    }
+    option(name, config) {
+        const input = {
+            config: captureConfig(config),
+            kind: 'option',
+            name,
+        };
+        return new CommandBuilder(declareOption(this.#state, input));
+    }
+    /**
+     * Hidden aliases are other bare tokens that route to this Command. They invalidate no call, and
+     * the tuple rest parameter rejects a call that names none.
+     */
+    alias(...names) {
+        return new CommandBuilder(declareAlias(this.#state, names));
+    }
+    /** A child arrives in any type state, because its own action is the call that finished it. */
+    command(child) {
+        return new CommandBuilder(attachChild(this.#state, child));
+    }
+    /** The action is the last declaration call, so the value it returns publishes `AfterAction`. */
+    action(handler) {
+        return new CommandBuilder(declareAction(this.#state, handler));
+    }
+    build(context) {
+        return buildCommand(this.#state, context);
+    }
+}
+/**
+ * The runtime class behind the public constructor. It is generic so that an instance's `Globals`
+ * is the type of the value it holds, with `{}` standing in when there is none, which is what each
+ * signature of the constructor interface publishes.
+ */
+class CommandDeclaration extends CommandBuilder {
+    constructor(name, globals) {
+        super(freshState(name, globals));
+    }
+}
+/** The public constructor requires a name and narrows the globals type to the supplied value. */
+export const Command = CommandDeclaration;
+/** Every declaration in the graph, so defaults are validated before any token is read. */
+export function collectInputs(command) {
+    return [
+        ...command.inputs,
+        ...[...command.children.values()].flatMap((child) => collectInputs(child)),
+    ];
+}
+/** Bare tokens, names or aliases, select children until a Command has none; a hyphen commits. */
+export function route(root, tokens) {
+    let command = root;
+    const path = [];
+    let index = 0;
+    while (command.children.size > 0) {
+        const token = tokens[index];
+        if (token === undefined || token === '--' || token.startsWith('-')) {
+            break;
+        }
+        const child = command.routes.get(token);
+        if (!child) {
+            throw new UnknownCommandError(token, [...command.children.keys()]);
+        }
+        // An alias routes like the canonical name, and the path it walks reports that name alone.
+        command = child.command;
+        path.push(child.name);
+        index += 1;
+    }
+    return { command, path, tokens: tokens.slice(index) };
+}
+/**
+ * The tokens each positional slot received. An omitted required argument binds nothing here and
+ * reports as a missing input in the validation phase, so omission has one class whether the input
+ * is an argument or an option. Extra tokens are a token fault, so this phase still reports them.
+ */
+function bindArguments(command, path, positionals) {
+    const values = new Map();
+    let index = 0;
+    for (const slot of command.arguments) {
+        if (slot.variadic) {
+            const rest = positionals.slice(index);
+            // An empty tail binds nothing, so validation reads it as `[]` or reports the omission.
+            if (rest.length > 0) {
+                values.set(slot.input, rest);
+            }
+            index = positionals.length;
+        }
+        else {
+            const value = positionals[index];
+            if (value !== undefined) {
+                values.set(slot.input, value);
+                index += 1;
+            }
+        }
+    }
+    if (index < positionals.length) {
+        throw new UnexpectedArgumentError(path, command.arguments.length, positionals.slice(index));
+    }
+    return values;
+}
+/** Consumes globals, routes to a Command, then validates globals and locals in one pass. */
+export async function selectCommand(graph, invocation) {
+    const { host } = invocation;
+    const scan = extractGlobals(graph.globals.options, [...host.argv]);
+    const { command, path, tokens: rest } = route(graph.root, scan.rest);
+    const { dispatch } = command;
+    // A group answers no invocation of its own, so it fails with the routing errors above it.
+    if (!dispatch) {
+        throw new NonCallableCommandError(path, [...command.children.keys()]);
+    }
+    const parsed = parseInputs(command.options, rest);
+    const args = bindArguments(command, path, parsed.positionals);
+    const values = await validateValues({
+        command: path,
+        defaults: invocation.defaults,
+        host,
+        inputs: { globals: graph.globals.inputs, locals: command.inputs },
+        passthrough: parsed.passthrough,
+        supplied: { args, options: mergeValues(scan.values, parsed.options) },
+    });
+    return { dispatch, passthrough: parsed.passthrough, values };
+}

package/dist/context.d.ts

@@ -0,0 +1,9 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { ValidationContext } from './types.js';
+/** The `libraryOptions` key core writes its context under. It names the package that owns it. */
+declare const validationContextKey = "@loomcli/core";
+/** The options of one schema call, with its context registered for the accessor to recognize. */
+declare function schemaOptions(context: ValidationContext): StandardSchemaV1.Options;
+/** Reads the context core attached to a schema call, or undefined when another caller ran it. */
+declare function validationContext(options: StandardSchemaV1.Options | undefined): ValidationContext | undefined;
+export { schemaOptions, validationContext, validationContextKey };

package/dist/context.js

@@ -0,0 +1,18 @@
+/** The `libraryOptions` key core writes its context under. It names the package that owns it. */
+const validationContextKey = '@loomcli/core';
+/**
+ * Every context core has emitted. The accessor answers from this registry alone, so a value some
+ * other caller wrote under the same key reads as no context, and the reading needs no assertion.
+ */
+const emitted = new WeakMap();
+/** The options of one schema call, with its context registered for the accessor to recognize. */
+function schemaOptions(context) {
+    emitted.set(context, context);
+    return { libraryOptions: { [validationContextKey]: context } };
+}
+/** Reads the context core attached to a schema call, or undefined when another caller ran it. */
+function validationContext(options) {
+    const carried = options?.libraryOptions?.[validationContextKey];
+    return carried !== null && typeof carried === 'object' ? emitted.get(carried) : undefined;
+}
+export { schemaOptions, validationContext, validationContextKey };

package/dist/errors.d.ts

@@ -0,0 +1,158 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { InputIdentity, Renderer } from './types.js';
+/**
+ * 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.
+ */
+type ShortGroupFault = {
+    reason: 'value-position';
+    token: string;
+} | {
+    reason: 'mixed-scope';
+    token: string;
+    global: string;
+    other: string;
+};
+/** One registration: the class it names, read as the prototype and the name that class holds. */
+interface Registration {
+    name: string;
+    prototype: unknown;
+    render: (failure: LoomError) => unknown;
+}
+/** Phantom key. It marks a failure registration and holds no runtime value. */
+declare const failureRegistration: unique symbol;
+/** The runtime value `renderFailure` returns. Its pair lives in the registry above. */
+declare class RegisteredFailure {
+    readonly [failureRegistration]: true;
+    constructor(registration: Registration);
+}
+/** 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 same subject at the start of a sentence. */
+export declare function commandSentence(name: string | null): string;
+/**
+ * Every failure `run()` reports is an instance of a public class. Each class carries the facts its
+ * sentence interpolates, so a renderer 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 renderers add it.
+ */
+export declare abstract class LoomError extends Error {
+    readonly exitCode: 1 | 2;
+    constructor(message: string, exitCode: 1 | 2);
+}
+/** Exit 2: the invocation, not the application, is wrong. */
+export declare abstract class UsageError extends LoomError {
+    constructor(message: string);
+}
+/** One input the validation phase rejected: an omission, or a value its schema refused. */
+export type InputProblem = {
+    input: InputIdentity;
+    spelling: string;
+    reason: 'missing';
+} | {
+    input: InputIdentity;
+    spelling: string;
+    reason: 'invalid';
+    issues: readonly StandardSchemaV1.Issue[];
+};
+/** 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[]);
+}
+export declare class UnknownCommandError extends UsageError {
+    readonly token: string;
+    readonly candidates: readonly string[];
+    constructor(token: string, candidates: readonly string[]);
+}
+/** A group answers no invocation of its own, so the routed path names no callable Command. */
+export declare class NonCallableCommandError extends UsageError {
+    readonly command: readonly string[];
+    readonly candidates: readonly string[];
+    constructor(command: readonly string[], candidates: readonly string[]);
+}
+export declare class UnexpectedArgumentError extends UsageError {
+    readonly command: readonly string[];
+    readonly accepted: number;
+    readonly extra: readonly string[];
+    constructor(command: readonly string[], accepted: number, extra: readonly string[]);
+}
+export declare class UnknownOptionError extends UsageError {
+    readonly spelling: string;
+    constructor(spelling: string);
+}
+export declare class MissingValueError extends UsageError {
+    readonly spelling: string;
+    constructor(spelling: string);
+}
+/** A Boolean spelling takes no value, so the token carried one the declaration cannot accept. */
+export declare class UnexpectedValueError extends UsageError {
+    readonly spelling: string;
+    readonly value: string;
+    constructor(spelling: string, value: string);
+}
+export declare class RepeatedOptionError extends UsageError {
+    readonly spelling: string;
+    constructor(spelling: string);
+}
+export declare class ShortGroupError extends UsageError {
+    readonly token: string;
+    readonly reason: 'value-position' | 'mixed-scope';
+    constructor(fault: ShortGroupFault);
+}
+/** Exit 1: the declaration is wrong, so the author reads the diagnostic. */
+export declare class DeclarationError extends LoomError {
+    constructor(message: string);
+}
+/** Exit 1: the application ended the invocation itself. An application may subclass it. */
+export declare class FatalError extends LoomError {
+    constructor(message: string);
+}
+/** Exit 1: an unexpected exception, a non-error throw, or a renderer that could not answer. */
+export declare class InternalError extends LoomError {
+    readonly cause: unknown;
+    constructor(message: string, cause: unknown);
+}
+/** What a diagnostic says about an unexpected value, whether or not it was an Error. */
+export declare function reasonOf(thrown: unknown): string;
+/**
+ * Why a returned value is not the text a renderer owes. A renderer 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.
+ */
+export declare function notTextReason(value: unknown): string;
+/** Every thrown value reaches reporting as a failure class; anything else is internal. */
+export declare function toFailure(thrown: unknown): LoomError;
+/** An opaque registration pairing one failure class with a renderer for its instances. */
+export type FailureRenderer = Pick<RegisteredFailure, typeof failureRegistration>;
+/**
+ * A registration pairing one failure class with a renderer for its instances. The helper is the
+ * typed path for a class-keyed list, because an array literal cannot carry a different type
+ * parameter per element.
+ */
+export declare function renderFailure<Failure extends LoomError>(type: abstract new (...args: never[]) => Failure, renderer: Renderer<Failure>): FailureRenderer;
+/** The renderers one application registered, keyed by the class each one names. */
+export type FailureRegistry = ReadonlyMap<unknown, Registration>;
+/** One class answers to one renderer, so a second registration for it is a declaration fault. */
+export declare function buildFailures(failures: readonly FailureRenderer[]): FailureRegistry;
+/**
+ * The report of one failure: the text core writes, and whether a registered renderer produced it.
+ * An unrendered report carries core's own text, which the plain fallback path writes beside the
+ * diagnostic naming the renderer that could not answer.
+ */
+export type FailureReport = {
+    kind: 'rendered';
+    text: string;
+} | {
+    kind: 'unrendered';
+    text: string;
+    reason: string;
+};
+/**
+ * The text core writes for one failure. Resolution walks the failure's prototype chain most
+ * derived first through the application's registrations, then falls to core's own text, so a
+ * registration for a base class brands every failure below it.
+ */
+export declare function describeFailure(registry: FailureRegistry, failure: LoomError): FailureReport;
+export {};