mergie-cli 0.1.0

package/src/services/git.ts

@@ -0,0 +1,297 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { bunRunner } from "@/services/exec.ts";
+import type { CommandRunner } from "@/services/exec.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Structured information about a single git commit.
+ */
+export interface CommitInfo {
+  /** Full 40-character commit SHA. */
+  sha: string;
+  /** Abbreviated 7-character commit SHA. */
+  shortSha: string;
+  /** The first line of the commit message. */
+  subject: string;
+  /** Display name of the commit author. */
+  authorName: string;
+  /** Email address of the commit author. */
+  authorEmail: string;
+  /**
+   * ISO 8601 timestamp of the author date, e.g. `2024-06-01T09:00:00+00:00`.
+   * Includes timezone offset so callers can display local time.
+   */
+  isoDate: string;
+}
+
+/**
+ * The git service provides all git operations needed for reviewing a PR.
+ * Every command is executed with `git -C <cloneDir>` so the instance is
+ * bound to one local repository directory.
+ */
+export interface GitService {
+  /**
+   * Ensure the repository is available locally and up to date.
+   *
+   * - If `<cloneDir>/.git` is absent: runs `git clone <sshUrl> <cloneDir>`.
+   * - If present: runs `git -C <cloneDir> fetch origin <refs...>`.
+   *
+   * Throws if the git process exits with a non-zero code; the error message
+   * includes stderr so callers can surface the reason.
+   *
+   * @param sshUrl - SSH remote URL, e.g. `git@github.com:org/repo.git`.
+   * @param refs   - Ref names / refspecs to fetch (e.g. `["main", "refs/pull/1/head"]`).
+   */
+  cloneOrFetch(sshUrl: string, refs: string[]): Promise<void>;
+
+  /**
+   * List commits in the range `startSha..endSha`, ordered oldest → newest.
+   *
+   * The `startSha` commit itself is excluded (standard git two-dot range
+   * semantics). Returns an empty array when the range contains no commits.
+   *
+   * @param startSha - Exclusive lower bound (SHA or any git revision).
+   * @param endSha   - Inclusive upper bound (SHA or any git revision).
+   */
+  listCommits(startSha: string, endSha: string): Promise<CommitInfo[]>;
+
+  /**
+   * Compute the best common ancestor of two commits.
+   *
+   * Equivalent to `git merge-base a b`. Returns the trimmed SHA string.
+   *
+   * @param a - First commit SHA or ref.
+   * @param b - Second commit SHA or ref.
+   */
+  mergeBase(a: string, b: string): Promise<string>;
+
+  /**
+   * Return the raw text content of a file at a specific commit.
+   *
+   * Runs `git show <sha>:<path>`. Returns `null` when the command exits
+   * non-zero (file absent at that ref, deleted, or binary unreadable as text).
+   *
+   * @param sha  - Commit SHA (or any git revision).
+   * @param path - Repo-relative file path.
+   */
+  fileAtRef(sha: string, path: string): Promise<string | null>;
+
+  /**
+   * Produce a unified diff between two commits, optionally restricted to a
+   * subset of file paths.
+   *
+   * Runs `git diff <startSha> <endSha> [-- <paths...>]`. Returns the raw
+   * unified-diff string (suitable for passing to `parseUnifiedDiff`). Returns
+   * an empty string when there are no differences.
+   *
+   * @param startSha - Base commit SHA.
+   * @param endSha   - Head commit SHA.
+   * @param paths    - Optional list of paths to restrict the diff to.
+   * @param ignoreWhitespace - When true, collapse whitespace-only changes
+   *                           (passes `--ignore-all-space` to git).
+   */
+  rawDiff(startSha: string, endSha: string, paths?: string[], ignoreWhitespace?: boolean): Promise<string>;
+
+  /**
+   * Like {@link rawDiff}, but in `--word-diff=porcelain` form (parsed by
+   * `parseWordDiff` into intra-line changed ranges). Returns an empty string
+   * when there are no differences.
+   */
+  rawWordDiff(startSha: string, endSha: string, paths?: string[], ignoreWhitespace?: boolean): Promise<string>;
+
+  /**
+   * Full-file unified diff for a single path with all context expanded (large
+   * `-U`), suitable for a split full-file view. Returns the raw diff string.
+   */
+  fullFileDiff(startSha: string, endSha: string, path: string, ignoreWhitespace?: boolean): Promise<string>;
+
+  /**
+   * Like {@link fullFileDiff}, but in `--word-diff=porcelain` form for the
+   * split full-file view's intra-line highlighting.
+   */
+  fullFileWordDiff(startSha: string, endSha: string, path: string, ignoreWhitespace?: boolean): Promise<string>;
+
+  /**
+   * Ensure a detached git worktree exists with the tree checked out at `sha`,
+   * and return its absolute path. Worktrees are cached per-SHA under a `wt`
+   * directory beside the clone; a symbol lookup can then run `sem`/`rg` against
+   * the on-disk files of that exact commit without disturbing the main clone.
+   *
+   * @param sha - Commit SHA to check out.
+   */
+  ensureWorktree(sha: string): Promise<string>;
+}
+
+// ---------------------------------------------------------------------------
+// Format string constants
+// ---------------------------------------------------------------------------
+
+/** Field separator between commit fields — ASCII Unit Separator (rarely appears in commit data). */
+const FIELD_SEP = "\x1f" as const;
+
+/** Record separator between commits — ASCII Record Separator. */
+const RECORD_SEP = "\x1e" as const;
+
+/**
+ * git log --format string that produces one record per commit.
+ * Fields: %H (full sha) %x1f %h (short sha) %x1f %s (subject) %x1f
+ *         %an (author name) %x1f %ae (author email) %x1f %aI (ISO 8601 author date)
+ * Records are separated by %x1e.
+ */
+const LOG_FORMAT =
+  `--format=%H${FIELD_SEP}%h${FIELD_SEP}%s${FIELD_SEP}%an${FIELD_SEP}%ae${FIELD_SEP}%aI${RECORD_SEP}` as const;
+
+/**
+ * Extra `git diff` flags to emit the porcelain word-diff. The regex makes each
+ * identifier run one token and every other non-space character its own token,
+ * so highlighting lands on whole words rather than whitespace-delimited chunks.
+ */
+const WORD_DIFF_ARGS = ["--word-diff=porcelain", "--word-diff-regex=[A-Za-z0-9_]+|[^[:space:]]"] as const;
+
+/**
+ * `git diff` option that collapses whitespace-only differences: a line whose
+ * only change is indentation/spacing stops showing as changed, and a hunk that
+ * was purely whitespace disappears. Equivalent to GitHub's "Hide whitespace".
+ */
+const IGNORE_WHITESPACE_ARG = "--ignore-all-space" as const;
+
+/** The whitespace-ignoring arg as a 0- or 1-element array, for arg splicing. */
+function wsArgs(ignoreWhitespace: boolean | undefined): readonly string[] {
+  return ignoreWhitespace ? [IGNORE_WHITESPACE_ARG] : [];
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/** Parse a single record (already split on RECORD_SEP) into CommitInfo. */
+function parseRecord(record: string): CommitInfo | null {
+  const record_ = record.trim();
+  if (record_ === "") return null;
+  const parts = record_.split(FIELD_SEP);
+  const [sha, shortSha, subject, authorName, authorEmail, isoDate] = parts;
+  if (!sha || !shortSha || !subject || !authorName || !authorEmail || !isoDate) return null;
+  return { sha, shortSha, subject, authorName, authorEmail, isoDate };
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a `GitService` bound to `cloneDir`, using `runner` for subprocess
+ * execution. Defaults to the real Bun-backed runner.
+ *
+ * @param cloneDir - Absolute path to the local repository directory.
+ * @param runner   - Command runner to use; defaults to `bunRunner`.
+ */
+export function createGitService(
+  cloneDir: string,
+  runner: CommandRunner = bunRunner,
+): GitService {
+  return {
+    async cloneOrFetch(sshUrl, refs) {
+      const hasGit = existsSync(`${cloneDir}/.git`);
+      const args: string[] = hasGit
+        ? ["-C", cloneDir, "fetch", "origin", ...refs]
+        : ["clone", sshUrl, cloneDir];
+
+      const result = await runner.run("git", args);
+      if (result.exitCode !== 0) {
+        throw new Error(`git operation failed: ${result.stderr}`);
+      }
+    },
+
+    async listCommits(startSha, endSha) {
+      const result = await runner.run("git", [
+        "-C",
+        cloneDir,
+        "log",
+        LOG_FORMAT,
+        `${startSha}..${endSha}`,
+      ]);
+
+      if (result.exitCode !== 0) {
+        throw new Error(`git log failed: ${result.stderr}`);
+      }
+
+      const commits: CommitInfo[] = result.stdout
+        .split(RECORD_SEP)
+        .map(parseRecord)
+        .filter((c): c is CommitInfo => c !== null)
+        .reverse(); // git log is newest-first; we want oldest-first
+
+      return commits;
+    },
+
+    async mergeBase(a, b) {
+      const result = await runner.run("git", ["-C", cloneDir, "merge-base", a, b]);
+      if (result.exitCode !== 0) {
+        throw new Error(`git merge-base failed: ${result.stderr}`);
+      }
+      return result.stdout.trim();
+    },
+
+    async fileAtRef(sha, path) {
+      const result = await runner.run("git", ["-C", cloneDir, "show", `${sha}:${path}`]);
+      if (result.exitCode !== 0) return null;
+      return result.stdout;
+    },
+
+    async rawDiff(startSha, endSha, paths, ignoreWhitespace) {
+      const args: string[] = ["-C", cloneDir, "diff", ...wsArgs(ignoreWhitespace), startSha, endSha];
+      if (paths !== undefined && paths.length > 0) {
+        args.push("--", ...paths);
+      }
+      const result = await runner.run("git", args);
+      if (result.exitCode !== 0) {
+        throw new Error(`git diff failed: ${result.stderr}`);
+      }
+      return result.stdout;
+    },
+
+    async rawWordDiff(startSha, endSha, paths, ignoreWhitespace) {
+      const args: string[] = ["-C", cloneDir, "diff", ...wsArgs(ignoreWhitespace), ...WORD_DIFF_ARGS, startSha, endSha];
+      if (paths !== undefined && paths.length > 0) {
+        args.push("--", ...paths);
+      }
+      const result = await runner.run("git", args);
+      if (result.exitCode !== 0) {
+        throw new Error(`git word-diff failed: ${result.stderr}`);
+      }
+      return result.stdout;
+    },
+
+    async fullFileDiff(startSha, endSha, path, ignoreWhitespace) {
+      const args: string[] = ["-C", cloneDir, "diff", ...wsArgs(ignoreWhitespace), startSha, endSha, "-U1000000", "--", path];
+      const result = await runner.run("git", args);
+      if (result.exitCode !== 0) {
+        throw new Error(`git diff failed: ${result.stderr}`);
+      }
+      return result.stdout;
+    },
+
+    async fullFileWordDiff(startSha, endSha, path, ignoreWhitespace) {
+      const args: string[] = ["-C", cloneDir, "diff", ...wsArgs(ignoreWhitespace), ...WORD_DIFF_ARGS, startSha, endSha, "-U1000000", "--", path];
+      const result = await runner.run("git", args);
+      if (result.exitCode !== 0) {
+        throw new Error(`git word-diff failed: ${result.stderr}`);
+      }
+      return result.stdout;
+    },
+
+    async ensureWorktree(sha) {
+      const wt: string = join(dirname(cloneDir), "wt", sha);
+      if (existsSync(wt)) return wt;
+      const result = await runner.run("git", ["-C", cloneDir, "worktree", "add", "--force", "--detach", wt, sha]);
+      if (result.exitCode !== 0) {
+        throw new Error(`git worktree add failed: ${result.stderr}`);
+      }
+      return wt;
+    },
+  };
+}

package/src/services/github.ts

@@ -0,0 +1,300 @@
+import { bunRunner, type CommandRunner } from "@/services/exec.ts";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/**
+ * A single inline diff comment fetched from GitHub.
+ * Maps from the GitHub REST API's pull request review comment object.
+ */
+export interface GithubComment {
+  /** GitHub's numeric comment ID. */
+  id: number;
+  /** File path the comment is anchored to. */
+  path: string;
+  /** Which side of the diff this comment sits on. */
+  side: "LEFT" | "RIGHT";
+  /**
+   * The last line of the commented range (or the single line for a single-line
+   * comment). Null when GitHub omits it (shouldn't happen for inline comments,
+   * but modelled defensively).
+   */
+  line: number | null;
+  /**
+   * First line of a multi-line comment span. Null for single-line comments.
+   */
+  startLine: number | null;
+  /** The commit SHA the comment was made against. */
+  commitId: string;
+  /** Markdown body of the comment. */
+  body: string;
+  /** GitHub login of the comment author. */
+  author: string;
+  /** ISO-8601 creation timestamp. */
+  createdAtIso: string;
+  /**
+   * ID of the parent comment if this is a reply; null for root comments.
+   */
+  inReplyToId: number | null;
+  /** The diff hunk context string returned by GitHub. */
+  diffHunk: string;
+  /** Full URL to view the comment on GitHub. */
+  htmlUrl: string;
+}
+
+/**
+ * A root comment plus all its direct replies, ordered by creation time.
+ */
+export interface CommentThread {
+  /** The top-level (non-reply) comment that started the thread. */
+  root: GithubComment;
+  /** All replies to the root, sorted oldest-first. */
+  replies: GithubComment[];
+}
+
+/**
+ * Input for posting a new inline comment to GitHub.
+ * When `startLine` is provided the comment spans from `startLine` to `line`
+ * (a whole-hunk multi-line comment).
+ */
+export interface PostCommentInput {
+  /** Markdown body to post. */
+  body: string;
+  /** The commit SHA to anchor the comment to. */
+  commitId: string;
+  /** File path being commented on. */
+  path: string;
+  /** Which side of the diff to post on. */
+  side: "LEFT" | "RIGHT";
+  /** The last (or only) line of the comment range. */
+  line: number;
+  /** First line for a multi-line span. Omit for a single-line comment. */
+  startLine?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Internal raw shape from the GitHub API
+// ---------------------------------------------------------------------------
+
+/** Raw shape of one item in the GitHub pull request review comments array. */
+interface RawGithubComment {
+  id: number;
+  path: string;
+  side: string;
+  line: number | null;
+  start_line: number | null;
+  commit_id: string;
+  body: string;
+  user: { login: string };
+  created_at: string;
+  in_reply_to_id: number | null;
+  diff_hunk: string;
+  html_url: string;
+}
+
+/** Minimal shape of the response from posting/replying a comment. */
+interface RawPostedComment {
+  id: number;
+  html_url: string;
+}
+
+/** The GitHub inline-comment service bound to one pull request. */
+export type GithubService = ReturnType<typeof createGithubService>;
+
+// ---------------------------------------------------------------------------
+// Service factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a GitHub service bound to a specific pull request.
+ * All GitHub API calls are made via `gh api` through the injected runner.
+ *
+ * @param ref - Owner, repo, and PR number identifying the pull request.
+ * @param runner - Command runner to use; defaults to the real Bun runner.
+ */
+export function createGithubService(
+  ref: { owner: string; repo: string; number: number },
+  runner: CommandRunner = bunRunner,
+) {
+  const { owner, repo, number: prNumber } = ref;
+  const base = `repos/${owner}/${repo}`;
+
+  /** Throws a descriptive error if the command result indicates failure. */
+  function assertSuccess(stderr: string, exitCode: number): void {
+    if (exitCode !== 0) {
+      throw new Error(stderr || `gh exited with code ${exitCode}`);
+    }
+  }
+
+  /** Normalises the raw GitHub side string to the typed union. */
+  function normaliseSide(side: string): "LEFT" | "RIGHT" {
+    return side === "LEFT" ? "LEFT" : "RIGHT";
+  }
+
+  /** Maps one raw GitHub comment object to a typed GithubComment. */
+  function mapComment(raw: RawGithubComment): GithubComment {
+    return {
+      id: raw.id,
+      path: raw.path,
+      side: normaliseSide(raw.side),
+      line: raw.line,
+      startLine: raw.start_line,
+      commitId: raw.commit_id,
+      body: raw.body,
+      author: raw.user.login,
+      createdAtIso: raw.created_at,
+      inReplyToId: raw.in_reply_to_id,
+      diffHunk: raw.diff_hunk,
+      htmlUrl: raw.html_url,
+    };
+  }
+
+  return {
+    /**
+     * The authenticated user's GitHub login (via `gh api user --jq .login`).
+     * Returns an empty string if the call fails (offline / unauthenticated) so
+     * callers can degrade gracefully rather than throw.
+     */
+    async viewer(): Promise<string> {
+      const { stdout, exitCode } = await runner.run("gh", ["api", "user", "--jq", ".login"]);
+      return exitCode === 0 ? stdout.trim() : "";
+    },
+
+    /**
+     * Fetches all inline review comments for the pull request.
+     * Follows pagination automatically via `--paginate`.
+     */
+    async listReviewComments(): Promise<GithubComment[]> {
+      const { stdout, stderr, exitCode } = await runner.run("gh", [
+        "api",
+        `${base}/pulls/${prNumber}/comments`,
+        "--paginate",
+      ]);
+      assertSuccess(stderr, exitCode);
+      const raw = JSON.parse(stdout) as RawGithubComment[];
+      return raw.map(mapComment);
+    },
+
+    /**
+     * Groups a flat list of comments into reply threads.
+     * A thread has one root comment (no inReplyToId) and zero or more replies.
+     * Orphan replies (whose parent is absent from the list) become their own
+     * single-comment thread to avoid silently dropping data.
+     * Replies within each thread are sorted oldest-first.
+     */
+    buildThreads(comments: GithubComment[]): CommentThread[] {
+      const byId = new Map<number, GithubComment>(comments.map((c) => [c.id, c]));
+      const replyBuckets = new Map<number, GithubComment[]>();
+      const roots: GithubComment[] = [];
+      const orphans: GithubComment[] = [];
+
+      for (const comment of comments) {
+        if (comment.inReplyToId === null) {
+          roots.push(comment);
+        } else if (byId.has(comment.inReplyToId)) {
+          const bucket = replyBuckets.get(comment.inReplyToId) ?? [];
+          bucket.push(comment);
+          replyBuckets.set(comment.inReplyToId, bucket);
+        } else {
+          orphans.push(comment);
+        }
+      }
+
+      const threads: CommentThread[] = roots.map((root) => ({
+        root,
+        replies: (replyBuckets.get(root.id) ?? []).sort(
+          (a, b) => a.createdAtIso.localeCompare(b.createdAtIso),
+        ),
+      }));
+
+      // Orphans form solo threads so no comment is silently dropped.
+      for (const orphan of orphans) {
+        threads.push({ root: orphan, replies: [] });
+      }
+
+      return threads;
+    },
+
+    /**
+     * Posts a new inline comment on the pull request.
+     * Passing `startLine` causes a multi-line (whole-hunk) comment spanning
+     * `startLine` through `line` on the same side.
+     */
+    async postComment(input: PostCommentInput): Promise<{ id: number; htmlUrl: string }> {
+      const args = [
+        "api",
+        `${base}/pulls/${prNumber}/comments`,
+        "--method",
+        "POST",
+        "-f",
+        `body=${input.body}`,
+        "-f",
+        `commit_id=${input.commitId}`,
+        "-f",
+        `path=${input.path}`,
+        "-f",
+        `side=${input.side}`,
+        "-F",
+        `line=${input.line}`,
+      ];
+
+      if (input.startLine !== undefined) {
+        args.push("-F", `start_line=${input.startLine}`, "-f", `start_side=${input.side}`);
+      }
+
+      const { stdout, stderr, exitCode } = await runner.run("gh", args);
+      assertSuccess(stderr, exitCode);
+      const raw = JSON.parse(stdout) as RawPostedComment;
+      return { id: raw.id, htmlUrl: raw.html_url };
+    },
+
+    /**
+     * Updates the body of an existing inline comment.
+     */
+    async editComment(id: number, body: string): Promise<void> {
+      const { stderr, exitCode } = await runner.run("gh", [
+        "api",
+        `${base}/pulls/comments/${id}`,
+        "--method",
+        "PATCH",
+        "-f",
+        `body=${body}`,
+      ]);
+      assertSuccess(stderr, exitCode);
+    },
+
+    /**
+     * Permanently deletes an inline comment from GitHub.
+     */
+    async deleteComment(id: number): Promise<void> {
+      const { stderr, exitCode } = await runner.run("gh", [
+        "api",
+        `${base}/pulls/comments/${id}`,
+        "--method",
+        "DELETE",
+      ]);
+      assertSuccess(stderr, exitCode);
+    },
+
+    /**
+     * Posts a reply to an existing inline comment thread.
+     */
+    async replyToComment(
+      inReplyToId: number,
+      body: string,
+    ): Promise<{ id: number; htmlUrl: string }> {
+      const { stdout, stderr, exitCode } = await runner.run("gh", [
+        "api",
+        `${base}/pulls/${prNumber}/comments/${inReplyToId}/replies`,
+        "--method",
+        "POST",
+        "-f",
+        `body=${body}`,
+      ]);
+      assertSuccess(stderr, exitCode);
+      const raw = JSON.parse(stdout) as RawPostedComment;
+      return { id: raw.id, htmlUrl: raw.html_url };
+    },
+  };
+}