@reviewflow/sdk 0.0.0-stage → 6.21.0

package/src/github/pullRequestHead.ts

@@ -0,0 +1,65 @@
+import type { PullRequestRef } from "../api/pullRequest.ts";
+import type { GitHubTransport } from "./transport.ts";
+
+export const pullRequestHeadQuery = `query PullRequestHead($owner: String!, $name: String!, $number: Int!) {
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) {
+      state
+      headRefName
+      isCrossRepository
+      headRepositoryOwner { login }
+    }
+  }
+}`;
+
+export interface PullRequestHeadData {
+  repository: {
+    pullRequest: {
+      state: "CLOSED" | "MERGED" | "OPEN";
+      headRefName: string;
+      isCrossRepository: boolean;
+      headRepositoryOwner: { login: string } | null;
+    } | null;
+  } | null;
+}
+
+type GhPullRequestState = NonNullable<
+  NonNullable<PullRequestHeadData["repository"]>["pullRequest"]
+>["state"];
+
+export interface PullRequestHead {
+  state: "closed" | "merged" | "open";
+  branch: string;
+  /** the head repository's owner when it is a fork, null when the branch is on origin */
+  fork: string | null;
+}
+
+const headStates: Record<GhPullRequestState, PullRequestHead["state"]> = {
+  CLOSED: "closed",
+  MERGED: "merged",
+  OPEN: "open",
+};
+
+/** Raises with GitHub's reason when the pull request is not one the token can read. */
+export const fetchPullRequestHead = async (
+  transport: GitHubTransport,
+  { ownerRepo, number }: PullRequestRef,
+): Promise<PullRequestHead> => {
+  const [owner = "", name = ""] = ownerRepo.split("/");
+  const { data, errors } = await transport.graphql<PullRequestHeadData>(
+    pullRequestHeadQuery,
+    { owner, name, number },
+  );
+  const pullRequest = data?.repository?.pullRequest ?? null;
+  if (pullRequest === null) {
+    const reason = errors.length > 0 ? errors.join("; ") : "not found";
+    throw new Error(`${ownerRepo}#${String(number)}: ${reason}`);
+  }
+  return {
+    state: headStates[pullRequest.state],
+    branch: pullRequest.headRefName,
+    fork: pullRequest.isCrossRepository
+      ? (pullRequest.headRepositoryOwner?.login ?? "a deleted fork")
+      : null,
+  };
+};

package/src/github/pullRequestRevisions.ts

@@ -0,0 +1,124 @@
+import type {
+  PullRequestRevision,
+  PullRequestRevisionsResponse,
+} from "../api/pullRequest.ts";
+import { diffLines } from "./lineDiff.ts";
+import type { GitHubTransport } from "./transport.ts";
+
+/** GitHub's own page lists a whole history; past this, the screen links to it. */
+const revisionsPage = 50;
+
+/**
+ * `userContentEdits` lists the newest first and ends on the original, when
+ * GitHub kept it (`includesCreatedEdit`). Despite its name, an edit's `diff` is
+ * the whole text of that version, not a change.
+ */
+export const pullRequestRevisionsQuery = `query PullRequestRevisions($id: ID!) {
+  node(id: $id) {
+    ... on Comment {
+      includesCreatedEdit
+      userContentEdits(first: ${String(revisionsPage)}) {
+        totalCount
+        nodes {
+          editedAt
+          deletedAt
+          editor { login avatarUrl }
+          deletedBy { login }
+          diff
+        }
+      }
+    }
+  }
+}`;
+
+interface GhActor {
+  login: string;
+  avatarUrl?: string | null;
+}
+
+interface GhContentEdit {
+  editedAt: string;
+  deletedAt: string | null;
+  editor: GhActor | null;
+  deletedBy: { login: string } | null;
+  diff: string | null;
+}
+
+export interface PullRequestRevisionsData {
+  node: {
+    includesCreatedEdit?: boolean;
+    userContentEdits?: {
+      totalCount: number;
+      nodes: (GhContentEdit | null)[] | null;
+    } | null;
+  } | null;
+}
+
+/** A body typed on GitHub's page carries `\r\n`, one sent through the API `\n`. */
+const normalizeNewlines = (text: string | null): string | null =>
+  text?.replaceAll("\r\n", "\n") ?? null;
+
+export const parsePullRequestRevisions = ({
+  data,
+  errors,
+  subjectId,
+}: {
+  data: PullRequestRevisionsData | null;
+  errors: string[];
+  subjectId: string;
+}): PullRequestRevisionsResponse => {
+  const edits = data?.node?.userContentEdits ?? null;
+  if (edits === null) {
+    const reason = errors.length > 0 ? errors.join("; ") : "not found";
+    throw new Error(`no edit history for ${subjectId}: ${reason}`);
+  }
+  // GitHub's index, before its unresolved (null) entries are dropped: the
+  // original is the last of `totalCount`, whatever the page lost
+  const nodes = (edits.nodes ?? []).flatMap((node, rawIndex) =>
+    node === null ? [] : [{ ...node, rawIndex }],
+  );
+  const bodies = nodes.map((node) =>
+    node.deletedAt === null ? normalizeNewlines(node.diff) : null,
+  );
+  const lastIndex = edits.totalCount - 1;
+
+  const revisions = nodes.map((node, index): PullRequestRevision => {
+    const body = bodies[index] ?? null;
+    const before = bodies.slice(index + 1).find((older) => older !== null);
+    return {
+      editedAt: node.editedAt,
+      editor:
+        node.editor === null
+          ? null
+          : {
+              login: node.editor.login,
+              avatarUrl: node.editor.avatarUrl ?? null,
+            },
+      original:
+        data?.node?.includesCreatedEdit === true && node.rawIndex === lastIndex,
+      body,
+      deletedBy: node.deletedBy?.login ?? null,
+      changes:
+        body === null || before === undefined
+          ? null
+          : diffLines({ before, after: body }),
+    };
+  });
+
+  return { revisions, revisionsTotal: edits.totalCount };
+};
+
+/**
+ * Raises with GitHub's reason when the id names nothing the token can read, or
+ * something that is not a comment.
+ */
+export const fetchPullRequestRevisions = async (
+  transport: GitHubTransport,
+  subjectId: string,
+): Promise<PullRequestRevisionsResponse> => {
+  const { data, errors } = await transport.graphql<PullRequestRevisionsData>(
+    pullRequestRevisionsQuery,
+    { id: subjectId },
+  );
+  return parsePullRequestRevisions({ data, errors, subjectId });
+};

package/src/github/transport.ts

@@ -0,0 +1,171 @@
+/**
+ * How this package reaches GitHub, supplied by the app: the token, the HTTP
+ * client and the identity the requests go out under are the app's, so the
+ * same queries run from a local server with the user's `gh` login, or from
+ * anywhere `fetch` exists.
+ *
+ * `createGitHubTransport` builds the three calls from one raw `send`; an app
+ * only has to authenticate and carry the bytes.
+ */
+
+export interface HttpAnswer {
+  status: number;
+  body: string;
+}
+
+export type HttpMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+
+export interface HttpRequest {
+  method: HttpMethod;
+  /** relative to the API root (`https://api.github.com/`), already encoded */
+  path: string;
+  accept: string;
+  /** JSON, already serialized */
+  body: string | undefined;
+}
+
+export type SendToGitHub = (request: HttpRequest) => Promise<HttpAnswer>;
+
+export interface GhGraphqlResult<Data> {
+  /** null when the whole query failed; partial when some aliases resolved */
+  data: Data | null;
+  errors: string[];
+}
+
+export type GhRestMethod = "DELETE" | "PATCH" | "POST" | "PUT";
+
+export interface GitHubTransport {
+  graphql: <Data>(
+    query: string,
+    variables?: Record<string, unknown>,
+  ) => Promise<GhGraphqlResult<Data>>;
+  rest: <Data>(request: {
+    method: GhRestMethod;
+    /** relative to the API root, already encoded */
+    path: string;
+    body?: unknown;
+  }) => Promise<Data | null>;
+  text: (request: {
+    /** relative to the API root, already encoded */
+    path: string;
+    accept: string;
+  }) => Promise<string>;
+}
+
+const firstLine = (text: string): string =>
+  text.split("\n", 1)[0]?.trim() ?? "";
+
+const isSuccess = (status: number): boolean => status >= 200 && status < 300;
+
+const parseJson = <Value>(text: string): Value | null => {
+  try {
+    return JSON.parse(text) as Value;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * A GraphQL answer carrying an `errors` array next to usable `data` — one
+ * repository the token cannot see — is a partial answer, not a failed request.
+ * Only an answer with no `data` at all is raised: an expired token, a rate
+ * limit or a network failure, which the user has to act on.
+ */
+export const interpretGraphql = <Data>({
+  status,
+  body,
+}: HttpAnswer): GhGraphqlResult<Data> => {
+  const parsed = parseJson<{
+    data?: Data | null;
+    errors?: { message?: string }[];
+    message?: string;
+  }>(body);
+
+  if (parsed === null || (!isSuccess(status) && parsed.data == null)) {
+    const detail = parsed?.message ?? firstLine(body);
+    throw new Error(
+      `GitHub graphql failed (HTTP ${String(status)})${detail === "" ? "" : `: ${detail}`}`,
+    );
+  }
+
+  return {
+    data: parsed.data ?? null,
+    errors: (parsed.errors ?? []).map(
+      ({ message }) => message ?? "github returned an unnamed error",
+    ),
+  };
+};
+
+interface GhRestError {
+  message?: string;
+  errors?: (string | { message?: string; code?: string; field?: string })[];
+}
+
+export const restErrorMessage = ({ status, body }: HttpAnswer): string => {
+  const parsed = parseJson<GhRestError>(body);
+  const details = (parsed?.errors ?? [])
+    .map((error) =>
+      typeof error === "string"
+        ? error
+        : (error.message ??
+          [error.field, error.code].filter(Boolean).join(" ")),
+    )
+    .filter((detail) => detail !== "");
+  const headline =
+    parsed?.message ?? (firstLine(body) || `HTTP ${String(status)}`);
+  return [headline, ...details].filter((part) => part !== "").join(": ");
+};
+
+/**
+ * A REST write's non-2xx status is the answer: a write GitHub refused changed
+ * nothing, so its message is raised as is. A text read (a unified diff, with
+ * `Accept: application/vnd.github.diff`) is refused past 300 files or 20,000
+ * lines with a 406, raised the same way.
+ */
+export const createGitHubTransport = (send: SendToGitHub): GitHubTransport => ({
+  graphql: async <Data>(
+    query: string,
+    variables?: Record<string, unknown>,
+  ): Promise<GhGraphqlResult<Data>> =>
+    interpretGraphql<Data>(
+      await send({
+        method: "POST",
+        path: "graphql",
+        accept: "application/json",
+        body: JSON.stringify(
+          variables === undefined ? { query } : { query, variables },
+        ),
+      }),
+    ),
+  rest: async <Data>({
+    method,
+    path,
+    body,
+  }: {
+    method: GhRestMethod;
+    path: string;
+    body?: unknown;
+  }): Promise<Data | null> => {
+    const answer = await send({
+      method,
+      path,
+      accept: "application/vnd.github+json",
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    if (!isSuccess(answer.status)) {
+      throw new Error(
+        `GitHub refused ${method} ${path}: ${restErrorMessage(answer)}`,
+      );
+    }
+    return parseJson<Data>(answer.body);
+  },
+  text: async ({ path, accept }) => {
+    const answer = await send({ method: "GET", path, accept, body: undefined });
+    if (!isSuccess(answer.status)) {
+      throw new Error(
+        `GitHub refused GET ${path}: ${restErrorMessage(answer)}`,
+      );
+    }
+    return answer.body;
+  },
+});

package/src/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Browser-safe surface: nothing here may import node. Reading a diff from a
+ * local checkout is `@reviewflow/sdk/git`, which is node only.
+ */
+export * from "./diff/diffPaths.ts";
+export type * from "./diff/impacts.ts";
+export { isAttachablePath, subjectsOf } from "./diff/readingOrder.ts";
+export * from "./diff/themes.ts";
+export * from "./diff/types.ts";
+export * from "./github/applySuggestions.ts";
+export * from "./github/editPullRequest.ts";
+export * from "./github/fetchCompareDiff.ts";
+export * from "./github/lineDiff.ts";
+export * from "./github/prQuery.ts";
+export * from "./github/pullRequestDetail.ts";
+export * from "./github/pullRequestHead.ts";
+export * from "./github/pullRequestRevisions.ts";
+export * from "./github/transport.ts";
+export type * from "./api/pullRequest.ts";
+export type * from "./types/entities.ts";
+export type * from "./types/ids.ts";
+export type * from "./types/reviewflow.ts";
+export * from "./utils/pullRequestEdit.ts";
+export * from "./utils/pullRequestPart.ts";
+export * from "./utils/pullRequestReaction.ts";
+export * from "./utils/pullRequestSuggestion.ts";
+export * from "./reviewflow/changedParts.ts";
+export * from "./reviewflow/checksFromReviewflow.ts";
+export * from "./reviewflow/client.ts";
+export * from "./reviewflow/stream.ts";
+export * from "./reviewflow/board.ts";
+export * from "./reviewflow/follow.ts";
+export type * from "./reviewflow/status.ts";
+export { insertCheckoutEntry } from "./config/insertCheckoutEntry.ts";
+export type { InsertedCheckoutEntry } from "./config/insertCheckoutEntry.ts";