diffcop 0.0.0-stage → 0.1.0

package/src/reporter/github/github-reporter.ts

@@ -0,0 +1,93 @@
+import { toError } from "@/util/errors";
+import type { ReviewResult } from "@/review/findings";
+import { thinkingLine, toolCallLine, verifyingLine } from "@/reporter/progress";
+import type { ReviewReporter, TextSink } from "@/reporter/review-reporter";
+import type { ReviewCommentFormatter } from "@/reporter/github/review-comment-formatter";
+import type { StickyComment } from "@/reporter/github/sticky-comment";
+
+export interface GitHubReporterOptions {
+  // Also log tool calls and thinking time, to see where a slow run went.
+  debug?: boolean;
+}
+
+export class GitHubReporter implements ReviewReporter {
+  readonly #comment: StickyComment;
+  readonly #formatter: ReviewCommentFormatter;
+  readonly #log: TextSink;
+  readonly #debug: boolean;
+
+  constructor(
+    comment: StickyComment,
+    formatter: ReviewCommentFormatter,
+    log: TextSink,
+    { debug = false }: GitHubReporterOptions = {},
+  ) {
+    this.#comment = comment;
+    this.#formatter = formatter;
+    this.#log = log;
+    this.#debug = debug;
+  }
+
+  // Only a status update, so a failure here (e.g. a GitHub API blip) doesn't
+  // stop the review; the result is still posted when it's done.
+  async started() {
+    await this.#post(this.#formatter.running()).catch((cause: unknown) => {
+      this.#warn(toError(cause));
+    });
+  }
+
+  // Re-posts the running status so the warning shows while the review runs.
+  async warning(message: string) {
+    this.#formatter.addWarning(message);
+    await this.started();
+  }
+
+  toolCall(toolName: string, input: string) {
+    if (this.#debug) {
+      this.#log.write(`${toolCallLine(toolName, input)}\n`);
+    }
+  }
+
+  thinking(durationMs: number) {
+    if (this.#debug) {
+      this.#log.write(`${thinkingLine(durationMs)}\n`);
+    }
+  }
+
+  // Logged even without debug: one line that explains a long second wait.
+  async verifying(findings: number) {
+    this.#log.write(`${verifyingLine(findings)}\n`);
+  }
+
+  // Unlike the status updates, a failed post throws: the run should fail, not
+  // pass with the comment stuck on "running".
+  async completed(result: ReviewResult) {
+    await this.#post(this.#formatter.review(result));
+  }
+
+  async failed(error: Error, { cancelled }: { cancelled: boolean }) {
+    await this.#post(
+      this.#formatter.failure(error, { cancelled: cancelled }),
+    ).catch((cause: unknown) => {
+      this.#warn(toError(cause));
+    });
+  }
+
+  // Every post respects a newer run's claim, the running status included, so a
+  // re-run of an older workflow run can't replace the newer run's review.
+  async #post(body: string) {
+    const posted = await this.#comment.upsert(body, { onlyIfOwned: true });
+    const where = this.#comment.location;
+    if (posted) {
+      this.#log.write(`Updated the diffcop comment on ${where}\n`);
+    } else {
+      this.#log.write(
+        `A newer run has taken over the diffcop comment on ${where}; leaving it alone\n`,
+      );
+    }
+  }
+
+  #warn(error: Error) {
+    this.#log.write(`Couldn't update the diffcop comment: ${String(error)}\n`);
+  }
+}

package/src/reporter/github/review-comment-formatter.ts

@@ -0,0 +1,144 @@
+import type { PullRequestContext } from "@/context/github/pull-request-context";
+import type { ReviewResult } from "@/review/findings";
+import { reviewLayout, sectionHeading } from "@/reporter/review-layout";
+import type { ReviewLayout, ReviewSection } from "@/reporter/review-layout";
+import { formatStats } from "@/reporter/stats";
+
+// GitHub rejects comment bodies over 65,536 characters.
+const MAX_COMMENT_CHARS = 60_000;
+const MAX_ERROR_CHARS = 2_000;
+
+const TRUNCATED = "_Review truncated; see the job log for the rest._";
+const BLOCK_GAP = "\n\n";
+
+// Blank lines inside <details> let GitHub render the body as markdown.
+function details(section: ReviewSection, body: string) {
+  const tag = section.open ? "<details open>" : "<details>";
+  return [
+    `${tag}<summary><b>${sectionHeading(section)}</b></summary>`,
+    "",
+    body,
+    "",
+    "</details>",
+  ].join("\n");
+}
+
+export interface ReviewCommentFormatterOptions {
+  // Scrubbed from everything posted, since PR comments aren't masked the way
+  // Actions logs are, and the reviewer can read files outside the repo.
+  secrets?: (string | undefined)[];
+}
+
+export class ReviewCommentFormatter {
+  readonly #pr: PullRequestContext;
+  readonly #secrets: string[];
+  readonly #warnings: string[] = [];
+
+  constructor(
+    pr: PullRequestContext,
+    { secrets = [] }: ReviewCommentFormatterOptions = {},
+  ) {
+    this.#pr = pr;
+    // Longest first, so a secret that contains another isn't left half-redacted.
+    this.#secrets = secrets
+      .filter((secret): secret is string => {
+        return Boolean(secret);
+      })
+      .toSorted((a, b) => {
+        return b.length - a.length;
+      });
+  }
+
+  // Shown at the top of every comment formatted after this.
+  addWarning(message: string) {
+    this.#warnings.push(message);
+  }
+
+  running() {
+    return this.#frame([
+      `⏳ Reviewing \`${this.#shortSha()}\`…${this.#runLink("Follow the run")}`,
+    ]);
+  }
+
+  failure(error: Error, { cancelled = false } = {}) {
+    if (cancelled) {
+      return this.#frame([
+        `⚪ The review of \`${this.#shortSha()}\` was cancelled before it finished.${this.#runLink("See the run")}`,
+      ]);
+    }
+    return this.#frame([
+      `❌ The review of \`${this.#shortSha()}\` failed.${this.#runLink("See the run log")}`,
+      "",
+      "```",
+      this.#errorMessage(error),
+      "```",
+    ]);
+  }
+
+  review(result: ReviewResult) {
+    const { stats } = result;
+    const footer = [`Reviewed ${this.#shortSha()}`, formatStats(stats)].join(
+      " · ",
+    );
+    return this.#frame([
+      this.#body(reviewLayout(result)),
+      "",
+      "---",
+      `<sub>${footer}${this.#runLink("run")}</sub>`,
+    ]);
+  }
+
+  // Truncates inside a section's body, so a cut never leaves <details> open.
+  #body({ headline, sections }: ReviewLayout) {
+    const top = `${headline.icon} **${headline.text}**`;
+    const blocks = [top];
+    let room = MAX_COMMENT_CHARS - top.length;
+    for (const section of sections) {
+      const body = this.#redact(section.body);
+      const block = details(section, body);
+      if (BLOCK_GAP.length + block.length <= room) {
+        blocks.push(block);
+        room -= BLOCK_GAP.length + block.length;
+        continue;
+      }
+      const ending = `${BLOCK_GAP}${TRUNCATED}`;
+      const overhead = BLOCK_GAP.length + details(section, ending).length;
+      const kept = body.slice(0, Math.max(0, room - overhead));
+      blocks.push(details(section, `${kept}${ending}`));
+      break;
+    }
+    return blocks.join(BLOCK_GAP);
+  }
+
+  #errorMessage(error: Error) {
+    const message = this.#redact(error.message);
+    // Keep the message inside its code fence.
+    return message.slice(0, MAX_ERROR_CHARS).replaceAll("```", "'''");
+  }
+
+  #redact(text: string) {
+    let redacted = text;
+    for (const secret of this.#secrets) {
+      redacted = redacted.replaceAll(secret, "***");
+    }
+    return redacted;
+  }
+
+  #frame(lines: string[]) {
+    const alerts = this.#warnings.flatMap((warning) => {
+      return ["> [!WARNING]", `> ${warning}`, ""];
+    });
+    return ["## diffcop review", "", ...alerts, ...lines].join("\n");
+  }
+
+  #shortSha() {
+    return this.#pr.headSha.slice(0, 7);
+  }
+
+  #runLink(label: string) {
+    if (!this.#pr.runUrl) {
+      return "";
+    }
+    return ` [${label}](${this.#pr.runUrl})`;
+  }
+}

package/src/reporter/github/sticky-comment.ts

@@ -0,0 +1,181 @@
+import { RequestError } from "@octokit/request-error";
+import { z } from "zod";
+import type { PullRequestContext } from "@/context/github/pull-request-context";
+import type { GitHubClient } from "@/github/github-client";
+import { unwrapResponse } from "@/github/unwrap-response";
+
+// Retries for creating the comment, on top of the first attempt.
+const CREATE_RETRIES = 3;
+
+// Hidden in the comment body so later runs find and edit the same comment.
+const MARKER = "<!-- diffcop:review -->";
+
+const issueComments = z.array(
+  z.object({
+    id: z.number(),
+    body: z.string().optional(),
+    user: z.object({ login: z.string() }).nullable(),
+  }),
+);
+
+const viewerQuery = z.object({ viewer: z.object({ login: z.string() }) });
+
+// Records which Actions run last claimed the comment, so a run that was
+// superseded doesn't overwrite the newer run's status.
+function runMarker(runId: string) {
+  return `<!-- diffcop:run=${runId} -->`;
+}
+
+function claimedRun(body: string) {
+  return body.match(/<!-- diffcop:run=(\d+) -->/)?.[1];
+}
+
+// Octokit's error message is only GitHub's response message, so say which
+// request failed and with what status.
+function describeFailure(cause: unknown) {
+  if (!(cause instanceof RequestError)) {
+    return cause;
+  }
+  const { method, url } = cause.request;
+  return new Error(
+    `GitHub API ${method} ${url} failed: ${cause.status} ${cause.message}`,
+    { cause: cause },
+  );
+}
+
+// Find-then-create isn't atomic, and GitHub can't create a comment only if absent,
+// so runs for one PR must be serialized (the workflow's `concurrency` group).
+export class StickyComment {
+  readonly #pr: PullRequestContext;
+  readonly #github: GitHubClient;
+  #login: Promise<string> | undefined;
+
+  constructor(pr: PullRequestContext, github: GitHubClient) {
+    this.#pr = pr;
+    this.#github = github;
+  }
+
+  get location() {
+    return `${this.#pr.repo}#${this.#pr.number}`;
+  }
+
+  // With `onlyIfOwned`, skips the write and returns false if a newer run has
+  // claimed the comment; a claim by an older (e.g. cancelled) run is taken over.
+  async upsert(body: string, { onlyIfOwned = false } = {}) {
+    try {
+      return await this.#upsert(body, onlyIfOwned);
+    } catch (error) {
+      throw describeFailure(error);
+    }
+  }
+
+  async #upsert(
+    body: string,
+    onlyIfOwned: boolean,
+    attempt = 1,
+  ): Promise<boolean> {
+    const { runId } = this.#pr;
+    const existing = await this.#find();
+    const claimedBy = existing?.body ? claimedRun(existing.body) : undefined;
+    if (
+      onlyIfOwned &&
+      runId &&
+      claimedBy &&
+      Number(claimedBy) > Number(runId)
+    ) {
+      return false;
+    }
+
+    const fullBody = [MARKER, ...(runId ? [runMarker(runId)] : []), body].join(
+      "\n",
+    );
+    if (existing) {
+      await this.#github.request(
+        "PATCH /repos/{owner}/{repo}/issues/comments/{comment_id}",
+        {
+          ...this.#repo(),
+          comment_id: existing.id,
+          body: fullBody,
+        },
+      );
+      return true;
+    }
+    try {
+      await this.#github.request(
+        "POST /repos/{owner}/{repo}/issues/{issue_number}/comments",
+        {
+          ...this.#repo(),
+          issue_number: this.#pr.number,
+          body: fullBody,
+          // GitHub can create the comment and still fail the response, so a
+          // blind retry would post a second one. Retry from the lookup instead.
+          request: { retries: 0 },
+        },
+      );
+    } catch (error) {
+      if (
+        attempt > CREATE_RETRIES ||
+        !(error instanceof RequestError) ||
+        error.status < 500
+      ) {
+        throw error;
+      }
+      await Bun.sleep(attempt ** 2 * this.#github.retryAfterBaseValue);
+      return this.#upsert(body, onlyIfOwned, attempt + 1);
+    }
+    return true;
+  }
+
+  async #find() {
+    const pages = this.#github.paginate.iterator(
+      "GET /repos/{owner}/{repo}/issues/{issue_number}/comments",
+      {
+        ...this.#repo(),
+        issue_number: this.#pr.number,
+        per_page: 100,
+      },
+    );
+    // Anyone who can comment can paste the marker, so only our own comment counts.
+    const login = await this.#viewerLogin();
+    for await (const { data } of pages) {
+      const comments = unwrapResponse(
+        issueComments.safeParse(data),
+        "GitHub's comment list",
+      );
+      const match = comments.find((c) => {
+        return c.user?.login === login && c.body?.includes(MARKER);
+      });
+      if (match) {
+        return match;
+      }
+    }
+    return undefined;
+  }
+
+  // GraphQL, since REST's GET /user rejects the Actions installation token.
+  async #viewerLogin() {
+    this.#login ??= this.#github
+      .graphql<unknown>("query { viewer { login } }")
+      .then((result) => {
+        const { viewer } = unwrapResponse(
+          viewerQuery.safeParse(result),
+          "GitHub's viewer query",
+        );
+        return viewer.login;
+      });
+    try {
+      return await this.#login;
+    } catch (error) {
+      this.#login = undefined;
+      throw error;
+    }
+  }
+
+  #repo() {
+    const [owner = "", repo = ""] = this.#pr.repo.split("/");
+    return {
+      owner: owner,
+      repo: repo,
+    };
+  }
+}

package/src/reporter/progress.ts

@@ -0,0 +1,12 @@
+export function toolCallLine(toolName: string, input: string) {
+  return `› ${toolName} ${input}`;
+}
+
+// Shown so slow runs make clear where the time went.
+export function thinkingLine(durationMs: number) {
+  return `› thinking (${Math.round(durationMs / 1000)}s)`;
+}
+
+export function verifyingLine(findings: number) {
+  return `› verifying ${findings} finding${findings === 1 ? "" : "s"}…`;
+}