/**
 * Supported schema value kinds for a flag.
 *
 * Use these literals in {@link FlagSpec.type} to declare how a logical option
 * should be parsed from argv tokens.
 */
export type FlagType = 'string' | 'boolean' | 'number' | 'array';
/**
 * Runtime value type mapped from a {@link FlagType}.
 *
 * This conditional type drives the inferred `values` shape returned by
 * {@link parseArgs}.
 */
export type FlagValue<T extends FlagType> = T extends 'string' ? string : T extends 'boolean' ? boolean : T extends 'number' ? number : T extends 'array' ? string[] : never;
/**
 * Single schema specification for one logical flag key.
 *
 * Constraints:
 * - `flags` must contain at least one token.
 * - Every token must start with `-`.
 * - `allowNo` is only valid for boolean flags.
 * - `allowEmpty` is only valid for string and array flags.
 * - Array defaults are cloned on each parse call.
 *
 * Defaults:
 * - `required`: `false`
 * - `allowEmpty`: `false`
 * - `allowNo`: `true` for boolean flags
 */
export interface FlagSpec<T extends FlagType = FlagType> {
    /** Parsed value kind for this option. */
    type: T;
    /** Accepted CLI spellings (for example `-m`, `--mode`). */
    flags: readonly string[];
    /** Marks the option as required when `true`. */
    required?: boolean;
    /** Fallback value used when the flag is not provided. */
    default?: FlagValue<T>;
    /** Allows empty string/array values for string and array specs. */
    allowEmpty?: boolean;
    /** Enables `--no-<flag>` negation for boolean specs. */
    allowNo?: boolean;
}
/** Structured metadata for boolean negation aliases discovered during schema normalization. */
export interface BooleanNegationMetadata {
    /** Logical schema key associated with the negation alias. */
    key: string;
    /** Positive flag name used in schema. */
    positiveFlag: string;
    /** Derived negation flag that the parser accepts. */
    negativeFlag: string;
}
/**
 * Parser schema keyed by logical option names.
 *
 * Schema keys become the stable property names in {@link ParseResult.values},
 * {@link ParseResult.present}, and {@link ParseIssue.key}.
 */
export type Schema = Record<string, FlagSpec>;
/**
 * Parser issue severity.
 */
export type IssueSeverity = 'error' | 'warning';
/**
 * Stable parser issue codes.
 *
 * Treat these codes as the machine contract. Human-readable `message` strings
 * are for logs and operator output, not programmatic branching.
 */
export type IssueCode = 'UNKNOWN_FLAG' | 'MISSING_VALUE' | 'INVALID_VALUE' | 'REQUIRED' | 'DUPLICATE' | 'EMPTY_VALUE';
/**
 * Structured parser issue payload.
 *
 * Returned in {@link ParseResult.issues} for unknown flags, missing values,
 * invalid coercions, required-field failures, and duplicate-flag warnings.
 */
export interface ParseIssue {
    /** Stable machine-readable issue code. */
    code: IssueCode;
    /** Issue severity used by `ok` computation. */
    severity: IssueSeverity;
    /** Human-readable diagnostic message. */
    message: string;
    /** Flag token associated with this issue, when available. */
    flag?: string;
    /** Schema key associated with this issue, when available. */
    key?: string;
    /** Raw value that triggered the issue, when available. */
    value?: string;
    /** Zero-based argv index for the related token, when available. */
    index?: number;
}
/** Non-throwing schema normalization result. */
export interface SchemaNormalizationResult {
    /** Parsed flag map keyed by token (`--flag`, `-f`) to schema key. */
    flagToKey: Record<string, string>;
    /** Normalized schema specs keyed by schema key. */
    normalized: Record<string, NormalizedSpec>;
    /** Effective negation aliases for boolean long flags. */
    booleanNegations: readonly BooleanNegationMetadata[];
    /** Human-readable schema issues. */
    issues: readonly string[];
    /** Whether schema normalization succeeded. */
    ok: boolean;
}
/**
 * Parse behavior toggles.
 *
 * Defaults:
 * - `argv`: runtime argv when available, otherwise `[]`
 * - `allowUnknown`: `false`
 * - `stopAtDoubleDash`: `true`
 */
export interface ParseOptions {
    /** Explicit argv input; defaults to runtime arguments when omitted. */
    argv?: readonly string[];
    /** Keeps unknown flags in `unknown` instead of emitting errors. */
    allowUnknown?: boolean;
    /** Treats `--` as a stop token for flag parsing (default: `true`). */
    stopAtDoubleDash?: boolean;
}
/**
 * Typed parsed values for a schema.
 *
 * Values stay `undefined` until a schema default or argv token supplies them.
 */
export type ParsedValues<S extends Schema> = {
    [K in keyof S]: FlagValue<S[K]['type']> | undefined;
};
/**
 * Presence map for explicitly supplied flags.
 *
 * A key is `true` only when argv explicitly contained the flag. Defaults do not
 * flip presence on.
 */
export type ParsedPresent<S extends Schema> = {
    [K in keyof S]: boolean;
};
/**
 * Full parse result payload.
 *
 * Semantics:
 * - `values` contains typed parsed output plus any schema defaults.
 * - `present` tracks whether a caller explicitly supplied a flag.
 * - `rest` preserves free positional tokens and tokens after `--`.
 * - `unknown` captures unknown flag tokens only when `allowUnknown` is enabled.
 * - `ok` is `false` only when at least one issue has severity `"error"`.
 */
export interface ParseResult<S extends Schema> {
    /** Parsed values keyed by schema key. */
    values: ParsedValues<S>;
    /** Presence map indicating which schema keys were explicitly provided. */
    present: ParsedPresent<S>;
    /** Non-flag argv tokens preserved in encounter order. */
    rest: string[];
    /** Unknown flag tokens collected when `allowUnknown` is enabled. */
    unknown: string[];
    /** Structured parse diagnostics. */
    issues: ParseIssue[];
    /** `true` when no issue with severity `error` exists. */
    ok: boolean;
}
/**
 * JSON-serializable value variant for parse results.
 *
 * This is the value domain produced by {@link toJsonResult}.
 */
export type JsonFlagValue = string | number | boolean | string[] | null;
/**
 * JSON-safe parse result payload.
 *
 * This shape is designed for validation against
 * `schema/parse-result.schema.json`, where missing typed values are encoded as
 * `null` instead of `undefined`.
 */
export interface ParseResultJson {
    /** JSON-safe parsed values keyed by schema key (`undefined` becomes `null`). */
    values: Record<string, JsonFlagValue>;
    /** JSON-safe presence map keyed by schema key. */
    present: Record<string, boolean>;
    /** JSON-safe copy of free argv values. */
    rest: string[];
    /** JSON-safe copy of unknown flag tokens. */
    unknown: string[];
    /** JSON-safe copy of parse diagnostics. */
    issues: ParseIssue[];
    /** `true` when no issue with severity `error` exists. */
    ok: boolean;
}
/**
 * Internalized flag specification used only by parser internals and schema normalization output.
 */
export interface NormalizedSpec extends FlagSpec {
    /** Normalized flag tokens with validated flag syntax. */
    flags: string[];
    /** Primary long flag token, if one was declared. */
    longFlag?: string;
    /** Effective negation alias derived from `--<flag>` for boolean options. */
    effectiveNegation?: string;
}
/** Validates and normalizes schema without throwing. */
export declare const normalizeSchema: (schema: unknown) => SchemaNormalizationResult;
/**
 * Identity helper that preserves schema typing for object literals.
 *
 * `defineSchema()` does not validate the schema eagerly. Structural validation
 * happens when {@link parseArgs} normalizes the schema before parsing.
 *
 * @example
 * ```ts
 * import { defineSchema } from "./index.ts";
 *
 * const schema = defineSchema({
 *   src: { type: "string", flags: ["--src"], required: true },
 *   verbose: { type: "boolean", flags: ["--verbose"], default: false },
 * });
 *
 * console.log(schema.src.flags[0]);
 * ```
 */
export declare const defineSchema: <T extends Schema>(schema: T) => T;
/**
 * Parses argv tokens against a declared schema and returns deterministic typed
 * output plus structured diagnostics.
 *
 * Defaults:
 * - `options.argv`: runtime argv (`process.argv.slice(2)` on Node/Bun,
 *   `Deno.args` on Deno, otherwise `[]`)
 * - `options.allowUnknown`: `false`
 * - `options.stopAtDoubleDash`: `true`
 *
 * Result semantics:
 * - `values` contains typed values plus defaults.
 * - `present` only marks explicitly supplied flags.
 * - `rest` contains free positional tokens and tokens after `--`.
 * - `unknown` only contains unknown flag tokens when `allowUnknown` is `true`.
 * - `issues` contains warnings and errors with stable issue codes.
 * - `ok` is `true` only when no `"error"` issue exists.
 *
 * @throws {TypeError} If the schema is structurally invalid.
 *
 * @example
 * ```ts
 * import { defineSchema, parseArgs } from "./index.ts";
 *
 * const schema = defineSchema({
 *   src: { type: "string", flags: ["--src"], required: true },
 *   retries: { type: "number", flags: ["--retries"] },
 *   verbose: { type: "boolean", flags: ["--verbose"], default: false },
 * });
 *
 * const result = parseArgs(schema, {
 *   argv: ["--src", "input.txt", "--retries", "3", "--verbose"],
 * });
 *
 * console.log(result.ok);
 * console.log(result.values.src);
 * console.log(result.values.retries);
 * console.log(result.present.verbose);
 * ```
 *
 * @example
 * ```ts
 * import { defineSchema, parseArgs } from "./index.ts";
 *
 * const schema = defineSchema({
 *   mode: { type: "string", flags: ["--mode"], required: true },
 * });
 *
 * const result = parseArgs(schema, {
 *   argv: ["--mode", "safe", "--", "--trace", "--limit=2"],
 * });
 *
 * console.log(result.rest);
 * ```
 */
export declare const parseArgs: <T extends Schema>(schema: T, options?: ParseOptions) => ParseResult<T>;
/**
 * Default export alias for {@link parseArgs}.
 */
export default parseArgs;
/**
 * Converts a typed parse result into a JSON-safe payload.
 *
 * Conversion rules:
 * - `undefined` values become `null`
 * - arrays are copied
 * - `present`, `rest`, `unknown`, and `issues` are copied into plain JSON-safe
 *   containers
 *
 * Use this before validating results against
 * `schema/parse-result.schema.json` or emitting machine-readable JSON from a
 * CLI wrapper.
 *
 * @example
 * ```ts
 * import { defineSchema, parseArgs, toJsonResult } from "./index.ts";
 *
 * const schema = defineSchema({
 *   count: { type: "number", flags: ["--count"] },
 * });
 *
 * const result = parseArgs(schema, { argv: [] });
 * const json = toJsonResult(result);
 *
 * console.log(json.values.count);
 * ```
 */
export declare const toJsonResult: <T extends Schema>(result: ParseResult<T>) => ParseResultJson;
//# sourceMappingURL=index.d.ts.map