@yoavsh/treekeeper 0.0.0-stage → 0.1.0

package/src/core/decide.ts

@@ -0,0 +1,230 @@
+import type { DirtyPolicy } from "./config.js";
+import type { PrRef } from "./forge.js";
+import { formatAgo, formatDuration } from "../util/time.js";
+
+/** How the work on a branch relates to the default branch and its pull request. */
+export type MergeStatus =
+  | { kind: "merged-ancestor"; base: string }
+  | { kind: "merged-pr"; pr: PrRef }
+  | { kind: "merged-pr-extra"; pr: PrRef; extra: number }
+  | { kind: "closed-pr"; pr: PrRef }
+  | { kind: "open-pr"; pr: PrRef }
+  | { kind: "unmerged"; forgeAvailable: boolean }
+  | { kind: "no-branch" };
+
+export type Risk = "dirty" | "closed-pr" | "extra-commits";
+
+export interface Verdict {
+  action: "reclaim" | "keep";
+  /** Human sentence shown in the plan and written to the log. */
+  reason: string;
+  /** Stable identifier for scripts reading `--json`. */
+  code: string;
+  /** Why this removal needs an archive first. Empty when the work is safely merged. */
+  risks: Risk[];
+}
+
+export interface Policy {
+  minAgeMs: number;
+  closedPrGraceMs: number;
+  onDirty: DirtyPolicy;
+  onClosedPr: DirtyPolicy;
+  onExtraCommits: DirtyPolicy;
+  /** Bypasses the age gate and the dirty / extra-commits / closed-PR holds. */
+  force: boolean;
+}
+
+export interface WorktreeFacts {
+  now: number;
+  isMain: boolean;
+  detached: boolean;
+  locked: boolean;
+  lockReason: string | null;
+  branch: string | null;
+  protectedBranch: boolean;
+  protectedPath: boolean;
+  /** The worktree contains the caller's working directory. */
+  isCwd: boolean;
+  merge: MergeStatus;
+  dirty: boolean;
+  dirtyCount: number;
+  /** Most recent agent/human activity, or null when nothing was detected. */
+  activity: { detector: string; lastActivity: number; detail: string } | null;
+  activityIsRecent: boolean;
+  /** Newest mtime seen for this worktree, used for the age gate. */
+  lastTouched: number;
+  inUse: boolean;
+}
+
+const keep = (code: string, reason: string): Verdict => ({ action: "keep", reason, code, risks: [] });
+
+/**
+ * Decide the fate of one worktree.
+ *
+ * Pure on purpose: every signal is gathered elsewhere, so the rules that decide
+ * whether a developer's directory gets deleted are a single readable function
+ * with a truth table in the tests.
+ *
+ * Invariant: a worktree is only ever reclaimed when its commits are reachable
+ * from the default branch, or its pull request was merged or closed. `force`
+ * does not relax that.
+ */
+export function decideWorktree(f: WorktreeFacts, policy: Policy): Verdict {
+  if (f.isMain) return keep("main-worktree", "the repo's main worktree");
+  if (f.protectedPath) return keep("protected-path", "matches protectPaths");
+  if (f.isCwd) return keep("cwd", "your current working directory");
+  if (f.locked) {
+    return keep("locked", `locked${f.lockReason ? `: ${f.lockReason}` : ""}`);
+  }
+  if (f.detached || !f.branch) return keep("detached", "detached HEAD — no branch to check");
+  if (f.protectedBranch) return keep("protected-branch", `${f.branch} matches protectBranches`);
+
+  const risks: Risk[] = [];
+  let mergedReason: string;
+
+  switch (f.merge.kind) {
+    case "merged-ancestor":
+      mergedReason = `merged into ${f.merge.base}`;
+      break;
+    case "merged-pr":
+      mergedReason = `PR #${f.merge.pr.number} merged`;
+      break;
+    case "merged-pr-extra": {
+      const n = f.merge.extra;
+      const detail = `PR #${f.merge.pr.number} merged, but the local branch has ${n} commit${n === 1 ? "" : "s"} the PR never had`;
+      if (policy.onExtraCommits === "keep" && !policy.force) {
+        return keep("extra-commits", detail);
+      }
+      risks.push("extra-commits");
+      mergedReason = detail;
+      break;
+    }
+    case "closed-pr": {
+      const detail = `PR #${f.merge.pr.number} closed without merging`;
+      if (policy.onClosedPr === "keep" && !policy.force) {
+        return keep("closed-pr", `${detail} — onClosedPr is "keep"`);
+      }
+      const closedAt = f.merge.pr.closedAt;
+      if (!policy.force && closedAt !== null) {
+        const waited = f.now - closedAt;
+        if (waited < policy.closedPrGraceMs) {
+          return keep(
+            "closed-pr-grace",
+            `${detail} ${formatAgo(closedAt, f.now)} — holding for ${formatDuration(policy.closedPrGraceMs - waited)} more`,
+          );
+        }
+      }
+      risks.push("closed-pr");
+      mergedReason = detail;
+      break;
+    }
+    case "open-pr":
+      return keep("open-pr", `PR #${f.merge.pr.number} is still open`);
+    case "unmerged":
+      return keep(
+        "unmerged",
+        f.merge.forgeAvailable
+          ? "not merged and has no merged pull request"
+          : "not merged (no pull-request data available)",
+      );
+    case "no-branch":
+      return keep("no-branch", "no branch to check");
+  }
+
+  // Work is finished. Now the "is anyone still using it" gates.
+  // A live process is checked first because it is the least ambiguous signal
+  // and deserves the clearest message.
+  if (f.inUse) {
+    return keep("in-use", `${mergedReason}, but a running process is still in it`);
+  }
+  if (f.activityIsRecent && f.activity) {
+    return keep(
+      "session-active",
+      `${mergedReason}, but ${f.activity.detector} activity ${formatAgo(f.activity.lastActivity, f.now)}`,
+    );
+  }
+
+  if (!policy.force) {
+    // Clamped: file mtimes carry sub-millisecond fractions while Date.now()
+    // truncates, so a worktree touched this instant can otherwise look like it
+    // was touched in the future.
+    const age = Math.max(0, f.now - f.lastTouched);
+    if (age < policy.minAgeMs) {
+      return keep(
+        "too-young",
+        `${mergedReason}, but touched ${formatAgo(f.lastTouched, f.now)} (minAge ${formatDuration(policy.minAgeMs)})`,
+      );
+    }
+  }
+
+  if (f.dirty) {
+    if (policy.onDirty === "keep" && !policy.force) {
+      return keep(
+        "dirty",
+        `${mergedReason}, but has ${f.dirtyCount} uncommitted change${f.dirtyCount === 1 ? "" : "s"}`,
+      );
+    }
+    risks.push("dirty");
+  }
+
+  return {
+    action: "reclaim",
+    reason: mergedReason,
+    code: f.merge.kind,
+    risks,
+  };
+}
+
+export interface BranchFacts {
+  now: number;
+  name: string;
+  isDefault: boolean;
+  protectedBranch: boolean;
+  /** A worktree still has this branch checked out. */
+  hasWorktree: boolean;
+  /** This branch is the current HEAD of the main worktree. */
+  isCurrent: boolean;
+  merge: MergeStatus;
+  lastCommit: number | null;
+}
+
+/**
+ * Decide whether a local branch with no worktree should be deleted.
+ *
+ * Deleting a branch only drops a pointer, so this is cheaper to get wrong than
+ * a worktree — but it can still orphan commits, so unmerged branches are never
+ * touched and closed-PR branches get archived like worktrees do.
+ */
+export function decideBranch(f: BranchFacts, policy: Policy): Verdict {
+  if (f.isDefault) return keep("default-branch", "the default branch");
+  if (f.isCurrent) return keep("current-branch", "currently checked out");
+  if (f.protectedBranch) return keep("protected-branch", "matches protectBranches");
+  if (f.hasWorktree) return keep("has-worktree", "still checked out in a worktree");
+
+  switch (f.merge.kind) {
+    case "merged-ancestor":
+      return { action: "reclaim", reason: `merged into ${f.merge.base}`, code: f.merge.kind, risks: [] };
+    case "merged-pr":
+      return { action: "reclaim", reason: `PR #${f.merge.pr.number} merged`, code: f.merge.kind, risks: [] };
+    case "merged-pr-extra": {
+      const detail = `PR #${f.merge.pr.number} merged, local tip has ${f.merge.extra} extra commit(s)`;
+      if (policy.onExtraCommits === "keep" && !policy.force) return keep("extra-commits", detail);
+      return { action: "reclaim", reason: detail, code: f.merge.kind, risks: ["extra-commits"] };
+    }
+    case "closed-pr": {
+      const detail = `PR #${f.merge.pr.number} closed without merging`;
+      if (policy.onClosedPr === "keep" && !policy.force) return keep("closed-pr", detail);
+      const closedAt = f.merge.pr.closedAt;
+      if (!policy.force && closedAt !== null && f.now - closedAt < policy.closedPrGraceMs) {
+        return keep("closed-pr-grace", `${detail} ${formatAgo(closedAt, f.now)} — still in the grace window`);
+      }
+      return { action: "reclaim", reason: detail, code: f.merge.kind, risks: ["closed-pr"] };
+    }
+    case "open-pr":
+      return keep("open-pr", `PR #${f.merge.pr.number} is still open`);
+    case "unmerged":
+      return keep("unmerged", "not merged");
+    case "no-branch":
+      return keep("no-branch", "no branch");
+  }
+}

package/src/core/forge.ts

@@ -0,0 +1,243 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { have, run } from "../util/exec.js";
+import type { Logger } from "../util/log.js";
+import { treekeeperHome } from "../util/paths.js";
+import { redactRemote } from "../util/redact.js";
+import { parseDuration } from "../util/time.js";
+import { originUrl } from "./git.js";
+
+export type PrState = "OPEN" | "MERGED" | "CLOSED";
+
+export interface PrRef {
+  number: number;
+  state: PrState;
+  headRefName: string;
+  headRefOid: string;
+  mergedAt: number | null;
+  closedAt: number | null;
+  url: string;
+  title: string;
+}
+
+/** Pull requests for a repo, keyed by head branch name. */
+export type PrIndex = Map<string, PrRef[]>;
+
+export interface Forge {
+  readonly kind: string;
+  /**
+   * `null` means "no information available" (no remote, no CLI, offline) which
+   * callers must treat as "unknown", never as "no PR exists".
+   */
+  lookup(repo: string): Promise<PrIndex | null>;
+  readonly unavailableReason: string | null;
+}
+
+export interface ForgeOptions {
+  kind: "github" | "none";
+  cacheTtl: string;
+  logger?: Logger;
+  /** Ignore cached answers (used by `--refresh`). */
+  refresh?: boolean;
+  limit?: number;
+}
+
+export function createForge(opts: ForgeOptions): Forge {
+  // Not a problem worth warning about: the repo header already shows that a
+  // sweep ran without pull-request data.
+  if (opts.kind === "none") return new NullForge(null);
+  return new GitHubForge(opts);
+}
+
+class NullForge implements Forge {
+  readonly kind = "none";
+  readonly unavailableReason: string | null;
+  constructor(reason: string | null) {
+    this.unavailableReason = reason;
+  }
+  async lookup(): Promise<PrIndex | null> {
+    return null;
+  }
+}
+
+interface CacheFile {
+  version: 1;
+  fetchedAt: number;
+  remote: string;
+  prs: PrRef[];
+}
+
+class GitHubForge implements Forge {
+  readonly kind = "github";
+  unavailableReason: string | null = null;
+  private readonly ttlMs: number;
+  private readonly memo = new Map<string, PrIndex | null>();
+  private ghChecked = false;
+
+  constructor(private readonly opts: ForgeOptions) {
+    this.ttlMs = parseDuration(opts.cacheTtl);
+  }
+
+  async lookup(repo: string): Promise<PrIndex | null> {
+    if (this.memo.has(repo)) return this.memo.get(repo)!;
+    const result = await this.fetch(repo);
+    this.memo.set(repo, result);
+    return result;
+  }
+
+  private async fetch(repo: string): Promise<PrIndex | null> {
+    const remote = await originUrl(repo);
+    if (!remote) {
+      this.opts.logger?.debug(`forge: ${repo} has no origin remote`);
+      return null;
+    }
+    if (!isGitHubRemote(remote)) {
+      this.opts.logger?.debug(`forge: ${redactRemote(remote)} is not a github remote`);
+      return null;
+    }
+
+    const cachePath = join(treekeeperHome(), "cache", `gh-${hash(remote)}.json`);
+    if (!this.opts.refresh) {
+      const cached = await readCache(cachePath);
+      if (cached && Date.now() - cached.fetchedAt < this.ttlMs) {
+        this.opts.logger?.debug(`forge: cache hit for ${redactRemote(remote)}`);
+        return index(cached.prs);
+      }
+    }
+
+    if (!this.ghChecked) {
+      this.ghChecked = true;
+      if (!(await have("gh"))) {
+        this.unavailableReason =
+          "the GitHub CLI (gh) is not installed, so squash-merged branches cannot be detected";
+        this.opts.logger?.warn(this.unavailableReason);
+      }
+    }
+    if (this.unavailableReason) {
+      const cached = await readCache(cachePath);
+      return cached ? index(cached.prs) : null;
+    }
+
+    const r = await run(
+      "gh",
+      [
+        "pr", "list",
+        "--repo", remote,
+        "--state", "all",
+        "--limit", String(this.opts.limit ?? 300),
+        "--json", "number,state,headRefName,headRefOid,mergedAt,closedAt,url,title",
+      ],
+      { timeoutMs: 60_000 },
+    );
+
+    if (r.code !== 0) {
+      const detail = (r.stderr || r.stdout).trim().split("\n")[0] ?? "unknown error";
+      this.opts.logger?.warn(`forge: gh pr list failed for ${redactRemote(remote)}: ${detail}`);
+      // Stale data beats no data: ancestry alone misses squash merges, and a
+      // missing PR record can only ever make treekeeper *more* conservative.
+      const cached = await readCache(cachePath);
+      return cached ? index(cached.prs) : null;
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(r.stdout);
+    } catch {
+      this.opts.logger?.warn(`forge: could not parse gh output for ${redactRemote(remote)}`);
+      return null;
+    }
+    if (!Array.isArray(parsed)) return null;
+
+    const prs = parsed.flatMap((item) => (isPrLike(item) ? [toPrRef(item)] : []));
+    await writeCache(cachePath, { version: 1, fetchedAt: Date.now(), remote: redactRemote(remote), prs });
+    this.opts.logger?.debug(`forge: fetched ${prs.length} PRs for ${redactRemote(remote)}`);
+    return index(prs);
+  }
+}
+
+function index(prs: PrRef[]): PrIndex {
+  const map: PrIndex = new Map();
+  for (const pr of prs) {
+    const list = map.get(pr.headRefName);
+    if (list) list.push(pr);
+    else map.set(pr.headRefName, [pr]);
+  }
+  for (const list of map.values()) list.sort((a, b) => b.number - a.number);
+  return map;
+}
+
+/**
+ * Pick the PR that decides a branch's fate. A branch name can be reused across
+ * several PRs, so prefer a merged PR whose head sha still matches the local tip,
+ * then any merged PR, then the newest.
+ */
+export function selectPr(prs: readonly PrRef[] | undefined, localTip: string | null): PrRef | null {
+  if (!prs || prs.length === 0) return null;
+  if (localTip) {
+    const exact = prs.find((p) => p.headRefOid === localTip && p.state === "MERGED");
+    if (exact) return exact;
+  }
+  const merged = prs.find((p) => p.state === "MERGED");
+  if (merged) return merged;
+  const open = prs.find((p) => p.state === "OPEN");
+  if (open) return open;
+  return prs[0] ?? null;
+}
+
+function isGitHubRemote(remote: string): boolean {
+  return /github\.com/i.test(remote) || /^git@github\.com/i.test(remote);
+}
+
+function hash(s: string): string {
+  return createHash("sha1").update(s).digest("hex").slice(0, 16);
+}
+
+async function readCache(path: string): Promise<CacheFile | null> {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(path, "utf8"));
+    if (
+      parsed !== null && typeof parsed === "object" &&
+      (parsed as CacheFile).version === 1 && Array.isArray((parsed as CacheFile).prs)
+    ) {
+      return parsed as CacheFile;
+    }
+  } catch {
+    /* no usable cache */
+  }
+  return null;
+}
+
+async function writeCache(path: string, data: CacheFile): Promise<void> {
+  try {
+    await mkdir(join(path, ".."), { recursive: true });
+    await writeFile(path, JSON.stringify(data));
+  } catch {
+    /* a cache that cannot be written is not an error */
+  }
+}
+
+function isPrLike(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === "object" && typeof (v as Record<string, unknown>)["number"] === "number";
+}
+
+function toPrRef(item: Record<string, unknown>): PrRef {
+  const stateRaw = String(item["state"] ?? "").toUpperCase();
+  const state: PrState = stateRaw === "MERGED" || stateRaw === "CLOSED" ? stateRaw : "OPEN";
+  return {
+    number: Number(item["number"]),
+    state,
+    headRefName: String(item["headRefName"] ?? ""),
+    headRefOid: String(item["headRefOid"] ?? ""),
+    mergedAt: toEpoch(item["mergedAt"]),
+    closedAt: toEpoch(item["closedAt"]),
+    url: String(item["url"] ?? ""),
+    title: String(item["title"] ?? ""),
+  };
+}
+
+function toEpoch(v: unknown): number | null {
+  if (typeof v !== "string" || v === "") return null;
+  const t = Date.parse(v);
+  return Number.isFinite(t) ? t : null;
+}