github.ts

import { Octokit } from '@octokit/rest'
import childProcess from 'child_process'
import { promisify } from 'util'
import { saveCachedData } from './cache'
import { isExcludedContributor } from './config'
import { Repo, Stat, Week } from './types'

const execFile = promisify(childProcess.execFile)

// Minimal structural client shape so tests can inject a fake without depending
// on the full Octokit type.
export interface StatsResponse {
  status: number
  data: unknown
}

export interface RequestSignal {
  request?: { signal?: AbortSignal }
}

export interface OctokitLike {
  rest: {
    repos: {
      getContributorsStats: (args: {
        owner: string
        repo: string
      } & RequestSignal) => Promise<StatsResponse>
      listForOrg: unknown
    }
    users: {
      getByUsername: (args: {
        username: string
      } & RequestSignal) => Promise<{ data: unknown }>
      getById: (args: {
        account_id: number
      } & RequestSignal) => Promise<{ data: unknown }>
    }
  }
  paginate: (method: unknown, args: unknown) => Promise<unknown[]>
}

// Resolve a token lazily. Environment tokens take priority so CI (which sets
// GITHUB_TOKEN/GH_TOKEN) never shells out. The local `gh` fallback is only
// attempted when both environment variables are absent.
export const resolveToken = async (): Promise<string | undefined> => {
  const envToken = (process.env.GH_TOKEN || process.env.GITHUB_TOKEN || '').trim()
  if (envToken) {
    return envToken
  }

  try {
    const { stdout } = await execFile('gh', ['auth', 'token'])
    const token = stdout.trim()
    return token || undefined
  } catch {
    return undefined
  }
}

let octokitPromise: Promise<Octokit> | undefined

export const getOctokit = (): Promise<Octokit> => {
  if (!octokitPromise) {
    octokitPromise = resolveToken().then(
      token => new Octokit(token ? { auth: token } : {}),
    )
  }
  return octokitPromise
}

const asClient = async (octokit?: OctokitLike): Promise<OctokitLike> => {
  if (octokit) {
    return octokit
  }
  return (await getOctokit()) as unknown as OctokitLike
}

const isRecord = (value: unknown): value is Record<string, unknown> =>
  typeof value === 'object' && value !== null

const isFiniteNonNegative = (value: unknown): value is number =>
  typeof value === 'number' && Number.isFinite(value) && value >= 0

const isValidWeek = (value: unknown): value is Week =>
  isRecord(value) &&
  isFiniteNonNegative(value.w) &&
  isFiniteNonNegative(value.a) &&
  isFiniteNonNegative(value.d) &&
  isFiniteNonNegative(value.c)

// A payload that does not match the documented stats shape is not a transient
// network problem, so it must never be retried or allowed to overwrite a valid
// historical archive.
export class MalformedPayloadError extends Error {
  constructor(message: string) {
    super(message)
    this.name = 'MalformedPayloadError'
  }
}

// Validate the raw stats payload at the API boundary before it is trusted or
// archived. GitHub returns HTTP 202 with an empty object while stats are still
// being computed; that is handled by the retry loop, not here.
export const isValidStat = (value: unknown): value is Stat => {
  if (!isRecord(value)) {
    return false
  }
  if (!isFiniteNonNegative(value.total) || !Array.isArray(value.weeks)) {
    return false
  }
  if (!value.weeks.every(isValidWeek)) {
    return false
  }
  const author = value.author
  if (author === null) {
    return true
  }
  return (
    isRecord(author) &&
    typeof author.login === 'string' &&
    author.login.trim().length > 0
  )
}

export const validateContributorsPayload = (data: unknown): Stat[] => {
  if (!Array.isArray(data)) {
    throw new MalformedPayloadError('Malformed contributors payload: expected an array')
  }
  const invalidIndex = data.findIndex(entry => !isValidStat(entry))
  if (invalidIndex >= 0) {
    throw new MalformedPayloadError(
      `Malformed contributors payload: invalid entry at index ${invalidIndex}`,
    )
  }
  return data as Stat[]
}

export interface RetryConfig {
  retries: number
  minTimeout: number
  maxTimeout: number
  factor: number
  totalBudgetMs: number
  requestTimeoutMs: number
  sleep: (ms: number) => Promise<void>
  now: () => number
}

// Tuned for a daily refresh: a handful of quick retries within a small per-repo
// budget. GitHub 202 (stats still computing) is expected to recover across
// scheduled runs, so there is no point in blocking a single build for long.
export const defaultRetryConfig: RetryConfig = {
  retries: 4,
  minTimeout: 3000,
  maxTimeout: 15000,
  factor: 2,
  totalBudgetMs: 60 * 1000,
  requestTimeoutMs: 30 * 1000,
  sleep: ms =>
    new Promise(resolve => {
      setTimeout(resolve, ms)
    }),
  now: () => Date.now(),
}

const getStatus = (error: unknown): number | undefined => {
  const err = error as { status?: number; response?: { status?: number } }
  return err?.status ?? err?.response?.status
}

const getHeaders = (
  error: unknown,
): Record<string, string | number | undefined> | undefined => {
  const err = error as {
    response?: { headers?: Record<string, string | number | undefined> }
    headers?: Record<string, string | number | undefined>
  }
  return err?.response?.headers ?? err?.headers
}

// Decide whether an API error is worth retrying. 202 means stats are still
// being computed; 403/429 and 5xx/network errors are transient (rate limits
// and outages). 404/401/422 and malformed payloads are not retried.
export const isRetryableGithubError = (error: unknown): boolean => {
  if (error instanceof MalformedPayloadError) {
    return false
  }
  const status = getStatus(error)
  if (status === undefined) {
    return true
  }
  if (status === 202 || status === 403 || status === 408 || status === 429) {
    return true
  }
  return status >= 500
}

// Honor Retry-After (seconds or HTTP date) and X-RateLimit-Reset (epoch
// seconds) when present, otherwise fall back to exponential backoff.
export const getRetryDelayMs = (
  error: unknown,
  attempt: number,
  config: RetryConfig,
): number | undefined => {
  const headers = getHeaders(error)
  const retryAfter = headers?.['retry-after']
  if (retryAfter !== undefined && retryAfter !== null) {
    const seconds = Number(retryAfter)
    if (Number.isFinite(seconds) && seconds >= 0) {
      return seconds * 1000
    }
    const timestamp = Date.parse(String(retryAfter))
    if (!Number.isNaN(timestamp)) {
      return Math.max(0, timestamp - config.now())
    }
  }

  const reset = headers?.['x-ratelimit-reset']
  if (reset !== undefined && reset !== null) {
    const resetMs = Number(reset) * 1000
    if (Number.isFinite(resetMs)) {
      return Math.max(0, resetMs - config.now())
    }
  }

  return Math.min(config.maxTimeout, config.minTimeout * config.factor ** attempt)
}

// Attach a real AbortSignal to the underlying request so a timeout actually
// cancels the in-flight HTTP call instead of merely racing it from the outside.
const withRequestTimeout = async <T>(
  ms: number,
  run: (signal: AbortSignal) => Promise<T>,
): Promise<T> => {
  const controller = new AbortController()
  const timer = setTimeout(() => controller.abort(), ms)
  try {
    return await run(controller.signal)
  } catch (error) {
    if (controller.signal.aborted) {
      throw new Error(`GitHub request timed out after ${ms}ms`)
    }
    throw error
  } finally {
    clearTimeout(timer)
  }
}

// Bounded retry loop. Both the time spent sleeping and the wall-clock elapsed
// time (including request time) are bounded by totalBudgetMs, so a slow or
// hostile server cannot stall a build indefinitely. The callback receives the
// timeout for that attempt, which is capped by the remaining budget so no
// request can outlive the deadline.
export const withBoundedRetry = async <T>(
  fn: (attempt: number, requestTimeoutMs: number) => Promise<T>,
  config: RetryConfig,
  isRetryable: (error: unknown) => boolean = isRetryableGithubError,
): Promise<T> => {
  const startedAt = config.now()
  let attempt = 0

  for (;;) {
    const remaining = config.totalBudgetMs - (config.now() - startedAt)
    if (remaining <= 0) {
      throw new Error(
        `GitHub request budget of ${config.totalBudgetMs}ms exhausted`,
      )
    }
    try {
      return await fn(attempt, Math.min(config.requestTimeoutMs, remaining))
    } catch (error) {
      const elapsed = config.now() - startedAt
      if (
        !isRetryable(error) ||
        attempt >= config.retries ||
        elapsed >= config.totalBudgetMs
      ) {
        throw error
      }
      const delay = getRetryDelayMs(error, attempt, config) ?? 0
      if (elapsed + delay > config.totalBudgetMs) {
        throw error
      }
      await config.sleep(delay)
      attempt += 1
    }
  }
}

const fetchContributorStats = async (
  client: OctokitLike,
  owner: string,
  repo: string,
  requestTimeoutMs: number,
): Promise<Stat[]> => {
  const response = await withRequestTimeout(requestTimeoutMs, signal =>
    client.rest.repos.getContributorsStats({
      owner,
      repo,
      request: { signal },
    }),
  )
  if (response.status === 202) {
    throw Object.assign(new Error('Stats being computed (202)'), { status: 202 })
  }
  return validateContributorsPayload(response.data)
}

export interface GetContributorsOptions {
  octokit?: OctokitLike
  previous?: Stat[] | null
  retry?: Partial<RetryConfig>
  save?: (repoFullName: string, data: Stat[]) => Promise<unknown>
}

// Bots are never trusted, archived, or returned: bot-only activity must not
// churn the archives or published output.
const withoutBots = (stats: Stat[]): Stat[] =>
  stats.filter(entry => !isExcludedContributor(entry.author))

// Stable identity of a stat author: the numeric GitHub account id when known,
// otherwise null. Comparing this first is what makes identity checks immune to
// username reuse and account renames.
const authorAccountId = (author: Stat['author']): number | null => {
  if (!author) {
    return null
  }
  const id = (author as { id?: unknown }).id
  return typeof id === 'number' && Number.isFinite(id) ? id : null
}

// Always refresh from GitHub on a normal build, but never replace valid
// historical data with a failure, empty or malformed response. The previous
// archive (if any) is returned as a fallback, with any legacy bot rows removed.
// Archive persistence failures propagate so the build fails loudly instead of
// pretending success.
export const getContributors = async (
  owner: string,
  repo: string,
  options: GetContributorsOptions = {},
): Promise<Stat[]> => {
  const repoFullName = `${owner}/${repo}`
  const previous = options.previous ?? null
  const client = await asClient(options.octokit)
  const config: RetryConfig = { ...defaultRetryConfig, ...options.retry }
  const save = options.save ?? saveCachedData

  let raw: Stat[]
  try {
    raw = await withBoundedRetry(
      (_attempt, requestTimeoutMs) =>
        fetchContributorStats(client, owner, repo, requestTimeoutMs),
      config,
    )
  } catch (error) {
    console.error(`[ERROR] failed to refresh ${repoFullName}:`, error)
    const fallback = withoutBots(previous ?? [])
    if (fallback.length > 0) {
      console.warn(`⚠️  keeping previous archived stats for ${repoFullName}`)
    }
    return fallback
  }

  // A truly empty payload is treated like a transient failure: keep the last
  // good human archive rather than overwriting it with nothing.
  if (raw.length === 0) {
    console.warn(`⚠️  empty data for ${repoFullName}; keeping previous archive`)
    return withoutBots(previous ?? [])
  }

  const fresh = withoutBots(raw)
  const previouslyKnown = withoutBots(previous ?? [])

  // A valid payload that only contains bots: if we already know humans, keep
  // them (the bot-only payload may be partial), otherwise persist an empty
  // archive so an all-bot repo stops churning and stays stable.
  if (fresh.length === 0) {
    if (previouslyKnown.length > 0) {
      console.warn(
        `⚠️  ${repoFullName}: fresh data had no human contributors; keeping previous archive`,
      )
      return previouslyKnown
    }
    await save(repoFullName, [])
    console.info(
      `✅ Refreshed 0 human contributors for ${repoFullName} (bots excluded)`,
    )
    return []
  }

  // Reconcile per identity against the previous archive. Match by stable
  // numeric ID whenever the previous row has one, otherwise by case-insensitive
  // login (legacy rows without IDs only). A same-ID rename or updated stats
  // supersede the previous row. A previous human missing from fresh data is
  // retained. A fresh row reusing that human's login with an ID that was not
  // previously known (including a missing ID when the previous ID is known) is a
  // misattributed replacement and is dropped, even when the original ID also
  // reappears under a renamed login; a previously known ID taking over the login
  // is a legitimate rename and is allowed.
  // Every archived login pinned to the ID(s) previously recorded for it, plus
  // the set of all archived IDs (globally known identities).
  const previousIds = new Set<number>()
  const previousPinnedByLogin = new Map<string, Set<number>>()
  for (const stat of previouslyKnown) {
    const author = stat.author
    if (!author) {
      continue
    }
    const id = authorAccountId(author)
    if (id === null) {
      continue
    }
    previousIds.add(id)
    const loginKey = author.login.toLowerCase()
    const pinned = previousPinnedByLogin.get(loginKey)
    if (pinned) {
      pinned.add(id)
    } else {
      previousPinnedByLogin.set(loginKey, new Set([id]))
    }
  }

  // A fresh row is a misattributed claimant when it reuses a login previously
  // pinned to a different identity and its own ID is neither that pinned ID nor
  // any other previously known ID. Deciding per row (not per login) keeps the
  // result independent of fresh row order and never drops a trusted row that
  // shares its login with a claimant.
  const isConflictingClaimant = (stat: Stat): boolean => {
    const author = stat.author
    if (!author) {
      return false
    }
    const pinned = previousPinnedByLogin.get(author.login.toLowerCase())
    if (!pinned) {
      return false
    }
    const id = authorAccountId(author)
    if (id !== null && (pinned.has(id) || previousIds.has(id))) {
      return false
    }
    return true
  }

  const accepted = fresh.filter(stat => !isConflictingClaimant(stat))
  const droppedClaimants = fresh.filter(isConflictingClaimant)

  // Retain an archived identity only when no accepted fresh row accounts for it.
  const acceptedIds = new Set<number>()
  const acceptedLogins = new Set<string>()
  for (const stat of accepted) {
    const author = stat.author
    if (!author) {
      continue
    }
    const id = authorAccountId(author)
    if (id !== null) {
      acceptedIds.add(id)
    }
    acceptedLogins.add(author.login.toLowerCase())
  }

  const retained: Stat[] = []
  for (const stat of previouslyKnown) {
    const author = stat.author
    if (!author) {
      continue
    }
    const id = authorAccountId(author)
    if (id !== null) {
      if (!acceptedIds.has(id)) {
        retained.push(stat)
      }
    } else if (!acceptedLogins.has(author.login.toLowerCase())) {
      retained.push(stat)
    }
  }

  if (droppedClaimants.length > 0) {
    console.warn(
      `⚠️  ${repoFullName}: fresh data reused login(s) with a different identity (${droppedClaimants
        .map(stat => stat.author!.login)
        .join(', ')}); dropped the fresh claimant and kept the archived identity`,
    )
  }
  if (retained.length > 0) {
    console.warn(
      `⚠️  ${repoFullName}: retaining ${retained.length} archived contributor row(s) missing from fresh data (${retained
        .map(stat => stat.author!.login)
        .join(', ')})`,
    )
  }

  const hasNullAuthors = fresh.some(stat => !stat.author)
  if (hasNullAuthors) {
    console.warn(
      `⚠️  ${repoFullName}: ${fresh.filter(stat => !stat.author).length}/${
        fresh.length
      } contributors have null author (skipped when aggregating)`,
    )
  }

  const reconciled = [...accepted, ...retained]
  await save(repoFullName, reconciled)
  console.info(
    `✅ Refreshed ${accepted.length} contributors for ${repoFullName}` +
      (retained.length > 0 ? ` (retained ${retained.length} archived)` : ''),
  )
  return reconciled
}

export const getRepos = async (octokit?: OctokitLike): Promise<Repo[]> => {
  const client = await asClient(octokit)
  const repos = await withRequestTimeout(
    defaultRetryConfig.requestTimeoutMs,
    signal =>
      client.paginate(client.rest.repos.listForOrg, {
        org: 'poooi',
        per_page: 100,
        request: { signal },
      }),
  )
  return repos as Repo[]
}

// Profile lookups run once per contributor and are best-effort, so they get a
// short timeout: a widespread outage must not let them dominate the job budget.
export const USER_REQUEST_TIMEOUT_MS = 5_000

export const getUser = async (
  login: string,
  octokit?: OctokitLike,
): Promise<Record<string, unknown> | null> => {
  const client = await asClient(octokit)
  try {
    const response = await withRequestTimeout(
      USER_REQUEST_TIMEOUT_MS,
      signal =>
        client.rest.users.getByUsername({
          username: login,
          request: { signal },
        }),
    )
    return (response.data as Record<string, unknown>) ?? null
  } catch (error) {
    if (getStatus(error) === 404) {
      return null
    }
    throw error
  }
}

// Look an account up by its stable numeric ID (`GET /user/{account_id}`). A 404
// returns null: the account is not found/unavailable, which may indicate
// deletion but is not definitive proof of it. Timeouts, rate limits and 5xx are
// transient failures and throw, so the caller never mistakes an outage for a
// deletion and can retry on a future build.
export const getUserById = async (
  accountId: number,
  octokit?: OctokitLike,
): Promise<Record<string, unknown> | null> => {
  const client = await asClient(octokit)
  try {
    const response = await withRequestTimeout(
      USER_REQUEST_TIMEOUT_MS,
      signal =>
        client.rest.users.getById({
          account_id: accountId,
          request: { signal },
        }),
    )
    return (response.data as Record<string, unknown>) ?? null
  } catch (error) {
    if (getStatus(error) === 404) {
      return null
    }
    throw error
  }
}