From f1608a6a4fef93aec29260791cb88b08f6c64d98 Mon Sep 17 00:00:00 2001
From: Chaitanya Giri <16ucc028@lnmiit.ac.in>
Date: Thu, 17 Sep 2026 19:11:38 +0530
Subject: [PATCH] test(ci): pin the no-visual-change waiver, and say it out
 loud in the template

THE ESCAPE ALREADY EXISTS. `.github/workflows/pr-evidence.yml` has had the
`no-visual-change` waiver since the gate shipped, at lines 55 to 59, checked
before any parsing and returning early. The bot's own failure comment already
tells the author about it, and the label already exists in the repository. I
used it on #547 today and the check passed in three seconds.

So this change does NOT build the escape. It does the two things that were
actually missing.

ONE. IT WAS COMPLETELY UNTESTED. A branch that lets a required status check pass,
with nothing asserting when it may and may not fire, is the dangerous shape: it
can rot in two directions and neither is loud. If it stops working, a CI tweak or
a typo has no way through a required check. If it starts always firing, the gate
is decorative on every pull request and nobody notices.

Eight tests, in the style already in this file: the label name, the ordering and
the guard are read OUT of the workflow rather than restated, so editing the
workflow carelessly fails here instead of on a contributor's pull request.

  the label still matches the template and the bot comment
  the waiver is checked BEFORE the evidence is computed
  the waiver returns early rather than falling through
  it FIRES with the label, at any position in the list
  it is case insensitive, because labels are typed by hand
  it does NOT fire without the label          <- the always-pass guard
  it needs the WHOLE label, so `needs-no-visual-change` does not walk through

All four mutations go red, checked before committing:
  rename the label in the workflow only            3 tests fail
  substring match instead of exact membership      6 tests fail
  remove the early return                          1 test fails
  move the waiver after the evidence parsing       1 test fails

TWO. THE TEMPLATE ONLY MENTIONED IT INSIDE AN HTML COMMENT, so it never rendered.
There is now a visible note under `## Evidence` naming the label and saying it is
the supported way past the check. Two further tests prove that adding visible
text changed nothing: an unfilled template still fails, and the note itself is
not mistaken for evidence.

`.github/workflows/pr-evidence.yml` IS NOT MODIFIED BY THIS COMMIT.

WHY 42 PULL REQUESTS ARE STUCK, since that was the reason for the work: not a
missing escape. Of 93 open pull requests exactly one carries the label. The
escape works and nobody is applying it. Labelling them is a maintainer action
and is not in this change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PogxmT9ULRQSYbfs1oigLx
---
 .github/PULL_REQUEST_TEMPLATE.md |   4 +
 test/pr-evidence-gate.test.cjs   | 125 +++++++++++++++++++++++++++++++
 2 files changed, 129 insertions(+)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 094d0c704..10c4b030c 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -21,6 +21,10 @@
 
 ## Evidence
 
+> Nothing observable to show, such as a CI tweak, a typo or a dependency bump?
+> Say so under **What & why** and ask a maintainer for the `no-visual-change` label.
+> It is the supported way past this check. Everything else still needs a before and an after.
+
 <!-- REQUIRED. Drag images or a screen recording directly under each heading —
      GitHub uploads them inline. Both headings must have something under them.
 
diff --git a/test/pr-evidence-gate.test.cjs b/test/pr-evidence-gate.test.cjs
index 194c0eb14..8d5892c89 100644
--- a/test/pr-evidence-gate.test.cjs
+++ b/test/pr-evidence-gate.test.cjs
@@ -98,3 +98,128 @@ test('a console transcript is NOT accepted as evidence', () => {
   assert.notEqual(section('before', transcript).trim(), '', 'the section is captured');
   assert.equal(hasEvidence(section('before', transcript)), false, 'but a transcript is not evidence');
 });
+
+// ── THE MAINTAINER WAIVER ────────────────────────────────────────────────────
+//
+// 17 Sep 2026. The `no-visual-change` escape has existed since the gate shipped,
+// and nothing tested it. That is the dangerous combination: a branch that lets a
+// required check pass, with no test saying when it may and may not fire.
+//
+// Two ways it could rot, and both are covered below. It could stop working, and
+// then a CI tweak or a typo has no way through a required check. Or it could
+// start always firing, and then the gate is decorative on every pull request.
+//
+// Same discipline as the tests above: the label name and the ordering are read
+// OUT of the workflow rather than restated here, so changing the workflow
+// without meaning to fails in this file rather than on somebody's pull request.
+
+/** The waiver label, taken from the workflow verbatim. */
+function waiverLabelFromWorkflow() {
+  const m = YML.match(/const WAIVER = '([^']+)'/);
+  assert.ok(m, 'the workflow still declares a WAIVER label');
+  return m[1];
+}
+
+/** The workflow's own guard, taken from the file so a rewrite is caught here. */
+function waiverGuardFromWorkflow() {
+  const m = YML.match(/if \((labels\.includes\(WAIVER\))\) \{/);
+  assert.ok(m, 'the waiver still guards on exact label membership');
+  return m[1];
+}
+
+/** The workflow's decision, rebuilt: labels are lowercased, then matched. */
+function waived(labelNames) {
+  const labels = labelNames.map((n) => n.toLowerCase());
+  const WAIVER = waiverLabelFromWorkflow();
+  waiverGuardFromWorkflow();
+  return labels.includes(WAIVER);
+}
+
+test('the waiver label is still the one the template and the bot comment name', () => {
+  // Three places have to agree or the escape is unreachable: the workflow, the
+  // comment the bot posts, and the PR template a contributor reads.
+  const label = waiverLabelFromWorkflow();
+  assert.equal(label, 'no-visual-change');
+
+  const template = fs.readFileSync(
+    path.resolve(__dirname, '..', '.github/PULL_REQUEST_TEMPLATE.md'), 'utf8'
+  );
+  assert.ok(template.includes(label), 'the PR template names the waiver label');
+  assert.ok(YML.includes('${WAIVER}'), 'the comment the bot posts names the waiver label');
+});
+
+test('the waiver is checked BEFORE the evidence is computed', () => {
+  // Ordering is the whole point. If the waiver moved below the section parsing
+  // it would still pass the check, but a waived PR would get a "missing
+  // evidence" comment posted on it first, which is how you train people to
+  // ignore the bot.
+  const waiverAt = YML.indexOf('labels.includes(WAIVER)');
+  const sectionAt = YML.indexOf('const before = section(');
+  assert.ok(waiverAt > -1, 'the waiver branch is present');
+  assert.ok(sectionAt > -1, 'the evidence parsing is present');
+  assert.ok(waiverAt < sectionAt, 'the waiver short circuits before any parsing');
+});
+
+test('the waiver returns early rather than falling through', () => {
+  // Without the `return` the job carries on and fails the PR anyway.
+  const m = YML.match(/if \(labels\.includes\(WAIVER\)\) \{[\s\S]{0,200}?\n\s*\}/);
+  assert.ok(m, 'the waiver branch is present');
+  assert.match(m[0], /\breturn\b/, 'the waiver branch returns');
+});
+
+test('the waiver FIRES when a maintainer applies the label', () => {
+  assert.equal(waived(['no-visual-change']), true);
+  assert.equal(waived(['bug', 'no-visual-change', 'ci']), true, 'position does not matter');
+});
+
+test('the waiver is case insensitive, because GitHub labels are typed by hand', () => {
+  assert.equal(waived(['No-Visual-Change']), true);
+  assert.equal(waived(['NO-VISUAL-CHANGE']), true);
+});
+
+test('the waiver does NOT fire without the label', () => {
+  // The always-pass failure mode. If this ever goes green for an unlabelled PR,
+  // the required check has quietly stopped being required for everyone.
+  assert.equal(waived([]), false, 'no labels at all');
+  assert.equal(waived(['bug', 'documentation', 'ci']), false, 'unrelated labels');
+});
+
+test('the waiver needs the WHOLE label, not something that merely contains it', () => {
+  // `includes` on the array is exact membership. A substring match would let
+  // anyone invent `needs-no-visual-change` and walk through the gate.
+  assert.equal(waived(['no-visual-changes']), false, 'trailing s is a different label');
+  assert.equal(waived(['needs-no-visual-change']), false, 'prefixed is a different label');
+  assert.equal(waived(['no-visual-change-please']), false, 'suffixed is a different label');
+});
+
+test('the unfilled template still FAILS the gate', () => {
+  // 17 Sep 2026: the template gained a visible note about the waiver. Visible
+  // text sits outside the HTML comments the gate strips, so it is now the first
+  // thing under `## Evidence`. Prove it changed nothing: an untouched template
+  // must still fail, or opening a PR and attaching nothing would pass.
+  const EVIDENCE = [
+    /!\[[^\]]*\]\([^)]+\)/,
+    /<img\b[^>]*\bsrc\s*=/i,
+    /<video\b/i,
+    /https:\/\/github\.com\/user-attachments\/assets\/[\w-]+/i,
+    /https:\/\/user-images\.githubusercontent\.com\/\S+/i,
+    /https:\/\/\S+\.(png|jpe?g|gif|webp|mp4|mov|webm)\b/i
+  ];
+  const hasEvidence = (t) => EVIDENCE.some((re) => re.test(t));
+  const template = fs.readFileSync(
+    path.resolve(__dirname, '..', '.github/PULL_REQUEST_TEMPLATE.md'), 'utf8'
+  );
+  assert.equal(hasEvidence(section('before', template)), false, 'empty Before is not evidence');
+  assert.equal(hasEvidence(section('after', template)), false, 'empty After is not evidence');
+});
+
+test('the visible waiver note is not itself mistaken for evidence', () => {
+  // The note names the label and talks about "a before and an after". Words are
+  // not evidence; only an image or a video is.
+  const template = fs.readFileSync(
+    path.resolve(__dirname, '..', '.github/PULL_REQUEST_TEMPLATE.md'), 'utf8'
+  );
+  const note = template.split('## Evidence')[1].split('<!--')[0];
+  assert.match(note, /no-visual-change/, 'the note is visible, not inside a comment');
+  assert.doesNotMatch(note, /!\[|<img|<video|https:\/\//, 'the note carries no image or link');
+});