Skip to content

Commit bbe6887

Browse files
committed
chore: add contribution firewall
1 parent bb8a95e commit bbe6887

7 files changed

Lines changed: 671 additions & 6 deletions

File tree

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 28 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,35 @@
11
## Summary
22

3-
- Explain the user-visible or maintainer-facing change.
3+
Explain the user-visible or maintainer-facing change and why this approach is appropriate.
4+
5+
## Linked issue
6+
7+
Closes #<!-- issue number -->
8+
9+
Implementation pull requests must reference an issue labeled `approved-for-work`. Documentation-only and maintainer-owned integration changes are exempt.
410

511
## Verification
612

7-
- List the commands or checks you ran.
13+
List the exact commands or checks you ran and their results. Do not write only "tested" or "CI".
14+
15+
```text
16+
bun run typecheck
17+
bun run test
18+
```
19+
20+
## Regression coverage
21+
22+
Name the test that fails without this change and passes with it. If automated coverage is genuinely impossible, explain why and describe the manual evidence.
23+
24+
## Screenshots or recordings
25+
26+
Required for user-visible dashboard changes. Remove this section when it does not apply.
827

9-
## Checklist
28+
## Author responsibility
1029

11-
- [ ] Scope stays focused and avoids unrelated cleanup.
12-
- [ ] Docs or release notes were updated when needed.
13-
- [ ] Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.
30+
- [ ] I reviewed every changed line and can explain the implementation.
31+
- [ ] I ran the validation commands listed above.
32+
- [ ] Behavior changes include focused regression coverage, or I explained why automated coverage is impossible.
33+
- [ ] The pull request contains no unrelated cleanup, generated churn, or accidental lockfile changes.
34+
- [ ] I checked automated-review findings critically instead of applying them blindly.
35+
- [ ] I will remain available to resolve CI failures and review feedback.

‎.github/scripts/pr-admission.cjs‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
"use strict";
2+
3+
const IMPLEMENTATION_PREFIXES = [
4+
"src/",
5+
"gui/",
6+
"scripts/",
7+
"tests/",
8+
"bin/",
9+
"packages/",
10+
];
11+
12+
const IMPLEMENTATION_FILES = new Set([
13+
"package.json",
14+
"bun.lock",
15+
"tsconfig.json",
16+
]);
17+
18+
const REQUIRED_ATTESTATIONS = [
19+
"I reviewed every changed line and can explain the implementation.",
20+
"I ran the validation commands listed above.",
21+
"Behavior changes include focused regression coverage, or I explained why automated coverage is impossible.",
22+
"The pull request contains no unrelated cleanup, generated churn, or accidental lockfile changes.",
23+
"I checked automated-review findings critically instead of applying them blindly.",
24+
"I will remain available to resolve CI failures and review feedback.",
25+
];
26+
27+
function normalizeCheckboxLabel(value) {
28+
return value.trim().replace(/\s+/g, " ");
29+
}
30+
31+
function checkedAttestations(body) {
32+
const checked = new Set();
33+
const text = typeof body === "string" ? body : "";
34+
for (const match of text.matchAll(/^\s*[-*+]\s+\[[xX]\]\s+(.+?)\s*$/gm)) {
35+
checked.add(normalizeCheckboxLabel(match[1]));
36+
}
37+
return checked;
38+
}
39+
40+
function missingAttestations(body) {
41+
const checked = checkedAttestations(body);
42+
return REQUIRED_ATTESTATIONS.filter((label) => !checked.has(label));
43+
}
44+
45+
function extractLinkedIssueNumbers(body) {
46+
const text = typeof body === "string" ? body : "";
47+
const numbers = new Set();
48+
49+
for (const match of text.matchAll(
50+
/\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?|refs?|issue)\s*:?\s*#(\d+)\b/gi,
51+
)) {
52+
numbers.add(Number(match[1]));
53+
}
54+
55+
return [...numbers];
56+
}
57+
58+
function isImplementationPath(path) {
59+
if (IMPLEMENTATION_FILES.has(path)) return true;
60+
return IMPLEMENTATION_PREFIXES.some((prefix) => path.startsWith(prefix));
61+
}
62+
63+
function needsApprovedIssue(changedFiles) {
64+
return changedFiles.some(isImplementationPath);
65+
}
66+
67+
function issueIsApproved(issue) {
68+
return issue.labels.some((label) => {
69+
const name = typeof label === "string" ? label : label?.name;
70+
return name === "approved-for-work";
71+
});
72+
}
73+
74+
function assessAdmission({
75+
body,
76+
changedFiles,
77+
linkedIssues,
78+
authorHasPushPermission = false,
79+
}) {
80+
const failures = [];
81+
const missing = missingAttestations(body);
82+
83+
if (missing.length > 0) {
84+
failures.push({ code: "missing_attestations", missing });
85+
}
86+
87+
if (needsApprovedIssue(changedFiles) && !authorHasPushPermission) {
88+
if (linkedIssues.length === 0) {
89+
failures.push({ code: "missing_issue" });
90+
} else if (!linkedIssues.some(issueIsApproved)) {
91+
failures.push({
92+
code: "issue_not_approved",
93+
issues: linkedIssues.map((issue) => issue.number),
94+
});
95+
}
96+
}
97+
98+
return failures;
99+
}
100+
101+
module.exports = {
102+
REQUIRED_ATTESTATIONS,
103+
assessAdmission,
104+
checkedAttestations,
105+
extractLinkedIssueNumbers,
106+
isImplementationPath,
107+
issueIsApproved,
108+
missingAttestations,
109+
needsApprovedIssue,
110+
};
Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
"use strict";
2+
3+
const { describe, it } = require("node:test");
4+
const assert = require("node:assert/strict");
5+
const {
6+
REQUIRED_ATTESTATIONS,
7+
assessAdmission,
8+
extractLinkedIssueNumbers,
9+
missingAttestations,
10+
needsApprovedIssue,
11+
} = require("./pr-admission.cjs");
12+
13+
function completeBody(extra = "") {
14+
return [
15+
"## Summary",
16+
"A complete explanation of the change and why it is needed.",
17+
"",
18+
"## Linked issue",
19+
"Closes #123",
20+
"",
21+
"## Author responsibility",
22+
...REQUIRED_ATTESTATIONS.map((label) => `- [x] ${label}`),
23+
"",
24+
extra,
25+
].join("\n");
26+
}
27+
28+
describe("missingAttestations", () => {
29+
it("rejects unchecked and missing author responsibility items", () => {
30+
const body = [
31+
`- [x] ${REQUIRED_ATTESTATIONS[0]}`,
32+
`- [ ] ${REQUIRED_ATTESTATIONS[1]}`,
33+
].join("\n");
34+
35+
assert.deepEqual(
36+
missingAttestations(body),
37+
REQUIRED_ATTESTATIONS.slice(1),
38+
);
39+
});
40+
41+
it("accepts every required checked item", () => {
42+
assert.deepEqual(missingAttestations(completeBody()), []);
43+
});
44+
});
45+
46+
describe("extractLinkedIssueNumbers", () => {
47+
it("recognizes closing and reference syntax without duplicates", () => {
48+
assert.deepEqual(
49+
extractLinkedIssueNumbers("Closes #12\nRefs: #34\nFixes #12"),
50+
[12, 34],
51+
);
52+
});
53+
});
54+
55+
describe("needsApprovedIssue", () => {
56+
it("requires an approved issue for implementation paths", () => {
57+
assert.equal(needsApprovedIssue(["src/router.ts"]), true);
58+
assert.equal(needsApprovedIssue(["gui/src/App.tsx"]), true);
59+
assert.equal(needsApprovedIssue(["package.json"]), true);
60+
});
61+
62+
it("does not require one for documentation-only changes", () => {
63+
assert.equal(
64+
needsApprovedIssue(["README.md", "docs-site/src/content/docs/foo.md"]),
65+
false,
66+
);
67+
});
68+
});
69+
70+
describe("assessAdmission", () => {
71+
it("rejects implementation PRs with no linked issue", () => {
72+
const failures = assessAdmission({
73+
body: completeBody(),
74+
changedFiles: ["src/router.ts"],
75+
linkedIssues: [],
76+
});
77+
78+
assert.deepEqual(failures, [{ code: "missing_issue" }]);
79+
});
80+
81+
it("rejects linked issues that are not approved for work", () => {
82+
const failures = assessAdmission({
83+
body: completeBody(),
84+
changedFiles: ["src/router.ts"],
85+
linkedIssues: [{ number: 123, labels: ["bug"] }],
86+
});
87+
88+
assert.deepEqual(failures, [
89+
{ code: "issue_not_approved", issues: [123] },
90+
]);
91+
});
92+
93+
it("accepts an approved implementation issue", () => {
94+
const failures = assessAdmission({
95+
body: completeBody(),
96+
changedFiles: ["src/router.ts"],
97+
linkedIssues: [
98+
{ number: 123, labels: [{ name: "approved-for-work" }] },
99+
],
100+
});
101+
102+
assert.deepEqual(failures, []);
103+
});
104+
105+
it("allows maintainers to perform integration work without an issue", () => {
106+
const failures = assessAdmission({
107+
body: completeBody(),
108+
changedFiles: ["src/router.ts"],
109+
linkedIssues: [],
110+
authorHasPushPermission: true,
111+
});
112+
113+
assert.deepEqual(failures, []);
114+
});
115+
116+
it("still requires maintainer attestations", () => {
117+
const failures = assessAdmission({
118+
body: "",
119+
changedFiles: ["src/router.ts"],
120+
linkedIssues: [],
121+
authorHasPushPermission: true,
122+
});
123+
124+
assert.equal(failures[0].code, "missing_attestations");
125+
});
126+
});

0 commit comments

Comments
 (0)