burgee/testing

import { processRuntime, captureConsole, codeOf, … } from 'burgee/testing';

function captureConsole(rt: FakeRuntime): () => void;

function codeOf(e: unknown): ExitCode;

function fakeClock(start?: number): FakeClock;

function fakeRuntime(opts: RunOptions): FakeRuntime;

function finish(rt: FakeRuntime, code: ExitCode, startedAt: number): RunResult;

function isExitCode(n: unknown): n is ExitCode;

function runBurgee(program: Manifest, opts: RunOptions): Promise<RunResult>;

function stripAnsi(text: string): string;

function swapEnv(env: Record<string, string> | undefined): () => void;

class RuntimeExit extends Error {
    readonly code: ExitCode;
    constructor(code: ExitCode);
}

const ExitCode: {
    /** Command completed. */
    readonly OK: 0;
    /** The command ran and failed. Never accompanied by help text (E2). */
    readonly RUNTIME: 1;
    /** Bad arguments, unknown command, missing flag, prompt needed in a non-TTY (P2). */
    readonly USAGE: 2;
    /** Config file or environment could not be loaded or validated (V1). */
    readonly CONFIG: 3;
    /** The user or caller cancelled. */
    readonly CANCELLED: 4;
    /**
     * E6 — the far side said no: a credential is missing, expired, or refused.
     *
     * Its own code because it is the most actionable one in the survey. `RUNTIME` means *it
     * failed, read the message*; `AUTH` means *log in and run it again*, and a script or an
     * agent can branch on that without parsing prose. `USAGE` says fix the script, `CONFIG`
     * says fix the runner, and this says fix the credential — three different responses that
     * collapsed into one code before it existed.
     *
     * **5, where `gh` uses 4.** Four is `CANCELLED` here and has been since the contract was
     * written, and moving a published code to match another tool's is a breaking change for
     * every consumer that already branches on it. The survey's other citation, `aws` v2, uses
     * 252/253/254 and agrees with nobody either; what matters is that the code is stable and
     * documented, not that it matches a particular neighbour.
     */
    readonly AUTH: 5;
    /** SIGINT after the terminal was restored (E5). */
    readonly SIGINT: 130;
};

type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];

const ExitCode: {
    /** Command completed. */
    readonly OK: 0;
    /** The command ran and failed. Never accompanied by help text (E2). */
    readonly RUNTIME: 1;
    /** Bad arguments, unknown command, missing flag, prompt needed in a non-TTY (P2). */
    readonly USAGE: 2;
    /** Config file or environment could not be loaded or validated (V1). */
    readonly CONFIG: 3;
    /** The user or caller cancelled. */
    readonly CANCELLED: 4;
    /**
     * E6 — the far side said no: a credential is missing, expired, or refused.
     *
     * Its own code because it is the most actionable one in the survey. `RUNTIME` means *it
     * failed, read the message*; `AUTH` means *log in and run it again*, and a script or an
     * agent can branch on that without parsing prose. `USAGE` says fix the script, `CONFIG`
     * says fix the runner, and this says fix the credential — three different responses that
     * collapsed into one code before it existed.
     *
     * **5, where `gh` uses 4.** Four is `CANCELLED` here and has been since the contract was
     * written, and moving a published code to match another tool's is a breaking change for
     * every consumer that already branches on it. The survey's other citation, `aws` v2, uses
     * 252/253/254 and agrees with nobody either; what matters is that the code is stable and
     * documented, not that it matches a particular neighbour.
     */
    readonly AUTH: 5;
    /** SIGINT after the terminal was restored (E5). */
    readonly SIGINT: 130;
};

type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];

const processRuntime: Runtime;

interface Clock {
    now(): number;
    schedule(fn: () => void, ms: number): () => void;
}

interface FakeClock extends Clock {
    /**
     * Advance by `ms`, running every callback that falls due, earliest first, then by order
     * scheduled. A callback that schedules inside the window runs in the same tick, so one that
     * reschedules itself at `0` would never leave the loop (real Node yields between turns);
     * a tick runs at most `TICK_CAP` callbacks and throws, naming the cap, when exceeded.
     */
    tick(ms: number): void;
    /** Callbacks scheduled and neither run nor cancelled. */
    pending(): number;
}

interface FakeRuntime extends Runtime {
    out: string[];
    err: string[];
    clock: FakeClock;
}

interface RunOptions {
    argv: string[];
    env?: Record<string, string>;
    stdin?: string | Readable;
    cwd?: string;
    /** `true` = every stream is a TTY; an object sets each; default: none is. */
    tty?: boolean | Partial<Runtime['isTTY']>;
    /** The clock the runtime reports; a fresh `fakeClock()` at 0 when not given. */
    clock?: FakeClock;
}

interface RunResult {
    code: ExitCode;
    stdout: string;
    stderr: string;
    /** Parsed stdout when `--json` was in argv and stdout parsed; see `finish`. */
    json?: unknown;
    durationMs: number;
}

interface Runtime {
    argv: string[];
    env: Record<string, string | undefined>;
    cwd: string;
    stdin: NodeJS.ReadableStream;
    stdout: Writer;
    stderr: Writer;
    isTTY: {
        stdin: boolean;
        stdout: boolean;
        stderr: boolean;
    };
    /** Ends the run with an E1 code. In the real runtime this never returns. */
    exit(code: ExitCode): never;
    /** `performance.now` and `setTimeout` in the real runtime; a manual tick in the harness. */
    clock: Clock;
}

interface Writer {
    write(chunk: string): unknown;
}