@loomcli/core 0.4.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
@@ -73,33 +117,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,72 +169,106 @@ 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) {
+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} collects its values and declares validateOmitted. Remove validateOmitted; an omitted collection reaches the schema as an empty array.`);
+        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 schema. Add validate or remove validateOmitted.`);
+        throw factFault(omissionWithoutValidator, site, {
+            correction: 'Add validate or remove validateOmitted.',
+            fact: 'validateOmitted',
+            sentence: `${subject} declares validateOmitted without a validator.`,
+        });
+    }
+}
+/** 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, subject) {
+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 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.`);
+    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.');
@@ -190,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.');
@@ -202,19 +291,21 @@ 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) {
-    const schema = input.config.validate;
-    if (schema === undefined) {
+async function validate(input, raw, call) {
+    const { context, place } = call;
+    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.');
         }
@@ -228,10 +319,51 @@ 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 });
     }
 }
+/**
+ * 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, place, signal } = call;
+    if (!collects(input) || input.config.validate === undefined) {
+        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(`${declarationSubject(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: context(), place });
+        if (result.issues === undefined) {
+            outputs.push(result.value);
+        }
+        else {
+            // 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 };
+}
 /**
  * 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,73 +376,97 @@ 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. 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, site, subject) {
+    const fault = (sentence, correction) => factFault(defaultShape, site, { correction, fact: 'default', sentence });
+    if (!collects(input)) {
+        return fault(`${subject} default must be a string without a validator.`, 'Supply a string default.');
+    }
+    return input.config.validate === undefined
+        ? 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) {
     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)) {
-            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.`);
+    for (const { input, site } of inputs) {
+        checkDeclaration(input, site, named ?? declarationSubject(input));
+    }
+    for (const { input, site } of inputs.filter((entry) => hasDefault(entry.input))) {
+        if (!holdsRawDefault(input)) {
+            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 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. `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);
-    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 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 schema.\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);
     }
     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 +495,95 @@ 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),
+            place: inputPlace(entry.input, { global: entry.global, path: invocation.command }),
+            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 +597,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 +612,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);
             }