@loomcli/core 0.5.0 → 0.7.0

package/dist/command.d.ts

@@ -1,5 +1,7 @@
+import type { Finding } from './diagnostic-text.js';
 import type { RegisteredGlobals } from './environment.js';
-import type { AnyExtension, DescriptorRegistry, ExtensionRecords, ExtensionStore, ExtensionSubject, ExtensionValue } from './extension.js';
+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';
@@ -7,7 +9,7 @@ import type { OptionValues } from './options.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, InputDeclaration, OptionInput, ValidatedInputs } from './validation.js';
+import type { ArgumentInput, DefaultValues, InputPlaces, InputDeclaration, OptionInput, ValidatedInputs } from './validation.js';
 /** One positional slot: the declaration it fills and whether it takes the remaining tokens. */
 export interface ArgumentSlot {
     input: InputDeclaration;
@@ -88,10 +90,14 @@ export interface CommandNodeHandle {
     readonly name: string;
     build(context: BuildContext): BuiltCommand;
 }
-/** One attached child, under the canonical name its parent's namespace holds it by. */
+/**
+ * One attached child, under the canonical name its parent's namespace holds it by, with the call
+ * that attached it, which a diagnostic about the child as a whole marks.
+ */
 export interface AttachedChild {
     readonly name: string;
     readonly node: CommandNodeHandle;
+    readonly placement: Finding;
 }
 /**
  * One graph build's shared state. `globals` compiles once and every Command reads it. The build is
@@ -108,6 +114,12 @@ interface BuildContext {
 }
 /** The handle behind a value an author built as a Command, or nothing for any other value. */
 export declare function commandNode(value: unknown): CommandNodeHandle | undefined;
+/** A call's arguments as its author wrote them: the trailing ones left undefined are dropped. */
+export declare function callArguments(...values: readonly unknown[]): readonly unknown[];
+/** A Command value as a finding prints it, which it would otherwise print as an ellipsis. */
+export declare function commandCode(name: string): object;
+/** The finding for one `command()` call that attached a child under the Command at `path`. */
+export declare function commandPlacement(path: readonly string[], child: string): Finding;
 /**
  * The portable name rule, for every name an operator types as a command at a shell prompt: the
  * application name, every Command name, and every alias. The characters are the POSIX portable
@@ -118,17 +130,20 @@ export declare function isPortableName(name: unknown): name is string;
 /** The one correction every portable name diagnostic ends with. */
 export declare const portableNameCorrection = "Use a nonempty name of A-Z, a-z, 0-9, \".\", \"_\", and \"-\" that does not start with \"-\" or \".\".";
 /**
- * One call of the results lane, in the order it was made. A `result()` or `rows()` call declares
- * the unit, and a `views()` call reshapes the views of whichever declaration it follows.
+ * One call of the results lane, in the order it was made, with the arguments a finding rebuilds it
+ * from. A `result()` or `rows()` call declares the unit, and a `views()` call reshapes the views of
+ * whichever declaration it follows.
  */
 export type ResultCall = {
+    arguments: readonly unknown[];
+} & ({
     kind: 'value' | 'rows';
     views: unknown;
 } | {
     default: unknown;
     kind: 'views';
     views: unknown;
-};
+});
 /** The core facts a named Command declares, which its constructor checked. The root carries none. */
 export interface CommandFacts {
     deprecated: string | undefined;
@@ -157,7 +172,7 @@ export interface CommandState<Args, Options, Globals> {
      * Every descriptor this declaration's extension values name, by identity. The root's holds the
      * whole Application's: its plugins', its global options', and every attached subtree's.
      */
-    descriptors: ReadonlyMap<string, AnyExtension>;
+    descriptors: ReadonlyMap<string, AdmittedDescriptor>;
     /** The extension values of every layer, validated at the call that carried each one. */
     extensions: ExtensionStore;
     facts: CommandFacts;
@@ -176,19 +191,19 @@ export declare function layerOf(name: string | null): ExtensionSubject;
  * declaration values arrive checked, because the constructor that read them threw for any fault.
  */
 export declare function freshState<Globals>(declaration: {
-    descriptors: ReadonlyMap<string, AnyExtension>;
+    descriptors: ReadonlyMap<string, AdmittedDescriptor>;
     extensions: ExtensionStore;
     facts: CommandFacts;
     name: string | null;
 }): CommandState<{}, {}, Globals>;
 /** The declared value joins `args` under its literal name, typed by its own config. */
-export declare function declareArgument<Args, Options, Globals, Name extends string, Config extends ArgumentConfig>(state: CommandState<Args, Options, Globals>, input: ArgumentInput<Name, Config>): CommandState<Args & Record<Name, ArgumentValue<Config>>, Options, Globals>;
+export declare function declareArgument<Args, Options, Globals, Name extends string, Config extends ArgumentConfig>(state: CommandState<Args, Options, Globals>, declared: ArgumentInput<Name, Config>): CommandState<Args & Record<Name, ArgumentValue<Config>>, Options, Globals>;
 /**
  * The declared value joins `options` under its literal name, typed by its own config. The root's
  * options also meet the Application's globals table, which a named Command meets when its subtree
  * joins an Application.
  */
-export declare function declareOption<Args, Options, Globals, Name extends string, Config extends OptionConfig>(state: CommandState<Args, Options, Globals>, input: OptionInput<Name, Config>, table?: GlobalTable): CommandState<Args, Options & Record<Name, OptionValue<Config>>, Globals>;
+export declare function declareOption<Args, Options, Globals, Name extends string, Config extends OptionConfig>(state: CommandState<Args, Options, Globals>, declared: OptionInput<Name, Config>, table?: GlobalTable): CommandState<Args, Options & Record<Name, OptionValue<Config>>, Globals>;
 /**
  * One call's names join the Command's aliases. A call that names none, which the types reject and
  * a JavaScript author can still write, reports as the call it is.
@@ -211,35 +226,48 @@ export declare function declareAction<Args, Options, Globals, Result>(state: Com
 export declare function declareResult<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, kind: 'value' | 'rows', declaration: unknown): CommandState<Args, Options, Globals>;
 /** A `views()` call reshapes views and closes nothing, so it is never a late declaration. */
 export declare function declareResultViews<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, replacements: unknown, options: unknown): CommandState<Args, Options, Globals>;
-/** The parent one attach reads: its name, the children it holds, and the calls that close it. */
-interface AttachParent {
+/** One Command a rule judges: the name its sentence reads, and the path its findings open with. */
+interface CommandPlace {
+    name: string | null;
+    path: readonly string[];
+}
+/** The parent one attach reads: its place, the children it holds, and the calls that close it. */
+interface AttachParent extends CommandPlace {
     /** The first argument the parent declares, which no child may sit beside. */
-    argument: string | undefined;
+    argument: InputDeclaration | undefined;
     children: readonly AttachedChild[];
     hasAction: boolean;
-    name: string | null;
 }
 /**
  * The one attach operation `Command.command()`, `Application.command()`, and a plugin's
  * `commands` list share. A Command is an immutable value, so the child is final here: it is checked
  * as a finished Command, against the parent's current children, and against the nesting cap from
- * the shallowest level the parent can sit at.
+ * the shallowest level the parent can sit at. The placement is the call that attached it, which a
+ * finding about the child as a whole marks.
  */
-export declare function attach(parent: AttachParent, node: CommandNodeHandle): AttachedChild;
+export declare function attach(parent: AttachParent, node: CommandNodeHandle, placement: Finding): AttachedChild;
 /** The handle behind the value one `command()` call received; anything else is a declaration error. */
 export declare function childNode(parent: string | null, child: unknown): CommandNodeHandle;
+/** The first place an Application holds one Command value: its parent's name and the attach call. */
+export interface ChildOwner {
+    name: string | null;
+    placement: Finding;
+}
 /** What an Application holds while a subtree joins it, each register a copy the caller commits. */
 interface JoinScope {
     descriptors: DescriptorRegistry;
-    /** The parent that claimed each node the Application holds, by the name a diagnostic reads. */
-    owners: Map<CommandNodeHandle, string | null>;
+    /** The first place that claimed each node the Application holds. */
+    owners: Map<CommandNodeHandle, ChildOwner>;
     table: GlobalTable;
 }
 /**
  * Attaches one child to an Application's root and walks the subtree it brings, once. The scope's
  * registers are copies: the caller commits the owners, and the returned root holds the descriptors.
  */
-export declare function attachToRoot<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, node: CommandNodeHandle, scope: JoinScope): CommandState<Args, Options, Globals>;
+export declare function attachToRoot<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, child: {
+    node: CommandNodeHandle;
+    placement: Finding;
+}, scope: JoinScope): CommandState<Args, Options, Globals>;
 /**
  * A declaration's own options and every attached Command's, against a globals table that has just
  * grown. The table's new option reads as the other side of any collision.
@@ -340,13 +368,22 @@ type CommandConstructor = new (name: string, options?: CommandOptions) => Comman
 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.
+ */
+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. */
-export declare function route(root: BuiltCommand, tokens: readonly string[]): {
+/**
+ * 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[];
@@ -363,8 +400,11 @@ export interface RoutedInvocation {
     scan: OptionValues;
     tokens: readonly string[];
 }
-/** Consumes the globals table, then routes the remaining bare tokens to a Command. */
-export declare function routeInvocation(graph: BuiltGraph, argv: readonly string[]): RoutedInvocation;
+/**
+ * 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. */
@@ -373,6 +413,8 @@ export interface DispatchInvocation {
     host: Host;
     /** 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. */
+    offer: (thrown: unknown) => LoomError | undefined;
     signal: AbortSignal;
     /** The channel a configuration source writes through, whose results call names the source. */
     sourceOut: Out<OpenResult>;