@loomcli/core 0.5.0 → 0.6.0

package/dist/bindings.js

@@ -1,45 +1,64 @@
-import { DeclarationError } from './errors.js';
+import { DeclarationError, quoted } from './errors.js';
+import { factFault, siteFinding } from './facts.js';
+import { envName, envOnArgument, envOnMultiple, variableBoundTwice } from './input-rules.js';
 /** A variable name: a letter or an underscore, then letters, digits, or underscores. */
 const variableName = /^[A-Za-z_][A-Za-z0-9_]*$/u;
 /**
  * The environment binding one option declares, or `undefined` when it declares none. A multiple
  * option takes its list from the configuration source, so it cannot bind, and a bound name must be
- * a variable name. `sentence` names the declaration at the start of the diagnostic.
+ * a variable name. The site names the declaration and marks its `env`.
  */
-export function checkEnvBinding(sentence, config) {
+export function checkEnvBinding(site, config) {
     const env = config.env;
     if (env === undefined) {
         return undefined;
     }
     if (config.multiple === true) {
-        throw new DeclarationError(`${sentence} is a multiple option and declares env. Remove env; a list comes from the configuration source.`);
+        throw factFault(envOnMultiple, site, {
+            correction: 'Remove env; a list comes from the configuration source.',
+            fact: 'env',
+            sentence: `${site.subject} is a multiple option and declares env.`,
+        });
     }
     if (typeof env !== 'string' || !variableName.test(env)) {
-        const quoted = typeof env === 'string' ? ` "${env}"` : '';
-        throw new DeclarationError(`${sentence} env${quoted} is not a variable name. Use a letter or an underscore, then letters, digits, or underscores.`);
+        const named = typeof env === 'string' ? ` ${quoted(env)}` : '';
+        throw factFault(envName, site, {
+            correction: 'Use a letter or an underscore, then letters, digits, or underscores.',
+            fact: 'env',
+            sentence: `${site.subject} env${named} is not a variable name.`,
+        });
     }
     return env;
 }
 /** An argument is identified by its place among bare tokens, so no variable can stand in for it. */
-export function checkNoArgumentBinding(sentence, config) {
+export function checkNoArgumentBinding(site, config) {
     if ('env' in config) {
-        throw new DeclarationError(`${sentence} declares env, which applies to options alone. Remove it.`);
+        throw factFault(envOnArgument, site, {
+            correction: 'Remove it.',
+            fact: 'env',
+            sentence: `${site.subject} declares env, which applies to options alone.`,
+        });
     }
 }
 /**
- * The variables one scope binds, each to the phrase of the option that binds it. Within one
- * invocation's scope a variable binds one option, so a second binder is a declaration error that
- * names the first binder, in scope order, and then the second. `held` is what an enclosing scope
- * already binds, such as the globals table under a Command's own options.
+ * The variables one scope binds, each to the option that binds it. Within one invocation's scope a
+ * variable binds one option, so a second binder is a declaration error that names the first
+ * binder, in scope order, and then the second. `held` is what an enclosing scope already binds,
+ * such as the globals table under a Command's own options.
  */
 export function claimVariables(bound, held = new Map()) {
     const claimed = new Map(held);
-    for (const { site, variable } of bound) {
+    for (const binder of bound) {
+        const { phrase, variable } = binder;
         const owner = claimed.get(variable);
         if (owner !== undefined) {
-            throw new DeclarationError(`Variable "${variable}" is bound by ${owner} and ${site}. Bind each variable to one option.`);
+            throw new DeclarationError(variableBoundTwice, {
+                correction: 'Bind each variable to one option.',
+                findings: [owner, binder].map(({ site }) => siteFinding(site, `${site.at}.env`)),
+                sentence: `Variable ${quoted(variable)} is bound by ${owner.phrase} and ${phrase}.`,
+            });
         }
-        claimed.set(variable, site);
+        claimed.set(variable, binder);
     }
     return claimed;
 }

package/dist/chain.d.ts

@@ -40,13 +40,19 @@ interface Invocation {
     /** The action's own channel, built from the routed Command's declaration when it dispatches. */
     channel: (binding: ResultBinding) => ActionChannel;
     defaults: DefaultValues;
-    facts: {
-        description: string | undefined;
-        version: string;
-    };
     graph: BuiltGraph;
     host: Host;
-    name: string;
+    /**
+     * The graph `inspect()` returns, built at most once for the run. A configuration source reads
+     * its requests from it, the chain reads it after the source, and an `onFailure` hook reads it too.
+     */
+    inspected: () => CommandGraph;
+    /**
+     * Offers one throw from the application's work to the translators, and answers with the failure
+     * that replaces it, or `undefined` when none does. The chain offers a throw where it leaves the
+     * chain, and a configuration source's throw is offered where the resolver's call settles.
+     */
+    offer: (thrown: unknown) => LoomError | undefined;
     /**
      * The invocation's own channel. A middleware reads it as the neutral `Out`, and the action
      * receives the channel the results lane builds for the Command that was routed.
@@ -57,7 +63,10 @@ interface Invocation {
     plugins: readonly BuiltPlugin[];
     /** A fault reported after the primary outcome, which turns a would-be 0 into 1. */
     report: (fault: LoomError) => void;
-    /** The routed path, published where routing resolved it, which output names in its own line. */
+    /**
+     * The path routing walked, published as each name routes, which output names in its own line
+     * and a failure view reads. An unknown Command leaves the partial path published.
+     */
     route: (path: readonly string[]) => void;
     signal: AbortSignal;
 }

package/dist/chain.js

@@ -1,8 +1,9 @@
 import { prepareDispatch, routeInvocation } from './command.js';
-import { InternalError, reasonOf, routedSubject, toFailure } from './errors.js';
-import { inspectGraph, nodeAt } from './inspect.js';
+import { foreignFailure, InternalError, routedSubject } from './errors.js';
+import { nodeAt } from './inspect.js';
 import { isSupplied } from './options.js';
 import { loadDefault, pluginSentence, pluginSpellings, pluginValues } from './plugin.js';
+import { nextMisuse, viewSelection, viewSelectionCorrection } from './rules.js';
 /**
  * The view one run selects, which is one value whichever middleware wrote it. The assignment is
  * kept as it arrived, because a JavaScript caller reaches the setter with any value and the check
@@ -53,13 +54,13 @@ class ViewSelection {
         const plugin = pluginSentence(assigned.identity);
         const { name } = assigned;
         if (!this.#result) {
-            throw new InternalError(`${plugin} selected view "${String(name)}" on ${routedSubject(path)}, which declares no result.`, undefined);
+            throw selectionFault(`${plugin} selected view "${String(name)}" on ${routedSubject(path)}, which declares no result.`);
         }
         if (typeof name !== 'string') {
-            throw new InternalError(`${plugin} selected a view that is not a string on ${routedSubject(path)}.`, undefined);
+            throw selectionFault(`${plugin} selected a view that is not a string on ${routedSubject(path)}.`);
         }
         if (!this.#result.views.has(name)) {
-            throw new InternalError(`${plugin} selected view "${name}", which ${routedSubject(path)} does not name.`, undefined);
+            throw selectionFault(`${plugin} selected view "${name}", which ${routedSubject(path)} does not name.`);
         }
         return name;
     }
@@ -118,9 +119,21 @@ async function quiet(pending) {
 function reported(chain, outcome) {
     return outcome === 'taken-over' && chain.cancelled() ? 'cancelled' : outcome;
 }
+/** The defect a view selection the routed Command cannot render reports. */
+function selectionFault(sentence) {
+    return new InternalError(viewSelection, {
+        cause: undefined,
+        correction: viewSelectionCorrection,
+        sentence,
+    });
+}
 /** A `next()` call that is no longer live: it dispatches nothing and rejects. */
 function misuse(turn) {
-    const fault = new InternalError(`${pluginSentence(turn.entry.identity)} called next() ${turn.state.returned ? 'after its middleware returned' : 'twice'}.`, undefined);
+    const fault = new InternalError(nextMisuse, {
+        cause: undefined,
+        correction: 'Call next() once, and await it before the middleware returns.',
+        sentence: `${pluginSentence(turn.entry.identity)} called next() ${turn.state.returned ? 'after its middleware returned' : 'twice'}.`,
+    });
     turn.chain.report(fault);
     const rejected = Promise.reject(fault);
     void rejected.catch(() => undefined);
@@ -183,7 +196,7 @@ async function settle(turn, thrown) {
          * again when the middleware let it escape. It keeps the one report it already has.
          */
         if (!chain.announced(thrown.value)) {
-            chain.report(new InternalError(reasonOf(thrown.value), thrown.value));
+            chain.report(foreignFailure(thrown.value));
         }
     }
     if (state.calls === 0) {
@@ -217,10 +230,16 @@ async function runEntry(entry, index, chain) {
     state.returned = true;
     return settle(turn, thrown);
 }
-/** The whole chain, answering with the failure it raised when a middleware caught that failure. */
+/**
+ * The whole chain, answering with the value it raised when a middleware caught that value. The
+ * value is kept as it was thrown, so it is offered to the translators once, where it leaves.
+ */
 async function runChain(invocation, routed, prepared) {
     const entries = activatedEntries(invocation.plugins, prepared.globals);
-    const run = { invoked: false, raised: undefined };
+    const run = {
+        invoked: false,
+        raised: undefined,
+    };
     const selection = new ViewSelection(prepared.result);
     /**
      * The dispatch boundary: the point the chain reaches when its last middleware continues. Core
@@ -271,7 +290,7 @@ async function runChain(invocation, routed, prepared) {
         }),
         invoked: () => run.invoked,
         record: (error) => {
-            run.raised ??= toFailure(error);
+            run.raised ??= { value: error };
         },
         report: (fault) => {
             announced.add(fault);
@@ -300,20 +319,21 @@ async function runChain(invocation, routed, prepared) {
  * raised and nothing later in the chain runs.
  */
 async function runInvocation(invocation) {
-    const routed = routeInvocation(invocation.graph, invocation.host.argv);
-    invocation.route(routed.path);
-    // The graph `inspect()` returns, built at most once for the run.
-    // A configuration source reads its requests from it, and the chain reads it after the source.
-    let graph = undefined;
-    const inspected = () => (graph ??= inspectGraph(invocation.name, invocation.graph, invocation.facts));
-    const run = { ...invocation, inspected };
-    const prepared = await prepareDispatch(invocation.graph, routed, run);
-    const raised = await runChain(run, routed, prepared);
+    const routed = routeInvocation(invocation.graph, invocation.host.argv, invocation.route);
+    const prepared = await prepareDispatch(invocation.graph, routed, invocation);
+    let raised = undefined;
+    try {
+        raised = await runChain(invocation, routed, prepared);
+    }
+    catch (error) {
+        // A throw leaves the chain here, so a middleware that awaited next() saw it raw.
+        throw invocation.offer(error) ?? error;
+    }
     if (raised) {
         // The chain resolved because a middleware caught the rejection.
         // The failure it caught still decides the exit code.
         // That is the rule an action's caught output rejection already follows.
-        throw raised;
+        throw invocation.offer(raised.value) ?? raised.value;
     }
 }
 export { runInvocation };

package/dist/command-rules.d.ts

@@ -0,0 +1,55 @@
+/** An application name, a Command name, or an alias outside the portable name rule. */
+declare const portableName: import("./diagnostic-text.js").DiagnosticRule;
+/** An argument name outside the declared-name rule. */
+declare const declaredName: import("./diagnostic-text.js").DiagnosticRule;
+/** Globals declared on a named Command's options. */
+declare const commandGlobals: import("./diagnostic-text.js").DiagnosticRule;
+/** A declaration call a Command's own `action()` already closed. */
+declare const declaredAfterAction: import("./diagnostic-text.js").DiagnosticRule;
+/** A second `action()` on one Command. */
+declare const multipleActions: import("./diagnostic-text.js").DiagnosticRule;
+/** One Command that declares arguments and attaches children. */
+declare const argumentsBesideChildren: import("./diagnostic-text.js").DiagnosticRule;
+/** Two arguments with one name on one Command. */
+declare const argumentDeclaredTwice: import("./diagnostic-text.js").DiagnosticRule;
+/** A variadic argument that another argument follows. */
+declare const variadicArgumentLast: import("./diagnostic-text.js").DiagnosticRule;
+/** An optional argument that another argument follows. */
+declare const optionalArgumentLast: import("./diagnostic-text.js").DiagnosticRule;
+/** An `alias()` call that names no alias. */
+declare const aliasWithoutNames: import("./diagnostic-text.js").DiagnosticRule;
+/** An alias that repeats its own Command's name or another of its aliases. */
+declare const repeatedAlias: import("./diagnostic-text.js").DiagnosticRule;
+/** A child whose name or alias repeats a sibling's name or alias. */
+declare const siblingNameTaken: import("./diagnostic-text.js").DiagnosticRule;
+/** A child that would sit more than two levels below the root. */
+declare const nestingDepth: import("./diagnostic-text.js").DiagnosticRule;
+/** A value passed to `command()` that is not a Command. */
+declare const notACommand: import("./diagnostic-text.js").DiagnosticRule;
+/** One Command value attached at two places. */
+declare const commandAttachedTwice: import("./diagnostic-text.js").DiagnosticRule;
+/** A Command with neither an action nor children. */
+declare const commandWithoutAction: import("./diagnostic-text.js").DiagnosticRule;
+/** A group, a Command with no action, that declares a local option. */
+declare const groupOption: import("./diagnostic-text.js").DiagnosticRule;
+/** A second `result()` or `rows()` on one Command. */
+declare const multipleResults: import("./diagnostic-text.js").DiagnosticRule;
+/** A `views()` call on a Command that declares no result. */
+declare const viewsWithoutResult: import("./diagnostic-text.js").DiagnosticRule;
+/** A views entry that is not exactly one view. */
+declare const viewShape: import("./diagnostic-text.js").DiagnosticRule;
+/** A row view under a result declared with `result()`. */
+declare const rowViewOnValue: import("./diagnostic-text.js").DiagnosticRule;
+/** A view name outside the declared-name rule, or one that is integer-like. */
+declare const viewName: import("./diagnostic-text.js").DiagnosticRule;
+/** A result on a Command with no action. */
+declare const resultWithoutAction: import("./diagnostic-text.js").DiagnosticRule;
+/** A result whose merged views record holds no view. */
+declare const resultWithoutViews: import("./diagnostic-text.js").DiagnosticRule;
+/** A default view that the merged views record does not hold. */
+declare const unknownDefaultView: import("./diagnostic-text.js").DiagnosticRule;
+/** A description, a deprecated message, or an Application version that is not one line of prose. */
+declare const notOneLine: import("./diagnostic-text.js").DiagnosticRule;
+/** `hidden` or `deprecated` on the Application or on an argument. */
+declare const misplacedListingFact: import("./diagnostic-text.js").DiagnosticRule;
+export { aliasWithoutNames, argumentDeclaredTwice, argumentsBesideChildren, commandAttachedTwice, commandGlobals, commandWithoutAction, declaredAfterAction, declaredName, groupOption, misplacedListingFact, multipleActions, multipleResults, nestingDepth, notOneLine, notACommand, optionalArgumentLast, portableName, repeatedAlias, resultWithoutAction, resultWithoutViews, rowViewOnValue, siblingNameTaken, unknownDefaultView, variadicArgumentLast, viewName, viewShape, viewsWithoutResult, };

package/dist/command-rules.js

@@ -0,0 +1,142 @@
+import { registerRule } from './diagnostic-text.js';
+/*
+ * Core's rules for the declaration faults of Commands and their names, aliases, nesting, children,
+ * actions, results, and core facts. Each is declared once here and shared by every site that raises
+ * it, as a plugin's rules are.
+ */
+/** An application name, a Command name, or an alias outside the portable name rule. */
+const portableName = registerRule('@loomcli/core/portable-name', {
+    explanation: 'An operator types the application name, each Command name, and each alias as a command at a shell prompt. A character outside the POSIX portable filename set needs quoting there, a leading "-" reads as an option, and a leading "." names a file a shell hides.',
+    headline: 'Name not portable',
+});
+/** An argument name outside the declared-name rule. */
+const declaredName = registerRule('@loomcli/core/declared-name', {
+    explanation: 'An action reads each argument and option under its name, and help and diagnostics print it. A leading "-" reads as an option, and whitespace or "=" splits the name where the parser reads it.',
+    headline: 'Invalid declared name',
+});
+/** Globals declared on a named Command's options. */
+const commandGlobals = registerRule('@loomcli/core/command-globals', {
+    explanation: "Global options belong to the Application, which declares them with globalOption() and hands their values to every action. A named Command reads their types from the Application's registered environment.",
+    headline: 'Globals on a named Command',
+});
+/** A declaration call a Command's own `action()` already closed. */
+const declaredAfterAction = registerRule('@loomcli/core/declared-after-action', {
+    explanation: "action() finishes a Command's declaration: the handler's types read every argument, option, alias, result, and child declared before it, so a later call would declare what the handler never sees.",
+    headline: 'Declared after the action',
+});
+/** A second `action()` on one Command. */
+const multipleActions = registerRule('@loomcli/core/multiple-actions', {
+    explanation: 'Routing runs one handler for the Command it selects, so a second action would leave one of the two unreachable.',
+    headline: 'Second action',
+});
+/** One Command that declares arguments and attaches children. */
+const argumentsBesideChildren = registerRule('@loomcli/core/arguments-beside-children', {
+    explanation: "A Command's first bare token either names a child or fills an argument, so a Command that holds both cannot tell which one an operator meant.",
+    headline: 'Arguments beside children',
+});
+/** Two arguments with one name on one Command. */
+const argumentDeclaredTwice = registerRule('@loomcli/core/argument-declared-twice', {
+    explanation: 'An action reads each argument under its name, so two arguments with one name leave one of them unreadable.',
+    headline: 'Argument declared twice',
+});
+/** A variadic argument that another argument follows. */
+const variadicArgumentLast = registerRule('@loomcli/core/variadic-argument-last', {
+    explanation: 'A variadic argument takes every positional token that remains, so an argument after it would never receive one.',
+    headline: 'Variadic argument not last',
+});
+/** An optional argument that another argument follows. */
+const optionalArgumentLast = registerRule('@loomcli/core/optional-argument-last', {
+    explanation: 'Positional tokens fill the arguments in order, and an operator leaves out an optional argument from the end of the line. An argument after an optional one would take the token the optional one was meant to receive.',
+    headline: 'Optional argument not last',
+});
+/** An `alias()` call that names no alias. */
+const aliasWithoutNames = registerRule('@loomcli/core/alias-without-names', {
+    explanation: 'alias() adds each name it receives to the names that route to its Command, so a call with none adds nothing.',
+    headline: 'Alias with no names',
+});
+/** An alias that repeats its own Command's name or another of its aliases. */
+const repeatedAlias = registerRule('@loomcli/core/repeated-alias', {
+    explanation: 'A Command answers to its name and to each of its aliases, so an alias that repeats one of them routes nothing new.',
+    headline: 'Alias repeats a name',
+});
+/** A child whose name or alias repeats a sibling's name or alias. */
+const siblingNameTaken = registerRule('@loomcli/core/sibling-name-taken', {
+    explanation: 'Every canonical name and alias under one parent routes one token to one child, so a name that two siblings share cannot route.',
+    headline: 'Name taken by a sibling',
+});
+/** A child that would sit more than two levels below the root. */
+const nestingDepth = registerRule('@loomcli/core/nesting-depth', {
+    explanation: 'Each level of nesting adds a token an operator types before a Command runs. Loom keeps every Command at most two levels below the root, so every invocation stays short enough to remember.',
+    headline: 'Commands nested too deep',
+});
+/** A value passed to `command()` that is not a Command. */
+const notACommand = registerRule('@loomcli/core/not-a-command', {
+    explanation: 'A Command value carries the declaration that routing, parsing, and help read. Any other value carries none.',
+    headline: 'Not a Command',
+});
+/** One Command value attached at two places. */
+const commandAttachedTwice = registerRule('@loomcli/core/command-attached-twice', {
+    explanation: 'A Command value sits at one place in the tree, where its path, its help page, and its parent read it, so one value attached at two places would have two paths.',
+    headline: 'Command attached twice',
+});
+/** A Command with neither an action nor children. */
+const commandWithoutAction = registerRule('@loomcli/core/command-without-action', {
+    explanation: "Routing ends at a Command that runs its action, or passes on to one of a group's children. A Command with neither leaves an invocation that reaches it nothing to run.",
+    headline: 'Nothing to run',
+});
+/** A group, a Command with no action, that declares a local option. */
+const groupOption = registerRule('@loomcli/core/group-option', {
+    explanation: 'A Command with no action is a group, which passes an invocation on to one of its children. A local option is never inherited, so no action reads an option a group declares.',
+    headline: 'Option on a group',
+});
+/** A second `result()` or `rows()` on one Command. */
+const multipleResults = registerRule('@loomcli/core/multiple-results', {
+    explanation: "A Command's action emits one result through out.results(), declared once, as a value with result() or as rows with rows(), so its consumers read one declaration.",
+    headline: 'Second result',
+});
+/** A `views()` call on a Command that declares no result. */
+const viewsWithoutResult = registerRule('@loomcli/core/views-without-result', {
+    explanation: 'views() reshapes the views a declared result renders through. A Command that declares no result emits nothing for a view to render.',
+    headline: 'Views with no result',
+});
+/** A views entry that is not exactly one view. */
+const viewShape = registerRule('@loomcli/core/view-shape', {
+    explanation: 'A views entry is a view with render, which receives the whole result, or a row view with row, which receives one row at a time. Core reads which function it holds to decide how to feed it.',
+    headline: 'Not one view',
+});
+/** A row view under a result declared with `result()`. */
+const rowViewOnValue = registerRule('@loomcli/core/row-view-on-value', {
+    explanation: 'A row view renders one row at a time, which only a result declared with rows() emits. A value result arrives whole, so a view with render reads it.',
+    headline: 'Row view on a value result',
+});
+/** A view name outside the declared-name rule, or one that is integer-like. */
+const viewName = registerRule('@loomcli/core/view-name', {
+    explanation: 'An operator and a middleware select a view by its name, so it is a bare token. It is not integer-like either, because an object moves such a key ahead of every other and the views lose the order they were declared in.',
+    headline: 'Invalid view name',
+});
+/** A result on a Command with no action. */
+const resultWithoutAction = registerRule('@loomcli/core/result-without-action', {
+    explanation: 'A declared result is a promise the action keeps by emitting through out.results(). A Command with no action has nothing to keep it.',
+    headline: 'Result with no action',
+});
+/** A result whose merged views record holds no view. */
+const resultWithoutViews = registerRule('@loomcli/core/result-without-views', {
+    explanation: 'A result prints through one of its views: the default one, or the one an operator or a middleware selects. A result with none has no way to print.',
+    headline: 'Result with no views',
+});
+/** A default view that the merged views record does not hold. */
+const unknownDefaultView = registerRule('@loomcli/core/unknown-default-view', {
+    explanation: 'The default view renders a result when nothing selects another, so it names one of the views the result declares.',
+    headline: 'Default view not declared',
+});
+/** A description, a deprecated message, or an Application version that is not one line of prose. */
+const notOneLine = registerRule('@loomcli/core/not-one-line', {
+    explanation: 'Help, --version, the manifest, and every other listing print a description, a deprecated message, and a version on one line beside what each names, so each holds prose and no line break. An operator or an agent follows a deprecated message to the replacement, so a bare true names none, and a version is a string as the package manifest spells it.',
+    headline: 'Text not one line',
+});
+/** `hidden` or `deprecated` on the Application or on an argument. */
+const misplacedListingFact = registerRule('@loomcli/core/misplaced-listing-fact', {
+    explanation: 'hidden and deprecated keep a named Command or an option off a listing, or mark it retired. The root is the entry point of every page, and an argument cannot leave the grammar it sits in, so neither carries them.',
+    headline: 'Listing fact out of place',
+});
+export { aliasWithoutNames, argumentDeclaredTwice, argumentsBesideChildren, commandAttachedTwice, commandGlobals, commandWithoutAction, declaredAfterAction, declaredName, groupOption, misplacedListingFact, multipleActions, multipleResults, nestingDepth, notOneLine, notACommand, optionalArgumentLast, portableName, repeatedAlias, resultWithoutAction, resultWithoutViews, rowViewOnValue, siblingNameTaken, unknownDefaultView, variadicArgumentLast, viewName, viewShape, viewsWithoutResult, };