@loomcli/core 0.7.0 → 0.8.0

package/dist/plugin.d.ts

@@ -9,18 +9,21 @@ import type { ProcessSignal } from './signals.js';
 import type { Palette } from './style-state.js';
 import type { ContextualStyle, ThemeConstraint, ThemeMapping } from './style.js';
 import type { Translation, TranslationContributor } from './translators.js';
-import type { CommandAttachHook, Host, OptionValue, Out, PluginOptionConfig } from './types.js';
+import type { CommandAttachHook, GlobalOptionConfig, Host, OptionValue, Out } from './types.js';
 import type { OptionInput } from './validation.js';
 import type { ViewContribution, ViewSubject } from './view.js';
 /**
- * The declaration record a plugin contributes its options under: the parsing part of an option
- * config, keyed by option name. A plugin option carries no schema and no presence rule, so the
- * config type publishes neither, and `plugin()` repeats the rule for a JavaScript author.
+ * The declaration record a plugin contributes its global options under, keyed by option name. Each
+ * entry takes the configuration `globalOption()` takes, so the config type publishes no presence
+ * rule, and `plugin()` repeats the rule for a JavaScript author.
+ */
+type PluginOptions = Readonly<Record<string, GlobalOptionConfig>>;
+/**
+ * The values one plugin's options take, read through the same `OptionValue` an action's options
+ * are, so a validated option reads as its validator's output.
  */
-type PluginOptions = Readonly<Record<string, PluginOptionConfig>>;
-/** The values one plugin's own options take, read through the same rules an action's options are. */
 type PluginOptionValues<Options extends PluginOptions> = {
-    readonly [Name in keyof Options]: OptionValue<Options[Name]>;
+    readonly [Name in keyof Options & string]: OptionValue<Options[Name]>;
 };
 /**
  * The spelling that supplied each of one plugin's own options given as a token, such as `-h`,
@@ -48,6 +51,16 @@ declare class PluginDeclaration<Options extends PluginOptions, Theme extends The
 type Plugin<Options extends PluginOptions = PluginOptions, Theme extends ThemeMapping = {}> = Pick<PluginDeclaration<Options, Theme>, typeof pluginOptions | typeof pluginTheme>;
 /** The declared options of a plugin, or of the factory that returns one. */
 type OptionsOf<Contributor> = Contributor extends Plugin<infer Options> ? Options : Contributor extends (...args: never[]) => Plugin<infer Options> ? Options : PluginOptions;
+/**
+ * The option values an installed plugin tuple contributes to every action's options, each plugin's
+ * read through `PluginOptionValues`. The Application computes it once from the constructor's
+ * `plugins`. A plugin typed as the wide `Plugin` states no option names, and a list widened to
+ * `Plugin[]` states no plugins, so neither names an option.
+ */
+type InstalledOptionValues<Plugins extends readonly Plugin[]> = Plugins extends readonly [
+    infer First extends Plugin,
+    ...infer Rest extends readonly Plugin[]
+] ? (string extends keyof OptionsOf<First> ? {} : PluginOptionValues<OptionsOf<First>>) & InstalledOptionValues<Rest> : {};
 /** A middleware reads its own plugin's options and either takes over or continues the chain. */
 type Middleware<Contributor extends Plugin | ((...args: never[]) => Plugin)> = (context: MiddlewareContext<OptionsOf<Contributor>>) => Promise<void> | void;
 /**
@@ -66,11 +79,12 @@ interface SourceContext<Options extends PluginOptions = PluginOptions> {
     readonly style: ContextualStyle;
 }
 /**
- * One answer: a value of the option's raw type, a string, a Boolean, or a list of strings for a
- * multiple option, and the one-line label core prints in a diagnostic about the value.
+ * One answer: a value of the option's raw type, a string, a Boolean, a whole number of 0 or more
+ * for a counted option, or a list of strings for a multiple option, and the one-line label core
+ * prints in a diagnostic about the value.
  */
 interface SourceAnswer {
-    readonly value: string | boolean | readonly string[];
+    readonly value: string | boolean | number | readonly string[];
     readonly label: string;
 }
 /**
@@ -182,17 +196,8 @@ interface BuiltPlugin {
 }
 /** The signals the one slot owner claimed, or none when no installed plugin claims the slot. */
 declare function ownedSignals(plugins: readonly BuiltPlugin[]): readonly ProcessSignal[];
-/** The value shape a plugin option takes, which is what `OptionValue` gives its declaration. */
-type PluginValues = Record<string, string | string[] | boolean | undefined>;
-/**
- * One plugin's own option values for one run: what argv or an input source supplied, or the
- * declared default, filled without validation. A collected value and an array default are copied,
- * so a plugin that writes to what it received changes neither the declaration nor the next run.
- * Entries become own keys even for a name such as `__proto__`, which assignment would not.
- */
-declare function pluginValues(inputs: readonly OptionInput[], values: OptionValues): PluginValues;
 /** One plugin's own spellings for one run, frozen, so no plugin writes what another reads. */
 declare function pluginSpellings(inputs: readonly OptionInput[], values: OptionValues): Readonly<Record<string, string>>;
 type ThemeOf<Contributor> = [Contributor] extends [never] ? {} : Contributor extends Plugin<PluginOptions, infer Theme> ? Theme : {};
-export type { ThemeOf, BuiltPlugin, BuiltSource, PluginValues, SourceAnswer, SourceContext, SourceResolver, Middleware, OptionsOf, Plugin, PluginDefinition, PluginOptions, PluginOptionSpellings, PluginOptionValues, };
-export { installPlugins, loadDefault, ownedSignals, plugin, pluginSentence, pluginSpellings, pluginViews, pluginValues, };
+export type { ThemeOf, BuiltPlugin, BuiltSource, InstalledOptionValues, SourceAnswer, SourceContext, SourceResolver, Middleware, OptionsOf, Plugin, PluginDefinition, PluginOptions, PluginOptionSpellings, PluginOptionValues, };
+export { installPlugins, loadDefault, ownedSignals, plugin, pluginSentence, pluginSpellings, pluginViews, };

package/dist/plugin.js

@@ -5,13 +5,13 @@ import { attach, commandCode, commandNode } from './command.js';
 import { elided, quoteString, spelled } from './diagnostic-text.js';
 import { DeclarationError, InternalError, quoted, reasonOf } from './errors.js';
 import { appliesTo, buildExtensions, isDescriptor, registerDescriptor } from './extension.js';
-import { checkDeprecated, checkDescription, checkHidden, factFault, partFinding, pluginOptionSite, slotSite, } from './facts.js';
-import { boundOptions, pluginSites } from './globals.js';
+import { checkDeprecated, checkDescription, checkHidden, partFinding, pluginOptionSite, slotSite, } from './facts.js';
+import { boundOptions, checkNoPresenceRule, pluginSites } from './globals.js';
 import { checkIdentity } from './identity.js';
 import { coreViews } from './lanes.js';
-import { booleanValue, compileOptions } from './options.js';
+import { compileOptions } from './options.js';
 import { copyOwnKeys, decidePlain, declaring, isPlainObject, shallowList, shallowRecord, } from './plain.js';
-import { foreignValue, middlewareActivation, notAFunction, notAList, notAnObject, pluginInstalledTwice, pluginOptionRule, signalClaimedTwice, slotTaken, sourceBinding, sourceBoundOwnOption, unknownSignal, } from './plugin-rules.js';
+import { foreignValue, middlewareActivation, notAFunction, notAList, notAnObject, pluginInstalledTwice, signalClaimedTwice, slotTaken, sourceBinding, sourceBoundOwnOption, unknownSignal, } from './plugin-rules.js';
 import { pluginLoaderFailed } from './rules.js';
 import { isProcessSignal } from './signals.js';
 import { buildTheme } from './theme.js';
@@ -208,10 +208,8 @@ function installPlugins(application, plugins) {
     }
     return { descriptors, plugins: installed };
 }
-/** The keys a plugin option may not declare, in the order its diagnostic names them. */
-const forbidden = ['validate', 'validateOmitted', 'required'];
 /**
- * The rules a plugin option answers before every rule an ordinary declaration carries, read from
+ * The rules a plugin's option answers before every rule an ordinary declaration carries, read from
  * the one copy of its config that `captureConfig` takes, which it answers with for every later read.
  * `siteOf` places the option with the value its entry prints as: the config as declared for a value
  * that is not one, elided for a config whose read threw, and the copy for every later rule.
@@ -236,14 +234,8 @@ function checkPluginOption(siteOf, declared) {
         },
     });
     const site = siteOf(config);
-    const rejected = forbidden.find((key) => key in config);
-    if (rejected !== undefined) {
-        throw factFault(pluginOptionRule, site, {
-            correction: 'Remove it; a plugin option carries no validator or presence rule, and the middleware interprets the value.',
-            fact: rejected,
-            sentence: `${sentence} declares ${rejected}.`,
-        });
-    }
+    // A plugin's options are global options, so they answer the global option's presence rule.
+    checkNoPresenceRule(site, config);
     checkDescription(site, config.description);
     checkHidden(site, config.hidden);
     checkDeprecated(site, config.deprecated);
@@ -293,7 +285,8 @@ function readOptions(identity, declared, build) {
         }));
         inputs.push(input);
     }
-    // Two options of one plugin meet in the one table the pre-scan reads, so they share its rules.
+    // Two options of one plugin meet in the globals table every Command's table holds.
+    // They therefore share its rules.
     const siteOf = pluginSites(identity, inputs);
     compileOptions(inputs, { siteOf, subject: `plugin ${quoted(identity)}` });
     claimVariables(boundOptions(inputs, (input) => ({
@@ -661,34 +654,6 @@ function readPlugin(named, definition) {
 function ownedSignals(plugins) {
     return plugins.find((entry) => entry.signals.length > 0)?.signals ?? [];
 }
-/** A collected value, or the declared array default, as this run's own copy. */
-function collectedValue(collected, declared) {
-    if (collected) {
-        return [...collected];
-    }
-    return Array.isArray(declared) ? [...declared] : [];
-}
-/** One plugin option's value for one run: what a tier supplied, or the declared default. */
-function pluginValue({ config, name }, values) {
-    const declared = config.default;
-    if (config.type === 'boolean') {
-        return booleanValue(values, name, config);
-    }
-    if (config.multiple === true) {
-        return collectedValue(values.lists.get(name), declared);
-    }
-    // Build already proved that a string option without a validator declares a string default.
-    return values.strings.get(name) ?? (typeof declared === 'string' ? declared : undefined);
-}
-/**
- * One plugin's own option values for one run: what argv or an input source supplied, or the
- * declared default, filled without validation. A collected value and an array default are copied,
- * so a plugin that writes to what it received changes neither the declaration nor the next run.
- * Entries become own keys even for a name such as `__proto__`, which assignment would not.
- */
-function pluginValues(inputs, values) {
-    return Object.fromEntries(inputs.map((input) => [input.name, pluginValue(input, values)]));
-}
 /** One plugin's own spellings for one run, frozen, so no plugin writes what another reads. */
 function pluginSpellings(inputs, values) {
     // Entries become own keys even for a name such as `__proto__`, which assignment would not.
@@ -698,4 +663,4 @@ function pluginSpellings(inputs, values) {
     });
     return Object.freeze(Object.fromEntries(supplied));
 }
-export { installPlugins, loadDefault, ownedSignals, plugin, pluginSentence, pluginSpellings, pluginViews, pluginValues, };
+export { installPlugins, loadDefault, ownedSignals, plugin, pluginSentence, pluginSpellings, pluginViews, };

package/dist/sources.d.ts

@@ -5,7 +5,7 @@ import type { OptionValues } from './options.js';
 import type { BuiltPlugin } from './plugin.js';
 import type { ContextualStyle } from './style.js';
 import type { Host, Out } from './types.js';
-import type { OptionInput } from './validation.js';
+import type { OptionInput, Provenance, Validation } from './validation.js';
 /**
  * One scope the stage fills: its options in declaration order, and the values argv supplied them.
  * The stage writes each fill into `values`, so the caller hands it the run's own copy.
@@ -35,23 +35,32 @@ interface SourceStage {
     signal: AbortSignal;
     /** The contextual style an action receives, so a source escapes raw data before it warns. */
     style: ContextualStyle;
+    /**
+     * Validates the listed options alone, from the values the stage has filled so far, with what the
+     * environment tier found about them, under the context every validator of the run reads. A
+     * configuration source's own options pass through it before the source loads.
+     */
+    validate: (inputs: readonly OptionInput[], provenance: Provenance) => Promise<Validation>;
 }
 /**
  * What the stage found beside the values it filled. `labels` names where each filled option's value
- * came from, by option name, and `rejected` names the variable of each Boolean option whose value
- * is outside the grammar. Both are internal to core's failure messages. `fault` is a configuration
+ * came from, by option name, and `rejected` names the variable of each Boolean or counted option
+ * whose value is outside its grammar. Both are internal to core's failure messages. `fault` is a configuration
  * source's own fault, or the failure its resolver threw, which stops the stage and takes the place
- * of every validation problem.
+ * of every validation problem. `validated` is the pass over the source's own options ahead of its
+ * call, whose values and problems the run's one validation pass reads.
  */
-interface SourceOutcome {
+interface SourceOutcome extends Provenance {
     fault: LoomError | undefined;
-    labels: ReadonlyMap<string, string>;
-    rejected: ReadonlyMap<string, string>;
+    validated: Validation | undefined;
 }
 /**
  * The input-source stage: the environment, then the configuration source, for every option in
- * scope that argv left unfilled. When no option is left to ask, the source never loads. A source
- * fault stops the stage and fills nothing more.
+ * scope that argv left unfilled. When no option is left to ask, the source never loads. The
+ * source's own options pass their validators before it loads, and when one is rejected the source
+ * is never called and the problem reports with every other validation problem, while each option
+ * the source would have been asked to fill reports no missing value. A source fault stops the
+ * stage and fills nothing more.
  */
 declare function fillInputs(stage: SourceStage): Promise<SourceOutcome>;
 export type { SourceOutcome, SourceStage, StageScope };

package/dist/sources.js

@@ -1,8 +1,9 @@
 import { asSentence, foreignFailure, InternalError, LoomError, quoted, reasonOf, } from './errors.js';
 import { isProseLine } from './facts.js';
+import { frozenValues } from './globals.js';
 import { isSupplied } from './options.js';
 import { isPlainObject } from './plain.js';
-import { loadDefault, pluginSentence, pluginValues } from './plugin.js';
+import { loadDefault, pluginSentence } from './plugin.js';
 import { foreignThrow, foreignThrowCorrection, sourceAnswers, sourceAnswersCorrection, } from './rules.js';
 /** The Boolean grammar a bound variable is read through: the whole value, case-insensitive. */
 const truths = new Map([
@@ -11,10 +12,13 @@ const truths = new Map([
     ['false', false],
     ['true', true],
 ]);
+/** The count grammar a bound variable is read through: the whole value, one or more ASCII digits. */
+const countText = /^[0-9]+$/u;
 /**
- * Reads one option's bound variable. An empty variable is unset and falls through, a string option
- * receives the raw string, and a Boolean option reads the whole value through the grammar, so the
- * value states the option's value and not a spelling.
+ * Reads one option's bound variable. An empty variable is unset and falls through, and a string
+ * option receives the raw string, never its implied value. A Boolean option reads the whole value
+ * through the grammar, so the value states the option's value and not a spelling, and a counted
+ * option reads the whole value as decimal digits.
  */
 function readVariable(input, env) {
     const variable = input.config.env;
@@ -25,6 +29,9 @@ function readVariable(input, env) {
     if (input.config.type === 'string') {
         return { kind: 'fill', value: raw };
     }
+    if (input.config.type === 'count') {
+        return countText.test(raw) ? { kind: 'fill', value: Number(raw) } : { kind: 'rejected' };
+    }
     const value = truths.get(raw.toLowerCase());
     return value === undefined ? { kind: 'rejected' } : { kind: 'fill', value };
 }
@@ -33,6 +40,9 @@ function fill(values, name, value) {
     if (typeof value === 'boolean') {
         values.booleans.set(name, value);
     }
+    else if (typeof value === 'number') {
+        values.counts.set(name, value);
+    }
     else if (typeof value === 'string') {
         values.strings.set(name, value);
     }
@@ -43,12 +53,13 @@ function fill(values, name, value) {
 /** How a fault names the value an answer owed, by the shape the option takes. */
 const owed = {
     boolean: 'a Boolean',
+    count: 'a whole number of 0 or more',
     list: 'an array of strings',
     string: 'a string',
 };
 function rawKind(input) {
-    if (input.config.type === 'boolean') {
-        return 'boolean';
+    if (input.config.type !== 'string') {
+        return input.config.type;
     }
     return input.config.multiple === true ? 'list' : 'string';
 }
@@ -78,6 +89,9 @@ function rawValue(kind, value) {
     if (kind === 'boolean') {
         return typeof value === 'boolean' ? value : undefined;
     }
+    if (kind === 'count') {
+        return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : undefined;
+    }
     return typeof value === 'string' ? value : undefined;
 }
 /**
@@ -150,7 +164,7 @@ function sourceFailure(sentence, error) {
  * Core builds the context before the call, so a fault of its own is never the plugin's.
  */
 async function askSource(stage, call) {
-    const { owner, requested } = call;
+    const { options, owner, requested } = call;
     const resolver = await loadDefault(owner.identity, owner.source.load, {
         guard: isResolverExport,
         noun: 'source',
@@ -162,7 +176,8 @@ async function askSource(stage, call) {
     const context = {
         graph: stage.inspected(),
         host: stage.host,
-        options: pluginValues(owner.inputs, stage.globals.values),
+        // Validation produced the record the plugin's option types describe.
+        options,
         out: stage.out,
         requests: requested.map(({ input, scope }) => stage.request(input, scope.global)),
         style: stage.style,
@@ -193,8 +208,8 @@ async function askSource(stage, call) {
 }
 /**
  * The environment tier: each option in scope that argv left unfilled reads its bound variable. A
- * filled option is labeled with its variable, and a Boolean one outside the grammar is recorded
- * as rejected, which fills nothing.
+ * filled option is labeled with its variable, and a Boolean or counted one outside its grammar is
+ * recorded as rejected, which fills nothing.
  */
 function fillFromEnvironment(scopes, env) {
     const labels = new Map();
@@ -228,8 +243,11 @@ function requestedOf(scopes, excluded, bound) {
 }
 /**
  * The input-source stage: the environment, then the configuration source, for every option in
- * scope that argv left unfilled. When no option is left to ask, the source never loads. A source
- * fault stops the stage and fills nothing more.
+ * scope that argv left unfilled. When no option is left to ask, the source never loads. The
+ * source's own options pass their validators before it loads, and when one is rejected the source
+ * is never called and the problem reports with every other validation problem, while each option
+ * the source would have been asked to fill reports no missing value. A source fault stops the
+ * stage and fills nothing more.
  */
 async function fillInputs(stage) {
     const scopes = stage.locals ? [stage.globals, stage.locals] : [stage.globals];
@@ -239,20 +257,32 @@ async function fillInputs(stage) {
         ? requestedOf(scopes, rejected, { binding: owner.source.binding, extensions: stage.extensions })
         : [];
     if (!owner || requested.length === 0) {
-        return { fault: undefined, labels, rejected };
+        return { fault: undefined, labels, rejected, validated: undefined };
     }
+    let validated = undefined;
     try {
-        for (const { label, target, value } of await askSource(stage, { owner, requested })) {
+        validated = await stage.validate(owner.inputs, { labels, rejected });
+        // A rejected own option skips the source, and the options it would have filled report no omission.
+        if (validated.failure) {
+            const unanswered = new Set(requested.map(({ input }) => input));
+            return { fault: undefined, labels, rejected, unanswered, validated };
+        }
+        // A run cancelled while the source's own options were validated loads nothing.
+        if (stage.signal.aborted) {
+            return { fault: undefined, labels, rejected, validated };
+        }
+        const options = frozenValues(owner.inputs, validated.values);
+        for (const { label, target, value } of await askSource(stage, { options, owner, requested })) {
             fill(target.scope.values, target.input.name, value);
             labels.set(target.input.name, label);
         }
-        return { fault: undefined, labels, rejected };
+        return { fault: undefined, labels, rejected, validated };
     }
     catch (error) {
         // The resolver's own failure keeps its class, and so its code.
         // Every other fault above is raised as an internal error, and anything else is wrapped the same way.
         const fault = error instanceof LoomError ? error : foreignFailure(error);
-        return { fault, labels, rejected };
+        return { fault, labels, rejected, validated };
     }
 }
 export { fillInputs };

package/dist/types.d.ts

@@ -8,12 +8,18 @@ import type { RenderingPolicy } from './rendering.js';
 import type { ContextualStyle } from './style.js';
 type LowercaseLetter = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z';
 type ShortAlias = LowercaseLetter | Uppercase<LowercaseLetter>;
+/**
+ * The spellings an option declares beyond its long form. `aliases` adds a long spelling for each
+ * name, so `shortOnly`, which removes every long spelling, never declares one.
+ */
 type OptionSpelling = {
     short?: ShortAlias;
     shortOnly?: false;
+    aliases?: readonly string[];
 } | {
     short: ShortAlias;
     shortOnly: true;
+    aliases?: never;
 };
 type Presence = {
     required: true;
@@ -48,6 +54,24 @@ type Omission = {
 } | {
     validateOmitted?: false;
 };
+/**
+ * The presence rules a global option never declares, because its validation runs on every Command.
+ * `GlobalOptionConfig` and `GlobalOmissionConstraint` both read the rule from here.
+ */
+type PresenceRuleKey = 'required' | 'validateOmitted';
+/** The fault each presence rule names when a global option declares it. */
+interface PresenceRuleFaults {
+    required: {
+        'A global option declares no required; the Commands that read it check for it': never;
+    };
+    validateOmitted: {
+        'A global option declares no validateOmitted; its omission is plain absence': never;
+    };
+}
+/** The first presence rule a config declares, in the order the faults name them. */
+type DeclaredPresenceRule<Config> = {
+    [Key in PresenceRuleKey]: [Extract<Config, Record<Key, unknown>>] extends [never] ? never : Key;
+}[PresenceRuleKey];
 /**
  * The one-line summary every projection reads. It is a core fact: optional, and a string that holds
  * a character other than whitespace and no line terminator.
@@ -156,8 +180,11 @@ export interface InputIdentity {
 export interface SuppliedInputs {
     /** Raw positional values of the routed Command: one string, or the tokens of a variadic. */
     args: Readonly<Record<string, string | readonly string[] | undefined>>;
-    /** Raw option values, globals and locals: a string, every occurrence, or a Boolean presence. */
-    options: Readonly<Record<string, string | readonly string[] | boolean | undefined>>;
+    /**
+     * Raw option values, globals and locals: a string, every occurrence, a Boolean presence, or the
+     * number of times a counted option was supplied.
+     */
+    options: Readonly<Record<string, string | readonly string[] | boolean | number | undefined>>;
 }
 /**
  * What core knows when it calls one schema. A default validates before any token is read, so its
@@ -317,7 +344,7 @@ export interface ResultBinding {
 /**
  * The routed Command's invocation after parsing and validation, which every middleware reads. The
  * values are what the action receives, the output of each declaration's schema, for that Command's
- * own arguments and local options; global and plugin option values are not here. The records are
+ * own arguments and local options; global option values are not here. The records are
  * untyped and frozen, because a middleware runs ahead of every action and the graph carries no
  * type for a value.
  */
@@ -341,6 +368,8 @@ export type StringOption = OptionSpelling & Presence & Multiplicity & Omission &
     type: 'string';
     polarity?: never;
     validate?: StandardSchemaV1;
+    /** The value a bare spelling supplies, so an explicit value is attached to the spelling. */
+    implied?: string;
 };
 /** A variadic argument collects the remaining tokens, so it follows the multiple option rules. */
 export type VariadicArgument = Presence & Described & ArgumentExtensions & {
@@ -357,6 +386,19 @@ export type ValidatedValue<Config, Raw> = Config extends unknown ? 'validate' ex
 export type DefaultConstraint<Config> = Config extends unknown ? Config & {
     default?: 'validate' extends keyof Config ? PerValue<Config, SchemaInput<Config['validate']>> : RawValue<Config>;
 } : never;
+/**
+ * An implied value is the string an operator would otherwise attach, so it must be a string the
+ * validator's input type accepts, as a default must be. A multiple option's validator reads one
+ * value, so the implied value meets that one value's input type. A validator that declares no types
+ * infers `never`, so it states nothing to check against. The key names the fault, the way the
+ * other declaration constraints do, because an intersection with the literal would reduce the whole
+ * config to `never` and report every key.
+ */
+export type ImpliedConstraint<Config> = Config extends {
+    implied: infer Implied;
+} ? 'validate' extends keyof Config ? [SchemaInput<Config['validate']>] extends [never] ? unknown : Implied extends SchemaInput<Config['validate']> ? unknown : {
+    'An implied value must be in the validator input type': Config['validate'];
+} : unknown : unknown;
 /**
  * A multiple option or a variadic argument passes each value to its validator alone, so the
  * declared validator must accept one `string`. The key names the fault, the way the other
@@ -404,19 +446,9 @@ export type ValidateOmittedConstraint<Config> = Config extends {
 /**
  * A global option declares no presence rule, so its omission is always plain absence. A union
  * config fails when any member declares the key, and a wide `OptionConfig` passes, because its
- * members only allow the key.
+ * members only allow the key. `required` is named first when a config declares both.
  */
-export type GlobalOmissionConstraint<Config> = [Extract<Config, {
-    required: unknown;
-}>] extends [
-    never
-] ? [Extract<Config, {
-    validateOmitted: unknown;
-}>] extends [never] ? unknown : {
-    'A global option declares no validateOmitted; its omission is plain absence': never;
-} : {
-    'A global option declares no required; the Commands that read it check for it': never;
-};
+export type GlobalOmissionConstraint<Config> = [DeclaredPresenceRule<Config>] extends [never] ? unknown : PresenceRuleFaults['required' extends DeclaredPresenceRule<Config> ? 'required' : 'validateOmitted'];
 export type ArgumentValue<Config extends ArgumentConfig> = Config extends {
     variadic: true;
 } ? ValidatedValue<Config, string[]> : ValidatedValue<Config, string> | (Config extends {
@@ -433,6 +465,7 @@ export type BooleanOption = (OptionSpelling & Described & Listed & EnvBinding &
     multiple?: never;
     required?: never;
     validateOmitted?: never;
+    implied?: never;
     polarity?: 'positive' | 'negative';
 }) | (Described & Listed & EnvBinding & OptionExtensions & {
     type: 'boolean';
@@ -441,27 +474,34 @@ export type BooleanOption = (OptionSpelling & Described & Listed & EnvBinding &
     multiple?: never;
     required?: never;
     validateOmitted?: never;
+    implied?: never;
     polarity: 'both';
     short?: ShortAlias;
     shortOnly?: false;
+    aliases?: readonly string[];
 });
-export type OptionConfig = StringOption | BooleanOption;
 /**
- * The parsing part of a string option config, which is all a plugin option declares. A plugin
- * option carries no schema and no presence rule, because the pre-scan consumes it ahead of routing,
- * where the validation context every schema is promised cannot exist. Its middleware interprets
- * the value.
- * A Boolean plugin option is an ordinary `BooleanOption`, which already declares none of them.
+ * A counted option takes no value and reads how many times it was supplied, across every spelling,
+ * so it declares no validator, default, presence rule, collection, polarity, or implied value.
  */
-export type PluginStringOption = OptionSpelling & Multiplicity & Described & Listed & OptionExtensions & {
-    type: 'string';
-    default?: string | string[];
-    polarity?: never;
-    required?: never;
+export type CountOption = OptionSpelling & Described & Listed & EnvBinding & OptionExtensions & {
+    type: 'count';
     validate?: never;
+    default?: never;
+    multiple?: never;
+    required?: never;
     validateOmitted?: never;
+    polarity?: never;
+    implied?: never;
 };
-export type PluginOptionConfig = PluginStringOption | BooleanOption;
+export type OptionConfig = StringOption | BooleanOption | CountOption;
+/**
+ * The configuration of a global option a plugin declares: everything `option()` takes except the
+ * presence rules, which a global option never declares, because its validation runs on every
+ * Command. `globalOption()` states the same rule through `GlobalOmissionConstraint`, which also
+ * accepts a config typed as the wide `OptionConfig`.
+ */
+export type GlobalOptionConfig = OptionConfig & Readonly<Partial<Record<PresenceRuleKey, never>>>;
 export type OptionValue<Config extends OptionConfig> = Config extends StringOption ? Config extends {
     multiple: true;
 } ? ValidatedValue<Config, string[]> : ValidatedValue<Config, string> | (Config extends {
@@ -470,7 +510,7 @@ export type OptionValue<Config extends OptionConfig> = Config extends StringOpti
     default: unknown;
 } | {
     validateOmitted: true;
-} ? never : undefined) : boolean;
+} ? never : undefined) : Config extends CountOption ? number : boolean;
 /**
  * What an action receives. `graph` is the frozen graph `inspect()` returns for this run, and
  * `command` is the routed node inside it: the same two values the run's middleware receive.