Commit 3f383fa9ffb for woocommerce
commit 3f383fa9ffb7652ac3b5a5e98a81294e222df5f5
Author: Vlad Olaru <vlad.olaru@automattic.com>
Date: Mon Nov 16 10:49:58 2026 +0200
[ai] Correct performance reviewer rules that contradict core behavior (#70845)
* docs(review): Correct performance reviewer rules that contradict core
Bring the performance review persona and its two guidelines in line
with current WooCommerce and WordPress behavior, as minimal edits to
the existing rules.
The get_items() exemption now excludes the parent of a variation (the
lazy path primes the variation only) and filter-added items. The OR
rule no longer flags an OR the result needs: a known customer ID does
not cover guest orders matched by billing email. The transient guard
includes wp_installing(), matching get_transient(). Feature-flag keys
join the options that may never have been saved. _prime_post_caches()
does not load HPOS orders, dates from WP 3.4, and expects IDs.
On ten adversarial eval fixtures the unmodified rules missed a removed
parent-product prime behind get_items() and flagged a required
customer_id OR billing_email query.
* docs(review): Clarify get_orders() and dead-priming reviewer rules
Review feedback on the performance reviewer corrections pointed at two
places where the new wording was still incomplete.
The persona named WC_Order_Factory::get_orders() as the fix for a
wc_get_order() loop without saying it is not a drop-in replacement. It
returns a list in input order with the input keys dropped, returns a
duplicate ID once, and does not return false for a missing ID: it
throws on post-based order storage and leaves a non-order entry in the
list under HPOS, with or without $skip_invalid. The rule now names
these differences and requires a suggested fix to keep the behavior
the caller relies on.
The dead-priming rules in the persona and the cache priming guideline
called any prime on IDs collected from order get_items() dead. That
contradicted the exceptions added to the get_items() exemption, since
the parent of a variation is collected there and the lazy path does
not prime it. Both rules now say the prime is dead only for IDs that
get_items() already warmed.
* docs(review): Limit the dead-priming rule to default cache flags
The performance persona called a _prime_post_caches() call dead after
any WP_Query that loaded full post objects, on the grounds that the
query already primed the post, meta, and term caches.
That holds only for the default cache flags. WP_Query passes
update_post_meta_cache and update_post_term_cache straight into its
own prime, and skips the prime when cache_results is false. A later
_prime_post_caches() fills the meta and term caches for every ID, so
after such a query it prevents per-item queries. The rule would have
told the reviewer to recommend removing a prime that is needed.
The persona now treats the prime as dead only when the flags are left
at their defaults and marks a prime after a query with a flag set to
false as correct. The cache priming guideline names the three flags in
its confirmation step.
diff --git a/.ai/review/guidelines/perf-cache-option-priming.md b/.ai/review/guidelines/perf-cache-option-priming.md
index 1994949bdff..570384606c9 100644
--- a/.ai/review/guidelines/perf-cache-option-priming.md
+++ b/.ai/review/guidelines/perf-cache-option-priming.md
@@ -18,8 +18,8 @@
- Product collections rendered with images without `ProductUtil::prime_image_caches()`.
- Sequential non-autoloaded `get_option()` calls (use `wp_prime_option_caches`).
- Removing an effective prime.
-- Dead priming: after a full-post `WP_Query`, on order line items, or behind `is_callable` guards.
+- Dead priming: after a full-post `WP_Query`, on line item product IDs that order `get_items()` already warmed, or behind `is_callable` guards.
-**How to confirm:** See where the IDs come from (`'fields' => 'ids'` or full posts). Check whether the options are autoloaded (WC settings API options are). Check transient names are only primed under `! wp_using_ext_object_cache()`.
+**How to confirm:** See where the IDs come from (`'fields' => 'ids'` or full posts) and whether the query turned off `update_post_meta_cache`, `update_post_term_cache` or `cache_results`. Check whether the options are autoloaded (WC settings API options are). Check transient names are only primed under `! wp_using_ext_object_cache() && ! wp_installing()`.
-**Don't flag when:** Autoloaded options. Loads through order `get_items()`. Tests and fixtures.
+**Don't flag when:** Autoloaded options. Loads through order `get_items()`, except the parent of a variation and filter-added items. Tests and fixtures.
diff --git a/.ai/review/guidelines/perf-sql-query-shape.md b/.ai/review/guidelines/perf-sql-query-shape.md
index 52875290298..cd6e64b0450 100644
--- a/.ai/review/guidelines/perf-sql-query-shape.md
+++ b/.ai/review/guidelines/perf-sql-query-shape.md
@@ -12,7 +12,7 @@
- a redundant `wp_posts` join when upstream already enforced type and status;
- `term_relationships` joined without `term_taxonomy_id`;
- per-item queries that could be one GROUP BY;
-- OR across two indexes;
+- OR across two indexes where one branch alone would answer;
- `meta_key IN` crossed with `meta_value IN`;
- posts + postmeta where `wc_product_meta_lookup` / `wc_product_attributes_lookup` (with correct gates) would do;
- MIN/MAX as a full scan.
diff --git a/.ai/review/personas/performance.md b/.ai/review/personas/performance.md
index 99d4531bbaa..d5c3d36c6f0 100644
--- a/.ai/review/personas/performance.md
+++ b/.ai/review/personas/performance.md
@@ -39,9 +39,10 @@ This controls false positives. Follow it strictly.
term_taxonomy_id IN (...))`.
- **N queries in a loop** varying one parameter (status, term, attribute) collapse into one
`GROUP BY` query.
-- **`OR` across two differently indexed columns** forces an index_merge sort_union. When one branch
- is strictly more selective (a resolved `customer_id` vs `billing_email`), evaluate it first in PHP
- and build the `OR` fallback only when it is unavailable.
+- **`OR` across two differently indexed columns** typically runs as an index_merge sort_union. When
+ one branch alone can answer the question, evaluate it first in PHP and build the `OR` only when it
+ cannot. Don't flag an `OR` the result needs: a known `customer_id` does not cover guest orders
+ matched by `billing_email`.
- **`meta_key IN (...) AND meta_value IN (...)`** cross-products keys and values: it matches invalid
pairs and range-scans the `meta_key` index. Split into per-key `(meta_key = X AND meta_value = Y)`
branches. When a postmeta result drives a join into a second fan-out table (order_items →
@@ -70,16 +71,25 @@ This controls false positives. Follow it strictly.
resolves to `get_post()` per raw ID, with no preceding `_prime_post_caches( $ids )` or native
batching argument (e.g. `get_comments( [ 'update_comment_post_cache' => true ] )`), runs per-item
queries instead of two batched ones. Flag the introduction. Flag REMOVAL of effective priming as a
- straight regression.
+ straight regression. `_prime_post_caches()` does not load HPOS orders: for `wc_get_order()` loops
+ the fix is `WC_Order_Factory::get_orders()`. It is not a drop-in replacement: it returns a list in
+ input order (input keys are dropped), returns a duplicate ID once, and does not return `false` for
+ a missing ID (it throws on post-based order storage and leaves a non-order entry in the list under
+ HPOS; `$skip_invalid` fixes neither). A suggested fix must keep the behavior the caller relies on.
- Exempt: product and variation loads reached through order `get_items()`. The order data store's
- batch prime and the lazy `get_items()` path already warm those caches.
+ batch prime and the lazy `get_items()` path already warm those caches. Not exempt: the parent of a
+ variation (the lazy path primes the variation only) and items added through the
+ `woocommerce_order_get_items` filter.
- Priming that is dead or wrong is a finding the other way (and removing it is the fix, not a
finding):
- - after a WP_Query that loaded full post objects (no `fields` argument): it already primed post,
- meta, and term caches, and `_prime_post_caches()` silently intvals its `WP_Post[]` to `1`. A
- `'fields' => 'ids'` query primes nothing, so priming its IDs afterward is CORRECT; don't flag it;
- - on product or variation IDs collected from order `get_items()`
- (`prime_product_post_caches_for_order_items` and the lazy path already primed them);
+ - after a WP_Query that loaded full post objects (no `fields` argument, cache flags left at
+ their defaults): it already primed post, meta, and term caches, and `_prime_post_caches()`
+ expects IDs, not `WP_Post[]`. A `'fields' => 'ids'` query primes nothing, and a query with
+ `update_post_meta_cache`, `update_post_term_cache` or `cache_results` set to `false` leaves
+ that cache cold, so priming those IDs afterward is CORRECT; don't flag it;
+ - on product or variation IDs that order `get_items()` already warmed
+ (`prime_product_post_caches_for_order_items` and the lazy path). Priming the "Not exempt" IDs
+ above is correct, not dead;
- on IDs an object-cache layer (e.g. OrderCache) already resolved; prime only the uncached rest.
- Rendering a product or variation collection with images needs the attachment prime too. For
variations this is two-phase: prime variation posts, then collect `_thumbnail_id` and
@@ -87,7 +97,7 @@ This controls false positives. Follow it strictly.
`Automattic\WooCommerce\Internal\Utilities\ProductUtil::prime_image_caches()` does this (featured
and gallery IDs, dedup, empty guard) and is the preferred form. Only flag when the render path
actually reads attachment posts; code returning raw gallery IDs needs no attachment prime.
-- `is_callable( '_prime_post_caches' )` guards are dead code (WP 4.1+, below WC's minimum). Same for
+- `is_callable( '_prime_post_caches' )` guards are dead code (WP 3.4+, below WC's minimum). Same for
guarding `wp_prime_option_caches` (WP 6.4+).
## Option and transient priming
@@ -97,13 +107,14 @@ This controls false positives. Follow it strictly.
patterns, or keys pulled from a settings or registry structure).
- **Autoload guard** (the false-positive control for this subsection): options saved through the WC
settings API autoload by default (`WC_Admin_Settings::save_fields`, `WC_Settings_API`). Endpoint
- options, feature toggles, and general store settings come from `alloptions` at boot, so a
+ options, settings toggles, and general store settings come from `alloptions` at boot, so a
missing-priming finding on autoloaded, already-saved options is a no-op. DO NOT flag it. Priming
such keys is justified only for options that may never have been saved (e.g. fresh-install email,
- gateway, or shipping `*_settings` loops).
+ gateway, or shipping `*_settings` loops, and `woocommerce_feature_*_enabled` keys).
- Transient-prefixed names (`_transient_*`, `_transient_timeout_*`, `_site_transient_*`) passed to
- `wp_prime_option_caches()` without a `! wp_using_ext_object_cache()` guard: on persistent-object-cache
- sites those rows never exist in `wp_options`, so every call grows the `notoptions` cache for good. A
+ `wp_prime_option_caches()` without a `! wp_using_ext_object_cache() && ! wp_installing()` guard: on
+ persistent-object-cache sites and during installation transients are not read from `wp_options`,
+ so every new name grows the `notoptions` cache. A
mixed list must be SPLIT (regular names primed always, transient names under the guard), never
wrapped whole. Check the guard's direction.