@reviewflow/sdk 6.25.0 → 6.27.0

package/src/git/checkoutSync.ts

@@ -0,0 +1,179 @@
+import type {
+  CheckoutHeadCommit,
+  CheckoutStatus,
+  CheckoutSyncResponse,
+} from "../checkout/sync.ts";
+import { pullRefusal, pushRefusal } from "../checkout/sync.ts";
+import { git, gitOrNull } from "./run.ts";
+
+export interface StatusV2 extends Omit<CheckoutStatus, "commit" | "path"> {
+  /** false on a branch with no commit yet (`branch.oid (initial)`) */
+  hasCommit: boolean;
+}
+
+const headerValue = (line: string, key: string): string | null =>
+  line.startsWith(`# ${key} `) ? line.slice(`# ${key} `.length) : null;
+
+/**
+ * `git status --porcelain=v2 --branch`: `# branch.*` headers, then one line per
+ * entry — `1`/`2` for a tracked change, `u` for an unmerged path, `?` for an
+ * untracked one (`!` only appears with `--ignored`). `branch.ab` is absent both
+ * without an upstream and when the upstream's ref is gone, which is why
+ * ahead/behind are null whenever it is.
+ */
+export const parseStatusV2 = (stdout: string): StatusV2 => {
+  const status: StatusV2 = {
+    branch: null,
+    hasCommit: true,
+    upstream: null,
+    ahead: null,
+    behind: null,
+    modified: 0,
+    untracked: 0,
+  };
+
+  for (const line of stdout.split("\n")) {
+    if (line.startsWith("# ")) {
+      const oid = headerValue(line, "branch.oid");
+      if (oid !== null) status.hasCommit = oid !== "(initial)";
+      const head = headerValue(line, "branch.head");
+      if (head !== null) status.branch = head === "(detached)" ? null : head;
+      const upstream = headerValue(line, "branch.upstream");
+      if (upstream !== null) status.upstream = upstream;
+      const ab = headerValue(line, "branch.ab");
+      const counts = ab === null ? null : /^\+(\d+) -(\d+)$/.exec(ab);
+      if (counts) {
+        status.ahead = Number(counts[1]);
+        status.behind = Number(counts[2]);
+      }
+    } else if (line.startsWith("? ")) {
+      status.untracked += 1;
+    } else if (/^[12u] /.test(line)) {
+      status.modified += 1;
+    }
+  }
+
+  return status;
+};
+
+const readHeadCommit = async (
+  cwd: string,
+): Promise<CheckoutHeadCommit | null> => {
+  const stdout = await gitOrNull(cwd, [
+    "log",
+    "-1",
+    "--format=%h%x00%s%x00%cI",
+    "--no-patch",
+  ]);
+  const [shortSha, subject, committedAt] = (stdout?.trim() ?? "").split("\0");
+  if (!shortSha || subject === undefined || !committedAt) return null;
+  return {
+    shortSha,
+    subject,
+    committedAt: new Date(committedAt).toISOString(),
+  };
+};
+
+/** One checkout's status: two git calls, read on request and never cached. */
+export const readCheckoutStatus = async (
+  cwd: string,
+): Promise<CheckoutStatus> => {
+  const { hasCommit, ...status } = parseStatusV2(
+    await git(cwd, ["status", "--porcelain=v2", "--branch"]),
+  );
+  return {
+    path: cwd,
+    ...status,
+    commit: hasCommit ? await readHeadCommit(cwd) : null,
+  };
+};
+
+const messageOf = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+const hasOriginRemote = async (cwd: string): Promise<boolean> =>
+  (await gitOrNull(cwd, ["remote", "get-url", "origin"])) !== null;
+
+/**
+ * Whether to fetch before reading. `always`: the caller wants behind counted
+ * against the remote as it is now. A sha: only when the upstream ref is not at
+ * it (a pull request's head as GitHub reported it), so reading costs no network
+ * call unless someone pushed. A branch with no upstream is never fetched: there
+ * is nothing it would pull.
+ */
+export type CheckoutFetch = "always" | "never" | { unlessUpstreamAt: string };
+
+const fetchFirst = async (
+  cwd: string,
+  fetch: CheckoutFetch,
+): Promise<string | null> => {
+  if (fetch === "never") return null;
+  const upstreamSha = await gitOrNull(cwd, [
+    "rev-parse",
+    "--verify",
+    "--quiet",
+    "@{upstream}",
+  ]);
+  if (upstreamSha === null) return null;
+  if (fetch !== "always" && upstreamSha.trim() === fetch.unlessUpstreamAt) {
+    return null;
+  }
+  try {
+    await git(cwd, ["fetch", "--quiet"], { network: true });
+    return null;
+  } catch (error) {
+    return messageOf(error);
+  }
+};
+
+export interface ReadCheckoutSyncParams {
+  cwd: string;
+  /** `never` unless set */
+  fetch?: CheckoutFetch;
+}
+
+/** A failed fetch degrades: the status is then as of the previous one, and says why. */
+export const readCheckoutSync = async ({
+  cwd,
+  fetch = "never",
+}: ReadCheckoutSyncParams): Promise<CheckoutSyncResponse> => {
+  const fetchError = await fetchFirst(cwd, fetch);
+  const [status, hasOrigin] = await Promise.all([
+    readCheckoutStatus(cwd),
+    hasOriginRemote(cwd),
+  ]);
+  return { status, hasOrigin, fetchError };
+};
+
+/**
+ * `--ff-only`: a pull that would need a merge or a rebase is a decision about
+ * someone's branch, and git refuses it with the reason. A dirty checkout is left
+ * to git too — it refuses only when an incoming change touches a modified file.
+ * The refusal a surface hides the button on is thrown first, with its reason.
+ */
+export const pullCheckout = async (cwd: string): Promise<void> => {
+  const refusal = pullRefusal(await readCheckoutStatus(cwd));
+  if (refusal !== null) throw new Error(refusal);
+  await git(cwd, ["pull", "--quiet", "--ff-only"], { network: true });
+};
+
+/**
+ * Never `--force`: a rejected non-fast-forward comes back as git's reason. A
+ * branch with no upstream is published to `origin` and starts tracking it, so
+ * the next push and the ahead count both work from the same place.
+ */
+export const pushCheckout = async (cwd: string): Promise<void> => {
+  const [status, hasOrigin] = await Promise.all([
+    readCheckoutStatus(cwd),
+    hasOriginRemote(cwd),
+  ]);
+  const refusal = pushRefusal(status, hasOrigin);
+  if (refusal !== null) throw new Error(refusal);
+  await git(
+    cwd,
+    status.upstream === null && status.branch !== null
+      ? ["push", "--quiet", "--set-upstream", "origin", status.branch]
+      : ["push", "--quiet"],
+    { network: true },
+  );
+};

package/src/git/readBranchDiff.ts

@@ -33,7 +33,7 @@ export interface DiffLimits {
   maxLinesPerFile: number;
   maxTotalLines: number;
   maxFiles: number;
-  /** untracked files read under the `all` scope; the rest are omitted */
+  /** untracked files read under the `workingTree` scope; the rest are omitted */
   maxUntrackedFiles: number;
   /** an untracked file larger than this is omitted as too large */
   maxUntrackedBytes: number;
@@ -289,12 +289,6 @@ const readUntrackedDiff = async (
   return { patches, paths, omitted };
 };
 
-/**
- * `committed`: the merge base to `head`. `all`: the merge base to the working
- * tree, which adds the staged and unstaged changes and the untracked files.
- */
-export type BranchDiffScope = "all" | "committed";
-
 export interface BranchDiff {
   patch: string;
   /** the files in `patch`, in its order */
@@ -304,15 +298,20 @@ export interface BranchDiff {
   untrackedCount: number;
 }
 
+/**
+ * Where the diff ends: `committed` at a commit, `workingTree` at the files on
+ * disk, staged, unstaged and untracked changes included.
+ */
+export type BranchDiffEnd = "committed" | "workingTree";
+
 interface ReadBranchDiffParams {
   cwd: string;
   mergeBase: string;
   /** `committed` unless set: the pull request path reads no working tree */
-  scope?: BranchDiffScope;
+  scope?: BranchDiffEnd;
   /**
    * The commit the `committed` scope ends at: a pull request's head, which no
-   * worktree need be on, or `HEAD` unless set. Ignored under `all`, which is
-   * the working tree.
+   * worktree need be on, or `HEAD` unless set. Ignored under `workingTree`.
    */
   head?: string;
   /** `show` unless set */

package/src/git/run.ts

@@ -21,6 +21,21 @@ export interface GitOptions {
   exitOneIsAnswer?: boolean;
   /** kills git when the caller no longer wants the answer */
   signal?: AbortSignal;
+  /**
+   * For a command that deletes files, which must never stop partway: killing
+   * `git worktree remove` leaves a directory with half its tracked files gone,
+   * which git then refuses to remove as dirty.
+   *
+   * - **No timeout**, and `maxBuffer`, `network` and `signal` are ignored. On a
+   *   worktree with a populated `node_modules` it outlasts any read timeout.
+   * - **Its own process group**, so a signal sent to the caller's group (Ctrl-C
+   *   in a terminal, a service manager stopping the job) does not reach it:
+   *   past a kill of the caller it still finishes.
+   *
+   * A caller that must also run its own bookkeeping afterwards holds its
+   * shutdown until the promise settles.
+   */
+  uninterruptible?: boolean;
 }
 
 /**
@@ -78,12 +93,50 @@ const isExitOneAnswer = (error: unknown): error is { stdout: string } =>
   typeof error.stdout === "string" &&
   error.stdout !== "";
 
+/**
+ * `execFile` forwards a fixed list of options to `spawn`, and `detached` is not
+ * on it.
+ */
+const runUninterruptible = async (
+  cwd: string,
+  args: string[],
+): Promise<string> =>
+  new Promise((resolve, reject) => {
+    const child = spawn("git", args, {
+      cwd,
+      env,
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8").on("data", (chunk: string) => {
+      stdout += chunk;
+    });
+    child.stderr.setEncoding("utf8").on("data", (chunk: string) => {
+      stderr += chunk;
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve(stdout);
+        return;
+      }
+      reject(
+        Object.assign(new Error(`git exited with ${String(code)}`), {
+          stderr,
+        }),
+      );
+    });
+  });
+
 /**
  * git reads are on-demand: nothing here caches, and every call names the repository it ran in so a failure is actionable.
  *
  * `execFile` with an argument array and no shell, which is what makes a branch
  * name safe to pass through: nothing here is ever interpolated into a command
- * line.  *
+ * line.
+ *
  * The message keeps only one stderr line on purpose (`reasonLine`): it is
  * rendered to the user verbatim, and the rest is
  * hints.
@@ -95,6 +148,7 @@ export const git = async (
 ): Promise<string> => {
   const timeout = options.network ? networkTimeoutMs : timeoutMs;
   try {
+    if (options.uninterruptible) return await runUninterruptible(cwd, args);
     const { stdout } = await execFileAsync("git", args, {
       cwd,
       timeout,

package/src/git/worktreeRemoval.ts

@@ -0,0 +1,316 @@
+import { execFile } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { lstat, readdir } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import { pid } from "node:process";
+import { promisify } from "node:util";
+import type {
+  WorktreeRemovalResult,
+  WorktreeRemovalStatus,
+} from "../checkout/worktreeRemoval.ts";
+import { worktreeRemovalRefusal } from "../checkout/worktreeRemoval.ts";
+import { parseWorktreeList } from "./checkoutBranches.ts";
+import { git, gitOrNull } from "./run.ts";
+
+const execFileAsync = promisify(execFile);
+
+const realpathOrSelf = (path: string): string => {
+  try {
+    return realpathSync.native(path);
+  } catch {
+    return path;
+  }
+};
+
+const isInsideDirectory = (directory: string, path: string): boolean => {
+  const relativePath = relative(directory, path);
+  return (
+    relativePath === "" ||
+    (!relativePath.startsWith("..") && !isAbsolute(relativePath))
+  );
+};
+
+const readGitDirectory = async (
+  worktree: string,
+  flag: "--git-common-dir" | "--git-dir",
+): Promise<string> => {
+  const directory = await git(worktree, [
+    "rev-parse",
+    "--path-format=absolute",
+    flag,
+  ]);
+  return realpathOrSelf(directory.trim());
+};
+
+/**
+ * The branch read from git, never from a cached listing: it is what
+ * `git branch -d` is handed. `--abbrev-ref` answers the literal `HEAD` on a
+ * detached head, the one case with no branch to delete.
+ */
+const readBranch = async (worktree: string): Promise<string | null> => {
+  const branch = await gitOrNull(worktree, [
+    "rev-parse",
+    "--abbrev-ref",
+    "HEAD",
+  ]);
+  const name = branch?.trim() ?? "";
+  return name === "" || name === "HEAD" ? null : name;
+};
+
+/**
+ * `??` is an untracked path, every other code a tracked change. Ignored files
+ * are absent without `--ignored`: `git worktree remove` ignores them too, so
+ * counting them would predict a refusal that never comes.
+ */
+const countChanges = async (
+  worktree: string,
+): Promise<Pick<WorktreeRemovalStatus, "modified" | "untracked">> => {
+  const porcelain = await git(worktree, ["status", "--porcelain"]);
+  const lines = porcelain.split("\n").filter((line) => line.trim() !== "");
+  const untracked = lines.filter((line) => line.startsWith("??")).length;
+  return { modified: lines.length - untracked, untracked };
+};
+
+const hasCommit = async (worktree: string, sha: string): Promise<boolean> =>
+  (await gitOrNull(worktree, ["cat-file", "-e", `${sha}^{commit}`])) !== null;
+
+/**
+ * Commits on HEAD reachable from no remote-tracking ref and from no kept sha.
+ * Not `@{u}..HEAD`: that has no answer once the upstream is gone, the normal
+ * state of a merged branch after `fetch --prune`, and it ignores a commit
+ * already on another remote branch. A kept sha missing from the object store
+ * is left out, which only counts more as unpushed: the guard errs toward
+ * refusing.
+ */
+const countUnpushedCommits = async (
+  worktree: string,
+  keptShas: string[],
+): Promise<number> => {
+  const present = await Promise.all(
+    keptShas
+      .filter((sha) => /^[\da-f]{7,64}$/i.test(sha))
+      .map(async (sha) => ((await hasCommit(worktree, sha)) ? sha : null)),
+  );
+  const count = await gitOrNull(worktree, [
+    "rev-list",
+    "--count",
+    "HEAD",
+    "--not",
+    "--remotes",
+    ...present.filter((sha) => sha !== null),
+  ]);
+  return count === null ? 0 : Number(count.trim());
+};
+
+const readLock = async (worktree: string): Promise<string | null> => {
+  const listed = parseWorktreeList(
+    await git(worktree, ["worktree", "list", "--porcelain"]),
+  );
+  const own = listed.find(
+    ({ path }) => realpathOrSelf(path) === realpathOrSelf(worktree),
+  );
+  return own?.lock ?? null;
+};
+
+/**
+ * `lsof -d cwd` lists every process's working directory in one call. It exits
+ * 1 with a partial listing when some processes cannot be read, which is still
+ * an answer; without `lsof` at all nothing can be told, and null refuses
+ * nothing. This server's own process is not counted.
+ */
+export const countProcessesInside = async (
+  directory: string,
+): Promise<number | null> => {
+  const stdout = await execFileAsync("lsof", ["-n", "-d", "cwd", "-F", "pn"], {
+    timeout: 10_000,
+    maxBuffer: 16 * 1024 * 1024,
+  }).then(
+    ({ stdout: answer }) => answer,
+    (error: unknown) => {
+      if (
+        typeof error === "object" &&
+        error !== null &&
+        "stdout" in error &&
+        typeof error.stdout === "string" &&
+        error.stdout !== ""
+      ) {
+        return error.stdout;
+      }
+      return null;
+    },
+  );
+  if (stdout === null) return null;
+  const root = realpathOrSelf(directory);
+  const inside = new Set<string>();
+  let processId = "";
+  for (const line of stdout.split("\n")) {
+    if (line.startsWith("p")) processId = line.slice(1);
+    else if (
+      line.startsWith("n") &&
+      processId !== String(pid) &&
+      isInsideDirectory(root, line.slice(1))
+    ) {
+      inside.add(processId);
+    }
+  }
+  return inside.size;
+};
+
+const ignoredPrefix = "!! ";
+
+/** A directory git collapsed to one entry, named file by file. */
+const listFiles = async (
+  worktree: string,
+  relativeDirectory: string,
+): Promise<string[]> => {
+  const entries = await readdir(join(worktree, relativeDirectory), {
+    recursive: true,
+    withFileTypes: true,
+  }).catch(() => []);
+  return entries
+    .filter((entry) => entry.isFile())
+    .map((entry) => relative(worktree, join(entry.parentPath, entry.name)))
+    .toSorted();
+};
+
+/**
+ * Compared by existence, not content: git collapses an ignored directory to one
+ * entry, and walking a `node_modules` to compare it is not a read to make on
+ * every confirmation. A symlink points at a file that survives, and a path the
+ * main checkout also has is regenerable or duplicated.
+ */
+const listLocalOnlyIgnored = async (
+  worktree: string,
+  mainCheckout: string,
+): Promise<string[]> => {
+  const porcelain = await git(worktree, [
+    "status",
+    "--porcelain",
+    "--ignored",
+    "-z",
+  ]);
+  const ignored = porcelain
+    .split("\0")
+    .filter((entry) => entry.startsWith(ignoredPrefix))
+    .map((entry) => entry.slice(ignoredPrefix.length));
+  const localOnly = await Promise.all(
+    ignored.map(async (relativePath): Promise<string[]> => {
+      // gone between the status and this read: nothing left to lose
+      const entry = await lstat(join(worktree, relativePath)).catch(() => null);
+      if (entry === null || entry.isSymbolicLink()) return [];
+      if (existsSync(join(mainCheckout, relativePath))) return [];
+      return entry.isDirectory()
+        ? listFiles(worktree, relativePath)
+        : [relativePath];
+    }),
+  );
+  return localOnly.flat();
+};
+
+export interface ReadWorktreeRemovalStatusParams {
+  /** the worktree, absolute */
+  worktree: string;
+  /**
+   * Commits known to be safe elsewhere although no remote-tracking ref holds
+   * them: the pull request heads GitHub keeps after deleting a head branch.
+   */
+  keptShas?: string[];
+}
+
+/**
+ * What removing the worktree would lose, read from git and the disk alone.
+ * Advisory on a surface: `prepareWorktreeRemoval` reads it again and refuses.
+ */
+export const readWorktreeRemovalStatus = async ({
+  worktree,
+  keptShas = [],
+}: ReadWorktreeRemovalStatusParams): Promise<WorktreeRemovalStatus> => {
+  const [gitDirectory, commonDirectory] = await Promise.all([
+    readGitDirectory(worktree, "--git-dir"),
+    readGitDirectory(worktree, "--git-common-dir"),
+  ]);
+  const [branch, changes, unpushedCommits, lock, ignored] = await Promise.all([
+    readBranch(worktree),
+    countChanges(worktree),
+    countUnpushedCommits(worktree, keptShas),
+    readLock(worktree),
+    listLocalOnlyIgnored(worktree, dirname(commonDirectory)),
+  ]);
+  // after the reads: the gits they run have their working directory inside too
+  const processesInside = await countProcessesInside(worktree);
+  return {
+    path: worktree,
+    main: gitDirectory === commonDirectory,
+    branch,
+    ...changes,
+    unpushedCommits,
+    lock,
+    processesInside,
+    localOnlyIgnored: ignored,
+  };
+};
+
+/** A removal every refusal has passed: what `completeWorktreeRemoval` runs. */
+export interface WorktreeRemovalPlan {
+  path: string;
+  /** where git runs from: the repository's `.git`, which outlives the worktree */
+  commonDirectory: string;
+  /** null when not asked for, or on a detached HEAD */
+  branch: string | null;
+}
+
+export interface PrepareWorktreeRemovalParams extends ReadWorktreeRemovalStatusParams {
+  /** run `git branch -d` on its branch after the removal */
+  deleteBranch: boolean;
+}
+
+/**
+ * Reads the status now and throws the first refusal, before anything is
+ * deleted; a caller with guards of its own (a live session) runs them before
+ * this. Split from the removal so a caller can answer once every refusal has
+ * passed and remove after.
+ */
+export const prepareWorktreeRemoval = async ({
+  deleteBranch,
+  ...params
+}: PrepareWorktreeRemovalParams): Promise<WorktreeRemovalPlan> => {
+  const status = await readWorktreeRemovalStatus(params);
+  const refusal = worktreeRemovalRefusal(status);
+  if (refusal !== null) throw new Error(refusal);
+  return {
+    path: status.path,
+    commonDirectory: await readGitDirectory(
+      params.worktree,
+      "--git-common-dir",
+    ),
+    branch: deleteBranch ? status.branch : null,
+  };
+};
+
+const messageOf = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+/**
+ * `git worktree remove` with no `--force`, then `git branch -d` (never `-D`,
+ * never a remote) when the plan carries a branch. The removal is
+ * `uninterruptible`: killed midway, it leaves half the tracked files gone and
+ * a worktree git then refuses as dirty, so neither a client leaving nor a
+ * signal to this process stops it. A refused branch deletion is reported in
+ * the result; the removal stands. A refused removal throws git's reason.
+ */
+export const completeWorktreeRemoval = async ({
+  path,
+  commonDirectory,
+  branch,
+}: WorktreeRemovalPlan): Promise<WorktreeRemovalResult> => {
+  await git(commonDirectory, ["worktree", "remove", path], {
+    uninterruptible: true,
+  });
+  if (branch === null) return { path, branch, branchError: null };
+  try {
+    await git(commonDirectory, ["branch", "-d", branch]);
+    return { path, branch, branchError: null };
+  } catch (error) {
+    return { path, branch, branchError: messageOf(error) };
+  }
+};

package/src/git.ts

@@ -9,12 +9,63 @@ export {
   parseNumstat,
   readBranchDiff,
 } from "./git/readBranchDiff.ts";
+export type { BranchDiffScope } from "./diff/types.ts";
 export type {
   BranchDiff,
-  BranchDiffScope,
+  BranchDiffEnd,
   DiffLimits,
   NumstatEntry,
 } from "./git/readBranchDiff.ts";
+export {
+  readCheckoutBranchDiff,
+  readDefaultBranch,
+  readHeadBranch,
+  readHeadSha,
+  resolveDiffBase,
+} from "./git/checkoutBranchDiff.ts";
+export type {
+  CheckoutBranchDiffParams,
+  ResolvedDiffBase,
+} from "./git/checkoutBranchDiff.ts";
+export {
+  defaultRecentCommits,
+  readCommitDiff,
+  readRecentCommits,
+} from "./git/checkoutCommits.ts";
+export type {
+  CommitDiffParams,
+  RecentCommitsParams,
+} from "./git/checkoutCommits.ts";
+export {
+  parseTrack,
+  parseWorktreeList,
+  readBranches,
+  readWorktrees,
+} from "./git/checkoutBranches.ts";
+export type { ReadBranchesParams } from "./git/checkoutBranches.ts";
+export {
+  completeWorktreeRemoval,
+  countProcessesInside,
+  prepareWorktreeRemoval,
+  readWorktreeRemovalStatus,
+} from "./git/worktreeRemoval.ts";
+export type {
+  PrepareWorktreeRemovalParams,
+  ReadWorktreeRemovalStatusParams,
+  WorktreeRemovalPlan,
+} from "./git/worktreeRemoval.ts";
+export {
+  parseStatusV2,
+  pullCheckout,
+  pushCheckout,
+  readCheckoutStatus,
+  readCheckoutSync,
+} from "./git/checkoutSync.ts";
+export type {
+  CheckoutFetch,
+  ReadCheckoutSyncParams,
+  StatusV2,
+} from "./git/checkoutSync.ts";
 export {
   groupDiffPaths,
   noPackages,