Release prep: BAC v4 docs, metrics refresh + gate, and a BAC test that never ran

[dknauss]

Release prep for the next version, plus one test defect found along the way.

Documentation the BAC v4 work never got

#68 updated the Block Accessibility Checks integration for BAC 4.0 but left no changelog trace, and readme.txt had no unreleased section at all — so the headline change of this release would have shipped invisible on WordPress.org. Recorded in both, along with the docs/current-metrics.md addition from #67.

BAC 4.0 replaced the registration API, so Borges now needs that plugin at 4.0 or later for its four checks to load. On 3.x the function_exists guard makes the integration a silent no-op — invisible to the user — so the requirement is now stated in the readme description, a new FAQ entry, and README.md.

Metrics refreshed and gated

docs/current-metrics.md was last verified 2026-07-05 at 49f623b; four merges had landed since. Every figure re-derived with the command the doc itself documents.

The footprint turned out smaller than recorded, not larger:

Metric	Was	Now
bibliography-builder.php	1,881	1,928
All first-party PHP	1,979	2,026
JS source	8,851	8,802
Release vendor/	~1.0 MB	792 KB
Total installed	~2.1 MB	~1.9 MB
Distributed ZIP	~0.9–1 MB	~461 KB

The ZIP moved enough to be suspicious, so it was checked for completeness before recording — 242 entries, unzip -t clean, all citeproc and CSL payloads present. It is a real reduction, not a short archive.

Nothing caught that drift, so composer verify:metrics (.github/scripts/verify-metrics.sh) now runs in CI. It checks the lines-of-code figures and re-runs the persistence/hook audit that underpins the zero-query runtime claim. It deliberately does not assert the du-based footprint or built-asset byte sizes: du reports allocated blocks and differs between macOS and the Linux runner, and webpack output is only byte-stable for a fixed toolchain. Asserting those would produce failures that say nothing about the repository, so they stay hand-verified and the script says so. Verified in both directions — exit 0 clean, exit 1 on a perturbed figure and on an introduced update_option call.

The BAC test never actually ran

scripts/test-a11y.sh booted Playground with --auto-mount --login and no blueprint, so BAC was never installed. The test that covers the integration detects BAC, skips when absent, and the suite still reported green — in CI too. The integration shipped in #68 with zero end-to-end coverage, which matters because BAC 4.0 silently ignores hooks registered under their pre-4.0 names: every check simply passes.

The assertions were also vacuous. They targeted .ba11y-block-indicator--error / --warning, classes with zero occurrences in v4 (it replaced them with a validation toolbar button). A .not.toBeVisible() on a class that no longer exists cannot fail.

The environment now installs BAC, and assertions read the block-accessibility-checks data store — the interface v4 documents for validation state. Verified non-vacuous: renaming the editor filter back to ba11yc_validate_block makes the test fail. All 5 a11y tests pass, none skipped.

Installing BAC also surfaced a race in the publish helper. BAC registers an error-level post_title_required editor check that holds core's post-saving lock while the title is empty; the helper set the title and saved in the same tick, so the save was rejected. This is not a Borges defect — a plain paragraph post with no bibliography block fails identically, and publishing through the UI works fine. The helper now waits for the lock to lift and verifies the post actually reached publish, instead of returning an auto-draft permalink that 404s later in the test.

Security hardening

PMID records now resolve through wp_safe_remote_get() rather than wp_remote_get(). The request follows up to three redirects, and only the safe variant runs each hop through wp_http_validate_url, which blocks targets on the site's own network. The exposure was narrow — the PMID is validated ^\d{1,8}$ before use and the endpoint host is a fixed constant, so the redirect chain was the only part of the request an upstream change could point somewhere unintended — but the safe variant is the correct default for an outbound call the plugin doesn't fully control.

Done test-first. The PHPUnit bootstrap now records which HTTP helper a call reached for, so the assertion is on the function rather than only the URL. Confirmed the assertion fails against the old call site before the change.

The skip mechanism, not just the skip

The commit above fixes why the BAC test never ran. This fixes how that went unnoticed: the test called test.skip() whenever BAC was absent, and a skip is indistinguishable from a pass on a green run.

It now skips gracefully for local runs without the plugin, but throws when CI is set, naming the blueprint and the script flag to check. Verified by booting Playground with no blueprint and CI=1 — the run goes red with an actionable message instead of quietly reporting success over no coverage.

Risk

Low. Documentation, a metrics refresh, a new CI check, and test-only changes. No plugin runtime code is touched.

Verification

Jest 660 passed, PHPUnit 174 tests / 394 assertions, PHPCS clean, Psalm clean, ESLint clean, a11y suite 5/5 with none skipped, verify-metrics green.

Deliberately not included: no version bump. That is a separate call when you are ready to tag.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.01%. Comparing base (8945eeb) to head (0011288).

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #71   +/-   ##
=======================================
  Coverage   81.01%   81.01%           
=======================================
  Files          43       43           
  Lines        3113     3113           
  Branches      522      522           
=======================================
  Hits         2522     2522           
  Misses        185      185           
  Partials      406      406           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.