Keep the pinned WordPress corpus current automatically

[sirreal]

Stacked on #284 — retarget to master when that merges. The only new file is .github/workflows/corpus-pin-update.yml; the pin in corpus-diff.yml is untouched here.

What it does

Dependabot can't track WordPress core releases, so WP_CORPUS_TAG would quietly rot on whatever tag it was born with. Weekly (Mondays 05:43 UTC) and on demand, this workflow:

1. Asks https://api.wordpress.org/core/version-check/1.7/ for offers[0].current. That endpoint is canonical and already excludes betas and RCs, unlike a raw tag listing of WordPress/WordPress. The answer must match ^[0-9]+\.[0-9]+(\.[0-9]+)?$ or the job fails — an API hiccup must not become a garbage commit.
2. Reads the current pin out of corpus-diff.yml and compares. It bumps only when the published stable is strictly newer (sort -V), so a deliberate pin ahead of stable is never walked back, and only when the WordPress/WordPress mirror has actually tagged the release, so it can't open a PR whose corpus download would 404.
3. Rewrites the one pin line, then asserts the result: the line reads back as the new version and git diff --numstat is exactly +1/-1. Anything else fails the job.
4. Opens bump-corpus-pin-<version> as a PR. Idempotent: if a PR for that branch already exists in any state — including closed, meaning a human declined the bump — it does nothing.

Why a bump PR is trivial to review

A bump PR changes only the corpus input, never the parser. Its own corpus-diff run therefore parses the new corpus with an identical parser on both sides: 0 hunks by construction. Reviewing one is just checking that the corpus guards (file count, export size) still pass on the new tag. A non-zero diff on a bump PR would mean corpus-diff isn't comparing what it claims to.

Dependency you may have to flip

PR creation with the built-in GITHUB_TOKEN requires Settings → Actions → General → Workflow permissions → "Allow GitHub Actions to create and approve pull requests". Many organizations disable it and the WordPress org may. If it's off, the branch still gets pushed and the "Open the bump PR" step fails with ::error:: naming that setting; the next run force-updates the branch and retries, so it self-heals once the setting is on. The alternative is a PAT with repo scope supplied as GH_TOKEN for that step. This is deliberately not swallowed: a silent no-op is how the corpus ends up three years stale with a green checkmark.

Verification

Can't run cron locally, so each piece was run instead. The step scripts were extracted from the parsed YAML (so what ran is exactly what the workflow contains) and executed against a real copy of corpus-diff.yml:

• Version resolution: Latest WordPress stable: 7.0.4.
• Against this branch's file (pinned 7.0.4): Already pinned to the latest stable; nothing to do → bump=false.
• Against the pre-bump file (pinned 6.8): bump=true current=6.8, rewrite produced exactly - WP_CORPUS_TAG: "6.8" / + WP_CORPUS_TAG: "7.0.4", file length unchanged, no temp file left behind.
• Skip paths, all bump=false: pin equals stable; pin ahead of stable (7.0.4 vs 7.0.1); version not tagged on the mirror yet.
• Fail-loud paths, all non-zero exit: API returns no version; API returns 404; pin line restructured so it can't be read; two pin-shaped lines, where the +2/-2 guard fires instead of committing a double rewrite.
• Full bump path re-run end to end against the 7.0.4 file with a fake mirror tag, to exercise the tag check's pass branch.
• actionlint 1.7.12: clean on both workflows. bash -n: clean on all four step scripts. YAML parses.

🤖 Generated with Claude Code