From 4062ffbbbe21cdcb86d55ccd1500afa8a9a63476 Mon Sep 17 00:00:00 2001 From: haelyra <49814733+haelyra@users.noreply.github.com> Date: Tue, 20 Oct 2026 16:15:38 -0400 Subject: [PATCH 1/4] fix(ci): grandfather open PRs under contributor cap --- .github/PR_MODERATION.md | 25 ++++++----- .github/workflows/pr-burst-guard.yml | 5 ++- CONTRIBUTING.md | 5 ++- scripts/ci/pr-burst-guard.js | 13 +++--- tests/ci/pr-burst-guard-workflow.test.js | 57 +++++++++++++++++++++++- tests/ci/pr-burst-guard.test.js | 51 ++++++++++++++++++--- 6 files changed, 128 insertions(+), 28 deletions(-) diff --git a/.github/PR_MODERATION.md b/.github/PR_MODERATION.md index 27b13f5cc..949ab92c6 100644 --- a/.github/PR_MODERATION.md +++ b/.github/PR_MODERATION.md @@ -10,7 +10,7 @@ judge whether a patch is useful. Existing open PRs are not bulk-closed on rollou | --- | --- | --- | | Burst allowance | Five creations per author in 20 minutes | Close and lock excess PRs | | Severe burst | More than ten creations in 20 minutes | Attempt account block; alert maintainers | -| Open-PR cap | Ten open PRs per author at any time | Close the newest PRs above the cap with an explanatory comment; no lock, no alert | +| Open-PR cap | Ten open PRs per author at any time | Close only the newly opened or reopened PR above the cap with an explanatory comment; no lock, no alert | | Known denied account | User ID `108231307`, currently `dajiaohuang` | Close and lock its incoming/reopened PR | | Trusted contributors | Live repository write, maintain, or admin permission | Exempt from the burst guard | | Notifications | `@affaan-m @haelyra` | One bot-authored issue per author per UTC day, plus one escalation comment | @@ -18,14 +18,20 @@ judge whether a patch is useful. Existing open PRs are not bulk-closed on rollou Edit `pr-burst-policy.json` to change thresholds, notification recipients or denied numeric IDs, or `maxOpen` to change the open-PR cap. -The open-PR cap is evaluated on the same opened and reopened events, after any -burst closures in that run, against a full paginated list of the repository's -open PRs. The author's oldest `maxOpen` PRs stay open; newer ones are closed with -a bot comment that names the count and the limit. Closing is reversible: once -the author is under the cap, reopening a closed PR passes. A PR the burst guard +The open-PR cap runs on opened and reopened events. Up to 100 author events +queue in Actions, so normal submission bursts keep their pending cap checks. +The guard checks a full paginated list of open PRs. A newly opened PR closes +only when at least ten older PRs by that author are still open. +Reopening consumes a new slot, so the reopened PR closes when the author is +over the cap. Existing open PRs stay open, even when their author already had +more than ten. A bot comment names the count and limit. Closing is reversible: +once the author is under the cap, reopening a closed PR passes. A PR the burst guard already closed and locked in the same run is never touched again by the cap. The -cap does not bulk-close PRs that were already open when it shipped; it applies -as each author opens or reopens their next PR. +cap does not bulk-close historical PRs; it applies when an author opens or +reopens a PR after rollout. Burst moderation runs before the cap in the same +job and still reads later creation windows to handle out-of-order API snapshots. +GitHub cancels excess pending runs beyond its 100-run queue; a prolonged backlog +that reaches that limit can leave an individual cap event unchecked. Closed and draft PRs count toward burst detection. Counting uses stable author IDs and paginated REST creation metadata, without the search index. A run checks @@ -33,8 +39,7 @@ historical windows from the triggering PR's creation time through newer API rows. Queue delays, out-of-order delivery and replaced pending runs cannot hide a burst already present in that snapshot. Excess PRs are determined in creation order across all scanned windows, with PR number breaking timestamp ties. -Already closed excess PRs count -but are not mutated again. +Already closed excess PRs count but are not mutated again. Reopening an old ordinary PR does not add a new creation to the burst count. Reopening a denied author's PR triggers denial even outside the time window. diff --git a/.github/workflows/pr-burst-guard.yml b/.github/workflows/pr-burst-guard.yml index 550655339..fbb19ecf3 100644 --- a/.github/workflows/pr-burst-guard.yml +++ b/.github/workflows/pr-burst-guard.yml @@ -4,11 +4,12 @@ on: pull_request_target: types: [opened, reopened] -# Process one author's ledger serially. A newer pending event replaces an older -# pending event; each run reads all PR states instead of relying on event counts. +# Queue up to 100 pending events per author. The burst scan still handles +# delayed or out-of-order API snapshots. concurrency: group: pr-burst-${{ github.repository }}-${{ github.event.pull_request.user.id }} cancel-in-progress: false + queue: max permissions: contents: read diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8fe695388..70790a656 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -442,8 +442,9 @@ still count toward the window. Contributors with repository write access bypass this policy. Maintainers can review exceptions through the moderation alert. Please also keep at most ten PRs open at a time. When you open or reopen a PR -above that cap, automation closes the newest ones with a comment explaining the -count. Get existing PRs merged or close the ones you no longer need, then reopen. +above that cap, automation closes that PR with a comment explaining the count. +Existing open PRs remain open. Get PRs merged or close the ones you no longer +need, then reopen. Ten open PRs is more than any one reviewer can keep in flight, so this keeps review time on the work you care about most. diff --git a/scripts/ci/pr-burst-guard.js b/scripts/ci/pr-burst-guard.js index d7f3f8653..db8fbfc5f 100644 --- a/scripts/ci/pr-burst-guard.js +++ b/scripts/ci/pr-burst-guard.js @@ -86,15 +86,18 @@ function strongestWindow(rows, current, policy, eventTime) { return { ...peak, excess: peak.denied ? peak.excess : [...excess.values()] }; } -/** Open-PR cap: keep the author's oldest `maxOpen` open PRs, close the rest. PRs the burst - * guard already closed in this run are treated as closed so nothing is mutated twice. */ -function capExcess(openRows, current, policy, alreadyClosed = new Set()) { +/** Only the triggering PR may be closed by the cap. Reopening consumes a new + * slot even if that PR is older than the author's other open PRs. */ +function capExcess(openRows, current, policy, alreadyClosed = new Set(), action = 'opened') { validatePolicy(policy); const open = [...new Map([...openRows, current].map(pr => [pr.number, pr])).values()] .filter(pr => pr.user.id === current.user.id && pr.state === 'open' && !alreadyClosed.has(pr.number)) .sort((a, b) => Date.parse(a.created_at) - Date.parse(b.created_at) || a.number - b.number); + const currentIndex = open.findIndex(pr => pr.number === current.number); return { openCount: open.length, maxOpen: policy.maxOpen, - capExcess: open.slice(policy.maxOpen).map(pr => ({ number: pr.number, state: pr.state })) }; + capExcess: open.length > policy.maxOpen && currentIndex >= 0 + && (action === 'reopened' || currentIndex >= policy.maxOpen) + ? [{ number: current.number, state: current.state }] : [] }; } const CAP_MARKER = ''; @@ -189,7 +192,7 @@ async function moderate({ api, blockAPI, repository, number, action = 'opened', dryRun, errors: [], blockStatus: 'Below blocking threshold' }; // Total open PRs is a separate, unwindowed list: the burst scan stops at the window edge. const openRows = await listPages(api, `${root}/pulls?state=open&sort=created&direction=desc`); - Object.assign(result, capExcess(openRows, current, policy, new Set(result.excess.map(pr => pr.number)))); + Object.assign(result, capExcess(openRows, current, policy, new Set(result.excess.map(pr => pr.number)), action)); if (dryRun) { if (result.block) result.blockStatus = 'Dry run: would attempt owner-scoped blocking'; return result; diff --git a/tests/ci/pr-burst-guard-workflow.test.js b/tests/ci/pr-burst-guard-workflow.test.js index 0ebe1f82b..e4ce66cef 100644 --- a/tests/ci/pr-burst-guard-workflow.test.js +++ b/tests/ci/pr-burst-guard-workflow.test.js @@ -10,6 +10,10 @@ const { promisify } = require('node:util'); const exec = promisify(execFile); const root = path.resolve(__dirname, '../..'); +function recordMutation(mutations, req, route, body) { + if (req.method !== 'GET') mutations.push({ method: req.method, route, body, token: req.headers.authorization }); +} + test('actual CLI closes six excess PRs, locks them, blocks with owner identity, and deduplicates alerts over HTTP', async () => { const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-pr-guard-')); const mutations = []; @@ -25,7 +29,7 @@ test('actual CLI closes six excess PRs, locks them, blocks with owner identity, for await (const chunk of req) text += chunk; const body = text ? JSON.parse(text) : undefined; const send = value => { res.setHeader('Content-Type', 'application/json'); res.end(JSON.stringify(value)); }; - if (req.method !== 'GET') mutations.push({ method: req.method, route: url.pathname, body, token: req.headers.authorization }); + recordMutation(mutations, req, url.pathname, body); if (url.pathname === '/repos/owner/repo') return send({ owner: { login: 'owner', type: 'User' } }); if (url.pathname === '/user') { assert.equal(req.headers.authorization, 'Bearer owner-token'); @@ -67,7 +71,7 @@ test('actual CLI closes six excess PRs, locks them, blocks with owner identity, await run(); assert.equal(mutations.filter(m => m.route.endsWith('/issues') && m.method === 'POST').length, 1); assert.equal(mutations.filter(m => /\/pulls\/\d+$/.test(m.route)).length, 6); - assert.equal(mutations.filter(m => m.route.endsWith('/lock')).length, 6); + assert.equal(new Set(mutations.filter(m => m.route.endsWith('/lock')).map(m => m.route)).size, 6); assert(mutations.some(m => m.route === '/user/blocks/contributor' && m.token === 'Bearer owner-token')); assert(mutations.filter(m => m.route.startsWith('/repos/')).every(m => m.token === 'Bearer moderation-token')); assert.doesNotMatch(fs.readFileSync(summary, 'utf8'), /untrusted|owner-token|moderation-token/); @@ -86,3 +90,52 @@ test('actual CLI closes six excess PRs, locks them, blocks with owner identity, fs.rmSync(tmp, { recursive: true, force: true }); } }); + +test('actual CLI closes only a new PR when twenty earlier PRs remain open', async () => { + const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-pr-cap-')); + const rows = Array.from({ length: 21 }, (_, i) => ({ number: i === 20 ? 3649 : i + 1, + user: { id: 42, login: 'contributor' }, state: 'open', + created_at: new Date(Date.UTC(2026, 9, 1, i, 0, 0)).toISOString() })); + const mutations = []; + const server = http.createServer(async (req, res) => { + const url = new URL(req.url, 'http://localhost'); + let text = ''; + for await (const chunk of req) text += chunk; + const body = text ? JSON.parse(text) : undefined; + const send = value => { res.setHeader('Content-Type', 'application/json'); res.end(JSON.stringify(value)); }; + if (req.method !== 'GET') mutations.push({ method: req.method, route: url.pathname, body }); + if (url.pathname === '/repos/owner/repo') return send({ owner: { login: 'owner', type: 'User' } }); + if (url.pathname.includes('/collaborators/')) return send({ permission: 'read' }); + if (url.pathname.endsWith('/pulls/3649') && req.method === 'GET') return send(rows[20]); + if (url.pathname.endsWith('/pulls')) return send(rows.filter(pr => url.searchParams.get('state') !== 'open' || pr.state === 'open').reverse()); + if (url.pathname.endsWith('/issues/3649/comments')) return send(req.method === 'GET' ? [] : {}); + if (url.pathname.endsWith('/pulls/3649') && req.method === 'PATCH') { rows[20].state = body.state; return send(rows[20]); } + res.statusCode = 404; send({ message: 'fixture route missing' }); + }); + await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)); + try { + const port = server.address().port; + const preload = path.join(tmp, 'transport.cjs'); + fs.writeFileSync(preload, `const original = global.fetch; global.fetch = (url, options) => original('http://127.0.0.1:${port}' + new URL(url).pathname + new URL(url).search, options);`); + const event = path.join(tmp, 'event.json'); + fs.writeFileSync(event, JSON.stringify({ action: 'opened', pull_request: { number: 3649 } })); + const env = { ...process.env, NODE_OPTIONS: `--require=${preload}`, GITHUB_REPOSITORY: 'owner/repo', + GITHUB_TOKEN: 'moderation-token', GITHUB_EVENT_PATH: event, PR_MODERATION_BLOCK_TOKEN: '' }; + const report = JSON.parse((await exec(process.execPath, ['scripts/ci/pr-burst-guard.js'], { cwd: root, env })).stdout); + assert.equal(report.openCount, 21); + assert.deepEqual(report.capExcess.map(pr => pr.number), [3649]); + assert.equal(rows.filter(pr => pr.state === 'open').length, 20); + assert.deepEqual(mutations.filter(m => m.method === 'PATCH').map(m => m.route), ['/repos/owner/repo/pulls/3649']); + assert.match(mutations.find(m => m.route.endsWith('/issues/3649/comments')).body.body, /21 open pull requests.*limit of 10/); + } finally { + await new Promise(resolve => server.close(resolve)); + fs.rmSync(tmp, { recursive: true, force: true }); + } +}); + +test('workflow requests the bounded author queue for pending cap checks', () => { + const workflow = fs.readFileSync(path.join(root, '.github/workflows/pr-burst-guard.yml'), 'utf8'); + assert.match(workflow, /group: pr-burst-.*github\.event\.pull_request\.user\.id/); + assert.match(workflow, /concurrency:[\s\S]*?queue: max/); + assert.match(workflow, /run: node scripts\/ci\/pr-burst-guard\.js/); +}); diff --git a/tests/ci/pr-burst-guard.test.js b/tests/ci/pr-burst-guard.test.js index 36902dc4e..48ef9be89 100644 --- a/tests/ci/pr-burst-guard.test.js +++ b/tests/ci/pr-burst-guard.test.js @@ -3,7 +3,8 @@ const assert = require('node:assert/strict'); const { test } = require('node:test'); const { evaluate, moderate, githubAPI, listPages, strongestWindow, capExcess } = require('../../scripts/ci/pr-burst-guard'); -const policy = { windowMinutes: 20, closeAbove: 5, blockAbove: 10, maxOpen: 10, deniedUserIDs: [999], notify: ['maintainer'] }; +const policy = { windowMinutes: 20, closeAbove: 5, blockAbove: 10, maxOpen: 10, + deniedUserIDs: [999], notify: ['maintainer'] }; const start = Date.parse('2026-10-14T19:00:00Z'); const pull = (number, extra = {}) => ({ number, user: { id: 42, login: 'contributor' }, created_at: new Date(start + number * 1000).toISOString(), state: 'open', ...extra }); @@ -16,7 +17,8 @@ function fixture(n, options = {}) { const api = async (method, route, body) => { calls.push({ method, route, body }); if (route === '/repos/owner/repo') return { owner: { login: 'owner', type: 'User' } }; - if (route.endsWith(`/pulls/${n}`)) return rows.find(p => p.number === n); + const pullNumber = route.match(/\/pulls\/(\d+)$/); + if (pullNumber && method === 'GET') return rows.find(p => p.number === Number(pullNumber[1])); if (route.includes('/collaborators/')) return { permission: options.permission || 'read' }; if (route.includes('/pulls?')) return rows.filter(p => !route.includes('state=open') || p.state === 'open').slice().reverse(); if (route.includes('/issues?')) return issue ? [issue] : []; @@ -183,16 +185,50 @@ test('closure failure still creates an alert with enforcement errors', async () const spread = (n, extra = {}) => Array.from({ length: n }, (_, i) => pull(i + 1, { created_at: new Date(start + i * 3600000).toISOString(), ...extra })); -test('open-PR cap keeps the oldest ten open and closes the rest, newest first', () => { +test('open-PR cap closes only the triggering excess PR', () => { + assert.deepEqual(capExcess(spread(10), spread(10)[9], policy).capExcess, []); + assert.deepEqual(capExcess(spread(11), spread(11)[10], policy).capExcess.map(p => p.number), [11]); const result = capExcess(spread(12), spread(12)[11], policy); assert.equal(result.openCount, 12); - assert.deepEqual(result.capExcess.map(p => p.number), [11, 12]); + assert.deepEqual(result.capExcess.map(p => p.number), [12]); + const grandfathered = capExcess(spread(21), spread(21)[20], policy); + assert.equal(grandfathered.openCount, 21); + assert.deepEqual(grandfathered.capExcess.map(p => p.number), [21]); + assert.deepEqual(capExcess(spread(11), spread(11)[0], policy, new Set(), 'reopened') + .capExcess.map(p => p.number), [1]); const closed = spread(12).map((p, i) => i < 3 ? { ...p, state: 'closed' } : p); assert.equal(capExcess(closed, closed[11], policy).openCount, 9); - assert.equal(capExcess(spread(12), spread(12)[11], policy, new Set([11, 12])).capExcess.length, 0); + assert.deepEqual(capExcess(spread(12), spread(12)[11], policy, new Set([12])).capExcess, []); assert.equal(capExcess(spread(12, { user: { id: 7, login: 'other' } }), pull(1), policy).openCount, 1); }); +test('a new PR over twenty existing open PRs is the only cap closure and gets a comment', async () => { + const f = fixture(21, { rows: spread(21) }); + const result = await moderate(f.args); + assert.deepEqual(result.capExcess.map(p => p.number), [21]); + assert.deepEqual(f.calls.filter(c => c.method === 'PATCH' && c.route.includes('/pulls/')).map(c => c.route), + ['/repos/owner/repo/pulls/21']); + const comment = f.calls.find(c => c.method === 'POST' && c.route.endsWith('/issues/21/comments')); + assert.match(comment.body.body, /21 open pull requests.*limit of 10/); +}); + +test('reopening an older PR over the cap closes that PR without touching its peers', async () => { + const f = fixture(11, { rows: spread(11), action: 'reopened' }); + f.args.number = 1; + const result = await moderate(f.args); + assert.deepEqual(result.capExcess.map(p => p.number), [1]); + assert.deepEqual(f.calls.filter(c => c.method === 'PATCH' && c.route.includes('/pulls/')).map(c => c.route), + ['/repos/owner/repo/pulls/1']); +}); + +test('an older allowed PR stays open when later PRs are already visible', async () => { + const f = fixture(12, { rows: spread(12) }); + f.args.number = 10; + const result = await moderate(f.args); + assert.deepEqual(result.capExcess, []); + assert.equal(f.calls.filter(c => c.method !== 'GET').length, 0); +}); + test('cap closes with an explanatory comment, no lock, no maintainer alert, and never comments twice', async () => { const rows = spread(11); const f = fixture(11, { rows }); @@ -221,13 +257,14 @@ test('cap counts open PRs after burst closures, so one run never closes a PR twi assert.equal(result.count, 6); assert.deepEqual(result.excess.map(p => p.number), [15]); assert.equal(result.openCount, 14); - assert.deepEqual(result.capExcess.map(p => p.number), [11, 12, 13, 14]); + assert.deepEqual(result.capExcess, []); assert.equal(f.calls.filter(c => c.method === 'PATCH' && c.route.endsWith('/pulls/15')).length, 1); + assert.equal(f.calls.filter(c => c.method === 'PATCH' && c.route.includes('/pulls/')).length, 1); }); test('cap dry run reports the excess without mutating; collaborators are exempt from the cap', async () => { const f = fixture(12, { rows: spread(12), dryRun: true }); - assert.deepEqual((await moderate(f.args)).capExcess.map(p => p.number), [11, 12]); + assert.deepEqual((await moderate(f.args)).capExcess.map(p => p.number), [12]); assert(f.calls.every(c => c.method === 'GET')); const w = fixture(12, { rows: spread(12), permission: 'write' }); assert.equal((await moderate(w.args)).exempt, true); From 3b31c2af66db021f2e07ea941cf3e0d67e35db6c Mon Sep 17 00:00:00 2001 From: haelyra <49814733+haelyra@users.noreply.github.com> Date: Tue, 20 Oct 2026 16:31:58 -0400 Subject: [PATCH 2/4] test(ci): reject duplicate burst lock requests --- tests/ci/pr-burst-guard-workflow.test.js | 1 + 1 file changed, 1 insertion(+) diff --git a/tests/ci/pr-burst-guard-workflow.test.js b/tests/ci/pr-burst-guard-workflow.test.js index e4ce66cef..5c260d6c0 100644 --- a/tests/ci/pr-burst-guard-workflow.test.js +++ b/tests/ci/pr-burst-guard-workflow.test.js @@ -71,6 +71,7 @@ test('actual CLI closes six excess PRs, locks them, blocks with owner identity, await run(); assert.equal(mutations.filter(m => m.route.endsWith('/issues') && m.method === 'POST').length, 1); assert.equal(mutations.filter(m => /\/pulls\/\d+$/.test(m.route)).length, 6); + assert.equal(mutations.filter(m => m.route.endsWith('/lock')).length, 6); assert.equal(new Set(mutations.filter(m => m.route.endsWith('/lock')).map(m => m.route)).size, 6); assert(mutations.some(m => m.route === '/user/blocks/contributor' && m.token === 'Bearer owner-token')); assert(mutations.filter(m => m.route.startsWith('/repos/')).every(m => m.token === 'Bearer moderation-token')); From bac1e475eeb224bd48ef51ea1376c02be1977f66 Mon Sep 17 00:00:00 2001 From: haelyra <49814733+haelyra@users.noreply.github.com> Date: Thu, 22 Oct 2026 18:05:18 -0400 Subject: [PATCH 3/4] fix(ci): apply open PR cap to every author --- .github/PR_MODERATION.md | 9 +++-- CONTRIBUTING.md | 7 ++-- scripts/ci/pr-burst-guard.js | 42 +++++++++++++--------- tests/ci/pr-burst-guard-workflow.test.js | 33 +++++++++++------ tests/ci/pr-burst-guard.test.js | 45 ++++++++++++++++++------ 5 files changed, 94 insertions(+), 42 deletions(-) diff --git a/.github/PR_MODERATION.md b/.github/PR_MODERATION.md index 949ab92c6..cca5ae07d 100644 --- a/.github/PR_MODERATION.md +++ b/.github/PR_MODERATION.md @@ -10,18 +10,21 @@ judge whether a patch is useful. Existing open PRs are not bulk-closed on rollou | --- | --- | --- | | Burst allowance | Five creations per author in 20 minutes | Close and lock excess PRs | | Severe burst | More than ten creations in 20 minutes | Attempt account block; alert maintainers | -| Open-PR cap | Ten open PRs per author at any time | Close only the newly opened or reopened PR above the cap with an explanatory comment; no lock, no alert | +| Open-PR cap | Ten open PRs per author at any time | Close excess new PRs or a reopened PR with an explanatory comment; no lock, no alert | | Known denied account | User ID `108231307`, currently `dajiaohuang` | Close and lock its incoming/reopened PR | -| Trusted contributors | Live repository write, maintain, or admin permission | Exempt from the burst guard | +| Trusted contributors | Live repository write, maintain, or admin permission | Exempt from burst and denied-account moderation; still subject to the open-PR cap | | Notifications | `@affaan-m @haelyra` | One bot-authored issue per author per UTC day, plus one escalation comment | Edit `pr-burst-policy.json` to change thresholds, notification recipients or denied numeric IDs, or `maxOpen` to change the open-PR cap. -The open-PR cap runs on opened and reopened events. Up to 100 author events +The open-PR cap applies to every author on opened and reopened events. Up to 100 author events queue in Actions, so normal submission bursts keep their pending cap checks. The guard checks a full paginated list of open PRs. A newly opened PR closes only when at least ten older PRs by that author are still open. +If an opened event runs late, it also closes newer excess PRs visible in that +snapshot. This catches new PRs whose individual checks were cancelled by the +Actions queue without closing any PR that predates the triggering opened event. Reopening consumes a new slot, so the reopened PR closes when the author is over the cap. Existing open PRs stay open, even when their author already had more than ten. A bot comment names the count and limit. Closing is reversible: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 70790a656..ecdcc89ef 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -439,12 +439,13 @@ Please submit at most five PRs within any 20-minute period. Automated moderation closes and locks excess PRs, including drafts. More than ten submissions within 20 minutes triggers a maintainer alert and an account-block attempt. Closed PRs still count toward the window. Contributors with repository write access bypass -this policy. Maintainers can review exceptions through the moderation alert. +burst moderation. Maintainers can review exceptions through the moderation alert. Please also keep at most ten PRs open at a time. When you open or reopen a PR above that cap, automation closes that PR with a comment explaining the count. -Existing open PRs remain open. Get PRs merged or close the ones you no longer -need, then reopen. +Existing open PRs remain open, even for authors already above ten. The cap applies +to every author, including maintainers. Get PRs merged or close the ones you no +longer need, then reopen. Ten open PRs is more than any one reviewer can keep in flight, so this keeps review time on the work you care about most. diff --git a/scripts/ci/pr-burst-guard.js b/scripts/ci/pr-burst-guard.js index db8fbfc5f..ad5bb4397 100644 --- a/scripts/ci/pr-burst-guard.js +++ b/scripts/ci/pr-burst-guard.js @@ -86,18 +86,22 @@ function strongestWindow(rows, current, policy, eventTime) { return { ...peak, excess: peak.denied ? peak.excess : [...excess.values()] }; } -/** Only the triggering PR may be closed by the cap. Reopening consumes a new - * slot even if that PR is older than the author's other open PRs. */ +/** Opened events may reconcile newer excess PRs when their own checks were + * cancelled. Reopening consumes a new slot but never revisits its older peers. */ function capExcess(openRows, current, policy, alreadyClosed = new Set(), action = 'opened') { validatePolicy(policy); const open = [...new Map([...openRows, current].map(pr => [pr.number, pr])).values()] .filter(pr => pr.user.id === current.user.id && pr.state === 'open' && !alreadyClosed.has(pr.number)) .sort((a, b) => Date.parse(a.created_at) - Date.parse(b.created_at) || a.number - b.number); const currentIndex = open.findIndex(pr => pr.number === current.number); + const currentTime = Date.parse(current.created_at); + const excess = open.length <= policy.maxOpen ? [] + : action === 'reopened' ? currentIndex < 0 ? [] : [open[currentIndex]] + : open.filter((pr, index) => index >= policy.maxOpen + && (Date.parse(pr.created_at) > currentTime + || Date.parse(pr.created_at) === currentTime && pr.number >= current.number)); return { openCount: open.length, maxOpen: policy.maxOpen, - capExcess: open.length > policy.maxOpen && currentIndex >= 0 - && (action === 'reopened' || currentIndex >= policy.maxOpen) - ? [{ number: current.number, state: current.state }] : [] }; + capExcess: excess.map(pr => ({ number: pr.number, state: pr.state })) }; } const CAP_MARKER = ''; @@ -110,7 +114,7 @@ async function enforceCap(api, root, pr, current, result) { await api('POST', `${root}/issues/${pr.number}/comments`, { body: [CAP_MARKER, `Closed automatically: @${current.user.login} has ${result.openCount} open pull requests in this repository, above the limit of ${result.maxOpen} per contributor.`, '', 'Get existing PRs merged, or close the ones you no longer need, then reopen this one. The limit is about review capacity, not the quality of this patch.', - 'Contributors with repository write access are exempt. Policy: `.github/PR_MODERATION.md`.'].join('\n') }); + 'The cap applies to all authors. Repository collaborators remain exempt from burst and denied-account moderation. Policy: `.github/PR_MODERATION.md`.'].join('\n') }); } catch (error) { result.errors.push(`#${pr.number}: ${error.message}`); } @@ -180,16 +184,22 @@ async function moderate({ api, blockAPI, repository, number, action = 'opened', if (error.status !== 404) throw error; permission = 'none'; } - if (['admin', 'maintain', 'write'].includes(permission)) return { exempt: true, author: current.user.login }; - // Anchor opened events to GitHub's creation time so Actions queue delays cannot erase a burst. - const end = action === 'opened' ? Date.parse(current.created_at) : now; - const since = end - policy.windowMinutes * 60000; - const rows = await listPages(api, `${root}/pulls?state=all&sort=created&direction=desc`, - batch => batch.some(pr => Date.parse(pr.created_at) < since)); - // Inspect later windows too: delivery order and replaced pending runs must not - // let an older event conceal a newer burst already present in the API snapshot. - const result = { ...strongestWindow(rows, current, policy, end), author: current.user.login, - dryRun, errors: [], blockStatus: 'Below blocking threshold' }; + const burstExempt = ['admin', 'maintain', 'write'].includes(permission); + let result; + if (burstExempt) { + result = { author: current.user.login, burstExempt, dryRun, errors: [], + excess: [], blockStatus: 'Exempt from burst threshold' }; + } else { + // Anchor opened events to GitHub's creation time so Actions queue delays cannot erase a burst. + const end = action === 'opened' ? Date.parse(current.created_at) : now; + const since = end - policy.windowMinutes * 60000; + const rows = await listPages(api, `${root}/pulls?state=all&sort=created&direction=desc`, + batch => batch.some(pr => Date.parse(pr.created_at) < since)); + // Inspect later windows too: delivery order and replaced pending runs must not + // let an older event conceal a newer burst already present in the API snapshot. + result = { ...strongestWindow(rows, current, policy, end), author: current.user.login, + burstExempt, dryRun, errors: [], blockStatus: 'Below blocking threshold' }; + } // Total open PRs is a separate, unwindowed list: the burst scan stops at the window edge. const openRows = await listPages(api, `${root}/pulls?state=open&sort=created&direction=desc`); Object.assign(result, capExcess(openRows, current, policy, new Set(result.excess.map(pr => pr.number)), action)); diff --git a/tests/ci/pr-burst-guard-workflow.test.js b/tests/ci/pr-burst-guard-workflow.test.js index 5c260d6c0..bfc2280da 100644 --- a/tests/ci/pr-burst-guard-workflow.test.js +++ b/tests/ci/pr-burst-guard-workflow.test.js @@ -85,18 +85,23 @@ test('actual CLI closes six excess PRs, locks them, blocks with owner identity, return true; }); permission = 'write'; - assert.equal(JSON.parse((await run()).stdout).exempt, true); + const beforeCollaboratorRun = mutations.length; + assert.equal(JSON.parse((await run()).stdout).burstExempt, true); + assert.equal(mutations.length, beforeCollaboratorRun); } finally { await new Promise(resolve => server.close(resolve)); fs.rmSync(tmp, { recursive: true, force: true }); } }); -test('actual CLI closes only a new PR when twenty earlier PRs remain open', async () => { +for (const permission of ['read', 'write']) test(`actual CLI caps ${permission} author without closing twenty earlier PRs`, async () => { const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-pr-cap-')); - const rows = Array.from({ length: 21 }, (_, i) => ({ number: i === 20 ? 3649 : i + 1, + const closedTrigger = permission === 'write'; + const extraNewer = closedTrigger ? 5 : 0; + const rows = Array.from({ length: 21 + extraNewer }, (_, i) => ({ number: i < 20 ? i + 1 : 3649 + i - 20, user: { id: 42, login: 'contributor' }, state: 'open', created_at: new Date(Date.UTC(2026, 9, 1, i, 0, 0)).toISOString() })); + if (closedTrigger) rows[20].state = 'closed'; const mutations = []; const server = http.createServer(async (req, res) => { const url = new URL(req.url, 'http://localhost'); @@ -106,11 +111,14 @@ test('actual CLI closes only a new PR when twenty earlier PRs remain open', asyn const send = value => { res.setHeader('Content-Type', 'application/json'); res.end(JSON.stringify(value)); }; if (req.method !== 'GET') mutations.push({ method: req.method, route: url.pathname, body }); if (url.pathname === '/repos/owner/repo') return send({ owner: { login: 'owner', type: 'User' } }); - if (url.pathname.includes('/collaborators/')) return send({ permission: 'read' }); + if (url.pathname.includes('/collaborators/')) return send({ permission }); if (url.pathname.endsWith('/pulls/3649') && req.method === 'GET') return send(rows[20]); if (url.pathname.endsWith('/pulls')) return send(rows.filter(pr => url.searchParams.get('state') !== 'open' || pr.state === 'open').reverse()); - if (url.pathname.endsWith('/issues/3649/comments')) return send(req.method === 'GET' ? [] : {}); - if (url.pathname.endsWith('/pulls/3649') && req.method === 'PATCH') { rows[20].state = body.state; return send(rows[20]); } + if (/\/issues\/\d+\/comments$/.test(url.pathname)) return send(req.method === 'GET' ? [] : {}); + if (/\/pulls\/\d+$/.test(url.pathname) && req.method === 'PATCH') { + const pr = rows.find(row => row.number === Number(url.pathname.split('/').pop())); + pr.state = body.state; return send(pr); + } res.statusCode = 404; send({ message: 'fixture route missing' }); }); await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)); @@ -123,11 +131,16 @@ test('actual CLI closes only a new PR when twenty earlier PRs remain open', asyn const env = { ...process.env, NODE_OPTIONS: `--require=${preload}`, GITHUB_REPOSITORY: 'owner/repo', GITHUB_TOKEN: 'moderation-token', GITHUB_EVENT_PATH: event, PR_MODERATION_BLOCK_TOKEN: '' }; const report = JSON.parse((await exec(process.execPath, ['scripts/ci/pr-burst-guard.js'], { cwd: root, env })).stdout); - assert.equal(report.openCount, 21); - assert.deepEqual(report.capExcess.map(pr => pr.number), [3649]); + assert.equal(report.openCount, 21 + extraNewer - Number(closedTrigger)); + assert.equal(report.burstExempt, permission === 'write'); + const expectedExcess = Array.from({ length: 1 + extraNewer - Number(closedTrigger) }, + (_, i) => 3649 + i + Number(closedTrigger)); + assert.deepEqual(report.capExcess.map(pr => pr.number), expectedExcess); assert.equal(rows.filter(pr => pr.state === 'open').length, 20); - assert.deepEqual(mutations.filter(m => m.method === 'PATCH').map(m => m.route), ['/repos/owner/repo/pulls/3649']); - assert.match(mutations.find(m => m.route.endsWith('/issues/3649/comments')).body.body, /21 open pull requests.*limit of 10/); + assert.deepEqual(mutations.filter(m => m.method === 'PATCH').map(m => m.route), + expectedExcess.map(number => `/repos/owner/repo/pulls/${number}`)); + assert.match(mutations.find(m => m.route.endsWith(`/issues/${expectedExcess[0]}/comments`)).body.body, + new RegExp(`${21 + extraNewer - Number(closedTrigger)} open pull requests.*limit of 10`)); } finally { await new Promise(resolve => server.close(resolve)); fs.rmSync(tmp, { recursive: true, force: true }); diff --git a/tests/ci/pr-burst-guard.test.js b/tests/ci/pr-burst-guard.test.js index 48ef9be89..3222019e6 100644 --- a/tests/ci/pr-burst-guard.test.js +++ b/tests/ci/pr-burst-guard.test.js @@ -101,10 +101,11 @@ test('wrong personal identity never blocks and records the failure', async () => assert.match((await moderate(f.args)).blockStatus, /owner identity/); }); -test('write/admin collaborators bypass; actor identity cannot exempt an outsider', async () => { +test('write/admin collaborators bypass burst moderation; actor identity cannot exempt an outsider', async () => { for (const permission of ['write', 'maintain', 'admin']) { - const f = fixture(11, { permission }); - assert.equal((await moderate(f.args)).exempt, true); + const f = fixture(10, { permission }); + const result = await moderate(f.args); + assert.equal(result.burstExempt, true); assert.equal(f.calls.filter(c => ['POST', 'PATCH', 'PUT'].includes(c.method)).length, 0); } const f = fixture(6, { actor: 'owner' }); @@ -202,6 +203,19 @@ test('open-PR cap closes only the triggering excess PR', () => { assert.equal(capExcess(spread(12, { user: { id: 7, login: 'other' } }), pull(1), policy).openCount, 1); }); +test('a delayed opened event reconciles newer excess PRs without touching older PRs', () => { + const rows = spread(25); + const result = capExcess(rows, rows[20], policy); + assert.deepEqual(result.capExcess.map(pr => pr.number), [21, 22, 23, 24, 25]); + const closedTrigger = { ...rows[20], state: 'closed' }; + assert.deepEqual(capExcess(rows.filter(pr => pr.number !== 21), closedTrigger, policy) + .capExcess.map(pr => pr.number), [22, 23, 24, 25]); + assert.deepEqual(capExcess(rows, rows[20], policy, new Set([21])) + .capExcess.map(pr => pr.number), [22, 23, 24, 25]); + assert.deepEqual(capExcess(rows, rows[0], policy, new Set(), 'reopened') + .capExcess.map(pr => pr.number), [1]); +}); + test('a new PR over twenty existing open PRs is the only cap closure and gets a comment', async () => { const f = fixture(21, { rows: spread(21) }); const result = await moderate(f.args); @@ -221,12 +235,13 @@ test('reopening an older PR over the cap closes that PR without touching its pee ['/repos/owner/repo/pulls/1']); }); -test('an older allowed PR stays open when later PRs are already visible', async () => { +test('an older allowed PR stays open while its newer excess peers are closed', async () => { const f = fixture(12, { rows: spread(12) }); f.args.number = 10; const result = await moderate(f.args); - assert.deepEqual(result.capExcess, []); - assert.equal(f.calls.filter(c => c.method !== 'GET').length, 0); + assert.deepEqual(result.capExcess.map(pr => pr.number), [11, 12]); + assert.deepEqual(f.calls.filter(c => c.method === 'PATCH').map(c => c.route), + ['/repos/owner/repo/pulls/11', '/repos/owner/repo/pulls/12']); }); test('cap closes with an explanatory comment, no lock, no maintainer alert, and never comments twice', async () => { @@ -262,13 +277,23 @@ test('cap counts open PRs after burst closures, so one run never closes a PR twi assert.equal(f.calls.filter(c => c.method === 'PATCH' && c.route.includes('/pulls/')).length, 1); }); -test('cap dry run reports the excess without mutating; collaborators are exempt from the cap', async () => { +test('cap dry run reports the excess without mutating', async () => { const f = fixture(12, { rows: spread(12), dryRun: true }); assert.deepEqual((await moderate(f.args)).capExcess.map(p => p.number), [12]); assert(f.calls.every(c => c.method === 'GET')); - const w = fixture(12, { rows: spread(12), permission: 'write' }); - assert.equal((await moderate(w.args)).exempt, true); - assert.equal(w.calls.filter(c => c.method !== 'GET').length, 0); +}); + +test('cap applies to every author while collaborators remain exempt from burst enforcement', async () => { + for (const permission of ['write', 'maintain', 'admin']) { + const f = fixture(21, { rows: spread(21), permission }); + const result = await moderate(f.args); + assert.equal(result.burstExempt, true); + assert.deepEqual(result.capExcess.map(p => p.number), [21]); + assert.deepEqual(f.calls.filter(c => c.method === 'PATCH').map(c => c.route), + ['/repos/owner/repo/pulls/21']); + assert(f.calls.some(c => c.method === 'POST' && c.route.endsWith('/issues/21/comments'))); + assert.equal(f.calls.filter(c => c.method === 'PUT').length, 0); + } }); test('policy requires a positive integer maxOpen', () => { From 688cefe95ea17804ab2182cdcd3fe82ec9d0e9f4 Mon Sep 17 00:00:00 2001 From: haelyra <49814733+haelyra@users.noreply.github.com> Date: Thu, 22 Oct 2026 18:11:04 -0400 Subject: [PATCH 4/4] docs(ci): clarify open PR grandfathering --- CONTRIBUTING.md | 7 ++++--- tests/ci/pr-burst-guard-workflow.test.js | 15 ++++++++------- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ecdcc89ef..a71189ad1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -443,9 +443,10 @@ burst moderation. Maintainers can review exceptions through the moderation alert Please also keep at most ten PRs open at a time. When you open or reopen a PR above that cap, automation closes that PR with a comment explaining the count. -Existing open PRs remain open, even for authors already above ten. The cap applies -to every author, including maintainers. Get PRs merged or close the ones you no -longer need, then reopen. +PRs already open before this policy update stay open, even for authors above ten. +A delayed check can close newer excess PRs already open when that check runs. +The cap applies to every author, including maintainers. Get PRs merged or close +the ones you no longer need, then reopen. Ten open PRs is more than any one reviewer can keep in flight, so this keeps review time on the work you care about most. diff --git a/tests/ci/pr-burst-guard-workflow.test.js b/tests/ci/pr-burst-guard-workflow.test.js index bfc2280da..a3da339c9 100644 --- a/tests/ci/pr-burst-guard-workflow.test.js +++ b/tests/ci/pr-burst-guard-workflow.test.js @@ -98,10 +98,9 @@ for (const permission of ['read', 'write']) test(`actual CLI caps ${permission} const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-pr-cap-')); const closedTrigger = permission === 'write'; const extraNewer = closedTrigger ? 5 : 0; - const rows = Array.from({ length: 21 + extraNewer }, (_, i) => ({ number: i < 20 ? i + 1 : 3649 + i - 20, - user: { id: 42, login: 'contributor' }, state: 'open', + let rows = Array.from({ length: 21 + extraNewer }, (_, i) => ({ number: i < 20 ? i + 1 : 3649 + i - 20, + user: { id: 42, login: 'contributor' }, state: closedTrigger && i === 20 ? 'closed' : 'open', created_at: new Date(Date.UTC(2026, 9, 1, i, 0, 0)).toISOString() })); - if (closedTrigger) rows[20].state = 'closed'; const mutations = []; const server = http.createServer(async (req, res) => { const url = new URL(req.url, 'http://localhost'); @@ -116,8 +115,9 @@ for (const permission of ['read', 'write']) test(`actual CLI caps ${permission} if (url.pathname.endsWith('/pulls')) return send(rows.filter(pr => url.searchParams.get('state') !== 'open' || pr.state === 'open').reverse()); if (/\/issues\/\d+\/comments$/.test(url.pathname)) return send(req.method === 'GET' ? [] : {}); if (/\/pulls\/\d+$/.test(url.pathname) && req.method === 'PATCH') { - const pr = rows.find(row => row.number === Number(url.pathname.split('/').pop())); - pr.state = body.state; return send(pr); + const number = Number(url.pathname.split('/').pop()); + rows = rows.map(row => row.number === number ? { ...row, state: body.state } : row); + return send(rows.find(row => row.number === number)); } res.statusCode = 404; send({ message: 'fixture route missing' }); }); @@ -139,8 +139,9 @@ for (const permission of ['read', 'write']) test(`actual CLI caps ${permission} assert.equal(rows.filter(pr => pr.state === 'open').length, 20); assert.deepEqual(mutations.filter(m => m.method === 'PATCH').map(m => m.route), expectedExcess.map(number => `/repos/owner/repo/pulls/${number}`)); - assert.match(mutations.find(m => m.route.endsWith(`/issues/${expectedExcess[0]}/comments`)).body.body, - new RegExp(`${21 + extraNewer - Number(closedTrigger)} open pull requests.*limit of 10`)); + const comment = mutations.find(m => m.route.endsWith(`/issues/${expectedExcess[0]}/comments`)).body.body; + assert(comment.includes(`${21 + extraNewer - Number(closedTrigger)} open pull requests`)); + assert(comment.includes('limit of 10')); } finally { await new Promise(resolve => server.close(resolve)); fs.rmSync(tmp, { recursive: true, force: true });