[aryanjasala]

What this PR does

The workflow half of #36. With coverage: true, PHPUnit and Jest measure coverage, wp-tooling coverage-gate fails the job when too few of the lines the PR changed are covered, the HTML report is uploaded as an artifact, and an opt-in workflow posts the summary as a comment on the PR. With coverage off, every job runs the same steps as before.

Closes

Closes #36

Changes

• ci-test-php.yml and ci-test-js.yml gain coverage (default false), coverage-threshold (80), coverage-artifact-name, base-ref and wp-tooling-ref. With coverage on:

  • the checkout keeps full history for the merge-base diff;
  • PHPUnit writes coverage/clover.xml and coverage/html (Xdebug inside wp-env, PCOV when standalone); Jest writes coverage/lcov.info and its HTML report to an absolute --coverageDirectory, because Jest resolves it against a rootDir the starters move;
  • coverage-gate runs with --output github: step outputs, annotations, and a per-file table of missed lines in the job summary, labelled with the job (PHPUnit, PHP 8.3, WP 6.8, plugins/acme);
  • the coverage/ directory, including that table as summary.md, is uploaded even when the gate or the tests fail, which is when it is wanted most (14-day retention).

• wp-env and Xdebug. wp-env bakes Xdebug into the image it builds, and any later wp-env start without --xdebug rebuilds it without. The starters run PHPUnit in a separate .wp-env.tests.json environment that their pretest:php hook starts. So with coverage on, the workflow starts that environment itself with --xdebug=coverage and the default command becomes npm run --ignore-scripts test:php --, which stops the hook from restarting it. Stop wp-env stops the same config.

• wp-ci.yml gains coverage and coverage-threshold. It measures test-js and only the first test-php matrix cell (several cells would multiply the cost and could disagree), names the artifacts per unit (coverage-php, coverage-js, suffixed with the directory in a monorepo), forwards base-ref and wp-tooling-ref, and fails fast in validate-inputs when test-php-exclude drops that first cell.

• New ci-coverage-comment.yml posts every summary.md of the run as one PR comment and updates it on later runs (or says nothing was measured). Fork PRs get a notice instead, since their token is read-only, and a refused comment (a Dependabot PR, say) is a warning, not a failure.

• Examples for all three workflows and a README Coverage section.

• Review fixes (543bbc6):

  • the comment's marker carries a hash of the caller's workflow name, and only a github-actions[bot] comment is ever edited, so a contributor's comment that quotes the marker is left alone and two caller workflows in one repository keep separate comments (checked against a stubbed gh: it edits the bot's own comment, and posts a new one when only a human's or another workflow's exists);
  • standalone runs set pcov.directory to the unit, because PCOV otherwise records only src/, lib/ or app/ when one exists and the starters keep PHP in inc/ (not yet run on a real runner);
  • base-ref and wp-tooling-ref in wp-ci.yml say they also drive the coverage gate, and that a branch is written origin/<branch>.

How I verified

$ actionlint .github/workflows/*.yml examples/*.yml
$ bin/check-workflows.sh
Workflow/example contract check passed.
$ pipx run yamllint .   # only the existing warning on main

• validate-inputs with coverage on: a plain matrix passes and emits coverage-php-artifact=coverage-php; test-php-exclude dropping the first cell ({"php":"8.2","wp":"6.7"} or just {"php":"8.2"}) fails with the error; working-dir: themes/acme gives coverage-php-themes-acme.
• coverage-gate from @rtcamp/wp-tooling 2.0.0 on a scratch repo, to confirm the summary format the label rewrite expects (### Changed-line coverage as the first line).
• The comment script with a stubbed gh on all four paths: new comment, update of an existing comment to "No coverage was measured", no summaries and no earlier comment (no call), fork PR (notice, no call).

Not done yet, and needed before merge: the end-to-end check from #36 on a real consumer (a covered change passes, a later commit that adds an untested branch fails and names the lines, a new untested file shows at 0%, then the fix passes). Docker was unavailable when I built this, so the wp-env and PCOV paths have only been linted, not run.

Acceptance criteria

Runtime behavior

• Coverage off: every job runs the same steps as before
• Coverage on a push event: report produced, gate prints a notice instead of failing
• One gate per unit: test-js and the first test-php cell only
• [ci-test] Enforce changed-line test coverage on every pull request commit #36's four-commit check on a consumer branch
• Comment appears on a real PR

Code quality

• Lint: zero errors
• Static analysis: zero errors (zizmor: two new adhoc-packages notes for the wp-tooling install, the same pattern ci-detect-changes.yml already uses)
• Tests pass (step scripts and the comment script against the cases above)

Housekeeping

• No CHANGELOG.md edit: release-please writes it from the PR title
• examples/<workflow>.yml added or updated to match any input change
• yamllint, actionlint and bin/check-workflows.sh pass locally

Reviewer notes

• Merge Dependabot feat(deps): bump actions/setup-node from 4.1.0 to 7.1.0 #54 (setup-node 7) before this PR. The new setup-node step in ci-test-php.yml sets package-manager-cache, which setup-node 4.1.0 doesn't know, so until feat(deps): bump actions/setup-node from 4.1.0 to 7.1.0 #54 every Test PHP run logs an "Unexpected input" warning. feat(deps): bump actions/setup-node from 4.1.0 to 7.1.0 #54 also conflicts with this file and needs a rebase either way.

• Why the comment is a separate workflow. A job that asks for pull-requests: write fails validation for every caller that does not grant it, even when the job would be skipped. Putting it inside wp-ci.yml would break every @v1 caller.

• --ignore-scripts skips the consumer's pretest:php. That is deliberate, but any project that does more than start wp-env in that hook loses it under coverage. A custom test-command must forward its arguments to PHPUnit.

• Consumer side: theme-elementary's test:php uses composer exec 'phpunit ...', which cannot take the appended flags. The starter PRs that turn coverage on fix that (-- vendor/bin/phpunit). New files only count once phpunit.xml.dist has processUncoveredFiles (or a <source> include) and Jest has collectCoverageFrom.

• Action pins: the new upload and download steps use main's pins (upload-artifact v4.6.2, download-artifact v4.3.0). The Dependabot majors (feat(deps): bump the github-actions group across 1 directory with 2 updates #53 to feat(deps): bump actions/cache from 4.2.0 to 6.1.0 #59) move them with everything else; nothing here needs v7 or v8.

• Out of scope, as [ci-test] Enforce changed-line test coverage on every pull request commit #36 says: Codecov or any upload, whole-project thresholds, coverage on push events.