@reviewflow/sdk 6.24.0 → 6.27.0

package/src/checkout/overview.ts

@@ -0,0 +1,109 @@
+import type { BranchDiffBase } from "../diff/types.ts";
+import type { IsoDateTime } from "../types/ids.ts";
+import type { CheckoutStatus } from "./sync.ts";
+
+/** One working tree of a repository, as `git worktree list` names it. */
+export interface CheckoutWorktree {
+  path: string;
+  /** the first one listed: the checkout the repository's `.git` lives in; none in a bare repository */
+  main: boolean;
+  /** null on a detached HEAD */
+  branch: string | null;
+  /** null on a branch with no commit yet */
+  headSha: string | null;
+  /** why it is locked, `""` when no reason was given; null when it is not */
+  lock: string | null;
+  /** its directory is gone: `git worktree prune` would drop it */
+  prunable: boolean;
+  /** null when prunable, or when git could not read it */
+  status: CheckoutStatus | null;
+}
+
+/** A local branch and where it stands. */
+export interface CheckoutBranch {
+  name: string;
+  sha: string;
+  /** e.g. `origin/feat`; null when it tracks nothing */
+  upstream: string | null;
+  /** null without an upstream, or when it is gone */
+  ahead: number | null;
+  behind: number | null;
+  /** the upstream it tracks no longer exists, as after GitHub deleted a merged head */
+  upstreamGone: boolean;
+  /**
+   * Every commit of it is in the base, so deleting it loses nothing; never the
+   * base branch itself, which a local copy behind its remote would otherwise
+   * be. A squash or rebase merge leaves it unmerged: `upstreamGone` is the
+   * sign then.
+   */
+  merged: boolean;
+  /** the worktree it is checked out in; null when none */
+  worktreePath: string | null;
+  lastCommit: { subject: string; committedAt: IsoDateTime };
+}
+
+/** `GET /api/repos/branches?repo=<owner/repo>` — read from git alone, no network. */
+export interface CheckoutBranchesResponse {
+  /** what `merged` is against; null when it cannot be found, no branch is then merged */
+  base: BranchDiffBase | null;
+  worktrees: CheckoutWorktree[];
+  /** most recently committed first */
+  branches: CheckoutBranch[];
+}
+
+/** An open pull request of a repository. */
+export interface OpenPullRequest {
+  number: number;
+  title: string;
+  isDraft: boolean;
+  headRefName: string;
+  /** the head's repository, a fork's included; null when it was deleted */
+  headOwnerRepo: string | null;
+  /** null for a deleted account */
+  author: string | null;
+  updatedAt: IsoDateTime;
+}
+
+/** `GET /api/repos/pulls?repo=<owner/repo>` — the open pull requests, most recently updated first. */
+export interface OpenPullRequestsResponse {
+  pullRequests: OpenPullRequest[];
+  /** every open pull request, the unlisted ones included */
+  totalCount: number;
+}
+
+/** A pull request whose head is a given branch, with the commit GitHub keeps for it. */
+export interface BranchPullRequestHead {
+  number: number;
+  state: "CLOSED" | "MERGED" | "OPEN";
+  /** the head commit, kept by GitHub after the head branch is deleted */
+  sha: string;
+}
+
+const sameRepo = (left: string | null, right: string): boolean =>
+  left !== null && left.toLowerCase() === right.toLowerCase();
+
+/** The open pull request whose head is this branch of this repository, not a fork's namesake. */
+export const pullRequestOfBranch = (
+  pullRequests: OpenPullRequest[],
+  ownerRepo: string,
+  branch: string,
+): OpenPullRequest | null =>
+  pullRequests.find(
+    (pullRequest) =>
+      pullRequest.headRefName === branch &&
+      sameRepo(pullRequest.headOwnerRepo, ownerRepo),
+  ) ?? null;
+
+/** The open pull requests no local branch is the head of: a fork's, or a branch never checked out. */
+export const pullRequestsWithoutBranch = (
+  pullRequests: OpenPullRequest[],
+  ownerRepo: string,
+  branches: CheckoutBranch[],
+): OpenPullRequest[] => {
+  const names = new Set(branches.map(({ name }) => name));
+  return pullRequests.filter(
+    (pullRequest) =>
+      !names.has(pullRequest.headRefName) ||
+      !sameRepo(pullRequest.headOwnerRepo, ownerRepo),
+  );
+};

package/src/checkout/sync.ts

@@ -0,0 +1,85 @@
+import type { IsoDateTime } from "../types/ids.ts";
+
+/** The commit a checkout has out, as its status line shows it. */
+export interface CheckoutHeadCommit {
+  shortSha: string;
+  subject: string;
+  committedAt: IsoDateTime;
+}
+
+/**
+ * What git says about one checkout, read fresh on every request. Ahead and
+ * behind are against the remote-tracking ref as of the last fetch.
+ */
+export interface CheckoutStatus {
+  path: string;
+  /** null on a detached HEAD */
+  branch: string | null;
+  /** null on a branch with no commit yet */
+  commit: CheckoutHeadCommit | null;
+  /** e.g. `origin/main`; null when the branch tracks nothing */
+  upstream: string | null;
+  /** null without an upstream, or when the upstream's ref no longer exists */
+  ahead: number | null;
+  behind: number | null;
+  modified: number;
+  untracked: number;
+}
+
+/** A checkout's status, for a surface offering Pull and Push on it. */
+export interface CheckoutSyncResponse {
+  status: CheckoutStatus;
+  /** whether a branch with no upstream can be published to `origin` */
+  hasOrigin: boolean;
+  /** the fetch failed; the status is then as of the previous one */
+  fetchError: string | null;
+}
+
+/**
+ * An upstream git still names but whose ref the last fetch pruned — GitHub
+ * deletes a merged head branch. Pushing would bring a merged branch back, so it
+ * is refused rather than treated as "no upstream" and published again.
+ */
+const upstreamGone = (upstream: string): string =>
+  `${upstream} no longer exists on the remote`;
+
+/**
+ * Why a pull would be refused, or null when it is offered. A surface shows the
+ * button only on null and the server throws the same sentence before running
+ * git, so the two cannot disagree on what "applicable" means.
+ *
+ * `behind` is as of the last fetch: a checkout reading 0 may still have
+ * something to pull, which is why a surface fetches before reading.
+ */
+export const pullRefusal = (status: CheckoutStatus): string | null => {
+  if (status.branch === null) return "a detached HEAD has nothing to pull into";
+  if (status.upstream === null) {
+    return `${status.branch} tracks no remote branch`;
+  }
+  if (status.behind === null) return upstreamGone(status.upstream);
+  if (status.behind === 0) {
+    return `${status.branch} is not behind ${status.upstream}`;
+  }
+  return null;
+};
+
+/**
+ * A branch with no upstream is published to `origin` rather than refused, so a
+ * new branch reaches GitHub from the same place. Diverged branches are offered
+ * too: git refuses the non-fast-forward itself, and its reason is what the
+ * user reads.
+ */
+export const pushRefusal = (
+  status: CheckoutStatus,
+  hasOrigin: boolean,
+): string | null => {
+  if (status.branch === null) return "a detached HEAD has no branch to push";
+  if (status.upstream === null) {
+    return hasOrigin ? null : "this repository has no origin remote";
+  }
+  if (status.ahead === null) return upstreamGone(status.upstream);
+  if (status.ahead === 0) {
+    return `${status.branch} has nothing to push to ${status.upstream}`;
+  }
+  return null;
+};

package/src/checkout/worktreeRemoval.ts

@@ -0,0 +1,136 @@
+import type { BranchPullRequestHead } from "./overview.ts";
+
+/**
+ * What removing a worktree would lose, and the refusals a surface and the
+ * server both ask before anything is deleted. Browser-safe: the reads and the
+ * removal itself are `@reviewflow/sdk/git`'s.
+ *
+ * **Refuse, never force.** An auto-remove that eats one uncommitted file loses
+ * trust for good, so nothing here passes `--force` or `-D`: a dirty worktree, a
+ * commit no remote holds, a lock or a process inside is refused with what to
+ * do, and git stays the last guard for a file written in between.
+ */
+
+export interface WorktreeRemovalStatus {
+  /** the worktree, absolute */
+  path: string;
+  /** the main checkout holds the repository's `.git`: it is never removed */
+  main: boolean;
+  /** null on a detached HEAD: there is no branch to offer deleting */
+  branch: string | null;
+  /** tracked files with changes; `git worktree remove` refuses while either is non-zero */
+  modified: number;
+  untracked: number;
+  /**
+   * Commits on HEAD that exist only in this clone: reachable from no
+   * remote-tracking ref and from no kept sha (a pull request head, which GitHub
+   * keeps after the head branch is deleted). git has no guard of its own here.
+   */
+  unpushedCommits: number;
+  /** why git holds it locked, `""` without a reason; null when it is not locked */
+  lock: string | null;
+  /**
+   * Processes whose working directory is inside: a shell, an editor, an agent
+   * that would lose the ground under it. Null when it cannot be told (no
+   * `lsof`), which refuses nothing.
+   */
+  processesInside: number | null;
+  /**
+   * Ignored files, relative to the worktree, not symlinks, that the main
+   * checkout does not have: `git worktree remove` deletes them without asking
+   * and nothing else holds a copy. A warning, not a refusal: an ignored file is
+   * usually ignored because it is disposable.
+   */
+  localOnlyIgnored: string[];
+}
+
+const fileCount = (count: number, kind: string): string | null =>
+  count === 0 ? null : `${String(count)} ${kind} file${count === 1 ? "" : "s"}`;
+
+export const mainWorktreeRefusal =
+  "This is the main checkout, which holds the repository: it is never removed.";
+
+export const dirtyRefusal = ({
+  modified,
+  untracked,
+}: Pick<WorktreeRemovalStatus, "modified" | "untracked">): string | null => {
+  const parts = [
+    fileCount(modified, "modified"),
+    fileCount(untracked, "untracked"),
+  ].filter((part) => part !== null);
+  if (parts.length === 0) return null;
+  return `${parts.join(" and ")}: git would refuse to remove this worktree. Commit or discard them first.`;
+};
+
+export const unpushedRefusal = (count: number): string | null => {
+  if (count === 0) return null;
+  const subject =
+    count === 1 ? "1 commit exists" : `${String(count)} commits exist`;
+  return `${subject} only in this clone, on no remote branch and in no pull request. Push them first.`;
+};
+
+export const lockRefusal = (lock: string | null): string | null => {
+  if (lock === null) return null;
+  const reason = lock === "" ? "" : ` (${lock})`;
+  return `git holds this worktree locked${reason}, usually by a Claude Code process still running in it. Exit it first.`;
+};
+
+export const processesRefusal = (count: number | null): string | null => {
+  if (count === null || count === 0) return null;
+  const subject =
+    count === 1 ? "1 process runs" : `${String(count)} processes run`;
+  return `${subject} inside this worktree (a shell, an editor or an agent): removing it would pull the directory out from under them. Exit them first.`;
+};
+
+/**
+ * Every reason the removal is refused, in the order to act on them; empty when
+ * it may go ahead. The server reads the status again and asks the same
+ * question before git touches the disk.
+ */
+export const worktreeRemovalRefusals = (
+  status: WorktreeRemovalStatus,
+): string[] => {
+  if (status.main) return [mainWorktreeRefusal];
+  return [
+    dirtyRefusal(status),
+    unpushedRefusal(status.unpushedCommits),
+    lockRefusal(status.lock),
+    processesRefusal(status.processesInside),
+  ].filter((refusal) => refusal !== null);
+};
+
+/** The first refusal, or null when the removal may go ahead. */
+export const worktreeRemovalRefusal = (
+  status: WorktreeRemovalStatus,
+): string | null => worktreeRemovalRefusals(status)[0] ?? null;
+
+/** What a removal did: the worktree is gone; the branch deletion, asked for or not, may have been refused. */
+export interface WorktreeRemovalResult {
+  path: string;
+  /** the branch `git branch -d` was run on; null when not asked, or on a detached HEAD */
+  branch: string | null;
+  /** git's refusal to delete the branch (unmerged, usually); the removal stands */
+  branchError: string | null;
+}
+
+/**
+ * `GET /api/repos/worktree-status?repo=<owner/repo>&worktree=<path>` — what
+ * removing the worktree would lose, its branch's pull request heads counted as
+ * pushed.
+ */
+export interface WorktreeRemovalStatusResponse {
+  status: WorktreeRemovalStatus;
+  /** the pull requests of its branch; empty on a detached HEAD or when GitHub failed */
+  pullRequests: BranchPullRequestHead[];
+  /** why GitHub could not be read: its heads then prove nothing, the count errs toward refusing */
+  pullRequestsError: string | null;
+}
+
+/**
+ * `POST /api/repos/worktree-remove?repo=<owner/repo>&worktree=<path>` —
+ * answered once git has removed it, or with the first refusal as a 400.
+ */
+export interface WorktreeRemovalRequest {
+  /** run `git branch -d` after the removal; a refusal is reported, never fatal */
+  deleteBranch: boolean;
+}

package/src/config/defaultRepoPaths.ts

@@ -0,0 +1,2 @@
+/** The repositories folders searched when `config.json` sets neither `repoPaths` nor the legacy `defaultRepoPath`. */
+export const defaultRepoPaths: readonly string[] = ["~/dev/"];

package/src/config/insertCheckoutEntry.ts

@@ -1,3 +1,9 @@
+import {
+  isRecord,
+  parseConfigText,
+  stringifyConfig,
+} from "./parseConfigText.ts";
+
 export interface InsertedCheckoutEntry {
   /** the config text with the entry in `repos` */
   source: string;
@@ -5,9 +11,6 @@ export interface InsertedCheckoutEntry {
   cursor: number;
 }
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === "object" && value !== null && !Array.isArray(value);
-
 /**
  * `"owner/repo": ""` added to `repos` of the app's config text, so an editor
  * can open on it with the cursor where the checkout path is typed. Nothing is
@@ -21,17 +24,8 @@ export const insertCheckoutEntry = (
   source: string,
   ownerRepo: string,
 ): InsertedCheckoutEntry | null => {
-  let parsed: unknown;
-  if (source.trim() === "") {
-    parsed = {};
-  } else {
-    try {
-      parsed = JSON.parse(source);
-    } catch {
-      return null;
-    }
-  }
-  if (!isRecord(parsed)) return null;
+  const parsed = parseConfigText(source);
+  if (parsed === null) return null;
   const repos = parsed.repos ?? {};
   if (!isRecord(repos)) return null;
 
@@ -41,7 +35,7 @@ export const insertCheckoutEntry = (
   );
   const key = existing ?? ownerRepo;
   const next = existing === undefined ? { ...repos, [key]: "" } : repos;
-  const text = `${JSON.stringify({ ...parsed, repos: next }, null, 2)}\n`;
+  const text = stringifyConfig({ ...parsed, repos: next });
 
   // the value follows the key on the same line; the same key may appear
   // earlier under another top-level key

package/src/config/parseConfigText.ts

@@ -0,0 +1,23 @@
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/**
+ * The app's config text as an object, a blank text being an empty config.
+ * `null` when the text is not a json object: the user's own text is not
+ * guessed at.
+ */
+export const parseConfigText = (
+  source: string,
+): Record<string, unknown> | null => {
+  if (source.trim() === "") return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(source);
+  } catch {
+    return null;
+  }
+  return isRecord(parsed) ? parsed : null;
+};
+
+export const stringifyConfig = (config: Record<string, unknown>): string =>
+  `${JSON.stringify(config, null, 2)}\n`;

package/src/config/repoPathsSetting.ts

@@ -0,0 +1,44 @@
+import { parseConfigText, stringifyConfig } from "./parseConfigText.ts";
+
+const repoPathsKeys = new Set(["repoPaths", "defaultRepoPath"]);
+
+const isStringArray = (value: unknown): value is string[] =>
+  Array.isArray(value) && value.every((item) => typeof item === "string");
+
+/**
+ * The repositories folders as the config text sets them: `repoPaths`, or the
+ * legacy `defaultRepoPath` as a one-folder list. `undefined` when neither is
+ * set or the text is unreadable, so the built-in default applies.
+ */
+export const readRepoPathsSetting = (source: string): string[] | undefined => {
+  const config = parseConfigText(source);
+  if (config === null) return undefined;
+  if (isStringArray(config.repoPaths)) return config.repoPaths;
+  if (typeof config.defaultRepoPath === "string") {
+    return [config.defaultRepoPath];
+  }
+  return undefined;
+};
+
+/**
+ * The config text with `repoPaths` set to `paths`, trimmed, without blanks or
+ * duplicates. It takes the place of the legacy `defaultRepoPath`, or goes
+ * first. An empty list is written as is: it searches no folder, unlike an
+ * unset key. Rewritten as two-space json, other keys kept. `null` when the
+ * text is not a json object.
+ */
+export const writeRepoPathsSetting = (
+  source: string,
+  paths: readonly string[],
+): string | null => {
+  const config = parseConfigText(source);
+  if (config === null) return null;
+  const repoPaths = [
+    ...new Set(paths.map((path) => path.trim()).filter((path) => path !== "")),
+  ];
+  const entries = Object.entries(config);
+  const at = entries.findIndex(([key]) => repoPathsKeys.has(key));
+  const others = entries.filter(([key]) => !repoPathsKeys.has(key));
+  others.splice(Math.max(at, 0), 0, ["repoPaths", repoPaths]);
+  return stringifyConfig(Object.fromEntries(others));
+};

package/src/diff/readingOrder.ts

@@ -381,9 +381,9 @@ const transitiveDependencies = (
 };
 
 /**
- * The root first, as `groupDiffPaths` has it; then a package before every
- * package it depends on, directly or through a package the change does not
- * touch. Alphabetical between two unrelated packages, and to break a cycle.
+ * A package before every package it depends on, directly or through a
+ * package the change does not touch. Alphabetical between two unrelated
+ * packages, and to break a cycle. The root last, as `groupDiffPaths` has it.
  */
 export const orderPackages = (
   names: readonly string[],
@@ -401,7 +401,7 @@ export const orderPackages = (
       (other) => other !== name && dependencies.get(other)!.has(name),
     );
 
-  const ordered = names.includes("") ? [""] : [];
+  const ordered: string[] = [];
   while (remaining.size > 0) {
     const sorted = [...remaining].toSorted((left, right) =>
       left.localeCompare(right),
@@ -411,6 +411,7 @@ export const orderPackages = (
     ordered.push(next);
     remaining.delete(next);
   }
+  if (names.includes("")) ordered.push("");
   return ordered;
 };
 

package/src/diff/themes.ts

@@ -5,6 +5,7 @@
  * same list the ui renders.
  */
 export const diffThemes = [
+  "reviewflow",
   "github",
   "github-high-contrast",
   "pierre",
@@ -28,13 +29,22 @@ export type DiffTheme = (typeof diffThemes)[number];
 export const isDiffTheme = (value: unknown): value is DiffTheme =>
   (diffThemes as readonly unknown[]).includes(value);
 
+export const defaultDiffTheme: DiffTheme = "reviewflow";
+
 interface DiffThemeFamily {
   label: string;
-  /** shiki theme names, the pierre ones resolved by `@pierre/diffs` itself */
+  /**
+   * shiki theme names, the pierre ones resolved by `@pierre/diffs` itself, the
+   * reviewflow ones registered by `@reviewflow/ui`
+   */
   themes: { light: string; dark: string };
 }
 
 const families: Record<DiffTheme, DiffThemeFamily> = {
+  reviewflow: {
+    label: "Reviewflow",
+    themes: { light: "reviewflow-light", dark: "reviewflow-dark" },
+  },
   github: {
     label: "GitHub",
     themes: { light: "github-light-default", dark: "github-dark-default" },
@@ -103,3 +113,21 @@ export const diffThemeOptions = diffThemes.map((theme) => ({
   value: theme,
   label: families[theme].label,
 }));
+
+/**
+ * The diff's code font: `alouette` is the design system's mono (Chivo Mono),
+ * `pierre` the system mono stack `@pierre/diffs` ships with, `custom` a font
+ * the user names (a CSS `font-family`, stored apart).
+ */
+export type DiffFont = "alouette" | "custom" | "pierre";
+
+export const isDiffFont = (value: unknown): value is DiffFont =>
+  value === "alouette" || value === "pierre" || value === "custom";
+
+export const defaultDiffFont: DiffFont = "alouette";
+
+export const diffFontOptions: { value: DiffFont; label: string }[] = [
+  { value: "alouette", label: "Alouette (Chivo Mono)" },
+  { value: "pierre", label: "Pierre (system mono)" },
+  { value: "custom", label: "Custom" },
+];

package/src/diff/types.ts

@@ -1,3 +1,5 @@
+import type { PullRequestCommit } from "../api/pullRequest.ts";
+
 /**
  * `show` is git's plain diff. `hide` is `git diff -w`, GitHub's "Hide
  * whitespace": a line whose only change is whitespace is not a change.
@@ -25,6 +27,116 @@ export interface DiffOmittedFile {
   reason: DiffOmittedReason;
 }
 
+/**
+ * `committed`: the merge base to `HEAD`, what the branch's pull request shows.
+ * `uncommitted`: `HEAD` to the working tree, the staged and unstaged changes
+ * and the untracked files.
+ */
+export type BranchDiffScope = "committed" | "uncommitted";
+
+export const isBranchDiffScope = (value: unknown): value is BranchDiffScope =>
+  value === "committed" || value === "uncommitted";
+
+/** What a checkout's branch is diffed against. */
+export interface BranchDiffBase {
+  /** the branch name, e.g. the repository's default branch */
+  name: string;
+  /** `origin/<name>` when that remote-tracking ref exists, `<name>` otherwise */
+  ref: string;
+  sha: string;
+}
+
+/**
+ * What a checked-out branch changed since it left its base. Nothing is fetched
+ * first: the base is as fresh as the last fetch, which is why its ref and sha
+ * travel with the patch.
+ */
+export interface CheckoutBranchDiffResponse {
+  scope: BranchDiffScope;
+  whitespace: DiffWhitespace;
+  /** null on a detached HEAD */
+  branch: string | null;
+  headSha: string;
+  /** null under `uncommitted`, which needs no base */
+  base: BranchDiffBase | null;
+  mergeBase: string | null;
+  /** a unified diff, `a/` and `b/` prefixes, the omitted files left out */
+  patch: string;
+  omitted: DiffOmittedFile[];
+  /** untracked files in `patch`; always 0 under `committed` */
+  untrackedCount: number;
+  /** every file in `patch`, once: the root's group first, then in patch order */
+  groups: DiffGroup[];
+}
+
+/** A checkout the app's config names, and the branch it has out. */
+export interface CheckoutRepo {
+  ownerRepo: string;
+  path: string;
+  /** false: not in the config, found directly under one of its `repoPaths` */
+  configured: boolean;
+  /** null on a detached HEAD, or when `problem` is set */
+  branch: string | null;
+  /** why the path cannot be used (missing, not this repository); null when it can */
+  problem: string | null;
+}
+
+/**
+ * `GET /api/repos` (`?refresh=1` scans the folders again) — the configured
+ * checkouts and the ones found directly under `repoPaths`, by `owner/repo`.
+ */
+export interface CheckoutReposResponse {
+  repos: CheckoutRepo[];
+  configPath: string;
+  /** expanded */
+  repoPaths: string[];
+  /** when the folders were scanned: the found checkouts are cached until a refresh or a change of `repoPaths` */
+  scannedAt: string;
+}
+
+/** A folder holding checkouts that `repoPaths` does not list yet. */
+export interface RepoPathSuggestion {
+  /** as it would be written in `repoPaths`: `~/…` under the home directory */
+  path: string;
+  /** the checkouts of GitHub repositories directly under it */
+  checkouts: number;
+}
+
+/** `GET /api/config/repo-paths/suggestions` */
+export interface RepoPathSuggestionsResponse {
+  suggestions: RepoPathSuggestion[];
+}
+
+/** A commit of a checkout, as git has it: the author is git's name, with no avatar. */
+export interface CheckoutCommit extends PullRequestCommit {
+  /** since the branch left its base: what the branch's diff carries */
+  onBranch: boolean;
+  /** reachable from a remote-tracking ref; null when the checkout has no remote */
+  pushed: boolean | null;
+}
+
+/** `GET /api/repos/commits` — the last commits of HEAD, newest first. */
+export interface CheckoutCommitsResponse {
+  /** null on a detached HEAD */
+  branch: string | null;
+  /** null when the base cannot be found: no commit is then marked on the branch */
+  base: BranchDiffBase | null;
+  /** every commit since the branch left its base, listed or not; null without a base */
+  onBranchCount: number | null;
+  commits: CheckoutCommit[];
+}
+
+/** `GET /api/repos/commit` — one commit against its first parent. */
+export interface CommitDiffResponse {
+  sha: string;
+  /** null for a root commit, diffed against the empty tree */
+  parentSha: string | null;
+  whitespace: DiffWhitespace;
+  patch: string;
+  omitted: DiffOmittedFile[];
+  groups: DiffGroup[];
+}
+
 /**
  * The files of one package: the nearest directory above them holding a
  * manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`,