//#region src/core/refChain.d.ts
/**
 * Generic single-pass `$ref` chain resolver.
 *
 * Several OpenAPI / JSON Schema code paths follow `$ref` indirection with
 * cycle and depth protection — Path Item refs, Parameter / Response refs,
 * Reference Object → Reference Object chains, etc. Each call site previously
 * hand-rolled the loop; this helper centralises the discipline so cycle
 * detection, depth-cap behaviour, and the lookup boundary are consistent.
 *
 * The helper is intentionally lookup-shape agnostic: it walks `string` refs
 * via a user-supplied `lookup`, recording each ref string in a `Set` to
 * detect cycles, and tracking hop count against `maxHops`. The caller chooses
 * what to do on cycle or depth-cap via `onCycle` / `onDepthExceeded`.
 */
/**
 * Configuration for a single chain resolution.
 *
 * `lookup(ref)` returns the dereferenced node for a given `$ref` string, or
 * `undefined` when the ref cannot be resolved. The chain follows further
 * `$ref` indirection on the returned node until either:
 *
 *  - The node is not a ref wrapper (final value reached) → returns the node.
 *  - The same ref string is encountered twice → calls `onCycle(ref)`.
 *  - The hop count exceeds `maxHops` → calls `onDepthExceeded(ref)`.
 *  - `lookup` returns `undefined` → returns `undefined`.
 *
 * Callers decide whether `onCycle` / `onDepthExceeded` should throw, emit
 * a diagnostic, or return a fallback value.
 */
interface ResolveRefChainOptions<T> {
  /** Resolve a `$ref` string to its target node, or `undefined`. */
  readonly lookup: (ref: string) => T | undefined;
  /**
   * Extract a `$ref` string from a node, or `undefined` when the node is
   * not a ref wrapper. The default reads `node.$ref` when `node` is an
   * object with a string `$ref` property.
   */
  readonly extractRef?: (node: T) => string | undefined;
  /**
   * Called when a previously-visited `$ref` is encountered. Returns the
   * value the resolver should return in place of further resolution.
   */
  readonly onCycle?: (ref: string) => T | undefined;
  /**
   * Called when `maxHops` is exceeded. Returns the value the resolver
   * should return in place of further resolution.
   */
  readonly onDepthExceeded?: (ref: string) => T | undefined;
  /**
   * Maximum number of `$ref` hops permitted before `onDepthExceeded` fires.
   * Defaults to `MAX_PATH_ITEM_REF_HOPS` from `core/limits.ts`, the
   * canonical cap shared with the OpenAPI Path Item ref walker.
   */
  readonly maxHops?: number;
  /**
   * Pre-seeded visited-set. Useful when the caller has already followed
   * one or more hops outside this helper.
   */
  readonly visited?: Set<string>;
}
/**
 * Resolve a `$ref` chain starting from `initial`. See `ResolveRefChainOptions`
 * for the contract. Returns the final dereferenced node, the cycle/depth
 * fallback, or `undefined` when a hop cannot be resolved.
 */
declare function resolveRefChain<T>(initial: T, options: ResolveRefChainOptions<T>): T | undefined;
//#endregion
export { ResolveRefChainOptions, resolveRefChain };