@loomcli/core 0.5.0 → 0.6.0

package/dist/validation.js

@@ -1,6 +1,12 @@
 import { schemaOptions } from './context.js';
-import { DeclarationError, InputError } from './errors.js';
+import { escapeControlCharacters } from './controls.js';
+import { asSentence, DeclarationError, InputError, quoted, reasonOf } from './errors.js';
+import { callSite, factFault, flagFault, partOf, siteFinding } from './facts.js';
+import { booleanOptionValueRule, defaultShape, invalidDefault, notAValidator, omissionAlreadyDecided, omissionWithoutValidator, requiredWithDefault, } from './input-rules.js';
 import { booleanValue } from './options.js';
+import { isPlainObject } from './plain.js';
+import { notAnObject } from './plugin-rules.js';
+import { validatorFailed } from './rules.js';
 /** Every declaration in validation order: the globals first, then the reading Command's own. */
 function scoped(inputs) {
     return [
@@ -46,6 +52,27 @@ class ValidatedInputs {
         return { [input.name]: this.#values.get(input) };
     }
 }
+/**
+ * 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 function checkInputConfig(declared, place) {
+    const { config, kind, name } = declared;
+    if (isPlainObject(config)) {
+        return;
+    }
+    const subject = kind === 'argument' ? 'Argument' : 'Option';
+    const site = callSite(`${subject} ${quoted(name)}`, {
+        arguments: [name, config],
+        ...place,
+    });
+    throw new DeclarationError(notAnObject, {
+        correction: `Supply ${kind === 'argument' ? 'an argument' : 'an option'} config object, such as ${kind === 'argument' ? '{}' : "{ type: 'string' }"}.`,
+        findings: [siteFinding(site, '1')],
+        sentence: `${site.subject} declares a config that is not an object.`,
+    });
+}
 /**
  * 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
@@ -59,8 +86,25 @@ export function captureConfig(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.
  */
-function declaredName(input) {
-    return input.kind === 'argument' ? `Argument "${input.name}"` : `Option "${input.name}"`;
+export function declarationSubject(input) {
+    return input.kind === 'argument'
+        ? `Argument ${quoted(input.name)}`
+        : `Option ${quoted(input.name)}`;
+}
+/**
+ * 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 function inputPlace(input, scope) {
+    return scope.global ? { call: 'globalOption', path: [] } : { call: input.kind, path: scope.path };
+}
+/**
+ * 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 function declaringSite(input, place, subject = declarationSubject(input)) {
+    return callSite(subject, { arguments: [input.name, input.config], ...place });
 }
 /**
  * The token an operator would type for one declaration: `--file` for an option, `-F` when the
@@ -143,61 +187,88 @@ function holdsRawDefault(input) {
  * rule that already decides absence rejects it, and the flag needs a validator to receive the
  * omission.
  */
-function checkOmissionValidation(input, subject) {
+function checkOmissionValidation(input, site, subject) {
     const { config } = input;
+    const decided = (sentence, correction) => factFault(omissionAlreadyDecided, site, { correction, fact: 'validateOmitted', sentence });
     if (config.required) {
-        throw new DeclarationError(`${subject} is required and declares validateOmitted. Remove validateOmitted or make the input optional.`);
+        throw decided(`${subject} is required and declares validateOmitted.`, 'Remove validateOmitted or make the input optional.');
     }
     if (hasDefault(input)) {
-        throw new DeclarationError(`${subject} declares a default and validateOmitted. Remove one; the default already fills an omitted value.`);
+        throw decided(`${subject} declares a default and validateOmitted.`, 'Remove one; the default already fills an omitted value.');
     }
     if (collects(input)) {
-        throw new DeclarationError(`${subject} takes several values and declares validateOmitted. Remove validateOmitted; with no values the action receives an empty array and no validator runs.`);
+        throw decided(`${subject} takes several values and declares validateOmitted.`, 'Remove validateOmitted; with no values the action receives an empty array and no validator runs.');
     }
     if (config.validate === undefined) {
-        throw new DeclarationError(`${subject} declares validateOmitted without a validator. Add validate or remove validateOmitted.`);
+        throw factFault(omissionWithoutValidator, site, {
+            correction: 'Add validate or remove validateOmitted.',
+            fact: 'validateOmitted',
+            sentence: `${subject} declares validateOmitted without a validator.`,
+        });
     }
 }
-function checkDeclaration(input, subject) {
+/** The value rules a Boolean option may not declare, in the order its diagnostic names them. */
+const valueRules = ['validate', 'default', 'required', 'validateOmitted'];
+/** Whether a `validate` value is a Standard Schema v1 object that core can call. */
+function isStandardSchema(validator) {
+    if (validator === null || (typeof validator !== 'object' && typeof validator !== 'function')) {
+        return false;
+    }
+    const props = Reflect.get(validator, '~standard');
+    return (typeof props === 'object' &&
+        props !== null &&
+        Reflect.get(props, 'version') === 1 &&
+        typeof Reflect.get(props, 'vendor') === 'string' &&
+        typeof Reflect.get(props, 'validate') === 'function');
+}
+function checkDeclaration(input, site, subject) {
     const { config } = input;
     if (input.kind === 'option' && input.config.type === 'boolean') {
-        if ('validate' in config ||
-            'default' in config ||
-            'required' in config ||
-            'validateOmitted' in config) {
-            throw new DeclarationError(`${subject} is Boolean. Remove validate, default, required, and validateOmitted; use polarity to control its absent value.`);
+        const declared = valueRules.find((key) => key in config);
+        if (declared !== undefined) {
+            throw factFault(booleanOptionValueRule, site, {
+                correction: `Remove ${declared}; use polarity to control its absent value.`,
+                fact: declared,
+                sentence: `${subject} is Boolean and declares ${declared}.`,
+            });
         }
         return;
     }
     if (config.required !== undefined && typeof config.required !== 'boolean') {
-        throw new DeclarationError(`${subject} required must be Boolean. Use true or false.`);
+        throw flagFault(site, 'required');
     }
     if (input.kind === 'argument' &&
         input.config.variadic !== undefined &&
         typeof input.config.variadic !== 'boolean') {
-        throw new DeclarationError(`${subject} variadic must be Boolean. Use true or false.`);
+        throw flagFault(site, 'variadic');
     }
     // The test reads presence, not truth, so a declared `undefined` is a declaration to reject.
     if ('validateOmitted' in config && typeof config.validateOmitted !== 'boolean') {
-        throw new DeclarationError(`${subject} validateOmitted must be Boolean. Use true or false.`);
+        throw flagFault(site, 'validateOmitted');
     }
     if (config.required && Object.hasOwn(config, 'default')) {
-        throw new DeclarationError(`${subject} is required and declares a default. Remove the default or make the input optional.`);
+        throw factFault(requiredWithDefault, site, {
+            correction: 'Remove the default or make the input optional.',
+            fact: 'default',
+            sentence: `${subject} is required and declares a default.`,
+        });
     }
     if (validatesOmission(input)) {
-        checkOmissionValidation(input, subject);
+        checkOmissionValidation(input, site, subject);
     }
-    const validator = config.validate;
-    if (validator !== undefined &&
-        (validator === null ||
-            (typeof validator !== 'object' && typeof validator !== 'function') ||
-            !validator['~standard'] ||
-            validator['~standard'].version !== 1 ||
-            typeof validator['~standard'].vendor !== 'string' ||
-            typeof validator['~standard'].validate !== 'function')) {
-        throw new DeclarationError(`${subject} validate must be a Standard Schema v1 object. Supply a compatible validator.`);
+    if (config.validate !== undefined && !isStandardSchema(config.validate)) {
+        throw factFault(notAValidator, site, {
+            correction: 'Supply a compatible validator.',
+            fact: 'validate',
+            sentence: `${subject} validate must be a Standard Schema v1 object.`,
+        });
     }
 }
+/**
+ * One issue a validator returned, checked where it enters. Core keeps every own enumerable field
+ * the issue carries and rewrites only `path`, reducing each segment to its key, so a field core
+ * never reads, such as a validator's issue code, reaches a failure view unchanged.
+ */
 function readIssue(issue) {
     if (issue === null || typeof issue !== 'object' || !('message' in issue)) {
         throw new Error('The validator returned an invalid Standard Schema issue.');
@@ -208,7 +279,7 @@ function readIssue(issue) {
     }
     const suppliedPath = 'path' in issue ? issue.path : undefined;
     if (suppliedPath === undefined) {
-        return { message };
+        return { ...issue, message };
     }
     if (!Array.isArray(suppliedPath)) {
         throw new Error('The validator returned an invalid Standard Schema issue path.');
@@ -220,13 +291,15 @@ function readIssue(issue) {
         }
         return key;
     });
-    return { message, path };
+    return { ...issue, message, path };
 }
 /**
  * A broken validator is a fault in the declaration, whichever value reached it, so its diagnostic
- * names the declaration. Returned issues belong to the value, so the caller names those.
+ * names the declaration and its finding marks the validator on the call at `place`. Returned issues
+ * belong to the value, so the caller names those.
  */
-async function validate(input, raw, context) {
+async function validate(input, raw, call) {
+    const { context, place } = call;
     const validator = input.config.validate;
     if (validator === undefined) {
         return { value: raw };
@@ -246,8 +319,13 @@ async function validate(input, raw, context) {
         return { issues: Array.from(issues, readIssue) };
     }
     catch (error) {
-        const reason = error instanceof Error ? error.message : 'Unknown validator failure.';
-        throw new DeclarationError(`${declaredName(input)} validator failed unexpectedly: ${reason} Fix the validator.`);
+        // The reason is the author's detail: a distributed build shows the generic defect message.
+        const site = place === undefined ? undefined : declaringSite(input, place);
+        throw new DeclarationError(validatorFailed, {
+            correction: 'Fix the validator.',
+            findings: site === undefined ? [] : [siteFinding(site, partOf(site, 'validate'))],
+            sentence: `${declarationSubject(input)} validator failed unexpectedly: ${asSentence(reasonOf(error))}`,
+        }, { cause: error });
     }
 }
 /**
@@ -258,13 +336,13 @@ async function validate(input, raw, context) {
  * next call. The host is the one captured object that every call and the action share.
  */
 async function validateDeclared(input, raw, call) {
-    const { context, signal } = call;
+    const { context, place, signal } = call;
     if (!collects(input) || input.config.validate === undefined) {
-        return validate(input, raw, context());
+        return validate(input, raw, { context: context(), place });
     }
     if (!Array.isArray(raw)) {
         // The parser, the input sources, and the declaration rules only ever supply an array here.
-        throw new TypeError(`${declaredName(input)} reached validation without an array of values.`);
+        throw new TypeError(`${declarationSubject(input)} reached validation without an array of values.`);
     }
     const outputs = [];
     const issues = [];
@@ -273,15 +351,15 @@ async function validateDeclared(input, raw, call) {
             // A cancelled run starts no further call; the run resolves its cancellation code instead.
             break;
         }
-        const result = await validate(input, value, context());
+        const result = await validate(input, value, { context: context(), place });
         if (result.issues === undefined) {
             outputs.push(result.value);
         }
         else {
-            issues.push(...reported(result.issues).map((issue) => ({
-                message: issue.message,
-                path: [position, ...(issue.path ?? [])],
-            })));
+            // The issue keeps its own fields, and only its path gains the value's position.
+            for (const issue of reported(result.issues)) {
+                issues.push({ ...issue, path: [position, ...(issue.path ?? [])] });
+            }
         }
     }
     return issues.length === 0 ? { value: outputs } : { issues };
@@ -304,23 +382,33 @@ export function issuePath(issue) {
  */
 function reported(issues) {
     return issues.length === 0
-        ? [{ message: 'The validator rejected this value without an explanation.' }]
+        ? [
+            {
+                message: 'The validator rejected this value without an explanation. Supply a different value.',
+            },
+        ]
         : issues;
 }
+/**
+ * One line per issue under the input's subject. A path segment can hold text the operator typed,
+ * such as a key of a record, so the line escapes the path; `issuePath` keeps it raw for a view.
+ */
 function messages(subject, issues) {
     return issues.map((issue) => {
         const path = issuePath(issue);
-        return `${subject}${path === undefined ? '' : ` at ${path}`}: ${issue.message}`;
+        const position = path === undefined ? '' : ` at ${escapeControlCharacters(path)}`;
+        return `${subject}${position}: ${issue.message}`;
     });
 }
 /** The fault a default of the wrong raw shape reports, by the shape its declaration expects. */
-function defaultShapeFault(input, subject) {
+function defaultShapeFault(input, site, subject) {
+    const fault = (sentence, correction) => factFault(defaultShape, site, { correction, fact: 'default', sentence });
     if (!collects(input)) {
-        return `${subject} default must be a string without a validator. Supply a string default.`;
+        return fault(`${subject} default must be a string without a validator.`, 'Supply a string default.');
     }
     return input.config.validate === undefined
-        ? `${subject} default must be an array of strings without a validator. Supply a string array default.`
-        : `${subject} default must be an array. Supply an array of values.`;
+        ? fault(`${subject} default must be an array of strings without a validator.`, 'Supply a string array default.')
+        : fault(`${subject} default must be an array.`, 'Supply an array of values.');
 }
 /** A declared `default: undefined` is a default, so presence is the key, never the value. */
 function hasDefault(input) {
@@ -334,31 +422,41 @@ function hasDefault(input) {
  * diagnostics read with; every other caller is named by the declaration itself.
  */
 export function checkDeclarations(inputs, named) {
-    for (const input of inputs) {
-        checkDeclaration(input, named ?? declaredName(input));
+    for (const { input, site } of inputs) {
+        checkDeclaration(input, site, named ?? declarationSubject(input));
     }
-    for (const input of inputs.filter((entry) => hasDefault(entry))) {
+    for (const { input, site } of inputs.filter((entry) => hasDefault(entry.input))) {
         if (!holdsRawDefault(input)) {
-            const subject = named ?? declaredName(input);
-            throw new DeclarationError(defaultShapeFault(input, subject));
+            throw defaultShapeFault(input, site, named ?? declarationSubject(input));
         }
     }
 }
 /**
  * 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 async function prepareInputs(inputs, host) {
+export async function prepareInputs(inputs, host, places) {
     const declarations = scoped(inputs);
     const defaults = new Map();
     for (const entry of declarations.filter(({ input }) => hasDefault(input))) {
         const { input } = entry;
-        const subject = declaredName(input);
+        const subject = declarationSubject(input);
+        const place = places.get(input);
         const result = await validateDeclared(input, input.config.default, {
             context: () => ({ host, input: identityOf(entry), phase: 'default' }),
+            place,
         });
         if (result.issues !== undefined) {
-            throw new DeclarationError(`${subject} has an invalid default. Fix the default or its validator.\n${messages(subject, reported(result.issues)).join('\n')}`);
+            const site = place === undefined ? undefined : declaringSite(input, place);
+            throw new DeclarationError(invalidDefault, {
+                correction: 'Fix the default or its validator.',
+                findings: site === undefined ? [] : [siteFinding(site, partOf(site, 'default'))],
+                sentence: [
+                    `${subject} has an invalid default.`,
+                    ...messages(subject, reported(result.issues)),
+                ].join('\n'),
+            });
         }
         defaults.set(input, result.value);
     }
@@ -461,6 +559,7 @@ export async function validateValues(invocation) {
     const accept = async (entry, raw, spelling) => {
         const result = await validateDeclared(entry.input, raw, {
             context: () => contextOf(entry),
+            place: inputPlace(entry.input, { global: entry.global, path: invocation.command }),
             signal: invocation.signal,
         });
         if (result.issues === undefined) {

package/dist/view.d.ts

@@ -39,11 +39,32 @@ type AnyDeclaredView = (View<never> | RowView<never>) & DeclaredViewBrand & {
 /** A failure class as an override key, so `UsageError` and an application's subclass both fit. */
 type FailureClass<Failure extends LoomError> = abstract new (...args: never[]) => Failure;
 /**
- * One stored view function, with the data type erased. A registry holds one entry per key and
- * cannot carry a type parameter per entry, so `override(key, replacement)` is where the
- * replacement is typed against the key it answers.
+ * What every failure view reads: the stderr view context, where the run was, and the hints the
+ * installed plugins' `onFailure` hooks returned. `run()` fills it where it catches the failure, so
+ * no failure class carries these facts. `path` holds the canonical names routing walked, `[]`
+ * before routing, and `hints` is `[]` when no hook contributed.
  */
-type ViewFunction = (data: never, context: ViewContext) => unknown;
+interface FailureViewContext extends ViewContext {
+    readonly application: string;
+    readonly path: readonly string[];
+    readonly hints: readonly string[];
+}
+/**
+ * A failure class's view. A `View<Failure>` written against `ViewContext` is assignable to it,
+ * because its function reads less of the context.
+ */
+interface FailureView<Failure extends LoomError> {
+    render: (failure: Readonly<Failure>, context: FailureViewContext) => string;
+    /** A failure view has one shape, as a view does. */
+    row?: never;
+}
+/**
+ * One stored view function, with the data type and the context erased. A registry holds one entry
+ * per key and cannot carry a type parameter per entry, so `override(key, replacement)` is where the
+ * replacement is typed against the key it answers: a failure class's view reads the failure view
+ * context, and every other view reads the view context.
+ */
+type ViewFunction = (data: never, context: never) => unknown;
 /** One stored row function, with the row type erased for the same reason. */
 type RowFunction = (row: never, index: number, context: ViewContext) => unknown;
 /** One stored function that opens a sequence and reads the context alone. */
@@ -114,7 +135,7 @@ declare function override<Data>(key: DeclaredView<Data>, replacement: NoInfer<Vi
 declare function override<Row>(key: DeclaredRowView<Row>, replacement: NoInfer<RowView<Row>>): ViewOverride;
 declare function override<Failure extends LoomError>(key: FailureClass<Failure> & {
     readonly [declaredView]?: never;
-}, replacement: NoInfer<View<Failure>>): ViewOverride;
+}, replacement: NoInfer<FailureView<Failure>>): ViewOverride;
 /** One contributor's overrides, read once per build and consulted in contributor order. */
 interface ViewContributions {
     failures: Map<unknown, StoredView>;
@@ -127,13 +148,20 @@ interface ViewContributions {
 type ViewRegistry = readonly ViewContributions[];
 /** The identities one build has met, so a second object under one identity is visible. */
 type ViewIdentities = Map<string, AnyDeclaredView>;
-/** How one contributor's diagnostics name it, and whether its list may declare a view. */
+/**
+ * How one contributor's diagnostics name it, whether its list may declare a view, and the call
+ * that declared the list, `plugin(identity, …)` or `new Application(name, …)`, which a fault marks.
+ */
 interface ViewSubject {
     /** A plugin declares views beside its overrides; an application overrides alone. */
     declares: boolean;
     sentence: string;
+    owner: {
+        call: string;
+        named: unknown;
+    };
 }
-/** The identity register one build starts from, holding the views core itself declares. */
+/** The identity one build starts from, holding the views core itself declares. */
 declare function viewIdentities(declared: readonly AnyDeclaredView[]): ViewIdentities;
 /**
  * One contributor's own overrides, with the identity of every declared view it lists or names as a
@@ -158,23 +186,29 @@ interface ResolvedRowView<Row> {
  */
 declare function resolveRowView<Row>(registry: ViewRegistry, value: RowView<Row>): ResolvedRowView<Row>;
 /**
- * The report of one failure: the text core writes, and whether a view produced it. An unrendered
- * report carries core's own text, which the plain fallback path writes beside the diagnostic
- * naming the view that could not answer.
+ * The report of one failure: the text core writes, and whether a view produced it. A rendered
+ * report says whether core's own default text answered, which for a defect is the generic defect
+ * message. An unrendered report carries core's own text, which the plain fallback path writes
+ * beside the diagnostic naming the view that could not answer, and what the view threw.
  */
 type FailureReport = {
     kind: 'rendered';
     text: string;
+    core: boolean;
 } | {
     kind: 'unrendered';
     text: string;
     reason: string;
+    cause: unknown;
 };
 /**
  * The text core writes for one failure. Resolution walks the registry as `resolveFailure` defines
- * it and falls to core's own default text, which escapes the raw facts it interpolates. A
- * `FatalError` keeps the authored marked message it was given.
+ * it and falls to core's own default text, which opens a usage failure with the context's
+ * application name and escapes the raw facts it interpolates. A `FatalError` keeps the authored
+ * marked message it was given. The default text writes each hint on its own line under the
+ * sentence, as marked text it does not escape; an override decides for itself. An unrendered report
+ * carries the same default text without hints, which the plain fallback path writes.
  */
-declare function describeFailure(registry: ViewRegistry, failure: LoomError, context?: ViewContext): FailureReport;
-export type { AnyDeclaredView, DeclaredRowView, DeclaredView, DeclaredViewBrand, FailureClass, FailureReport, ResolvedRowView, ViewContribution, ViewContributions, ViewIdentities, ViewOverride, ViewRegistry, ViewShape, };
+declare function describeFailure(registry: ViewRegistry, failure: LoomError, context: FailureViewContext): FailureReport;
+export type { AnyDeclaredView, DeclaredRowView, DeclaredView, DeclaredViewBrand, FailureClass, FailureReport, FailureView, FailureViewContext, ResolvedRowView, ViewContribution, ViewContributions, ViewSubject, ViewIdentities, ViewOverride, ViewRegistry, ViewShape, };
 export { buildViews, describeFailure, override, resolveRowView, resolveView, shapeOf, view, viewIdentities, };