|
| 1 | +/** |
| 2 | + * PR Draft Explainer Bot |
| 3 | + * |
| 4 | + * Triggers when a pull request is converted to draft. |
| 5 | + * |
| 6 | + * Safety: |
| 7 | + * - Prevents duplicate comments using a unique HTML marker. |
| 8 | + * - Only posts if a CHANGES_REQUESTED review exists. |
| 9 | + * - Fails safely if review lookup fails. |
| 10 | + * - Uses pagination to scan existing comments safely. |
| 11 | + */ |
| 12 | + |
| 13 | +const COMMENT_MARKER = "<!-- pr-draft-explainer -->"; |
| 14 | +const DRY_RUN = process.env.DRY_RUN === "true"; |
| 15 | +const manualPRNumber = process.env.PR_NUMBER; |
| 16 | + |
| 17 | +/** |
| 18 | + * Checks if the reminder comment already exists. |
| 19 | + * Uses GitHub pagination to safely scan all comments. |
| 20 | + * |
| 21 | + * @param {import("@actions/github").GitHub} params.github - Authenticated GitHub client. |
| 22 | + * @param {string} params.owner - Repository owner. |
| 23 | + * @param {string} params.repo - Repository name. |
| 24 | + * @param {number} params.issueNumber - Pull request number. |
| 25 | + * @param {string} params.marker - Unique marker string to detect duplicate comments. |
| 26 | + * @returns {Promise<boolean>} - True if a comment with the marker exists. |
| 27 | + */ |
| 28 | + |
| 29 | +async function commentExists({ github, owner, repo, issueNumber, marker }) { |
| 30 | + console.log("Checking for existing explanation comments..."); |
| 31 | + |
| 32 | + let scanned = 0; |
| 33 | + const MAX_COMMENTS = 500; |
| 34 | + |
| 35 | + for await (const response of github.paginate.iterator( |
| 36 | + github.rest.issues.listComments, |
| 37 | + { |
| 38 | + owner, |
| 39 | + repo, |
| 40 | + issue_number: issueNumber, |
| 41 | + per_page: 100, |
| 42 | + } |
| 43 | + )) { |
| 44 | + for (const comment of response.data) { |
| 45 | + scanned++; |
| 46 | + if (comment.body?.includes(marker)) { |
| 47 | + console.log(`Found existing explanation comment (scanned ${scanned} comments).`); |
| 48 | + return true; |
| 49 | + } |
| 50 | + if (scanned >= MAX_COMMENTS) { |
| 51 | + console.log(`Reached scan limit (${MAX_COMMENTS} comments) — assuming no duplicate.`); |
| 52 | + return false; |
| 53 | + } |
| 54 | + } |
| 55 | + } |
| 56 | + |
| 57 | + console.log(`No existing explainer comment found (scanned ${scanned} comments).`); |
| 58 | + return false; |
| 59 | +} |
| 60 | + |
| 61 | +/** |
| 62 | + * Builds the draft explainer comment body. |
| 63 | + * |
| 64 | + * @param {string} greetingTarget - Formatted username to greet (e.g., "@username"). |
| 65 | + * @returns {string} - Formatted reminder message. |
| 66 | + */ |
| 67 | + |
| 68 | +function buildExplainerComment(greetingTarget) { |
| 69 | + return ` |
| 70 | +${COMMENT_MARKER} |
| 71 | +Hi ${greetingTarget}! |
| 72 | +
|
| 73 | +We suggested a few updates and moved this PR to **draft** while you apply the feedback. This keeps it out of the review queue until it is ready again. |
| 74 | +
|
| 75 | +### What happens next? |
| 76 | +- Make the requested changes. |
| 77 | +- When you are ready, click **“Ready for review”** (recommended) or use the \`/review\` command. |
| 78 | +
|
| 79 | +Thanks again for your contribution! |
| 80 | +`.trim(); |
| 81 | +} |
| 82 | + |
| 83 | +/** |
| 84 | + * Main entry point. |
| 85 | + * |
| 86 | + * Execution Flow: |
| 87 | + * 1. Ensure PR exists in event payload. |
| 88 | + * 2. Prevent duplicate bot comments. |
| 89 | + * 3. Confirm at least one CHANGES_REQUESTED review exists. |
| 90 | + * 4. Post explanation comment. |
| 91 | + */ |
| 92 | + |
| 93 | +module.exports = async ({ github, context }) => { |
| 94 | + let pr = context.payload.pull_request; |
| 95 | + let prNumber = pr?.number || manualPRNumber; |
| 96 | + const { owner, repo } = context.repo; |
| 97 | + |
| 98 | + if (!prNumber) { |
| 99 | + console.log("No PR number found in payload or environment. Exiting."); |
| 100 | + return; |
| 101 | + } |
| 102 | + if (!pr) { |
| 103 | + console.log(`Fetching PR #${prNumber} (manual workflow_dispatch run)...`); |
| 104 | + |
| 105 | + try { |
| 106 | + const prResponse = await github.rest.pulls.get({ |
| 107 | + owner, |
| 108 | + repo, |
| 109 | + pull_number: prNumber, |
| 110 | + }); |
| 111 | + |
| 112 | + pr = prResponse.data; |
| 113 | + } catch (error) { |
| 114 | + console.log(`Failed to fetch PR #${prNumber}: ${error.message}`); |
| 115 | + return; |
| 116 | + } |
| 117 | + } |
| 118 | + |
| 119 | + const authorLogin = pr.user?.login; |
| 120 | + const greetingTarget = authorLogin ? `@${authorLogin}` : "there"; |
| 121 | + |
| 122 | + if (!pr.draft) { |
| 123 | + console.log(`PR #${prNumber} is not draft. Skipping.`); |
| 124 | + return; |
| 125 | + } |
| 126 | + |
| 127 | + console.log(`PR #${prNumber} was converted to draft. Checking if explanation is needed.`); |
| 128 | + |
| 129 | + // Prevent duplicate comments |
| 130 | + let alreadyCommented = false; |
| 131 | + try { |
| 132 | + alreadyCommented = await commentExists({ |
| 133 | + github, |
| 134 | + owner, |
| 135 | + repo, |
| 136 | + issueNumber: prNumber, |
| 137 | + marker: COMMENT_MARKER, |
| 138 | + }); |
| 139 | + } catch (err) { |
| 140 | + console.log(`Failed to check existing comments on PR #${prNumber} in ${owner}/${repo}: ${err.message}`); |
| 141 | + console.log("Skipping explanation to avoid potential duplicate."); |
| 142 | + return; |
| 143 | + } |
| 144 | + |
| 145 | + if (alreadyCommented) { |
| 146 | + console.log("Explanation already exists — skipping."); |
| 147 | + return; |
| 148 | + } |
| 149 | + |
| 150 | + // Only proceed if changes were previously requested on this PR |
| 151 | + try { |
| 152 | + const reviews = await github.rest.pulls.listReviews({ |
| 153 | + owner, |
| 154 | + repo, |
| 155 | + pull_number: prNumber, |
| 156 | + per_page: 100, |
| 157 | + }); |
| 158 | + |
| 159 | + // Track the latest review from each reviewer |
| 160 | + const latestReviews = new Map(); |
| 161 | + |
| 162 | + for (const review of reviews.data) { |
| 163 | + const reviewer = review.user?.login; |
| 164 | + if (!reviewer) continue; |
| 165 | + |
| 166 | + const previous = latestReviews.get(reviewer); |
| 167 | + |
| 168 | + if (!previous || new Date(review.submitted_at) > new Date(previous.submitted_at)) { |
| 169 | + latestReviews.set(reviewer, review); |
| 170 | + } |
| 171 | + } |
| 172 | + |
| 173 | + const hasChangeRequest = [...latestReviews.values()].some( |
| 174 | + (review) => review.state === "CHANGES_REQUESTED" |
| 175 | + ); |
| 176 | + |
| 177 | + if (!hasChangeRequest) { |
| 178 | + console.log("No CHANGES_REQUESTED review found. Skipping explanation comment."); |
| 179 | + return; |
| 180 | + } |
| 181 | + |
| 182 | + } catch (error) { |
| 183 | + console.log(`Review lookup failed for PR #${prNumber}: ${error.message}. Skipping to avoid a false explanation.`); |
| 184 | + return; |
| 185 | + } |
| 186 | + |
| 187 | + // Post explanation comment |
| 188 | + try { |
| 189 | + if (DRY_RUN) { |
| 190 | + console.log(`[DRY RUN] Explanation comment would be posted on PR #${prNumber}.`); |
| 191 | + return; |
| 192 | + } |
| 193 | + await github.rest.issues.createComment({ |
| 194 | + owner, |
| 195 | + repo, |
| 196 | + issue_number: prNumber, |
| 197 | + body: buildExplainerComment(greetingTarget), |
| 198 | + }); |
| 199 | + console.log(`Posted draft explanation comment on PR #${prNumber}.`); |
| 200 | + } catch (error) { |
| 201 | + console.log(`Failed to post draft explanation on PR #${prNumber}: ${error.message}`); |
| 202 | + } |
| 203 | +}; |
0 commit comments