/**
 * @file Resolve GitHub git refs (tag / branch / commit) to full commit SHAs.
 *   Two-tier strategy with cross-backend fallback:
 *
 *   1. REST cascade (`fetchRefSha`): tag → branch → commit. The first 200 OK wins.
 *   2. GraphQL fallback (`fetchRefShaViaGraphQL`): fires only when the REST
 *      cascade hits the documented 200-OK-empty-body incident shape. GraphQL
 *      queries hit a different backend at GitHub, so it stays consistent
 *      through Elasticsearch outages that produce empty REST bodies. Caching: a
 *      `TtlCache` keyed by `${owner}/${repo}@${ref}` with a 5-minute TTL plus
 *      in-memory memoization. `clearRefCache()` clears the in-memory tier; the
 *      persistent disk tier survives so the cache warms quickly on the next
 *      run. Disable everything with the `DISABLE_GITHUB_CACHE` env var. Module
 *      shape: this file holds the public `resolveRefToSha` entry point.
 *      Supporting surface lives in sibling leaves and is re-exported here so
 *      existing `github/refs` importers keep working unchanged:
 *
 *   - REST tier cascade — `./refs-rest`
 *   - GraphQL fallback — `./refs-graphql`
 *   - TtlCache singleton + clearRefCache — `./refs-cache`
 */
import type { ResolveRefOptions } from './types';
/**
 * Resolve a git ref (tag, branch, or commit SHA) to its full commit SHA.
 * Handles tags (annotated and lightweight), branches, and commit SHAs. Results
 * are cached in-memory and on disk (with TTL) to minimize API calls.
 *
 * Resolution strategy:
 *
 * 1. Try as a tag (refs/tags/{ref})
 * 2. If tag is annotated, dereference to get the commit SHA
 * 3. If not a tag, try as a branch (refs/heads/{ref})
 * 4. If not a branch, try as a commit SHA directly
 *
 * Caching behavior:
 *
 * - In-memory cache (Map) for immediate lookups
 * - Persistent disk cache (cacache) for durability across runs
 * - Default TTL: 5 minutes
 * - Disable caching with `DISABLE_GITHUB_CACHE` env var
 *
 * @example
 *   ;```ts
 *   // Resolve a tag to commit SHA
 *   const sha = await resolveRefToSha('owner', 'repo', 'v1.0.0')
 *   console.log(sha) // 'a1b2c3d4e5f6...'
 *   ```
 *
 * @example
 *   ;```ts
 *   // Resolve a branch to latest commit SHA
 *   const sha = await resolveRefToSha('owner', 'repo', 'main')
 *   console.log(sha) // Latest commit on main branch
 *   ```
 *
 * @example
 *   ;```ts
 *   // Resolve with custom token
 *   const sha = await resolveRefToSha('owner', 'repo', 'develop', {
 *     token: 'ghp_customtoken',
 *   })
 *   ```
 *
 * @example
 *   ;```ts
 *   // Commit SHA passes through unchanged (but validates it exists)
 *   const sha = await resolveRefToSha('owner', 'repo', 'a1b2c3d4')
 *   console.log(sha) // Full 40-char SHA
 *   ```
 *
 * @param owner - Repository owner (user or organization name)
 * @param repo - Repository name.
 * @param ref - Git reference to resolve (tag name, branch name, or commit SHA)
 * @param options - Resolution options including authentication token.
 *
 * @returns The full commit SHA (40-character hex string)
 *
 * @throws {Error} When ref cannot be resolved after trying all strategies
 * @throws {GitHubRateLimitError} When API rate limit is exceeded
 */
export declare function resolveRefToSha(owner: string, repo: string, ref: string, options?: ResolveRefOptions | undefined): Promise<string>;
export { clearRefCache, getGithubCache } from './refs-cache';
export { fetchRefShaViaGraphQL } from './refs-graphql';
export { fetchRefSha } from './refs-rest';
