ttsc/lib/flags/parser.d.ts

General-purpose TypeScript-Go compiler, runtime, plugin host, and LSP host.

import type { AnySubcommand, ValueValidator } from "./schema";
/**
 * Per-subcommand parse result. `values` is keyed by the canonical flag name
 * (e.g. `"--singleThreaded"`); boolean flags resolve to `true`/`false`, value
 * flags to the parsed value type. Callers narrow with the helpers below
 * (`getBoolean`, `getString`, `getNumber`).
 */
export interface ParseResult {
    /** Canonical flag name → resolved value. */
    readonly values: ReadonlyMap<string, string | boolean | number>;
    /**
     * Canonical flag name → every accepted value, in argv order. Populated only
     * for flags declared `repeatable` in `FLAG_SCHEMA` (`ttsx -r a -r b`), where
     * the last-value-wins `values` entry is not the whole answer. Read it through
     * `getStringList`.
     */
    readonly repeated: ReadonlyMap<string, readonly (string | boolean | number)[]>;
    /** Flags the engine did not consume — forwarded to tsgo. */
    readonly passthrough: readonly string[];
    /** Bare non-flag positional arguments, in original order. */
    readonly positional: readonly string[];
    /**
     * Tokens that arrived after the `forwardAfterFirstPositional` sentinel. These
     * are intended for the user's program (e.g. ttsx's entry-file argv); they are
     * NOT forwarded to tsgo. Always empty when `forwardAfterFirstPositional` is
     * false.
     */
    readonly tail: readonly string[];
}
/** Options controlling a single `parseFlags` invocation. */
export interface ParseOptions {
    /** Which subcommand's flag subset to accept. */
    readonly subcommand: AnySubcommand;
    /** Argv tail (the launcher has already split off the subcommand). */
    readonly argv: readonly string[];
    /**
     * Error prefix used when the parser throws (`"ttsc:"` or `"ttsx:"`). The
     * engine itself is product-neutral; the caller controls the brand.
     */
    readonly errorPrefix: string;
    /**
     * `true` to treat the FIRST positional token as a sentinel that switches the
     * engine to "forward everything after" mode (ttsx's entry-file behaviour:
     * tokens after the entry are runtime argv, not tsgo flags). The sentinel
     * itself is still recorded as a positional argument.
     */
    readonly forwardAfterFirstPositional?: boolean;
    /**
     * Optional `"--"` separator handling: when present in argv, every token after
     * `--` is appended to `passthrough` as-is (ttsx already does this).
     */
    readonly honorDoubleDashSeparator?: boolean;
    /**
     * Classifies a bare (non-dash) token as a genuine positional argument (a
     * source file, the ttsx entry, a project path) rather than the
     * space-separated value of a preceding forwarded flag.
     *
     * When omitted, every bare token is a positional — the historical behaviour
     * for project-shaped subcommands that never forward `--flag value` pairs.
     *
     * When provided, a bare token that fails the predicate is appended to
     * `passthrough` in its original position instead of `positional`, so an
     * unknown `--flag value` pair reaches tsgo with its adjacency and relative
     * order intact. The parser deliberately does not guess a forwarded flag's
     * arity from the flag itself (it has no schema for a truly unknown flag); the
     * predicate is the only signal that separates a forwarded value from a real
     * input file, and both callers key it on the TypeScript source extension.
     *
     * Every path that can move a bare token out of `positional` consults it: the
     * main loop below and `forwardKnownButUnaccepted`, which answers the same
     * question for a schema-known flag this subcommand does not accept.
     */
    readonly isPositional?: (token: string) => boolean;
}
/**
 * Parse `argv` according to FLAG_SCHEMA filtered by `subcommand`. Returns a
 * `ParseResult`. Throws `Error` (with the configured prefix) on invalid input —
 * unknown subcommand-only flag, missing required value, value that fails its
 * validator.
 */
export declare function parseFlags(opts: ParseOptions): ParseResult;
/** Return the boolean value of `flag` or `undefined` if not present. */
export declare function getBoolean(result: ParseResult, flag: string): boolean | undefined;
/** Return the string value of `flag` or `undefined` if not present. */
export declare function getString(result: ParseResult, flag: string): string | undefined;
/**
 * Return every string value accepted for a `repeatable` flag, in argv order.
 *
 * `values` keeps only the last occurrence, which is the wrong answer for a flag
 * whose whole point is repetition (`ttsx -r a -r b` preloads both). Returns an
 * empty array when the flag never appeared.
 */
export declare function getStringList(result: ParseResult, flag: string): string[];
/** Return the numeric value of `flag` or `undefined` if not present. */
export declare function getNumber(result: ParseResult, flag: string): number | undefined;
/** Marker type so docs callers can name the validator without an import dance. */
export type { ValueValidator };