Debug Helper: predict package provenance per WP/Gutenberg version

[retrofox]

Proposed changes

The Package Provenance module shows, on the current admin screen, which runtime serves each wp-* package: WordPress core, the Gutenberg plugin, or Jetpack's wp-build-polyfills. Reading it across the WordPress × Gutenberg matrix still means switching the site by hand, one cell at a time.

This PR adds a WP-CLI command that computes the same table for versions the site is not running, and goes one step further than the panel: it cross-checks the module names the site's bundles opt in with (__dangerousOptInToUnstableAPIsOnlyForCoreModules( …, '@wordpress/x' )) against the allowlist of the wp-private-apis copy that would win in that cell. A name outside that allowlist is the load-time You tried to opt-in to unstable APIs as module "…" error, so the command predicts that failure without loading a page.

wp jetpack-debug provenance predict --wp=7.0.4,7.1 --gutenberg=off,23.8.0
wp jetpack-debug provenance predict --wp=7.1 --gutenberg=/tmp/gutenberg.zip --format=json

How it works:

• Core inventory (classic scripts in wp-includes/js/dist, script modules, and the compiled private-apis allowlist) is read from disk for the running version, and from the WordPress/WordPress mirror on GitHub for any other release or trunk.
• Gutenberg inventory comes from off, active (the installed plugin), a release version (zip downloaded from GitHub Releases) or a path to a plugin zip or directory. Both build/scripts + build/modules and the older build/build-module layouts are understood; zips are read without extracting.
• The polyfill inventory comes from the wp-build-polyfills copy the autoloader loaded, and the force/fallback decision from the new WP_Build_Polyfills::predict_registration(), so the CLI and the runtime share one rule table.
• Bundles are found by scanning the active plugins (and mu-plugins) for the opt-in call; node_modules, vendor, tests and src are skipped.

The command exits with status 1 when any cell rejects an opt-in, so it can gate a script. --polyfills=<dir> and --plugins=<dirs> point it at another checkout's builds, so a branch that bumps the bundled packages can be evaluated from any site that mounts it (this is how the #51303 build was checked: its Premium Analytics bundles are the ones a Gutenberg 23.9 private-apis rejects).

wp-build-polyfills gets a public predict_registration( $wp_version, $gutenberg_version, $wp_version_threshold ) returning force | fallback per handle and module; register_scripts() now reads the same policy table instead of inlining it. No behavior change.

Related product discussion/links

• Update Bundled @wordpress/* monorepo #51303 (bundled @wordpress/* update) and the manual matrix that motivated this.
• DataViews: Add a lint rule preventing private API imports WordPress/gutenberg#81478 removes @wordpress/dataviews from the private-apis allowlist in Gutenberg 23.9, the case this command was built to predict.

Does this pull request change what data or activity we track or use?

No.

Testing instructions

• Enable the Package Provenance module in Jetpack Debug Tools (or wp option update jetpack_debug_helper_active_modules '["package-provenance"]' --format=json).
• Run wp jetpack-debug provenance predict with no arguments: it evaluates the running WordPress without Gutenberg and should match what the admin-bar panel shows on a Jetpack dashboard screen.
• Run wp jetpack-debug provenance predict --wp=7.0.4,7.1 --gutenberg=off,23.8.0 and check the four cells against the rules in class-wp-build-polyfills.php: on 7.0.4 without Gutenberg, wp-private-apis and wp-rich-text are polyfill; with 23.8.0 they are gutenberg; on 7.1 they are core.
• Run it against a Gutenberg trunk zip built after DataViews: Add a lint rule preventing private API imports WordPress/gutenberg#81478 (--gutenberg=/path/to/gutenberg.zip): every bundle that inlines DataViews 17.x/18.0 is listed as a rejected @wordpress/dataviews opt-in and the command exits 1.
• jp test php plugins/debug-helper and jp test php packages/wp-build-polyfills.

Sample run on a docker site (WP 7.1) with the branch build, against a Gutenberg trunk build from after WordPress/gutenberg#81478:

$ wp jetpack-debug provenance predict --wp=7.0.4,7.1 --gutenberg=off,/tmp/gutenberg.zip

== WP 7.0.4 · Gutenberg inactive ==
package                       type     provider  reason
wp-notices                    classic  core      core registers it
wp-private-apis               classic  polyfill  forced: WP too old and no Gutenberg new enough
wp-rich-text                  classic  polyfill  forced: WP too old and no Gutenberg new enough
wp-theme                      classic  core      core registers it
wp-views                      classic  polyfill  nobody else ships it
@wordpress/boot               module   core      core registers it
@wordpress/route              module   core      core registers it
@wordpress/a11y               module   core      core registers it
@wordpress/widget-primitives  module   polyfill  nobody else ships it
private-apis served by polyfill (allowlist: 44 modules)

== WP 7.1 · Gutenberg 23.9.0-dev ==
package                       type     provider   reason
wp-notices                    classic  gutenberg  Gutenberg registers it
wp-private-apis               classic  gutenberg  Gutenberg registers it
…
private-apis served by gutenberg (allowlist: 42 modules)
Warning: opt-in rejected: @wordpress/dataviews (jetpack/jetpack_vendor/automattic/jetpack-forms/dist/dashboard/jetpack-forms-dashboard.js)
$ echo $?
1

[github-actions]

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

• To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack or WordPress.com Site Helper), and enable the update/debug-helper-provenance-predict branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack update/debug-helper-provenance-predict

bin/jetpack-downloader test jetpack-mu-wpcom-plugin update/debug-helper-provenance-predict

Interested in more tips and information?

• In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
• Read more about our development workflow here: PCYsg-eg0-p2
• Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

[github-actions]

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

• ✅ Include a description of your PR changes.
  
• ✅ Add a "[Status]" label (In Progress, Needs Review, ...).
  
• ✅ Add testing instructions.
  
• ✅ Specify whether this PR includes any changes to data or privacy.
  
• ✅ Add changelog entries to affected projects
  

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

---

Follow this PR Review Process:

1. Ensure all required checks appearing at the bottom of this PR are passing.
2. Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
3. You can use GitHub's Reviewers functionality to request a review.
4. When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

---

Debug Helper plugin:

No scheduled milestone found for this plugin.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

[jp-launch-control]

Code Coverage Summary

Coverage changed in 1 file.

File	Coverage	Δ%	Δ Uncovered
projects/packages/wp-build-polyfills/src/class-wp-build-polyfills.php	122/131 (93.13%)	0.51%	0 💚

28 files are newly checked for coverage. Only the first 5 are listed here.

File	Coverage
projects/plugins/debug-helper/modules/class-autoloader-debug-helper.php	0/163 (0.00%) 💔
projects/plugins/debug-helper/modules/class-broken-token.php	0/322 (0.00%) 💔
projects/plugins/debug-helper/modules/class-cookie-state.php	0/97 (0.00%) 💔
projects/plugins/debug-helper/modules/class-idc-simulator.php	0/247 (0.00%) 💔
projects/plugins/debug-helper/modules/class-jetpack-sync-debug-helper.php	0/59 (0.00%) 💔

Full summary · PHP report · JS report

_{If appropriate, add one of these labels to override the failing coverage check: Covered by non-unit tests Use to ignore the Code coverage requirement check when E2Es or other non-unit tests cover the code Coverage tests to be added later Use to ignore the Code coverage requirement check when tests will be added in a follow-up PR I don't care about code coverage for this PR Use this label to ignore the check for insufficient code coveage.}

[simison]

Warning: opt-in rejected: @wordpress/dataviews (jetpack/jetpack_vendor/automattic/jetpack-forms/dist/dashboard/jetpack-forms-dashboard.js)

Could something like this fail in CI as an early alert?