@loomcli/core 0.5.0 → 0.6.0

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;

package/dist/validation.d.ts

@@ -1,4 +1,6 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { Finding } from './diagnostic-text.js';
+import type { InputSite } from './facts.js';
 import type { OptionValues } from './options.js';
 import type { ArgumentConfig, ArgumentValue, Host, OptionConfig, OptionValue } from './types.js';
 /**
@@ -73,12 +75,43 @@ declare class ValidatedInputs {
     read(input: InputDeclaration): unknown;
 }
 export type { ValidatedInputs };
+/**
+ * The one check every `argument()`, `option()`, and `globalOption()` call makes before it reads its
+ * config, so a call in JavaScript that supplies none, or a value of another kind, reports a
+ * declaration fault and not a TypeError. `place` is where the call sits.
+ */
+export declare function checkInputConfig(declared: {
+    readonly config: unknown;
+    readonly kind: InputDeclaration['kind'];
+    readonly name: string;
+}, place: InputPlace): void;
 /**
  * Authoring's snapshot of one config. An array default is the one declared value core hands to an
  * action as its own value, so the declaration keeps a copy and the caller keeps its array. Every
  * other property is captured as declared, because core clones no library object.
  */
 export declare function captureConfig<Config extends ArgumentConfig | OptionConfig>(config: Config): Config;
+/**
+ * A declaration error names the declaration, because the author reads the declaration to fix it.
+ * An argument declares and reads under one name, so the two namings differ for options alone.
+ */
+export declare function declarationSubject(input: InputDeclaration): string;
+/** Where the call that declared one input sits: the call's name and the Command it is on. */
+export type InputPlace = Pick<Finding, 'call' | 'path'>;
+/**
+ * Where one input was declared: a global option at its `globalOption()` call, and every other input
+ * at its own `argument()` or `option()` call on the Command at `path`.
+ */
+export declare function inputPlace(input: InputDeclaration, scope: {
+    readonly global: boolean;
+    readonly path: readonly string[];
+}): InputPlace;
+/**
+ * The site of the call that declared one input at `place`, rebuilt as `call(name, config)`. Every
+ * finding for an input's own call starts from it, so each marks the call the same way. `subject`
+ * is the sentence's name for the input.
+ */
+export declare function declaringSite(input: InputDeclaration, place: InputPlace, subject?: string): InputSite;
 /**
  * The declaration flag that sends an omitted value to its own validator. Every declaration reads it
  * here, and the declaration rules below reject it wherever another rule already decides absence.
@@ -90,6 +123,11 @@ export declare function validatesOmission(input: InputDeclaration): boolean;
  * helper, so a rejected item reads alike wherever its diagnostic is written.
  */
 export declare function issuePath(issue: StandardSchemaV1.Issue): string | undefined;
+/** One declaration and where it was declared, which its faults' findings rebuild. */
+export interface SitedInput {
+    readonly input: InputDeclaration;
+    readonly site: InputSite;
+}
 /**
  * Every declaration rule that reads the declaration alone. It is synchronous, so the call that
  * declares an input applies it, and build applies it to an input a lifecycle hook declared; only
@@ -97,10 +135,13 @@ export declare function issuePath(issue: StandardSchemaV1.Issue): string | undef
  * contributor that declares under its own name, such as a plugin, supplies the subject its
  * diagnostics read with; every other caller is named by the declaration itself.
  */
-export declare function checkDeclarations(inputs: readonly InputDeclaration[], named?: string): void;
+export declare function checkDeclarations(inputs: readonly SitedInput[], named?: string): void;
+/** The call that declared one input and the Command it sits on, which a default's fault rebuilds. */
+export type InputPlaces = ReadonlyMap<InputDeclaration, InputPlace>;
 /**
  * Every declared default, validated before any token is read. The host is captured by then, so a
- * default's validator reads the same Host its action will, under the `default` phase.
+ * default's validator reads the same Host its action will, under the `default` phase. `places`
+ * says where each declaration sits, which a rejected default's finding rebuilds.
  */
-export declare function prepareInputs(inputs: ScopedInputs, host: Host): Promise<DefaultValues>;
+export declare function prepareInputs(inputs: ScopedInputs, host: Host, places: InputPlaces): Promise<DefaultValues>;
 export declare function validateValues(invocation: Invocation): Promise<ValidatedInputs>;