@loomcli/core 0.7.0 → 0.8.0

package/dist/validation.js

@@ -4,8 +4,8 @@ import { escapeControlCharacters } from './controls.js';
 import { elided, spelled } from './diagnostic-text.js';
 import { asSentence, DeclarationError, InputError, quoted, reasonOf } from './errors.js';
 import { callSite, factFault, flagFault, partOf, siteFinding } from './facts.js';
-import { booleanOptionValueRule, defaultDepth, defaultLevels, defaultShape, invalidDefault, notAValidator, omissionAlreadyDecided, omissionWithoutValidator, requiredWithDefault, } from './input-rules.js';
-import { booleanValue } from './options.js';
+import { booleanOptionValueRule, countOptionValueRule, defaultDepth, defaultLevels, defaultShape, invalidDefault, invalidImplied, notAValidator, omissionAlreadyDecided, omissionWithoutValidator, requiredWithDefault, } from './input-rules.js';
+import { booleanValue, reportedOf, spellingsOf } from './options.js';
 import { boundedSnapshot, NestedTooDeepError, shallowList } from './plain.js';
 import { notAnObject } from './plugin-rules.js';
 import { validatorFailed } from './rules.js';
@@ -44,6 +44,10 @@ class ValidatedInputs {
     read(input) {
         return this.#values.get(input);
     }
+    /** Whether this pass validated the declaration's value. */
+    has(input) {
+        return this.#values.has(input);
+    }
     #field(input) {
         // Last resort: no typed path exists. The map stores every validated value as `unknown`.
         // An object literal with a generic computed key does not type as `Record<Name, _>` either.
@@ -56,14 +60,14 @@ class ValidatedInputs {
 }
 /**
  * Authoring's one read of a config, through `captureDeclaration`: the prototype verdict, the copy of
- * every own string key, the copy of its `extensions` list, and the snapshot of its default, inside
- * one try. Every later check, the registry entry, and every sentence read the copy and never the
- * author's object again, so a getter runs once and the caller's later changes reach nothing. The
- * default is copied and frozen to `defaultLevels` levels, cycles included, and that copy is the
- * value the graph publishes and a run validates; every other property is captured as declared,
- * because core clones no library object. A read that throws, from a getter or a proxy trap, is the
- * unreadable fault, named by the key it threw in, a default nested deeper is the too-deep fault,
- * and a value that is not a plain object is the not-an-object fault.
+ * every own string key, the copies of its `extensions` and `aliases` lists, and the snapshot of its
+ * default, inside one try. Every later check, the registry entry, and every sentence read the copy
+ * and never the author's object again, so a getter runs once and the caller's later changes reach
+ * nothing. The default is copied and frozen to `defaultLevels` levels, cycles included, and that
+ * copy is the value the graph publishes and a run validates; every other property is captured as
+ * declared, because core clones no library object. A read that throws, from a getter or a proxy
+ * trap, is the unreadable fault, named by the key it threw in, a default nested deeper is the
+ * too-deep fault, and a value that is not a plain object is the not-an-object fault.
  */
 export function captureConfig(config, faults) {
     const { notAnObject: notAnObjectFault, tooDeep, unreadable } = faults;
@@ -71,6 +75,7 @@ export function captureConfig(config, faults) {
         // Presence is the key, so a declared `default: undefined` stays a default.
         read.nested(copy, 'default', (value) => boundedSnapshot(value, defaultLevels));
         read.nested(copy, 'extensions', shallowList);
+        read.nested(copy, 'aliases', shallowList);
     }, {
         notAnObject: notAnObjectFault,
         unreadable: (thrown, slot) => thrown instanceof NestedTooDeepError ? tooDeep() : unreadable(thrown, slot),
@@ -125,11 +130,11 @@ export function declarationSubject(input) {
         : `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`.
+ * Where one Command's own input was declared: its `argument()` or `option()` call on the Command at
+ * `path`. A global option's site is the built table's, under `BuiltGlobals.sites`.
  */
-export function inputPlace(input, scope) {
-    return scope.global ? { call: 'globalOption', path: [] } : { call: input.kind, path: scope.path };
+export function inputPlace(input, path) {
+    return { call: input.kind, path };
 }
 /**
  * The site of the call that declared one input at `place`, rebuilt as `call(name, config)`. Every
@@ -149,23 +154,15 @@ export function configUnread(site) {
     return { ...site, declaration: { ...site.declaration, arguments: shown } };
 }
 /**
- * The token an operator would type for one declaration: `--file` for an option, `-F` when the
- * option declares `shortOnly`, and the declared name for an argument. Every input diagnostic and
+ * The token an operator would type for one declaration: an option's reported spelling, read from
+ * the routed Command's table, and the declared name for an argument. Every input diagnostic and
  * every reported problem names the declaration this way, so an omission and a rejected value read
  * alike and a `shortOnly` option is never named by a long form it does not accept.
  */
-function spellingOf(input) {
-    if (input.kind === 'argument') {
-        return input.name;
-    }
-    const { config } = input;
-    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}`;
+function spellingOf(input, table) {
+    return input.kind === 'argument'
+        ? input.name
+        : reportedOf(spellingsOf(table, input.name), input.name);
 }
 /**
  * An input diagnostic names the declaration by kind and by the spelling that reaches it. A value an
@@ -249,7 +246,7 @@ function checkOmissionValidation(input, site, subject) {
         });
     }
 }
-/** The value rules a Boolean option may not declare, in the order its diagnostic names them. */
+/** The value rules a Boolean or counted option may not declare, in the order a 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) {
@@ -263,17 +260,32 @@ function isStandardSchema(validator) {
         typeof Reflect.get(props, 'vendor') === 'string' &&
         typeof Reflect.get(props, 'validate') === 'function');
 }
+/**
+ * The value rules a Boolean or counted option declares, which take a value it never consumes. Each
+ * kind names its own absent value in the correction.
+ */
+function checkValueless(config, site, subject) {
+    const declared = valueRules.find((key) => key in config);
+    if (declared === undefined) {
+        return;
+    }
+    if (config.type === 'count') {
+        throw factFault(countOptionValueRule, site, {
+            correction: `Remove ${declared}; a counted option reads 0 when no occurrence supplies it.`,
+            fact: declared,
+            sentence: `${subject} is a counted option and declares ${declared}.`,
+        });
+    }
+    throw factFault(booleanOptionValueRule, site, {
+        correction: `Remove ${declared}; use polarity to control its absent value.`,
+        fact: declared,
+        sentence: `${subject} is Boolean and declares ${declared}.`,
+    });
+}
 function checkDeclaration(input, site, subject) {
     const { config } = input;
-    if (input.kind === 'option' && input.config.type === 'boolean') {
-        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}.`,
-            });
-        }
+    if (input.kind === 'option' && input.config.type !== 'string') {
+        checkValueless(input.config, site, subject);
         return;
     }
     if (config.required !== undefined && typeof config.required !== 'boolean') {
@@ -341,7 +353,7 @@ function readIssue(issue) {
  * belong to the value, so the caller names those.
  */
 async function validate(input, raw, call) {
-    const { context, place } = call;
+    const { context, site } = call;
     const validator = input.config.validate;
     if (validator === undefined) {
         return { value: raw };
@@ -362,7 +374,6 @@ async function validate(input, raw, call) {
     }
     catch (error) {
         // 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'))],
@@ -370,17 +381,34 @@ async function validate(input, raw, call) {
         }, { cause: error });
     }
 }
+/**
+ * Where a bare spelling supplied one option's implied value, with that value's prepared output, or
+ * `undefined` when no bare spelling supplied it.
+ */
+function impliedPositions(input, read) {
+    const positions = input.kind === 'option' ? read.options.implied.get(input.name) : undefined;
+    return positions === undefined
+        ? undefined
+        : { output: read.declaredValues.implied.get(input), positions };
+}
 /**
  * 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.
+ * A bare spelling's implied value never meets the validator here: its output was prepared before
+ * any token, so a scalar that a bare spelling supplied, and each bare occurrence in a multiple
+ * option's list, reuse a copy of that output in place. 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;
+    const { context, implied, signal, site } = call;
+    if (!collects(input) && implied?.positions.includes(0) === true) {
+        // A bare spelling supplied the implied value, whose output was prepared before any token.
+        return { value: freshDeclaredValue(implied.output) };
+    }
     if (!collects(input) || input.config.validate === undefined) {
-        return validate(input, raw, { context: context(), place });
+        return validate(input, raw, { context: context(), site });
     }
     if (!Array.isArray(raw)) {
         // The parser, the input sources, and the declaration rules only ever supply an array here.
@@ -393,7 +421,10 @@ async function validateDeclared(input, raw, call) {
             // A cancelled run starts no further call; the run resolves its cancellation code instead.
             break;
         }
-        const result = await validate(input, value, { context: context(), place });
+        // A bare occurrence holds the implied value, whose output was prepared before any token.
+        const result = implied?.positions.includes(position) === true
+            ? { value: freshDeclaredValue(implied.output) }
+            : await validate(input, value, { context: context(), site });
         if (result.issues === undefined) {
             outputs.push(result.value);
         }
@@ -474,44 +505,81 @@ export function checkDeclarations(inputs, named) {
     }
 }
 /**
- * Every declared default, validated before any token is read. The host is captured by then, so a
- * default's validator reads the same Host its action will, under the `default` phase. `places`
- * says where each declaration sits, which a rejected default's finding rebuilds.
+ * Every declared default and implied value, validated before any token is read, in declaration
+ * order, a declaration's default before its implied value. The host is captured by then, so each
+ * validator reads the same Host its action will, under the `default` phase. `places` says where each
+ * declaration sits, which a rejected value's finding rebuilds. An implied value is judged whether or
+ * not an invocation holds a bare spelling, because the author declared it.
  */
-export async function prepareInputs(inputs, host, places) {
-    const declarations = scoped(inputs);
+export async function prepareDeclaredValues(inputs, host, places) {
     const defaults = new Map();
-    for (const entry of declarations.filter(({ input }) => hasDefault(input))) {
+    const implied = new Map();
+    for (const entry of scoped(inputs)) {
         const { input } = entry;
-        const subject = declarationSubject(input);
-        const place = places.get(input);
-        const result = await validateDeclared(input, input.config.default, {
+        const call = {
             context: () => ({ host, input: identityOf(entry), phase: 'default' }),
-            place,
-        });
-        if (result.issues !== undefined) {
-            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'),
-            });
+            site: places.get(input),
+        };
+        if (hasDefault(input)) {
+            const result = await validateDeclared(input, input.config.default, call);
+            defaults.set(input, declaredOutput(input, result, { fault: 'default', site: call.site }));
+        }
+        const value = impliedOf(input);
+        if (value !== undefined) {
+            // A bare spelling supplies one value, so even a multiple option's validator reads it alone.
+            const result = await validate(input, value, { context: call.context(), site: call.site });
+            implied.set(input, declaredOutput(input, result, { fault: 'implied', site: call.site }));
         }
-        defaults.set(input, result.value);
     }
-    return defaults;
+    return { defaults, implied };
+}
+/** How each declared value names itself when its validator rejects it, and the fix. */
+const declaredFaults = {
+    default: {
+        correction: 'Fix the default or its validator.',
+        noun: 'default',
+        rule: invalidDefault,
+    },
+    implied: {
+        correction: 'Fix the implied value or its validator.',
+        noun: 'implied value',
+        rule: invalidImplied,
+    },
+};
+/**
+ * The output of a declared value its validator accepted, or the declaration fault it is when the
+ * validator rejected it, one line per issue under the sentence, marking the key that declares it.
+ */
+function declaredOutput(input, result, declared) {
+    if (result.issues === undefined) {
+        return result.value;
+    }
+    const { fault, site } = declared;
+    const { correction, noun, rule } = declaredFaults[fault];
+    const subject = declarationSubject(input);
+    throw new DeclarationError(rule, {
+        correction,
+        findings: site === undefined ? [] : [siteFinding(site, partOf(site, fault))],
+        sentence: [
+            `${subject} has an invalid ${noun}.`,
+            ...messages(subject, reported(result.issues)),
+        ].join('\n'),
+    });
+}
+/** The implied value a string option declares, which a bare spelling supplies, or `undefined`. */
+function impliedOf(input) {
+    return input.kind === 'option' && input.config.type === 'string'
+        ? input.config.implied
+        : undefined;
 }
 /**
- * An array default reaches the action as its own mutable 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 frozen snapshot the declaring call took,
- * so each read copies it. The copy keeps a hole where the default has one, as the graph's does.
- * Every other output passes through unchanged.
+ * An array default or implied output reaches the action as its own mutable copy, so an action that
+ * mutates its array rewrites neither the declaration nor the next invocation. One prepared declared
+ * value serves every invocation of a run, and an unvalidated default is the frozen snapshot the
+ * declaring call took, so each read copies it. The copy keeps a hole where the value has one, as
+ * the graph's does. Every other output passes through unchanged.
  */
-function freshDefault(value) {
+function freshDeclaredValue(value) {
     // A spread reads a hole as `undefined`, and `slice` keeps it.
     // oxlint-disable-next-line unicorn/prefer-spread
     return Array.isArray(value) ? value.slice() : value;
@@ -532,6 +600,9 @@ function suppliedInputs(declarations, supplied) {
         else if (input.config.type === 'boolean') {
             options[input.name] = supplied.options.booleans.get(input.name);
         }
+        else if (input.config.type === 'count') {
+            options[input.name] = supplied.options.counts.get(input.name);
+        }
         else {
             options[input.name] =
                 copied(suppliedOption(supplied.options, input.name, collected)) ??
@@ -540,22 +611,29 @@ 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.
+ * The one issue a variable outside its option's grammar reports: the Boolean grammar, or the count
+ * grammar of ASCII decimal digits.
  */
-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)];
+function grammarIssues(input) {
+    return input.config.type === 'count'
+        ? [{ message: 'Use a whole number of 0 or more.' }]
+        : [{ message: 'Use true, false, 1, or 0.' }];
+}
+/**
+ * Whether a pass rejected a global option, which leaves no global value a middleware may read. A
+ * global option declares no presence rule, so every problem it reports is a rejected value.
+ */
+export function rejectsGlobal(validation) {
+    return validation.failure?.problems.some((problem) => problem.input.global) ?? false;
 }
+/**
+ * Validates one invocation in reporting order: the global options, the application's and then each
+ * plugin's, and then the routed Command's own declarations, each in authoring order.
+ */
 export async function validateValues(invocation) {
-    const { defaults, sources, supplied } = invocation;
+    const { declaredValues, prior, sources, supplied } = invocation;
+    const { defaults } = declaredValues;
     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;
@@ -588,24 +666,40 @@ export async function validateValues(invocation) {
         };
     };
     const values = new Map();
-    const lines = [];
-    const problems = [];
+    // Each input reports at most once, so insertion order is the order this phase reaches them.
+    const reports = new Map();
+    /**
+     * One missing input, in the order this phase reaches it, unless a skipped configuration source
+     * would have been asked to fill it.
+     */
+    const omit = (entry, spelling, line) => {
+        if (sources.unanswered?.has(entry.input) === true) {
+            return;
+        }
+        reports.set(entry.input, {
+            lines: [line],
+            problem: { input: identityOf(entry), reason: 'missing', spelling },
+        });
+    };
     /** One rejected input, whatever rejected it, in the order this phase reaches it. */
     const reject = (entry, issues, subject) => {
-        problems.push({
-            input: identityOf(entry),
-            issues,
-            reason: 'invalid',
-            spelling: spellingOf(entry.input),
+        reports.set(entry.input, {
+            lines: messages(subject, issues),
+            problem: {
+                input: identityOf(entry),
+                issues,
+                reason: 'invalid',
+                spelling: spellingOf(entry.input, invocation.table),
+            },
         });
-        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 }),
+            implied: impliedPositions(entry.input, { declaredValues, options: supplied.options }),
             signal: invocation.signal,
+            site: invocation.places.get(entry.input),
         });
         if (result.issues === undefined) {
             values.set(entry.input, result.value);
@@ -613,7 +707,9 @@ export async function validateValues(invocation) {
         }
         reject(entry, reported(result.issues), suppliedName(entry.input, spelling, originOf(entry.input)));
     };
-    for (const entry of reportingOrder(invocation)) {
+    const { only } = invocation;
+    const validated = only ? declarations.filter(({ input }) => only.has(input)) : declarations;
+    for (const entry of validated) {
         if (invocation.signal.aborted) {
             /**
              * A cancelled run starts no further validator call. The one already in flight was awaited
@@ -624,16 +720,29 @@ export async function validateValues(invocation) {
         }
         const { input } = entry;
         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));
+        const earlier = prior?.reports.get(input);
+        if (prior?.values.has(input) === true) {
+            // An earlier pass validated this value once, and one value meets its validator once.
+            values.set(input, prior.values.read(input));
+        }
+        else if (earlier !== undefined) {
+            // The earlier pass's problem reports here, in this pass's order.
+            reports.set(input, earlier);
+        }
+        else if (input.kind === 'option' && variable !== undefined) {
+            // A variable outside its option's grammar filled nothing, so it is the option's problem.
+            reject(entry, grammarIssues(input), suppliedName(input, spellingOf(input, invocation.table), variable));
         }
         else if (input.kind === 'option' && input.config.type === 'boolean') {
             values.set(input, booleanValue(supplied.options, input.name, input.config));
         }
+        else if (input.kind === 'option' && input.config.type === 'count') {
+            // A count passes no validator, and no occurrence and no source reads 0.
+            values.set(input, supplied.options.counts.get(input.name) ?? 0);
+        }
         else {
             const collected = collects(input);
-            const spelling = spellingOf(input);
+            const spelling = spellingOf(input, invocation.table);
             const raw = input.kind === 'argument'
                 ? supplied.args.get(input)
                 : suppliedOption(supplied.options, input.name, collected);
@@ -641,34 +750,37 @@ export async function validateValues(invocation) {
                 if (input.config.required) {
                     // 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 }));
+                    omit(entry, spelling, missingMessage(input, spelling, { collected }));
                 }
                 else if (collected && !defaults.has(input)) {
                     // No occurrence has no value to validate, so the action receives an empty array.
                     values.set(input, []);
                 }
-                else if (validatesOmission(input)) {
+                else if (validatesOmission(input) && sources.unanswered?.has(input) !== true) {
                     // The flag sends the omission itself to the validator.
+                    // An option a skipped configuration source would have filled is not judged absent.
                     // An absence rule reads the context a supplied value reads, and reports input issues.
                     await accept(entry, undefined, spelling);
                 }
                 else {
-                    values.set(input, freshDefault(defaults.get(input)));
+                    values.set(input, freshDeclaredValue(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) }));
+                omit(entry, spelling, missingMessage(input, spelling, { collected, origin: originOf(input) }));
             }
             else {
                 await accept(entry, raw, spelling);
             }
         }
     }
-    if (problems.length > 0) {
-        throw new InputError(lines.join('\n'), problems);
-    }
-    return new ValidatedInputs(values);
+    const found = [...reports.values()];
+    return {
+        failure: found.length > 0
+            ? new InputError(found.flatMap((report) => report.lines).join('\n'), found.map((report) => report.problem))
+            : undefined,
+        reports,
+        values: new ValidatedInputs(values),
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loomcli/core",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "The Loom CLI core package. Provides the scaffolding for creating new Loom CLI applications.",
   "license": "MIT AND Unicode-3.0",
   "repository": {