@socketsecurity/lib 5.28.0 → 6.0.0

package/dist/git/unstaged.d.ts

@@ -0,0 +1,141 @@
+/**
+ * @file "Edited but not yet staged" helpers — `git diff` over the working tree
+ *   only. Excludes index-staged changes and untracked paths; use `changed.ts`
+ *   for the broader view or `staged.ts` for the index.
+ */
+import type { GitDiffOptions } from './types';
+/**
+ * Get unstaged modified files (changes not yet staged for commit).
+ *
+ * Uses `git diff --name-only` which returns only unstaged modifications to
+ * tracked files. Does NOT include: - Untracked files (new files not added to
+ * git) - Staged changes (files added with `git add`)
+ *
+ * This is a focused check for uncommitted changes to existing tracked files.
+ * Useful for detecting work-in-progress modifications before staging.
+ *
+ * @example
+ *   ;```typescript
+ *   // Get unstaged files
+ *   const files = await getUnstagedFiles()
+ *   // => ['src/foo.ts', 'src/bar.ts']
+ *
+ *   // After staging some files
+ *   await spawn('git', ['add', 'src/foo.ts'])
+ *   const files = await getUnstagedFiles()
+ *   // => ['src/bar.ts'] (foo.ts no longer included)
+ *
+ *   // Get absolute paths
+ *   const files = await getUnstagedFiles({ absolute: true })
+ *   // => ['/path/to/repo/src/bar.ts']
+ *   ```
+ *
+ * @param options - Options controlling path format and filtering.
+ *
+ * @returns Promise resolving to array of unstaged file paths.
+ */
+export declare function getUnstagedFiles(options?: GitDiffOptions | undefined): Promise<string[]>;
+/**
+ * Get unstaged modified files (changes not yet staged for commit).
+ *
+ * Synchronous version of `getUnstagedFiles()`. Uses `git diff --name-only`
+ * which returns only unstaged modifications to tracked files. Does NOT include:
+ * - Untracked files (new files not added to git) - Staged changes (files added
+ * with `git add`)
+ *
+ * This is a focused check for uncommitted changes to existing tracked files.
+ * Useful for detecting work-in-progress modifications before staging.
+ *
+ * @example
+ *   ;```typescript
+ *   // Get unstaged files
+ *   const files = getUnstagedFilesSync()
+ *   // => ['src/foo.ts', 'src/bar.ts']
+ *
+ *   // After staging some files
+ *   spawnSync('git', ['add', 'src/foo.ts'])
+ *   const files = getUnstagedFilesSync()
+ *   // => ['src/bar.ts'] (foo.ts no longer included)
+ *
+ *   // Get absolute paths
+ *   const files = getUnstagedFilesSync({ absolute: true })
+ *   // => ['/path/to/repo/src/bar.ts']
+ *   ```
+ *
+ * @param options - Options controlling path format and filtering.
+ *
+ * @returns Array of unstaged file paths.
+ */
+export declare function getUnstagedFilesSync(options?: GitDiffOptions | undefined): string[];
+/**
+ * Check if a file or directory has unstaged changes.
+ *
+ * Checks if the given pathname has modifications that are not yet staged for
+ * commit (changes not added with `git add`). Does NOT include: - Staged changes
+ * (already added with `git add`) - Untracked files (new files not in git)
+ *
+ * For directories, returns `true` if ANY file within the directory has unstaged
+ * changes.
+ *
+ * Symlinks in the pathname and cwd are automatically resolved using
+ * `fs.realpathSync()` before comparison.
+ *
+ * @example
+ *   ;```typescript
+ *   // Check if file has unstaged changes
+ *   const unstaged = await isUnstaged('src/foo.ts')
+ *   // => true
+ *
+ *   // After staging the file
+ *   await spawn('git', ['add', 'src/foo.ts'])
+ *   const unstaged = await isUnstaged('src/foo.ts')
+ *   // => false
+ *
+ *   // Check directory
+ *   const unstaged = await isUnstaged('src/')
+ *   // => true (if any file in src/ has unstaged changes)
+ *   ```
+ *
+ * @param pathname - File or directory path to check.
+ * @param options - Options for the git diff check.
+ *
+ * @returns Promise resolving to `true` if path has unstaged changes, `false`
+ *   otherwise.
+ */
+export declare function isUnstaged(pathname: string, options?: GitDiffOptions | undefined): Promise<boolean>;
+/**
+ * Check if a file or directory has unstaged changes.
+ *
+ * Synchronous version of `isUnstaged()`. Checks if the given pathname has
+ * modifications that are not yet staged for commit (changes not added with `git
+ * add`). Does NOT include: - Staged changes (already added with `git add`) -
+ * Untracked files (new files not in git)
+ *
+ * For directories, returns `true` if ANY file within the directory has unstaged
+ * changes.
+ *
+ * Symlinks in the pathname and cwd are automatically resolved using
+ * `fs.realpathSync()` before comparison.
+ *
+ * @example
+ *   ;```typescript
+ *   // Check if file has unstaged changes
+ *   const unstaged = isUnstagedSync('src/foo.ts')
+ *   // => true
+ *
+ *   // After staging the file
+ *   spawnSync('git', ['add', 'src/foo.ts'])
+ *   const unstaged = isUnstagedSync('src/foo.ts')
+ *   // => false
+ *
+ *   // Check directory
+ *   const unstaged = isUnstagedSync('src/')
+ *   // => true (if any file in src/ has unstaged changes)
+ *   ```
+ *
+ * @param pathname - File or directory path to check.
+ * @param options - Options for the git diff check.
+ *
+ * @returns `true` if path has unstaged changes, `false` otherwise.
+ */
+export declare function isUnstagedSync(pathname: string, options?: GitDiffOptions | undefined): boolean;

package/dist/git/unstaged.js

@@ -0,0 +1,71 @@
+"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 unstaged_exports = {};
+__export(unstaged_exports, {
+  getUnstagedFiles: () => getUnstagedFiles,
+  getUnstagedFilesSync: () => getUnstagedFilesSync,
+  isUnstaged: () => isUnstaged,
+  isUnstagedSync: () => isUnstagedSync
+});
+module.exports = __toCommonJS(unstaged_exports);
+var import_normalize = require("../paths/normalize");
+var import_array = require("../primordials/array");
+var import_internal = require("./_internal");
+var import_repo = require("./repo");
+async function getUnstagedFiles(options) {
+  const args = (0, import_internal.getGitDiffSpawnArgs)(options?.cwd).unstaged;
+  return await (0, import_internal.innerDiff)(args, options);
+}
+function getUnstagedFilesSync(options) {
+  const args = (0, import_internal.getGitDiffSpawnArgs)(options?.cwd).unstaged;
+  return (0, import_internal.innerDiffSync)(args, options);
+}
+async function isUnstaged(pathname, options) {
+  const files = await getUnstagedFiles({
+    __proto__: null,
+    ...options,
+    absolute: false
+  });
+  const path = (0, import_repo.getPath)();
+  const resolvedPathname = (0, import_repo.getCachedRealpath)(pathname);
+  const baseCwd = options?.cwd ? (0, import_repo.getCachedRealpath)(options["cwd"]) : (0, import_repo.getCwd)();
+  const relativePath = (0, import_normalize.normalizePath)(path.relative(baseCwd, resolvedPathname));
+  return (0, import_array.ArrayPrototypeIncludes)(files, relativePath);
+}
+function isUnstagedSync(pathname, options) {
+  const files = getUnstagedFilesSync({
+    __proto__: null,
+    ...options,
+    absolute: false
+  });
+  const path = (0, import_repo.getPath)();
+  const resolvedPathname = (0, import_repo.getCachedRealpath)(pathname);
+  const baseCwd = options?.cwd ? (0, import_repo.getCachedRealpath)(options["cwd"]) : (0, import_repo.getCwd)();
+  const relativePath = (0, import_normalize.normalizePath)(path.relative(baseCwd, resolvedPathname));
+  return (0, import_array.ArrayPrototypeIncludes)(files, relativePath);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getUnstagedFiles,
+  getUnstagedFilesSync,
+  isUnstaged,
+  isUnstagedSync
+});

package/dist/github/constants.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @file GitHub API URL + cache-TTL constants. Inlined so values are captured at
+ *   coverage-mode bundle time rather than referenced through a module graph
+ *   indirection.
+ */
+/**
+ * GitHub REST API base URL.
+ */
+export declare const GITHUB_API_BASE_URL = "https://api.github.com";
+/**
+ * GitHub GraphQL API endpoint.
+ */
+export declare const GITHUB_GRAPHQL_URL = "https://api.github.com/graphql";
+/**
+ * Default TTL for the GitHub cache (5 minutes). Used by ref resolution and the
+ * GHSA cache layer.
+ */
+export declare const DEFAULT_CACHE_TTL_MS: number;

package/dist/github/constants.js

@@ -0,0 +1,36 @@
+"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 constants_exports = {};
+__export(constants_exports, {
+  DEFAULT_CACHE_TTL_MS: () => DEFAULT_CACHE_TTL_MS,
+  GITHUB_API_BASE_URL: () => GITHUB_API_BASE_URL,
+  GITHUB_GRAPHQL_URL: () => GITHUB_GRAPHQL_URL
+});
+module.exports = __toCommonJS(constants_exports);
+const GITHUB_API_BASE_URL = "https://api.github.com";
+const GITHUB_GRAPHQL_URL = "https://api.github.com/graphql";
+const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1e3;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_CACHE_TTL_MS,
+  GITHUB_API_BASE_URL,
+  GITHUB_GRAPHQL_URL
+});

package/dist/github/errors.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @file Named errors thrown by `github/*` helpers.
+ */
+/**
+ * Thrown by `fetchGitHub` when GitHub returns HTTP 200 OK with a zero-byte body
+ * — the "successful empty response" pattern.
+ *
+ * Why this exists (background for new contributors): GitHub's REST API has a
+ * documented failure mode that is _very_ easy to miss in code review. During
+ * incidents where the search / Elasticsearch backing index is degraded (see
+ * GitHub status pages with titles like "search is degraded" or "Pull Requests
+ * degraded"), the REST `/repos/...` GET endpoints return: - HTTP status: 200 OK
+ * ← looks like success - Body: "" ← but the payload is empty - Headers: no
+ * Retry-After, no rate-limit signal, nothing.
+ *
+ * Without a typed error, calling code does
+ * `JSON.parse(response.body.toString('utf8'))` on an empty string, which throws
+ * a confusing `SyntaxError: Unexpected end of JSON input`. That error has
+ * nothing to do with bad code on our side; it's GitHub's incident manifesting
+ * as a parse failure several frames deep. We surface the actual condition (`200
+ * \+ empty body`) as its own typed exception so the call path can either fall
+ * through to the GraphQL backend (which queries a different data path and uses
+ * a different backend and is unaffected by ES outages), or surface a clean
+ * message to the user.
+ *
+ * The HTTP status is hard-coded to 200 because that's _exactly_ what makes this
+ * insidious — a real 4xx/5xx would already be handled by the rate-limit /
+ * status-code branch above.
+ */
+export declare class GitHubEmptyBodyError extends Error {
+    /**
+     * HTTP status (always 200 — that's what makes this case insidious).
+     */
+    status: number;
+    constructor(url: string);
+}

package/dist/github/errors.js

@@ -0,0 +1,40 @@
+"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 errors_exports = {};
+__export(errors_exports, {
+  GitHubEmptyBodyError: () => GitHubEmptyBodyError
+});
+module.exports = __toCommonJS(errors_exports);
+class GitHubEmptyBodyError extends Error {
+  /**
+   * HTTP status (always 200 — that's what makes this case insidious).
+   */
+  status;
+  constructor(url) {
+    super(`GitHub API returned HTTP 200 with empty body: ${url}`);
+    this.name = "GitHubEmptyBodyError";
+    this.status = 200;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GitHubEmptyBodyError
+});

package/dist/github/fetch.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @file Authenticated GitHub REST fetch. `fetchGitHub` is the single entry
+ *   point that the rest of the github/ modules go through for REST calls. It
+ *   handles four things the callers shouldn't have to repeat:
+ *
+ *   1. Token resolution (env → git config) when the caller doesn't pass an
+ *      explicit token.
+ *   2. Standard headers (Accept, User-Agent) merged with caller- supplied headers.
+ *   3. Rate-limit detection — when GitHub returns 403 with `x-ratelimit-remaining:
+ *      0`, throw a typed `GitHubRateLimitError` so callers can react (set
+ *      GITHUB_TOKEN, retry after reset).
+ *   4. Empty-body detection — 200 OK + zero-byte body is the documented incident
+ *      shape (see GitHubEmptyBodyError JSDoc). Raised as a typed error so the
+ *      ref / GHSA modules can fall back to GraphQL on a different backend.
+ *      `getGhsaUrl` lives here because it's the URL counterpart to the GHSA
+ *      fetch path — the only other consumer is the GHSA module.
+ */
+import type { GitHubFetchOptions } from './types';
+/**
+ * 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.
+ *
+ * @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 (e) {
+ *   if (e.status === 403 && e.resetTime) {
+ *   console.error(`Rate limited until ${e.resetTime}`)
+ *   }
+ *   }
+ *   ```
+ *
+ * @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
+ */
+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.
+ *
+ * @example
+ *   ;```ts
+ *   const url = getGhsaUrl('GHSA-1234-5678-90ab')
+ *   console.log(url) // 'https://github.com/advisories/GHSA-1234-5678-90ab'
+ *   ```
+ *
+ * @param ghsaId - GHSA identifier (e.g., 'GHSA-xxxx-yyyy-zzzz')
+ *
+ * @returns Full URL to the advisory page
+ */
+export declare function getGhsaUrl(ghsaId: string): string;

package/dist/github/fetch.js

@@ -0,0 +1,87 @@
+"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 fetch_exports = {};
+__export(fetch_exports, {
+  fetchGitHub: () => fetchGitHub,
+  getGhsaUrl: () => getGhsaUrl
+});
+module.exports = __toCommonJS(fetch_exports);
+var import_message = require("../errors/message");
+var import_request = require("../http-request/request");
+var import_date = require("../primordials/date");
+var import_error = require("../primordials/error");
+var import_json = require("../primordials/json");
+var import_token = require("./token");
+var import_errors = require("./errors");
+async function fetchGitHub(url, options) {
+  const opts = { __proto__: null, ...options };
+  const token = opts.token || (0, import_token.getGitHubToken)();
+  const headers = {
+    Accept: "application/vnd.github.v3+json",
+    "User-Agent": "socket-registry-github-client",
+    ...opts.headers
+  };
+  if (token) {
+    headers["Authorization"] = `Bearer ${token}`;
+  }
+  const response = await (0, import_request.httpRequest)(url, { headers });
+  if (!response.ok) {
+    if (response.status === 403) {
+      const rateLimit = response.headers["x-ratelimit-remaining"];
+      const rateLimitStr = typeof rateLimit === "string" ? rateLimit : rateLimit?.[0];
+      if (rateLimitStr === "0") {
+        const resetTime = response.headers["x-ratelimit-reset"];
+        const resetTimeStr = typeof resetTime === "string" ? resetTime : resetTime?.[0];
+        const resetDate = resetTimeStr ? new import_date.DateCtor(Number(resetTimeStr) * 1e3) : void 0;
+        const error = new import_error.ErrorCtor(
+          `GitHub API rate limit exceeded${resetDate ? `. Resets at ${resetDate.toLocaleString()}` : ""}. Use GITHUB_TOKEN environment variable to increase rate limit.`
+        );
+        error.status = 403;
+        error.resetTime = resetDate;
+        throw error;
+      }
+    }
+    throw new import_error.ErrorCtor(
+      `GitHub API error ${response.status}: ${response.statusText}`
+    );
+  }
+  if (response.body.byteLength === 0) {
+    throw new import_errors.GitHubEmptyBodyError(url);
+  }
+  try {
+    return (0, import_json.JSONParse)(response.body.toString("utf8"));
+  } catch (e) {
+    throw new import_error.ErrorCtor(
+      `Failed to parse GitHub API response: ${(0, import_message.errorMessage)(e)}
+URL: ${url}
+Response may be malformed or incomplete.`,
+      { cause: e }
+    );
+  }
+}
+function getGhsaUrl(ghsaId) {
+  return `https://github.com/advisories/${ghsaId}`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fetchGitHub,
+  getGhsaUrl
+});

package/dist/github/ghsa.d.ts

@@ -0,0 +1,118 @@
+/**
+ * @file GitHub Security Advisory (GHSA) lookups. Three layers, narrowest first:
+ *
+ *   - `cacheFetchGhsa` — caches GHSA fetches in the same `TtlCache` used by ref
+ *     resolution (5-minute TTL, two-tier).
+ *   - `fetchGhsaDetails` — REST `/advisories/:id` with the same empty-body
+ *     fallback to GraphQL that ref resolution uses.
+ *   - `fetchGhsaDetailsViaGraphQL` — GraphQL `securityAdvisory(...)` with shape
+ *     normalization back to the REST surface so callers don't have to know
+ *     which transport ran.
+ */
+import type { GhsaDetails, GitHubFetchOptions } from './types';
+/**
+ * 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).
+ *
+ * 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
+ *
+ * @example
+ *   ;```ts
+ *   // 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')
+ *   ```
+ *
+ * @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
+ */
+export declare function cacheFetchGhsa(ghsaId: string, options?: GitHubFetchOptions | undefined): Promise<GhsaDetails>;
+/**
+ * Fetch GitHub Security Advisory details from the API. Retrieves complete
+ * advisory information including severity, affected packages, CVSS scores, and
+ * CWE classifications.
+ *
+ * @example
+ *   ```ts
+ *   const advisory = await fetchGhsaDetails('GHSA-1234-5678-90ab')
+ *   console.log(`Severity: ${advisory.severity}`)
+ *   console.log(`Affects: ${advisory.vulnerabilities.length} packages`)
+ *   if (advisory.cvss) {
+ *   console.log(`CVSS Score: ${advisory.cvss.score}`)
+ *   }
+ *   ```
+ *
+ * @example
+ *   ```ts
+ *   // Check if vulnerability is patched
+ *   const advisory = await fetchGhsaDetails('GHSA-xxxx-yyyy-zzzz')
+ *   for (const vuln of advisory.vulnerabilities) {
+ *   if (vuln.firstPatchedVersion) {
+ *   console.log(
+ *   `Patched in ${vuln.package.name}@${vuln.firstPatchedVersion.identifier}`,
+ *   )
+ *   }
+ *   }
+ *   ```
+ *
+ * @param ghsaId - GHSA identifier to fetch (e.g., 'GHSA-xxxx-yyyy-zzzz')
+ * @param options - Fetch options including authentication token.
+ *
+ * @returns Complete advisory details with normalized field names
+ *
+ * @throws {Error} If advisory cannot be found or API request fails
+ * @throws {GitHubRateLimitError} When API rate limit is exceeded
+ */
+export declare function fetchGhsaDetails(ghsaId: string, options?: GitHubFetchOptions | undefined): Promise<GhsaDetails>;
+/**
+ * GraphQL counterpart for `fetchGhsaDetails`.
+ *
+ * What it does: Queries the GraphQL `securityAdvisory(ghsaId)` connection and
+ * reshapes the response to match the REST `/advisories/:id` JSON so callers
+ * don't have to know which transport ran.
+ *
+ * Three normalizations the REST shape differs from GraphQL on:
+ *
+ * 1. Severity case REST returns lowercase strings like "moderate", "high". GraphQL
+ *    returns SCREAMING_CASE enum values: "MODERATE", "HIGH", "CRITICAL". We
+ *    `.toLowerCase()` so callers can compare against a single canonical form.
+ * 2. Identifiers vs. aliases REST has an `aliases: ["CVE-2024-..."]` array — a
+ *    flat list of non-GHSA IDs (CVEs, etc.) for the same vulnerability. GraphQL
+ *    has `identifiers: [{type, value}]` which INCLUDES the advisory's own GHSA
+ *    id alongside CVE ids. We filter out the GHSA self-reference so the list
+ *    matches REST.
+ * 3. Connection wrapping GraphQL wraps array fields in `{ nodes: [...] }`
+ *    connection objects (it's how pagination works in GraphQL). REST returns
+ *    plain arrays. We unwrap with `?.nodes ?? []`.
+ *
+ * `description` (GraphQL) maps to `details` (REST) — same data, different field
+ * name. The mapping below renames it.
+ *
+ * Token handling: We re-derive the token from `options.token ||
+ * getGitHubToken()` because this function may be called from places that didn't
+ * thread an explicit token through. GraphQL queries to private data require
+ * auth even when the equivalent REST GET works anonymously, so the auth header
+ * is mandatory in practice.
+ */
+export declare function fetchGhsaDetailsViaGraphQL(ghsaId: string, options?: GitHubFetchOptions | undefined): Promise<GhsaDetails>;