@loomcli/core 0.4.0 → 0.6.0

package/dist/validation.d.ts

@@ -1,4 +1,6 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { Finding } from './diagnostic-text.js';
+import type { InputSite } from './facts.js';
 import type { OptionValues } from './options.js';
 import type { ArgumentConfig, ArgumentValue, Host, OptionConfig, OptionValue } from './types.js';
 /**
@@ -24,6 +26,14 @@ export interface ScopedInputs {
     globals: readonly InputDeclaration[];
     locals: readonly InputDeclaration[];
 }
+/**
+ * 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.
+ */
+interface Provenance {
+    labels: ReadonlyMap<string, string>;
+    rejected: ReadonlyMap<string, string>;
+}
 /** The raw tokens one invocation collected, keyed by declaration and by option name. */
 interface SuppliedValues {
     args: ReadonlyMap<InputDeclaration, string | string[]>;
@@ -36,8 +46,14 @@ export interface Invocation {
     host: Host;
     inputs: ScopedInputs;
     passthrough: readonly string[];
-    /** The run's cancellation signal, which stops this phase between two schema calls. */
+    /**
+     * 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.
+     */
+    plugins: readonly OptionInput[];
+    /** The run's cancellation signal, which stops this phase between two validator calls. */
     signal: AbortSignal;
+    sources: Provenance;
     supplied: SuppliedValues;
 }
 /**
@@ -59,6 +75,16 @@ declare class ValidatedInputs {
     read(input: InputDeclaration): unknown;
 }
 export type { ValidatedInputs };
+/**
+ * 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 declare function checkInputConfig(declared: {
+    readonly config: unknown;
+    readonly kind: InputDeclaration['kind'];
+    readonly name: string;
+}, place: InputPlace): void;
 /**
  * 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
@@ -66,7 +92,28 @@ export type { ValidatedInputs };
  */
 export declare function captureConfig<Config extends ArgumentConfig | OptionConfig>(config: Config): Config;
 /**
- * The declaration flag that sends an omitted value to its own schema. Every declaration reads it
+ * 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.
+ */
+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`.
+ */
+export declare function inputPlace(input: InputDeclaration, scope: {
+    readonly global: boolean;
+    readonly 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;
+/**
+ * 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 declare function validatesOmission(input: InputDeclaration): boolean;
@@ -76,17 +123,25 @@ export declare function validatesOmission(input: InputDeclaration): boolean;
  * helper, so a rejected item reads alike wherever its diagnostic is written.
  */
 export declare function issuePath(issue: StandardSchemaV1.Issue): string | undefined;
+/** One declaration and where it was declared, which its faults' findings rebuild. */
+export interface SitedInput {
+    readonly input: InputDeclaration;
+    readonly site: InputSite;
+}
 /**
- * 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 declare function checkDeclarations(inputs: readonly InputDeclaration[], named?: string): void;
+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 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 declare function prepareInputs(inputs: ScopedInputs, host: Host): Promise<DefaultValues>;
+export declare function prepareInputs(inputs: ScopedInputs, host: Host, places: InputPlaces): Promise<DefaultValues>;
 export declare function validateValues(invocation: Invocation): Promise<ValidatedInputs>;