@struktoai/mirage-core/dist/commands/spec/compile.d.ts

A Unified Virtual Filesystem For AI Agents

import { type Argument, type CommandSpec, type ValueType } from './types.ts';
/** First short and long spelling, for dialects that display each separately. */
export declare function optionSpellings(argument: Argument): [string | null, string | null];
/** Canonical option spelling, or the positional argument's name. */
export declare function argumentDest(argument: Argument): string;
/** Declared positional placeholder, including an explicit empty placeholder. */
export declare function positionalName(argument: Argument): string;
export declare function positionalRequired(argument: Argument): boolean;
/**
 * A CommandSpec lowered into the lookup tables the parser walks.
 *
 * Built once per spec (cached) instead of rebuilt on every parseCommand
 * call. Spellings are the dashed forms as typed (`-e`, `--regexp`);
 * `dest` maps every spelling to its canonical spelling, the long form
 * when an option declares both, so the parsed flag bag holds ONE entry
 * per option regardless of which spelling appeared on the line
 * (click/argparse dest semantics). Mirrors Python's CompiledSpec.
 */
export interface CompiledSpec {
    readonly nargsByDest: ReadonlyMap<string, number>;
    readonly valueTypesByDest: ReadonlyMap<string, readonly ValueType[]>;
    readonly detachedOptionalSpellings: ReadonlySet<string>;
    readonly options: readonly Argument[];
    readonly positional: readonly Argument[];
    readonly rest: Argument | null;
    /** Short spellings parsed as bare booleans (true booleans plus
     * optional-value shorts). */
    readonly boolSpellings: ReadonlySet<string>;
    /** Short spellings expecting a value, longest first so `-name` can
     * never lose an attached match to `-n`. */
    readonly valueSpellings: readonly string[];
    /** Short spellings whose value may attach to the same token
     * (`split -d10`), longest first. */
    readonly attachSpellings: readonly string[];
    /** Long spellings parsed as bare booleans (true booleans plus
     * optional-value longs). */
    readonly longBoolSpellings: ReadonlySet<string>;
    /** Long spellings that require a value. */
    readonly longValueSpellings: ReadonlySet<string>;
    /** Long spellings whose value only attaches via `=` (GNU optional
     * argument). */
    readonly longOptionalSpellings: ReadonlySet<string>;
    /** Every long spelling in declaration order (the order GNU's ambiguity
     * refusal lists possibilities), for getopt_long prefix expansion. */
    readonly longSpellings: readonly string[];
    /** Canonical spellings of int-typed options; the parser refuses a
     * non-integer value at parse time (argparse `type=int`). */
    readonly intDests: ReadonlySet<string>;
    /** Canonical spellings of float-typed options, refused the same way
     * (argparse `type=float`). */
    readonly floatDests: ReadonlySet<string>;
    /** Value kind per spelling (parse-time lookup). */
    readonly kindOf: ReadonlyMap<string, ValueType>;
    /** Value kind per canonical spelling, for post-parse PATH/TEXT value
     * collection. */
    readonly kindByDest: ReadonlyMap<string, ValueType>;
    /** Spelling -> canonical spelling. */
    readonly dest: ReadonlyMap<string, string>;
    /** Canonical spellings that accumulate repeated values into a list. */
    readonly multipleDests: ReadonlySet<string>;
    /** Canonical spellings of boolean flags whose occurrences accumulate
     * into a number (click count, `-vvv`). */
    readonly countDests: ReadonlySet<string>;
    /** Allowed values per canonical spelling, in declaration order (the
     * order GNU's word-choice refusal lists them). */
    readonly choicesByDest: ReadonlyMap<string, readonly string[]>;
    /** Canonical spellings that must appear, in declaration order; a
     * default satisfies the requirement. */
    readonly requiredDests: readonly string[];
    /** Value recorded per canonical spelling when the flag is absent from
     * the line. */
    readonly defaults: ReadonlyMap<string, string>;
    readonly envByDest: ReadonlyMap<string, string>;
    /** Canonical spelling fed by the `-<digits>` shorthand, when one
     * option declares it. */
    readonly numericDest: string | null;
    /** Kind of the rest operand. */
    readonly restKind: ValueType | null;
    readonly remainder: boolean;
    readonly baseDest: string | null;
    /** Canonical spelling for a typed spelling. */
    destOf(spelling: string): string;
}
/** Lower a CommandSpec into parser lookup tables, cached per spec. */
export declare function compileSpec(spec: CommandSpec): CompiledSpec;
/**
 * getopt_long prefix matching for a long spelling.
 *
 * An exact declared spelling always wins (GNU: `--binary` never trips
 * over `--binary-files`); otherwise the candidates are every declared
 * long the typed spelling prefixes. Two declared options are two options,
 * so a prefix of both is ambiguous (`ls --re` is `--reverse` or
 * `--recursive`), unless `synonyms` (from LONG_SYNONYMS) names them one
 * option under two names, the way glibc treats several table entries
 * sharing one `val` (`grep --colo` resolves despite `--color`/`--colour`
 * being separate entries); then the prefix resolves to the first. The
 * result length tells the caller everything: 0 unknown, 1 match, 2+
 * ambiguous (every matching spelling in declaration order, the order GNU
 * lists possibilities, synonyms included like GNU's own listing).
 */
/**
 * git's parse-options resolution of one long option against the program's own
 * table, which lists each option in git's `--[no-]` notation.
 *
 * An exact name wins at once, a negatable option answering to its `--no-`
 * form too. Otherwise the word may abbreviate one option, `--no-` abbreviating
 * a negation, and a word that abbreviates two is ambiguous: git names the last
 * two it found, each with the `no-` it was matched under. A word matching
 * nothing is null, and the caller decides what that is. The result is the
 * spelling the table resolves to, which the spec may or may not declare.
 *
 * @param table the program's long options, e.g. `['[no-]verbose', 'contains']`
 * @param typed the word as typed, `--` included and any `=value` removed
 */
export declare function expandGitLong(table: readonly string[], typed: string): {
    spelling: string;
} | {
    ambiguous: [string, string];
} | null;
/**
 * getopt_long prefix matching against a program's whole table.
 *
 * An entry spelled exactly names its option; otherwise every entry the typed
 * spelling prefixes is a candidate. glibc sets aside a later candidate that
 * names the same option as the first one, so one option's aliases resolve
 * where two options are ambiguous. The result length tells the caller
 * everything: 0 unknown, 1 the option's primary spelling, 2+ the
 * possibilities glibc lists (the first candidate and every later one naming
 * another option, in table order). `table` is each option's primary spelling
 * then its aliases, in the program's table order (LONG_OPTION_TABLES).
 * Mirrors Python's expand_table_long.
 */
export declare function expandTableLong(table: readonly (readonly string[])[], spelling: string): readonly string[];
export declare function expandLong(cs: CompiledSpec, spelling: string, synonyms?: ReadonlyMap<string, string>): readonly string[];
//# sourceMappingURL=compile.d.ts.map