@loomcli/core 0.4.0 → 0.6.0

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. */
@@ -78,7 +99,7 @@ declare function view<Data>(identity: string, definition: View<Data>): DeclaredV
 declare function view<Row>(identity: string, definition: RowView<Row>): DeclaredRowView<Row>;
 /**
  * What one override replaces: a declared view, a failure class read as its prototype, or a value
- * that is neither, which build reports as the entry fault of the list that holds it.
+ * that is neither, which the list that holds it reports as its entry fault.
  */
 type OverrideKey = {
     kind: 'view';
@@ -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, };

package/dist/view.js

@@ -1,4 +1,10 @@
-import { DeclarationError, defaultText, FatalError, notTextReason, reasonOf } from './errors.js';
+import { viewShape } from './command-rules.js';
+import { elided, quoteString, spelled } from './diagnostic-text.js';
+import { DeclarationError, defaultText, FatalError, notTextReason, quoted, reasonOf, } from './errors.js';
+import { partFinding, slotSite } from './facts.js';
+import { checkIdentity } from './identity.js';
+import { foreignValue, notAList, overrideKey, overrideTwice, twoPackageCopies, } from './plugin-rules.js';
+import { prototypeChain } from './prototypes.js';
 import { escapeText } from './style.js';
 /** Authored declarations register here, so a hand-built object with an identity is a bare view. */
 const declarations = new WeakMap();
@@ -48,12 +54,22 @@ function shapeOf(value) {
     return render ? 'render' : 'neither';
 }
 function view(identity, definition) {
+    checkIdentity('view', identity);
     const shape = shapeOf(definition);
+    const findings = [{ arguments: [identity, definition], call: 'view', mark: '1' }];
     if (shape === 'both') {
-        throw new DeclarationError(`View "${identity}" carries render and row. Supply one of the two.`);
+        throw new DeclarationError(viewShape, {
+            correction: 'Supply one of the two.',
+            findings,
+            sentence: `View ${quoted(identity)} carries render and row.`,
+        });
     }
     if (shape === 'neither') {
-        throw new DeclarationError(`View "${identity}" carries neither render nor row. Supply a view with render or a row view with row.`);
+        throw new DeclarationError(viewShape, {
+            correction: 'Supply a view with render or a row view with row.',
+            findings,
+            sentence: `View ${quoted(identity)} carries neither render nor row.`,
+        });
     }
     return typeof definition.row === 'function'
         ? new RowViewDeclaration(identity, definition)
@@ -83,8 +99,8 @@ function override(key, replacement) {
 }
 /**
  * The key one failure-class override answers. A class is a function whose `prototype` is the
- * object a thrown failure's chain holds, so anything else is no key at all and build reports it as
- * the entry fault of the list that holds it, rather than colliding with every other such value.
+ * object a thrown failure's chain holds, so anything else is no key at all and the list that holds
+ * it reports it as its entry fault, rather than colliding with every other such value.
  */
 function failureKey(key) {
     if (typeof key !== 'function' || !('prototype' in key)) {
@@ -97,7 +113,7 @@ function failureKey(key) {
     const name = 'name' in key && typeof key.name === 'string' && key.name !== '' ? key.name : 'a failure class';
     return { kind: 'failure', name, prototype };
 }
-/** 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. */
 function viewIdentities(declared) {
     const identities = new Map();
     for (const value of declared) {
@@ -105,22 +121,63 @@ function viewIdentities(declared) {
     }
     return identities;
 }
-/** One identity means one declared view, wherever on the graph that view appears. */
-function registerIdentity(identities, declared) {
+/**
+ * One identity means one declared view, wherever on the graph that view appears. `place` marks the
+ * list entry that names the view, when one does.
+ */
+function registerIdentity(identities, declared, place) {
     const known = identities.get(declared.identity);
     if (known === undefined) {
         identities.set(declared.identity, declared);
         return;
     }
     if (known !== declared) {
-        throw new DeclarationError(`View "${declared.identity}" is declared by two distinct objects. Install one copy of the package that declares it.`);
+        throw new DeclarationError(twoPackageCopies, {
+            correction: 'Install one copy of the package that declares it.',
+            findings: place === undefined ? [] : [{ ...place, note: `another ${quoted(declared.identity)}` }],
+            sentence: `View ${quoted(declared.identity)} is declared by two distinct objects.`,
+        });
     }
 }
-/** The sentence one contributor's list reports for a value it cannot read. */
-function entryFault(subject) {
+/** A name JavaScript source can spell as an identifier, which a finding prints a class key as. */
+const identifier = /^[A-Za-z_$][\w$]*$/u;
+/** How a finding prints an override's key: a failure class by its name, anything else elided. */
+function keyCode(key) {
+    return key.kind === 'failure' && identifier.test(key.name) ? key.name : elided;
+}
+/**
+ * One list entry as a finding prints it: a declared view as the `view()` call that made it, an
+ * override as its `override()` call, and any other value as it is.
+ */
+function entryCode(entry) {
+    if (typeof entry !== 'object' || entry === null) {
+        return entry;
+    }
+    const listed = declarations.get(entry);
+    if (listed) {
+        return spelled(`view(${quoteString(listed.identity)}, ${elided})`);
+    }
+    const record = overrides.get(entry);
+    return record ? spelled(`override(${keyCode(record.key)}, ${elided})`) : entry;
+}
+/** Where one contributor's `views` list sits, with each entry printed as the call that made it. */
+function listSite(subject, declared) {
+    const views = Array.isArray(declared) ? Array.from(declared, entryCode) : declared;
+    return slotSite({ ...subject.owner, subject: subject.sentence }, 'views', views);
+}
+/** The fault of one list entry that is not a value this contributor's list may hold. */
+function entryFault(subject, place) {
     return subject.declares
-        ? `${subject.sentence} holds a value that is not a view. Supply the value returned by view(identity, definition) or override(key, view).`
-        : `${subject.sentence} holds a value that is not a view override. Supply the value returned by override(key, view).`;
+        ? new DeclarationError(foreignValue, {
+            correction: 'Supply the value returned by view(identity, definition) or override(key, view).',
+            findings: [place],
+            sentence: `${subject.sentence} holds a value that is not a view.`,
+        })
+        : new DeclarationError(foreignValue, {
+            correction: 'Supply the value returned by override(key, view).',
+            findings: [place],
+            sentence: `${subject.sentence} holds a value that is not a view override.`,
+        });
 }
 /** A `views` slot holds a list, so anything else is the same declaration fault. */
 function readContributions(subject, declared) {
@@ -128,50 +185,80 @@ function readContributions(subject, declared) {
         return [];
     }
     if (!Array.isArray(declared)) {
-        throw new DeclarationError(subject.declares
-            ? `${subject.sentence} declares views that are not an array. Supply a list of declared views and override values.`
-            : entryFault(subject));
+        throw new DeclarationError(notAList, {
+            correction: subject.declares
+                ? 'Supply a list of declared views and override values.'
+                : 'Supply a list of override values.',
+            findings: [partFinding(listSite(subject, declared), [])],
+            sentence: `${subject.sentence} declares views that are not an array.`,
+        });
     }
     return declared;
 }
-/** The override one entry carries; anything else is a declaration fault of the slot. */
-function overrideOf(subject, entry) {
-    const record = typeof entry === 'object' && entry !== null ? overrides.get(entry) : undefined;
-    if (!record) {
-        throw new DeclarationError(entryFault(subject));
+/**
+ * The entry a key's first override sits at, recording this one's when it is the first. One key
+ * answers to one override inside one contributor, so a second override marks both entries.
+ */
+function claimKey(build, key, index) {
+    const slot = key.kind === 'failure' ? key.prototype : key.view;
+    const first = build.positions.get(slot);
+    if (first === undefined) {
+        build.positions.set(slot, index);
+        return;
     }
-    return record;
+    const clause = key.kind === 'failure'
+        ? `the view for ${quoted(key.name)}`
+        : `view ${quoted(key.view.identity)}`;
+    throw new DeclarationError(overrideTwice, {
+        correction: 'Remove one override.',
+        findings: [
+            partFinding(build.site, [first], 'the first override'),
+            partFinding(build.site, [index], 'the second override'),
+        ],
+        sentence: `${build.subject.sentence} overrides ${clause} twice.`,
+    });
 }
 /**
- * One override recorded under the key it answers. One key answers to one override inside one
- * contributor, so a second override for it is a declaration fault; the same key overridden by two
- * contributors resolves first-in-wins. A key that is neither a declared view nor a failure class
- * is the entry fault of the list that holds it, reported here rather than at the `override()` call.
+ * One override recorded under the key it answers. The same key overridden by two contributors
+ * resolves first-in-wins. A key that is neither a declared view nor a failure class is a fault of
+ * the list that holds it, reported here rather than at the `override()` call.
  */
-function recordOverride(build, { key, replacement }) {
+function recordOverride(build, { key, replacement }, index) {
     if (key.kind === 'invalid') {
-        throw new DeclarationError(entryFault(build.subject));
+        throw new DeclarationError(overrideKey, {
+            correction: 'Key the override on a value view(identity, definition) returned, or on a failure class.',
+            findings: [partFinding(build.site, [index])],
+            sentence: `${build.subject.sentence} overrides a key that is neither a declared view nor a failure class.`,
+        });
     }
+    claimKey(build, key, index);
     if (key.kind === 'failure') {
-        recordFailureOverride(build, key, replacement);
+        build.contributions.failures.set(key.prototype, replacement);
         return;
     }
-    recordViewOverride(build, key.view, replacement);
+    // Naming a declared view as a key registers its identity, as listing the declaration does.
+    registerIdentity(build.identities, key.view, partFinding(build.site, [index]));
+    build.contributions.views.set(key.view, replacement);
 }
-/** One failure class answers to one override inside one contributor, keyed by its prototype. */
-function recordFailureOverride({ contributions, subject }, key, replacement) {
-    if (contributions.failures.has(key.prototype)) {
-        throw new DeclarationError(`${subject.sentence} overrides the view for "${key.name}" twice. Remove one override.`);
+/**
+ * One entry of a contributor's list: a declared view, which only a plugin may list, or an
+ * override. Any other value is the list's entry fault.
+ */
+function recordEntry(build, entry, index) {
+    const { identities, site, subject } = build;
+    const place = partFinding(site, [index]);
+    const object = typeof entry === 'object' && entry !== null ? entry : undefined;
+    const listed = object === undefined ? undefined : declarations.get(object);
+    const record = object === undefined ? undefined : overrides.get(object);
+    if (listed && subject.declares) {
+        registerIdentity(identities, listed, place);
     }
-    contributions.failures.set(key.prototype, replacement);
-}
-/** Naming a declared view as a key registers its identity, as listing the declaration does. */
-function recordViewOverride({ contributions, identities, subject }, key, replacement) {
-    registerIdentity(identities, key);
-    if (contributions.views.has(key)) {
-        throw new DeclarationError(`${subject.sentence} overrides view "${key.identity}" twice. Remove one override.`);
+    else if (record) {
+        recordOverride(build, record, index);
+    }
+    else {
+        throw entryFault(subject, place);
     }
-    contributions.views.set(key, replacement);
 }
 /**
  * One contributor's own overrides, with the identity of every declared view it lists or names as a
@@ -180,17 +267,10 @@ function recordViewOverride({ contributions, identities, subject }, key, replace
  */
 function buildViews(subject, declared, identities) {
     const contributions = { failures: new Map(), views: new Map() };
-    for (const entry of readContributions(subject, declared)) {
-        const listed = typeof entry === 'object' && entry !== null ? declarations.get(entry) : undefined;
-        if (listed && !subject.declares) {
-            throw new DeclarationError(entryFault(subject));
-        }
-        if (listed) {
-            registerIdentity(identities, listed);
-        }
-        else {
-            recordOverride({ contributions, identities, subject }, overrideOf(subject, entry));
-        }
+    const site = listSite(subject, declared);
+    const build = { contributions, identities, positions: new Map(), site, subject };
+    for (const [index, entry] of readContributions(subject, declared).entries()) {
+        recordEntry(build, entry, index);
     }
     return contributions;
 }
@@ -198,9 +278,10 @@ function buildViews(subject, declared, identities) {
 function readStored(stored) {
     // Last resort: no typed path exists.
     // A registry holds one entry per key and cannot carry a type parameter per entry.
-    // A stored view value therefore reads back with its data type erased.
+    // A stored view value therefore reads back with its data type and its context erased.
     // It holds because `override(key, replacement)` typed the replacement against its key's data.
     // Resolution reaches a stored value through that key alone.
+    // A failure key is resolved by `describeFailure` alone, which passes the failure view context.
     // oxlint-disable-next-line typescript/no-unsafe-type-assertion
     return stored;
 }
@@ -217,16 +298,6 @@ function missing(name, key) {
 function callView(stored, key) {
     return readStored(stored).render ?? missing('render', key);
 }
-/** Every prototype in a failure's chain, most derived first, so one walk reads one contributor. */
-function chainOf(failure) {
-    const chain = [];
-    let prototype = Object.getPrototypeOf(failure);
-    while (prototype !== null) {
-        chain.push(prototype);
-        prototype = Object.getPrototypeOf(prototype);
-    }
-    return chain;
-}
 /**
  * The view function one declared view resolves to: the first contributor that overrides it, then
  * its own default. A bare view is never overridden, so it resolves to its own function.
@@ -267,7 +338,8 @@ function resolveRowView(registry, value) {
  * for a base class beats a plugin's override for a subclass.
  */
 function resolveFailure(registry, failure) {
-    const chain = chainOf(failure);
+    // A failure core reports has a readable chain, so the empty fallback only keeps the walk total.
+    const chain = prototypeChain(failure) ?? [];
     for (const contributor of registry) {
         for (const prototype of chain) {
             const replacement = contributor.failures.get(prototype);
@@ -278,30 +350,36 @@ function resolveFailure(registry, failure) {
     }
     return undefined;
 }
+/**
+ * Core's own default text for one failure, escaped unless it is the authored marked message of a
+ * `FatalError`, with each hint on its own line under it as marked text it does not escape.
+ */
+function coreText(failure, text, hints) {
+    const sentence = failure instanceof FatalError ? text : escapeText(text);
+    return `${sentence}${hints.map((hint) => `${hint}\n`).join('')}`;
+}
 /**
  * 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.
  */
 function describeFailure(registry, failure, context) {
+    const text = defaultText(failure, context.application);
     const replacement = resolveFailure(registry, failure);
     if (!replacement) {
-        return {
-            kind: 'rendered',
-            text: failure instanceof FatalError ? defaultText(failure) : escapeText(defaultText(failure)),
-        };
+        return { core: true, kind: 'rendered', text: coreText(failure, text, context.hints) };
     }
     try {
-        if (context === undefined) {
-            throw new Error('Missing rendering context.');
-        }
-        const text = callView(replacement, failure.name)(failure, context);
-        return typeof text === 'string'
-            ? { kind: 'rendered', text }
-            : { kind: 'unrendered', reason: notTextReason(text), text: defaultText(failure) };
+        const rendered = callView(replacement, failure.name)(failure, context);
+        return typeof rendered === 'string'
+            ? { core: false, kind: 'rendered', text: rendered }
+            : { cause: undefined, kind: 'unrendered', reason: notTextReason(rendered), text };
     }
     catch (error) {
-        return { kind: 'unrendered', reason: reasonOf(error), text: defaultText(failure) };
+        return { cause: error, kind: 'unrendered', reason: reasonOf(error), text };
     }
 }
 export { buildViews, describeFailure, override, resolveRowView, resolveView, shapeOf, view, viewIdentities, };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loomcli/core",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "The Loom CLI core package. Provides the scaffolding for creating new Loom CLI applications.",
   "license": "MIT",
   "repository": {
@@ -8,7 +8,8 @@
     "url": "git+https://github.com/dbtlr/loomcli.git"
   },
   "files": [
-    "dist"
+    "dist",
+    "LICENSE"
   ],
   "type": "module",
   "exports": {