fix(sharding): improve PHPStan type annotations and typings

- Add precise array shapes for health, queue, and cleanup methods
- Fix nullable and optional keys in health check results
- Replace null coalescing with explicit empty string in rollbackQuery
- Add explicit type checks to prevent mixed types
- Correct test imports for PHPStan compliance

Author: donhardman

src/Plugin/Sharding/CleanupManager.php

@@ -18,7 +18,7 @@ public function __construct(
 
 	/**
 	 * Comprehensive cleanup of all orphaned resources
-	 * @return array Cleanup results
+	 * @return array{timestamp: int, actions_taken: array<string>, resources_cleaned: int, errors: array<string>} Cleanup results
 	 */
 	public function performFullCleanup(): array {
 		$results = [
@@ -58,7 +58,7 @@ public function performFullCleanup(): array {
 
 	/**
 	 * Find and clean up orphaned temporary clusters
-	 * @return array Cleanup results
+	 * @return array{cleaned_count: int, errors: array<string>} Cleanup results
 	 */
 	public function cleanupOrphanedTemporaryClusters(): array {
 		$results = ['cleaned_count' => 0, 'errors' => []];
@@ -71,7 +71,7 @@ public function cleanupOrphanedTemporaryClusters(): array {
 			$clusters = $clusterData[0]['data'] ?? [];
 
 			foreach ($clusters as $cluster) {
-				$clusterName = $cluster['cluster'] ?? '';
+				$clusterName = $cluster['cluster'];
 
 				// Check if it's a temporary cluster (starts with temp_move_)
 				if (strpos($clusterName, 'temp_move_') !== 0) {
@@ -100,7 +100,7 @@ public function cleanupOrphanedTemporaryClusters(): array {
 
 	/**
 	 * Clean up failed operation groups from queue
-	 * @return array Cleanup results
+	 * @return array{cleaned_count: int, errors: array<string>} Cleanup results
 	 */
 	public function cleanupFailedOperationGroups(): array {
 		$results = ['cleaned_count' => 0, 'errors' => []];
@@ -158,7 +158,7 @@ public function cleanupFailedOperationGroups(): array {
 
 	/**
 	 * Clean up expired queue items (older than 7 days)
-	 * @return array Cleanup results
+	 * @return array{cleaned_count: int, errors: array<string>} Cleanup results
 	 */
 	public function cleanupExpiredQueueItems(): array {
 		$results = ['cleaned_count' => 0, 'errors' => []];
@@ -203,7 +203,7 @@ public function cleanupExpiredQueueItems(): array {
 
 	/**
 	 * Clean up stale state entries
-	 * @return array Cleanup results
+	 * @return array{cleaned_count: int, errors: array<string>} Cleanup results
 	 */
 	public function cleanupStaleStateEntries(): array {
 		$results = ['cleaned_count' => 0, 'errors' => []];

src/Plugin/Sharding/Cluster.php

@@ -109,7 +109,7 @@ protected function runQuery(
 		?string $operationGroup = null
 	): int {
 		if ($queue) {
-			$queueId = $queue->add($this->nodeId, $query, $rollbackQuery, $operationGroup);
+			$queueId = $queue->add($this->nodeId, $query, $rollbackQuery ?? '', $operationGroup);
 		} else {
 			$this->client->sendRequest($query, disableAgentHeader: true);
 		}

src/Plugin/Sharding/HealthMonitor.php

@@ -17,7 +17,7 @@ public function __construct(
 
 	/**
 	 * Perform comprehensive health check
-	 * @return array Health status
+	 * @return array{overall_status: string, timestamp: int, checks: array<string, mixed>, issues: array<mixed>, warnings: array<mixed>, recommendations: array<string>} Health status
 	 */
 	public function performHealthCheck(): array {
 		$health = [
@@ -83,7 +83,7 @@ public function performHealthCheck(): array {
 
 	/**
 	 * Attempt automatic recovery for detected issues
-	 * @return array Recovery results
+	 * @return array{timestamp: int, actions_taken: array<string>, recovered_tables: array<string>, failed_recoveries: array<string>, cleanup_performed: bool} Recovery results
 	 */
 	public function performAutoRecovery(): array {
 		$results = [
@@ -109,8 +109,8 @@ public function performAutoRecovery(): array {
 
 	/**
 	 * Process health issues and attempt recovery
-	 * @param array $issues
-	 * @param array &$results
+	 * @param array<mixed> $issues
+	 * @param array{timestamp: int, actions_taken: array<string>, recovered_tables: array<string>, failed_recoveries: array<string>, cleanup_performed: bool} &$results
 	 */
 	private function processHealthIssues(array $issues, array &$results): void {
 		foreach ($issues as $issue) {
@@ -124,8 +124,8 @@ private function processHealthIssues(array $issues, array &$results): void {
 
 	/**
 	 * Recover stuck operations for given tables
-	 * @param array $tables
-	 * @param array &$results
+	 * @param array<string> $tables
+	 * @param array{timestamp: int, actions_taken: array<string>, recovered_tables: array<string>, failed_recoveries: array<string>, cleanup_performed: bool} &$results
 	 */
 	private function recoverStuckOperations(array $tables, array &$results): void {
 		foreach ($tables as $tableName) {
@@ -144,8 +144,8 @@ private function recoverStuckOperations(array $tables, array &$results): void {
 
 	/**
 	 * Recover failed operations for given tables
-	 * @param array $tables
-	 * @param array &$results
+	 * @param array<string> $tables
+	 * @param array{timestamp: int, actions_taken: array<string>, recovered_tables: array<string>, failed_recoveries: array<string>, cleanup_performed: bool} &$results
 	 */
 	private function recoverFailedOperations(array $tables, array &$results): void {
 		foreach ($tables as $tableName) {
@@ -164,8 +164,8 @@ private function recoverFailedOperations(array $tables, array &$results): void {
 
 	/**
 	 * Perform cleanup if warnings exist
-	 * @param array $warnings
-	 * @param array &$results
+	 * @param array<mixed> $warnings
+	 * @param array{timestamp: int, actions_taken: array<string>, recovered_tables: array<string>, failed_recoveries: array<string>, cleanup_performed: bool} &$results
 	 */
 	private function performCleanupIfNeeded(array $warnings, array &$results): void {
 		if (empty($warnings)) {
@@ -180,7 +180,7 @@ private function performCleanupIfNeeded(array $warnings, array &$results): void
 
 	/**
 	 * Check for stuck rebalancing operations
-	 * @return array Check results
+	 * @return array{stuck_tables: array<string>, check_time: int, error?: string} Check results
 	 */
 	private function checkStuckOperations(): array {
 		$results = ['stuck_tables' => [], 'check_time' => time()];
@@ -223,7 +223,7 @@ private function checkStuckOperations(): array {
 
 	/**
 	 * Check for failed operations
-	 * @return array Check results
+	 * @return array{failed_tables: array<string>, check_time: int, error?: string} Check results
 	 */
 	private function checkFailedOperations(): array {
 		$results = ['failed_tables' => [], 'check_time' => time()];
@@ -262,7 +262,7 @@ private function checkFailedOperations(): array {
 
 	/**
 	 * Check for orphaned resources
-	 * @return array Check results
+	 * @return array{orphaned_count: int, details: array<string>, check_time: int, error?: string} Check results
 	 */
 	private function checkOrphanedResources(): array {
 		$results = ['orphaned_count' => 0, 'details' => [], 'check_time' => time()];
@@ -275,7 +275,7 @@ private function checkOrphanedResources(): array {
 			$clusters = $data[0]['data'] ?? [];
 
 			foreach ($clusters as $cluster) {
-				$clusterName = $cluster['cluster'] ?? '';
+			$clusterName = $cluster['cluster'];
 				if (strpos($clusterName, 'temp_move_') !== 0) {
 					continue;
 				}
@@ -292,7 +292,7 @@ private function checkOrphanedResources(): array {
 
 	/**
 	 * Check queue health
-	 * @return array Check results
+	 * @return array{depth: int, threshold: int, high_depth: bool, check_time: int, error?: string} Check results
 	 */
 	private function checkQueueHealth(): array {
 		$results = ['depth' => 0, 'threshold' => 100, 'high_depth' => false, 'check_time' => time()];
@@ -322,8 +322,8 @@ private function checkQueueHealth(): array {
 
 	/**
 	 * Generate recommendations based on health check
-	 * @param array $health
-	 * @return array Recommendations
+	 * @param array{overall_status: string, timestamp: int, checks: array<string, mixed>, issues: array<mixed>, warnings: array<mixed>, recommendations: array<string>} $health
+	 * @return array<string> Recommendations
 	 */
 	private function generateRecommendations(array $health): array {
 		$recommendations = [];
@@ -361,7 +361,7 @@ private function generateRecommendations(array $health): array {
 	/**
 	 * Recover stuck operation
 	 * @param string $tableName
-	 * @return array Recovery result
+	 * @return array{success: bool, message?: string, error?: string} Recovery result
 	 */
 	private function recoverStuckOperation(string $tableName): array {
 		try {
@@ -377,7 +377,7 @@ private function recoverStuckOperation(string $tableName): array {
 	/**
 	 * Recover failed operation
 	 * @param string $tableName
-	 * @return array Recovery result
+	 * @return array{success: bool, message?: string, error?: string} Recovery result
 	 */
 	private function recoverFailedOperation(string $tableName): array {
 		try {

src/Plugin/Sharding/Queue.php

@@ -356,7 +356,7 @@ public function rollbackOperationGroup(string $operationGroup): bool {
 	/**
 	 * Get rollback commands for operation group in reverse order
 	 * @param string $operationGroup
-	 * @return array Rollback commands in reverse execution order
+	 * @return array<array{id:int,node:string,rollback_query:string,rollback_wait_for_id:int}> Rollback commands in reverse execution order
 	 */
 	protected function getRollbackCommands(string $operationGroup): array {
 		$table = $this->cluster->getSystemTableName($this->table);
@@ -379,7 +379,7 @@ protected function getRollbackCommands(string $operationGroup): array {
 
 	/**
 	 * Execute rollback commands in sequence
-	 * @param array $rollbackCommands
+	 * @param array<array{id:int,node:string,rollback_query:string,rollback_wait_for_id:int}> $rollbackCommands
 	 * @return bool Success status
 	 */
 	protected function executeRollbackSequence(array $rollbackCommands): bool {

src/Plugin/Sharding/Table.php

@@ -490,14 +490,14 @@ public function rebalance(Queue $queue): void {
 			$state->set("rebalance_group:{$this->name}", null); // Clear operation group
 		} catch (\Throwable $t) {
 			// Enhanced error handling with rollback
-			$this->handleRebalancingFailure($t, $operationGroup ?? '', $queue, $state ?? null);
+			$this->handleRebalancingFailure($t, $operationGroup, $queue, $state ?? null);
 		}
 	}
 
 	/**
 	 * Stop rebalancing operation
 	 * @param bool $graceful If true, complete current operation before stopping
-	 * @return array Status information
+	 * @return array{status: string, message: string, current_status?: string, graceful?: bool, rollback_executed?: bool} Status information
 	 */
 	public function stopRebalancing(bool $graceful = true): array {
 		$state = new State($this->client);
@@ -524,7 +524,7 @@ public function stopRebalancing(bool $graceful = true): array {
 
 		// Immediate stop with rollback
 		$operationGroup = $state->get("rebalance_group:{$this->name}");
-		if ($operationGroup) {
+		if (is_string($operationGroup)) {
 			$queue = new Queue($this->cluster, $this->client);
 			$queue->rollbackOperationGroup($operationGroup);
 		}
@@ -576,7 +576,7 @@ public function resumeRebalancing(): bool {
 
 	/**
 	 * Get detailed rebalancing progress
-	 * @return array Progress information
+	 * @return array{status: string, table: string, operation_group: mixed, can_stop: bool, can_pause: bool, can_resume: bool, queue_total?: int, queue_completed?: int, queue_failed?: int, queue_pending?: int, progress_percentage?: float} Progress information
 	 */
 	public function getRebalancingProgress(): array {
 		$state = new State($this->client);
@@ -593,7 +593,7 @@ public function getRebalancingProgress(): array {
 			'can_resume' => $status === 'paused',
 		];
 
-		if ($operationGroup) {
+		if (is_string($operationGroup)) {
 			// Get queue progress for this operation group
 			$queueProgress = $this->getQueueProgress($operationGroup);
 			$progress = array_merge($progress, $queueProgress);
@@ -709,7 +709,7 @@ protected function handleRebalancingFailure(
 	/**
 	 * Get queue progress for operation group
 	 * @param string $operationGroup
-	 * @return array
+	 * @return array{queue_total: int, queue_completed: int, queue_failed: int, queue_pending: int, progress_percentage: float}
 	 */
 	protected function getQueueProgress(string $operationGroup): array {
 		$table = $this->cluster->getSystemTableName('system.sharding_queue');
@@ -729,10 +729,10 @@ protected function getQueueProgress(string $operationGroup): array {
 		$data = $result[0]['data'][0] ?? [];
 
 		return [
-			'queue_total' => $data['total'] ?? 0,
-			'queue_completed' => $data['completed'] ?? 0,
-			'queue_failed' => $data['failed'] ?? 0,
-			'queue_pending' => $data['pending'] ?? 0,
+			'queue_total' => $data['total'],
+			'queue_completed' => $data['completed'],
+			'queue_failed' => $data['failed'],
+			'queue_pending' => $data['pending'],
 			'progress_percentage' => $data['total'] > 0
 				? round(($data['completed'] / $data['total']) * 100, 2)
 				: 0,

test/Plugin/Sharding/OutageQueueCommandTest.php

@@ -13,8 +13,8 @@
 use Manticoresearch\Buddy\Base\Plugin\Sharding\Queue;
 use Manticoresearch\Buddy\Core\ManticoreSearch\Client;
 use Manticoresearch\Buddy\Test\Plugin\Sharding\TestDoubles\TestableCluster;
-use Manticoresearch\Buddy\Test\Plugin\Sharding\TestDoubles\TestableQueue;
 use Manticoresearch\Buddy\Test\Plugin\Sharding\TestDoubles\TestableTable;
+use Manticoresearch\BuddyTest\Plugin\Sharding\TestDoubles\TestableQueue;
 use PHPUnit\Framework\TestCase;
 
 /**

test/Plugin/Sharding/QueueCommandVerificationTest.php

@@ -13,8 +13,8 @@
 use Manticoresearch\Buddy\Base\Plugin\Sharding\Queue;
 use Manticoresearch\Buddy\Core\ManticoreSearch\Client;
 use Manticoresearch\Buddy\Test\Plugin\Sharding\TestDoubles\TestableCluster;
-use Manticoresearch\Buddy\Test\Plugin\Sharding\TestDoubles\TestableQueue;
 use Manticoresearch\Buddy\Test\Plugin\Sharding\TestDoubles\TestableTable;
+use Manticoresearch\BuddyTest\Plugin\Sharding\TestDoubles\TestableQueue;
 use PHPUnit\Framework\TestCase;
 
 /**

test/Plugin/Sharding/QueueRollbackIntegrationTest.php

@@ -20,6 +20,7 @@
 final class QueueRollbackIntegrationTest extends TestCase {
 
 	private TestableQueue $queue;
+
 	private TestableTable $table;
 
 	protected function setUp(): void {

test/Plugin/Sharding/TableRebalanceTest.php

@@ -13,8 +13,8 @@
 use Ds\Vector;
 use Manticoresearch\Buddy\Base\Plugin\Sharding\Util;
 use Manticoresearch\Buddy\Test\Plugin\Sharding\TestDoubles\TestableCluster;
-use Manticoresearch\Buddy\Test\Plugin\Sharding\TestDoubles\TestableQueue;
-use Manticoresearch\Buddy\Test\Plugin\Sharding\TestDoubles\TestableTable;
+use Manticoresearch\BuddyTest\Plugin\Sharding\TestDoubles\TestableQueue;
+use Manticoresearch\BuddyTest\Plugin\Sharding\TestDoubles\TestableTable;
 use PHPUnit\Framework\TestCase;
 
 /** @package  */