import { FlagSchema } from "../schema/flag.mjs";
import { CommandSchema } from "../schema/command.mjs";
import "../schema/index.mjs";
//#region src/core/parse/index.d.ts
/**
 * Token discriminated union.
 *
 * The tokenizer produces these from raw argv strings. The parser then
 * interprets them against a command schema.
 */
type Token = {
  readonly kind: 'long-flag';
  readonly name: string;
  readonly value: string | undefined;
} | {
  readonly kind: 'short-flags';
  readonly chars: string;
} | {
  readonly kind: 'positional';
  readonly value: string;
} | {
  readonly kind: 'separator';
};
/**
 * Tokenize raw argv into structured tokens.
 *
 * Low-level utility: most apps should use {@link parse}, `cli().run()`, or
 * `runCommand()` instead of tokenizing manually. Reach for `tokenize()` when
 * building custom tooling such as debuggers, inspectors, or parser tests.
 *
 * Rules:
 * - `--`        → separator (everything after is positional)
 * - `--flag`    → long flag, no inline value
 * - `--flag=v`  → long flag with inline value
 * - `-abc`      → short flags (expanded individually by parser)
 * - `-`         → positional (convention: stdin placeholder)
 * - everything else → positional
 *
 * @param argv - Raw argument strings to tokenize
 * @returns Ordered token array ready for {@link parse}
 *
 * @example
 * ```ts
 * tokenize(['deploy', '--force', '--region=eu', '-v']);
 * ```
 */
declare function tokenize(argv: readonly string[]): readonly Token[];
/**
 * Whether `token` appears in argv before the `--` end-of-options separator.
 *
 * Everything at or after the first `--` is a literal positional, so root-level
 * flag interception (`--help` / `--version` / `--json`) must use this instead of
 * a naive `Array.includes()` — otherwise a post-separator literal (`-- --json`)
 * is wrongly treated as the flag.
 *
 * @param argv - Raw argument strings.
 * @param token - Exact flag token to look for (e.g. `--version`).
 * @returns `true` if `token` occurs before any `--` separator.
 */
declare function includesBeforeSeparator(argv: readonly string[], token: string): boolean;
/**
 * Remove every occurrence of `token` that appears before the `--` end-of-options
 * separator, leaving post-separator literals untouched.
 *
 * The strip counterpart to {@linkcode includesBeforeSeparator}: root-level flags
 * (`--json`) are stripped before dispatch/parse so the command schema never sees
 * them, but a literal after `--` (`-- --json`) must reach the command unchanged.
 *
 * @param argv - Raw argument strings.
 * @param token - Exact flag token to strip (e.g. `--json`).
 * @returns A new argv with pre-separator occurrences of `token` removed, or the
 *   original reference when `token` does not occur before the separator.
 */
declare function stripBeforeSeparator(argv: readonly string[], token: string): readonly string[];
/**
 * Raw parsed values before resolution (defaults, env, config, etc.).
 *
 * Flag values are `unknown` because type coercion happens here but the
 * generic type info lives in the schema builders, not at runtime.
 */
interface ParseResult {
  /** Flag values keyed by canonical flag name. */
  readonly flags: Readonly<Record<string, unknown>>;
  /** Positional arg values keyed by arg name. */
  readonly args: Readonly<Record<string, unknown>>;
}
/** Options accepted by {@link parse} and {@link buildFlagLookup}. */
interface ParseOptions {
  /**
   * Accept the kebab↔camel counterpart spelling of each flag name/alias
   * (`--doThis` for a flag named `do-this`, and vice versa). Automatically
   * disabled per spelling pair when a command explicitly defines both.
   *
   * @defaultValue `true`
   */
  readonly caseParity?: boolean;
}
/** `do-this` → `doThis`. Returns the input unchanged when nothing converts. */
declare function kebabToCamel(name: string): string;
/** `doThis` → `do-this`. Returns the input unchanged when nothing converts. */
declare function camelToKebab(name: string): string;
/** One resolvable spelling in the flag lookup map. */
interface FlagLookupEntry {
  /** Canonical flag name (the key in the command's flag record). */
  readonly name: string;
  /** The flag's schema. */
  readonly schema: FlagSchema;
  /** This spelling is the flag's negated form (`--no-foo`) — parses to `false`. */
  readonly negated: boolean;
  /** This spelling is a case-parity counterpart, not a declared spelling. */
  readonly parity: boolean;
}
/**
 * Build a map from flag spelling → {@link FlagLookupEntry}.
 *
 * Covers canonical names, aliases (long + single-char), negated spellings of
 * `.negatable()` booleans, and — unless `caseParity` is `false` — the
 * kebab↔camel counterpart of every declared spelling. Counterparts never
 * override declared spellings: when a command defines both `do-this` and
 * `doThis` explicitly, each spelling exact-matches its own flag and no
 * parity entries are added for the pair.
 *
 * @param flags - Flag schemas keyed by canonical name
 * @param options - Parity toggle (see {@link ParseOptions})
 * @returns Lookup map covering all resolvable spellings
 */
declare function buildFlagLookup(flags: Readonly<Record<string, FlagSchema>>, options?: ParseOptions): ReadonlyMap<string, FlagLookupEntry>;
/**
 * Whether a flag kind expects a value argument (vs. being a bare boolean).
 *
 * @param schema - Flag schema to check
 * @returns `true` if the flag expects a value token after it
 */
declare function flagExpectsValue(schema: FlagSchema): boolean;
/**
 * Parse tokenized argv against a command schema.
 *
 * Low-level API: most apps should let `cli()` or `runCommand()` handle parsing
 * automatically. Call `parse()` directly when you need raw parsed values before
 * env/config/default resolution or when writing custom tooling around schemas.
 *
 * @param schema - The command schema to parse against
 * @param argv   - Raw argv strings (NOT including the command name itself)
 * @param options - Parser behavior toggles (see {@link ParseOptions})
 * @returns Parsed flag and arg values
 * @throws ParseError for unknown flags, missing values, type mismatches
 *
 * @example
 * ```ts
 * const parsed = parse(deploy.schema, ['production', '--force']);
 * // => { args: { target: 'production' }, flags: { force: true } }
 * ```
 */
declare function parse(schema: CommandSchema, argv: readonly string[], options?: ParseOptions): ParseResult;
//#endregion
export { type FlagLookupEntry, type ParseOptions, type ParseResult, type Token, buildFlagLookup, camelToKebab, flagExpectsValue, includesBeforeSeparator, kebabToCamel, parse, stripBeforeSeparator, tokenize };