@loomcli/core 0.4.0 → 0.5.0

package/dist/validation.js

@@ -73,33 +73,44 @@ function spellingOf(input) {
         return input.name;
     }
     const { config } = input;
-    return config.shortOnly === true && config.short !== undefined
-        ? `-${config.short}`
+    if (config.shortOnly === true && config.short !== undefined) {
+        return `-${config.short}`;
+    }
+    // A negative-only Boolean option accepts its negative form alone.
+    return config.type === 'boolean' && config.polarity === 'negative'
+        ? `--no-${input.name}`
         : `--${input.name}`;
 }
-/** An input diagnostic names the declaration by kind and by the spelling that reaches it. */
-function suppliedName(input, spelling) {
-    return input.kind === 'argument' ? `Argument "${spelling}"` : `Option "${spelling}"`;
+/**
+ * An input diagnostic names the declaration by kind and by the spelling that reaches it. A value an
+ * input source filled adds its source in parentheses, so the operator learns where it came from.
+ */
+function suppliedName(input, spelling, origin) {
+    if (input.kind === 'argument') {
+        return `Argument "${spelling}"`;
+    }
+    return origin === undefined ? `Option "${spelling}"` : `Option "${spelling}" (from ${origin})`;
 }
 /**
  * The default sentence for an omitted required input. An argument and an option keep the wording
  * each phase used before omission became one problem, and a collected input asks for one value
  * more than a scalar does.
  */
-function missingMessage(input, spelling, collected) {
+function missingMessage(input, spelling, facts) {
+    const { collected, origin } = facts;
     return input.kind === 'argument'
         ? `Argument "${spelling}" requires ${collected ? 'at least one value' : 'a value'}. Supply a value for "${spelling}".`
-        : `Option "${spelling}" is required. Supply ${collected ? 'at least one value' : 'a value'}.`;
+        : `${suppliedName(input, spelling, origin)} is required. Supply ${collected ? 'at least one value' : 'a value'}.`;
 }
 /**
  * A multiple option collects its occurrences and a variadic argument collects the remaining
- * tokens, so either one carries the whole `string[]` as its raw value.
+ * tokens, so either one carries a `string[]` as its raw value and validates each value alone.
  */
 function collects(input) {
     return input.kind === 'option' ? input.config.multiple === true : input.config.variadic === true;
 }
 /**
- * The declaration flag that sends an omitted value to its own schema. Every declaration reads it
+ * 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.
  */
 export function validatesOmission(input) {
@@ -114,16 +125,23 @@ function suppliedOption(options, name, collected) {
 function copied(value) {
     return Array.isArray(value) ? [...value] : value;
 }
-/** Without a schema the raw shape is the declared default's only contract. */
+/**
+ * Without a validator the raw shape is the declared default's only contract. With one, a default
+ * of several values must still be an array, because each of its values passes the validator.
+ */
 function holdsRawDefault(input) {
     const value = input.config.default;
-    return collects(input)
-        ? Array.isArray(value) && value.every((entry) => typeof entry === 'string')
-        : typeof value === 'string';
+    if (!collects(input)) {
+        return input.config.validate !== undefined || typeof value === 'string';
+    }
+    return (Array.isArray(value) &&
+        (input.config.validate !== undefined ||
+            value.every((entry) => typeof entry === 'string')));
 }
 /**
- * `validateOmitted: true` is the one way an omitted scalar reaches its schema, so every other rule
- * that already decides absence rejects it, and the flag needs a schema to receive the omission.
+ * `validateOmitted: true` is the one way an omitted scalar reaches its validator, so every other
+ * rule that already decides absence rejects it, and the flag needs a validator to receive the
+ * omission.
  */
 function checkOmissionValidation(input, subject) {
     const { config } = input;
@@ -134,10 +152,10 @@ function checkOmissionValidation(input, subject) {
         throw new DeclarationError(`${subject} declares a default and validateOmitted. Remove one; the default already fills an omitted value.`);
     }
     if (collects(input)) {
-        throw new DeclarationError(`${subject} collects its values and declares validateOmitted. Remove validateOmitted; an omitted collection reaches the schema as an empty array.`);
+        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.`);
     }
     if (config.validate === undefined) {
-        throw new DeclarationError(`${subject} declares validateOmitted without a schema. Add validate or remove validateOmitted.`);
+        throw new DeclarationError(`${subject} declares validateOmitted without a validator. Add validate or remove validateOmitted.`);
     }
 }
 function checkDeclaration(input, subject) {
@@ -169,15 +187,15 @@ function checkDeclaration(input, subject) {
     if (validatesOmission(input)) {
         checkOmissionValidation(input, subject);
     }
-    const schema = config.validate;
-    if (schema !== undefined &&
-        (schema === null ||
-            (typeof schema !== 'object' && typeof schema !== 'function') ||
-            !schema['~standard'] ||
-            schema['~standard'].version !== 1 ||
-            typeof schema['~standard'].vendor !== 'string' ||
-            typeof schema['~standard'].validate !== 'function')) {
-        throw new DeclarationError(`${subject} validate must be a Standard Schema v1 object. Supply a compatible schema.`);
+    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.`);
     }
 }
 function readIssue(issue) {
@@ -209,12 +227,12 @@ function readIssue(issue) {
  * names the declaration. Returned issues belong to the value, so the caller names those.
  */
 async function validate(input, raw, context) {
-    const schema = input.config.validate;
-    if (schema === undefined) {
+    const validator = input.config.validate;
+    if (validator === undefined) {
         return { value: raw };
     }
     try {
-        const result = await schema['~standard'].validate(raw, schemaOptions(context));
+        const result = await validator['~standard'].validate(raw, schemaOptions(context));
         if (result === null || typeof result !== 'object') {
             throw new Error('The validator returned an invalid Standard Schema result.');
         }
@@ -232,6 +250,42 @@ async function validate(input, raw, context) {
         throw new DeclarationError(`${declaredName(input)} validator failed unexpectedly: ${reason} Fix the validator.`);
     }
 }
+/**
+ * One validation of a declared value. A multiple option or a variadic argument passes each of its
+ * values through the validator in order, and each issue reads at its value's position before its
+ * own path, so the action receives the array of outputs. Every other input passes its value once.
+ * Each call reads a fresh context whose arrays are copies, so a write to them never reaches the
+ * 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;
+    if (!collects(input) || input.config.validate === undefined) {
+        return validate(input, raw, context());
+    }
+    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.`);
+    }
+    const outputs = [];
+    const issues = [];
+    for (const [position, value] of raw.entries()) {
+        if (signal?.aborted) {
+            // A cancelled run starts no further call; the run resolves its cancellation code instead.
+            break;
+        }
+        const result = await validate(input, value, context());
+        if (result.issues === undefined) {
+            outputs.push(result.value);
+        }
+        else {
+            issues.push(...reported(result.issues).map((issue) => ({
+                message: issue.message,
+                path: [position, ...(issue.path ?? [])],
+            })));
+        }
+    }
+    return issues.length === 0 ? { value: outputs } : { issues };
+}
 /**
  * The dotted path an issue names inside a value, or `undefined` when the issue names the value
  * itself. Core's default text and an application's own view read a position through this one
@@ -244,13 +298,13 @@ export function issuePath(issue) {
     return path === undefined || path === '' ? undefined : path;
 }
 /**
- * The issues one rejection reports. A schema that returned none still rejected the value, so the
+ * The issues one rejection reports. A validator that returned none still rejected the value, so the
  * placeholder stands in for its silence. Reporting takes this list once: the reported problem
  * carries it and the default text is derived from it, so a view and core read the same issues.
  */
 function reported(issues) {
     return issues.length === 0
-        ? [{ message: 'The schema rejected this value without an explanation.' }]
+        ? [{ message: 'The validator rejected this value without an explanation.' }]
         : issues;
 }
 function messages(subject, issues) {
@@ -259,58 +313,62 @@ function messages(subject, issues) {
         return `${subject}${path === undefined ? '' : ` at ${path}`}: ${issue.message}`;
     });
 }
+/** The fault a default of the wrong raw shape reports, by the shape its declaration expects. */
+function defaultShapeFault(input, subject) {
+    if (!collects(input)) {
+        return `${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.`;
+}
 /** A declared `default: undefined` is a default, so presence is the key, never the value. */
 function hasDefault(input) {
     return Object.hasOwn(input.config, 'default');
 }
 /**
- * Every declaration rule that reads the declaration alone. It is synchronous, so `inspect()` and
- * `run()` apply exactly the same rules, and only validating a default through its schema, which
- * can be asynchronous, is left to `run()`. A 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.
+ * 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
+ * validating a default through its validator, which can be asynchronous, is left to `run()`. A
+ * 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 function checkDeclarations(inputs, named) {
     for (const input of inputs) {
         checkDeclaration(input, named ?? declaredName(input));
     }
     for (const input of inputs.filter((entry) => hasDefault(entry))) {
-        if (input.config.validate === undefined && !holdsRawDefault(input)) {
+        if (!holdsRawDefault(input)) {
             const subject = named ?? declaredName(input);
-            throw new DeclarationError(collects(input)
-                ? `${subject} default must be an array of strings without a schema. Supply a string array default.`
-                : `${subject} default must be a string without a schema. Supply a string default.`);
+            throw new DeclarationError(defaultShapeFault(input, subject));
         }
     }
 }
 /**
  * Every declared default, validated before any token is read. The host is captured by then, so a
- * default's schema 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.
  */
 export async function prepareInputs(inputs, host) {
     const declarations = scoped(inputs);
-    checkDeclarations(declarations.map((entry) => entry.input));
     const defaults = new Map();
     for (const entry of declarations.filter(({ input }) => hasDefault(input))) {
         const { input } = entry;
         const subject = declaredName(input);
-        const result = await validate(input, input.config.default, {
-            host,
-            input: identityOf(entry),
-            phase: 'default',
+        const result = await validateDeclared(input, input.config.default, {
+            context: () => ({ host, input: identityOf(entry), phase: 'default' }),
         });
         if (result.issues !== undefined) {
-            throw new DeclarationError(`${subject} has an invalid default. Fix the default or its schema.\n${messages(subject, reported(result.issues)).join('\n')}`);
+            throw new DeclarationError(`${subject} has an invalid default. Fix the default or its validator.\n${messages(subject, reported(result.issues)).join('\n')}`);
         }
         defaults.set(input, result.value);
     }
     return defaults;
 }
 /**
- * An array default reaches the action as its own copy, so an action that mutates its collection
- * rewrites neither the declaration nor the next invocation. A schema that returns a new array is
- * copied too, because a pass-through schema returns the declared array itself and cannot be told
- * apart from one that built its own. Every other output passes through unchanged.
+ * An array default reaches the action as its own copy, so an action that mutates its array
+ * rewrites neither the declaration nor the next invocation. One prepared default serves every
+ * invocation of a run, and an unvalidated default is the declared array itself, so each read
+ * copies it. Every other output passes through unchanged.
  */
 function freshDefault(value) {
     return Array.isArray(value) ? [...value] : value;
@@ -339,50 +397,94 @@ function suppliedInputs(declarations, supplied) {
     }
     return { args, options };
 }
+/** The Boolean grammar's one issue, which a variable outside it reports. */
+const grammarIssues = [{ message: 'Use true, false, 1, or 0.' }];
+/**
+ * Every declaration in the order this phase reports its problems: the globals, then each plugin
+ * option whose variable is outside the grammar, then the routed Command's own declarations.
+ */
+function reportingOrder(invocation) {
+    const declarations = scoped(invocation.inputs);
+    const globals = declarations.filter((entry) => entry.global);
+    const rejected = invocation.plugins
+        .filter((input) => invocation.sources.rejected.has(input.name))
+        .map((input) => ({ global: true, input }));
+    return [...globals, ...rejected, ...declarations.filter((entry) => !entry.global)];
+}
 export async function validateValues(invocation) {
-    const { defaults, supplied } = invocation;
+    const { defaults, sources, supplied } = invocation;
     const declarations = scoped(invocation.inputs);
+    /** Where a filled option's value came from, which its diagnostic names; argv names none. */
+    const originOf = (input) => input.kind === 'option' ? sources.labels.get(input.name) : undefined;
     /**
-     * One reading of the tokens and the route, built anew for each schema call. The route, the
-     * tail, and every collected value are copies, so a schema that writes to them reaches neither
-     * the parser's collections, nor the tail the action receives, nor the next schema of this
-     * invocation. The host is the captured object itself, the one the action receives.
+     * One reading of the tokens and the route, built anew for each validator call. The route, the
+     * tail, and every collected value are copies, so a validator that writes to them reaches neither
+     * the parser's collections, nor the tail the action receives, nor the next validator call of
+     * this invocation. Each copy is made on its first read and kept for the call, so a validator
+     * that never reads one never pays for it, however many values a list holds. The host is the
+     * captured object itself, the one the action receives.
      */
-    const facts = () => ({
-        command: [...invocation.command],
-        host: invocation.host,
-        passthrough: [...invocation.passthrough],
-        supplied: suppliedInputs(declarations.map((entry) => entry.input), supplied),
-    });
+    const contextOf = (entry) => {
+        const copies = {};
+        return {
+            get command() {
+                copies.command ??= [...invocation.command];
+                return copies.command;
+            },
+            host: invocation.host,
+            input: identityOf(entry),
+            get passthrough() {
+                copies.passthrough ??= [...invocation.passthrough];
+                return copies.passthrough;
+            },
+            phase: 'invocation',
+            get supplied() {
+                copies.supplied ??= suppliedInputs(declarations.map((declared) => declared.input), supplied);
+                return copies.supplied;
+            },
+        };
+    };
     const values = new Map();
     const lines = [];
     const problems = [];
-    /** One path for every value the schema reads, so a raw shape and its issues meet it once. */
-    const accept = async (entry, raw, spelling) => {
-        const result = await validate(entry.input, raw, {
-            ...facts(),
+    /** One rejected input, whatever rejected it, in the order this phase reaches it. */
+    const reject = (entry, issues, subject) => {
+        problems.push({
             input: identityOf(entry),
-            phase: 'invocation',
+            issues,
+            reason: 'invalid',
+            spelling: spellingOf(entry.input),
+        });
+        lines.push(...messages(subject, issues));
+    };
+    /** One path for every value a validator reads, so a raw shape and its issues meet it once. */
+    const accept = async (entry, raw, spelling) => {
+        const result = await validateDeclared(entry.input, raw, {
+            context: () => contextOf(entry),
+            signal: invocation.signal,
         });
         if (result.issues === undefined) {
             values.set(entry.input, result.value);
             return;
         }
-        const issues = reported(result.issues);
-        problems.push({ input: identityOf(entry), issues, reason: 'invalid', spelling });
-        lines.push(...messages(suppliedName(entry.input, spelling), issues));
+        reject(entry, reported(result.issues), suppliedName(entry.input, spelling, originOf(entry.input)));
     };
-    for (const entry of declarations) {
+    for (const entry of reportingOrder(invocation)) {
         if (invocation.signal.aborted) {
             /**
-             * A cancelled run starts no further schema call. The one already in flight was awaited
+             * A cancelled run starts no further validator call. The one already in flight was awaited
              * above, and whatever this phase collected is never raised, because the run resolves its
              * cancellation code instead.
              */
             break;
         }
         const { input } = entry;
-        if (input.kind === 'option' && input.config.type === 'boolean') {
+        const variable = sources.rejected.get(input.name);
+        if (input.kind === 'option' && variable !== undefined) {
+            // A Boolean variable outside the grammar filled nothing, so it is the option's problem.
+            reject(entry, grammarIssues, suppliedName(input, spellingOf(input), variable));
+        }
+        else if (input.kind === 'option' && input.config.type === 'boolean') {
             values.set(input, booleanValue(supplied.options, input.name, input.config));
         }
         else {
@@ -396,14 +498,14 @@ export async function validateValues(invocation) {
                     // An omitted required argument arrives here too, so omission has one class.
                     // One aggregated diagnostic covers an omitted argument and an omitted option alike.
                     problems.push({ input: identityOf(entry), reason: 'missing', spelling });
-                    lines.push(missingMessage(input, spelling, collected));
+                    lines.push(missingMessage(input, spelling, { collected }));
                 }
                 else if (collected && !defaults.has(input)) {
-                    // No occurrence is an accurate empty collection, so it reads like a supplied value.
-                    await accept(entry, [], spelling);
+                    // No occurrence has no value to validate, so the action receives an empty array.
+                    values.set(input, []);
                 }
                 else if (validatesOmission(input)) {
-                    // The flag sends the omission itself to the schema.
+                    // The flag sends the omission itself to the validator.
                     // An absence rule reads the context a supplied value reads, and reports input issues.
                     await accept(entry, undefined, spelling);
                 }
@@ -411,6 +513,11 @@ export async function validateValues(invocation) {
                     values.set(input, freshDefault(defaults.get(input)));
                 }
             }
+            else if (input.config.required && Array.isArray(raw) && raw.length === 0) {
+                // A filled list satisfies the at-least-one rule by its length, so an empty one is missing.
+                problems.push({ input: identityOf(entry), reason: 'missing', spelling });
+                lines.push(missingMessage(input, spelling, { collected, origin: originOf(input) }));
+            }
             else {
                 await accept(entry, raw, spelling);
             }

package/dist/view.d.ts

@@ -78,7 +78,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';

package/dist/view.js

@@ -83,8 +83,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)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loomcli/core",
-  "version": "0.4.0",
+  "version": "0.5.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": {