@reviewflow/sdk 6.25.0 → 6.27.0

package/src/git/checkoutBranchDiff.ts

@@ -0,0 +1,191 @@
+import type {
+  BranchDiffBase,
+  BranchDiffScope,
+  CheckoutBranchDiffResponse,
+  DiffWhitespace,
+} from "../diff/types.ts";
+import { groupDiffPaths, packagesOnDisk } from "./groupDiffPaths.ts";
+import type { DiffLimits } from "./readBranchDiff.ts";
+import { readBranchDiff } from "./readBranchDiff.ts";
+import { git, gitOrNull } from "./run.ts";
+
+/** null on a detached HEAD */
+export const readHeadBranch = async (cwd: string): Promise<string | null> => {
+  const branch = await gitOrNull(cwd, [
+    "symbolic-ref",
+    "--quiet",
+    "--short",
+    "HEAD",
+  ]);
+  return branch === null || branch.trim() === "" ? null : branch.trim();
+};
+
+export const readHeadSha = async (
+  cwd: string,
+  ref = "HEAD",
+): Promise<string> => {
+  const sha = await git(cwd, ["rev-parse", ref]);
+  return sha.trim();
+};
+
+/**
+ * The branch `origin/HEAD` points at, as the last clone or
+ * `git remote set-head` recorded it; null when it was never recorded.
+ */
+export const readDefaultBranch = async (
+  cwd: string,
+): Promise<string | null> => {
+  const ref = await gitOrNull(cwd, [
+    "symbolic-ref",
+    "--quiet",
+    "--short",
+    "refs/remotes/origin/HEAD",
+  ]);
+  const name = ref?.trim().replace(/^origin\//, "") ?? "";
+  return name === "" ? null : name;
+};
+
+const readCommit = async (cwd: string, ref: string): Promise<string | null> => {
+  const sha = await gitOrNull(cwd, [
+    "rev-parse",
+    "--verify",
+    "--quiet",
+    `${ref}^{commit}`,
+  ]);
+  return sha === null ? null : sha.trim();
+};
+
+/** Where a read of a checkout starts: its HEAD, or one of its local branches. */
+export interface ReadHead {
+  ref: string;
+  /** null on a detached HEAD */
+  branch: string | null;
+}
+
+/**
+ * The checkout's HEAD when `branch` is absent, else `refs/heads/<branch>`,
+ * which must exist: the full ref keeps a name from being taken for an option
+ * or for another kind of revision.
+ */
+export const resolveReadHead = async (
+  cwd: string,
+  branch: string | undefined,
+): Promise<ReadHead> => {
+  if (branch === undefined) {
+    return { ref: "HEAD", branch: await readHeadBranch(cwd) };
+  }
+  const ref = `refs/heads/${branch}`;
+  if ((await readCommit(cwd, ref)) === null) {
+    throw new Error(`no local branch ${branch} in ${cwd}`);
+  }
+  return { ref, branch };
+};
+
+export interface ResolvedDiffBase {
+  base: BranchDiffBase;
+  mergeBase: string;
+}
+
+/**
+ * `origin/<name>` before `<name>`: in a worktree setup the local base branch is
+ * whatever was last pulled in the main checkout, usually older than the last
+ * fetch. Nothing is fetched: a read that talks to the network on every open is
+ * not on-demand anymore, so the ref and its sha travel with the diff.
+ *
+ * The diff starts at the merge base, not at the base's tip: what landed on the
+ * base since the branch left it is not the branch's change.
+ */
+export const resolveDiffBase = async (
+  cwd: string,
+  name: string,
+  head = "HEAD",
+): Promise<ResolvedDiffBase> => {
+  const candidates = [
+    { ref: `origin/${name}`, fullRef: `refs/remotes/origin/${name}` },
+    { ref: name, fullRef: `refs/heads/${name}` },
+  ];
+  for (const { ref, fullRef } of candidates) {
+    const sha = await readCommit(cwd, fullRef);
+    if (sha === null) continue;
+    const mergeBase = await gitOrNull(cwd, ["merge-base", sha, head]);
+    if (mergeBase === null) {
+      throw new Error(`${head} shares no history with ${ref}`);
+    }
+    return { base: { name, ref, sha }, mergeBase: mergeBase.trim() };
+  }
+  throw new Error(
+    `neither origin/${name} nor ${name} exists in ${cwd}: fetch the repository, or check its default branch`,
+  );
+};
+
+export interface CheckoutBranchDiffParams {
+  cwd: string;
+  /** absent: the branch `origin/HEAD` names, else `main` */
+  baseName?: string;
+  scope: BranchDiffScope;
+  /** a local branch to read instead of HEAD; `committed` only, it has no working tree here */
+  branch?: string;
+  whitespace?: DiffWhitespace;
+  limits?: DiffLimits;
+}
+
+interface ScopeStartParams {
+  cwd: string;
+  scope: BranchDiffScope;
+  baseName: string | undefined;
+  head: string;
+}
+
+const readScopeStart = async ({
+  cwd,
+  scope,
+  baseName,
+  head,
+}: ScopeStartParams): Promise<ResolvedDiffBase | null> => {
+  if (scope === "uncommitted") return null;
+  const name = baseName ?? (await readDefaultBranch(cwd)) ?? "main";
+  return resolveDiffBase(cwd, name, head);
+};
+
+/**
+ * The checked-out branch, or `branch`, since it left its base (`committed`),
+ * or the working tree since `HEAD` (`uncommitted`), grouped by package. The
+ * packages are those on disk, the checked-out ones, even for another branch.
+ */
+export const readCheckoutBranchDiff = async ({
+  cwd,
+  baseName,
+  scope,
+  branch: branchName,
+  whitespace = "show",
+  limits,
+}: CheckoutBranchDiffParams): Promise<CheckoutBranchDiffResponse> => {
+  if (branchName !== undefined && scope === "uncommitted") {
+    throw new Error(
+      `${branchName} is not checked out here: it has nothing uncommitted`,
+    );
+  }
+  const head = await resolveReadHead(cwd, branchName);
+  const [start, headSha] = await Promise.all([
+    readScopeStart({ cwd, scope, baseName, head: head.ref }),
+    readHeadSha(cwd, head.ref),
+  ]);
+  const { paths, ...diff } = await readBranchDiff({
+    cwd,
+    mergeBase: start?.mergeBase ?? headSha,
+    head: head.ref,
+    scope: scope === "uncommitted" ? "workingTree" : "committed",
+    whitespace,
+    limits,
+  });
+  return {
+    scope,
+    whitespace,
+    branch: head.branch,
+    headSha,
+    base: start?.base ?? null,
+    mergeBase: start?.mergeBase ?? null,
+    ...diff,
+    groups: groupDiffPaths(packagesOnDisk(cwd), paths),
+  };
+};

package/src/git/checkoutBranches.ts

@@ -0,0 +1,187 @@
+import type {
+  CheckoutBranch,
+  CheckoutBranchesResponse,
+  CheckoutWorktree,
+} from "../checkout/overview.ts";
+import type { ResolvedDiffBase } from "./checkoutBranchDiff.ts";
+import { readDefaultBranch, resolveDiffBase } from "./checkoutBranchDiff.ts";
+import { readCheckoutStatus } from "./checkoutSync.ts";
+import { git, gitOrNull } from "./run.ts";
+
+interface ListedWorktree {
+  path: string;
+  branch: string | null;
+  headSha: string | null;
+  bare: boolean;
+  /** why it is locked, `""` when no reason was given; null when it is not */
+  lock: string | null;
+  prunable: boolean;
+}
+
+const zeroSha = /^0+$/;
+
+/**
+ * `git worktree list --porcelain`: one block per worktree, blocks separated by
+ * an empty line, each opening with `worktree <path>`; `HEAD`, `branch`,
+ * `detached`, `bare`, `locked` and `prunable` follow. A worktree on a branch
+ * with no commit yet has an all-zero `HEAD`.
+ */
+export const parseWorktreeList = (output: string): ListedWorktree[] =>
+  output
+    .split(/\n{2,}/)
+    .map((block) => block.split("\n").filter((line) => line !== ""))
+    .filter((lines) => lines[0]?.startsWith("worktree ") === true)
+    .map((lines) => {
+      const value = (key: string): string | null => {
+        const line = lines.find(
+          (candidate) => candidate === key || candidate.startsWith(`${key} `),
+        );
+        return line === undefined ? null : line.slice(key.length + 1);
+      };
+      const head = value("HEAD");
+      const branch = value("branch");
+      return {
+        path: value("worktree") ?? "",
+        branch: branch === null ? null : branch.replace(/^refs\/heads\//, ""),
+        headSha: head === null || zeroSha.test(head) ? null : head,
+        bare: value("bare") !== null,
+        lock: value("locked"),
+        prunable: value("prunable") !== null,
+      };
+    });
+
+/**
+ * Every worktree of the repository `cwd` belongs to, the main one first, each
+ * with its status; a bare repository's own entry is left out, having no files.
+ */
+export const readWorktrees = async (
+  cwd: string,
+): Promise<CheckoutWorktree[]> => {
+  const listed = parseWorktreeList(
+    await git(cwd, ["worktree", "list", "--porcelain"]),
+  );
+  return Promise.all(
+    listed
+      .map((worktree, index) => ({ ...worktree, main: index === 0 }))
+      .filter(({ bare }) => !bare)
+      .map(async ({ bare: _bare, ...worktree }) => ({
+        ...worktree,
+        status: worktree.prunable
+          ? null
+          : await readCheckoutStatus(worktree.path).catch(() => null),
+      })),
+  );
+};
+
+const fieldSeparator = "\u0000";
+const branchFormat = [
+  "%(refname:lstrip=2)",
+  "%(objectname)",
+  "%(upstream:short)",
+  "%(upstream:track)",
+  "%(committerdate:iso-strict)",
+  "%(worktreepath)",
+  "%(subject)",
+].join("%00");
+
+interface Track {
+  ahead: number | null;
+  behind: number | null;
+  gone: boolean;
+}
+
+/**
+ * `%(upstream:track)`: `[ahead 2, behind 1]`, `[gone]`, or empty both in sync
+ * and without an upstream, which `hasUpstream` tells apart.
+ */
+export const parseTrack = (track: string, hasUpstream: boolean): Track => {
+  if (!hasUpstream) return { ahead: null, behind: null, gone: false };
+  if (track === "[gone]") return { ahead: null, behind: null, gone: true };
+  const count = (word: string): number =>
+    Number(new RegExp(`${word} (\\d+)`).exec(track)?.[1] ?? 0);
+  return { ahead: count("ahead"), behind: count("behind"), gone: false };
+};
+
+const readMergedBranches = async (
+  cwd: string,
+  start: ResolvedDiffBase | null,
+): Promise<Set<string>> => {
+  if (start === null) return new Set();
+  const listed = await git(cwd, [
+    "for-each-ref",
+    `--merged=${start.base.sha}`,
+    "--format=%(refname:lstrip=2)",
+    "refs/heads",
+  ]);
+  return new Set(
+    listed
+      .split("\n")
+      .filter((name) => name !== "" && name !== start.base.name),
+  );
+};
+
+const readBase = async (
+  cwd: string,
+  baseName: string | undefined,
+): Promise<ResolvedDiffBase | null> => {
+  const name = baseName ?? (await readDefaultBranch(cwd)) ?? "main";
+  return resolveDiffBase(cwd, name).catch(() => null);
+};
+
+export interface ReadBranchesParams {
+  cwd: string;
+  /** absent: the branch `origin/HEAD` names, else `main` */
+  baseName?: string;
+}
+
+/**
+ * The local branches, most recently committed first, and the worktrees they
+ * are checked out in. Nothing is fetched: ahead, behind and gone are as of the
+ * last fetch.
+ */
+export const readBranches = async ({
+  cwd,
+  baseName,
+}: ReadBranchesParams): Promise<CheckoutBranchesResponse> => {
+  const start = await readBase(cwd, baseName);
+  const [listing, merged, worktrees] = await Promise.all([
+    gitOrNull(cwd, [
+      "for-each-ref",
+      "--sort=-committerdate",
+      `--format=${branchFormat}`,
+      "refs/heads",
+    ]),
+    readMergedBranches(cwd, start),
+    readWorktrees(cwd),
+  ]);
+  const branches = (listing ?? "")
+    .split("\n")
+    .filter((line) => line !== "")
+    .map((line): CheckoutBranch => {
+      const [
+        name = "",
+        sha = "",
+        upstream = "",
+        track = "",
+        committedAt = "",
+        worktreePath = "",
+        subject = "",
+      ] = line.split(fieldSeparator);
+      const { ahead, behind, gone } = parseTrack(track, upstream !== "");
+      return {
+        name,
+        sha,
+        upstream: upstream === "" ? null : upstream,
+        ahead,
+        behind,
+        upstreamGone: gone,
+        merged: merged.has(name),
+        worktreePath: worktreePath === "" ? null : worktreePath,
+        lastCommit: {
+          subject,
+          committedAt: new Date(committedAt).toISOString(),
+        },
+      };
+    });
+  return { base: start?.base ?? null, worktrees, branches };
+};

package/src/git/checkoutCommits.ts

@@ -0,0 +1,223 @@
+import type {
+  BranchDiffBase,
+  CheckoutCommit,
+  CheckoutCommitsResponse,
+  CommitDiffResponse,
+  DiffWhitespace,
+} from "../diff/types.ts";
+import {
+  readDefaultBranch,
+  resolveDiffBase,
+  resolveReadHead,
+} from "./checkoutBranchDiff.ts";
+import { groupDiffPaths, packagesOnDisk } from "./groupDiffPaths.ts";
+import type { DiffLimits } from "./readBranchDiff.ts";
+import { readBranchDiff } from "./readBranchDiff.ts";
+import { git, gitOrNull } from "./run.ts";
+
+export const defaultRecentCommits = 30;
+
+const fieldSeparator = "\u001F";
+const recordSeparator = "\u001E";
+const logFormat = ["%H", "%P", "%an", "%cI", "%s", "%b"].join("%x1f");
+
+interface LoggedCommit {
+  sha: string;
+  parents: string[];
+  author: string;
+  committedAt: string;
+  headline: string;
+  body: string;
+}
+
+const parseLog = (output: string): LoggedCommit[] =>
+  output
+    .split(recordSeparator)
+    .map((record) => record.replace(/^\n/, ""))
+    .filter((record) => record !== "")
+    .map((record) => {
+      const [
+        sha = "",
+        parents = "",
+        author = "",
+        committedAt = "",
+        headline = "",
+        body = "",
+      ] = record.split(fieldSeparator);
+      return {
+        sha,
+        parents: parents === "" ? [] : parents.split(" "),
+        author,
+        committedAt,
+        headline,
+        body: body.trim(),
+      };
+    });
+
+interface BranchStart {
+  base: BranchDiffBase;
+  /** the branch's commits among the listed ones: its head has them, the base has not */
+  onBranch: Set<string>;
+  /** every commit of the branch, listed or not */
+  count: number;
+}
+
+interface BranchStartParams {
+  cwd: string;
+  baseName: string | undefined;
+  limit: number;
+  head: string;
+}
+
+/**
+ * Null when the base cannot be resolved: nothing is then marked on the branch.
+ * The range keeps `git log`'s order, so its first `limit` commits hold every
+ * listed one it has.
+ */
+const readBranchStart = async ({
+  cwd,
+  baseName,
+  limit,
+  head,
+}: BranchStartParams): Promise<BranchStart | null> => {
+  const name = baseName ?? (await readDefaultBranch(cwd)) ?? "main";
+  try {
+    const { base, mergeBase } = await resolveDiffBase(cwd, name, head);
+    const range = `${mergeBase}..${head}`;
+    const [listed, count] = await Promise.all([
+      git(cwd, ["rev-list", `--max-count=${String(limit)}`, range]),
+      git(cwd, ["rev-list", "--count", range]),
+    ]);
+    return {
+      base,
+      onBranch: new Set(listed.split("\n").filter((sha) => sha !== "")),
+      count: Number(count.trim()),
+    };
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * The commits among the head's last `limit` that no remote-tracking ref
+ * reaches: `--not --remotes` keeps rev-list's order, so the ones in the log are
+ * all in its first `limit`. Null when the checkout has no remote, where every
+ * commit would read as not pushed.
+ */
+const readUnpushed = async (
+  cwd: string,
+  limit: number,
+  head: string,
+): Promise<Set<string> | null> => {
+  const remotes = await git(cwd, ["remote"]);
+  if (remotes.trim() === "") return null;
+  const listed = await gitOrNull(cwd, [
+    "rev-list",
+    `--max-count=${String(limit)}`,
+    head,
+    "--not",
+    "--remotes",
+  ]);
+  return new Set((listed ?? "").split("\n").filter((sha) => sha !== ""));
+};
+
+export interface RecentCommitsParams {
+  cwd: string;
+  /** `defaultRecentCommits` unless set */
+  limit?: number;
+  /** absent: the branch `origin/HEAD` names, else `main` */
+  baseName?: string;
+  /** a local branch to read instead of HEAD */
+  branch?: string;
+}
+
+/**
+ * The last commits of HEAD, or of `branch`, newest first, each marked when the
+ * branch carries it since it left its base, and when it is pushed. A
+ * repository without a commit has none.
+ */
+export const readRecentCommits = async ({
+  cwd,
+  limit = defaultRecentCommits,
+  baseName,
+  branch: branchName,
+}: RecentCommitsParams): Promise<CheckoutCommitsResponse> => {
+  const head = await resolveReadHead(cwd, branchName);
+  const [start, unpushed, log] = await Promise.all([
+    readBranchStart({ cwd, baseName, limit, head: head.ref }),
+    readUnpushed(cwd, limit, head.ref),
+    gitOrNull(cwd, [
+      "log",
+      "--no-color",
+      `--max-count=${String(limit)}`,
+      `--format=${logFormat}%x1e`,
+      head.ref,
+    ]),
+  ]);
+  const { branch } = head;
+  const commits = parseLog(log ?? "").map((commit): CheckoutCommit => ({
+    oid: commit.sha,
+    parentOid: commit.parents[0] ?? null,
+    merge: commit.parents.length > 1,
+    headline: commit.headline,
+    body: commit.body,
+    author: { login: commit.author, avatarUrl: null },
+    committedAt: commit.committedAt,
+    onBranch: start?.onBranch.has(commit.sha) ?? false,
+    pushed: unpushed === null ? null : !unpushed.has(commit.sha),
+  }));
+  return {
+    branch,
+    base: start?.base ?? null,
+    onBranchCount: start?.count ?? null,
+    commits,
+  };
+};
+
+/** The empty tree, in whichever object format the repository uses. */
+const emptyTree = async (cwd: string): Promise<string> => {
+  const tree = await git(cwd, ["hash-object", "-t", "tree", "/dev/null"]);
+  return tree.trim();
+};
+
+export interface CommitDiffParams {
+  cwd: string;
+  sha: string;
+  whitespace?: DiffWhitespace;
+  limits?: DiffLimits;
+}
+
+/**
+ * One commit against its first parent, a merge included (its diff then
+ * carries what was merged in); a root commit against the empty tree.
+ */
+export const readCommitDiff = async ({
+  cwd,
+  sha,
+  whitespace = "show",
+  limits,
+}: CommitDiffParams): Promise<CommitDiffResponse> => {
+  const listed = await git(cwd, [
+    "rev-list",
+    "--parents",
+    "--max-count=1",
+    `${sha}^{commit}`,
+  ]);
+  const [commit = sha, parentSha = null] = listed.trim().split(" ");
+  const { paths, patch, omitted } = await readBranchDiff({
+    cwd,
+    mergeBase: parentSha ?? (await emptyTree(cwd)),
+    head: commit,
+    scope: "committed",
+    whitespace,
+    limits,
+  });
+  return {
+    sha: commit,
+    parentSha,
+    whitespace,
+    patch,
+    omitted,
+    groups: groupDiffPaths(packagesOnDisk(cwd), paths),
+  };
+};