clap-ts 0.2.0 → 0.3.0

package/dist/spec.d.ts

@@ -0,0 +1,83 @@
+/**
+ * A machine-readable description of a command tree.
+ *
+ * ```ts
+ * import { toSpec } from 'clap-ts/spec';
+ *
+ * writeFileSync('cli.json', JSON.stringify(toSpec(main), null, 2));
+ * ```
+ *
+ * Useful for generating a docs site, driving editor integration, or turning a
+ * CLI into tool definitions for something that calls it. The shape is plain
+ * JSON: no functions survive, so a `valueParser` function is reported only as
+ * the fact that one exists.
+ */
+import type { ArgDef, CommandDef, PossibleValue, ValueHint } from './types.js';
+/** One argument, flattened to JSON. */
+export interface ArgSpecJson {
+    readonly name: string;
+    readonly type: ArgDef['type'];
+    readonly description?: string;
+    readonly longDescription?: string;
+    readonly short?: string;
+    readonly long?: string;
+    readonly aliases?: readonly string[];
+    readonly visibleAliases?: readonly string[];
+    readonly valueName?: string;
+    readonly valueNames?: readonly string[];
+    readonly valueHint?: ValueHint;
+    readonly required: boolean;
+    readonly hidden: boolean;
+    readonly deprecated?: string | true;
+    readonly replacedBy?: string;
+    readonly global?: boolean;
+    readonly env?: string;
+    readonly default?: string | number | boolean | readonly string[];
+    readonly action?: ArgDef['action'];
+    readonly numArgs?: {
+        readonly min: number;
+        readonly max: number;
+    };
+    readonly possibleValues?: readonly PossibleValue[];
+    /** True when a function parser is attached; the function itself cannot serialise. */
+    readonly hasCustomParser?: boolean;
+    readonly conflictsWith?: readonly string[];
+    readonly requires?: readonly string[];
+    readonly groups?: readonly string[];
+    readonly helpHeading?: string;
+}
+/** One command, flattened to JSON, with its subcommands nested. */
+export interface CommandSpecJson {
+    readonly name: string;
+    readonly path: readonly string[];
+    readonly description?: string;
+    readonly about?: string;
+    readonly longAbout?: string;
+    readonly version?: string;
+    readonly author?: string;
+    readonly aliases?: readonly string[];
+    readonly hidden: boolean;
+    readonly deprecated?: string | true;
+    readonly replacedBy?: string;
+    readonly usage: string;
+    readonly args: readonly ArgSpecJson[];
+    readonly subcommands: readonly CommandSpecJson[];
+}
+export interface SpecOptions {
+    /** Root name; defaults to the command's binName or name. */
+    readonly name?: string;
+    /** Include args and commands marked hidden (default false). */
+    readonly includeHidden?: boolean;
+}
+/**
+ * Describe a command tree as plain JSON-safe data.
+ *
+ * Forces any `lazySubCommands` thunk, since the whole tree has to be walked.
+ */
+export declare function toSpec(command: CommandDef, opts?: SpecOptions): CommandSpecJson;
+/** Describe a command tree as a JSON string. */
+export declare function toSpecJson(command: CommandDef, opts?: SpecOptions & {
+    space?: number;
+}): string;
+/** Walk every command in a spec, root first. */
+export declare function walkSpec(spec: CommandSpecJson): Generator<CommandSpecJson>;

package/dist/spec.js

@@ -0,0 +1,124 @@
+/**
+ * A machine-readable description of a command tree.
+ *
+ * ```ts
+ * import { toSpec } from 'clap-ts/spec';
+ *
+ * writeFileSync('cli.json', JSON.stringify(toSpec(main), null, 2));
+ * ```
+ *
+ * Useful for generating a docs site, driving editor integration, or turning a
+ * CLI into tool definitions for something that calls it. The shape is plain
+ * JSON: no functions survive, so a `valueParser` function is reported only as
+ * the fact that one exists.
+ */
+import { possibleValues, subCommandsOf } from './parser.js';
+function defined(obj) {
+    for (const key of Object.keys(obj)) {
+        if (obj[key] === undefined) {
+            delete obj[key];
+        }
+    }
+    return obj;
+}
+function normalizeDeprecated(value) {
+    if (value === undefined || value === false) {
+        return undefined;
+    }
+    return value === true ? true : value;
+}
+function argToJson(key, def) {
+    const values = possibleValues(def);
+    const groups = def.group === undefined ? def.groups : [def.group, ...(def.groups ?? [])];
+    return defined({
+        name: key,
+        type: def.type,
+        description: def.description,
+        longDescription: def.longDescription,
+        short: def.short,
+        long: def.long ?? (def.type === 'positional' ? undefined : key),
+        aliases: def.alias,
+        visibleAliases: def.visibleAlias,
+        valueName: def.valueName,
+        valueNames: def.valueNames,
+        valueHint: def.valueHint,
+        required: def.required === true,
+        hidden: def.hidden === true,
+        deprecated: normalizeDeprecated(def.deprecated),
+        replacedBy: def.replacedBy,
+        global: def.global,
+        env: def.env,
+        default: def.default,
+        action: def.action,
+        numArgs: def.numArgs,
+        possibleValues: values.length > 0 ? values : undefined,
+        hasCustomParser: typeof def.valueParser === 'function' ? true : undefined,
+        conflictsWith: def.conflictsWith,
+        requires: def.requires,
+        groups,
+        helpHeading: def.helpHeading,
+    });
+}
+function usageOf(path, command, args) {
+    const parts = [...path];
+    if (args.some((a) => a.type !== 'positional')) {
+        parts.push('[OPTIONS]');
+    }
+    for (const arg of args) {
+        if (arg.type !== 'positional') {
+            continue;
+        }
+        const name = `<${arg.valueName ?? arg.name.toUpperCase()}>`;
+        parts.push(arg.required ? name : `[${name}]`);
+    }
+    if (Object.keys(subCommandsOf(command)).length > 0) {
+        parts.push(`[${command.meta.subcommandValueName ?? 'COMMAND'}]`);
+    }
+    return parts.join(' ');
+}
+function commandToJson(command, path, includeHidden) {
+    const argsDef = command.args ?? {};
+    const args = Object.entries(argsDef)
+        .filter(([, def]) => includeHidden || def.hidden !== true)
+        .map(([key, def]) => argToJson(key, def));
+    const subcommands = Object.entries(subCommandsOf(command))
+        .filter(([, sub]) => includeHidden || sub.meta.hidden !== true)
+        .map(([name, sub]) => commandToJson(sub, [...path, name], includeHidden));
+    const { meta } = command;
+    return defined({
+        name: meta.name,
+        path,
+        description: meta.description,
+        about: meta.about,
+        longAbout: meta.longAbout,
+        version: meta.version,
+        author: meta.author,
+        aliases: meta.aliases,
+        hidden: meta.hidden === true,
+        deprecated: normalizeDeprecated(meta.deprecated),
+        replacedBy: meta.replacedBy,
+        usage: usageOf(path, command, args),
+        args,
+        subcommands,
+    });
+}
+/**
+ * Describe a command tree as plain JSON-safe data.
+ *
+ * Forces any `lazySubCommands` thunk, since the whole tree has to be walked.
+ */
+export function toSpec(command, opts) {
+    const name = opts?.name ?? command.meta.binName ?? command.meta.name;
+    return commandToJson(command, [name], opts?.includeHidden === true);
+}
+/** Describe a command tree as a JSON string. */
+export function toSpecJson(command, opts) {
+    return JSON.stringify(toSpec(command, opts), null, opts?.space ?? 2);
+}
+/** Walk every command in a spec, root first. */
+export function* walkSpec(spec) {
+    yield spec;
+    for (const sub of spec.subcommands) {
+        yield* walkSpec(sub);
+    }
+}

package/dist/testing.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Test helpers: run a command definition and get back what it wrote and the
+ * code it settled on, without spawning a process or stubbing globals.
+ *
+ * ```ts
+ * import { runCli } from 'clap-ts/testing';
+ *
+ * const result = await runCli(main, ['serve', '--port', '8080']);
+ * expect(result.exitCode).toBe(0);
+ * expect(result.stdout).toContain('listening');
+ * ```
+ */
+import type { CommandDef, CommandContext, RunOptions } from './types.js';
+/** Everything a run produced. */
+export interface CliResult {
+    /** Text written to stdout, with ANSI escapes intact. */
+    readonly stdout: string;
+    /** Text written to stderr, with ANSI escapes intact. */
+    readonly stderr: string;
+    /** stdout with ANSI escapes removed, for readable assertions. */
+    readonly plainStdout: string;
+    /** stderr with ANSI escapes removed. */
+    readonly plainStderr: string;
+    /** The code the run settled on. 0 unless something failed. */
+    readonly exitCode: number;
+    /** An error that escaped the command handler, if any. */
+    readonly error?: unknown;
+}
+/** Strip ANSI colour codes from text. */
+export declare function stripAnsi(text: string): string;
+/** Options for runCli, minus the ones it controls itself. */
+export type RunCliOptions = Omit<RunOptions, 'argv' | 'exit' | 'stdout' | 'stderr' | 'onExit'>;
+/**
+ * Run a command against an argv and capture the result.
+ *
+ * The process is never exited and no global is patched: output goes to
+ * collectors and the exit code is observed through `onExit`. An error thrown by
+ * a handler is returned on `error` rather than rethrown, so one assertion style
+ * covers success and failure alike.
+ */
+export declare function runCli(command: CommandDef<any>, argv?: readonly string[], opts?: RunCliOptions): Promise<CliResult>;
+/**
+ * Capture the args the handler that actually runs receives, without running its
+ * body. Every `run` in the tree is replaced, so this works for a subcommand as
+ * well as the root.
+ *
+ * ```ts
+ * const { args } = await captureArgs(main, ['serve', '--port', '9']);
+ * expect(args.port).toBe(9);
+ * ```
+ *
+ * Note this forces any `lazySubCommands` thunk, since the tree has to be walked
+ * to be probed.
+ */
+export declare function captureArgs(command: CommandDef<any>, argv?: readonly string[], opts?: RunCliOptions): Promise<{
+    args: Record<string, unknown>;
+    context?: CommandContext<any>;
+    result: CliResult;
+}>;

package/dist/testing.js

@@ -0,0 +1,113 @@
+/**
+ * Test helpers: run a command definition and get back what it wrote and the
+ * code it settled on, without spawning a process or stubbing globals.
+ *
+ * ```ts
+ * import { runCli } from 'clap-ts/testing';
+ *
+ * const result = await runCli(main, ['serve', '--port', '8080']);
+ * expect(result.exitCode).toBe(0);
+ * expect(result.stdout).toContain('listening');
+ * ```
+ */
+import { runMain } from './runner.js';
+import { subCommandsOf, hasSubCommands } from './parser.js';
+const ANSI = /\x1b\[[0-9;]*m/g;
+/** Strip ANSI colour codes from text. */
+export function stripAnsi(text) {
+    return text.replace(ANSI, '');
+}
+/** A sink that keeps everything written to it. */
+function collector() {
+    const chunks = [];
+    return {
+        write(chunk) {
+            chunks.push(chunk);
+        },
+        text() {
+            return chunks.join('');
+        },
+    };
+}
+/**
+ * Run a command against an argv and capture the result.
+ *
+ * The process is never exited and no global is patched: output goes to
+ * collectors and the exit code is observed through `onExit`. An error thrown by
+ * a handler is returned on `error` rather than rethrown, so one assertion style
+ * covers success and failure alike.
+ */
+export async function runCli(command, argv = [], opts) {
+    const out = collector();
+    const err = collector();
+    let exitCode = 0;
+    let error;
+    try {
+        await runMain(command, {
+            ...opts,
+            argv,
+            exit: false,
+            stdout: out,
+            stderr: err,
+            onExit: (code) => {
+                exitCode = code;
+            },
+        });
+    }
+    catch (caught) {
+        error = caught;
+        if (exitCode === 0) {
+            exitCode = 1;
+        }
+    }
+    const stdout = out.text();
+    const stderr = err.text();
+    return {
+        stdout,
+        stderr,
+        plainStdout: stripAnsi(stdout),
+        plainStderr: stripAnsi(stderr),
+        exitCode,
+        ...(error === undefined ? {} : { error }),
+    };
+}
+/**
+ * Replace every `run` in the tree with the same probe, so whichever command the
+ * argv resolves to is the one observed.
+ */
+function probeTree(command, onRun) {
+    const probed = {};
+    if (hasSubCommands(command)) {
+        for (const [name, sub] of Object.entries(subCommandsOf(command))) {
+            probed[name] = probeTree(sub, onRun);
+        }
+    }
+    return {
+        ...command,
+        run: onRun,
+        ...(hasSubCommands(command) ? { subCommands: probed, lazySubCommands: undefined } : {}),
+    };
+}
+/**
+ * Capture the args the handler that actually runs receives, without running its
+ * body. Every `run` in the tree is replaced, so this works for a subcommand as
+ * well as the root.
+ *
+ * ```ts
+ * const { args } = await captureArgs(main, ['serve', '--port', '9']);
+ * expect(args.port).toBe(9);
+ * ```
+ *
+ * Note this forces any `lazySubCommands` thunk, since the tree has to be walked
+ * to be probed.
+ */
+export async function captureArgs(command, argv = [], opts) {
+    let args = {};
+    let context;
+    const probe = probeTree(command, (ctx) => {
+        args = ctx.args;
+        context = ctx;
+    });
+    const result = await runCli(probe, argv, opts);
+    return { args, ...(context === undefined ? {} : { context }), result };
+}