fix: update phpstan types and annotations for compatibility

Author: Morgy93

src/Console/Command/Hyva/CompatibilityCheckCommand.php

@@ -19,6 +19,10 @@
  *
  * Scans modules for RequireJS, Knockout.js, jQuery, and UI Components usage
  * that would be incompatible with Hyvä themes.
+ *
+ * @phpstan-import-type CheckResults from \OpenForgeProject\MageForge\Service\Hyva\CompatibilityChecker
+ * @phpstan-import-type CheckSummary from \OpenForgeProject\MageForge\Service\Hyva\CompatibilityChecker
+ * @phpstan-import-type ModuleEntry from \OpenForgeProject\MageForge\Service\Hyva\CompatibilityChecker
  */
 class CompatibilityCheckCommand extends AbstractCommand
 {
@@ -271,7 +275,7 @@ private function runScan(
      * Display compatibility check results
      *
      * @param array $results
-     * @phpstan-param array{modules: array<string, array{compatible: bool, hasWarnings: bool, scanResult: array{files: array<string, array<int, array{description: string, severity: string, line: int, pattern: string}>>, totalIssues: int, criticalIssues: int}, moduleInfo: array{name: string, version: string, isHyvaAware: bool}}>, hasIncompatibilities: bool} $results
+     * @phpstan-param CheckResults $results
      * @param bool $showAll
      */
     private function displayResults(array $results, bool $showAll): void
@@ -292,7 +296,7 @@ private function displayResults(array $results, bool $showAll): void
      * Display detailed file-level issues
      *
      * @param array $results
-     * @phpstan-param array{modules: array<string, array{compatible: bool, hasWarnings: bool, scanResult: array{files: array<string, array<int, array{description: string, severity: string, line: int, pattern: string}>>, totalIssues: int, criticalIssues: int}, moduleInfo: array{name: string, version: string, isHyvaAware: bool}}>, hasIncompatibilities: bool} $results
+     * @phpstan-param CheckResults $results
      */
     private function displayDetailedIssues(array $results): void
     {
@@ -333,7 +337,7 @@ private function displayDetailedIssues(array $results): void
      * Display summary statistics
      *
      * @param array $results
-     * @phpstan-param array{summary: array{total: int, compatible: int, incompatible: int, hyvaAware: int, criticalIssues: int, warningIssues: int}} $results
+     * @phpstan-param array{summary: CheckSummary} $results
      */
     private function displaySummary(array $results): void
     {

src/Service/Hyva/CompatibilityChecker.php

@@ -9,12 +9,21 @@
 use Symfony\Component\Console\Output\OutputInterface;
 use Symfony\Component\Console\Style\SymfonyStyle;
 
+// phpcs:disable Generic.Files.LineLength.TooLong
 /**
  * Service that orchestrates Hyvä compatibility checking across Magento modules
  *
  * This service scans modules, detects incompatibilities with Hyvä theme framework,
  * and provides formatted results with summary statistics.
+ *
+ * @phpstan-import-type ScanIssue from IncompatibilityDetector
+ * @phpstan-import-type ScanResult from ModuleScanner
+ * @phpstan-import-type ModuleInfo from ModuleScanner
+ * @phpstan-type ModuleEntry array{compatible: bool, hasWarnings: bool, scanResult: ScanResult, moduleInfo: ModuleInfo}
+ * @phpstan-type CheckSummary array{total: int, compatible: int, incompatible: int, hyvaAware: int, criticalIssues: int, warningIssues: int}
+ * @phpstan-type CheckResults array{modules: array<string, ModuleEntry>, summary: CheckSummary, hasIncompatibilities: bool}
  */
+// phpcs:enable Generic.Files.LineLength.TooLong
 class CompatibilityChecker
 {
     /**
@@ -37,7 +46,7 @@ public function __construct(
      * @param bool $excludeVendor Whether to exclude modules from the vendor/ directory
      * @return array<string, mixed> Results with structure: ['modules' => [], 'summary' => [],
      *     'hasIncompatibilities' => bool]
-     * @phpstan-return array{modules: array<string, array{compatible: bool, hasWarnings: bool, scanResult: array{files: array<string, array<int, array{description: string, severity: string, line: int, pattern: string}>>, totalIssues: int, criticalIssues: int}, moduleInfo: array{name: string, version: string, isHyvaAware: bool}}>, summary: array{total: int, compatible: int, incompatible: int, hyvaAware: int, criticalIssues: int, warningIssues: int}, hasIncompatibilities: bool}
+     * @phpstan-return CheckResults
      */
     public function check(
         SymfonyStyle $io,
@@ -140,7 +149,7 @@ private function isMagentoModule(string $moduleName): bool
      * Format results for display
      *
      * @param array $results
-     * @phpstan-param array{modules: array<string, array{compatible: bool, hasWarnings: bool, scanResult: array{files: array<string, array<int, array{description: string, severity: string, line: int, pattern: string}>>, totalIssues: int, criticalIssues: int}, moduleInfo: array{name: string, version: string, isHyvaAware: bool}}>} $results
+     * @phpstan-param CheckResults $results
      * @param bool $showAll
      * @return array<int, array<int, string>>
      */
@@ -168,7 +177,7 @@ public function formatResultsForDisplay(array $results, bool $showAll = false):
      * Get status display string with colors
      *
      * @param array $moduleData
-     * @phpstan-param array{compatible: bool, hasWarnings: bool, scanResult: array<string, mixed>, moduleInfo: array<string, mixed>} $moduleData
+     * @phpstan-param ModuleEntry $moduleData
      * @return string
      */
     private function getStatusDisplay(array $moduleData): string
@@ -192,7 +201,7 @@ private function getStatusDisplay(array $moduleData): string
      * Get issues display string
      *
      * @param array $moduleData
-     * @phpstan-param array{compatible: bool, hasWarnings: bool, scanResult: array{totalIssues: int, criticalIssues: int}, moduleInfo: array<string, mixed>} $moduleData
+     * @phpstan-param ModuleEntry $moduleData
      * @return string
      */
     private function getIssuesDisplay(array $moduleData): string
@@ -223,8 +232,8 @@ private function getIssuesDisplay(array $moduleData): string
      *
      * @param string $moduleName
      * @param array $moduleData
-     * @phpstan-param array{compatible: bool, hasWarnings: bool, scanResult: array{files: array<string, array<int, array{description: string, severity: string, line: int, pattern: string}>>, totalIssues: int, criticalIssues: int}, moduleInfo: array{name: string, version: string, isHyvaAware: bool}} $moduleData
-     * @return array<int, array{file: string, issues: array<int, array{description: string, severity: string, line: int, pattern: string}>}>
+     * @phpstan-param ModuleEntry $moduleData
+     * @return array<int, array{file: string, issues: array<int, ScanIssue>}>
      */
     public function getDetailedIssues(string $moduleName, array $moduleData): array
     {

src/Service/Hyva/IncompatibilityDetector.php

@@ -11,6 +11,8 @@
  *
  * Uses pattern matching to identify RequireJS, Knockout.js, jQuery, and UI Components
  * usage that would be problematic in a Hyvä environment.
+ *
+ * @phpstan-type ScanIssue array{description: string, severity: string, line: int, pattern: string}
  */
 class IncompatibilityDetector
 {
@@ -107,7 +109,7 @@ public function __construct(
      *
      * @param string $filePath
      * @return array<int, array<string, mixed>> Array of issues with keys: pattern, description, severity, line
-     * @phpstan-return array<int, array{description: string, severity: string, line: int, pattern: string}>
+     * @phpstan-return array<int, ScanIssue>
      */
     public function detectInFile(string $filePath): array
     {
@@ -154,7 +156,7 @@ private function mapExtensionToType(string $extension): string
      * @param array $lines
      * @param array $patterns
      * @return array<int, array<string, mixed>>
-     * @phpstan-return array<int, array{description: string, severity: string, line: int, pattern: string}>
+     * @phpstan-return array<int, ScanIssue>
      * @phpstan-param array<int, string> $lines
      * @phpstan-param array<int, array{pattern: string, description: string, severity: string}> $patterns
      */

src/Service/Hyva/ModuleScanner.php

@@ -11,6 +11,10 @@
  *
  * Recursively scans JavaScript, XML, and PHTML files within module directories
  * to identify patterns that may be incompatible with Hyvä themes.
+ *
+ * @phpstan-import-type ScanIssue from IncompatibilityDetector
+ * @phpstan-type ScanResult array{files: array<string, array<int, ScanIssue>>, totalIssues: int, criticalIssues: int}
+ * @phpstan-type ModuleInfo array{name: string, version: string, isHyvaAware: bool}
  */
 class ModuleScanner
 {
@@ -32,7 +36,7 @@ public function __construct(
      *
      * @param string $modulePath
      * @return array<string, mixed> Array with structure: ['files' => [], 'totalIssues' => int, 'criticalIssues' => int]
-     * @phpstan-return array{files: array<string, array<int, array{description: string, severity: string, line: int, pattern: string}>>, totalIssues: int, criticalIssues: int}
+     * @phpstan-return ScanResult
      */
     public function scanModule(string $modulePath): array
     {
@@ -176,7 +180,7 @@ public function hasHyvaCompatibilityPackage(string $modulePath): bool
      *
      * @param string $modulePath
      * @return array<string, mixed>
-     * @phpstan-return array{name: string, version: string, isHyvaAware: bool}
+     * @phpstan-return ModuleInfo
      */
     public function getModuleInfo(string $modulePath): array
     {