@loomcli/core 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,266 @@
+/// <reference types="node" preserve="true" />
+import type { Readable, Writable } from 'node:stream';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+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>;
+type OptionSpelling = {
+    short?: ShortAlias;
+    shortOnly?: false;
+} | {
+    short: ShortAlias;
+    shortOnly: true;
+};
+type Presence = {
+    required: true;
+    default?: never;
+} | {
+    required?: false;
+    default?: unknown;
+};
+/** The literal member keeps `multiple: true` exact under contextual typing, as `Presence` does. */
+type Multiplicity = {
+    multiple: true;
+} | {
+    multiple?: false;
+};
+/**
+ * `validateOmitted: true` sends an omitted optional scalar to its own schema. The literal member
+ * keeps the flag exact under contextual typing, as `Multiplicity` does.
+ */
+type Omission = {
+    validateOmitted: true;
+} | {
+    validateOmitted?: false;
+};
+/**
+ * The tokens one declaration collects before validation: one string, or the whole collection. A
+ * multiple option and a variadic argument collect alike, so they share this raw shape.
+ */
+type RawValue<Config> = Config extends {
+    multiple: true;
+} | {
+    variadic: true;
+} ? string[] : string;
+type SchemaOutput<Schema, Raw> = Schema extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<Schema> : Raw;
+type SchemaInput<Schema> = Schema extends StandardSchemaV1 ? StandardSchemaV1.InferInput<Schema> : string;
+/** The named key states the rule, so a rejected declaration name reads as its own diagnostic. */
+interface LiteralNameFault {
+    'Declaration names must be one literal string': never;
+}
+type ActionArgument<Declaration> = ActionHandler<Declaration> extends (context: infer Context) => unknown ? Context : never;
+/** A local option name cannot repeat a key the globals already own; the key names the fault. */
+export type GlobalNameConstraint<Name extends string, Globals> = Name extends keyof Globals ? {
+    'This option name is already declared as a global option': Name;
+} : unknown;
+/** A required record key excludes open strings; distribution rejects each union member. */
+export type NameConstraint<Name extends string, Whole extends string = Name> = {} extends Record<Name, unknown> ? LiteralNameFault : Name extends Whole ? [Whole] extends [Name] ? unknown : LiteralNameFault : LiteralNameFault;
+export type ExitCode = 0 | 1 | 2;
+export interface InputTerminal {
+    isTTY: boolean;
+}
+export interface OutputTerminal extends InputTerminal {
+    columns: number | undefined;
+    rows: number | undefined;
+}
+export interface Host {
+    argv: string[];
+    cwd: string;
+    env: Record<string, string | undefined>;
+    terminal: {
+        stdin: InputTerminal;
+        stdout: OutputTerminal;
+        stderr: OutputTerminal;
+    };
+    stdin: Readable;
+    stdout: Writable;
+    stderr: Writable;
+}
+export interface RunOptions {
+    host?: Partial<Host>;
+}
+/** The declaration one schema call validates, under the name and the scope it was declared in. */
+export interface InputIdentity {
+    kind: 'argument' | 'option';
+    name: string;
+    global: boolean;
+}
+/**
+ * The raw tokens of one invocation, keyed by declared name, before any schema or default runs.
+ * Each schema call reads its own snapshot, so a collected value is read-only and writing to one
+ * changes nothing the parser, a later schema, or the action reads.
+ */
+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>>;
+}
+/**
+ * What core knows when it calls one schema. A default validates before any token is read, so its
+ * phase carries the host and the declaration alone. An invocation call adds the routed path, the
+ * passthrough tail, and the tokens every declared input received.
+ */
+export type ValidationContext = {
+    phase: 'default';
+    host: Host;
+    input: InputIdentity;
+} | {
+    phase: 'invocation';
+    host: Host;
+    input: InputIdentity;
+    command: readonly string[];
+    passthrough: readonly string[];
+    supplied: SuppliedInputs;
+};
+/**
+ * One value turned into the exact text core writes. A renderer owns every byte, the trailing
+ * newline included. It is synchronous and pure: it receives the value alone, returns a string, and
+ * holds no output handle. A throw or a non-string return is a renderer failure.
+ */
+export interface Renderer<Data> {
+    render: (data: Readonly<Data>) => string;
+}
+export interface Out {
+    print(message: string): Promise<void>;
+    info(message: string): Promise<void>;
+    success(message: string): Promise<void>;
+    warn(message: string): Promise<void>;
+    error(message: string): Promise<void>;
+    /** The neutral presentation call: a rendered value has no purpose and no destination. */
+    render<Data>(data: Data, renderer: Renderer<Data>): Promise<void>;
+    fatal(message: string): never;
+}
+export type StringOption = OptionSpelling & Presence & Multiplicity & Omission & {
+    type: 'string';
+    polarity?: never;
+    validate?: StandardSchemaV1;
+};
+/** A variadic argument collects the remaining tokens, so it follows the multiple option rules. */
+export type VariadicArgument = Presence & {
+    variadic: true;
+    validate?: StandardSchemaV1;
+};
+export type ScalarArgument = Presence & Omission & {
+    variadic?: false;
+    validate?: StandardSchemaV1;
+};
+export type ArgumentConfig = VariadicArgument | ScalarArgument;
+export type ValidatedValue<Config, Raw> = Config extends unknown ? 'validate' extends keyof Config ? SchemaOutput<Config['validate'], Raw> : Raw : never;
+/** Keep each conditional declaration paired with its own schema input type. */
+export type DefaultConstraint<Config> = Config extends unknown ? Config & {
+    default?: 'validate' extends keyof Config ? SchemaInput<Config['validate']> : RawValue<Config>;
+} : never;
+/**
+ * A multiple option hands its whole collection to one schema, so the declared schema must accept a
+ * `string[]` input. The key names the fault, the way the other declaration constraints do.
+ */
+export type MultipleConstraint<Config> = Config extends {
+    multiple: true;
+} ? 'validate' extends keyof Config ? string[] extends SchemaInput<Config['validate']> ? unknown : {
+    'A multiple option schema must accept a string[] input': Config['validate'];
+} : unknown : unknown;
+/**
+ * The declaration rules `validateOmitted: true` needs: a schema that accepts `undefined`, an
+ * omission the schema can answer, and no other rule that already decides absence. Each key names
+ * its fault, the way the other declaration constraints do.
+ */
+export type ValidateOmittedConstraint<Config> = Config extends {
+    validateOmitted: true;
+} ? Config extends {
+    type: 'boolean';
+} ? {
+    'A Boolean option declares no validateOmitted': never;
+} : Config extends {
+    required: true;
+} ? {
+    'A required input rejects validateOmitted': never;
+} : Config extends {
+    default: unknown;
+} ? {
+    'A declared default rejects validateOmitted': never;
+} : Config extends {
+    multiple: true;
+} | {
+    variadic: true;
+} ? {
+    'A collected input validates its omission as an empty array': never;
+} : 'validate' extends keyof Config ? undefined extends SchemaInput<Config['validate']> ? unknown : {
+    'A validateOmitted schema must accept an undefined input': Config['validate'];
+} : {
+    'validateOmitted needs a validate schema to receive the omission': never;
+} : unknown;
+export type ArgumentValue<Config extends ArgumentConfig> = Config extends {
+    variadic: true;
+} ? ValidatedValue<Config, string[]> : ValidatedValue<Config, string> | (Config extends {
+    required: true;
+} | {
+    default: unknown;
+} | {
+    validateOmitted: true;
+} ? never : undefined);
+export type BooleanOption = (OptionSpelling & {
+    type: 'boolean';
+    validate?: never;
+    default?: never;
+    multiple?: never;
+    required?: never;
+    validateOmitted?: never;
+    polarity?: 'positive' | 'negative';
+}) | {
+    type: 'boolean';
+    validate?: never;
+    default?: never;
+    multiple?: never;
+    required?: never;
+    validateOmitted?: never;
+    polarity: 'both';
+    short?: ShortAlias;
+    shortOnly?: false;
+};
+export type OptionConfig = StringOption | BooleanOption;
+export type OptionValue<Config extends OptionConfig> = Config extends StringOption ? Config extends {
+    multiple: true;
+} ? ValidatedValue<Config, string[]> : ValidatedValue<Config, string> | (Config extends {
+    required: true;
+} | {
+    default: unknown;
+} | {
+    validateOmitted: true;
+} ? never : undefined) : boolean;
+export interface ActionContext<Args, Options = {}> {
+    args: Args;
+    options: Options;
+    passthrough: string[];
+    out: Out;
+    host: Host;
+}
+export type Action<Args, Options = {}> = (context: ActionContext<Args, Options>) => unknown;
+/** Phantom key. It keeps the inferred declaration types exact and holds no runtime value. */
+export declare const declaredTypes: unique symbol;
+/**
+ * The three inferred types one declaration carries. The phantom member keeps them exact. Args and
+ * options widen, so a child can satisfy a looser reader. The globals appear in both a parameter and
+ * a return position, which makes them invariant: a child's globals must be the parent's own type,
+ * not a subset and not a superset, because one table serves every Command in the graph.
+ */
+export interface DeclaredTypes<Args, Options, Globals> {
+    args: Args;
+    globals: (value: Globals) => Globals;
+    options: Options;
+}
+/**
+ * The handler one declaration accepts. It reads the phantom types, not the `action()` call, so it
+ * holds on a fresh declaration, on a partly declared one, and on one that registered its action.
+ */
+export type ActionHandler<Declaration> = Declaration extends {
+    [declaredTypes]: DeclaredTypes<infer Args, infer Options, infer Globals>;
+} ? Action<Args, Globals & Options> : never;
+/** The args object an extracted handler receives for this declaration. */
+export type ActionArgs<Declaration> = ActionArgument<Declaration> extends {
+    args: infer Args;
+} ? Args : never;
+/** The options object an extracted handler receives, global values included. */
+export type ActionOptions<Declaration> = ActionArgument<Declaration> extends {
+    options: infer Options;
+} ? Options : never;
+export {};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validation.d.ts

@@ -0,0 +1,83 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { OptionValues } 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
+ * the config, never claimed apart from it, so a declaration cannot be written under a value type
+ * that its config does not produce. Untyped readers use the defaults.
+ */
+export interface ArgumentInput<Name extends string = string, Config extends ArgumentConfig = ArgumentConfig> {
+    readonly kind: 'argument';
+    readonly name: Name;
+    readonly config: Config;
+}
+export interface OptionInput<Name extends string = string, Config extends OptionConfig = OptionConfig> {
+    readonly kind: 'option';
+    readonly name: Name;
+    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 declarations one pass reads, by the scope that holds them: the graph's, then a Command's. */
+export interface ScopedInputs {
+    globals: readonly InputDeclaration[];
+    locals: readonly InputDeclaration[];
+}
+/** The raw tokens one invocation collected, keyed by declaration and by option name. */
+interface SuppliedValues {
+    args: ReadonlyMap<InputDeclaration, string | string[]>;
+    options: OptionValues;
+}
+/** Everything one invocation validates: its declarations, its tokens, and where they were read. */
+export interface Invocation {
+    command: readonly string[];
+    defaults: DefaultValues;
+    host: Host;
+    inputs: ScopedInputs;
+    passthrough: readonly string[];
+    supplied: SuppliedValues;
+}
+/**
+ * The validated values of one invocation, keyed by declaration. Only `validateValues` constructs
+ * one, and its two readers are the only places where a validated value takes its declared type, so
+ * every binder reads through them and none asserts on its own.
+ */
+declare class ValidatedInputs {
+    #private;
+    constructor(values: ReadonlyMap<InputDeclaration, unknown>);
+    /** The one-key record this argument contributes to `args`, typed by its own config. */
+    argument<Name extends string, Config extends ArgumentConfig>(input: ArgumentInput<Name, Config>): Record<Name, ArgumentValue<Config>>;
+    /** The one-key record this option contributes to `options`, typed by its own config. */
+    option<Name extends string, Config extends OptionConfig>(input: OptionInput<Name, Config>): Record<Name, OptionValue<Config>>;
+}
+export type { ValidatedInputs };
+/**
+ * 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.
+ */
+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
+ * here, and the declaration rules below reject it wherever another rule already decides absence.
+ */
+export declare function validatesOmission(input: InputDeclaration): boolean;
+/**
+ * The dotted path an issue names inside a value, or `undefined` when the issue names the value
+ * itself. Core's default text and an application's own renderer read a position through this one
+ * helper, so a rejected item reads alike wherever its diagnostic is written.
+ */
+export declare function issuePath(issue: StandardSchemaV1.Issue): string | undefined;
+/**
+ * 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()`.
+ */
+export declare function checkDeclarations(inputs: readonly InputDeclaration[]): void;
+/**
+ * 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.
+ */
+export declare function prepareInputs(inputs: ScopedInputs, host: Host): Promise<DefaultValues>;
+export declare function validateValues(invocation: Invocation): Promise<ValidatedInputs>;