Address corpus-diff review notes

- Name the comparison for what it is: on pull_request HEAD is the PR merged
  into the base branch, so the merge base resolves to the base branch tip.
  Rename the step, explain it in the workflow, and say the same in the
  README, including how to reproduce that comparison locally.
- Drop the unreachable is_array() guard in tools/export-corpus.php:
  get_wp_files() returns a WP_Error on failure, which does not exist under
  plain PHP, so that path fatals with a non-zero exit before it can return.
- Add a concurrency group so a new push cancels the in-flight run for the
  same PR.

Author: sirreal

.github/workflows/corpus-diff.yml

@@ -1,7 +1,8 @@
-# Parses a pinned corpus of WordPress core source with the parser at the PR's
-# merge base and at its head, normalizes both JSON outputs with prep-diff.php,
-# and diffs them. Anything in the diff is a behavior change this PR makes:
-# every hunk must be either intended (and explained in the PR) or a regression.
+# Parses a pinned corpus of WordPress core source with the parser at the base
+# branch and with the PR merged into it, normalizes both JSON outputs with
+# prep-diff.php, and diffs them. Anything in the diff is a behavior change this
+# PR makes: every hunk must be either intended (and explained in the PR) or a
+# regression.
 #
 # Policy decisions, deliberate:
 # - The corpus is pinned to one WordPress tag so diffs are reproducible.
@@ -19,6 +20,11 @@ name: Corpus Diff
 on:
   pull_request:
 
+# A new push to the PR supersedes any run still in flight for it.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
 jobs:
   corpus-diff:
     name: WordPress corpus regeneration diff
@@ -65,7 +71,12 @@ jobs:
           echo "Corpus PHP files: ${count}"
           [ "$count" -ge 500 ]
 
-      - name: Check out merge base
+      # On pull_request, HEAD is the PR merged into the base branch, so its
+      # merge base with the base branch is the base branch tip, not the commit
+      # the PR branched from. That is the intended comparison: base as it is
+      # now against base plus exactly this PR, with no hunks from other work
+      # that landed since the branch point.
+      - name: Check out base
         run: git worktree add base "$(git merge-base "origin/${{ github.base_ref }}" HEAD)"
 
       - name: Install Composer dependencies (head)

README.md

@@ -53,7 +53,7 @@ wp parser create /path/to/source/code --user=<id|login>
 
 ## Corpus diff
 
-Unit tests do not cover every shape of real-world documentation, so changes to the parser are also checked against a corpus of WordPress core source. The same corpus is parsed with the parser at two refs — the merge base of a pull request and its head — both JSON outputs are normalized with `prep-diff.php`, and the two are diffed. Everything in that diff is a behavior change the pull request makes: every hunk must be either intended and explained, or it is a regression.
+Unit tests do not cover every shape of real-world documentation, so changes to the parser are also checked against a corpus of WordPress core source. The same corpus is parsed with the parser at two refs — the base branch and the pull request merged into it — both JSON outputs are normalized with `prep-diff.php`, and the two are diffed. Everything in that diff is a behavior change the pull request makes: every hunk must be either intended and explained, or it is a regression.
 
 `.github/workflows/corpus-diff.yml` runs this on every pull request. The corpus is `wp-includes` from a pinned WordPress tag (`WP_CORPUS_TAG` in the workflow), so diffs are reproducible. The job is non-blocking: it uploads the diff as a `corpus.diff` artifact and reports the hunk count in the job summary. The head checkout's `tools/export-corpus.php` and `prep-diff.php` drive both sides, so tooling changes never masquerade as parser changes; when `prep-diff.php` itself changes, its effect on normalization shows up in the diff and is reviewed like any other change.
 
@@ -72,6 +72,8 @@ composer --working-dir=base install
 composer install
 ```
 
+On a branch this compares against the commit the branch left `master` at. CI runs on the pull request merged into `master`, so it compares against the `master` tip; merge `master` into the branch first to get the same comparison.
+
 Export both sides over the same corpus, normalize, and diff. `export-corpus.php` takes the parser root and the corpus directory, and writes JSON to stdout:
 
 ```bash

tools/export-corpus.php

@@ -38,11 +38,9 @@
 
 require $parser_root . '/vendor/autoload.php';
 
+// get_wp_files() reports an unreadable subdirectory with a WP_Error, a class
+// that only exists inside WordPress: under plain PHP that path is a fatal
+// error with a non-zero exit, so there is no return value to check here.
 $files = \WP_Parser\get_wp_files( $corpus_dir );
 
-if ( ! is_array( $files ) ) {
-	fwrite( STDERR, 'Could not list the PHP files in ' . $corpus_dir . '.' . PHP_EOL );
-	exit( 1 );
-}
-
 echo json_encode( \WP_Parser\parse_files( $files, $corpus_dir ), JSON_PRETTY_PRINT ), PHP_EOL;