Skip to content

Commit 6eb1c0c

Browse files
authored
Merge pull request #960 from lidge-jun/codex/gui-screenshot-gate
feat(ci): require UI screenshot evidence for PRs mentioning gui
2 parents cb8fcf3 + 40291f8 commit 6eb1c0c

10 files changed

Lines changed: 471 additions & 12 deletions

File tree

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
## Verification
66

77
- List the commands or checks you ran.
8+
- If this PR changes the GUI, include a screenshot of the UI change in the description.
89

910
## Checklist
1011

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

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,11 +22,27 @@ const UNSTRUCTURED_MIN_BLOCKS = 2;
2222
const PR_TEMPLATE_BOILERPLATE_LINES = new Set([
2323
"explain the user-visible or maintainer-facing change.",
2424
"list the commands or checks you ran.",
25+
"if this pr changes the gui, include a screenshot of the ui change in the description.",
2526
"scope stays focused and avoids unrelated cleanup.",
2627
"docs or release notes were updated when needed.",
2728
"security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.",
2829
]);
2930

31+
/** Case-insensitive whole-word match for the GUI surface (repo convention: `gui/`). */
32+
const GUI_CUE_RE = /\bgui\b/i;
33+
/** HTML comments, which GitHub never renders. */
34+
const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
35+
/** Fenced code blocks (``` or ~~~) whose content GitHub does not render. */
36+
const FENCED_CODE_RE = /(?:^|\n)[ \t]*(`{3,}|~{3,})[^\n]*\n[\s\S]*?^[ \t]*\1[ \t]*(?=\n|$)/gm;
37+
/** Embedded markdown image (`![alt](url)`), as GitHub renders for dropped images. */
38+
const MARKDOWN_IMAGE_RE = /!\[[^\]]*\]\([^)]+\)/;
39+
/** Reference-style markdown image (`![alt][id]`, collapsed `![alt][]`). */
40+
const MARKDOWN_REFERENCE_IMAGE_RE = /!\[([^\]]*)\]\[([^\]]*)\]/g;
41+
/** Link definitions (`[id]: url`) that reference-style images depend on. */
42+
const MARKDOWN_REFERENCE_DEF_RE = /^\s*\[([^\]]+)\]:\s*\S+/gm;
43+
/** Embedded HTML image with a renderable `src` (`<img ... src="...">`). */
44+
const HTML_IMAGE_RE = /<img\b[^>]*\bsrc\s*=\s*(?:"[^"]+"|'[^']+'|[^\s>"']+)[^>]*>/i;
45+
3046
function isWrongAncestry({
3147
behindMain,
3248
behindBase,
@@ -124,9 +140,61 @@ function assessPrDescription(body) {
124140
return { ok: false, reason: "thin" };
125141
}
126142

143+
/**
144+
* True when the PR title or description names the GUI surface as a whole word.
145+
* The description is template-stripped first so the template's own screenshot
146+
* instruction cannot arm the gate on its own.
147+
*/
148+
function hasGuiCue(title, body) {
149+
return (
150+
(typeof title === "string" && GUI_CUE_RE.test(title)) ||
151+
(typeof body === "string" && GUI_CUE_RE.test(body))
152+
);
153+
}
154+
155+
/**
156+
* Drop the regions GitHub does not render as Markdown: HTML comments and
157+
* fenced code blocks. Image syntax there is literal text, not evidence.
158+
*/
159+
function stripNonRenderedRegions(body) {
160+
return body.replace(HTML_COMMENT_RE, "").replace(FENCED_CODE_RE, "");
161+
}
162+
163+
/**
164+
* True when the description contains a reference-style image (`![alt][id]` or
165+
* collapsed `![alt][]`) backed by a matching `[id]: url` definition — GitHub
166+
* renders only those reference images, so a bare token is not evidence.
167+
*/
168+
function hasRenderableReferenceImage(visible) {
169+
const definitions = new Set();
170+
for (const match of visible.matchAll(MARKDOWN_REFERENCE_DEF_RE)) {
171+
definitions.add(match[1].trim().toLowerCase());
172+
}
173+
if (definitions.size === 0) return false;
174+
for (const match of visible.matchAll(MARKDOWN_REFERENCE_IMAGE_RE)) {
175+
const id = (match[2] || match[1]).trim().toLowerCase();
176+
if (id && definitions.has(id)) return true;
177+
}
178+
return false;
179+
}
180+
181+
/**
182+
* True when the rendered description embeds a screenshot image: an inline
183+
* markdown image, a reference-style image with a definition, or an `<img>` tag
184+
* with a non-empty `src`. A plain link to an image is not visual evidence.
185+
*/
186+
function hasScreenshotEvidence(body) {
187+
if (typeof body !== "string") return false;
188+
const visible = stripNonRenderedRegions(body);
189+
if (MARKDOWN_IMAGE_RE.test(visible)) return true;
190+
if (HTML_IMAGE_RE.test(visible)) return true;
191+
return hasRenderableReferenceImage(visible);
192+
}
193+
127194
function collectPrQualityFailures({
128195
baseRef,
129196
allowedBases,
197+
title = "",
130198
body,
131199
behindMain,
132200
behindBase,
@@ -162,6 +230,18 @@ function collectPrQualityFailures({
162230
if (!desc.ok) {
163231
failures.push({ code: "bad_description", reason: desc.reason });
164232
}
233+
234+
// GUI-cued PRs must prove the UI change visually. The template's own
235+
// screenshot instruction is boilerplate, so it cannot trigger this gate.
236+
if (
237+
hasGuiCue(
238+
title,
239+
typeof body === "string" ? stripPrTemplateBoilerplate(body) : "",
240+
) &&
241+
!hasScreenshotEvidence(body)
242+
) {
243+
failures.push({ code: "missing_ui_screenshot" });
244+
}
165245
return failures;
166246
}
167247

@@ -171,6 +251,8 @@ module.exports = {
171251
isWrongAncestry,
172252
authorHasPushPermission,
173253
assessPrDescription,
254+
hasGuiCue,
255+
hasScreenshotEvidence,
174256
collectPrQualityFailures,
175257
hasEscapedNewlines,
176258
stripPrTemplateBoilerplate,

‎.github/scripts/pr-quality.test.cjs‎

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ const {
77
isWrongAncestry,
88
authorHasPushPermission,
99
assessPrDescription,
10+
hasGuiCue,
11+
hasScreenshotEvidence,
1012
collectPrQualityFailures,
1113
} = require("./pr-quality.cjs");
1214

@@ -81,6 +83,7 @@ describe("assessPrDescription", () => {
8183
"## Verification",
8284
"",
8385
"- List the commands or checks you ran.",
86+
"- If this PR changes the GUI, include a screenshot of the UI change in the description.",
8487
"",
8588
"## Checklist",
8689
"",
@@ -114,9 +117,115 @@ describe("assessPrDescription", () => {
114117
});
115118
});
116119

120+
describe("hasGuiCue", () => {
121+
it("matches gui as a whole word, case-insensitively, in title or body", () => {
122+
assert.equal(hasGuiCue("Fix GUI spacing", ""), true);
123+
assert.equal(hasGuiCue("fix gui spacing", ""), true);
124+
assert.equal(hasGuiCue("", "This changes gui/src/App.tsx"), true);
125+
assert.equal(
126+
hasGuiCue("", "## Summary\nGUI button is misaligned in the dashboard"),
127+
true,
128+
);
129+
});
130+
131+
it("does not match gui inside other words", () => {
132+
assert.equal(hasGuiCue("Add contributor guidance", ""), false);
133+
assert.equal(hasGuiCue("", "Fix the guild invitation bug"), false);
134+
assert.equal(hasGuiCue("", "Remove guillotine dead code"), false);
135+
});
136+
137+
it("does not match missing or non-string inputs", () => {
138+
assert.equal(hasGuiCue(undefined, undefined), false);
139+
assert.equal(hasGuiCue(null, null), false);
140+
});
141+
});
142+
143+
describe("hasScreenshotEvidence", () => {
144+
it("accepts embedded markdown images", () => {
145+
assert.equal(
146+
hasScreenshotEvidence("![after](https://example.com/after.png)"),
147+
true,
148+
);
149+
assert.equal(
150+
hasScreenshotEvidence(
151+
"Before:\n\n![Screenshot 2026-08-03 at 14.22](https://user-images.githubusercontent.com/1/2.png)",
152+
),
153+
true,
154+
);
155+
});
156+
157+
it("accepts HTML img tags", () => {
158+
assert.equal(
159+
hasScreenshotEvidence('<img src="https://example.com/ui.png" width="600">'),
160+
true,
161+
);
162+
});
163+
164+
it("accepts reference-style images with a matching definition", () => {
165+
assert.equal(
166+
hasScreenshotEvidence(
167+
"After:\n\n![after][shot]\n\n[shot]: https://example.com/after.png",
168+
),
169+
true,
170+
);
171+
assert.equal(
172+
hasScreenshotEvidence(
173+
"![after][]\n\n[after]: https://example.com/after.png",
174+
),
175+
true,
176+
);
177+
});
178+
179+
it("rejects image syntax inside fenced code and HTML comments", () => {
180+
assert.equal(
181+
hasScreenshotEvidence('```\n![after](https://example.com/after.png)\n```'),
182+
false,
183+
);
184+
assert.equal(
185+
hasScreenshotEvidence('```\n<img src="https://example.com/ui.png">\n```'),
186+
false,
187+
);
188+
assert.equal(
189+
hasScreenshotEvidence("<!-- ![after](https://example.com/after.png) -->"),
190+
false,
191+
);
192+
assert.equal(
193+
hasScreenshotEvidence('<!-- <img src="https://example.com/ui.png"> -->'),
194+
false,
195+
);
196+
});
197+
198+
it("rejects img tags without a renderable src and references without a definition", () => {
199+
assert.equal(hasScreenshotEvidence("<img>"), false);
200+
assert.equal(hasScreenshotEvidence('<img src="">'), false);
201+
assert.equal(
202+
hasScreenshotEvidence("![after][shot]"),
203+
false,
204+
);
205+
});
206+
207+
it("rejects plain links, bare image URLs, and text-only bodies", () => {
208+
assert.equal(
209+
hasScreenshotEvidence("[Screenshot](https://example.com/ui.png)"),
210+
false,
211+
);
212+
assert.equal(hasScreenshotEvidence("https://example.com/ui.png"), false);
213+
assert.equal(hasScreenshotEvidence("No screenshot here."), false);
214+
assert.equal(hasScreenshotEvidence(undefined), false);
215+
});
216+
});
217+
117218
describe("collectPrQualityFailures", () => {
118219
const allowed = ["dev"];
119220

221+
const richBody = [
222+
"## Summary",
223+
"This change fixes the provider list spacing in the dashboard.",
224+
"",
225+
"## Test plan",
226+
"- Ran bun test tests/ci-workflows.test.ts",
227+
].join("\n");
228+
120229
it("reports wrong_base without requiring ancestry inputs", () => {
121230
const failures = collectPrQualityFailures({
122231
baseRef: "main",
@@ -277,4 +386,128 @@ describe("collectPrQualityFailures", () => {
277386
});
278387
assert.ok(failures.some((f) => f.code === "wrong_base"));
279388
});
389+
390+
it("flags a gui title without a screenshot", () => {
391+
const failures = collectPrQualityFailures({
392+
baseRef: "dev",
393+
allowedBases: allowed,
394+
title: "GUI: fix provider list spacing",
395+
body: richBody,
396+
behindMain: 0,
397+
behindBase: 0,
398+
authorPermission: "read",
399+
});
400+
assert.ok(failures.some((f) => f.code === "missing_ui_screenshot"));
401+
});
402+
403+
it("flags a gui mention in the body without a screenshot", () => {
404+
const failures = collectPrQualityFailures({
405+
baseRef: "dev",
406+
allowedBases: allowed,
407+
title: "Fix dashboard spacing",
408+
body: [
409+
"## Summary",
410+
"This change adjusts gui/ spacing tokens used by the dashboard.",
411+
"",
412+
"## Test plan",
413+
"- Ran bun test tests/ci-workflows.test.ts",
414+
].join("\n"),
415+
behindMain: 0,
416+
behindBase: 0,
417+
authorPermission: "read",
418+
});
419+
assert.ok(failures.some((f) => f.code === "missing_ui_screenshot"));
420+
});
421+
422+
it("accepts a gui title when a screenshot image is embedded", () => {
423+
const failures = collectPrQualityFailures({
424+
baseRef: "dev",
425+
allowedBases: allowed,
426+
title: "GUI: fix provider list spacing",
427+
body: [
428+
"## Summary",
429+
"This change fixes the provider list spacing in the dashboard.",
430+
"",
431+
"![after](https://example.com/after.png)",
432+
"",
433+
"## Test plan",
434+
"- Ran bun test tests/ci-workflows.test.ts",
435+
].join("\n"),
436+
behindMain: 0,
437+
behindBase: 0,
438+
authorPermission: "read",
439+
});
440+
assert.ok(!failures.some((f) => f.code === "missing_ui_screenshot"));
441+
});
442+
443+
it("accepts a gui title when the screenshot uses reference-style markdown", () => {
444+
const failures = collectPrQualityFailures({
445+
baseRef: "dev",
446+
allowedBases: allowed,
447+
title: "GUI: fix provider list spacing",
448+
body: [
449+
"## Summary",
450+
"This change fixes the provider list spacing in the dashboard.",
451+
"",
452+
"![after][shot]",
453+
"",
454+
"[shot]: https://example.com/after.png",
455+
"",
456+
"## Test plan",
457+
"- Ran bun test tests/ci-workflows.test.ts",
458+
].join("\n"),
459+
behindMain: 0,
460+
behindBase: 0,
461+
authorPermission: "read",
462+
});
463+
assert.ok(!failures.some((f) => f.code === "missing_ui_screenshot"));
464+
});
465+
466+
it("still flags a gui title when image syntax is only inside a code fence", () => {
467+
const failures = collectPrQualityFailures({
468+
baseRef: "dev",
469+
allowedBases: allowed,
470+
title: "GUI: fix provider list spacing",
471+
body: [
472+
"## Summary",
473+
"This change fixes the provider list spacing in the dashboard.",
474+
"",
475+
"```",
476+
"![after](https://example.com/after.png)",
477+
"```",
478+
"",
479+
"## Test plan",
480+
"- Ran bun test tests/ci-workflows.test.ts",
481+
].join("\n"),
482+
behindMain: 0,
483+
behindBase: 0,
484+
authorPermission: "read",
485+
});
486+
assert.ok(failures.some((f) => f.code === "missing_ui_screenshot"));
487+
});
488+
489+
it("ignores the template's own gui/screenshot instruction", () => {
490+
const failures = collectPrQualityFailures({
491+
baseRef: "dev",
492+
allowedBases: allowed,
493+
title: "Add a thing",
494+
body: [
495+
"## Summary",
496+
"This change touches the proxy only; no UI surface changed.",
497+
"",
498+
"## Verification",
499+
"- List the commands or checks you ran.",
500+
"- If this PR changes the GUI, include a screenshot of the UI change in the description.",
501+
"",
502+
"## Checklist",
503+
"- [ ] Scope stays focused and avoids unrelated cleanup.",
504+
"- [ ] Docs or release notes were updated when needed.",
505+
"- [ ] Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.",
506+
].join("\n"),
507+
behindMain: 0,
508+
behindBase: 0,
509+
authorPermission: "read",
510+
});
511+
assert.ok(!failures.some((f) => f.code === "missing_ui_screenshot"));
512+
});
280513
});

0 commit comments

Comments
 (0)