Add github action to verify compat flags have docs

[jasnell]

No description provided.

[ask-bonk]

I'm Bonk, and I've done a quick review of your PR.

This PR adds a GitHub Action that verifies new compat flags with default-on dates have corresponding documentation in cloudflare-docs. The Python script parses compatibility-date.capnp, diffs against the base branch, and uses gh CLI to check for docs on the production branch or in approved open PRs. A test flag (justATestThisWontBeLanded) is included to exercise the check.

Findings (highest severity first):

1. [HIGH] github.token lacks cross-repo read access — The default GITHUB_TOKEN is scoped to cloudflare/workerd. Calls to gh api repos/cloudflare/cloudflare-docs/contents/... and gh search prs --repo cloudflare/cloudflare-docs will likely 404 or 403 because the token has no read permission on cloudflare/cloudflare-docs. You'll need a PAT or a GitHub App token with cross-repo contents:read scope. If this already works due to an org-level policy, a comment explaining that would be helpful.

2. [MED] merge_group event sets GITHUB_BASE_SHA to empty string — For merge_group events, github.event.pull_request.base.sha is not populated and will evaluate to an empty string. The script's resolve_base_sha() correctly falls back through GITHUB_EVENT_PATH and git merge-base, but passing an empty-string env var means the first branch (os.environ.get("GITHUB_BASE_SHA")) returns "" which is truthy in Python, so git show :src/workerd/io/compatibility-date.capnp runs (no commit ref) and the fallback never triggers.

3. [MED] Script collects experimental status but never uses it — parse_compat_flags records "experimental": is_experimental for each flag, but this value is never checked. Should experimental flags be exempt from the documentation requirement? If so, the check should skip them; if not, the field should be removed to avoid confusion.

4. [LOW] $compatEnableAllDates is not detected — The script checks for $compatEnableDate and $impliedByAfterDate as triggers for requiring docs, but $compatEnableAllDates (which makes a flag default-on for all dates) is not handled. Currently only one flag uses it (r2PublicBetaApi), so this is low-impact, but worth noting for completeness.

5. [LOW] Missing permissions block in workflow — CodeQL already flagged this. Adding an explicit permissions block (e.g. contents: read) is best practice for least-privilege.

---

This review was generated by an AI assistant and may contain inaccuracies.

[ask-bonk]

I'm Bonk, and I've done a quick review of your PR.

Review posted on PR #6518 with 5 findings and inline comments with suggestions:

1. [HIGH] github.token lacks cross-repo read access — the default GITHUB_TOKEN can't query cloudflare/cloudflare-docs unless there's an org-level policy.
2. [MED] merge_group events pass empty string as GITHUB_BASE_SHA, which is truthy in Python, causing resolve_base_sha() to skip its fallback logic and git show to read from the index instead of the actual base.
3. [MED] is_experimental is collected in parse_compat_flags but never used — unclear whether experimental flags should be exempt from the docs requirement.
4. [LOW] $compatEnableAllDates is not detected as a trigger for requiring documentation.
5. [LOW] Missing permissions block in the workflow (also flagged by CodeQL).

github run

[npaun]

See also #5839

[jasnell]

I thought the idea sounded familiar ;-) ... I'm good with either one landing.

[harrishancock]

Looks reasonable to me, though Bonk seems to have some smart comments.