types.ts

/**
 * @file Public type surface for `github/*` modules — pure interfaces. No I/O or
 *   runtime side effects so this module stays cheap to import everywhere.
 *   Constants live in `./constants`, named errors in `./errors`.
 */

/**
 * Options for GitHub API fetch requests.
 */
export interface GitHubFetchOptions {
  /**
   * GitHub authentication token. If not provided, will attempt to use token
   * from environment variables.
   */
  token?: string | undefined
  /**
   * Additional HTTP headers to include in the request. Will be merged with
   * default headers (Accept, User-Agent, Authorization).
   */
  headers?: Record<string, string> | undefined
}

/**
 * Error thrown when GitHub API rate limit is exceeded. Extends the standard
 * Error with additional rate limit information.
 */
export interface GitHubRateLimitError extends Error {
  /**
   * HTTP status code (always 403 for rate limit errors)
   */
  status: number
  /**
   * Date when the rate limit will reset. Undefined if reset time is not
   * available in response headers.
   */
  resetTime?: Date | undefined
}

/**
 * GitHub ref object returned by the API. Represents a git reference (tag or
 * branch).
 */
export interface GitHubRef {
  /**
   * The object this ref points to.
   */
  object: {
    /**
     * SHA of the commit or tag object.
     */
    sha: string
    /**
     * Type of object ('commit' or 'tag')
     */
    type: string
    /**
     * API URL to fetch the full object details.
     */
    url: string
  }
  /**
   * Full ref path (e.g., 'refs/tags/v1.0.0' or 'refs/heads/main')
   */
  ref: string
  /**
   * API URL for this ref.
   */
  url: string
}

/**
 * GitHub annotated tag object returned by the API. Represents a git tag with
 * metadata.
 */
export interface GitHubTag {
  /**
   * Tag annotation message.
   */
  message: string
  /**
   * The commit this tag points to.
   */
  object: {
    /**
     * SHA of the commit.
     */
    sha: string
    /**
     * Type of object (usually 'commit')
     */
    type: string
    /**
     * API URL to fetch the commit details.
     */
    url: string
  }
  /**
   * SHA of this tag object itself.
   */
  sha: string
  /**
   * Tag name (e.g., 'v1.0.0')
   */
  tag: string
  /**
   * Information about who created the tag. Undefined for lightweight tags.
   */
  tagger?: {
    /**
     * Tag creation date in ISO 8601 format.
     */
    date: string
    /**
     * Tagger's email address.
     */
    email: string
    /**
     * Tagger's name.
     */
    name: string
  }
  /**
   * API URL for this tag object.
   */
  url: string
}

/**
 * GitHub commit object returned by the API. Represents a git commit with
 * metadata.
 */
export interface GitHubCommit {
  /**
   * Full commit SHA.
   */
  sha: string
  /**
   * API URL for this commit.
   */
  url: string
  /**
   * Commit details.
   */
  commit: {
    /**
     * Commit message.
     */
    message: string
    /**
     * Author information.
     */
    author: {
      /**
       * Commit author date in ISO 8601 format.
       */
      date: string
      /**
       * Author's email address.
       */
      email: string
      /**
       * Author's name.
       */
      name: string
    }
  }
}

/**
 * Options for resolving git refs to commit SHAs.
 */
export interface ResolveRefOptions {
  /**
   * GitHub authentication token. If not provided, will attempt to use token
   * from environment variables.
   */
  token?: string | undefined
}

/**
 * GitHub Security Advisory (GHSA) details. Represents a complete security
 * advisory from GitHub's database.
 */
export interface GhsaDetails {
  /**
   * GHSA identifier (e.g., 'GHSA-xxxx-yyyy-zzzz')
   */
  ghsaId: string
  /**
   * Short summary of the vulnerability.
   */
  summary: string
  /**
   * Detailed description of the vulnerability.
   */
  details: string
  /**
   * Severity level ('low', 'moderate', 'high', 'critical')
   */
  severity: string
  /**
   * Alternative identifiers (CVE IDs, etc.)
   */
  aliases: string[]
  /**
   * ISO 8601 timestamp when advisory was published.
   */
  publishedAt: string
  /**
   * ISO 8601 timestamp when advisory was last updated.
   */
  updatedAt: string
  /**
   * ISO 8601 timestamp when advisory was withdrawn. `null` if advisory is still
   * active.
   */
  withdrawnAt: string | null
  /**
   * External reference URLs for more information.
   */
  references: Array<{ url: string }>
  /**
   * Affected packages and version ranges.
   */
  vulnerabilities: Array<{
    /**
     * Package information.
     */
    package: {
      /**
       * Ecosystem (e.g., 'npm', 'pip', 'maven')
       */
      ecosystem: string
      /**
       * Package name.
       */
      name: string
    }
    /**
     * Version range expression for vulnerable versions.
     */
    vulnerableVersionRange: string
    /**
     * First patched version that fixes the vulnerability. `null` if no patched
     * version exists yet.
     */
    firstPatchedVersion: { identifier: string } | null
  }>
  /**
   * CVSS (Common Vulnerability Scoring System) information. `null` if CVSS
   * score is not available.
   */
  cvss: {
    /**
     * CVSS score (0.0-10.0)
     */
    score: number
    /**
     * CVSS vector string describing the vulnerability characteristics.
     */
    vectorString: string
  } | null
  /**
   * CWE (Common Weakness Enumeration) categories.
   */
  cwes: Array<{
    /**
     * CWE identifier (e.g., 'CWE-79')
     */
    cweId: string
    /**
     * Human-readable CWE name.
     */
    name: string
    /**
     * Description of the weakness category.
     */
    description: string
  }>
}