@socketsecurity/lib 5.18.2 → 5.19.0

package/dist/github.d.ts

@@ -1,3 +1,25 @@
+/**
+ * @fileoverview GitHub utilities for Socket projects.
+ * Provides GitHub API integration for repository operations.
+ *
+ * Authentication:
+ * - getGitHubToken: Retrieve GitHub token from environment variables
+ * - fetchGitHub: Authenticated GitHub API requests with rate limit handling
+ *
+ * Ref Resolution:
+ * - resolveRefToSha: Convert tags/branches to commit SHAs (with memoization and persistent cache)
+ * - clearRefCache: Clear the in-memory memoization cache
+ *
+ * Caching:
+ * - Uses cacache for persistent storage with in-memory memoization
+ * - Two-tier caching: in-memory (Map) for hot data, persistent (cacache) for durability
+ * - Default TTL: 5 minutes
+ * - Disable with DISABLE_GITHUB_CACHE env var
+ *
+ * Rate Limiting:
+ * - Automatic rate limit detection and error messages
+ * - Cache to minimize API calls
+ */
 import type { SpawnOptions } from './spawn';
 /**
  * Options for GitHub API fetch requests.
@@ -27,83 +49,6 @@ export interface GitHubRateLimitError extends Error {
      */
     resetTime?: Date | undefined;
 }
-/**
- * Get GitHub authentication token from environment variables.
- * Checks multiple environment variable names in priority order.
- *
- * Environment variables checked (in order):
- * 1. `GITHUB_TOKEN` - Standard GitHub token variable
- * 2. `GH_TOKEN` - Alternative GitHub CLI token variable
- * 3. `SOCKET_CLI_GITHUB_TOKEN` - Socket-specific token variable
- *
- * @returns The first available GitHub token, or `undefined` if none found
- *
- * @example
- * ```ts
- * const token = getGitHubToken()
- * if (!token) {
- *   console.warn('No GitHub token found')
- * }
- * ```
- */
-export declare function getGitHubToken(): string | undefined;
-/**
- * Fetch data from GitHub API with automatic authentication and rate limit handling.
- * Makes authenticated requests to the GitHub REST API with proper error handling.
- *
- * Features:
- * - Automatic token injection from environment if not provided
- * - Rate limit detection with helpful error messages
- * - Standard GitHub API headers (Accept, User-Agent)
- * - JSON response parsing
- *
- * @template T - Expected response type (defaults to `unknown`)
- * @param url - Full GitHub API URL (e.g., 'https://api.github.com/repos/owner/repo')
- * @param options - Fetch options including token and custom headers
- * @returns Parsed JSON response of type `T`
- *
- * @throws {GitHubRateLimitError} When API rate limit is exceeded (status 403)
- * @throws {Error} For other API errors with status code and message
- *
- * @example
- * ```ts
- * // Fetch repository information
- * interface Repo {
- *   name: string
- *   full_name: string
- *   default_branch: string
- * }
- * const repo = await fetchGitHub<Repo>(
- *   'https://api.github.com/repos/owner/repo'
- * )
- * console.log(`Default branch: ${repo.default_branch}`)
- * ```
- *
- * @example
- * ```ts
- * // With custom token and headers
- * const data = await fetchGitHub(
- *   'https://api.github.com/user',
- *   {
- *     token: 'ghp_customtoken',
- *     headers: { 'X-Custom-Header': 'value' }
- *   }
- * )
- * ```
- *
- * @example
- * ```ts
- * // Handle rate limit errors
- * try {
- *   await fetchGitHub('https://api.github.com/repos/owner/repo')
- * } catch (error) {
- *   if (error.status === 403 && error.resetTime) {
- *     console.error(`Rate limited until ${error.resetTime}`)
- *   }
- * }
- * ```
- */
-export declare function fetchGitHub<T = unknown>(url: string, options?: GitHubFetchOptions | undefined): Promise<T>;
 /**
  * GitHub ref object returned by the API.
  * Represents a git reference (tag or branch).
@@ -192,129 +137,6 @@ export interface ResolveRefOptions {
      */
     token?: string | undefined;
 }
-/**
- * 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
- *
- * @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
- *
- * @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
- * ```
- */
-export declare function resolveRefToSha(owner: string, repo: string, ref: string, options?: ResolveRefOptions | undefined): Promise<string>;
-/**
- * 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.
- *
- * @returns Promise that resolves when cache is cleared
- *
- * @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
- * ```
- */
-export declare function clearRefCache(): Promise<void>;
-/**
- * Get GitHub authentication token from git config.
- * Reads the `github.token` configuration value from git config.
- * This is a fallback method when environment variables don't contain a token.
- *
- * @param options - Spawn options for git command execution
- * @returns GitHub token from git config, or `undefined` if not configured
- *
- * @example
- * ```ts
- * const token = await getGitHubTokenFromGitConfig()
- * if (token) {
- *   console.log('Found token in git config')
- * }
- * ```
- *
- * @example
- * ```ts
- * // With custom working directory
- * const token = await getGitHubTokenFromGitConfig({
- *   cwd: '/path/to/repo'
- * })
- * ```
- */
-export declare function getGitHubTokenFromGitConfig(options?: SpawnOptions | undefined): Promise<string | undefined>;
-/**
- * Get GitHub authentication token from all available sources.
- * Checks environment variables first, then falls back to git config.
- * This is the recommended way to get a GitHub token with maximum compatibility.
- *
- * Priority order:
- * 1. Environment variables (GITHUB_TOKEN, GH_TOKEN, SOCKET_CLI_GITHUB_TOKEN)
- * 2. Git config (github.token)
- *
- * @returns GitHub token from first available source, or `undefined` if none found
- *
- * @example
- * ```ts
- * const token = await getGitHubTokenWithFallback()
- * if (!token) {
- *   throw new Error('GitHub token required')
- * }
- * ```
- */
-export declare function getGitHubTokenWithFallback(): Promise<string | undefined>;
 /**
  * GitHub Security Advisory (GHSA) details.
  * Represents a complete security advisory from GitHub's database.
@@ -383,19 +205,60 @@ export interface GhsaDetails {
     }>;
 }
 /**
- * Generate GitHub Security Advisory URL from GHSA ID.
- * Constructs the public advisory URL for a given GHSA identifier.
+ * Fetch GitHub Security Advisory details with caching.
+ * Retrieves advisory information with two-tier caching (in-memory + persistent).
+ * Cached results are stored with the default TTL (5 minutes).
  *
- * @param ghsaId - GHSA identifier (e.g., 'GHSA-xxxx-yyyy-zzzz')
- * @returns Full URL to the advisory page
+ * Caching behavior:
+ * - Checks in-memory cache first for immediate response
+ * - Falls back to persistent disk cache if not in memory
+ * - Fetches from API only if not cached
+ * - Stores result in both cache tiers
+ * - Respects `DISABLE_GITHUB_CACHE` env var
+ *
+ * @param ghsaId - GHSA identifier to fetch
+ * @param options - Fetch options including authentication token
+ * @returns Complete advisory details
+ *
+ * @throws {Error} If advisory cannot be found or API request fails
+ * @throws {GitHubRateLimitError} When API rate limit is exceeded
  *
  * @example
  * ```ts
- * const url = getGhsaUrl('GHSA-1234-5678-90ab')
- * console.log(url) // 'https://github.com/advisories/GHSA-1234-5678-90ab'
+ * // First call hits API
+ * const advisory = await cacheFetchGhsa('GHSA-1234-5678-90ab')
+ *
+ * // Second call within 5 minutes returns cached data
+ * const cached = await cacheFetchGhsa('GHSA-1234-5678-90ab')
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Disable caching for fresh data
+ * process.env.DISABLE_GITHUB_CACHE = '1'
+ * const advisory = await cacheFetchGhsa('GHSA-xxxx-yyyy-zzzz')
  * ```
  */
-export declare function getGhsaUrl(ghsaId: string): string;
+export declare function cacheFetchGhsa(ghsaId: string, options?: GitHubFetchOptions | undefined): Promise<GhsaDetails>;
+/**
+ * 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.
+ *
+ * @returns Promise that resolves when cache is cleared
+ *
+ * @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
+ * ```
+ */
+export declare function clearRefCache(): Promise<void>;
 /**
  * Fetch GitHub Security Advisory details from the API.
  * Retrieves complete advisory information including severity, affected packages,
@@ -433,38 +296,197 @@ export declare function getGhsaUrl(ghsaId: string): string;
  */
 export declare function fetchGhsaDetails(ghsaId: string, options?: GitHubFetchOptions | undefined): Promise<GhsaDetails>;
 /**
- * Fetch GitHub Security Advisory details with caching.
- * Retrieves advisory information with two-tier caching (in-memory + persistent).
- * Cached results are stored with the default TTL (5 minutes).
+ * Fetch data from GitHub API with automatic authentication and rate limit handling.
+ * Makes authenticated requests to the GitHub REST API with proper error handling.
+ *
+ * Features:
+ * - Automatic token injection from environment if not provided
+ * - Rate limit detection with helpful error messages
+ * - Standard GitHub API headers (Accept, User-Agent)
+ * - JSON response parsing
+ *
+ * @template T - Expected response type (defaults to `unknown`)
+ * @param url - Full GitHub API URL (e.g., 'https://api.github.com/repos/owner/repo')
+ * @param options - Fetch options including token and custom headers
+ * @returns Parsed JSON response of type `T`
+ *
+ * @throws {GitHubRateLimitError} When API rate limit is exceeded (status 403)
+ * @throws {Error} For other API errors with status code and message
+ *
+ * @example
+ * ```ts
+ * // Fetch repository information
+ * interface Repo {
+ *   name: string
+ *   full_name: string
+ *   default_branch: string
+ * }
+ * const repo = await fetchGitHub<Repo>(
+ *   'https://api.github.com/repos/owner/repo'
+ * )
+ * console.log(`Default branch: ${repo.default_branch}`)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With custom token and headers
+ * const data = await fetchGitHub(
+ *   'https://api.github.com/user',
+ *   {
+ *     token: 'ghp_customtoken',
+ *     headers: { 'X-Custom-Header': 'value' }
+ *   }
+ * )
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Handle rate limit errors
+ * try {
+ *   await fetchGitHub('https://api.github.com/repos/owner/repo')
+ * } catch (error) {
+ *   if (error.status === 403 && error.resetTime) {
+ *     console.error(`Rate limited until ${error.resetTime}`)
+ *   }
+ * }
+ * ```
+ */
+export declare function fetchGitHub<T = unknown>(url: string, options?: GitHubFetchOptions | undefined): Promise<T>;
+/**
+ * Generate GitHub Security Advisory URL from GHSA ID.
+ * Constructs the public advisory URL for a given GHSA identifier.
+ *
+ * @param ghsaId - GHSA identifier (e.g., 'GHSA-xxxx-yyyy-zzzz')
+ * @returns Full URL to the advisory page
+ *
+ * @example
+ * ```ts
+ * const url = getGhsaUrl('GHSA-1234-5678-90ab')
+ * console.log(url) // 'https://github.com/advisories/GHSA-1234-5678-90ab'
+ * ```
+ */
+export declare function getGhsaUrl(ghsaId: string): string;
+/**
+ * Get GitHub authentication token from environment variables.
+ * Checks multiple environment variable names in priority order.
+ *
+ * Environment variables checked (in order):
+ * 1. `GITHUB_TOKEN` - Standard GitHub token variable
+ * 2. `GH_TOKEN` - Alternative GitHub CLI token variable
+ * 3. `SOCKET_CLI_GITHUB_TOKEN` - Socket-specific token variable
+ *
+ * @returns The first available GitHub token, or `undefined` if none found
+ *
+ * @example
+ * ```ts
+ * const token = getGitHubToken()
+ * if (!token) {
+ *   console.warn('No GitHub token found')
+ * }
+ * ```
+ */
+export declare function getGitHubToken(): string | undefined;
+/**
+ * Get GitHub authentication token from git config.
+ * Reads the `github.token` configuration value from git config.
+ * This is a fallback method when environment variables don't contain a token.
+ *
+ * @param options - Spawn options for git command execution
+ * @returns GitHub token from git config, or `undefined` if not configured
+ *
+ * @example
+ * ```ts
+ * const token = await getGitHubTokenFromGitConfig()
+ * if (token) {
+ *   console.log('Found token in git config')
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With custom working directory
+ * const token = await getGitHubTokenFromGitConfig({
+ *   cwd: '/path/to/repo'
+ * })
+ * ```
+ */
+export declare function getGitHubTokenFromGitConfig(options?: SpawnOptions | undefined): Promise<string | undefined>;
+/**
+ * Get GitHub authentication token from all available sources.
+ * Checks environment variables first, then falls back to git config.
+ * This is the recommended way to get a GitHub token with maximum compatibility.
+ *
+ * Priority order:
+ * 1. Environment variables (GITHUB_TOKEN, GH_TOKEN, SOCKET_CLI_GITHUB_TOKEN)
+ * 2. Git config (github.token)
+ *
+ * @returns GitHub token from first available source, or `undefined` if none found
+ *
+ * @example
+ * ```ts
+ * const token = await getGitHubTokenWithFallback()
+ * if (!token) {
+ *   throw new Error('GitHub token required')
+ * }
+ * ```
+ */
+export declare function getGitHubTokenWithFallback(): Promise<string | undefined>;
+/**
+ * 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:
- * - Checks in-memory cache first for immediate response
- * - Falls back to persistent disk cache if not in memory
- * - Fetches from API only if not cached
- * - Stores result in both cache tiers
- * - Respects `DISABLE_GITHUB_CACHE` env var
+ * - 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
  *
- * @param ghsaId - GHSA identifier to fetch
- * @param options - Fetch options including authentication token
- * @returns Complete advisory details
+ * @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} If advisory cannot be found or API request fails
+ * @throws {Error} When ref cannot be resolved after trying all strategies
  * @throws {GitHubRateLimitError} When API rate limit is exceeded
  *
  * @example
  * ```ts
- * // First call hits API
- * const advisory = await cacheFetchGhsa('GHSA-1234-5678-90ab')
+ * // Resolve a tag to commit SHA
+ * const sha = await resolveRefToSha('owner', 'repo', 'v1.0.0')
+ * console.log(sha) // 'a1b2c3d4e5f6...'
+ * ```
  *
- * // Second call within 5 minutes returns cached data
- * const cached = await cacheFetchGhsa('GHSA-1234-5678-90ab')
+ * @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
- * // Disable caching for fresh data
- * process.env.DISABLE_GITHUB_CACHE = '1'
- * const advisory = await cacheFetchGhsa('GHSA-xxxx-yyyy-zzzz')
+ * // 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
  * ```
  */
-export declare function cacheFetchGhsa(ghsaId: string, options?: GitHubFetchOptions | undefined): Promise<GhsaDetails>;
+export declare function resolveRefToSha(owner: string, repo: string, ref: string, options?: ResolveRefOptions | undefined): Promise<string>;