From 71018fe16a47703d2ec899af370762e4adcd1087 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 31 Aug 2026 18:37:42 +0000 Subject: [PATCH] docs(check-release-section-coverage): mark the v17 fixture historical, not "actually shipped" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The `REAL_V17_HEADINGS` fixture carried a present-tense docblock — "Kept verbatim so the matcher is judged against text that actually shipped" — while the text it snapshots no longer ships. #13754 (merged 2026-08-31) cascaded the release-page headings: `content/docs/releases/v17.mdx` now reads `## 17.0.0 in detail`, and no page under `content/docs/releases/` carries a body-level h1 any more (0 such lines across the ten pages, counter-checked against 54 `## ` lines in the same files). The gate is green either way and stays green — `headingsNamingMinor` is `^#{1,6}`, level-agnostic by construction, and nothing compares the fixture to the live page. The defect is the claim, not the behaviour: the file already keeps a deliberately historical snapshot beside it (`PRE_10232_V17_HEADINGS`), so a reader diffing either against the live page could not tell which was which. Relabelled to that sibling's existing convention rather than a third one: renamed `REAL_V17_HEADINGS` -> `PRE_13754_V17_HEADINGS` (the identifier is the label a reader meets at the three use sites; the docblock is only visible at the definition), and the docblock now names what changed and when, as `PRE_10232_V17_HEADINGS`'s does. The docblock also carries the reason it must not be re-snapshotted, measured rather than assumed: a re-snapshot would remove the last h1 that reaches the matcher through a whole-page fixture, and would remove it in silence — 17.0 is covered twice over here, so every case in this file stays green with the `# ` demoted to `##`. The matcher's `^#{1,6}` breadth itself is pinned separately by the `'# 16.1.0'` / `'###### 16.1.0'` case, so the fixture is NOT the only h1-bearing input and the docblock does not claim to be. The 17.0 self-test label said the fixture covers 17.0 "via `# 17.0.0 in detail`", which reads as though the h1 were load-bearing there. Measured: 17.0 matches both `## Highlights — 17.0.0` and `# 17.0.0 in detail`. The label now says so, and says the case cannot catch a re-snapshot. No changeset: script-only, publishes nothing from any package — the repo's precedent (15/15 recent commits touching only `scripts/check-*.mjs`) carries none. `skip-changeset` applied on the PR. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01Pk26oZ12t5N1hwGW1m1MgC --- scripts/check-release-section-coverage.mjs | 32 ++++++++++++++++------ 1 file changed, 24 insertions(+), 8 deletions(-) diff --git a/scripts/check-release-section-coverage.mjs b/scripts/check-release-section-coverage.mjs index 23e631182c..48c4ae4b84 100644 --- a/scripts/check-release-section-coverage.mjs +++ b/scripts/check-release-section-coverage.mjs @@ -370,10 +370,25 @@ export function indexCurrencyFindings(major, newestVersion, line) { // ── Self-test ──────────────────────────────────────────────────────────────── /** - * The real v17 page heading set, trimmed to the lines that matter. Kept verbatim - * so the matcher is judged against text that actually shipped. + * The real v17 page heading set as it stood between #10232 and #13754, trimmed to + * the lines that matter. HISTORICAL — a snapshot, like `PRE_10232_V17_HEADINGS` + * below, and no longer the page as it reads today: #13754 (merged 2026-08-31) + * cascaded the release-page headings, so this page's `# 17.0.0 in detail` is now + * `## 17.0.0 in detail` and NO page under `content/docs/releases/` carries a + * body-level h1 any more (measured on the merge commit: 0 such lines across the + * ten pages, against 54 `## ` lines in the same files — so the zero is a reading, + * not a broken query). + * + * Do NOT re-snapshot it from the live page. `headingsNamingMinor` is `^#{1,6}` by + * construction and its breadth is pinned directly by the `'# 16.1.0'` / + * `'###### 16.1.0'` case in the self-test below, which a re-snapshot would not + * touch. What a re-snapshot WOULD remove is the last h1 reaching the matcher + * through a whole-PAGE fixture — and it would remove it in silence: 17.0 is + * covered here twice over (`## Highlights — 17.0.0` matches it too), so every case + * in this file stays green with the `# ` demoted to `##`. Measured, not assumed. + * The ban is written here because nothing mechanical enforces it. */ -const REAL_V17_HEADINGS = [ +const PRE_13754_V17_HEADINGS = [ '## Highlights — 17.0.0', '## Highlights — 17.1.0', '# 17.0.0 in detail', @@ -544,13 +559,14 @@ export function selfTest() { .some((f) => f.includes('NO heading on this page names the 17.1 series')), ); expect( - 'coverage/GREEN — the real v17 headings AFTER #10232 cover 17.1 via "## Highlights — 17.1.0". A ' - + 'check that reds on everything is not a check', - coverageFindings(17, 1, 'v17.mdx', REAL_V17_HEADINGS).length === 0, + 'coverage/GREEN — the real v17 headings between #10232 and #13754 cover 17.1 via "## Highlights ' + + '— 17.1.0". A check that reds on everything is not a check', + coverageFindings(17, 1, 'v17.mdx', PRE_13754_V17_HEADINGS).length === 0, ); expect( - 'coverage/GREEN — and they cover 17.0 via "# 17.0.0 in detail"', - coverageFindings(17, 0, 'v17.mdx', REAL_V17_HEADINGS).length === 0, + 'coverage/GREEN — and they cover 17.0 TWICE OVER, via "## Highlights — 17.0.0" and "# 17.0.0 in ' + + 'detail". Neither is load-bearing alone, so this case cannot catch a re-snapshot of the h1', + coverageFindings(17, 0, 'v17.mdx', PRE_13754_V17_HEADINGS).length === 0, ); expect( 'coverage — TRAP 1: `## What\'s new in 11.10.0` does NOT cover minor 11.1. Major 11 published '