orca/src/shared/loose-ref-count.ts

import { readdir } from 'node:fs/promises'
import { join } from 'node:path'

export type LooseRefCount = {
  /** Loose ref files seen, never above `budget`. */
  count: number
  /** The walk stopped early, so `count` is a floor rather than the total. */
  saturated: boolean
}

// Why: a ref tree is shallow and wide; this bounds both the directories visited
// and the queue holding those still to visit, so neither a symlink loop nor a
// pathological repo turns a gate probe into an unbounded walk.
const DIRECTORY_VISIT_CEILING = 4096

/**
 * Count loose refs under a repository's `refs/` directory, stopping at `budget`.
 *
 * Deliberately budgeted: callers use this as an admission gate, so the cost has
 * to be bounded by the threshold being tested and not by the size of the
 * backlog it is testing for.
 *
 * One `readdir` per directory, dirents only -- no `stat` per entry, and no
 * `opendir` streaming. Measured against a real 36,600-loose-ref repository, the
 * batched form is ~8x faster (23ms vs 177ms median to reach a 1000 threshold)
 * and holds the event loop for less than half as long, because streaming issues
 * a thread-pool round trip every 32 entries where this issues one per
 * directory. The cost is holding one directory's dirents at a time, which is
 * bounded by the widest ref namespace rather than by the size of the tree.
 *
 * Strictly sequential on purpose: it awaits one directory before opening the
 * next, so it can never occupy more than one of libuv's four thread-pool slots
 * and cannot stall unrelated main-process filesystem work.
 *
 * `signal` stops the walk between directories. A single hung `readdir` is not
 * interruptible, but it holds no Git lock, so it delays only maintenance.
 */
export async function countLooseRefs(
  refsDirectory: string,
  budget: number,
  signal?: AbortSignal
): Promise<LooseRefCount> {
  const pending = [refsDirectory]
  let count = 0
  let visited = 0
  while (pending.length > 0) {
    const directory = pending.pop()
    if (directory === undefined) {
      break
    }
    visited += 1
    // A cancelled walk reports what it saw as a floor rather than throwing; callers
    // already have to treat a saturated result as "not known to be clean".
    if (
      signal?.aborted === true ||
      visited > DIRECTORY_VISIT_CEILING ||
      pending.length > DIRECTORY_VISIT_CEILING
    ) {
      return { count, saturated: true }
    }
    let entries: { name: string; isDirectory: () => boolean }[]
    try {
      entries = await readdir(directory, { withFileTypes: true })
    } catch {
      // A missing or unreadable namespace contributes nothing to the count.
      continue
    }
    for (const entry of entries) {
      if (entry.isDirectory()) {
        pending.push(join(directory, entry.name))
        continue
      }
      count += 1
      if (count >= budget) {
        return { count, saturated: true }
      }
    }
  }
  return { count, saturated: false }
}