@loomcli/core 0.6.0 → 0.8.0

package/dist/command.d.ts

@@ -4,12 +4,12 @@ import type { LoomError } from './errors.js';
 import type { AdmittedDescriptor, DescriptorRegistry, ExtensionRecords, ExtensionStore, ExtensionSubject, ExtensionValue } from './extension.js';
 import type { BuiltGlobals, GlobalsState, GlobalTable, InputRecords } from './globals.js';
 import type { CommandGraph, CommandNode } from './inspect.js';
-import { compileOptions } from './options.js';
-import type { OptionValues } from './options.js';
+import type { OptionValues, SpellingTable } from './options.js';
+import type { ParsedInvocation } from './parse.js';
 import type { BuiltPlugin } from './plugin.js';
 import type { ContextualStyle } from './style.js';
-import type { Action, ActionChannel, ArgumentConfig, ArgumentValue, declaredTypes, DeclaredResult, DeclaredTypes, DefaultConstraint, GlobalNameConstraint, Host, PerValueConstraint, NameConstraint, OpenResult, OptionConfig, OptionValue, Out, Request, ResultBinding, ResultViews, ResultViewsOf, RowViews, ValidateOmittedConstraint } from './types.js';
-import type { ArgumentInput, DefaultValues, InputPlaces, InputDeclaration, OptionInput, ValidatedInputs } from './validation.js';
+import type { Action, ActionChannel, ArgumentConfig, ArgumentValue, declaredTypes, DeclaredResult, DeclaredTypes, DefaultConstraint, ImpliedConstraint, GlobalNameConstraint, Host, PerValueConstraint, NameConstraint, OpenResult, OptionConfig, OptionValue, Out, Request, ResultBinding, ResultViews, ResultViewsOf, RowViews, ValidateOmittedConstraint } from './types.js';
+import type { ArgumentInput, InputPlaces, InputDeclaration, OptionInput, DeclaredValues, ValidatedInputs } from './validation.js';
 /** One positional slot: the declaration it fills and whether it takes the remaining tokens. */
 export interface ArgumentSlot {
     input: InputDeclaration;
@@ -58,7 +58,12 @@ export interface BuiltCommand {
     hidden: boolean;
     inputs: readonly InputDeclaration[];
     name: string | null;
-    options: ReturnType<typeof compileOptions>;
+    /**
+     * The one table the parser reads this Command's words against, built after every lifecycle hook
+     * ran: its own options, hook-declared ones included, and every global option. Each entry names
+     * one declaration, so a group's table holds the global options alone.
+     */
+    table: SpellingTable;
     /** The result the Command declares, or nothing where it declares none. */
     /** The built declaration is the shape the write site reads, so the channel carries it. */
     result: DeclaredResult | undefined;
@@ -290,14 +295,14 @@ export interface BuiltGraph {
  * The globals table compiles once per build and the whole graph shares it. The root's registry
  * holds every descriptor the Application names, so a hook's `extend()` call meets all of them.
  */
-export declare function buildGraph<Args, Options, Globals>(root: CommandState<Args, Options, Globals>, globals: GlobalsState<Globals>, plugins: readonly BuiltPlugin[]): BuiltGraph;
+export declare function buildGraph<Args, Options, Globals>(root: CommandState<Args, Options, Globals>, globals: GlobalsState, plugins: readonly BuiltPlugin[]): BuiltGraph;
 export declare class CommandBuilder<Args, Options, Globals, State extends CommandMethod = CommandMethod, Result = unknown> {
     #private;
     readonly [commandValue]: true;
     readonly [declaredTypes]: DeclaredTypes<Args, Options, Globals, Result>;
     constructor(name: string, state: CommandState<Args, Options, Globals>);
     argument<const Name extends string, const Config extends ArgumentConfig>(name: Name, config: Config & NameConstraint<Name> & NoInfer<DefaultConstraint<Config>> & NoInfer<PerValueConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Command<Args & Record<Name, ArgumentValue<Config>>, Options, Globals, AfterArgument<State>, Result>;
-    option<const Name extends string, const Config extends OptionConfig>(name: Name, config: Config & NameConstraint<Name> & GlobalNameConstraint<Name, Globals> & NoInfer<DefaultConstraint<Config>> & NoInfer<PerValueConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Command<Args, Options & Record<Name, OptionValue<Config>>, Globals, State, Result>;
+    option<const Name extends string, const Config extends OptionConfig>(name: Name, config: Config & NameConstraint<Name> & GlobalNameConstraint<Name, Globals> & NoInfer<DefaultConstraint<Config>> & NoInfer<ImpliedConstraint<Config>> & NoInfer<PerValueConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Command<Args, Options & Record<Name, OptionValue<Config>>, Globals, State, Result>;
     /**
      * Aliases are other portable names that route to this Command. They invalidate no call, and the
      * tuple rest parameter rejects a call that names none.
@@ -369,48 +374,20 @@ export declare const Command: CommandConstructor;
 /** Every declaration in the graph, so defaults are validated before any token is read. */
 export declare function collectInputs(command: BuiltCommand): InputDeclaration[];
 /**
- * Where every input of one graph was declared: each global option at its `globalOption()` call,
- * and each Command's own inputs at their calls on the Command, under its path from the root.
+ * Where every input of one graph was declared: each global option at its `globalOption()` call or
+ * in its plugin's `options` record, and each Command's own inputs at their calls on the Command,
+ * under its path from the root.
  */
 export declare function inputPlaces(graph: BuiltGraph): InputPlaces;
-/**
- * Whether a token names one of the Command's children: the Command has children and the token is
- * no option token. Routing and `locate` read a bare word through this rule.
- */
-export declare function readsAsChild(command: BuiltCommand, token: string): boolean;
-/**
- * Bare tokens, names or aliases, select children until a Command has none; a hyphen commits.
- * `walked` receives the path after each name routes, so an unknown Command leaves its caller
- * holding the partial path walked before it.
- */
-export declare function route(root: BuiltCommand, tokens: readonly string[], walked?: (path: readonly string[]) => void): {
-    command: BuiltCommand;
-    path: string[];
-    tokens: string[];
-};
-/**
- * The slot the positional at one index fills: the slot at that index, else a variadic last slot,
- * which accepts every later positional, else none. Binding and `locate` read positions through it.
- */
-export declare function argumentSlot(slots: readonly ArgumentSlot[], position: number): ArgumentSlot | undefined;
-/** One invocation after the pre-scan and routing, which the middleware chain runs on top of. */
-export interface RoutedInvocation {
-    command: BuiltCommand;
-    path: readonly string[];
-    scan: OptionValues;
-    tokens: readonly string[];
-}
-/**
- * Consumes the globals table, then routes the remaining bare tokens to a Command. `walked`
- * receives the path as routing extends it, the partial path of an unknown Command included.
- */
-export declare function routeInvocation(graph: BuiltGraph, argv: readonly string[], walked: (path: readonly string[]) => void): RoutedInvocation;
 /** What one invocation reaches the middleware chain with. */
 export interface DispatchInvocation {
     /** The channel the action receives, which the results lane builds from the routed node. */
     channel: (binding: ResultBinding) => ActionChannel;
-    defaults: DefaultValues;
     host: Host;
+    /** Where every input of the graph was declared, which a broken validator's finding rebuilds. */
+    places: InputPlaces;
+    /** Every declared default and implied value, validated before any token was read. */
+    declaredValues: DeclaredValues;
     /** The graph `inspect()` returns for the run, built on its first read, which a source reads. */
     inspected: () => CommandGraph;
     /** Offers a configuration source's foreign throw to the translators where its call settles. */
@@ -425,11 +402,14 @@ export interface DispatchInvocation {
  * reads and the call that dispatches; `'held'` carries the fault this phase found, which core
  * raises at the dispatch boundary and never before, so a takeover swallows it. `result` is what the
  * routed Command declared, whose views a middleware selects among, on either shape. `globals` holds
- * the globals table's values after the input-source stage, which activation and every plugin's own
- * options read on either shape.
+ * the globals table's values after the input-source stage, which activation and each plugin's
+ * spellings read on either shape. `options` is every global option's validated value, which every
+ * middleware reads, or `null` when a global option has a structural fault or was rejected, or the
+ * values could not be read.
  */
 export type Prepared = {
     globals: OptionValues;
+    options: Readonly<Record<string, unknown>> | null;
     result: DeclaredResult | undefined;
 } & ({
     dispatch: (view: string | null) => Promise<void>;
@@ -443,8 +423,12 @@ export type Prepared = {
 /**
  * Prepares one dispatch ahead of the middleware chain and holds whatever fault it found, so a
  * middleware reads the request before the action runs and a takeover never observes the fault.
- * The phases run in order: local parsing, the input-source stage, and validation. A local fault
- * outranks a configuration source's fault, and after either one core runs no validation.
+ * The phases run in order: the structural fault parsing held, a group's missing subcommand, the
+ * input-source stage, and validation. Either of the first two outranks a configuration source's
+ * fault, and a source's fault takes the place of every validation problem. Validation checks the
+ * global options whatever was held, so a middleware reads them after a local fault; a structural
+ * fault on a global option, a rejected global option, a source's fault, or a validator's own fault
+ * leaves `options` `null`.
  */
-export declare function prepareDispatch(graph: BuiltGraph, routed: RoutedInvocation, invocation: DispatchInvocation): Promise<Prepared>;
+export declare function prepareDispatch(graph: BuiltGraph, routed: ParsedInvocation, invocation: DispatchInvocation): Promise<Prepared>;
 export {};