refactor(features): resolve legacy licenses once per feature collection

Previously hydrate_feature() called legacy_repository->find() once per
catalog feature, which dispatched the lw-harbor/legacy_licenses filter on
every iteration. Beyond the wasted work that hurt scaling with catalog
size, it widened the surface for re-entrant filter callbacks: any
callback consulting Harbor itself (e.g. Solid Backups via
lw_harbor_is_feature_available) compounded that cost per feature.

Hoist the lookup to __invoke(), build a slug => Legacy_License map once,
and pass each feature's match (or null) into hydrate_feature(). Filter
dispatches drop from O(features) to O(1) per resolution, and any
re-entry guard in License_Repository now only has to cover a single
dispatch window.

Existing reflection-based hydrate_feature() tests in Feature_RepositoryTest
pass the new fifth argument as null since they exercise paths that don't
touch the legacy grant.

Author: d4mation

src/Harbor/Features/Resolve_Feature_Collection.php

@@ -10,6 +10,7 @@
 use LiquidWeb\Harbor\Features\Types\Plugin;
 use LiquidWeb\Harbor\Features\Types\Service;
 use LiquidWeb\Harbor\Features\Types\Theme;
+use LiquidWeb\Harbor\Legacy\Legacy_License;
 use LiquidWeb\Harbor\Legacy\License_Repository as Legacy_License_Repository;
 use LiquidWeb\Harbor\Licensing\Enums\Validation_Status;
 use LiquidWeb\Harbor\Licensing\Error_Code as Licensing_Error_Code;
@@ -158,7 +159,8 @@ public function __invoke() {
 			}
 		}
 
-		$collection = new Feature_Collection();
+		$collection      = new Feature_Collection();
+		$legacy_licenses = $this->build_legacy_license_map();
 
 		foreach ( $catalog as $product ) {
 			if ( ! $product instanceof Product_Catalog ) {
@@ -169,7 +171,8 @@ public function __invoke() {
 			$license_tier_rank = $this->resolve_license_tier_rank( $product, $products );
 
 			foreach ( $product->get_features() as $catalog_feature ) {
-				$feature = $this->hydrate_feature( $catalog_feature, $product, $capabilities, $license_tier_rank );
+				$legacy_license = $legacy_licenses[ $catalog_feature->get_slug() ] ?? null;
+				$feature        = $this->hydrate_feature( $catalog_feature, $product, $capabilities, $license_tier_rank, $legacy_license );
 
 				if ( is_wp_error( $feature ) ) {
 					static::debug_log( $feature->get_error_message() );
@@ -183,6 +186,28 @@ public function __invoke() {
 		return $collection;
 	}
 
+	/**
+	 * Builds a `slug => Legacy_License` map from the legacy repository.
+	 *
+	 * Resolved once per `__invoke()` call so the `lw-harbor/legacy_licenses`
+	 * filter dispatches once per resolution rather than once per catalog
+	 * feature. This also narrows the surface for filter re-entry: only one
+	 * dispatch can be in-flight while hydrate_feature() iterates.
+	 *
+	 * @since TBD
+	 *
+	 * @return array<string, Legacy_License>
+	 */
+	private function build_legacy_license_map(): array {
+		$map = [];
+
+		foreach ( $this->legacy_repository->all() as $license ) {
+			$map[ $license->slug ] = $license;
+		}
+
+		return $map;
+	}
+
 	/**
 	 * Resolves the capabilities granted by the license for a given product.
 	 *
@@ -271,18 +296,20 @@ private function is_license_invalid( ?string $validation_status ): bool {
 	 *
 	 * @since 1.0.0
 	 *
-	 * @param Catalog_Feature $catalog_feature   The catalog feature entry.
-	 * @param Product_Catalog $product           The parent catalog product.
-	 * @param string[]|null   $capabilities      The license capabilities, or null if unlicensed.
-	 * @param int             $license_tier_rank The user's licensed tier rank, or -1 if unlicensed.
+	 * @param Catalog_Feature     $catalog_feature   The catalog feature entry.
+	 * @param Product_Catalog     $product           The parent catalog product.
+	 * @param string[]|null       $capabilities      The license capabilities, or null if unlicensed.
+	 * @param int                 $license_tier_rank The user's licensed tier rank, or -1 if unlicensed.
+	 * @param Legacy_License|null $legacy_license    The legacy license entry whose slug matches this feature, or null if none.
 	 *
 	 * @return Feature|WP_Error The hydrated feature, or WP_Error for unknown types.
 	 */
 	private function hydrate_feature(
 		Catalog_Feature $catalog_feature,
 		Product_Catalog $product,
 		?array $capabilities,
-		int $license_tier_rank
+		int $license_tier_rank,
+		?Legacy_License $legacy_license
 	) {
 		$catalog_kind = $catalog_feature->get_kind();
 		$class        = $this->type_map[ $catalog_kind ] ?? null;
@@ -301,7 +328,6 @@ private function hydrate_feature(
 		$minimum_tier = $product->get_tier_by_slug( $catalog_feature->get_minimum_tier() );
 		$minimum_rank = $minimum_tier !== null ? $minimum_tier->get_rank() : PHP_INT_MAX;
 
-		$legacy_license   = $this->legacy_repository->find( $catalog_feature->get_slug() );
 		$has_legacy_grant = $legacy_license !== null
 			&& $legacy_license->is_active
 			&& $legacy_license->key !== ''

tests/wpunit/Features/Feature_RepositoryTest.php

@@ -342,7 +342,7 @@ public function test_hydrate_feature_returns_wp_error_for_unknown_type(): void {
 		$method = new ReflectionMethod( Resolve_Feature_Collection::class, 'hydrate_feature' );
 		$method->setAccessible( true ); // Required for PHP < 8.1.
 
-		$result = $method->invoke( $resolver, $catalog_feature, $product, null, -1 );
+		$result = $method->invoke( $resolver, $catalog_feature, $product, null, -1, null );
 
 		$this->assertInstanceOf( WP_Error::class, $result );
 		$this->assertSame( Error_Code::UNKNOWN_FEATURE_TYPE, $result->get_error_code() );
@@ -388,7 +388,7 @@ public function test_hydrate_feature_returns_feature_for_known_type(): void {
 		$method = new ReflectionMethod( Resolve_Feature_Collection::class, 'hydrate_feature' );
 		$method->setAccessible( true ); // Required for PHP < 8.1.
 
-		$result = $method->invoke( $resolver, $catalog_feature, $product, [ 'test-plugin' ], 1 );
+		$result = $method->invoke( $resolver, $catalog_feature, $product, [ 'test-plugin' ], 1, null );
 
 		$this->assertInstanceOf( Plugin::class, $result );
 		$this->assertSame( 'test-plugin', $result->get_slug() );
@@ -445,7 +445,7 @@ public function test_free_tier_feature_available_for_licensed_user_regardless_of
 
 		// Omit the free feature from capabilities, simulating a Commerce Portal that only
 		// lists paid features. The resolver must still mark it available and in tier.
-		$result = $method->invoke( $resolver, $catalog_feature, $product, [ 'some-paid-feature' ], 1 );
+		$result = $method->invoke( $resolver, $catalog_feature, $product, [ 'some-paid-feature' ], 1, null );
 
 		$this->assertInstanceOf( Plugin::class, $result );
 		$this->assertTrue( $result->is_available(), 'Free-tier feature must be available regardless of capabilities.' );

tests/wpunit/Features/Resolve_Feature_CollectionTest.php

@@ -414,4 +414,47 @@ public function test_resolver_without_legacy_repo_argument_uses_filter_backed_de
 
 		$this->assert_resolved_feature_flags( $resolver, 'kad-blocks-pro', true, true );
 	}
+
+	/**
+	 * Tests that resolving a catalog with multiple features dispatches the
+	 * `lw-harbor/legacy_licenses` filter exactly once.
+	 *
+	 * Before the legacy lookup was hoisted out of hydrate_feature(), the filter
+	 * fired once per catalog feature. That meant every consumer hooked to the
+	 * filter ran N times on every resolution, and any callback that consults
+	 * Harbor itself (e.g. Solid Backups via lw_harbor_is_feature_available)
+	 * compounded that cost N-fold. Hoisting the lookup to once per __invoke()
+	 * is what this test pins down.
+	 *
+	 * @return void
+	 */
+	public function test_legacy_filter_dispatches_once_per_resolution_not_per_feature(): void {
+		$dispatch_count = 0;
+
+		add_filter(
+			'lw-harbor/legacy_licenses',
+			static function ( array $licenses ) use ( &$dispatch_count ) {
+				++$dispatch_count;
+
+				return $licenses;
+			}
+		);
+
+		$resolver = $this->make_resolver( $this->make_catalog(), new Product_Collection() );
+
+		$collection = ( $resolver )();
+
+		$this->assertInstanceOf( Feature_Collection::class, $collection );
+		$this->assertGreaterThan(
+			1,
+			$collection->count(),
+			'Sanity: the fixture catalog must contain more than one feature for this test to be meaningful.'
+		);
+		$this->assertSame(
+			1,
+			$dispatch_count,
+			'The lw-harbor/legacy_licenses filter must fire exactly once per resolution, '
+			. 'not once per catalog feature.'
+		);
+	}
 }