@socketsecurity/lib 5.28.0 → 6.0.0

package/dist/github/ghsa.js

@@ -0,0 +1,178 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var ghsa_exports = {};
+__export(ghsa_exports, {
+  cacheFetchGhsa: () => cacheFetchGhsa,
+  fetchGhsaDetails: () => fetchGhsaDetails,
+  fetchGhsaDetailsViaGraphQL: () => fetchGhsaDetailsViaGraphQL
+});
+module.exports = __toCommonJS(ghsa_exports);
+var import_node_process = __toESM(require("node:process"));
+var import_request = require("../http-request/request");
+var import_error = require("../primordials/error");
+var import_json = require("../primordials/json");
+var import_fetch = require("./fetch");
+var import_refs = require("./refs");
+var import_token = require("./token");
+var import_constants = require("./constants");
+var import_errors = require("./errors");
+async function cacheFetchGhsa(ghsaId, options) {
+  const cache = (0, import_refs.getGithubCache)();
+  const key = `ghsa:${ghsaId}`;
+  if (import_node_process.default.env["DISABLE_GITHUB_CACHE"]) {
+    return await fetchGhsaDetails(ghsaId, options);
+  }
+  return await cache.getOrFetch(key, async () => {
+    return await fetchGhsaDetails(ghsaId, options);
+  });
+}
+async function fetchGhsaDetails(ghsaId, options) {
+  const url = `https://api.github.com/advisories/${ghsaId}`;
+  try {
+    const data = await (0, import_fetch.fetchGitHub)(url, options);
+    return {
+      ghsaId: data.ghsa_id,
+      summary: data.summary,
+      details: data.details,
+      severity: data.severity,
+      aliases: data.aliases || [],
+      publishedAt: data.published_at,
+      updatedAt: data.updated_at,
+      withdrawnAt: data.withdrawn_at,
+      references: data.references || [],
+      vulnerabilities: data.vulnerabilities || [],
+      cvss: data.cvss,
+      cwes: data.cwes || []
+    };
+  } catch (e) {
+    if (e instanceof import_errors.GitHubEmptyBodyError) {
+      try {
+        return await fetchGhsaDetailsViaGraphQL(ghsaId, options);
+      } catch (cause) {
+        throw new import_error.ErrorCtor(
+          `Failed to fetch advisory ${ghsaId}: both REST and GraphQL backends degraded`,
+          { cause }
+        );
+      }
+    }
+    throw e;
+  }
+}
+async function fetchGhsaDetailsViaGraphQL(ghsaId, options) {
+  const opts = { __proto__: null, ...options };
+  const token = opts.token || (0, import_token.getGitHubToken)();
+  const headers = {
+    Accept: "application/vnd.github.v3+json",
+    "Content-Type": "application/json",
+    "User-Agent": "socket-registry-github-client",
+    ...opts.headers
+  };
+  if (token) {
+    headers["Authorization"] = `Bearer ${token}`;
+  }
+  const query = `query($ghsaId: String!) {
+    securityAdvisory(ghsaId: $ghsaId) {
+      ghsaId
+      summary
+      description
+      severity
+      publishedAt
+      updatedAt
+      withdrawnAt
+      cvss { score vectorString }
+      cwes(first: 50) { nodes { cweId name description } }
+      references { url }
+      vulnerabilities(first: 100) {
+        nodes {
+          package { ecosystem name }
+          vulnerableVersionRange
+          firstPatchedVersion { identifier }
+        }
+      }
+      identifiers { type value }
+    }
+  }`;
+  const response = await (0, import_request.httpRequest)(import_constants.GITHUB_GRAPHQL_URL, {
+    body: (0, import_json.JSONStringify)({ query, variables: { ghsaId } }),
+    headers,
+    method: "POST"
+  });
+  if (!response.ok) {
+    throw new import_error.ErrorCtor(
+      `GitHub GraphQL API error ${response.status}: ${response.statusText}`
+    );
+  }
+  if (response.body.byteLength === 0) {
+    throw new import_errors.GitHubEmptyBodyError(import_constants.GITHUB_GRAPHQL_URL);
+  }
+  let parsed;
+  try {
+    parsed = (0, import_json.JSONParse)(response.body.toString("utf8"));
+  } catch (cause) {
+    throw new import_error.ErrorCtor(
+      `Failed to parse GitHub GraphQL response for advisory ${ghsaId}`,
+      { cause }
+    );
+  }
+  if (parsed.errors?.length) {
+    throw new import_error.ErrorCtor(
+      `GraphQL securityAdvisory(${ghsaId}) returned errors: ${parsed.errors.map((e) => e.message).join("; ")}`
+    );
+  }
+  const adv = parsed.data?.securityAdvisory;
+  if (!adv) {
+    throw new import_error.ErrorCtor(`GHSA ${ghsaId} not found`);
+  }
+  return {
+    ghsaId: adv.ghsaId,
+    summary: adv.summary,
+    details: adv.description,
+    severity: adv.severity.toLowerCase(),
+    aliases: adv.identifiers?.filter((i) => i.type !== "GHSA").map((i) => i.value) ?? [],
+    publishedAt: adv.publishedAt,
+    updatedAt: adv.updatedAt,
+    withdrawnAt: adv.withdrawnAt ?? "",
+    references: adv.references ?? [],
+    vulnerabilities: adv.vulnerabilities?.nodes ?? [],
+    // GhsaDetails.cvss is typed `... | null` to match the REST
+    // `/advisories/:id` shape. Preserving `null` here is the external-
+    // API-contract exception called out in the lint rule docs.
+    // oxlint-disable-next-line socket/prefer-undefined-over-null
+    cvss: adv.cvss ?? null,
+    cwes: adv.cwes?.nodes ?? []
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  cacheFetchGhsa,
+  fetchGhsaDetails,
+  fetchGhsaDetailsViaGraphQL
+});

package/dist/github/refs-cache.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @file TtlCache singleton for github/refs. Split out of `github/refs.ts` for
+ *   size hygiene. Owns the lazy `_githubCache` slot, the accessor
+ *   (`getGithubCache`), and the in-memory-only clear (`clearRefCache`). Caching
+ *   strategy:
+ *
+ *   - In-memory cache (Map) for immediate lookups
+ *   - Persistent disk cache (cacache) for durability across runs
+ *   - Default TTL: 5 minutes
+ *   - Disable everything with the `DISABLE_GITHUB_CACHE` env var
+ */
+import type { TtlCache } from '../ttl-cache/types';
+/**
+ * Clear the ref resolution cache (in-memory only). Clears the in-memory
+ * memoization cache without affecting the persistent disk cache. Useful for
+ * testing or when you need fresh data from the API.
+ *
+ * Note: This only clears the in-memory cache. The persistent cacache storage
+ * remains intact and will be used to rebuild the in-memory cache on next
+ * access.
+ *
+ * @example
+ *   ;```ts
+ *   // Clear cache to force fresh API calls
+ *   await clearRefCache()
+ *   const sha = await resolveRefToSha('owner', 'repo', 'main')
+ *   // This will hit the persistent cache or API, not in-memory cache
+ *   ```
+ *
+ * @returns Promise that resolves when cache is cleared
+ */
+export declare function clearRefCache(): Promise<void>;
+/**
+ * Get or create the GitHub cache instance. Lazy initializes the cache with
+ * default TTL and memoization enabled. Used internally for caching GitHub API
+ * responses.
+ *
+ * @returns The singleton cache instance
+ */
+export declare function getGithubCache(): TtlCache;

package/dist/github/refs-cache.js

@@ -0,0 +1,49 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var refs_cache_exports = {};
+__export(refs_cache_exports, {
+  clearRefCache: () => clearRefCache,
+  getGithubCache: () => getGithubCache
+});
+module.exports = __toCommonJS(refs_cache_exports);
+var import_cache = require("../ttl-cache/cache");
+var import_constants = require("./constants");
+let _githubCache;
+async function clearRefCache() {
+  if (_githubCache) {
+    await _githubCache.clear({ memoOnly: true });
+  }
+}
+function getGithubCache() {
+  if (_githubCache === void 0) {
+    _githubCache = (0, import_cache.createTtlCache)({
+      memoize: true,
+      prefix: "github-refs",
+      ttl: import_constants.DEFAULT_CACHE_TTL_MS
+    });
+  }
+  return _githubCache;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clearRefCache,
+  getGithubCache
+});

package/dist/github/refs-graphql.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @file Resolve a GitHub git ref via GraphQL. Split out of `github/refs.ts` for
+ *   size hygiene. The fallback the REST tier-cascade calls when it detects the
+ *   documented "200 + empty body" incident shape — GraphQL hits a different
+ *   backend at GitHub (not the same Elasticsearch index as REST listings) and
+ *   stays consistent through those incidents.
+ */
+import type { GitHubFetchOptions } from './types';
+/**
+ * Resolve a ref to its commit SHA via GraphQL.
+ *
+ * Why this function exists: This is the fallback that `fetchRefSha` calls when
+ * the REST tier-cascade detects the "GitHub returned 200 + empty body" incident
+ * shape. GraphQL hits a different backend than REST listings, so it stays
+ * consistent through the kinds of incidents that produce empty REST responses.
+ *
+ * What it does: The REST cascade needs three separate calls (tag, branch,
+ * commit) because REST has no single "resolve any ref" endpoint. GraphQL DOES —
+ * `Repository.ref(qualifiedName)` resolves tags AND branches by their
+ * fully-qualified name, and `Repository.object(oid)` resolves a raw commit SHA.
+ * We bundle all three into ONE query using GraphQL aliases (`tagRef`,
+ * `branchRef`, `commit`) and pick whichever resolved.
+ *
+ * Annotated vs lightweight tags: In Git, a "lightweight tag" is just a name
+ * that points directly at a commit. An "annotated tag" is a separate object
+ * (with tagger info, message, etc.) that itself points at the commit. GraphQL's
+ * `Tag.target` field gives us the commit SHA for annotated tags in one shot —
+ * REST needs a _second_ HTTP call to dereference. The `... on Tag { target {
+ * oid } }` / `... on Commit { oid }` inline-fragments handle both shapes.
+ *
+ * Return contract:
+ *
+ * - Returns the SHA string when any form matches.
+ * - Returns `undefined` when the ref genuinely doesn't exist as a tag, branch, OR
+ *   commit. The caller treats `undefined` the same as "REST cascade also
+ *   failed" — a real "ref not found".
+ * - Returns `undefined` (not throws) on transport-level failures too: non-OK
+ *   HTTP, empty GraphQL body, or JSON parse error. The REST cascade's "ref not
+ *   found" message is more useful to the end user than a GraphQL transport
+ *   error.
+ */
+export declare function fetchRefShaViaGraphQL(owner: string, repo: string, ref: string, options: GitHubFetchOptions): Promise<string | undefined>;

package/dist/github/refs-graphql.js

@@ -0,0 +1,109 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var refs_graphql_exports = {};
+__export(refs_graphql_exports, {
+  fetchRefShaViaGraphQL: () => fetchRefShaViaGraphQL
+});
+module.exports = __toCommonJS(refs_graphql_exports);
+var import_request = require("../http-request/request");
+var import_json = require("../primordials/json");
+var import_token = require("./token");
+var import_constants = require("./constants");
+async function fetchRefShaViaGraphQL(owner, repo, ref, options) {
+  const token = options.token || (0, import_token.getGitHubToken)();
+  const headers = {
+    Accept: "application/vnd.github.v3+json",
+    "Content-Type": "application/json",
+    "User-Agent": "socket-registry-github-client",
+    ...options.headers
+  };
+  if (token) {
+    headers["Authorization"] = `Bearer ${token}`;
+  }
+  const query = `query($owner: String!, $repo: String!, $tag: String!, $branch: String!, $oid: GitObjectID!) {
+    repository(owner: $owner, name: $repo) {
+      tagRef: ref(qualifiedName: $tag) {
+        target {
+          __typename
+          ... on Tag { target { oid } }
+          ... on Commit { oid }
+        }
+      }
+      branchRef: ref(qualifiedName: $branch) {
+        target { oid }
+      }
+      commit: object(oid: $oid) {
+        __typename
+        ... on Commit { oid }
+      }
+    }
+  }`;
+  const looksLikeSha = /^[a-f0-9]{40}$/i.test(ref);
+  const oidArg = looksLikeSha ? ref : "0000000000000000000000000000000000000000";
+  const response = await (0, import_request.httpRequest)(import_constants.GITHUB_GRAPHQL_URL, {
+    body: (0, import_json.JSONStringify)({
+      query,
+      variables: {
+        branch: `refs/heads/${ref}`,
+        oid: oidArg,
+        owner,
+        repo,
+        tag: `refs/tags/${ref}`
+      }
+    }),
+    headers,
+    method: "POST"
+  });
+  if (!response.ok || response.body.byteLength === 0) {
+    return void 0;
+  }
+  let parsed;
+  try {
+    parsed = (0, import_json.JSONParse)(response.body.toString("utf8"));
+  } catch {
+    return void 0;
+  }
+  const repoData = parsed.data?.repository;
+  if (!repoData) {
+    return void 0;
+  }
+  const tagTarget = repoData.tagRef?.target;
+  if (tagTarget) {
+    if (tagTarget.__typename === "Tag") {
+      return tagTarget.target?.oid ?? void 0;
+    }
+    if (tagTarget.__typename === "Commit") {
+      return tagTarget.oid ?? void 0;
+    }
+  }
+  const branchOid = repoData.branchRef?.target?.oid;
+  if (branchOid) {
+    return branchOid;
+  }
+  if (repoData.commit?.__typename === "Commit" && repoData.commit.oid) {
+    return repoData.commit.oid;
+  }
+  return void 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fetchRefShaViaGraphQL
+});

package/dist/github/refs-rest.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @file Resolve a GitHub git ref via REST tier-cascade. Split out of
+ *   `github/refs.ts` for size hygiene. Walks tag → branch → commit endpoints in
+ *   sequence; the first 200 OK wins. If any tier hits the documented
+ *   200-OK-empty-body incident shape, falls back to the GraphQL transport in
+ *   `./refs-graphql`.
+ */
+import type { ResolveRefOptions } from './types';
+/**
+ * Fetch the SHA for a git ref from GitHub API. Internal helper that implements
+ * the multi-strategy ref resolution logic. Tries tags, branches, and direct
+ * commit lookups in sequence.
+ *
+ * @param owner - Repository owner.
+ * @param repo - Repository name.
+ * @param ref - Git reference to resolve.
+ * @param options - Resolution options with authentication token.
+ *
+ * @returns The full commit SHA
+ *
+ * @throws {Error} When ref cannot be resolved after all strategies fail
+ */
+export declare function fetchRefSha(owner: string, repo: string, ref: string, options: ResolveRefOptions): Promise<string>;

package/dist/github/refs-rest.js

@@ -0,0 +1,104 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var refs_rest_exports = {};
+__export(refs_rest_exports, {
+  fetchRefSha: () => fetchRefSha
+});
+module.exports = __toCommonJS(refs_rest_exports);
+var import_message = require("../errors/message");
+var import_error = require("../primordials/error");
+var import_fetch = require("./fetch");
+var import_refs_graphql = require("./refs-graphql");
+var import_constants = require("./constants");
+var import_errors = require("./errors");
+async function fetchRefSha(owner, repo, ref, options) {
+  const fetchOptions = {
+    token: options.token
+  };
+  let sawEmptyBody = false;
+  const note404 = (e) => {
+    if (e instanceof import_errors.GitHubEmptyBodyError) {
+      sawEmptyBody = true;
+    }
+    return e;
+  };
+  try {
+    const tagUrl = `${import_constants.GITHUB_API_BASE_URL}/repos/${owner}/${repo}/git/refs/tags/${ref}`;
+    const tagData = await (0, import_fetch.fetchGitHub)(tagUrl, fetchOptions);
+    if (tagData.object.type === "tag") {
+      const tagObject = await (0, import_fetch.fetchGitHub)(
+        tagData.object.url,
+        fetchOptions
+      );
+      return tagObject.object.sha;
+    }
+    return tagData.object.sha;
+  } catch (e) {
+    note404(e);
+    try {
+      const branchUrl = `${import_constants.GITHUB_API_BASE_URL}/repos/${owner}/${repo}/git/refs/heads/${ref}`;
+      const branchData = await (0, import_fetch.fetchGitHub)(branchUrl, fetchOptions);
+      return branchData.object.sha;
+    } catch (e2) {
+      note404(e2);
+      try {
+        const commitUrl = `${import_constants.GITHUB_API_BASE_URL}/repos/${owner}/${repo}/commits/${ref}`;
+        const commitData = await (0, import_fetch.fetchGitHub)(
+          commitUrl,
+          fetchOptions
+        );
+        return commitData.sha;
+      } catch (e3) {
+        note404(e3);
+        if (sawEmptyBody) {
+          let graphqlSha;
+          let graphqlErr;
+          try {
+            graphqlSha = await (0, import_refs_graphql.fetchRefShaViaGraphQL)(
+              owner,
+              repo,
+              ref,
+              fetchOptions
+            );
+          } catch (cause) {
+            graphqlErr = cause;
+          }
+          if (graphqlSha) {
+            return graphqlSha;
+          }
+          if (graphqlErr !== void 0) {
+            throw new import_error.ErrorCtor(
+              `Failed to resolve ref "${ref}" for ${owner}/${repo}: both REST and GraphQL backends degraded`,
+              { cause: graphqlErr }
+            );
+          }
+        }
+        throw new import_error.ErrorCtor(
+          `Failed to resolve ref "${ref}" for ${owner}/${repo}: ${(0, import_message.errorMessage)(e3)}`
+        );
+      }
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fetchRefSha
+});

package/dist/github/refs.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @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';