diff --git a/packages/experimental/forge-github/README.i18n.yaml b/packages/experimental/forge-github/README.i18n.yaml index 42a42a70c5..52977df4e4 100644 --- a/packages/experimental/forge-github/README.i18n.yaml +++ b/packages/experimental/forge-github/README.i18n.yaml @@ -15,11 +15,11 @@ en: d152484eb41ac6b4 zh: 2f8a621b991260a1 /deepseek-ai-dsh-experimental-forge-github/use-this-package: - en: 2ab29060f216c1aa - zh: 0518073681b2c8e3 + en: ba6f281a24f3cce0 + zh: b99a3c479b250402 /deepseek-ai-dsh-experimental-forge-github/understand-the-implementation: - en: c6975cef45d63fe8 - zh: ccb96a7eee385c13 + en: 9b639e511e850042 + zh: 25a1a3bde330e7da /deepseek-ai-dsh-experimental-forge-github/further-exploration: en: d377d5fd9d9f190e zh: 920bcbfdb8c993f2 diff --git a/packages/experimental/forge-github/README.md b/packages/experimental/forge-github/README.md index cc87b02c32..d272b7bc67 100644 --- a/packages/experimental/forge-github/README.md +++ b/packages/experimental/forge-github/README.md @@ -34,7 +34,7 @@ Mount the provider after the forge registry and list every GitHub Enterprise hos hosts: [github.com, ghe.example.com] ``` -The provider runs `gh` as a host process, even when Sessions execute commands in another execution world. Sign in once per host with `gh auth login --hostname `. The child receives the host environment without `DSH_*` variables and without variables whose names contain `KEY`, `PASSWORD`, `SECRET`, or `TOKEN`, so `GH_TOKEN` and `GITHUB_TOKEN` are not forwarded and `gh` uses its own credential store. Prompts, update notices, pagers, and colors are disabled. `maxOutputBytes`, `maxReviewThreads`, and `maxCommits` must be positive safe integers; only `timeoutMs` is bounded by the runtime timer limit. `ghCommand`, `hosts`, `timeoutMs`, `maxOutputBytes`, `maxReviewThreads`, and `maxCommits` are listed in the [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-experimental-forge-github). +The provider runs `gh` as a host process, even when Sessions execute commands in another execution world. Sign in once per host with `gh auth login --hostname `. The child receives the host environment without `DSH_*` variables and without variables whose names contain `KEY`, `PASSWORD`, `SECRET`, or `TOKEN`, so `GH_TOKEN` and `GITHUB_TOKEN` are not forwarded and `gh` uses its own credential store. Prompts, update notices, pagers, and colors are disabled. `maxOutputBytes`, `maxReviewThreads`, `maxCommits`, and `maxViewedFiles` must be positive safe integers; only `timeoutMs` is bounded by the runtime timer limit. `ghCommand`, `hosts`, `timeoutMs`, `maxOutputBytes`, `maxReviewThreads`, `maxCommits`, and `maxViewedFiles` are listed in the [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-experimental-forge-github). The provider serves a remote URL in `https`, `http`, `ssh`, or `git` form, or in scp form such as `git@github.com:owner/name.git`, when its host is configured. HTTP(S) remotes retain custom ports in the host identity; SSH and Git transport ports are excluded. It serves pull request URLs of the form `https://///pull/` with any trailing path, query, or fragment, and builds that form without the suffix as the canonical URL. A readiness probe runs `gh auth status --hostname `: exit status 0 is `ready`, another exit status is `unauthenticated` with the first diagnostic line, and a `gh` that cannot start is `unavailable`. A head lookup returns up to 20 open pull requests whose head is the branch, newest first, excluding pull requests from forks; a lookup of the default branch returns none. @@ -56,6 +56,10 @@ The same first page reads what the signed-in viewer may write: each thread's `vi `writeReview` first reads the pull request's `headRefOid` and the viewer's pending review in one GraphQL query and returns `stale` without writing when the head is not `write.headSha`. It then sends one mutation with its variables as JSON on stdin: `addPullRequestReviewThreadReply`, inside the pending review for a pending reply; `resolveReviewThread` or `unresolveReviewThread`; `updatePullRequestReviewComment` or `deletePullRequestReviewComment`; `addPullRequestReviewThread` into the pending review, or `addPullRequestReview` at `write.headSha` with the comment as its first thread when the viewer has none; and `submitPullRequestReview` or `deletePullRequestReview` for the pending review the write names, which the check must still find. A pending reply without a pending review first starts an empty one at the head, so it takes two mutations; when the reply then fails, the empty review stays. A write to a thread or comment also reads, in the same check, the pull request that holds it, and returns `failed` without a mutation when that is another pull request. GitHub adds every reply of a user with a pending review to that review, even one sent without its id, so a reply at once returns `failed` without a mutation while the viewer has one; a thread added to a pending review numbers the lines of the current head, whichever commit the review started at. A mutation's payload means GitHub applied it; GraphQL errors whose types all name a refusal (`FORBIDDEN`, `INSUFFICIENT_SCOPES`, `NOT_FOUND`, `RATE_LIMITED`, `UNPROCESSABLE`) and HTTP 400, 401, 403, 404, 409, and 422 refusals return `failed`, as does a `gh` that cannot start; any other GraphQL error, such as GitHub's timeout message, a `gh` timeout, a server error, or an answer without the payload returns `unknown`. No mutation is retried. +Every status read also reads the overview of each pull request: up to 25 review requests, latest reviews, latest opinionated reviews, and closing issue references, each list marked truncated when GitHub counts more. A review request names a user, bot, or team, and whether it is a code owner request. Reviews of the author and reviews without an author are left out; a dismissed review counts as `dismissed`, and a later opinionated review decides the verdict over a comment. `branchUpdates` is empty for a pull request that is not open, that GitHub reports as conflicting, or whose head the signed-in user may not update; otherwise it offers merge, and rebase as well when GitHub can rebase the head. `canRequestReviews` requires triage, write, maintain, or admin permission on an open pull request, and `canRerunChecks` requires write, maintain, or admin permission. A check run of a GitHub Actions workflow names its workflow run as `rerun`; status contexts and other check runs name none. + +`viewedFiles` lists the pull request's files through GraphQL, 100 per page, up to `maxViewedFiles` (default 3,000) files, and sets `truncated` when GitHub counts more; GitHub's `VIEWED`, `UNVIEWED`, and `DISMISSED` map to `viewed`, `unviewed`, and `dismissed`, and an unknown state to `unviewed`. A page whose head is not the requested commit makes the read `stale`, and a page that does not advance makes it `unavailable`. `setViewed` checks the head, then calls `markFileAsViewed` or `unmarkFileAsViewed`; GitHub keeps one viewed mark per file and user, whatever the commit. `rerunChecks` reads the complete checks, returns `stale` when the head moved, and posts `repos///actions/runs//rerun-failed-jobs` once for each workflow run with a failed check, stopping at the first refusal; GitHub reruns the failed jobs with the jobs that depend on them. `requestReviews` calls `requestReviewsByLogin` with `union: true`, so existing requests stay, and adds the `[bot]` suffix to bot logins. `reviewerCandidates` lists up to 20 assignable users whose login or name contains the query, and with an empty query GitHub's suggested reviewers first; the author is left out. `updateBranch` checks the head, then calls `updatePullRequestBranch` with the update method and `expectedHeadOid`, so GitHub refuses once new commits arrived. These mutations go through the sender `writeReview` uses, with their GraphQL document and variables as JSON on stdin, and are never retried; because each sets a state, a refusal and an outcome GitHub did not confirm both become `failed` with GitHub's message. + ----- @@ -74,7 +78,11 @@ A fetch groups references by host and sends one initial `gh api graphql` query p | [`src/compare.ts`](src/compare.ts) | Patch between two commits through the compare API, shared by every diff read | | [`src/threads.ts`](src/threads.ts) | Review thread read, pagination, and mapping onto head and original positions | | [`src/review-writes.ts`](src/review-writes.ts) | Head check and review thread and pending review mutations | +| [`src/mutation.ts`](src/mutation.ts) | Sending one GraphQL mutation and classifying its outcome | | [`src/gh.ts`](src/gh.ts) | Host `gh` execution with environment scrubbing and limits | +| [`src/viewed.ts`](src/viewed.ts) | Viewed file reads and writes | +| [`src/overview.ts`](src/overview.ts) | Review requests, reviewer search, and branch updates | +| [`src/pull-request-node.ts`](src/pull-request-node.ts) | Pull request node id at a checked head, for mutations | | [`src/urls.ts`](src/urls.ts) | Remote URL and pull request URL parsing, and validation of inlined names and commits | diff --git a/packages/experimental/forge-github/README.zh.md b/packages/experimental/forge-github/README.zh.md index 0000255392..9750b2846a 100644 --- a/packages/experimental/forge-github/README.zh.md +++ b/packages/experimental/forge-github/README.zh.md @@ -34,7 +34,7 @@ kind: "package-reference" hosts: [github.com, ghe.example.com] ``` -即使 Session 在其他执行环境中运行命令,提供方也以宿主进程的形式运行 `gh`。每个主机执行一次 `gh auth login --hostname ` 完成登录。子进程继承的宿主环境去掉了 `DSH_*` 变量以及名称包含 `KEY`、`PASSWORD`、`SECRET` 或 `TOKEN` 的变量,因此 `GH_TOKEN` 与 `GITHUB_TOKEN` 不会被转发,`gh` 使用自己的凭据存储。交互提示、更新提醒、分页器与颜色输出均被关闭。`maxOutputBytes`、`maxReviewThreads` 与 `maxCommits` 必须是正安全整数;只有 `timeoutMs` 受运行时定时器上限约束。`ghCommand`、`hosts`、`timeoutMs`、`maxOutputBytes`、`maxReviewThreads` 与 `maxCommits` 见[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-experimental-forge-github)。 +即使 Session 在其他执行环境中运行命令,提供方也以宿主进程的形式运行 `gh`。每个主机执行一次 `gh auth login --hostname ` 完成登录。子进程继承的宿主环境去掉了 `DSH_*` 变量以及名称包含 `KEY`、`PASSWORD`、`SECRET` 或 `TOKEN` 的变量,因此 `GH_TOKEN` 与 `GITHUB_TOKEN` 不会被转发,`gh` 使用自己的凭据存储。交互提示、更新提醒、分页器与颜色输出均被关闭。`maxOutputBytes`、`maxReviewThreads`、`maxCommits` 与 `maxViewedFiles` 必须是正安全整数;只有 `timeoutMs` 受运行时定时器上限约束。`ghCommand`、`hosts`、`timeoutMs`、`maxOutputBytes`、`maxReviewThreads`、`maxCommits` 与 `maxViewedFiles` 见[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-experimental-forge-github)。 当主机在配置中时,提供方服务 `https`、`http`、`ssh`、`git` 形式的远端 URL,以及 `git@github.com:owner/name.git` 这类 scp 形式。HTTP(S) 远端在主机标识中保留自定义端口;SSH 和 Git 传输端口不计入主机标识。它服务 `https://///pull/` 形式的 pull request URL,允许其后附带任意路径、查询或片段,并以去掉这些后缀的形式作为规范 URL。就绪探测运行 `gh auth status --hostname `:退出码为 0 时为 `ready`,其他退出码为 `unauthenticated` 并带第一行诊断,`gh` 无法启动时为 `unavailable`。按 head 分支查找时,最多返回 20 个以该分支为 head 的打开状态 pull request,按创建时间从新到旧排列,不包含来自 fork 的 pull request;查找默认分支时返回空结果。 @@ -56,6 +56,10 @@ pull request 处于打开状态、不是草稿、GitHub 报告其合并状态为 `writeReview` 先用一次 GraphQL 查询读出 pull request 的 `headRefOid` 和用户的待提交评审;head 不是 `write.headSha` 时不写入,直接返回 `stale`。随后发送一个 mutation,变量以 JSON 形式经 stdin 传入:回复用 `addPullRequestReviewThreadReply`,待提交的回复加入待提交评审;`resolveReviewThread` 或 `unresolveReviewThread`;`updatePullRequestReviewComment` 或 `deletePullRequestReviewComment`;新评论用 `addPullRequestReviewThread` 加入待提交评审,用户还没有待提交评审时,用 `addPullRequestReview` 在 `write.headSha` 上开始一个评审,并把这条评论作为它的第一个讨论;提交或丢弃用 `submitPullRequestReview` 或 `deletePullRequestReview`,作用于写操作指定的待提交评审,检查时必须仍能找到它。没有待提交评审时,待提交的回复会先在 head 上开始一个空评审,因此需要两个 mutation;回复随后失败时,这个空评审会保留下来。写入讨论或评论时,同一次检查还会读出它所属的 pull request,不是当前 pull request 时不发送 mutation,直接返回 `failed`。用户有待提交评审时,GitHub 会把该用户的每条回复都加入这个评审,即使发送时没有带上评审 id;因此该用户有待提交评审时,立即回复不发送 mutation,直接返回 `failed`。加入待提交评审的讨论使用当前 head 的行号,与评审开始时所在的提交无关。mutation 返回 payload 即表示 GitHub 已执行;错误类型全部表示拒绝(`FORBIDDEN`、`INSUFFICIENT_SCOPES`、`NOT_FOUND`、`RATE_LIMITED`、`UNPROCESSABLE`)的 GraphQL 错误以及 HTTP 400、401、403、404、409、422 拒绝返回 `failed`,`gh` 无法启动时也是如此;其他 GraphQL 错误(例如 GitHub 的超时提示)、`gh` 超时、服务端错误或没有 payload 的响应返回 `unknown`。mutation 从不重试。 +每次状态读取还会读取每个 pull request 的概览:最多 25 个评审请求、最近评审、最近的表态评审与关闭的 issue 引用,GitHub 统计到更多时把对应列表标记为截断。评审请求指向用户、bot 或团队,并说明是否为代码所有者请求。作者本人的评审与没有作者的评审被略去;被驳回的评审记为 `dismissed`,较新的表态评审优先于评论决定结论。pull request 未处于 open、GitHub 报告存在冲突或当前登录用户无权更新其 head 时,`branchUpdates` 为空;否则提供 merge,GitHub 能变基该 head 时也提供 rebase。`canRequestReviews` 要求 open 的 pull request 与 triage、write、maintain 或 admin 权限,`canRerunChecks` 要求 write、maintain 或 admin 权限。GitHub Actions 工作流的 check run 以其工作流运行作为 `rerun`;状态上下文与其他 check run 没有 `rerun`。 + +`viewedFiles` 经 GraphQL 每页 100 个列出 pull request 的文件,最多 `maxViewedFiles`(默认 3,000)个,GitHub 统计到更多时设置 `truncated`;GitHub 的 `VIEWED`、`UNVIEWED` 与 `DISMISSED` 分别映射为 `viewed`、`unviewed` 与 `dismissed`,未知状态映射为 `unviewed`。某页的 head 不是请求的提交时读取为 `stale`,分页不前进时为 `unavailable`。`setViewed` 先检查 head,再调用 `markFileAsViewed` 或 `unmarkFileAsViewed`;GitHub 对每个文件和用户只保存一个已审阅标记,与提交无关。`rerunChecks` 读取完整检查,head 已移动时返回 `stale`,再对每个含失败检查的工作流运行 POST 一次 `repos///actions/runs//rerun-failed-jobs`,遇到第一次拒绝即停止;GitHub 会重跑失败的 job 及依赖它们的 job。`requestReviews` 以 `union: true` 调用 `requestReviewsByLogin`,保留已有请求,并为 bot 登录名加上 `[bot]` 后缀。`reviewerCandidates` 列出登录名或名称包含查询文本的最多 20 个可指派用户,查询为空时 GitHub 建议的评审者排在最前;作者被略去。`updateBranch` 先检查 head,再以更新方式与 `expectedHeadOid` 调用 `updatePullRequestBranch`,因此新提交到来后 GitHub 会拒绝。这些写操作与 `writeReview` 使用同一个发送方式,把 GraphQL 文档与变量作为 JSON 经标准输入发送,且从不重试;由于每个写操作都只设置一种状态,GitHub 的拒绝与未确认的结果都为 `failed`,并附 GitHub 的原因。 + ----- @@ -74,7 +78,11 @@ pull request 处于打开状态、不是草稿、GitHub 报告其合并状态为 | [`src/compare.ts`](src/compare.ts) | 经 compare API 读取两个提交之间的补丁,供所有 diff 读取共用 | | [`src/threads.ts`](src/threads.ts) | 读取评审讨论、分页,并映射到 head 位置与原始位置 | | [`src/review-writes.ts`](src/review-writes.ts) | head 检查,以及评审讨论与待提交评审的 mutation | +| [`src/mutation.ts`](src/mutation.ts) | 发送单个 GraphQL mutation 并判定其结果 | | [`src/gh.ts`](src/gh.ts) | 在宿主上执行 `gh`,清理环境变量并施加限制 | +| [`src/viewed.ts`](src/viewed.ts) | 读取与写入已审阅文件 | +| [`src/overview.ts`](src/overview.ts) | 评审请求、评审者搜索与分支更新 | +| [`src/pull-request-node.ts`](src/pull-request-node.ts) | 在核对过的 head 上读取 pull request 节点 id,供写操作使用 | | [`src/urls.ts`](src/urls.ts) | 解析远端 URL 与 pull request URL,并校验写入请求的名称与提交 | diff --git a/packages/experimental/forge-github/src/graphql.ts b/packages/experimental/forge-github/src/graphql.ts index ec97758af6..479c3f3c54 100644 --- a/packages/experimental/forge-github/src/graphql.ts +++ b/packages/experimental/forge-github/src/graphql.ts @@ -3,8 +3,8 @@ import type { Branded } from '@deepseek-ai/dsh-brand' import { changeRequestKey } from '@deepseek-ai/dsh-experimental-forge' import type { - ChangeRequestCheck, ChangeRequestKey, ChangeRequestRef, ChangeRequestSnapshot, CheckState, ChecksRollup, ForgeFailure, ForgeRepository, - Mergeability, MergeMethod, ReviewDecision, + ChangeRequestCheck, ChangeRequestKey, ChangeRequestRef, ChangeRequestReviewer, ChangeRequestSnapshot, CheckState, ChecksRollup, + ForgeCheckId, ForgeFailure, ForgeRepository, Mergeability, MergeMethod, ReviewDecision, ReviewVerdict, } from '@deepseek-ai/dsh-experimental-forge' import { z } from 'zod' import { checkedRepository, isCommit } from './urls.ts' @@ -14,7 +14,7 @@ const CHECK_FIELDS = `pageInfo { hasNextPage endCursor } __typename ... on CheckRun { id databaseId name status conclusion detailsUrl startedAt completedAt - checkSuite { app { id } workflowRun { event workflow { id name } } } + checkSuite { app { id } workflowRun { databaseId event workflow { id name } } } } ... on StatusContext { context state targetUrl createdAt } }` @@ -24,6 +24,11 @@ const PAGE_SIZE = 100 const THREAD_FIELDS = 'pageInfo { hasNextPage endCursor } nodes { isResolved }' +/** Most review requests, reviews per kind, and closing issues one snapshot reads. */ +const OVERVIEW_PAGE = 25 + +const REVIEW_FIELDS = 'totalCount nodes { state commit { oid } author { __typename login avatarUrl } }' + /** * Pull request fields of one snapshot. * @param threads - review threads the first page holds, at most {@link PAGE_SIZE}. @@ -32,8 +37,15 @@ const THREAD_FIELDS = 'pageInfo { hasNextPage endCursor } nodes { isResolved }' function pullRequestFields(threads: number): string { return `id number url title state isDraft updatedAt closedAt author { login } - headRefName headRefOid baseRefName baseRefOid additions deletions mergeable mergeStateStatus reviewDecision + headRefName headRefOid baseRefName baseRefOid additions deletions mergeable mergeStateStatus reviewDecision viewerCanUpdateBranch + canBeRebased reviewThreads(first: ${threads}) { ${THREAD_FIELDS} } + reviewRequests(first: ${OVERVIEW_PAGE}) { totalCount nodes { asCodeOwner requestedReviewer { + __typename ... on User { login avatarUrl } ... on Bot { login avatarUrl } ... on Team { combinedSlug avatarUrl } + } } } + latestReviews(first: ${OVERVIEW_PAGE}) { ${REVIEW_FIELDS} } + latestOpinionatedReviews(first: ${OVERVIEW_PAGE}) { ${REVIEW_FIELDS} } + closingIssuesReferences(first: ${OVERVIEW_PAGE}) { totalCount nodes { number title state url repository { name owner { login } } } } commits(last: 1) { nodes { commit { statusCheckRollup { id state contexts(first: ${PAGE_SIZE}) { ${CHECK_FIELDS} } } } } }` @@ -76,7 +88,11 @@ const checkRunSchema = z.object({ completedAt: z.string().nullable(), checkSuite: z.object({ app: z.object({ id: z.string() }).nullable(), - workflowRun: z.object({ event: z.string(), workflow: z.object({ id: z.string(), name: z.string() }) }).nullable(), + workflowRun: z.object({ + databaseId: z.number().int().nonnegative().nullable(), + event: z.string(), + workflow: z.object({ id: z.string(), name: z.string() }), + }).nullable(), }).nullable(), }) @@ -120,6 +136,13 @@ export interface SnapshotPages { readonly checks?: (id: RollupId, cursor: string) => Promise } +const actorSchema = z.object({ __typename: z.string(), login: z.string(), avatarUrl: z.string().nullable() }) + +const reviewsSchema = z.object({ + totalCount: z.number().int().nonnegative(), + nodes: z.array(z.object({ state: z.string(), commit: z.object({ oid: z.string() }).nullable(), author: actorSchema.nullable() })), +}) + const pullRequestSchema = z.object({ id: z.string().transform(value => value as PullRequestId), url: z.string(), @@ -139,7 +162,33 @@ const pullRequestSchema = z.object({ mergeable: z.string(), mergeStateStatus: z.string(), reviewDecision: z.string().nullable(), + viewerCanUpdateBranch: z.boolean(), + canBeRebased: z.boolean(), reviewThreads: threadPageSchema, + reviewRequests: z.object({ + totalCount: z.number().int().nonnegative(), + nodes: z.array(z.object({ + asCodeOwner: z.boolean(), + requestedReviewer: z.object({ + __typename: z.string(), + login: z.string().optional(), + combinedSlug: z.string().optional(), + avatarUrl: z.string().nullable().optional(), + }).nullable(), + })), + }), + latestReviews: reviewsSchema, + latestOpinionatedReviews: reviewsSchema, + closingIssuesReferences: z.object({ + totalCount: z.number().int().nonnegative(), + nodes: z.array(z.object({ + number: z.number().int().positive(), + title: z.string(), + state: z.string(), + url: z.string(), + repository: z.object({ name: z.string(), owner: z.object({ login: z.string() }) }), + })), + }), commits: z.object({ nodes: z.array(z.object({ commit: z.object({ @@ -199,9 +248,17 @@ type RepositoryNode = z.infer /** GitHub merge states in which the merge button works: mergeable, with passing or non-required failing checks. */ const MERGEABLE_NOW: ReadonlySet = new Set(['CLEAN', 'HAS_HOOKS', 'UNSTABLE']) -/** Repository permissions that may merge. */ +/** Repository permissions that may merge and rerun workflow jobs. */ const MERGERS: ReadonlySet = new Set(['ADMIN', 'MAINTAIN', 'WRITE']) +/** Repository permissions that may request reviews. */ +const TRIAGERS: ReadonlySet = new Set(['ADMIN', 'MAINTAIN', 'WRITE', 'TRIAGE']) + +/** Outcome of a submitted review by GitHub state; a pending review is not submitted. */ +const VERDICTS: Readonly> = { + APPROVED: 'approved', CHANGES_REQUESTED: 'changes-requested', COMMENTED: 'commented', DISMISSED: 'dismissed', +} + /** Merge methods in menu order, with the repository setting that allows each and GitHub's name for it. */ const METHODS: readonly { readonly method: MergeMethod @@ -433,6 +490,7 @@ function toSnapshot( workflow: run.data.checkSuite?.workflowRun?.workflow.name ?? null, startedAt: run.data.startedAt, completedAt: run.data.completedAt, + rerun: workflow?.databaseId == null ? null : actionsRun(workflow.databaseId), }) continue } @@ -445,6 +503,7 @@ function toSnapshot( workflow: null, startedAt: null, completedAt: null, + rerun: null, }) } else if (typeof context === 'object' && context !== null && '__typename' in context && (context.__typename === 'CheckRun' || context.__typename === 'StatusContext')) { @@ -458,6 +517,8 @@ function toSnapshot( const summary: ChecksRollup = rollup?.contexts.pageInfo.hasNextPage || unknownContext || checks.length === 0 ? checksRollup(rollup?.state) : checks.some(check => check.state === 'failure' || check.state === 'cancelled') ? 'failure' : checks.some(check => check.state === 'pending') ? 'pending' : 'success' + const permission = settings?.viewerPermission ?? '' + const open = node.state === 'OPEN' return { ref, url: node.url, @@ -475,17 +536,83 @@ function toSnapshot( mergeReady: settings !== undefined && MERGERS.has(settings.viewerPermission ?? '') && node.state === 'OPEN' && !node.isDraft && MERGEABLE_NOW.has(node.mergeStateStatus), mergeMethods: settings === undefined ? [] : mergeMethods(settings), + branchUpdates: !open || !node.viewerCanUpdateBranch || node.mergeable === 'CONFLICTING' ? [] + : node.canBeRebased ? ['merge', 'rebase'] : ['merge'], reviewDecision: reviewDecision(node.reviewDecision), + reviewers: reviewersOf(node), + reviewersTruncated: [node.reviewRequests, node.latestReviews, node.latestOpinionatedReviews] + .some(connection => connection.totalCount > connection.nodes.length), + canRequestReviews: open && TRIAGERS.has(permission), checks, checksRollup: summary, checksTruncated: rollup?.contexts.pageInfo.hasNextPage ?? false, + canRerunChecks: MERGERS.has(permission), unresolvedThreads: node.reviewThreads.nodes.filter(thread => !thread.isResolved).length, threadsTruncated: node.reviewThreads.pageInfo.hasNextPage, + closingIssues: node.closingIssuesReferences.nodes.map(issue => ({ + repository: { + forge: ref.repository.forge, host: ref.repository.host, owner: issue.repository.owner.login, name: issue.repository.name, + }, + number: issue.number, + title: issue.title, + state: issue.state === 'OPEN' ? 'open' as const : 'closed' as const, + url: issue.url, + })), + closingIssuesTruncated: node.closingIssuesReferences.totalCount > node.closingIssuesReferences.nodes.length, updatedAt: node.updatedAt, closedAt: node.closedAt, } } +/** + * The requested reviewers in host order, then the other accounts that submitted a review, each with their latest + * outcome. An approval or change request outlasts later comments, as GitHub's reviewer list shows it; the author and + * accounts GitHub does not name are left out. + */ +function reviewersOf(node: PullRequestNode): ChangeRequestReviewer[] { + const reviewers = new Map() + const keyOf = (kind: ChangeRequestReviewer['kind'], login: string): string => `${kind}:${login.toLowerCase()}` + for (const request of node.reviewRequests.nodes) { + const reviewer = request.requestedReviewer + const kind = reviewer?.__typename === 'User' ? 'user' : reviewer?.__typename === 'Bot' ? 'bot' : reviewer?.__typename === 'Team' ? 'team' : undefined + const login = kind === 'team' ? reviewer?.combinedSlug : reviewer?.login + if (kind === undefined || login === undefined) continue + reviewers.set(keyOf(kind, login), { + kind, login, avatarUrl: reviewer?.avatarUrl ?? null, requested: true, codeOwner: request.asCodeOwner, + verdict: null, reviewedSha: null, + }) + } + const author = node.author?.login.toLowerCase() + for (const review of [...node.latestReviews.nodes, ...node.latestOpinionatedReviews.nodes]) { + const verdict = VERDICTS[review.state] + const account = review.author + if (verdict === undefined || account === null || account.login.toLowerCase() === author) continue + const kind = account.__typename === 'Bot' ? 'bot' : 'user' + const key = keyOf(kind, account.login) + const known = reviewers.get(key) + reviewers.set(key, { + kind, login: account.login, avatarUrl: known?.avatarUrl ?? account.avatarUrl, requested: known?.requested ?? false, + codeOwner: known?.codeOwner ?? false, verdict, reviewedSha: review.commit?.oid ?? null, + }) + } + return [...reviewers.values()] +} + +/** The rerun identity of a GitHub Actions job: the database id of its workflow run, which reruns its failed jobs. */ +function actionsRun(run: number): ForgeCheckId { + return `actions:${run}` as ForgeCheckId +} + +/** + * Read the workflow run database id from a check's rerun identity. + * @param id - identity a snapshot of this provider named. + * @returns the workflow run id, or undefined for an identity this provider did not build. + */ +export function actionsRunOf(id: ForgeCheckId): number | undefined { + const match = /^actions:(\d{1,15})$/.exec(id) + return match === null ? undefined : Number(match[1]) +} + /** The methods the repository allows, the viewer's default first. */ function mergeMethods(settings: RepositoryNode): MergeMethod[] { const allowed = METHODS.filter(entry => settings[entry.allowed]) diff --git a/packages/experimental/forge-github/src/index.ts b/packages/experimental/forge-github/src/index.ts index 3235e030a3..aa5b5776f2 100644 --- a/packages/experimental/forge-github/src/index.ts +++ b/packages/experimental/forge-github/src/index.ts @@ -27,6 +27,8 @@ export interface Config { maxReviewThreads?: number /** Most commits one pull request commit listing returns; GitHub lists at most 250 commits of a pull request. */ maxCommits?: number + /** Most files whose viewed marks one read lists; GitHub lists at most 3,000 files of a pull request. */ + maxViewedFiles?: number } export const Config: z = z.object({ @@ -36,6 +38,7 @@ export const Config: z = z.object({ maxOutputBytes: z.number().default(8_388_608), maxReviewThreads: z.number().default(1_000), maxCommits: z.number().default(250), + maxViewedFiles: z.number().default(3_000), }) const HOST = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*(:\d+)?$/i @@ -50,7 +53,7 @@ export function apply(ctx: Context, config: Config): void { if (!Number.isSafeInteger(resolved.timeoutMs) || resolved.timeoutMs <= 0 || resolved.timeoutMs > MAX_TIMER_DELAY_MS) { throw new Error(`forge-github: timeoutMs must be a positive integer no greater than ${MAX_TIMER_DELAY_MS}`) } - for (const key of ['maxOutputBytes', 'maxReviewThreads', 'maxCommits'] as const) { + for (const key of ['maxOutputBytes', 'maxReviewThreads', 'maxCommits', 'maxViewedFiles'] as const) { if (!Number.isSafeInteger(resolved[key]) || resolved[key] <= 0) throw new Error(`forge-github: ${key} must be a positive safe integer`) } ctx.forge.register(new GitHubProvider(ghRunner(resolved), resolved.hosts, resolved)) diff --git a/packages/experimental/forge-github/src/mutation.ts b/packages/experimental/forge-github/src/mutation.ts new file mode 100644 index 0000000000..0261f8d6e3 --- /dev/null +++ b/packages/experimental/forge-github/src/mutation.ts @@ -0,0 +1,86 @@ +/** GitHub GraphQL mutations sent once through `gh`, with the document and variables as JSON on standard input. */ + +import type { ForgeActionFailure } from '@deepseek-ai/dsh-experimental-forge' +import { z } from 'zod' +import { GhUnavailableError, type GhOutput, type GhRunner } from './gh.ts' + +/** HTTP statuses that mean GitHub refused the request, so it changed nothing. */ +const REFUSED = /\(HTTP (?:400|401|403|404|409|422)\)/ + +/** + * GraphQL error types that mean GitHub refused a mutation before applying it. An error without one of them, such as + * GitHub's "Something went wrong … may be the result of a timeout", leaves the outcome unknown. + */ +const REFUSALS: ReadonlySet = new Set(['FORBIDDEN', 'INSUFFICIENT_SCOPES', 'NOT_FOUND', 'RATE_LIMITED', 'UNPROCESSABLE']) + +const graphqlErrors = z.object({ errors: z.array(z.object({ message: z.string(), type: z.string().optional() })).min(1) }) + +/** One mutation and the payload field that holds its result. */ +export interface GraphqlMutation { + /** GraphQL document with one mutation field. */ + readonly query: string + /** Name of the mutation field, which holds the payload once GitHub applied the mutation. */ + readonly field: string + /** Variables of the document. */ + readonly variables: Readonly> +} + +/** + * A mutation's result: the payload once GitHub applied it; else `failed` when GitHub refused it or `gh` could not start, + * so nothing changed, or `unknown` when the mutation may have been applied and must be checked on GitHub. + */ +export type MutationResult = + | { readonly ok: true; readonly payload: unknown } + | { readonly ok: false; readonly code: 'failed' | 'unknown'; readonly message: string } + +/** + * Runs one mutation on `host` through {@link sendMutation}; resolves to undefined once GitHub applied it, or to a + * `failed` action failure when GitHub refused it or did not confirm it. + */ +export type GraphqlWriter = (host: string, mutation: GraphqlMutation, signal: AbortSignal) => Promise + +/** + * Send one mutation with its query and variables as JSON on stdin. The mutation is never retried. + * @param gh - runs `gh` on the Host. + * @param host - GitHub host the mutation goes to. + * @param mutation - the document, its field, and its variables. + * @param signal - cancellation of the request. + * @returns the payload of `mutation.field`; `failed` when GitHub reports a refusal by its HTTP status or GraphQL error + * type, or `gh` cannot start, else `unknown`. + */ +export async function sendMutation(gh: GhRunner, host: string, mutation: GraphqlMutation, signal: AbortSignal): Promise { + let output: GhOutput + try { + output = await gh(['api', 'graphql', '--hostname', host, '--input', '-'], signal, + JSON.stringify({ query: mutation.query, variables: mutation.variables })) + } catch (error) { + const message = error instanceof Error ? error.message : String(error) + return { ok: false, code: error instanceof GhUnavailableError ? 'failed' : 'unknown', message } + } + const body = parse(output.stdout) + // A payload means GitHub applied the mutation, even beside errors about the fields it selects. + const payload = z.object({ data: z.record(z.string(), z.unknown()) }).safeParse(body) + const value = payload.success ? payload.data.data[mutation.field] : undefined + if (value !== undefined && value !== null) return { ok: true, payload: value } + const errors = graphqlErrors.safeParse(body) + if (errors.success) { + const refused = errors.data.errors.every(error => error.type !== undefined && REFUSALS.has(error.type)) + return { ok: false, code: refused ? 'failed' : 'unknown', message: errors.data.errors.map(error => error.message).join('; ') } + } + if (output.exitCode !== 0) { + const message = output.stderr.trim() || output.stdout.trim() || `gh exited with ${output.exitCode}` + return { ok: false, code: REFUSED.test(output.stderr) ? 'failed' : 'unknown', message } + } + return { ok: false, code: 'unknown', message: `unexpected GitHub response to ${mutation.field}` } +} + +function parse(text: string): unknown { + let value: unknown + try { + value = JSON.parse(text) + } catch (error) { + void error // gh prints diagnostics instead of JSON when a request fails before GitHub answers. + return undefined + } + return value +} diff --git a/packages/experimental/forge-github/src/overview.ts b/packages/experimental/forge-github/src/overview.ts new file mode 100644 index 0000000000..afba1a1e60 --- /dev/null +++ b/packages/experimental/forge-github/src/overview.ts @@ -0,0 +1,128 @@ +/** GitHub writes and reads of the change request overview: review requests, reviewer candidates, and branch updates. */ + +import type { + BranchUpdateRequest, ChangeRequestRef, ForgeActionFailure, ForgeFailure, ForgeReviewerCandidate, ForgeReviewersRequest, +} from '@deepseek-ai/dsh-experimental-forge' +import { z } from 'zod' +import type { GraphqlReader } from './commits.ts' +import type { GraphqlWriter } from './mutation.ts' +import { pullRequestNode } from './pull-request-node.ts' +import { checkedRepository, isCommit } from './urls.ts' + +/** Add review requests by login; variable `input` is a `RequestReviewsByLoginInput`. */ +export const REQUEST_REVIEWS_MUTATION = `mutation($input: RequestReviewsByLoginInput!) { + requestReviewsByLogin(input: $input) { clientMutationId } +}` + +/** Merge or rebase the base branch into the head branch; variable `input` is an `UpdatePullRequestBranchInput`. */ +export const UPDATE_BRANCH_MUTATION = `mutation($input: UpdatePullRequestBranchInput!) { + updatePullRequestBranch(input: $input) { clientMutationId } +}` + +/** Most accounts one candidate listing returns. */ +const CANDIDATES = 20 + +/** Accounts that can review and GitHub's suggestions; variables `owner`, `name`, and `search` are strings, `number` is an integer. */ +export const CANDIDATES_QUERY = `query($owner: String!, $name: String!, $number: Int!, $search: String!) { + repository(owner: $owner, name: $name) { + assignableUsers(first: ${CANDIDATES}, query: $search) { nodes { login name avatarUrl } } + pullRequest(number: $number) { author { login } suggestedReviewers { reviewer { login name avatarUrl } } } + } +}` + +const account = z.object({ login: z.string(), name: z.string().nullable(), avatarUrl: z.string().nullable() }) + +const candidatesSchema = z.object({ + data: z.object({ + repository: z.object({ + assignableUsers: z.object({ nodes: z.array(account) }), + pullRequest: z.object({ + author: z.object({ login: z.string() }).nullable(), + suggestedReviewers: z.array(z.object({ reviewer: account })), + }).nullable(), + }).nullable(), + }), +}) + +/** + * Request reviews by login with `requestReviewsByLogin`, adding to the requests GitHub holds; a bot is named with + * GitHub's `[bot]` suffix and a team by `organization/slug`. + * @param read - runs one GraphQL query. + * @param write - runs one GraphQL mutation. + * @param ref - pull request address. + * @param request - the reviewers to ask. + * @param signal - cancellation of both requests. + * @returns undefined once GitHub accepted the request, or why it refused. + */ +export async function requestGitHubReviews( + read: GraphqlReader, write: GraphqlWriter, ref: ChangeRequestRef, request: ForgeReviewersRequest, signal: AbortSignal, +): Promise { + if (request.reviewers.length === 0) return { code: 'failed', message: 'No reviewer was named' } + const id = await pullRequestNode(read, ref, null, signal) + if (typeof id !== 'string') return id + const logins = (kind: string): string[] => request.reviewers.filter(reviewer => reviewer.kind === kind).map(reviewer => reviewer.login) + const input: Record = { pullRequestId: id, union: true } + const users = logins('user') + const bots = logins('bot').map(login => login.endsWith('[bot]') ? login : `${login}[bot]`) + const teams = logins('team') + if (users.length > 0) input.userLogins = users + if (bots.length > 0) input.botLogins = bots + if (teams.length > 0) input.teamSlugs = teams + return await write(ref.repository.host, { query: REQUEST_REVIEWS_MUTATION, field: 'requestReviewsByLogin', variables: { input } }, signal) +} + +/** + * Update the head branch with `updatePullRequestBranch`. The head is read first and the update is refused once it is + * another commit; GitHub also checks `expectedHeadOid` itself. + * @param read - runs one GraphQL query. + * @param write - runs one GraphQL mutation. + * @param ref - pull request address. + * @param request - update method and the head commit the user confirmed. + * @param signal - cancellation of both requests. + * @returns undefined once GitHub accepted the update, `stale` when the head moved, or why GitHub refused. + * @throws when `request.headSha` is not a full commit object name. + */ +export async function updateGitHubBranch( + read: GraphqlReader, write: GraphqlWriter, ref: ChangeRequestRef, request: BranchUpdateRequest, signal: AbortSignal, +): Promise { + if (!isCommit(request.headSha)) throw new Error(`forge-github: invalid head commit ${JSON.stringify(request.headSha)}`) + const id = await pullRequestNode(read, ref, request.headSha, signal) + if (typeof id !== 'string') return id + return await write(ref.repository.host, { query: UPDATE_BRANCH_MUTATION, field: 'updatePullRequestBranch', variables: { + input: { pullRequestId: id, expectedHeadOid: request.headSha, updateMethod: request.method === 'rebase' ? 'REBASE' : 'MERGE' }, + } }, signal) +} + +/** + * List accounts a review can be requested from: GitHub's suggestions for the pull request when `query` is empty, then + * the accounts that can be assigned in the repository whose login or name matches `query`, without the author. + * @param read - runs one GraphQL query. + * @param ref - pull request address. + * @param query - text the login or name contains. + * @param signal - cancellation of the read. + * @returns at most 20 accounts, each once, or why GitHub did not list them. + */ +export async function gitHubReviewerCandidates( + read: GraphqlReader, ref: ChangeRequestRef, query: string, signal: AbortSignal, +): Promise { + const { host, owner, name } = checkedRepository(ref) + const search = query.trim() + const body = await read([ + 'api', 'graphql', '--hostname', host, '-f', `query=${CANDIDATES_QUERY}`, '-f', `owner=${owner}`, '-f', `name=${name}`, + '-F', `number=${ref.number}`, '-f', `search=${search}`, + ], signal) + if (!body.ok) return body.failure + const parsed = candidatesSchema.safeParse(body.body) + if (!parsed.success) return { code: 'unavailable', message: 'unexpected GitHub response to the reviewer listing' } + const repository = parsed.data.data.repository + if (repository === null) return { code: 'not-found', message: `repository ${owner}/${name} is not visible` } + const author = repository.pullRequest?.author?.login.toLowerCase() + const listed = new Map() + const add = (entry: z.infer, suggested: boolean): void => { + const key = entry.login.toLowerCase() + if (key !== author && !listed.has(key)) listed.set(key, { login: entry.login, name: entry.name, avatarUrl: entry.avatarUrl, suggested }) + } + if (search === '') for (const suggestion of repository.pullRequest?.suggestedReviewers ?? []) add(suggestion.reviewer, true) + for (const user of repository.assignableUsers.nodes) add(user, false) + return [...listed.values()].slice(0, CANDIDATES) +} diff --git a/packages/experimental/forge-github/src/provider.ts b/packages/experimental/forge-github/src/provider.ts index bd99a59cf6..f3aca26627 100644 --- a/packages/experimental/forge-github/src/provider.ts +++ b/packages/experimental/forge-github/src/provider.ts @@ -2,22 +2,25 @@ import { changeRequestKey } from '@deepseek-ai/dsh-experimental-forge' import type { - ChangeRequestKey, ChangeRequestRef, ChangeRequestSnapshot, ForgeActionFailure, ForgeCommitList, ForgeFailure, ForgeProvider, - ForgeReadiness, ForgeRepository, ForgeReviewData, ForgeReviewRequest, ForgeReviewResult, ForgeReviewWrite, ForgeReviewWriteResult, - MergeRequest, + BranchUpdateRequest, ChangeRequestKey, ChangeRequestRef, ChangeRequestSnapshot, ForgeActionFailure, ForgeCommitList, ForgeFailure, + ForgeProvider, ForgeReadiness, ForgeRepository, ForgeRerunRequest, ForgeReviewData, ForgeReviewerCandidate, ForgeReviewersRequest, + ForgeReviewRequest, ForgeReviewResult, ForgeReviewWrite, ForgeReviewWriteResult, ForgeViewedFiles, ForgeViewedRequest, MergeRequest, } from '@deepseek-ai/dsh-experimental-forge' import { listCommits } from './commits.ts' import type { GraphqlReader } from './commits.ts' +import { sendMutation, type GraphqlWriter } from './mutation.ts' import { GhOutputLimitError, GhTimeoutError, GhUnavailableError } from './gh.ts' import type { GhOutput, GhRunner } from './gh.ts' import { readComparison } from './compare.ts' import { - CHECKS_QUERY, hasGraphqlFields, HEAD_QUERY, mapCheckPageResponse, mapHeadResponse, mapPullRequestCommitsResponse, + actionsRunOf, CHECKS_QUERY, hasGraphqlFields, HEAD_QUERY, mapCheckPageResponse, mapHeadResponse, mapPullRequestCommitsResponse, mapSnapshotResponse, mapThreadPageResponse, PULL_REQUEST_COMMITS_QUERY, snapshotQuery, THREADS_QUERY, } from './graphql.ts' import type { PageResult, SnapshotPages } from './graphql.ts' import { checkedRepository, isCommit, parsePullRequestUrl, parseRemoteUrl } from './urls.ts' import { submitGitHubReview } from './review.ts' +import { readViewed, writeViewed } from './viewed.ts' +import { gitHubReviewerCandidates, requestGitHubReviews, updateGitHubBranch } from './overview.ts' import { writeGitHubReview } from './review-writes.ts' import { readReviewThreads } from './threads.ts' @@ -43,6 +46,8 @@ export interface GitHubLimits { readonly maxReviewThreads: number /** Most commits one commit listing returns. */ readonly maxCommits: number + /** Most files whose viewed marks one read lists. */ + readonly maxViewedFiles: number } /** Reads GitHub and GitHub Enterprise pull requests through a `gh` runner. */ @@ -81,7 +86,8 @@ export class GitHubProvider implements ForgeProvider { /** * @param gh - runner that executes `gh` on the host. * @param hosts - host names this provider serves, such as `github.com` and Enterprise hosts. - * @param limits - bounds on retained check and review bytes, counted and read review threads, and listed commits. + * @param limits - bounds on retained check and review bytes, counted and read review threads, listed commits, and listed + * viewed files. */ constructor(private readonly gh: GhRunner, hosts: readonly string[], private readonly limits: GitHubLimits) { this.hosts = new Set(hosts.map(host => host.toLowerCase())) @@ -251,6 +257,70 @@ export class GitHubProvider implements ForgeProvider { return await readComparison(async (args, operation) => await this.read(args, operation), ref.repository, base, head, signal) } + /** Read the viewer's viewed marks through GraphQL, at most `maxViewedFiles`, every page at `headSha`. */ + async viewedFiles(ref: ChangeRequestRef, headSha: string, signal: AbortSignal): Promise { + const failure = this.hostFailure(checkedRepository(ref).host) + if (failure !== undefined) return failure + return await readViewed(this.graphql, ref, headSha, this.limits.maxViewedFiles, signal) + } + + /** Set or clear the viewer's mark with `markFileAsViewed` or `unmarkFileAsViewed` after confirming the head. */ + async setViewed(ref: ChangeRequestRef, request: ForgeViewedRequest, signal: AbortSignal): Promise { + const failure = this.hostFailure(checkedRepository(ref).host) + if (failure !== undefined) return { code: 'failed', message: failure.message } + return await writeViewed(this.graphql, this.mutate, ref, request, signal) + } + + /** + * Rerun every workflow run with a failed GitHub Actions job on the head commit through the REST API; GitHub reruns + * its failed jobs with the jobs that depend on them. Other checks name no rerun. + */ + async rerunChecks(ref: ChangeRequestRef, request: ForgeRerunRequest, signal: AbortSignal): Promise { + const { host, owner, name } = checkedRepository(ref) + const failure = this.hostFailure(host) + if (failure !== undefined) return { code: 'failed', message: failure.message } + if (!isCommit(request.headSha)) throw new Error(`forge-github: invalid head commit ${JSON.stringify(request.headSha)}`) + const snapshot = await this.fetchChecks(ref, signal) + if ('code' in snapshot) return { code: snapshot.code === 'unauthenticated' ? 'unauthenticated' : 'failed', message: snapshot.message } + if (snapshot.headSha.toLowerCase() !== request.headSha.toLowerCase()) { + return { code: 'stale', message: `the pull request head moved from ${request.headSha} to ${snapshot.headSha}` } + } + const endpoint = `repos/${owner}/${name}/actions` + const runs = new Set() + for (const check of snapshot.checks) { + const run = check.state === 'failure' && check.rerun !== null ? actionsRunOf(check.rerun) : undefined + if (run !== undefined) runs.add(run) + } + if (runs.size === 0) return { code: 'failed', message: 'No failed GitHub Actions job of the head commit can be rerun' } + for (const run of runs) { + const refused = await this.act(['api', '--hostname', host, '--method', 'POST', `${endpoint}/runs/${run}/rerun-failed-jobs`], signal) + if (refused !== undefined) return refused + } + return undefined + } + + async requestReviews( + ref: ChangeRequestRef, request: ForgeReviewersRequest, signal: AbortSignal, + ): Promise { + const failure = this.hostFailure(checkedRepository(ref).host) + if (failure !== undefined) return { code: 'failed', message: failure.message } + return await requestGitHubReviews(this.graphql, this.mutate, ref, request, signal) + } + + async reviewerCandidates( + ref: ChangeRequestRef, query: string, signal: AbortSignal, + ): Promise { + const failure = this.hostFailure(checkedRepository(ref).host) + if (failure !== undefined) return failure + return await gitHubReviewerCandidates(this.graphql, ref, query, signal) + } + + async updateBranch(ref: ChangeRequestRef, request: BranchUpdateRequest, signal: AbortSignal): Promise { + const failure = this.hostFailure(checkedRepository(ref).host) + if (failure !== undefined) return { code: 'failed', message: failure.message } + return await updateGitHubBranch(this.graphql, this.mutate, ref, request, signal) + } + fileUrl(ref: ChangeRequestRef, commit: string, path: string): string { const { host, owner, name } = ref.repository return `https://${host}/${owner}/${name}/blob/${commit}/${encodedPath(path)}` @@ -301,6 +371,16 @@ export class GitHubProvider implements ForgeProvider { return { ok: true, body } } + /** + * Run one GraphQL mutation with its query and variables as JSON on standard input, never in arguments. A refusal, a + * `gh` that cannot start, a body that is not GraphQL, and GraphQL errors become failures; the write is never retried. + */ + /** Every refusal and every unconfirmed outcome fails: these mutations set a state, so trying again is safe. */ + private readonly mutate: GraphqlWriter = async (host, mutation, signal) => { + const sent = await sendMutation(this.gh, host, mutation, signal) + return sent.ok ? undefined : { code: 'failed', message: sent.message } + } + /** Run one changing `gh` command; a refusal or a `gh` that cannot start becomes a failure. */ private async act(args: readonly string[], signal: AbortSignal): Promise { const output = await this.attempt(args, signal) diff --git a/packages/experimental/forge-github/src/pull-request-node.ts b/packages/experimental/forge-github/src/pull-request-node.ts new file mode 100644 index 0000000000..4f155f5e1a --- /dev/null +++ b/packages/experimental/forge-github/src/pull-request-node.ts @@ -0,0 +1,42 @@ +/** The node id of a pull request that a GraphQL mutation names, read together with the head the write must still find. */ + +import type { ChangeRequestRef, ForgeActionFailure } from '@deepseek-ai/dsh-experimental-forge' +import { z } from 'zod' +import type { GraphqlReader } from './commits.ts' +import { checkedRepository } from './urls.ts' + +/** Node id and head commit of one pull request; variables `owner` and `name` are strings, `number` is an integer. */ +export const PULL_REQUEST_NODE_QUERY = `query($owner: String!, $name: String!, $number: Int!) { + repository(owner: $owner, name: $name) { pullRequest(number: $number) { id headRefOid } } +}` + +const nodeSchema = z.object({ + data: z.object({ repository: z.object({ pullRequest: z.object({ id: z.string(), headRefOid: z.string() }).nullable() }).nullable() }), +}) + +/** + * Read a pull request's node id before a write, refusing once its head is not `headSha`. + * @param read - runs one GraphQL query. + * @param ref - pull request address. + * @param headSha - head commit the write must still find, or null for a write that does not depend on the head. + * @param signal - cancellation of the read. + * @returns the node id, `stale` when the head moved, or why the write must not proceed. + */ +export async function pullRequestNode( + read: GraphqlReader, ref: ChangeRequestRef, headSha: string | null, signal: AbortSignal, +): Promise { + const { host, owner, name } = checkedRepository(ref) + const node = await read([ + 'api', 'graphql', '--hostname', host, '-f', `query=${PULL_REQUEST_NODE_QUERY}`, '-f', `owner=${owner}`, '-f', `name=${name}`, + '-F', `number=${ref.number}`, + ], signal) + if (!node.ok) return { code: node.failure.code === 'unauthenticated' ? 'unauthenticated' : 'failed', message: node.failure.message } + const parsed = nodeSchema.safeParse(node.body) + if (!parsed.success) return { code: 'failed', message: 'unexpected GitHub response to the pull request read' } + const pull = parsed.data.data.repository?.pullRequest + if (pull == null) return { code: 'failed', message: `pull request ${ref.number} was not found` } + if (headSha !== null && pull.headRefOid.toLowerCase() !== headSha.toLowerCase()) { + return { code: 'stale', message: `the pull request head moved from ${headSha} to ${pull.headRefOid}` } + } + return pull.id +} diff --git a/packages/experimental/forge-github/src/review-writes.ts b/packages/experimental/forge-github/src/review-writes.ts index 86ae145d91..00a2cde7d8 100644 --- a/packages/experimental/forge-github/src/review-writes.ts +++ b/packages/experimental/forge-github/src/review-writes.ts @@ -6,7 +6,8 @@ import type { import { assertNever } from '@deepseek-ai/dsh-util-values' import { z } from 'zod' import type { GraphqlReader } from './commits.ts' -import { GhUnavailableError, type GhOutput, type GhRunner } from './gh.ts' +import type { GhRunner } from './gh.ts' +import { sendMutation, type GraphqlMutation, type MutationResult } from './mutation.ts' import { checkedRepository } from './urls.ts' /** @@ -68,15 +69,6 @@ export const DELETE_REVIEW_MUTATION = 'mutation($review: ID!) { deletePullReques const EVENTS = { comment: 'COMMENT', approve: 'APPROVE', 'request-changes': 'REQUEST_CHANGES' } as const -/** HTTP statuses that mean GitHub refused the request, so it changed nothing. */ -const REFUSED = /\(HTTP (?:400|401|403|404|409|422)\)/ - -/** - * GraphQL error types that mean GitHub refused a mutation before applying it. An error without one of them, such as - * GitHub's "Something went wrong … may be the result of a timeout", leaves the outcome unknown. - */ -const REFUSALS: ReadonlySet = new Set(['FORBIDDEN', 'INSUFFICIENT_SCOPES', 'NOT_FOUND', 'RATE_LIMITED', 'UNPROCESSABLE']) - const checkSchema = z.object({ data: z.object({ repository: z.object({ pullRequest: z.object({ id: z.string(), @@ -86,18 +78,6 @@ const checkSchema = z.object({ data: z.object({ target: z.object({ pullRequest: z.object({ id: z.string() }).optional() }).nullable().optional(), }) }) -const graphqlErrors = z.object({ errors: z.array(z.object({ message: z.string(), type: z.string().optional() })).min(1) }) - -/** One mutation and the payload field that holds its result. */ -interface Mutation { - readonly query: string - readonly field: string - readonly variables: Readonly> -} - -/** A mutation's result: the payload on success, else the write's outcome. */ -type Sent = { readonly ok: true; readonly payload: unknown } | Extract - const stringId = z.object({ id: z.string() }) /** @@ -136,10 +116,10 @@ export async function writeGitHubReview( } const pending = pull.reviews.nodes.find(review => review.viewerDidAuthor)?.id ?? null signal.throwIfAborted() - const send = async (mutation: Mutation): Promise => await sendMutation(gh, host, mutation, signal) - const done = (sent: Sent): ForgeReviewWriteResult => sent.ok ? { ok: true } : sent + const send = async (mutation: GraphqlMutation): Promise => await sendMutation(gh, host, mutation, signal) + const done = (sent: MutationResult): ForgeReviewWriteResult => sent.ok ? { ok: true } : sent /** Find the pending review, starting one at the head without threads when the user has none. */ - const pendingReview = async (): Promise<{ readonly ok: true; readonly id: string } | Extract> => { + const pendingReview = async (): Promise<{ readonly ok: true; readonly id: string } | Extract> => { if (pending !== null) return { ok: true, id: pending } const started = await send({ query: ADD_REVIEW_MUTATION, field: 'addPullRequestReview', variables: { pull: pull.id, commit: write.headSha, threads: null } }) @@ -210,45 +190,3 @@ function draftThread(comment: ForgeLineComment): Readonly { - let output: GhOutput - try { - output = await gh(['api', 'graphql', '--hostname', host, '--input', '-'], signal, - JSON.stringify({ query: mutation.query, variables: mutation.variables })) - } catch (error) { - const message = error instanceof Error ? error.message : String(error) - return { ok: false, code: error instanceof GhUnavailableError ? 'failed' : 'unknown', message } - } - const body = parse(output.stdout) - // A payload means GitHub applied the mutation, even beside errors about the fields it selects. - const payload = z.object({ data: z.record(z.string(), z.unknown()) }).safeParse(body) - const value = payload.success ? payload.data.data[mutation.field] : undefined - if (value !== undefined && value !== null) return { ok: true, payload: value } - const errors = graphqlErrors.safeParse(body) - if (errors.success) { - const refused = errors.data.errors.every(error => error.type !== undefined && REFUSALS.has(error.type)) - return { ok: false, code: refused ? 'failed' : 'unknown', message: errors.data.errors.map(error => error.message).join('; ') } - } - if (output.exitCode !== 0) { - const message = output.stderr.trim() || output.stdout.trim() || `gh exited with ${output.exitCode}` - return { ok: false, code: REFUSED.test(output.stderr) ? 'failed' : 'unknown', message } - } - return { ok: false, code: 'unknown', message: `unexpected GitHub response to ${mutation.field}` } -} - -function parse(text: string): unknown { - let value: unknown - try { - value = JSON.parse(text) - } catch (error) { - void error // gh prints diagnostics instead of JSON when a request fails before GitHub answers. - return undefined - } - return value -} diff --git a/packages/experimental/forge-github/src/viewed.ts b/packages/experimental/forge-github/src/viewed.ts new file mode 100644 index 0000000000..f9cedeeddf --- /dev/null +++ b/packages/experimental/forge-github/src/viewed.ts @@ -0,0 +1,128 @@ +/** The signed-in user's viewed marks on pull request files through GraphQL, pinned to one head commit. */ + +import type { + ChangeRequestRef, ForgeActionFailure, ForgeFailure, ForgeViewedFiles, ForgeViewedRequest, ForgeViewedState, +} from '@deepseek-ai/dsh-experimental-forge' +import { pullRequestNode } from './pull-request-node.ts' +import { z } from 'zod' +import type { GraphqlReader } from './commits.ts' +import type { GraphqlWriter } from './mutation.ts' +import { checkedRepository, isCommit } from './urls.ts' + +/** Files GitHub returns per GraphQL page, its connection maximum. */ +const PAGE = 100 + +/** One page of a pull request's files with the viewer's marks and its head; `cursor` continues after the previous page. */ +export const VIEWED_QUERY = `query($owner: String!, $name: String!, $number: Int!, $first: Int!, $cursor: String) { + repository(owner: $owner, name: $name) { + pullRequest(number: $number) { + headRefOid + files(first: $first, after: $cursor) { totalCount pageInfo { hasNextPage endCursor } nodes { path viewerViewedState } } + } + } +}` + +/** Mark one file viewed; variables `id` (pull request node id) and `path`, sent on standard input. */ +export const MARK_VIEWED_MUTATION = `mutation($id: ID!, $path: String!) { + markFileAsViewed(input: { pullRequestId: $id, path: $path }) { clientMutationId } +}` + +/** Clear one file's viewed mark; variables `id` (pull request node id) and `path`, sent on standard input. */ +export const UNMARK_VIEWED_MUTATION = `mutation($id: ID!, $path: String!) { + unmarkFileAsViewed(input: { pullRequestId: $id, path: $path }) { clientMutationId } +}` + +const STATES: Readonly> = { VIEWED: 'viewed', UNVIEWED: 'unviewed', DISMISSED: 'dismissed' } + +const pageSchema = z.object({ + data: z.object({ + repository: z.object({ + pullRequest: z.object({ + headRefOid: z.string(), + files: z.object({ + totalCount: z.number().int().nonnegative(), + pageInfo: z.object({ hasNextPage: z.boolean(), endCursor: z.string().nullable() }), + nodes: z.array(z.object({ path: z.string(), viewerViewedState: z.string() })), + }).nullable(), + }).nullable(), + }).nullable(), + }), +}) + +/** + * Read the viewer's marks on a pull request's files, at most `limit`, reading pages until the limit or the last file. + * Every page must name `headSha` as the head, so the marks never mix two pushes, and a cursor no earlier page returned, + * so the listing ends. A state GitHub adds later reads as `unviewed`. + * @param read - runs one GraphQL request. + * @param ref - pull request address. + * @param headSha - head commit the marks must be read at. + * @param limit - most files listed. + * @param signal - cancellation of every page. + * @returns the marks at `headSha`, `stale` once the head is another commit, or why GitHub did not list them. + * @throws when `headSha` is not a full commit object name. + */ +export async function readViewed( + read: GraphqlReader, + ref: ChangeRequestRef, + headSha: string, + limit: number, + signal: AbortSignal, +): Promise { + const { host, owner, name } = checkedRepository(ref) + if (!isCommit(headSha)) throw new Error(`forge-github: invalid head commit ${JSON.stringify(headSha)}`) + const files: Record = {} + let listed = 0 + const cursors = new Set() + let cursor: string | null = null + for (;;) { + const body = await read([ + 'api', 'graphql', '--hostname', host, '-f', `query=${VIEWED_QUERY}`, '-f', `owner=${owner}`, '-f', `name=${name}`, + '-F', `number=${ref.number}`, '-F', `first=${Math.min(PAGE, limit - listed)}`, ...cursor === null ? [] : ['-f', `cursor=${cursor}`], + ], signal) + if (!body.ok) return body.failure + const parsed = pageSchema.safeParse(body.body) + if (!parsed.success) return { code: 'unavailable', message: 'unexpected GitHub response to the viewed file read' } + const pull = parsed.data.data.repository?.pullRequest + if (pull == null) return { code: 'not-found', message: `pull request ${ref.number} was not found` } + if (pull.headRefOid.toLowerCase() !== headSha.toLowerCase()) { + return { code: 'stale', message: `the pull request head moved from ${headSha} to ${pull.headRefOid}` } + } + // GitHub answers null for the files of a pull request whose diff it cannot list. + if (pull.files === null) return { code: 'unavailable', message: 'GitHub did not list the pull request files' } + const { totalCount, pageInfo: { hasNextPage, endCursor }, nodes } = pull.files + for (const node of nodes) files[node.path] = STATES[node.viewerViewedState] ?? 'unviewed' + listed += nodes.length + if (!hasNextPage || listed >= limit) return { headSha: pull.headRefOid, files, truncated: totalCount > listed } + if (endCursor === null || cursors.has(endCursor)) return { code: 'unavailable', message: 'GitHub file pagination did not advance' } + cursors.add(endCursor) + cursor = endCursor + } +} + +/** + * Set or clear the viewer's mark on one file. GitHub's mutations take no head commit, so the pull request head is read + * first and the write is refused once it is another commit; a push between that read and the write leaves the mark on + * the file as the new head has it. + * @param read - runs one GraphQL query. + * @param write - runs one GraphQL mutation. + * @param ref - pull request address. + * @param request - the file, its mark, and the head commit the user saw. + * @param signal - cancellation of both requests. + * @returns undefined once GitHub saved the mark, `stale` when the head moved, or why GitHub refused. + * @throws when `request.headSha` is not a full commit object name. + */ +export async function writeViewed( + read: GraphqlReader, + write: GraphqlWriter, + ref: ChangeRequestRef, + request: ForgeViewedRequest, + signal: AbortSignal, +): Promise { + if (!isCommit(request.headSha)) throw new Error(`forge-github: invalid head commit ${JSON.stringify(request.headSha)}`) + const id = await pullRequestNode(read, ref, request.headSha, signal) + if (typeof id !== 'string') return id + const variables = { id, path: request.path } + return await write(ref.repository.host, request.viewed + ? { query: MARK_VIEWED_MUTATION, field: 'markFileAsViewed', variables } + : { query: UNMARK_VIEWED_MUTATION, field: 'unmarkFileAsViewed', variables }, signal) +} diff --git a/packages/experimental/forge-github/tests/fixtures.ts b/packages/experimental/forge-github/tests/fixtures.ts index bc5d1297b0..7ec8fb50ea 100644 --- a/packages/experimental/forge-github/tests/fixtures.ts +++ b/packages/experimental/forge-github/tests/fixtures.ts @@ -18,7 +18,10 @@ export function checkRun(name: string, status: string, conclusion: string | null detailsUrl: `https://github.com/octo/demo/actions/runs/1/job/${name}`, startedAt: status === 'QUEUED' ? null : '2026-10-09T01:00:00Z', completedAt: status === 'COMPLETED' ? '2026-10-09T01:02:07Z' : null, - checkSuite: { app: { id: 'github-actions' }, workflowRun: workflow === null ? null : { event: 'pull_request', workflow: { id: workflow, name: workflow } } }, + checkSuite: { + app: { id: 'github-actions' }, + workflowRun: workflow === null ? null : { databaseId: 7, event: 'pull_request', workflow: { id: workflow, name: workflow } }, + }, } } @@ -60,7 +63,13 @@ export function pullRequestNode(number: number, overrides: Record { mergeability: 'mergeable', mergeReady: true, mergeMethods: ['merge', 'squash'], + branchUpdates: [], reviewDecision: 'none', + reviewers: [], + reviewersTruncated: false, + canRequestReviews: true, checks: [{ name: 'lint', state: 'success', @@ -77,11 +82,15 @@ describe('snapshot mapping', () => { workflow: 'ci', startedAt: '2026-10-09T01:00:00Z', completedAt: '2026-10-09T01:02:07Z', + rerun: 'actions:7', }], checksRollup: 'success', checksTruncated: false, + canRerunChecks: true, unresolvedThreads: 2, threadsTruncated: false, + closingIssues: [], + closingIssuesTruncated: false, updatedAt: '2026-10-09T01:02:03Z', closedAt: null, }) @@ -100,7 +109,7 @@ describe('snapshot mapping', () => { const old = checkRun('build', 'COMPLETED', 'FAILURE') const newer = { ...checkRun('build', 'QUEUED', null), databaseId: 9 } const suite = (app: string, workflow: string, event: string) => ({ app: { id: app }, - workflowRun: { event, workflow: { id: workflow, name: 'CI' } } }) + workflowRun: { databaseId: 7, event, workflow: { id: workflow, name: 'CI' } } }) const result = await single(pullRequestNode(1, {}, [ old, newer, { ...old, databaseId: 2 }, { ...old, checkSuite: suite('github-actions', 'ci', 'push') }, @@ -212,7 +221,7 @@ describe('snapshot mapping', () => { ['EXPECTED', 'pending'], ])('maps status context %s to %s', async (state, expected) => { expect((await single(pullRequestNode(1, {}, [statusContext('deploy', state)]))).checks).toEqual([{ - name: 'deploy', state: expected, url: null, workflow: null, startedAt: null, completedAt: null, + name: 'deploy', state: expected, url: null, workflow: null, startedAt: null, completedAt: null, rerun: null, }]) }) @@ -452,3 +461,95 @@ describe('head branch lookup mapping', () => { expect(() => mapHeadResponse({ data: {} }, demo, 'topic')).toThrow('forge-github: unexpected GitHub response to the head branch lookup') }) }) + +describe('overview mapping', () => { + const user = (login: string) => ({ __typename: 'User', login, avatarUrl: `https://avatars.example/${login}` }) + const review = (state: string, author: unknown, oid: string | null = 'f'.repeat(40)) => ({ state, commit: oid === null ? null : { oid }, author }) + + it('lists requested reviewers in host order, then other reviewers, each with their latest outcome', async () => { + const snapshot = await single(pullRequestNode(1, { + reviewRequests: { totalCount: 4, nodes: [ + { asCodeOwner: false, requestedReviewer: user('lin') }, + { asCodeOwner: true, requestedReviewer: { __typename: 'Team', combinedSlug: 'octo/forge', avatarUrl: null } }, + { asCodeOwner: false, requestedReviewer: { __typename: 'Bot', login: 'copilot', avatarUrl: null } }, + { asCodeOwner: false, requestedReviewer: { __typename: 'Mannequin', login: 'ghost' } }, + { asCodeOwner: false, requestedReviewer: null }, + ] }, + latestReviews: { totalCount: 4, nodes: [ + review('COMMENTED', { __typename: 'Bot', login: 'review-bot', avatarUrl: null }), + review('COMMENTED', user('zhou'), 'e'.repeat(40)), + review('COMMENTED', user('octo')), + review('PENDING', user('qian')), + review('COMMENTED', null), + ] }, + latestOpinionatedReviews: { totalCount: 2, nodes: [review('CHANGES_REQUESTED', user('zhou'), 'e'.repeat(40)), review('APPROVED', user('LIN'), null)] }, + })) + expect(snapshot.reviewers).toEqual([ + { kind: 'user', login: 'LIN', avatarUrl: 'https://avatars.example/lin', requested: true, codeOwner: false, verdict: 'approved', reviewedSha: null }, + { kind: 'team', login: 'octo/forge', avatarUrl: null, requested: true, codeOwner: true, verdict: null, reviewedSha: null }, + { kind: 'bot', login: 'copilot', avatarUrl: null, requested: true, codeOwner: false, verdict: null, reviewedSha: null }, + { kind: 'bot', login: 'review-bot', avatarUrl: null, requested: false, codeOwner: false, verdict: 'commented', reviewedSha: 'f'.repeat(40) }, + { kind: 'user', login: 'zhou', avatarUrl: 'https://avatars.example/zhou', requested: false, codeOwner: false, + verdict: 'changes-requested', reviewedSha: 'e'.repeat(40) }, + ]) + expect(snapshot.reviewersTruncated).toBe(false) + }) + + it.each([ + ['review requests', { reviewRequests: { totalCount: 30, nodes: [] } }], + ['reviews', { latestReviews: { totalCount: 30, nodes: [] } }], + ['opinionated reviews', { latestOpinionatedReviews: { totalCount: 30, nodes: [] } }], + ])('reports more %s than it read as an incomplete reviewer list', async (_label, overrides) => { + expect((await single(pullRequestNode(1, overrides))).reviewersTruncated).toBe(true) + }) + + it.each([ + ['an open, mergeable head the viewer may update', {}, ['merge']], + ['a head that can also be rebased', { canBeRebased: true }, ['merge', 'rebase']], + ['a conflicting head', { mergeable: 'CONFLICTING' }, []], + ['a closed pull request', { state: 'CLOSED' }, []], + ['a head the viewer may not update', { viewerCanUpdateBranch: false }, []], + ])('offers branch updates for %s', async (_label, overrides, updates) => { + expect((await single(pullRequestNode(1, { viewerCanUpdateBranch: true, ...overrides }))).branchUpdates).toEqual(updates) + }) + + it.each([ + ['TRIAGE', 'OPEN', true, false], + ['WRITE', 'OPEN', true, true], + ['READ', 'OPEN', false, false], + ['ADMIN', 'MERGED', false, true], + ])('lets a %s viewer of a %s pull request request reviews: %s, and rerun checks: %s', async (permission, state, requests, reruns) => { + const snapshot = await single(pullRequestNode(1, { state }), repositorySettings({ viewerPermission: permission })) + expect([snapshot.canRequestReviews, snapshot.canRerunChecks]).toEqual([requests, reruns]) + }) + + it('grants neither without readable repository settings', async () => { + const snapshot = await single(pullRequestNode(1), null) + expect([snapshot.canRequestReviews, snapshot.canRerunChecks]).toEqual([false, false]) + }) + + it('names a rerun only for a check of a workflow run with a database id', async () => { + const run = checkRun('lint', 'COMPLETED', 'FAILURE') + const snapshot = await single(pullRequestNode(1, {}, [ + run, + { ...checkRun('test', 'COMPLETED', 'FAILURE'), checkSuite: { app: { id: 'github-actions' }, workflowRun: null } }, + { ...checkRun('e2e', 'COMPLETED', 'FAILURE'), checkSuite: { app: { id: 'github-actions' }, + workflowRun: { databaseId: null, event: 'pull_request', workflow: { id: 'e2e', name: 'e2e' } } } }, + ])) + expect(snapshot.checks.map(check => [check.name, check.rerun])).toEqual([['lint', 'actions:7'], ['test', null], ['e2e', null]]) + expect(actionsRunOf('actions:7' as ForgeCheckId)).toBe(7) + expect(actionsRunOf('status:7' as ForgeCheckId)).toBeUndefined() + }) + + it('maps the linked issues of any repository on the host, noting more than it read', async () => { + const snapshot = await single(pullRequestNode(1, { closingIssuesReferences: { totalCount: 3, nodes: [ + { number: 6, title: 'Show progress', state: 'OPEN', url: 'https://github.com/octo/demo/issues/6', repository: { name: 'demo', owner: { login: 'octo' } } }, + { number: 2, title: 'Rerun', state: 'CLOSED', url: 'https://github.com/octo/tracker/issues/2', repository: { name: 'tracker', owner: { login: 'octo' } } }, + ] } })) + expect(snapshot.closingIssues).toEqual([ + { repository: demo, number: 6, title: 'Show progress', state: 'open', url: 'https://github.com/octo/demo/issues/6' }, + { repository: { ...demo, name: 'tracker' }, number: 2, title: 'Rerun', state: 'closed', url: 'https://github.com/octo/tracker/issues/2' }, + ]) + expect(snapshot.closingIssuesTruncated).toBe(true) + }) +}) diff --git a/packages/experimental/forge-github/tests/overview.spec.ts b/packages/experimental/forge-github/tests/overview.spec.ts new file mode 100644 index 0000000000..6890327d7c --- /dev/null +++ b/packages/experimental/forge-github/tests/overview.spec.ts @@ -0,0 +1,135 @@ +import { describe, expect, it, vi } from 'vitest' +import type { GraphqlReader } from '../src/commits.ts' +import type { GraphqlWriter } from '../src/mutation.ts' +import { + CANDIDATES_QUERY, gitHubReviewerCandidates, REQUEST_REVIEWS_MUTATION, requestGitHubReviews, UPDATE_BRANCH_MUTATION, updateGitHubBranch, +} from '../src/overview.ts' +import { pullRequestNode } from '../src/pull-request-node.ts' +import { pull } from './fixtures.ts' + +const HEAD = 'f'.repeat(40) +const signal = new AbortController().signal + +function reader(...bodies: unknown[]): { read: GraphqlReader; calls: (readonly string[])[] } { + const calls: (readonly string[])[] = [] + return { + calls, + read: async (args) => { + calls.push(args) + const body = bodies.shift() + if (body instanceof Error) return { ok: false, failure: { code: body.message === 'signed out' ? 'unauthenticated' : 'unavailable', message: body.message } } + return { ok: true, body } + }, + } +} + +const node = (headRefOid = HEAD) => ({ data: { repository: { pullRequest: { id: 'PR_7', headRefOid } } } }) + +describe('pull request node reads', () => { + it.each([ + ['a head that moved', node('e'.repeat(40)), HEAD, { code: 'stale', message: `the pull request head moved from ${HEAD} to ${'e'.repeat(40)}` }], + ['an unexpected response', { data: {} }, HEAD, { code: 'failed', message: 'unexpected GitHub response to the pull request read' }], + ['a missing pull request', { data: { repository: { pullRequest: null } } }, HEAD, { code: 'failed', message: 'pull request 7 was not found' }], + ['a missing repository', { data: { repository: null } }, null, { code: 'failed', message: 'pull request 7 was not found' }], + ['a refused read', new Error('rate limited'), null, { code: 'failed', message: 'rate limited' }], + ['a missing sign-in', new Error('signed out'), null, { code: 'unauthenticated', message: 'signed out' }], + ])('refuses %s', async (_label, body, head, failure) => { + await expect(pullRequestNode(reader(body).read, pull(7), head, signal)).resolves.toEqual(failure) + }) + + it('returns the node id at the head, or at any head without one, comparing heads without regard to case', async () => { + await expect(pullRequestNode(reader(node()).read, pull(7), HEAD.toUpperCase(), signal)).resolves.toBe('PR_7') + await expect(pullRequestNode(reader(node('e'.repeat(40))).read, pull(7), null, signal)).resolves.toBe('PR_7') + }) +}) + +describe('review requests', () => { + it('adds users, bots with the bot suffix, and teams by login to the requests GitHub holds', async () => { + const write = vi.fn(async () => undefined) + const reviewers = [ + { kind: 'user' as const, login: 'mona' }, { kind: 'bot' as const, login: 'copilot' }, { kind: 'bot' as const, login: 'helper[bot]' }, + { kind: 'team' as const, login: 'octo/forge' }, + ] + await expect(requestGitHubReviews(reader(node()).read, write, pull(7), { reviewers }, signal)).resolves.toBeUndefined() + expect(write).toHaveBeenCalledWith('github.com', { query: REQUEST_REVIEWS_MUTATION, field: 'requestReviewsByLogin', variables: { input: { + pullRequestId: 'PR_7', union: true, userLogins: ['mona'], botLogins: ['copilot[bot]', 'helper[bot]'], teamSlugs: ['octo/forge'], + } } }, signal) + }) + + it('names only the kinds it requests, at any head', async () => { + const write = vi.fn(async () => ({ code: 'failed', message: 'Could not resolve user' })) + await expect(requestGitHubReviews(reader(node('e'.repeat(40))).read, write, pull(7), { reviewers: [{ kind: 'user', login: 'mona' }] }, signal)) + .resolves.toEqual({ code: 'failed', message: 'Could not resolve user' }) + expect(write.mock.calls[0]?.[1].variables).toEqual({ input: { pullRequestId: 'PR_7', union: true, userLogins: ['mona'] } }) + await requestGitHubReviews(reader(node()).read, write, pull(7), { reviewers: [{ kind: 'team', login: 'octo/forge' }] }, signal) + expect(write.mock.calls[1]?.[1].variables).toEqual({ input: { pullRequestId: 'PR_7', union: true, teamSlugs: ['octo/forge'] } }) + }) + + it('refuses an empty request without reading, and a failed node read without writing', async () => { + const write = vi.fn() + const empty = reader() + await expect(requestGitHubReviews(empty.read, write, pull(7), { reviewers: [] }, signal)).resolves.toEqual({ code: 'failed', message: 'No reviewer was named' }) + expect(empty.calls).toEqual([]) + await expect(requestGitHubReviews(reader(new Error('down')).read, write, pull(7), { reviewers: [{ kind: 'user', login: 'mona' }] }, signal)) + .resolves.toEqual({ code: 'failed', message: 'down' }) + expect(write).not.toHaveBeenCalled() + }) +}) + +describe('branch updates', () => { + it.each([['merge', 'MERGE'], ['rebase', 'REBASE']] as const)('updates by %s with the confirmed head as GitHub expects it', async (method, updateMethod) => { + const write = vi.fn(async () => undefined) + await expect(updateGitHubBranch(reader(node()).read, write, pull(7), { method, headSha: HEAD }, signal)).resolves.toBeUndefined() + expect(write).toHaveBeenCalledWith('github.com', { query: UPDATE_BRANCH_MUTATION, field: 'updatePullRequestBranch', + variables: { input: { pullRequestId: 'PR_7', expectedHeadOid: HEAD, updateMethod } } }, signal) + }) + + it('refuses a moved head without writing and an invalid head without reading', async () => { + const write = vi.fn() + await expect(updateGitHubBranch(reader(node('e'.repeat(40))).read, write, pull(7), { method: 'merge', headSha: HEAD }, signal)) + .resolves.toMatchObject({ code: 'stale' }) + expect(write).not.toHaveBeenCalled() + const none = reader() + await expect(updateGitHubBranch(none.read, write, pull(7), { method: 'merge', headSha: 'main' }, signal)) + .rejects.toThrow('forge-github: invalid head commit "main"') + expect(none.calls).toEqual([]) + }) +}) + +describe('reviewer candidates', () => { + const account = (login: string, name: string | null = null) => ({ login, name, avatarUrl: null }) + const listing = (suggested: readonly unknown[], users: readonly unknown[], author: unknown = { login: 'Octo' }) => ({ data: { repository: { + assignableUsers: { nodes: users }, + pullRequest: { author, suggestedReviewers: suggested.map(reviewer => ({ reviewer })) }, + } } }) + + it('lists the suggestions first without the author, then the accounts, each once', async () => { + const { read, calls } = reader(listing([account('lin', 'Lin'), account('octo')], [account('LIN'), account('mona', 'Mona'), account('octo')])) + await expect(gitHubReviewerCandidates(read, pull(7), ' ', signal)).resolves.toEqual([ + { login: 'lin', name: 'Lin', avatarUrl: null, suggested: true }, + { login: 'mona', name: 'Mona', avatarUrl: null, suggested: false }, + ]) + expect(calls[0]).toEqual(['api', 'graphql', '--hostname', 'github.com', '-f', `query=${CANDIDATES_QUERY}`, '-f', 'owner=octo', '-f', 'name=demo', + '-F', 'number=7', '-f', 'search=']) + }) + + it('leaves suggestions out of a search and keeps at most twenty accounts', async () => { + const users = Array.from({ length: 25 }, (_, index) => account(`user${index}`)) + const result = await gitHubReviewerCandidates(reader(listing([account('lin')], users, null)).read, pull(7), 'user', signal) + expect('code' in result ? result : result.map(entry => entry.login)).toEqual(users.slice(0, 20).map(user => user.login)) + }) + + it('lists accounts when the pull request is gone', async () => { + const body = { data: { repository: { assignableUsers: { nodes: [account('mona')] }, pullRequest: null } } } + await expect(gitHubReviewerCandidates(reader(body).read, pull(7), '', signal)) + .resolves.toEqual([{ login: 'mona', name: null, avatarUrl: null, suggested: false }]) + }) + + it.each([ + ['a refused read', new Error('down'), { code: 'unavailable', message: 'down' }], + ['an unexpected response', { data: {} }, { code: 'unavailable', message: 'unexpected GitHub response to the reviewer listing' }], + ['a hidden repository', { data: { repository: null } }, { code: 'not-found', message: 'repository octo/demo is not visible' }], + ])('reports %s', async (_label, body, failure) => { + await expect(gitHubReviewerCandidates(reader(body).read, pull(7), '', signal)).resolves.toEqual(failure) + }) +}) diff --git a/packages/experimental/forge-github/tests/provider.spec.ts b/packages/experimental/forge-github/tests/provider.spec.ts index d923d7425e..a9a3d0c20f 100644 --- a/packages/experimental/forge-github/tests/provider.spec.ts +++ b/packages/experimental/forge-github/tests/provider.spec.ts @@ -3,6 +3,8 @@ import { describe, expect, it, vi } from 'vitest' import { GhOutputLimitError, GhTimeoutError, GhUnavailableError } from '../src/gh.ts' import type { GhOutput, GhRunner } from '../src/gh.ts' import { PULL_REQUEST_COMMITS_QUERY, THREADS_QUERY } from '../src/graphql.ts' +import { CANDIDATES_QUERY } from '../src/overview.ts' +import { VIEWED_QUERY } from '../src/viewed.ts' import { GitHubProvider } from '../src/provider.ts' import type { GitHubLimits } from '../src/provider.ts' import { checkRun, demo, pull, pullRequestNode, threadPage } from './fixtures.ts' @@ -25,7 +27,7 @@ function output(stdout: unknown, exitCode = 0, stderr = ''): GhOutput { return { exitCode, stdout: typeof stdout === 'string' ? stdout : JSON.stringify(stdout), stderr } } -const limits: GitHubLimits = { maxOutputBytes: 8_388_608, maxReviewThreads: 1_000, maxCommits: 250 } +const limits: GitHubLimits = { maxOutputBytes: 8_388_608, maxReviewThreads: 1_000, maxCommits: 250, maxViewedFiles: 3_000 } function provider(run: GhRunner): GitHubProvider { return new GitHubProvider(run, ['github.com', 'GHE.corp.example'], limits) @@ -706,3 +708,134 @@ it('rejects readiness, actions, and content reads for an unconfigured host witho await expect(subject.compare(unsafe, 'a'.repeat(40), 'b'.repeat(40), signal)).rejects.toThrow(invalid) expect(gh.calls).toEqual([]) }) + +describe('GitHub provider overview and viewed marks', () => { + const HEAD = 'f'.repeat(40) + const unconfigured = pull(1, { ...demo, host: 'gitlab.com' }) + const node = { data: { repository: { pullRequest: { id: 'PR_1', headRefOid: HEAD, baseRefOid: 'e'.repeat(40) } } } } + /** A double whose GraphQL reads answer `reads` by query and whose writes take their body from standard input. */ + function double( + reads: (query: string) => unknown, + write: (body: { query: string; variables: unknown }) => GhOutput = body => output({ data: { [/\{\s*(\w+)\(input:/.exec(body.query)?.[1] ?? '']: {} } }), + ) { + const inputs: unknown[] = [] + const calls: string[][] = [] + const run: GhRunner = async (args, _signal, input) => { + calls.push([...args]) + if (args.includes('--input')) { + const body = JSON.parse(input ?? '') as { query: string; variables: unknown } + inputs.push(body) + return write(body) + } + if (args[1] === 'graphql') return output(reads(args.find(arg => arg.startsWith('query='))?.slice('query='.length) ?? '')) + return output('') + } + return { run, inputs, calls } + } + + it('reads viewed marks through the files listing, bounded by maxViewedFiles', async () => { + const gh = double(query => query === VIEWED_QUERY ? { data: { repository: { pullRequest: { headRefOid: HEAD, files: { + totalCount: 1, pageInfo: { hasNextPage: false, endCursor: null }, nodes: [{ path: 'a.ts', viewerViewedState: 'VIEWED' }], + } } } } } : {}) + const subject = new GitHubProvider(gh.run, ['github.com'], { ...limits, maxViewedFiles: 7 }) + await expect(subject.viewedFiles(pull(1), HEAD, signal)).resolves.toEqual({ headSha: HEAD, files: { 'a.ts': 'viewed' }, truncated: false }) + expect(gh.calls[0]).toContain('first=7') + }) + + it('writes a viewed mark as JSON on standard input, never in the arguments', async () => { + const gh = double(() => node) + await expect(provider(gh.run).setViewed(pull(1), { path: 'src/$(x).ts', viewed: true, headSha: HEAD }, signal)).resolves.toBeUndefined() + expect(gh.calls[1]).toEqual(['api', 'graphql', '--hostname', 'github.com', '--input', '-']) + expect(gh.inputs[0]).toMatchObject({ variables: { id: 'PR_1', path: 'src/$(x).ts' } }) + expect(gh.calls.flat().some(arg => arg.includes('$(x)'))).toBe(false) + }) + + it.each([ + ['a refusing GraphQL error', output({ data: null, errors: [{ type: 'FORBIDDEN', message: 'Resource not accessible by integration' }] }), + { code: 'failed', message: 'Resource not accessible by integration' }], + ['a GraphQL error that leaves the outcome unknown', output({ data: null, errors: [{ message: 'Something went wrong' }] }), + { code: 'failed', message: 'Something went wrong' }], + ['a refusal without a body', output('', 1, 'gh: Bad credentials (HTTP 401)'), { code: 'failed', message: 'gh: Bad credentials (HTTP 401)' }], + ['a body that is not GraphQL', output({ message: 'Not Found' }), { code: 'failed', message: 'unexpected GitHub response to unmarkFileAsViewed' }], + ])('reports a mutation refused or not confirmed with %s as failed', async (_label, answer, failure) => { + const gh = double(() => node, () => answer) + await expect(provider(gh.run).setViewed(pull(1), { path: 'a', viewed: false, headSha: HEAD }, signal)).resolves.toEqual(failure) + }) + + it('reports a mutation as failed when gh cannot start', async () => { + let reads = 0 + const run: GhRunner = async (args) => { + if (args.includes('--input')) throw new GhUnavailableError('gh could not start') + reads++ + return output(node) + } + await expect(provider(run).setViewed(pull(1), { path: 'a', viewed: true, headSha: HEAD }, signal)) + .resolves.toEqual({ code: 'failed', message: 'gh could not start' }) + expect(reads).toBe(1) + }) + + it('requests reviews, lists candidates, and updates the branch through GraphQL', async () => { + const gh = double(query => query === CANDIDATES_QUERY + ? { data: { repository: { assignableUsers: { nodes: [{ login: 'mona', name: null, avatarUrl: null }] }, pullRequest: null } } } + : node) + const subject = provider(gh.run) + await expect(subject.requestReviews(pull(1), { reviewers: [{ kind: 'user', login: 'mona' }] }, signal)).resolves.toBeUndefined() + await expect(subject.reviewerCandidates(pull(1), 'mo', signal)).resolves.toEqual([{ login: 'mona', name: null, avatarUrl: null, suggested: false }]) + await expect(subject.updateBranch(pull(1), { method: 'rebase', headSha: HEAD }, signal)).resolves.toBeUndefined() + expect(gh.inputs.map(body => (body as { variables: unknown }).variables)).toEqual([ + { input: { pullRequestId: 'PR_1', union: true, userLogins: ['mona'] } }, + { input: { pullRequestId: 'PR_1', expectedHeadOid: HEAD, updateMethod: 'REBASE' } }, + ]) + }) + + it('reruns each workflow run with a failed Actions job once, after confirming the head', async () => { + const actions = (name: string, conclusion: string, run: number | null) => ({ ...checkRun(name, 'COMPLETED', conclusion), + checkSuite: { app: { id: 'github-actions' }, workflowRun: { databaseId: run, event: 'pull_request', workflow: { id: name, name } } } }) + const contexts = [actions('lint', 'FAILURE', 41), actions('test', 'FAILURE', 41), actions('e2e', 'FAILURE', 42), actions('docs', 'SUCCESS', 43), + actions('other', 'FAILURE', null)] + const gh = fakeGh(args => args[1] === 'graphql' ? output({ data: { r0: { p0: pullRequestNode(1, {}, contexts) } } }) : output('')) + await expect(provider(gh.run).rerunChecks(pull(1), { headSha: HEAD }, signal)).resolves.toBeUndefined() + expect(gh.calls.filter(args => args[0] === 'api' && args[1] !== 'graphql')).toEqual([ + ['api', '--hostname', 'github.com', '--method', 'POST', 'repos/octo/demo/actions/runs/41/rerun-failed-jobs'], + ['api', '--hostname', 'github.com', '--method', 'POST', 'repos/octo/demo/actions/runs/42/rerun-failed-jobs'], + ]) + }) + + it('stops at the first refused rerun', async () => { + const failed = (run: number) => ({ ...checkRun(`job${run}`, 'COMPLETED', 'FAILURE'), + checkSuite: { app: { id: 'github-actions' }, workflowRun: { databaseId: run, event: 'pull_request', workflow: { id: `w${run}`, name: 'w' } } } }) + const gh = fakeGh(args => args[1] === 'graphql' ? output({ data: { r0: { p0: pullRequestNode(1, {}, [failed(1), failed(2)]) } } }) + : output({ message: 'Must have admin rights to Repository.' }, 1, 'gh: Must have admin rights to Repository. (HTTP 403)')) + await expect(provider(gh.run).rerunChecks(pull(1), { headSha: HEAD }, signal)) + .resolves.toEqual({ code: 'failed', message: 'Must have admin rights to Repository.' }) + expect(gh.calls.filter(args => args[4] === 'POST')).toHaveLength(1) + }) + + it.each([ + ['a moved head', () => output({ data: { r0: { p0: pullRequestNode(1, { headRefOid: 'e'.repeat(40) }) } } }), { code: 'stale' }], + ['no failed Actions job', () => output({ data: { r0: { p0: pullRequestNode(1, {}, [checkRun('lint', 'COMPLETED', 'SUCCESS')]) } } }), + { code: 'failed', message: 'No failed GitHub Actions job of the head commit can be rerun' }], + ['an unreadable status', () => output('', 1, 'gh: HTTP 401: Bad credentials'), { code: 'unauthenticated' }], + ['a status read that failed', () => output({ data: { r0: { p0: null } } }), { code: 'failed', message: 'pull request not found' }], + ])('refuses a rerun after %s', async (_label, answer, failure) => { + await expect(provider(fakeGh(answer).run).rerunChecks(pull(1), { headSha: HEAD }, signal)).resolves.toMatchObject(failure) + }) + + it('refuses a rerun at a head that is not a full commit object name', async () => { + await expect(provider(fakeGh(() => output('')).run).rerunChecks(pull(1), { headSha: 'main' }, signal)) + .rejects.toThrow('forge-github: invalid head commit "main"') + }) + + it('refuses every overview and viewed operation on an unconfigured host without running gh', async () => { + const gh = fakeGh(() => output('')) + const subject = provider(gh.run) + const failure = { code: 'failed', message: 'forge-github: host "gitlab.com" is not configured' } + await expect(subject.viewedFiles(unconfigured, HEAD, signal)).resolves.toEqual({ ...failure, code: 'unavailable' }) + await expect(subject.setViewed(unconfigured, { path: 'a', viewed: true, headSha: HEAD }, signal)).resolves.toEqual(failure) + await expect(subject.rerunChecks(unconfigured, { headSha: HEAD }, signal)).resolves.toEqual(failure) + await expect(subject.requestReviews(unconfigured, { reviewers: [{ kind: 'user', login: 'mona' }] }, signal)).resolves.toEqual(failure) + await expect(subject.reviewerCandidates(unconfigured, '', signal)).resolves.toEqual({ ...failure, code: 'unavailable' }) + await expect(subject.updateBranch(unconfigured, { method: 'merge', headSha: HEAD }, signal)).resolves.toEqual(failure) + expect(gh.calls).toEqual([]) + }) +}) diff --git a/packages/experimental/forge-github/tests/review-writes.spec.ts b/packages/experimental/forge-github/tests/review-writes.spec.ts index 81c5b4e4ed..765c6b2df6 100644 --- a/packages/experimental/forge-github/tests/review-writes.spec.ts +++ b/packages/experimental/forge-github/tests/review-writes.spec.ts @@ -53,7 +53,7 @@ function fakeGh(check: GhOutput, ...mutations: Array): { run: } function provider(run: GhRunner): GitHubProvider { - return new GitHubProvider(run, ['github.com'], { maxOutputBytes: 8_388_608, maxReviewThreads: 1_000, maxCommits: 250 }) + return new GitHubProvider(run, ['github.com'], { maxOutputBytes: 8_388_608, maxReviewThreads: 1_000, maxCommits: 250, maxViewedFiles: 3_000 }) } function payload(field: string, value: unknown = { id: 'x' }): GhOutput { diff --git a/packages/experimental/forge-github/tests/review.spec.ts b/packages/experimental/forge-github/tests/review.spec.ts index 8a71ba6494..6d23ddab02 100644 --- a/packages/experimental/forge-github/tests/review.spec.ts +++ b/packages/experimental/forge-github/tests/review.spec.ts @@ -6,12 +6,13 @@ import { GhTimeoutError, GhUnavailableError, type GhRunner } from '../src/gh.ts' const ref = { repository: { forge: 'github', host: 'github.com', owner: 'octo', name: 'demo' }, number: 7 } const head = 'a'.repeat(40) +const LIMITS = { maxOutputBytes: 8_388_608, maxReviewThreads: 1_000, maxCommits: 250, maxViewedFiles: 3_000 } const comment = { path: 'src/space name.ts', side: 'L' as const, startLine: 3, endLine: 5, body: 'Check `$(secret)`\n第二行' } const single: ForgeReviewRequest = { kind: 'comment', headSha: head, comment } const success = { exitCode: 0, stdout: JSON.stringify({ html_url: 'https://github.com/octo/demo/pull/7#discussion_r1' }), stderr: '' } function fixture() { const gh = vi.fn().mockResolvedValueOnce({ exitCode: 0, stdout: JSON.stringify({ head: { sha: head }, state: 'open' }), stderr: '' }).mockResolvedValue(success) - return { gh, provider: new GitHubProvider(gh, ['github.com'], { maxOutputBytes: 8_388_608, maxReviewThreads: 1_000, maxCommits: 250 }), signal: new AbortController().signal } + return { gh, provider: new GitHubProvider(gh, ['github.com'], LIMITS), signal: new AbortController().signal } } describe('review submission', () => { @@ -91,7 +92,7 @@ describe('review submission', () => { }) it('rejects a host outside the provider configuration without invoking gh', async () => { const { gh, signal } = fixture() - expect(await new GitHubProvider(gh, ['enterprise.test'], { maxOutputBytes: 8_388_608, maxReviewThreads: 1_000, maxCommits: 250 }).submitReview(ref, single, signal)).toMatchObject({ ok: false, code: 'failed' }) + expect(await new GitHubProvider(gh, ['enterprise.test'], LIMITS).submitReview(ref, single, signal)).toMatchObject({ ok: false, code: 'failed' }) expect(gh).not.toHaveBeenCalled() }) }) diff --git a/packages/experimental/forge-github/tests/threads.spec.ts b/packages/experimental/forge-github/tests/threads.spec.ts index 46bf80bf80..e7389b4b12 100644 --- a/packages/experimental/forge-github/tests/threads.spec.ts +++ b/packages/experimental/forge-github/tests/threads.spec.ts @@ -21,7 +21,7 @@ function fakeGh(handler: (args: readonly string[]) => GhOutput): { run: GhRunner } function provider(run: GhRunner, limits: Partial = {}): GitHubProvider { - return new GitHubProvider(run, ['github.com'], { maxOutputBytes: 8_388_608, maxReviewThreads: 1_000, maxCommits: 250, ...limits }) + return new GitHubProvider(run, ['github.com'], { maxOutputBytes: 8_388_608, maxReviewThreads: 1_000, maxCommits: 250, maxViewedFiles: 3_000, ...limits }) } function page(nodes: readonly unknown[], next: string | null = null): Record { diff --git a/packages/experimental/forge-github/tests/viewed.spec.ts b/packages/experimental/forge-github/tests/viewed.spec.ts new file mode 100644 index 0000000000..9dcf064810 --- /dev/null +++ b/packages/experimental/forge-github/tests/viewed.spec.ts @@ -0,0 +1,118 @@ +import { describe, expect, it, vi } from 'vitest' +import type { GraphqlReader } from '../src/commits.ts' +import type { GraphqlWriter } from '../src/mutation.ts' +import { PULL_REQUEST_NODE_QUERY } from '../src/pull-request-node.ts' +import { MARK_VIEWED_MUTATION, readViewed, UNMARK_VIEWED_MUTATION, VIEWED_QUERY, writeViewed } from '../src/viewed.ts' +import { pull } from './fixtures.ts' + +const HEAD = 'f'.repeat(40) +const signal = new AbortController().signal + +/** One files page at `head` with the viewer's marks, followed by the page after `next` when it is a cursor. */ +function page(files: readonly [string, string][], options: { head?: string; total?: number; next?: string | null } = {}): unknown { + return { data: { repository: { pullRequest: { headRefOid: options.head ?? HEAD, files: { + totalCount: options.total ?? files.length, + pageInfo: { hasNextPage: options.next != null, endCursor: options.next ?? null }, + nodes: files.map(([path, viewerViewedState]) => ({ path, viewerViewedState })), + } } } } } +} + +/** A reader that answers each request with the next body, recording the requests. */ +function reader(...bodies: unknown[]): { read: GraphqlReader; calls: (readonly string[])[] } { + const calls: (readonly string[])[] = [] + return { + calls, + read: async (args) => { + calls.push(args) + const body = bodies.shift() + return body instanceof Error ? { ok: false, failure: { code: 'unavailable', message: body.message } } : { ok: true, body } + }, + } +} + +describe('viewed file reads', () => { + it('reads the marks across pages at the requested head, mapping unknown states to unviewed', async () => { + const { read, calls } = reader( + page([['src/a.ts', 'VIEWED'], ['src/b.ts', 'DISMISSED']], { total: 3, next: 'files-1' }), + page([['src/c.ts', 'LATER_STATE']], { total: 3 }), + ) + await expect(readViewed(read, pull(7), HEAD.toUpperCase(), 3_000, signal)).resolves.toEqual({ + headSha: HEAD, files: { 'src/a.ts': 'viewed', 'src/b.ts': 'dismissed', 'src/c.ts': 'unviewed' }, truncated: false, + }) + expect(calls[0]).toEqual(['api', 'graphql', '--hostname', 'github.com', '-f', `query=${VIEWED_QUERY}`, '-f', 'owner=octo', '-f', 'name=demo', + '-F', 'number=7', '-F', 'first=100']) + expect(calls[1]?.slice(-2)).toEqual(['-f', 'cursor=files-1']) + }) + + it('stops at the limit and reports the rest as truncated', async () => { + const { read, calls } = reader(page([['src/a.ts', 'VIEWED'], ['src/b.ts', 'UNVIEWED']], { total: 5, next: 'files-1' })) + await expect(readViewed(read, pull(7), HEAD, 2, signal)).resolves.toEqual({ + headSha: HEAD, files: { 'src/a.ts': 'viewed', 'src/b.ts': 'unviewed' }, truncated: true, + }) + expect(calls[0]?.at(-1)).toBe('first=2') + expect(calls).toHaveLength(1) + }) + + it.each([ + ['a head that moved', [page([], { head: 'e'.repeat(40) })], { code: 'stale', message: `the pull request head moved from ${HEAD} to ${'e'.repeat(40)}` }], + ['a head that moved on a later page', [page([['a', 'VIEWED']], { next: 'files-1' }), page([], { head: 'e'.repeat(40) })], { code: 'stale' }], + ['a refused read', [new Error('rate limited')], { code: 'unavailable', message: 'rate limited' }], + ['an unexpected response', [{ data: {} }], { code: 'unavailable', message: 'unexpected GitHub response to the viewed file read' }], + ['a missing pull request', [{ data: { repository: { pullRequest: null } } }], { code: 'not-found', message: 'pull request 7 was not found' }], + ['a missing repository', [{ data: { repository: null } }], { code: 'not-found' }], + ['files GitHub cannot list', [{ data: { repository: { pullRequest: { headRefOid: HEAD, files: null } } } }], + { code: 'unavailable', message: 'GitHub did not list the pull request files' }], + ['a page without a cursor', [page([['a', 'VIEWED']], { next: null, total: 9 }), page([])], undefined], + ['a repeated cursor', [page([['a', 'VIEWED']], { next: 'files-1' }), page([['b', 'VIEWED']], { next: 'files-1' })], + { code: 'unavailable', message: 'GitHub file pagination did not advance' }], + ] as const)('refuses %s', async (_label, bodies, failure) => { + const result = await readViewed(reader(...bodies).read, pull(7), HEAD, 3_000, signal) + if (failure === undefined) expect(result).toMatchObject({ truncated: true }) + else expect(result).toMatchObject(failure) + }) + + it('reports a next page without a cursor as pagination that did not advance', async () => { + const body = page([['a', 'VIEWED']], { total: 9 }) as { data: { repository: { pullRequest: { files: { pageInfo: object } } } } } + body.data.repository.pullRequest.files.pageInfo = { hasNextPage: true, endCursor: null } + await expect(readViewed(reader(body).read, pull(7), HEAD, 3_000, signal)) + .resolves.toEqual({ code: 'unavailable', message: 'GitHub file pagination did not advance' }) + }) + + it('refuses a head that is not a full commit object name before reading', async () => { + const { read, calls } = reader() + await expect(readViewed(read, pull(7), 'main', 3_000, signal)).rejects.toThrow('forge-github: invalid head commit "main"') + expect(calls).toEqual([]) + }) +}) + +describe('viewed file writes', () => { + const node = { data: { repository: { pullRequest: { id: 'PR_7', headRefOid: HEAD } } } } + + it.each([ + [true, MARK_VIEWED_MUTATION, 'markFileAsViewed'], + [false, UNMARK_VIEWED_MUTATION, 'unmarkFileAsViewed'], + ])('confirms the head, then sends the mutation for viewed %s with the node id and path as variables', async (viewed, query, field) => { + const { read, calls } = reader(node) + const write = vi.fn(async () => undefined) + await expect(writeViewed(read, write, pull(7), { path: 'src/a b.ts', viewed, headSha: HEAD }, signal)).resolves.toBeUndefined() + expect(calls[0]).toContain(`query=${PULL_REQUEST_NODE_QUERY}`) + expect(write).toHaveBeenCalledWith('github.com', { query, field, variables: { id: 'PR_7', path: 'src/a b.ts' } }, signal) + }) + + it('refuses to write once the head moved, and passes a refused write on', async () => { + const write = vi.fn(async () => ({ code: 'failed', message: 'Resource not accessible' })) + const moved = { data: { repository: { pullRequest: { id: 'PR_7', headRefOid: 'e'.repeat(40) } } } } + await expect(writeViewed(reader(moved).read, write, pull(7), { path: 'a', viewed: true, headSha: HEAD }, signal)) + .resolves.toMatchObject({ code: 'stale' }) + expect(write).not.toHaveBeenCalled() + await expect(writeViewed(reader(node).read, write, pull(7), { path: 'a', viewed: true, headSha: HEAD }, signal)) + .resolves.toEqual({ code: 'failed', message: 'Resource not accessible' }) + }) + + it('refuses a head that is not a full commit object name before reading', async () => { + const { read, calls } = reader() + await expect(writeViewed(read, vi.fn(), pull(7), { path: 'a', viewed: true, headSha: 'main' }, signal)) + .rejects.toThrow('forge-github: invalid head commit "main"') + expect(calls).toEqual([]) + }) +})