import { ValueParserResult } from "./valueparser.cjs";

//#region src/input-trace.d.ts

/**
 * A replayable record of raw input consumed by a single parser node.
 *
 * @internal
 * @since 1.0.0
 */
interface TraceEntry {
  /** The kind of input that was consumed. */
  readonly kind: "option-value" | "argument-value" | "literal" | "custom";
  /** The raw input string to be replayed. */
  readonly rawInput: string;
  /** The tokens consumed from the buffer. */
  readonly consumed: readonly string[];
  /** The preliminary parse result using default dependency values. */
  readonly preliminaryResult?: ValueParserResult<unknown>;
  /**
   * Snapshotted default dependency values captured during parse.
   *
   * Present when a derived parser snapshots default dependency values during
   * parse, including both `derive()` and `deriveFrom()` parsers.
   * This avoids re-evaluating dynamic default thunks during replay.
   */
  readonly defaultDependencyValues?: readonly unknown[];
  /** The option names that matched (e.g., `["--env", "-e"]`). */
  readonly optionNames?: readonly string[];
  /** The metavar of the value parser. */
  readonly metavar?: string;
}
/**
 * An immutable, path-keyed store of {@link TraceEntry} records.
 *
 * Each entry is keyed by a path of `PropertyKey` segments (strings, numbers,
 * or symbols) corresponding to the position of the parser in the parse tree.
 *
 * All mutation methods return a new `InputTrace` instance; the original is
 * never modified.
 *
 * @internal
 * @since 1.0.0
 */
interface InputTrace {
  /**
   * Retrieves the trace entry at the given path.
   *
   * @param path The path segments identifying the entry.
   * @returns The entry, or `undefined` if no entry exists at that path.
   */
  get(path: readonly PropertyKey[]): TraceEntry | undefined;
  /**
   * Returns a new trace with the entry set at the given path.
   *
   * @param path The path segments identifying the entry.
   * @param entry The trace entry to store.
   * @returns A new `InputTrace` with the entry stored.
   */
  set(path: readonly PropertyKey[], entry: TraceEntry): InputTrace;
  /**
   * Returns a new trace with the entry at the given path removed.
   *
   * @param path The path segments identifying the entry to remove.
   * @returns A new `InputTrace` without the entry.
   */
  delete(path: readonly PropertyKey[]): InputTrace;
}
/**
 * Creates a new empty {@link InputTrace}.
 *
 * @returns An empty immutable input trace.
 * @internal
 * @since 1.0.0
 */
declare function createInputTrace(): InputTrace;
//#endregion
export { InputTrace, TraceEntry, createInputTrace };