@loomcli/core 0.6.0 → 0.8.0

package/dist/validation.d.ts

@@ -1,7 +1,10 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { CaptureFaults } from './capture.js';
 import type { Finding } from './diagnostic-text.js';
+import { DeclarationError, InputError } from './errors.js';
+import type { InputProblem } from './errors.js';
 import type { InputSite } from './facts.js';
-import type { OptionValues } from './options.js';
+import type { OptionValues, SpellingTable } from './options.js';
 import type { ArgumentConfig, ArgumentValue, Host, OptionConfig, OptionValue } from './types.js';
 /**
  * One declared input, typed by its literal name and its own config. The value type is derived from
@@ -19,8 +22,14 @@ export interface OptionInput<Name extends string = string, Config extends Option
     readonly config: Config;
 }
 export type InputDeclaration<Name extends string = string> = ArgumentInput<Name> | OptionInput<Name>;
-/** Validated defaults, read before any token is parsed. Values stay `unknown` here. */
-export type DefaultValues = ReadonlyMap<InputDeclaration, unknown>;
+/**
+ * The declared values validated before any token is parsed: each default, and each implied value a
+ * bare spelling supplies. Values stay `unknown` here.
+ */
+export interface DeclaredValues {
+    readonly defaults: ReadonlyMap<InputDeclaration, unknown>;
+    readonly implied: ReadonlyMap<InputDeclaration, unknown>;
+}
 /** The declarations one pass reads, by the scope that holds them: the graph's, then a Command's. */
 export interface ScopedInputs {
     globals: readonly InputDeclaration[];
@@ -28,11 +37,15 @@ export interface ScopedInputs {
 }
 /**
  * What the input-source stage leaves for validation's messages, by option name: the label of each
- * value it filled, and the variable of each Boolean option whose value is outside the grammar.
+ * value it filled, and the variable of each Boolean or counted option whose value is outside its
+ * grammar. `unanswered` holds each option a configuration source would have filled had one of its own
+ * options not been rejected; such an option reports no missing value and no absence rule judges it,
+ * because the operator's configuration may hold it.
  */
-interface Provenance {
+export interface Provenance {
     labels: ReadonlyMap<string, string>;
     rejected: ReadonlyMap<string, string>;
+    unanswered?: ReadonlySet<InputDeclaration>;
 }
 /** The raw tokens one invocation collected, keyed by declaration and by option name. */
 interface SuppliedValues {
@@ -42,19 +55,31 @@ interface SuppliedValues {
 /** Everything one invocation validates: its declarations, its tokens, and where they were read. */
 export interface Invocation {
     command: readonly string[];
-    defaults: DefaultValues;
+    /** Every declared default and implied value, validated before any token was read. */
+    declaredValues: DeclaredValues;
     host: Host;
     inputs: ScopedInputs;
     passthrough: readonly string[];
     /**
-     * The plugin options, which are never validated. A Boolean one whose variable is outside the
-     * grammar is still a problem of this phase, reported after the globals and before the locals.
+     * The declarations this pass validates, when it validates only some of `inputs`, such as a
+     * configuration source's own options ahead of its call. Every declaration of `inputs` still
+     * appears in the validation context's `supplied` record.
      */
-    plugins: readonly OptionInput[];
+    only?: ReadonlySet<InputDeclaration>;
+    /** Where each declaration was declared, which a broken validator's finding rebuilds. */
+    places: InputPlaces;
+    /**
+     * An earlier pass of this invocation, such as the one over a configuration source's own options.
+     * This pass reads each value it accepted and each problem it reported, in this pass's own order,
+     * and never sends those values to their validators a second time.
+     */
+    prior?: Validation;
     /** The run's cancellation signal, which stops this phase between two validator calls. */
     signal: AbortSignal;
     sources: Provenance;
     supplied: SuppliedValues;
+    /** The routed Command's spelling table, which names each option the way a problem reports it. */
+    table: SpellingTable;
 }
 /**
  * The validated values of one invocation, keyed by declaration. Only `validateValues` constructs
@@ -73,24 +98,40 @@ declare class ValidatedInputs {
      * middleware's request receives. The declared types stay with the two readers above.
      */
     read(input: InputDeclaration): unknown;
+    /** Whether this pass validated the declaration's value. */
+    has(input: InputDeclaration): boolean;
 }
 export type { ValidatedInputs };
+/** The faults a config's capture raises: those of every capture, and a default nested too deep. */
+export interface ConfigFaults extends CaptureFaults {
+    /** The default holds a path deeper than `defaultLevels`; the finding prints it elided. */
+    readonly tooDeep: () => DeclarationError;
+}
 /**
- * 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.
+ * Authoring's one read of a config, through `captureDeclaration`: the prototype verdict, the copy of
+ * 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 declare function checkInputConfig(declared: {
-    readonly config: unknown;
-    readonly kind: InputDeclaration['kind'];
-    readonly name: string;
-}, place: InputPlace): void;
+export declare function captureConfig<Config extends ArgumentConfig | OptionConfig>(config: Config, faults: ConfigFaults): Config;
+/** The fault of a default nested deeper than `defaultLevels`, declared by `subject`. */
+export declare function defaultDepthFault(subject: string, findings: readonly Finding[]): DeclarationError;
 /**
- * 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
- * other property is captured as declared, because core clones no library object.
+ * The config every `argument()`, `option()`, and `globalOption()` call, and every input a lifecycle
+ * hook declares, reads through `captureConfig`. A call in JavaScript that supplies none, or a value
+ * of another kind, reports a declaration fault and not a TypeError, and so does a config whose read
+ * throws. Each fault marks the config on the call at `place`.
  */
-export declare function captureConfig<Config extends ArgumentConfig | OptionConfig>(config: Config): Config;
+export declare function captureInputConfig<Config extends ArgumentConfig | OptionConfig>(declared: {
+    readonly config: Config;
+    readonly kind: InputDeclaration['kind'];
+    readonly name: string;
+}, place: InputPlace): 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.
@@ -99,19 +140,21 @@ export declare function declarationSubject(input: InputDeclaration): string;
 /** Where the call that declared one input sits: the call's name and the Command it is on. */
 export type InputPlace = Pick<Finding, 'call' | 'path'>;
 /**
- * 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 declare function inputPlace(input: InputDeclaration, scope: {
-    readonly global: boolean;
-    readonly path: readonly string[];
-}): InputPlace;
+export declare function inputPlace(input: InputDeclaration, path: readonly string[]): InputPlace;
 /**
  * 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 declare function declaringSite(input: InputDeclaration, place: InputPlace, subject?: string): InputSite;
+/**
+ * One input's site with its config printed elided, for a fault judged before the config is read,
+ * such as an invalid name, so the fault reads none of the config.
+ */
+export declare function configUnread(site: InputSite): InputSite;
 /**
  * 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.
@@ -136,12 +179,43 @@ export interface SitedInput {
  * diagnostics read with; every other caller is named by the declaration itself.
  */
 export declare function checkDeclarations(inputs: readonly SitedInput[], named?: string): void;
-/** The call that declared one input and the Command it sits on, which a default's fault rebuilds. */
-export type InputPlaces = ReadonlyMap<InputDeclaration, InputPlace>;
 /**
- * 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.
+ * The site of the call that declared each input, which a fault about its default or its validator
+ * rebuilds: `globalOption()` or a plugin's `options` record for a global option, and the input's
+ * own call on its Command for every other input.
+ */
+export type InputPlaces = ReadonlyMap<InputDeclaration, InputSite>;
+/**
+ * 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 declare function prepareDeclaredValues(inputs: ScopedInputs, host: Host, places: InputPlaces): Promise<DeclaredValues>;
+/** One rejected or missing input: the problem it reports, and the lines core's default text holds. */
+interface Report {
+    readonly lines: readonly string[];
+    readonly problem: InputProblem;
+}
+/**
+ * What one validation pass produced: every value its validator accepted, each input's report in
+ * reporting order, and those reports aggregated into one failure, or `undefined` when there were
+ * none. A pass that found problems still answers with the values it accepted, so a reader of the
+ * global options keeps them when only a local input was rejected.
+ */
+export interface Validation {
+    readonly failure: InputError | undefined;
+    readonly reports: ReadonlyMap<InputDeclaration, Report>;
+    readonly values: ValidatedInputs;
+}
+/**
+ * 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 declare function rejectsGlobal(validation: Validation): boolean;
+/**
+ * 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 declare function prepareInputs(inputs: ScopedInputs, host: Host, places: InputPlaces): Promise<DefaultValues>;
-export declare function validateValues(invocation: Invocation): Promise<ValidatedInputs>;
+export declare function validateValues(invocation: Invocation): Promise<Validation>;